feat(please-plugins): add plugin discovery and setup for pleaseai marketplace (#119)

* docs(track): nuxt-session-hook-20260328 추가

* docs(track): update spec and plan with PostToolUse hook and async SessionStart

* docs(track): expand to standalone plugin-recommender plugin

Repurpose nuxt-specific hook track to a general-purpose plugin
recommender that covers all npm-based marketplace plugins.

* chore(track): nuxt-session-hook-20260328 구현 시작

* feat(plugin-recommender): add plugin manifest

* feat(plugin-recommender): add dependency detection hook with tests

Implements SessionStart and PostToolUse hook that detects npm packages
in package.json and recommends corresponding marketplace plugins.

Supports 20 package-to-plugin mappings including nuxt, vue, pinia,
vitest, prisma, supabase, and more.

* feat(plugin-recommender): add hooks.json registration

SessionStart (async) + PostToolUse for bun/npm/pnpm install commands.

* feat(plugin-recommender): add to marketplace registry

* docs(track): update progress for nuxt-session-hook-20260328

* fix(plugin-recommender): rename shadowed variable in detectPackages

Rename inner loop variable from `pkg` to `pkgName` to avoid shadowing
the outer function parameter.

* refactor(plugin-recommender): extract plugin mappings to JSON file

Move PLUGIN_MAPPINGS data to plugin-mappings.json for easier
maintenance without touching TypeScript code.

* chore: apply AI code review suggestions for plugin-recommender hooks

- Refactor main() into detectForEvent() helper to eliminate duplication between SessionStart and PostToolUse branches
- Simplify hooks.json PostToolUse config to a single Bash matcher instead of five repetitive if-filtered entries
- Fix extractPackagesFromCommand to strip version/tag suffixes (e.g. pkg@latest → pkg) so PostToolUse matching works correctly; use lookbehind to preserve scoped package prefixes (@scope/pkg)
- Add test cases for version suffix stripping

* fix(plugin-recommender): restore install-command filter in PostToolUse hook

Collapse the five per-command if-filters into a single pipe-separated
if pattern so the recommender only spawns on package install commands,
avoiding overhead on unrelated Bash usage.

* feat(plugin-recommender): detect tooling from lock files and packageManager

Add tooling-mappings.json for non-npm-package detection:
- pnpm-lock.yaml or packageManager: pnpm → pnpm plugin
- turbo.json → turborepo plugin

Easily extensible via tooling-mappings.json.

* feat(plugin-recommender): add /plugin-recommender:setup command

Interactive setup that scans dependencies, shows installed vs
available plugins, and lets users install all at once.

* refactor(plugin-recommender): rename to please-plugins

Rename plugin-recommender → please-plugins for better naming.
Command: /please-plugins:setup

* feat(please-plugins): add mappings for flutter, sentry, posthog, playwright, and more

New plugin-mappings: sentry, posthog, playwright-cli, tosspayments,
slack-agent, mcp-neo4j. Added @nuxt/content to docus mapping.
New tooling-mapping: pubspec.yaml → flutter.

* fix(please-plugins): rename lockFiles to files in tooling mappings

The field contained indicator files (turbo.json, pubspec.yaml) that
aren't lock files. Renamed to 'files' for accuracy. Also use
pubspec.lock as primary Flutter indicator with pubspec.yaml fallback.

Author: amondnet

.claude-plugin/marketplace.json

@@ -479,6 +479,14 @@
         "source": "github",
         "repo": "makenotion/claude-code-notion-plugin"
       }
+    },
+    {
+      "name": "please-plugins",
+      "description": "Auto-detect project dependencies and recommend matching Claude Code plugins from the pleaseai marketplace",
+      "category": "tooling",
+      "keywords": ["please-plugins", "discovery", "marketplace", "auto-detect", "setup"],
+      "tags": ["tooling", "discovery"],
+      "source": "./plugins/please-plugins"
     }
   ]
 }

.please/config.yml

@@ -1,3 +1,5 @@
+schema_version: 2          # Config schema version (do not edit manually)
+
 language: en   # Output language (ko | en)
 
 # Document path overrides (optional — defaults shown)

.please/docs/tracks/active/nuxt-session-hook-20260328/metadata.json

@@ -0,0 +1,10 @@
+{
+  "track_id": "nuxt-session-hook-20260328",
+  "type": "feature",
+  "status": "in_progress",
+  "created_at": "2026-03-28T22:24:12+09:00",
+  "updated_at": "2026-03-28T22:35:00+09:00",
+  "issue": "",
+  "pr": "",
+  "project": ""
+}

.please/docs/tracks/active/nuxt-session-hook-20260328/plan.md

@@ -0,0 +1,122 @@
+# Plan: Plugin Recommender
+
+> Track: nuxt-session-hook-20260328
+> Spec: [spec.md](./spec.md)
+
+## Overview
+
+- **Source**: [spec.md](./spec.md)
+- **Issue**: TBD
+- **Created**: 2026-03-28
+- **Approach**: Minimal Change
+
+## Purpose
+
+After this change, developers will automatically see recommendations to install relevant Claude Code plugins based on npm packages detected in their `package.json`. Recommendations appear at session start (async, non-blocking) and after running package install commands. They can verify it works by starting a Claude Code session in a project with `@nuxt/ui` and seeing the recommendation to install `nuxt-ui@pleaseai`.
+
+## Context
+
+The `pleaseai` marketplace offers many plugins that correspond to npm packages (nuxt, vue, pinia, vueuse, vitest, prisma, supabase, etc.), but users may not know these plugins exist. Currently there is no automatic discovery mechanism.
+
+This feature creates a standalone `plugin-recommender` plugin with two complementary hooks:
+
+1. **SessionStart hook** (`async: true`): Scans `package.json` at session start in the background, without blocking session initialization. Outputs `systemMessage` (user-facing) and `additionalContext` (Claude-facing).
+
+2. **PostToolUse hook** (`matcher: "Bash"`): Fires after `bun add`, `npm install/add`, `pnpm add/install` commands. When a user installs a matching package during the session, immediately recommends the corresponding plugin.
+
+Both hooks share detection logic in a single TypeScript file. The package-to-plugin mapping is a simple data array, making it trivial to add new mappings as plugins are added to the marketplace.
+
+The existing `worktree-context.ts` hook provides the reference TypeScript pattern: stdin-based JSON input, pure functions for testability, and `import.meta.main` guard.
+
+Non-goals: No auto-installation, no monorepo workspace scanning, no non-npm ecosystems.
+
+## Architecture Decision
+
+Standalone plugin at `plugins/plugin-recommender/` rather than embedding hooks in individual framework plugins. This centralizes the recommendation logic and avoids duplication across plugins.
+
+The hook uses `hooks/hooks.json` (auto-loaded by Claude Code) rather than `plugin.json`'s `hooks` field. Pure functions are exported for unit testing, and `import.meta.main` guard separates entry point from testable logic.
+
+For installed plugin detection, the hook checks `.claude/settings.json` (project-level) and `~/.claude/settings.json` (user-level) for `enabledPlugins` entries matching `pluginName@pleaseai`.
+
+A single script handles both events via `hook_event_name` field from stdin JSON.
+
+## Tasks
+
+- [x] T001 Create plugin manifest (file: plugins/plugin-recommender/.claude-plugin/plugin.json)
+- [x] T002 Create dependency detection hook (file: plugins/plugin-recommender/hooks/check-dependencies.ts) (depends on T001)
+- [x] T003 Create hooks.json registration (file: plugins/plugin-recommender/hooks/hooks.json) (depends on T002)
+- [x] T004 [P] Create unit tests for hook (file: plugins/plugin-recommender/hooks/check-dependencies.test.ts) (depends on T002)
+- [x] T005 Add plugin-recommender to marketplace.json (file: .claude-plugin/marketplace.json) (depends on T001)
+
+## Progress
+
+- [x] (2026-03-28 22:35 KST) T001 Create plugin manifest
+- [x] (2026-03-28 22:36 KST) T002 Create dependency detection hook
+  Evidence: `bun test` → 32 tests passed (62ms)
+- [x] (2026-03-28 22:37 KST) T003 Create hooks.json registration
+- [x] (2026-03-28 22:36 KST) T004 Create unit tests for hook
+  Evidence: `bun test` → 32 tests passed, 93 expect() calls
+- [x] (2026-03-28 22:38 KST) T005 Add plugin-recommender to marketplace.json
+
+## Key Files
+
+### Create
+
+- `plugins/plugin-recommender/.claude-plugin/plugin.json` — Plugin manifest with name, version, description
+- `plugins/plugin-recommender/hooks/check-dependencies.ts` — Main hook with package detection, plugin status checking, and JSON output
+- `plugins/plugin-recommender/hooks/hooks.json` — Hook registration: SessionStart (async) + PostToolUse (matcher: Bash)
+- `plugins/plugin-recommender/hooks/check-dependencies.test.ts` — Unit tests for detection/filtering functions
+
+### Modify
+
+- `.claude-plugin/marketplace.json` — Add `plugin-recommender` entry
+
+### Reuse (Reference)
+
+- `plugins/worktree/hooks/worktree-context.ts` — TypeScript hook pattern (stdin parsing, JSON output, `import.meta.main`)
+- `plugins/worktree/hooks/worktree-context.test.ts` — Test pattern for TypeScript hooks
+
+## Verification
+
+### Automated Tests
+
+- [ ] Detects `@nuxt/ui` in dependencies and returns `nuxt-ui` recommendation
+- [ ] Detects `pinia` or `@pinia/nuxt` and returns `pinia` recommendation
+- [ ] Detects `vitest` in devDependencies and returns `vitest` recommendation
+- [ ] Detects `@prisma/client` and returns `prisma` recommendation
+- [ ] Detects multiple packages and returns all recommendations
+- [ ] Returns empty result when no matching packages found
+- [ ] Returns empty result when all matching plugins are already installed
+- [ ] Handles missing `package.json` gracefully (no error, no output)
+- [ ] Handles malformed `package.json` gracefully
+- [ ] Output JSON has valid `hookSpecificOutput` with `systemMessage` and `additionalContext`
+- [ ] PostToolUse: extracts package name from `bun add @nuxt/ui` command
+- [ ] PostToolUse: extracts package name from `npm install prisma` command
+- [ ] PostToolUse: extracts package name from `pnpm add @vueuse/nuxt` command
+- [ ] Adding a new mapping requires only a data change
+
+### Observable Outcomes
+
+- After starting Claude Code in a project with `@nuxt/ui` installed, the session shows a recommendation to install `nuxt-ui@pleaseai`
+- After running `bun add @prisma/client`, the PostToolUse hook shows the prisma recommendation
+
+## Decision Log
+
+- Decision: Standalone `plugin-recommender` plugin instead of per-framework hooks
+  Rationale: Centralizes recommendation logic, avoids duplication, covers all npm-based plugins in one place
+  Date/Author: 2026-03-28 / user + Claude
+- Decision: Use `hooks/hooks.json` over `plugin.json` hooks field
+  Rationale: CLAUDE.md convention — `hooks/hooks.json` is auto-loaded
+  Date/Author: 2026-03-28 / Claude
+- Decision: Check both project-level and user-level `.claude/settings.json` for installed plugins
+  Rationale: Users may have plugins enabled at project or global scope
+  Date/Author: 2026-03-28 / Claude
+- Decision: Use `async: true` for SessionStart hook
+  Rationale: Package detection is informational and should not block session initialization
+  Date/Author: 2026-03-28 / user + Claude
+- Decision: Add PostToolUse hook for package install commands
+  Rationale: Recommend plugins immediately when a matching package is installed
+  Date/Author: 2026-03-28 / user + Claude
+- Decision: Single script handles both events via `hook_event_name` field
+  Rationale: Shared detection logic avoids code duplication
+  Date/Author: 2026-03-28 / Claude

.please/docs/tracks/active/nuxt-session-hook-20260328/spec.md

@@ -0,0 +1,83 @@
+# Plugin Recommender
+
+> Track: nuxt-session-hook-20260328
+
+## Overview
+
+Create a standalone `plugin-recommender` plugin that detects npm packages in the user's `package.json` and recommends installing corresponding marketplace plugins from `pleaseai`. Two hooks work together:
+
+1. **SessionStart hook** (`async: true`): Scans `package.json` at session start in the background
+2. **PostToolUse hook**: Triggers after `bun add`, `npm install/add`, `pnpm add/install` commands to recommend plugins for newly installed packages
+
+Both hooks output `systemMessage` (user-facing install recommendations) and `additionalContext` (Claude-facing context about available plugins).
+
+## Requirements
+
+### Functional Requirements
+
+- [ ] FR-1: Create a standalone plugin at `plugins/plugin-recommender/` with `.claude-plugin/plugin.json`
+- [ ] FR-2: Create a TypeScript hook (`hooks/check-dependencies.ts`) with shared detection logic for both SessionStart and PostToolUse events
+- [ ] FR-3: Detect npm packages and map them to marketplace plugins:
+  | npm package(s) | Marketplace plugin |
+  |---|---|
+  | `nuxt` | `nuxt` |
+  | `@nuxt/ui` | `nuxt-ui` |
+  | `@nuxtjs/seo`, `nuxt-seo-utils` | `nuxt-seo` |
+  | `vue` | `vue` |
+  | `pinia`, `@pinia/nuxt` | `pinia` |
+  | `@vueuse/nuxt`, `@vueuse/core` | `vueuse` |
+  | `vitest` | `vitest` |
+  | `unocss`, `@unocss/nuxt` | `unocss` |
+  | `vitepress` | `vitepress` |
+  | `vite` | `vite` |
+  | `firebase`, `firebase-admin` | `firebase` |
+  | `@prisma/client`, `prisma` | `prisma` |
+  | `@supabase/supabase-js` | `supabase` |
+  | `better-auth` | `better-auth` |
+  | `ai`, `@ai-sdk/openai` | `ai-sdk` |
+  | `mastra`, `@mastra/core` | `mastra` |
+  | `stripe`, `@stripe/stripe-js` | `stripe` |
+  | `@slidev/cli` | `slidev` |
+  | `tsdown` | `tsdown` |
+  | `docus` | `docus` |
+- [ ] FR-4: Only recommend plugins that are **not already installed** by the user
+- [ ] FR-5: Output `systemMessage` (user-facing) with install commands (`/plugin install <name>@pleaseai`) for each detected-but-not-installed plugin
+- [ ] FR-6: Output `additionalContext` (Claude-facing) with guidance to leverage the recommended plugins for better assistance
+- [ ] FR-7: If no matching packages are found or all matching plugins are already installed, exit silently (no output)
+- [ ] FR-8: Create `hooks/hooks.json` to register both hooks:
+  - SessionStart with `async: true` (non-blocking background execution)
+  - PostToolUse with `matcher: "Bash"` and `if` conditions for package install commands
+- [ ] FR-9: Hook must handle missing `package.json` gracefully (exit silently)
+- [ ] FR-10: PostToolUse hook must detect `bun add`, `npm install`, `npm add`, `pnpm add`, `pnpm install` commands
+- [ ] FR-11: The package-to-plugin mapping must be easily extensible (simple data structure, not scattered logic)
+- [ ] FR-12: Add `plugin-recommender` to `marketplace.json`
+
+### Non-functional Requirements
+
+- [ ] NFR-1: Hook must complete within 10 seconds (timeout)
+- [ ] NFR-2: Hook must not fail if `package.json` is malformed (graceful error handling)
+- [ ] NFR-3: TypeScript implementation must be testable with Vitest
+
+## Acceptance Criteria
+
+- [ ] AC-1: When a project has `@nuxt/ui` in dependencies and `nuxt-ui` plugin is not installed, the hook recommends installing `nuxt-ui@pleaseai`
+- [ ] AC-2: When multiple matching packages are found, all corresponding plugins are recommended in a single output
+- [ ] AC-3: When all matching plugins are already installed, no output is produced
+- [ ] AC-4: When `package.json` does not exist, no output is produced and no error occurs
+- [ ] AC-5: The hook output contains valid JSON with both `systemMessage` and `additionalContext` fields
+- [ ] AC-6: After running `bun add @nuxt/ui`, the PostToolUse hook recommends installing `nuxt-ui@pleaseai`
+- [ ] AC-7: The SessionStart hook runs asynchronously (does not block session initialization)
+- [ ] AC-8: Adding a new package-to-plugin mapping requires only a data change, not logic changes
+
+## Out of Scope
+
+- Auto-installing plugins without user action
+- Checking plugin version compatibility
+- Detecting packages in monorepo workspaces (only checks root `package.json`)
+- Non-npm package detection (e.g., Flutter/Dart, Python, Go)
+
+## Assumptions
+
+- The hook can determine installed plugins by checking `.claude/settings.json` for `enabledPlugins`
+- `bun` is available in the user's environment
+- The `package.json` is at the working directory root

.please/docs/tracks/index.md

@@ -7,6 +7,7 @@
 | Track | Feature | Type | Issue | Started | Status |
 |-------|---------|------|-------|---------|--------|
 | [nuxt-ui-hook-guidance-20260328](active/nuxt-ui-hook-guidance-20260328/plan.md) | Nuxt UI Hook Guidance | feature | TBD | 2026-03-28 | in_progress |
+| [nuxt-session-hook-20260328](active/nuxt-session-hook-20260328/) | Plugin Recommender | feature | — | 2026-03-28 | in_progress |
 
 ## Recently Completed
 

.release-please-manifest.json

@@ -34,5 +34,6 @@
   "plugins/markitdown": "1.0.0",
   "plugins/ast-grep": "1.0.0",
   "plugins/chat-sdk": "1.0.0",
-  "plugins/docus": "1.0.0"
+  "plugins/docus": "1.0.0",
+  "plugins/please-plugins": "1.0.0"
 }

plugins/please-plugins/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "please-plugins",
+  "version": "1.0.0",
+  "description": "Auto-detect project dependencies and recommend matching Claude Code plugins from the pleaseai marketplace",
+  "author": {
+    "name": "Passion Factory",
+    "url": "https://github.com/pleaseai"
+  },
+  "homepage": "https://github.com/pleaseai/claude-code-plugins",
+  "repository": "https://github.com/pleaseai/claude-code-plugins",
+  "license": "MIT",
+  "keywords": [
+    "please-plugins",
+    "discovery",
+    "marketplace",
+    "auto-detect",
+    "setup"
+  ]
+}

plugins/please-plugins/commands/setup.md

@@ -0,0 +1,77 @@
+---
+description: Scan project dependencies and install recommended Claude Code plugins
+allowed-tools: Read, Bash, Glob, Grep, AskUserQuestion
+---
+
+# Plugin Recommender Setup
+
+Scan the current project's `package.json` and tooling files to detect packages that have corresponding Claude Code plugins in the `pleaseai` marketplace, then help the user install them.
+
+## Step 1: Scan Dependencies
+
+Read `package.json` in the current working directory. If it doesn't exist, inform the user and stop.
+
+Read the plugin mappings and tooling mappings from the plugin's data files:
+
+```bash
+cat "${CLAUDE_PLUGIN_ROOT}/hooks/plugin-mappings.json"
+cat "${CLAUDE_PLUGIN_ROOT}/hooks/tooling-mappings.json"
+```
+
+Parse the project's `dependencies` and `devDependencies` to find matches against the plugin mappings. Also check for tooling indicators:
+- Lock files: `pnpm-lock.yaml`, `turbo.json`
+- `packageManager` field in `package.json`
+
+## Step 2: Check Installed Plugins
+
+Read `.claude/settings.json` (project-level) to check which plugins are already installed. Look for entries in `enabledPlugins` matching `<pluginName>@pleaseai`.
+
+## Step 3: Show Results
+
+Present the scan results to the user, categorized:
+
+```
+AskUserQuestion({
+  questions: [{
+    header: "Plugins",
+    question: "Detected packages and their plugin status:\n\n{for each detected plugin: ✅ installed / ⬜ not installed — source package}\n\nSelect plugins to install:",
+    multiSelect: true,
+    options: [
+      // Only list NOT-installed plugins as selectable options
+      { label: "{pluginName}", description: "Detected: {source package or tooling indicator}" },
+      ...
+    ]
+  }]
+})
+```
+
+If all detected plugins are already installed, inform the user: "All recommended plugins are already installed!"
+
+If no packages match any plugin mappings, inform the user: "No matching plugins found for this project's dependencies."
+
+## Step 4: Install Selected Plugins
+
+For each selected plugin, run the install command:
+
+```bash
+claude plugin install {pluginName}@pleaseai
+```
+
+Show the result of each installation.
+
+## Step 5: Summary
+
+Show a summary of what was installed:
+
+```
+Plugin Recommender Setup Complete!
+
+Installed: {count} plugins
+  - {pluginName1}
+  - {pluginName2}
+
+Already installed: {count} plugins
+  - {pluginName3}
+
+To manage plugins: /plugin list
+```