@sitecoreai-labs/sitecoreai-cli 0.0.4

package/dist/recipe/schema/source-fields.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Renderer for the structured source fields on `SitecoreFieldAugment`.
+ *
+ * The recipe author surface decomposes Sitecore's `Source` field into
+ * orthogonal pieces:
+ *
+ *   sourceTypes   string[]   — picker filter (template handles)
+ *   sourceQuery   string     — where to look (Sitecore Query)
+ *   sourceScope   string     — where to look (fixed content path)
+ *   sourceRaw     string     — escape hatch (verbatim Source string)
+ *
+ * `renderSourceFields` composes them into the URL-encoded Source value
+ * Sitecore expects. The combinations preserve longstanding Sitecore
+ * semantics:
+ *
+ *   sourceQuery alone        → `query:<query>`         (Droplist shorthand)
+ *   sourceTypes alone        → `IncludeTemplatesForSelection={GUID},...`
+ *   sourceScope alone        → `DataSource=<path>`
+ *   sourceQuery + types      → `DataSource=query:<query>&IncludeTemplatesForSelection=...`
+ *   sourceScope + types      → `DataSource=<path>&IncludeTemplatesForSelection=...`
+ *   sourceRaw                → verbatim, ignores everything else
+ *
+ * Authors who need a Source form outside this surface (e.g. a bare
+ * `/sitecore/content/Tags` Treelist source) use `sourceRaw`.
+ */
+export interface SourceFields {
+    sourceTypes?: readonly string[];
+    sourceQuery?: string;
+    sourceScope?: string;
+    sourceRaw?: string;
+}
+/**
+ * Compose structured source fields into the Sitecore-encoded Source string.
+ * `resolveHandle` maps a recipe handle to its deterministic template GUID
+ * (typically `templateId(handle)` from `guids.ts`).
+ *
+ * Returns `undefined` when no source fields are set — callers can use this
+ * to decide whether to emit the Source field at all.
+ */
+export declare const renderSourceFields: (fields: SourceFields, resolveHandle: (handle: string) => string) => string | undefined;
+/**
+ * True when the structured source fields require recipe-handle resolution
+ * to render. The compiler uses this to decide between emitting a plain
+ * `string` RefValue at compile time vs deferring to the executor via
+ * `ref-source-fields`.
+ */
+export declare const sourceFieldsNeedHandleResolution: (fields: SourceFields) => boolean;
+//# sourceMappingURL=source-fields.d.ts.map

package/dist/recipe/schema/source-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-fields.d.ts","sourceRoot":"","sources":["../../../src/recipe/schema/source-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,WAAW,YAAY;IAC3B,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,YAAY,EACpB,eAAe,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,KACxC,MAAM,GAAG,SAmCX,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,GAAI,QAAQ,YAAY,KAAG,OACJ,CAAC"}

package/dist/recipe/schema/source-fields.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Renderer for the structured source fields on `SitecoreFieldAugment`.
+ *
+ * The recipe author surface decomposes Sitecore's `Source` field into
+ * orthogonal pieces:
+ *
+ *   sourceTypes   string[]   — picker filter (template handles)
+ *   sourceQuery   string     — where to look (Sitecore Query)
+ *   sourceScope   string     — where to look (fixed content path)
+ *   sourceRaw     string     — escape hatch (verbatim Source string)
+ *
+ * `renderSourceFields` composes them into the URL-encoded Source value
+ * Sitecore expects. The combinations preserve longstanding Sitecore
+ * semantics:
+ *
+ *   sourceQuery alone        → `query:<query>`         (Droplist shorthand)
+ *   sourceTypes alone        → `IncludeTemplatesForSelection={GUID},...`
+ *   sourceScope alone        → `DataSource=<path>`
+ *   sourceQuery + types      → `DataSource=query:<query>&IncludeTemplatesForSelection=...`
+ *   sourceScope + types      → `DataSource=<path>&IncludeTemplatesForSelection=...`
+ *   sourceRaw                → verbatim, ignores everything else
+ *
+ * Authors who need a Source form outside this surface (e.g. a bare
+ * `/sitecore/content/Tags` Treelist source) use `sourceRaw`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sourceFieldsNeedHandleResolution = exports.renderSourceFields = void 0;
+const formatGuidCurly = (guid) => `{${guid.toUpperCase()}}`;
+/**
+ * Compose structured source fields into the Sitecore-encoded Source string.
+ * `resolveHandle` maps a recipe handle to its deterministic template GUID
+ * (typically `templateId(handle)` from `guids.ts`).
+ *
+ * Returns `undefined` when no source fields are set — callers can use this
+ * to decide whether to emit the Source field at all.
+ */
+const renderSourceFields = (fields, resolveHandle) => {
+    if (fields.sourceRaw !== undefined) {
+        return fields.sourceRaw;
+    }
+    const types = fields.sourceTypes && fields.sourceTypes.length > 0 ? fields.sourceTypes : undefined;
+    const query = fields.sourceQuery;
+    const scope = fields.sourceScope;
+    if (!types && !query && !scope) {
+        return undefined;
+    }
+    const includeTemplates = types
+        ? `IncludeTemplatesForSelection=${types.map((h) => formatGuidCurly(resolveHandle(h))).join(",")}`
+        : undefined;
+    // Standalone forms preserve Sitecore's per-field-type shorthand.
+    if (!types && query && !scope) {
+        return `query:${query}`;
+    }
+    if (types && !query && !scope) {
+        return includeTemplates;
+    }
+    if (!types && !query && scope) {
+        return `DataSource=${scope}`;
+    }
+    // Combined form — URL-encoded property bag.
+    const parts = [];
+    if (query)
+        parts.push(`DataSource=query:${query}`);
+    else if (scope)
+        parts.push(`DataSource=${scope}`);
+    if (includeTemplates)
+        parts.push(includeTemplates);
+    return parts.join("&");
+};
+exports.renderSourceFields = renderSourceFields;
+/**
+ * True when the structured source fields require recipe-handle resolution
+ * to render. The compiler uses this to decide between emitting a plain
+ * `string` RefValue at compile time vs deferring to the executor via
+ * `ref-source-fields`.
+ */
+const sourceFieldsNeedHandleResolution = (fields) => Array.isArray(fields.sourceTypes) && fields.sourceTypes.length > 0;
+exports.sourceFieldsNeedHandleResolution = sourceFieldsNeedHandleResolution;

package/dist/recipe/tasks/compile.d.ts

@@ -0,0 +1,14 @@
+import { type RecipeCompileOptions } from "./shared";
+/**
+ * `scai recipe compile` — pure-logic: recipe (.ts or .json) → Operation IR JSON.
+ *
+ * Resolves inputs from `--input` (single file) or the config `recipes`
+ * glob (zero-to-many files). Writes one IR per recipe at
+ * `--output` (single mode) or `<dir>/<handle>.ir.json` (multi mode).
+ *
+ * No tenant access — the IR is tenant-shaped (`templatesRoot`,
+ * `renderingsRoot` are CLI inputs), so re-compile if the same recipe
+ * lands in a different tenant tree.
+ */
+export declare const runRecipeCompile: (options: RecipeCompileOptions) => Promise<void>;
+//# sourceMappingURL=compile.d.ts.map

package/dist/recipe/tasks/compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../../src/recipe/tasks/compile.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,UAAU,CAAC;AAElB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,GAAU,SAAS,oBAAoB,KAAG,OAAO,CAAC,IAAI,CAsFlF,CAAC"}

package/dist/recipe/tasks/compile.js

@@ -0,0 +1,89 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runRecipeCompile = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const config_1 = require("../../config");
+const errors_1 = require("../../shared/errors");
+const compile_1 = require("../compile");
+const io_1 = require("../io");
+const shared_1 = require("./shared");
+/**
+ * `scai recipe compile` — pure-logic: recipe (.ts or .json) → Operation IR JSON.
+ *
+ * Resolves inputs from `--input` (single file) or the config `recipes`
+ * glob (zero-to-many files). Writes one IR per recipe at
+ * `--output` (single mode) or `<dir>/<handle>.ir.json` (multi mode).
+ *
+ * No tenant access — the IR is tenant-shaped (`templatesRoot`,
+ * `renderingsRoot` are CLI inputs), so re-compile if the same recipe
+ * lands in a different tenant tree.
+ */
+const runRecipeCompile = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const root = (0, config_1.readRootConfiguration)(options.config ?? process.cwd(), options.environmentName);
+    // Resolve parent paths from CLI flags or active env profile (when given).
+    const envName = options.environmentName ?? root.defaultEnvironment;
+    const environment = envName ? root.environments[envName] : undefined;
+    const { templatesRoot, renderingsRoot } = (0, shared_1.resolveRecipeRoots)(options, environment, envName ?? "(no environment)");
+    // Phase 2 per-site folder layout roots — optional. When unset the
+    // compiler falls back to `templatesRoot` for both, which means
+    // section-aware components nest under templatesRoot (mid-migration
+    // fallback) and content templates land mixed in with components.
+    const componentsRoot = options.componentsRoot ?? environment?.componentsRoot;
+    const contentModelsRoot = options.contentModelsRoot ?? environment?.contentModelsRoot;
+    // Phase 4 composition roots — optional. The per-recipe compile fns
+    // throw with their own clear messages when a partial-design /
+    // page-design / content-item recipe is in play but the corresponding
+    // root is missing.
+    const partialDesignsRoot = options.partialDesignsRoot ?? environment?.partialDesignsRoot;
+    const pageDesignsRoot = options.pageDesignsRoot ?? environment?.pageDesignsRoot;
+    const contentItemsRoot = options.contentItemsRoot ?? environment?.contentItemsRoot;
+    const headlessVariantsRoot = options.headlessVariantsRoot ?? environment?.headlessVariantsRoot;
+    const availableRenderingsRoot = options.availableRenderingsRoot ?? environment?.availableRenderingsRoot;
+    const enumerationsRoot = options.enumerationsRoot ?? environment?.enumerationsRoot;
+    const { files, source } = await (0, shared_1.resolveRecipeInputs)(options, root);
+    if (options.output && files.length > 1) {
+        throw (0, errors_1.createCliError)("--output cannot be combined with multi-file compile.", "INPUT_INVALID", {
+            hint: "Compile a single recipe with --input <file> --output <ir>, or omit --output to write per-recipe IRs to <dir>/<handle>.ir.json.",
+        });
+    }
+    const results = [];
+    for (const file of files) {
+        const recipe = await (0, io_1.loadRecipe)(file);
+        const ir = (0, compile_1.compileRecipe)(recipe, {
+            templatesRoot,
+            renderingsRoot,
+            componentsRoot,
+            contentModelsRoot,
+            partialDesignsRoot,
+            pageDesignsRoot,
+            contentItemsRoot,
+            headlessVariantsRoot,
+            availableRenderingsRoot,
+            enumerationsRoot,
+        });
+        const outputPath = options.output ?? (0, io_1.defaultIrPath)(recipe.handle, node_path_1.default.dirname(node_path_1.default.resolve(file)));
+        await (0, io_1.writeIr)(outputPath, ir);
+        results.push({
+            recipeHandle: recipe.handle,
+            input: file,
+            output: outputPath,
+            operationCount: ir.operations.length,
+        });
+        if (!logger.isJson()) {
+            logger.info(`Compiled ${recipe.handle} → ${outputPath}`, "green");
+            logger.info(`  ${ir.operations.length} operation${ir.operations.length === 1 ? "" : "s"}.`);
+        }
+    }
+    if (logger.isJson()) {
+        logger.json({
+            command: "recipe.compile",
+            source,
+            results,
+        });
+    }
+};
+exports.runRecipeCompile = runRecipeCompile;

package/dist/recipe/tasks/diff.d.ts

@@ -0,0 +1,17 @@
+import type { ExecutionResult } from "../execute";
+import type { RecipePushOptions } from "./shared";
+/**
+ * `scai recipe diff` — read-only "what would change" against a tenant.
+ *
+ * Drives the same input resolution, in-memory compile, and planner
+ * as `recipe push`, but read-only by construction: `whatIf` is forced
+ * on, `allowWrite` is ignored (no `ensureAllowWrite` gate fires
+ * because dry-run mode skips it), and no Sites API job ever dispatches.
+ *
+ * Operators reach for `diff` when reviewing a change set; reach for
+ * `recipe push --what-if` when they're about to apply and want a
+ * last-look. Same output, different framing.
+ */
+export type RecipeDiffOptions = Omit<RecipePushOptions, "whatIf" | "allowWrite">;
+export declare const runRecipeDiff: (options: RecipeDiffOptions) => Promise<ExecutionResult[]>;
+//# sourceMappingURL=diff.d.ts.map

package/dist/recipe/tasks/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../../src/recipe/tasks/diff.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAElD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,EAAE,QAAQ,GAAG,YAAY,CAAC,CAAC;AAEjF,eAAO,MAAM,aAAa,GAAU,SAAS,iBAAiB,KAAG,OAAO,CAAC,eAAe,EAAE,CAC7C,CAAC"}

package/dist/recipe/tasks/diff.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runRecipeDiff = void 0;
+const push_1 = require("./push");
+const runRecipeDiff = async (options) => (0, push_1.runRecipePush)({ ...options, whatIf: true });
+exports.runRecipeDiff = runRecipeDiff;

package/dist/recipe/tasks/index.d.ts

@@ -0,0 +1,9 @@
+export { runRecipeCompile } from "./compile";
+export { runRecipeDiff } from "./diff";
+export type { RecipeDiffOptions } from "./diff";
+export { runRecipePlan } from "./plan";
+export { runRecipePush } from "./push";
+export { runRecipePruneDefaults } from "./prune-defaults";
+export type { RecipePruneDefaultsOptions, RecipePruneDefaultsResult } from "./prune-defaults";
+export type { RecipeCompileOptions, RecipePlanOptions, RecipePushOptions } from "./shared";
+//# sourceMappingURL=index.d.ts.map

package/dist/recipe/tasks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/recipe/tasks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,YAAY,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,YAAY,EAAE,0BAA0B,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAC9F,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC"}

package/dist/recipe/tasks/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runRecipePruneDefaults = exports.runRecipePush = exports.runRecipePlan = exports.runRecipeDiff = exports.runRecipeCompile = void 0;
+var compile_1 = require("./compile");
+Object.defineProperty(exports, "runRecipeCompile", { enumerable: true, get: function () { return compile_1.runRecipeCompile; } });
+var diff_1 = require("./diff");
+Object.defineProperty(exports, "runRecipeDiff", { enumerable: true, get: function () { return diff_1.runRecipeDiff; } });
+var plan_1 = require("./plan");
+Object.defineProperty(exports, "runRecipePlan", { enumerable: true, get: function () { return plan_1.runRecipePlan; } });
+var push_1 = require("./push");
+Object.defineProperty(exports, "runRecipePush", { enumerable: true, get: function () { return push_1.runRecipePush; } });
+var prune_defaults_1 = require("./prune-defaults");
+Object.defineProperty(exports, "runRecipePruneDefaults", { enumerable: true, get: function () { return prune_defaults_1.runRecipePruneDefaults; } });

package/dist/recipe/tasks/placeholder-allow.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Placeholder allow-controls resolver — runs after `runRecipePush`'s
+ * IR loop to register each recipe's rendering with the SXA placeholder
+ * slots it declares compatibility with.
+ *
+ * Why this lives outside the IR pipeline: scai's IR ops target items
+ * by recipe-internal refKey or known content-tree path. Placeholder
+ * Settings items are looked up by their `Placeholder Key` *field
+ * value*, which the compiler can't know in advance — different
+ * tenants name their placeholder items differently while sharing the
+ * same key. So this step does a runtime walk of the configured roots
+ * and matches by field, then updates `Allowed Controls` directly via
+ * the Authoring API.
+ *
+ * Idempotent: existing entries on `Allowed Controls` are preserved;
+ * we only append IDs that aren't already there. Safe to re-run.
+ */
+import type { AuthoringApiClient } from "../api/client";
+import type { Recipe } from "../schema/recipe";
+export interface PlaceholderAllowResult {
+    /** Number of placeholder items whose Allowed Controls field was updated. */
+    patched: number;
+    /** Number of `(placeholder, rendering)` pairs added across all updates. */
+    totalAdded: number;
+    /** Recipe handles whose rendering item couldn't be resolved on the tenant. */
+    unresolvedRecipeHandles: string[];
+    /** Recipe placeholder keys with no matching Placeholder item under any root. */
+    unmatchedPlaceholderKeys: string[];
+}
+export interface PlaceholderAllowOptions {
+    client: AuthoringApiClient;
+    recipes: readonly Recipe[];
+    renderingsRoot: string;
+    placeholderSettingsRoots: readonly string[];
+    /** When false, plan but do not write. */
+    apply: boolean;
+    /** Per-update progress hook. Called with placeholder path + how many entries were added. */
+    onUpdate?: (placeholderPath: string, added: number) => void;
+}
+/**
+ * Resolve every component-template recipe's `placeholders` declarations
+ * against the tenant and append the recipe's rendering itemId to each
+ * matching `Allowed Controls` field. Returns a summary so callers can
+ * surface the resolver's reach in their command output.
+ *
+ * Failure modes (each surfaced in the result, none fatal):
+ *   - Rendering item missing on tenant → recipe handle in
+ *     `unresolvedRecipeHandles`; that recipe's placeholders are skipped.
+ *   - Placeholder key never matched → key in `unmatchedPlaceholderKeys`;
+ *     other matches still apply.
+ */
+export declare const applyPlaceholderAllowControls: (options: PlaceholderAllowOptions) => Promise<PlaceholderAllowResult>;
+//# sourceMappingURL=placeholder-allow.d.ts.map

package/dist/recipe/tasks/placeholder-allow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placeholder-allow.d.ts","sourceRoot":"","sources":["../../../src/recipe/tasks/placeholder-allow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAc,MAAM,eAAe,CAAC;AAMpE,OAAO,KAAK,EAA2B,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAsHxE,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,uBAAuB,EAAE,MAAM,EAAE,CAAC;IAClC,gFAAgF;IAChF,wBAAwB,EAAE,MAAM,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,wBAAwB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,yCAAyC;IACzC,KAAK,EAAE,OAAO,CAAC;IACf,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,CAAC,eAAe,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7D;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,6BAA6B,GACxC,SAAS,uBAAuB,KAC/B,OAAO,CAAC,sBAAsB,CAqGhC,CAAC"}

package/dist/recipe/tasks/placeholder-allow.js

@@ -0,0 +1,218 @@
+"use strict";
+/**
+ * Placeholder allow-controls resolver — runs after `runRecipePush`'s
+ * IR loop to register each recipe's rendering with the SXA placeholder
+ * slots it declares compatibility with.
+ *
+ * Why this lives outside the IR pipeline: scai's IR ops target items
+ * by recipe-internal refKey or known content-tree path. Placeholder
+ * Settings items are looked up by their `Placeholder Key` *field
+ * value*, which the compiler can't know in advance — different
+ * tenants name their placeholder items differently while sharing the
+ * same key. So this step does a runtime walk of the configured roots
+ * and matches by field, then updates `Allowed Controls` directly via
+ * the Authoring API.
+ *
+ * Idempotent: existing entries on `Allowed Controls` are preserved;
+ * we only append IDs that aren't already there. Safe to re-run.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyPlaceholderAllowControls = void 0;
+const ref_encoding_1 = require("../api/ref-encoding");
+const sitecore_templates_1 = require("../ir/sitecore-templates");
+const joinPath = (parent, name) => parent.endsWith("/") ? `${parent}${name}` : `${parent}/${name}`;
+const isPlaceholder = (item) => normaliseGuid(item.templateId) === normaliseGuid(sitecore_templates_1.PLACEHOLDER_TEMPLATE_ID);
+const normaliseGuid = (guid) => guid.replace(/[{}-]/g, "").toLowerCase();
+const toCurly = (guid) => `{${(0, ref_encoding_1.dashifyGuid)(guid).toUpperCase()}}`;
+/**
+ * Look up the rendering's itemId for a component-template recipe.
+ * Mirrors the path the recipe push compiler emits at:
+ *   `<renderingsRoot>/<section>/<recipe.name>` (when section is set)
+ *   `<renderingsRoot>/<recipe.name>` (legacy flat layout)
+ *
+ * Returns null when the rendering item isn't on the tenant — usually
+ * because the recipe's IR aborted before creating it. The caller skips
+ * that recipe instead of failing the whole resolver.
+ */
+const resolveRenderingItemId = async (client, renderingsRoot, recipe, sectionName) => {
+    const path = sectionName
+        ? joinPath(joinPath(renderingsRoot, sectionName), recipe.name)
+        : joinPath(renderingsRoot, recipe.name);
+    const item = await client.getItem({ path });
+    return item ? item.itemId : null;
+};
+/**
+ * Walk the configured Placeholder Settings roots once and collect
+ * every Placeholder item with its `Placeholder Key` value. Doesn't
+ * filter — callers match keys against this collected list. Recursive
+ * so nested folders (Partial Design / Page Designs / Container 70 /
+ * etc.) are all visited.
+ */
+const collectPlaceholders = async (client, roots) => {
+    const found = [];
+    const visit = async (path) => {
+        const item = await client.getItem({ path });
+        if (!item)
+            return;
+        if (isPlaceholder(item)) {
+            const keyField = item.fields.find((f) => normaliseGuid(f.fieldId) ===
+                normaliseGuid(sitecore_templates_1.PLACEHOLDER_FIELDS.PLACEHOLDER_KEY));
+            const placeholderKey = keyField?.value?.trim();
+            if (placeholderKey) {
+                found.push({ item, placeholderKey });
+            }
+            // A Placeholder item may itself contain children (e.g. a default
+            // Allowed Controls subtree). Recurse anyway — cheap, and safer
+            // than assuming leaf-only.
+        }
+        const children = await client.getChildren({ path });
+        for (const child of children) {
+            await visit(child.path);
+        }
+    };
+    for (const root of roots) {
+        await visit(root);
+    }
+    return found;
+};
+const findAllowedControlsValue = (item) => {
+    const field = item.fields.find((f) => normaliseGuid(f.fieldId) ===
+        normaliseGuid(sitecore_templates_1.PLACEHOLDER_FIELDS.ALLOWED_CONTROLS));
+    return field?.value ?? "";
+};
+const splitMultilist = (value) => value
+    .split("|")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+const mergeAllowedControls = (existing, toAdd) => {
+    // Normalise existing entries to dashed-curly form so de-dup works
+    // regardless of what shape was previously stored (some tools write
+    // `{NODASH}`, others `{DASHED}`). Final value uses dashed-curly
+    // only — that's what Sitecore's Treelist resolver expects.
+    const seen = new Set();
+    const result = [];
+    for (const entry of splitMultilist(existing)) {
+        const canonical = toCurly(entry);
+        if (seen.has(canonical))
+            continue;
+        seen.add(canonical);
+        result.push(canonical);
+    }
+    let added = 0;
+    for (const itemId of toAdd) {
+        const canonical = toCurly(itemId);
+        if (seen.has(canonical))
+            continue;
+        seen.add(canonical);
+        result.push(canonical);
+        added += 1;
+    }
+    return { value: result.join("|"), added };
+};
+/**
+ * Resolve every component-template recipe's `placeholders` declarations
+ * against the tenant and append the recipe's rendering itemId to each
+ * matching `Allowed Controls` field. Returns a summary so callers can
+ * surface the resolver's reach in their command output.
+ *
+ * Failure modes (each surfaced in the result, none fatal):
+ *   - Rendering item missing on tenant → recipe handle in
+ *     `unresolvedRecipeHandles`; that recipe's placeholders are skipped.
+ *   - Placeholder key never matched → key in `unmatchedPlaceholderKeys`;
+ *     other matches still apply.
+ */
+const applyPlaceholderAllowControls = async (options) => {
+    const { client, recipes, renderingsRoot, placeholderSettingsRoots, apply, onUpdate } = options;
+    // Build the section handle → name map so we can resolve each
+    // component's `section.handle` to a name for the rendering path.
+    const sectionsByHandle = new Map();
+    for (const recipe of recipes) {
+        if (recipe.kind === "component-section") {
+            sectionsByHandle.set(recipe.handle, recipe.name);
+        }
+    }
+    // Collect: placeholderKey → Set<renderingItemId>
+    const keyToRenderings = new Map();
+    const unresolvedRecipeHandles = [];
+    for (const recipe of recipes) {
+        if (recipe.kind !== "component-template")
+            continue;
+        // `placedIn` is the placement allow-list — placeholder keys this
+        // rendering can be placed into. Distinct from `placeholders`, which
+        // is for slots this component DEFINES (handled elsewhere).
+        const keys = recipe.placedIn ?? [];
+        if (keys.length === 0)
+            continue;
+        const sectionName = recipe.section
+            ? sectionsByHandle.get(recipe.section.handle)
+            : undefined;
+        const renderingItemId = await resolveRenderingItemId(client, renderingsRoot, recipe, sectionName);
+        if (!renderingItemId) {
+            unresolvedRecipeHandles.push(recipe.handle);
+            continue;
+        }
+        for (const key of keys) {
+            let bucket = keyToRenderings.get(key);
+            if (!bucket) {
+                bucket = new Set();
+                keyToRenderings.set(key, bucket);
+            }
+            bucket.add(renderingItemId);
+        }
+    }
+    if (keyToRenderings.size === 0) {
+        return {
+            patched: 0,
+            totalAdded: 0,
+            unresolvedRecipeHandles,
+            unmatchedPlaceholderKeys: [],
+        };
+    }
+    if (placeholderSettingsRoots.length === 0) {
+        // Recipes asked for placeholder registration but no roots are
+        // configured — surface that as "every requested key unmatched"
+        // so the caller's summary makes the gap visible.
+        return {
+            patched: 0,
+            totalAdded: 0,
+            unresolvedRecipeHandles,
+            unmatchedPlaceholderKeys: Array.from(keyToRenderings.keys()),
+        };
+    }
+    const placeholders = await collectPlaceholders(client, placeholderSettingsRoots);
+    const matchedKeys = new Set();
+    let patched = 0;
+    let totalAdded = 0;
+    for (const { item, placeholderKey } of placeholders) {
+        const renderings = keyToRenderings.get(placeholderKey);
+        if (!renderings)
+            continue;
+        matchedKeys.add(placeholderKey);
+        const existing = findAllowedControlsValue(item);
+        const merged = mergeAllowedControls(existing, Array.from(renderings));
+        if (merged.added === 0 && merged.value === existing)
+            continue;
+        if (apply) {
+            await client.updateItem({
+                itemId: item.itemId,
+                fields: [
+                    {
+                        fieldId: sitecore_templates_1.PLACEHOLDER_FIELDS.ALLOWED_CONTROLS,
+                        fieldName: "Allowed Controls",
+                        value: { kind: "string", value: merged.value },
+                    },
+                ],
+            });
+        }
+        onUpdate?.(item.path, merged.added);
+        patched += 1;
+        totalAdded += merged.added;
+    }
+    const unmatchedPlaceholderKeys = [];
+    for (const key of keyToRenderings.keys()) {
+        if (!matchedKeys.has(key))
+            unmatchedPlaceholderKeys.push(key);
+    }
+    return { patched, totalAdded, unresolvedRecipeHandles, unmatchedPlaceholderKeys };
+};
+exports.applyPlaceholderAllowControls = applyPlaceholderAllowControls;

package/dist/recipe/tasks/plan.d.ts

@@ -0,0 +1,11 @@
+import { type Plan } from "../plan";
+import { type RecipePlanOptions } from "./shared";
+/**
+ * `scai recipe plan` — read-then-diff against a tenant, no mutations.
+ *
+ * Operates on a pre-compiled IR file (the artifact from `scai recipe
+ * compile`). For the recipe-source workflow, use `scai recipe push
+ * --what-if` instead — it compiles in-memory and runs the planner.
+ */
+export declare const runRecipePlan: (options: RecipePlanOptions) => Promise<Plan>;
+//# sourceMappingURL=plan.d.ts.map

package/dist/recipe/tasks/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../../src/recipe/tasks/plan.ts"],"names":[],"mappings":"AAGA,OAAO,EAAa,KAAK,IAAI,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE3E;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GAAU,SAAS,iBAAiB,KAAG,OAAO,CAAC,IAAI,CAkD5E,CAAC"}