@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

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

@@ -0,0 +1,76 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface CleanupVersionsPruneOptions extends HygieneCommonOptions {
+    /**
+     * Required. Number of most-recent versions to keep per (item, language).
+     * Older versions are deleted. Must be >= 1.
+     */
+    keep: number;
+    /**
+     * Required scope. Prune is restricted to descendants of this content
+     * path — there's no tenant-wide form. This is a guardrail: a stray
+     * `--keep 1` against `/sitecore` would otherwise mass-delete platform
+     * version history.
+     */
+    root: string;
+    /**
+     * Restrict pruning to one language. Defaults to all languages found
+     * for each item.
+     */
+    language?: string;
+    /** Cap on items inspected. Default 5000. */
+    limit?: number;
+    /** Override the search index. */
+    index?: string;
+    /** Concurrency for version reads + deletes. Default 4. */
+    concurrency?: number;
+    /** Include system items. Off by default. */
+    includeSystem?: boolean;
+    whatIf?: boolean;
+    allowWrite?: boolean;
+    /**
+     * Override the default safety guard that refuses to operate against
+     * `/sitecore/system` or `/sitecore/templates` even when those are the
+     * `--root`. Off by default. Set only when intentionally pruning
+     * platform-area versions.
+     */
+    force?: boolean;
+}
+export interface VersionPruneAction {
+    itemId: string;
+    path: string;
+    language: string;
+    versionsBefore: number;
+    versionsAfter: number;
+    deletedVersions: number[];
+    errors: string[];
+}
+/**
+ * Prune per-item, per-language version history down to the N most recent
+ * versions.
+ *
+ * Safety rails:
+ *   - `--root` is required. The command never operates tenant-wide
+ *     because a stray `--keep 1` would mass-delete platform versions.
+ *   - `--keep` must be >= 1. Setting it to zero would orphan a language
+ *     entry with no versions (the very pattern `audit language-data
+ *     list` flags).
+ *   - The `/sitecore/system`, `/sitecore/templates/System`, and
+ *     `/sitecore/layout/Layouts/System` subtrees are protected; the
+ *     prune refuses to operate on those paths unless `--force` is also
+ *     set.
+ *   - Without `--what-if`, the environment must have `allowWrite: true`
+ *     (or `--allow-write` passed). Same contract as serialization push
+ *     / recipe push.
+ *
+ * Behavior:
+ *   1. Search for items under `--root` (one row per language). For each
+ *      observed (item, language), fetch the version list via
+ *      `getItemVersions`. If the list has more than `--keep` entries,
+ *      schedule deletes for the oldest (`length - keep`) entries.
+ *   2. Under `--what-if`, just emit the plan and return.
+ *   3. Otherwise, execute `deleteItemVersion` sequentially per item
+ *      (concurrent across items, bounded by `--concurrency`). Failures
+ *      collect into the item's `errors` array but don't abort other
+ *      items — the report shows partial success.
+ */
+export declare const runCleanupVersionsPrune: (options: CleanupVersionsPruneOptions) => Promise<VersionPruneAction[]>;

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

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCleanupVersionsPrune = 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",
+];
+/**
+ * Prune per-item, per-language version history down to the N most recent
+ * versions.
+ *
+ * Safety rails:
+ *   - `--root` is required. The command never operates tenant-wide
+ *     because a stray `--keep 1` would mass-delete platform versions.
+ *   - `--keep` must be >= 1. Setting it to zero would orphan a language
+ *     entry with no versions (the very pattern `audit language-data
+ *     list` flags).
+ *   - The `/sitecore/system`, `/sitecore/templates/System`, and
+ *     `/sitecore/layout/Layouts/System` subtrees are protected; the
+ *     prune refuses to operate on those paths unless `--force` is also
+ *     set.
+ *   - Without `--what-if`, the environment must have `allowWrite: true`
+ *     (or `--allow-write` passed). Same contract as serialization push
+ *     / recipe push.
+ *
+ * Behavior:
+ *   1. Search for items under `--root` (one row per language). For each
+ *      observed (item, language), fetch the version list via
+ *      `getItemVersions`. If the list has more than `--keep` entries,
+ *      schedule deletes for the oldest (`length - keep`) entries.
+ *   2. Under `--what-if`, just emit the plan and return.
+ *   3. Otherwise, execute `deleteItemVersion` sequentially per item
+ *      (concurrent across items, bounded by `--concurrency`). Failures
+ *      collect into the item's `errors` array but don't abort other
+ *      items — the report shows partial success.
+ */
+const runCleanupVersionsPrune = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    if (!options.root) {
+        throw (0, errors_1.createScaiError)("--root is required for versions prune.", "INPUT_INVALID", {
+            hint: "Pass --root '/sitecore/content/<site>' to scope the prune.",
+        });
+    }
+    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 prune 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, "cleanup-versions-prune");
+    }
+    const concurrency = options.concurrency ?? 4;
+    const includeSystem = Boolean(options.includeSystem);
+    const limit = options.limit ?? 5000;
+    if (options.whatIf && !logger.isJson()) {
+        logger.info("What-if mode active — no versions will be deleted.", "yellow");
+    }
+    // Resolve root → itemId for the search filter.
+    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", {
+            hint: "Verify the path exists in the tenant before pruning.",
+        });
+    }
+    // Enumerate candidates: (item, language) pairs found via the index.
+    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);
+        const keepFrom = sorted.slice(0, options.keep);
+        const deleteFrom = sorted.slice(options.keep);
+        return {
+            itemId: p.itemId,
+            path: p.path,
+            language: p.language,
+            keepFrom: keepFrom.map((v) => ({ version: v.version })),
+            deleteFrom: deleteFrom.map((v) => ({ version: 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.deleteFrom.length,
+            versionsAfter: plan.keepFrom.length,
+            deletedVersions: [],
+            errors: [],
+        };
+        if (options.whatIf) {
+            action.deletedVersions = plan.deleteFrom.map((v) => v.version);
+            return action;
+        }
+        // Delete sequentially per item — Authoring API serialises version
+        // mutations per item anyway, and a parallel delete inside one item
+        // can race on the version index.
+        for (const v of plan.deleteFrom) {
+            try {
+                await client.deleteItemVersion({
+                    itemId: (0, shared_1.dashifyItemId)(plan.itemId),
+                    language: plan.language,
+                    version: v.version,
+                });
+                action.deletedVersions.push(v.version);
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                action.errors.push(`v${v.version}: ${msg}`);
+            }
+        }
+        action.versionsAfter = action.versionsBefore - action.deletedVersions.length;
+        return action;
+    }, concurrency);
+    actions.sort((a, b) => a.path.localeCompare(b.path));
+    const totalDeleted = actions.reduce((sum, a) => sum + a.deletedVersions.length, 0);
+    const totalErrors = actions.reduce((sum, a) => sum + a.errors.length, 0);
+    const summary = options.whatIf
+        ? `Plan: would delete ${totalDeleted} version(s) across ${actions.length} item-language pair(s).`
+        : `Deleted ${totalDeleted} version(s) across ${actions.length} item-language pair(s)${totalErrors > 0 ? ` (${totalErrors} error(s))` : ""}.`;
+    (0, shared_1.printReport)({
+        logger,
+        command: "cleanup.versions.prune",
+        envName,
+        results: actions,
+        summary,
+        formatLine: (a) => {
+            const deleted = a.deletedVersions.length
+                ? `${a.deletedVersions.length} version${a.deletedVersions.length === 1 ? "" : "s"} (${a.deletedVersions.join(",")})`
+                : "none";
+            const errors = a.errors.length ? ` errors: ${a.errors.join(" / ")}` : "";
+            return `${a.path} @${a.language}: keep ${a.versionsAfter}, deleted ${deleted}.${errors}`;
+        },
+        extra: {
+            root: options.root,
+            keep: options.keep,
+            language: options.language ?? null,
+            whatIf: Boolean(options.whatIf),
+            scannedCount: scanned,
+            plannedCount: plansWithWork.length,
+            deletedCount: totalDeleted,
+            errorCount: totalErrors,
+        },
+        options,
+    });
+    return actions;
+};
+exports.runCleanupVersionsPrune = runCleanupVersionsPrune;

package/dist/hygiene/tasks/cleanup/workflow-advance.d.ts

@@ -0,0 +1,76 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface CleanupWorkflowAdvanceOptions extends HygieneCommonOptions {
+    /**
+     * Days since last update. Items in workflow that haven't been
+     * touched for this long are eligible for the advance. Default 30.
+     */
+    staleDays?: number;
+    /**
+     * Required. Workflow command name to execute (case-insensitive).
+     * Resolved against the item's active workflow. E.g. "Submit",
+     * "Approve", "Reject". The cleanup task fails the item if its
+     * workflow doesn't expose this command.
+     */
+    commandName: string;
+    /** Comment recorded with the workflow execution (audit trail). */
+    comments?: string;
+    /** Content root to scope. Default `/sitecore/content`. */
+    root?: string;
+    /** Cap on items advanced. Default 100. */
+    maxAdvances?: number;
+    /** Restrict by workflow state name (e.g. "Draft"). */
+    fromState?: string;
+    index?: string;
+    limit?: number;
+    includeSystem?: boolean;
+    pageParallelism?: number;
+    concurrency?: number;
+    exclude?: string[];
+    since?: string;
+    whatIf?: boolean;
+    allowWrite?: boolean;
+    baseline?: boolean;
+    output?: string;
+    format?: "json" | "csv" | "markdown";
+}
+export interface WorkflowAdvanceAction {
+    itemId: string;
+    path: string;
+    workflowName: string | null;
+    fromState: string | null;
+    toState: string | null;
+    commandUsed: string;
+    status: "advanced" | "what-if" | "failed" | "skipped-no-command";
+    error?: string;
+}
+/**
+ * Advance items stuck in a workflow state by executing the chosen
+ * workflow command. Soft counterpart to `audit stale-workflow list`.
+ *
+ * Strategy:
+ *   1. Use search to enumerate items under `--root`, filtered by
+ *      `updatedDate < now - --stale-days`.
+ *   2. For each candidate, fetch its `ItemWorkflow` to confirm it's
+ *      in a non-final state. Optionally filter by `--from-state`.
+ *   3. Resolve `--command-name` against the item's workflow
+ *      (`getWorkflowCommands`); pick the first command whose
+ *      `displayName` matches case-insensitively.
+ *   4. Call `executeWorkflowCommand`. Capture nextStateId for the
+ *      report.
+ *
+ * Safety rails:
+ *   - `--max-advances` caps the blast radius (default 100).
+ *   - `--what-if` reports the plan without executing.
+ *   - `--allow-write` (or env `allowWrite`) required outside `--what-if`.
+ *   - `--command-name` is required. There is no "auto-advance to
+ *     next state" default — workflows can be arbitrary, and silently
+ *     picking a command could approve content prematurely.
+ *
+ * Notes:
+ *   - The Authoring API's `executeWorkflowCommand` doesn't reveal
+ *     which commands are valid in the current state. We try the
+ *     requested command and surface the API's success/failure verbatim.
+ *   - Workflow command lookups are cached per-workflow within one
+ *     run (avoid N round trips for the same workflow's commands).
+ */
+export declare const runCleanupWorkflowAdvance: (options: CleanupWorkflowAdvanceOptions) => Promise<WorkflowAdvanceAction[]>;

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

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCleanupWorkflowAdvance = void 0;
+const cli_tasks_1 = require("../../../shared/cli-tasks");
+const errors_1 = require("../../../shared/errors");
+const resolve_command_1 = require("../../../workflow/api/resolve-command");
+const shared_1 = require("../shared");
+/**
+ * Advance items stuck in a workflow state by executing the chosen
+ * workflow command. Soft counterpart to `audit stale-workflow list`.
+ *
+ * Strategy:
+ *   1. Use search to enumerate items under `--root`, filtered by
+ *      `updatedDate < now - --stale-days`.
+ *   2. For each candidate, fetch its `ItemWorkflow` to confirm it's
+ *      in a non-final state. Optionally filter by `--from-state`.
+ *   3. Resolve `--command-name` against the item's workflow
+ *      (`getWorkflowCommands`); pick the first command whose
+ *      `displayName` matches case-insensitively.
+ *   4. Call `executeWorkflowCommand`. Capture nextStateId for the
+ *      report.
+ *
+ * Safety rails:
+ *   - `--max-advances` caps the blast radius (default 100).
+ *   - `--what-if` reports the plan without executing.
+ *   - `--allow-write` (or env `allowWrite`) required outside `--what-if`.
+ *   - `--command-name` is required. There is no "auto-advance to
+ *     next state" default — workflows can be arbitrary, and silently
+ *     picking a command could approve content prematurely.
+ *
+ * Notes:
+ *   - The Authoring API's `executeWorkflowCommand` doesn't reveal
+ *     which commands are valid in the current state. We try the
+ *     requested command and surface the API's success/failure verbatim.
+ *   - Workflow command lookups are cached per-workflow within one
+ *     run (avoid N round trips for the same workflow's commands).
+ */
+const runCleanupWorkflowAdvance = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    if (!options.commandName) {
+        throw (0, errors_1.createScaiError)("--command-name is required.", "INPUT_INVALID");
+    }
+    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 workflow commands will be executed.", "yellow");
+    }
+    const days = options.staleDays ?? 30;
+    const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+    const knobs = (0, shared_1.resolveHygieneKnobs)(options);
+    const concurrency = options.concurrency ?? knobs.concurrency;
+    const maxAdvances = options.maxAdvances ?? 100;
+    const root = options.root ?? "/sitecore/content";
+    const includeSystem = Boolean(options.includeSystem);
+    const fromState = options.fromState?.toLowerCase();
+    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;
+    const candidates = [];
+    let scanned = 0;
+    for await (const r of client.searchAll({
+        index: options.index,
+        latestVersionOnly: true,
+        ...(rootItemId && { searchStatement: (0, shared_1.buildPathFilterStatement)(rootItemId) }),
+    }, 100, knobs.pageParallelism)) {
+        if (!includeSystem && (0, shared_1.isSystemPath)(r.path))
+            continue;
+        scanned += 1;
+        if (!r.updatedDate)
+            continue;
+        const t = Date.parse(r.updatedDate);
+        if (!Number.isFinite(t) || t >= cutoff)
+            continue;
+        candidates.push({ itemId: (0, shared_1.normalizeItemId)(r.itemId), path: r.path });
+        if (candidates.length >= (options.limit ?? 5000))
+            break;
+    }
+    logger.verbose(`Scanned ${scanned} items; ${candidates.length} stale candidates.`);
+    // Phase 2: per-candidate check + advance.
+    const actions = (await (0, cli_tasks_1.mapWithConcurrency)(candidates, async (c, idx) => {
+        if (idx >= maxAdvances)
+            return null;
+        const wf = await client.getItemWorkflow(c.itemId, c.path);
+        if (!wf || !wf.workflowId || wf.stateIsFinal)
+            return null;
+        if (fromState && wf.stateName?.toLowerCase() !== fromState)
+            return null;
+        // Commands depend on the item's current state (Authoring API
+        // requires `commands(query: {item})`), so caching across items
+        // isn't valid.
+        const command = await (0, resolve_command_1.resolveWorkflowCommandId)(client, {
+            workflowId: wf.workflowId,
+            itemId: (0, shared_1.dashifyItemId)(c.itemId),
+            commandName: options.commandName,
+        });
+        if (!command) {
+            return {
+                itemId: c.itemId,
+                path: c.path,
+                workflowName: wf.workflowName,
+                fromState: wf.stateName,
+                toState: null,
+                commandUsed: options.commandName,
+                status: "skipped-no-command",
+                error: `Workflow '${wf.workflowName}' has no command named '${options.commandName}'.`,
+            };
+        }
+        if (options.whatIf) {
+            return {
+                itemId: c.itemId,
+                path: c.path,
+                workflowName: wf.workflowName,
+                fromState: wf.stateName,
+                toState: null,
+                commandUsed: command.displayName,
+                status: "what-if",
+            };
+        }
+        try {
+            const res = await client.executeWorkflowCommand({
+                commandId: command.commandId,
+                itemId: (0, shared_1.dashifyItemId)(c.itemId),
+                comments: options.comments,
+            });
+            return {
+                itemId: c.itemId,
+                path: c.path,
+                workflowName: wf.workflowName,
+                fromState: wf.stateName,
+                toState: res.nextStateId,
+                commandUsed: command.displayName,
+                status: res.successful ? "advanced" : "failed",
+                ...(res.successful ? {} : { error: res.message ?? "unknown failure" }),
+            };
+        }
+        catch (error) {
+            return {
+                itemId: c.itemId,
+                path: c.path,
+                workflowName: wf.workflowName,
+                fromState: wf.stateName,
+                toState: null,
+                commandUsed: command.displayName,
+                status: "failed",
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }, concurrency)).filter((a) => a !== null);
+    const advanced = actions.filter((a) => a.status === "advanced").length;
+    const failed = actions.filter((a) => a.status === "failed").length;
+    const skipped = actions.filter((a) => a.status === "skipped-no-command").length;
+    const summary = options.whatIf
+        ? `Plan: would advance ${actions.length} item${actions.length === 1 ? "" : "s"}.`
+        : `Advanced ${advanced}, ${failed} failed, ${skipped} skipped (no matching command).`;
+    (0, shared_1.printReport)({
+        logger,
+        command: "cleanup.workflow.advance",
+        envName,
+        results: actions,
+        summary,
+        formatLine: (a) => `${a.status === "what-if" ? "[would advance] " : a.status === "failed" ? "[failed] " : a.status === "skipped-no-command" ? "[skipped] " : ""}${a.path} — ${a.workflowName}/${a.fromState} ${a.toState ? `→ ${a.toState}` : ""}${a.error ? ` — ${a.error}` : ""}`,
+        extra: {
+            root,
+            staleDays: days,
+            commandName: options.commandName,
+            fromState: options.fromState ?? null,
+            whatIf: Boolean(options.whatIf),
+            maxAdvances,
+            scannedCount: scanned,
+            advancedCount: advanced,
+            failedCount: failed,
+            skippedCount: skipped,
+        },
+        options,
+    });
+    return actions;
+};
+exports.runCleanupWorkflowAdvance = runCleanupWorkflowAdvance;

package/dist/hygiene/tasks/cleanup/workflow-apply.d.ts

@@ -0,0 +1,97 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface CleanupWorkflowApplyOptions extends HygieneCommonOptions {
+    /**
+     * Workflow ref — GUID, content-tree path, or display/item name.
+     * Required. Same resolution as `scai content workflow apply` /
+     * `scai content workflow inspect`.
+     */
+    workflow: string;
+    /**
+     * Optional target state ref (GUID or state name). Defaults to the
+     * workflow's `__Initial state`.
+     */
+    state?: string;
+    /**
+     * Optional template filter. Accepts a Sitecore template GUID or
+     * absolute content-tree path (e.g.
+     * `/sitecore/templates/Foundation/Article`). When set, only items
+     * whose `_template` matches are attached. Unset = every item under
+     * `--root` is eligible (subject to the other filters).
+     */
+    template?: string;
+    /**
+     * When true, overwrite the assignment on items already attached to
+     * any workflow. Default false — items already on a workflow are
+     * skipped with status `skipped-already-attached` so the verb defaults
+     * to a safe backfill.
+     */
+    reattach?: boolean;
+    /**
+     * Optional stale-days filter — only items not updated for at least
+     * this many days are eligible. Unset = no recency filter.
+     */
+    staleDays?: number;
+    /** Content root to scope. Default `/sitecore/content`. */
+    root?: string;
+    /** Cap on items attached per run. Default 100. */
+    maxApplies?: number;
+    /** Cap on items inspected. Default 5000. */
+    limit?: number;
+    /** Override the search index. */
+    index?: string;
+    /** Include `/sitecore/system` results. Off by default. */
+    includeSystem?: boolean;
+    pageParallelism?: number;
+    concurrency?: number;
+    exclude?: string[];
+    since?: string;
+    whatIf?: boolean;
+    allowWrite?: boolean;
+    baseline?: boolean;
+    output?: string;
+    format?: "json" | "csv" | "markdown";
+}
+export type WorkflowApplyActionStatus = "applied" | "what-if" | "failed" | "skipped-already-attached" | "skipped-template-mismatch";
+export interface WorkflowApplyAction {
+    itemId: string;
+    path: string;
+    templateId: string | null;
+    workflowItemId: string;
+    workflowName: string;
+    stateItemId: string;
+    stateName: string;
+    status: WorkflowApplyActionStatus;
+    /** Workflow currently attached, when present and we're not reattaching. */
+    existingWorkflowId?: string | null;
+    /** State currently attached, when present and we're not reattaching. */
+    existingStateId?: string | null;
+    error?: string;
+}
+/**
+ * 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.
+ */
+export declare const runCleanupWorkflowApply: (options: CleanupWorkflowApplyOptions) => Promise<WorkflowApplyAction[]>;