@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/hygiene/tasks/cleanup/dead-templates.js

@@ -0,0 +1,247 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCleanupDeadTemplates = void 0;
+const cli_tasks_1 = require("../../../shared/cli-tasks");
+const errors_1 = require("../../../shared/errors");
+const dead_templates_1 = require("../audit/dead-templates");
+const template_dependencies_1 = require("../audit/template-dependencies");
+const shared_1 = require("../shared");
+const PROTECTED_TEMPLATE_ROOTS = [
+    "/sitecore/templates/System",
+    "/sitecore/templates/Branches/System",
+];
+/**
+ * The Authoring API's template-cache can lag ~30-90s after a large
+ * cascade delete: deleting a template whose dependents were JUST
+ * removed may 4xx with "template has dependents" until the cache
+ * settles. The pre-flight `audit template-dependencies` has already
+ * filtered templates with *real* structural dependents, so a dependents
+ * error here is the stale-cache false positive — retry past the settle
+ * window before surfacing it. (With `--force` the pre-flight is skipped,
+ * so a genuine dependents error simply retries then surfaces — a bounded
+ * ~39s cost, not a hang.)
+ */
+const TEMPLATE_CACHE_LAG = /dependent|used by/i;
+const RETRY_DELAYS_MS = [4000, 10000, 25000];
+const deleteItemTemplateWithRetry = async (client, templateId, logger) => {
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            await client.deleteItemTemplate(templateId);
+            return;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (attempt >= RETRY_DELAYS_MS.length || !TEMPLATE_CACHE_LAG.test(message)) {
+                throw error;
+            }
+            const waitMs = RETRY_DELAYS_MS[attempt];
+            logger.info(`Template-cache lag on ${templateId} — retrying in ${waitMs / 1000}s ` +
+                `(attempt ${attempt + 1}/${RETRY_DELAYS_MS.length}).`, "yellow");
+            await new Promise((resolve) => setTimeout(resolve, waitMs));
+        }
+    }
+};
+/**
+ * Walk a template root bottom-up and delete folders that are empty after
+ * the dead-templates purge.
+ *
+ * Algorithm:
+ *   1. List children of the root.
+ *   2. For each child, recurse: if it's a template-folder-shaped node
+ *      (no template fields beyond folder template id), check its
+ *      children. If empty, delete it.
+ *   3. Bubble up — a parent may become empty after its children are
+ *      deleted.
+ *
+ * Returns the list of folder deletions attempted, with status.
+ */
+const cleanupEmptyTemplateFolders = async (client, rootPath, options) => {
+    const actions = [];
+    const walk = async (path) => {
+        // Returns true if the folder ended up empty (parent should re-check).
+        const children = await client.getChildren({ path });
+        if (children.length === 0)
+            return true;
+        // Recurse into each child; track which ones are themselves empty folders.
+        const childResults = await Promise.all(children.map(async (child) => {
+            // Walk recursively; this may delete the child if it ends empty.
+            const childEmpty = await walk(child.path);
+            if (!childEmpty)
+                return false;
+            const action = {
+                path: child.path,
+                itemId: child.itemId,
+                status: options.whatIf ? "what-if" : "deleted",
+            };
+            if (!options.whatIf) {
+                try {
+                    await client.deleteItem({ itemId: child.itemId, permanently: true });
+                }
+                catch (error) {
+                    action.status = "failed";
+                    action.error = error instanceof Error ? error.message : String(error);
+                }
+            }
+            actions.push(action);
+            return action.status !== "failed";
+        }));
+        // The current folder is empty iff every child ended empty (and was
+        // successfully deleted, or marked what-if).
+        return childResults.every((r) => r === true);
+    };
+    await walk(rootPath);
+    return actions;
+};
+/**
+ * Delete templates that have zero items deriving from them, then
+ * optionally clean up empty template folders left behind.
+ *
+ * Strategy:
+ *   1. Run `audit dead-templates` to identify candidates.
+ *   2. For each dead template, call `deleteItemTemplate(templateId)`.
+ *   3. If `--cleanup-empty-folders` (default true), walk the template
+ *      tree bottom-up and delete folders that ended up empty.
+ *
+ * Safety rails:
+ *   - `--root` defaults to `/sitecore/templates/Project` (project-owned).
+ *   - Refuses to operate on `/sitecore/templates/System` without
+ *     `--force`. Deleting system templates breaks editor UIs even when
+ *     they show zero items in the search index.
+ *   - `--allow-write` / `allowWrite` enforced outside `--what-if`.
+ *   - Cascades not handled: the underlying mutation fails (returns
+ *     `successful: false`) if a template is still used as a base
+ *     template by another, even when no items derive from it. Those
+ *     failures surface as per-record errors with the operator's
+ *     suggested next step in the message.
+ */
+const runCleanupDeadTemplates = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const root = options.root ?? "/sitecore/templates/Project";
+    if (!options.force && PROTECTED_TEMPLATE_ROOTS.some((p) => root.startsWith(p))) {
+        throw (0, errors_1.createScaiError)(`Refusing to operate on protected template root '${root}'.`, "INPUT_INVALID", { hint: "Pass --force to override (only when you intentionally target a system tree)." });
+    }
+    const { envName, root: rootConfig, client } = (0, shared_1.resolveTenant)(options);
+    if (!options.whatIf) {
+        (0, shared_1.ensureAllowWriteForCleanup)(rootConfig, envName, options.allowWrite, "cleanup-dead-templates");
+    }
+    else if (!logger.isJson()) {
+        logger.info("What-if mode active — no templates or folders will be deleted.", "yellow");
+    }
+    // Reuse the audit task to find candidates.
+    const dead = await (0, dead_templates_1.runAuditDeadTemplates)({
+        ...options,
+        // Suppress the audit's own report — we'll emit a combined cleanup
+        // report below. Two ways: pipe through --json + ignore, or swallow
+        // the print via a side-channel. For now we just let the audit print
+        // its own report; under --json the caller sees two records (audit
+        // then cleanup) which is reasonable.
+    });
+    const templateActions = await (0, cli_tasks_1.mapWithConcurrency)(dead, async (t) => {
+        // Pre-flight check: `audit dead-templates` only counts primary-template
+        // refs (items whose `_template` is t.templateId). Templates can still
+        // be in use as base templates, insert-options entries, branch sources,
+        // or datasource templates — none of which the dead-templates audit
+        // sees. Running `audit template-dependencies` here catches all four
+        // structural shapes via the search index before we attempt a delete
+        // the Authoring API would reject anyway. The agent gets a structured
+        // `blockers` list instead of a terse "is used by other items" string.
+        //
+        // --force skips the pre-flight and lets the Authoring API decide
+        // (preserves the existing escape hatch for ops who know the API
+        // would accept the delete despite stale index entries).
+        if (!options.force) {
+            const blockers = await (0, template_dependencies_1.runAuditTemplateDependencies)({
+                ...options,
+                templateId: t.templateId,
+                silent: true,
+            });
+            if (blockers.length > 0) {
+                return {
+                    templateId: t.templateId,
+                    name: t.name,
+                    fullName: t.fullName,
+                    status: "blocked",
+                    blockers,
+                };
+            }
+        }
+        if (options.whatIf) {
+            return {
+                templateId: t.templateId,
+                name: t.name,
+                fullName: t.fullName,
+                status: "what-if",
+            };
+        }
+        try {
+            await deleteItemTemplateWithRetry(client, t.templateId, logger);
+            return {
+                templateId: t.templateId,
+                name: t.name,
+                fullName: t.fullName,
+                status: "purged",
+            };
+        }
+        catch (error) {
+            return {
+                templateId: t.templateId,
+                name: t.name,
+                fullName: t.fullName,
+                status: "failed",
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }, options.concurrency ?? 4);
+    let folderActions = [];
+    const cleanupFolders = options.cleanupEmptyFolders !== false;
+    if (cleanupFolders && templateActions.length > 0) {
+        folderActions = await cleanupEmptyTemplateFolders(client, root, {
+            whatIf: Boolean(options.whatIf),
+        });
+    }
+    const purged = templateActions.filter((a) => a.status === "purged").length;
+    const failed = templateActions.filter((a) => a.status === "failed").length;
+    const blocked = templateActions.filter((a) => a.status === "blocked").length;
+    const wouldDelete = templateActions.filter((a) => a.status === "what-if").length;
+    const foldersRemoved = folderActions.filter((a) => a.status === "deleted").length;
+    const blockedSuffix = blocked > 0 ? `, ${blocked} blocked by inbound refs` : "";
+    const summary = options.whatIf
+        ? `Plan: would delete ${wouldDelete} dead template${wouldDelete === 1 ? "" : "s"}${folderActions.length > 0
+            ? ` and ${folderActions.length} empty folder${folderActions.length === 1 ? "" : "s"}`
+            : ""}${blockedSuffix}.`
+        : `Deleted ${purged} template${purged === 1 ? "" : "s"}${foldersRemoved > 0
+            ? ` and ${foldersRemoved} empty folder${foldersRemoved === 1 ? "" : "s"}`
+            : ""}${failed > 0 ? ` (${failed} template failure${failed === 1 ? "" : "s"})` : ""}${blockedSuffix}.`;
+    (0, shared_1.printReport)({
+        logger,
+        command: "cleanup.dead-templates.purge",
+        envName,
+        results: [...templateActions, ...folderActions.map((f) => ({ ...f, kind: "folder" }))],
+        summary,
+        formatLine: (a) => "templateId" in a
+            ? `${a.status === "what-if"
+                ? "[would delete] "
+                : a.status === "failed"
+                    ? "[failed] "
+                    : a.status === "blocked"
+                        ? `[blocked × ${a.blockers?.length ?? 0}] `
+                        : ""}${a.fullName ?? a.name}${a.error ? ` — ${a.error}` : ""}${a.status === "blocked" && a.blockers && a.blockers.length > 0
+                ? ` — ${a.blockers
+                    .slice(0, 3)
+                    .map((b) => `${b.referenceKind}:${b.path ?? b.name}`)
+                    .join(", ")}${a.blockers.length > 3 ? "…" : ""}`
+                : ""}`
+            : `${a.status === "what-if" ? "[would delete folder] " : a.status === "failed" ? "[failed folder] " : "[folder] "}${a.path}${a.error ? ` — ${a.error}` : ""}`,
+        extra: {
+            root,
+            whatIf: Boolean(options.whatIf),
+            templatePurgedCount: purged,
+            templateFailedCount: failed,
+            templateBlockedCount: blocked,
+            foldersRemovedCount: foldersRemoved,
+        },
+        options,
+    });
+    return { templates: templateActions, folders: folderActions };
+};
+exports.runCleanupDeadTemplates = runCleanupDeadTemplates;

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

@@ -0,0 +1,86 @@
+import { type DuplicatesGroup } from "../audit/duplicates";
+import { type ReferenceReport } from "../audit/references";
+import { type HygieneCommonOptions } from "../shared";
+export type DuplicatesKeepRule = "oldest" | "newest" | "shortest-path" | "interactive";
+export interface CleanupDuplicatesOptions extends HygieneCommonOptions {
+    root?: string;
+    index?: string;
+    limit?: number;
+    includeSystem?: boolean;
+    includeSystemFields?: boolean;
+    language?: string;
+    batchSize?: number;
+    minGroupSize?: number;
+    /**
+     * Which member of each duplicate group survives. Default `oldest`
+     * (created-date) — the original wins, most likely the one with
+     * inbound refs.
+     */
+    keepRule?: DuplicatesKeepRule;
+    /** Concurrency for delete calls. Default 4. */
+    concurrency?: number;
+    whatIf?: boolean;
+    allowWrite?: boolean;
+    /** Required when `keepRule === "interactive"` and stdin isn't a TTY. */
+    nonInteractive?: boolean;
+    /**
+     * Skip the inbound-reference pre-flight. Use when the operator
+     * knows refs to dupes are acceptable (e.g. a content migration that
+     * will rebuild refs separately). The pre-flight is enabled by
+     * default so a dupe delete doesn't silently break content links;
+     * `audit broken-links list` was the previous post-cleanup mitigation
+     * but the agent never knew to run it. Inverse: `--force` also
+     * bypasses (existing escape hatch).
+     */
+    skipRefCheck?: boolean;
+    /** Force-delete dupes even when blockers are found. */
+    force?: boolean;
+    /**
+     * Skip the internal `runAuditDuplicates` call and use this pre-
+     * computed group list as the cleanup input. Set by the CLI's
+     * `--from-stdin` flag when the operator pipes `scai hygiene audit
+     * duplicates list --json` directly into the cleanup. Eliminates the
+     * dual-discovery drift where audit and cleanup run the same hash
+     * pass twice (and could disagree on the group set when the tenant
+     * changes between calls).
+     */
+    preComputedGroups?: DuplicatesGroup[];
+}
+export interface DuplicatePurgeAction {
+    contentHash: string;
+    kept: {
+        itemId: string;
+        path: string;
+    };
+    deleted: Array<{
+        itemId: string;
+        path: string;
+        status: "deleted" | "what-if" | "failed" | "blocked";
+        error?: string;
+        /**
+         * Inbound-reference reports that blocked the delete. Populated
+         * when status is "blocked". The cleanup ran `audit references`
+         * for the dupe's itemId; the operator can resolve each pointer
+         * before re-running, or pass `--skip-ref-check` / `--force` to
+         * delete anyway and clean up dangling refs after.
+         */
+        blockers?: ReferenceReport[];
+    }>;
+}
+/**
+ * Purge duplicate items, keeping one per group according to `--keep-rule`.
+ *
+ * Strategy:
+ *   1. Run `audit duplicates` to find groups.
+ *   2. For each group, apply the keep-rule to pick the survivor.
+ *   3. Delete the rest via `deleteItem(permanently: true)`.
+ *
+ * Notes:
+ *   - **Inbound refs to deleted dupes become broken.** Run
+ *     `audit broken-links list` after a purge — the duplicates that
+ *     other content pointed to leave dangling references behind.
+ *   - With `--keep-rule interactive`, the command prompts per group.
+ *     Honors `s`/`skip` per-group to leave a group untouched.
+ *     Requires a TTY; pass any other keep-rule when scripting.
+ */
+export declare const runCleanupDuplicates: (options: CleanupDuplicatesOptions) => Promise<DuplicatePurgeAction[]>;

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

@@ -0,0 +1,189 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCleanupDuplicates = void 0;
+const node_readline_1 = __importDefault(require("node:readline"));
+const cli_tasks_1 = require("../../../shared/cli-tasks");
+const errors_1 = require("../../../shared/errors");
+const duplicates_1 = require("../audit/duplicates");
+const references_1 = require("../audit/references");
+const shared_1 = require("../shared");
+const pickByRule = (group, rule) => {
+    const sorted = [...group.members];
+    switch (rule) {
+        case "oldest":
+            sorted.sort((a, b) => {
+                const aT = a.createdDate ? Date.parse(a.createdDate) : Number.POSITIVE_INFINITY;
+                const bT = b.createdDate ? Date.parse(b.createdDate) : Number.POSITIVE_INFINITY;
+                return aT - bT;
+            });
+            break;
+        case "newest":
+            sorted.sort((a, b) => {
+                const aT = a.updatedDate ? Date.parse(a.updatedDate) : 0;
+                const bT = b.updatedDate ? Date.parse(b.updatedDate) : 0;
+                return bT - aT;
+            });
+            break;
+        case "shortest-path":
+            sorted.sort((a, b) => {
+                const lenDiff = a.path.length - b.path.length;
+                return lenDiff !== 0 ? lenDiff : a.path.localeCompare(b.path);
+            });
+            break;
+    }
+    return { kept: sorted[0], rest: sorted.slice(1) };
+};
+const promptForKeep = async (group) => {
+    const rl = node_readline_1.default.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        process.stdout.write(`\nDuplicate group [${group.contentHash}] — ${group.count} copies:\n`);
+        group.members.forEach((m, i) => {
+            process.stdout.write(`  [${i + 1}] ${m.path}${m.createdDate ? ` (created ${m.createdDate.slice(0, 10)})` : ""}\n`);
+        });
+        process.stdout.write(`  [s]kip group\nKeep which? [1-${group.members.length}/s]: `);
+        const answer = await new Promise((resolve) => rl.question("", (a) => resolve(a.trim().toLowerCase())));
+        if (answer === "s" || answer === "skip") {
+            // Skip = keep first, delete none (signaled by returning empty rest).
+            return { kept: group.members[0], rest: [] };
+        }
+        const idx = parseInt(answer, 10) - 1;
+        if (!Number.isFinite(idx) || idx < 0 || idx >= group.members.length) {
+            throw (0, errors_1.createScaiError)(`Invalid selection '${answer}' for group ${group.contentHash}.`, "INPUT_INVALID");
+        }
+        return {
+            kept: group.members[idx],
+            rest: group.members.filter((_, i) => i !== idx),
+        };
+    }
+    finally {
+        rl.close();
+    }
+};
+/**
+ * Purge duplicate items, keeping one per group according to `--keep-rule`.
+ *
+ * Strategy:
+ *   1. Run `audit duplicates` to find groups.
+ *   2. For each group, apply the keep-rule to pick the survivor.
+ *   3. Delete the rest via `deleteItem(permanently: true)`.
+ *
+ * Notes:
+ *   - **Inbound refs to deleted dupes become broken.** Run
+ *     `audit broken-links list` after a purge — the duplicates that
+ *     other content pointed to leave dangling references behind.
+ *   - With `--keep-rule interactive`, the command prompts per group.
+ *     Honors `s`/`skip` per-group to leave a group untouched.
+ *     Requires a TTY; pass any other keep-rule when scripting.
+ */
+const runCleanupDuplicates = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const keepRule = options.keepRule ?? "oldest";
+    if (keepRule === "interactive") {
+        if (!process.stdin.isTTY || options.nonInteractive) {
+            throw (0, errors_1.createScaiError)("--keep-rule interactive requires a TTY (cannot run with --non-interactive or piped stdin).", "INPUT_INVALID", { hint: "Pass --keep-rule oldest|newest|shortest-path for CI / agent use." });
+        }
+    }
+    const { envName, root: rootConfig, client } = (0, shared_1.resolveTenant)(options);
+    if (!options.whatIf) {
+        (0, shared_1.ensureAllowWriteForCleanup)(rootConfig, envName, options.allowWrite, "cleanup-duplicates");
+    }
+    else if (!logger.isJson()) {
+        logger.info("What-if mode active — no items will be deleted.", "yellow");
+    }
+    // Reuse audit to find groups — unless the caller piped in an audit
+    // envelope via --from-stdin. Skipping the internal audit prevents the
+    // tenant-state-changed-between-calls drift the dual-discovery model
+    // could surface, and shaves the full discovery scan off the cleanup.
+    const groups = options.preComputedGroups ??
+        (await (0, duplicates_1.runAuditDuplicates)({ ...options, json: true, quiet: true }));
+    const actions = [];
+    for (const group of groups) {
+        let selection;
+        if (keepRule === "interactive") {
+            selection = await promptForKeep(group);
+        }
+        else {
+            selection = pickByRule(group, keepRule);
+        }
+        const action = {
+            contentHash: group.contentHash,
+            kept: { itemId: selection.kept.itemId, path: selection.kept.path },
+            deleted: [],
+        };
+        // Pre-flight: scan content for inbound refs to each deletion
+        // candidate. `audit references` with `cache: true` shares its
+        // field-cache across back-to-back calls so only the first scan
+        // pays the full O(items × fields) cost; subsequent dupes hit the
+        // warm cache. `--skip-ref-check` or `--force` opts out for
+        // operators who know inbound refs are acceptable.
+        const runRefCheck = !options.skipRefCheck && !options.force && !options.whatIf;
+        const deleteResults = await (0, cli_tasks_1.mapWithConcurrency)(selection.rest, async (m) => {
+            if (runRefCheck) {
+                const refs = await (0, references_1.runAuditReferences)({
+                    ...options,
+                    to: m.itemId,
+                    silent: true,
+                    cache: true,
+                });
+                if (refs.length > 0) {
+                    return {
+                        itemId: m.itemId,
+                        path: m.path,
+                        status: "blocked",
+                        blockers: refs,
+                    };
+                }
+            }
+            if (options.whatIf) {
+                return { itemId: m.itemId, path: m.path, status: "what-if" };
+            }
+            try {
+                await client.deleteItem({
+                    itemId: (0, shared_1.dashifyItemId)(m.itemId),
+                    permanently: true,
+                });
+                return { itemId: m.itemId, path: m.path, status: "deleted" };
+            }
+            catch (error) {
+                return {
+                    itemId: m.itemId,
+                    path: m.path,
+                    status: "failed",
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        }, options.concurrency ?? 4);
+        action.deleted = deleteResults;
+        actions.push(action);
+    }
+    const totalDeleted = actions.reduce((n, a) => n + a.deleted.filter((d) => d.status === "deleted").length, 0);
+    const totalFailed = actions.reduce((n, a) => n + a.deleted.filter((d) => d.status === "failed").length, 0);
+    const totalBlocked = actions.reduce((n, a) => n + a.deleted.filter((d) => d.status === "blocked").length, 0);
+    const blockedSuffix = totalBlocked > 0 ? `; ${totalBlocked} blocked by inbound refs` : "";
+    const summary = options.whatIf
+        ? `Plan: would delete ${actions.reduce((n, a) => n + a.deleted.length, 0)} duplicate item${actions.reduce((n, a) => n + a.deleted.length, 0) === 1 ? "" : "s"} across ${actions.length} group${actions.length === 1 ? "" : "s"} (keep-rule: ${keepRule}).`
+        : `Deleted ${totalDeleted} duplicate${totalDeleted === 1 ? "" : "s"} across ${actions.length} group${actions.length === 1 ? "" : "s"} (keep-rule: ${keepRule})${totalFailed > 0 ? `; ${totalFailed} failed` : ""}${blockedSuffix}.`;
+    (0, shared_1.printReport)({
+        logger,
+        command: "cleanup.duplicates.purge",
+        envName,
+        results: actions,
+        summary,
+        formatLine: (a) => `[${a.contentHash}] keep ${a.kept.path}; deleted ${a.deleted
+            .map((d) => `${d.status === "deleted" ? "" : `[${d.status}] `}${d.path}`)
+            .join(", ")}`,
+        extra: {
+            keepRule,
+            whatIf: Boolean(options.whatIf),
+            groupCount: actions.length,
+            deletedCount: totalDeleted,
+            failedCount: totalFailed,
+        },
+        options,
+    });
+    return actions;
+};
+exports.runCleanupDuplicates = runCleanupDuplicates;

package/dist/hygiene/tasks/cleanup/empty-folders.d.ts

@@ -0,0 +1,75 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface CleanupEmptyFoldersOptions extends HygieneCommonOptions {
+    /** Required. Root path to clean up under. */
+    root: string;
+    /** Cap on deletions. Default 500. */
+    maxDeletions?: number;
+    whatIf?: boolean;
+    allowWrite?: boolean;
+    baseline?: boolean;
+    output?: string;
+    format?: "json" | "csv" | "markdown";
+    /**
+     * Permit operating against `/sitecore/system` and templates roots.
+     * Off by default. Required even with `--what-if` to avoid surprise.
+     */
+    force?: boolean;
+    /**
+     * Additional template IDs to treat as folders, beyond the well-known
+     * Sitecore folder templates. Accept any case + dashed/curly/flat
+     * GUID form — values are normalised before comparison. Repeat or
+     * comma-separate at the CLI layer.
+     *
+     * Without an allowlist, the cleanup would delete *any* leaf item
+     * (Pages, Datasources, etc.) the moment its children were emptied —
+     * the original implementation had exactly this footgun in production.
+     */
+    folderTemplateIds?: string[];
+    /**
+     * Treat any item whose template name matches this regular expression
+     * as a folder for deletion purposes. Off by default. Use with care —
+     * a permissive pattern (e.g. `.*Folder.*`) will sweep "Folder Settings"
+     * or "Folder Mapping" templates alongside actual folders. The default
+     * folder-id allowlist is the safer surface for most operators.
+     */
+    templateNamePattern?: string;
+    /**
+     * Disable the folder-template gate and revert to the pre-2026
+     * behaviour of deleting any leaf item with zero children. Provided
+     * only as an emergency escape hatch — pair with `--what-if` first
+     * and a tightly scoped `--root` to avoid mass deletion of Page items.
+     */
+    anyTemplate?: boolean;
+}
+export interface EmptyFolderAction {
+    itemId: string;
+    path: string;
+    status: "deleted" | "what-if" | "failed";
+    error?: string;
+}
+/**
+ * Delete folder-like items that have no children, recursively
+ * bottom-up under `--root`.
+ *
+ * Strategy:
+ *   1. Walk the tree depth-first via `getChildren`.
+ *   2. At each node, recurse; if every child reports as "empty after
+ *      cleanup" (i.e. itself got deleted), and the node itself has
+ *      no remaining children, delete the node.
+ *   3. Continue bubbling up — parent may become empty after its
+ *      children are deleted.
+ *
+ * Safety rails:
+ *   - `--root` required; no tenant-wide form.
+ *   - `/sitecore/system`, `/sitecore/templates`, `/sitecore/layout`
+ *     refused without `--force`.
+ *   - `--allow-write` (or env `allowWrite`) required outside
+ *     `--what-if`.
+ *   - `--max-deletions` caps total folder removals.
+ *   - Items that have content (non-folder template, fields with
+ *     values) are NOT touched — we ONLY delete items with zero
+ *     children, regardless of their template. If a "Page" item has
+ *     no children, the operator should clean it via `cleanup
+ *     duplicates` or similar, not here.
+ */
+export declare const runCleanupEmptyFolders: (options: CleanupEmptyFoldersOptions) => Promise<EmptyFolderAction[]>;