@sitecoreai-labs/sitecoreai-cli 0.0.4

package/dist/recipe/layout/emit.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitLayoutXml = emitLayoutXml;
+const uuid_1 = require("uuid");
+const errors_1 = require("../../shared/errors");
+const formatGuidCurly = (guid) => `{${guid.toUpperCase()}}`;
+const escapeXmlAttribute = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+const encodeParams = (params) => Object.entries(params)
+    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+    .join("&");
+const placementUid = (parentItemId, placeholderKey, index, componentHandle) => (0, uuid_1.v5)(`placement:${placeholderKey}:${index}:${componentHandle}`, parentItemId);
+const resolvePlacement = (placement, placeholderKey, index, ctx) => {
+    const renderingId = formatGuidCurly(ctx.renderingIdFor(placement.componentHandle));
+    const uid = formatGuidCurly(placementUid(ctx.parentItemId, placeholderKey, index, placement.componentHandle));
+    let dsAttr = "";
+    if (placement.datasourceRef !== undefined) {
+        switch (placement.datasourceRef.kind) {
+            case "shared":
+                dsAttr = ` ds="${formatGuidCurly(ctx.contentItemIdFor(placement.datasourceRef.handle))}"`;
+                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");
+                }
+                // 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.
+                break;
+        }
+    }
+    const allParams = { ...(placement.params ?? {}) };
+    if (placement.variant !== undefined) {
+        // SXA Rendering Variant selection rides as the FieldNames
+        // rendering parameter — this is the SXA convention.
+        allParams.FieldNames = placement.variant;
+    }
+    const parValue = Object.keys(allParams).length > 0 ? encodeParams(allParams) : "";
+    return { renderingId, uid, placeholderKey, dsAttr, parValue };
+};
+/**
+ * Emit the layout XML for a `Layout` block. Returns an empty string
+ * when the layout has no placements — caller decides whether to write
+ * an empty `__Renderings` field or skip it.
+ *
+ * Mode selection (see `LayoutEmitContext.mode` JSDoc):
+ *  - `"canonical"` (default) — what page-design items round-trip cleanly.
+ *  - `"delta"` — SXA partial-design wire form so first push converges.
+ *
+ * Throws when a `kind: "scoped"` datasourceRef appears and
+ * `ctx.allowScoped` is false — partial designs and page designs reject
+ * scoped refs because they lack a host page.
+ */
+function emitLayoutXml(layout, ctx) {
+    const placeholderEntries = Object.entries(layout.placeholders).filter(([, placements]) => placements.length > 0);
+    if (placeholderEntries.length === 0) {
+        return "";
+    }
+    if ((ctx.mode ?? "canonical") === "delta") {
+        return emitDelta(placeholderEntries, ctx);
+    }
+    return emitCanonical(placeholderEntries, ctx);
+}
+const emitCanonical = (placeholderEntries, ctx) => {
+    const elements = [];
+    for (const [placeholderKey, placements] of placeholderEntries) {
+        placements.forEach((placement, idx) => {
+            const r = resolvePlacement(placement, placeholderKey, idx, ctx);
+            const parAttr = r.parValue ? ` par="${escapeXmlAttribute(r.parValue)}"` : "";
+            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>`;
+};
+/**
+ * Emit SXA Partial Design delta form. Per-placeholder anchor sequence:
+ *  - First placement in a placeholder: `p:before="*"` (insert before all)
+ *  - Last placement (when there are 2+ placements): `p:after="*[1=2]"`
+ *    (sentinel: position after a non-matching XPath = "at the end")
+ *  - Middle placements: `p:after="r[@uid='<previous-uid-in-placeholder>']"`
+ *
+ * Single-placement placeholders only emit `p:before="*"`. Across
+ * placeholders, anchor sequences are independent — each placeholder's
+ * placements form their own first/middle/last sequence in the order
+ * the recipe declares them. Attribute names get the `s:` prefix
+ * (`s:placeh`, `s:ds`, `s:id`, `s:par`); `uid` stays unprefixed; and
+ * `s:par=""` is always present (canonical form omits empty `par`).
+ */
+const emitDelta = (placeholderEntries, ctx) => {
+    const elements = [`<p:da name="l" />`];
+    for (const [placeholderKey, placements] of placeholderEntries) {
+        let prevUid = null;
+        placements.forEach((placement, idx) => {
+            const r = resolvePlacement(placement, placeholderKey, idx, ctx);
+            const isFirst = idx === 0;
+            const isLast = idx === placements.length - 1;
+            let anchorAttr;
+            if (isFirst) {
+                anchorAttr = ` p:before="*"`;
+            }
+            else if (isLast) {
+                anchorAttr = ` p:after="*[1=2]"`;
+            }
+            else if (prevUid) {
+                // Middle: reference the previous sibling's uid (without curlies in
+                // the XPath — Sitecore writes them bare in the `r[@uid='…']` form).
+                anchorAttr = ` p:after="r[@uid='${escapeXmlAttribute(prevUid)}']"`;
+            }
+            else {
+                // Defensive — shouldn't be reachable since prevUid is set after idx 0.
+                anchorAttr = ` p:after="*[1=2]"`;
+            }
+            // Convert canonical `ds="…"` → namespaced `s:ds="…"`. The dsAttr
+            // string already includes a leading space + `ds=` prefix, so we
+            // splice the `s:` prefix in.
+            const sDsAttr = r.dsAttr ? r.dsAttr.replace(/^ ds=/, " s:ds=") : "";
+            // s:par is always emitted in delta form (canonical omits empty par).
+            const sParAttr = ` s:par="${escapeXmlAttribute(r.parValue)}"`;
+            elements.push(`<r uid="${r.uid}"${anchorAttr} s:placeh="${escapeXmlAttribute(r.placeholderKey)}"${sDsAttr} s:id="${r.renderingId}"${sParAttr} />`);
+            prevUid = r.uid;
+        });
+    }
+    return `<r xmlns:p="p" xmlns:s="s" p:p="1"><d id="${formatGuidCurly(ctx.deviceId)}">${elements.join("")}</d></r>`;
+};

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

@@ -0,0 +1,28 @@
+/**
+ * URL-string encoder for Sitecore SXA's `TemplatesMapping` field on
+ * the Page Designs root item. The field stores a property bag in
+ * URL-encoded form:
+ *
+ *   {tplGuid1}={designGuid1}&{tplGuid2}={designGuid2}
+ *
+ * Each page design contributes one entry per applies-to template.
+ *
+ * Multi-recipe merging is the executor's job — when several
+ * `PageDesignRecipe`s in one push contribute their own slices of the
+ * mapping, the executor reads the existing field, merges contributions
+ * keyed by template GUID, and writes the combined result. This module
+ * is purely the wire-format encoder for one slice.
+ */
+export interface TemplatesMappingEntry {
+    /** Page-template item GUID (e.g. for `home-page@1`). */
+    templateGuid: string;
+    /** Page-design item GUID this template should use. */
+    designGuid: string;
+}
+/**
+ * Encode a list of template-to-design mappings into the URL-string
+ * form Sitecore stores in the `TemplatesMapping` field. GUIDs are
+ * 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/layout/templates-mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates-mapping.d.ts","sourceRoot":"","sources":["../../../src/recipe/layout/templates-mapping.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,MAAM,WAAW,qBAAqB;IACpC,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,SAAS,qBAAqB,EAAE,GAAG,MAAM,CAOxF"}

package/dist/recipe/layout/templates-mapping.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * URL-string encoder for Sitecore SXA's `TemplatesMapping` field on
+ * the Page Designs root item. The field stores a property bag in
+ * URL-encoded form:
+ *
+ *   {tplGuid1}={designGuid1}&{tplGuid2}={designGuid2}
+ *
+ * Each page design contributes one entry per applies-to template.
+ *
+ * Multi-recipe merging is the executor's job — when several
+ * `PageDesignRecipe`s in one push contribute their own slices of the
+ * mapping, the executor reads the existing field, merges contributions
+ * keyed by template GUID, and writes the combined result. This module
+ * is purely the wire-format encoder for one slice.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeTemplatesMapping = encodeTemplatesMapping;
+const formatGuidCurly = (guid) => `{${guid.toUpperCase()}}`;
+/**
+ * Encode a list of template-to-design mappings into the URL-string
+ * form Sitecore stores in the `TemplatesMapping` field. GUIDs are
+ * normalized to upper-case curly form before URL-encoding.
+ */
+function encodeTemplatesMapping(entries) {
+    return entries
+        .map(({ templateGuid, designGuid }) => `${encodeURIComponent(formatGuidCurly(templateGuid))}=${encodeURIComponent(formatGuidCurly(designGuid))}`)
+        .join("&");
+}

package/dist/recipe/plan.d.ts

@@ -0,0 +1,134 @@
+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:
+ *
+ *   for each op:
+ *     resolve the target item (path-based for CreateItem, captured-id
+ *       based for update-style ops)
+ *     read remote state; diff against IR
+ *     emit mutation per policy (create / update / skip / error)
+ *
+ * Sitecore's Authoring API server-assigns itemIds on `createItem`. The
+ * IR carries deterministic uuidv5 refKeys (recipe-internal) plus
+ * Sitecore paths (deterministic from recipe + envProfile roots). On each
+ * push, the executor maintains a per-run `capturedItemIds: Map<refKey,
+ * sitecoreItemId>` populated from `getItem(by path)` and `createItem`
+ * responses. Subsequent ops resolve their target by refKey → captured
+ * itemId, and `ref-recipe` field values resolve through the same map.
+ */
+export interface FieldDiffEntry {
+    fieldId: string;
+    before: string | null;
+    after: string;
+    language?: string;
+    version?: number;
+}
+type ActionStatus = "create" | "update" | "skip" | "error";
+export interface PlannedAction {
+    index: number;
+    operation: Operation;
+    status: ActionStatus;
+    reason?: string;
+    diff?: FieldDiffEntry[];
+    /** Snapshot of the mutation the executor will/would dispatch. */
+    mutation?: {
+        kind: "createItem";
+        input: CreateItemInput;
+    } | {
+        kind: "updateItem";
+        input: UpdateItemInput;
+    } | {
+        kind: "createSite";
+        input: NewSiteInput;
+        /**
+         * RefKey of the site item — the executor stores the
+         * server-assigned site itemId here in `capturedItemIds` so
+         * subsequent SetField ops scoped to the site (dictionary
+         * overrides etc.) can resolve.
+         */
+        siteRefKey: string;
+    };
+    /**
+     * Pre-mutation remote state captured during plan-time read. `null` means
+     * the target item did not exist at plan time. Used by rollback to
+     * derive inverse mutations.
+     */
+    snapshot?: RemoteItem | null;
+}
+export interface PlanSummary {
+    create: number;
+    update: number;
+    skip: number;
+    error: number;
+}
+export interface Plan {
+    schemaVersion: "1";
+    recipeHandle: string;
+    actions: PlannedAction[];
+    summary: PlanSummary;
+}
+export type PlanEvent = {
+    kind: "op-start";
+    index: number;
+    operation: Operation;
+} | {
+    kind: "op-result";
+    action: PlannedAction;
+} | {
+    kind: "op-error";
+    index: number;
+    operation: Operation;
+    error: string;
+};
+export interface PlanOptions {
+    emit?: (event: PlanEvent) => void;
+    /**
+     * Per-run map from recipe-internal refKey (uuidv5) to Sitecore-assigned
+     * itemId. The executor passes a shared map and updates it as creates
+     * resolve. Plan mode passes a fresh map; refs that don't resolve
+     * during plan-mode produce `skip` actions.
+     */
+    capturedItemIds?: Map<string, string>;
+    /**
+     * Sites API client — only consulted when an IR contains
+     * `CreateSiteFromTemplate` ops. Recipe sets that don't include
+     * SiteRecipes don't need a sites client; passing undefined is fine
+     * and yields an `error` action only if a site op is encountered.
+     */
+    sitesClient?: SitesApiClient;
+    /**
+     * Workspace-wide path → RemoteItem snapshot cache. When provided,
+     * `buildAction` consults it before issuing `client.getItem({ path })`
+     * for CreateItem ops. Cache hits skip the wire call entirely.
+     */
+    pathSnapshotCache?: Map<string, RemoteItem | null>;
+    /**
+     * Workspace-wide path → itemId cache (shared with the AuthoringApiClient).
+     * Threaded so `buildAction` can populate it after a successful read,
+     * and so the planner sees same path resolutions a sibling recipe
+     * already made earlier in the push.
+     */
+    pathItemIdCache?: Map<string, string>;
+}
+/**
+ * Plan a single op against the current remote state. Exposed so the
+ * executor's apply mode can interleave plan-and-apply per-op (each op's
+ * plan sees the cascading effect of earlier ops' applies — required for
+ * idempotency: a second push must see no drift on update-style ops whose
+ * targets the first push created).
+ *
+ * Updates `capturedItemIds` when `getItem(by path)` finds an existing
+ * item (so subsequent ops can resolve refs without dispatching).
+ *
+ * When a `pathSnapshotCache` is provided (workspace prefetch), each
+ * `getItem({ path })` call short-circuits to the cached value when the
+ * path is already known — `null` means "checked and missing", a
+ * `RemoteItem` means "use this snapshot". Non-path lookups (by itemId)
+ * still hit the wire.
+ */
+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

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

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/recipe/plan.ts"],"names":[],"mappings":"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"}