@sitecoreai-labs/sitecoreai-cli 0.0.4

package/dist/recipe/rollback.d.ts

@@ -0,0 +1,72 @@
+import type { AuthoringApiClient, UpdateItemInput } from "./api/client";
+import type { PlannedAction } from "./plan";
+/**
+ * Best-effort rollback for partial recipe pushes.
+ *
+ * When the executor's apply phase errors mid-IR, ops that already landed
+ * are still on the tenant. The rollback module unwinds them in LIFO order
+ * (reverse of the apply order, which mirrors topological order) using the
+ * pre-mutation snapshot each op captured at plan time:
+ *
+ *   - applied `createItem` (snapshot was null) → `deleteItem(itemId)`
+ *   - applied `updateItem` → `updateItem` with the prior value of each
+ *     touched field, or empty string when the field was unset
+ *
+ * "Best-effort" means a rollback step that itself errors is logged and
+ * counted, never cascaded — remaining rollbacks still run. The result
+ * carries `{rolledBack, errors}` for the terminal `failed` event payload.
+ */
+export type InverseMutation = {
+    kind: "deleteItem";
+    itemId: string;
+} | {
+    kind: "updateItem";
+    input: UpdateItemInput;
+};
+export interface RollbackError {
+    index: number;
+    label: string;
+    error: string;
+}
+export interface RollbackResult {
+    rolledBack: number;
+    errors: RollbackError[];
+}
+export type RollbackEvent = {
+    kind: "rollback-start";
+    action: PlannedAction;
+} | {
+    kind: "rollback-skip";
+    action: PlannedAction;
+    reason: string;
+} | {
+    kind: "rollback-success";
+    action: PlannedAction;
+} | {
+    kind: "rollback-failed";
+    action: PlannedAction;
+    error: string;
+};
+export interface RollbackOptions {
+    emit?: (event: RollbackEvent) => void;
+}
+/**
+ * Produce the inverse mutation for an applied action. Returns `null` when
+ * there's nothing to undo (a skip with no mutation).
+ *
+ * For an applied `createItem`, the inverse is `deleteItem(itemId)` where
+ * `itemId` is the Sitecore-assigned ID — captured by the executor on
+ * dispatch and looked up here via `capturedItemIds[action.operation.id]`.
+ *
+ * For an applied `updateItem`, each touched field reverts to its prior
+ * snapshot value. If a field was unset prior, the inverse sets it to ""
+ * (Sitecore's pragmatic clear). True "field-not-set" semantics would
+ * require a deleteField mutation; deferred to Phase 4.
+ */
+export declare const inverseOf: (action: PlannedAction, capturedItemIds: ReadonlyMap<string, string>) => InverseMutation | null;
+/**
+ * Unwind `applied` actions in LIFO order. Each step catches its own
+ * errors so a rollback failure on op N doesn't abort rollback of op N-1.
+ */
+export declare const rollback: (applied: PlannedAction[], client: AuthoringApiClient, capturedItemIds: ReadonlyMap<string, string>, options?: RollbackOptions) => Promise<RollbackResult>;
+//# sourceMappingURL=rollback.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rollback.d.ts","sourceRoot":"","sources":["../../src/recipe/rollback.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAc,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,eAAe,CAAA;CAAE,CAAC;AAEnD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtE,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;CACvC;AA0BD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,SAAS,GACpB,QAAQ,aAAa,EACrB,iBAAiB,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,KAC3C,eAAe,GAAG,IAoDpB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,QAAQ,GACnB,SAAS,aAAa,EAAE,EACxB,QAAQ,kBAAkB,EAC1B,iBAAiB,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5C,UAAS,eAAoB,KAC5B,OAAO,CAAC,cAAc,CAkDxB,CAAC"}

package/dist/recipe/rollback.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rollback = exports.inverseOf = void 0;
+const errors_1 = require("../shared/errors");
+const findPriorValue = (snapshot, fieldId, fieldName, language, version) => {
+    if (!snapshot)
+        return null;
+    // Match by name when the IR carries one — recipe-created fields don't
+    // share GUIDs between the IR (uuidv5 refKey) and the tenant (server-
+    // assigned). Else match by fieldId (system fields, real Sitecore GUIDs).
+    const found = snapshot.fields.find((f) => {
+        const idMatches = fieldName
+            ? f.name === fieldName
+            : f.fieldId.toLowerCase() === fieldId.toLowerCase();
+        return (idMatches &&
+            (language === undefined || f.language === language) &&
+            (version === undefined || f.version === version));
+    });
+    return found ? found.value : null;
+};
+/**
+ * Produce the inverse mutation for an applied action. Returns `null` when
+ * there's nothing to undo (a skip with no mutation).
+ *
+ * For an applied `createItem`, the inverse is `deleteItem(itemId)` where
+ * `itemId` is the Sitecore-assigned ID — captured by the executor on
+ * dispatch and looked up here via `capturedItemIds[action.operation.id]`.
+ *
+ * For an applied `updateItem`, each touched field reverts to its prior
+ * snapshot value. If a field was unset prior, the inverse sets it to ""
+ * (Sitecore's pragmatic clear). True "field-not-set" semantics would
+ * require a deleteField mutation; deferred to Phase 4.
+ */
+const inverseOf = (action, capturedItemIds) => {
+    if (!action.mutation)
+        return null;
+    if (action.mutation.kind === "createItem") {
+        if (action.operation.op !== "CreateItem") {
+            throw (0, errors_1.createCliError)("createItem mutation expected on a CreateItem operation.", "UNKNOWN");
+        }
+        const itemId = capturedItemIds.get(action.operation.id);
+        if (!itemId) {
+            // The create dispatched but we never captured its assigned itemId —
+            // refuse to roll back rather than guess. Caller treats as best-effort
+            // failure and continues.
+            throw (0, errors_1.createCliError)(`Rollback: no captured itemId for createItem refKey ${action.operation.id}.`, "UNKNOWN");
+        }
+        return { kind: "deleteItem", itemId };
+    }
+    if (action.mutation.kind === "createSite") {
+        // Site rollback is intentionally warn-only. The Sites API's
+        // `deleteSite` cascades through pages, settings, media, datasources,
+        // presentation, dictionaries, components, variants, and page designs
+        // — destructive enough that an automatic rollback during a
+        // half-failed push could remove operator content. Operators delete
+        // sites explicitly; the recipe pipeline doesn't.
+        return null;
+    }
+    // updateItem: each touched field reverts to its prior snapshot value.
+    const priorFields = action.mutation.input.fields.map((field) => {
+        const prior = findPriorValue(action.snapshot, field.fieldId, field.fieldName, field.language, field.version);
+        return {
+            fieldId: field.fieldId,
+            fieldName: field.fieldName,
+            language: field.language,
+            version: field.version,
+            value: { kind: "string", value: prior ?? "" },
+        };
+    });
+    return {
+        kind: "updateItem",
+        input: { itemId: action.mutation.input.itemId, fields: priorFields },
+    };
+};
+exports.inverseOf = inverseOf;
+/**
+ * Unwind `applied` actions in LIFO order. Each step catches its own
+ * errors so a rollback failure on op N doesn't abort rollback of op N-1.
+ */
+const rollback = async (applied, client, capturedItemIds, options = {}) => {
+    const result = { rolledBack: 0, errors: [] };
+    for (let i = applied.length - 1; i >= 0; i -= 1) {
+        const action = applied[i];
+        let inverse;
+        try {
+            inverse = (0, exports.inverseOf)(action, capturedItemIds);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            result.errors.push({
+                index: action.index,
+                label: action.operation.label,
+                error: message,
+            });
+            options.emit?.({ kind: "rollback-failed", action, error: message });
+            continue;
+        }
+        if (!inverse) {
+            options.emit?.({
+                kind: "rollback-skip",
+                action,
+                reason: "no inverse needed (no forward mutation)",
+            });
+            continue;
+        }
+        options.emit?.({ kind: "rollback-start", action });
+        try {
+            if (inverse.kind === "deleteItem") {
+                await client.deleteItem({ itemId: inverse.itemId });
+            }
+            else {
+                await client.updateItem(inverse.input);
+            }
+            result.rolledBack += 1;
+            options.emit?.({ kind: "rollback-success", action });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            result.errors.push({
+                index: action.index,
+                label: action.operation.label,
+                error: message,
+            });
+            options.emit?.({ kind: "rollback-failed", action, error: message });
+            // best-effort: continue with remaining rollbacks
+        }
+    }
+    return result;
+};
+exports.rollback = rollback;

package/dist/recipe/schema/field-types.d.ts

@@ -0,0 +1,72 @@
+import { z } from "zod";
+/**
+ * Two related taxonomies for recipe-defined fields:
+ *
+ * - `FieldShape` — abstract data shape from the React component's
+ *   perspective (text, image, link, enum, …). Recipe authors write this.
+ * - `SitecoreFieldType` — the canonical Sitecore field-type *string*
+ *   (Single-Line Text, Rich Text, …) stored verbatim in the field item's
+ *   `Type` shared field. Sitecore stores this as a string, NOT a GUID.
+ *
+ * The compiler maps `shape` → default Sitecore type, overridable
+ * per-field via `sitecore.type` on the recipe.
+ *
+ * **This taxonomy must stay in sync with the registry's working copy at
+ * `<registry>/src/lib/registry/sitecore-recipes.ts`.** Once scai exposes
+ * a typed recipe export, the registry will import it and this duplication
+ * goes away.
+ */
+export declare const FIELD_SHAPES: readonly ["text", "richText", "image", "link", "boolean", "number", "integer", "date", "datetime", "enum", "reference"];
+export type FieldShape = (typeof FIELD_SHAPES)[number];
+export declare const FieldShapeSchema: z.ZodEnum<{
+    number: "number";
+    boolean: "boolean";
+    integer: "integer";
+    link: "link";
+    enum: "enum";
+    text: "text";
+    date: "date";
+    richText: "richText";
+    image: "image";
+    datetime: "datetime";
+    reference: "reference";
+}>;
+export declare const SITECORE_FIELD_TYPES: readonly ["single-line-text", "multi-line-text", "rich-text", "image", "file", "general-link", "checkbox", "number", "integer", "date", "datetime", "droplist", "droplink", "treelist", "treelist-with-search", "lookup", "tags"];
+export type SitecoreFieldType = (typeof SITECORE_FIELD_TYPES)[number];
+export declare const SitecoreFieldTypeSchema: z.ZodEnum<{
+    number: "number";
+    integer: "integer";
+    tags: "tags";
+    lookup: "lookup";
+    date: "date";
+    file: "file";
+    image: "image";
+    datetime: "datetime";
+    "single-line-text": "single-line-text";
+    "multi-line-text": "multi-line-text";
+    "rich-text": "rich-text";
+    "general-link": "general-link";
+    checkbox: "checkbox";
+    droplist: "droplist";
+    droplink: "droplink";
+    treelist: "treelist";
+    "treelist-with-search": "treelist-with-search";
+}>;
+/** Stored verbatim in the field item's `Type` shared field. */
+export declare const sitecoreFieldTypeLabel: (type: SitecoreFieldType) => string;
+/**
+ * Map an abstract field shape to its default Sitecore field type.
+ * `reference` resolves to `treelist` when `multiple === true`, otherwise
+ * `droplink`. All other shapes are 1:1.
+ *
+ * `enum` maps to `droplink` (NOT droplist): SXA Headless rendering
+ * parameters and content fields back enumerated values with item-shaped
+ * Droplink references — the editor enumerates the source location's
+ * children at edit time. Pipe-delimited Droplist Source is the older
+ * vanilla-Sitecore pattern and is not how working SXA Headless params
+ * fields are wired (verified against tenant introspection 2026-05-02).
+ * Authors who specifically need a Droplist can override via
+ * `sitecore.type: "droplist"` on the field.
+ */
+export declare const defaultSitecoreFieldType: (shape: FieldShape, multiple?: boolean) => SitecoreFieldType;
+//# sourceMappingURL=field-types.d.ts.map

package/dist/recipe/schema/field-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-types.d.ts","sourceRoot":"","sources":["../../../src/recipe/schema/field-types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;GAgBG;AAEH,eAAO,MAAM,YAAY,yHAYf,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;EAAuB,CAAC;AAErD,eAAO,MAAM,oBAAoB,mOAkBvB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;EAA+B,CAAC;AAsBpE,+DAA+D;AAC/D,eAAO,MAAM,sBAAsB,GAAI,MAAM,iBAAiB,KAAG,MAChC,CAAC;AAElC;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB,GACnC,OAAO,UAAU,EACjB,WAAW,OAAO,KACjB,iBAyBF,CAAC"}

package/dist/recipe/schema/field-types.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultSitecoreFieldType = exports.sitecoreFieldTypeLabel = exports.SitecoreFieldTypeSchema = exports.SITECORE_FIELD_TYPES = exports.FieldShapeSchema = exports.FIELD_SHAPES = void 0;
+const zod_1 = require("zod");
+/**
+ * Two related taxonomies for recipe-defined fields:
+ *
+ * - `FieldShape` — abstract data shape from the React component's
+ *   perspective (text, image, link, enum, …). Recipe authors write this.
+ * - `SitecoreFieldType` — the canonical Sitecore field-type *string*
+ *   (Single-Line Text, Rich Text, …) stored verbatim in the field item's
+ *   `Type` shared field. Sitecore stores this as a string, NOT a GUID.
+ *
+ * The compiler maps `shape` → default Sitecore type, overridable
+ * per-field via `sitecore.type` on the recipe.
+ *
+ * **This taxonomy must stay in sync with the registry's working copy at
+ * `<registry>/src/lib/registry/sitecore-recipes.ts`.** Once scai exposes
+ * a typed recipe export, the registry will import it and this duplication
+ * goes away.
+ */
+exports.FIELD_SHAPES = [
+    "text",
+    "richText",
+    "image",
+    "link",
+    "boolean",
+    "number",
+    "integer",
+    "date",
+    "datetime",
+    "enum",
+    "reference",
+];
+exports.FieldShapeSchema = zod_1.z.enum(exports.FIELD_SHAPES);
+exports.SITECORE_FIELD_TYPES = [
+    "single-line-text",
+    "multi-line-text",
+    "rich-text",
+    "image",
+    "file",
+    "general-link",
+    "checkbox",
+    "number",
+    "integer",
+    "date",
+    "datetime",
+    "droplist",
+    "droplink",
+    "treelist",
+    "treelist-with-search",
+    "lookup",
+    "tags",
+];
+exports.SitecoreFieldTypeSchema = zod_1.z.enum(exports.SITECORE_FIELD_TYPES);
+const SITECORE_FIELD_TYPE_LABEL = {
+    "single-line-text": "Single-Line Text",
+    "multi-line-text": "Multi-Line Text",
+    "rich-text": "Rich Text",
+    image: "Image",
+    file: "File",
+    "general-link": "General Link",
+    checkbox: "Checkbox",
+    number: "Number",
+    integer: "Integer",
+    date: "Date",
+    datetime: "Datetime",
+    droplist: "Droplist",
+    droplink: "Droplink",
+    treelist: "Treelist",
+    "treelist-with-search": "Treelist with Search",
+    lookup: "Lookup",
+    tags: "Tags",
+};
+/** Stored verbatim in the field item's `Type` shared field. */
+const sitecoreFieldTypeLabel = (type) => SITECORE_FIELD_TYPE_LABEL[type];
+exports.sitecoreFieldTypeLabel = sitecoreFieldTypeLabel;
+/**
+ * Map an abstract field shape to its default Sitecore field type.
+ * `reference` resolves to `treelist` when `multiple === true`, otherwise
+ * `droplink`. All other shapes are 1:1.
+ *
+ * `enum` maps to `droplink` (NOT droplist): SXA Headless rendering
+ * parameters and content fields back enumerated values with item-shaped
+ * Droplink references — the editor enumerates the source location's
+ * children at edit time. Pipe-delimited Droplist Source is the older
+ * vanilla-Sitecore pattern and is not how working SXA Headless params
+ * fields are wired (verified against tenant introspection 2026-05-02).
+ * Authors who specifically need a Droplist can override via
+ * `sitecore.type: "droplist"` on the field.
+ */
+const defaultSitecoreFieldType = (shape, multiple) => {
+    switch (shape) {
+        case "text":
+            return "single-line-text";
+        case "richText":
+            return "rich-text";
+        case "image":
+            return "image";
+        case "link":
+            return "general-link";
+        case "boolean":
+            return "checkbox";
+        case "number":
+            return "number";
+        case "integer":
+            return "integer";
+        case "date":
+            return "date";
+        case "datetime":
+            return "datetime";
+        case "enum":
+            return "droplink";
+        case "reference":
+            return multiple ? "treelist" : "droplink";
+    }
+};
+exports.defaultSitecoreFieldType = defaultSitecoreFieldType;