@webpresso/agent-kit 3.3.2 → 3.3.4

package/dist/esm/cli/commands/init/mcp-spec.js

@@ -4,18 +4,26 @@
  * One source of truth for how every supported host launches the webpresso MCP
  * server. Each host channel (Claude plugin manifest, Codex plugin manifest,
  * Codex `config.toml`, OpenCode `opencode.json`, Grok `.grok/config.toml`)
- * projects this spec into its own config dialect. The two committed plugin
- * manifests reference the launcher via `${CLAUDE_PLUGIN_ROOT}`/`${PLUGIN_ROOT}`;
- * the setup-time writers resolve an absolute `bin/wp` path via
- * {@link findWebpressoMcpEntry}. Compare channels *semantically* (command
+ * projects this spec into its own config dialect. The Claude plugin manifest
+ * references the launcher via `${CLAUDE_PLUGIN_ROOT}`, which Claude Code
+ * expands. Codex does **not** expand `${PLUGIN_ROOT}` in a bundled `.mcp.json`
+ * — that variable reaches hook commands only — and it spawns bundled MCP
+ * servers with the *project* cwd and no plugin env, so the Codex manifest can
+ * anchor on neither the plugin root nor a relative path and uses the bare
+ * `wp` name resolved from PATH at spawn time. The remaining setup-time writers
+ * (Grok, OpenCode) resolve an absolute `bin/wp` path via
+ * {@link resolveWebpressoMcpEntry}. Compare channels *semantically* (command
  * basename, args, env) — never byte-for-byte.
  */
 import { accessSync, constants, existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { isVersionedAgentKitPayloadPath } from "#cli/auto-update/self-invocation.js";
 import { pathCandidates } from "#runtime/command-exists.js";
+import { isManagedWorktreePath, isPathContained } from "#worktrees/identity.js";
+import { resolveKnownManagedWorktreeRoots } from "#worktrees/location.js";
 export const WEBPRESSO_MCP_SERVER_NAME = "webpresso";
 /**
  * The single canonical launch spec for the webpresso MCP server. `name` is the
@@ -62,23 +70,57 @@ const WP_LAUNCHER_REQUIRED_RELATIVES = [
     join("bin", "runtime-lanes.js"),
     join("bin", "runtime-manifest.json"),
 ];
+function isUsableWebpressoMcpRoot(root) {
+    return WP_LAUNCHER_REQUIRED_RELATIVES.every((relativePath) => existsSync(join(root, relativePath)));
+}
+/**
+ * True when `entryPath` is the stable vite-plus multi-package `wp` shim that
+ * dispatches to `@webpresso/agent-kit` via `~/.vite-plus/bins/wp.json`.
+ *
+ * Unlike {@link isWebpressoWpEntry}, this does **not** require realpath to land
+ * inside a package `bin/wp` tree — vite-plus's `wp` is a symlink to the `vp`
+ * binary, so package-root ownership is proven via the bins metadata instead.
+ */
+export function isVitePlusManagedWebpressoWp(entryPath) {
+    try {
+        if (isVersionedAgentKitPayloadPath(entryPath))
+            return false;
+        const binDir = dirname(entryPath);
+        if (basename(binDir) !== "bin")
+            return false;
+        if (basename(dirname(binDir)) !== ".vite-plus")
+            return false;
+        const base = basename(entryPath).toLowerCase();
+        if (base !== "wp" && base !== "wp.exe")
+            return false;
+        const metaPath = join(dirname(binDir), "bins", "wp.json");
+        const meta = JSON.parse(readFileSync(metaPath, "utf8"));
+        return meta.package === "@webpresso/agent-kit";
+    }
+    catch {
+        return false;
+    }
+}
+function isDurableMcpEntryPath(entryPath) {
+    return !isVersionedAgentKitPayloadPath(entryPath);
+}
 /**
  * Resolve the absolute path to webpresso's global `bin/wp` launcher on this
  * machine. Probes the locations consumers use to install webpresso, in order
  * of stability:
  *
- *   1. the stable global `wp` shim available on PATH
- *   2. the currently executing `@webpresso/agent-kit` package
+ *   1. the stable global `wp` shim available on PATH (including the
+ *      vite-plus multi-package shim at `~/.vite-plus/bin/wp`)
+ *   2. the currently executing `@webpresso/agent-kit` package **only when it
+ *      is not a vite-plus `agent-kit#<installId>` payload path**
  *   3. Claude plugin install — `~/.claude/plugins/cache/.../agent-kit/`
  *   4. bun global — `~/.bun/install/global/node_modules/@webpresso/agent-kit/`
- * Returns `null` when none of the candidates contain a usable `bin/wp`.
+ *
+ * Host MCP configs (Grok/OpenCode) must never be pinned to a versioned
+ * installId tree: the next `wp update` / `vp update -g` deletes that path and
+ * leaves every host with a dead launcher. `entryPath` is `null` when none of
+ * the candidates yield a durable `wp`.
  */
-export function findWebpressoMcpEntry(probe = {}) {
-    return resolveWebpressoMcpEntry(probe).entryPath;
-}
-function isUsableWebpressoMcpRoot(root) {
-    return WP_LAUNCHER_REQUIRED_RELATIVES.every((relativePath) => existsSync(join(root, relativePath)));
-}
 export function resolveWebpressoMcpEntry(probe = {}) {
     const checked = [];
     if (probe.candidates === undefined) {
@@ -88,10 +130,17 @@ export function resolveWebpressoMcpEntry(probe = {}) {
         if (stableEntry) {
             checked.push(stableEntry);
             const packageWp = packageWpFromAdjacentNpmCmdShim(stableEntry);
-            if (packageWp !== null)
+            if (packageWp !== null && isDurableMcpEntryPath(packageWp)) {
                 return { entryPath: packageWp, checked };
+            }
             const verifierAllows = probe.stableEntryIsWebpresso?.(stableEntry) ?? true;
-            if (verifierAllows && isWebpressoWpEntry(stableEntry)) {
+            // Prefer the vite-plus multi-package shim before package-root ownership:
+            // it survives installId swaps and is what PATH `wp` resolves to in the
+            // default consumer install.
+            if (verifierAllows && isVitePlusManagedWebpressoWp(stableEntry)) {
+                return { entryPath: stableEntry, checked };
+            }
+            if (verifierAllows && isWebpressoWpEntry(stableEntry) && isDurableMcpEntryPath(stableEntry)) {
                 return { entryPath: stableEntry, checked };
             }
         }
@@ -103,8 +152,12 @@ export function resolveWebpressoMcpEntry(probe = {}) {
                 continue;
             checked.push(root);
             const wpBin = join(root, WP_BIN_RELATIVE);
-            if (isTrustedWebpressoPackageRoot(root))
+            // Never materialize host MCP configs against a vite-plus installId tree.
+            if (!isDurableMcpEntryPath(wpBin))
+                continue;
+            if (isTrustedWebpressoPackageRoot(root, probe.sourceRoot)) {
                 return { entryPath: wpBin, checked };
+            }
         }
     }
     return { entryPath: null, checked };
@@ -152,27 +205,78 @@ function isPathInsideOrEqual(parent, candidate) {
     const rel = relative(resolve(parentRoot), resolve(candidateRoot));
     return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
 }
-function isTrustedWebpressoPackageRoot(packageRoot) {
+function isTrustedWebpressoPackageRoot(packageRoot, resolveSourceRoot = currentAgentKitPackageRoot) {
     try {
         if (!isUsableWebpressoPackageRoot(packageRoot))
             return false;
         const realPackageRoot = realpathSync(packageRoot);
-        const sourceRoot = currentAgentKitPackageRoot();
-        if (sourceRoot !== null && realPackageRoot === realpathSync(sourceRoot))
+        const sourceRoot = resolveSourceRoot();
+        // A managed blueprint worktree is deleted by `wp worktree merge-cleanup`
+        // once its PR lands, so self-trusting it here would persist a path into
+        // host MCP configs that later resolves to nothing. Only the durable
+        // primary checkout may earn self-trust.
+        const home = process.env.HOME || homedir();
+        const isManagedWorktree = isManagedWorktreePath(realPackageRoot, resolveKnownManagedWorktreeRoots(home));
+        if (sourceRoot !== null && !isManagedWorktree && realPackageRoot === realpathSync(sourceRoot)) {
             return true;
+        }
         return trustedHomeInstallPackageRoots().some((anchor) => existsSync(anchor) && isPathInsideOrEqual(anchor, realPackageRoot));
     }
     catch {
         return false;
     }
 }
-function trustedHomeInstallPackageRoots() {
-    const home = process.env.HOME || homedir();
+function trustedHomeInstallPackageRoots(home = process.env.HOME || homedir()) {
     return [
         join(home, ".claude", "plugins", "cache", "webpresso", "agent-kit"),
         join(home, ".bun", "install", "global", "node_modules", "@webpresso", "agent-kit"),
     ];
 }
+/**
+ * Every root under which agent-kit itself installs (or checks out) a `bin/wp`.
+ * A `wp` launcher recorded inside one of these was written by agent-kit; a
+ * launcher anywhere else is an operator's deliberate choice.
+ */
+export function agentKitOwnedCommandRoots(probe = {}) {
+    const home = probe.home ?? process.env.HOME ?? homedir();
+    const sourceRoot = (probe.sourceRoot ?? currentAgentKitPackageRoot)();
+    return [
+        ...trustedHomeInstallPackageRoots(home),
+        join(home, ".vite-plus"),
+        ...resolveKnownManagedWorktreeRoots(home),
+        ...(sourceRoot === null ? [] : [sourceRoot]),
+    ];
+}
+const WP_LAUNCHER_BASENAMES = new Set(["wp", "wp.exe"]);
+/**
+ * Ownership — not shape — decides whether setup may retire a persisted MCP
+ * entry. An entry is agent-kit's own when it launches `wp mcp` from an
+ * ABSOLUTE path AND either that path is gone (one we would have deleted) or
+ * it lives inside one
+ * of {@link agentKitOwnedCommandRoots}. A *live* `wp mcp` launcher outside
+ * those roots is an operator pointing Codex at a custom build: preserve it.
+ */
+export function isAgentKitOwnedWpCommand(command, args, probe = {}) {
+    if (!WP_LAUNCHER_BASENAMES.has(basename(command).toLowerCase()))
+        return false;
+    if (args.length !== WEBPRESSO_MCP_SPEC.args.length)
+        return false;
+    if (args.some((value, index) => value !== WEBPRESSO_MCP_SPEC.args[index]))
+        return false;
+    // Every agent-kit writer of this block persisted an ABSOLUTE launcher path
+    // (see resolveWebpressoMcpEntry). A bare PATH name — the spelling the Codex
+    // plugin manifest itself ships — or a cwd-relative path is therefore
+    // operator-authored, and its meaning depends on a PATH/cwd this predicate
+    // cannot reconstruct. Preserve it and let the doctor report it.
+    if (!isAbsolute(command))
+        return false;
+    const exists = probe.exists ?? existsSync;
+    // Only an absolute path can have been written by us and then rotted away
+    // (deleted managed worktree, replaced versioned install tree).
+    if (!exists(command))
+        return true;
+    return agentKitOwnedCommandRoots(probe).some((root) => isPathContained(root, command));
+}
 function packageWpFromAdjacentNpmCmdShim(entryPath) {
     if (!entryPath.toLowerCase().endsWith(".cmd"))
         return null;

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

@@ -9,10 +9,21 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync, readdirSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { convergeUnitFromTarget } from "./convergence.js";
-import { resolveUntrackedCollision } from "./untracked-collision.js";
-function guardUntrackedOverwrite(targetPath, incoming, opts) {
+import { isGitIgnored, resolveUntrackedCollision } from "./untracked-collision.js";
+/**
+ * Guard an overwrite against clobbering unknown untracked content. Returns a
+ * warning to surface to the caller when the write proceeded past divergent
+ * content it could safely recover from (git-ignored lane only); throws when
+ * the write must be blocked.
+ *
+ * `patchDerived` must be true only when `incoming` was computed FROM the
+ * target's existing content (e.g. `patchJsonFile`'s key-preserving patch) —
+ * that is what makes it safe to write through divergent unmarked content
+ * without a backup.
+ */
+function guardUntrackedOverwrite(targetPath, incoming, opts, patchDerived) {
     if (!opts.repoRoot)
-        return;
+        return undefined;
     const repoRoot = resolve(opts.repoRoot);
     const target = resolve(targetPath);
     const repoRelative = relative(repoRoot, target);
@@ -20,19 +31,25 @@ function guardUntrackedOverwrite(targetPath, incoming, opts) {
         repoRelative === ".." ||
         repoRelative.startsWith(`..${sep}`) ||
         isAbsolute(repoRelative)) {
-        return;
+        return undefined;
     }
+    const gitPath = repoRelative.split(sep).join("/");
+    const scope = isGitIgnored(repoRoot, gitPath) ? "repo-ignored" : "repo-committed";
     const result = resolveUntrackedCollision({
         unit: convergeUnitFromTarget(repoRoot, target, {
             action: "modify",
-            scope: "repo-committed",
+            scope,
             reason: "setup merge target",
         }),
         desiredContent: incoming,
         force: opts.overwrite,
+        patchDerived,
     });
     if (!result.ok)
         throw new Error(result.error);
+    if (result.warning)
+        console.error(`wp setup: ${result.warning}`);
+    return result.warning;
 }
 export function writeFileMerged(targetPath, incoming, opts = {}) {
     const exists = existsSync(targetPath);
@@ -51,9 +68,9 @@ export function writeFileMerged(targetPath, incoming, opts = {}) {
     if (shouldOverwrite) {
         if (opts.dryRun)
             return { targetPath, action: "skipped-dry" };
-        guardUntrackedOverwrite(targetPath, incoming, opts);
+        const warning = guardUntrackedOverwrite(targetPath, incoming, opts, false);
         writeFileSync(targetPath, incoming);
-        return { targetPath, action: "overwritten" };
+        return { targetPath, action: "overwritten", ...(warning ? { note: warning } : {}) };
     }
     if (opts.dryRun)
         return { targetPath, action: "skipped-dry" };
@@ -119,11 +136,14 @@ export function patchJsonFile(targetPath, patcher, opts = {}) {
     if (opts.dryRun) {
         return { targetPath, action: "skipped-dry" };
     }
-    if (exists)
-        guardUntrackedOverwrite(targetPath, incoming, opts);
+    const warning = exists ? guardUntrackedOverwrite(targetPath, incoming, opts, true) : undefined;
     mkdirSync(dirname(targetPath), { recursive: true });
     writeFileSync(targetPath, incoming);
-    return { targetPath, action: exists ? "overwritten" : "created" };
+    return {
+        targetPath,
+        action: exists ? "overwritten" : "created",
+        ...(warning ? { note: warning } : {}),
+    };
 }
 export function summarizeResults(results) {
     const summary = {

package/dist/esm/cli/commands/init/scaffold-agents-md.js

@@ -30,13 +30,11 @@ const TECH_STACK_RULES = [
     { dep: /^typescript$/, label: "TypeScript" },
 ];
 // Kept under the 8 KB (8192-byte) hard ceiling. The rendered template embeds
-// the full `native_tool_names` registry list, so this soft target tracks the
-// tool count: adding an MCP tool grows the list by ~15-17 bytes. Bumped
-// 8_100 -> 8_180 for the four-tool batch (wp_ci_preflight, wp_session_id,
-// wp_session_info, wp_review_run), which renders ~8_160 — still 30+ bytes under
-// 8_192. The 8_192 ceiling is the real guardrail; the next addition that would
-// breach it should trigger a conscious restructure (or exclude the
-// auto-generated tool list from the prose budget), not another reflexive bump.
+// the full `native_tool_names` registry list (~15-17 bytes per tool). Soft
+// target 8_180 leaves headroom under 8_192. The ui-compose batch
+// (wp_ui_blocks_list, wp_ui_compose, wp_ui_preview) required trimming catalog
+// AGENTS.md.tpl prose rather than raising the ceiling. Next breach of 8_192
+// should restructure (or stop embedding the full tool list), not bump again.
 export const AGENTS_MD_MAX_BYTES = 8_180;
 export function renderRepositoryMap(consumer) {
     const packages = consumer.workspacePackages;

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

@@ -6,21 +6,18 @@
  * the patch tiny and deterministic: per-server upserts, no TOML parser
  * dependency, no edits to unrelated user config.
  *
- * Managed blocks come from two sources:
- *   1. `[mcp_servers.webpresso]` — points at webpresso's own MCP server.
- *      Path-stability requires discovery: webpresso lives in different
- *      locations depending on how the user installed it (Claude plugin
- *      install, bun global, pnpm/npm global). Discovery happens at scaffold
- *      time; the resolved absolute path is written into the codex config.
- *      When the unified-cli sibling cutover lands (`webpresso mcp serve`
- *      from a path-stable bin), this block collapses to a fixed `command`.
- *   2. Consumer-owned `.mcp.json` package declarations — compiled to setup-
- *      provisioned, exact-version binaries with environment-variable names
- *      forwarded through Codex's stdio `env_vars` allow-list.
+ * Webpresso's own MCP server is NOT one of them. Codex receives `webpresso`
+ * over exactly one delivery channel — the bundled Codex plugin's `.mcp.json`.
+ * Setup therefore *retires* the `[mcp_servers.webpresso]` block earlier
+ * versions wrote here (see {@link pruneLegacyCodexWebpressoMcp}) instead of
+ * refreshing it. What remains managed here is consumer-owned `.mcp.json`
+ * package declarations — compiled to setup-provisioned, exact-version binaries
+ * with environment-variable names forwarded through Codex's stdio `env_vars`
+ * allow-list.
  */
 import { spawnSync } from "node:child_process";
-import { findWebpressoMcpEntry, WEBPRESSO_MCP_SERVER_NAME, type WebpressoInstallProbe } from "#cli/commands/init/mcp-spec.js";
-export { findWebpressoMcpEntry, WEBPRESSO_MCP_SERVER_NAME };
+import { WEBPRESSO_MCP_SERVER_NAME, type AgentKitOwnedCommandProbe, type WebpressoInstallProbe } from "#cli/commands/init/mcp-spec.js";
+export { WEBPRESSO_MCP_SERVER_NAME };
 export type { WebpressoInstallProbe };
 import type { MergeOptions } from "#cli/commands/init/merge";
 import { type PinnedCodexMcpDefinition } from "#hooks/host-config-contract.js";
@@ -143,35 +140,63 @@ export type EnsureClaudePlaywrightMcpResult = {
     path: string;
 };
 export declare function ensureClaudePlaywrightMcp(input: EnsureClaudePlaywrightMcpInput): EnsureClaudePlaywrightMcpResult;
-export declare function agentKitMcpBlock(entryPath: string): string;
-export declare function upsertWebpressoMcpServer(raw: string, entryPath: string): string;
-export interface EnsureCodexWebpressoMcpInput {
+export type PruneOwnedMcpServerOutcome = {
+    readonly kind: "removed";
+    readonly raw: string;
+    readonly command: string;
+} | {
+    readonly kind: "absent";
+    readonly raw: string;
+} | {
+    readonly kind: "preserved";
+    readonly raw: string;
+    readonly command: string | null;
+} | {
+    readonly kind: "ambiguous";
+    readonly raw: string;
+};
+/**
+ * Remove `[mcp_servers.<serverId>]` (plus its contiguous sub-tables) when
+ * `isOwned` claims the block's launch tuple. Fails closed — leaving `raw`
+ * byte-identical — for every TOML spelling this line scanner cannot rewrite
+ * safely (dotted keys, inline parent table, array tables, non-contiguous
+ * sub-tables).
+ */
+export declare function pruneOwnedMcpServerBlock(raw: string, serverId: string, isOwned: (command: string, args: readonly string[]) => boolean): PruneOwnedMcpServerOutcome;
+export interface PruneLegacyCodexWebpressoMcpInput {
     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;
+    /** Test seam — override agent-kit install-root ownership resolution. */
+    ownership?: AgentKitOwnedCommandProbe;
 }
-export type EnsureCodexWebpressoMcpResult = {
-    kind: "codex-webpresso-mcp-written";
+export type PruneLegacyCodexWebpressoMcpResult = {
+    kind: "codex-legacy-webpresso-mcp-removed";
     path: string;
-    entryPath: string;
+    command: string;
 } | {
-    kind: "codex-webpresso-mcp-unchanged";
+    kind: "codex-legacy-webpresso-mcp-absent";
     path: string;
-    entryPath: string;
 } | {
-    kind: "codex-webpresso-mcp-ambiguous";
+    kind: "codex-legacy-webpresso-mcp-preserved";
     path: string;
-    entryPath: string;
+    command: string | null;
 } | {
-    kind: "codex-webpresso-mcp-skipped-dry-run";
+    kind: "codex-legacy-webpresso-mcp-ambiguous";
     path: string;
 } | {
-    kind: "codex-webpresso-mcp-not-installed";
+    kind: "codex-legacy-webpresso-mcp-skipped-dry-run";
     path: string;
-    checked: readonly string[];
 };
-export declare function ensureCodexWebpressoMcp(input: EnsureCodexWebpressoMcpInput): EnsureCodexWebpressoMcpResult;
+/**
+ * Retire the legacy user-global `[mcp_servers.webpresso]` block. Runs from
+ * setup AND from the `wp codex` launch preflight — the launch path is the only
+ * one that reaches machines that never re-run setup.
+ */
+export declare function pruneLegacyCodexWebpressoMcp(input: PruneLegacyCodexWebpressoMcpInput): PruneLegacyCodexWebpressoMcpResult;
+/**
+ * Installed Codex plugin MCP manifests — the surviving delivery channel.
+ * Cheap directory probe only: no `codex plugin` subprocess belongs on the
+ * launch hot path.
+ */
+export declare function findInstalledCodexPluginMcpManifests(homeDir?: string): readonly string[];