@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/hygiene/tasks/cleanup/subtree.js

@@ -0,0 +1,312 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCleanupSubtree = void 0;
+const cli_tasks_1 = require("../../../shared/cli-tasks");
+const errors_1 = require("../../../shared/errors");
+const shared_1 = require("../shared");
+const subtree_prune_1 = require("./subtree-prune");
+const reference_kind_1 = require("../reference-kind");
+const PROTECTED_ROOTS = [
+    "/sitecore/system",
+    "/sitecore/layout/Layouts/System",
+    "/sitecore/templates/System",
+    "/sitecore/templates/Branches/System",
+    "/sitecore/content/Recycle Bin",
+];
+/**
+ * Build every canonical form of an itemId the Authoring API might
+ * surface in a field value. Single set of forms shared across all
+ * subtree items so the per-field scan can be a flat substring check.
+ */
+const buildIdForms = (normalizedIds) => {
+    // Map from search-form (the thing we look for in field values) →
+    // the normalized 32-char id (the thing we store in the result row).
+    const forms = new Map();
+    for (const id of normalizedIds) {
+        const flat = id;
+        const dashed = `${flat.slice(0, 8)}-${flat.slice(8, 12)}-${flat.slice(12, 16)}-${flat.slice(16, 20)}-${flat.slice(20)}`;
+        forms.set(flat.toLowerCase(), id);
+        forms.set(dashed.toLowerCase(), id);
+        forms.set(`{${dashed.toLowerCase()}}`, id);
+        forms.set(`{${dashed.toUpperCase()}}`, id);
+    }
+    return forms;
+};
+/**
+ * Find every external item whose field value references any item in the
+ * subtree. Walks `scanRoot` once, skipping items that are themselves in
+ * `targetIds`. Self-references inside the subtree are not blockers —
+ * the bottom-up delete walks past them.
+ */
+const findInboundBlockers = async (client, envName, scanRoot, targetIds, options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const idForms = buildIdForms(targetIds);
+    // Sort the form set descending by length so curly-wrapped matches
+    // win over bare-dashed wins over flat. `String.includes` is O(n*m),
+    // but field values are typically short and the form set is small.
+    const sortedForms = [...idForms.entries()].sort((a, b) => b[0].length - a[0].length);
+    const fieldFilter = options.fields?.length
+        ? new Set(options.fields.map((f) => f.toLowerCase()))
+        : null;
+    const { scanned, fieldsByItemId } = await (0, shared_1.scanItemsAndFields)({
+        client,
+        envName,
+        root: scanRoot,
+        logger,
+        options,
+    });
+    const blockers = [];
+    for (const item of scanned) {
+        if (targetIds.has(item.itemId))
+            continue;
+        const fields = fieldsByItemId.get(item.itemId);
+        if (!fields || !Array.isArray(fields))
+            continue;
+        for (const field of fields) {
+            if (!field.value)
+                continue;
+            if (fieldFilter && !fieldFilter.has(field.name.toLowerCase()))
+                continue;
+            // Lowercase-once per field so the substring search is cheap.
+            const lower = field.value.toLowerCase();
+            // One blocker per (referrer, field, target). A multi-list field
+            // referencing two subtree items emits two blockers — the cleanup
+            // groups them back into one updateItemFields call later. Stop
+            // recording once a target is seen so we don't double-count when
+            // both the curly and dashed forms of the same id are in the value.
+            const seenTargets = new Set();
+            for (const [form, targetId] of sortedForms) {
+                if (seenTargets.has(targetId))
+                    continue;
+                if (lower.includes(form)) {
+                    blockers.push({
+                        referrerItemId: item.itemId,
+                        referrerPath: item.path,
+                        referrerTemplateName: item.templateName,
+                        fieldName: field.name,
+                        referenceKind: (0, reference_kind_1.classifyReferenceKind)(field.name),
+                        targetItemId: targetId,
+                        fieldValue: field.value,
+                    });
+                    seenTargets.add(targetId);
+                }
+            }
+        }
+    }
+    return blockers;
+};
+/**
+ * Bottom-up cascade delete of a Sitecore subtree.
+ *
+ * Steps:
+ *   1. Resolve `--path` to an itemId; refuse protected roots.
+ *   2. Enumerate the subtree via `_path CONTAINS <rootItemId>` and
+ *      sort path-length-descending so leaves delete before their
+ *      parents.
+ *   3. Scan `--scan-root` (default `/sitecore`) for items outside the
+ *      subtree whose field values reference any item inside.
+ *   4. Hard-block by default. With `--orphan-external-refs clear`,
+ *      empty each referring field, then proceed.
+ *   5. Walk the deletion list and delete each item.
+ *
+ * Safety rails match the rest of `scai hygiene cleanup`: `--what-if` for
+ * plan-only mode, `--allow-write` enforced outside what-if,
+ * `--max-deletions` blast-radius cap.
+ */
+const runCleanupSubtree = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    if (!options.path) {
+        throw (0, errors_1.createScaiError)("cleanup subtree requires --path <content-tree-path>.", "INPUT_INVALID");
+    }
+    const subtreePath = options.path;
+    if (!options.force && PROTECTED_ROOTS.some((p) => subtreePath.startsWith(p))) {
+        throw (0, errors_1.createScaiError)(`Refusing to operate on protected root '${subtreePath}'.`, "INPUT_INVALID", { hint: "Pass --force to override (only when you intentionally target a system tree)." });
+    }
+    const policy = options.orphanExternalRefs ?? "block";
+    const scanRoot = options.scanRoot ?? "/sitecore";
+    // `leave` mode skips the inbound-reference scan entirely, so the
+    // path-under-scan-root invariant doesn't apply. Other modes need
+    // the scan to either block (default) or compute prune/clear writes,
+    // so they enforce the invariant.
+    if (policy !== "leave" && !subtreePath.startsWith(scanRoot)) {
+        throw (0, errors_1.createScaiError)(`--path '${subtreePath}' is not under --scan-root '${scanRoot}'.`, "INPUT_INVALID", {
+            hint: "Either narrow --scan-root or broaden it to cover the deletion path. Defaulting to /sitecore covers every root.",
+        });
+    }
+    const { envName, root: rootConfig, client } = (0, shared_1.resolveTenant)(options);
+    if (!options.whatIf) {
+        (0, shared_1.ensureAllowWriteForCleanup)(rootConfig, envName, options.allowWrite, "cleanup-subtree");
+    }
+    else if (!logger.isJson()) {
+        logger.info("What-if mode active — no items will be deleted.", "yellow");
+    }
+    // ─── Resolve the subtree root ─────────────────────────────────────────
+    const rootSearch = await client.search({
+        index: options.index,
+        paging: { pageSize: 1 },
+        searchStatement: {
+            criteria: { field: "_fullpath", value: subtreePath.toLowerCase(), criteriaType: "EXACT" },
+        },
+    });
+    const rootItem = rootSearch.results[0];
+    if (!rootItem) {
+        throw (0, errors_1.createScaiError)(`Subtree root '${subtreePath}' not found.`, "INPUT_INVALID", {
+            hint: "Verify the path exists in the tenant (`scai hygiene audit broken-links` can help locate misspellings).",
+        });
+    }
+    const rootItemId = (0, shared_1.normalizeItemId)(rootItem.itemId);
+    // ─── Enumerate the subtree (root + descendants), bottom-up ────────────
+    const knobs = (0, shared_1.resolveHygieneKnobs)(options);
+    const subtreeItems = [
+        { itemId: rootItemId, path: rootItem.path },
+    ];
+    for await (const r of client.searchAll({
+        index: options.index,
+        latestVersionOnly: true,
+        searchStatement: (0, shared_1.buildPathFilterStatement)(rootItemId),
+    }, 100, knobs.pageParallelism)) {
+        const id = (0, shared_1.normalizeItemId)(r.itemId);
+        if (id === rootItemId)
+            continue;
+        subtreeItems.push({ itemId: id, path: r.path });
+    }
+    // Bottom-up: longer paths first. Stable for items at the same depth.
+    subtreeItems.sort((a, b) => b.path.length - a.path.length || a.path.localeCompare(b.path));
+    const maxDeletions = options.maxDeletions ?? 1000;
+    if (subtreeItems.length > maxDeletions) {
+        throw (0, errors_1.createScaiError)(`Subtree contains ${subtreeItems.length} items — exceeds --max-deletions ${maxDeletions}.`, "INPUT_INVALID", {
+            hint: `Raise --max-deletions explicitly when you intend a large purge, or narrow the subtree with a deeper --path.`,
+        });
+    }
+    const targetIds = new Set(subtreeItems.map((i) => i.itemId));
+    // ─── Inbound-reference scan ───────────────────────────────────────────
+    // Skipped in `leave` mode — the operator is opting out of inbound-ref
+    // safety in exchange for speed, accepting that they'll run `audit
+    // broken-links` afterward to find dangling refs.
+    let blockers = [];
+    if (policy !== "leave") {
+        logger.verbose(`Scanning ${scanRoot} for inbound references to ${subtreeItems.length} subtree item(s).`);
+        blockers = await findInboundBlockers(client, envName, scanRoot, targetIds, options);
+    }
+    if (blockers.length > 0 && policy === "block") {
+        // Print the blockers so the operator can choose: clear external refs,
+        // or fix the refs out-of-band first.
+        // Sort by referenceKind priority so structural blockers (base-template,
+        // insert-options, …) surface before plain field-value refs — those are
+        // the ones the operator needs to triage first.
+        const sortedBlockers = [...blockers].sort((a, b) => reference_kind_1.REFERENCE_KIND_PRIORITY[a.referenceKind] - reference_kind_1.REFERENCE_KIND_PRIORITY[b.referenceKind]);
+        const sample = sortedBlockers
+            .slice(0, 5)
+            .map((b) => `  [${b.referenceKind}] ${b.referrerPath} . ${b.fieldName} → ${b.targetItemId.slice(0, 8)}…`)
+            .join("\n");
+        throw (0, errors_1.createScaiError)(`Refusing to delete subtree '${subtreePath}': ${blockers.length} external reference(s) point into it. ` +
+            `Pass --orphan-external-refs clear (empty the fields), prune (surgical removal preserving siblings), or leave (accept dangling refs and clean up later via audit broken-links).\n${sample}${blockers.length > 5 ? `\n  …and ${blockers.length - 5} more` : ""}`, "INPUT_INVALID");
+    }
+    // ─── Optionally clear or prune external referring fields ──────────────
+    if (blockers.length > 0 && policy !== "block" && !options.whatIf) {
+        // Group blockers by (referrerItemId, fieldName) — multiple targets
+        // could point at the same field. One update per (item, field).
+        const byKey = new Map();
+        for (const b of blockers) {
+            const key = `${b.referrerItemId}::${b.fieldName}`;
+            const bucket = byKey.get(key);
+            if (bucket)
+                bucket.push(b);
+            else
+                byKey.set(key, [b]);
+        }
+        await (0, cli_tasks_1.mapWithConcurrency)([...byKey.entries()], async ([, group]) => {
+            const [first] = group;
+            // Decide the new value:
+            //   - `clear`: always empty string.
+            //   - `prune`: try pruners (renderings XML, multi-list). When no
+            //     pruner matches the value's shape, fall back to clearing —
+            //     a single-value reference field has nothing to preserve.
+            let newValue = "";
+            if (policy === "prune" && first.fieldValue) {
+                const targetsInThisField = new Set(group.map((b) => b.targetItemId));
+                const pruned = (0, subtree_prune_1.pruneFieldValue)(first.fieldValue, targetsInThisField);
+                if (pruned !== null)
+                    newValue = pruned;
+            }
+            try {
+                await client.updateItemFields({
+                    itemId: first.referrerItemId,
+                    fields: [{ name: first.fieldName, value: newValue }],
+                });
+                for (const b of group)
+                    b.cleared = true;
+            }
+            catch (error) {
+                // Leave `cleared: undefined` so the caller can see the field
+                // wasn't written; downstream delete will likely fail too.
+                logger.warn(`Failed to ${policy} ${first.referrerPath}.${first.fieldName}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }, options.concurrency ?? 4);
+    }
+    // ─── Delete bottom-up ─────────────────────────────────────────────────
+    const deletions = [];
+    for (const item of subtreeItems) {
+        if (options.whatIf) {
+            deletions.push({ itemId: item.itemId, path: item.path, status: "what-if" });
+            continue;
+        }
+        try {
+            await client.deleteItem({ itemId: item.itemId, permanently: true });
+            deletions.push({ itemId: item.itemId, path: item.path, status: "deleted" });
+        }
+        catch (error) {
+            deletions.push({
+                itemId: item.itemId,
+                path: item.path,
+                status: "failed",
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    const result = {
+        blockers,
+        deletions,
+        policy,
+        whatIf: Boolean(options.whatIf),
+    };
+    const deletedCount = deletions.filter((d) => d.status === "deleted").length;
+    const failedCount = deletions.filter((d) => d.status === "failed").length;
+    // Verb describing what the policy did to each external referring
+    // field. "clearing" for clear, "pruning" for prune, "blocking on"
+    // when the operator hit a hard-block.
+    const refVerb = policy === "clear" ? "clearing" : policy === "prune" ? "pruning" : "blocking on";
+    const writtenVerb = policy === "clear" ? "cleared" : policy === "prune" ? "pruned" : "wrote";
+    const leaveNote = policy === "leave"
+        ? " (leave mode: dangling refs accepted; run `audit broken-links` afterward to triage)"
+        : "";
+    const summary = options.whatIf
+        ? `Plan: would delete ${subtreeItems.length} item${subtreeItems.length === 1 ? "" : "s"}${blockers.length > 0
+            ? ` (after ${refVerb} ${blockers.length} external ref${blockers.length === 1 ? "" : "s"})`
+            : ""}${leaveNote}.`
+        : `Deleted ${deletedCount} of ${subtreeItems.length} item${subtreeItems.length === 1 ? "" : "s"}${blockers.length > 0
+            ? ` (${writtenVerb} ${blockers.filter((b) => b.cleared).length} of ${blockers.length} referring field${blockers.length === 1 ? "" : "s"})`
+            : ""}${failedCount > 0 ? ` (${failedCount} delete failure${failedCount === 1 ? "" : "s"})` : ""}${leaveNote}.`;
+    (0, shared_1.printReport)({
+        logger,
+        command: "cleanup.subtree.delete",
+        envName,
+        results: deletions,
+        summary,
+        formatLine: (d) => `${d.status === "what-if" ? "[would delete] " : d.status === "failed" ? "[failed] " : "[deleted] "}${d.path}${d.error ? ` — ${d.error}` : ""}`,
+        extra: {
+            path: subtreePath,
+            scanRoot,
+            policy,
+            whatIf: Boolean(options.whatIf),
+            subtreeSize: subtreeItems.length,
+            blockerCount: blockers.length,
+            blockersCleared: blockers.filter((b) => b.cleared).length,
+            deletedCount,
+            failedCount,
+        },
+        options,
+    });
+    return result;
+};
+exports.runCleanupSubtree = runCleanupSubtree;

package/dist/hygiene/tasks/cleanup/users.d.ts

@@ -0,0 +1,48 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface CleanupUsersOptions extends HygieneCommonOptions {
+    /** Inactivity threshold in days. Default 365 (one year). */
+    notActiveDays?: number;
+    /** Cap on deletions. Default 25. */
+    maxDeletions?: number;
+    /** Include administrators. Strongly discouraged. */
+    includeAdmins?: boolean;
+    /** Include service accounts (regex match). Off by default. */
+    includeServiceAccounts?: boolean;
+    /** Use UserProfile.lastActivityDate instead of lastLoginDate. */
+    useActivityDate?: boolean;
+    concurrency?: number;
+    whatIf?: boolean;
+    allowWrite?: boolean;
+    baseline?: boolean;
+    output?: string;
+    format?: "json" | "csv" | "markdown";
+}
+export interface UserCleanupAction {
+    user: string;
+    daysSinceActive: number | null;
+    status: "deleted" | "what-if" | "failed";
+    error?: string;
+}
+/**
+ * Purge stale users. Pairs with `audit stale-users list`.
+ *
+ * Safety rails:
+ *   - Default threshold is **one year** (365 days), much higher than
+ *     the audit's 180 default. Deleting users is more destructive
+ *     than flagging them.
+ *   - `--max-deletions` defaults to 25 per run (vs. 100 in
+ *     find-replace) — same reasoning.
+ *   - Administrators excluded by default; pass `--include-admins`
+ *     with caution.
+ *   - Service accounts excluded by default; OAuth client-credentials
+ *     auth doesn't update `lastLoginDate` so service accounts will
+ *     ALWAYS look stale.
+ *   - `--allow-write` (or env `allowWrite`) required outside `--what-if`.
+ *
+ * Notes:
+ *   - The Authoring API's `deleteUser` mutation removes the user.
+ *     Items the user authored aren't deleted (they're owned by the
+ *     tenant), but `__Created by` / `__Updated by` references become
+ *     stale strings rather than resolvable user accounts.
+ */
+export declare const runCleanupUsers: (options: CleanupUsersOptions) => Promise<UserCleanupAction[]>;

package/dist/hygiene/tasks/cleanup/users.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCleanupUsers = void 0;
+const cli_tasks_1 = require("../../../shared/cli-tasks");
+const stale_users_1 = require("../audit/stale-users");
+const shared_1 = require("../shared");
+/**
+ * Purge stale users. Pairs with `audit stale-users list`.
+ *
+ * Safety rails:
+ *   - Default threshold is **one year** (365 days), much higher than
+ *     the audit's 180 default. Deleting users is more destructive
+ *     than flagging them.
+ *   - `--max-deletions` defaults to 25 per run (vs. 100 in
+ *     find-replace) — same reasoning.
+ *   - Administrators excluded by default; pass `--include-admins`
+ *     with caution.
+ *   - Service accounts excluded by default; OAuth client-credentials
+ *     auth doesn't update `lastLoginDate` so service accounts will
+ *     ALWAYS look stale.
+ *   - `--allow-write` (or env `allowWrite`) required outside `--what-if`.
+ *
+ * Notes:
+ *   - The Authoring API's `deleteUser` mutation removes the user.
+ *     Items the user authored aren't deleted (they're owned by the
+ *     tenant), but `__Created by` / `__Updated by` references become
+ *     stale strings rather than resolvable user accounts.
+ */
+const runCleanupUsers = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const { envName, root: rootConfig, client } = (0, shared_1.resolveTenant)(options);
+    if (!options.whatIf) {
+        (0, shared_1.ensureAllowWriteForCleanup)(rootConfig, envName, options.allowWrite, "cleanup-users");
+    }
+    else if (!logger.isJson()) {
+        logger.info("What-if mode active — no users will be deleted.", "yellow");
+    }
+    const days = options.notActiveDays ?? 365;
+    const maxDeletions = options.maxDeletions ?? 25;
+    const stale = await (0, stale_users_1.runAuditStaleUsers)({
+        ...options,
+        notActiveDays: days,
+        includeAdmins: options.includeAdmins,
+        includeServiceAccounts: options.includeServiceAccounts,
+        useActivityDate: options.useActivityDate,
+        json: true,
+        quiet: true,
+    });
+    const targets = stale.slice(0, maxDeletions);
+    const knobs = (0, shared_1.resolveHygieneKnobs)(options);
+    const concurrency = options.concurrency ?? knobs.concurrency;
+    const actions = await (0, cli_tasks_1.mapWithConcurrency)(targets, async (u) => {
+        if (options.whatIf) {
+            return { user: u.user, daysSinceActive: u.daysSinceActive, status: "what-if" };
+        }
+        try {
+            await client.deleteUser(u.user);
+            return { user: u.user, daysSinceActive: u.daysSinceActive, status: "deleted" };
+        }
+        catch (error) {
+            return {
+                user: u.user,
+                daysSinceActive: u.daysSinceActive,
+                status: "failed",
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }, concurrency);
+    const deleted = actions.filter((a) => a.status === "deleted").length;
+    const failed = actions.filter((a) => a.status === "failed").length;
+    const summary = options.whatIf
+        ? `Plan: would delete ${actions.length} stale user${actions.length === 1 ? "" : "s"} (inactive > ${days} days).`
+        : `Deleted ${deleted} user${deleted === 1 ? "" : "s"}${failed > 0 ? ` (${failed} failed)` : ""}.`;
+    (0, shared_1.printReport)({
+        logger,
+        command: "cleanup.users.purge-stale",
+        envName,
+        results: actions,
+        summary,
+        formatLine: (a) => `${a.status === "what-if" ? "[would delete] " : a.status === "failed" ? "[failed] " : ""}${a.user} — ${a.daysSinceActive === null ? "never active" : `${a.daysSinceActive}d`}${a.error ? ` — ${a.error}` : ""}`,
+        extra: {
+            notActiveDays: days,
+            whatIf: Boolean(options.whatIf),
+            maxDeletions,
+            deletedCount: deleted,
+            failedCount: failed,
+        },
+        options,
+    });
+    return actions;
+};
+exports.runCleanupUsers = runCleanupUsers;

package/dist/hygiene/tasks/cleanup/versions-archive.d.ts

@@ -0,0 +1,57 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface CleanupVersionsArchiveOptions extends HygieneCommonOptions {
+    /** Required. Number of most-recent versions to keep per (item, language). */
+    keep: number;
+    /** Required scope. */
+    root: string;
+    /** Restrict to one language. */
+    language?: string;
+    /** Cap on items inspected. Default 5000. */
+    limit?: number;
+    /** Override the search index. */
+    index?: string;
+    /** Concurrency. Default 4. */
+    concurrency?: number;
+    includeSystem?: boolean;
+    whatIf?: boolean;
+    allowWrite?: boolean;
+    /**
+     * Permit operating against `/sitecore/system` / `/sitecore/templates`
+     * subtrees. Off by default.
+     */
+    force?: boolean;
+    /**
+     * Name of the archive bucket. Default unset (Sitecore's default
+     * archive). Useful for separating CLI-driven archive activity from
+     * UI-driven activity.
+     */
+    archiveName?: string;
+}
+export interface VersionArchiveAction {
+    itemId: string;
+    path: string;
+    language: string;
+    versionsBefore: number;
+    versionsAfter: number;
+    archivedVersions: number[];
+    errors: string[];
+}
+/**
+ * Soft alternative to `cleanup versions prune`. Instead of deleting
+ * older versions, move them to the Sitecore archive via `archiveVersion`.
+ *
+ * Same safety rails as `prune`:
+ *   - `--root` required.
+ *   - `--keep` must be >= 1.
+ *   - Protected roots refused without `--force`.
+ *   - `--allow-write` enforced outside `--what-if`.
+ *
+ * Difference from `prune`:
+ *   - The mutation is `archiveVersion` instead of `deleteItemVersion`.
+ *     Archived versions can be restored via `restoreArchivedVersion`
+ *     (Sitecore admin UI) — reversible. Pruned versions are gone for
+ *     good.
+ *   - Returns `archiveVersionId` per archived version, surfaced in the
+ *     report so operators can restore individual versions later.
+ */
+export declare const runCleanupVersionsArchive: (options: CleanupVersionsArchiveOptions) => Promise<VersionArchiveAction[]>;

package/dist/hygiene/tasks/cleanup/versions-archive.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCleanupVersionsArchive = void 0;
+const cli_tasks_1 = require("../../../shared/cli-tasks");
+const errors_1 = require("../../../shared/errors");
+const shared_1 = require("../shared");
+const PROTECTED_ROOTS = [
+    "/sitecore/system",
+    "/sitecore/templates/System",
+    "/sitecore/layout/Layouts/System",
+];
+/**
+ * Soft alternative to `cleanup versions prune`. Instead of deleting
+ * older versions, move them to the Sitecore archive via `archiveVersion`.
+ *
+ * Same safety rails as `prune`:
+ *   - `--root` required.
+ *   - `--keep` must be >= 1.
+ *   - Protected roots refused without `--force`.
+ *   - `--allow-write` enforced outside `--what-if`.
+ *
+ * Difference from `prune`:
+ *   - The mutation is `archiveVersion` instead of `deleteItemVersion`.
+ *     Archived versions can be restored via `restoreArchivedVersion`
+ *     (Sitecore admin UI) — reversible. Pruned versions are gone for
+ *     good.
+ *   - Returns `archiveVersionId` per archived version, surfaced in the
+ *     report so operators can restore individual versions later.
+ */
+const runCleanupVersionsArchive = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    if (!options.root) {
+        throw (0, errors_1.createScaiError)("--root is required for versions archive.", "INPUT_INVALID");
+    }
+    if (!Number.isFinite(options.keep) || options.keep < 1) {
+        throw (0, errors_1.createScaiError)("--keep must be an integer >= 1.", "INPUT_INVALID");
+    }
+    if (!options.force && PROTECTED_ROOTS.some((p) => options.root.startsWith(p))) {
+        throw (0, errors_1.createScaiError)(`Refusing to archive versions under protected path '${options.root}'.`, "INPUT_INVALID", { hint: "Pass --force to override the safety guard for system / template paths." });
+    }
+    const { envName, root, client } = (0, shared_1.resolveTenant)(options);
+    if (!options.whatIf) {
+        (0, shared_1.ensureAllowWriteForCleanup)(root, envName, options.allowWrite);
+    }
+    else if (!logger.isJson()) {
+        logger.info("What-if mode active — no versions will be archived.", "yellow");
+    }
+    const concurrency = options.concurrency ?? 4;
+    const includeSystem = Boolean(options.includeSystem);
+    const limit = options.limit ?? 5000;
+    const rootSearch = await client.search({
+        index: options.index,
+        paging: { pageSize: 1 },
+        searchStatement: {
+            criteria: { field: "_fullpath", value: options.root.toLowerCase(), criteriaType: "EXACT" },
+        },
+    });
+    const rootItemId = rootSearch.results[0]?.itemId;
+    if (!rootItemId) {
+        throw (0, errors_1.createScaiError)(`Root path '${options.root}' not found in search index.`, "INPUT_INVALID");
+    }
+    const pairs = new Map();
+    let scanned = 0;
+    for await (const r of client.searchAll({
+        index: options.index,
+        latestVersionOnly: false,
+        ...(options.language && { language: options.language }),
+        searchStatement: (0, shared_1.buildPathFilterStatement)(rootItemId),
+    }, 100)) {
+        if (!includeSystem && (0, shared_1.isSystemPath)(r.path))
+            continue;
+        const id = (0, shared_1.normalizeItemId)(r.itemId);
+        const lang = r.language?.name ?? options.language;
+        if (!lang)
+            continue;
+        const key = `${id}|${lang}`;
+        if (!pairs.has(key)) {
+            pairs.set(key, { itemId: id, path: r.path, language: lang });
+            scanned += 1;
+            if (scanned >= limit)
+                break;
+        }
+    }
+    logger.verbose(`Scanned ${pairs.size} (item, language) candidates.`);
+    const plans = await (0, cli_tasks_1.mapWithConcurrency)(Array.from(pairs.values()), async (p) => {
+        const versions = await client.getItemVersions({
+            itemId: p.itemId,
+            language: p.language,
+        });
+        if (versions.length <= options.keep)
+            return null;
+        const sorted = [...versions].sort((a, b) => b.version - a.version);
+        return {
+            itemId: p.itemId,
+            path: p.path,
+            language: p.language,
+            keepFrom: sorted.slice(0, options.keep).map((v) => v.version),
+            archiveFrom: sorted.slice(options.keep).map((v) => v.version),
+        };
+    }, concurrency);
+    const plansWithWork = plans.filter((p) => p !== null);
+    const actions = await (0, cli_tasks_1.mapWithConcurrency)(plansWithWork, async (plan) => {
+        const action = {
+            itemId: plan.itemId,
+            path: plan.path,
+            language: plan.language,
+            versionsBefore: plan.keepFrom.length + plan.archiveFrom.length,
+            versionsAfter: plan.keepFrom.length,
+            archivedVersions: [],
+            errors: [],
+        };
+        if (options.whatIf) {
+            action.archivedVersions = plan.archiveFrom;
+            return action;
+        }
+        for (const v of plan.archiveFrom) {
+            try {
+                await client.archiveVersion({
+                    itemId: (0, shared_1.dashifyItemId)(plan.itemId),
+                    language: plan.language,
+                    version: v,
+                    archiveName: options.archiveName,
+                });
+                action.archivedVersions.push(v);
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                action.errors.push(`v${v}: ${msg}`);
+            }
+        }
+        action.versionsAfter = action.versionsBefore - action.archivedVersions.length;
+        return action;
+    }, concurrency);
+    actions.sort((a, b) => a.path.localeCompare(b.path));
+    const totalArchived = actions.reduce((n, a) => n + a.archivedVersions.length, 0);
+    const totalErrors = actions.reduce((n, a) => n + a.errors.length, 0);
+    const summary = options.whatIf
+        ? `Plan: would archive ${totalArchived} version${totalArchived === 1 ? "" : "s"} across ${actions.length} item-language pair${actions.length === 1 ? "" : "s"}.`
+        : `Archived ${totalArchived} version${totalArchived === 1 ? "" : "s"} across ${actions.length} item-language pair${actions.length === 1 ? "" : "s"}${totalErrors > 0 ? ` (${totalErrors} error${totalErrors === 1 ? "" : "s"})` : ""}.`;
+    (0, shared_1.printReport)({
+        logger,
+        command: "cleanup.versions.archive",
+        envName,
+        results: actions,
+        summary,
+        formatLine: (a) => `${a.path} @${a.language}: keep ${a.versionsAfter}, archived ${a.archivedVersions.join(",") || "none"}${a.errors.length ? ` errors: ${a.errors.join(" / ")}` : ""}`,
+        extra: {
+            root: options.root,
+            keep: options.keep,
+            language: options.language ?? null,
+            whatIf: Boolean(options.whatIf),
+            scannedCount: scanned,
+            plannedCount: plansWithWork.length,
+            archivedCount: totalArchived,
+            errorCount: totalErrors,
+            archiveName: options.archiveName ?? null,
+        },
+        options,
+    });
+    return actions;
+};
+exports.runCleanupVersionsArchive = runCleanupVersionsArchive;