@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/hygiene/tasks/cleanup/find-replace.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCleanupFindReplace = void 0;
+const cli_tasks_1 = require("../../../shared/cli-tasks");
+const errors_1 = require("../../../shared/errors");
+const shared_1 = require("../shared");
+const compilePattern = (pattern, options) => {
+    if (!pattern) {
+        throw (0, errors_1.createScaiError)("--pattern is required.", "INPUT_INVALID");
+    }
+    const baseFlags = options.flags ?? "g";
+    let flags = baseFlags;
+    if (options.ignoreCase && !flags.includes("i"))
+        flags += "i";
+    if (!flags.includes("g"))
+        flags += "g";
+    const escaped = options.literal ? pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") : pattern;
+    return new RegExp(escaped, flags);
+};
+const snippet = (value, maxLen = 80) => {
+    const trimmed = value.replace(/\s+/g, " ").trim();
+    if (trimmed.length <= maxLen)
+        return trimmed;
+    return trimmed.slice(0, maxLen - 1) + "…";
+};
+/**
+ * Apply a find-replace operation across content fields.
+ *
+ * Strategy:
+ *   1. Use `scanItemsAndFields` to crawl items and load fields.
+ *   2. Compile the pattern once; for each field, run `.replace` to
+ *      compute the new value and count matches.
+ *   3. Apply via `updateItemFields(itemId, [{name, value}])` per item.
+ *   4. Stop when `--max-mutations` items have been touched.
+ *
+ * Safety rails:
+ *   - `--what-if` reports the planned changes without calling the API.
+ *   - `--allow-write` (or env `allowWrite`) required outside `--what-if`.
+ *   - `--max-mutations` caps the change blast-radius. Default 100.
+ *   - `__`-prefixed system fields are excluded by default. Operators
+ *     who want to touch them must pass `--include-system-fields` AND
+ *     know what they're doing — replacing a `__Renderings` value via
+ *     regex will mangle the XML.
+ *
+ * Notes:
+ *   - The `replacement` string supports JS RegExp backreferences
+ *     (`$1`, `$&`, `$<name>`), same as `String.replace()`. Operators
+ *     who want literal `$` use `$$$$`.
+ *   - Each item is mutated in a single `updateItem` call regardless
+ *     of how many fields change on it. Per-language updates aren't
+ *     supported in this round — the Authoring API treats the update
+ *     as latest-version on the item's primary language.
+ */
+const runCleanupFindReplace = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    if (!options.pattern) {
+        throw (0, errors_1.createScaiError)("--pattern is required.", "INPUT_INVALID");
+    }
+    if (options.replacement === undefined || options.replacement === null) {
+        throw (0, errors_1.createScaiError)("--replacement is required.", "INPUT_INVALID");
+    }
+    const regex = compilePattern(options.pattern, options);
+    const maxMutations = options.maxMutations ?? 100;
+    const fieldFilter = options.fields?.length
+        ? new Set(options.fields.map((f) => f.toLowerCase()))
+        : null;
+    const includeSystemFields = Boolean(options.includeSystemFields);
+    const { envName, root: rootConfig, client } = (0, shared_1.resolveTenant)(options);
+    if (!options.whatIf) {
+        (0, shared_1.ensureAllowWriteForCleanup)(rootConfig, envName, options.allowWrite);
+    }
+    else if (!logger.isJson()) {
+        logger.info("What-if mode active — no items will be modified.", "yellow");
+    }
+    const { scanned, fieldsByItemId, cache, knobs } = await (0, shared_1.scanItemsAndFields)({
+        client,
+        envName,
+        root: options.root ?? "/sitecore/content",
+        logger,
+        options,
+    });
+    const plans = [];
+    for (const item of scanned) {
+        const fields = fieldsByItemId.get(item.itemId);
+        if (!fields || !Array.isArray(fields))
+            continue;
+        const fieldUpdates = [];
+        for (const field of fields) {
+            if (!field.value)
+                continue;
+            if (fieldFilter && !fieldFilter.has(field.name.toLowerCase()))
+                continue;
+            if (!includeSystemFields && field.name.startsWith("__"))
+                continue;
+            regex.lastIndex = 0;
+            const matchCount = (field.value.match(regex) || []).length;
+            if (matchCount === 0)
+                continue;
+            regex.lastIndex = 0;
+            const newValue = field.value.replace(regex, options.replacement);
+            if (newValue === field.value)
+                continue;
+            fieldUpdates.push({
+                name: field.name,
+                oldValue: field.value,
+                newValue,
+                matchCount,
+            });
+        }
+        if (fieldUpdates.length > 0)
+            plans.push({ item, fieldUpdates });
+        if (plans.length >= maxMutations) {
+            logger.warn(`Hit --max-mutations cap (${maxMutations}); ${scanned.length - plans.length} item(s) skipped. Re-run with a higher cap to widen.`);
+            break;
+        }
+    }
+    logger.verbose(`${plans.length} item(s) plan to mutate.`);
+    const actions = await (0, cli_tasks_1.mapWithConcurrency)(plans, async (plan) => {
+        const base = {
+            itemId: plan.item.itemId,
+            path: plan.item.path,
+            templateName: plan.item.templateName,
+            language: plan.item.language,
+            fieldsChanged: plan.fieldUpdates.map((f) => ({
+                fieldName: f.name,
+                matchCount: f.matchCount,
+                samples: [{ before: snippet(f.oldValue), after: snippet(f.newValue) }],
+            })),
+        };
+        if (options.whatIf) {
+            return { ...base, status: "what-if" };
+        }
+        try {
+            await client.updateItemFields({
+                itemId: (0, shared_1.dashifyItemId)(plan.item.itemId),
+                fields: plan.fieldUpdates.map((f) => ({ name: f.name, value: f.newValue })),
+            });
+            return { ...base, status: "applied" };
+        }
+        catch (error) {
+            return {
+                ...base,
+                status: "failed",
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }, knobs.concurrency);
+    await cache?.flush();
+    const applied = actions.filter((a) => a.status === "applied").length;
+    const failed = actions.filter((a) => a.status === "failed").length;
+    const totalMatches = actions.reduce((n, a) => n + a.fieldsChanged.reduce((m, f) => m + f.matchCount, 0), 0);
+    const summary = options.whatIf
+        ? `Plan: would update ${actions.length} item${actions.length === 1 ? "" : "s"} (${totalMatches} match occurrences).`
+        : `Applied ${applied} of ${actions.length} update${actions.length === 1 ? "" : "s"} (${totalMatches} replacements)${failed > 0 ? `; ${failed} failed` : ""}.`;
+    (0, shared_1.printReport)({
+        logger,
+        command: "cleanup.find-replace",
+        envName,
+        results: actions,
+        summary,
+        formatLine: (a) => `${a.status === "what-if" ? "[would change] " : a.status === "failed" ? "[failed] " : ""}${a.path} — ${a.fieldsChanged
+            .slice(0, 2)
+            .map((f) => `${f.fieldName}(${f.matchCount}×)`)
+            .join(", ")}${a.fieldsChanged.length > 2 ? "…" : ""}${a.error ? ` — ${a.error}` : ""}`,
+        extra: {
+            pattern: options.pattern,
+            replacement: options.replacement,
+            literal: Boolean(options.literal),
+            ignoreCase: Boolean(options.ignoreCase),
+            whatIf: Boolean(options.whatIf),
+            maxMutations,
+            appliedCount: applied,
+            failedCount: failed,
+            totalMatches,
+        },
+        options,
+    });
+    return actions;
+};
+exports.runCleanupFindReplace = runCleanupFindReplace;

package/dist/hygiene/tasks/cleanup/language-version-add.d.ts

@@ -0,0 +1,74 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface CleanupLanguageVersionAddOptions extends HygieneCommonOptions {
+    /** Required. Language code(s) to add (e.g. ["fr", "es"]). */
+    languages: string[];
+    /**
+     * Optional source language. When supplied, the new version's fields
+     * are copied from the latest version in that language. Defaults to
+     * letting Sitecore seed the new version empty.
+     */
+    fromLanguage?: string;
+    /** Restrict by template name pattern. Recommended. */
+    templatePattern?: string;
+    /** Content-tree root. Default `/sitecore/content`. */
+    root?: string;
+    index?: string;
+    limit?: number;
+    includeSystem?: boolean;
+    concurrency?: number;
+    pageParallelism?: number;
+    cache?: boolean;
+    exclude?: string[];
+    since?: string;
+    owner?: string;
+    whatIf?: boolean;
+    allowWrite?: boolean;
+    baseline?: boolean;
+    output?: string;
+    format?: "json" | "csv" | "markdown";
+    /**
+     * Maximum number of (item, language) versions created per run.
+     * Default 500. One run on /sitecore/content × 4 languages can fan
+     * out to 10k+ writes; cap defends against runaway scope.
+     */
+    maxAdds?: number;
+}
+export interface LanguageVersionAddAction {
+    itemId: string;
+    path: string;
+    templateName: string | null;
+    language: string;
+    versionNumber: number | null;
+    status: "applied" | "what-if" | "failed" | "skipped-existing";
+    error?: string;
+}
+/**
+ * Add empty (or copied) language versions to items in bulk so
+ * translators can pick them up without per-item clicking.
+ *
+ * Strategy:
+ *   1. Scan items via `scanItemsAndFields(skipFields: true)`.
+ *   2. For each (item, requested-language) pair, call
+ *      `client.addItemVersion({itemId, language, baseVersion?})`. The
+ *      Authoring API creates a new version in the target language
+ *      whose fields are seeded empty (or copied from `fromLanguage`'s
+ *      latest version when `baseVersion` is supplied).
+ *
+ * What this does NOT do:
+ *   - It does not detect existing versions before calling — the
+ *     Authoring API is the source of truth for "is this version
+ *     already present?" Calling addItemVersion when a version exists
+ *     returns the existing one (no duplicate created); we surface
+ *     that as `skipped-existing` based on the returned versionNumber
+ *     matching an already-known state. This is a server-side decision
+ *     we trust, not a client-side check.
+ *
+ * Safety rails:
+ *   - `--what-if` reports planned (item, language) pairs.
+ *   - `--allow-write` required outside what-if.
+ *   - `--max-adds` caps the version-creation count. Default 500.
+ *   - `--template-pattern` is strongly recommended — adding language
+ *     versions to every item under /sitecore/content (including system
+ *     items) is rarely the intent.
+ */
+export declare const runCleanupLanguageVersionAdd: (options: CleanupLanguageVersionAddOptions) => Promise<LanguageVersionAddAction[]>;

package/dist/hygiene/tasks/cleanup/language-version-add.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCleanupLanguageVersionAdd = void 0;
+const cli_tasks_1 = require("../../../shared/cli-tasks");
+const errors_1 = require("../../../shared/errors");
+const shared_1 = require("../shared");
+/**
+ * Add empty (or copied) language versions to items in bulk so
+ * translators can pick them up without per-item clicking.
+ *
+ * Strategy:
+ *   1. Scan items via `scanItemsAndFields(skipFields: true)`.
+ *   2. For each (item, requested-language) pair, call
+ *      `client.addItemVersion({itemId, language, baseVersion?})`. The
+ *      Authoring API creates a new version in the target language
+ *      whose fields are seeded empty (or copied from `fromLanguage`'s
+ *      latest version when `baseVersion` is supplied).
+ *
+ * What this does NOT do:
+ *   - It does not detect existing versions before calling — the
+ *     Authoring API is the source of truth for "is this version
+ *     already present?" Calling addItemVersion when a version exists
+ *     returns the existing one (no duplicate created); we surface
+ *     that as `skipped-existing` based on the returned versionNumber
+ *     matching an already-known state. This is a server-side decision
+ *     we trust, not a client-side check.
+ *
+ * Safety rails:
+ *   - `--what-if` reports planned (item, language) pairs.
+ *   - `--allow-write` required outside what-if.
+ *   - `--max-adds` caps the version-creation count. Default 500.
+ *   - `--template-pattern` is strongly recommended — adding language
+ *     versions to every item under /sitecore/content (including system
+ *     items) is rarely the intent.
+ */
+const runCleanupLanguageVersionAdd = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    if (!options.languages?.length) {
+        throw (0, errors_1.createScaiError)("`languages` is required (at least one language code).", "INPUT_INVALID");
+    }
+    const templateRegex = options.templatePattern ? new RegExp(options.templatePattern, "i") : null;
+    const maxAdds = options.maxAdds ?? 500;
+    const { envName, root: rootConfig, client } = (0, shared_1.resolveTenant)(options);
+    if (!options.whatIf) {
+        (0, shared_1.ensureAllowWriteForCleanup)(rootConfig, envName, options.allowWrite);
+    }
+    else if (!logger.isJson()) {
+        logger.info("What-if mode active — no language versions will be created.", "yellow");
+    }
+    const { scanned, cache, knobs } = await (0, shared_1.scanItemsAndFields)({
+        client,
+        envName,
+        root: options.root ?? "/sitecore/content",
+        logger,
+        options,
+        skipFields: true,
+    });
+    const plans = [];
+    outer: for (const item of scanned) {
+        if (templateRegex && !templateRegex.test(item.templateName ?? ""))
+            continue;
+        for (const language of options.languages) {
+            plans.push({ item, language });
+            if (plans.length >= maxAdds) {
+                logger.warn(`Hit --max-adds cap (${maxAdds}); ${scanned.length - plans.length} item(s) skipped. Re-run with a higher cap to widen.`);
+                break outer;
+            }
+        }
+    }
+    const actions = await (0, cli_tasks_1.mapWithConcurrency)(plans, async (plan) => {
+        const base = {
+            itemId: plan.item.itemId,
+            path: plan.item.path,
+            templateName: plan.item.templateName,
+            language: plan.language,
+        };
+        if (options.whatIf) {
+            return { ...base, versionNumber: null, status: "what-if" };
+        }
+        try {
+            const result = await client.addItemVersion({
+                itemId: (0, shared_1.dashifyItemId)(plan.item.itemId),
+                language: plan.language,
+                ...(options.fromLanguage && { baseVersion: 1 }),
+            });
+            return {
+                ...base,
+                versionNumber: result.versionNumber,
+                status: "applied",
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            // The Authoring API tends to reject "version already exists"
+            // with a recognizable error rather than returning the existing
+            // version — we surface that as skipped-existing so the operator
+            // sees a clean count rather than a noise of "failed" rows.
+            if (/already.*exist/i.test(message)) {
+                return { ...base, versionNumber: null, status: "skipped-existing" };
+            }
+            return {
+                ...base,
+                versionNumber: null,
+                status: "failed",
+                error: message,
+            };
+        }
+    }, knobs.concurrency);
+    await cache?.flush();
+    const applied = actions.filter((a) => a.status === "applied").length;
+    const skipped = actions.filter((a) => a.status === "skipped-existing").length;
+    const failed = actions.filter((a) => a.status === "failed").length;
+    const summary = options.whatIf
+        ? `Plan: would create ${actions.length} (item, language) version(s).`
+        : `Created ${applied} version(s)${skipped > 0 ? `; ${skipped} already existed` : ""}${failed > 0 ? `; ${failed} failed` : ""}.`;
+    (0, shared_1.printReport)({
+        logger,
+        command: "cleanup.language-version-add",
+        envName,
+        results: actions,
+        summary,
+        formatLine: (a) => `${a.status === "applied" ? "" : `[${a.status}] `}${a.path} [${a.language}]${a.versionNumber ? ` v${a.versionNumber}` : ""}${a.error ? ` — ${a.error}` : ""}`,
+        extra: {
+            languages: options.languages,
+            fromLanguage: options.fromLanguage ?? null,
+            whatIf: Boolean(options.whatIf),
+            maxAdds,
+            appliedCount: applied,
+            skippedCount: skipped,
+            failedCount: failed,
+        },
+        options,
+    });
+    return actions;
+};
+exports.runCleanupLanguageVersionAdd = runCleanupLanguageVersionAdd;

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

@@ -0,0 +1,78 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface CleanupRenameOptions extends HygieneCommonOptions {
+    /**
+     * Required. Pattern to match against item names. JS regex by default;
+     * pass `--literal` to escape the input.
+     */
+    pattern: string;
+    /**
+     * Required. Replacement string. Supports JS RegExp backreferences
+     * (`$1`, `$&`, `$<group>`). Use `$$` for a literal `$`.
+     */
+    replacement: string;
+    literal?: boolean;
+    ignoreCase?: boolean;
+    flags?: string;
+    /** Restrict by template name pattern. Recommended. */
+    templatePattern?: string;
+    /** Content-tree root. Default `/sitecore/content`. */
+    root?: string;
+    index?: string;
+    limit?: number;
+    includeSystem?: boolean;
+    concurrency?: number;
+    pageParallelism?: number;
+    cache?: boolean;
+    exclude?: string[];
+    since?: string;
+    owner?: string;
+    whatIf?: boolean;
+    allowWrite?: boolean;
+    baseline?: boolean;
+    output?: string;
+    format?: "json" | "csv" | "markdown";
+    /**
+     * Maximum number of items renamed per run. Default 100. Renames mutate
+     * paths — a stray match against `Page1`/`Page2`/... could thousand-fold
+     * the site map. Cap is intentionally low.
+     */
+    maxRenames?: number;
+}
+export interface RenameAction {
+    itemId: string;
+    oldPath: string;
+    oldName: string;
+    newName: string;
+    newPath: string;
+    templateName: string | null;
+    status: "applied" | "what-if" | "failed" | "skipped-no-change" | "skipped-shape";
+    error?: string;
+}
+/**
+ * Bulk-rename items by pattern.
+ *
+ * Strategy:
+ *   1. Scan via `scanItemsAndFields(skipFields: true)` — we only need
+ *      the item's name + path.
+ *   2. For each item, compute `newName = oldName.replace(pattern, replacement)`.
+ *   3. Validate the new name: no slashes, non-empty, ≠ old name.
+ *   4. Call `client.renameItem({itemId, name: newName})`.
+ *
+ * Safety rails:
+ *   - `--what-if` reports without writing.
+ *   - `--allow-write` required outside what-if.
+ *   - `--max-renames` caps the blast radius (default 100).
+ *   - `--template-pattern` is strongly recommended; renaming items by
+ *     a generic name pattern across every template is rarely the
+ *     intent.
+ *
+ * Notes:
+ *   - The Authoring API's `updateItem(name: …)` rejects slashes in
+ *     names (resolves to an unreachable path). We reject up-front.
+ *   - Renaming changes the URL slug of pages — coordinate with
+ *     redirects / sitemap regeneration in the surrounding workflow.
+ *   - Display name (`__Display Name`) is a separate field; this verb
+ *     does NOT touch it. Use `cleanup field-set --field "__Display Name"`
+ *     when the operator wants the editor-visible name to change too.
+ */
+export declare const runCleanupRename: (options: CleanupRenameOptions) => Promise<RenameAction[]>;

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

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCleanupRename = void 0;
+const cli_tasks_1 = require("../../../shared/cli-tasks");
+const errors_1 = require("../../../shared/errors");
+const shared_1 = require("../shared");
+const compilePattern = (pattern, options) => {
+    if (!pattern) {
+        throw (0, errors_1.createScaiError)("--pattern is required.", "INPUT_INVALID");
+    }
+    const baseFlags = options.flags ?? "";
+    let flags = baseFlags;
+    if (options.ignoreCase && !flags.includes("i"))
+        flags += "i";
+    // Intentionally NOT adding `g` — `name.replace(pattern, ...)` should
+    // match once on the name string (names are short; global replace
+    // creates surprising results for patterns like `[0-9]+`).
+    const escaped = options.literal ? pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") : pattern;
+    return new RegExp(escaped, flags);
+};
+/**
+ * Bulk-rename items by pattern.
+ *
+ * Strategy:
+ *   1. Scan via `scanItemsAndFields(skipFields: true)` — we only need
+ *      the item's name + path.
+ *   2. For each item, compute `newName = oldName.replace(pattern, replacement)`.
+ *   3. Validate the new name: no slashes, non-empty, ≠ old name.
+ *   4. Call `client.renameItem({itemId, name: newName})`.
+ *
+ * Safety rails:
+ *   - `--what-if` reports without writing.
+ *   - `--allow-write` required outside what-if.
+ *   - `--max-renames` caps the blast radius (default 100).
+ *   - `--template-pattern` is strongly recommended; renaming items by
+ *     a generic name pattern across every template is rarely the
+ *     intent.
+ *
+ * Notes:
+ *   - The Authoring API's `updateItem(name: …)` rejects slashes in
+ *     names (resolves to an unreachable path). We reject up-front.
+ *   - Renaming changes the URL slug of pages — coordinate with
+ *     redirects / sitemap regeneration in the surrounding workflow.
+ *   - Display name (`__Display Name`) is a separate field; this verb
+ *     does NOT touch it. Use `cleanup field-set --field "__Display Name"`
+ *     when the operator wants the editor-visible name to change too.
+ */
+const runCleanupRename = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    if (!options.pattern) {
+        throw (0, errors_1.createScaiError)("--pattern is required.", "INPUT_INVALID");
+    }
+    if (options.replacement === undefined || options.replacement === null) {
+        throw (0, errors_1.createScaiError)("--replacement is required.", "INPUT_INVALID");
+    }
+    const regex = compilePattern(options.pattern, options);
+    const templateRegex = options.templatePattern ? new RegExp(options.templatePattern, "i") : null;
+    const maxRenames = options.maxRenames ?? 100;
+    const { envName, root: rootConfig, client } = (0, shared_1.resolveTenant)(options);
+    if (!options.whatIf) {
+        (0, shared_1.ensureAllowWriteForCleanup)(rootConfig, envName, options.allowWrite);
+    }
+    else if (!logger.isJson()) {
+        logger.info("What-if mode active — no items will be renamed.", "yellow");
+    }
+    const { scanned, cache, knobs } = await (0, shared_1.scanItemsAndFields)({
+        client,
+        envName,
+        root: options.root ?? "/sitecore/content",
+        logger,
+        options,
+        skipFields: true,
+    });
+    const plans = [];
+    for (const item of scanned) {
+        if (templateRegex && !templateRegex.test(item.templateName ?? ""))
+            continue;
+        const newName = item.name.replace(regex, options.replacement);
+        if (newName === item.name)
+            continue;
+        let skip;
+        if (!newName.trim()) {
+            skip = "skipped-shape";
+        }
+        else if (/[/\\]/.test(newName)) {
+            skip = "skipped-shape";
+        }
+        plans.push({ item, newName, ...(skip && { skip }) });
+        if (plans.filter((p) => !p.skip).length >= maxRenames) {
+            logger.warn(`Hit --max-renames cap (${maxRenames}); ${scanned.length - plans.length} item(s) skipped. Re-run with a higher cap to widen.`);
+            break;
+        }
+    }
+    const actions = await (0, cli_tasks_1.mapWithConcurrency)(plans, async (plan) => {
+        const oldPath = plan.item.path;
+        const lastSlash = oldPath.lastIndexOf("/");
+        const newPath = lastSlash >= 0 ? `${oldPath.slice(0, lastSlash)}/${plan.newName}` : oldPath;
+        const base = {
+            itemId: plan.item.itemId,
+            oldPath,
+            oldName: plan.item.name,
+            newName: plan.newName,
+            newPath,
+            templateName: plan.item.templateName,
+        };
+        if (plan.skip)
+            return { ...base, status: plan.skip };
+        if (options.whatIf)
+            return { ...base, status: "what-if" };
+        try {
+            await client.renameItem({
+                itemId: (0, shared_1.dashifyItemId)(plan.item.itemId),
+                name: plan.newName,
+            });
+            return { ...base, status: "applied" };
+        }
+        catch (error) {
+            return {
+                ...base,
+                status: "failed",
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }, knobs.concurrency);
+    await cache?.flush();
+    const applied = actions.filter((a) => a.status === "applied").length;
+    const failed = actions.filter((a) => a.status === "failed").length;
+    const summary = options.whatIf
+        ? `Plan: would rename ${actions.filter((a) => a.status === "what-if").length} item(s).`
+        : `Renamed ${applied} item(s)${failed > 0 ? `; ${failed} failed` : ""}.`;
+    (0, shared_1.printReport)({
+        logger,
+        command: "cleanup.rename",
+        envName,
+        results: actions,
+        summary,
+        formatLine: (a) => `${a.status === "applied" ? "" : `[${a.status}] `}${a.oldPath} → ${a.newName}${a.error ? ` — ${a.error}` : ""}`,
+        extra: {
+            pattern: options.pattern,
+            replacement: options.replacement,
+            literal: Boolean(options.literal),
+            ignoreCase: Boolean(options.ignoreCase),
+            whatIf: Boolean(options.whatIf),
+            maxRenames,
+            appliedCount: applied,
+            failedCount: failed,
+        },
+        options,
+    });
+    return actions;
+};
+exports.runCleanupRename = runCleanupRename;

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

@@ -0,0 +1,58 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface CleanupRolesOptions extends HygieneCommonOptions {
+    /** Restrict to a specific domain. */
+    domain?: string;
+    /** Cap on deletions. Default 50. */
+    maxDeletions?: number;
+    concurrency?: number;
+    whatIf?: boolean;
+    allowWrite?: boolean;
+    baseline?: boolean;
+    output?: string;
+    format?: "json" | "csv" | "markdown";
+    /**
+     * Include Sitecore platform / built-in roles in the purge. Off by
+     * default — built-in roles (Administrator, Author, every `Sitecore
+     * Client …` role, every `Analytics …` and `Marketer …` role) ship
+     * empty on a fresh tenant and remain empty until operators wire them
+     * up; deleting them by mistake breaks the platform's role model and
+     * the Items.AccessRights inheritance that depends on those roles
+     * existing. Pass `--include-builtin` only after triple-checking the
+     * audit output.
+     */
+    includeBuiltin?: boolean;
+    /**
+     * Additional role names to never delete, on top of the built-in skip
+     * list. Match is case-insensitive and supports both the bare name and
+     * the `domain\name` form.
+     */
+    alwaysSkip?: string[];
+}
+export interface RoleCleanupAction {
+    name: string;
+    domain: string | null;
+    status: "deleted" | "what-if" | "failed";
+    error?: string;
+}
+/**
+ * Purge empty roles. Pairs with `audit empty-roles list`.
+ *
+ * Safety rails:
+ *   - `--what-if` reports the plan without mutating.
+ *   - `--allow-write` required outside `--what-if`.
+ *   - `--max-deletions` caps per-run blast radius (default 50).
+ *   - Sitecore built-in roles (sitecore\\Author, sitecore\\Developer,
+ *     etc.) are surfaced by `audit empty-roles` only if they are
+ *     genuinely empty. If they're empty by accident (after a user
+ *     migration), deleting them breaks the platform's role model.
+ *     Operators should review the audit output BEFORE running cleanup.
+ *
+ * Notes:
+ *   - The Authoring API's `deleteRole` cascades — users in the role
+ *     lose that membership. Empty roles have no members by definition,
+ *     so no membership change.
+ *   - Roles that are members of OTHER roles (via `Role.memberOf`)
+ *     leave dangling memberships when deleted. We don't check that
+ *     here; the cleanup is intentionally minimal.
+ */
+export declare const runCleanupRoles: (options: CleanupRolesOptions) => Promise<RoleCleanupAction[]>;