@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/recipe/ir/sitecore-templates.js

@@ -11,7 +11,7 @@
  * executor layer.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ENUMERATION_ICON = exports.FOLDER_ICON = exports.DEFAULT_ICON = exports.DEFAULT_VERSION = exports.DEFAULT_LANGUAGE = exports.SECTION_DEFINITION_FIELDS = exports.DICTIONARY_ENTRY_FIELDS = exports.RENDERING_FIELDS = exports.DEFAULT_DEVICE_ID = exports.COMPOSITION_FIELDS = exports.SITE_FIELDS = exports.SITE_TEMPLATE_FIELDS = exports.LAYOUT_FIELDS = exports.TEMPLATE_FIELD_FIELDS = exports.SYSTEM_FIELDS = exports.SXA_HEADLESS_PARAMS_BASE_TEMPLATES = exports.STANDARD_TEMPLATE_ID = exports.SXA_COMPONENT_BASE_TEMPLATES = exports.PLACEHOLDER_FIELDS = exports.PLACEHOLDER_TEMPLATE_ID = exports.AVAILABLE_RENDERINGS_FIELDS = exports.SITECORE_TEMPLATES = void 0;
+exports.PAGE_TEMPLATE_ICON = exports.ENUMERATION_ICON = exports.FOLDER_ICON = exports.DEFAULT_ICON = exports.DEFAULT_VERSION = exports.DEFAULT_LANGUAGE = exports.SECTION_DEFINITION_FIELDS = exports.DICTIONARY_ENTRY_FIELDS = exports.RENDERING_FIELDS = exports.DEFAULT_DEVICE_ID = exports.COMPOSITION_FIELDS = exports.SITE_FIELDS = exports.SITE_TEMPLATE_FIELDS = exports.LAYOUT_FIELDS = exports.TEMPLATE_FIELD_FIELDS = exports.SYSTEM_FIELDS = exports.SXA_JSON_LAYOUT_ID = exports.PAGE_DESIGN_FIELD_ID = exports.SXA_HEADLESS_PAGE_BASE_TEMPLATES = exports.SXA_HEADLESS_PARAMS_BASE_TEMPLATES = exports.STANDARD_TEMPLATE_ID = exports.SXA_COMPONENT_BASE_TEMPLATES = exports.PLACEHOLDER_FIELDS = exports.PLACEHOLDER_SETTINGS_FOLDER_TEMPLATE_ID = exports.PLACEHOLDER_TEMPLATE_ID = exports.AVAILABLE_RENDERINGS_FIELDS = exports.SITECORE_TEMPLATES = void 0;
 exports.SITECORE_TEMPLATES = {
     /** Item conforms to this when it *is* a data template. */
     TEMPLATE: "ab86861a-6030-46c5-b394-e8f99e8b87db",
@@ -178,6 +178,24 @@ exports.AVAILABLE_RENDERINGS_FIELDS = {
  * conforms to this template.
  */
 exports.PLACEHOLDER_TEMPLATE_ID = "d2a6884c-04d5-4089-a64e-d27ca9d68d4c";
+/**
+ * SXA `Placeholder Settings Folder` template
+ * (`/sitecore/templates/Foundation/JSS Experience Accelerator/Placeholder
+ * Settings/Placeholder Settings Folder`). The organisational folder
+ * inside a Placeholder Settings tree — recipe-defined placeholder
+ * grouping folders conform to this so they inherit its `__Standard
+ * Values` Insert Options (`Placeholder` + `Placeholder Settings
+ * Folder`), giving authors the right right-click → Insert UX without
+ * scai having to stamp `__Masters` explicitly.
+ *
+ * Verified against sandbox tenant (`xmc-lizsitecore088b-…`) on
+ * 2026-05-15 via Authoring API introspection — the `Placeholder
+ * Settings` root and its `Partial Design` child both conform to it, and
+ * the template's SV carries
+ * `__Masters = {D2A6884C-…}|{52288E39-…}` (see
+ * `scripts/_recon-page-template.cjs`).
+ */
+exports.PLACEHOLDER_SETTINGS_FOLDER_TEMPLATE_ID = "52288e39-7830-4694-b62d-32a54c6ef7ba";
 /**
  * Fields of the Sitecore `Placeholder` template that recipes interact
  * with:
@@ -260,6 +278,66 @@ exports.SXA_HEADLESS_PARAMS_BASE_TEMPLATES = [
     "44a022db-56d3-419a-b43b-e27e4d8e9c41",
     "3db3eb10-f8d0-4cc9-be26-18ce7b139ec8",
 ];
+/**
+ * SXA Headless page base templates — what a recipe-emitted page template
+ * must inherit so XM Cloud Pages recognises items conforming to it as
+ * authorable pages: they pick up the layout/presentation fields, the
+ * navigation facet, taxonomy tagging, the page-design binding, and
+ * sitemap metadata.
+ *
+ * This is exactly the base set the OOTB per-site `Page` template
+ * carries. Captured 2026-05-15 by walking the `__Base template` chain of
+ * `/sitecore/templates/Project/demo-registry/Page` on the sandbox tenant
+ * (`xmc-lizsitecore088b-…`) via Authoring API introspection — see
+ * `scripts/_recon-page-template.cjs`. All five are SXA Foundation
+ * templates, so the GUIDs are stable across tenants (same identity model
+ * as `SXA_COMPONENT_BASE_TEMPLATES`).
+ *
+ *   - `Base Page`  ({47151711-26CA-434E-8132-D3E0B7D26683}) —
+ *     `/sitecore/templates/Foundation/JSS Experience Accelerator/Multisite/Base Page`.
+ *     The SXA Headless page base; chains in the EXA `Page` →
+ *     Standard template, so the Layout / Appearance / Publishing
+ *     sections all arrive transitively.
+ *   - `_Navigable`  ({371D5FBB-5498-4D94-AB2B-E3B70EEBE78C}) —
+ *     navigation facet: `NavigationTitle`, `ChangeFrequency`, `Priority`.
+ *   - `_Taggable`  ({F39A594A-7BC9-4DB0-BAA1-88543409C1F9}) —
+ *     taxonomy tagging facet.
+ *   - `_Designable`  ({6650FB34-7EA1-4245-A919-5CC0F002A6D7}) —
+ *     carries the `Page Design` Droplink field (the per-item
+ *     page-design override). The default template→design binding is
+ *     the `TemplatesMapping` aggregate on the Page Designs root, not
+ *     this field — see `compileRecipeSet`.
+ *   - `_Sitemap`  ({4414A1F9-826A-4647-8DF4-ED6A95E64C43}) —
+ *     sitemap metadata facet.
+ */
+exports.SXA_HEADLESS_PAGE_BASE_TEMPLATES = [
+    "47151711-26ca-434e-8132-d3e0b7d26683",
+    "371d5fbb-5498-4d94-ab2b-e3b70eebe78c",
+    "f39a594a-7bc9-4db0-baa1-88543409c1f9",
+    "6650fb34-7ea1-4245-a919-5cc0f002a6d7",
+    "4414a1f9-826a-4647-8df4-ed6a95e64c43",
+];
+/**
+ * `Page Design` field on the SXA `_Designable` facet — a Droplink whose
+ * Source is `query:$pageDesigns//*[@@templatename='Page Design']`. The
+ * per-item page-design override; recipe-emitted page templates leave it
+ * unset (the default binding flows through the Page Designs root's
+ * `TemplatesMapping`). Captured in the same 2026-05-15 recon pass.
+ */
+exports.PAGE_DESIGN_FIELD_ID = "24171bf1-c0e1-480e-be76-4c0a1876f916";
+/**
+ * SXA Headless JSON `Layout` definition item (`/sitecore/layout/Layouts/
+ * Project/.../JSON Layout`). A page's `__Renderings` field wraps its
+ * device element with `l="{this}"` — `<d id="{device}" l="{layout}" />`.
+ * Recipe-emitted page templates stamp it on the `__Standard Values`
+ * layout shell so pages conforming to them render through the headless
+ * JSON layout pipeline.
+ *
+ * Captured 2026-05-15 from the `Page` template's `__Standard Values`
+ * `__Renderings` field on the sandbox tenant. SXA-shipped item, stable
+ * GUID across tenants.
+ */
+exports.SXA_JSON_LAYOUT_ID = "96e5f4ba-a2cf-4a4c-a4e7-64da88226362";
 /**
  * Stable system-field GUIDs that recipes need to write.
  * Auto-generated metadata fields (__Created, __Updated, __Revision, __Owner)
@@ -294,6 +372,14 @@ exports.TEMPLATE_FIELD_FIELDS = {
      * value, not per-language). GUID is the well-known Sitecore built-in.
      */
     SHARED: "be351a73-fcb0-4213-93fa-c302d8ab4f51",
+    /**
+     * `Unversioned` toggle on a Template Field — `"1"` makes the field's
+     * value per-language but shared across numbered versions (vs `SHARED`,
+     * which is one value for the whole item). Verified against the live
+     * `test` tenant via Authoring API introspection on 2026-05-15. GUID is
+     * the well-known Sitecore built-in.
+     */
+    UNVERSIONED: "39847666-389d-409b-95bd-f2016f11eed5",
 };
 /**
  * Sitecore layout fields. `__Renderings` carries the shared layout
@@ -463,3 +549,10 @@ exports.FOLDER_ICON = "office/16x16/folder.png";
  * icon through template-level inheritance.
  */
 exports.ENUMERATION_ICON = "office/32x32/keyboard_key_e.png";
+/**
+ * Icon for recipe-emitted page templates — matches the icon the OOTB
+ * SXA Headless `Page` template carries (`Office/32x32/document_text.png`,
+ * verified 2026-05-15 on the sandbox tenant), so page templates read as
+ * pages — not generic data templates — in the content-tree.
+ */
+exports.PAGE_TEMPLATE_ICON = "Office/32x32/document_text.png";

package/dist/recipe/layout/emit.d.ts

@@ -63,10 +63,20 @@ export interface LayoutEmitContext {
     /**
      * Whether `kind: "scoped"` datasource refs are permitted. False for
      * partial-design and page-design layouts (they don't have a host page
-     * to resolve scoped refs against). True will be set by Phase 5
-     * `PageRecipe` compilation when scoped refs become meaningful.
+     * to resolve scoped refs against); `PageRecipe` sets it true.
      */
     allowScoped: boolean;
+    /**
+     * Resolver for `kind: "scoped"` datasource refs — maps a placement's
+     * `slot` to the GUID of the page-local datasource item the caller
+     * materialises at `<page>/Data/<slot>`. `PageRecipe` passes this; the
+     * scoped `<r>` element then carries `ds="{resolvedGuid}"`.
+     *
+     * When `allowScoped` is true but this is absent, a scoped ref falls
+     * back to a `ds="local:<slot>"` sentinel (recognisable, fails loudly
+     * if executed) — kept only for forward-compat / diagnostics.
+     */
+    scopedDatasourceIdFor?: (slot: string) => string;
     /**
      * Wire form for the emitted XML.
      *
@@ -83,6 +93,16 @@ export interface LayoutEmitContext {
      *   mode (they preserve canonical and would diverge).
      */
     mode?: "canonical" | "delta";
+    /**
+     * SXA JSON Layout definition GUID. When set, the device element
+     * carries an `l="{layoutId}"` attribute — `<d id="{device}"
+     * l="{layout}">…</d>` — and `emitLayoutXml` emits the wrapper shell
+     * even when there are zero placements (a page-template `__Standard
+     * Values` layout: device + JSON-layout pointer, no renderings). Used
+     * only in `"canonical"` mode; `"delta"` ignores it. When unset, the
+     * device element has no `l` attribute (partial / page-design layouts).
+     */
+    layoutId?: string;
 }
 /**
  * Emit the layout XML for a `Layout` block. Returns an empty string
@@ -98,4 +118,3 @@ export interface LayoutEmitContext {
  * scoped refs because they lack a host page.
  */
 export declare function emitLayoutXml(layout: LayoutInput, ctx: LayoutEmitContext): string;
-//# sourceMappingURL=emit.d.ts.map

package/dist/recipe/layout/emit.js

@@ -20,12 +20,18 @@ const resolvePlacement = (placement, placeholderKey, index, ctx) => {
                 break;
             case "scoped":
                 if (!ctx.allowScoped) {
-                    throw (0, errors_1.createCliError)(`scoped datasourceRef is invalid in this layout context (no host page to resolve against). Slot: '${placement.datasourceRef.slot}'. Use 'shared' for reusable content or 'none' for config-driven renderings.`, "INPUT_INVALID");
+                    throw (0, errors_1.createScaiError)(`scoped datasourceRef is invalid in this layout context (no host page to resolve against). Slot: '${placement.datasourceRef.slot}'. Use 'shared' for reusable content or 'none' for config-driven renderings.`, "INPUT_INVALID");
+                }
+                if (ctx.scopedDatasourceIdFor) {
+                    // Page-local datasource — resolved to the GUID of the item the
+                    // page compiler materialises at `<page>/Data/<slot>`.
+                    dsAttr = ` ds="${formatGuidCurly(ctx.scopedDatasourceIdFor(placement.datasourceRef.slot))}"`;
+                }
+                else {
+                    // No resolver — emit an explicit `local:` sentinel so any
+                    // premature execution fails loudly with a recognizable marker.
+                    dsAttr = ` ds="local:${escapeXmlAttribute(placement.datasourceRef.slot)}"`;
                 }
-                // Scoped resolution is a Phase 5 concern (PageRecipe). Emit
-                // an explicit local-* sentinel so any premature execution
-                // fails loudly with a recognizable marker.
-                dsAttr = ` ds="local:${escapeXmlAttribute(placement.datasourceRef.slot)}"`;
                 break;
             case "none":
                 // No ds attribute — rendering is config-driven via params.
@@ -56,7 +62,11 @@ const resolvePlacement = (placement, placeholderKey, index, ctx) => {
  */
 function emitLayoutXml(layout, ctx) {
     const placeholderEntries = Object.entries(layout.placeholders).filter(([, placements]) => placements.length > 0);
-    if (placeholderEntries.length === 0) {
+    // With `layoutId` set the caller wants the device+layout shell even
+    // when empty (a page-template standard-values layout). Otherwise an
+    // empty layout emits nothing — the caller decides whether to skip the
+    // field write.
+    if (placeholderEntries.length === 0 && ctx.layoutId === undefined) {
         return "";
     }
     if ((ctx.mode ?? "canonical") === "delta") {
@@ -73,7 +83,8 @@ const emitCanonical = (placeholderEntries, ctx) => {
             elements.push(`<r id="${r.renderingId}" placeh="${escapeXmlAttribute(r.placeholderKey)}"${r.dsAttr}${parAttr} uid="${r.uid}" />`);
         });
     }
-    return `<r xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><d id="${formatGuidCurly(ctx.deviceId)}">${elements.join("")}</d></r>`;
+    const layoutAttr = ctx.layoutId ? ` l="${formatGuidCurly(ctx.layoutId)}"` : "";
+    return `<r xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><d id="${formatGuidCurly(ctx.deviceId)}"${layoutAttr}>${elements.join("")}</d></r>`;
 };
 /**
  * Emit SXA Partial Design delta form. Per-placeholder anchor sequence:

package/dist/recipe/layout/parse.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Parse a Sitecore layout XML string back into a structural `Layout` shape.
+ *
+ * This is the inverse of `emitLayoutXml` (`./emit.ts`): where the emitter
+ * turns a recipe-level `Layout` into the wire string Sitecore stores on the
+ * `__Renderings` / `__Final Renderings` field, `parseLayoutXml` walks that
+ * wire string and reconstructs the `Layout` — the seam `read-current.ts`
+ * uses to reverse-project the layout-bearing recipe kinds (partial-design,
+ * page-design, page).
+ *
+ * ## Both wire forms
+ *
+ * `emitLayoutXml` emits two forms; this parser auto-detects and handles
+ * both off the root element's namespace declarations:
+ *
+ *  - **canonical** — `<r xmlns:xsd xmlns:xsi><d id="{device}" [l="{layout}"]>
+ *    <r id placeh ds par uid /></d></r>`. The default form; Page Design
+ *    items round-trip it byte-for-byte.
+ *
+ *  - **delta** — SXA Partial Design form: `<r xmlns:p xmlns:s p:p="1"><d>
+ *    <p:da name="l" /><r uid p:before|p:after s:placeh s:ds s:id s:par />
+ *    </d></r>`. The Partial Design Layout pipeline normalises canonical
+ *    input into this form on first write.
+ *
+ * The two forms differ only in attribute prefixes (`s:placeh` vs `placeh`),
+ * the always-present `s:par=""` in delta, the `<p:da name="l" />` directive
+ * element delta carries, and the per-placement anchor attributes
+ * (`p:before` / `p:after`) delta uses instead of document order. Either
+ * way the parser reads the `<r>` rendering elements in document order —
+ * which is the placement order both emitters write — so placement ordering
+ * is preserved without interpreting the delta anchors. (The delta anchors
+ * are themselves derived from document order by `emitDelta`, so document
+ * order is the faithful signal.)
+ *
+ * ## What a parsed placement carries
+ *
+ * Each `<r>` rendering element yields a `ParsedPlacement`:
+ *
+ *   id    → renderingGuid   (bare 32-hex, lower-case)
+ *   placeh→ placeholderKey  (the `Layout.placeholders` dictionary key)
+ *   ds    → datasourceGuid  (bare hex) — or a `local:<slot>` sentinel
+ *   par   → variant + params (URL-decoded; the `FieldNames` param lifts
+ *           out to `variant`, the rest stay in `params`)
+ *   uid   → placementUid    (bare hex; informational — placement identity
+ *           is positional, not uid-derived, on the reverse path)
+ *
+ * GUID→handle resolution is NOT done here: this module is a pure
+ * wire-format decoder with no knowledge of the recipe handle space.
+ * `read-current.ts` owns the GUID→handle index and maps
+ * `ParsedPlacement` → `ComponentPlacement`.
+ */
+/**
+ * A single rendering placement decoded from one `<r>` element, before
+ * GUID→handle resolution. `read-current.ts` turns this into a recipe-level
+ * `ComponentPlacement`.
+ */
+export interface ParsedPlacement {
+    /** Rendering item GUID, bare 32-hex lower-case (the `id` attribute). */
+    renderingGuid: string;
+    /** Placeholder key — the `Layout.placeholders` dictionary key. */
+    placeholderKey: string;
+    /** Placement UID, bare hex. Informational; placement identity is positional. */
+    uid: string;
+    /**
+     * Datasource the placement binds to. Absent when the `<r>` element had
+     * no `ds` attribute (a `kind: "none"` config-driven rendering).
+     *
+     *  - `{ kind: "guid" }`  — a real Sitecore item GUID (bare hex). The
+     *    caller resolves it to a `shared` (content-item) or `scoped`
+     *    (page-local) datasource ref.
+     *  - `{ kind: "local" }` — the `local:<slot>` sentinel `emitLayoutXml`
+     *    writes for an unresolved scoped ref. Maps straight to a
+     *    `kind: "scoped"` datasourceRef with that slot.
+     */
+    datasource?: {
+        kind: "guid";
+        guid: string;
+    } | {
+        kind: "local";
+        slot: string;
+    };
+    /** SXA Rendering Variant — the `FieldNames` rendering parameter, if present. */
+    variant?: string;
+    /** Remaining rendering parameters (everything in `par` except `FieldNames`). */
+    params?: Record<string, string>;
+}
+/**
+ * The structural result of parsing a layout XML string. `placeholders`
+ * preserves placement order per key — array order is render order, the
+ * same contract `LayoutSchema` carries.
+ */
+export interface ParsedLayout {
+    placeholders: Record<string, ParsedPlacement[]>;
+    /**
+     * The wire form the input was in — `"canonical"` or `"delta"`. Returned
+     * for diagnostics; callers reconstructing a `Layout` ignore it (the
+     * recipe `Layout` shape is form-agnostic).
+     */
+    mode: "canonical" | "delta";
+    /**
+     * SXA JSON Layout definition GUID (bare hex), recovered from the device
+     * element's `l="{…}"` attribute when present. Only canonical layouts
+     * carry it (a page-template `__Standard Values` shell); `undefined`
+     * otherwise.
+     */
+    layoutId?: string;
+}
+/**
+ * Decode a `par` blob (URL-encoded `key=value&key=value` pairs) into a
+ * `{ variant, params }` split. The SXA Rendering Variant selection rides
+ * as the `FieldNames` parameter (see `emit.ts` `resolvePlacement`), so it
+ * is lifted out to `variant`; every other pair stays in `params`.
+ *
+ * Exported for direct unit testing — it is the trickiest decode in the
+ * round-trip and the one place a `+`-vs-`%20` or empty-value quirk would
+ * bite.
+ *
+ * `params` is `undefined` (not `{}`) when no non-FieldNames pairs remain,
+ * so the reconstructed placement omits an empty `params` rather than
+ * fabricating one — the lossy-projection contract `read-current.ts` keeps.
+ */
+export declare const decodeParBlob: (par: string) => {
+    variant?: string;
+    params?: Record<string, string>;
+};
+/**
+ * Parse a Sitecore layout XML string into a `ParsedLayout`.
+ *
+ * Auto-detects the wire form (`canonical` vs `delta`) from the root `<r>`
+ * element's namespace declarations — `xmlns:p` / `p:p` is the delta
+ * marker. Reads every `<r>` rendering element inside the single device
+ * element in document order, groups them by `placeh`, and preserves
+ * per-placeholder placement order.
+ *
+ * Returns an empty-placeholders `ParsedLayout` for an empty string or a
+ * device shell with no renderings (a page-template standard-values layout)
+ * — an empty layout is valid, not an error.
+ *
+ * Throws `INPUT_INVALID` only for genuinely malformed input: a string that
+ * isn't a layout XML root, or an `<r>` element with no rendering id.
+ */
+export declare function parseLayoutXml(xml: string): ParsedLayout;
+/**
+ * Structural equality of two layout XML strings — the seam the planner
+ * uses to decide whether a layout field genuinely drifted.
+ *
+ * Sitecore's layout pipeline normalises layout XML on write: canonical
+ * input is rewritten to SXA delta form, and a versioned `__Final
+ * Renderings` picks up extra `<p:da>` baseline directives. A naive
+ * string compare of "what the recipe emits" vs "what the tenant stores"
+ * then reports a phantom update on every re-push. Parsing both sides and
+ * comparing the recovered structure makes the diff wire-form-agnostic —
+ * same placeholders, same placements (rendering, datasource, variant,
+ * params) in the same order ⇒ equivalent.
+ *
+ * Placement `uid`s are excluded (placement identity is positional, and
+ * the uid is a deterministic derivation either way); `mode` is excluded
+ * (it IS the wire-form difference being normalised away); `layoutId` IS
+ * compared — it's semantically meaningful.
+ *
+ * Falls back to strict string equality when either side fails to parse,
+ * so genuinely malformed input is never silently treated as equal.
+ */
+export declare const layoutXmlEquivalent: (a: string, b: string) => boolean;