@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/mcp/tools/explain.d.ts

@@ -0,0 +1,2 @@
+import type { McpRegistry } from "../registry";
+export declare const registerExplainTools: (registry: McpRegistry) => void;

package/dist/mcp/tools/explain.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerExplainTools = void 0;
+/**
+ * Explain MCP tool — the projection of `scai hygiene explain`.
+ *
+ * `audit_inspect` runs ONE audit at a time. `explain` is the composed
+ * surface: a single `{ verb }`-discriminated entry that chains several
+ * audits into a focused answer to a specific operator question —
+ *
+ *   - `why-blocked`  — every inbound reference that would block a delete
+ *                      of an item (`audit references` +
+ *                      `audit template-dependencies`), sorted by kind.
+ *   - `orphan-site`  — what residue a deleted site left behind, and
+ *                      which of it is still referenced by live content
+ *                      (`audit site-residue` + `audit references`).
+ *
+ * Read-only: the composed audits never mutate the tenant. The runners
+ * are the exact CLI-shared `runExplain*` tasks invoked with
+ * `silent: true` so nothing reaches stdout — the MCP layer owns the
+ * structured envelope; the task only returns its report.
+ */
+const zod_1 = require("zod");
+const why_blocked_1 = require("../../hygiene/tasks/explain/why-blocked");
+const orphan_site_1 = require("../../hygiene/tasks/explain/orphan-site");
+const errors_1 = require("../../shared/errors");
+const descriptions_1 = require("../descriptions");
+const common_1 = require("../schemas/common");
+const registerExplainTools = (registry) => {
+    registry.registerTool({
+        name: "explain",
+        description: descriptions_1.TOOL_DESCRIPTIONS.explain,
+        auth: "read",
+        annotations: {
+            title: "Compose audits into a focused operator answer",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            verb: zod_1.z
+                .enum(["why-blocked", "orphan-site"])
+                .describe("Which composed question to answer. `why-blocked` lists every inbound reference blocking a delete of `itemId`. `orphan-site` lists the residue a deleted `site` left behind and flags trees still referenced by live content."),
+            itemId: zod_1.z
+                .string()
+                .optional()
+                .describe("verb='why-blocked': the item to explain (any GUID form). Required for that verb."),
+            site: zod_1.z
+                .string()
+                .optional()
+                .describe("verb='orphan-site': the deleted site (or tenant) folder name to explain. Required for that verb."),
+            root: zod_1.z
+                .string()
+                .optional()
+                .describe("verb='why-blocked': content root for the field-value scan. Default `/sitecore/content`."),
+            index: zod_1.z.string().optional().describe("Override the search index name used by the scan."),
+            limit: zod_1.z
+                .number()
+                .int()
+                .positive()
+                .max(50000)
+                .optional()
+                .describe("Cap on inbound references counted per scan."),
+            skipContentScan: zod_1.z
+                .boolean()
+                .optional()
+                .describe("verb='why-blocked': skip the slow field-value content scan. Use when only structural template refs matter."),
+            skipTemplateDeps: zod_1.z
+                .boolean()
+                .optional()
+                .describe("verb='why-blocked': skip the search-index template-dependency check. Use for leaf content items never referenced as a template."),
+            ...common_1.environmentBindingShape,
+        },
+        handler: async (input, context) => {
+            const envName = input.environmentName ?? context.envName;
+            const base = {
+                config: context.configPath,
+                environmentName: envName,
+                quiet: true,
+                json: true,
+                silent: true,
+            };
+            if (input.verb === "why-blocked") {
+                if (!input.itemId) {
+                    throw (0, errors_1.createScaiError)("verb='why-blocked' requires `itemId`.", "INPUT_INVALID");
+                }
+                const report = await (0, why_blocked_1.runExplainWhyBlocked)({
+                    ...base,
+                    itemId: input.itemId,
+                    ...(input.root !== undefined && { root: input.root }),
+                    ...(input.index !== undefined && { index: input.index }),
+                    ...(input.limit !== undefined && { limit: input.limit }),
+                    ...(input.skipContentScan !== undefined && { skipContentScan: input.skipContentScan }),
+                    ...(input.skipTemplateDeps !== undefined && { skipTemplateDeps: input.skipTemplateDeps }),
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: report.blockers.length === 0
+                                ? `${report.itemId} has no inbound references — safe to delete.`
+                                : `${report.itemId} is blocked by ${report.blockers.length} inbound reference(s).`,
+                        },
+                    ],
+                    structuredContent: { verb: input.verb, ...report },
+                };
+            }
+            if (!input.site) {
+                throw (0, errors_1.createScaiError)("verb='orphan-site' requires `site`.", "INPUT_INVALID");
+            }
+            const report = await (0, orphan_site_1.runExplainOrphanSite)({
+                ...base,
+                site: input.site,
+                ...(input.index !== undefined && { index: input.index }),
+                ...(input.limit !== undefined && { limit: input.limit }),
+            });
+            const referenced = report.orphans.filter((o) => o.inboundRefs > 0).length;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: report.orphans.length === 0
+                            ? `No orphan residue found for site '${report.site}'.`
+                            : `Site '${report.site}': ${report.orphans.length} orphan tree(s), ${referenced} still referenced.`,
+                    },
+                ],
+                structuredContent: { verb: input.verb, ...report },
+            };
+        },
+    });
+};
+exports.registerExplainTools = registerExplainTools;

package/dist/mcp/tools/inspector.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Inspector tools — used by humans (and orchestrating agents) to peek
+ * at the registered tool surface without round-tripping through SDK
+ * introspection.
+ *
+ * `tools_list` returns names + descriptions + auth class.
+ * `tools_schema` returns the Zod-derived JSON schema for one tool or
+ * all tools. Implementation note: we use `zod`'s `z.toJSONSchema`
+ * (Zod 4+) to keep the surface dependency-free.
+ */
+import { McpRegistry } from "../registry";
+export declare const registerInspectorTools: (registry: McpRegistry) => void;

package/dist/mcp/tools/inspector.js

@@ -0,0 +1,101 @@
+"use strict";
+/**
+ * Inspector tools — used by humans (and orchestrating agents) to peek
+ * at the registered tool surface without round-tripping through SDK
+ * introspection.
+ *
+ * `tools_list` returns names + descriptions + auth class.
+ * `tools_schema` returns the Zod-derived JSON schema for one tool or
+ * all tools. Implementation note: we use `zod`'s `z.toJSONSchema`
+ * (Zod 4+) to keep the surface dependency-free.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerInspectorTools = void 0;
+const zod_1 = require("zod");
+const descriptions_1 = require("../descriptions");
+const toolJsonSchema = (tool) => zod_1.z.toJSONSchema(zod_1.z.object({ ...tool.inputSchema }));
+const registerInspectorTools = (registry) => {
+    registry.registerTool({
+        name: "tools_list",
+        description: descriptions_1.TOOL_DESCRIPTIONS.tools_list,
+        auth: "read",
+        annotations: {
+            title: "List MCP tools",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+        inputSchema: {},
+        handler: async () => {
+            const tools = registry.listTools().map((tool) => ({
+                name: tool.name,
+                description: tool.description,
+                auth: tool.auth,
+                annotations: tool.annotations,
+            }));
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `${tools.length} tool(s) registered on this MCP server.`,
+                    },
+                ],
+                structuredContent: { tools },
+            };
+        },
+    });
+    registry.registerTool({
+        name: "tools_schema",
+        description: descriptions_1.TOOL_DESCRIPTIONS.tools_schema,
+        auth: "read",
+        annotations: {
+            title: "Get tool input schema(s)",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+        inputSchema: {
+            name: zod_1.z
+                .string()
+                .optional()
+                .describe("Optional tool name. When omitted, returns schemas for every registered tool."),
+        },
+        handler: async (input) => {
+            if (input.name) {
+                const tool = registry.getTool(input.name);
+                if (!tool) {
+                    return {
+                        isError: true,
+                        content: [
+                            {
+                                type: "text",
+                                text: `What happened: Tool '${input.name}' is not registered.\n` +
+                                    `Why: The provided name does not match any tool on this MCP server.\n` +
+                                    `Next: Call tools_list to discover available tool names.`,
+                            },
+                        ],
+                        structuredContent: {
+                            code: "INPUT_INVALID",
+                            what: "Unknown tool",
+                            why: `Tool '${input.name}' is not registered.`,
+                            next: "Call tools_list to discover available tool names.",
+                        },
+                    };
+                }
+                return {
+                    content: [{ type: "text", text: `Schema for tool '${tool.name}'.` }],
+                    structuredContent: { name: tool.name, schema: toolJsonSchema(tool) },
+                };
+            }
+            const schemas = registry.listTools().map((tool) => ({
+                name: tool.name,
+                schema: toolJsonSchema(tool),
+            }));
+            return {
+                content: [{ type: "text", text: `Schemas for ${schemas.length} tool(s).` }],
+                structuredContent: { schemas },
+            };
+        },
+    });
+};
+exports.registerInspectorTools = registerInspectorTools;

package/dist/mcp/tools/onboard.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `environment_onboard` — stand up a new environment profile.
+ *
+ * Write-gated. Fills the gap where the MCP, bound to one already-healthy
+ * environment at startup, had no surface to add another. Writes the
+ * profile, runs the access preflight, and reports the steps that remain
+ * — policy enrollment, and the human-only credential step. The MCP
+ * wrapper over `runEnvironmentOnboard` (`@/serialization/tasks/env/onboard`).
+ */
+import type { McpRegistry } from "../registry";
+export declare const registerOnboardTools: (registry: McpRegistry) => void;

package/dist/mcp/tools/onboard.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * `environment_onboard` — stand up a new environment profile.
+ *
+ * Write-gated. Fills the gap where the MCP, bound to one already-healthy
+ * environment at startup, had no surface to add another. Writes the
+ * profile, runs the access preflight, and reports the steps that remain
+ * — policy enrollment, and the human-only credential step. The MCP
+ * wrapper over `runEnvironmentOnboard` (`@/serialization/tasks/env/onboard`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerOnboardTools = void 0;
+const zod_1 = require("zod");
+const onboard_1 = require("../../serialization/tasks/env/onboard");
+const descriptions_1 = require("../descriptions");
+const common_1 = require("../schemas/common");
+const registerOnboardTools = (registry) => {
+    registry.registerTool({
+        name: "environment_onboard",
+        description: descriptions_1.TOOL_DESCRIPTIONS.environment_onboard,
+        auth: "write",
+        annotations: {
+            title: "Onboard a new environment",
+            readOnlyHint: false,
+            destructiveHint: true,
+            openWorldHint: false,
+        },
+        inputSchema: {
+            environmentName: zod_1.z
+                .string()
+                .min(1)
+                .describe("Local profile name for the new environment in sitecoreai.cli.json."),
+            organizationId: zod_1.z.string().min(1).describe("Sitecore organization id (org_…)."),
+            projectId: zod_1.z.string().min(1).describe("Deploy project id the environment belongs to."),
+            environmentId: zod_1.z.string().min(1).describe("Deploy environment id."),
+            host: zod_1.z.string().min(1).describe("CM host, e.g. xmc-org-env.sitecorecloud.io."),
+            environmentType: zod_1.z
+                .enum(["cm", "eh"])
+                .default("cm")
+                .describe("Environment type — cm (content management) or eh (editing host)."),
+            ...common_1.allowWriteShape,
+        },
+        handler: async (input, context) => {
+            const result = await (0, onboard_1.runEnvironmentOnboard)({
+                config: context.configPath,
+                environmentName: input.environmentName,
+                organizationId: input.organizationId,
+                projectId: input.projectId,
+                environmentId: input.environmentId,
+                host: input.host,
+                environmentType: input.environmentType,
+            });
+            const next = result.access.nextStep;
+            const text = `Environment '${result.environmentName}' added to sitecoreai.cli.json. ` +
+                (result.access.ready
+                    ? "All access gates pass — it is ready to use."
+                    : `Not ready yet — next: ${next ? `${next.fix} [${next.actor}]` : "see access gates"}.`);
+            return {
+                content: [{ type: "text", text }],
+                structuredContent: result,
+            };
+        },
+    });
+};
+exports.registerOnboardTools = registerOnboardTools;

package/dist/mcp/tools/publish.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Publishing domain MCP tools — read-side + cancel only.
+ *
+ * Deliberately MINIMAL surface for the v1 ship:
+ *
+ *   - `publish_inspect` (read): `status` / `list-running` / `history`.
+ *     No mutating fall-through; no scope-token mint (the operator
+ *     mints scope tokens through the CLI dry-run flow, then passes
+ *     them out-of-band — the agent never holds one).
+ *
+ *   - `publish_lifecycle` (write): `cancel` only. Cancel is the
+ *     safety-improving op (stops a running publish); recoverable by
+ *     resubmission.
+ *
+ * NOT exposed via MCP — by design:
+ *
+ *   - `submit_item` / `submit_all`: publishing pushes content to
+ *     Experience Edge and is immediately visible to end users. The
+ *     safety model (`feedback_destructive_ops_need_consent`) requires
+ *     structured consent that only a human-driven CLI invocation
+ *     mints. An MCP-callable submit would let an agent both prepare
+ *     and execute, defeating the consent gate. Submission stays
+ *     CLI-only until a proper MCP consent flow is designed.
+ *
+ *   - `unpublish`: same rationale. Even the reversible
+ *     `never-publish` strategy modifies content state and triggers an
+ *     Edge update; gated to CLI for now.
+ */
+import type { McpRegistry } from "../registry";
+export declare const registerPublishingTools: (registry: McpRegistry) => void;

package/dist/mcp/tools/publish.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * Publishing domain MCP tools — read-side + cancel only.
+ *
+ * Deliberately MINIMAL surface for the v1 ship:
+ *
+ *   - `publish_inspect` (read): `status` / `list-running` / `history`.
+ *     No mutating fall-through; no scope-token mint (the operator
+ *     mints scope tokens through the CLI dry-run flow, then passes
+ *     them out-of-band — the agent never holds one).
+ *
+ *   - `publish_lifecycle` (write): `cancel` only. Cancel is the
+ *     safety-improving op (stops a running publish); recoverable by
+ *     resubmission.
+ *
+ * NOT exposed via MCP — by design:
+ *
+ *   - `submit_item` / `submit_all`: publishing pushes content to
+ *     Experience Edge and is immediately visible to end users. The
+ *     safety model (`feedback_destructive_ops_need_consent`) requires
+ *     structured consent that only a human-driven CLI invocation
+ *     mints. An MCP-callable submit would let an agent both prepare
+ *     and execute, defeating the consent gate. Submission stays
+ *     CLI-only until a proper MCP consent flow is designed.
+ *
+ *   - `unpublish`: same rationale. Even the reversible
+ *     `never-publish` strategy modifies content state and triggers an
+ *     Edge update; gated to CLI for now.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerPublishingTools = void 0;
+const zod_1 = require("zod");
+const environment_1 = require("../../policy/environment");
+const allow_write_1 = require("../../policy/allow-write");
+const errors_1 = require("../../shared/errors");
+const auth_1 = require("../../publishing/api/auth");
+const client_1 = require("../../publishing/api/client");
+const publish_audit_1 = require("../../shared/publish-audit");
+const auth_2 = require("../auth");
+const descriptions_1 = require("../descriptions");
+const common_1 = require("../schemas/common");
+const acquireClient = async (envName) => {
+    const { environment, timeoutMs } = (0, environment_1.resolveEnvironment)({ environmentName: envName });
+    const accessToken = await (0, auth_1.acquirePublishingToken)({ envName, environment });
+    return { accessToken, timeoutMs };
+};
+const registerPublishingTools = (registry) => {
+    registry.registerTool({
+        name: "publish_inspect",
+        description: descriptions_1.TOOL_DESCRIPTIONS.publish_inspect,
+        auth: "read",
+        annotations: {
+            title: "Inspect publishing jobs and history",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            verb: zod_1.z
+                .enum(["status", "list-running", "history"])
+                .describe("Which read operation: `status` (one job, jobId required), `list-running` (all queued/running in env), `history` (local audit log)."),
+            jobId: zod_1.z.string().optional().describe("Publish job id. Required for verb='status'."),
+            historyEnv: zod_1.z
+                .string()
+                .optional()
+                .describe("verb='history': filter to entries from this env name."),
+            historyCommand: zod_1.z
+                .string()
+                .optional()
+                .describe("verb='history': substring match against the audit `command` field."),
+            historyOutcome: zod_1.z
+                .enum(["ok", "error", "cancelled"])
+                .optional()
+                .describe("verb='history': filter by outcome."),
+            ...common_1.paginationShape,
+            ...common_1.environmentBindingShape,
+        },
+        handler: async (input, context) => {
+            const envName = input.environmentName ?? context.envName;
+            switch (input.verb) {
+                case "status": {
+                    if (!input.jobId) {
+                        throw (0, errors_1.createScaiError)("verb='status' requires a `jobId`.", "INPUT_INVALID");
+                    }
+                    const client = await acquireClient(envName);
+                    const job = await (0, client_1.getPublishJob)(client, input.jobId);
+                    return {
+                        content: [{ type: "text", text: `Job ${job.id}: ${job.state}` }],
+                        structuredContent: { verb: "status", job },
+                    };
+                }
+                case "list-running": {
+                    const client = await acquireClient(envName);
+                    const jobs = await (0, client_1.listPublishJobs)(client, { statuses: ["Queued", "Running"] });
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `${jobs.length} job(s) queued or running in env '${envName}'.`,
+                            },
+                        ],
+                        structuredContent: { verb: "list-running", jobs, count: jobs.length },
+                    };
+                }
+                case "history": {
+                    const all = (0, publish_audit_1.readRecentPublishAudit)(500);
+                    const filtered = all.filter((entry) => {
+                        if (input.historyEnv && entry.scope?.envName !== input.historyEnv) {
+                            return false;
+                        }
+                        if (input.historyCommand && !entry.command.includes(input.historyCommand)) {
+                            return false;
+                        }
+                        if (input.historyOutcome && entry.outcome !== input.historyOutcome) {
+                            return false;
+                        }
+                        return true;
+                    });
+                    const limit = input.limit;
+                    const trimmed = filtered.slice(-limit);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Returned ${trimmed.length} audit entr${trimmed.length === 1 ? "y" : "ies"}.`,
+                            },
+                        ],
+                        structuredContent: {
+                            verb: "history",
+                            entries: trimmed,
+                            count: trimmed.length,
+                            scanned: all.length,
+                        },
+                    };
+                }
+            }
+        },
+    });
+    registry.registerTool({
+        name: "publish_lifecycle",
+        description: descriptions_1.TOOL_DESCRIPTIONS.publish_lifecycle,
+        auth: "write",
+        annotations: {
+            title: "Cancel a running publish job",
+            readOnlyHint: false,
+            destructiveHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            verb: zod_1.z
+                .enum(["cancel"])
+                .describe("Which mutation. Only `cancel` is exposed via MCP; submission is CLI-only."),
+            jobId: zod_1.z.string().describe("Publish job id to cancel."),
+            ...common_1.environmentBindingShape,
+            ...common_1.allowWriteShape,
+        },
+        handler: async (input, context) => {
+            const binding = await (0, auth_2.resolveToolBinding)(context, input.environmentName);
+            (0, allow_write_1.ensureMcpElevationAllowed)(binding.resolved.root, binding.envName);
+            const client = await acquireClient(binding.envName);
+            await (0, client_1.cancelPublishJob)(client, input.jobId);
+            // Re-read to capture the post-cancel state (cancellation is
+            // asynchronous server-side; the immediate state is typically
+            // `cancelling` not `cancelled`).
+            const job = await (0, client_1.getPublishJob)(client, input.jobId);
+            return {
+                content: [{ type: "text", text: `Cancel requested for ${job.id} (now ${job.state}).` }],
+                structuredContent: { verb: "cancel", job },
+            };
+        },
+    });
+};
+exports.registerPublishingTools = registerPublishingTools;

package/dist/mcp/tools/recipe-sync.d.ts

@@ -0,0 +1,2 @@
+import type { McpRegistry } from "../registry";
+export declare const registerRecipeSyncTools: (registry: McpRegistry) => void;

package/dist/mcp/tools/recipe-sync.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerRecipeSyncTools = void 0;
+/**
+ * Cross-domain recipe-sync MCP tool — the projection of `scai sync`.
+ *
+ * The per-instance `*_recipe_inspect` / `*_recipe_push` tools each
+ * operate on ONE brand kit or ONE brief type. `recipe_sync` is the
+ * aggregate: a single `{ verb }`-discriminated entry that fans out over
+ * every enumerable recipe kind at once —
+ *
+ *   - `pull`   — enumerate every brand kit + brief type and capture
+ *                each as a recipe file under the workspace directory.
+ *   - `status` — diff every workspace recipe file against the env.
+ *   - `push`   — converge every workspace recipe file onto the env
+ *                (dry-run unless `whatIf: false`).
+ *
+ * Routing + the kinds list are shared with the CLI: `aggregatePull` /
+ * `aggregateStatus` / `aggregatePush` live in `@/sync`, and the covered
+ * kinds come from `@/sync/aggregate-kinds` — the same list `scai sync`
+ * uses, so the two surfaces can never drift on which kinds participate.
+ *
+ * `auth: "write"` because `pull` writes recipe files to the workspace
+ * and `push` mutates the tenant — the whole tool sits behind the
+ * `allowWrite` gate, matching `audit_baseline` (read-ish `status` verb
+ * included). The structured result is verbatim from the aggregate
+ * engine; this layer only adds the text summary + envelope.
+ */
+const zod_1 = require("zod");
+const sync_1 = require("../../sync");
+const aggregate_kinds_1 = require("../../sync/aggregate-kinds");
+const descriptions_1 = require("../descriptions");
+const common_1 = require("../schemas/common");
+const syncContextFrom = (context, environmentName, signal) => ({
+    environmentName: environmentName ?? context.envName,
+    configPath: context.configPath,
+    signal,
+});
+const registerRecipeSyncTools = (registry) => {
+    registry.registerTool({
+        name: "recipe_sync",
+        description: descriptions_1.TOOL_DESCRIPTIONS.recipe_sync,
+        auth: "write",
+        annotations: {
+            title: "Pull, diff, and push every enumerable recipe kind at once",
+            readOnlyHint: false,
+            destructiveHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            verb: zod_1.z
+                .enum(["pull", "status", "push"])
+                .describe("Which aggregate operation. `pull` enumerates every brand kit + brief type and writes each as a recipe file under `dir`. `status` diffs every recipe file in `dir` against the environment (no writes). `push` converges every recipe file onto the environment — a dry-run unless `whatIf: false`."),
+            dir: zod_1.z
+                .string()
+                .optional()
+                .describe(`Workspace directory for recipe files. Layout is <dir>/<kind>/<slug>.yaml. Defaults to '${sync_1.DEFAULT_SYNC_DIR}'.`),
+            prune: zod_1.z
+                .boolean()
+                .default(false)
+                .describe("verb='push': include delete changes. Off by default — push is additive (a recipe omitting an instance never deletes it)."),
+            ...common_1.whatIfShape,
+            ...common_1.environmentBindingShape,
+            ...common_1.allowWriteShape,
+        },
+        handler: async (input, context, extra) => {
+            const ctx = syncContextFrom(context, input.environmentName, extra.signal);
+            const dir = input.dir;
+            if (input.verb === "pull") {
+                const result = await (0, sync_1.aggregatePull)(aggregate_kinds_1.ENUMERABLE_RECIPE_KINDS, ctx, { dir });
+                const skipped = result.kinds.filter((k) => k.skipped).length;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Pulled ${result.total} recipe(s) into ${result.dir}` +
+                                (skipped > 0 ? ` (${skipped} kind(s) skipped — no credential).` : "."),
+                        },
+                    ],
+                    structuredContent: { verb: input.verb, ...result },
+                };
+            }
+            if (input.verb === "status") {
+                const result = await (0, sync_1.aggregateStatus)(aggregate_kinds_1.ENUMERABLE_RECIPE_KINDS, ctx, { dir });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: result.drifted === 0
+                                ? `Everything in sync (${result.dir}).`
+                                : `${result.drifted} recipe(s) drifted from the environment.`,
+                        },
+                    ],
+                    structuredContent: { verb: input.verb, ...result },
+                };
+            }
+            const mode = input.whatIf ? "what-if" : "apply";
+            const result = await (0, sync_1.aggregatePush)(aggregate_kinds_1.ENUMERABLE_RECIPE_KINDS, ctx, {
+                dir,
+                mode,
+                prune: input.prune,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: mode === "apply"
+                            ? `Applied ${result.applied} change(s) across the workspace.`
+                            : "Dry run — no writes. Re-invoke with whatIf: false to converge.",
+                    },
+                ],
+                structuredContent: { verb: input.verb, ...result },
+            };
+        },
+    });
+};
+exports.registerRecipeSyncTools = registerRecipeSyncTools;

package/dist/mcp/tools/recipe.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Recipe domain — compile, plan, diff, push.
+ *
+ * `recipe_compile` is pure-logic and explicitly does NOT touch disk
+ * (unlike the CLI counterpart, which writes the IR alongside the input).
+ * The other three (plan, diff, push) talk to the bound tenant via
+ * `runRecipePlan` / `runRecipeDiff` / `runRecipePush`; their CLI-shaped
+ * task runners stay the contract surface so the MCP layer benefits from
+ * cache reuse, retry behaviour, and execution-event collation without
+ * re-implementing them.
+ *
+ * Inline-TS recipe sources are intentionally not supported in v1 —
+ * agents should reference a recipe by file path. (A TS-source escape
+ * hatch would require an in-process compile to JS and is a code-injection
+ * risk that's out-of-scope for this milestone.)
+ */
+import type { McpRegistry } from "../registry";
+export declare const registerRecipeTools: (registry: McpRegistry) => void;