@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/hygiene/tasks/audit/unused-media.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuditUnusedMedia = void 0;
+const shared_1 = require("../shared");
+const client_1 = require("../../api/client");
+/**
+ * Audit `/sitecore/media library` for media items that aren't referenced
+ * by any content item.
+ *
+ * Strategy (two-pass scan, both via the search index):
+ *
+ *   1. Enumerate every media item under `--media-root`. These become
+ *      candidates for "unused."
+ *   2. Enumerate every non-media item under `--reference-root` (default
+ *      `/sitecore/content`). For each, fetch all fields in batches and
+ *      run `extractMediaRefs` over field values. The output is the set
+ *      of media itemIds that *are* referenced.
+ *   3. Subtract: candidates minus referenced = unused media.
+ *
+ * Notes:
+ *   - The Authoring API exposes neither a "where-used" query nor a link
+ *     database read surface. This is the cheapest correct approach.
+ *   - False positives are possible when a media item is referenced from
+ *     content stored OUTSIDE `--reference-root` (e.g. presentation
+ *     definitions under `/sitecore/layout` or rendering parameters in
+ *     non-content trees). Operators with mixed content/layout media
+ *     references should re-run with `--reference-root /sitecore`.
+ *   - References from RichText `<link linktype="media">` tags and Image
+ *     field XML (`<image mediaid="...">`) are recognised; bare GUIDs in
+ *     Multilist fields targeting media are also captured by
+ *     `extractInternalRefs` and filtered against the candidates set.
+ */
+const runAuditUnusedMedia = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const { envName, client } = (0, shared_1.resolveTenant)(options);
+    const mediaRoot = options.mediaRoot ?? client_1.MEDIA_LIBRARY_ROOT;
+    const referenceRoot = options.referenceRoot ?? "/sitecore/content";
+    const mediaLimit = options.mediaLimit ?? 5000;
+    const referenceLimit = options.referenceLimit ?? 10000;
+    const knobs = (0, shared_1.resolveHygieneKnobs)(options);
+    // Resolve roots → itemIds for `_path` filter.
+    const resolveRootItemId = async (path) => {
+        const r = await client.search({
+            index: options.index,
+            paging: { pageSize: 1 },
+            searchStatement: {
+                criteria: { field: "_fullpath", value: path.toLowerCase(), criteriaType: "EXACT" },
+            },
+        });
+        return r.results[0]?.itemId;
+    };
+    const mediaRootId = await resolveRootItemId(mediaRoot);
+    const referenceRootId = await resolveRootItemId(referenceRoot);
+    if (!mediaRootId) {
+        logger.warn(`Media root '${mediaRoot}' not found in index; scanning full master DB.`);
+    }
+    if (!referenceRootId) {
+        logger.warn(`Reference root '${referenceRoot}' not found in index; scanning full master DB.`);
+    }
+    // Pass 1 — enumerate media item candidates (no fields needed).
+    const candidates = new Map();
+    let mediaCount = 0;
+    for await (const r of client.searchAll({
+        index: options.index,
+        latestVersionOnly: true,
+        ...(mediaRootId && { searchStatement: (0, shared_1.buildPathFilterStatement)(mediaRootId) }),
+    }, 100, knobs.pageParallelism)) {
+        // The `_path` CONTAINS filter on `mediaRootId` already restricts the
+        // result set to descendants of the media library. We do NOT add a
+        // string-prefix path check here because the XM Cloud search index
+        // returns *media paths* (e.g. "/default website/images/...") rather
+        // than full content-tree paths for items under
+        // `/sitecore/media library`. A `startsWith("/sitecore/media library/")`
+        // check would reject every result. Skip the media-library root item
+        // itself by itemId comparison — that's the only false positive.
+        if (mediaRootId && (0, shared_1.normalizeItemId)(r.itemId) === (0, shared_1.normalizeItemId)(mediaRootId))
+            continue;
+        const id = (0, shared_1.normalizeItemId)(r.itemId);
+        if (!candidates.has(id)) {
+            candidates.set(id, {
+                itemId: id,
+                path: r.path,
+                templateName: r.templateName ?? null,
+            });
+        }
+        mediaCount += 1;
+        if (mediaCount >= mediaLimit)
+            break;
+    }
+    logger.verbose(`Pass 1: ${candidates.size} media-item candidates.`);
+    // Pass 2 — enumerate reference-side items + fields via the perf-tuned helper.
+    const { scanned: referenceItems, fieldsByItemId, cache, } = await (0, shared_1.scanItemsAndFields)({
+        client,
+        envName,
+        root: referenceRoot,
+        logger,
+        options: { ...options, limit: referenceLimit, includeSystem: false },
+    });
+    logger.verbose(`Pass 2: ${referenceItems.length} reference-side items inspected.`);
+    const referenced = new Set();
+    for (const item of referenceItems) {
+        if ((0, shared_1.isSystemPath)(item.path))
+            continue;
+        const fields = fieldsByItemId.get(item.itemId);
+        if (!fields || !Array.isArray(fields))
+            continue;
+        for (const field of fields) {
+            if (!field.value)
+                continue;
+            for (const ref of (0, shared_1.extractMediaRefs)(field.value))
+                referenced.add(ref);
+            // Multilist/Treelist GUIDs that happen to point at media candidates.
+            for (const ref of (0, shared_1.extractInternalRefs)(field.value)) {
+                if (candidates.has(ref))
+                    referenced.add(ref);
+            }
+        }
+    }
+    logger.verbose(`Found ${referenced.size} distinct media refs across reference items.`);
+    await cache?.flush();
+    const unused = [];
+    for (const [id, candidate] of candidates) {
+        if (!referenced.has(id))
+            unused.push(candidate);
+    }
+    unused.sort((a, b) => a.path.localeCompare(b.path));
+    (0, shared_1.printReport)({
+        logger,
+        command: "audit.unused-media.list",
+        envName,
+        results: unused,
+        summary: `Scanned ${candidates.size} media items, ${referenceItems.length} ref-side items; ${unused.length} unused.`,
+        formatLine: (r) => `${r.path}${r.templateName ? ` (${r.templateName})` : ""}`,
+        extra: {
+            mediaRoot,
+            referenceRoot,
+            mediaScanned: candidates.size,
+            referenceScanned: referenceItems.length,
+        },
+        options,
+    });
+    return unused;
+};
+exports.runAuditUnusedMedia = runAuditUnusedMedia;

package/dist/hygiene/tasks/browse.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `runContentBrowse` — enumerate the content tree under a path.
+ *
+ * The plain "what is under here?" read the audits never offered: a
+ * bounded-depth walk of item children via the Authoring API, returning
+ * each item's name / path / id / template. Answers "what templates (or
+ * renderings, or items) do I have under X" in one call, instead of
+ * bending a quality audit to the job.
+ *
+ * Traversal-based — uses `getChildren` (an `item.children` GraphQL
+ * query), so it works on environments with no provisioned search index.
+ */
+import { type HygieneCommonOptions } from "./shared";
+/** Hard ceiling on recursion depth — bounds fan-out on wide trees. */
+export declare const MAX_BROWSE_DEPTH = 5;
+export interface ContentBrowseOptions extends HygieneCommonOptions {
+    /** Content-tree path to browse, e.g. `/sitecore/templates/Project`. */
+    path: string;
+    /** Recursion depth — 1 is direct children only. Clamped to [1, MAX_BROWSE_DEPTH]. */
+    depth?: number;
+}
+/** One item in the browse tree. */
+export interface BrowseNode {
+    itemId: string;
+    name: string;
+    path: string;
+    /** Id of the template this item is based on, or `null` when unknown. */
+    templateId: string | null;
+    /**
+     * Direct children — present when the walk recursed past this node;
+     * omitted at the depth limit (re-call `content_browse` deeper to see
+     * them).
+     */
+    children?: BrowseNode[];
+}
+export interface ContentBrowseResult {
+    path: string;
+    /** Effective depth after clamping. */
+    depth: number;
+    nodes: BrowseNode[];
+    /** Total items across every level returned. */
+    totalCount: number;
+}
+/**
+ * Walk the content tree under `path` to a bounded depth. A non-existent
+ * path resolves to an empty `nodes` list (the Authoring API returns no
+ * children) rather than throwing.
+ */
+export declare const runContentBrowse: (options: ContentBrowseOptions) => Promise<ContentBrowseResult>;

package/dist/hygiene/tasks/browse.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * `runContentBrowse` — enumerate the content tree under a path.
+ *
+ * The plain "what is under here?" read the audits never offered: a
+ * bounded-depth walk of item children via the Authoring API, returning
+ * each item's name / path / id / template. Answers "what templates (or
+ * renderings, or items) do I have under X" in one call, instead of
+ * bending a quality audit to the job.
+ *
+ * Traversal-based — uses `getChildren` (an `item.children` GraphQL
+ * query), so it works on environments with no provisioned search index.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runContentBrowse = exports.MAX_BROWSE_DEPTH = void 0;
+const cli_tasks_1 = require("../../shared/cli-tasks");
+const shared_1 = require("./shared");
+/** Hard ceiling on recursion depth — bounds fan-out on wide trees. */
+exports.MAX_BROWSE_DEPTH = 5;
+/**
+ * Walk the content tree under `path` to a bounded depth. A non-existent
+ * path resolves to an empty `nodes` list (the Authoring API returns no
+ * children) rather than throwing.
+ */
+const runContentBrowse = async (options) => {
+    const { client } = (0, shared_1.resolveTenant)(options);
+    const depth = Math.min(Math.max(1, options.depth ?? 1), exports.MAX_BROWSE_DEPTH);
+    // Browse exposes no perf knobs of its own — take the project defaults.
+    const knobs = (0, shared_1.resolveHygieneKnobs)({});
+    let totalCount = 0;
+    const walk = async (selector, remaining) => {
+        const children = await client.getChildren(selector);
+        totalCount += children.length;
+        return (0, cli_tasks_1.mapWithConcurrency)(children, async (child) => {
+            const node = {
+                itemId: child.itemId,
+                name: child.name,
+                path: child.path,
+                templateId: child.templateId,
+            };
+            if (remaining > 1) {
+                node.children = await walk({ itemId: child.itemId }, remaining - 1);
+            }
+            return node;
+        }, knobs.concurrency);
+    };
+    const nodes = await walk({ path: options.path }, depth);
+    return { path: options.path, depth, nodes, totalCount };
+};
+exports.runContentBrowse = runContentBrowse;

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

@@ -0,0 +1,50 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface CleanupArchivePurgeOptions extends HygieneCommonOptions {
+    /**
+     * Only purge archived items older than N days. Default 30. Setting to
+     * 0 purges everything in the archive (use with care).
+     */
+    olderThanDays?: number;
+    /** Cap on the number of items purged. Default 1000. */
+    limit?: number;
+    /** Limit to a specific archive name. */
+    archiveName?: string;
+    /** Concurrency for delete calls. Default 4. */
+    concurrency?: number;
+    /** Page size for archive listing. Default 100. */
+    pageSize?: number;
+    whatIf?: boolean;
+    allowWrite?: boolean;
+}
+export interface ArchivePurgeAction {
+    archivalId: string;
+    itemId: string;
+    name: string;
+    originalLocation: string;
+    archivedDate: string | null;
+    daysSinceArchived: number | null;
+    status: "purged" | "skipped" | "what-if" | "failed";
+    error?: string;
+}
+/**
+ * Purge items from the Sitecore archive (recycle bin) that have been
+ * archived longer than `--older-than-days N`.
+ *
+ * Strategy:
+ *   1. Page through `archivedItems`, computing days-since-archived per
+ *      record.
+ *   2. Skip records younger than the threshold.
+ *   3. For each eligible record, call `deleteArchivedItem(archivalId)`.
+ *      Failures don't abort; they're collected per-record so the report
+ *      shows partial success.
+ *
+ * Safety rails:
+ *   - `ensureAllowWriteForCleanup` enforces `--allow-write` / env
+ *     `allowWrite` outside `--what-if` mode.
+ *   - `--older-than-days 0` is allowed but logged as a warning — it
+ *     purges everything in the archive.
+ *   - There is no `--force` here because archive items are already a
+ *     "soft delete" by Sitecore's standards. Operators who got here
+ *     have already accepted the data loss.
+ */
+export declare const runCleanupArchivePurge: (options: CleanupArchivePurgeOptions) => Promise<ArchivePurgeAction[]>;

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

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCleanupArchivePurge = void 0;
+const cli_tasks_1 = require("../../../shared/cli-tasks");
+const errors_1 = require("../../../shared/errors");
+const shared_1 = require("../shared");
+/**
+ * Purge items from the Sitecore archive (recycle bin) that have been
+ * archived longer than `--older-than-days N`.
+ *
+ * Strategy:
+ *   1. Page through `archivedItems`, computing days-since-archived per
+ *      record.
+ *   2. Skip records younger than the threshold.
+ *   3. For each eligible record, call `deleteArchivedItem(archivalId)`.
+ *      Failures don't abort; they're collected per-record so the report
+ *      shows partial success.
+ *
+ * Safety rails:
+ *   - `ensureAllowWriteForCleanup` enforces `--allow-write` / env
+ *     `allowWrite` outside `--what-if` mode.
+ *   - `--older-than-days 0` is allowed but logged as a warning — it
+ *     purges everything in the archive.
+ *   - There is no `--force` here because archive items are already a
+ *     "soft delete" by Sitecore's standards. Operators who got here
+ *     have already accepted the data loss.
+ */
+const runCleanupArchivePurge = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const { envName, root, client } = (0, shared_1.resolveTenant)(options);
+    const olderThanDays = options.olderThanDays ?? 30;
+    if (!Number.isFinite(olderThanDays) || olderThanDays < 0) {
+        throw (0, errors_1.createScaiError)("--older-than-days must be a non-negative integer.", "INPUT_INVALID");
+    }
+    if (olderThanDays === 0 && !logger.isJson()) {
+        logger.warn("--older-than-days=0 will purge the entire archive.");
+    }
+    const limit = options.limit ?? 1000;
+    const concurrency = options.concurrency ?? 4;
+    const pageSize = options.pageSize ?? 100;
+    if (!options.whatIf) {
+        (0, shared_1.ensureAllowWriteForCleanup)(root, envName, options.allowWrite, "cleanup-archive-purge");
+    }
+    else if (!logger.isJson()) {
+        logger.info("What-if mode active — no archived items will be deleted.", "yellow");
+    }
+    const cutoff = Date.now() - olderThanDays * 24 * 60 * 60 * 1000;
+    const candidates = [];
+    let pageIndex = 0;
+    while (candidates.length < limit) {
+        const page = await client.listArchivedItems({
+            archiveName: options.archiveName,
+            pageIndex,
+            pageSize,
+        });
+        if (page.length === 0)
+            break;
+        for (const item of page) {
+            if (candidates.length >= limit)
+                break;
+            const ts = item.archivedDate ? Date.parse(item.archivedDate) : NaN;
+            const eligible = !Number.isFinite(ts) || ts <= cutoff;
+            if (!eligible)
+                continue;
+            const daysSince = Number.isFinite(ts)
+                ? Math.floor((Date.now() - ts) / (24 * 60 * 60 * 1000))
+                : null;
+            candidates.push({
+                archivalId: item.archivalId,
+                itemId: item.itemId,
+                name: item.name,
+                originalLocation: item.originalLocation,
+                archivedDate: item.archivedDate,
+                daysSince,
+            });
+        }
+        if (page.length < pageSize)
+            break;
+        pageIndex += 1;
+    }
+    logger.verbose(`Found ${candidates.length} eligible archived items.`);
+    const actions = await (0, cli_tasks_1.mapWithConcurrency)(candidates, async (c) => {
+        const base = {
+            archivalId: c.archivalId,
+            itemId: c.itemId,
+            name: c.name,
+            originalLocation: c.originalLocation,
+            archivedDate: c.archivedDate,
+            daysSinceArchived: c.daysSince,
+        };
+        if (options.whatIf) {
+            return { ...base, status: "what-if" };
+        }
+        try {
+            await client.deleteArchivedItem(c.archivalId, options.archiveName);
+            return { ...base, status: "purged" };
+        }
+        catch (error) {
+            return {
+                ...base,
+                status: "failed",
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }, concurrency);
+    const purged = actions.filter((a) => a.status === "purged").length;
+    const failed = actions.filter((a) => a.status === "failed").length;
+    const summary = options.whatIf
+        ? `Plan: would purge ${actions.length} archived item${actions.length === 1 ? "" : "s"} older than ${olderThanDays} days.`
+        : `Purged ${purged} archived item${purged === 1 ? "" : "s"} older than ${olderThanDays} days${failed > 0 ? ` (${failed} failed)` : ""}.`;
+    (0, shared_1.printReport)({
+        logger,
+        command: "cleanup.archive.purge",
+        envName,
+        results: actions,
+        summary,
+        formatLine: (a) => `${a.status === "what-if" ? "[would purge] " : a.status === "failed" ? "[failed] " : ""}${a.name} from ${a.originalLocation}${a.daysSinceArchived !== null ? ` (${a.daysSinceArchived}d)` : ""}${a.error ? ` — ${a.error}` : ""}`,
+        extra: {
+            olderThanDays,
+            archiveName: options.archiveName ?? null,
+            whatIf: Boolean(options.whatIf),
+            purgedCount: purged,
+            failedCount: failed,
+        },
+        options,
+    });
+    return actions;
+};
+exports.runCleanupArchivePurge = runCleanupArchivePurge;

package/dist/hygiene/tasks/cleanup/dead-templates.d.ts

@@ -0,0 +1,74 @@
+import { type TemplateDependencyReport } from "../audit/template-dependencies";
+import { type HygieneCommonOptions } from "../shared";
+export interface CleanupDeadTemplatesOptions extends HygieneCommonOptions {
+    /** Template-tree root. Default `/sitecore/templates/Project`. */
+    root?: string;
+    /** Cap on templates inspected. Default 5000. */
+    limit?: number;
+    /** Concurrency. Default 4. */
+    concurrency?: number;
+    /** Override the search index. */
+    index?: string;
+    /**
+     * Whether to recursively delete now-empty template folders after
+     * removing dead templates. Default true. Setting false leaves the
+     * folder structure intact even when every template inside was dead.
+     */
+    cleanupEmptyFolders?: boolean;
+    whatIf?: boolean;
+    allowWrite?: boolean;
+    /**
+     * Permit operating against `/sitecore/templates/System` and other
+     * platform template subtrees. Off by default — deleting a system
+     * template breaks editor UIs even if it shows zero items.
+     */
+    force?: boolean;
+}
+export interface DeadTemplatePurgeAction {
+    templateId: string;
+    name: string;
+    fullName: string | null;
+    status: "purged" | "what-if" | "failed" | "blocked";
+    error?: string;
+    /**
+     * Inbound structural references that blocked the delete: base-template
+     * inheritors, insert-options hosts, branch sources, datasource
+     * templates. Populated when status is "blocked". The cleanup ran
+     * `audit template-dependencies` as a pre-flight; the operator can
+     * resolve each blocker before re-running cleanup, or pass --force to
+     * attempt delete anyway (the Authoring API may still reject).
+     */
+    blockers?: TemplateDependencyReport[];
+}
+export interface FolderCleanupAction {
+    path: string;
+    itemId: string;
+    status: "deleted" | "what-if" | "failed" | "skipped";
+    error?: string;
+}
+/**
+ * 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.
+ */
+export declare const runCleanupDeadTemplates: (options: CleanupDeadTemplatesOptions) => Promise<{
+    templates: DeadTemplatePurgeAction[];
+    folders: FolderCleanupAction[];
+}>;