@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.1

package/dist/recipe/layout/parse.js

@@ -0,0 +1,295 @@
+"use strict";
+/**
+ * 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`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.layoutXmlEquivalent = exports.decodeParBlob = void 0;
+exports.parseLayoutXml = parseLayoutXml;
+const errors_1 = require("../../shared/errors");
+/** Normalise a Sitecore GUID to bare 32-hex, lower-case (strip `{}` and `-`). */
+const normalizeGuid = (guid) => guid.trim().toLowerCase().replace(/[{}-]/g, "");
+/**
+ * Decode the XML-attribute entity escapes `escapeXmlAttribute` introduces.
+ * Inverse of the emitter's `&` → `&amp;` etc. chain; `&amp;` is decoded
+ * last so a literal `&amp;lt;` in the source survives intact.
+ */
+const unescapeXmlAttribute = (value) => value
+    .replace(/&quot;/g, '"')
+    .replace(/&gt;/g, ">")
+    .replace(/&lt;/g, "<")
+    .replace(/&amp;/g, "&");
+/**
+ * Pull every `name="value"` (or `name='value'`) attribute off a single XML
+ * element's start tag into a map. Attribute values are XML-unescaped; the
+ * map key is the raw attribute name including any namespace prefix
+ * (`s:placeh`, `p:before`). Sitecore's layout XML never nests quotes inside
+ * an attribute value other than via the `&quot;` entity, so a
+ * non-greedy `"[^"]*"` / `'[^']*'` scan is exact for this format.
+ */
+const parseAttributes = (tag) => {
+    const attrs = {};
+    const attrRe = /([\w:.-]+)\s*=\s*("([^"]*)"|'([^']*)')/g;
+    let match;
+    while ((match = attrRe.exec(tag)) !== null) {
+        const rawValue = match[3] !== undefined ? match[3] : (match[4] ?? "");
+        attrs[match[1]] = unescapeXmlAttribute(rawValue);
+    }
+    return attrs;
+};
+/**
+ * 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.
+ */
+const decodeParBlob = (par) => {
+    const trimmed = par.trim();
+    if (trimmed === "")
+        return {};
+    let variant;
+    const params = {};
+    for (const pair of trimmed.split("&")) {
+        if (pair === "")
+            continue;
+        const eq = pair.indexOf("=");
+        // A bare token with no `=` is a degenerate pair — treat it as a
+        // key with an empty value rather than dropping it.
+        const rawKey = eq >= 0 ? pair.slice(0, eq) : pair;
+        const rawValue = eq >= 0 ? pair.slice(eq + 1) : "";
+        const key = decodeURIComponent(rawKey);
+        const value = decodeURIComponent(rawValue);
+        if (key === "FieldNames") {
+            variant = value;
+        }
+        else {
+            params[key] = value;
+        }
+    }
+    const result = {};
+    if (variant !== undefined)
+        result.variant = variant;
+    if (Object.keys(params).length > 0)
+        result.params = params;
+    return result;
+};
+exports.decodeParBlob = decodeParBlob;
+/**
+ * Build a `ParsedPlacement` from one `<r>` rendering element's attributes.
+ * Handles both wire forms by reading either the prefixed (`s:placeh`,
+ * `s:ds`, `s:id`, `s:par`) or the canonical (`placeh`, `ds`, `id`, `par`)
+ * attribute name — delta-form `<r>` elements only ever carry the prefixed
+ * set, canonical only the bare set, so a prefer-prefixed-then-bare lookup
+ * is unambiguous.
+ */
+const placementFromAttributes = (attrs) => {
+    const pick = (...names) => {
+        for (const name of names) {
+            if (attrs[name] !== undefined)
+                return attrs[name];
+        }
+        return undefined;
+    };
+    const rawId = pick("s:id", "id");
+    if (rawId === undefined || rawId.trim() === "") {
+        throw (0, errors_1.createScaiError)("layout XML <r> element is missing its rendering id attribute — not a parseable placement.", "INPUT_INVALID");
+    }
+    const placeholderKey = pick("s:placeh", "placeh") ?? "";
+    const uid = pick("uid");
+    const placement = {
+        renderingGuid: normalizeGuid(rawId),
+        placeholderKey,
+        uid: uid !== undefined ? normalizeGuid(uid) : "",
+    };
+    const rawDs = pick("s:ds", "ds");
+    if (rawDs !== undefined && rawDs.trim() !== "") {
+        if (rawDs.startsWith("local:")) {
+            // The `local:<slot>` sentinel emitLayoutXml writes for an
+            // unresolved scoped datasource ref.
+            placement.datasource = { kind: "local", slot: rawDs.slice("local:".length) };
+        }
+        else {
+            placement.datasource = { kind: "guid", guid: normalizeGuid(rawDs) };
+        }
+    }
+    // `par` is optional in canonical form, always present (often empty) in
+    // delta form — `decodeParBlob` treats an empty blob as no variant/params.
+    const par = pick("s:par", "par");
+    if (par !== undefined) {
+        const { variant, params } = (0, exports.decodeParBlob)(par);
+        if (variant !== undefined)
+            placement.variant = variant;
+        if (params !== undefined)
+            placement.params = params;
+    }
+    return placement;
+};
+/**
+ * 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.
+ */
+function parseLayoutXml(xml) {
+    const trimmed = xml.trim();
+    if (trimmed === "") {
+        return { placeholders: {}, mode: "canonical" };
+    }
+    // The root element is always `<r …>`. Isolate its start tag to read the
+    // namespace declarations that distinguish the two wire forms.
+    const rootTagMatch = /^<r\b([^>]*)>/.exec(trimmed);
+    if (!rootTagMatch) {
+        throw (0, errors_1.createScaiError)("string is not a Sitecore layout XML — expected a <r> root element.", "INPUT_INVALID");
+    }
+    const rootAttrs = parseAttributes(`<r${rootTagMatch[1]}>`);
+    // Delta form declares the `p` (parameters) namespace and carries `p:p`;
+    // canonical declares the XSD/XSI schema namespaces. Default to canonical.
+    const mode = rootAttrs["xmlns:p"] !== undefined || rootAttrs["p:p"] !== undefined ? "delta" : "canonical";
+    // The device element wraps every rendering. Recover its `l` (JSON
+    // Layout) attribute when present — canonical-only.
+    let layoutId;
+    const deviceTagMatch = /<d\b([^>]*)>/.exec(trimmed);
+    if (deviceTagMatch) {
+        const deviceAttrs = parseAttributes(`<d${deviceTagMatch[1]}>`);
+        if (deviceAttrs["l"] !== undefined && deviceAttrs["l"].trim() !== "") {
+            layoutId = normalizeGuid(deviceAttrs["l"]);
+        }
+    }
+    const placeholders = {};
+    // Scan every `<r …/>` (or `<r …></r>`) element that is NOT the root.
+    // The root `<r>` start tag has children, so it never matches the
+    // self-closing / short-form `<r …/>` pattern; the rendering elements
+    // emitLayoutXml writes are always self-closing. `<p:da …/>` is the
+    // delta directive element — skipped because it doesn't match `<r\b`.
+    const renderingRe = /<r\b([^>]*?)\/>/g;
+    let match;
+    while ((match = renderingRe.exec(trimmed)) !== null) {
+        const attrs = parseAttributes(`<r${match[1]}/>`);
+        const placement = placementFromAttributes(attrs);
+        if (placeholders[placement.placeholderKey] === undefined) {
+            placeholders[placement.placeholderKey] = [];
+        }
+        placeholders[placement.placeholderKey].push(placement);
+    }
+    const result = { placeholders, mode };
+    if (layoutId !== undefined)
+        result.layoutId = layoutId;
+    return result;
+}
+/**
+ * Canonical comparable projection of a parsed layout — placeholder keys
+ * sorted (key order is irrelevant), placement order preserved (it IS the
+ * render order), params sorted, `uid` and `mode` dropped.
+ */
+const canonicalLayout = (parsed) => {
+    const placeholders = Object.keys(parsed.placeholders)
+        .sort()
+        .map((key) => [
+        key,
+        parsed.placeholders[key].map((placement) => ({
+            rendering: placement.renderingGuid,
+            placeholder: placement.placeholderKey,
+            datasource: placement.datasource ?? null,
+            variant: placement.variant ?? null,
+            params: Object.fromEntries(Object.entries(placement.params ?? {}).sort()),
+        })),
+    ]);
+    return JSON.stringify({ layoutId: parsed.layoutId ?? null, placeholders });
+};
+/**
+ * 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.
+ */
+const layoutXmlEquivalent = (a, b) => {
+    if (a === b)
+        return true;
+    try {
+        return canonicalLayout(parseLayoutXml(a)) === canonicalLayout(parseLayoutXml(b));
+    }
+    catch {
+        return false;
+    }
+};
+exports.layoutXmlEquivalent = layoutXmlEquivalent;

package/dist/recipe/layout/templates-mapping.d.ts

@@ -25,4 +25,3 @@ export interface TemplatesMappingEntry {
  * normalized to upper-case curly form before URL-encoding.
  */
 export declare function encodeTemplatesMapping(entries: readonly TemplatesMappingEntry[]): string;
-//# sourceMappingURL=templates-mapping.d.ts.map

package/dist/recipe/marker.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Recipe identity marker — the `Scai Handle` field.
+ *
+ * Every recipe-managed Sitecore item carries its recipe handle in a
+ * `Scai Handle` field (a shared field on the Standard Template). The
+ * handle — not the mutable content-tree path — is the recipe's identity
+ * hook: a moved or renamed item is still matched on the next push, and
+ * `readCurrent` recovers the exact authored handle instead of
+ * synthesising one from the item name.
+ *
+ * This module owns the push-write half — `injectHandleMarker` stamps the
+ * marker onto every `CreateItem` op a compiled recipe emits. Reading the
+ * marker back (planner match + `readCurrent`) lives with those consumers.
+ *
+ * See docs/recipe-sync-architecture.md, "Recipe identity — the marker field".
+ */
+import type { OperationIr } from "./ir/operations";
+/** Field name of the recipe-identity marker on the Standard Template. */
+export declare const SCAI_HANDLE_FIELD_NAME = "Scai Handle";
+/**
+ * Inject the recipe handle as a `Scai Handle` field on every `CreateItem`
+ * op in an IR, so every recipe-managed item carries its recipe identity.
+ *
+ * Pure. Idempotent — a `CreateItem` op that already carries the marker is
+ * returned unchanged. The marker rides the op's `fields`, so it is written
+ * on create and re-converged through the same field-drift path on update.
+ */
+export declare const injectHandleMarker: (ir: OperationIr) => OperationIr;

package/dist/recipe/marker.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.injectHandleMarker = exports.SCAI_HANDLE_FIELD_NAME = void 0;
+/** Field name of the recipe-identity marker on the Standard Template. */
+exports.SCAI_HANDLE_FIELD_NAME = "Scai Handle";
+/**
+ * Placeholder `fieldId` for the marker. The marker is always written and
+ * matched by NAME — the authoring client's field input and the planner's
+ * drift check both prefer `fieldName` — and the real field's GUID is
+ * server-assigned per environment, so a stable sentinel is correct here.
+ */
+const SCAI_HANDLE_FIELD_ID = "00000000-0000-0000-0000-5ca15ca15ca1";
+const markerField = (handle) => ({
+    fieldId: SCAI_HANDLE_FIELD_ID,
+    fieldName: exports.SCAI_HANDLE_FIELD_NAME,
+    value: { kind: "string", value: handle },
+});
+/**
+ * Inject the recipe handle as a `Scai Handle` field on every `CreateItem`
+ * op in an IR, so every recipe-managed item carries its recipe identity.
+ *
+ * Pure. Idempotent — a `CreateItem` op that already carries the marker is
+ * returned unchanged. The marker rides the op's `fields`, so it is written
+ * on create and re-converged through the same field-drift path on update.
+ */
+const injectHandleMarker = (ir) => ({
+    ...ir,
+    operations: ir.operations.map((op) => {
+        if (op.op !== "CreateItem")
+            return op;
+        if (op.fields.some((field) => field.fieldName === exports.SCAI_HANDLE_FIELD_NAME)) {
+            return op;
+        }
+        return { ...op, fields: [...op.fields, markerField(ir.recipeHandle)] };
+    }),
+});
+exports.injectHandleMarker = injectHandleMarker;

package/dist/recipe/plan.d.ts

@@ -2,7 +2,7 @@ import type { Operation, OperationIr } from "./ir/operations";
 import type { AuthoringApiClient, CreateItemInput, RemoteItem, UpdateItemInput } from "./api/client";
 import type { NewSiteInput, SitesApiClient } from "./api/sites-client";
 /**
- * `scai recipe plan` and `scai recipe push` share this read-then-diff path:
+ * `scai provision recipe plan` and `scai provision recipe push` share this read-then-diff path:
  *
  *   for each op:
  *     resolve the target item (path-based for CreateItem, captured-id
@@ -49,6 +49,14 @@ export interface PlannedAction {
          * overrides etc.) can resolve.
          */
         siteRefKey: string;
+    } | {
+        kind: "addItemVersion";
+        /** Sitecore itemId of the target item. */
+        itemId: string;
+        /** Language whose numbered-version stack to extend. */
+        language: string;
+        /** How many versions to add to reach the op's declared `version`. */
+        addCount: number;
     };
     /**
      * Pre-mutation remote state captured during plan-time read. `null` means
@@ -131,4 +139,3 @@ export interface PlanOptions {
 export declare const buildAction: (index: number, op: Operation, client: AuthoringApiClient, capturedItemIds: Map<string, string>, sitesClient?: SitesApiClient, pathSnapshotCache?: Map<string, RemoteItem | null>) => Promise<PlannedAction>;
 export declare const buildPlan: (ir: OperationIr, client: AuthoringApiClient, options?: PlanOptions) => Promise<Plan>;
 export {};
-//# sourceMappingURL=plan.d.ts.map