@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/hygiene/tasks/shared.js

@@ -0,0 +1,532 @@
+"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.ensureAllowWriteForCleanup = exports.scanItemsAndFields = exports.matchesScanFilters = exports.resolveScanFilters = exports.isPageDesignField = exports.PAGE_DESIGN_FIELDS = exports.computeContentHash = exports.extractPersonalizationRefs = exports.extractRenderingDatasources = exports.isRenderingField = exports.RENDERING_FIELDS = exports.resolveHygieneKnobs = exports.isSystemPath = exports.SYSTEM_PATH_PREFIXES = exports.buildPathFilterStatement = exports.extractMediaRefs = exports.extractInternalRefs = exports.dashifyItemId = exports.normalizeItemId = exports.finishAudit = exports.printReport = exports.resolveTenant = exports.toLogger = void 0;
+const logger_1 = require("../../shared/logger");
+const errors_1 = require("../../shared/errors");
+const environment_1 = require("../../policy/environment");
+const cli_tasks_1 = require("../../shared/cli-tasks");
+const envelope_1 = require("../../shared/envelope");
+const client_1 = require("../api/client");
+const cache_1 = require("../cache");
+const baseline_1 = require("../baseline");
+const output_adapters_1 = require("../output-adapters");
+const node_path_1 = __importDefault(require("node:path"));
+const toLogger = (options) => new logger_1.Logger(Boolean(options.verbose), Boolean(options.trace), Boolean(options.json), Boolean(options.quiet), options.logFile ?? process.env.SITECOREAI_LOG_FILE);
+exports.toLogger = toLogger;
+const resolveTenant = (options) => {
+    const { envName, environment, root, timeoutMs } = (0, environment_1.resolveEnvironment)(options);
+    const client = (0, client_1.createHygieneApiClient)({
+        environment,
+        request: { timeoutMs },
+    });
+    return { envName, environment, root, client };
+};
+exports.resolveTenant = resolveTenant;
+const printReport = (params) => {
+    (0, exports.finishAudit)({ ...params, auditName: deriveAuditName(params.command) });
+};
+exports.printReport = printReport;
+const deriveAuditName = (command) => {
+    // command shape: "audit.<name>.<verb>" e.g. "audit.broken-links.list"
+    const m = /^audit\.([^.]+)\./.exec(command);
+    return m?.[1];
+};
+const resolveConfigDir = (config) => {
+    if (!config)
+        return process.cwd();
+    if (config.endsWith(".json"))
+        return node_path_1.default.dirname(config);
+    return config;
+};
+const finishAudit = (params) => {
+    const { logger, command, envName, formatLine, summary, extra, options, auditName } = params;
+    let results = params.results;
+    let ignoredCount = 0;
+    // Total accepted entries for this audit across all runs — surfaced
+    // even when --baseline isn't set, so operators discover the baseline
+    // exists and know how many findings are already accepted.
+    let baselineAcceptedTotal;
+    // Open the baseline once if we know the audit name. `openBaseline`
+    // is cheap when the file doesn't exist (returns an empty in-memory
+    // baseline), so the unconditional open here costs ~ms on the warm
+    // path. Both behaviors — filtering on `--baseline` and surfacing
+    // accepted counts on every run — share the same handle.
+    if (auditName) {
+        try {
+            const baseline = (0, baseline_1.openBaseline)({
+                envName,
+                configDir: resolveConfigDir(options?.config),
+                logger,
+            });
+            const snapshot = baseline.snapshot();
+            const acceptedForThisAudit = snapshot.ignored[auditName]?.length ?? 0;
+            if (acceptedForThisAudit > 0) {
+                baselineAcceptedTotal = acceptedForThisAudit;
+            }
+            if (options?.baseline) {
+                const split = (0, baseline_1.splitByBaseline)(auditName, results, baseline);
+                results = split.kept;
+                ignoredCount = split.ignored.length;
+            }
+        }
+        catch (error) {
+            logger.warn(`Failed to apply baseline filter for '${auditName}': ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    else if (options?.baseline && !auditName) {
+        logger.warn(`--baseline requested but the audit command name '${command}' doesn't map to a baseline key.`);
+    }
+    // Build the canonical `ScaiEnvelope` shape — `data` (not `results`)
+    // for the primary payload; `meta` collects command-specific extras
+    // that don't have a structured slot. Pre-2026-05-14 this surface
+    // emitted `results` while deploy emitted `result`; the unification
+    // lets agents parse one shape across every CLI command.
+    const envelope = (0, envelope_1.buildScaiEnvelope)({
+        command,
+        environment: envName,
+        data: results,
+        extra: {
+            ...(extra ?? {}),
+            count: results.length,
+            ...(ignoredCount > 0 ? { ignoredCount } : {}),
+            ...(baselineAcceptedTotal !== undefined ? { baselineAcceptedTotal } : {}),
+        },
+    });
+    // Output adapter: --output writes serialised report to file.
+    const explicitFormat = options?.format;
+    const inferredFormat = options?.output ? (0, output_adapters_1.inferFormatFromExtension)(options.output) : undefined;
+    const format = explicitFormat ?? inferredFormat ?? "json";
+    if (options?.output) {
+        // ScaiEnvelope is structurally compatible with AuditEnvelope but
+        // lacks the latter's `[key: string]: unknown` index signature;
+        // cast widens the type without changing the runtime shape.
+        (0, output_adapters_1.writeAuditOutput)(envelope, { format, output: options.output });
+        if (!logger.isJson()) {
+            logger.info(`Wrote ${options.output} (${envelope.count} finding${envelope.count === 1 ? "" : "s"}${ignoredCount > 0 ? `, ${ignoredCount} ignored by baseline` : ""}).`, "green");
+        }
+        return;
+    }
+    // Stdout path — same as the original printReport behavior.
+    if (logger.isJson()) {
+        logger.json(envelope);
+        return;
+    }
+    const headline = summary ?? `${results.length} item${results.length === 1 ? "" : "s"} found.`;
+    logger.info(headline, results.length === 0 ? "green" : "yellow");
+    if (ignoredCount > 0) {
+        logger.info(`  (${ignoredCount} ignored by baseline)`, "gray");
+    }
+    // Always surface the per-audit baseline size — even when the operator
+    // didn't pass --baseline. The agent feedback called out that baseline
+    // is underused because it's invisible; showing the count nudges
+    // operators toward it. Skip when --baseline is on (the ignoredCount
+    // line above already says what got filtered).
+    if (baselineAcceptedTotal !== undefined && !options?.baseline) {
+        logger.info(`  (${baselineAcceptedTotal} finding${baselineAcceptedTotal === 1 ? "" : "s"} in baseline; pass --baseline to filter, or 'scai hygiene audit baseline accept --audit ${auditName} --from-stdin' to add more)`, "gray");
+    }
+    for (const item of results) {
+        logger.info(`  - ${formatLine(item)}`);
+    }
+};
+exports.finishAudit = finishAudit;
+/** Normalize a Sitecore itemId to lowercase, no dashes, no braces (search-index form). */
+const normalizeItemId = (raw) => raw.toLowerCase().replace(/[{}-]/g, "");
+exports.normalizeItemId = normalizeItemId;
+/** Dashify a flat 32-char itemId back to canonical 8-4-4-4-12. */
+const dashifyItemId = (flat) => {
+    const norm = flat.replace(/[-{}]/g, "");
+    if (norm.length !== 32)
+        return flat;
+    return `${norm.slice(0, 8)}-${norm.slice(8, 12)}-${norm.slice(12, 16)}-${norm.slice(16, 20)}-${norm.slice(20)}`;
+};
+exports.dashifyItemId = dashifyItemId;
+/**
+ * Extract internal Sitecore itemId references from a field value.
+ *
+ * Recognises three field-value shapes:
+ *
+ *   1. Bare GUID — `{11111111-...}` or unwrapped uuid. Used by single-item-ref
+ *      fields (Droplink, General Link, Droptree, etc.).
+ *   2. Pipe-delimited GUIDs — `{guid1}|{guid2}|...`. Used by Multilist
+ *      (Treelist, Multilist, TreelistEx, MultilistEx).
+ *   3. RichText `<link>` tags — `<link linktype="internal" id="{guid}" ...>`
+ *      (Sitecore RichText editor inserts internal links this way).
+ *      External (`linktype="external"`) and media (`linktype="media"`) tags
+ *      are ignored at this layer — media refs are surfaced separately by
+ *      `extractMediaReferences`.
+ *
+ * Returns normalized lowercase no-dash itemIds (search-index form) so a
+ * Set<string> comparison with `_path` / `parentId` fields from search results
+ * compares clean.
+ */
+const extractInternalRefs = (value) => {
+    if (!value)
+        return [];
+    const refs = [];
+    const guidPattern = /\{?([0-9a-f]{8})-?([0-9a-f]{4})-?([0-9a-f]{4})-?([0-9a-f]{4})-?([0-9a-f]{12})\}?/gi;
+    let match;
+    while ((match = guidPattern.exec(value))) {
+        refs.push((match[1] + match[2] + match[3] + match[4] + match[5]).toLowerCase());
+    }
+    return refs;
+};
+exports.extractInternalRefs = extractInternalRefs;
+/**
+ * Extract media item references — refs that point at items under the
+ * `/sitecore/media library` tree.
+ *
+ * Recognises:
+ *   1. RichText `<link linktype="media" id="{guid}" />` tags.
+ *   2. Image-field XML — `<image mediaid="{guid}" ...>` (Sitecore's Image
+ *      field stores this XML in field values).
+ *   3. Bare GUIDs in Multilist-style fields targeting media items (caller
+ *      passes those through `extractInternalRefs` and resolves against the
+ *      media library at a higher layer).
+ *
+ * Returns normalized itemIds. Callers de-dup with a Set; ordering is not
+ * preserved.
+ */
+const extractMediaRefs = (value) => {
+    if (!value)
+        return [];
+    const refs = [];
+    // <link linktype="media" id="{guid}">
+    const linkMediaPattern = /<link\b[^>]*\blinktype=["']?media["']?[^>]*\bid=["']?(\{?[0-9a-f-]{32,38}\}?)/gi;
+    // <image mediaid="{guid}">  — the Sitecore Image field XML shape
+    const imageFieldPattern = /<image\b[^>]*\bmediaid=["']?(\{?[0-9a-f-]{32,38}\}?)/gi;
+    for (const pattern of [linkMediaPattern, imageFieldPattern]) {
+        let m;
+        while ((m = pattern.exec(value))) {
+            const guid = m[1].replace(/[{}-]/g, "").toLowerCase();
+            if (guid.length === 32)
+                refs.push(guid);
+        }
+    }
+    return refs;
+};
+exports.extractMediaRefs = extractMediaRefs;
+/**
+ * Build a SearchStatement that limits results to descendants of the given
+ * itemId (i.e. items whose `_path` indexed field contains the ancestor's
+ * itemId). Used to scope audits to a sub-tree.
+ */
+const buildPathFilterStatement = (ancestorItemId) => ({
+    criteria: {
+        field: "_path",
+        value: (0, exports.normalizeItemId)(ancestorItemId),
+        criteriaType: "CONTAINS",
+    },
+});
+exports.buildPathFilterStatement = buildPathFilterStatement;
+/**
+ * Sitecore-controlled item paths that audits should skip by default.
+ *
+ * `/sitecore/system` and `/sitecore/templates/System` carry hundreds of
+ * thousands of platform-supplied items that aren't user-authored and
+ * aren't actionable hygiene targets. Without this filter, `audit
+ * broken-links list` and `audit stale-workflow list` would surface
+ * platform noise that the operator can't fix.
+ *
+ * Operators can opt in to scanning system items with `--include-system`.
+ */
+exports.SYSTEM_PATH_PREFIXES = [
+    "/sitecore/system",
+    "/sitecore/layout/Layouts/System",
+    "/sitecore/templates/System",
+    "/sitecore/templates/Branches/System",
+];
+const isSystemPath = (path) => exports.SYSTEM_PATH_PREFIXES.some((prefix) => path.startsWith(prefix));
+exports.isSystemPath = isSystemPath;
+const parseIntEnv = (value, fallback) => {
+    if (!value)
+        return fallback;
+    const n = parseInt(value, 10);
+    return Number.isFinite(n) && n >= 1 ? n : fallback;
+};
+const resolveHygieneKnobs = (options) => ({
+    concurrency: options.concurrency ?? parseIntEnv(process.env.SITECOREAI_HYGIENE_CONCURRENCY, 8),
+    batchSize: options.batchSize ?? parseIntEnv(process.env.SITECOREAI_HYGIENE_BATCH_SIZE, 50),
+    pageParallelism: options.pageParallelism ?? parseIntEnv(process.env.SITECOREAI_HYGIENE_PAGE_PARALLELISM, 4),
+});
+exports.resolveHygieneKnobs = resolveHygieneKnobs;
+/**
+ * Sitecore field names that hold layout rendering XML. These are the
+ * fields parsed by `extractRenderingDatasources` and
+ * `extractPersonalizationVariantRefs`.
+ *
+ * - `__Renderings`        — shared (multi-language) presentation layer.
+ * - `__Final Renderings`  — per-language presentation overlay.
+ * - `__Renderings (Page)` — page-design-tier layout (rare; only on Page
+ *                           Design items).
+ */
+exports.RENDERING_FIELDS = ["__Renderings", "__Final Renderings", "__Renderings (Page)"];
+const isRenderingField = (fieldName) => exports.RENDERING_FIELDS.includes(fieldName);
+exports.isRenderingField = isRenderingField;
+/**
+ * Extract datasource references from a rendering-layout XML value.
+ *
+ * Sitecore stores rendering presentation as XML like:
+ *
+ *   <r uid="{...}" id="{rendering-id}" ds="/sitecore/content/Home/DS"
+ *      s:ds="{...}" par="..." />
+ *
+ * The `ds` (or sometimes `s:ds`) attribute on each `<r>` element holds
+ * the datasource — either a content-tree path, a bare itemId, or a
+ * Sitecore query (`query:./ancestor-or-self::*[@@templatename='Site']/Data`).
+ * Queries are dynamic; they're returned with a `query:` prefix so the
+ * caller can decide whether to skip them. Empty `ds` values are
+ * omitted from the result.
+ *
+ * Returns values verbatim (path / itemId / `query:…`) for the caller to
+ * resolve.
+ */
+const extractRenderingDatasources = (renderingsXml) => {
+    if (!renderingsXml)
+        return [];
+    const out = [];
+    // Match every <r ...> element start tag — attribute order is unstable.
+    const rPattern = /<r\b([^>]*)>/gi;
+    let m;
+    while ((m = rPattern.exec(renderingsXml))) {
+        const attrs = m[1];
+        // Prefer `s:ds` if present, fall back to bare `ds`. Some tenants
+        // emit both with the namespaced form taking precedence at runtime.
+        const dsMatch = /\bs?:?ds=["']([^"']*)["']/i.exec(attrs);
+        if (!dsMatch || !dsMatch[1])
+            continue;
+        const idMatch = /\bs?:?id=["']([^"']*)["']/i.exec(attrs);
+        out.push({
+            datasource: dsMatch[1],
+            renderingId: idMatch?.[1] ?? null,
+        });
+    }
+    return out;
+};
+exports.extractRenderingDatasources = extractRenderingDatasources;
+/**
+ * Extract personalization variant + rule references from a rendering-layout
+ * XML value.
+ *
+ * Personalization is stored in `<rules>` elements nested under `<r>`:
+ *
+ *   <r ...>
+ *     <rules s:set="{xyz}">
+ *       <rule s:uid="{...}" s:name="..." s:templateid="{variant-tid}">
+ *         <conditions>...</conditions>
+ *         <actions>
+ *           <action id="{...}" datasource="{variant-itemId}" />
+ *         </actions>
+ *       </rule>
+ *     </rules>
+ *   </r>
+ *
+ * Returns refs found in `datasource=` attributes of `<action>` elements
+ * AND in rule `s:set=` attributes (the rule-set itemId).
+ */
+const extractPersonalizationRefs = (renderingsXml) => {
+    if (!renderingsXml)
+        return [];
+    const refs = [];
+    const actionDs = /<action\b[^>]*\bdatasource=["']([^"']*)["']/gi;
+    const ruleSet = /<rules\b[^>]*\bs:set=["']([^"']*)["']/gi;
+    for (const pattern of [actionDs, ruleSet]) {
+        let m;
+        while ((m = pattern.exec(renderingsXml))) {
+            if (m[1])
+                refs.push(m[1]);
+        }
+    }
+    return refs;
+};
+exports.extractPersonalizationRefs = extractPersonalizationRefs;
+/**
+ * Compute a content hash over an item's authored fields, suitable for
+ * exact-duplicate detection.
+ *
+ * Includes only authored fields (not `__`-prefixed system fields, which
+ * carry per-item metadata like `__Created`, `__Updated`, `__Lock`).
+ * Field name + trimmed value joined by `\0`, fields sorted by name for
+ * determinism. SHA-256, returned as 16-char hex (sufficient to bucket
+ * tenant-scale item counts without realistic collision).
+ */
+const computeContentHash = async (fields, options = {}) => {
+    const crypto = await Promise.resolve().then(() => __importStar(require("node:crypto")));
+    const filtered = fields
+        .filter((f) => options.includeSystem || !f.name.startsWith("__"))
+        .map((f) => ({ name: f.name, value: (f.value ?? "").trim() }))
+        .filter((f) => f.value.length > 0);
+    // An item with no authored content has nothing to fingerprint. Return
+    // empty string so callers' `if (!hash) continue;` correctly skips it —
+    // otherwise every empty item shares sha256("") = "e3b0c44298fc1c14",
+    // bucketing unrelated blank items into a single false-positive
+    // "duplicate group" in `audit duplicates`.
+    if (filtered.length === 0)
+        return "";
+    filtered.sort((a, b) => a.name.localeCompare(b.name));
+    const input = filtered.map((f) => `${f.name}\0${f.value}`).join("");
+    return crypto.createHash("sha256").update(input).digest("hex").slice(0, 16);
+};
+exports.computeContentHash = computeContentHash;
+/**
+ * Sitecore's `__Final Page Design` (or fallback `__Page Design`) field
+ * holds a page design itemId GUID. Empty string means "inherit from
+ * ancestor / no override."
+ */
+exports.PAGE_DESIGN_FIELDS = ["__Final Page Design", "__Page Design"];
+const isPageDesignField = (fieldName) => exports.PAGE_DESIGN_FIELDS.includes(fieldName);
+exports.isPageDesignField = isPageDesignField;
+const resolveScanFilters = (options) => {
+    const excludePaths = options.exclude?.length
+        ? options.exclude.map((p) => p.toLowerCase()).filter((p) => p.length > 0)
+        : undefined;
+    let sinceMs;
+    if (options.since) {
+        const ts = Date.parse(options.since);
+        if (Number.isFinite(ts))
+            sinceMs = ts;
+        else
+            throw (0, errors_1.createScaiError)(`--since '${options.since}' is not a valid ISO date.`, "INPUT_INVALID", { hint: "Use YYYY-MM-DD or a full ISO 8601 timestamp." });
+    }
+    return { excludePaths, sinceMs, owner: options.owner };
+};
+exports.resolveScanFilters = resolveScanFilters;
+/** Returns true if the search result should be excluded by the filters. */
+const matchesScanFilters = (r, filters) => {
+    if (filters.excludePaths) {
+        const p = r.path?.toLowerCase() ?? "";
+        if (filters.excludePaths.some((e) => p.startsWith(e)))
+            return false;
+    }
+    if (filters.sinceMs !== undefined) {
+        const t = r.updatedDate ? Date.parse(r.updatedDate) : NaN;
+        if (!Number.isFinite(t) || t < filters.sinceMs)
+            return false;
+    }
+    // The owner filter is harder — `createdBy` / `updatedBy` aren't on
+    // SearchResultItem. Defer to the audit task layer when needed; we
+    // can't filter here without a per-item Authoring API call. (Kept on
+    // the interface so the helper signature is forward-compatible.)
+    return true;
+};
+exports.matchesScanFilters = matchesScanFilters;
+const scanItemsAndFields = async ({ client, envName, root, logger, options, latestVersionOnly = true, skipFields = false, }) => {
+    const knobs = (0, exports.resolveHygieneKnobs)(options);
+    const cacheEnabled = options.cache ?? (0, cache_1.isAuditCacheEnabled)();
+    const cache = cacheEnabled ? (0, cache_1.createFieldCache)({ envName, logger }) : null;
+    const limit = options.limit ?? 5000;
+    const includeSystem = Boolean(options.includeSystem);
+    const filters = (0, exports.resolveScanFilters)({
+        exclude: options.exclude,
+        since: options.since,
+        owner: options.owner,
+    });
+    // Resolve root path → itemId.
+    let rootItemId;
+    if (root) {
+        const r = await client.search({
+            index: options.index,
+            paging: { pageSize: 1 },
+            searchStatement: {
+                criteria: { field: "_fullpath", value: root.toLowerCase(), criteriaType: "EXACT" },
+            },
+        });
+        rootItemId = r.results[0]?.itemId;
+        if (!rootItemId) {
+            logger.warn(`Root path '${root}' not found in search index — scanning entire master DB.`);
+        }
+    }
+    // Paged enumeration with optional parallel page-windows.
+    const scanned = [];
+    for await (const r of client.searchAll({
+        index: options.index,
+        latestVersionOnly,
+        ...(options.language && { language: options.language }),
+        ...(rootItemId && { searchStatement: (0, exports.buildPathFilterStatement)(rootItemId) }),
+    }, 100, knobs.pageParallelism)) {
+        if (!includeSystem && (0, exports.isSystemPath)(r.path))
+            continue;
+        if (!(0, exports.matchesScanFilters)(r, filters))
+            continue;
+        scanned.push({
+            itemId: (0, exports.normalizeItemId)(r.itemId),
+            path: r.path,
+            name: r.name,
+            templateName: r.templateName ?? null,
+            templateId: r.templateId ?? null,
+            language: r.language?.name ?? null,
+            version: r.version ?? null,
+            createdDate: r.createdDate ?? null,
+            updatedDate: r.updatedDate ?? null,
+        });
+        if (scanned.length >= limit)
+            break;
+    }
+    logger.verbose(`Scanned ${scanned.length} items (concurrency=${knobs.concurrency}, batchSize=${knobs.batchSize}, pageParallel=${knobs.pageParallelism}${cache ? ", cache=on" : ""}).`);
+    // Skip the field-fetch phase if caller doesn't need fields.
+    if (skipFields) {
+        return { scanned, fieldsByItemId: new Map(), cache, knobs };
+    }
+    // Build per-item updatedDate map for cache freshness.
+    const updatedDateByItemId = new Map();
+    for (const s of scanned)
+        updatedDateByItemId.set(s.itemId, s.updatedDate);
+    // Choose the underlying fetcher — either direct, or cache-wrapped.
+    const getFieldsBatch = cache
+        ? (0, cache_1.wrapFieldsBatchWithCache)((ids) => client.getItemFieldsBatch(ids), cache, updatedDateByItemId)
+        : (ids) => client.getItemFieldsBatch(ids);
+    // Batch + fan out.
+    const batches = [];
+    for (let i = 0; i < scanned.length; i += knobs.batchSize) {
+        batches.push(scanned.slice(i, i + knobs.batchSize).map((s) => s.itemId));
+    }
+    const batchResults = await (0, cli_tasks_1.mapWithConcurrency)(batches, (ids) => getFieldsBatch(ids), knobs.concurrency);
+    const fieldsByItemId = new Map();
+    for (const m of batchResults) {
+        for (const [id, fields] of m)
+            fieldsByItemId.set(id, fields ?? null);
+    }
+    if (cache) {
+        const stats = cache.stats();
+        logger.verbose(`Cache stats: ${stats.hits} hits / ${stats.misses} misses (${stats.size} stored).`);
+    }
+    return { scanned, fieldsByItemId, cache, knobs };
+};
+exports.scanItemsAndFields = scanItemsAndFields;
+var allow_write_1 = require("../../policy/allow-write");
+Object.defineProperty(exports, "ensureAllowWriteForCleanup", { enumerable: true, get: function () { return allow_write_1.ensureAllowWrite; } });

package/dist/mcp/auth.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Resolves the environment binding for `scai mcp serve` and packages
+ * everything tool handlers need into a single `McpContext`.
+ *
+ * One server instance, ONE bound/default env — but, since the
+ * multi-environment ("Option B") redesign, every environment-scoped
+ * tool call may target ANY configured environment. The bound env is
+ * the default; `resolveEnvBinding` resolves any other env on demand.
+ *
+ * Two-phase resolution so the stdio transport can answer the MCP
+ * `initialize` handshake before any keychain access happens:
+ *
+ *   1. `resolveMcpEnv` — synchronous, reads the config file from disk
+ *      and validates the named environment. Throws on missing config
+ *      or unknown env so startup fails fast and loudly.
+ *
+ *   2. `createMcpContextProvider` — returns a memoized async getter
+ *      that fetches the deploy token from the OS keychain on first
+ *      invocation. Tool dispatchers `await` this; concurrent first
+ *      calls share the same in-flight promise so the keychain prompt
+ *      surfaces once, not per-call. Failures are not cached, so a
+ *      subsequent tool call retries after the operator unlocks the
+ *      keychain or runs `scai setup login`.
+ *
+ * Per-call retargeting: `resolveEnvBinding(configPath, envName)`
+ * resolves any environment on demand and is memoized per
+ * `configPath::envName` so a retargeted tool call doesn't re-mint a
+ * deploy token on every invocation. The bound `McpContext` is a
+ * superset of an `EnvBinding`, so handlers can treat either uniformly.
+ *
+ * The Authoring API access token is acquired lazily on first use —
+ * recipe and serialization tools handle their own OAuth flow because
+ * the authoring credentials may differ from the deploy credentials.
+ */
+import { type ResolvedEnvironment } from "../policy/environment";
+/**
+ * Everything a tool handler needs to talk to ONE environment. The bound
+ * `McpContext` is structurally a superset of this — a handler that
+ * accepts an `EnvBinding` works equally with the bound context or a
+ * per-call retargeted binding.
+ */
+export interface EnvBinding {
+    envName: string;
+    resolved: ResolvedEnvironment;
+    allowWriteEnabled: boolean;
+    /** Deploy access token for this environment. */
+    deployToken: string;
+}
+export interface McpContext extends EnvBinding {
+    /** The bound/default environment's name. Same as `envName`. */
+    envName: string;
+    configPath: string;
+    resolved: ResolvedEnvironment;
+    allowWriteEnabled: boolean;
+    /** Cached deploy access token (resolved on first tool call). */
+    deployToken: string;
+}
+export interface BindMcpEnvironmentOptions {
+    configPath?: string;
+    environmentName?: string;
+}
+export type McpContextProvider = () => Promise<McpContext>;
+export declare const resolveMcpEnv: (options: BindMcpEnvironmentOptions) => ResolvedEnvironment;
+export declare const createMcpContextProvider: (resolved: ResolvedEnvironment, configPath: string) => McpContextProvider;
+export declare const bindMcpEnvironment: (options: BindMcpEnvironmentOptions) => Promise<McpContext>;
+export declare const resolveEnvBinding: (configPath: string, envName: string) => Promise<EnvBinding>;
+/**
+ * Test-only — clears the per-`configPath::envName` binding cache so
+ * memoization state doesn't leak across `describe` blocks.
+ */
+export declare const __resetEnvBindingCacheForTests: () => void;
+/**
+ * Resolve the `EnvBinding` an environment-scoped tool should operate
+ * against. When `environmentName` is omitted (the common case), returns
+ * the bound `McpContext` itself — it IS an `EnvBinding` — so behavior is
+ * byte-for-byte identical to the pre-Option-B single-env server. When
+ * set, resolves (and memoizes) the named environment via
+ * `resolveEnvBinding`.
+ */
+export declare const resolveToolBinding: (context: McpContext, environmentName: string | undefined) => Promise<EnvBinding>;