@webpresso/agent-kit 0.26.0 → 0.26.2

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Webpresso agent-kit Claude Code plugin: blueprints, skills, hooks, MCP server",
-    "version": "0.26.0"
+    "version": "0.26.2"
   },
   "plugins": [
     {
@@ -23,5 +23,5 @@
       ]
     }
   ],
-  "version": "0.26.0"
+  "version": "0.26.2"
 }

package/.claude-plugin/plugin.json

@@ -1,66 +1,9 @@
 {
   "name": "webpresso",
-  "version": "0.26.0",
+  "version": "0.26.2",
   "description": "Webpresso agent-kit: blueprints, skills, lore commit protocol, tech-debt lifecycle",
   "skills": "./skills",
   "commands": "./commands",
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash|Edit|Write|MultiEdit|WebFetch|Read|Grep",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/bin/wp-pretool-guard.js"
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "Edit|Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/bin/wp-post-tool.js",
-            "timeout": 15
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/bin/wp-stop-qa.js"
-          }
-        ]
-      }
-    ],
-    "UserPromptSubmit": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/bin/wp-guard-switch.js",
-            "timeout": 5
-          }
-        ]
-      }
-    ],
-    "SessionStart": [
-      {
-        "matcher": "startup|resume|compact",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/bin/wp-sessionstart-routing.js"
-          }
-        ]
-      }
-    ]
-  },
   "mcpServers": {
     "webpresso": {
       "command": "node",

package/README.md

@@ -44,6 +44,15 @@ Playwright, unit-test and file-based e2e smoke assets), wires `AGENTS.md` /
 execution-owned vs authoring-owned dependency migration guidance. Re-running
 refreshes the webpresso-owned pieces and preserves consumer-owned files.
 
+> **`wp setup` is required for hooks.** The Claude Code hooks (PreToolUse guard,
+> Stop-QA gate, SessionStart routing, …) are installed by `wp setup` into your
+> repo's `.claude/settings.json`. They are intentionally **not** shipped in the
+> plugin manifest — declaring them in both places double-fires every hook (Claude
+> Code does not dedup across sources), and settings.json is the more reliable
+> surface. So enabling the plugin alone does **not** activate hooks; run
+> `wp setup`. Run `wp hooks doctor` to check — it warns if the managed hooks are
+> missing from `.claude/settings.json`.
+
 `wp` owns **execution** for the generic tool lanes it manages (test / mutation /
 e2e / lint / format / typecheck). That does **not** mean every local
 devDependency disappears — keep dependencies your repo imports directly (e.g.

package/dist/esm/audit/toolchain-isolation.js

@@ -114,6 +114,11 @@ function shouldSkipDirectory(name) {
         '.omx',
         '.omc',
         '.codex',
+        // Gitignored Claude Code agent surface — agent worktree scratch under
+        // .claude/worktrees/* carries vendored package manifests that are not the
+        // repo's own packages; walking it produces false positives on local dev
+        // machines and in consumer repos that run agent worktrees.
+        '.claude',
     ].includes(name);
 }
 function readPackageJson(file) {

package/dist/esm/cli/commands/init/index.js

@@ -35,7 +35,7 @@ import { scaffoldAuditHooks } from './scaffolders/audit-hooks/index.js';
 import { ensureClaudeCodeUserPlugin } from './scaffolders/claude-plugin/index.js';
 import { scaffoldClaudeRules } from './scaffolders/claude-rules/index.js';
 import { ensureCodexCli } from './scaffolders/codex-cli/index.js';
-import { ensureCodexWebpressoMcp, ensureCodexPlaywrightMcp } from './scaffolders/codex-mcp/index.js';
+import { ensureCodexWebpressoMcp, ensureCodexPlaywrightMcp, ensureClaudePlaywrightMcp, } from './scaffolders/codex-mcp/index.js';
 import { scaffoldExampleSkill } from './scaffolders/example-skill/index.js';
 import { ensureGstack } from './scaffolders/gstack/index.js';
 import { scaffoldLoreCommits } from './scaffolders/lore-commits/index.js';
@@ -437,6 +437,24 @@ export async function runInit(flags) {
                     console.log('  codex playwright mcp: skipped (--dry-run)');
                     break;
             }
+            const claudePlaywrightMcpResult = ensureClaudePlaywrightMcp({
+                options,
+                repoRoot: consumer.repoRoot,
+            });
+            switch (claudePlaywrightMcpResult.kind) {
+                case 'claude-playwright-mcp-written':
+                    console.log(`  claude playwright mcp: ✓ ${claudePlaywrightMcpResult.path}`);
+                    break;
+                case 'claude-playwright-mcp-unchanged':
+                    console.log(`  claude playwright mcp: already configured at ${claudePlaywrightMcpResult.path}`);
+                    break;
+                case 'claude-playwright-mcp-skipped-dry-run':
+                    console.log('  claude playwright mcp: skipped (--dry-run)');
+                    break;
+                case 'claude-playwright-mcp-invalid-json':
+                    console.warn(`  claude playwright mcp: ⚠ ${claudePlaywrightMcpResult.path} is not valid JSON; left unchanged`);
+                    break;
+            }
         }
         if (presets.includes('omx')) {
             agentHooksResult = await scaffoldAgentHooks({

package/dist/esm/cli/commands/init/scaffolders/codex-cli/index.js

@@ -20,7 +20,11 @@ export function ensureCodexCli(input) {
         }
     }
     else if (!shouldSkipCodexRefresh()) {
-        spawn('vp', ['update', '-g', '@openai/codex'], { stdio: 'inherit' });
+        // `--latest` ignores the recorded semver range so the global is pulled to
+        // the absolute newest published release, matching the force-to-latest
+        // guarantee `vp install -g <bare>` gives the agent-kit self-update. Plain
+        // `vp update -g` is range-bound and can strand the global on an old major.
+        spawn('vp', ['update', '-g', '--latest', '@openai/codex'], { stdio: 'inherit' });
     }
     return { kind: 'codex-cli-ok', installed };
 }

package/dist/esm/cli/commands/init/scaffolders/codex-mcp/index.d.ts

@@ -1,7 +1,7 @@
 import type { MergeOptions } from '#cli/commands/init/merge';
 export declare const PLAYWRIGHT_MCP_SERVER_NAME = "playwright";
 export declare const PLAYWRIGHT_MCP_HEADER = "[mcp_servers.playwright]";
-export declare const PLAYWRIGHT_MCP_BLOCK = "[mcp_servers.playwright]\ncommand = \"vp\"\nargs = [\"dlx\", \"@playwright/mcp@latest\", \"--caps=testing,storage,network,devtools\"]\nenabled = true\nstartup_timeout_sec = 30\n";
+export declare const PLAYWRIGHT_MCP_BLOCK: string;
 export declare const WEBPRESSO_MCP_SERVER_NAME = "webpresso";
 export declare const WEBPRESSO_MCP_HEADER = "[mcp_servers.webpresso]";
 export interface EnsureCodexPlaywrightMcpInput {
@@ -21,6 +21,34 @@ export type EnsureCodexPlaywrightMcpResult = {
 };
 export declare function upsertPlaywrightMcpServer(raw: string): string;
 export declare function ensureCodexPlaywrightMcp(input: EnsureCodexPlaywrightMcpInput): EnsureCodexPlaywrightMcpResult;
+/**
+ * Upsert the `playwright` server into a `.mcp.json` document, preserving every
+ * other server (e.g. `context7`, `exa`) and any non-server top-level keys.
+ * Output is normalized to 2-space JSON with a trailing newline so repeated runs
+ * converge — idempotent after the first write.
+ */
+export declare function upsertClaudePlaywrightMcpServer(raw: string): string;
+export interface EnsureClaudePlaywrightMcpInput {
+    options: MergeOptions;
+    /** Project root whose `.mcp.json` is managed. */
+    repoRoot: string;
+    /** Test seam. Defaults to `<repoRoot>/.mcp.json`. */
+    configPath?: string;
+}
+export type EnsureClaudePlaywrightMcpResult = {
+    kind: 'claude-playwright-mcp-written';
+    path: string;
+} | {
+    kind: 'claude-playwright-mcp-unchanged';
+    path: string;
+} | {
+    kind: 'claude-playwright-mcp-skipped-dry-run';
+    path: string;
+} | {
+    kind: 'claude-playwright-mcp-invalid-json';
+    path: string;
+};
+export declare function ensureClaudePlaywrightMcp(input: EnsureClaudePlaywrightMcpInput): EnsureClaudePlaywrightMcpResult;
 export interface WebpressoInstallProbe {
     /** Test seam — override the candidate roots. Default: probe in fixed order. */
     candidates?: readonly string[];

package/dist/esm/cli/commands/init/scaffolders/codex-mcp/index.js

@@ -22,10 +22,27 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 export const PLAYWRIGHT_MCP_SERVER_NAME = 'playwright';
+/**
+ * Single source of truth for how the Playwright MCP server is launched. Both
+ * the Codex TOML block and the Claude Code `.mcp.json` block render from these.
+ * The portable `vp dlx` facade fetches the npm-published server on demand, so
+ * there is no machine-specific bin path to rot — the failure mode a hand-
+ * authored `~/.bun/bin/playwright-mcp` entry hits the moment that global bin
+ * disappears (ENOENT on spawn).
+ */
+const PLAYWRIGHT_MCP_COMMAND = 'vp';
+const PLAYWRIGHT_MCP_ARGS = [
+    'dlx',
+    '@playwright/mcp@latest',
+    '--caps=testing,storage,network,devtools',
+];
+function tomlStringArray(values) {
+    return `[${values.map((value) => `"${value}"`).join(', ')}]`;
+}
 export const PLAYWRIGHT_MCP_HEADER = `[mcp_servers.${PLAYWRIGHT_MCP_SERVER_NAME}]`;
 export const PLAYWRIGHT_MCP_BLOCK = `${PLAYWRIGHT_MCP_HEADER}
-command = "vp"
-args = ["dlx", "@playwright/mcp@latest", "--caps=testing,storage,network,devtools"]
+command = "${PLAYWRIGHT_MCP_COMMAND}"
+args = ${tomlStringArray(PLAYWRIGHT_MCP_ARGS)}
 enabled = true
 startup_timeout_sec = 30
 `;
@@ -70,6 +87,59 @@ export function ensureCodexPlaywrightMcp(input) {
     writeFileSync(configPath, next, 'utf8');
     return { kind: 'codex-playwright-mcp-written', path: configPath };
 }
+function claudePlaywrightServer() {
+    return { command: PLAYWRIGHT_MCP_COMMAND, args: [...PLAYWRIGHT_MCP_ARGS] };
+}
+function isJsonRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parseJson(raw) {
+    try {
+        return { ok: true, value: JSON.parse(raw) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+/**
+ * Upsert the `playwright` server into a `.mcp.json` document, preserving every
+ * other server (e.g. `context7`, `exa`) and any non-server top-level keys.
+ * Output is normalized to 2-space JSON with a trailing newline so repeated runs
+ * converge — idempotent after the first write.
+ */
+export function upsertClaudePlaywrightMcpServer(raw) {
+    const parsed = raw.trim().length > 0 ? parseJson(raw) : { ok: true, value: {} };
+    if (!parsed.ok) {
+        throw new Error('cannot upsert playwright into .mcp.json: existing file is not valid JSON');
+    }
+    const root = isJsonRecord(parsed.value) ? parsed.value : {};
+    const servers = isJsonRecord(root.mcpServers) ? root.mcpServers : {};
+    const next = {
+        ...root,
+        mcpServers: {
+            ...servers,
+            [PLAYWRIGHT_MCP_SERVER_NAME]: claudePlaywrightServer(),
+        },
+    };
+    return `${JSON.stringify(next, null, 2)}\n`;
+}
+export function ensureClaudePlaywrightMcp(input) {
+    const configPath = input.configPath ?? join(input.repoRoot, '.mcp.json');
+    if (input.options.dryRun) {
+        return { kind: 'claude-playwright-mcp-skipped-dry-run', path: configPath };
+    }
+    const existing = existsSync(configPath) ? readFileSync(configPath, 'utf8') : '';
+    if (existing.trim().length > 0 && !parseJson(existing).ok) {
+        return { kind: 'claude-playwright-mcp-invalid-json', path: configPath };
+    }
+    const next = upsertClaudePlaywrightMcpServer(existing);
+    if (next === existing) {
+        return { kind: 'claude-playwright-mcp-unchanged', path: configPath };
+    }
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync(configPath, next, 'utf8');
+    return { kind: 'claude-playwright-mcp-written', path: configPath };
+}
 // ────────────────────────────────────────────────────────────────────────────
 // Agent-kit MCP server registration
 // ────────────────────────────────────────────────────────────────────────────

package/dist/esm/hooks/doctor.d.ts

@@ -13,6 +13,8 @@ export interface DoctorCheck {
     name: string;
     ok: boolean;
     detail?: string;
+    /** Advisory checks surface a warning but do not flip the doctor's exit code. */
+    advisory?: boolean;
 }
 export interface DoctorResult {
     ok: boolean;
@@ -28,6 +30,16 @@ export interface RunHooksDoctorOptions {
 }
 export declare function findOwningPackageRoot(startDir: string): string | null;
 export declare function checkRtkOnPath(cwd?: string): Promise<DoctorCheck | null>;
+/**
+ * Verify the consumer's `.claude/settings.json` carries the managed agent-kit
+ * hook launchers. Since the hooks are single-sourced there (not in the plugin
+ * manifest), a missing reference means a plugin-only install that never ran
+ * `wp setup` — i.e. no agent-kit hooks are active.
+ */
+export declare function checkManagedHooksInstalled(cwd?: string): {
+    ok: boolean;
+    detail?: string;
+};
 export declare function runHooksDoctor(opts?: RunHooksDoctorOptions): Promise<DoctorResult>;
 export declare function printHooksDoctor(opts?: RunHooksDoctorOptions): Promise<number>;
 export {};

package/dist/esm/hooks/doctor.js

@@ -590,6 +590,40 @@ function checkLiveSourceDevLink(cwd = process.cwd()) {
         detail: `${state.package} → ${state.linkedFrom}`,
     };
 }
+// Marker for the managed hook launchers `wp setup` writes under
+// `.claude/hooks/managed/` (CLAUDE_MANAGED_HOOK_SUBDIR in the agent-hooks
+// scaffolder). The plugin manifest no longer ships hooks (they double-fired
+// against these and were the less reliable surface), so settings.json is the
+// single source — if it does not reference them, the hooks are not installed.
+const MANAGED_HOOK_MARKER = 'hooks/managed/wp-pretool-guard';
+/**
+ * Verify the consumer's `.claude/settings.json` carries the managed agent-kit
+ * hook launchers. Since the hooks are single-sourced there (not in the plugin
+ * manifest), a missing reference means a plugin-only install that never ran
+ * `wp setup` — i.e. no agent-kit hooks are active.
+ */
+export function checkManagedHooksInstalled(cwd = process.cwd()) {
+    const settingsPath = join(cwd, '.claude', 'settings.json');
+    if (!tryAccess(settingsPath)) {
+        return {
+            ok: false,
+            detail: 'no .claude/settings.json — run `wp setup` to install the agent-kit hooks',
+        };
+    }
+    try {
+        const raw = readFileSync(settingsPath, 'utf-8');
+        if (!raw.includes(MANAGED_HOOK_MARKER)) {
+            return {
+                ok: false,
+                detail: 'agent-kit hooks not found in .claude/settings.json — run `wp setup`',
+            };
+        }
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, detail: `failed to read .claude/settings.json: ${String(err)}` };
+    }
+}
 export async function runHooksDoctor(opts = {}) {
     const checks = [];
     const isWin = platform() === 'win32';
@@ -609,6 +643,11 @@ export async function runHooksDoctor(opts = {}) {
     }
     checks.push(checkConsumerCodexHookPaths(opts.cwd));
     checks.push({ name: 'plugin.json integrity', ...checkPluginJson() });
+    checks.push({
+        name: 'managed hooks installed (.claude/settings.json)',
+        advisory: true,
+        ...checkManagedHooksInstalled(opts.cwd),
+    });
     if (opts.skipMcp) {
         checks.push({ name: 'MCP server liveness', ok: true, detail: 'skipped (--skip-mcp)' });
     }
@@ -676,7 +715,7 @@ export async function runHooksDoctor(opts = {}) {
             }
         }
     }
-    const nonMcpChecks = checks.filter((c) => !c.name.startsWith('MCP '));
+    const nonMcpChecks = checks.filter((c) => !c.name.startsWith('MCP ') && !c.advisory);
     const overallOk = nonMcpChecks.every((c) => c.ok);
     return { ok: overallOk, checks };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpresso/agent-kit",
-  "version": "0.26.0",
+  "version": "0.26.2",
   "private": false,
   "repository": {
     "type": "git",
@@ -710,10 +710,10 @@
     "@stryker-mutator/typescript-checker": "^9.6.1",
     "@playwright/test": "^1.55.0",
     "wrangler": "^4.50.0",
-    "@webpresso/agent-kit-runtime-darwin-arm64": "0.26.0",
-    "@webpresso/agent-kit-runtime-darwin-x64": "0.26.0",
-    "@webpresso/agent-kit-runtime-linux-x64": "0.26.0",
-    "@webpresso/agent-kit-runtime-linux-arm64": "0.26.0",
-    "@webpresso/agent-kit-runtime-windows-x64": "0.26.0"
+    "@webpresso/agent-kit-runtime-darwin-arm64": "0.26.2",
+    "@webpresso/agent-kit-runtime-darwin-x64": "0.26.2",
+    "@webpresso/agent-kit-runtime-linux-x64": "0.26.2",
+    "@webpresso/agent-kit-runtime-linux-arm64": "0.26.2",
+    "@webpresso/agent-kit-runtime-windows-x64": "0.26.2"
   }
 }