@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/recipe/compile.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ENUMERATIONS_ROOT_AGGREGATE_HANDLE = exports.SITE_DATA_ROOT_AGGREGATE_HANDLE = exports.SHARED_DATA_FOLDERS_AGGREGATE_HANDLE = exports.AVAILABLE_RENDERINGS_AGGREGATE_HANDLE = exports.TEMPLATES_MAPPING_AGGREGATE_HANDLE = exports.compileEnumerationRecipe = exports.compileSiteRecipe = exports.compileSiteTemplateRecipe = exports.compileContentItemRecipe = exports.compilePageDesignRecipe = exports.compilePartialDesignRecipe = exports.compileSectionDefinitionRecipe = exports.compileParametersTemplateRecipe = exports.compileContentTemplateRecipe = exports.compileComponentTemplateRecipe = exports.compileComponentSectionRecipe = void 0;
+exports.PLACEHOLDER_SETTINGS_AGGREGATE_HANDLE = exports.ENUMERATIONS_ROOT_AGGREGATE_HANDLE = exports.SITE_DATA_ROOT_AGGREGATE_HANDLE = exports.SHARED_DATA_FOLDERS_AGGREGATE_HANDLE = exports.AVAILABLE_RENDERINGS_AGGREGATE_HANDLE = exports.TEMPLATES_MAPPING_AGGREGATE_HANDLE = exports.compileWebhookAuthorizationRecipe = exports.compileWorkflowRecipe = exports.compileEnumerationRecipe = exports.compileSiteRecipe = exports.compileSiteTemplateRecipe = exports.compileContentItemRecipe = exports.compilePlaceholderRecipe = exports.compilePageRecipe = exports.compilePageTemplateRecipe = exports.compilePageDesignRecipe = exports.compilePartialDesignRecipe = exports.compileSectionDefinitionRecipe = exports.compileDesignParametersTemplateRecipe = exports.compileContentTemplateRecipe = exports.compileComponentTemplateRecipe = exports.compileComponentSectionRecipe = void 0;
 exports.compileRecipeSet = compileRecipeSet;
 exports.compileRecipe = compileRecipe;
+const errors_1 = require("../shared/errors");
 const guids_1 = require("./guids");
 const operations_1 = require("./ir/operations");
 const policy_1 = require("./policy");
@@ -15,14 +16,20 @@ const component_template_1 = require("./compile/component-template");
 Object.defineProperty(exports, "compileComponentTemplateRecipe", { enumerable: true, get: function () { return component_template_1.compileComponentTemplateRecipe; } });
 const content_template_1 = require("./compile/content-template");
 Object.defineProperty(exports, "compileContentTemplateRecipe", { enumerable: true, get: function () { return content_template_1.compileContentTemplateRecipe; } });
-const parameters_template_1 = require("./compile/parameters-template");
-Object.defineProperty(exports, "compileParametersTemplateRecipe", { enumerable: true, get: function () { return parameters_template_1.compileParametersTemplateRecipe; } });
+const design_parameters_template_1 = require("./compile/design-parameters-template");
+Object.defineProperty(exports, "compileDesignParametersTemplateRecipe", { enumerable: true, get: function () { return design_parameters_template_1.compileDesignParametersTemplateRecipe; } });
 const section_definition_1 = require("./compile/section-definition");
 Object.defineProperty(exports, "compileSectionDefinitionRecipe", { enumerable: true, get: function () { return section_definition_1.compileSectionDefinitionRecipe; } });
 const partial_design_1 = require("./compile/partial-design");
 Object.defineProperty(exports, "compilePartialDesignRecipe", { enumerable: true, get: function () { return partial_design_1.compilePartialDesignRecipe; } });
 const page_design_1 = require("./compile/page-design");
 Object.defineProperty(exports, "compilePageDesignRecipe", { enumerable: true, get: function () { return page_design_1.compilePageDesignRecipe; } });
+const page_template_1 = require("./compile/page-template");
+Object.defineProperty(exports, "compilePageTemplateRecipe", { enumerable: true, get: function () { return page_template_1.compilePageTemplateRecipe; } });
+const page_1 = require("./compile/page");
+Object.defineProperty(exports, "compilePageRecipe", { enumerable: true, get: function () { return page_1.compilePageRecipe; } });
+const placeholder_1 = require("./compile/placeholder");
+Object.defineProperty(exports, "compilePlaceholderRecipe", { enumerable: true, get: function () { return placeholder_1.compilePlaceholderRecipe; } });
 const content_item_1 = require("./compile/content-item");
 Object.defineProperty(exports, "compileContentItemRecipe", { enumerable: true, get: function () { return content_item_1.compileContentItemRecipe; } });
 const site_template_1 = require("./compile/site-template");
@@ -31,6 +38,10 @@ const site_1 = require("./compile/site");
 Object.defineProperty(exports, "compileSiteRecipe", { enumerable: true, get: function () { return site_1.compileSiteRecipe; } });
 const enumeration_1 = require("./compile/enumeration");
 Object.defineProperty(exports, "compileEnumerationRecipe", { enumerable: true, get: function () { return enumeration_1.compileEnumerationRecipe; } });
+const workflow_1 = require("./compile/workflow");
+Object.defineProperty(exports, "compileWorkflowRecipe", { enumerable: true, get: function () { return workflow_1.compileWorkflowRecipe; } });
+const webhook_authorization_1 = require("./compile/webhook-authorization");
+Object.defineProperty(exports, "compileWebhookAuthorizationRecipe", { enumerable: true, get: function () { return webhook_authorization_1.compileWebhookAuthorizationRecipe; } });
 const shared_1 = require("./compile/shared");
 /**
  * Stable handle for the synthetic IR `compileRecipeSet` emits to write
@@ -84,6 +95,54 @@ exports.SITE_DATA_ROOT_AGGREGATE_HANDLE = "__site-data-root__";
  * per-recipe enumeration folder templates).
  */
 exports.ENUMERATIONS_ROOT_AGGREGATE_HANDLE = "__enumerations-root__";
+/**
+ * Stable handle for the synthetic IR `compileRecipeSet` emits to
+ * materialise the Placeholder Settings items — one per unique
+ * placeholder key declared anywhere in the set (a `PlaceholderRecipe`
+ * or an inline `ComponentTemplateRecipe.placeholders` slot). Each key's
+ * `Allowed Controls` whitelist is the union of slot-side
+ * `allowedComponents` and every component naming the key in `placedIn`.
+ *
+ * Same `__…__` compiler-synthesized convention as the other aggregate
+ * handles in this file.
+ */
+exports.PLACEHOLDER_SETTINGS_AGGREGATE_HANDLE = "__placeholder-settings__";
+/**
+ * Cross-recipe apply-ordering rank, by recipe kind. `compileRecipeSet`
+ * stably sorts per-recipe IRs by this rank so every recipe is applied
+ * after the definitions it references:
+ *
+ *   0  definitions — templates, sections, enums, workflows: referenced
+ *      by everything, reference nothing cross-recipe forward.
+ *   1  content items + placeholders — reference rank-0 templates.
+ *   2  partial designs — place components, bind shared content items.
+ *   3  page designs + pages — reference page templates, partials,
+ *      content items.
+ *   4  site templates — reference page templates + page designs.
+ *   5  sites — instance a site template, point at an initial page.
+ *
+ * The rank is coarse — it orders ACROSS kinds, not within. Intra-rank
+ * forward references (e.g. one component's `insertOptions` naming
+ * another) still rely on the executor's `crossRecipeRefs` path seeding.
+ */
+const RECIPE_APPLY_RANK = {
+    "component-section": 0,
+    "component-template": 0,
+    "content-template": 0,
+    "page-template": 0,
+    "design-parameters-template": 0,
+    "section-definition": 0,
+    enumeration: 0,
+    workflow: 0,
+    "webhook-authorization": 0,
+    "content-item": 1,
+    placeholder: 1,
+    "partial-design": 2,
+    "page-design": 3,
+    page: 3,
+    "site-template": 4,
+    site: 5,
+};
 /**
  * Build the synthetic IR that materialises the SXA `Available Renderings`
  * section items for the recipe set, one per `recipe.section` value
@@ -276,7 +335,10 @@ const buildSharedDataFoldersAggregate = (shared, context, site) => {
         // FIRST `::` only.
         const sepIdx = key.indexOf("::");
         const subfolder = key.slice(sepIdx + 2);
-        const segments = subfolder.split("/").map((s) => s.trim()).filter(Boolean);
+        const segments = subfolder
+            .split("/")
+            .map((s) => s.trim())
+            .filter(Boolean);
         // Pre-pass already filters out empty subfolders (the `!!l.subfolder`
         // check), but defend against authored multi-`/` strings collapsing
         // to nothing after trim — skip rather than emitting a malformed op.
@@ -545,6 +607,192 @@ const buildEnumerationsRootAggregate = (recipes, context, site) => {
         operations,
     });
 };
+/**
+ * Derive a Sitecore item name from a placeholder key. Keys carry shapes
+ * item names can't (`/header`, `headless-main-{*}`); this strips the
+ * leading slash, drops `{…}` dynamic segments, and collapses remaining
+ * slashes to hyphens. Used only for inline `placeholders` slots — a
+ * standalone `PlaceholderRecipe` supplies `name` explicitly.
+ */
+const placeholderItemName = (key) => {
+    const cleaned = key
+        .replace(/^\/+/, "")
+        .replace(/\{[^}]*\}/g, "")
+        .replace(/\/+/g, "-")
+        .replace(/-+$/g, "")
+        .trim();
+    return cleaned.length > 0 ? cleaned : "placeholder";
+};
+/**
+ * Build the synthetic IR materialising the Placeholder Settings items
+ * for the recipe set — the hybrid placeholder model's emission seam.
+ *
+ * Collects every recipe-defined placeholder key:
+ *   - standalone `PlaceholderRecipe` (key + metadata + allowedComponents)
+ *   - inline `ComponentTemplateRecipe.placeholders` (key + allowedComponents)
+ *
+ * A `folder` (on either form) nests the item under
+ * `<placeholderSettingsRoot>/<folder>/<name>` — each path segment is a
+ * `CreateOnly` grouping folder conforming to the SXA `Placeholder
+ * Settings Folder` template (deduped across the set), so it inherits
+ * that template's Insert Options.
+ *
+ * For each unique key it emits:
+ *   1. `CreateItem` (CreateOnly) for the Placeholder Settings item under
+ *      `placeholderSettingsRoot` (or its `folder` subtree), carrying the
+ *      `Placeholder Key` field.
+ *   2. `SetField(Allowed Controls)` — a `ref-recipe-list` of rendering
+ *      refKeys, the UNION of slot-side `allowedComponents` and every
+ *      component naming the key in `placedIn`. One aggregated write per
+ *      key (full-replace is safe — scai owns these items), `tolerateMissing`
+ *      so an aborted sibling rendering IR doesn't fail the whole write.
+ *
+ * `placedIn` keys with no recipe declaration are NOT materialised here —
+ * those are pre-existing tenant placeholders, resolved post-IR by
+ * `applyPlaceholderAllowControls`.
+ *
+ * Returns null when the set declares no placeholders. Throws
+ * INPUT_INVALID when it declares placeholders but `placeholderSettingsRoot`
+ * is unconfigured.
+ */
+const buildPlaceholderSettingsAggregate = (recipes, context, site) => {
+    const byKey = new Map();
+    const ensure = (key) => {
+        let decl = byKey.get(key);
+        if (!decl) {
+            decl = { key, name: placeholderItemName(key), displayName: key, allowed: new Set() };
+            byKey.set(key, decl);
+        }
+        return decl;
+    };
+    for (const recipe of recipes) {
+        if (recipe.kind === "placeholder") {
+            const decl = ensure(recipe.key);
+            decl.name = recipe.name;
+            decl.displayName = recipe.displayName;
+            if (recipe.icon)
+                decl.icon = recipe.icon;
+            if (recipe.folder)
+                decl.folder = recipe.folder;
+            for (const handle of recipe.allowedComponents ?? [])
+                decl.allowed.add(handle);
+        }
+        else if (recipe.kind === "component-template") {
+            for (const slot of recipe.placeholders ?? []) {
+                const decl = ensure(slot.key);
+                // Inline displayName / folder only fill in when nothing better
+                // is set (a PlaceholderRecipe for the same key wins).
+                if (slot.displayName && decl.displayName === decl.key) {
+                    decl.displayName = slot.displayName;
+                }
+                if (slot.folder && decl.folder === undefined)
+                    decl.folder = slot.folder;
+                for (const handle of slot.allowedComponents ?? [])
+                    decl.allowed.add(handle);
+            }
+        }
+    }
+    if (byKey.size === 0)
+        return null;
+    if (!context.placeholderSettingsRoot) {
+        throw (0, errors_1.createScaiError)("Recipe set declares placeholders (PlaceholderRecipe or inline component placeholders) but no placeholderSettingsRoot is configured.", "INPUT_INVALID", {
+            hint: "Set `placeholderSettingsRoot` on the active envProfile in sitecoreai.cli.json — e.g. `/sitecore/content/<site>/Presentation/Placeholder Settings`.",
+        });
+    }
+    // Component-side allow pushes: a `placedIn` entry naming a
+    // recipe-defined key contributes that component to the key's
+    // whitelist. `placedIn` keys with no declaration are skipped (left
+    // to the runtime placeholder-allow task).
+    for (const recipe of recipes) {
+        if (recipe.kind !== "component-template")
+            continue;
+        for (const key of recipe.placedIn ?? []) {
+            byKey.get(key)?.allowed.add(recipe.handle);
+        }
+    }
+    const root = context.placeholderSettingsRoot;
+    const policy = (0, policy_1.defaultPolicyForRecipe)("placeholder");
+    const operations = [];
+    // Materialise a placeholder `folder` path, emitting one CreateOnly
+    // grouping folder per segment (deduped across the aggregate). Each
+    // folder conforms to the SXA `Placeholder Settings Folder` template,
+    // so it inherits that template's Insert Options whitelist. Returns the
+    // parent ref + path the leaf placeholder item lands under.
+    const emittedFolders = new Set();
+    const resolveFolderParent = (folder) => {
+        const segments = (folder ?? "")
+            .split("/")
+            .map((segment) => segment.trim())
+            .filter(Boolean);
+        let parentPath = root;
+        let parentRef = { kind: "ref-path", value: root };
+        let cumulative = "";
+        for (const segment of segments) {
+            cumulative = cumulative ? `${cumulative}/${segment}` : segment;
+            const folderRefKey = (0, guids_1.placeholderSettingsFolderId)(site, cumulative);
+            const folderPath = (0, shared_1.joinPath)(parentPath, segment);
+            if (!emittedFolders.has(folderRefKey)) {
+                emittedFolders.add(folderRefKey);
+                operations.push({
+                    op: "CreateItem",
+                    policy: "CreateOnly",
+                    label: `placeholder-settings-folder:${site}:${cumulative}`,
+                    id: folderRefKey,
+                    path: folderPath,
+                    parent: parentRef,
+                    templateOf: sitecore_templates_1.PLACEHOLDER_SETTINGS_FOLDER_TEMPLATE_ID,
+                    name: segment,
+                    // No fields — the folder inherits its icon and Insert Options
+                    // from the Placeholder Settings Folder template.
+                    fields: [],
+                });
+            }
+            parentPath = folderPath;
+            parentRef = { kind: "ref-recipe", refKey: folderRefKey };
+        }
+        return { parent: parentRef, basePath: parentPath };
+    };
+    for (const key of [...byKey.keys()].sort((a, b) => a.localeCompare(b))) {
+        const decl = byKey.get(key);
+        const refKey = (0, guids_1.placeholderSettingsId)(site, key);
+        const { parent, basePath } = resolveFolderParent(decl.folder);
+        operations.push({
+            op: "CreateItem",
+            policy: "CreateOnly",
+            label: `placeholder-settings:${site}:${key}`,
+            id: refKey,
+            path: (0, shared_1.joinPath)(basePath, decl.name),
+            parent,
+            templateOf: sitecore_templates_1.PLACEHOLDER_TEMPLATE_ID,
+            name: decl.name,
+            fields: [
+                (0, shared_1.sharedField)(sitecore_templates_1.PLACEHOLDER_FIELDS.PLACEHOLDER_KEY, { kind: "string", value: decl.key }),
+                ...(decl.icon
+                    ? [(0, shared_1.sharedField)(sitecore_templates_1.SYSTEM_FIELDS.ICON, { kind: "string", value: decl.icon })]
+                    : []),
+                (0, shared_1.versionedField)(sitecore_templates_1.SYSTEM_FIELDS.DISPLAY_NAME, { kind: "string", value: decl.displayName }),
+            ],
+        });
+        const sortedHandles = [...decl.allowed].sort((a, b) => a.localeCompare(b));
+        operations.push({
+            op: "SetField",
+            policy,
+            label: `placeholder-allowed-controls:${site}:${key}`,
+            itemRefKey: refKey,
+            fieldId: sitecore_templates_1.PLACEHOLDER_FIELDS.ALLOWED_CONTROLS,
+            value: {
+                kind: "ref-recipe-list",
+                refKeys: sortedHandles.map((handle) => (0, guids_1.renderingId)(site, handle)),
+                tolerateMissing: true,
+            },
+        });
+    }
+    return operations_1.OperationIrSchema.parse({
+        schemaVersion: "1",
+        recipeHandle: exports.PLACEHOLDER_SETTINGS_AGGREGATE_HANDLE,
+        operations,
+    });
+};
 /**
  * Compile a coherent set of recipes to a list of Operation IRs.
  *
@@ -599,11 +847,20 @@ function compileRecipeSet(recipes, context) {
             enumsByHandle.set(recipe.handle, recipe);
         }
     }
+    // Cross-recipe component map — `compilePageRecipe` uses it to resolve
+    // a scoped placement's component to its datasource template.
+    const componentsByHandle = new Map();
+    for (const recipe of recipes) {
+        if (recipe.kind === "component-template") {
+            componentsByHandle.set(recipe.handle, recipe);
+        }
+    }
     const perRecipeContext = {
         ...context,
         ...(sharedSubfolders.size > 0 ? { sharedSubfolders } : {}),
         ...(sectionsByHandle.size > 0 ? { sectionsByHandle } : {}),
         ...(enumsByHandle.size > 0 ? { enumsByHandle } : {}),
+        ...(componentsByHandle.size > 0 ? { componentsByHandle } : {}),
     };
     // Process section recipes FIRST so their rich-fields folder ops seed
     // `emittedFolders` sentinels before any component recipe's `ensure*`
@@ -627,8 +884,11 @@ function compileRecipeSet(recipes, context) {
             case "content-template":
                 ir = (0, content_template_1.compileContentTemplateRecipe)(recipe, perRecipeContext, emittedFolders);
                 break;
-            case "parameters-template":
-                ir = (0, parameters_template_1.compileParametersTemplateRecipe)(recipe, perRecipeContext, emittedFolders);
+            case "page-template":
+                ir = (0, page_template_1.compilePageTemplateRecipe)(recipe, perRecipeContext, emittedFolders);
+                break;
+            case "design-parameters-template":
+                ir = (0, design_parameters_template_1.compileDesignParametersTemplateRecipe)(recipe, perRecipeContext, emittedFolders);
                 break;
             case "enumeration":
                 ir = (0, enumeration_1.compileEnumerationRecipe)(recipe, perRecipeContext, emittedFolders);
@@ -638,9 +898,17 @@ function compileRecipeSet(recipes, context) {
         }
         irByHandle.set(recipe.handle, ir);
     }
-    // Preserve INPUT order for IR output — section-first ordering was a
-    // compile-time emission concern only, not a wire-order requirement.
-    const irs = recipes.map((r) => irByHandle.get(r.handle));
+    // Order per-recipe IRs by cross-recipe dependency rank so a referencing
+    // recipe is always applied AFTER the definitions it points at — a page
+    // after its page template, a page design after its partials, a site
+    // after its site template. On a fresh push the executor resolves a
+    // cross-recipe `templateOf` / ref-recipe only once the defining
+    // recipe's IR has run; input (file-glob) order doesn't guarantee that
+    // (`home@1` sorts before `page@1`). The sort is STABLE — input order
+    // is preserved within a rank, so intra-rank emission order (section
+    // folders, etc.) is untouched.
+    const ranked = [...recipes].sort((a, b) => RECIPE_APPLY_RANK[a.kind] - RECIPE_APPLY_RANK[b.kind]);
+    const irs = ranked.map((r) => irByHandle.get(r.handle));
     const setSite = (0, shared_1.siteOf)(context);
     const entries = [];
     for (const recipe of recipes) {
@@ -709,6 +977,14 @@ function compileRecipeSet(recipes, context) {
     if (enumerationsRoot) {
         irs.push(enumerationsRoot);
     }
+    // Placeholder Settings aggregate — one CreateItem + Allowed Controls
+    // SetField per unique placeholder key (standalone PlaceholderRecipe +
+    // inline component placeholders). Emitted last so per-recipe rendering
+    // CreateItem ops have run before its ref-recipe-list resolves.
+    const placeholderSettings = buildPlaceholderSettingsAggregate(recipes, context, setSiteForShared);
+    if (placeholderSettings) {
+        irs.push(placeholderSettings);
+    }
     return irs;
 }
 /** Front-door dispatcher — accepts any registered recipe kind. */
@@ -723,8 +999,14 @@ function compileRecipe(input, context) {
             return (0, content_template_1.compileContentTemplateRecipe)(recipe, context);
         case "content-item":
             return (0, content_item_1.compileContentItemRecipe)(recipe, context);
-        case "parameters-template":
-            return (0, parameters_template_1.compileParametersTemplateRecipe)(recipe, context);
+        case "page-template":
+            return (0, page_template_1.compilePageTemplateRecipe)(recipe, context);
+        case "page":
+            return (0, page_1.compilePageRecipe)(recipe, context);
+        case "placeholder":
+            return (0, placeholder_1.compilePlaceholderRecipe)(recipe, context);
+        case "design-parameters-template":
+            return (0, design_parameters_template_1.compileDesignParametersTemplateRecipe)(recipe, context);
         case "section-definition":
             return (0, section_definition_1.compileSectionDefinitionRecipe)(recipe, context);
         case "partial-design":
@@ -737,5 +1019,9 @@ function compileRecipe(input, context) {
             return (0, site_1.compileSiteRecipe)(recipe, context);
         case "enumeration":
             return (0, enumeration_1.compileEnumerationRecipe)(recipe, context);
+        case "workflow":
+            return (0, workflow_1.compileWorkflowRecipe)(recipe, context);
+        case "webhook-authorization":
+            return (0, webhook_authorization_1.compileWebhookAuthorizationRecipe)(recipe, context);
     }
 }

package/dist/recipe/ensure-marker-field.d.ts

@@ -0,0 +1,25 @@
+import type { AuthoringApiClient } from "./api/client";
+/** Name of the scai-owned Template Section the marker field lives under. */
+export declare const SCAI_SECTION_NAME = "Scai";
+/** Outcome of {@link ensureMarkerField}. */
+export interface EnsureMarkerFieldResult {
+    /** `"created"` when this call added the field; `"already-present"` when it was found. */
+    status: "created" | "already-present";
+    /** itemId of the `Scai Handle` Template Field item. */
+    fieldItemId: string;
+    /** itemId of the Template Section the field lives under. */
+    sectionItemId: string;
+}
+/**
+ * Ensure the `Scai Handle` marker field exists on the Standard Template.
+ *
+ * Idempotent: scans every Template Section directly under the Standard
+ * Template for an existing `Scai Handle` field and returns it untouched when
+ * found (even if a prior bootstrap placed it under a differently-named
+ * section). Otherwise it ensures the `Scai` section and creates the field.
+ *
+ * Throws `INPUT_INVALID` when the Standard Template can't be resolved — the
+ * environment isn't pointed at an XM Cloud authoring endpoint, or the
+ * authoring database lacks the built-in template.
+ */
+export declare const ensureMarkerField: (client: AuthoringApiClient) => Promise<EnsureMarkerFieldResult>;

package/dist/recipe/ensure-marker-field.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureMarkerField = exports.SCAI_SECTION_NAME = void 0;
+/**
+ * Bootstrap the `Scai Handle` marker field — the one-time, per-environment
+ * setup that makes recipe identity work (see `marker.ts` and
+ * docs/recipe-sync-architecture.md, "Recipe identity — the marker field").
+ *
+ * `injectHandleMarker` (push) and the planner's marker-match both assume the
+ * `Scai Handle` field *exists* on the tenant. It does not, on a fresh
+ * environment. This module adds it: a single shared string field on the
+ * Sitecore **Standard Template**, so every item — template, section, field,
+ * enumeration, content — inherits it uniformly.
+ *
+ * The field lives under a scai-owned `Scai` section (a direct-child Template
+ * Section of the Standard Template) parked at a high sort order, so it sits
+ * out of an author's way: it is scai-managed metadata, not authored content.
+ *
+ * `ensureMarkerField` is idempotent — running it on an environment that
+ * already has the field is a no-op read. The bootstrap is also expressible
+ * as a content-template recipe; this imperative form is what `scai`'s setup
+ * path calls before the first recipe push.
+ *
+ * Caveat (verify on a live XM Cloud tenant): adding a field to the built-in
+ * Standard Template, and the field-visibility setting that keeps it out of
+ * the content editor — both are flagged unverified in the architecture doc.
+ */
+const errors_1 = require("../shared/errors");
+const sitecore_templates_1 = require("./ir/sitecore-templates");
+const field_types_1 = require("./schema/field-types");
+const marker_1 = require("./marker");
+/** Name of the scai-owned Template Section the marker field lives under. */
+exports.SCAI_SECTION_NAME = "Scai";
+/**
+ * Sort order for the `Scai` section and the `Scai Handle` field. A high
+ * value parks both at the bottom of the content editor — the marker is
+ * scai-managed metadata, not something an author should reach for.
+ */
+const SCAI_MARKER_SORT_ORDER = 9999;
+/**
+ * Compare two Sitecore GUIDs ignoring case, curly braces, AND hyphens.
+ * The Authoring API returns GUIDs hyphen-less (`1930bbeb7805471a…`) while
+ * the built-in constants are hyphenated — a brace/case-only compare misses.
+ */
+const sameGuid = (a, b) => {
+    const norm = (g) => g.trim().toLowerCase().replace(/[{}-]/g, "");
+    return norm(a) === norm(b);
+};
+/**
+ * The field definition written onto the `Scai Handle` Template Field item:
+ * a shared Single-Line Text field, high sort order, with `Title` /
+ * `__Display name` set so the CMS labels it sensibly. `Shared = "1"` because
+ * the marker is per-item identity — it must not vary by language or version.
+ */
+const markerFieldDefinition = () => [
+    {
+        fieldId: sitecore_templates_1.TEMPLATE_FIELD_FIELDS.TYPE,
+        value: { kind: "string", value: (0, field_types_1.sitecoreFieldTypeLabel)("single-line-text") },
+    },
+    {
+        fieldId: sitecore_templates_1.SYSTEM_FIELDS.SORT_ORDER,
+        value: { kind: "number", value: SCAI_MARKER_SORT_ORDER },
+    },
+    {
+        fieldId: sitecore_templates_1.TEMPLATE_FIELD_FIELDS.SHARED,
+        value: { kind: "string", value: "1" },
+    },
+    {
+        fieldId: sitecore_templates_1.TEMPLATE_FIELD_FIELDS.TITLE,
+        language: sitecore_templates_1.DEFAULT_LANGUAGE,
+        version: sitecore_templates_1.DEFAULT_VERSION,
+        value: { kind: "string", value: marker_1.SCAI_HANDLE_FIELD_NAME },
+    },
+    {
+        fieldId: sitecore_templates_1.SYSTEM_FIELDS.DISPLAY_NAME,
+        language: sitecore_templates_1.DEFAULT_LANGUAGE,
+        version: sitecore_templates_1.DEFAULT_VERSION,
+        value: { kind: "string", value: marker_1.SCAI_HANDLE_FIELD_NAME },
+    },
+];
+/**
+ * Ensure the `Scai Handle` marker field exists on the Standard Template.
+ *
+ * Idempotent: scans every Template Section directly under the Standard
+ * Template for an existing `Scai Handle` field and returns it untouched when
+ * found (even if a prior bootstrap placed it under a differently-named
+ * section). Otherwise it ensures the `Scai` section and creates the field.
+ *
+ * Throws `INPUT_INVALID` when the Standard Template can't be resolved — the
+ * environment isn't pointed at an XM Cloud authoring endpoint, or the
+ * authoring database lacks the built-in template.
+ */
+const ensureMarkerField = async (client) => {
+    const standardTemplate = await client.getItem({ itemId: sitecore_templates_1.STANDARD_TEMPLATE_ID });
+    if (!standardTemplate) {
+        throw (0, errors_1.createScaiError)("Could not resolve the Sitecore Standard Template — the `Scai Handle` marker field cannot be bootstrapped.", "INPUT_INVALID", {
+            hint: `Expected the built-in Standard Template (${sitecore_templates_1.STANDARD_TEMPLATE_ID}) in the authoring 'master' database. Verify the environment points at an XM Cloud authoring endpoint.`,
+        });
+    }
+    // Direct-child Template Sections of the Standard Template. A
+    // previously-bootstrapped marker field lives under one of them.
+    const sections = (await client.getChildren({ itemId: standardTemplate.itemId })).filter((child) => sameGuid(child.templateId, sitecore_templates_1.SITECORE_TEMPLATES.TEMPLATE_SECTION));
+    for (const section of sections) {
+        const fields = await client.getChildren({ itemId: section.itemId });
+        const existing = fields.find((f) => sameGuid(f.templateId, sitecore_templates_1.SITECORE_TEMPLATES.TEMPLATE_FIELD) &&
+            f.name.toLowerCase() === marker_1.SCAI_HANDLE_FIELD_NAME.toLowerCase());
+        if (existing) {
+            return {
+                status: "already-present",
+                fieldItemId: existing.itemId,
+                sectionItemId: section.itemId,
+            };
+        }
+    }
+    // Not present — reuse the `Scai` section if it already exists, else create
+    // it, then create the field under it.
+    const existingScaiSection = sections.find((s) => s.name.toLowerCase() === exports.SCAI_SECTION_NAME.toLowerCase());
+    const sectionItemId = existingScaiSection?.itemId ??
+        (await client.createItem({
+            parent: standardTemplate.itemId,
+            templateId: sitecore_templates_1.SITECORE_TEMPLATES.TEMPLATE_SECTION,
+            name: exports.SCAI_SECTION_NAME,
+            fields: [
+                {
+                    fieldId: sitecore_templates_1.SYSTEM_FIELDS.SORT_ORDER,
+                    value: { kind: "number", value: SCAI_MARKER_SORT_ORDER },
+                },
+            ],
+            idempotencyCheck: true,
+        })).itemId;
+    const field = await client.createItem({
+        parent: sectionItemId,
+        templateId: sitecore_templates_1.SITECORE_TEMPLATES.TEMPLATE_FIELD,
+        name: marker_1.SCAI_HANDLE_FIELD_NAME,
+        fields: markerFieldDefinition(),
+        idempotencyCheck: true,
+    });
+    return { status: "created", fieldItemId: field.itemId, sectionItemId };
+};
+exports.ensureMarkerField = ensureMarkerField;

package/dist/recipe/execute.d.ts

@@ -3,8 +3,9 @@ import type { SitesApiClient } from "./api/sites-client";
 import type { OperationIr } from "./ir/operations";
 import { type Plan, type PlanEvent, type PlannedAction, type PlanSummary } from "./plan";
 import { type RollbackError, type RollbackEvent, type RollbackResult } from "./rollback";
+import type { RollbackLogger } from "./rollback-log";
 /**
- * `scai recipe push` and `scai recipe plan` share the same per-op
+ * `scai provision recipe push` and `scai provision recipe plan` share the same per-op
  * read-then-diff loop. Apply mode interleaves plan-and-apply: each op's
  * plan sees the cascading effect of earlier ops' applies — required for
  * idempotency.
@@ -71,6 +72,15 @@ export interface ExecutionResult {
 export interface ExecuteOptions {
     mode: ExecutionMode;
     emit?: (event: ExecutionEvent) => void;
+    /**
+     * Cooperative cancellation. When `signal.aborted` becomes true, the
+     * executor stops *between* operations, runs the same rollback path
+     * as a failed op, and returns an `ExecutionResult` with
+     * `aborted: true` and a reason indicating client-initiated cancel.
+     * In-flight requests are not interrupted — finishing the current op
+     * keeps the rollback inventory accurate.
+     */
+    signal?: AbortSignal;
     /**
      * Cross-recipe ref pre-seed: `refKey → expectedPath` for items
      * produced by OTHER recipes in the same workspace. The executor
@@ -114,6 +124,13 @@ export interface ExecuteOptions {
      * indicates a CreateItem is needed.
      */
     pathSnapshotCache?: Map<string, RemoteItem | null>;
+    /**
+     * On-disk rollback audit log. Threaded through to `rollback()` so each
+     * compensating-op outcome is captured, and to `executeIr` so the
+     * per-recipe summary line is written when a push aborts. Optional —
+     * when absent, the executor still rolls back in-memory but writes
+     * nothing to disk.
+     */
+    rollbackLog?: RollbackLogger;
 }
 export declare const executeIr: (ir: OperationIr, client: AuthoringApiClient, options: ExecuteOptions) => Promise<ExecutionResult>;
-//# sourceMappingURL=execute.d.ts.map