@webpresso/agent-kit 0.21.0

package/dist/esm/cli/commands/init/scaffolders/agent-hooks/skill-hooks.js

@@ -0,0 +1,123 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import matter from 'gray-matter';
+import { z } from 'zod';
+const SKILL_HOOK_EVENTS = [
+    'PreToolUse',
+    'PostToolUse',
+    'Stop',
+    'SessionStart',
+    'UserPromptSubmit',
+];
+const RESERVED_GLOBAL_BINS = [
+    'wp-pretool-guard',
+    'wp-post-tool',
+    'wp-guard-switch',
+    'wp-sessionstart-routing',
+    'wp-stop-qa',
+];
+const TRACEABILITY_PREFIX = '# from-skill:';
+const SkillHookEntrySchema = z
+    .object({
+    matcher: z.string().trim().min(1).optional(),
+    command: z.string().trim().min(1, 'command is required'),
+    timeout: z.number().int().positive().optional(),
+})
+    .strict();
+const SkillHooksSchema = z
+    .object({
+    PreToolUse: z.array(SkillHookEntrySchema).optional(),
+    PostToolUse: z.array(SkillHookEntrySchema).optional(),
+    Stop: z.array(SkillHookEntrySchema).optional(),
+    SessionStart: z.array(SkillHookEntrySchema).optional(),
+    UserPromptSubmit: z.array(SkillHookEntrySchema).optional(),
+})
+    .strict()
+    .superRefine((hooks, ctx) => {
+    for (const event of ['PreToolUse', 'PostToolUse']) {
+        const entries = hooks[event] ?? [];
+        entries.forEach((entry, index) => {
+            if (!entry.matcher) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: `${event} hooks require a matcher`,
+                    path: [event, index, 'matcher'],
+                });
+            }
+        });
+    }
+    for (const event of SKILL_HOOK_EVENTS) {
+        const entries = hooks[event] ?? [];
+        entries.forEach((entry, index) => {
+            const reserved = RESERVED_GLOBAL_BINS.find((bin) => entry.command.includes(bin));
+            if (reserved) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: `reserved global hook command ${reserved} is not allowed in skill hooks`,
+                    path: [event, index, 'command'],
+                });
+            }
+        });
+    }
+});
+function formatIssues(error) {
+    return error.issues
+        .map((issue) => `${issue.path.join('.') || 'hooks'}: ${issue.message}`)
+        .join('; ');
+}
+export function validateSkillHooks(skillName, hooks) {
+    const parsed = SkillHooksSchema.safeParse(hooks ?? {});
+    if (!parsed.success) {
+        throw new Error(`Invalid hooks frontmatter in skill ${skillName}: ${formatIssues(parsed.error)}`);
+    }
+    return parsed.data;
+}
+export function extractSkillHooks(skillsDir) {
+    if (!existsSync(skillsDir))
+        return [];
+    const hooks = [];
+    // Wave-3: `.agent/skills/<slug>` may be a symlink (catalog projection via
+    // unified-sync) — `withFileTypes` reports isDirectory()=false for those, so
+    // we stat-resolve through symlinks before filtering.
+    const skillNames = readdirSync(skillsDir, { withFileTypes: true })
+        .filter((entry) => {
+        if (entry.isDirectory())
+            return true;
+        if (!entry.isSymbolicLink())
+            return false;
+        try {
+            return statSync(join(skillsDir, entry.name)).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    })
+        .map((entry) => entry.name)
+        .sort();
+    for (const skillName of skillNames) {
+        const skillPath = join(skillsDir, skillName, 'SKILL.md');
+        if (!existsSync(skillPath))
+            continue;
+        const parsed = matter(readFileSync(skillPath, 'utf8'));
+        const validated = validateSkillHooks(skillName, parsed.data.hooks);
+        for (const event of SKILL_HOOK_EVENTS) {
+            for (const entry of validated[event] ?? []) {
+                hooks.push({
+                    skillName,
+                    event,
+                    matcher: entry.matcher,
+                    command: entry.command,
+                    timeout: entry.timeout,
+                });
+            }
+        }
+    }
+    return hooks;
+}
+export function buildSkillTag(skillName) {
+    return `${TRACEABILITY_PREFIX} ${skillName}`;
+}
+export function isTaggedSkillHook(command) {
+    return typeof command === 'string' && command.includes(TRACEABILITY_PREFIX);
+}
+//# sourceMappingURL=skill-hooks.js.map

package/dist/esm/cli/commands/init/scaffolders/audit-hooks/index.d.ts

@@ -0,0 +1,16 @@
+import type { MergeOptions } from '#cli/commands/init/merge';
+export interface ScaffoldAuditHooksInput {
+    repoRoot: string;
+    options: MergeOptions;
+}
+export interface ScaffoldAuditHooksResult {
+    preCommitPath: string;
+    action: 'created' | 'appended' | 'identical' | 'skipped-dry';
+}
+/**
+ * Append audit hook lines to `.husky/pre-commit` if not already present.
+ * Creates the file with a shebang if it does not exist.
+ * Idempotent: re-running produces no change when lines are present.
+ */
+export declare function scaffoldAuditHooks(input: ScaffoldAuditHooksInput): ScaffoldAuditHooksResult;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,65 @@
+/**
+ * `audit-hooks` scaffolder preset.
+ *
+ * Extends `.husky/pre-commit` to ensure the shared policy checks are present.
+ *
+ * Additive: appends lines only when not already present (idempotent).
+ * Does not remove existing content.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * Lines to append to `.husky/pre-commit` (each must be idempotently checked).
+ */
+const AUDIT_HOOK_LINES = [
+    '# webpresso audit hooks (staged mode — fast)',
+    'bun scripts/check-no-dev-vars.ts',
+    'wp audit absolute-path-policy --root .',
+    'bun scripts/audit-secret-provider-quarantine.ts',
+];
+const SHEBANG = '#!/bin/sh\n';
+function hasEquivalentLine(existingContent, line) {
+    if (existingContent.includes(line))
+        return true;
+    if (line === '# webpresso audit hooks (staged mode — fast)') {
+        return (existingContent.includes('check-no-dev-vars.ts') &&
+            (existingContent.includes('wp audit absolute-path-policy --root .') ||
+                existingContent.includes('"$WP" audit absolute-path-policy --root .')) &&
+            existingContent.includes('audit-secret-provider-quarantine.ts'));
+    }
+    if (line === 'wp audit absolute-path-policy --root .') {
+        return existingContent.includes('"$WP" audit absolute-path-policy --root .');
+    }
+    return false;
+}
+/**
+ * Append audit hook lines to `.husky/pre-commit` if not already present.
+ * Creates the file with a shebang if it does not exist.
+ * Idempotent: re-running produces no change when lines are present.
+ */
+export function scaffoldAuditHooks(input) {
+    const preCommitPath = path.join(input.repoRoot, '.husky', 'pre-commit');
+    if (input.options.dryRun) {
+        return { preCommitPath, action: 'skipped-dry' };
+    }
+    const huskyDir = path.dirname(preCommitPath);
+    mkdirSync(huskyDir, { recursive: true });
+    const existingContent = existsSync(preCommitPath) ? readFileSync(preCommitPath, 'utf8') : null;
+    if (existingContent === null) {
+        // Create fresh file
+        const newContent = [SHEBANG, ...AUDIT_HOOK_LINES].join('\n') + '\n';
+        writeFileSync(preCommitPath, newContent, 'utf8');
+        return { preCommitPath, action: 'created' };
+    }
+    // Determine which lines are missing
+    const missingLines = AUDIT_HOOK_LINES.filter((line) => !hasEquivalentLine(existingContent, line));
+    if (missingLines.length === 0) {
+        return { preCommitPath, action: 'identical' };
+    }
+    // Append missing lines
+    const separator = existingContent.endsWith('\n') ? '' : '\n';
+    const appended = existingContent + separator + missingLines.join('\n') + '\n';
+    writeFileSync(preCommitPath, appended, 'utf8');
+    return { preCommitPath, action: 'appended' };
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/cli/commands/init/scaffolders/claude-plugin/index.d.ts

@@ -0,0 +1,33 @@
+import type { MergeOptions } from '#cli/commands/init/merge';
+export declare const CLAUDE_PLUGIN_ID = "webpresso@webpresso";
+export interface EnsureClaudePluginInput {
+    options: MergeOptions;
+    packageRoot: string;
+    commandExists?: (command: string) => boolean;
+    runCommand?: (command: string, args: readonly string[]) => number;
+}
+export type EnsureClaudePluginResult = {
+    kind: 'claude-plugin-installed';
+    packageRoot: string;
+    pluginId: string;
+} | {
+    kind: 'claude-plugin-skipped-dry-run';
+    packageRoot: string;
+} | {
+    kind: 'claude-plugin-skipped-opt-out';
+    packageRoot: string;
+} | {
+    kind: 'claude-plugin-skipped-no-cli';
+    packageRoot: string;
+} | {
+    kind: 'claude-plugin-unavailable';
+    packageRoot: string;
+} | {
+    kind: 'claude-plugin-failed';
+    packageRoot: string;
+    pluginId: string;
+    step: 'marketplace-add' | 'plugin-install' | 'plugin-update';
+    exitCode: number;
+};
+export declare function ensureClaudeCodeUserPlugin(input: EnsureClaudePluginInput): EnsureClaudePluginResult;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,67 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+export const CLAUDE_PLUGIN_ID = 'webpresso@webpresso';
+function defaultCommandExists(command) {
+    const result = spawnSync('which', [command], { stdio: 'ignore' });
+    return result.status === 0;
+}
+function defaultRunCommand(command, args) {
+    const result = spawnSync(command, [...args], {
+        stdio: 'inherit',
+        env: process.env,
+    });
+    if (result.error)
+        throw result.error;
+    return result.status ?? 1;
+}
+export function ensureClaudeCodeUserPlugin(input) {
+    const packageRoot = input.packageRoot;
+    const pluginManifestPath = join(packageRoot, '.claude-plugin', 'plugin.json');
+    if (!existsSync(pluginManifestPath)) {
+        return { kind: 'claude-plugin-unavailable', packageRoot };
+    }
+    if (input.options.dryRun) {
+        return { kind: 'claude-plugin-skipped-dry-run', packageRoot };
+    }
+    if (process.env.WP_SKIP_CLAUDE_PLUGIN === '1') {
+        return { kind: 'claude-plugin-skipped-opt-out', packageRoot };
+    }
+    const commandExists = input.commandExists ?? defaultCommandExists;
+    if (!commandExists('claude')) {
+        return { kind: 'claude-plugin-skipped-no-cli', packageRoot };
+    }
+    const runCommand = input.runCommand ?? defaultRunCommand;
+    const steps = [
+        {
+            step: 'marketplace-add',
+            args: ['plugin', 'marketplace', 'add', '--scope', 'user', packageRoot],
+        },
+        {
+            step: 'plugin-install',
+            args: ['plugin', 'install', '--scope', 'user', CLAUDE_PLUGIN_ID],
+        },
+        {
+            step: 'plugin-update',
+            args: ['plugin', 'update', '--scope', 'user', CLAUDE_PLUGIN_ID],
+        },
+    ];
+    for (const { step, args } of steps) {
+        const exitCode = runCommand('claude', args);
+        if (exitCode !== 0) {
+            return {
+                kind: 'claude-plugin-failed',
+                packageRoot,
+                pluginId: CLAUDE_PLUGIN_ID,
+                step,
+                exitCode,
+            };
+        }
+    }
+    return {
+        kind: 'claude-plugin-installed',
+        packageRoot,
+        pluginId: CLAUDE_PLUGIN_ID,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/cli/commands/init/scaffolders/claude-rules/index.d.ts

@@ -0,0 +1,7 @@
+import type { MergeOptions, MergeResult } from '#cli/commands/init/merge';
+export interface ScaffoldClaudeRulesInput {
+    repoRoot: string;
+    options: MergeOptions;
+}
+export declare function scaffoldClaudeRules(input: ScaffoldClaudeRulesInput): MergeResult[];
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,127 @@
+/**
+ * Create `.claude/rules/<name>.md` symlinks pointing to the canonical catalog
+ * rules directory for the current mode.
+ */
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync, } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readConfig } from '#cli/commands/init/config';
+import { readPackageJson } from '#cli/commands/init/detect-consumer';
+function detectMode(repoRoot) {
+    const pkg = readPackageJson(repoRoot).info;
+    if (pkg?.name === 'webpresso') {
+        return {
+            mode: 'self',
+            sourceRoot: join(repoRoot, 'catalog', 'agent', 'rules'),
+        };
+    }
+    const installedPackageJsonPath = join(repoRoot, 'node_modules', 'webpresso', 'package.json');
+    const installedRulesRoot = join(repoRoot, 'node_modules', 'webpresso', 'catalog', 'agent', 'rules');
+    if (existsSync(installedPackageJsonPath) && existsSync(installedRulesRoot)) {
+        return {
+            mode: 'consumer',
+            sourceRoot: installedRulesRoot,
+        };
+    }
+    return {
+        mode: 'package-fallback',
+        sourceRoot: join(resolveCurrentPackageRoot(), 'catalog', 'agent', 'rules'),
+    };
+}
+function writeOverrideRule(targetPath, sourcePath, options) {
+    const incoming = readFileSync(sourcePath, 'utf8');
+    if (!existsSync(targetPath)) {
+        if (options.dryRun)
+            return { targetPath, action: 'created' };
+        writeFileSync(targetPath, incoming);
+        return { targetPath, action: 'created' };
+    }
+    const stat = lstatSync(targetPath);
+    if (stat.isSymbolicLink()) {
+        if (options.dryRun)
+            return { targetPath, action: 'overwritten' };
+        rmSync(targetPath);
+        writeFileSync(targetPath, incoming);
+        return { targetPath, action: 'overwritten' };
+    }
+    const existing = readFileSync(targetPath, 'utf8');
+    if (existing === incoming)
+        return { targetPath, action: 'identical' };
+    if (options.overwrite) {
+        if (options.dryRun)
+            return { targetPath, action: 'overwritten' };
+        writeFileSync(targetPath, incoming);
+        return { targetPath, action: 'overwritten' };
+    }
+    if (options.dryRun)
+        return { targetPath, action: 'skipped-dry' };
+    return { targetPath, action: 'drifted' };
+}
+function resolveCurrentPackageRoot() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 8; depth++) {
+        if (existsSync(join(dir, 'package.json')) && existsSync(join(dir, 'catalog'))) {
+            return dir;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new Error('wp init: could not locate the webpresso package root for claude-rules fallback.');
+}
+export function scaffoldClaudeRules(input) {
+    const { repoRoot, options } = input;
+    const mode = detectMode(repoRoot);
+    const rulesSource = mode.sourceRoot;
+    const rulesTarget = join(repoRoot, '.claude', 'rules');
+    const results = [];
+    if (!existsSync(rulesSource))
+        return results;
+    const entries = readdirSync(rulesSource).filter((f) => f.endsWith('.md') && f !== 'README.md' && f !== '.markdownlint.json');
+    const overrideSet = new Set(readConfig(repoRoot)?.rules.overrides ?? []);
+    if (entries.length === 0)
+        return results;
+    if (!options.dryRun) {
+        mkdirSync(rulesTarget, { recursive: true });
+    }
+    for (const name of entries) {
+        const sourcePath = join(rulesSource, name);
+        const targetPath = join(rulesTarget, name);
+        if (overrideSet.has(name.replace(/\.md$/u, ''))) {
+            results.push(writeOverrideRule(targetPath, sourcePath, options));
+            continue;
+        }
+        const symTarget = relative(dirname(targetPath), sourcePath);
+        if (options.dryRun) {
+            results.push({ targetPath, action: 'created' });
+            continue;
+        }
+        try {
+            const stat = lstatSync(targetPath);
+            if (stat.isSymbolicLink()) {
+                const currentTarget = readlinkSync(targetPath);
+                if (currentTarget === symTarget) {
+                    results.push({ targetPath, action: 'identical' });
+                }
+                else if (options.overwrite) {
+                    rmSync(targetPath);
+                    symlinkSync(symTarget, targetPath);
+                    results.push({ targetPath, action: 'overwritten' });
+                }
+                else {
+                    results.push({ targetPath, action: 'drifted' });
+                }
+            }
+            else {
+                results.push({ targetPath, action: 'identical' });
+            }
+        }
+        catch {
+            symlinkSync(symTarget, targetPath);
+            results.push({ targetPath, action: 'created' });
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,17 @@
+import { spawnSync } from 'node:child_process';
+import type { MergeOptions } from '#cli/commands/init/merge';
+export interface EnsureCodexCliInput {
+    options: MergeOptions;
+    spawn?: typeof spawnSync;
+}
+export type EnsureCodexCliResult = {
+    kind: 'codex-cli-ok';
+    installed: boolean;
+} | {
+    kind: 'codex-cli-skipped-dry-run';
+} | {
+    kind: 'codex-cli-unavailable';
+    hint: string;
+};
+export declare function ensureCodexCli(input: EnsureCodexCliInput): EnsureCodexCliResult;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,27 @@
+import { spawnSync } from 'node:child_process';
+const NOT_FOUND_HINT = 'codex is not on PATH after `vp install -g @openai/codex`. Install it manually and re-run.';
+function shouldSkipCodexRefresh(env = process.env) {
+    return env.WP_SKIP_UPDATE_CHECK === '1';
+}
+export function ensureCodexCli(input) {
+    if (input.options.dryRun)
+        return { kind: 'codex-cli-skipped-dry-run' };
+    const spawn = input.spawn ?? spawnSync;
+    let installed = false;
+    let probe = spawn('codex', ['--version'], { encoding: 'utf8' });
+    if (probe.error || (probe.status !== null && probe.status !== 0)) {
+        const install = spawn('vp', ['install', '-g', '@openai/codex'], { stdio: 'inherit' });
+        if (install.status !== 0)
+            return { kind: 'codex-cli-unavailable', hint: NOT_FOUND_HINT };
+        installed = true;
+        probe = spawn('codex', ['--version'], { encoding: 'utf8' });
+        if (probe.error || (probe.status !== null && probe.status !== 0)) {
+            return { kind: 'codex-cli-unavailable', hint: NOT_FOUND_HINT };
+        }
+    }
+    else if (!shouldSkipCodexRefresh()) {
+        spawn('vp', ['update', '-g', '@openai/codex'], { stdio: 'inherit' });
+    }
+    return { kind: 'codex-cli-ok', installed };
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,79 @@
+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 WEBPRESSO_MCP_SERVER_NAME = "webpresso";
+export declare const WEBPRESSO_MCP_HEADER = "[mcp_servers.webpresso]";
+export interface EnsureCodexPlaywrightMcpInput {
+    options: MergeOptions;
+    /** Test seam. Defaults to `$CODEX_HOME/config.toml` or `~/.codex/config.toml`. */
+    configPath?: string;
+}
+export type EnsureCodexPlaywrightMcpResult = {
+    kind: 'codex-playwright-mcp-written';
+    path: string;
+} | {
+    kind: 'codex-playwright-mcp-unchanged';
+    path: string;
+} | {
+    kind: 'codex-playwright-mcp-skipped-dry-run';
+    path: string;
+};
+export declare function upsertPlaywrightMcpServer(raw: string): string;
+export declare function ensureCodexPlaywrightMcp(input: EnsureCodexPlaywrightMcpInput): EnsureCodexPlaywrightMcpResult;
+export interface WebpressoInstallProbe {
+    /** Test seam — override the candidate roots. Default: probe in fixed order. */
+    candidates?: readonly string[];
+    /** Test seam — return value for `pnpm root -g`. Default: shell out. */
+    pnpmGlobalRoot?: () => string | null;
+    /** Test seam — return value for `npm root -g`. Default: shell out. */
+    npmGlobalRoot?: () => string | null;
+}
+/**
+ * Resolve the absolute path to webpresso's MCP entry on this machine. Probes
+ * the locations consumers use to install webpresso, in order of stability:
+ *
+ *   1. Claude plugin install — `~/.claude/plugins/cache/webpresso/webpresso/`
+ *      (path-stable; updated by Claude Code's plugin manager)
+ *   2. bun global — `~/.bun/install/global/node_modules/webpresso/`
+ *   3. pnpm global — `$(pnpm root -g)/webpresso/`
+ *   4. npm global — `$(npm root -g)/webpresso/`
+ *
+ * Returns `null` when none of the candidates contain `src/mcp/cli.ts`. The
+ * caller surfaces a clear error in that case rather than writing a broken
+ * codex config.
+ */
+export declare function findWebpressoMcpEntry(probe?: WebpressoInstallProbe): string | null;
+export declare function agentKitMcpLaunchCommand(entryPath: string): {
+    command: 'bun' | 'node';
+    args: string[];
+};
+export declare function agentKitMcpBlock(entryPath: string): string;
+export declare function upsertWebpressoMcpServer(raw: string, entryPath: string): string;
+export interface EnsureCodexWebpressoMcpInput {
+    options: MergeOptions;
+    /** Test seam — override the resolved MCP entry path. */
+    entryPath?: string;
+    /** Test seam — override `$CODEX_HOME/config.toml`. */
+    configPath?: string;
+    /** Test seam — override the install-discovery probe. */
+    probe?: WebpressoInstallProbe;
+}
+export type EnsureCodexWebpressoMcpResult = {
+    kind: 'codex-webpresso-mcp-written';
+    path: string;
+    entryPath: string;
+} | {
+    kind: 'codex-webpresso-mcp-unchanged';
+    path: string;
+    entryPath: string;
+} | {
+    kind: 'codex-webpresso-mcp-skipped-dry-run';
+    path: string;
+} | {
+    kind: 'codex-webpresso-mcp-not-installed';
+    path: string;
+    checked: readonly string[];
+};
+export declare function ensureCodexWebpressoMcp(input: EnsureCodexWebpressoMcpInput): EnsureCodexWebpressoMcpResult;
+//# sourceMappingURL=index.d.ts.map