@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/mcp/tools/recipe.js

@@ -0,0 +1,250 @@
+"use strict";
+/**
+ * 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.)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerRecipeTools = void 0;
+const zod_1 = require("zod");
+const compile_1 = require("../../recipe/compile");
+const recipe_1 = require("../../recipe/schema/recipe");
+const io_1 = require("../../recipe/io");
+const diff_1 = require("../../recipe/tasks/diff");
+const plan_1 = require("../../recipe/tasks/plan");
+const push_1 = require("../../recipe/tasks/push");
+const errors_1 = require("../../shared/errors");
+const auth_1 = require("../auth");
+const descriptions_1 = require("../descriptions");
+const common_1 = require("../schemas/common");
+const compileContextSchema = zod_1.z
+    .object({
+    templatesRoot: zod_1.z.string().optional(),
+    renderingsRoot: zod_1.z.string().optional(),
+    componentsRoot: zod_1.z.string().optional(),
+    contentModelsRoot: zod_1.z.string().optional(),
+    partialDesignsRoot: zod_1.z.string().optional(),
+    pageDesignsRoot: zod_1.z.string().optional(),
+    contentItemsRoot: zod_1.z.string().optional(),
+    headlessVariantsRoot: zod_1.z.string().optional(),
+    availableRenderingsRoot: zod_1.z.string().optional(),
+    enumerationsRoot: zod_1.z.string().optional(),
+})
+    .optional();
+const resolveCompileContext = (envConfig, override) => {
+    const get = (key) => override?.[key] ??
+        envConfig[key];
+    const templatesRoot = get("templatesRoot");
+    const renderingsRoot = get("renderingsRoot");
+    if (!templatesRoot || !renderingsRoot) {
+        throw (0, errors_1.createScaiError)("templatesRoot and renderingsRoot are required (set them in the env profile, or pass overrides in `roots`).", "INPUT_INVALID");
+    }
+    return {
+        templatesRoot,
+        renderingsRoot,
+        componentsRoot: get("componentsRoot"),
+        contentModelsRoot: get("contentModelsRoot"),
+        partialDesignsRoot: get("partialDesignsRoot"),
+        pageDesignsRoot: get("pageDesignsRoot"),
+        contentItemsRoot: get("contentItemsRoot"),
+        headlessVariantsRoot: get("headlessVariantsRoot"),
+        availableRenderingsRoot: get("availableRenderingsRoot"),
+        enumerationsRoot: get("enumerationsRoot"),
+    };
+};
+const baseTaskOptions = (config, envName, overrides = {}) => ({
+    config,
+    environmentName: envName,
+    quiet: true,
+    json: false,
+    ...overrides,
+});
+const registerRecipeTools = (registry) => {
+    registry.registerTool({
+        name: "recipe_compile",
+        description: descriptions_1.TOOL_DESCRIPTIONS.recipe_compile,
+        auth: "read",
+        annotations: {
+            title: "Compile recipe to Operation IR",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+        inputSchema: {
+            inputPath: zod_1.z.string().optional().describe("Recipe file path (.ts or .json)."),
+            inputRecipe: zod_1.z
+                .record(zod_1.z.string(), zod_1.z.unknown())
+                .optional()
+                .describe("Pre-parsed JSON recipe object. Mutually exclusive with inputPath."),
+            roots: compileContextSchema.describe("Optional overrides for the compile roots (templatesRoot, renderingsRoot, ...)."),
+            ...common_1.environmentBindingShape,
+        },
+        handler: async (input, context) => {
+            if (!input.inputPath && !input.inputRecipe) {
+                throw (0, errors_1.createScaiError)("Either `inputPath` or `inputRecipe` must be provided.", "INPUT_INVALID");
+            }
+            if (input.inputPath && input.inputRecipe) {
+                throw (0, errors_1.createScaiError)("`inputPath` and `inputRecipe` are mutually exclusive.", "INPUT_INVALID");
+            }
+            const recipeRaw = input.inputPath
+                ? await (0, io_1.loadRecipe)(input.inputPath)
+                : recipe_1.RecipeSchema.parse(input.inputRecipe);
+            const binding = await (0, auth_1.resolveToolBinding)(context, input.environmentName);
+            const compileCtx = resolveCompileContext(binding.resolved.environment, input.roots);
+            const ir = (0, compile_1.compileRecipe)(recipeRaw, compileCtx);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Compiled recipe '${ir.recipeHandle}' to ${ir.operations.length} operation(s).`,
+                    },
+                ],
+                structuredContent: { ir },
+            };
+        },
+    });
+    registry.registerTool({
+        name: "recipe_diff",
+        description: descriptions_1.TOOL_DESCRIPTIONS.recipe_diff,
+        auth: "read",
+        annotations: {
+            title: "Diff recipe against bound tenant",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            inputPath: zod_1.z.string().describe("Recipe (.ts/.json) or IR (.json) file path."),
+            ...common_1.environmentBindingShape,
+        },
+        handler: async (input, context) => {
+            const envName = input.environmentName ?? context.envName;
+            const results = await (0, diff_1.runRecipeDiff)(baseTaskOptions(context.configPath, envName, { input: input.inputPath }));
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Diffed ${results.length} recipe action(s) against '${envName}'.`,
+                    },
+                ],
+                structuredContent: { results },
+            };
+        },
+    });
+    registry.registerTool({
+        name: "recipe_plan",
+        description: descriptions_1.TOOL_DESCRIPTIONS.recipe_plan,
+        auth: "read",
+        annotations: {
+            title: "Plan recipe against bound tenant",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            inputPath: zod_1.z.string().describe("Pre-compiled IR file path (.ir.json)."),
+            ...common_1.environmentBindingShape,
+        },
+        handler: async (input, context) => {
+            const envName = input.environmentName ?? context.envName;
+            const plan = await (0, plan_1.runRecipePlan)(baseTaskOptions(context.configPath, envName, { input: input.inputPath }));
+            const total = plan.summary.create + plan.summary.update + plan.summary.skip + plan.summary.error;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Plan for '${plan.recipeHandle}' on '${envName}': ${total} action(s) — create:${plan.summary.create}, update:${plan.summary.update}, skip:${plan.summary.skip}, error:${plan.summary.error}.`,
+                    },
+                ],
+                structuredContent: {
+                    environment: envName,
+                    recipeHandle: plan.recipeHandle,
+                    summary: plan.summary,
+                    actions: plan.actions.map((action) => ({
+                        index: action.index,
+                        op: action.operation.op,
+                        status: action.status,
+                        reason: action.reason,
+                    })),
+                },
+            };
+        },
+    });
+    registry.registerTool({
+        name: "recipe_push",
+        description: descriptions_1.TOOL_DESCRIPTIONS.recipe_push,
+        auth: "write",
+        annotations: {
+            title: "Push recipe to bound tenant",
+            readOnlyHint: false,
+            destructiveHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            inputPath: zod_1.z.string().describe("Recipe (.ts/.json) or IR (.json) file path."),
+            ...common_1.whatIfShape,
+            ...common_1.environmentBindingShape,
+            ...common_1.allowWriteShape,
+        },
+        handler: async (input, context, extra) => {
+            const envName = input.environmentName ?? context.envName;
+            let opCount = 0;
+            const results = await (0, push_1.runRecipePush)(baseTaskOptions(context.configPath, envName, {
+                input: input.inputPath,
+                whatIf: input.whatIf,
+                allowWrite: input.allowWrite,
+                signal: extra.signal,
+                emit: ({ recipe, event }) => {
+                    // Translate per-op events into MCP progress notifications.
+                    // We don't know the total op count up-front (compileRecipeSet
+                    // expands at runtime), so leave `total` undefined and use
+                    // an incrementing progress counter the client renders.
+                    if (event.kind === "op-start") {
+                        opCount += 1;
+                        void extra.sendProgress(opCount, undefined, `[${recipe}] op ${event.index}: ${event.operation.op}`);
+                    }
+                    else if (event.kind === "apply-success") {
+                        void extra.sendProgress(opCount, undefined, `[${recipe}] applied op ${event.action.index}`);
+                    }
+                    else if (event.kind === "apply-error") {
+                        void extra.sendProgress(opCount, undefined, `[${recipe}] error op ${event.action.index}: ${event.error}`);
+                    }
+                },
+            }));
+            const succeeded = results.filter((r) => !r.aborted).length;
+            const failed = results.length - succeeded;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Pushed ${results.length} recipe(s) to '${envName}'${input.whatIf ? " (whatIf)" : ""}: ${succeeded} succeeded, ${failed} aborted.`,
+                    },
+                ],
+                structuredContent: {
+                    environment: envName,
+                    whatIf: Boolean(input.whatIf),
+                    succeeded,
+                    failed,
+                    results: results.map((result) => ({
+                        recipeHandle: result.plan.recipeHandle,
+                        aborted: result.aborted,
+                        summary: result.summary,
+                        rollback: result.rollback,
+                    })),
+                },
+            };
+        },
+    });
+};
+exports.registerRecipeTools = registerRecipeTools;

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

@@ -0,0 +1,17 @@
+/**
+ * Serialization domain — wraps the local-vs-tenant sync flows (pull,
+ * push, diff) plus inspect / validate / publish around a workflow-shaped
+ * tool surface.
+ *
+ * `serialization_sync` consolidates `runPull` / `runPush` / `runDiff`
+ * behind a single `{ direction }` discriminator. Push and diff-with-push
+ * require `allowWrite: true`; pull is technically a write-to-disk but
+ * remains read-class because it never mutates the tenant.
+ *
+ * Detailed line-item output is intentionally suppressed at the tool
+ * boundary — long-form item-by-item logs would explode the response.
+ * Agents re-inspect via `serialization_inspect` (filesystem) or
+ * `environment_status` (tenant) after a sync to confirm the new state.
+ */
+import type { McpRegistry } from "../registry";
+export declare const registerSerializationTools: (registry: McpRegistry) => void;

package/dist/mcp/tools/serialization.js

@@ -0,0 +1,282 @@
+"use strict";
+/**
+ * Serialization domain — wraps the local-vs-tenant sync flows (pull,
+ * push, diff) plus inspect / validate / publish around a workflow-shaped
+ * tool surface.
+ *
+ * `serialization_sync` consolidates `runPull` / `runPush` / `runDiff`
+ * behind a single `{ direction }` discriminator. Push and diff-with-push
+ * require `allowWrite: true`; pull is technically a write-to-disk but
+ * remains read-class because it never mutates the tenant.
+ *
+ * Detailed line-item output is intentionally suppressed at the tool
+ * boundary — long-form item-by-item logs would explode the response.
+ * Agents re-inspect via `serialization_inspect` (filesystem) or
+ * `environment_status` (tenant) after a sync to confirm the new state.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSerializationTools = void 0;
+const zod_1 = require("zod");
+const pull_1 = require("../../serialization/tasks/pull");
+const push_1 = require("../../serialization/tasks/push");
+const diff_1 = require("../../serialization/tasks/diff");
+const validate_1 = require("../../serialization/tasks/validate");
+const info_1 = require("../../serialization/tasks/info");
+const shared_1 = require("../../serialization/tasks/shared");
+const publish_1 = require("../../serialization/api/publish");
+const errors_1 = require("../../shared/errors");
+const auth_1 = require("../auth");
+const descriptions_1 = require("../descriptions");
+const common_1 = require("../schemas/common");
+const baseSyncOptions = (config, envName, overrides = {}) => ({
+    config,
+    environmentName: envName,
+    quiet: true,
+    json: false,
+    ...overrides,
+});
+const registerSerializationTools = (registry) => {
+    registry.registerTool({
+        name: "serialization_inspect",
+        description: descriptions_1.TOOL_DESCRIPTIONS.serialization_inspect,
+        auth: "read",
+        annotations: {
+            title: "Inspect serialization modules",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+        inputSchema: {
+            path: zod_1.z
+                .string()
+                .optional()
+                .describe("Optional Sitecore item path. When provided, returns the per-subtree explanation; otherwise returns the full module set."),
+            ...common_1.environmentBindingShape,
+        },
+        handler: async (input, context) => {
+            const envName = input.environmentName ?? context.envName;
+            const options = baseSyncOptions(context.configPath, envName);
+            const { root, modules } = await (0, shared_1.loadConfigAndModules)(options);
+            // runInfo also writes to consola (stderr per our redirector) but
+            // we don't need its side-effect — we already have the data shape.
+            void info_1.runInfo;
+            const filtered = input.path
+                ? modules
+                    .map((module) => ({
+                    ...module,
+                    items: {
+                        ...module.items,
+                        includes: module.items.includes.filter((sub) => sub.path.toPathString().toLowerCase() === input.path.toLowerCase()),
+                    },
+                }))
+                    .filter((module) => module.items.includes.length > 0)
+                : modules;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Resolved ${filtered.length} module(s) for environment '${envName}'.`,
+                    },
+                ],
+                structuredContent: {
+                    environment: envName,
+                    excludedFields: root.serialization.excludedFields,
+                    modules: filtered.map((module) => ({
+                        namespace: module.namespace,
+                        description: module.description,
+                        sourceIdentifier: module.sourceIdentifier,
+                        references: module.references,
+                        subtrees: module.items.includes.map((subtree) => ({
+                            name: subtree.name,
+                            database: subtree.database,
+                            path: subtree.path.toPathString(),
+                            scope: subtree.scope,
+                            physicalPath: subtree.physicalPath,
+                            allowedPushOperations: subtree.allowedPushOperations,
+                        })),
+                        roleCount: module.roles.length,
+                        userCount: module.users.length,
+                    })),
+                },
+            };
+        },
+    });
+    registry.registerTool({
+        name: "serialization_sync",
+        description: descriptions_1.TOOL_DESCRIPTIONS.serialization_sync,
+        auth: "write",
+        annotations: {
+            title: "Pull / push / diff serialized items",
+            readOnlyHint: false,
+            destructiveHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            direction: zod_1.z.enum(["pull", "push", "diff"]),
+            path: zod_1.z.string().optional().describe("Optional Sitecore item path narrow (sync only)."),
+            modules: zod_1.z.array(zod_1.z.string()).optional().describe("Optional module namespace include filter."),
+            source: zod_1.z.string().optional().describe("Source environment name (direction=diff only)."),
+            destination: zod_1.z
+                .string()
+                .optional()
+                .describe("Destination environment name (direction=diff only)."),
+            pushOnDiff: zod_1.z
+                .boolean()
+                .default(false)
+                .describe("When direction=diff, push the diff to the destination. Requires allowWrite: true."),
+            ...common_1.whatIfShape,
+            ...common_1.environmentBindingShape,
+            ...common_1.allowWriteShape,
+        },
+        handler: async (input, context, extra) => {
+            const envName = input.environmentName ?? context.envName;
+            const isWrite = input.direction === "push" || (input.direction === "diff" && input.pushOnDiff);
+            if (isWrite && !input.allowWrite) {
+                throw (0, errors_1.createScaiError)("Direction 'push' (and 'diff' with pushOnDiff) requires allowWrite: true.", "INPUT_INVALID");
+            }
+            const include = input.modules ?? [];
+            let dbCount = 0;
+            const emit = (event) => {
+                switch (event.kind) {
+                    case "database-start":
+                        dbCount += 1;
+                        void extra.sendProgress(dbCount, undefined, `Starting ${event.database} (${event.subtreeCount} subtree(s))`);
+                        break;
+                    case "database-changes-detected":
+                        void extra.sendProgress(dbCount, undefined, `${event.database}: ${event.changes} change(s) detected`);
+                        break;
+                    case "database-applied":
+                        void extra.sendProgress(dbCount, undefined, `${event.database}: applied ${event.changes} change(s)${event.whatIf ? " (whatIf)" : ""}`);
+                        break;
+                    case "database-skipped":
+                        void extra.sendProgress(dbCount, undefined, `${event.database}: skipped (${event.reason})`);
+                        break;
+                }
+            };
+            const baseOptions = baseSyncOptions(context.configPath, envName, {
+                whatIf: input.whatIf,
+                allowWrite: input.allowWrite,
+                include,
+                exclude: [],
+                emit,
+                signal: extra.signal,
+            });
+            switch (input.direction) {
+                case "pull":
+                    await (0, pull_1.runPull)(baseOptions);
+                    break;
+                case "push":
+                    await (0, push_1.runPush)(baseOptions);
+                    break;
+                case "diff": {
+                    const diffOptions = {
+                        ...baseOptions,
+                        source: input.source ?? envName,
+                        destination: input.destination ?? envName,
+                        push: input.pushOnDiff,
+                        path: input.path,
+                    };
+                    await (0, diff_1.runDiff)(diffOptions);
+                    break;
+                }
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `serialization ${input.direction} completed for '${envName}'${input.whatIf ? " (whatIf)" : ""}.`,
+                    },
+                ],
+                structuredContent: {
+                    direction: input.direction,
+                    environment: envName,
+                    whatIf: Boolean(input.whatIf),
+                    modulesIncluded: include,
+                    databasesProcessed: dbCount,
+                    status: "completed",
+                },
+            };
+        },
+    });
+    registry.registerTool({
+        name: "serialization_validate",
+        description: descriptions_1.TOOL_DESCRIPTIONS.serialization_validate,
+        auth: "read",
+        annotations: {
+            title: "Validate serialization config",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+        inputSchema: {
+            fix: zod_1.z.boolean().default(false).describe("Attempt automatic fixes for safe issues."),
+            ...common_1.environmentBindingShape,
+        },
+        handler: async (input, context) => {
+            const envName = input.environmentName ?? context.envName;
+            try {
+                await (0, validate_1.runValidate)(baseSyncOptions(context.configPath, envName, { fix: input.fix }));
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `serialization validation failed for '${envName}'.`,
+                        },
+                    ],
+                    structuredContent: {
+                        valid: false,
+                        environment: envName,
+                        error: error instanceof Error ? error.message : String(error),
+                    },
+                };
+            }
+            return {
+                content: [{ type: "text", text: `serialization validation passed for '${envName}'.` }],
+                structuredContent: { valid: true, environment: envName },
+            };
+        },
+    });
+    registry.registerTool({
+        name: "serialization_publish",
+        description: descriptions_1.TOOL_DESCRIPTIONS.serialization_publish,
+        auth: "write",
+        annotations: {
+            title: "Publish item subtree",
+            readOnlyHint: false,
+            destructiveHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            path: zod_1.z.string().describe("Sitecore item path (master database) to publish."),
+            database: zod_1.z.string().default("master").describe("Source database to read the item from."),
+            target: zod_1.z.string().optional().describe("Optional publish target name."),
+            ...common_1.environmentBindingShape,
+            ...common_1.allowWriteShape,
+        },
+        handler: async (input, context) => {
+            const binding = await (0, auth_1.resolveToolBinding)(context, input.environmentName);
+            const result = await (0, publish_1.publishItemSubtree)(binding.resolved.environment, input.path, {
+                database: input.database,
+                target: input.target,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Published ${result.itemCount} item(s) under '${result.path}'. Job '${result.job.id}' state '${result.job.stateName}'.`,
+                    },
+                ],
+                structuredContent: {
+                    path: result.path,
+                    database: result.database,
+                    target: result.target,
+                    itemCount: result.itemCount,
+                    job: result.job,
+                },
+            };
+        },
+    });
+};
+exports.registerSerializationTools = registerSerializationTools;

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

@@ -0,0 +1,12 @@
+/**
+ * Webhook domain — inspect + manage.
+ *
+ *   - `webhook_inspect` (read) lists handlers or fetches one by id/path.
+ *   - `webhook_manage` (write) creates an item/publish event handler or
+ *     a workflow submit/validation action, and deletes any of the above.
+ *
+ * Mirrors the workflow tools' discriminated-verb pattern. Each handler
+ * delegates to the `runWebhook*` task functions shared with the CLI.
+ */
+import type { McpRegistry } from "../registry";
+export declare const registerWebhookTools: (registry: McpRegistry) => void;