@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/hygiene/tasks/cleanup/workflow-apply.js

@@ -0,0 +1,310 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCleanupWorkflowApply = void 0;
+const cli_tasks_1 = require("../../../shared/cli-tasks");
+const environment_1 = require("../../../policy/environment");
+const errors_1 = require("../../../shared/errors");
+const client_1 = require("../../../workflow/api/client");
+const shared_1 = require("../../../workflow/tasks/shared");
+const shared_2 = require("../shared");
+/**
+ * Bulk-attach a workflow to items under `--root`, writing `__Workflow`
+ * and `__Workflow state` directly via `setItemWorkflowState`. Bypasses
+ * the workflow engine: submit/validation actions on the target state
+ * do NOT fire — this is a raw field write, the same one used by
+ * `scai content workflow apply <item>` for the single-item case.
+ *
+ * Strategy:
+ *   1. Resolve `--workflow` to a `WorkflowDefinitionDetail`. Resolve
+ *      `--state` (or fall back to the workflow's `__Initial state`).
+ *   2. Optionally resolve `--template` (path → GUID via search) for
+ *      the `_template` filter clause.
+ *   3. Enumerate items under `--root` via the search index, applying
+ *      template / system / staleness filters in-stream.
+ *   4. For each candidate, fetch its `ItemWorkflow`. If already
+ *      attached to the target workflow + state, skip (idempotent). If
+ *      attached to any workflow and `--reattach` is false, skip with
+ *      `skipped-already-attached`. Otherwise call
+ *      `setItemWorkflowState({ workflowId, stateId })`.
+ *
+ * Safety:
+ *   - `--max-applies` caps the blast radius (default 100).
+ *   - `--what-if` reports the plan without mutating.
+ *   - `--allow-write` (or `allowWrite` opt) required outside `--what-if`.
+ *   - `--reattach` defaults off so the verb is safe to run against
+ *     mixed content — items already on a workflow stay put.
+ */
+const runCleanupWorkflowApply = async (options) => {
+    const logger = (0, shared_2.toLogger)(options);
+    if (!options.workflow) {
+        throw (0, errors_1.createScaiError)("--workflow is required.", "INPUT_INVALID");
+    }
+    const { envName, root: rootConfig, client } = (0, shared_2.resolveTenant)(options);
+    if (!options.whatIf) {
+        (0, shared_2.ensureAllowWriteForCleanup)(rootConfig, envName, options.allowWrite);
+    }
+    else if (!logger.isJson()) {
+        logger.info("What-if mode active — no workflow attachments will be written.", "yellow");
+    }
+    // Build a workflow API client off the same resolved environment as the
+    // hygiene client so both share the request timeout config.
+    const { environment, timeoutMs } = (0, environment_1.resolveEnvironment)(options);
+    const workflowClient = (0, client_1.createWorkflowApiClient)({
+        environment,
+        request: { timeoutMs },
+    });
+    // Phase 0: resolve workflow + target state.
+    const workflowDetail = await (0, shared_1.resolveWorkflowRef)(workflowClient, options.workflow);
+    if (!workflowDetail) {
+        throw (0, errors_1.createScaiError)(`Workflow '${options.workflow}' did not resolve to a Workflow-templated item.`, "INPUT_INVALID", {
+            hint: "Pass a workflow GUID, content-tree path under /sitecore/system/Workflows, or the workflow's display/item name (case-insensitive).",
+        });
+    }
+    const { stateId: targetStateId, stateName: targetStateName } = await resolveTargetState(workflowClient, workflowDetail, options.state);
+    // Phase 1: optional template filter — resolve path → GUID once.
+    const root = options.root ?? "/sitecore/content";
+    let templateId = null;
+    if (options.template) {
+        templateId = await resolveTemplateRef(client, options.template, options.index);
+        if (!templateId) {
+            throw (0, errors_1.createScaiError)(`--template '${options.template}' did not resolve to a template item.`, "INPUT_INVALID", {
+                hint: "Pass a Sitecore template GUID or an absolute content-tree path under /sitecore/templates.",
+            });
+        }
+    }
+    const knobs = (0, shared_2.resolveHygieneKnobs)(options);
+    const concurrency = options.concurrency ?? knobs.concurrency;
+    const maxApplies = options.maxApplies ?? 100;
+    const includeSystem = Boolean(options.includeSystem);
+    const staleDays = options.staleDays;
+    const cutoff = staleDays !== undefined && staleDays > 0 ? Date.now() - staleDays * 24 * 60 * 60 * 1000 : null;
+    // Phase 2: resolve root → itemId for the `_path` filter.
+    const rootSearch = await client.search({
+        index: options.index,
+        paging: { pageSize: 1 },
+        searchStatement: {
+            criteria: { field: "_fullpath", value: root.toLowerCase(), criteriaType: "EXACT" },
+        },
+    });
+    const rootItemId = rootSearch.results[0]?.itemId;
+    // Phase 3: enumerate candidates with the strongest filter we can push
+    // into the search index — `_path` contains rootItemId AND (optionally)
+    // `_template` matches the resolved templateId. The staleness / system
+    // path filters run in-stream because the search field grammar doesn't
+    // expose them uniformly across tenants.
+    const searchStatement = buildCandidateStatement(rootItemId, templateId);
+    const candidates = [];
+    let scanned = 0;
+    for await (const r of client.searchAll({
+        index: options.index,
+        latestVersionOnly: true,
+        ...(searchStatement ? { searchStatement } : {}),
+    }, 100, knobs.pageParallelism)) {
+        if (!includeSystem && (0, shared_2.isSystemPath)(r.path))
+            continue;
+        scanned += 1;
+        if (cutoff !== null) {
+            if (!r.updatedDate)
+                continue;
+            const t = Date.parse(r.updatedDate);
+            if (!Number.isFinite(t) || t >= cutoff)
+                continue;
+        }
+        candidates.push({
+            itemId: (0, shared_2.normalizeItemId)(r.itemId),
+            path: r.path,
+            templateId: r.templateId ?? null,
+        });
+        if (candidates.length >= (options.limit ?? 5000))
+            break;
+    }
+    logger.verbose(`Scanned ${scanned} items; ${candidates.length} candidates.`);
+    // Phase 4: per-candidate idempotency check + write.
+    const targetWorkflowGuid = (0, shared_2.normalizeItemId)(workflowDetail.itemId);
+    const targetStateGuid = (0, shared_2.normalizeItemId)(targetStateId);
+    const actions = (await (0, cli_tasks_1.mapWithConcurrency)(candidates, async (c, idx) => {
+        if (idx >= maxApplies)
+            return null;
+        const existingWf = await workflowClient.getItemWorkflow({ itemId: c.itemId });
+        const existingWorkflowGuid = existingWf?.workflowId
+            ? (0, shared_2.normalizeItemId)(existingWf.workflowId)
+            : null;
+        const existingStateGuid = existingWf?.stateId ? (0, shared_2.normalizeItemId)(existingWf.stateId) : null;
+        // Already on the target workflow + state — idempotent skip.
+        if (existingWorkflowGuid === targetWorkflowGuid && existingStateGuid === targetStateGuid) {
+            return {
+                itemId: c.itemId,
+                path: c.path,
+                templateId: c.templateId,
+                workflowItemId: workflowDetail.itemId,
+                workflowName: workflowDetail.displayName ?? workflowDetail.name,
+                stateItemId: targetStateId,
+                stateName: targetStateName,
+                status: "skipped-already-attached",
+                existingWorkflowId: existingWorkflowGuid,
+                existingStateId: existingStateGuid,
+            };
+        }
+        // Attached to a different workflow and we're not reattaching.
+        if (existingWorkflowGuid &&
+            existingWorkflowGuid !== targetWorkflowGuid &&
+            !options.reattach) {
+            return {
+                itemId: c.itemId,
+                path: c.path,
+                templateId: c.templateId,
+                workflowItemId: workflowDetail.itemId,
+                workflowName: workflowDetail.displayName ?? workflowDetail.name,
+                stateItemId: targetStateId,
+                stateName: targetStateName,
+                status: "skipped-already-attached",
+                existingWorkflowId: existingWorkflowGuid,
+                existingStateId: existingStateGuid,
+            };
+        }
+        if (options.whatIf) {
+            return {
+                itemId: c.itemId,
+                path: c.path,
+                templateId: c.templateId,
+                workflowItemId: workflowDetail.itemId,
+                workflowName: workflowDetail.displayName ?? workflowDetail.name,
+                stateItemId: targetStateId,
+                stateName: targetStateName,
+                status: "what-if",
+                existingWorkflowId: existingWorkflowGuid,
+                existingStateId: existingStateGuid,
+            };
+        }
+        try {
+            await workflowClient.setItemWorkflowState({
+                itemId: (0, shared_2.dashifyItemId)(c.itemId),
+                workflowId: workflowDetail.itemId,
+                stateId: targetStateId,
+            });
+            return {
+                itemId: c.itemId,
+                path: c.path,
+                templateId: c.templateId,
+                workflowItemId: workflowDetail.itemId,
+                workflowName: workflowDetail.displayName ?? workflowDetail.name,
+                stateItemId: targetStateId,
+                stateName: targetStateName,
+                status: "applied",
+                existingWorkflowId: existingWorkflowGuid,
+                existingStateId: existingStateGuid,
+            };
+        }
+        catch (error) {
+            return {
+                itemId: c.itemId,
+                path: c.path,
+                templateId: c.templateId,
+                workflowItemId: workflowDetail.itemId,
+                workflowName: workflowDetail.displayName ?? workflowDetail.name,
+                stateItemId: targetStateId,
+                stateName: targetStateName,
+                status: "failed",
+                existingWorkflowId: existingWorkflowGuid,
+                existingStateId: existingStateGuid,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }, concurrency)).filter((a) => a !== null);
+    const applied = actions.filter((a) => a.status === "applied").length;
+    const failed = actions.filter((a) => a.status === "failed").length;
+    const skippedAttached = actions.filter((a) => a.status === "skipped-already-attached").length;
+    const summary = options.whatIf
+        ? `Plan: would attach ${actions.filter((a) => a.status === "what-if").length} item(s) to '${workflowDetail.displayName ?? workflowDetail.name}' at '${targetStateName}'.`
+        : `Attached ${applied}, ${failed} failed, ${skippedAttached} already attached.`;
+    (0, shared_2.printReport)({
+        logger,
+        command: "cleanup.workflow.apply",
+        envName,
+        results: actions,
+        summary,
+        formatLine: (a) => `${a.status === "what-if" ? "[would attach] " : a.status === "failed" ? "[failed] " : a.status === "skipped-already-attached" ? "[skipped] " : ""}${a.path} — ${a.workflowName}/${a.stateName}${a.error ? ` — ${a.error}` : ""}`,
+        extra: {
+            root,
+            workflow: workflowDetail.displayName ?? workflowDetail.name,
+            workflowItemId: workflowDetail.itemId,
+            state: targetStateName,
+            stateItemId: targetStateId,
+            template: options.template ?? null,
+            templateId,
+            reattach: Boolean(options.reattach),
+            staleDays: staleDays ?? null,
+            whatIf: Boolean(options.whatIf),
+            maxApplies,
+            scannedCount: scanned,
+            appliedCount: applied,
+            failedCount: failed,
+            skippedAlreadyAttachedCount: skippedAttached,
+        },
+        options,
+    });
+    return actions;
+};
+exports.runCleanupWorkflowApply = runCleanupWorkflowApply;
+const resolveTargetState = async (client, workflow, stateRef) => {
+    if (stateRef) {
+        const match = (0, shared_1.resolveWorkflowState)(workflow, stateRef);
+        if (!match) {
+            throw (0, errors_1.createScaiError)(`Workflow '${workflow.displayName ?? workflow.name}' has no state matching '${stateRef}'.`, "INPUT_INVALID", {
+                hint: `Available states: ${workflow.states.map((s) => s.displayName ?? s.name).join(", ")}.`,
+            });
+        }
+        return { stateId: match.itemId, stateName: match.name };
+    }
+    const initialStateId = await client.getWorkflowInitialStateId(workflow.itemId);
+    if (!initialStateId) {
+        throw (0, errors_1.createScaiError)(`Workflow '${workflow.displayName ?? workflow.name}' has no __Initial state set.`, "UNKNOWN");
+    }
+    const initial = workflow.states.find((s) => (0, shared_2.normalizeItemId)(s.itemId) === (0, shared_2.normalizeItemId)(initialStateId));
+    return {
+        stateId: initialStateId,
+        stateName: initial?.displayName ?? initial?.name ?? "(initial)",
+    };
+};
+/**
+ * Resolve a template ref to its itemId. Accepts a GUID directly or an
+ * absolute content-tree path (looked up via the search index). Returns
+ * `null` when the path doesn't resolve.
+ */
+const resolveTemplateRef = async (client, ref, index) => {
+    const trimmed = ref.trim();
+    if (/^\{?[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}\}?$/i.test(trimmed)) {
+        return (0, shared_2.normalizeItemId)(trimmed);
+    }
+    if (!trimmed.startsWith("/sitecore/")) {
+        return null;
+    }
+    const r = await client.search({
+        index,
+        paging: { pageSize: 1 },
+        searchStatement: {
+            criteria: { field: "_fullpath", value: trimmed.toLowerCase(), criteriaType: "EXACT" },
+        },
+    });
+    return r.results[0]?.itemId ? (0, shared_2.normalizeItemId)(r.results[0].itemId) : null;
+};
+const buildCandidateStatement = (rootItemId, templateId) => {
+    const clauses = [];
+    if (rootItemId) {
+        clauses.push((0, shared_2.buildPathFilterStatement)(rootItemId));
+    }
+    if (templateId) {
+        clauses.push({
+            criteria: {
+                field: "_template",
+                value: (0, shared_2.normalizeItemId)(templateId),
+                criteriaType: "EXACT",
+            },
+        });
+    }
+    if (clauses.length === 0)
+        return undefined;
+    if (clauses.length === 1)
+        return clauses[0];
+    return { operator: "MUST", subStatements: clauses };
+};

package/dist/hygiene/tasks/explain/orphan-site.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `scai hygiene explain orphan-site <site>` — answer "what is left behind
+ * for this site, and is any of it still referenced?"
+ *
+ * After a Sites-API site delete (or a subtree-removal mistake), folders
+ * can survive under `/sitecore/templates/Project`, `/layout`, and the
+ * media library with no active site pointing at them. `audit
+ * site-residue` finds those orphan trees; but knowing an orphan is
+ * *unreferenced* is what makes it safe to purge. This verb composes the
+ * two:
+ *
+ *   - `audit site-residue` — orphan tenant/site trees (run silent).
+ *   - `audit references`   — inbound field references to each orphan
+ *                            (run silent, once per orphan tree).
+ *
+ * The report flags every orphan that still has inbound references —
+ * those need their referrers resolved before a
+ * `cleanup site-residue purge` is safe.
+ */
+import { type SiteResidueKind } from "../audit/site-residue";
+import { type HygieneCommonOptions } from "../shared";
+export interface ExplainOrphanSiteOptions extends HygieneCommonOptions {
+    /** Required. Site (or tenant) folder name to explain. */
+    site?: string;
+    /** Override the search index. */
+    index?: string;
+    /** Cap on inbound refs counted per orphan tree. */
+    limit?: number;
+    /**
+     * Suppress the printed report. The structured `ExplainOrphanSiteReport`
+     * is still returned — set by non-CLI callers (the MCP `explain` tool)
+     * that render the result themselves and must not write to stdout.
+     */
+    silent?: boolean;
+}
+export interface OrphanSiteEntry {
+    kind: SiteResidueKind;
+    path: string;
+    itemId: string;
+    /** Descendant items in the orphan tree. */
+    descendantCount: number;
+    /** Inbound field references to the orphan tree's root, from live content. */
+    inboundRefs: number;
+}
+export interface ExplainOrphanSiteReport {
+    site: string;
+    orphans: OrphanSiteEntry[];
+}
+/**
+ * Run `audit site-residue` for the named site, then `audit references`
+ * against each orphan tree's root, and print one merged report.
+ */
+export declare const runExplainOrphanSite: (options: ExplainOrphanSiteOptions) => Promise<ExplainOrphanSiteReport>;

package/dist/hygiene/tasks/explain/orphan-site.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * `scai hygiene explain orphan-site <site>` — answer "what is left behind
+ * for this site, and is any of it still referenced?"
+ *
+ * After a Sites-API site delete (or a subtree-removal mistake), folders
+ * can survive under `/sitecore/templates/Project`, `/layout`, and the
+ * media library with no active site pointing at them. `audit
+ * site-residue` finds those orphan trees; but knowing an orphan is
+ * *unreferenced* is what makes it safe to purge. This verb composes the
+ * two:
+ *
+ *   - `audit site-residue` — orphan tenant/site trees (run silent).
+ *   - `audit references`   — inbound field references to each orphan
+ *                            (run silent, once per orphan tree).
+ *
+ * The report flags every orphan that still has inbound references —
+ * those need their referrers resolved before a
+ * `cleanup site-residue purge` is safe.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runExplainOrphanSite = void 0;
+const errors_1 = require("../../../shared/errors");
+const site_residue_1 = require("../audit/site-residue");
+const references_1 = require("../audit/references");
+const shared_1 = require("../shared");
+const summarize = (site, orphans) => {
+    if (orphans.length === 0) {
+        return `No orphan residue found for site '${site}'.`;
+    }
+    const referenced = orphans.filter((o) => o.inboundRefs > 0).length;
+    const trees = `${orphans.length} orphan tree${orphans.length === 1 ? "" : "s"}`;
+    if (referenced === 0) {
+        return `Site '${site}': ${trees}, none still referenced — safe to \`cleanup site-residue purge\`.`;
+    }
+    return (`Site '${site}': ${trees}; ${referenced} still referenced by live content — ` +
+        `resolve those referrers before purging.`);
+};
+/**
+ * Run `audit site-residue` for the named site, then `audit references`
+ * against each orphan tree's root, and print one merged report.
+ */
+const runExplainOrphanSite = async (options) => {
+    if (!options.site) {
+        throw (0, errors_1.createScaiError)("explain orphan-site requires <site>.", "INPUT_INVALID");
+    }
+    const logger = (0, shared_1.toLogger)(options);
+    const { envName } = (0, shared_1.resolveTenant)(options);
+    const site = options.site;
+    const residue = await (0, site_residue_1.runAuditSiteResidue)({ ...options, silent: true });
+    // Match by site folder (orphan-site) or tenant folder (orphan-tenant).
+    const matched = residue.filter((r) => r.site === site || r.tenant === site);
+    const orphans = [];
+    for (const r of matched) {
+        const references = await (0, references_1.runAuditReferences)({ ...options, to: r.itemId, silent: true });
+        const inboundRefs = references.reduce((n, ref) => n + ref.matches.length, 0);
+        orphans.push({
+            kind: r.kind,
+            path: r.path,
+            itemId: r.itemId,
+            descendantCount: r.descendantCount,
+            inboundRefs,
+        });
+    }
+    // Referenced orphans first — those are the ones that need attention.
+    orphans.sort((a, b) => b.inboundRefs - a.inboundRefs || a.path.localeCompare(b.path));
+    const report = { site, orphans };
+    if (!options.silent) {
+        (0, shared_1.printReport)({
+            logger,
+            command: "explain.orphan-site",
+            envName,
+            results: orphans,
+            summary: summarize(site, orphans),
+            formatLine: (o) => `[${o.kind}] ${o.path} — ${o.descendantCount} item(s), ` +
+                `${o.inboundRefs} inbound ref(s)${o.inboundRefs > 0 ? " — still referenced" : ""}`,
+            extra: { site, orphanCount: orphans.length },
+            options,
+        });
+    }
+    return report;
+};
+exports.runExplainOrphanSite = runExplainOrphanSite;

package/dist/hygiene/tasks/explain/why-blocked.d.ts

@@ -0,0 +1,81 @@
+/**
+ * `scai hygiene explain why-blocked <itemId>` — answer the question "why
+ * won't this item delete?" with a structured, kind-sorted list of
+ * every inbound reference that would block (or potentially block) a
+ * Authoring-API delete.
+ *
+ * The Authoring API rejects delete requests with terse messages like
+ * "Template is used by at least one item" — enough to know something
+ * is wrong, not enough to know what. Operators (and agents) end up
+ * piecing together the picture by hand: run `audit references`, then
+ * `audit template-dependencies`, then cross-reference the field
+ * names. This verb does that composition once and returns a single
+ * report with each blocker labeled by reference kind.
+ *
+ * Combines two existing primitives:
+ *
+ *   - `audit references` (text walk of content fields)
+ *   - `audit template-dependencies` (search-index queries against the
+ *     five structural fields `_template` / `_basetemplates` /
+ *     `__masters` / `__source` / `datasource template`)
+ *
+ * Both are invoked with `silent: true` so this verb owns the printed
+ * report.
+ */
+import { type ReferenceKind } from "../reference-kind";
+import { type HygieneCommonOptions } from "../shared";
+export interface ExplainWhyBlockedOptions extends HygieneCommonOptions {
+    /** Required. ItemId to explain (any GUID form accepted). */
+    itemId?: string;
+    /** Content root for the field-value scan. Default `/sitecore/content`. */
+    root?: string;
+    /** Override the search index. */
+    index?: string;
+    /** Cap on inbound refs returned per check. Default 5000. */
+    limit?: number;
+    /**
+     * Skip the field-value content scan (the slow part). Use when you
+     * already know the target is a template and only structural refs
+     * matter — typically when triaging a template-delete failure.
+     */
+    skipContentScan?: boolean;
+    /**
+     * Skip the template-dependencies (search-index) check. Use when
+     * the target is a content item that isn't referenced as a template
+     * by anything — saves the five search-index round-trips. Most useful
+     * for triaging deletes of leaf content items, never for templates.
+     */
+    skipTemplateDeps?: boolean;
+    /** Pass through to the field-value scan when caching back-to-back invocations. */
+    cache?: boolean;
+    /**
+     * Suppress the printed report. The structured `ExplainWhyBlockedReport`
+     * is still returned — set by non-CLI callers (the MCP `explain` tool)
+     * that render the result themselves and must not write to stdout.
+     */
+    silent?: boolean;
+}
+export interface BlockerEntry {
+    referenceKind: ReferenceKind;
+    referrerItemId: string;
+    referrerPath: string | null;
+    /** Field name that holds the ref. Null for template-deps results that don't surface a field. */
+    fieldName: string | null;
+    /** Templating context — `null` when the referrer isn't a template. */
+    referrerTemplateName: string | null;
+    /** Source of the finding — useful when both scans surface the same referrer for different reasons. */
+    source: "audit-references" | "audit-template-dependencies";
+}
+export interface ExplainWhyBlockedReport {
+    /** Normalized 32-char itemId of the target. */
+    itemId: string;
+    blockers: BlockerEntry[];
+}
+/**
+ * Run both audits in parallel against `itemId`, merge the findings
+ * into a single sorted-by-kind blocker list, and print the canonical
+ * envelope. Used by `scai hygiene explain why-blocked <itemId>` and any
+ * automation that wants a single answer to "what's holding this
+ * delete back?"
+ */
+export declare const runExplainWhyBlocked: (options: ExplainWhyBlockedOptions) => Promise<ExplainWhyBlockedReport>;

package/dist/hygiene/tasks/explain/why-blocked.js

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * `scai hygiene explain why-blocked <itemId>` — answer the question "why
+ * won't this item delete?" with a structured, kind-sorted list of
+ * every inbound reference that would block (or potentially block) a
+ * Authoring-API delete.
+ *
+ * The Authoring API rejects delete requests with terse messages like
+ * "Template is used by at least one item" — enough to know something
+ * is wrong, not enough to know what. Operators (and agents) end up
+ * piecing together the picture by hand: run `audit references`, then
+ * `audit template-dependencies`, then cross-reference the field
+ * names. This verb does that composition once and returns a single
+ * report with each blocker labeled by reference kind.
+ *
+ * Combines two existing primitives:
+ *
+ *   - `audit references` (text walk of content fields)
+ *   - `audit template-dependencies` (search-index queries against the
+ *     five structural fields `_template` / `_basetemplates` /
+ *     `__masters` / `__source` / `datasource template`)
+ *
+ * Both are invoked with `silent: true` so this verb owns the printed
+ * report.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runExplainWhyBlocked = void 0;
+const errors_1 = require("../../../shared/errors");
+const references_1 = require("../audit/references");
+const template_dependencies_1 = require("../audit/template-dependencies");
+const reference_kind_1 = require("../reference-kind");
+const shared_1 = require("../shared");
+// `audit-template-dependencies` returns one of five reference kinds —
+// the structural ones. Map 1:1 to our wider `ReferenceKind` (which
+// also includes `field-value` for content refs that aren't structural).
+const TEMPLATE_KIND_TO_REFERENCE_KIND = {
+    "primary-template": "primary-template",
+    "base-template": "base-template",
+    "insert-options": "insert-options",
+    "branch-source": "branch-source",
+    "datasource-template": "datasource-template",
+};
+const sortBlockers = (a, b) => {
+    const kindDiff = reference_kind_1.REFERENCE_KIND_PRIORITY[a.referenceKind] - reference_kind_1.REFERENCE_KIND_PRIORITY[b.referenceKind];
+    if (kindDiff !== 0)
+        return kindDiff;
+    const aPath = a.referrerPath ?? a.referrerItemId;
+    const bPath = b.referrerPath ?? b.referrerItemId;
+    return aPath.localeCompare(bPath);
+};
+const summarize = (itemId, blockers) => {
+    if (blockers.length === 0) {
+        return `No inbound references found for ${itemId}. Item should be safe to delete.`;
+    }
+    const byKind = new Map();
+    for (const b of blockers) {
+        byKind.set(b.referenceKind, (byKind.get(b.referenceKind) ?? 0) + 1);
+    }
+    const parts = [...byKind.entries()]
+        .sort(([a], [b]) => reference_kind_1.REFERENCE_KIND_PRIORITY[a] - reference_kind_1.REFERENCE_KIND_PRIORITY[b])
+        .map(([kind, count]) => `${count} ${kind}`);
+    return `${itemId} is blocked by ${blockers.length} inbound reference(s): ${parts.join(", ")}.`;
+};
+/**
+ * Run both audits in parallel against `itemId`, merge the findings
+ * into a single sorted-by-kind blocker list, and print the canonical
+ * envelope. Used by `scai hygiene explain why-blocked <itemId>` and any
+ * automation that wants a single answer to "what's holding this
+ * delete back?"
+ */
+const runExplainWhyBlocked = async (options) => {
+    if (!options.itemId) {
+        throw (0, errors_1.createScaiError)("explain why-blocked requires <itemId>.", "INPUT_INVALID");
+    }
+    const logger = (0, shared_1.toLogger)(options);
+    // Resolve the tenant once up front. The downstream audits also
+    // resolve, but doing it here gives us a single `envName` for the
+    // printed envelope and ensures auth errors surface before either
+    // audit runs.
+    const { envName } = (0, shared_1.resolveTenant)(options);
+    const normalizedTarget = (0, shared_1.normalizeItemId)(options.itemId);
+    const referencesPromise = options.skipContentScan
+        ? Promise.resolve([])
+        : (0, references_1.runAuditReferences)({
+            ...options,
+            to: normalizedTarget,
+            silent: true,
+        });
+    const templateDepsPromise = options.skipTemplateDeps
+        ? Promise.resolve([])
+        : (0, template_dependencies_1.runAuditTemplateDependencies)({
+            ...options,
+            templateId: normalizedTarget,
+            silent: true,
+        });
+    const [referencesResult, templateDepsResult] = await Promise.all([
+        referencesPromise,
+        templateDepsPromise,
+    ]);
+    const blockers = [];
+    for (const r of referencesResult) {
+        // One field-value report can carry multiple field matches — emit
+        // one BlockerEntry per (referrer, fieldName) so the kind sorting
+        // and the per-field action are both visible.
+        for (const match of r.matches) {
+            blockers.push({
+                referenceKind: "field-value",
+                referrerItemId: (0, shared_1.normalizeItemId)(r.itemId),
+                referrerPath: r.path,
+                fieldName: match.fieldName,
+                referrerTemplateName: r.templateName,
+                source: "audit-references",
+            });
+        }
+    }
+    for (const t of templateDepsResult) {
+        blockers.push({
+            referenceKind: TEMPLATE_KIND_TO_REFERENCE_KIND[t.referenceKind],
+            referrerItemId: t.itemId,
+            referrerPath: t.path,
+            fieldName: null,
+            referrerTemplateName: t.templateName,
+            source: "audit-template-dependencies",
+        });
+    }
+    blockers.sort(sortBlockers);
+    const report = {
+        itemId: normalizedTarget,
+        blockers,
+    };
+    if (!options.silent) {
+        (0, shared_1.printReport)({
+            logger,
+            command: "explain.why-blocked",
+            envName,
+            results: blockers,
+            summary: summarize(normalizedTarget, blockers),
+            formatLine: (b) => `[${b.referenceKind}] ${b.referrerPath ?? b.referrerItemId}${b.fieldName ? ` . ${b.fieldName}` : ""}`,
+            extra: {
+                itemId: normalizedTarget,
+                scannedContent: !options.skipContentScan,
+                scannedTemplateDeps: !options.skipTemplateDeps,
+            },
+            options,
+        });
+    }
+    return report;
+};
+exports.runExplainWhyBlocked = runExplainWhyBlocked;