@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/hygiene/tasks/audit/history.js

@@ -0,0 +1,161 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runHistoryDiff = exports.runHistoryList = exports.runHistoryCapture = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const environment_1 = require("../../../policy/environment");
+const errors_1 = require("../../../shared/errors");
+const all_1 = require("./all");
+const history_1 = require("../../history");
+const shared_1 = require("../shared");
+const resolveConfigDir = (options) => {
+    if (!options.config)
+        return process.cwd();
+    if (options.config.endsWith(".json"))
+        return node_path_1.default.dirname(options.config);
+    return options.config;
+};
+const runHistoryCapture = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const { envName } = (0, environment_1.resolveEnvironment)(options);
+    const configDir = resolveConfigDir(options);
+    // Capture into an in-memory envelope by running audit all with
+    // --output set to a tmp file, then reading + persisting under
+    // the history dir. Cleaner than refactoring runAuditAll to return
+    // its envelope directly.
+    const fs = await Promise.resolve().then(() => __importStar(require("node:fs")));
+    const os = await Promise.resolve().then(() => __importStar(require("node:os")));
+    const tmpFile = node_path_1.default.join(os.tmpdir(), `scai-audit-all-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.json`);
+    await (0, all_1.runAuditAll)({
+        ...options,
+        output: tmpFile,
+        format: "json",
+        quiet: true,
+    });
+    let envelope;
+    try {
+        envelope = JSON.parse(fs.readFileSync(tmpFile, "utf8"));
+    }
+    finally {
+        try {
+            fs.unlinkSync(tmpFile);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    const file = (0, history_1.captureHistory)({ envName, configDir, envelope, logger });
+    if (logger.isJson()) {
+        logger.json({
+            command: "audit.history.capture",
+            environment: envName,
+            file,
+            totalFindings: Object.values(envelope.audits ?? {}).reduce((n, info) => n + (info.findings?.length ?? 0), 0),
+        });
+        return;
+    }
+    logger.info(`Captured snapshot: ${file}`, "green");
+};
+exports.runHistoryCapture = runHistoryCapture;
+const runHistoryList = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const { envName } = (0, environment_1.resolveEnvironment)(options);
+    const configDir = resolveConfigDir(options);
+    const snapshots = (0, history_1.listHistory)({ envName, configDir });
+    if (logger.isJson()) {
+        logger.json({
+            command: "audit.history.list",
+            environment: envName,
+            count: snapshots.length,
+            snapshots,
+        });
+        return;
+    }
+    if (snapshots.length === 0) {
+        logger.info("No snapshots yet. Run `scai hygiene audit history capture` to take one.", "green");
+        return;
+    }
+    logger.info(`${snapshots.length} snapshot${snapshots.length === 1 ? "" : "s"}:`);
+    for (const s of snapshots.slice(0, 20)) {
+        logger.info(`  ${s.capturedAt}  ${node_path_1.default.basename(s.filePath)}`);
+    }
+    if (snapshots.length > 20)
+        logger.info(`  … +${snapshots.length - 20} more`);
+};
+exports.runHistoryList = runHistoryList;
+const runHistoryDiff = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const { envName } = (0, environment_1.resolveEnvironment)(options);
+    const configDir = resolveConfigDir(options);
+    const snapshots = (0, history_1.listHistory)({ envName, configDir });
+    if (snapshots.length < 2 && (!options.from || !options.to)) {
+        throw (0, errors_1.createScaiError)(`Need at least 2 snapshots to diff (have ${snapshots.length}). Run \`scai hygiene audit history capture\` first.`, "INPUT_INVALID");
+    }
+    // newest first → snapshots[0] is most recent
+    const toPath = options.to ?? snapshots[0].filePath;
+    const fromPath = options.from ?? snapshots[1].filePath;
+    const from = (0, history_1.loadSnapshot)(fromPath);
+    const to = (0, history_1.loadSnapshot)(toPath);
+    const diff = (0, history_1.diffSnapshots)(from, to);
+    if (logger.isJson()) {
+        logger.json({
+            command: "audit.history.diff",
+            environment: envName,
+            fromFile: fromPath,
+            toFile: toPath,
+            ...diff,
+        });
+        return;
+    }
+    logger.info(`Diff: ${from.capturedAt} → ${to.capturedAt}`);
+    logger.info(`Totals: +${diff.totals.added} added, -${diff.totals.removed} removed, net ${diff.totals.net >= 0 ? "+" : ""}${diff.totals.net}.`, diff.totals.net > 0 ? "yellow" : "green");
+    for (const [audit, entry] of Object.entries(diff.perAudit)) {
+        const { total, added, removed } = entry;
+        if (added.length === 0 && removed.length === 0)
+            continue;
+        const sign = total.delta > 0 ? "+" : total.delta < 0 ? "" : "±";
+        logger.info(`  ${audit}: ${total.from} → ${total.to} (${sign}${total.delta})`, total.delta > 0 ? "yellow" : total.delta < 0 ? "green" : undefined);
+        for (const a of added.slice(0, 3)) {
+            logger.info(`    + ${a.sample?.path ?? a.fingerprint.slice(0, 12)}`);
+        }
+        for (const r of removed.slice(0, 3)) {
+            logger.info(`    - ${r.sample?.path ?? r.fingerprint.slice(0, 12)}`);
+        }
+    }
+};
+exports.runHistoryDiff = runHistoryDiff;

package/dist/hygiene/tasks/audit/language-data.d.ts

@@ -0,0 +1,55 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface AuditLanguageDataOptions extends HygieneCommonOptions {
+    /** Scope to descendants of this content path. Default `/sitecore/content`. */
+    root?: string;
+    /**
+     * Languages to inspect for empty entries. Defaults to all languages
+     * found in the search index under `--root`.
+     */
+    languages?: string[];
+    /** Override the search index. */
+    index?: string;
+    /** Cap on items inspected. Default 5000. */
+    limit?: number;
+    /** Include system items. Off by default. */
+    includeSystem?: boolean;
+    /** Per-item check concurrency. Default 4. */
+    concurrency?: number;
+}
+export interface LanguageDataReport {
+    itemId: string;
+    path: string;
+    templateName?: string | null;
+    /** Languages where the item exists as a database entry but has zero versions. */
+    emptyLanguages: string[];
+}
+/**
+ * Report items that have a per-language entry in the master DB but
+ * **zero versions** in that language — the XM Cloud equivalent of the
+ * dotnet `clean-invalid-language-data` diagnostic.
+ *
+ * **No remediation API on XM Cloud.** This command is read-only by
+ * design. The Authoring GraphQL API exposes only two language
+ * mutations:
+ *   - `deleteLanguage(input: { database, name })` — removes the
+ *     language from the entire tenant. Destructive; not per-item.
+ *   - `deleteItemVersion` — removes a single version, but there's no
+ *     version-zero entry to delete.
+ *
+ * There is no `deleteItemLanguage(itemId, language)` mutation on XM
+ * Cloud Authoring. So the on-prem `clean-invalid-language-data` shape
+ * (per-item, per-language cleanup) can't be ported.
+ *
+ * What this command does:
+ *   1. Use search to enumerate items under `--root` and gather the set
+ *      of languages observed across those items.
+ *   2. For each item, ask the Authoring API for its versions per
+ *      candidate language (`getItemVersions({ language })`). Versions
+ *      list is empty → that's an empty-language-entry.
+ *
+ * Operators who want to "clean" can either: (a) re-author at least one
+ * version in the affected language, or (b) `deleteLanguage` tenant-wide
+ * if the language is no longer in use. Both are out-of-scope for this
+ * command.
+ */
+export declare const runAuditLanguageData: (options: AuditLanguageDataOptions) => Promise<LanguageDataReport[]>;

package/dist/hygiene/tasks/audit/language-data.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuditLanguageData = void 0;
+const cli_tasks_1 = require("../../../shared/cli-tasks");
+const shared_1 = require("../shared");
+/**
+ * Report items that have a per-language entry in the master DB but
+ * **zero versions** in that language — the XM Cloud equivalent of the
+ * dotnet `clean-invalid-language-data` diagnostic.
+ *
+ * **No remediation API on XM Cloud.** This command is read-only by
+ * design. The Authoring GraphQL API exposes only two language
+ * mutations:
+ *   - `deleteLanguage(input: { database, name })` — removes the
+ *     language from the entire tenant. Destructive; not per-item.
+ *   - `deleteItemVersion` — removes a single version, but there's no
+ *     version-zero entry to delete.
+ *
+ * There is no `deleteItemLanguage(itemId, language)` mutation on XM
+ * Cloud Authoring. So the on-prem `clean-invalid-language-data` shape
+ * (per-item, per-language cleanup) can't be ported.
+ *
+ * What this command does:
+ *   1. Use search to enumerate items under `--root` and gather the set
+ *      of languages observed across those items.
+ *   2. For each item, ask the Authoring API for its versions per
+ *      candidate language (`getItemVersions({ language })`). Versions
+ *      list is empty → that's an empty-language-entry.
+ *
+ * Operators who want to "clean" can either: (a) re-author at least one
+ * version in the affected language, or (b) `deleteLanguage` tenant-wide
+ * if the language is no longer in use. Both are out-of-scope for this
+ * command.
+ */
+const runAuditLanguageData = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const { envName, client } = (0, shared_1.resolveTenant)(options);
+    const root = options.root ?? "/sitecore/content";
+    const limit = options.limit ?? 5000;
+    const knobs = (0, shared_1.resolveHygieneKnobs)(options);
+    const concurrency = options.concurrency ?? knobs.concurrency;
+    const includeSystem = Boolean(options.includeSystem);
+    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;
+    // Pass 1: enumerate items and collect language set per item.
+    const itemLanguages = new Map();
+    let scanned = 0;
+    for await (const r of client.searchAll({
+        index: options.index,
+        // Important: don't filter latestVersionOnly here — we want to see
+        // language entries that have no versions at all.
+        latestVersionOnly: false,
+        ...(rootItemId && { searchStatement: (0, shared_1.buildPathFilterStatement)(rootItemId) }),
+    }, 100, knobs.pageParallelism)) {
+        if (!includeSystem && (0, shared_1.isSystemPath)(r.path))
+            continue;
+        const id = (0, shared_1.normalizeItemId)(r.itemId);
+        if (!itemLanguages.has(id)) {
+            itemLanguages.set(id, {
+                path: r.path,
+                templateName: r.templateName ?? null,
+                languages: new Set(),
+            });
+            scanned += 1;
+            if (scanned >= limit)
+                break;
+        }
+        const lang = r.language?.name;
+        if (lang)
+            itemLanguages.get(id).languages.add(lang);
+    }
+    // If the user provided an explicit language set, intersect.
+    const requested = options.languages?.length ? new Set(options.languages) : undefined;
+    const pairs = [];
+    for (const [id, info] of itemLanguages) {
+        for (const lang of info.languages) {
+            if (requested && !requested.has(lang))
+                continue;
+            pairs.push({ itemId: id, path: info.path, templateName: info.templateName, language: lang });
+        }
+    }
+    logger.verbose(`Probing ${pairs.length} (item, language) pairs for empty entries.`);
+    const empty = await (0, cli_tasks_1.mapWithConcurrency)(pairs, async (p) => {
+        const versions = await client.getItemVersions({
+            itemId: p.itemId,
+            language: p.language,
+        });
+        return versions.length === 0 ? p : null;
+    }, concurrency);
+    const byItem = new Map();
+    for (const p of empty) {
+        if (!p)
+            continue;
+        const existing = byItem.get(p.itemId);
+        if (existing) {
+            existing.emptyLanguages.push(p.language);
+        }
+        else {
+            byItem.set(p.itemId, {
+                itemId: p.itemId,
+                path: p.path,
+                templateName: p.templateName,
+                emptyLanguages: [p.language],
+            });
+        }
+    }
+    const reports = Array.from(byItem.values()).sort((a, b) => a.path.localeCompare(b.path));
+    (0, shared_1.printReport)({
+        logger,
+        command: "audit.language-data.list",
+        envName,
+        results: reports,
+        summary: `Scanned ${scanned} items, ${pairs.length} (item, language) pairs; ${reports.length} with empty language entries.`,
+        formatLine: (r) => `${r.path} — empty: ${r.emptyLanguages.join(", ")}`,
+        extra: { root, limit, scannedCount: scanned, pairsChecked: pairs.length },
+        options,
+    });
+    return reports;
+};
+exports.runAuditLanguageData = runAuditLanguageData;

package/dist/hygiene/tasks/audit/large-fields.d.ts

@@ -0,0 +1,48 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface AuditLargeFieldsOptions extends HygieneCommonOptions {
+    /** Size threshold in bytes for a field to count as "large". Default 100_000. */
+    threshold?: number;
+    /** Content root. Default `/sitecore/content`. */
+    root?: string;
+    index?: string;
+    limit?: number;
+    includeSystem?: boolean;
+    language?: string;
+    batchSize?: number;
+    concurrency?: number;
+    pageParallelism?: number;
+    cache?: boolean;
+    exclude?: string[];
+    since?: string;
+    owner?: string;
+    baseline?: boolean;
+    output?: string;
+    format?: "json" | "csv" | "markdown";
+    /** Include __-prefixed system fields in the size check. Off by default. */
+    includeSystemFields?: boolean;
+}
+export interface LargeFieldReport {
+    itemId: string;
+    path: string;
+    templateName: string | null;
+    language: string | null;
+    largeFields: Array<{
+        fieldName: string;
+        size: number;
+    }>;
+    totalSize: number;
+}
+/**
+ * Audit content for field values exceeding a size threshold.
+ *
+ * Common culprits: RichText pasted from Word (huge HTML blobs), raw
+ * JSON dumps in text fields, base64-embedded images in HTML.
+ * Defaults to 100KB per field — the byte size where renders start
+ * impacting LCP and authoring tools start lagging.
+ *
+ * Strategy:
+ *   1. Use `scanItemsAndFields` to enumerate + fetch fields.
+ *   2. For each non-system field, byte-length check against threshold.
+ *   3. Report per-item; sort by total bloated bytes desc.
+ */
+export declare const runAuditLargeFields: (options: AuditLargeFieldsOptions) => Promise<LargeFieldReport[]>;

package/dist/hygiene/tasks/audit/large-fields.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuditLargeFields = void 0;
+const shared_1 = require("../shared");
+/**
+ * Audit content for field values exceeding a size threshold.
+ *
+ * Common culprits: RichText pasted from Word (huge HTML blobs), raw
+ * JSON dumps in text fields, base64-embedded images in HTML.
+ * Defaults to 100KB per field — the byte size where renders start
+ * impacting LCP and authoring tools start lagging.
+ *
+ * Strategy:
+ *   1. Use `scanItemsAndFields` to enumerate + fetch fields.
+ *   2. For each non-system field, byte-length check against threshold.
+ *   3. Report per-item; sort by total bloated bytes desc.
+ */
+const runAuditLargeFields = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const { envName, client } = (0, shared_1.resolveTenant)(options);
+    const root = options.root ?? "/sitecore/content";
+    const threshold = options.threshold ?? 100000;
+    const includeSystemFields = Boolean(options.includeSystemFields);
+    const { scanned, fieldsByItemId, cache } = await (0, shared_1.scanItemsAndFields)({
+        client,
+        envName,
+        root,
+        logger,
+        options,
+    });
+    const reports = [];
+    for (const item of scanned) {
+        const fields = fieldsByItemId.get(item.itemId);
+        if (!fields || !Array.isArray(fields))
+            continue;
+        const large = [];
+        let total = 0;
+        for (const field of fields) {
+            if (!field.value)
+                continue;
+            if (!includeSystemFields && field.name.startsWith("__"))
+                continue;
+            const size = Buffer.byteLength(field.value, "utf8");
+            if (size >= threshold) {
+                large.push({ fieldName: field.name, size });
+                total += size;
+            }
+        }
+        if (large.length > 0) {
+            reports.push({
+                itemId: item.itemId,
+                path: item.path,
+                templateName: item.templateName,
+                language: item.language,
+                largeFields: large,
+                totalSize: total,
+            });
+        }
+    }
+    reports.sort((a, b) => b.totalSize - a.totalSize);
+    await cache?.flush();
+    (0, shared_1.printReport)({
+        logger,
+        command: "audit.large-fields.list",
+        envName,
+        results: reports,
+        summary: `Scanned ${scanned.length} items; ${reports.length} have fields >= ${formatBytes(threshold)}.`,
+        formatLine: (r) => `${r.path} — ${formatBytes(r.totalSize)} across ${r.largeFields.length} field${r.largeFields.length === 1 ? "" : "s"}: ${r.largeFields
+            .slice(0, 3)
+            .map((f) => `${f.fieldName}(${formatBytes(f.size)})`)
+            .join(", ")}${r.largeFields.length > 3 ? "…" : ""}`,
+        extra: { root, threshold, scannedCount: scanned.length },
+        options,
+    });
+    return reports;
+};
+exports.runAuditLargeFields = runAuditLargeFields;
+const formatBytes = (n) => {
+    if (n < 1024)
+        return `${n}B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)}KB`;
+    return `${(n / (1024 * 1024)).toFixed(2)}MB`;
+};

package/dist/hygiene/tasks/audit/missing-meta.d.ts

@@ -0,0 +1,57 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface AuditMissingMetaOptions extends HygieneCommonOptions {
+    /**
+     * Required field names that should have a non-empty value on every
+     * scanned item. Defaults to the common SEO set: meta-title,
+     * meta-description, og-image, og-title.
+     */
+    requiredFields?: string[];
+    /** Content root. Default `/sitecore/content`. */
+    root?: string;
+    index?: string;
+    limit?: number;
+    includeSystem?: boolean;
+    language?: string;
+    batchSize?: number;
+    concurrency?: number;
+    pageParallelism?: number;
+    cache?: boolean;
+    exclude?: string[];
+    since?: string;
+    owner?: string;
+    baseline?: boolean;
+    output?: string;
+    format?: "json" | "csv" | "markdown";
+    /**
+     * Restrict by template name (or pattern). When set, only items
+     * whose templateName matches are checked. Default: all items —
+     * this can be noisy, so most operators will scope to "Page"
+     * templates with `--template-pattern Page`.
+     */
+    templatePattern?: string;
+}
+export interface MissingMetaReport {
+    itemId: string;
+    path: string;
+    templateName: string | null;
+    language: string | null;
+    missingFields: string[];
+}
+/**
+ * Audit content for items missing required (SEO) field values.
+ *
+ * Strategy:
+ *   1. Enumerate items via `scanItemsAndFields`.
+ *   2. For each, check that every required field is present and
+ *      non-empty (whitespace-only counts as missing).
+ *   3. Field-name matching is case-insensitive and falls back to
+ *      Title-Case-To-Hyphenated variants ("Meta Description" ↔
+ *      "meta-description") to tolerate template naming styles.
+ *
+ * The default required set is SEO-oriented. Pass `--required-fields
+ * "title,banner-image,...` to define your own per-project policy.
+ *
+ * `--template-pattern` scopes the check — typically you want to
+ * apply this only to Page templates, not Datasource items.
+ */
+export declare const runAuditMissingMeta: (options: AuditMissingMetaOptions) => Promise<MissingMetaReport[]>;

package/dist/hygiene/tasks/audit/missing-meta.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuditMissingMeta = void 0;
+const shared_1 = require("../shared");
+const DEFAULT_REQUIRED = ["meta-title", "meta-description", "og-image", "og-title"];
+/**
+ * Audit content for items missing required (SEO) field values.
+ *
+ * Strategy:
+ *   1. Enumerate items via `scanItemsAndFields`.
+ *   2. For each, check that every required field is present and
+ *      non-empty (whitespace-only counts as missing).
+ *   3. Field-name matching is case-insensitive and falls back to
+ *      Title-Case-To-Hyphenated variants ("Meta Description" ↔
+ *      "meta-description") to tolerate template naming styles.
+ *
+ * The default required set is SEO-oriented. Pass `--required-fields
+ * "title,banner-image,...` to define your own per-project policy.
+ *
+ * `--template-pattern` scopes the check — typically you want to
+ * apply this only to Page templates, not Datasource items.
+ */
+const runAuditMissingMeta = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const { envName, client } = (0, shared_1.resolveTenant)(options);
+    const root = options.root ?? "/sitecore/content";
+    const required = (options.requiredFields?.length ? options.requiredFields : DEFAULT_REQUIRED).map((s) => s.toLowerCase());
+    const templateRegex = options.templatePattern ? new RegExp(options.templatePattern, "i") : null;
+    const { scanned, fieldsByItemId, cache } = await (0, shared_1.scanItemsAndFields)({
+        client,
+        envName,
+        root,
+        logger,
+        options,
+    });
+    const reports = [];
+    for (const item of scanned) {
+        if (templateRegex && !templateRegex.test(item.templateName ?? ""))
+            continue;
+        const fields = fieldsByItemId.get(item.itemId);
+        if (!fields || !Array.isArray(fields))
+            continue;
+        // Track two sets:
+        //   - `present` — every field the item's template defines (regardless
+        //     of value). If a required field isn't in this set, the template
+        //     itself doesn't declare it, which is a content-model decision,
+        //     not a content-quality issue — skip rather than flag.
+        //   - `populated` — fields whose value is non-empty after trimming.
+        // A required field is reported missing only when `present && !populated`.
+        // Prior to this distinction the audit fired on every item in tenants
+        // whose content model didn't include the SEO field set at all (e.g.
+        // an internal-tools tenant without `meta-title`), generating one
+        // finding per item across the entire content tree.
+        const present = new Set();
+        const populated = new Set();
+        for (const f of fields) {
+            const name = f.name.toLowerCase();
+            const hyphenated = name.replace(/\s+/g, "-");
+            present.add(name);
+            present.add(hyphenated);
+            if (f.value && f.value.trim()) {
+                populated.add(name);
+                populated.add(hyphenated);
+            }
+        }
+        const missing = [];
+        for (const req of required) {
+            if (!present.has(req))
+                continue;
+            if (!populated.has(req))
+                missing.push(req);
+        }
+        if (missing.length > 0) {
+            reports.push({
+                itemId: item.itemId,
+                path: item.path,
+                templateName: item.templateName,
+                language: item.language,
+                missingFields: missing,
+            });
+        }
+    }
+    reports.sort((a, b) => a.path.localeCompare(b.path));
+    await cache?.flush();
+    (0, shared_1.printReport)({
+        logger,
+        command: "audit.missing-meta.list",
+        envName,
+        results: reports,
+        summary: `Scanned ${scanned.length} items; ${reports.length} missing required field${required.length === 1 ? "" : "s"} (${required.join(", ")}).`,
+        formatLine: (r) => `${r.path} — missing: ${r.missingFields.join(", ")}`,
+        extra: { root, requiredFields: required, scannedCount: scanned.length },
+        options,
+    });
+    return reports;
+};
+exports.runAuditMissingMeta = runAuditMissingMeta;

package/dist/hygiene/tasks/audit/orphans.d.ts

@@ -0,0 +1,47 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface AuditOrphansOptions extends HygieneCommonOptions {
+    /**
+     * Page size for the archive listing. Default 100 (Authoring API
+     * default). Higher values reduce request count for large archives.
+     */
+    pageSize?: number;
+    /** Cap on the number of archived items returned. Default 1000. */
+    limit?: number;
+    /**
+     * Override the archive name. Defaults to undefined, which means "all
+     * archives" on the Authoring API.
+     */
+    archiveName?: string;
+}
+export interface OrphanReport {
+    archivalId: string;
+    itemId: string;
+    name: string;
+    originalLocation: string;
+    archivedBy: string | null;
+    archivedDate: string | null;
+}
+/**
+ * List orphan items — i.e., items in the Sitecore archive (recycle bin).
+ *
+ * **XM Cloud reality check.** The dotnet `Sitecore.DevEx`
+ * `clean-orphan-items` operation targeted SQL-layer orphans (items in
+ * the master DB whose `ParentID` referenced a nonexistent parent).
+ * That state isn't reachable through the XM Cloud Authoring API: the
+ * GraphQL schema enforces parent integrity on every mutation, and
+ * delete cascades from parent → children, so a "missing parent"
+ * orphan can't be produced through normal use.
+ *
+ * What XM Cloud *does* expose is the archive (recycle bin). When an
+ * operator deletes an item via XM Cloud UIs or via `deleteItem(input:
+ * { permanently: false })`, it moves to the archive — visible only via
+ * the `archivedItems` query. This is the closest analogue to
+ * "orphaned" content on XM Cloud and is what an operator would mean by
+ * "find items I can clean up."
+ *
+ * For genuine missing-parent items (extremely rare on XM Cloud, but
+ * possible in disaster-recovery scenarios), a follow-up command could
+ * walk the tree via `getChildren` and flag dangling refs — not in
+ * this PR's scope.
+ */
+export declare const runAuditOrphans: (options: AuditOrphansOptions) => Promise<OrphanReport[]>;