@sitecoreai-labs/sitecoreai-cli 0.0.4

package/dist/recipe/ir/operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../../src/recipe/ir/operations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAkBxB,eAAO,MAAM,gBAAgB;;;;EAAqE,CAAC;AAEnG,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BA8CzB,CAAC;AAEH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwB3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAQ1D,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6B7B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6B3B,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;;;;;;;;iBAMnC,CAAC;AAEH,eAAO,MAAM,yBAAyB;;;;;;;;;;iBAOpC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;iBA8CzC,CAAC;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;iBA6DpC,CAAC;AAEH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;yBAO1B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC1D,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC1E,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAC5E,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AACtF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAC5E,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAK5B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/recipe/ir/operations.js

@@ -0,0 +1,347 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OperationIrSchema = exports.OperationSchema = exports.AppendToMultiListOpSchema = exports.CreateSiteFromTemplateOpSchema = exports.SetStandardValuesOpSchema = exports.SetBaseTemplatesOpSchema = exports.SetFieldOpSchema = exports.CreateItemOpSchema = exports.FieldValueSchema = exports.RefValueSchema = exports.PushPolicySchema = void 0;
+const zod_1 = require("zod");
+/**
+ * Operation IR — the only artifact the recipe compiler emits.
+ *
+ * Each operation carries a deterministic GUID (resolved via uuidv5 from the
+ * recipe handle) so re-running the compiler against the same inputs yields
+ * the same IR, and re-applying it against a tenant is a no-op once the
+ * items exist (the executor reads remote state by GUID, diffs, then mutates).
+ *
+ * `policy` is the per-operation push policy: `CreateOnly` is how author
+ * edits in the CMS are protected; `CreateAndUpdate` is the default for
+ * registry-owned templates and renderings.
+ */
+const GUID = zod_1.z.string().uuid();
+const NON_EMPTY = zod_1.z.string().min(1);
+exports.PushPolicySchema = zod_1.z.enum(["CreateAndUpdate", "CreateOnly", "CreateUpdateAndDelete"]);
+/**
+ * Reference encodings the IR must distinguish — Sitecore stores cross-item
+ * references in many shapes (see `plans/sitecore-relationships.md`,
+ * "Reference encoding patterns"). The executor decides per-field which form
+ * to serialize.
+ *
+ * Two flavors of GUID reference:
+ *
+ *   - `ref-guid` / `ref-guid-list` — known-at-compile-time GUIDs (Sitecore
+ *     built-ins like the Standard Template, Folder, View Rendering). Inline
+ *     constants; no runtime resolution needed.
+ *   - `ref-recipe` / `ref-recipe-list` — references to items the executor
+ *     creates during this push. The Authoring API server-assigns itemIds
+ *     on create, so the IR carries a recipe-internal `refKey` (uuidv5
+ *     derived from the recipe handle) and the executor substitutes the
+ *     captured Sitecore itemId before dispatching the field write.
+ */
+exports.RefValueSchema = zod_1.z.discriminatedUnion("kind", [
+    zod_1.z.object({ kind: zod_1.z.literal("string"), value: zod_1.z.string() }),
+    zod_1.z.object({ kind: zod_1.z.literal("bool"), value: zod_1.z.boolean() }),
+    zod_1.z.object({ kind: zod_1.z.literal("number"), value: zod_1.z.number() }),
+    zod_1.z.object({ kind: zod_1.z.literal("ref-guid"), value: GUID }),
+    zod_1.z.object({ kind: zod_1.z.literal("ref-guid-list"), values: zod_1.z.array(GUID) }),
+    zod_1.z.object({ kind: zod_1.z.literal("ref-recipe"), refKey: GUID }),
+    zod_1.z.object({
+        kind: zod_1.z.literal("ref-recipe-list"),
+        refKeys: zod_1.z.array(GUID),
+        /**
+         * When `true`, the resolver silently drops refKeys it can't find
+         * in the captured-itemId map instead of throwing. Default false
+         * (existing strict behavior — used by per-recipe SetField ops
+         * where a missing ref means a real bug). Set true on cross-recipe
+         * aggregate ops (e.g. `__available-renderings__`) where some
+         * sibling recipe IRs may have aborted and the aggregate should
+         * still write whichever items DID get created.
+         */
+        tolerateMissing: zod_1.z.boolean().optional(),
+    }),
+    zod_1.z.object({ kind: zod_1.z.literal("ref-path"), value: NON_EMPTY }),
+    zod_1.z.object({ kind: zod_1.z.literal("query"), value: NON_EMPTY }),
+    /**
+     * Structured source fields whose `sourceTypes` reference one or more
+     * recipe handles. Resolution requires the captured-itemId map; rendered
+     * by the executor (via `renderSourceFields`) just before dispatching
+     * the field write. Mirrors the `SitecoreFieldAugment` source surface
+     * minus `sourceRaw` (raw is always rendered at compile time).
+     *
+     * `site` is the site name the compiler emitted under — required so the
+     * executor can resolve handle refKeys via the (site, handle)-scoped
+     * `templateId(site, handle)` derivation. Defaults to `default` when the
+     * compiler ran without `context.site`.
+     */
+    zod_1.z.object({
+        kind: zod_1.z.literal("ref-source-fields"),
+        site: NON_EMPTY,
+        sourceTypes: zod_1.z.array(NON_EMPTY).min(1),
+        sourceQuery: zod_1.z.string().optional(),
+        sourceScope: zod_1.z.string().optional(),
+    }),
+    zod_1.z.object({
+        kind: zod_1.z.literal("url-string-map"),
+        entries: zod_1.z.record(zod_1.z.string(), zod_1.z.string()),
+    }),
+]);
+exports.FieldValueSchema = zod_1.z.object({
+    fieldId: GUID,
+    /**
+     * Optional human-readable field name (e.g. "Body"). When present, the
+     * authoring client uses this as the mutation's field selector and the
+     * planner uses it for diff matching against `RemoteFieldValue.name`.
+     *
+     * Required for fields on RECIPE-CREATED templates: Sitecore assigns
+     * server-side itemIds to Template Field items, so the recipe-derived
+     * `fieldId(handle, name)` is just an internal refKey — the tenant has
+     * a different GUID for the same field. Sitecore's `FieldValueInput.name`
+     * accepts either a name or an ID, but only IDs that exist on the tenant
+     * resolve. Field names always resolve against the item's template.
+     *
+     * Omit for SYSTEM fields (e.g. `__Display Name`, `__Renderings`,
+     * `TemplatesMapping`) — those GUIDs are real Sitecore built-ins and
+     * resolve directly.
+     */
+    fieldName: zod_1.z.string().min(1).optional(),
+    /** Omit for shared fields; default `en` for versioned fields. */
+    language: zod_1.z.string().optional(),
+    /** Omit for shared fields; default `1` for versioned fields. */
+    version: zod_1.z.number().int().positive().optional(),
+    value: exports.RefValueSchema,
+});
+const BaseOpFields = {
+    policy: exports.PushPolicySchema,
+    /** Stable, recipe-derived label used in plan/push progress events. */
+    label: NON_EMPTY,
+};
+exports.CreateItemOpSchema = zod_1.z.object({
+    op: zod_1.z.literal("CreateItem"),
+    ...BaseOpFields,
+    /**
+     * Recipe-internal uuidv5. Stable across compiles. Used as the refKey for
+     * `ref-recipe` substitutions in subsequent ops. NOT a Sitecore item ID —
+     * Sitecore assigns those server-side on `createItem`.
+     */
+    id: GUID,
+    /**
+     * Sitecore content-tree path where the item lives (parent + name). The
+     * runtime authority for "does this item exist?" — the planner reads
+     * by path, the executor creates at this path. Examples:
+     *   /sitecore/templates/Project/CtaButton
+     *   /sitecore/templates/Project/CtaButton/Content/Link
+     */
+    path: NON_EMPTY,
+    /**
+     * Parent ref. `ref-recipe` resolves to the captured Sitecore itemId for
+     * a previously-created item in this push; `ref-path` is a Sitecore path
+     * (typically the configured templatesRoot for top-level items).
+     */
+    parent: zod_1.z.discriminatedUnion("kind", [
+        zod_1.z.object({ kind: zod_1.z.literal("ref-recipe"), refKey: GUID }),
+        zod_1.z.object({ kind: zod_1.z.literal("ref-path"), value: NON_EMPTY }),
+    ]),
+    templateOf: GUID,
+    name: NON_EMPTY,
+    fields: zod_1.z.array(exports.FieldValueSchema),
+});
+exports.SetFieldOpSchema = zod_1.z.object({
+    op: zod_1.z.literal("SetField"),
+    ...BaseOpFields,
+    /** RefKey of the target item — resolves to Sitecore itemId at execute time. */
+    itemRefKey: GUID,
+    fieldId: GUID,
+    /**
+     * Optional human-readable field name. See `FieldValueSchema.fieldName`
+     * — required for fields on recipe-created templates, omit for system
+     * fields whose GUIDs are Sitecore built-ins.
+     */
+    fieldName: zod_1.z.string().min(1).optional(),
+    language: zod_1.z.string().optional(),
+    version: zod_1.z.number().int().positive().optional(),
+    value: exports.RefValueSchema,
+    /**
+     * Optional content-tree path for late ref seeding. Used by SiteRecipe
+     * dictionary overrides where the target item (`<site>/Dictionary/<phrase>`)
+     * is materialised by SXA's Site Wizard during a `CreateSiteFromTemplate`
+     * apply, AFTER initial `crossRecipeRefs` seeding. The executor checks
+     * if `itemRefKey` is in the captured map; if not AND `latePath` is
+     * present, it runs `getItem({ path: latePath })` on demand to seed
+     * before planning the SetField.
+     *
+     * Compiler emits this only when the target item is created indirectly
+     * (Sites API / SXA scaffolding); regular SetField ops on items the
+     * recipe itself creates leave this undefined.
+     */
+    latePath: zod_1.z.string().min(1).optional(),
+});
+exports.SetBaseTemplatesOpSchema = zod_1.z.object({
+    op: zod_1.z.literal("SetBaseTemplates"),
+    ...BaseOpFields,
+    /** RefKey of the target item. */
+    itemRefKey: GUID,
+    baseTemplates: zod_1.z.array(GUID).min(1),
+});
+exports.SetStandardValuesOpSchema = zod_1.z.object({
+    op: zod_1.z.literal("SetStandardValues"),
+    ...BaseOpFields,
+    /** RefKey of the template item. */
+    templateRefKey: GUID,
+    /** RefKey of the standard-values item. */
+    standardValuesRefKey: GUID,
+});
+/**
+ * Site instantiation via Sitecore's Sites API. Unlike CreateItem (which
+ * dispatches to Authoring GraphQL), CreateSiteFromTemplate dispatches
+ * to the Sites API's `createSite` operation — the only way to spin up
+ * a site instance with all the SXA initialization (content tree
+ * skeleton, settings, dictionary structure, etc.) that Authoring API
+ * `createItem` can't reproduce.
+ *
+ * Async semantics: the Sites API's `createSite` returns a JobResponse
+ * (a job handle); the executor polls until completion, then looks up
+ * the created site by name to capture its assigned itemId. The
+ * captured itemId becomes the resolution target for subsequent ops
+ * keyed on `siteRefKey`.
+ *
+ * Idempotency: planner checks if a site with this `siteName` already
+ * exists in the environment via Sites API `listSites`. If yes →
+ * status: skip (mutation: undefined). If no → status: create, mutation
+ * dispatches `createSite`. There is no "update site template"
+ * operation on the Sites API; mismatched-template sites are reported
+ * as planning errors rather than silently re-instantiated.
+ */
+exports.CreateSiteFromTemplateOpSchema = zod_1.z.object({
+    op: zod_1.z.literal("CreateSiteFromTemplate"),
+    ...BaseOpFields,
+    /**
+     * Recipe-internal uuidv5 for this site (`siteId(handle)`). Subsequent
+     * SetField ops on the site's content tree (dictionary overrides,
+     * taxonomy overrides) reference items the Sites API materialises
+     * under this site; the executor seeds those itemIds via a post-apply
+     * re-walk of the cross-recipe ref map.
+     */
+    siteRefKey: GUID,
+    /**
+     * The Sitecore site Name (becomes Sites API `NewSiteInput.siteName`).
+     * Distinct from the recipe handle.
+     */
+    siteName: NON_EMPTY,
+    displayName: zod_1.z.string().optional(),
+    description: zod_1.z.string().optional(),
+    /** Primary site language ISO code (Sites API `NewSiteInput.language`). */
+    language: NON_EMPTY,
+    /** Additional supported languages on this site (added via `addLanguage`). */
+    additionalLanguages: zod_1.z.array(zod_1.z.string().min(2)).optional(),
+    /**
+     * Optional primary hostname (Sites API `NewSiteInput.hostName`). When
+     * unset, the site is created without an explicit primary host (the
+     * customer can configure hosts via the Site Hosts surface).
+     */
+    hostName: zod_1.z.string().optional(),
+    /**
+     * RefKey of the `SiteTemplateRecipe` this site instances. Resolves at
+     * execute time to the template's Sitecore itemId via the captured
+     * map; that itemId becomes Sites API `NewSiteInput.templateId`.
+     */
+    templateRefKey: GUID,
+    /**
+     * Existing collection ID. Mutually exclusive with `collectionName` —
+     * compiler validates that exactly one is present.
+     */
+    collectionId: zod_1.z.string().optional(),
+    /**
+     * Name of a NEW collection to create alongside the site. Mutually
+     * exclusive with `collectionId`.
+     */
+    collectionName: zod_1.z.string().optional(),
+    collectionDisplayName: zod_1.z.string().optional(),
+    collectionDescription: zod_1.z.string().optional(),
+});
+/**
+ * Append GUIDs to an existing item's multi-list field without disturbing
+ * existing values. Used by registry-driven recipes to register their
+ * renderings against pre-existing SXA Available Rendering Section
+ * Definition items (`availableIn` on `ComponentTemplateRecipe`).
+ *
+ * Idempotent under `policy: "merge-unique"` — the executor reads the
+ * current field value, parses it as a pipe-separated GUID list,
+ * unions the desired values into the existing set, and writes back
+ * only if the set changed. Re-pushing a recipe with the same
+ * `values` is a no-op once the values are present.
+ *
+ * Removal is intentionally NOT modelled here — uninstalling a
+ * component does not auto-remove it from a section's Available
+ * Renderings; that's an explicit operator action with a different
+ * policy.
+ */
+exports.AppendToMultiListOpSchema = zod_1.z.object({
+    op: zod_1.z.literal("AppendToMultiList"),
+    ...BaseOpFields,
+    /**
+     * RefKey of the target item — typically a SectionDefinitionRecipe's
+     * `sectionDefinitionId(handle)`. The executor resolves it to a
+     * Sitecore itemId via the captured map; cross-recipe pre-seeding
+     * (path lookup) populates the map for items the current recipe
+     * doesn't itself create.
+     */
+    itemRefKey: GUID,
+    /**
+     * Optional content-tree path for late-path seeding — same semantics
+     * as `SetFieldOpSchema.latePath`. Section definition items are
+     * typically pre-existing tenant scaffolding (not created by the
+     * recipe set), so the compiler emits this so the executor can
+     * resolve the itemId on demand if it's not in the captured map.
+     */
+    latePath: zod_1.z.string().min(1).optional(),
+    /**
+     * Field GUID — the multi-list field to append into (e.g.
+     * Available Renderings). System fields use real Sitecore GUIDs;
+     * recipe-defined multi-list fields would carry the recipe-internal
+     * refKey (this case isn't used today but is forward-compatible).
+     */
+    fieldId: GUID,
+    /**
+     * Optional human-readable field name. See `FieldValueSchema.fieldName`
+     * — required for fields on recipe-created templates, omit for
+     * system fields whose GUIDs are real Sitecore built-ins.
+     */
+    fieldName: zod_1.z.string().min(1).optional(),
+    /**
+     * GUIDs to append. Same value can be specified twice (the executor
+     * de-duplicates after the merge) but compilers should normalise.
+     * Each entry is either:
+     *   - a real Sitecore GUID (`ref-guid` style — already resolved)
+     *   - a recipe-internal refKey (`ref-recipe` style — resolved via
+     *     captured map at execute time)
+     *
+     * The compiler emits a discriminated `RefValue` per entry so the
+     * executor can resolve recipe-handle refs (rendering GUIDs derived
+     * from `renderingId(handle)`) without compile-time knowledge of
+     * the tenant's assigned itemIds.
+     */
+    values: zod_1.z
+        .array(zod_1.z.discriminatedUnion("kind", [
+        zod_1.z.object({ kind: zod_1.z.literal("ref-guid"), value: GUID }),
+        zod_1.z.object({ kind: zod_1.z.literal("ref-recipe"), refKey: GUID }),
+    ]))
+        .min(1),
+    /**
+     * Append policy. `merge-unique` is the only supported value today
+     * (preserve existing, add missing). The discriminator is reserved so
+     * future policies — `replace` (full overwrite) or `replace-prefix`
+     * (atomic swap of a recipe-owned subset) — can land without changing
+     * the op shape. Existing IRs continue to round-trip unchanged.
+     */
+    appendPolicy: zod_1.z.literal("merge-unique"),
+});
+exports.OperationSchema = zod_1.z.discriminatedUnion("op", [
+    exports.CreateItemOpSchema,
+    exports.SetFieldOpSchema,
+    exports.SetBaseTemplatesOpSchema,
+    exports.SetStandardValuesOpSchema,
+    exports.CreateSiteFromTemplateOpSchema,
+    exports.AppendToMultiListOpSchema,
+]);
+exports.OperationIrSchema = zod_1.z.object({
+    schemaVersion: zod_1.z.literal("1"),
+    /** Source recipe handle, e.g. `cta-button@1`. */
+    recipeHandle: NON_EMPTY,
+    operations: zod_1.z.array(exports.OperationSchema),
+});