@webpresso/agent-kit 3.3.2 → 3.3.4

package/dist/esm/mcp/tools/_shared/redact.d.ts

@@ -1 +1,23 @@
+/**
+ * Redaction for the shared read-only MCP path (`wp_pr_status`, `wp_pr_wait`,
+ * `wp_run_wait` error tails, `_readonly-ops`, worker tails, hook logs — 11
+ * consumers). Output reaches agent context, session memory, and committed
+ * review artifacts in a public repository, so a credential surviving here is
+ * irreversible and externally exploitable.
+ *
+ * Three properties are load-bearing; changing any of them breaks a consumer:
+ *
+ * 1. {@link mask} is **partial disclosure by design** — first and last two
+ *    characters survive above six, and the mask is deterministic.
+ *    `run-wait.ts` redacts both sides of its SHA comparison and relies on
+ *    identical input producing identical output.
+ * 2. The generic 40+-character rule masks full commit SHAs as a side effect,
+ *    compensated downstream by that same mask-aware equality. Do not "fix" it
+ *    here without updating those consumers.
+ * 3. **Every quantifier is bounded.** Callers pass unbounded log text —
+ *    `run-wait.ts` redacts the whole tail *before* clipping it to 2000 bytes —
+ *    so an unbounded `[A-Za-z0-9_]*` around a keyword alternation backtracks
+ *    quadratically and a hostile CI log can stall the MCP path for tens of
+ *    seconds. Keep the `{0,64}` bounds.
+ */
 export declare function redactText(value: string | undefined): string | undefined;

package/dist/esm/mcp/tools/_shared/redact.js

@@ -1,22 +1,128 @@
-const KEY_PATTERNS = [
-    /\b(?:GH_PACKAGES_TOKEN|GITHUB_TOKEN|GITHUB_PAT|NEON_API_KEY(?:_PLATFORM)?|CHEF_CI_TOKEN)\b\s*=\s*([^\s]+)/giu,
+/**
+ * Redaction for the shared read-only MCP path (`wp_pr_status`, `wp_pr_wait`,
+ * `wp_run_wait` error tails, `_readonly-ops`, worker tails, hook logs — 11
+ * consumers). Output reaches agent context, session memory, and committed
+ * review artifacts in a public repository, so a credential surviving here is
+ * irreversible and externally exploitable.
+ *
+ * Three properties are load-bearing; changing any of them breaks a consumer:
+ *
+ * 1. {@link mask} is **partial disclosure by design** — first and last two
+ *    characters survive above six, and the mask is deterministic.
+ *    `run-wait.ts` redacts both sides of its SHA comparison and relies on
+ *    identical input producing identical output.
+ * 2. The generic 40+-character rule masks full commit SHAs as a side effect,
+ *    compensated downstream by that same mask-aware equality. Do not "fix" it
+ *    here without updating those consumers.
+ * 3. **Every quantifier is bounded.** Callers pass unbounded log text —
+ *    `run-wait.ts` redacts the whole tail *before* clipping it to 2000 bytes —
+ *    so an unbounded `[A-Za-z0-9_]*` around a keyword alternation backtracks
+ *    quadratically and a hostile CI log can stall the MCP path for tens of
+ *    seconds. Keep the `{0,64}` bounds.
+ */
+/** Key-name fragments that advertise a secret. */
+const SECRET_WORD = "PASSWORD|PASSWD|SECRET|TOKEN|API[_-]?KEY|ACCESS[_-]?KEY|PRIVATE[_-]?KEY|CREDENTIALS?";
+/**
+ * Optional opening quote OUTSIDE the capture, then the value up to the first
+ * closing delimiter.
+ *
+ * Both halves matter. Excluding quotes from the class stops a greedy capture
+ * pulling the closing quote into the mask (`sk***6"` instead of `sk***56`).
+ * Consuming an optional *opening* quote is what keeps `KEY="secret"` matching
+ * at all — omitting it makes the `+` match zero characters, the pattern fail,
+ * and the most common real-world shape (quoted shell/JSON/YAML values) sail
+ * through completely unredacted.
+ */
+// `\x60` is the backtick: a literal one cannot appear inside a String.raw
+// template, and `\`` is an invalid escape under the `u` flag.
+const QUOTED_VALUE = String.raw `["'\x60]?([^\s"'\x60,;)\]}\[]+)`;
+/** As above, with a length floor — see the `:` rule below. */
+const QUOTED_VALUE_LONG = String.raw `["'\x60]?([^\s"'\x60,;)\]}\[]{12,})`;
+/**
+ * Optional closing quote on the KEY, before the separator. JSON and quoted-key
+ * YAML put it there — `{"password":"…"}` — and without this the separator match
+ * fails on the key's own closing quote and the whole line sails through.
+ */
+const KEY_CLOSE = String.raw `["']?[ \t]*`;
+/**
+ * Credential value for the keyword rules (`Bearer`, `Basic`, `Cookie`), which
+ * carry no assignment signal at all — and whose keywords are ordinary English
+ * words. Without a floor, `Basic checks passed` becomes
+ * `Basic [REDACTED] passed`, and that reaches users: `pr-upsert.ts` pushes PR
+ * **titles** through this function, so "Add Bearer token support" would render
+ * corrupted.
+ *
+ * So the value must be ≥12 characters AND contain at least one uppercase
+ * letter, digit or base64 punctuation — enough to separate `dXNlcjpwYXNzd29yZA==`
+ * from `authentication`.
+ *
+ * The keyword rules therefore drop the `i` flag and spell each casing out.
+ * Under `i`, `[A-Z]` also matches lowercase, so this lookahead would be
+ * silently satisfied by any long lowercase word and the check would do nothing.
+ */
+const KEYWORD_CRED = String.raw `["'\x60]?((?:(?=[^\s"'\x60,;)\]}\[]*[A-Z0-9+/=_-])[^\s"'\x60,;)\]}\[]{12,}|[^\s"'\x60,;)\]}\[]{24,}))`;
+/**
+ * Patterns whose **first capture group** is the secret. Only that group is
+ * masked, so the header name, config key or URL host stays readable — a
+ * redactor that destroys the line it protects gets routed around.
+ */
+const CAPTURING_PATTERNS = [
+    // Originally-named credential env assignments.
+    new RegExp(String.raw `\b(?:GH_PACKAGES_TOKEN|GITHUB_TOKEN|GITHUB_PAT|NEON_API_KEY(?:_PLATFORM)?|CHEF_CI_TOKEN)\b` +
+        KEY_CLOSE +
+        String.raw `=[ \t]*` +
+        QUOTED_VALUE, "giu"),
+    // Generic secret-named key with `=`. Assignment is an unambiguous signal, so
+    // no length floor: `PASSWORD=x` should mask even when short.
+    new RegExp(String.raw `\b[A-Za-z0-9_]{0,64}(?:${SECRET_WORD})[A-Za-z0-9_]{0,64}` +
+        KEY_CLOSE +
+        String.raw `=[ \t]*` +
+        QUOTED_VALUE, "giu"),
+    // Generic secret-named key with `:`. Deliberately stricter than `=`, because
+    // `:` is overloaded across YAML, tables, markdown and plain prose — without a
+    // floor this masks `tokens: 512`, `secret: true`, `credentials: verified for
+    // 3 users` and `**Token:** an opaque handle`, corrupting ordinary CI output.
+    // A 12-character floor admits real secrets while excluding those.
+    new RegExp(String.raw `\b[A-Za-z0-9_]{0,64}(?:${SECRET_WORD})[A-Za-z0-9_]{0,64}` +
+        KEY_CLOSE +
+        String.raw `:[ \t]*` +
+        QUOTED_VALUE_LONG, "giu"),
+    // `Authorization: Bearer <token>` / bare `Bearer <token>`. Casings spelled
+    // out because `KEYWORD_CRED`'s lookahead is case-sensitive by necessity.
+    new RegExp(String.raw `\b(?:Bearer|bearer|BEARER)\s+` + KEYWORD_CRED, "gu"),
+    // `Authorization: Basic <base64>` — same header family, and the base64 is
+    // usually under the generic 40-character floor.
+    new RegExp(String.raw `\b(?:Basic|basic|BASIC)\s+` + KEYWORD_CRED, "gu"),
+    // Session cookies: the cookie NAME (`session`, `sid`) never matches a
+    // secret-word rule, so the value needs its own case or session tokens ride
+    // through CI and proxy logs intact. Anchoring on `name=` both avoids matching
+    // prose after a bare `Cookie:` and keeps the cookie name readable in output.
+    new RegExp(String.raw `\b(?:Set-|set-|SET-)?(?:Cookie|cookie|COOKIE)\s*:\s*[^\s=;]{1,64}=` + KEYWORD_CRED, "gu"),
+    // Credential-bearing URL userinfo: `https://user:pass@host/…`. Masking the
+    // whole userinfo keeps the host, which is what makes the log useful.
+    /:\/\/([^\s/@]+)@/gu,
 ];
-const TOKEN_PATTERNS = [
+/** Patterns where the entire match is the secret. */
+const WHOLE_MATCH_PATTERNS = [
     /\bghp_[A-Za-z0-9]{20,}\b/gu,
     /\b(?:cf|sk|tok)_[A-Za-z0-9_-]{16,}\b/gu,
+    // JWTs, whose segments routinely fall under the generic 40-character floor.
+    /\beyJ[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}\b/gu,
     /\b[A-Za-z0-9+/_-]{40,}\b/gu,
 ];
 export function redactText(value) {
     if (!value)
         return value;
     let output = value;
-    for (const pattern of KEY_PATTERNS) {
-        output = output.replace(pattern, (whole, token) => {
-            const trimmed = String(token ?? "").trim();
-            return whole.includes("=") ? whole.replace(trimmed, mask(trimmed)) : mask(trimmed);
+    for (const pattern of CAPTURING_PATTERNS) {
+        output = output.replace(pattern, (whole, secret) => {
+            const trimmed = String(secret ?? "").trim();
+            if (trimmed.length === 0)
+                return whole;
+            return whole.replace(trimmed, mask(trimmed));
         });
     }
-    for (const pattern of TOKEN_PATTERNS) {
+    for (const pattern of WHOLE_MATCH_PATTERNS) {
         output = output.replace(pattern, (token) => mask(token));
     }
     return output;

package/dist/esm/mcp/tools/gain.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { resolveManagedRtkExecutable } from "#tool-runtime/managed-rtk.js";
 import { createSummaryOutputSchema, createSummaryResult } from "./_shared/result.js";
 import { readonlyOpsBaseSchema, resolveReadonlyCwd, runReadonlyCommand } from "./_readonly-ops.js";
 const inputSchema = readonlyOpsBaseSchema
@@ -19,8 +20,12 @@ const outputSchema = createSummaryOutputSchema({
     }),
 });
 function commandFor(input) {
-    if (input.source === "rtk")
-        return { command: "rtk", args: ["gain", "--format", "json"] };
+    if (input.source === "rtk") {
+        const rtkBin = resolveManagedRtkExecutable();
+        if (!rtkBin)
+            return null;
+        return { command: rtkBin, args: ["gain", "--format", "json"] };
+    }
     return { command: "./bin/wp", args: input.sessions ? ["gain", "--sessions"] : ["gain"] };
 }
 const tool = {
@@ -39,6 +44,27 @@ const tool = {
         const input = inputSchema.parse(raw ?? {});
         const cwd = resolveReadonlyCwd(input);
         const command = commandFor(input);
+        if (command === null) {
+            return createSummaryResult({
+                passed: false,
+                summary: "managed RTK not available (wp setup --with rtk or WP_RTK_BIN)",
+                exitCode: 1,
+                counts: { commandCount: 0, passedCount: 0, failedCount: 1 },
+                details: {
+                    cwd,
+                    source: input.source,
+                    format: input.format,
+                    sessions: input.sessions,
+                    command: {},
+                    result: { error: "managed_rtk_missing" },
+                },
+                rawOutput: "",
+                truncated: false,
+                timedOut: false,
+                aborted: false,
+                warnings: ["managed RTK binary missing"],
+            });
+        }
         const result = await runReadonlyCommand("gain", command.command, command.args, {
             cwd,
             timeoutMs: input.timeoutMs,

package/dist/esm/mcp/tools/release-progress.d.ts

@@ -0,0 +1,9 @@
+import type { ToolDescriptor } from "#mcp/auto-discover";
+import { type RunReleaseProgressOptions } from "#cli/commands/release-progress.js";
+export type ReleaseProgressToolDeps = Pick<RunReleaseProgressOptions, "fetchJobs" | "resolveLatestRunId">;
+/**
+ * Build the tool descriptor. Tests inject gh seams; production uses defaults.
+ */
+export declare function createReleaseProgressTool(deps?: ReleaseProgressToolDeps): ToolDescriptor;
+declare const tool: ToolDescriptor;
+export default tool;

package/dist/esm/mcp/tools/release-progress.js

@@ -0,0 +1,110 @@
+/**
+ * `wp_release_progress` — read-only Release workflow phase reporter for agents.
+ *
+ * Shares {@link runReleaseProgress} with the CLI so MCP and `wp release-progress`
+ * never diverge. Does not mutate GitHub; only reads via `gh`.
+ */
+import { z } from "zod";
+import { runReleaseProgress, } from "#cli/commands/release-progress.js";
+import { createSummaryOutputSchema, createSummaryResult } from "./_shared/result.js";
+import { readonlyOpsBaseSchema } from "./_readonly-ops.js";
+const inputSchema = readonlyOpsBaseSchema
+    .extend({
+    runId: z.union([z.string().min(1), z.number().int().positive()]).optional(),
+    repo: z.string().min(1).optional(),
+})
+    .strict();
+const releaseProgressDetailsSchema = z
+    .object({
+    runId: z.string(),
+    repo: z.string(),
+    phase: z.enum(["detect", "native-matrix", "publish", "done", "failed"]),
+    detail: z.string(),
+    native: z.object({
+        done: z.number().int().nonnegative(),
+        total: z.number().int().nonnegative(),
+        failed: z.number().int().nonnegative(),
+        inProgress: z.number().int().nonnegative(),
+    }),
+    publishRunning: z.boolean(),
+    publishDone: z.boolean(),
+    publishFailed: z.boolean(),
+    line: z.string(),
+})
+    .strict();
+const outputSchema = createSummaryOutputSchema({
+    details: releaseProgressDetailsSchema,
+});
+/**
+ * Build the tool descriptor. Tests inject gh seams; production uses defaults.
+ */
+export function createReleaseProgressTool(deps = {}) {
+    return {
+        name: "wp_release_progress",
+        description: "Read-only GitHub Actions Release workflow phase reporter (detect | native-matrix | publish | done | failed) with session-memory native matrix counts. Use instead of silent npm view polls after Version Packages merge. Does not mutate GitHub. Prefer this over shelling `wp release-progress` when available.",
+        inputSchema,
+        outputSchema,
+        annotations: {
+            title: "Release progress",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        handler: async (raw) => {
+            const input = inputSchema.parse(raw ?? {});
+            const repo = input.repo ?? "webpresso/agent-kit";
+            try {
+                const result = runReleaseProgress({
+                    runId: input.runId,
+                    repo,
+                    json: false,
+                    fetchJobs: deps.fetchJobs,
+                    resolveLatestRunId: deps.resolveLatestRunId,
+                    // Suppress CLI text I/O; structuredContent is the MCP contract.
+                    stdout: { write: () => undefined },
+                    stderr: { write: () => undefined },
+                });
+                const { progress, runId, line } = result;
+                const failed = progress.phase === "failed";
+                return createSummaryResult({
+                    passed: !failed,
+                    summary: line,
+                    details: {
+                        runId,
+                        repo,
+                        phase: progress.phase,
+                        detail: progress.detail,
+                        native: progress.native,
+                        publishRunning: progress.publishRunning,
+                        publishDone: progress.publishDone,
+                        publishFailed: progress.publishFailed,
+                        line,
+                    },
+                    warnings: failed ? [progress.detail] : [],
+                }, { isError: failed });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return createSummaryResult({
+                    passed: false,
+                    summary: `release-progress failed: ${message}`,
+                    details: {
+                        runId: input.runId === undefined ? "" : String(input.runId),
+                        repo,
+                        phase: "failed",
+                        detail: message,
+                        native: { done: 0, total: 0, failed: 0, inProgress: 0 },
+                        publishRunning: false,
+                        publishDone: false,
+                        publishFailed: false,
+                        line: `release-progress phase=failed native=0/0 ${message}`,
+                    },
+                    warnings: [message],
+                }, { isError: true });
+            }
+        },
+    };
+}
+const tool = createReleaseProgressTool();
+export default tool;

package/dist/esm/mcp/tools/worktree.js

@@ -15,6 +15,7 @@ import { gitBranchExists, listEntries, resolveNewWorktreeTarget, resolveWorktree
 import { deriveRepoNamespace, resolveKnownManagedWorktreeRoots, resolveWorktreeRoot, } from "#worktrees/location.js";
 import { readRepoOriginUrl, repoManagedRoot } from "#worktrees/manager.js";
 import { buildWorktreeInventory, canonicalizeWorktreePath, isManagedWorktreePath, resolveRepoIdentity, } from "#worktrees/identity.js";
+import { isStaleWorktreeRegistration, pruneStaleGitWorktreeMetadata, } from "#worktrees/git-metadata.js";
 import { findRegistryCandidatesByPath, pruneStaleWorktreeRegistryEntries, removeWorktreeRegistryEntries, repoScopedPathPredicate, upsertWorktreeRegistryEntry, } from "#worktrees/registry.js";
 const ACTIONS = ["list", "root", "new", "remove", "prune", "refresh"];
 const MUTATING_ACTIONS = new Set(["new", "remove", "prune", "refresh"]);
@@ -105,6 +106,53 @@ function isRegisteredManagedWorktree(resolvedPath, _context) {
     // a legacy-root worktree registered by an earlier binary authorizes removal.
     return findRegistryCandidatesByPath(canonicalizeWorktreePath(resolvedPath)).length > 0;
 }
+/**
+ * A stale registration may already have lost its registry entry to an earlier
+ * prune, so registration alone cannot gate reconciling it. Fall back to the
+ * managed-root boundary, which still keeps unmanaged worktrees protected.
+ */
+function isRemovableManagedTarget(resolved, context, stale) {
+    if (isRegisteredManagedWorktree(resolved, context))
+        return true;
+    if (!stale)
+        return false;
+    return isManagedWorktreePath(canonicalizeWorktreePath(resolved), resolveKnownManagedWorktreeRoots());
+}
+/** Reconcile git + registry for a worktree whose directory is already gone. */
+function clearStaleRegistration(input, repoRoot, resolved, entries, entry) {
+    const gitPruned = pruneStaleGitWorktreeMetadata(repoRoot, entries);
+    if (gitPruned.error) {
+        return {
+            passed: false,
+            summary: `wp_worktree remove failed: git worktree prune failed: ${gitPruned.error}`,
+            action: input.action,
+            executed: false,
+            warnings: ["git_worktree_prune_failed"],
+            nextAction: "Inspect the repository's git worktree admin records and retry.",
+        };
+    }
+    const warnings = [];
+    try {
+        removeWorktreeRegistryEntries(repoScopedPathPredicate(resolved, { authoritativeRepoKey: resolveRepoIdentity(repoRoot) }));
+    }
+    catch {
+        warnings.push("registry_cleanup_failed");
+    }
+    return {
+        passed: true,
+        summary: `Cleared stale worktree registration ${resolved} (directory already gone)`,
+        action: input.action,
+        executed: true,
+        removed: {
+            path: resolved,
+            ...(entry?.branch ? { branch: entry.branch.replace("refs/heads/", "") } : {}),
+        },
+        warnings,
+        ...(warnings.includes("registry_cleanup_failed")
+            ? { nextAction: "Run wp_worktree prune with execute:true to repair stale registry metadata." }
+            : {}),
+    };
+}
 function refreshManagedEntries(repoRoot) {
     const { originUrl, repoNamespace } = managedContext(repoRoot);
     const knownRoots = resolveKnownManagedWorktreeRoots();
@@ -234,6 +282,7 @@ function handleRemove(input, repoRoot) {
     }
     const entry = entries.find((candidate) => candidate.path === resolved);
     const context = managedContext(repoRoot);
+    const stale = isStaleWorktreeRegistration(entry, resolved, existsSync);
     if (resolved === repoRoot) {
         return {
             passed: false,
@@ -243,7 +292,7 @@ function handleRemove(input, repoRoot) {
             warnings: ["main_checkout_protected"],
         };
     }
-    if (!isRegisteredManagedWorktree(resolved, context)) {
+    if (!isRemovableManagedTarget(resolved, context, stale)) {
         return {
             passed: false,
             summary: `wp_worktree remove refused: ${resolved} is not a registered managed worktree for this repository`,
@@ -263,6 +312,10 @@ function handleRemove(input, repoRoot) {
             nextAction: "Unlock the worktree explicitly with git after confirming it is safe, then retry.",
         };
     }
+    // Checked before the dirty gate: `git status` fails in a missing directory,
+    // which would otherwise be reported as "uncommitted changes".
+    if (stale)
+        return clearStaleRegistration(input, repoRoot, resolved, entries, entry);
     if (isDirty(resolved)) {
         return {
             passed: false,
@@ -368,6 +421,10 @@ const tool = {
                     warnings: [],
                 }, false);
             }
+            // Reconcile git's own admin records FIRST: a hand-deleted worktree
+            // directory leaves a record that still claims its branch, and it would
+            // otherwise read as live below and pin its registry entry in place too.
+            const gitPruned = pruneStaleGitWorktreeMetadata(repoRoot, listEntries(repoRoot));
             // Repository-scoped, three-state prune across every known root: only THIS
             // repo's entries proven stale against a COMPLETE git-live inventory drop;
             // unknown, other-repo, and live-legacy entries are retained. `existsSync`
@@ -377,12 +434,17 @@ const tool = {
                 inventory,
                 scope: { authoritativeRepoKey: resolveRepoIdentity(repoRoot) },
             });
+            const gitSummary = gitPruned.error
+                ? ""
+                : ` and ${gitPruned.prunedPaths.length} stale git worktree registration${gitPruned.prunedPaths.length === 1 ? "" : "s"}`;
             return result({
                 passed: true,
-                summary: `Pruned ${pruned.removed.length} stale managed registry entr${pruned.removed.length === 1 ? "y" : "ies"}`,
+                summary: `Pruned ${pruned.removed.length} stale managed registry entr${pruned.removed.length === 1 ? "y" : "ies"}${gitSummary}`,
                 action: input.action,
                 executed: true,
-                warnings: pruned.warnings,
+                warnings: gitPruned.error
+                    ? [...pruned.warnings, `git_worktree_prune_failed:${gitPruned.error}`]
+                    : pruned.warnings,
             }, false);
         }
         catch (error) {

package/dist/esm/mcp/tools/wp-ui-blocks-list.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDescriptor } from "#mcp/auto-discover";
+declare const tool: ToolDescriptor;
+export default tool;

package/dist/esm/mcp/tools/wp-ui-blocks-list.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { resolveBlockRegistry } from "#compose/registry-resolve.js";
+const inputSchema = z
+    .object({
+    cwd: z.string().optional(),
+    profile: z.enum(["admin-crud", "ops-report"]).optional(),
+})
+    .strict();
+const tool = {
+    name: "wp_ui_blocks_list",
+    description: "List the agent UI block catalog for composition. Resolves project `.webpresso/generated/frontend/blocks/registry.json` when present, otherwise the offline catalog snapshot. Always returns source (project|snapshot), registryVersion, and warnings (e.g. snapshot used inside a webpresso tree without a generated registry).",
+    inputSchema,
+    annotations: {
+        title: "UI blocks list",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    handler: async (raw) => {
+        const input = inputSchema.parse(raw ?? {});
+        const resolved = resolveBlockRegistry({ cwd: input.cwd });
+        // admin-crud: full registry (list/detail/form). ops-report: no admin blocks.
+        const blocks = input.profile === "ops-report" ? [] : resolved.registry.blocks;
+        const summary = `UI blocks: ${blocks.length} (source=${resolved.source}, version=${resolved.registryVersion})`;
+        const payload = {
+            passed: true,
+            summary,
+            source: resolved.source,
+            registryVersion: resolved.registryVersion,
+            path: resolved.path,
+            warnings: [...resolved.warnings],
+            profiles: ["admin-crud", "ops-report"],
+            blocks,
+            webpressoPresentWithoutRegistry: resolved.webpressoPresentWithoutRegistry,
+        };
+        return {
+            content: [{ type: "text", text: summary }],
+            structuredContent: payload,
+        };
+    },
+};
+export default tool;

package/dist/esm/mcp/tools/wp-ui-compose.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDescriptor } from "#mcp/auto-discover";
+declare const tool: ToolDescriptor;
+export default tool;

package/dist/esm/mcp/tools/wp-ui-compose.js

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import { composeValidate } from "#compose/compose.js";
+const inputSchema = z
+    .object({
+    cwd: z.string().optional(),
+    profile: z.enum(["admin-crud", "ops-report"]),
+    kind: z.enum(["list", "detail", "form"]).optional(),
+    spec: z.unknown(),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    if (value.profile === "admin-crud" && value.kind === undefined) {
+        ctx.addIssue({
+            code: "custom",
+            message: "kind is required for admin-crud (list|detail|form)",
+            path: ["kind"],
+        });
+    }
+});
+const tool = {
+    name: "wp_ui_compose",
+    description: "Validate a profile-discriminated UI compose input. admin-crud: validate list/detail/form specs against the block registry (returns input spec unchanged when legal). ops-report: validate flat OpsReportSpec. Does not write files or open a browser.",
+    inputSchema,
+    annotations: {
+        title: "UI compose validate",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    handler: async (raw) => {
+        const parsed = inputSchema.safeParse(raw ?? {});
+        if (!parsed.success) {
+            const summary = `Invalid wp_ui_compose input: ${parsed.error.issues.map((i) => i.message).join("; ")}`;
+            return {
+                content: [{ type: "text", text: summary }],
+                structuredContent: {
+                    passed: false,
+                    summary,
+                    ok: false,
+                    diagnostics: parsed.error.issues.map((i) => ({
+                        path: i.path.length > 0 ? i.path.join(".") : "(root)",
+                        message: i.message,
+                    })),
+                },
+                isError: true,
+            };
+        }
+        const input = parsed.data;
+        if (input.profile === "admin-crud") {
+            if (input.spec === null || typeof input.spec !== "object" || Array.isArray(input.spec)) {
+                const summary = "Invalid wp_ui_compose admin-crud spec: expected a non-null object (not string/array/empty coercion)";
+                return {
+                    content: [{ type: "text", text: summary }],
+                    structuredContent: {
+                        passed: false,
+                        summary,
+                        ok: false,
+                        diagnostics: [{ path: "spec", message: summary }],
+                    },
+                    isError: true,
+                };
+            }
+        }
+        const composeInput = input.profile === "admin-crud"
+            ? {
+                profile: "admin-crud",
+                kind: input.kind,
+                spec: input.spec,
+            }
+            : { profile: "ops-report", spec: input.spec };
+        const result = composeValidate(composeInput, { cwd: input.cwd });
+        const summary = result.ok
+            ? `compose ok (${result.profile})`
+            : `compose failed (${result.profile}): ${result.diagnostics.map((d) => d.message).join("; ")}`;
+        // MCP tool execution errors (incl. domain validation) use isError:true so
+        // models self-correct; diagnostics stay in content text + structuredContent.
+        return {
+            content: [{ type: "text", text: summary }],
+            structuredContent: {
+                passed: result.ok,
+                summary,
+                profile: result.profile,
+                ok: result.ok,
+                spec: result.spec,
+                diagnostics: result.diagnostics,
+                registrySource: result.registrySource,
+                registryVersion: result.registryVersion,
+                warnings: result.warnings,
+                blockTypesValidated: result.blockTypesValidated,
+            },
+            ...(result.ok ? {} : { isError: true }),
+        };
+    },
+};
+export default tool;

package/dist/esm/mcp/tools/wp-ui-preview.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDescriptor } from "#mcp/auto-discover";
+declare const tool: ToolDescriptor;
+export default tool;

package/dist/esm/mcp/tools/wp-ui-preview.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { previewOpsReport } from "#compose/preview.js";
+const inputSchema = z
+    .object({
+    cwd: z.string().optional(),
+    profile: z.literal("ops-report"),
+    spec: z.unknown(),
+})
+    .strict();
+const tool = {
+    name: "wp_ui_preview",
+    description: "Validate an ops-report compose spec, write self-contained HTML under the worktree state surface (or .webpresso/compose fallback), and return { path } only. Does not open a browser. admin-crud is not supported for preview.",
+    inputSchema,
+    annotations: {
+        title: "UI ops-report preview",
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    handler: async (raw) => {
+        const parsed = inputSchema.safeParse(raw ?? {});
+        if (!parsed.success) {
+            const message = `Invalid wp_ui_preview input: ${parsed.error.issues.map((i) => i.message).join("; ")} (ops-report profile only; admin-crud is not supported)`;
+            return {
+                content: [{ type: "text", text: message }],
+                structuredContent: {
+                    passed: false,
+                    summary: message,
+                },
+                isError: true,
+            };
+        }
+        try {
+            const { path } = previewOpsReport({ cwd: parsed.data.cwd, spec: parsed.data.spec });
+            const summary = `ops-report preview written: ${path}`;
+            return {
+                content: [{ type: "text", text: summary }],
+                structuredContent: {
+                    passed: true,
+                    summary,
+                    path,
+                },
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: "text", text: message }],
+                structuredContent: {
+                    passed: false,
+                    summary: message,
+                },
+                isError: true,
+            };
+        }
+    },
+};
+export default tool;