@sitecoreai-labs/sitecoreai-cli 0.0.4

package/dist/recipe/compile/content-item.d.ts

@@ -0,0 +1,31 @@
+import { type OperationIr } from "../ir/operations";
+import { type ContentItemRecipe } from "../schema/recipe";
+import { type CompileContext } from "./shared";
+/**
+ * Compile a `ContentItemRecipe` to an Operation IR.
+ *
+ * Emits one `CreateItem` for the content item plus one `SetField` per
+ * field value. The item's `templateOf` resolves via `templateId(templateType)`
+ * — the corresponding `ContentTemplateRecipe` (or `ComponentTemplateRecipe`)
+ * must ship in the same set so the executor's captured-itemId map carries
+ * its server-assigned GUID at apply time. The cross-recipe validator
+ * (`validateRecipeSet`) catches missing template references before push.
+ *
+ * Field values dispatch on `shape` to one of the encoders below. Most
+ * shapes encode at compile time to a `kind: "string"` value (Sitecore's
+ * stored representation is always a string); `reference` shapes emit
+ * `kind: "ref-recipe-list"` so the executor substitutes captured itemIds
+ * at apply time.
+ *
+ * Phase 4 v1 limitations:
+ *  - `link-internal` is deferred — the wire format is XML wrapping a
+ *    refKey-resolved GUID, which requires a new RefValue kind. Authors
+ *    should use `reference` (with a single-element `refs` array) for
+ *    Droplink/Reference fields, or `link-external` for external URLs.
+ *  - `image.mediaPath` is treated as an opaque path — no media-item
+ *    upload. Sitecore renders the field if a media library item exists
+ *    at that path; otherwise the field is empty until media seeding
+ *    lands in Phase 5+.
+ */
+export declare function compileContentItemRecipe(input: ContentItemRecipe, context: CompileContext): OperationIr;
+//# sourceMappingURL=content-item.d.ts.map

package/dist/recipe/compile/content-item.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-item.d.ts","sourceRoot":"","sources":["../../../src/recipe/compile/content-item.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,WAAW,EAIjB,MAAM,kBAAkB,CAAC;AAQ1B,OAAO,EAEL,KAAK,iBAAiB,EAEvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAiD,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAE9F;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,cAAc,GACtB,WAAW,CAgEb"}

package/dist/recipe/compile/content-item.js

@@ -0,0 +1,189 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileContentItemRecipe = compileContentItemRecipe;
+const errors_1 = require("../../shared/errors");
+const guids_1 = require("../guids");
+const operations_1 = require("../ir/operations");
+const policy_1 = require("../policy");
+const sitecore_templates_1 = require("../ir/sitecore-templates");
+const recipe_1 = require("../schema/recipe");
+const shared_1 = require("./shared");
+/**
+ * Compile a `ContentItemRecipe` to an Operation IR.
+ *
+ * Emits one `CreateItem` for the content item plus one `SetField` per
+ * field value. The item's `templateOf` resolves via `templateId(templateType)`
+ * — the corresponding `ContentTemplateRecipe` (or `ComponentTemplateRecipe`)
+ * must ship in the same set so the executor's captured-itemId map carries
+ * its server-assigned GUID at apply time. The cross-recipe validator
+ * (`validateRecipeSet`) catches missing template references before push.
+ *
+ * Field values dispatch on `shape` to one of the encoders below. Most
+ * shapes encode at compile time to a `kind: "string"` value (Sitecore's
+ * stored representation is always a string); `reference` shapes emit
+ * `kind: "ref-recipe-list"` so the executor substitutes captured itemIds
+ * at apply time.
+ *
+ * Phase 4 v1 limitations:
+ *  - `link-internal` is deferred — the wire format is XML wrapping a
+ *    refKey-resolved GUID, which requires a new RefValue kind. Authors
+ *    should use `reference` (with a single-element `refs` array) for
+ *    Droplink/Reference fields, or `link-external` for external URLs.
+ *  - `image.mediaPath` is treated as an opaque path — no media-item
+ *    upload. Sitecore renders the field if a media library item exists
+ *    at that path; otherwise the field is empty until media seeding
+ *    lands in Phase 5+.
+ */
+function compileContentItemRecipe(input, context) {
+    const recipe = recipe_1.ContentItemRecipeSchema.parse(input);
+    if (!context.contentItemsRoot) {
+        throw (0, errors_1.createCliError)(`compileContentItemRecipe requires context.contentItemsRoot; tenant-side path missing for recipe ${recipe.handle}`, "INPUT_INVALID");
+    }
+    const operations = [];
+    const policy = (0, policy_1.defaultPolicyForRecipe)(recipe.kind);
+    const site = (0, shared_1.siteOf)(context);
+    const itemRefKey = (0, guids_1.contentItemId)(site, recipe.handle);
+    const itemPath = (0, shared_1.joinPath)(context.contentItemsRoot, recipe.name);
+    const templateRefKey = (0, guids_1.templateId)(site, recipe.templateType);
+    operations.push({
+        op: "CreateItem",
+        policy,
+        label: `content-item:${recipe.handle}`,
+        id: itemRefKey,
+        path: itemPath,
+        parent: { kind: "ref-path", value: context.contentItemsRoot },
+        // String GUID — the executor treats this as a refKey when it matches a
+        // captured-itemId entry (the ContentTemplateRecipe / ComponentTemplateRecipe
+        // for `recipe.templateType` registers `templateId(handle)` at apply
+        // time), else as a literal Sitecore template GUID.
+        templateOf: templateRefKey,
+        name: recipe.name,
+        fields: [
+            (0, shared_1.sharedField)(sitecore_templates_1.SYSTEM_FIELDS.ICON, { kind: "string", value: sitecore_templates_1.DEFAULT_ICON }),
+            (0, shared_1.versionedField)(sitecore_templates_1.SYSTEM_FIELDS.DISPLAY_NAME, { kind: "string", value: recipe.displayName }),
+        ],
+    });
+    for (const [fieldName, fieldValue] of Object.entries(recipe.fields)) {
+        const value = encodeContentFieldValue(fieldValue, recipe.handle, site);
+        if (value === null)
+            continue;
+        const fieldGuid = (0, guids_1.fieldId)(site, recipe.templateType, fieldName);
+        operations.push({
+            op: "SetField",
+            policy,
+            label: `content-item-field:${recipe.handle}:${fieldName}`,
+            itemRefKey,
+            fieldId: fieldGuid,
+            // Recipe-created field — Sitecore assigns its own GUID to the
+            // Template Field item, so fieldGuid is only an IR-internal refKey.
+            // The mutation needs the human-readable name; planner uses it for
+            // diff matching against the remote item's field-by-name.
+            fieldName,
+            // Versioned: content-item field values are language/version-scoped.
+            // Default language/version are filled in by versionedField helper —
+            // duplicating its shape here so the SetField op carries them.
+            language: sitecore_templates_1.DEFAULT_LANGUAGE,
+            version: sitecore_templates_1.DEFAULT_VERSION,
+            value,
+        });
+    }
+    return operations_1.OperationIrSchema.parse({
+        schemaVersion: "1",
+        recipeHandle: recipe.handle,
+        operations,
+    });
+}
+/**
+ * Format a recipe `date` (ISO `YYYY-MM-DD`) or `datetime` (ISO 8601 with
+ * timezone) into Sitecore's stored format `yyyyMMddTHHmmssZ`.
+ */
+const toSitecoreDate = (iso, kind) => {
+    const parsed = new Date(iso);
+    if (Number.isNaN(parsed.getTime())) {
+        throw (0, errors_1.createCliError)(`ContentFieldValue ${kind}: '${iso}' is not a valid ISO date`, "INPUT_INVALID");
+    }
+    if (kind === "date") {
+        // Date-only — pin to UTC midnight to keep the output deterministic
+        // regardless of host timezone.
+        const isoDateOnly = iso.includes("T") ? iso.slice(0, 10) : iso;
+        return `${isoDateOnly.replace(/-/g, "")}T000000Z`;
+    }
+    // Datetime: yyyyMMddTHHmmssZ in UTC.
+    const yyyy = parsed.getUTCFullYear().toString().padStart(4, "0");
+    const MM = (parsed.getUTCMonth() + 1).toString().padStart(2, "0");
+    const dd = parsed.getUTCDate().toString().padStart(2, "0");
+    const HH = parsed.getUTCHours().toString().padStart(2, "0");
+    const mm = parsed.getUTCMinutes().toString().padStart(2, "0");
+    const ss = parsed.getUTCSeconds().toString().padStart(2, "0");
+    return `${yyyy}${MM}${dd}T${HH}${mm}${ss}Z`;
+};
+/**
+ * Sitecore image-field XML. Phase 4 v1 emits `mediapath` only — see
+ * `compileContentItemRecipe` JSDoc for the media-item upload caveat.
+ */
+const encodeImageXml = (img) => {
+    const attrs = [`mediapath="${escapeXmlAttr(img.mediaPath)}"`];
+    if (img.alt !== undefined)
+        attrs.push(`alt="${escapeXmlAttr(img.alt)}"`);
+    if (img.width !== undefined)
+        attrs.push(`width="${img.width}"`);
+    if (img.height !== undefined)
+        attrs.push(`height="${img.height}"`);
+    return `<image ${attrs.join(" ")} />`;
+};
+/**
+ * Sitecore General Link XML for an external URL (`linktype="external"`).
+ */
+const encodeExternalLinkXml = (link) => {
+    const attrs = [`linktype="external"`, `url="${escapeXmlAttr(link.href)}"`];
+    if (link.text !== undefined)
+        attrs.push(`text="${escapeXmlAttr(link.text)}"`);
+    if (link.target !== undefined)
+        attrs.push(`target="${escapeXmlAttr(link.target)}"`);
+    if (link.title !== undefined)
+        attrs.push(`title="${escapeXmlAttr(link.title)}"`);
+    return `<link ${attrs.join(" ")} />`;
+};
+const escapeXmlAttr = (s) => s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+/**
+ * Encode one ContentFieldValue to a RefValue. Returns null when the
+ * shape is deferred (e.g. `link-internal` in Phase 4 v1) — the caller
+ * skips emitting a SetField op for it. Throws on truly invalid input.
+ */
+const encodeContentFieldValue = (value, recipeHandle, site) => {
+    switch (value.shape) {
+        case "text":
+        case "richText":
+        case "enum":
+            return { kind: "string", value: value.value };
+        case "boolean":
+            return { kind: "bool", value: value.value };
+        case "number":
+        case "integer":
+            return { kind: "number", value: value.value };
+        case "date":
+        case "datetime":
+            return { kind: "string", value: toSitecoreDate(value.value, value.shape) };
+        case "image":
+            return { kind: "string", value: encodeImageXml(value) };
+        case "link-external":
+            return { kind: "string", value: encodeExternalLinkXml(value) };
+        case "link-internal":
+            // Deferred: General Link XML wrapping a refKey-resolved GUID needs
+            // a new RefValue kind. Recipe authors targeting Phase 4 should use
+            // `reference` (single-element refs[]) for Droplink-shaped fields.
+            throw (0, errors_1.createCliError)(`ContentItemRecipe '${recipeHandle}': link-internal is deferred to Phase 5. ` +
+                `Use 'reference' shape with a single-element refs[] for Droplink/Reference fields, ` +
+                `or 'link-external' with an absolute URL for now.`, "INPUT_INVALID");
+        case "reference":
+            return {
+                kind: "ref-recipe-list",
+                refKeys: value.refs.map((handle) => (0, guids_1.contentItemId)(site, handle)),
+            };
+    }
+};

package/dist/recipe/compile/content-template.d.ts

@@ -0,0 +1,18 @@
+import { type OperationIr } from "../ir/operations";
+import { type ContentTemplateRecipe } from "../schema/recipe";
+import { type CompileContext } from "./shared";
+/**
+ * Compile a `ContentTemplateRecipe` to an Operation IR.
+ *
+ * Content templates are data-only: a Sitecore template + sections + fields
+ * + standard values + back-fill. No rendering, no params, no variants.
+ *
+ * Path resolution:
+ *   - With `contentModelsRoot` and `meta.tax.group` set →
+ *     `<contentModelsRoot>/<group>/<name>` (group folder created
+ *     idempotently as a CreateOnly op).
+ *   - With `contentModelsRoot` and no group → `<contentModelsRoot>/<name>`.
+ *   - Without `contentModelsRoot` → legacy `<templatesRoot>/<name>`.
+ */
+export declare function compileContentTemplateRecipe(input: ContentTemplateRecipe, context: CompileContext, emittedFolders?: Set<string>): OperationIr;
+//# sourceMappingURL=content-template.d.ts.map

package/dist/recipe/compile/content-template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-template.d.ts","sourceRoot":"","sources":["../../../src/recipe/compile/content-template.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,WAAW,EAAqB,MAAM,kBAAkB,CAAC;AAGvF,OAAO,EAAE,KAAK,qBAAqB,EAA+B,MAAM,kBAAkB,CAAC;AAC3F,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,UAAU,CAAC;AAElB;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,qBAAqB,EAC5B,OAAO,EAAE,cAAc,EACvB,cAAc,GAAE,GAAG,CAAC,MAAM,CAAa,GACtC,WAAW,CA2Cb"}

package/dist/recipe/compile/content-template.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileContentTemplateRecipe = compileContentTemplateRecipe;
+const operations_1 = require("../ir/operations");
+const policy_1 = require("../policy");
+const sitecore_templates_1 = require("../ir/sitecore-templates");
+const recipe_1 = require("../schema/recipe");
+const shared_1 = require("./shared");
+/**
+ * Compile a `ContentTemplateRecipe` to an Operation IR.
+ *
+ * Content templates are data-only: a Sitecore template + sections + fields
+ * + standard values + back-fill. No rendering, no params, no variants.
+ *
+ * Path resolution:
+ *   - With `contentModelsRoot` and `meta.tax.group` set →
+ *     `<contentModelsRoot>/<group>/<name>` (group folder created
+ *     idempotently as a CreateOnly op).
+ *   - With `contentModelsRoot` and no group → `<contentModelsRoot>/<name>`.
+ *   - Without `contentModelsRoot` → legacy `<templatesRoot>/<name>`.
+ */
+function compileContentTemplateRecipe(input, context, emittedFolders = new Set()) {
+    const recipe = recipe_1.ContentTemplateRecipeSchema.parse(input);
+    const operations = [];
+    const group = recipe.meta?.tax?.group;
+    let parentPath;
+    let parentRefKey;
+    if (context.contentModelsRoot) {
+        if (group) {
+            const groupRefKey = (0, shared_1.ensureContentModelsGroupFolder)(operations, context, group, emittedFolders);
+            parentPath = (0, shared_1.joinPath)(context.contentModelsRoot, group);
+            parentRefKey = groupRefKey;
+        }
+        else {
+            parentPath = context.contentModelsRoot;
+        }
+    }
+    (0, shared_1.emitDatasourceTemplate)(operations, {
+        handle: recipe.handle,
+        name: recipe.name,
+        displayName: recipe.displayName,
+        fields: recipe.fields,
+        insertOptions: recipe.insertOptions,
+        ...(parentPath !== undefined && { parentPath }),
+        ...(parentRefKey !== undefined && { parentRefKey }),
+    }, context, sitecore_templates_1.DEFAULT_ICON, (0, policy_1.defaultPolicyForRecipe)(recipe.kind));
+    return operations_1.OperationIrSchema.parse({
+        schemaVersion: "1",
+        recipeHandle: recipe.handle,
+        operations,
+    });
+}

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

@@ -0,0 +1,59 @@
+import { type OperationIr } from "../ir/operations";
+import { type EnumerationRecipe } from "../schema/recipe";
+import { type CompileContext } from "./shared";
+/**
+ * Compile an `EnumerationRecipe` to an Operation IR.
+ *
+ * Emits the per-site `Enumerations Folder` + `Enumeration` +
+ * `Enumeration Value` template trio (idempotent across the recipe set
+ * via the shared `emittedFolders` sentinel), an optional grouping
+ * folder under `<enumerationsRoot>` driven by `recipe.location.folder`
+ * (also idempotent), one CreateItem op for the per-enum container item,
+ * and one CreateItem op per declared value parented under that
+ * container.
+ *
+ * Path resolution:
+ *   - With `recipe.location.folder` set →
+ *     `<enumerationsRoot>/<folder>/<EnumName>/<ValueName>`. The leaf
+ *     folder lands as a `CreateOnly` item conforming to the per-site
+ *     `Enumerations Folder` template; multiple recipes naming the same
+ *     folder path share it via the `emittedFolders` sentinel.
+ *   - Without `recipe.location` (or `recipe.location.folder`) →
+ *     `<enumerationsRoot>/<EnumName>/<ValueName>` (flat layout).
+ *
+ * Template assignment (each item conforms to a different template —
+ * roles are NOT collapsed):
+ *   - Grouping folders         → `Enumerations Folder` template
+ *   - Per-enum container       → `Enumeration` template
+ *   - Leaf value items         → `Enumeration Value` template
+ *
+ * All three templates inherit Standard Template and stamp the
+ * `keyboard_key_e.png` icon via template-level inheritance, so the SXA
+ * editor shows enum items with the enum icon without per-item overrides.
+ *
+ * Each value item also writes its `value.name` to the `Value` shared
+ * field defined on the `Enumeration Value` template's inner
+ * `Enumeration` section. Without this the value items would have no
+ * payload — the Droplink picker would still enumerate them, but
+ * consumers reading the picked item's `Value` field (the canonical SXA
+ * pattern) would find it empty.
+ *
+ * Refkeys:
+ *   - Grouping folder: `enumerationsGroupingFolderId(site, folder)` —
+ *     site + cumulative path keyed so two recipes naming the same
+ *     folder reuse one item rather than colliding.
+ *   - Per-enum container:  `enumerationFolderId(site, recipe.handle)` —
+ *     site-scoped so cross-site pushes don't collide. (Function name is
+ *     legacy; the item it identifies is the per-enum container, not a
+ *     folder.)
+ *   - Values:  `enumValueId(folderRefKey, value.name)` — value-name keyed
+ *     under the container. Renaming a value (`primary` → `accent`) emits
+ *     a different GUID; consuming fields whose default referenced the
+ *     old name end up orphaned. Author error.
+ *
+ * Throws `INPUT_INVALID` when `context.enumerationsRoot` is unset, or
+ * when `recipe.location.scope` is `"siteCollection"` (reserved for
+ * shared-vocabulary use; not yet implemented).
+ */
+export declare function compileEnumerationRecipe(input: EnumerationRecipe, context: CompileContext, emittedFolders?: Set<string>): OperationIr;
+//# sourceMappingURL=enumeration.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"enumeration.d.ts","sourceRoot":"","sources":["../../../src/recipe/compile/enumeration.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,WAAW,EAEjB,MAAM,kBAAkB,CAAC;AAI1B,OAAO,EAAE,KAAK,iBAAiB,EAA2B,MAAM,kBAAkB,CAAC;AACnF,OAAO,EAML,KAAK,cAAc,EACpB,MAAM,UAAU,CAAC;AAElB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,cAAc,EACvB,cAAc,GAAE,GAAG,CAAC,MAAM,CAAa,GACtC,WAAW,CA0Mb"}

package/dist/recipe/compile/enumeration.js

@@ -0,0 +1,236 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileEnumerationRecipe = compileEnumerationRecipe;
+const guids_1 = require("../guids");
+const operations_1 = require("../ir/operations");
+const policy_1 = require("../policy");
+const errors_1 = require("../../shared/errors");
+const sitecore_templates_1 = require("../ir/sitecore-templates");
+const recipe_1 = require("../schema/recipe");
+const shared_1 = require("./shared");
+/**
+ * Compile an `EnumerationRecipe` to an Operation IR.
+ *
+ * Emits the per-site `Enumerations Folder` + `Enumeration` +
+ * `Enumeration Value` template trio (idempotent across the recipe set
+ * via the shared `emittedFolders` sentinel), an optional grouping
+ * folder under `<enumerationsRoot>` driven by `recipe.location.folder`
+ * (also idempotent), one CreateItem op for the per-enum container item,
+ * and one CreateItem op per declared value parented under that
+ * container.
+ *
+ * Path resolution:
+ *   - With `recipe.location.folder` set →
+ *     `<enumerationsRoot>/<folder>/<EnumName>/<ValueName>`. The leaf
+ *     folder lands as a `CreateOnly` item conforming to the per-site
+ *     `Enumerations Folder` template; multiple recipes naming the same
+ *     folder path share it via the `emittedFolders` sentinel.
+ *   - Without `recipe.location` (or `recipe.location.folder`) →
+ *     `<enumerationsRoot>/<EnumName>/<ValueName>` (flat layout).
+ *
+ * Template assignment (each item conforms to a different template —
+ * roles are NOT collapsed):
+ *   - Grouping folders         → `Enumerations Folder` template
+ *   - Per-enum container       → `Enumeration` template
+ *   - Leaf value items         → `Enumeration Value` template
+ *
+ * All three templates inherit Standard Template and stamp the
+ * `keyboard_key_e.png` icon via template-level inheritance, so the SXA
+ * editor shows enum items with the enum icon without per-item overrides.
+ *
+ * Each value item also writes its `value.name` to the `Value` shared
+ * field defined on the `Enumeration Value` template's inner
+ * `Enumeration` section. Without this the value items would have no
+ * payload — the Droplink picker would still enumerate them, but
+ * consumers reading the picked item's `Value` field (the canonical SXA
+ * pattern) would find it empty.
+ *
+ * Refkeys:
+ *   - Grouping folder: `enumerationsGroupingFolderId(site, folder)` —
+ *     site + cumulative path keyed so two recipes naming the same
+ *     folder reuse one item rather than colliding.
+ *   - Per-enum container:  `enumerationFolderId(site, recipe.handle)` —
+ *     site-scoped so cross-site pushes don't collide. (Function name is
+ *     legacy; the item it identifies is the per-enum container, not a
+ *     folder.)
+ *   - Values:  `enumValueId(folderRefKey, value.name)` — value-name keyed
+ *     under the container. Renaming a value (`primary` → `accent`) emits
+ *     a different GUID; consuming fields whose default referenced the
+ *     old name end up orphaned. Author error.
+ *
+ * Throws `INPUT_INVALID` when `context.enumerationsRoot` is unset, or
+ * when `recipe.location.scope` is `"siteCollection"` (reserved for
+ * shared-vocabulary use; not yet implemented).
+ */
+function compileEnumerationRecipe(input, context, emittedFolders = new Set()) {
+    const recipe = recipe_1.EnumerationRecipeSchema.parse(input);
+    if (!context.enumerationsRoot) {
+        throw (0, errors_1.createCliError)(`Recipe '${recipe.handle}' is an enumeration but no enumerationsRoot is configured.`, "INPUT_INVALID", {
+            hint: "Set `enumerationsRoot` on the active envProfile in sitecoreai.cli.json (e.g. `/sitecore/content/<siteCollection>/<site>/Settings/Enumerations`).",
+        });
+    }
+    const operations = [];
+    const policy = (0, policy_1.defaultPolicyForRecipe)(recipe.kind);
+    const site = (0, shared_1.siteOf)(context);
+    const { folderTemplateRefKey, enumerationTemplateRefKey, containerValueFieldRefKey, valueTemplateRefKey, valueFieldRefKey, } = (0, shared_1.ensureEnumerationTemplates)(operations, context, site, emittedFolders);
+    // Validate `default` matches one of the declared value names. Lives
+    // here (not on the schema) because `discriminatedUnion` rejects
+    // `ZodEffects` members, so cross-field validation can't be expressed
+    // on `EnumerationRecipeSchema` directly.
+    if (recipe.default !== undefined) {
+        const valueNames = new Set(recipe.values.map((v) => v.name));
+        if (!valueNames.has(recipe.default)) {
+            throw (0, errors_1.createCliError)(`Recipe '${recipe.handle}' declares default='${recipe.default}' but no matching value.name.`, "INPUT_INVALID", {
+                hint: `default must match one of values[].name (got: ${[...valueNames].join(", ") || "<none>"}).`,
+            });
+        }
+    }
+    // siteCollection scope is reserved for shared-vocabulary use
+    // (multiple sites in a collection sourcing one canonical enum) but
+    // requires a `siteCollectionEnumerationsRoot` on `CompileContext`
+    // that doesn't exist yet. Reject explicitly so authors don't get a
+    // surprise misplacement.
+    if (recipe.location?.scope === "siteCollection") {
+        throw (0, errors_1.createCliError)(`Recipe '${recipe.handle}' declares location.scope='siteCollection' but the siteCollection enumerations root isn't wired up yet.`, "INPUT_INVALID", {
+            hint: 'Use `location.scope: "site"` for now (or omit `location`). Site-collection scope will land when the orchestrator threads a siteCollectionEnumerationsRoot through CompileContext.',
+        });
+    }
+    // Optional grouping folder(s) driven by `location.folder`. CreateOnly +
+    // dedup via emittedFolders so multiple recipes naming the same folder
+    // share one item. Multi-segment paths (e.g. "Components/Card") split
+    // on `/` — EVERY segment gets an explicit CreateItem conforming to
+    // the per-site Enumerations Folder template (intermediates included).
+    // Without an explicit emit per segment, Sitecore's executor path-walker
+    // auto-creates intermediates as the generic `Folder` template, which
+    // breaks the Insert Options chain (a generic Folder doesn't carry
+    // the Enumerations Folder Standard Values, so authors right-clicking
+    // `Components/` see no Insert Options for `Enumeration` /
+    // `Enumerations Folder`).
+    //
+    // Each segment is keyed on its CUMULATIVE path (`enumerationsGroupingFolderId(site,
+    // cumulativePath)`) so two recipes sharing a prefix (`Components/Card`
+    // + `Components/Tabs`) reuse the same `Components` item rather than
+    // colliding. Parent chain: first segment ref-paths the enumerations
+    // root; subsequent segments ref-recipe the prior segment so the
+    // executor resolves the captured itemId.
+    let parentPath = context.enumerationsRoot;
+    let parentRef = {
+        kind: "ref-path",
+        value: context.enumerationsRoot,
+    };
+    const folder = recipe.location?.folder;
+    if (folder) {
+        const folderSegments = folder
+            .split("/")
+            .map((s) => s.trim())
+            .filter(Boolean);
+        if (folderSegments.length === 0) {
+            throw (0, errors_1.createCliError)(`Recipe '${recipe.handle}' declares location.folder that is empty after trimming.`, "INPUT_INVALID", {
+                hint: "Use a non-empty folder string like 'Theme' or 'Components/Card'.",
+            });
+        }
+        const cumulativeSegments = [];
+        for (const segment of folderSegments) {
+            cumulativeSegments.push(segment);
+            const cumulativePath = cumulativeSegments.join("/");
+            const segmentRefKey = (0, guids_1.enumerationsGroupingFolderId)(site, cumulativePath);
+            const segmentPath = (0, shared_1.joinPath)(context.enumerationsRoot, cumulativePath);
+            if (!emittedFolders.has(segmentRefKey)) {
+                emittedFolders.add(segmentRefKey);
+                operations.push({
+                    op: "CreateItem",
+                    policy: "CreateOnly",
+                    label: `enumerations-grouping-folder:${site}:${cumulativePath}`,
+                    id: segmentRefKey,
+                    path: segmentPath,
+                    parent: parentRef,
+                    templateOf: folderTemplateRefKey,
+                    name: segment,
+                    fields: [],
+                });
+            }
+            parentPath = segmentPath;
+            parentRef = { kind: "ref-recipe", refKey: segmentRefKey };
+        }
+    }
+    // Per-enum container item (e.g. `Color Scheme`, `Heading Size`).
+    // Conforms to the `Enumeration` template — NOT `Enumerations Folder`,
+    // which is reserved for grouping folders. The container's own
+    // `__Standard Values` (set on the Enumeration template) advertises
+    // `Enumeration Value` as the only Insert Option, so authors can
+    // right-click → Insert → Enumeration Value to add a value.
+    //
+    // RefKey name `folderRefKey` is legacy from before the template
+    // separation — the item it identifies is the per-enum container, not
+    // a folder.
+    const folderRefKey = (0, guids_1.enumerationFolderId)(site, recipe.handle);
+    const folderPath = (0, shared_1.joinPath)(parentPath, recipe.name);
+    const folderDisplayName = recipe.displayName ?? recipe.name;
+    // When `recipe.default` is set, write it to the container's `Value`
+    // shared field. The field write carries `fieldName: "Value"` so the
+    // executor's tenant-side resolver matches by name (recipe-derived
+    // field GUIDs don't line up with server-assigned ones once the
+    // template is materialised) — same pattern as the leaf value items.
+    const containerFields = [
+        (0, shared_1.versionedField)(sitecore_templates_1.SYSTEM_FIELDS.DISPLAY_NAME, { kind: "string", value: folderDisplayName }),
+    ];
+    if (recipe.default !== undefined) {
+        containerFields.push({
+            ...(0, shared_1.sharedField)(containerValueFieldRefKey, { kind: "string", value: recipe.default }),
+            fieldName: "Value",
+        });
+    }
+    operations.push({
+        op: "CreateItem",
+        policy,
+        label: `enumeration:${recipe.handle}`,
+        id: folderRefKey,
+        path: folderPath,
+        parent: parentRef,
+        templateOf: enumerationTemplateRefKey,
+        name: recipe.name,
+        fields: containerFields,
+    });
+    for (const value of recipe.values) {
+        const valueDisplayName = value.displayName ?? value.name;
+        operations.push({
+            op: "CreateItem",
+            policy,
+            label: `enumeration-value:${recipe.handle}/${value.name}`,
+            id: (0, guids_1.enumValueId)(folderRefKey, value.name),
+            path: (0, shared_1.joinPath)(folderPath, value.name),
+            parent: { kind: "ref-recipe", refKey: folderRefKey },
+            templateOf: valueTemplateRefKey,
+            name: value.name,
+            // The `Value` shared field carries the actual enumeration string
+            // (matches canonical pattern: each value item under
+            // `Background Themes/shooting-star` stores `Value: "shooting-star"`).
+            // `fieldName` is required so the executor's tenant-side resolver
+            // can locate the field by name — the recipe-derived `valueFieldRefKey`
+            // doesn't match the Sitecore-assigned field GUID after the template
+            // is materialised.
+            fields: [
+                {
+                    ...(0, shared_1.sharedField)(valueFieldRefKey, { kind: "string", value: value.name }),
+                    fieldName: "Value",
+                },
+                (0, shared_1.versionedField)(sitecore_templates_1.SYSTEM_FIELDS.DISPLAY_NAME, {
+                    kind: "string",
+                    value: valueDisplayName,
+                }),
+            ],
+        });
+    }
+    // Per-data-folder __Standard Values is intentionally NOT emitted —
+    // Insert Options now live on the Enumerations Folder template's own
+    // Standard Values (set up in `ensureEnumerationTemplates`) and
+    // propagate to every item conforming to the template. Emitting an SV
+    // ITEM under each data folder would re-introduce the old bug where
+    // the Droplink picker enumerates the SV as a sibling of the enum
+    // value items (the Source path's children include any direct child).
+    return operations_1.OperationIrSchema.parse({
+        schemaVersion: "1",
+        recipeHandle: recipe.handle,
+        operations,
+    });
+}

package/dist/recipe/compile/page-design.d.ts

@@ -0,0 +1,22 @@
+import { type OperationIr } from "../ir/operations";
+import { type PageDesignRecipe } from "../schema/recipe";
+import { type CompileContext } from "./shared";
+/**
+ * Compile a `PageDesignRecipe` to an Operation IR.
+ *
+ * Emits up to three ops:
+ *   1. `CreateItem` for the page-design item (SXA Page Design template)
+ *   2. `SetField(PartialDesigns)` — pipe-separated GUID list of partials
+ *   3. `SetField(__Renderings)` — only when recipe.layout is non-empty
+ *
+ * The recipe's `appliesTo` contributions to the Page Designs root's
+ * `TemplatesMapping` field are NOT emitted here — that field is
+ * cross-recipe (every page design contributes a slice) and a per-recipe
+ * `kind: "string"` write would full-replace under the executor's write
+ * semantics, with each page design overwriting its siblings. Use
+ * `compileRecipeSet` (below) to compile a coherent set of recipes —
+ * it aggregates `appliesTo` contributions across every page-design
+ * recipe in the set into one combined IR.
+ */
+export declare function compilePageDesignRecipe(input: PageDesignRecipe, context: CompileContext): OperationIr;
+//# sourceMappingURL=page-design.d.ts.map

package/dist/recipe/compile/page-design.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-design.d.ts","sourceRoot":"","sources":["../../../src/recipe/compile/page-design.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,WAAW,EAGjB,MAAM,kBAAkB,CAAC;AAU1B,OAAO,EAAE,KAAK,gBAAgB,EAA0B,MAAM,kBAAkB,CAAC;AAEjF,OAAO,EAAiD,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAE9F;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,cAAc,GACtB,WAAW,CAwEb"}