@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/mcp/tools/cleanup.js

@@ -0,0 +1,608 @@
+"use strict";
+/**
+ * Cleanup domain — preview + execute.
+ *
+ * Two tools cover the destructive hygiene surface:
+ *
+ *   - `cleanup_preview` (read) — runs any cleanup verb with
+ *     `whatIf: true` so the agent can show the user what would change
+ *     before asking for write authorization. No tenant mutations occur.
+ *
+ *   - `cleanup_execute` (write) — single destructive entry point,
+ *     discriminated on `verb`. Honors the per-call `allowWrite` gate
+ *     enforced at dispatch, the `whatIf` plan-only flag, and per-verb
+ *     blast-radius caps (`max*` options forwarded to the underlying
+ *     library). Every verb returns a per-action list so the caller can
+ *     inspect what actually applied.
+ *
+ * Verbs map 1:1 with the `scai hygiene cleanup` CLI verbs whose library task
+ * honors `--what-if`. The interactive-keep mode for `duplicates` stays
+ * CLI-only because it requires per-group keystroke selection.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerCleanupTools = void 0;
+const zod_1 = require("zod");
+const archive_purge_1 = require("../../hygiene/tasks/cleanup/archive-purge");
+const dead_templates_1 = require("../../hygiene/tasks/cleanup/dead-templates");
+const duplicates_1 = require("../../hygiene/tasks/cleanup/duplicates");
+const empty_folders_1 = require("../../hygiene/tasks/cleanup/empty-folders");
+const field_set_1 = require("../../hygiene/tasks/cleanup/field-set");
+const find_replace_1 = require("../../hygiene/tasks/cleanup/find-replace");
+const language_version_add_1 = require("../../hygiene/tasks/cleanup/language-version-add");
+const rename_1 = require("../../hygiene/tasks/cleanup/rename");
+const roles_1 = require("../../hygiene/tasks/cleanup/roles");
+const site_residue_1 = require("../../hygiene/tasks/cleanup/site-residue");
+const slug_conflicts_1 = require("../../hygiene/tasks/cleanup/slug-conflicts");
+const subtree_1 = require("../../hygiene/tasks/cleanup/subtree");
+const users_1 = require("../../hygiene/tasks/cleanup/users");
+const versions_archive_1 = require("../../hygiene/tasks/cleanup/versions-archive");
+const versions_prune_1 = require("../../hygiene/tasks/cleanup/versions-prune");
+const workflow_advance_1 = require("../../hygiene/tasks/cleanup/workflow-advance");
+const workflow_apply_1 = require("../../hygiene/tasks/cleanup/workflow-apply");
+const allow_write_1 = require("../../policy/allow-write");
+const errors_1 = require("../../shared/errors");
+const auth_1 = require("../auth");
+const descriptions_1 = require("../descriptions");
+const common_1 = require("../schemas/common");
+/**
+ * Convert a typed runner into the loose-typed dispatch shape. Replaces
+ * the prior `as never` casts. Still an unsafe cast at its core, but
+ * localized to one helper *and* the caller's runner is required to
+ * return `Promise<readonly X[]>` — so if a runner is refactored to
+ * return a non-array (the way `runCleanupDeadTemplates` historically
+ * did), the call to `loosen` fails type-check and surfaces the bug
+ * here instead of leaking into the dispatch path.
+ */
+const loosen = (fn) => fn;
+/**
+ * Cleanup verb registry — verb name → task runner. Each runner accepts
+ * an option bag whose shape varies per verb; the input schema below
+ * documents which options each verb honors.
+ *
+ * Dead-templates returns `{templates, folders}` rather than a flat
+ * array, so it gets an inline flatten so the dispatch handler can treat
+ * every runner's output uniformly (`actions.length`, iterable for
+ * `summarizeActions`).
+ */
+const CLEANUP_RUNNERS = {
+    "versions-prune": loosen(versions_prune_1.runCleanupVersionsPrune),
+    "versions-archive": loosen(versions_archive_1.runCleanupVersionsArchive),
+    "archive-purge": loosen(archive_purge_1.runCleanupArchivePurge),
+    "dead-templates": loosen(async (options) => {
+        const r = await (0, dead_templates_1.runCleanupDeadTemplates)(options);
+        return [...r.templates, ...r.folders.map((f) => ({ ...f, kind: "folder" }))];
+    }),
+    duplicates: loosen(duplicates_1.runCleanupDuplicates),
+    "empty-folders": loosen(empty_folders_1.runCleanupEmptyFolders),
+    "field-set": loosen(field_set_1.runCleanupFieldSet),
+    "find-replace": loosen(find_replace_1.runCleanupFindReplace),
+    "language-versions-add": loosen(language_version_add_1.runCleanupLanguageVersionAdd),
+    rename: loosen(rename_1.runCleanupRename),
+    roles: loosen(roles_1.runCleanupRoles),
+    "site-residue": loosen(site_residue_1.runCleanupSiteResidue),
+    "slug-conflicts": loosen(slug_conflicts_1.runCleanupSlugConflicts),
+    subtree: loosen(async (options) => {
+        const r = await (0, subtree_1.runCleanupSubtree)(options);
+        // Flatten the {blockers, deletions} envelope so the MCP dispatch
+        // handler's `actions.length` matches the user-visible work.
+        return [
+            ...r.blockers.map((b) => ({ ...b, kind: "blocker" })),
+            ...r.deletions.map((d) => ({ ...d, kind: "deletion" })),
+        ];
+    }),
+    users: loosen(users_1.runCleanupUsers),
+    "workflow-advance": loosen(workflow_advance_1.runCleanupWorkflowAdvance),
+    "workflow-apply": loosen(workflow_apply_1.runCleanupWorkflowApply),
+};
+/**
+ * Verbs whose underlying library expects `root` as a `string[]` (extra
+ * roots beyond the SXA defaults) rather than the usual single
+ * content-tree path. The top-level `root` field is omitted for these
+ * — callers pass the array via `extraRoots`.
+ */
+const ROOT_AS_ARRAY_VERBS = new Set(["site-residue"]);
+const baseTaskOptions = (config, envName, overrides = {}) => ({
+    config,
+    environmentName: envName,
+    quiet: true,
+    json: true,
+    ...overrides,
+});
+/** Validate verb-specific required inputs that the runner would otherwise reject later. */
+const validateVerbInputs = (verb, input) => {
+    switch (verb) {
+        case "versions-prune":
+        case "versions-archive":
+            if (input.keep === undefined) {
+                throw (0, errors_1.createScaiError)(`verb='${verb}' requires \`keep\`.`, "INPUT_INVALID");
+            }
+            if (!input.root) {
+                throw (0, errors_1.createScaiError)(`verb='${verb}' requires \`root\`.`, "INPUT_INVALID");
+            }
+            break;
+        case "empty-folders":
+            if (!input.root) {
+                throw (0, errors_1.createScaiError)("verb='empty-folders' requires `root`.", "INPUT_INVALID");
+            }
+            break;
+        case "find-replace":
+            if (!input.pattern || input.replacement === undefined) {
+                throw (0, errors_1.createScaiError)("verb='find-replace' requires `pattern` and `replacement`.", "INPUT_INVALID");
+            }
+            break;
+        case "workflow-advance":
+            if (!input.commandName) {
+                throw (0, errors_1.createScaiError)("verb='workflow-advance' requires `commandName`.", "INPUT_INVALID");
+            }
+            break;
+        case "workflow-apply":
+            if (!input.workflow) {
+                throw (0, errors_1.createScaiError)("verb='workflow-apply' requires `workflow`.", "INPUT_INVALID");
+            }
+            break;
+        case "field-set":
+            if (!input.field) {
+                throw (0, errors_1.createScaiError)("verb='field-set' requires `field`.", "INPUT_INVALID");
+            }
+            if (input.mode !== "clear" && (input.value === undefined || input.value === null)) {
+                throw (0, errors_1.createScaiError)(`verb='field-set' requires \`value\` (mode='${input.mode ?? "replace"}').`, "INPUT_INVALID");
+            }
+            break;
+        case "rename":
+            if (!input.pattern || input.replacement === undefined) {
+                throw (0, errors_1.createScaiError)("verb='rename' requires `pattern` and `replacement`.", "INPUT_INVALID");
+            }
+            break;
+        case "language-versions-add":
+            if (!input.languages) {
+                throw (0, errors_1.createScaiError)("verb='language-versions-add' requires `languages`.", "INPUT_INVALID");
+            }
+            break;
+    }
+};
+const summarizeActions = (verb, actions) => {
+    const counts = new Map();
+    for (const a of actions) {
+        const status = a.status ?? "unknown";
+        counts.set(status, (counts.get(status) ?? 0) + 1);
+    }
+    if (counts.size === 0)
+        return `cleanup ${verb}: 0 actions.`;
+    const parts = [...counts.entries()].map(([k, v]) => `${k}=${v}`).join(", ");
+    return `cleanup ${verb}: ${actions.length} action(s) (${parts}).`;
+};
+/**
+ * Forward every input field except routing/auth flags to the runner.
+ * The library validates its own option keys; passing extras is safe
+ * (each task reads only the keys it knows about).
+ */
+const buildRunnerOptions = (verb, input, shared, whatIf) => {
+    const merged = { ...shared, whatIf };
+    const rootAsArray = ROOT_AS_ARRAY_VERBS.has(verb);
+    for (const [k, v] of Object.entries(input)) {
+        if (v === undefined)
+            continue;
+        if (k === "verb" || k === "whatIf" || k === "allowWrite" || k === "environmentName")
+            continue;
+        // Skip the top-level `root` (string) for verbs that expect an array;
+        // the `extraRoots` field below feeds it instead.
+        if (rootAsArray && k === "root")
+            continue;
+        if (k === "extraRoots") {
+            if (rootAsArray)
+                merged.root = v;
+            continue;
+        }
+        merged[k] = v;
+    }
+    return merged;
+};
+const registerCleanupTools = (registry) => {
+    registry.registerTool({
+        name: "cleanup_preview",
+        description: descriptions_1.TOOL_DESCRIPTIONS.cleanup_preview,
+        auth: "read",
+        annotations: {
+            title: "Plan a cleanup verb without mutating the tenant",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            ...cleanupInputSchema(),
+            ...common_1.environmentBindingShape,
+        },
+        handler: async (input, context) => {
+            validateVerbInputs(input.verb, input);
+            const runner = CLEANUP_RUNNERS[input.verb];
+            if (!runner) {
+                throw (0, errors_1.createScaiError)(`Unknown cleanup verb '${input.verb}'.`, "INPUT_INVALID");
+            }
+            const opts = buildRunnerOptions(input.verb, input, baseTaskOptions(context.configPath, input.environmentName ?? context.envName), true);
+            const actions = await runner(opts);
+            return {
+                content: [{ type: "text", text: summarizeActions(input.verb, actions) }],
+                structuredContent: {
+                    verb: input.verb,
+                    whatIf: true,
+                    count: actions.length,
+                    actions,
+                },
+            };
+        },
+    });
+    registry.registerTool({
+        name: "cleanup_execute",
+        description: descriptions_1.TOOL_DESCRIPTIONS.cleanup_execute,
+        auth: "write",
+        annotations: {
+            title: "Execute a destructive cleanup verb (versions, archive, roles, users, ...)",
+            readOnlyHint: false,
+            // Every verb either deletes content/users/roles or rewrites field
+            // values. Mark destructive so the host's confirmation UX fires.
+            destructiveHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            ...cleanupInputSchema(),
+            ...common_1.whatIfShape,
+            ...common_1.environmentBindingShape,
+            ...common_1.allowWriteShape,
+        },
+        handler: async (input, context) => {
+            validateVerbInputs(input.verb, input);
+            const runner = CLEANUP_RUNNERS[input.verb];
+            if (!runner) {
+                throw (0, errors_1.createScaiError)(`Unknown cleanup verb '${input.verb}'.`, "INPUT_INVALID");
+            }
+            const whatIf = input.whatIf === true;
+            // Resolve the target environment (bound default unless retargeted
+            // via `environmentName`).
+            const binding = await (0, auth_1.resolveToolBinding)(context, input.environmentName);
+            // Per-env opt-out for MCP-elevated writes, checked against the
+            // TARGET env. Only enforced when this call would actually mutate
+            // the tenant — what-if previews are read-only and always permitted.
+            if (!whatIf) {
+                (0, allow_write_1.ensureMcpElevationAllowed)(binding.resolved.root, binding.envName);
+            }
+            const opts = buildRunnerOptions(input.verb, input, baseTaskOptions(context.configPath, binding.envName, {
+                allowWrite: !whatIf,
+            }), whatIf);
+            const actions = await runner(opts);
+            return {
+                content: [{ type: "text", text: summarizeActions(input.verb, actions) }],
+                structuredContent: {
+                    verb: input.verb,
+                    whatIf,
+                    count: actions.length,
+                    actions,
+                },
+            };
+        },
+    });
+};
+exports.registerCleanupTools = registerCleanupTools;
+/**
+ * Shared input schema for cleanup_preview + cleanup_execute. Built as a
+ * function so each tool gets its own ZodRawShape instance (the registry
+ * spreads them into separate input objects; sharing would couple the
+ * defaults).
+ */
+const cleanupInputSchema = () => ({
+    verb: zod_1.z
+        .enum([
+        "versions-prune",
+        "versions-archive",
+        "archive-purge",
+        "dead-templates",
+        "duplicates",
+        "empty-folders",
+        "field-set",
+        "find-replace",
+        "language-versions-add",
+        "rename",
+        "roles",
+        "site-residue",
+        "slug-conflicts",
+        "subtree",
+        "users",
+        "workflow-advance",
+        "workflow-apply",
+    ])
+        .describe("Which cleanup operation to run. Each verb maps 1:1 to a `scai hygiene cleanup …` CLI command and shares its option contract. Mostly destructive — pair with cleanup_preview first, or pass `whatIf: true`. Required fields per verb: versions-prune/versions-archive (`keep`, `root`); empty-folders (`root`); field-set (`field`; `value` unless mode='clear'); find-replace (`pattern`, `replacement`); language-versions-add (`languages`); rename (`pattern`, `replacement`); subtree (`path`); workflow-advance (`commandName`); workflow-apply (`workflow`). site-residue extends the SXA Project defaults via `extraRoots` (its underlying option is `string[]`, not the top-level `root`). slug-conflicts honors `keepRule` + `action` (`delete` default, or `rename` with optional `renameSuffix`) — `audit slug-conflicts` first to preview groups. subtree refuses by default when external items reference the deletion target — pass `orphanExternalRefs: 'clear'` to empty those fields first. All others have safe defaults but accept the same option bag."),
+    // versions-prune / versions-archive
+    keep: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Number of most-recent versions to keep per (item, language). Required for versions-prune / versions-archive."),
+    root: zod_1.z
+        .string()
+        .optional()
+        .describe("Content-tree root to operate under. Required for versions-prune, versions-archive, empty-folders. Default per-verb otherwise."),
+    language: zod_1.z
+        .string()
+        .optional()
+        .describe("Restrict to a single language code (e.g. 'en'). Honored by versions-prune, versions-archive, find-replace."),
+    limit: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .max(50000)
+        .optional()
+        .describe("Cap on items inspected. Per-verb default."),
+    index: zod_1.z.string().optional().describe("Override the search index name."),
+    concurrency: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .max(32)
+        .optional()
+        .describe("Parallelism for the underlying library calls. Default 4."),
+    includeSystem: zod_1.z
+        .boolean()
+        .optional()
+        .describe("Permit operating against /sitecore/system + /sitecore/templates/System subtrees. Off by default."),
+    force: zod_1.z
+        .boolean()
+        .optional()
+        .describe("Override the per-verb safety guard that refuses to operate on platform subtrees (templates/System, layout/Layouts/System). Off by default."),
+    // archive-purge
+    olderThanDays: zod_1.z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe("archive-purge: only purge items archived more than N days ago. Default 30. Setting to 0 purges every archived item."),
+    archiveName: zod_1.z.string().optional().describe("archive-purge: limit to one archive name."),
+    pageSize: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("archive-purge: archive listing page size. Default 100."),
+    // dead-templates
+    cleanupEmptyFolders: zod_1.z
+        .boolean()
+        .optional()
+        .describe("dead-templates: also delete now-empty template folders after removing dead templates. Default true."),
+    // duplicates
+    minGroupSize: zod_1.z
+        .number()
+        .int()
+        .min(2)
+        .optional()
+        .describe("duplicates: minimum group size to consider a duplicate. Default 2."),
+    keepRule: zod_1.z
+        .enum(["oldest", "newest", "shortest-path"])
+        .optional()
+        .describe("duplicates / slug-conflicts: which group member survives. Default `oldest`. (interactive keep is CLI-only — not exposed via MCP.)"),
+    includeSystemFields: zod_1.z
+        .boolean()
+        .optional()
+        .describe("duplicates / find-replace: hash/scan __-prefixed system fields. Off by default."),
+    // slug-conflicts
+    action: zod_1.z
+        .enum(["delete", "rename"])
+        .optional()
+        .describe("slug-conflicts: what to do with losing siblings. `delete` (default) calls deleteItem(permanently: true) — breaks inbound refs. `rename` calls renameItem with a suffix derived from `renameSuffix` — preserves inbound refs but leaves stale slugs."),
+    renameSuffix: zod_1.z
+        .string()
+        .optional()
+        .describe("slug-conflicts: suffix template when `action: 'rename'`. Placeholders: `{shortId}` (8-char itemId prefix), `{full}` (32-char id). Default: '-{shortId}'."),
+    caseInsensitive: zod_1.z
+        .boolean()
+        .optional()
+        .describe("slug-conflicts: treat sibling names as case-insensitive when grouping. Default true — matches the audit's default and most renderers' URL resolution."),
+    checkRefs: zod_1.z
+        .boolean()
+        .optional()
+        .describe("slug-conflicts: pre-scan inbound references per loser. Preview mode attaches counts to each resolved row (warn-only). Apply mode (`whatIf: false`) aborts the call when any loser has positive counts — INPUT_INVALID with the blocker list. Off by default; cost scales with number of losers."),
+    refCheckRoot: zod_1.z
+        .string()
+        .optional()
+        .describe("slug-conflicts: content root for the inbound-ref scan when `checkRefs: true`. Default `/sitecore` (full tenant). Narrow on large tenants if you know refs only come from a subtree."),
+    // empty-folders
+    maxDeletions: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .max(10000)
+        .optional()
+        .describe("Blast-radius cap. Default per-verb (empty-folders 500, roles 50, users 25)."),
+    // find-replace
+    pattern: zod_1.z
+        .string()
+        .optional()
+        .describe("find-replace: search pattern. Required for find-replace."),
+    replacement: zod_1.z
+        .string()
+        .optional()
+        .describe("find-replace: replacement string. Required for find-replace."),
+    literal: zod_1.z
+        .boolean()
+        .optional()
+        .describe("find-replace: treat `pattern` as a literal string, not a regex. Default false."),
+    ignoreCase: zod_1.z
+        .boolean()
+        .optional()
+        .describe("find-replace: case-insensitive matching. Default false."),
+    flags: zod_1.z
+        .string()
+        .optional()
+        .describe("find-replace: regex flags string (e.g. 'gim'). Mutually exclusive with literal."),
+    fields: zod_1.z.array(zod_1.z.string()).optional().describe("find-replace: restrict to these field names."),
+    batchSize: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("find-replace / duplicates: field-batch read size."),
+    pageParallelism: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("find-replace: scan-page parallelism."),
+    cache: zod_1.z.boolean().optional().describe("find-replace: enable on-disk field cache."),
+    exclude: zod_1.z.array(zod_1.z.string()).optional().describe("find-replace: glob patterns to exclude."),
+    // roles
+    domain: zod_1.z
+        .string()
+        .optional()
+        .describe("roles: restrict to one Sitecore domain (e.g. 'sitecore')."),
+    // users
+    notActiveDays: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("users: inactivity threshold. Default 365."),
+    includeAdmins: zod_1.z
+        .boolean()
+        .optional()
+        .describe("users: include administrators in the deletion set. Strongly discouraged — opt-in only."),
+    includeServiceAccounts: zod_1.z
+        .boolean()
+        .optional()
+        .describe("users: include service-account names (regex-matched). Off by default."),
+    useActivityDate: zod_1.z
+        .boolean()
+        .optional()
+        .describe("users: use lastActivityDate instead of lastLoginDate for the inactivity check. Off by default."),
+    // subtree
+    path: zod_1.z
+        .string()
+        .optional()
+        .describe("subtree: content-tree path of the subtree root to delete. Required for subtree."),
+    scanRoot: zod_1.z
+        .string()
+        .optional()
+        .describe("subtree: content root scanned for inbound references. Default `/sitecore` (entire CMS). Narrow for speed at the cost of missing refs outside the chosen root."),
+    orphanExternalRefs: zod_1.z
+        .enum(["clear", "prune", "leave"])
+        .optional()
+        .describe("subtree: how to handle external items whose fields reference the subtree. Omit (default) = refuse with blocker list. 'clear' empties the entire referring field. 'prune' surgically removes only the offending entries (preserves siblings in multi-list / treelist fields and `<r>` elements in `__Renderings` XML); falls back to clear for single-value fields. 'leave' skips the inbound-ref scan entirely — fastest mode; accepts dangling refs and expects an `audit broken-links` follow-up. Use --what-if first to preview the non-`leave` modes."),
+    // site-residue
+    extraRoots: zod_1.z
+        .array(zod_1.z.string())
+        .optional()
+        .describe("site-residue: additional roots to scan beyond the SXA Project defaults (templates/Project, layout/Renderings/Project, media library/Project). Replaces the top-level `root` for this verb."),
+    contentRoot: zod_1.z
+        .string()
+        .optional()
+        .describe("site-residue: override the content root walked when discovering active sites. Default `/sitecore/content`."),
+    skipRefCheck: zod_1.z
+        .boolean()
+        .optional()
+        .describe("site-residue: skip the inbound-ref pre-flight that protects active content from broken links. Faster but loses the safety net — pair with a separate `audit broken-links` run."),
+    // workflow-advance
+    commandName: zod_1.z
+        .string()
+        .optional()
+        .describe("workflow-advance: workflow command to execute (case-insensitive, e.g. 'Submit', 'Approve'). Required for workflow-advance."),
+    comments: zod_1.z
+        .string()
+        .optional()
+        .describe("workflow-advance: comment recorded with the workflow execution (audit trail)."),
+    staleDays: zod_1.z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe("workflow-advance: items not updated for this many days are eligible. Default 30."),
+    maxAdvances: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("workflow-advance: cap on items advanced per run. Default 100."),
+    fromState: zod_1.z
+        .string()
+        .optional()
+        .describe("workflow-advance: restrict to items currently in this workflow state (e.g. 'Draft')."),
+    // workflow-apply
+    //
+    // Note: `staleDays` (above) is shared with workflow-apply where it
+    // means "only attach to items not updated for N days" (optional;
+    // omit to attach to every match). Other workflow-advance fields
+    // are not reused — workflow-apply does not need `commandName`,
+    // `comments`, `maxAdvances`, or `fromState`.
+    workflow: zod_1.z
+        .string()
+        .optional()
+        .describe("workflow-apply: workflow GUID, content-tree path, or display/item name (case-insensitive). Required for workflow-apply."),
+    state: zod_1.z
+        .string()
+        .optional()
+        .describe("workflow-apply: target state (GUID or state name). Defaults to the workflow's __Initial state."),
+    template: zod_1.z
+        .string()
+        .optional()
+        .describe("workflow-apply: only attach to items conforming to this template (GUID or absolute /sitecore/templates path). Omit to attach to every item under `root`."),
+    reattach: zod_1.z
+        .boolean()
+        .optional()
+        .describe("workflow-apply: overwrite items already attached to a different workflow. Off by default — already-attached items are skipped so the verb defaults to a safe backfill."),
+    maxApplies: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .max(10000)
+        .optional()
+        .describe("workflow-apply: cap on items attached per run. Default 100."),
+    // field-set
+    field: zod_1.z
+        .string()
+        .optional()
+        .describe("field-set: name of the single field to write (case-insensitive, resolved against the item's template). Required for field-set."),
+    value: zod_1.z
+        .string()
+        .optional()
+        .describe("field-set: value to write. mode='replace' writes verbatim; mode='add'/'remove' parse it as a comma- or pipe-separated GUID list. Ignored for mode='clear'."),
+    mode: zod_1.z
+        .enum(["replace", "add", "remove", "clear"])
+        .optional()
+        .describe("field-set: how to combine `value` with the existing field state. `replace` (default) overwrites; `add` unions GUIDs into a pipe-delimited list (this is the answer to bulk tag-add); `remove` subtracts GUIDs; `clear` wipes the field. add/remove reject fields whose existing value isn't a pipe-delimited GUID list to prevent corrupting text fields."),
+    templatePattern: zod_1.z
+        .string()
+        .optional()
+        .describe("field-set / rename / language-versions-add: restrict to items whose templateName matches this regex. Strongly recommended — without it the verb operates on every item in --root."),
+    whereCurrentMatches: zod_1.z
+        .string()
+        .optional()
+        .describe("field-set: only update items whose current value of `field` matches this regex (e.g. '^$' for empty-only). Enables idempotent fill-the-blank workflows."),
+    maxMutations: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .max(50000)
+        .optional()
+        .describe("field-set: cap on items mutated per run. Default 100."),
+    // language-versions-add
+    languages: zod_1.z
+        .array(zod_1.z.string())
+        .optional()
+        .describe("language-versions-add: language codes to create versions in (required)."),
+    // rename (pattern / replacement / flags / literal / ignoreCase are declared above under find-replace)
+    maxRenames: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .max(10000)
+        .optional()
+        .describe("rename: cap on items renamed per run. Default 100."),
+    // language-versions-add
+    fromLanguage: zod_1.z
+        .string()
+        .optional()
+        .describe("language-versions-add: source language to copy fields from. Default: seed the new version empty."),
+    maxAdds: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .max(50000)
+        .optional()
+        .describe("language-versions-add: cap on (item, language) versions created per run. Default 500."),
+});

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

@@ -0,0 +1,19 @@
+/**
+ * Deploy domain — workflow-shaped tools over scai's Deploy API surface.
+ *
+ * The library exports ~40 fetch/mutate primitives in `@/deploy/api`.
+ * Here, those primitives are recomposed into ~9 task-shaped tools that
+ * match how an agent actually reasons about an XM Cloud tenant:
+ *
+ *   - `*_inspect` tools fan out to read multiple resources in one call
+ *     and return a coherent "snapshot" structure.
+ *   - `*_manage` / `*_lifecycle` tools take a discriminated `action`
+ *     input and route to the right write primitive. The dispatcher's
+ *     allowWrite gate runs before any side-effecting library call.
+ *
+ * Never expose secret-returning library calls (edge token, editing
+ * secret, source-control access tokens). Auth flows are server-side
+ * only; agents reason about the bound env via deploy_environment_inspect.
+ */
+import type { McpRegistry } from "../registry";
+export declare const registerDeployTools: (registry: McpRegistry) => void;