@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/mcp/tools/audit.js

@@ -0,0 +1,584 @@
+"use strict";
+/**
+ * Audit domain — inspect, baseline, suite.
+ *
+ * Three read-side tools cover the full hygiene-reporting surface:
+ *
+ *   - `audit_inspect` — discriminated `{ verb }` entry that lists
+ *     available audits, runs one (or `all`) in-process, captures a
+ *     history snapshot, lists captured snapshots, or diffs two
+ *     snapshots. The single tool replaces five CLI verbs so agents
+ *     don't need to memorize a half-dozen names; the verb discriminator
+ *     keeps each call's inputs scoped.
+ *
+ *   - `audit_baseline` — discriminated `{ verb }` entry for the per-env
+ *     baseline file at `.scai/audit-baseline-<envName>.json`. Show is
+ *     free; `update`, `remove`, and `reset` mutate the local baseline
+ *     file (not the tenant), and are write-gated so the host's
+ *     confirmation UX kicks in before any baseline change.
+ *
+ *   - `audit_suite_run` — load + execute a YAML suite file. Read-side
+ *     by definition (suites themselves can't mutate the tenant), but
+ *     can resolve `baseline=true` if the suite says so.
+ *
+ * Every audit run delegates to the CLI-shared `runAudit*` task; this
+ * MCP layer only forwards routing + the structured-content envelope.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAuditTools = exports.SINGLE_AUDIT_RUNNERS = void 0;
+const zod_1 = require("zod");
+const all_1 = require("../../hygiene/tasks/audit/all");
+const alt_text_missing_1 = require("../../hygiene/tasks/audit/alt-text-missing");
+const broken_images_1 = require("../../hygiene/tasks/audit/broken-images");
+const broken_links_1 = require("../../hygiene/tasks/audit/broken-links");
+const datasource_missing_1 = require("../../hygiene/tasks/audit/datasource-missing");
+const dead_templates_1 = require("../../hygiene/tasks/audit/dead-templates");
+const duplicates_1 = require("../../hygiene/tasks/audit/duplicates");
+const empty_items_1 = require("../../hygiene/tasks/audit/empty-items");
+const empty_links_1 = require("../../hygiene/tasks/audit/empty-links");
+const empty_roles_1 = require("../../hygiene/tasks/audit/empty-roles");
+const fallback_drift_1 = require("../../hygiene/tasks/audit/fallback-drift");
+const find_replace_1 = require("../../hygiene/tasks/audit/find-replace");
+const heavy_templates_1 = require("../../hygiene/tasks/audit/heavy-templates");
+const language_data_1 = require("../../hygiene/tasks/audit/language-data");
+const large_fields_1 = require("../../hygiene/tasks/audit/large-fields");
+const missing_meta_1 = require("../../hygiene/tasks/audit/missing-meta");
+const orphans_1 = require("../../hygiene/tasks/audit/orphans");
+const page_design_orphans_1 = require("../../hygiene/tasks/audit/page-design-orphans");
+const personalization_broken_1 = require("../../hygiene/tasks/audit/personalization-broken");
+const references_1 = require("../../hygiene/tasks/audit/references");
+const role_bloat_1 = require("../../hygiene/tasks/audit/role-bloat");
+const site_residue_1 = require("../../hygiene/tasks/audit/site-residue");
+const slug_conflicts_1 = require("../../hygiene/tasks/audit/slug-conflicts");
+const stale_content_1 = require("../../hygiene/tasks/audit/stale-content");
+const stale_users_1 = require("../../hygiene/tasks/audit/stale-users");
+const stale_workflow_1 = require("../../hygiene/tasks/audit/stale-workflow");
+const template_dependencies_1 = require("../../hygiene/tasks/audit/template-dependencies");
+const suite_run_1 = require("../../hygiene/tasks/audit/suite-run");
+const translation_coverage_1 = require("../../hygiene/tasks/audit/translation-coverage");
+const unused_media_1 = require("../../hygiene/tasks/audit/unused-media");
+const baseline_1 = require("../../hygiene/tasks/audit/baseline");
+const history_1 = require("../../hygiene/tasks/audit/history");
+const errors_1 = require("../../shared/errors");
+const descriptions_1 = require("../descriptions");
+const common_1 = require("../schemas/common");
+/**
+ * Convert a typed runner into a loose-typed one for the dispatch table.
+ * The inner cast is the same unsafe move that `as never` used to make,
+ * but it's localized to one helper *and* it requires the caller to
+ * supply a function whose return type is `Promise<readonly X[]>` — so
+ * if a runner ever stops returning a flat array (the way
+ * `runCleanupDeadTemplates` does — see cleanup.ts for the workaround),
+ * the call to `loosen` fails type-check and the bug surfaces here
+ * instead of in production.
+ */
+const loosen = (fn) => fn;
+/**
+ * Routing table for `audit_inspect` verb=run. The list mirrors
+ * `AUDIT_REGISTRY` in `src/hygiene/tasks/audit/all.ts` — the
+ * `cli-mcp-parity.test.ts` routing-table test asserts the two stay in
+ * lockstep, so it is exported for that test.
+ */
+exports.SINGLE_AUDIT_RUNNERS = {
+    "alt-text-missing": loosen(alt_text_missing_1.runAuditAltTextMissing),
+    "broken-images": loosen(broken_images_1.runAuditBrokenImages),
+    "broken-links": loosen(broken_links_1.runAuditBrokenLinks),
+    "datasource-missing": loosen(datasource_missing_1.runAuditDatasourceMissing),
+    "dead-templates": loosen(dead_templates_1.runAuditDeadTemplates),
+    duplicates: loosen(duplicates_1.runAuditDuplicates),
+    "empty-items": loosen(empty_items_1.runAuditEmptyItems),
+    "empty-links": loosen(empty_links_1.runAuditEmptyLinks),
+    "empty-roles": loosen(empty_roles_1.runAuditEmptyRoles),
+    "fallback-drift": loosen(fallback_drift_1.runAuditFallbackDrift),
+    "find-replace": loosen(find_replace_1.runAuditFindReplace),
+    "heavy-templates": loosen(heavy_templates_1.runAuditHeavyTemplates),
+    "language-data": loosen(language_data_1.runAuditLanguageData),
+    "large-fields": loosen(large_fields_1.runAuditLargeFields),
+    "missing-meta": loosen(missing_meta_1.runAuditMissingMeta),
+    orphans: loosen(orphans_1.runAuditOrphans),
+    "page-design-orphans": loosen(page_design_orphans_1.runAuditPageDesignOrphans),
+    "personalization-broken": loosen(personalization_broken_1.runAuditPersonalizationBroken),
+    references: loosen(references_1.runAuditReferences),
+    "role-bloat": loosen(role_bloat_1.runAuditRoleBloat),
+    "site-residue": loosen(site_residue_1.runAuditSiteResidue),
+    "slug-conflicts": loosen(slug_conflicts_1.runAuditSlugConflicts),
+    "stale-content": loosen(stale_content_1.runAuditStaleContent),
+    "stale-users": loosen(stale_users_1.runAuditStaleUsers),
+    "stale-workflow": loosen(stale_workflow_1.runAuditStaleWorkflow),
+    "template-dependencies": loosen(template_dependencies_1.runAuditTemplateDependencies),
+    "translation-coverage": loosen(translation_coverage_1.runAuditTranslationCoverage),
+    "unused-media": loosen(unused_media_1.runAuditUnusedMedia),
+};
+const baseTaskOptions = (config, envName, overrides = {}) => ({
+    config,
+    environmentName: envName,
+    quiet: true,
+    json: true,
+    ...overrides,
+});
+const registerAuditTools = (registry) => {
+    registry.registerTool({
+        name: "audit_inspect",
+        description: descriptions_1.TOOL_DESCRIPTIONS.audit_inspect,
+        auth: "read",
+        annotations: {
+            title: "Inspect, run, and diff content hygiene audits",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            verb: zod_1.z
+                .enum(["list", "run", "history-capture", "history-list", "history-diff"])
+                .describe("Which read-side audit operation to run. `list` returns the registry of available audit names. `run` executes one audit (`audit: 'broken-links'`) or every audit (`audit: 'all'`). `history-capture` runs `all` and persists the result to `.scai/audit-history/<env>/<datetime>.json`. `history-list` returns the snapshots already on disk. `history-diff` compares two snapshots by fingerprint and returns per-audit added/removed counts."),
+            audit: zod_1.z
+                .string()
+                .optional()
+                .describe("Audit name for `run` — one of the names returned by `verb='list'`, or the literal 'all' for the consolidated run. Ignored for other verbs."),
+            // Cross-cutting filters honored by every audit runner.
+            root: zod_1.z
+                .string()
+                .optional()
+                .describe("Content-tree root to scope the audit to. Default `/sitecore/content`."),
+            limit: zod_1.z
+                .number()
+                .int()
+                .positive()
+                .max(50000)
+                .optional()
+                .describe("Maximum number of items to scan for a single audit. Default per-audit."),
+            includeSystem: zod_1.z
+                .boolean()
+                .optional()
+                .describe("Include items under /sitecore/system and /sitecore/templates. Off by default — most audits restrict to content."),
+            exclude: zod_1.z
+                .array(zod_1.z.string())
+                .optional()
+                .describe("Glob patterns of paths to exclude from the scan."),
+            since: zod_1.z
+                .string()
+                .optional()
+                .describe("ISO-8601 datetime — restrict to items updated since this instant."),
+            owner: zod_1.z.string().optional().describe("Filter to items last-updated by this user."),
+            baseline: zod_1.z
+                .boolean()
+                .optional()
+                .describe("When true, filter findings through the per-env baseline file. Findings whose fingerprint appears in the baseline are returned in `ignored` rather than `findings`."),
+            // history-diff inputs
+            from: zod_1.z
+                .string()
+                .optional()
+                .describe("Snapshot file path to diff FROM (verb='history-diff'). Defaults to the second-most-recent snapshot."),
+            to: zod_1.z
+                .string()
+                .optional()
+                .describe("Snapshot file path to diff TO (verb='history-diff'). Defaults to the most recent snapshot."),
+            // Per-audit options that show up often enough to surface here. The
+            // long tail (per-audit specifics like `targetLanguages`, `pattern`,
+            // `requiredFields`) is passed through `auditOptions` so we don't
+            // explode the top-level schema with every leaf flag.
+            auditOptions: zod_1.z
+                .record(zod_1.z.string(), zod_1.z.unknown())
+                .optional()
+                .describe("Per-audit option bag. Forwarded verbatim to the runner. Use this for audit-specific flags — e.g. `{ requiredFields: ['title','description'] }` for missing-meta, `{ pattern: 'foo' }` for find-replace, or `{ targetLanguages: ['en','fr'] }` for translation-coverage. Stays opt-in so common runs don't need it."),
+            ...common_1.environmentBindingShape,
+        },
+        handler: async (input, context) => {
+            const envName = input.environmentName ?? context.envName;
+            switch (input.verb) {
+                case "list": {
+                    const names = (0, all_1.auditNames)();
+                    return {
+                        content: [{ type: "text", text: `${names.length} audit(s) registered.` }],
+                        structuredContent: { verb: input.verb, audits: names },
+                    };
+                }
+                case "run": {
+                    if (!input.audit) {
+                        throw (0, errors_1.createScaiError)("verb='run' requires `audit`. Use `audit: 'all'` for the consolidated run, or one of the names from verb='list'.", "INPUT_INVALID");
+                    }
+                    // `site-residue` is the lone audit whose `root` is `string[]`
+                    // (extra SXA Project roots) instead of a content-tree string.
+                    // Forwarding the top-level `root` (string) here would corrupt
+                    // the array spread. Callers extend the SXA defaults via
+                    // `auditOptions: { root: [...] }`.
+                    const forwardRoot = input.audit !== "site-residue";
+                    const shared = baseTaskOptions(context.configPath, envName, {
+                        ...(forwardRoot && input.root !== undefined && { root: input.root }),
+                        ...(input.limit !== undefined && { limit: input.limit }),
+                        ...(input.includeSystem !== undefined && { includeSystem: input.includeSystem }),
+                        ...(input.exclude !== undefined && { exclude: input.exclude }),
+                        ...(input.since !== undefined && { since: input.since }),
+                        ...(input.owner !== undefined && { owner: input.owner }),
+                        ...(input.baseline !== undefined && { baseline: input.baseline }),
+                        ...(input.auditOptions ?? {}),
+                    });
+                    if (input.audit === "all") {
+                        // runAuditAll prints + writes; it doesn't return the
+                        // envelope. Pipe through a tmpfile so the MCP client gets
+                        // structured output (matches the pattern in audit-history).
+                        const fs = await Promise.resolve().then(() => __importStar(require("node:fs")));
+                        const os = await Promise.resolve().then(() => __importStar(require("node:os")));
+                        const path = await Promise.resolve().then(() => __importStar(require("node:path")));
+                        const tmpFile = path.join(os.tmpdir(), `scai-audit-all-mcp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.json`);
+                        await (0, all_1.runAuditAll)({
+                            ...shared,
+                            output: tmpFile,
+                            format: "json",
+                        });
+                        let envelope;
+                        try {
+                            envelope = JSON.parse(fs.readFileSync(tmpFile, "utf8"));
+                        }
+                        finally {
+                            try {
+                                fs.unlinkSync(tmpFile);
+                            }
+                            catch {
+                                /* ignore */
+                            }
+                        }
+                        const count = envelope.counts
+                            ?.totalFindings;
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `audit all: ${count ?? "?"} finding(s) across ${Object.keys(envelope.audits ?? {}).length} audit(s).`,
+                                },
+                            ],
+                            structuredContent: { verb: input.verb, audit: "all", envelope },
+                        };
+                    }
+                    const runner = exports.SINGLE_AUDIT_RUNNERS[input.audit];
+                    if (!runner) {
+                        throw (0, errors_1.createScaiError)(`Unknown audit '${input.audit}'. Run verb='list' to see registered audits.`, "INPUT_INVALID");
+                    }
+                    const findings = await runner(shared);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `audit ${input.audit}: ${findings.length} finding(s).`,
+                            },
+                        ],
+                        structuredContent: {
+                            verb: input.verb,
+                            audit: input.audit,
+                            count: findings.length,
+                            findings,
+                        },
+                    };
+                }
+                case "history-capture": {
+                    await (0, history_1.runHistoryCapture)(baseTaskOptions(context.configPath, envName, {
+                        ...(input.root !== undefined && { root: input.root }),
+                        ...(input.limit !== undefined && { limit: input.limit }),
+                        ...(input.includeSystem !== undefined && { includeSystem: input.includeSystem }),
+                        ...(input.exclude !== undefined && { exclude: input.exclude }),
+                        ...(input.since !== undefined && { since: input.since }),
+                    }));
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: "Captured audit history snapshot.",
+                            },
+                        ],
+                        structuredContent: { verb: input.verb, captured: true },
+                    };
+                }
+                case "history-list": {
+                    // runHistoryList prints; reconstruct by reading directly.
+                    // Re-use the same module so we don't duplicate the path layout.
+                    const { listHistory } = await Promise.resolve().then(() => __importStar(require("../../hygiene/history")));
+                    const path = await Promise.resolve().then(() => __importStar(require("node:path")));
+                    const configDir = context.configPath?.endsWith(".json")
+                        ? path.dirname(context.configPath)
+                        : (context.configPath ?? process.cwd());
+                    const snapshots = listHistory({ envName, configDir });
+                    // Invoke the task runner too, so the logger trail mirrors the CLI
+                    // (no-op when quiet=true; included for parity with other tools).
+                    await (0, history_1.runHistoryList)(baseTaskOptions(context.configPath, envName));
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `${snapshots.length} snapshot(s) on disk.`,
+                            },
+                        ],
+                        structuredContent: {
+                            verb: input.verb,
+                            count: snapshots.length,
+                            snapshots,
+                        },
+                    };
+                }
+                case "history-diff": {
+                    // runHistoryDiff prints; we need the structured diff too.
+                    // Re-implement against the same primitives.
+                    const { listHistory, loadSnapshot, diffSnapshots } = await Promise.resolve().then(() => __importStar(require("../../hygiene/history")));
+                    const path = await Promise.resolve().then(() => __importStar(require("node:path")));
+                    const configDir = context.configPath?.endsWith(".json")
+                        ? path.dirname(context.configPath)
+                        : (context.configPath ?? process.cwd());
+                    const snapshots = listHistory({ envName, configDir });
+                    if (snapshots.length < 2 && (!input.from || !input.to)) {
+                        throw (0, errors_1.createScaiError)(`Need at least 2 snapshots to diff (have ${snapshots.length}).`, "INPUT_INVALID");
+                    }
+                    const toPath = input.to ?? snapshots[0].filePath;
+                    const fromPath = input.from ?? snapshots[1].filePath;
+                    const diff = diffSnapshots(loadSnapshot(fromPath), loadSnapshot(toPath));
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Diff: +${diff.totals.added} added, -${diff.totals.removed} removed (net ${diff.totals.net >= 0 ? "+" : ""}${diff.totals.net}).`,
+                            },
+                        ],
+                        structuredContent: {
+                            verb: input.verb,
+                            fromFile: fromPath,
+                            toFile: toPath,
+                            ...diff,
+                        },
+                    };
+                }
+            }
+        },
+    });
+    registry.registerTool({
+        name: "audit_baseline",
+        description: descriptions_1.TOOL_DESCRIPTIONS.audit_baseline,
+        auth: "write",
+        annotations: {
+            title: "Manage the per-env audit baseline file",
+            readOnlyHint: false,
+            // The baseline file is local, not tenant state. Still mark
+            // destructive so hosts surface confirmation before a reset / remove
+            // wipes an accepted-findings set the operator may want to keep.
+            destructiveHint: true,
+            openWorldHint: false,
+        },
+        inputSchema: {
+            verb: zod_1.z
+                .enum(["show", "update", "remove", "reset"])
+                .describe("Baseline operation. `show` is read-only and returns the per-audit fingerprint listing. `update` runs the selected audits and folds every current finding into the baseline (use after an operator review accepts the current state). `remove` deletes a single fingerprint from a named audit. `reset` clears every entry for one named audit (or every audit, if `audit` is omitted)."),
+            audit: zod_1.z
+                .string()
+                .optional()
+                .describe("Audit name. Required for `remove`. Optional for `reset` (defaults to all audits) and `update` (defaults to running every audit)."),
+            audits: zod_1.z
+                .array(zod_1.z.string())
+                .optional()
+                .describe("For `update`: list of audit names to run when refreshing the baseline. Defaults to every audit."),
+            fingerprint: zod_1.z
+                .string()
+                .optional()
+                .describe("For `remove`: the finding fingerprint to drop. Get this from `audit_baseline` verb='show'."),
+            resetFirst: zod_1.z
+                .boolean()
+                .optional()
+                .describe("For `update`: drop existing entries for the target audits before re-running, instead of merging. Default false (merge)."),
+            root: zod_1.z.string().optional().describe("Forwarded to the audit run when `verb='update'`."),
+            limit: zod_1.z
+                .number()
+                .int()
+                .positive()
+                .max(50000)
+                .optional()
+                .describe("Forwarded to the audit run when `verb='update'`."),
+            includeSystem: zod_1.z
+                .boolean()
+                .optional()
+                .describe("Forwarded to the audit run when `verb='update'`."),
+            ...common_1.environmentBindingShape,
+            ...common_1.allowWriteShape,
+        },
+        handler: async (input, context) => {
+            const envName = input.environmentName ?? context.envName;
+            const shared = baseTaskOptions(context.configPath, envName);
+            switch (input.verb) {
+                case "show": {
+                    // runBaselineShow prints; re-derive the structure for the
+                    // structuredContent envelope.
+                    const { openBaseline } = await Promise.resolve().then(() => __importStar(require("../../hygiene/baseline")));
+                    const path = await Promise.resolve().then(() => __importStar(require("node:path")));
+                    const configDir = context.configPath?.endsWith(".json")
+                        ? path.dirname(context.configPath)
+                        : (context.configPath ?? process.cwd());
+                    const baseline = openBaseline({
+                        envName,
+                        configDir,
+                        logger: undefined,
+                    });
+                    const snapshot = baseline.snapshot();
+                    const totalEntries = Object.values(snapshot.ignored).reduce((n, list) => n + list.length, 0);
+                    await (0, baseline_1.runBaselineShow)(shared);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Baseline ${baseline.filePath}: ${totalEntries} entr${totalEntries === 1 ? "y" : "ies"}.`,
+                            },
+                        ],
+                        structuredContent: {
+                            verb: input.verb,
+                            filePath: baseline.filePath,
+                            totalEntries,
+                            ignored: snapshot.ignored,
+                        },
+                    };
+                }
+                case "update": {
+                    await (0, baseline_1.runBaselineCreate)({
+                        ...shared,
+                        ...(input.audits !== undefined && { audits: input.audits }),
+                        ...(input.audit !== undefined && !input.audits && { audits: [input.audit] }),
+                        ...(input.resetFirst !== undefined && { reset: input.resetFirst }),
+                        ...(input.root !== undefined && { root: input.root }),
+                        ...(input.limit !== undefined && { limit: input.limit }),
+                        ...(input.includeSystem !== undefined && { includeSystem: input.includeSystem }),
+                    });
+                    return {
+                        content: [{ type: "text", text: "Baseline updated." }],
+                        structuredContent: { verb: input.verb, updated: true },
+                    };
+                }
+                case "remove": {
+                    if (!input.audit || !input.fingerprint) {
+                        throw (0, errors_1.createScaiError)("verb='remove' requires `audit` and `fingerprint`.", "INPUT_INVALID");
+                    }
+                    await (0, baseline_1.runBaselineRemove)({
+                        ...shared,
+                        audit: input.audit,
+                        fingerprint: input.fingerprint,
+                    });
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Removed ${input.audit}/${input.fingerprint} from baseline.`,
+                            },
+                        ],
+                        structuredContent: {
+                            verb: input.verb,
+                            audit: input.audit,
+                            fingerprint: input.fingerprint,
+                            removed: true,
+                        },
+                    };
+                }
+                case "reset": {
+                    await (0, baseline_1.runBaselineReset)({
+                        ...shared,
+                        ...(input.audit !== undefined && { audit: input.audit }),
+                    });
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: input.audit
+                                    ? `Reset baseline entries for ${input.audit}.`
+                                    : "Reset every baseline entry.",
+                            },
+                        ],
+                        structuredContent: {
+                            verb: input.verb,
+                            audit: input.audit ?? null,
+                            reset: true,
+                        },
+                    };
+                }
+            }
+        },
+    });
+    registry.registerTool({
+        name: "audit_suite_run",
+        description: descriptions_1.TOOL_DESCRIPTIONS.audit_suite_run,
+        auth: "read",
+        annotations: {
+            title: "Run a YAML-defined audit suite",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            file: zod_1.z
+                .string()
+                .describe("Path to the suite YAML file. Resolved relative to the MCP server's working directory."),
+            baseline: zod_1.z.boolean().optional().describe("Override the suite's `baseline.enabled` setting."),
+            output: zod_1.z
+                .string()
+                .optional()
+                .describe("Override the suite's `output.path`. Supports {date}, {datetime}, {env}, {suite} tokens."),
+            format: zod_1.z
+                .enum(["json", "csv", "markdown"])
+                .optional()
+                .describe("Override the suite's `output.format`."),
+            only: zod_1.z
+                .array(zod_1.z.string())
+                .optional()
+                .describe("Run only this subset of the suite's audits. Useful for re-running after a targeted fix."),
+            ...common_1.environmentBindingShape,
+        },
+        handler: async (input, context) => {
+            await (0, suite_run_1.runAuditSuiteRun)({
+                ...baseTaskOptions(context.configPath, input.environmentName ?? context.envName),
+                file: input.file,
+                ...(input.baseline !== undefined && { baseline: input.baseline }),
+                ...(input.output !== undefined && { output: input.output }),
+                ...(input.format !== undefined && { format: input.format }),
+                ...(input.only !== undefined && { only: input.only }),
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Suite '${input.file}' executed${input.output ? ` → ${input.output}` : ""}.`,
+                    },
+                ],
+                structuredContent: {
+                    verb: "run",
+                    file: input.file,
+                    executed: true,
+                    output: input.output ?? null,
+                },
+            };
+        },
+    });
+};
+exports.registerAuditTools = registerAuditTools;

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

@@ -0,0 +1,8 @@
+/**
+ * Bootstrap tools — `scai_overview` is the first call an agent makes
+ * from a cold start; `environment_status` is the live-pulse probe.
+ *
+ * Both are read-only and never gate on `allowWrite`.
+ */
+import type { McpRegistry } from "../registry";
+export declare const registerBootstrapTools: (registry: McpRegistry) => void;