@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/mcp/errors.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * Maps `ScaiError` (and unknown thrown values) onto the MCP
+ * `CallToolResult` error envelope shape consumed by every tool handler.
+ *
+ * Envelope:
+ *   - `isError: true`
+ *   - `content[0]`: text composed as "What happened. Why. Next."
+ *   - `structuredContent`: typed `{ code, exitCode, what, why, hint, docsUri? }`
+ *
+ * Both the text body and the structured content flow through
+ * `redactStructured` so secrets that leaked into error messages never
+ * cross the wire.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolResultFromError = void 0;
+const errors_1 = require("../shared/errors");
+const redact_1 = require("./redact");
+const DOCS_URI_BY_CODE = {
+    AUTH_REQUIRED: "scai://help/overview",
+    CONFIG_NOT_FOUND: "scai://help/overview",
+    CONFIG_INVALID: "scai://help/overview",
+    ENV_NOT_FOUND: "scai://env/current/manifest",
+};
+const NEXT_HINT_BY_CODE = {
+    AUTH_REQUIRED: "Run `scai setup login` for the bound environment, then restart the MCP server.",
+    CONFIG_NOT_FOUND: "Confirm a sitecoreai.cli.json exists in the working tree the MCP server was launched from.",
+    CONFIG_INVALID: "Fix the offending field in sitecoreai.cli.json (see `why`) and restart the MCP server.",
+    INPUT_INVALID: "Re-call the tool with the missing or corrected field. The `why` field describes the offending input.",
+    NETWORK: "Retry shortly; if the failure persists, check Sitecore Cloud status.",
+    ENV_NOT_FOUND: "Confirm the environment name is configured in sitecoreai.cli.json.",
+    DEPLOY_FAILED: "Inspect deploy logs via `deploy_run_inspect` and address the failure before retrying.",
+    SITES_API_FAILED: "Confirm the bound environment has Sites API access and the access token is fresh.",
+    BRIEF_API_FAILED: "Confirm the bound environment has Content Operations Brief API access and the access token is fresh.",
+    CAMPAIGN_API_FAILED: "Confirm the bound environment has Orchestrate (Campaign) API access and the access token is fresh.",
+    AGENTS_API_FAILED: "Confirm the Agentic Studio session is valid (`scai agents login`) and your account holds the Builder role and license.",
+    CANCELLED: "The tool was cancelled by the client. Any partial application is documented in `why`; re-run the tool with the same arguments to resume.",
+    AUTH_BRAND_REQUIRED: "Authenticate with the Sitecore Brand service for the bound environment, then re-run the tool.",
+    AUTH_DENIED: "The bound environment has denyMcpElevation set; MCP write tools can't mutate this tenant. Run the destructive op via the CLI with --allow-write, or clear denyMcpElevation in sitecoreai.cli.json if MCP-driven writes are acceptable for this env.",
+    POLICY_DENIED: "The target environment is not on the scai workspace-policy allowlist, or its tenant identity drifted from what was pinned at enrollment. The operator must enroll or re-pin it (`scai policy allow <env>` / `scai policy trust <env>`) — an agent cannot self-authorize an environment.",
+    BRAND_API_FAILED: "Confirm the bound environment has Brand API access and the access token is fresh; check Sitecore Cloud status if the failure persists.",
+    UNKNOWN: "Re-run with `SITECOREAI_TRACE=1` set in the launcher to capture a verbose trace.",
+};
+const summarizeError = (error) => {
+    switch (error.code) {
+        case "AUTH_REQUIRED":
+            return "Authentication required.";
+        case "AUTH_DENIED":
+            return "MCP write tools are not permitted for this environment.";
+        case "POLICY_DENIED":
+            return "The target environment is not allowed by the workspace policy.";
+        case "CONFIG_NOT_FOUND":
+            return "scai configuration was not found.";
+        case "CONFIG_INVALID":
+            return "scai configuration is invalid.";
+        case "INPUT_INVALID":
+            return "Tool input is invalid.";
+        case "NETWORK":
+            return "A network call to Sitecore Cloud failed.";
+        case "ENV_NOT_FOUND":
+            return "The requested environment is not configured.";
+        case "DEPLOY_FAILED":
+            return "The XM Cloud Deploy operation failed.";
+        case "SITES_API_FAILED":
+            return "The Sites API call failed.";
+        case "BRIEF_API_FAILED":
+            return "The Brief API call failed.";
+        case "CANCELLED":
+            return "The tool was cancelled mid-flight by the client.";
+        case "UNKNOWN":
+        default:
+            return "The tool failed with an unexpected error.";
+    }
+};
+const toolResultFromError = (error) => {
+    const scaiError = (0, errors_1.toScaiError)(error);
+    const what = summarizeError(scaiError);
+    const why = (0, redact_1.redactString)(scaiError.message);
+    const hint = scaiError.hint ? (0, redact_1.redactString)(scaiError.hint) : undefined;
+    const next = NEXT_HINT_BY_CODE[scaiError.code] ?? NEXT_HINT_BY_CODE.UNKNOWN;
+    const docsUri = DOCS_URI_BY_CODE[scaiError.code];
+    const remediation = scaiError.remediation
+        ? {
+            actor: scaiError.remediation.actor,
+            fix: (0, redact_1.redactString)(scaiError.remediation.fix),
+            detail: scaiError.remediation.detail
+                ? (0, redact_1.redactString)(scaiError.remediation.detail)
+                : undefined,
+        }
+        : undefined;
+    // A structured remediation is more specific than the per-code `next`
+    // hint — lead the "Next" line with it when present.
+    const nextLine = remediation
+        ? `${remediation.fix} [${remediation.actor}]${remediation.detail ? ` — ${remediation.detail}` : ""}`
+        : next;
+    const text = [
+        `What happened: ${what}`,
+        `Why: ${why}${hint ? ` (${hint})` : ""}`,
+        `Next: ${nextLine}`,
+    ].join("\n");
+    const envelope = {
+        code: scaiError.code,
+        exitCode: scaiError.exitCode,
+        what,
+        why,
+        hint,
+        next,
+        remediation,
+        docsUri,
+    };
+    return {
+        isError: true,
+        content: [{ type: "text", text }],
+        structuredContent: (0, redact_1.redactStructured)(envelope),
+    };
+};
+exports.toolResultFromError = toolResultFromError;

package/dist/mcp/http.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `scai mcp serve --transport http` — Streamable HTTP transport.
+ *
+ * Why a second transport file? `server.ts` owns the stdio path, where
+ * one long-lived `McpServer` is bound to the process for its whole
+ * lifetime. HTTP is request-scoped: the MCP Streamable HTTP spec wants
+ * a fresh server + transport per POST so concurrent clients can't
+ * collide on JSON-RPC request ids.
+ *
+ * We run **stateless** (no `Mcp-Session-Id`). scai's dispatch rwlock
+ * already serializes writes process-wide, so there is no per-session
+ * state worth keeping alive between requests, and progress
+ * notifications still ride the per-request response stream.
+ *
+ * Security: binds to loopback by default and validates the `Host`
+ * header against the bound address (DNS-rebinding defense — a
+ * malicious web page cannot point its own hostname at this loopback
+ * port). CORS is permissive on `Origin` so a browser-hosted MCP client
+ * can connect; the real boundary is the loopback bind + Host check +
+ * the per-call `allowWrite` gate every write tool already enforces.
+ */
+import { type McpServerOptions } from "./server";
+export interface HttpTransportOptions extends McpServerOptions {
+    /** Bind address. Callers default this to loopback. */
+    host: string;
+    /** Listener port. `0` lets the OS assign one (used by tests). */
+    port: number;
+}
+export interface HttpTransportHandle {
+    /** Full MCP endpoint URL, e.g. `http://127.0.0.1:3399/mcp`. */
+    url: string;
+    /** Actually-bound port — resolves `port: 0` to the OS-assigned port. */
+    port: number;
+    /** Stop the listener and release the port. */
+    close: () => Promise<void>;
+}
+/**
+ * Start the Streamable HTTP listener. Resolves once the socket is bound
+ * (or rejects on a bind error, e.g. `EADDRINUSE`). The returned handle
+ * keeps the process alive via the open server; `close()` releases it.
+ */
+export declare const startHttpTransport: (options: HttpTransportOptions) => Promise<HttpTransportHandle>;

package/dist/mcp/http.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * `scai mcp serve --transport http` — Streamable HTTP transport.
+ *
+ * Why a second transport file? `server.ts` owns the stdio path, where
+ * one long-lived `McpServer` is bound to the process for its whole
+ * lifetime. HTTP is request-scoped: the MCP Streamable HTTP spec wants
+ * a fresh server + transport per POST so concurrent clients can't
+ * collide on JSON-RPC request ids.
+ *
+ * We run **stateless** (no `Mcp-Session-Id`). scai's dispatch rwlock
+ * already serializes writes process-wide, so there is no per-session
+ * state worth keeping alive between requests, and progress
+ * notifications still ride the per-request response stream.
+ *
+ * Security: binds to loopback by default and validates the `Host`
+ * header against the bound address (DNS-rebinding defense — a
+ * malicious web page cannot point its own hostname at this loopback
+ * port). CORS is permissive on `Origin` so a browser-hosted MCP client
+ * can connect; the real boundary is the loopback bind + Host check +
+ * the per-call `allowWrite` gate every write tool already enforces.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startHttpTransport = void 0;
+const node_http_1 = require("node:http");
+const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+const server_1 = require("./server");
+/** The single MCP endpoint path. Everything else 404s. */
+const MCP_PATH = "/mcp";
+const writeJsonRpcError = (res, status, code, message) => {
+    res.writeHead(status, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ jsonrpc: "2.0", error: { code, message }, id: null }));
+};
+/**
+ * Permissive CORS so a browser-hosted MCP client can connect from any
+ * local dev origin. Origin filtering is deliberately *not* the security
+ * boundary here (see the file header) — it is reflected, not enforced.
+ */
+const applyCorsHeaders = (req, res) => {
+    const origin = req.headers.origin;
+    if (origin) {
+        res.setHeader("Access-Control-Allow-Origin", origin);
+        res.setHeader("Vary", "Origin");
+    }
+    else {
+        res.setHeader("Access-Control-Allow-Origin", "*");
+    }
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type, Accept, Authorization, Last-Event-ID, Mcp-Session-Id, Mcp-Protocol-Version");
+    res.setHeader("Access-Control-Expose-Headers", "Mcp-Session-Id");
+    res.setHeader("Access-Control-Max-Age", "86400");
+};
+const handleRequest = async (req, res, ctx) => {
+    applyCorsHeaders(req, res);
+    if (req.method === "OPTIONS") {
+        res.writeHead(204).end();
+        return;
+    }
+    // DNS-rebinding defense: the Host header must match the bound address.
+    const hostHeader = req.headers.host;
+    if (!hostHeader || !ctx.allowedHosts.has(hostHeader)) {
+        writeJsonRpcError(res, 403, -32600, `Forbidden: Host header '${hostHeader ?? ""}' is not allowed.`);
+        return;
+    }
+    const pathname = new URL(req.url ?? "/", `http://${hostHeader}`).pathname;
+    if (pathname !== MCP_PATH) {
+        writeJsonRpcError(res, 404, -32600, `Not found. The MCP endpoint is ${MCP_PATH}.`);
+        return;
+    }
+    // Stateless mode: GET (standalone SSE stream) and DELETE (session
+    // teardown) have no meaning without sessions.
+    if (req.method !== "POST") {
+        writeJsonRpcError(res, 405, -32600, `Method ${req.method ?? "?"} not allowed. POST JSON-RPC to ${MCP_PATH}.`);
+        return;
+    }
+    // A fresh server + transport per request so concurrent clients can't
+    // collide on JSON-RPC request ids. `buildMcpServer` is a cheap
+    // synchronous factory; the shared `getContext` provider stays
+    // memoized across all of them.
+    const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+    const server = (0, server_1.buildMcpServer)({ getContext: ctx.getContext, registry: ctx.registry });
+    res.on("close", () => {
+        void transport.close();
+        void server.close();
+    });
+    try {
+        await server.connect(transport);
+        await transport.handleRequest(req, res);
+    }
+    catch (error) {
+        if (!res.headersSent) {
+            writeJsonRpcError(res, 500, -32603, error instanceof Error ? error.message : String(error));
+        }
+    }
+};
+/**
+ * Start the Streamable HTTP listener. Resolves once the socket is bound
+ * (or rejects on a bind error, e.g. `EADDRINUSE`). The returned handle
+ * keeps the process alive via the open server; `close()` releases it.
+ */
+const startHttpTransport = (options) => {
+    const { host, port, getContext, registry } = options;
+    const allowedHosts = new Set();
+    const httpServer = (0, node_http_1.createServer)((req, res) => {
+        void handleRequest(req, res, { getContext, registry, allowedHosts });
+    });
+    return new Promise((resolve, reject) => {
+        const onError = (error) => reject(error);
+        httpServer.once("error", onError);
+        httpServer.listen(port, host, () => {
+            httpServer.off("error", onError);
+            const boundPort = httpServer.address().port;
+            // Populate the rebinding allowlist with the real port — the
+            // loopback aliases plus whatever `--host` resolved to.
+            for (const alias of [host, "localhost", "127.0.0.1", "[::1]"]) {
+                allowedHosts.add(`${alias}:${boundPort}`);
+            }
+            resolve({
+                url: `http://${host}:${boundPort}${MCP_PATH}`,
+                port: boundPort,
+                close: () => new Promise((closeResolve, closeReject) => {
+                    httpServer.close((err) => (err ? closeReject(err) : closeResolve()));
+                }),
+            });
+        });
+    });
+};
+exports.startHttpTransport = startHttpTransport;

package/dist/mcp/logging.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Stdout discipline for `scai mcp serve`.
+ *
+ * The stdio transport reserves stdout exclusively for JSON-RPC frames.
+ * Anything else that lands there breaks the protocol. The library code
+ * under scai is generally well-behaved (consola defaults to stderr,
+ * spinners and the Logger respect SITECOREAI_QUIET/JSON), but
+ * `installMcpStdoutDiscipline()` is the belt-and-braces guard:
+ *
+ *  1. Sets `SITECOREAI_MCP_SERVE=1`, `SITECOREAI_JSON=1`,
+ *     `SITECOREAI_QUIET=1`, `SITECOREAI_NON_INTERACTIVE=1` BEFORE any
+ *     other scai module loads. These suppress spinners, banners, and
+ *     stdout JSON dumps in the existing task runners.
+ *  2. Honors `--no-telemetry`: when telemetry is disabled for the
+ *     session it sets `SITECOREAI_TELEMETRY=false`. Otherwise it leaves
+ *     the env var untouched so normal resolution applies — telemetry is
+ *     on by default and `DO_NOT_TRACK` still wins.
+ *  3. Installs a consola reporter that pipes every log line to stderr,
+ *     regardless of consola's default level/destination behaviour.
+ *
+ * Call this at the very top of the `mcp serve` command action, before
+ * importing any other scai-internal module that might write to stdout
+ * during initialization.
+ */
+export declare const installMcpStdoutDiscipline: (options?: {
+    telemetry?: boolean;
+}) => void;
+export declare const writeStartupLine: (message: string) => void;

package/dist/mcp/logging.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Stdout discipline for `scai mcp serve`.
+ *
+ * The stdio transport reserves stdout exclusively for JSON-RPC frames.
+ * Anything else that lands there breaks the protocol. The library code
+ * under scai is generally well-behaved (consola defaults to stderr,
+ * spinners and the Logger respect SITECOREAI_QUIET/JSON), but
+ * `installMcpStdoutDiscipline()` is the belt-and-braces guard:
+ *
+ *  1. Sets `SITECOREAI_MCP_SERVE=1`, `SITECOREAI_JSON=1`,
+ *     `SITECOREAI_QUIET=1`, `SITECOREAI_NON_INTERACTIVE=1` BEFORE any
+ *     other scai module loads. These suppress spinners, banners, and
+ *     stdout JSON dumps in the existing task runners.
+ *  2. Honors `--no-telemetry`: when telemetry is disabled for the
+ *     session it sets `SITECOREAI_TELEMETRY=false`. Otherwise it leaves
+ *     the env var untouched so normal resolution applies — telemetry is
+ *     on by default and `DO_NOT_TRACK` still wins.
+ *  3. Installs a consola reporter that pipes every log line to stderr,
+ *     regardless of consola's default level/destination behaviour.
+ *
+ * Call this at the very top of the `mcp serve` command action, before
+ * importing any other scai-internal module that might write to stdout
+ * during initialization.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeStartupLine = exports.installMcpStdoutDiscipline = void 0;
+const consola_1 = require("consola");
+const FLAGS = [
+    ["SITECOREAI_MCP_SERVE", "1"],
+    ["SITECOREAI_JSON", "1"],
+    ["SITECOREAI_QUIET", "1"],
+    ["SITECOREAI_NON_INTERACTIVE", "1"],
+];
+let installed = false;
+const installMcpStdoutDiscipline = (options = {}) => {
+    if (installed) {
+        return;
+    }
+    installed = true;
+    for (const [key, value] of FLAGS) {
+        process.env[key] = value;
+    }
+    if (options.telemetry === false) {
+        process.env.SITECOREAI_TELEMETRY = "false";
+    }
+    const stderrReporter = {
+        log: (logObj) => {
+            const parts = [];
+            if (logObj.message !== undefined) {
+                parts.push(String(logObj.message));
+            }
+            if (logObj.args && logObj.args.length > 0) {
+                for (const arg of logObj.args) {
+                    parts.push(typeof arg === "string" ? arg : safeStringify(arg));
+                }
+            }
+            const line = parts.join(" ");
+            if (line.length > 0) {
+                process.stderr.write(`${line}\n`);
+            }
+        },
+    };
+    consola_1.consola.setReporters([stderrReporter]);
+};
+exports.installMcpStdoutDiscipline = installMcpStdoutDiscipline;
+const safeStringify = (value) => {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+};
+const writeStartupLine = (message) => {
+    process.stderr.write(`${message}\n`);
+};
+exports.writeStartupLine = writeStartupLine;

package/dist/mcp/prompts/workflows.d.ts

@@ -0,0 +1,13 @@
+/**
+ * MCP Prompts — slash-command-style templates surfaced by compatible
+ * clients. Each prompt returns a single user-role message that
+ * instructs the agent how to chain the registered tools to accomplish
+ * a higher-level workflow.
+ *
+ * The prompts are intentionally instruction text, not tool routing —
+ * the agent reads the message and dispatches the tools itself. This
+ * keeps the prompt layer transport-agnostic and easy to update without
+ * code changes elsewhere.
+ */
+import type { McpRegistry } from "../registry";
+export declare const registerWorkflowPrompts: (registry: McpRegistry) => void;

package/dist/mcp/prompts/workflows.js

@@ -0,0 +1,171 @@
+"use strict";
+/**
+ * MCP Prompts — slash-command-style templates surfaced by compatible
+ * clients. Each prompt returns a single user-role message that
+ * instructs the agent how to chain the registered tools to accomplish
+ * a higher-level workflow.
+ *
+ * The prompts are intentionally instruction text, not tool routing —
+ * the agent reads the message and dispatches the tools itself. This
+ * keeps the prompt layer transport-agnostic and easy to update without
+ * code changes elsewhere.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerWorkflowPrompts = void 0;
+const zod_1 = require("zod");
+const registerWorkflowPrompts = (registry) => {
+    registry.registerPrompt({
+        name: "scai.deploy_recipe",
+        description: "Guided workflow: compile a recipe, plan it, diff it, and push it to the target environment with explicit confirmations.",
+        argsSchema: {
+            recipeName: zod_1.z.string().describe("Recipe handle or file path."),
+            targetEnv: zod_1.z.string().describe("Target environment name."),
+        },
+        handler: async (args) => ({
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: [
+                            `Deploy recipe '${args.recipeName}' to environment '${args.targetEnv}'.`,
+                            "",
+                            "Step 1. Call `recipe_compile` with `inputPath: <path to recipe>` to produce the IR.",
+                            "Step 2. Call `recipe_diff` with `inputPath: <same path>` to surface the planned changes. Show the diff to the user.",
+                            "Step 3. Get explicit user confirmation before mutating the tenant.",
+                            "Step 4. Call `recipe_push` with `inputPath: <same path>`, `whatIf: false`, `allowWrite: true`.",
+                            "Step 5. Summarize the apply result back to the user (succeeded / aborted counts, any rollback).",
+                            "",
+                            "Abort early if step 2 surfaces destructive changes the user did not expect. Never set `allowWrite: true` without an explicit user confirmation in this turn.",
+                        ].join("\n"),
+                    },
+                },
+            ],
+        }),
+    });
+    registry.registerPrompt({
+        name: "scai.diff_envs",
+        description: "Guided workflow: diff serialized items between two environments, summarize, and propose next steps.",
+        argsSchema: {
+            sourceEnv: zod_1.z.string().describe("Source environment name."),
+            targetEnv: zod_1.z.string().describe("Target environment name."),
+        },
+        handler: async (args) => ({
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: [
+                            `Diff serialized state between '${args.sourceEnv}' and '${args.targetEnv}'.`,
+                            "",
+                            `Step 1. Call \`serialization_sync\` with \`direction: "diff"\`, \`source: "${args.sourceEnv}"\`, \`destination: "${args.targetEnv}"\`, \`pushOnDiff: false\`. Do NOT pass allowWrite.`,
+                            "Step 2. Summarize the diff for the user — count of items added, modified, removed.",
+                            `Step 3. If the user wants to push the diff to '${args.targetEnv}', re-call the tool with \`pushOnDiff: true\` AND \`allowWrite: true\` (only after explicit confirmation).`,
+                        ].join("\n"),
+                    },
+                },
+            ],
+        }),
+    });
+    registry.registerPrompt({
+        name: "scai.compose_workflow",
+        description: "Guided workflow: design a Sitecore workflow from a natural-language description, emit a recipe, and walk the user through dry-run + apply.",
+        argsSchema: {
+            intent: zod_1.z
+                .string()
+                .describe("Plain-English description of the workflow's purpose, the states it should have, and the webhook hooks (if any). Example: 'Editorial workflow for blog articles. Draft → In Review → Approved. In Review notifies a Slack channel; approval runs a lint webhook; Approved auto-publishes.'"),
+            handle: zod_1.z
+                .string()
+                .optional()
+                .describe("Recipe handle, format `<kebab-name>@<major>`. The agent should propose a sensible one if omitted (e.g. `blog-article-approval@1`)."),
+            targetEnv: zod_1.z
+                .string()
+                .optional()
+                .describe("Environment to push to. When omitted, uses the bound env."),
+        },
+        handler: async (args) => ({
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: [
+                            `Compose a workflow recipe from this intent:`,
+                            "",
+                            `> ${args.intent}`,
+                            "",
+                            args.handle
+                                ? `Use the handle '${args.handle}'.`
+                                : "Choose a stable handle in `<kebab-name>@<major>` form and tell the user what you chose + why.",
+                            "",
+                            "Step 1. **Read the reference first.** Call `resources/read` with `uri: 'scai://help/recipes-workflow'`. The reference covers the runtime model, recipe schema for both `workflow` and `webhook-authorization` kinds, authorization types + the `$ENV:VAR` secret-ref pattern, content-tree mapping, and failure modes.",
+                            "",
+                            "Step 2. **Verify the tenant supports webhook-action templates** before designing actions. Call `workflow_inspect verb='inspect' item: 'Sample Workflow'`. If the response's `result.definition.states[].actions[]` contains items templated `Webhook Submit Action` or `Webhook Validation Action`, the tenant supports webhook actions. If not, design WITHOUT `actions`/`validations`.",
+                            "",
+                            "Step 3. **Plan the workflow shape with the user before writing code.** Confirm:",
+                            "  - State keys + display names (kebab-case keys; need at least one `final: true`)",
+                            "  - Commands per state + their `nextState` targets",
+                            "  - For each webhook action: URL, kind (submit vs validation), authorization choice",
+                            "",
+                            "Step 4. **Emit the recipe.** Construct a `WorkflowRecipe` object literal matching the schema. If the design uses webhook authorizations not already on the tenant, also emit one or more `WebhookAuthorizationRecipe` objects. Don't write to disk yourself — present the TypeScript to the user and ask where they want it saved (typically `recipes/workflows/<handle>.recipe.ts`).",
+                            "",
+                            "Step 5. **Dry-run via the recipe MCP tools**:",
+                            "  - `recipe_compile` with the file path to confirm it parses to the expected IR.",
+                            "  - `recipe_diff` to surface what would change against the tenant.",
+                            "  - Show the IR + diff to the user.",
+                            "",
+                            "Step 6. **Apply on explicit confirmation only**:",
+                            args.targetEnv
+                                ? `  - The target environment is '${args.targetEnv}'. Confirm with the user before pushing.`
+                                : "  - Confirm the target environment is what the user expects (check the bound env via `scai_overview`).",
+                            "  - Call `recipe_push` with `inputPath: <file>`, `whatIf: false`, `allowWrite: true`.",
+                            "  - Show the per-op apply summary back to the user.",
+                            "",
+                            "Step 7. **Verify** by calling `workflow_inspect verb='inspect' item: '<displayName>'`. Walk the user through the state tree the response returns.",
+                            "",
+                            "Guardrails:",
+                            "- Never set `allowWrite: true` without an explicit user confirmation in this turn.",
+                            "- If a planned action's `authorizationRef` resolves nothing, abort and ask whether to (a) author a `webhook-authorization` recipe, (b) point at a tenant-side path via `authorizationPath`, or (c) drop authorization for now.",
+                            "- Recommend `webhook-validation` for synchronous gates (data quality, approval) and `webhook-submit` for one-way notifications (Slack, publish triggers).",
+                        ].join("\n"),
+                    },
+                },
+            ],
+        }),
+    });
+    registry.registerPrompt({
+        name: "scai.recover_failed_deploy",
+        description: "Guided workflow: inspect the last failed deployment, pull its logs, and present a remediation plan.",
+        argsSchema: {
+            deploymentId: zod_1.z
+                .string()
+                .optional()
+                .describe("Specific failed deployment id. When omitted, uses the most recent failed deploy."),
+        },
+        handler: async (args) => ({
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: [
+                            "Diagnose and remediate a failed XM Cloud deployment.",
+                            "",
+                            args.deploymentId
+                                ? `Step 1. Call \`deploy_run_inspect\` with \`deploymentId: "${args.deploymentId}"\`, \`includeLogs: true\`.`
+                                : "Step 1. Call `deploy_run_inspect` with no `deploymentId` to list recent deploys; identify the most recent failure; then call again with that deployment's id and `includeLogs: true`.",
+                            "Step 2. Read the logs and summarize the failure cause for the user.",
+                            "Step 3. Propose a remediation. Common patterns:",
+                            "  - Bad env variable → `deploy_environment_variables action=upsert` (allowWrite, with confirmation).",
+                            "  - Stale context → `deploy_environment_lifecycle action=regenerate-context` (allowWrite, with confirmation).",
+                            "  - Re-run the deployment → `deploy_run_start` with the same environmentId.",
+                            "Step 4. Wait for explicit user confirmation before any allowWrite step.",
+                        ].join("\n"),
+                    },
+                },
+            ],
+        }),
+    });
+};
+exports.registerWorkflowPrompts = registerWorkflowPrompts;

package/dist/mcp/redact.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Redaction wrapper for MCP tool result payloads.
+ *
+ * Wraps `redactSecrets` from `@/shared/redact` so it can walk a
+ * JSON-shaped structuredContent tree and scrub secrets from string
+ * values. Tool results that contain raw API responses (env variables,
+ * source-control integrations, auth metadata) flow through here before
+ * crossing the wire.
+ */
+export declare const redactString: (value: string) => string;
+export declare const redactStructured: (value: unknown) => unknown;

package/dist/mcp/redact.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * Redaction wrapper for MCP tool result payloads.
+ *
+ * Wraps `redactSecrets` from `@/shared/redact` so it can walk a
+ * JSON-shaped structuredContent tree and scrub secrets from string
+ * values. Tool results that contain raw API responses (env variables,
+ * source-control integrations, auth metadata) flow through here before
+ * crossing the wire.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redactStructured = exports.redactString = void 0;
+const redact_1 = require("../shared/redact");
+const redactString = (value) => (0, redact_1.redactSecrets)(value);
+exports.redactString = redactString;
+const redactStructured = (value) => {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (typeof value === "string") {
+        return (0, redact_1.redactSecrets)(value);
+    }
+    if (typeof value !== "object") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(exports.redactStructured);
+    }
+    const out = {};
+    for (const [key, nested] of Object.entries(value)) {
+        out[key] = (0, exports.redactStructured)(nested);
+    }
+    return out;
+};
+exports.redactStructured = redactStructured;