@webpresso/agent-kit 0.21.4 → 0.23.0

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

@@ -9,9 +9,10 @@
  *
  * Runs by default on every `wp setup`.
  */
-import { chmodSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { patchJsonFile } from '#cli/commands/init/merge';
 import { CodexAppServerClient } from '#codex/app-server/client.js';
 import { normalizeGlobalCodexHooksFile, resolveBinaryOnPath, } from '#cli/commands/init/scaffolders/agent-hooks/codex-global-normalize';
@@ -28,16 +29,32 @@ import { buildSkillTag, extractSkillHooks, isTaggedSkillHook, } from './skill-ho
 //   bypass when the guard binary is missing/non-executable.
 const PRETOOL_GUARD_BIN = 'wp-pretool-guard';
 const PRETOOL_GUARD_MISSING_DENY = `printf '%s\\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"wp-pretool-guard is unavailable. Run vp install or wp setup."}}'`;
+const CLAUDE_MANAGED_HOOK_SUBDIR = '.claude/hooks/managed';
+const CODEX_MANAGED_HOOK_SUBDIR = '.codex/managed-hooks';
+function claudeManagedHookLauncherPath(name) {
+    return `$CLAUDE_PROJECT_DIR/${CLAUDE_MANAGED_HOOK_SUBDIR}/${name}.sh`;
+}
+function codexManagedHookLauncherPath(repoRoot, name) {
+    return resolve(repoRoot, CODEX_MANAGED_HOOK_SUBDIR, `${name}.sh`);
+}
+function quoteShell(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function quoteHookCommandPath(value) {
+    if (value.startsWith('$CLAUDE_PROJECT_DIR/'))
+        return `"${value}"`;
+    return quoteShell(value);
+}
 function buildGuardedHookCommand(binPath, name) {
+    const quotedBinPath = quoteHookCommandPath(binPath);
     if (name === PRETOOL_GUARD_BIN) {
-        return `[ -x "${binPath}" ] && "${binPath}" || ${PRETOOL_GUARD_MISSING_DENY}`;
+        return `[ -x ${quotedBinPath} ] && ${quotedBinPath} || ${PRETOOL_GUARD_MISSING_DENY}`;
     }
-    return `[ -x "${binPath}" ] && "${binPath}" || true`;
+    return `[ -x ${quotedBinPath} ] && ${quotedBinPath} || true`;
 }
-const CC_BIN = (name) => buildGuardedHookCommand(`$CLAUDE_PROJECT_DIR/node_modules/.bin/${name}`, name);
+const CC_BIN = (name) => buildGuardedHookCommand(claudeManagedHookLauncherPath(name), name);
 const CODEX_BIN = (repoRoot) => (name) => {
-    const binPath = resolve(repoRoot, 'node_modules', '.bin', name);
-    return buildGuardedHookCommand(binPath, name);
+    return buildGuardedHookCommand(codexManagedHookLauncherPath(repoRoot, name), name);
 };
 // Canonical hook event names recognised by both Claude Code and Codex CLI.
 // Used by `hoistTopLevelEvents` to identify legacy flat-form keys to migrate.
@@ -77,6 +94,8 @@ const DIRECT_NODE_MODULES_BIN_PATTERN = /^(?:\.\/|\/.*\/)?node_modules\/\.bin\/(
 const GUARDED_NODE_MODULES_BIN_PATTERN = /^\[ -x (["']?)((?:\.\/|\/.*\/)?node_modules\/\.bin\/([\w-]+))\1 \] && \1\2\1 \|\| (?:true|printf .+)$/u;
 const DIRECT_CLAUDE_NODE_MODULES_BIN_PATTERN = /^["']?\$CLAUDE_PROJECT_DIR\/node_modules\/\.bin\/([\w-]+)["']?$/u;
 const GUARDED_CLAUDE_NODE_MODULES_BIN_PATTERN = /^\[ -x (["']?)\$CLAUDE_PROJECT_DIR\/node_modules\/\.bin\/([\w-]+)\1 \] && \1\$CLAUDE_PROJECT_DIR\/node_modules\/\.bin\/\2\1 \|\| (?:true|printf .+)$/u;
+const DIRECT_MANAGED_HOOK_LAUNCHER_PATTERN = /^(?:["']?)((?:\$CLAUDE_PROJECT_DIR\/\.claude\/hooks\/managed|(?:\.\/|\/.*\/)?\.claude\/hooks\/managed|(?:\.\/|\/.*\/)?\.codex\/managed-hooks)\/((?:wp|ak)-[\w-]+)\.sh)(?:["']?)$/u;
+const GUARDED_MANAGED_HOOK_LAUNCHER_PATTERN = /^\[ -x (["']?)((?:\$CLAUDE_PROJECT_DIR\/\.claude\/hooks\/managed|(?:\.\/|\/.*\/)?\.claude\/hooks\/managed|(?:\.\/|\/.*\/)?\.codex\/managed-hooks)\/((?:wp|ak)-[\w-]+)\.sh)\1 \] && \1\2\1 \|\| (?:true|printf .+)$/u;
 // Capture the basename of any path that ends in a known script extension.
 // Handles trailing chars (quote, space, end-of-string).
 const SCRIPT_BASENAME_PATTERN = new RegExp(String.raw `([\w-]+\.(?:${SCRIPT_EXTENSIONS.join('|')}))(?=$|["'\s])`, 'u');
@@ -110,9 +129,15 @@ function extractAgentKitCodexBinName(command) {
     const directBinMatch = DIRECT_NODE_MODULES_BIN_PATTERN.exec(normalizedCommand);
     if (directBinMatch !== null)
         return directBinMatch[1] ?? null;
+    const directManagedLauncherMatch = DIRECT_MANAGED_HOOK_LAUNCHER_PATTERN.exec(normalizedCommand);
+    if (directManagedLauncherMatch !== null)
+        return directManagedLauncherMatch[2] ?? null;
     const guardedBinMatch = GUARDED_NODE_MODULES_BIN_PATTERN.exec(command.trim());
     if (guardedBinMatch !== null)
         return guardedBinMatch[3] ?? null;
+    const guardedManagedLauncherMatch = GUARDED_MANAGED_HOOK_LAUNCHER_PATTERN.exec(command.trim());
+    if (guardedManagedLauncherMatch !== null)
+        return guardedManagedLauncherMatch[3] ?? null;
     return null;
 }
 function extractClaudeBinName(command) {
@@ -120,9 +145,15 @@ function extractClaudeBinName(command) {
     const directBinMatch = DIRECT_CLAUDE_NODE_MODULES_BIN_PATTERN.exec(normalizedCommand);
     if (directBinMatch !== null)
         return directBinMatch[1] ?? null;
+    const directManagedLauncherMatch = DIRECT_MANAGED_HOOK_LAUNCHER_PATTERN.exec(normalizedCommand);
+    if (directManagedLauncherMatch !== null)
+        return directManagedLauncherMatch[2] ?? null;
     const guardedBinMatch = GUARDED_CLAUDE_NODE_MODULES_BIN_PATTERN.exec(command.trim());
     if (guardedBinMatch !== null)
         return guardedBinMatch[2] ?? null;
+    const guardedManagedLauncherMatch = GUARDED_MANAGED_HOOK_LAUNCHER_PATTERN.exec(command.trim());
+    if (guardedManagedLauncherMatch !== null)
+        return guardedManagedLauncherMatch[3] ?? null;
     return null;
 }
 function stripSingleShellQuotePair(value) {
@@ -305,20 +336,33 @@ function normalizeCodexAgentKitCommands(hooks, repoRoot) {
     }
     return normalized;
 }
-function pruneLegacyClaudeAgentKitCommands(hooks) {
+function normalizeClaudeAgentKitCommands(hooks) {
     const normalized = {};
     for (const [event, groups] of Object.entries(hooks)) {
-        const keptGroups = groups
-            .map((group) => {
-            const keptHooks = group.hooks.filter((hook) => {
-                const classification = classifyWebpressoHookBin(extractClaudeBinName(hook.command));
-                return classification === null || classification.kind !== 'legacy';
-            });
-            return keptHooks.length > 0 ? { ...group, hooks: keptHooks } : null;
-        })
-            .filter((group) => group !== null);
-        if (keptGroups.length > 0)
-            normalized[event] = keptGroups;
+        const normalizedGroups = groups.reduce((dedupedGroups, group) => {
+            const nextGroup = {
+                ...group,
+                hooks: group.hooks.flatMap((hook) => {
+                    const command = hook.command;
+                    if (typeof command !== 'string')
+                        return hook;
+                    const classification = classifyWebpressoHookBin(extractClaudeBinName(command));
+                    if (classification === null)
+                        return hook;
+                    if (classification.kind === 'legacy')
+                        return [];
+                    return {
+                        ...hook,
+                        command: CC_BIN(classification.binName),
+                    };
+                }),
+            };
+            if (nextGroup.hooks.length === 0)
+                return dedupedGroups;
+            return ensureGroup(dedupedGroups, nextGroup);
+        }, []);
+        if (normalizedGroups.length > 0)
+            normalized[event] = normalizedGroups;
     }
     return normalized;
 }
@@ -380,7 +424,7 @@ function patchClaudeUserSettings(existing) {
     return next;
 }
 function patchClaudeSettings(existing, skillHooks) {
-    const existingHooks = pruneLegacyClaudeAgentKitCommands((existing.hooks ?? {}));
+    const existingHooks = normalizeClaudeAgentKitCommands((existing.hooks ?? {}));
     const withSkills = mergeSkillHooks(existingHooks, skillHooks);
     const webpresso = buildWebpressoHookGroups({
         resolveBin: CC_BIN,
@@ -560,8 +604,74 @@ function ensureGstackHooks(repoRoot, options = {}) {
         chmodSync(sessionPath, 0o755);
     }
 }
+function resolveProjectHookBinPath(repoRoot, binName) {
+    return resolve(repoRoot, 'node_modules', '@webpresso', 'agent-kit', 'bin', `${binName}.js`);
+}
+function resolvePackageHookBin(binName) {
+    return join(resolvePackageRoot(), 'bin', `${binName}.js`);
+}
+function resolvePackageRoot() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 10; depth++) {
+        if (existsSync(join(dir, 'package.json')) && existsSync(join(dir, 'bin', 'wp.js'))) {
+            return dir;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new Error('wp setup: could not locate @webpresso/agent-kit package root for hook launchers.');
+}
+function renderManagedWebpressoHookLauncher(repoRoot, binName) {
+    const nodeBinary = quoteShell(process.execPath);
+    const projectBinPath = quoteShell(resolveProjectHookBinPath(repoRoot, binName));
+    const fallbackBinPath = quoteShell(resolvePackageHookBin(binName));
+    const missingFallback = binName === PRETOOL_GUARD_BIN ? PRETOOL_GUARD_MISSING_DENY : 'exit 0';
+    return `#!/bin/sh
+NODE_BINARY=${nodeBinary}
+PROJECT_BIN_PATH=${projectBinPath}
+FALLBACK_BIN_PATH=${fallbackBinPath}
+
+if [ ! -x "$NODE_BINARY" ]; then
+  ${missingFallback}
+  exit 0
+fi
+
+if [ -f "$PROJECT_BIN_PATH" ]; then
+  exec "$NODE_BINARY" "$PROJECT_BIN_PATH" "$@"
+fi
+
+if [ -f "$FALLBACK_BIN_PATH" ]; then
+  exec "$NODE_BINARY" "$FALLBACK_BIN_PATH" "$@"
+fi
+
+${missingFallback}
+exit 0
+`;
+}
+function ensureManagedWebpressoHookLaunchers(repoRoot, options = {}) {
+    if (options.dryRun)
+        return;
+    const launcherTargets = [
+        join(repoRoot, CLAUDE_MANAGED_HOOK_SUBDIR),
+        join(repoRoot, CODEX_MANAGED_HOOK_SUBDIR),
+    ];
+    for (const directory of launcherTargets) {
+        mkdirSync(directory, { recursive: true });
+        for (const binName of WEBPRESSO_HOOK_BIN_NAMES) {
+            const launcherPath = join(directory, `${binName}.sh`);
+            const content = renderManagedWebpressoHookLauncher(repoRoot, binName);
+            if (!existsSync(launcherPath) || readFileSync(launcherPath, 'utf8') !== content) {
+                writeFileSync(launcherPath, content, 'utf8');
+            }
+            chmodSync(launcherPath, 0o755);
+        }
+    }
+}
 export async function scaffoldAgentHooks(input) {
     ensureGstackHooks(input.repoRoot, input.options);
+    ensureManagedWebpressoHookLaunchers(input.repoRoot, input.options);
     const skillHooks = extractSkillHooks(join(input.repoRoot, '.agent', 'skills'));
     const result = {
         claude: patchJsonFile(join(input.repoRoot, '.claude', 'settings.json'), (existing) => patchClaudeSettings(existing, skillHooks), input.options),

package/dist/esm/cli/commands/init/scaffolders/agent-kit-global/index.d.ts

@@ -0,0 +1,65 @@
+/**
+ * `agent-kit-global` self-update scaffolder.
+ *
+ * Keeps the ONE globally-distributed `@webpresso/agent-kit` binary fresh on
+ * every `wp setup`, mirroring how omx / omc / codex / claude self-update their
+ * own global installs. The PATH `wp`, the Claude plugin MCP, and the agent
+ * hooks all resolve to this single global binary, so refreshing it here means
+ * the next invocation everywhere runs the latest published release.
+ *
+ * Uses the exact same command the auto-update installer infers
+ * (`buildVpGlobalInstallCommand` — single source of truth), so there is no
+ * second place that can drift on the install incantation.
+ *
+ * Skipped (no-op, non-fatal) when:
+ *   - `--dry-run` (no writes anywhere),
+ *   - `WP_SKIP_AUTO_INSTALL=1` (the documented opt-out, surfaced in the update
+ *     banner),
+ *   - the running binary resolves into a webpresso source/git clone — a global
+ *     install would clobber the developer's working clone with a published
+ *     tarball (`detectGitInstall`),
+ *   - `vp` is not on PATH (nothing to install with).
+ *
+ * A failed refresh is reported but NEVER fails consumer setup: keeping the
+ * global tool current is ancillary to scaffolding the consumer repo (same
+ * warn-only contract as the codex-cli scaffolder).
+ */
+import { spawnSync } from 'node:child_process';
+import type { MergeOptions } from '#cli/commands/init/merge';
+import { type SpinnerFactory } from '#cli/commands/init/scaffolders/spinner';
+export interface EnsureAgentKitGlobalInput {
+    options: MergeOptions;
+    /** DI seam for child_process.spawnSync. */
+    spawn?: typeof spawnSync;
+    /** DI seam for environment-backed opt-out. */
+    env?: NodeJS.ProcessEnv;
+    /** The running binary path (defaults to process.argv[1]). Used for source-clone detection. */
+    argv1?: string;
+    /** DI seam for source/git-clone detection. */
+    detectGit?: (argv1: string) => string | null;
+    /** DI seam for spinner. Defaults to noop when !process.stdout.isTTY. */
+    spinnerFactory?: SpinnerFactory;
+}
+export type EnsureAgentKitGlobalResult = {
+    kind: 'agent-kit-global-updated';
+    command: readonly string[];
+} | {
+    kind: 'agent-kit-global-skipped-dry-run';
+} | {
+    kind: 'agent-kit-global-skipped-opt-out';
+} | {
+    kind: 'agent-kit-global-skipped-source-clone';
+    repoRoot: string;
+} | {
+    kind: 'agent-kit-global-skipped-no-vp';
+    hint: string;
+} | {
+    kind: 'agent-kit-global-failed';
+    exitCode: number;
+    command: readonly string[];
+};
+/**
+ * Refresh the single global `@webpresso/agent-kit` install via `vp install -g`.
+ */
+export declare function ensureAgentKitGlobal(input: EnsureAgentKitGlobalInput): EnsureAgentKitGlobalResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/cli/commands/init/scaffolders/agent-kit-global/index.js

@@ -0,0 +1,64 @@
+/**
+ * `agent-kit-global` self-update scaffolder.
+ *
+ * Keeps the ONE globally-distributed `@webpresso/agent-kit` binary fresh on
+ * every `wp setup`, mirroring how omx / omc / codex / claude self-update their
+ * own global installs. The PATH `wp`, the Claude plugin MCP, and the agent
+ * hooks all resolve to this single global binary, so refreshing it here means
+ * the next invocation everywhere runs the latest published release.
+ *
+ * Uses the exact same command the auto-update installer infers
+ * (`buildVpGlobalInstallCommand` — single source of truth), so there is no
+ * second place that can drift on the install incantation.
+ *
+ * Skipped (no-op, non-fatal) when:
+ *   - `--dry-run` (no writes anywhere),
+ *   - `WP_SKIP_AUTO_INSTALL=1` (the documented opt-out, surfaced in the update
+ *     banner),
+ *   - the running binary resolves into a webpresso source/git clone — a global
+ *     install would clobber the developer's working clone with a published
+ *     tarball (`detectGitInstall`),
+ *   - `vp` is not on PATH (nothing to install with).
+ *
+ * A failed refresh is reported but NEVER fails consumer setup: keeping the
+ * global tool current is ancillary to scaffolding the consumer repo (same
+ * warn-only contract as the codex-cli scaffolder).
+ */
+import { spawnSync } from 'node:child_process';
+import { makeNoopSpinnerFactory } from '#cli/commands/init/scaffolders/spinner';
+import { buildVpGlobalInstallCommand, detectGitInstall, PUBLIC_PACKAGE_NAME, } from '#cli/auto-update/detect-pm.js';
+const NO_VP_HINT = 'vp (vite-plus) is not on PATH; cannot refresh the global ' +
+    `${PUBLIC_PACKAGE_NAME}. Install vite-plus, then re-run \`wp setup\`.`;
+/**
+ * Refresh the single global `@webpresso/agent-kit` install via `vp install -g`.
+ */
+export function ensureAgentKitGlobal(input) {
+    if (input.options.dryRun)
+        return { kind: 'agent-kit-global-skipped-dry-run' };
+    const env = input.env ?? process.env;
+    if (env.WP_SKIP_AUTO_INSTALL === '1') {
+        return { kind: 'agent-kit-global-skipped-opt-out' };
+    }
+    const argv1 = input.argv1 ?? process.argv[1] ?? '';
+    const detectGit = input.detectGit ?? detectGitInstall;
+    const sourceCloneRoot = argv1.length > 0 ? detectGit(argv1) : null;
+    if (sourceCloneRoot !== null) {
+        return { kind: 'agent-kit-global-skipped-source-clone', repoRoot: sourceCloneRoot };
+    }
+    const spawn = input.spawn ?? spawnSync;
+    const spinner = (input.spinnerFactory ?? makeNoopSpinnerFactory())('agent-kit-global');
+    const probe = spawn('vp', ['--version'], { encoding: 'utf8' });
+    if (probe.error || (probe.status !== null && probe.status !== 0)) {
+        return { kind: 'agent-kit-global-skipped-no-vp', hint: NO_VP_HINT };
+    }
+    const command = buildVpGlobalInstallCommand();
+    spinner.start();
+    const install = spawn(command[0], command.slice(1), { stdio: 'inherit' });
+    if (install.status !== 0) {
+        spinner.fail('agent-kit global refresh failed');
+        return { kind: 'agent-kit-global-failed', exitCode: install.status ?? -1, command };
+    }
+    spinner.succeed('agent-kit global up to date');
+    return { kind: 'agent-kit-global-updated', command };
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/cli/commands/package-manager.d.ts

@@ -0,0 +1,15 @@
+import type { CAC } from 'cac';
+import type { SpawnSyncReturns } from 'node:child_process';
+export declare const PACKAGE_MANAGER_VERBS: readonly ["install", "add", "remove", "update", "exec", "run"];
+export type PackageManagerVerb = (typeof PACKAGE_MANAGER_VERBS)[number];
+export interface PackageManagerCommandConfig {
+    readonly command: string;
+    readonly args: readonly string[];
+}
+export interface PackageManagerCommandDeps {
+    readonly run?: (command: string, args: readonly string[]) => SpawnSyncReturns<string>;
+}
+export declare function registerPackageManagerCommand(cli: CAC, verb: PackageManagerVerb): void;
+export declare function buildPackageManagerCommand(verb: PackageManagerVerb, argv?: readonly string[]): PackageManagerCommandConfig;
+export declare function runPackageManagerCommand(verb: PackageManagerVerb, deps?: PackageManagerCommandDeps): number;
+//# sourceMappingURL=package-manager.d.ts.map

package/dist/esm/cli/commands/package-manager.js

@@ -0,0 +1,42 @@
+import { spawnSync } from 'node:child_process';
+import { getManagedRunner } from '#tool-runtime';
+export const PACKAGE_MANAGER_VERBS = ['install', 'add', 'remove', 'update', 'exec', 'run'];
+const HELP_BY_VERB = {
+    install: 'Install dependencies through the managed vp facade.',
+    add: 'Add dependencies through the managed vp facade.',
+    remove: 'Remove dependencies through the managed vp facade.',
+    update: 'Update dependencies through the managed vp facade.',
+    exec: 'Run a binary through the managed vp facade.',
+    run: 'Run a package script through the managed vp facade.',
+};
+export function registerPackageManagerCommand(cli, verb) {
+    cli
+        .command(`${verb} [...args]`, HELP_BY_VERB[verb])
+        .allowUnknownOptions()
+        .action(() => runPackageManagerCommand(verb));
+}
+export function buildPackageManagerCommand(verb, argv = process.argv) {
+    const resolution = getManagedRunner('vp', { outputPolicy: 'structured' });
+    return {
+        command: resolution.command,
+        args: [...resolution.args, verb, ...extractVerbArgs(verb, argv)],
+    };
+}
+export function runPackageManagerCommand(verb, deps = {}) {
+    const command = buildPackageManagerCommand(verb);
+    const result = (deps.run ?? defaultRun)(command.command, command.args);
+    return typeof result.status === 'number' ? result.status : 1;
+}
+function extractVerbArgs(verb, argv) {
+    const verbIndex = argv.findIndex((arg, index) => index >= 2 && arg === verb);
+    return verbIndex === -1 ? [] : argv.slice(verbIndex + 1);
+}
+function defaultRun(command, args) {
+    return spawnSync(command, [...args], {
+        encoding: 'utf8',
+        env: process.env,
+        stdio: 'inherit',
+        windowsHide: true,
+    });
+}
+//# sourceMappingURL=package-manager.js.map

package/dist/esm/cli/commands/test.d.ts

@@ -2,6 +2,7 @@ import type { CommandConfig, TestCommandOptions } from '#test';
 import type { CAC } from 'cac';
 export declare const TEST_COMMAND_HELP: string;
 export interface AkTestCommandInput extends TestCommandOptions {
+    cwd?: string;
     package?: readonly string[] | string;
     file?: readonly string[] | string;
     targets?: readonly string[] | string;

package/dist/esm/cli/commands/test.js

@@ -14,7 +14,7 @@ export function createAkTestCommandConfig(input) {
         file: toArray(input.file),
         positional: toArray(input.targets),
     });
-    return buildTestCommand(target, input);
+    return buildTestCommand(target, { ...input, cwd: input.cwd });
 }
 export function registerTestCommand(cli) {
     cli
@@ -35,6 +35,7 @@ export function registerTestCommand(cli) {
         .action((targets, flags) => {
         const rawArgv = process.argv.slice(2);
         const command = createAkTestCommandConfig({
+            cwd: process.cwd(),
             package: flags.package,
             file: flags.file,
             targets: targets ?? [],

package/dist/esm/cli/commands/typecheck.js

@@ -1,6 +1,6 @@
+import { getManagedRunner } from '#tool-runtime';
+import { getPackageScript, isRecursiveWpScript } from '#cli/package-scripts.js';
 import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
 export const TYPECHECK_COMMAND_HELP = [
     'Typecheck the current workspace through the portable wp surface.',
     '',
@@ -16,15 +16,18 @@ export function registerTypecheckCommand(cli) {
 }
 export function buildTypecheckCommand(options = {}) {
     const cwd = options.cwd ?? process.cwd();
-    if (hasCheckTypesScript(cwd)) {
+    const checkTypesScript = getPackageScript(cwd, 'check-types');
+    if (checkTypesScript && !isRecursiveWpScript(checkTypesScript, 'typecheck')) {
+        const resolution = getManagedRunner('vp', { outputPolicy: 'structured' });
         return {
-            command: 'vp',
-            args: ['run', 'check-types'],
+            command: resolution.command,
+            args: [...resolution.args, 'run', 'check-types'],
         };
     }
+    const resolution = getManagedRunner('tsc', { outputPolicy: 'structured' });
     return {
-        command: 'tsc',
-        args: ['--noEmit', ...(options.pretty ? [] : ['--pretty', 'false'])],
+        command: resolution.command,
+        args: [...resolution.args, '--noEmit', ...(options.pretty ? [] : ['--pretty', 'false'])],
     };
 }
 export function runTypecheckCommand(options = {}, deps = {}) {
@@ -42,16 +45,4 @@ function defaultRun(command, args) {
         windowsHide: true,
     });
 }
-function hasCheckTypesScript(cwd) {
-    const packageJsonPath = join(cwd, 'package.json');
-    if (!existsSync(packageJsonPath))
-        return false;
-    try {
-        const parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
-        return typeof parsed.scripts?.['check-types'] === 'string';
-    }
-    catch {
-        return false;
-    }
-}
 //# sourceMappingURL=typecheck.js.map

package/dist/esm/cli/package-scripts.d.ts

@@ -0,0 +1,12 @@
+export interface PackageJsonLike {
+    readonly scripts?: Record<string, unknown>;
+    readonly dependencies?: Record<string, unknown>;
+    readonly devDependencies?: Record<string, unknown>;
+    readonly optionalDependencies?: Record<string, unknown>;
+}
+export declare function readPackageJson(cwd: string): PackageJsonLike | undefined;
+export declare function getPackageScript(cwd: string, name: string): string | undefined;
+export declare function packageHasDependency(cwd: string, dependencyName: string): boolean;
+export declare function packageUsesVitest(cwd: string): boolean;
+export declare function isRecursiveWpScript(script: string, verb: string): boolean;
+//# sourceMappingURL=package-scripts.d.ts.map

package/dist/esm/cli/package-scripts.js

@@ -0,0 +1,59 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export function readPackageJson(cwd) {
+    const packageJsonPath = join(cwd, 'package.json');
+    if (!existsSync(packageJsonPath))
+        return;
+    try {
+        const parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return;
+        return parsed;
+    }
+    catch {
+        return;
+    }
+}
+export function getPackageScript(cwd, name) {
+    const parsed = readPackageJson(cwd);
+    const candidate = parsed?.scripts?.[name];
+    return typeof candidate === 'string' ? candidate : undefined;
+}
+export function packageHasDependency(cwd, dependencyName) {
+    const parsed = readPackageJson(cwd);
+    if (!parsed)
+        return false;
+    return ['dependencies', 'devDependencies', 'optionalDependencies'].some((section) => {
+        const dependencies = parsed[section];
+        return Boolean(dependencies &&
+            typeof dependencies === 'object' &&
+            !Array.isArray(dependencies) &&
+            dependencyName in dependencies);
+    });
+}
+export function packageUsesVitest(cwd) {
+    return packageHasDependency(cwd, 'vitest');
+}
+export function isRecursiveWpScript(script, verb) {
+    const normalized = stripLeadingEnvAssignments(script.trim());
+    if (!normalized)
+        return false;
+    const patterns = [
+        new RegExp(`^(?:vp\\s+exec\\s+)?wp\\s+${escapeRegExp(verb)}(?:\\s|$)`),
+        new RegExp(`^(?:bunx?|npx)\\s+(?:--yes\\s+)?(?:@webpresso/agent-kit\\s+)?wp\\s+${escapeRegExp(verb)}(?:\\s|$)`),
+    ];
+    return patterns.some((pattern) => pattern.test(normalized));
+}
+function stripLeadingEnvAssignments(input) {
+    let remaining = input.replace(/^env\s+/u, '');
+    while (true) {
+        const next = remaining.replace(/^(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|\S+)\s+)/u, '');
+        if (next === remaining)
+            return remaining.trim();
+        remaining = next;
+    }
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}
+//# sourceMappingURL=package-scripts.js.map

package/dist/esm/cli/utils.js

@@ -5,8 +5,9 @@
  * unknown-command formatting) and webpresso/packages/cli/cli-utils
  * (getProjectRoot) so this package has no @webpresso/* runtime dependencies.
  */
-import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
+import { existsSync } from 'node:fs';
+import { readOwnedPackageVersion } from '#runtime/package-version.js';
 // ---------------------------------------------------------------------------
 // Project root resolution
 // ---------------------------------------------------------------------------
@@ -131,26 +132,6 @@ export function formatUnknownCommandError(input, commands, binName = 'wp') {
  * having to know how many `..` segments to append.
  */
 export function readPackageVersion(metaUrl) {
-    const url = new URL(metaUrl);
-    let dir = path.dirname(url.pathname);
-    for (let i = 0; i < 6; i++) {
-        const candidate = path.join(dir, 'package.json');
-        if (existsSync(candidate)) {
-            try {
-                const parsed = JSON.parse(readFileSync(candidate, 'utf-8'));
-                if (parsed.name === 'webpresso') {
-                    return parsed.version ?? '0.0.0';
-                }
-            }
-            catch {
-                // keep walking
-            }
-        }
-        const parent = path.dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    return '0.0.0';
+    return readOwnedPackageVersion(metaUrl);
 }
 //# sourceMappingURL=utils.js.map

package/dist/esm/cli/wp-extensions.d.ts

@@ -0,0 +1,14 @@
+import type { CAC } from 'cac';
+import { type LoadWpExtensionsOptions, type WpExtensionAliasV1 } from '#wp-extension';
+export interface RegisterWpExtensionsOptions extends LoadWpExtensionsOptions {
+    readonly cli: CAC;
+    readonly baseCommands: readonly string[];
+}
+export interface RegisteredWpExtensions {
+    readonly aliasMap: ReadonlyMap<string, WpExtensionAliasV1>;
+    readonly warnings: readonly string[];
+    readonly commandNames: readonly string[];
+}
+export declare function registerWpExtensions(options: RegisterWpExtensionsOptions): Promise<RegisteredWpExtensions>;
+export declare function resolveWpCommandAlias(command: string | undefined, aliasMap: ReadonlyMap<string, WpExtensionAliasV1>): string | undefined;
+//# sourceMappingURL=wp-extensions.d.ts.map

package/dist/esm/cli/wp-extensions.js

@@ -0,0 +1,34 @@
+import { loadWpExtensions, resolveAcceptedExtensionAliases, } from '#wp-extension';
+export async function registerWpExtensions(options) {
+    const loaded = await loadWpExtensions(options);
+    const warnings = loaded.flatMap((entry) => entry.warnings);
+    const commandNames = [];
+    const blockedCommandNames = new Set(options.baseCommands);
+    const registeredCommandNames = new Set();
+    for (const extension of loaded) {
+        if (!extension.extension || !extension.compatible || !extension.detected)
+            continue;
+        for (const command of extension.extension.commands) {
+            if (blockedCommandNames.has(command.name)) {
+                warnings.push(`${extension.packageName}: skipped command "${command.name}" because it collides with an existing command`);
+                continue;
+            }
+            command.register(options.cli);
+            commandNames.push(command.name);
+            blockedCommandNames.add(command.name);
+            registeredCommandNames.add(command.name);
+        }
+    }
+    const aliasResolution = resolveAcceptedExtensionAliases(loaded, options.baseCommands, registeredCommandNames);
+    return {
+        aliasMap: aliasResolution.aliases,
+        warnings: [...warnings, ...aliasResolution.warnings],
+        commandNames,
+    };
+}
+export function resolveWpCommandAlias(command, aliasMap) {
+    if (!command)
+        return command;
+    return aliasMap.get(command)?.commandName ?? command;
+}
+//# sourceMappingURL=wp-extensions.js.map

package/dist/esm/config/docs-lint/schemas/common.d.ts

@@ -46,8 +46,8 @@ export declare const implementationStatus: z.ZodEnum<{
     completed: "completed";
     draft: "draft";
     planned: "planned";
-    "in-progress": "in-progress";
     parked: "parked";
+    "in-progress": "in-progress";
     archived: "archived";
     current: "current";
     complete: "complete";