@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/recipe/plan.js

@@ -2,7 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildPlan = exports.buildAction = void 0;
 const sitecore_templates_1 = require("./ir/sitecore-templates");
+const marker_1 = require("./marker");
+const guids_1 = require("./guids");
 const ref_encoding_1 = require("./api/ref-encoding");
+const parse_1 = require("./layout/parse");
 const lookupField = (remote, fieldId, fieldName, language, version) => remote.fields.find((f) => {
     // Match by name when the IR carries one — recipe-created field GUIDs
     // are IR-internal refKeys that don't match the tenant's actual GUIDs,
@@ -24,6 +27,27 @@ const resolveAll = (fields, capturedItemIds) => fields.map((field) => ({
     ...field,
     value: (0, ref_encoding_1.resolveRecipeRefs)(field.value, capturedItemIds),
 }));
+/**
+ * Build an `UpdateItemInput`, lifting a uniform field `language` / `version`
+ * to the input level. The Authoring API writes every `FieldValueInput` at
+ * the input's language/version — per-field language/version is not on the
+ * wire — so a `SetField` targeting a non-default language or a story-seed
+ * numbered version must surface it here. When the fields disagree (or carry
+ * none) the level is left unset and the write lands on the item's default
+ * language / latest version.
+ */
+const toUpdateItemInput = (itemId, fields) => {
+    const input = { itemId, fields };
+    const languages = new Set(fields.map((field) => field.language));
+    if (languages.size === 1 && fields[0]?.language !== undefined) {
+        input.language = fields[0].language;
+    }
+    const versions = new Set(fields.map((field) => field.version));
+    if (versions.size === 1 && fields[0]?.version !== undefined) {
+        input.version = fields[0].version;
+    }
+    return input;
+};
 const computeFieldDrift = (desired, remote, capturedItemIds) => {
     const drift = [];
     for (const field of desired) {
@@ -40,7 +64,15 @@ const computeFieldDrift = (desired, remote, capturedItemIds) => {
             });
             continue;
         }
-        if (found.value !== want) {
+        // Layout fields (`__Renderings` / `__Final Renderings`) carry XML
+        // that Sitecore's layout pipeline normalises on write (canonical →
+        // SXA delta, plus baseline `<p:da>` directives). A raw string
+        // compare would report a phantom update on every re-push, so diff
+        // them structurally — same placements ⇒ no drift.
+        const isLayoutField = field.fieldId === sitecore_templates_1.LAYOUT_FIELDS.RENDERINGS ||
+            field.fieldId === sitecore_templates_1.LAYOUT_FIELDS.FINAL_RENDERINGS;
+        const equal = isLayoutField ? (0, parse_1.layoutXmlEquivalent)(found.value, want) : found.value === want;
+        if (!equal) {
             drift.push({
                 fieldId: field.fieldId,
                 before: found.value,
@@ -91,17 +123,68 @@ const resolveCreateItemParent = (op, capturedItemIds) => {
     }
     return { unresolvedRefKey: op.parent.refKey };
 };
-/** Resolve a CreateItem op's templateOf — usually a constant Sitecore GUID,
- *  but the SV item case has it as the recipe's own template refKey. */
+/**
+ * Strict variant of parent resolution for the plan-time sibling-name
+ * fallback. Unlike `resolveCreateItemParent` (which has plan-mode-friendly
+ * path-string fallbacks), this returns an itemId ONLY when one is
+ * actually in the captured map — so the caller can safely pass the
+ * result to `getChildren({ itemId })` without risk of feeding it a path.
+ */
+const resolveParentItemIdForFallback = (op, capturedItemIds) => {
+    const candidate = op.parent.kind === "ref-path"
+        ? capturedItemIds.get(op.parent.value)
+        : capturedItemIds.get(op.parent.refKey);
+    if (!candidate)
+        return null;
+    if (candidate.startsWith("/"))
+        return null;
+    return candidate;
+};
+/**
+ * The `Scai Handle` recipe-identity marker `injectHandleMarker` stamped on a
+ * CreateItem op, or `undefined` for an op that carries none (e.g. an IR that
+ * never went through `injectHandleMarker`).
+ */
+const opHandleMarker = (op) => {
+    const field = op.fields.find((f) => (f.fieldName ?? "").toLowerCase() === marker_1.SCAI_HANDLE_FIELD_NAME.toLowerCase());
+    return field && field.value.kind === "string" ? field.value.value : undefined;
+};
+/** The `Scai Handle` marker value on a live item, or `undefined` when unmarked. */
+const remoteHandleMarker = (item) => item.fields.find((f) => (f.name ?? "").toLowerCase() === marker_1.SCAI_HANDLE_FIELD_NAME.toLowerCase())
+    ?.value;
+/**
+ * Resolve a CreateItem op's templateOf to a Sitecore item ID.
+ *
+ *   - String form: usually a constant Sitecore built-in GUID. If it
+ *     matches a refKey captured during this push (e.g. SV item under
+ *     a recipe-created template), resolve to the captured itemId.
+ *   - `{kind: "ref-path"}` form: late-resolved against a content-tree
+ *     path. The push pipeline seeds `crossRecipeRefs[templatePathRefKey(path)] = path`;
+ *     the executor's `getItemsByPaths` batch lookup populates
+ *     `capturedItemIds` before planning starts. A miss here means the
+ *     template item doesn't exist on the tenant — planner skips with a
+ *     clear reason rather than letting the upstream createItem throw.
+ */
 const resolveTemplateOf = (op, capturedItemIds) => {
-    // If templateOf matches a refKey in our captured map, resolve it.
-    // Otherwise it's a known Sitecore built-in GUID and we use as-is.
-    const captured = capturedItemIds.get(op.templateOf);
-    if (captured) {
-        return { resolved: captured };
+    if (typeof op.templateOf === "string") {
+        // If templateOf matches a refKey in our captured map, resolve it.
+        // Otherwise it's a known Sitecore built-in GUID and we use as-is.
+        const captured = capturedItemIds.get(op.templateOf);
+        if (captured) {
+            return { resolved: captured };
+        }
+        // Known Sitecore built-in (Template, Section, Field, Folder, Rendering, etc.).
+        return { resolved: op.templateOf };
     }
-    // Known Sitecore built-in (Template, Section, Field, Folder, Rendering, etc.).
-    return { resolved: op.templateOf };
+    // ref-path: resolve via the seed map.
+    const refKey = (0, guids_1.templatePathRefKey)(op.templateOf.value);
+    const captured = capturedItemIds.get(refKey);
+    if (captured)
+        return { resolved: captured };
+    return {
+        unresolvedRefKey: refKey,
+        reason: `templateOf path '${op.templateOf.value}' did not resolve. The template item is missing from the tenant or the path is wrong — verify the template exists.`,
+    };
 };
 const planCreateItem = (op, remote, index, capturedItemIds) => {
     if (!remote) {
@@ -120,7 +203,7 @@ const planCreateItem = (op, remote, index, capturedItemIds) => {
                 index,
                 operation: op,
                 status: "skip",
-                reason: `templateOf ref ${tpl.unresolvedRefKey} not yet captured.`,
+                reason: tpl.reason ?? `templateOf ref ${tpl.unresolvedRefKey} not yet captured.`,
             };
         }
         // Plan-mode preview tolerates unresolved field refs: we report status
@@ -152,6 +235,14 @@ const planCreateItem = (op, remote, index, capturedItemIds) => {
                     templateId: tpl.resolved,
                     name: op.name,
                     fields: resolvedFields,
+                    // The planner reads existence via the path index, which lags
+                    // writes by seconds-to-minutes. On a rapid second push the
+                    // planner can see "missing" and plan a create against a path
+                    // the tenant already has — request an authoritative
+                    // parent-children pre-check at apply time to prevent
+                    // duplicate-sibling creation (the root cause of the
+                    // `audit slug-conflicts` false positives after re-push).
+                    idempotencyCheck: true,
                 },
             },
         };
@@ -182,7 +273,7 @@ const planCreateItem = (op, remote, index, capturedItemIds) => {
         diff: drift,
         mutation: {
             kind: "updateItem",
-            input: { itemId: remote.itemId, fields: fieldsToSet },
+            input: toUpdateItemInput(remote.itemId, fieldsToSet),
         },
     };
 };
@@ -222,10 +313,7 @@ const planUpdateOp = (index, op, itemRefKey, desiredFields, policy, remote, capt
         diff: drift,
         mutation: {
             kind: "updateItem",
-            input: {
-                itemId: remote.itemId,
-                fields: resolveAll(desiredFields, capturedItemIds),
-            },
+            input: toUpdateItemInput(remote.itemId, resolveAll(desiredFields, capturedItemIds)),
         },
     };
 };
@@ -273,7 +361,7 @@ const lookupSelector = (op, capturedItemIds) => {
         refKey = op.templateRefKey;
     }
     else {
-        // AppendToMultiList — target item is keyed by itemRefKey, same as SetField.
+        // AppendToMultiList / AddItemVersion — target item keyed by itemRefKey.
         refKey = op.itemRefKey;
     }
     const itemId = capturedItemIds.get(refKey);
@@ -320,7 +408,7 @@ const buildAction = async (index, op, client, capturedItemIds, sitesClient, path
         }
     }
     const selector = lookupSelector(op, capturedItemIds);
-    const remote = await (async () => {
+    let remote = await (async () => {
         if (!selector)
             return null;
         if (selector.path)
@@ -344,6 +432,50 @@ const buildAction = async (index, op, client, capturedItemIds, sitesClient, path
             }
         }
     }
+    // Sibling fallback for CreateItem against a null-cached path. Two cases
+    // both end with the planner finding the live item it would otherwise
+    // duplicate:
+    //
+    //   1. Path-index lag — Sitecore's path index trails writes by
+    //      seconds-to-minutes, so a repeat push within that window sees
+    //      `getItem({path})` return null for a path the tenant already has.
+    //      A name match among the parent's children is the lag-immune fix.
+    //   2. Rename — a CMS user renamed the item, so neither the path nor the
+    //      sibling NAME matches. The `Scai Handle` marker is identity that
+    //      survives a rename: a child still carrying this recipe's handle IS
+    //      the item, just renamed. The marker carries the *recipe* handle, so
+    //      every item one recipe creates under a shared parent gets the same
+    //      marker — the match is trusted only when exactly one sibling
+    //      carries it (an unambiguous (parent, handle) pair); >1 falls
+    //      through to the name path, never risking a wrong rebind.
+    //
+    // Without this, the planner schedules a duplicate create — the
+    // `createItem` mutation then either errors through the authoring-client's
+    // name-conflict trap (best case) or silently produces a duplicate item.
+    //
+    // `getChildren(parent)` walks the live item tree and is not lag-prone.
+    // Gated on parent-itemId-known so we don't pay an extra getChildren round
+    // trip on a true first push (where the parent itself is null too).
+    if (op.op === "CreateItem" && !remote) {
+        const parentItemId = resolveParentItemIdForFallback(op, capturedItemIds);
+        if (parentItemId) {
+            const siblings = await client.getChildren({ itemId: parentItemId });
+            let match = siblings.find((s) => s.name === op.name);
+            if (!match) {
+                const handle = opHandleMarker(op);
+                if (handle !== undefined) {
+                    const marked = siblings.filter((s) => remoteHandleMarker(s) === handle);
+                    if (marked.length === 1)
+                        match = marked[0];
+                }
+            }
+            if (match) {
+                remote = match;
+                capturedItemIds.set(op.id, match.itemId);
+                pathSnapshotCache?.set(op.path, match);
+            }
+        }
+    }
     const action = await (async () => {
         switch (op.op) {
             case "CreateItem":
@@ -358,6 +490,8 @@ const buildAction = async (index, op, client, capturedItemIds, sitesClient, path
                 return planCreateSite(index, op, capturedItemIds, sitesClient);
             case "AppendToMultiList":
                 return planAppendToMultiList(index, op, remote, capturedItemIds);
+            case "AddItemVersion":
+                return planAddItemVersion(index, op, remote, client);
         }
     })();
     return { ...action, snapshot: remote };
@@ -452,7 +586,49 @@ const planAppendToMultiList = (index, op, remote, capturedItemIds) => {
         ],
         mutation: {
             kind: "updateItem",
-            input: { itemId: remote.itemId, fields: [updatedField] },
+            input: toUpdateItemInput(remote.itemId, [updatedField]),
+        },
+    };
+};
+/**
+ * Plan an `AddItemVersion` op. Reads the target item's current versions in
+ * `op.language` and emits an `addItemVersion` mutation only when the
+ * declared `version` doesn't exist yet — so a re-push of a story-seed
+ * recipe is an all-`skip` no-op once the version stack is materialised.
+ *
+ * `addCount` is `op.version - currentMax`: the executor adds that many
+ * versions (Sitecore assigns the numbers sequentially). When `language` has
+ * no versions yet `currentMax` is 0, and adding version 1 also creates the
+ * language version.
+ */
+const planAddItemVersion = async (index, op, remote, client) => {
+    if (!remote) {
+        return {
+            index,
+            operation: op,
+            status: "skip",
+            reason: `Target item (refKey ${op.itemRefKey}) not yet captured/created.`,
+        };
+    }
+    const existing = await client.getItemVersions({ itemId: remote.itemId }, op.language);
+    const currentMax = existing.length > 0 ? Math.max(...existing) : 0;
+    if (currentMax >= op.version) {
+        return {
+            index,
+            operation: op,
+            status: "skip",
+            reason: `Version ${op.version} already exists in '${op.language}'.`,
+        };
+    }
+    return {
+        index,
+        operation: op,
+        status: "create",
+        mutation: {
+            kind: "addItemVersion",
+            itemId: remote.itemId,
+            language: op.language,
+            addCount: op.version - currentMax,
         },
     };
 };

package/dist/recipe/policy.d.ts

@@ -40,4 +40,3 @@ export declare const defaultPolicyForRecipe: (kind: Recipe["kind"]) => PushPolic
  * mapping.
  */
 export declare const policyForOp: (op: Operation) => PushPolicy;
-//# sourceMappingURL=policy.d.ts.map

package/dist/recipe/policy.js

@@ -10,10 +10,23 @@ const PURPOSE_BY_RECIPE_KIND = {
     "component-template": "template-structure",
     "content-template": "template-structure",
     "content-item": "datasource-item",
+    // Page templates are registry-owned data templates (with SXA page
+    // base inheritance + a layout-bearing standard values item) —
+    // template-structure, same CreateAndUpdate posture as component
+    // and content templates.
+    "page-template": "template-structure",
+    // A page is author-owned content — the registry seeds the page item
+    // and its layout; authors own it thereafter. CreateOnly (via the
+    // `page-item` purpose) so a re-push never clobbers author edits.
+    page: "page-item",
+    // Placeholder Settings items are registry-owned composition
+    // scaffolding — CreateAndUpdate so re-pushes can widen/narrow the
+    // Allowed Controls whitelist as the recipe set evolves.
+    placeholder: "composition-structure",
     // Standalone parameters templates and the synthesised inline-hoisted
     // ones share the same policy as component templates — they're
     // registry-owned and should overwrite tenant edits.
-    "parameters-template": "template-structure",
+    "design-parameters-template": "template-structure",
     // Section definitions are typically tenant-pre-existing; the
     // compiler emits AppendToMultiList ops against them rather than
     // CreateItem. Treat as composition-structure so any future
@@ -39,6 +52,11 @@ const PURPOSE_BY_RECIPE_KIND = {
     // to the recipe and re-push; CMS edits to enumeration items get
     // overwritten.
     enumeration: "template-structure",
+    // Workflows + webhook authorizations are registry-owned tenant-wide
+    // structure. CreateAndUpdate so re-pushes update state/command labels,
+    // webhook URLs, and authorization metadata as the recipe evolves.
+    workflow: "composition-structure",
+    "webhook-authorization": "composition-structure",
 };
 const purposeForRecipe = (kind) => PURPOSE_BY_RECIPE_KIND[kind];
 exports.purposeForRecipe = purposeForRecipe;

package/dist/recipe/read-current.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Reverse-projection — live Sitecore items → clean `Recipe` objects.
+ *
+ * This is the inverse of `src/recipe/compile/*`: where the compilers turn
+ * recipes into the Sitecore items a push would create, `readCurrent` walks
+ * the items a compiler *would have* produced and reconstructs the recipe.
+ * It is the `readCurrent` half of the `recipe` recipe kind (see
+ * `recipe-kind.ts` and docs/recipe-sync-architecture.md).
+ *
+ * ## Scope
+ *
+ * Nine recipe kinds reverse-project here — those whose item layout is
+ * stable and recoverable from the content tree alone:
+ *
+ *   1. `component-section`  — a Template Folder directly under componentsRoot
+ *   2. `component-template` — a Template with a matching rendering item
+ *   3. `content-template`   — a Template under contentModelsRoot, no rendering
+ *   4. `page-template`      — a Template carrying the SXA page base set
+ *   5. `enumeration`        — an Enumeration container under enumerationsRoot
+ *   6. `partial-design`     — an SXA Partial Design item under partialDesignsRoot
+ *   7. `page-design`        — an SXA Page Design item under pageDesignsRoot
+ *   8. `page`               — a page item under pagesRoot
+ *   9. `placeholder`        — a Placeholder Settings item under
+ *                             placeholderSettingsRoot
+ *
+ * Kinds 6–9 are the layout-bearing (and layout-adjacent) kinds: their
+ * fidelity hinges on parsing Sitecore layout XML back into the recipe
+ * `Layout` structure — `src/recipe/layout/parse.ts`, the inverse of
+ * `layout/emit.ts`. GUIDs inside the layout XML reference renderings and
+ * datasources; `readCurrent` builds a GUID→handle index off the
+ * `Scai Handle` marker (see `buildGuidHandleIndex`) and resolves them.
+ *
+ * Items under the configured roots that match none of these patterns are
+ * silently skipped — not an error. The remaining kinds (site, workflow,
+ * content-item, webhook-authorization, …) live in trees this walk doesn't
+ * visit; `readCurrent` just doesn't produce them.
+ *
+ * ## Fidelity — this projection is LOSSY by design
+ *
+ * Recipes carry high-level *intent* the item tree doesn't preserve. The
+ * contract is a documented best-effort: reconstruct what the items
+ * faithfully yield, and where a recipe field genuinely can't be recovered,
+ * **omit it or use the schema default — never fabricate a value**. A
+ * `readCurrent` → compile → `plan` round-trip on an unchanged environment
+ * should be close to all-`noop`; perfect is the goal, best-effort is the
+ * accepted v1 bar. See the per-kind JSDoc below for exactly what is faithful
+ * vs. approximated vs. omitted.
+ *
+ * Layout-XML reverse parsing is itself lossy at the GUID-resolution step:
+ * a layout `<r>` element that references a GUID with no `Scai Handle`
+ * marker is genuinely unrecoverable — the placement is dropped rather than
+ * pointed at a fabricated handle. See `placementFromParsed`.
+ *
+ * ## v1 limitation
+ *
+ * `ref.id` is ignored — `readCurrent` pulls every reverse-projectable
+ * subtree under the configured roots. Scoping the pull to a single item by
+ * name is a future refinement; the orchestrator (`recipe-kind.ts`) passes
+ * the whole-set `KindRef` today.
+ */
+import type { AuthoringApiClient } from "./api/client";
+import type { Recipe } from "./schema/recipe";
+/**
+ * The compile-time content-tree roots `readCurrent` walks. Mirrors the
+ * subset of `CompileContext` that the in-scope kinds actually live under.
+ * `recipe-kind.ts` builds this off the resolved env profile — the same
+ * fields `plan` reads.
+ */
+export interface ReadCurrentRoots {
+    /** Legacy flat templates root. Content/component templates fall back here. */
+    templatesRoot: string;
+    /** Renderings root — used to detect which templates have a rendering. */
+    renderingsRoot: string;
+    /** Per-site Components bucket. Component templates + sections live here. */
+    componentsRoot?: string;
+    /** Per-site Content Models bucket. Content templates live here. */
+    contentModelsRoot?: string;
+    /** Page-templates root. Templates carrying the SXA page base set live here. */
+    pageTemplatesRoot?: string;
+    /** Enumerations root. Enumeration containers + value items live here. */
+    enumerationsRoot?: string;
+    /** Partial Designs root. SXA Partial Design items live here. */
+    partialDesignsRoot?: string;
+    /** Page Designs root. SXA Page Design items live directly under it. */
+    pageDesignsRoot?: string;
+    /** Pages root. Concrete page items live here (often the site Home node). */
+    pagesRoot?: string;
+    /** Placeholder Settings root. Placeholder Settings items live under it. */
+    placeholderSettingsRoot?: string;
+}
+/**
+ * Reverse-project every in-scope subtree under the configured roots into a
+ * `Recipe[]` — all nine reverse-projectable kinds (see the module JSDoc).
+ *
+ * Order of work: the templates trees and enumerations first, then the
+ * layout-bearing kinds. The layout-bearing walkers share a GUID→handle
+ * marker index (`buildGuidHandleIndex`) built once up front — skipped
+ * entirely when no layout-bearing root is configured, so an environment
+ * without partial/page designs pays nothing for the index walk.
+ *
+ * Returns `null` only when the environment has *no* roots configured at all
+ * — the signal `recipe-kind.ts` uses to report "this environment has no
+ * recipe-projectable surface." Otherwise always returns the array, which may
+ * legitimately be empty (roots configured but empty trees).
+ *
+ * @param roots  Content-tree roots resolved off the env profile.
+ * @param client Authoring API read client (`getItem` / `getChildren`).
+ */
+export declare const readCurrentRecipes: (roots: ReadCurrentRoots, client: AuthoringApiClient) => Promise<Recipe[] | null>;