@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/recipe/index.js

@@ -11,36 +11,35 @@
  * Stability contract: the surface in this file is the public contract.
  * Anything not exported here is internal and may move between scai
  * versions without notice.
+ *
+ * The recipe composition kinds (`ContentItem`, `PageDesign`, `PartialDesign`,
+ * `SiteRecipe`, `SiteTemplate`) are NOT part of the 0.1.0 stability promise
+ * and live on the separate `./recipe/unstable` entry (`src/recipe/unstable.ts`).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NAMESPACE_ROOT = exports.NAMESPACE_RENDERING = exports.NAMESPACE_PROJECT = exports.NAMESPACE_PARTIAL_DESIGN = exports.NAMESPACE_PAGE_DESIGN = exports.NAMESPACE_CONTENT_ITEM = exports.encodeTemplatesMapping = exports.emitLayoutXml = exports.TEMPLATES_MAPPING_AGGREGATE_HANDLE = exports.compileSiteTemplateRecipe = exports.compileSiteRecipe = exports.compileSectionDefinitionRecipe = exports.compileRecipeSet = exports.compileRecipe = exports.compilePartialDesignRecipe = exports.compileParametersTemplateRecipe = exports.compilePageDesignRecipe = exports.compileContentTemplateRecipe = exports.compileContentItemRecipe = exports.compileComponentTemplateRecipe = exports.sitecoreFieldTypeLabel = exports.defaultSitecoreFieldType = exports.SitecoreFieldTypeSchema = exports.SITECORE_FIELD_TYPES = exports.FieldShapeSchema = exports.FIELD_SHAPES = exports.SitecoreFieldAugmentSchema = exports.SiteTemplateTaxonomyEntrySchema = exports.SiteTemplateRecipeSchema = exports.SiteTemplateDictionaryEntrySchema = exports.SiteRecipeSchema = exports.SiteGroupingSchema = exports.SectionDefinitionRecipeSchema = exports.RenderingVariantDefinitionSchema = exports.RenderingDatasourceLocationSchema = exports.RecipeDatasourceSchema = exports.RecipeSchema = exports.RecipeMetaSchema = exports.PlaceholderDefinitionSchema = exports.PartialDesignRecipeSchema = exports.ParametersTemplateRecipeSchema = exports.ParamDefinitionSchema = exports.PageDesignRecipeSchema = exports.LayoutSchema = exports.FieldDefinitionSchema = exports.ContentTemplateRecipeSchema = exports.ContentItemRecipeSchema = exports.ContentFieldValueSchema = exports.ComponentTemplateRecipeSchema = exports.ComponentPlacementSchema = void 0;
-exports.STANDARD_TEMPLATE_ID = exports.SITECORE_TEMPLATES = exports.SITE_TEMPLATE_FIELDS = exports.SITE_FIELDS = exports.SECTION_DEFINITION_FIELDS = exports.RENDERING_FIELDS = exports.LAYOUT_FIELDS = exports.DEFAULT_VERSION = exports.DEFAULT_LANGUAGE = exports.DEFAULT_ICON = exports.DEFAULT_DEVICE_ID = exports.COMPOSITION_FIELDS = exports.SetStandardValuesOpSchema = exports.SetFieldOpSchema = exports.SetBaseTemplatesOpSchema = exports.RefValueSchema = exports.PushPolicySchema = exports.OperationSchema = exports.OperationIrSchema = exports.FieldValueSchema = exports.CreateItemOpSchema = exports.AppendToMultiListOpSchema = exports.variantsFolderId = exports.variantId = exports.templateId = exports.standardValuesId = exports.siteDataFolderId = exports.siteBranchId = exports.sectionId = exports.sectionFolderId = exports.sectionDefinitionId = exports.renderingsSectionFolderId = exports.renderingId = exports.presentationParametersBucketId = exports.partialDesignId = exports.paramsTemplateId = exports.paramsSectionId = exports.paramsFieldId = exports.pageDesignId = exports.fieldId = exports.datasourceId = exports.contentModelsGroupFolderId = exports.contentItemId = exports.componentFoldersBucketId = exports.componentFolderTemplateId = exports.componentFolderStandardValuesId = exports.PAGE_DESIGNS_ROOT_REF_KEY = exports.NAMESPACE_TEMPLATE = exports.NAMESPACE_SITE_BRANCH = exports.NAMESPACE_SECTION_DEFINITION = void 0;
-exports.validateRecipeSetOrThrow = exports.validateRecipeSet = exports.isValid = exports.formatValidationErrors = exports.purposeForRecipe = exports.policyForOp = exports.policyFor = exports.defaultPolicyForRecipe = exports.sourceFieldsNeedHandleResolution = exports.renderSourceFields = exports.renderRefValue = exports.executeIr = exports.buildPlan = exports.TEMPLATE_FIELD_FIELDS = exports.SYSTEM_FIELDS = void 0;
+exports.PAGE_DESIGNS_ROOT_REF_KEY = exports.NAMESPACE_TEMPLATE = exports.NAMESPACE_SITE_BRANCH = exports.NAMESPACE_SECTION_DEFINITION = exports.NAMESPACE_ROOT = exports.NAMESPACE_RENDERING = exports.NAMESPACE_PROJECT = exports.NAMESPACE_PLACEHOLDER = exports.NAMESPACE_PARTIAL_DESIGN = exports.NAMESPACE_PAGE_DESIGN = exports.NAMESPACE_PAGE = exports.NAMESPACE_CONTENT_ITEM = exports.encodeTemplatesMapping = exports.emitLayoutXml = exports.TEMPLATES_MAPPING_AGGREGATE_HANDLE = exports.PLACEHOLDER_SETTINGS_AGGREGATE_HANDLE = exports.compileSectionDefinitionRecipe = exports.compileRecipeSet = exports.compileRecipe = exports.compileDesignParametersTemplateRecipe = exports.compilePlaceholderRecipe = exports.compilePageRecipe = exports.compilePageTemplateRecipe = exports.compileContentTemplateRecipe = exports.compileComponentTemplateRecipe = exports.sitecoreFieldTypeLabel = exports.defaultSitecoreFieldType = exports.SitecoreFieldTypeSchema = exports.SITECORE_FIELD_TYPES = exports.FieldShapeSchema = exports.FIELD_SHAPES = exports.SitecoreFieldAugmentSchema = exports.SectionDefinitionRecipeSchema = exports.RenderingVariantDefinitionSchema = exports.RenderingDatasourceLocationSchema = exports.RecipeDatasourceSchema = exports.RecipeSchema = exports.RecipeMetaSchema = exports.PlaceholderRecipeSchema = exports.PlaceholderDefinitionSchema = exports.DesignParametersTemplateRecipeSchema = exports.DesignParameterSchema = exports.PageTemplateRecipeSchema = exports.PageRecipeSchema = exports.LayoutSchema = exports.FieldDefinitionSchema = exports.ContentTemplateRecipeSchema = exports.ContentFieldValueSchema = exports.ComponentTemplateRecipeSchema = exports.ComponentPlacementSchema = void 0;
+exports.SYSTEM_FIELDS = exports.STANDARD_TEMPLATE_ID = exports.SITECORE_TEMPLATES = exports.SITE_TEMPLATE_FIELDS = exports.SITE_FIELDS = exports.SECTION_DEFINITION_FIELDS = exports.RENDERING_FIELDS = exports.LAYOUT_FIELDS = exports.DEFAULT_VERSION = exports.DEFAULT_LANGUAGE = exports.DEFAULT_ICON = exports.DEFAULT_DEVICE_ID = exports.COMPOSITION_FIELDS = exports.SetStandardValuesOpSchema = exports.SetFieldOpSchema = exports.SetBaseTemplatesOpSchema = exports.RefValueSchema = exports.PushPolicySchema = exports.OperationSchema = exports.OperationIrSchema = exports.FieldValueSchema = exports.CreateItemOpSchema = exports.AppendToMultiListOpSchema = exports.variantsFolderId = exports.variantId = exports.templateId = exports.standardValuesId = exports.siteDataFolderId = exports.siteBranchId = exports.sectionId = exports.sectionFolderId = exports.sectionDefinitionId = exports.renderingsSectionFolderId = exports.renderingId = exports.presentationDesignParametersBucketId = exports.partialDesignId = exports.designParametersTemplateId = exports.designParametersSectionId = exports.designParameterFieldId = exports.placeholderSettingsId = exports.pageTemplatesGroupFolderId = exports.pageItemId = exports.pageDesignId = exports.fieldId = exports.datasourceId = exports.contentModelsGroupFolderId = exports.contentItemId = exports.componentFoldersBucketId = exports.componentFolderTemplateId = exports.componentFolderStandardValuesId = void 0;
+exports.validateRecipeSetOrThrow = exports.validateRecipeSet = exports.isValid = exports.formatValidationErrors = exports.purposeForRecipe = exports.policyForOp = exports.policyFor = exports.defaultPolicyForRecipe = exports.sourceFieldsNeedHandleResolution = exports.renderSourceFields = exports.renderRefValue = exports.createSitesApiClient = exports.runAuthoringGraphQL = exports.createAuthoringClient = exports.executeIr = exports.buildPlan = exports.TEMPLATE_FIELD_FIELDS = void 0;
 // Recipe author surface ---------------------------------------------------
 var recipe_1 = require("./schema/recipe");
 Object.defineProperty(exports, "ComponentPlacementSchema", { enumerable: true, get: function () { return recipe_1.ComponentPlacementSchema; } });
 Object.defineProperty(exports, "ComponentTemplateRecipeSchema", { enumerable: true, get: function () { return recipe_1.ComponentTemplateRecipeSchema; } });
 Object.defineProperty(exports, "ContentFieldValueSchema", { enumerable: true, get: function () { return recipe_1.ContentFieldValueSchema; } });
-Object.defineProperty(exports, "ContentItemRecipeSchema", { enumerable: true, get: function () { return recipe_1.ContentItemRecipeSchema; } });
 Object.defineProperty(exports, "ContentTemplateRecipeSchema", { enumerable: true, get: function () { return recipe_1.ContentTemplateRecipeSchema; } });
 Object.defineProperty(exports, "FieldDefinitionSchema", { enumerable: true, get: function () { return recipe_1.FieldDefinitionSchema; } });
 Object.defineProperty(exports, "LayoutSchema", { enumerable: true, get: function () { return recipe_1.LayoutSchema; } });
-Object.defineProperty(exports, "PageDesignRecipeSchema", { enumerable: true, get: function () { return recipe_1.PageDesignRecipeSchema; } });
-Object.defineProperty(exports, "ParamDefinitionSchema", { enumerable: true, get: function () { return recipe_1.ParamDefinitionSchema; } });
-Object.defineProperty(exports, "ParametersTemplateRecipeSchema", { enumerable: true, get: function () { return recipe_1.ParametersTemplateRecipeSchema; } });
-Object.defineProperty(exports, "PartialDesignRecipeSchema", { enumerable: true, get: function () { return recipe_1.PartialDesignRecipeSchema; } });
+Object.defineProperty(exports, "PageRecipeSchema", { enumerable: true, get: function () { return recipe_1.PageRecipeSchema; } });
+Object.defineProperty(exports, "PageTemplateRecipeSchema", { enumerable: true, get: function () { return recipe_1.PageTemplateRecipeSchema; } });
+Object.defineProperty(exports, "DesignParameterSchema", { enumerable: true, get: function () { return recipe_1.DesignParameterSchema; } });
+Object.defineProperty(exports, "DesignParametersTemplateRecipeSchema", { enumerable: true, get: function () { return recipe_1.DesignParametersTemplateRecipeSchema; } });
 Object.defineProperty(exports, "PlaceholderDefinitionSchema", { enumerable: true, get: function () { return recipe_1.PlaceholderDefinitionSchema; } });
+Object.defineProperty(exports, "PlaceholderRecipeSchema", { enumerable: true, get: function () { return recipe_1.PlaceholderRecipeSchema; } });
 Object.defineProperty(exports, "RecipeMetaSchema", { enumerable: true, get: function () { return recipe_1.RecipeMetaSchema; } });
 Object.defineProperty(exports, "RecipeSchema", { enumerable: true, get: function () { return recipe_1.RecipeSchema; } });
 Object.defineProperty(exports, "RecipeDatasourceSchema", { enumerable: true, get: function () { return recipe_1.RecipeDatasourceSchema; } });
 Object.defineProperty(exports, "RenderingDatasourceLocationSchema", { enumerable: true, get: function () { return recipe_1.RenderingDatasourceLocationSchema; } });
 Object.defineProperty(exports, "RenderingVariantDefinitionSchema", { enumerable: true, get: function () { return recipe_1.RenderingVariantDefinitionSchema; } });
 Object.defineProperty(exports, "SectionDefinitionRecipeSchema", { enumerable: true, get: function () { return recipe_1.SectionDefinitionRecipeSchema; } });
-Object.defineProperty(exports, "SiteGroupingSchema", { enumerable: true, get: function () { return recipe_1.SiteGroupingSchema; } });
-Object.defineProperty(exports, "SiteRecipeSchema", { enumerable: true, get: function () { return recipe_1.SiteRecipeSchema; } });
-Object.defineProperty(exports, "SiteTemplateDictionaryEntrySchema", { enumerable: true, get: function () { return recipe_1.SiteTemplateDictionaryEntrySchema; } });
-Object.defineProperty(exports, "SiteTemplateRecipeSchema", { enumerable: true, get: function () { return recipe_1.SiteTemplateRecipeSchema; } });
-Object.defineProperty(exports, "SiteTemplateTaxonomyEntrySchema", { enumerable: true, get: function () { return recipe_1.SiteTemplateTaxonomyEntrySchema; } });
 Object.defineProperty(exports, "SitecoreFieldAugmentSchema", { enumerable: true, get: function () { return recipe_1.SitecoreFieldAugmentSchema; } });
 var field_types_1 = require("./schema/field-types");
 Object.defineProperty(exports, "FIELD_SHAPES", { enumerable: true, get: function () { return field_types_1.FIELD_SHAPES; } });
@@ -50,18 +49,20 @@ Object.defineProperty(exports, "SitecoreFieldTypeSchema", { enumerable: true, ge
 Object.defineProperty(exports, "defaultSitecoreFieldType", { enumerable: true, get: function () { return field_types_1.defaultSitecoreFieldType; } });
 Object.defineProperty(exports, "sitecoreFieldTypeLabel", { enumerable: true, get: function () { return field_types_1.sitecoreFieldTypeLabel; } });
 // Compiler ----------------------------------------------------------------
+// `compileRecipe` / `compileRecipeSet` dispatch across every kind including
+// the composition kinds; the kind-specific composition compilers
+// (`compilePageDesignRecipe`, …) live on `./recipe/unstable`.
 var compile_1 = require("./compile");
 Object.defineProperty(exports, "compileComponentTemplateRecipe", { enumerable: true, get: function () { return compile_1.compileComponentTemplateRecipe; } });
-Object.defineProperty(exports, "compileContentItemRecipe", { enumerable: true, get: function () { return compile_1.compileContentItemRecipe; } });
 Object.defineProperty(exports, "compileContentTemplateRecipe", { enumerable: true, get: function () { return compile_1.compileContentTemplateRecipe; } });
-Object.defineProperty(exports, "compilePageDesignRecipe", { enumerable: true, get: function () { return compile_1.compilePageDesignRecipe; } });
-Object.defineProperty(exports, "compileParametersTemplateRecipe", { enumerable: true, get: function () { return compile_1.compileParametersTemplateRecipe; } });
-Object.defineProperty(exports, "compilePartialDesignRecipe", { enumerable: true, get: function () { return compile_1.compilePartialDesignRecipe; } });
+Object.defineProperty(exports, "compilePageTemplateRecipe", { enumerable: true, get: function () { return compile_1.compilePageTemplateRecipe; } });
+Object.defineProperty(exports, "compilePageRecipe", { enumerable: true, get: function () { return compile_1.compilePageRecipe; } });
+Object.defineProperty(exports, "compilePlaceholderRecipe", { enumerable: true, get: function () { return compile_1.compilePlaceholderRecipe; } });
+Object.defineProperty(exports, "compileDesignParametersTemplateRecipe", { enumerable: true, get: function () { return compile_1.compileDesignParametersTemplateRecipe; } });
 Object.defineProperty(exports, "compileRecipe", { enumerable: true, get: function () { return compile_1.compileRecipe; } });
 Object.defineProperty(exports, "compileRecipeSet", { enumerable: true, get: function () { return compile_1.compileRecipeSet; } });
 Object.defineProperty(exports, "compileSectionDefinitionRecipe", { enumerable: true, get: function () { return compile_1.compileSectionDefinitionRecipe; } });
-Object.defineProperty(exports, "compileSiteRecipe", { enumerable: true, get: function () { return compile_1.compileSiteRecipe; } });
-Object.defineProperty(exports, "compileSiteTemplateRecipe", { enumerable: true, get: function () { return compile_1.compileSiteTemplateRecipe; } });
+Object.defineProperty(exports, "PLACEHOLDER_SETTINGS_AGGREGATE_HANDLE", { enumerable: true, get: function () { return compile_1.PLACEHOLDER_SETTINGS_AGGREGATE_HANDLE; } });
 Object.defineProperty(exports, "TEMPLATES_MAPPING_AGGREGATE_HANDLE", { enumerable: true, get: function () { return compile_1.TEMPLATES_MAPPING_AGGREGATE_HANDLE; } });
 var emit_1 = require("./layout/emit");
 Object.defineProperty(exports, "emitLayoutXml", { enumerable: true, get: function () { return emit_1.emitLayoutXml; } });
@@ -70,8 +71,10 @@ Object.defineProperty(exports, "encodeTemplatesMapping", { enumerable: true, get
 // GUID derivation ---------------------------------------------------------
 var guids_1 = require("./guids");
 Object.defineProperty(exports, "NAMESPACE_CONTENT_ITEM", { enumerable: true, get: function () { return guids_1.NAMESPACE_CONTENT_ITEM; } });
+Object.defineProperty(exports, "NAMESPACE_PAGE", { enumerable: true, get: function () { return guids_1.NAMESPACE_PAGE; } });
 Object.defineProperty(exports, "NAMESPACE_PAGE_DESIGN", { enumerable: true, get: function () { return guids_1.NAMESPACE_PAGE_DESIGN; } });
 Object.defineProperty(exports, "NAMESPACE_PARTIAL_DESIGN", { enumerable: true, get: function () { return guids_1.NAMESPACE_PARTIAL_DESIGN; } });
+Object.defineProperty(exports, "NAMESPACE_PLACEHOLDER", { enumerable: true, get: function () { return guids_1.NAMESPACE_PLACEHOLDER; } });
 Object.defineProperty(exports, "NAMESPACE_PROJECT", { enumerable: true, get: function () { return guids_1.NAMESPACE_PROJECT; } });
 Object.defineProperty(exports, "NAMESPACE_RENDERING", { enumerable: true, get: function () { return guids_1.NAMESPACE_RENDERING; } });
 Object.defineProperty(exports, "NAMESPACE_ROOT", { enumerable: true, get: function () { return guids_1.NAMESPACE_ROOT; } });
@@ -87,11 +90,14 @@ Object.defineProperty(exports, "contentModelsGroupFolderId", { enumerable: true,
 Object.defineProperty(exports, "datasourceId", { enumerable: true, get: function () { return guids_1.datasourceId; } });
 Object.defineProperty(exports, "fieldId", { enumerable: true, get: function () { return guids_1.fieldId; } });
 Object.defineProperty(exports, "pageDesignId", { enumerable: true, get: function () { return guids_1.pageDesignId; } });
-Object.defineProperty(exports, "paramsFieldId", { enumerable: true, get: function () { return guids_1.paramsFieldId; } });
-Object.defineProperty(exports, "paramsSectionId", { enumerable: true, get: function () { return guids_1.paramsSectionId; } });
-Object.defineProperty(exports, "paramsTemplateId", { enumerable: true, get: function () { return guids_1.paramsTemplateId; } });
+Object.defineProperty(exports, "pageItemId", { enumerable: true, get: function () { return guids_1.pageItemId; } });
+Object.defineProperty(exports, "pageTemplatesGroupFolderId", { enumerable: true, get: function () { return guids_1.pageTemplatesGroupFolderId; } });
+Object.defineProperty(exports, "placeholderSettingsId", { enumerable: true, get: function () { return guids_1.placeholderSettingsId; } });
+Object.defineProperty(exports, "designParameterFieldId", { enumerable: true, get: function () { return guids_1.designParameterFieldId; } });
+Object.defineProperty(exports, "designParametersSectionId", { enumerable: true, get: function () { return guids_1.designParametersSectionId; } });
+Object.defineProperty(exports, "designParametersTemplateId", { enumerable: true, get: function () { return guids_1.designParametersTemplateId; } });
 Object.defineProperty(exports, "partialDesignId", { enumerable: true, get: function () { return guids_1.partialDesignId; } });
-Object.defineProperty(exports, "presentationParametersBucketId", { enumerable: true, get: function () { return guids_1.presentationParametersBucketId; } });
+Object.defineProperty(exports, "presentationDesignParametersBucketId", { enumerable: true, get: function () { return guids_1.presentationDesignParametersBucketId; } });
 Object.defineProperty(exports, "renderingId", { enumerable: true, get: function () { return guids_1.renderingId; } });
 Object.defineProperty(exports, "renderingsSectionFolderId", { enumerable: true, get: function () { return guids_1.renderingsSectionFolderId; } });
 Object.defineProperty(exports, "sectionDefinitionId", { enumerable: true, get: function () { return guids_1.sectionDefinitionId; } });
@@ -135,6 +141,23 @@ var plan_1 = require("./plan");
 Object.defineProperty(exports, "buildPlan", { enumerable: true, get: function () { return plan_1.buildPlan; } });
 var execute_1 = require("./execute");
 Object.defineProperty(exports, "executeIr", { enumerable: true, get: function () { return execute_1.executeIr; } });
+// Production AuthoringApiClient factory. Library callers use this when
+// they want scai's implementation (path resolution, parent-folder
+// auto-creation, retry-on-throttle for read GETs) without re-implementing
+// the wire-protocol semantics from scratch.
+var authoring_client_1 = require("./api/authoring-client");
+Object.defineProperty(exports, "createAuthoringClient", { enumerable: true, get: function () { return authoring_client_1.createAuthoringClient; } });
+// Authoring GraphQL transport. `runAuthoringGraphQL` is the escape hatch
+// for ad-hoc queries scai's typed clients don't cover; it shares retry +
+// timeout + auth + redaction with `createAuthoringClient`.
+var graphql_1 = require("./api/graphql");
+Object.defineProperty(exports, "runAuthoringGraphQL", { enumerable: true, get: function () { return graphql_1.runAuthoringGraphQL; } });
+// Sites API client seam + factory + types. Parallels the Authoring
+// client pair: the interface is what the recipe planner depends on,
+// `createSitesApiClient` is the production adapter over the Sites HTTP
+// API, and the re-exported types describe the values flowing across.
+var sites_client_1 = require("./api/sites-client");
+Object.defineProperty(exports, "createSitesApiClient", { enumerable: true, get: function () { return sites_client_1.createSitesApiClient; } });
 // Reference encoding (RefValue → canonical Sitecore string) -------------
 var ref_encoding_1 = require("./api/ref-encoding");
 Object.defineProperty(exports, "renderRefValue", { enumerable: true, get: function () { return ref_encoding_1.renderRefValue; } });

package/dist/recipe/io.d.ts

@@ -18,4 +18,3 @@ export declare const loadIr: (filePath: string) => Promise<OperationIr>;
 export declare const writePlan: (filePath: string, plan: Plan) => Promise<void>;
 export declare const defaultIrPath: (recipeHandle: string, baseDir: string) => string;
 export declare const defaultPlanPath: (recipeHandle: string, baseDir: string) => string;
-//# sourceMappingURL=io.d.ts.map

package/dist/recipe/io.js

@@ -9,6 +9,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const errors_1 = require("../shared/errors");
 const recipe_1 = require("./schema/recipe");
 const operations_1 = require("./ir/operations");
+const load_1 = require("./sandbox/load");
 /**
  * Recipe + IR + Plan I/O.
  *
@@ -25,17 +26,17 @@ const readJson = async (filePath) => {
     }
     catch (error) {
         if (error.code === "ENOENT") {
-            throw (0, errors_1.createCliError)(`File not found: ${filePath}`, "INPUT_INVALID", {
+            throw (0, errors_1.createScaiError)(`File not found: ${filePath}`, "INPUT_INVALID", {
                 hint: "Check the path spelling and that the file exists.",
             });
         }
-        throw (0, errors_1.createCliError)(`Failed to read ${filePath}: ${error instanceof Error ? error.message : String(error)}`, "INPUT_INVALID");
+        throw (0, errors_1.createScaiError)(`Failed to read ${filePath}: ${error instanceof Error ? error.message : String(error)}`, "INPUT_INVALID");
     }
     try {
         return JSON.parse(raw);
     }
     catch (error) {
-        throw (0, errors_1.createCliError)(`Invalid JSON in ${filePath}: ${error instanceof Error ? error.message : String(error)}`, "INPUT_INVALID", { hint: "Ensure the file contains a valid JSON document." });
+        throw (0, errors_1.createScaiError)(`Invalid JSON in ${filePath}: ${error instanceof Error ? error.message : String(error)}`, "INPUT_INVALID", { hint: "Ensure the file contains a valid JSON document." });
     }
 };
 const writeJson = async (filePath, value) => {
@@ -60,7 +61,7 @@ const loadRecipe = async (filePath) => {
         : await readJson(filePath);
     const result = recipe_1.RecipeSchema.safeParse(raw);
     if (!result.success) {
-        throw (0, errors_1.createCliError)(`Invalid recipe at ${filePath}.`, "INPUT_INVALID", {
+        throw (0, errors_1.createScaiError)(`Invalid recipe at ${filePath}.`, "INPUT_INVALID", {
             hint: "Ensure the file exports a `ComponentTemplateRecipe` or `ContentTemplateRecipe`.",
             details: result.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`),
         });
@@ -72,7 +73,7 @@ exports.loadRecipe = loadRecipe;
  * Lazily install tsx's CommonJS require hook *once* per process. Earlier
  * versions of this file called `register()` and the matching `unregister`
  * cleanup on every `loadRecipe` call — fine for one-shot CLI runs but
- * wasteful in long-running surfaces like `scai shell` where N recipe
+ * wasteful in long-running surfaces like `scai cli shell` where N recipe
  * loads = N register/unregister cycles. Once installed, the hook stays
  * for the rest of the process lifetime; recipe changes mid-shell-session
  * therefore require an exit (the per-recipe `require.cache` clear below
@@ -89,7 +90,29 @@ const ensureTsxRegistered = () => {
     tsxApi.register();
     tsxRegistered = true;
 };
+let sandboxOptOutWarned = false;
+const warnSandboxDisabled = () => {
+    if (sandboxOptOutWarned) {
+        return;
+    }
+    sandboxOptOutWarned = true;
+    process.stderr.write("scai: SITECOREAI_RECIPE_SANDBOX=0 — loading .recipe.ts in-process; " +
+        "a hostile recipe runs with scai's full privileges.\n");
+};
+/**
+ * Load a `.recipe.ts` and return its exported recipe object. By default the
+ * file is loaded in a confined child process (see docs/recipe-sandbox.md) so
+ * a hostile recipe a weaponized config could point at cannot run with scai's
+ * privileges. `SITECOREAI_RECIPE_SANDBOX=0` forces the legacy in-process load.
+ */
 const loadRecipeFromTypeScript = async (filePath) => {
+    if ((0, load_1.isRecipeSandboxEnabled)()) {
+        return (0, load_1.loadRecipeInSandbox)(filePath);
+    }
+    warnSandboxDisabled();
+    return loadRecipeInProcess(filePath);
+};
+const loadRecipeInProcess = async (filePath) => {
     const absolute = node_path_1.default.resolve(filePath);
     try {
         ensureTsxRegistered();
@@ -108,16 +131,16 @@ const loadRecipeFromTypeScript = async (filePath) => {
                 return mod[key];
             }
         }
-        throw (0, errors_1.createCliError)(`Recipe at ${filePath} has no exports.`, "INPUT_INVALID", {
+        throw (0, errors_1.createScaiError)(`Recipe at ${filePath} has no exports.`, "INPUT_INVALID", {
             hint: "Add `export default <recipe>` (or any named export) to the file.",
         });
     }
     catch (error) {
         // Don't double-wrap our own CliErrors (e.g. "Recipe at <path> has no exports.").
-        if (error instanceof errors_1.CliError) {
+        if (error instanceof errors_1.ScaiError) {
             throw error;
         }
-        throw (0, errors_1.createCliError)(`Failed to load recipe TypeScript file ${filePath}: ${error instanceof Error ? error.message : String(error)}`, "INPUT_INVALID", { hint: "Confirm the file compiles standalone (try `pnpm exec tsx <file>`)." });
+        throw (0, errors_1.createScaiError)(`Failed to load recipe TypeScript file ${filePath}: ${error instanceof Error ? error.message : String(error)}`, "INPUT_INVALID", { hint: "Confirm the file compiles standalone (try `pnpm exec tsx <file>`)." });
     }
 };
 const writeIr = async (filePath, ir) => {
@@ -128,8 +151,8 @@ const loadIr = async (filePath) => {
     const json = await readJson(filePath);
     const result = operations_1.OperationIrSchema.safeParse(json);
     if (!result.success) {
-        throw (0, errors_1.createCliError)(`Invalid Operation IR at ${filePath}.`, "INPUT_INVALID", {
-            hint: "Re-run `scai recipe compile` to regenerate the IR.",
+        throw (0, errors_1.createScaiError)(`Invalid Operation IR at ${filePath}.`, "INPUT_INVALID", {
+            hint: "Re-run `scai provision recipe compile` to regenerate the IR.",
             details: result.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`),
         });
     }

package/dist/recipe/ir/operations.d.ts

@@ -116,7 +116,10 @@ export declare const CreateItemOpSchema: z.ZodObject<{
         kind: z.ZodLiteral<"ref-path">;
         value: z.ZodString;
     }, z.core.$strip>], "kind">;
-    templateOf: z.ZodString;
+    templateOf: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        kind: z.ZodLiteral<"ref-path">;
+        value: z.ZodString;
+    }, z.core.$strip>]>;
     name: z.ZodString;
     fields: z.ZodArray<z.ZodObject<{
         fieldId: z.ZodString;
@@ -325,6 +328,37 @@ export declare const AppendToMultiListOpSchema: z.ZodObject<{
     label: z.ZodString;
     op: z.ZodLiteral<"AppendToMultiList">;
 }, z.core.$strip>;
+/**
+ * Add a numbered version (or a language version) to an existing item.
+ *
+ * `CreateItem` makes an item with version 1 in the default language;
+ * `SetField` writes a field on an *assumed-existing* `(language, version)`.
+ * Neither *creates* a version. Story-seed content recipes — which author
+ * en v1/v2/v3, fr v1, … — need this op to materialise the version slots
+ * the per-version `SetField` ops then fill.
+ *
+ * `version` declares intent: "version N should exist in `language`."
+ * Sitecore assigns numbered versions sequentially, so the executor
+ * reconciles — it adds versions until the item has at least `version` of
+ * them in `language`. Idempotent: a no-op when the version already
+ * exists, which is what lets a re-push converge cleanly. When `language`
+ * has no versions yet, the executor creates that language version too.
+ *
+ * Emitted in version order by the content-item compiler, between the
+ * `CreateItem` op and the per-version `SetField` ops.
+ */
+export declare const AddItemVersionOpSchema: z.ZodObject<{
+    itemRefKey: z.ZodString;
+    language: z.ZodString;
+    version: z.ZodNumber;
+    policy: z.ZodEnum<{
+        CreateUpdateAndDelete: "CreateUpdateAndDelete";
+        CreateAndUpdate: "CreateAndUpdate";
+        CreateOnly: "CreateOnly";
+    }>;
+    label: z.ZodString;
+    op: z.ZodLiteral<"AddItemVersion">;
+}, z.core.$strip>;
 export declare const OperationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     id: z.ZodString;
     path: z.ZodString;
@@ -335,7 +369,10 @@ export declare const OperationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"ref-path">;
         value: z.ZodString;
     }, z.core.$strip>], "kind">;
-    templateOf: z.ZodString;
+    templateOf: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        kind: z.ZodLiteral<"ref-path">;
+        value: z.ZodString;
+    }, z.core.$strip>]>;
     name: z.ZodString;
     fields: z.ZodArray<z.ZodObject<{
         fieldId: z.ZodString;
@@ -500,6 +537,17 @@ export declare const OperationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }>;
     label: z.ZodString;
     op: z.ZodLiteral<"AppendToMultiList">;
+}, z.core.$strip>, z.ZodObject<{
+    itemRefKey: z.ZodString;
+    language: z.ZodString;
+    version: z.ZodNumber;
+    policy: z.ZodEnum<{
+        CreateUpdateAndDelete: "CreateUpdateAndDelete";
+        CreateAndUpdate: "CreateAndUpdate";
+        CreateOnly: "CreateOnly";
+    }>;
+    label: z.ZodString;
+    op: z.ZodLiteral<"AddItemVersion">;
 }, z.core.$strip>], "op">;
 export type CreateItemOp = z.infer<typeof CreateItemOpSchema>;
 export type SetFieldOp = z.infer<typeof SetFieldOpSchema>;
@@ -507,6 +555,7 @@ export type SetBaseTemplatesOp = z.infer<typeof SetBaseTemplatesOpSchema>;
 export type SetStandardValuesOp = z.infer<typeof SetStandardValuesOpSchema>;
 export type CreateSiteFromTemplateOp = z.infer<typeof CreateSiteFromTemplateOpSchema>;
 export type AppendToMultiListOp = z.infer<typeof AppendToMultiListOpSchema>;
+export type AddItemVersionOp = z.infer<typeof AddItemVersionOpSchema>;
 export type Operation = z.infer<typeof OperationSchema>;
 export declare const OperationIrSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<"1">;
@@ -521,7 +570,10 @@ export declare const OperationIrSchema: z.ZodObject<{
             kind: z.ZodLiteral<"ref-path">;
             value: z.ZodString;
         }, z.core.$strip>], "kind">;
-        templateOf: z.ZodString;
+        templateOf: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            kind: z.ZodLiteral<"ref-path">;
+            value: z.ZodString;
+        }, z.core.$strip>]>;
         name: z.ZodString;
         fields: z.ZodArray<z.ZodObject<{
             fieldId: z.ZodString;
@@ -686,7 +738,17 @@ export declare const OperationIrSchema: z.ZodObject<{
         }>;
         label: z.ZodString;
         op: z.ZodLiteral<"AppendToMultiList">;
+    }, z.core.$strip>, z.ZodObject<{
+        itemRefKey: z.ZodString;
+        language: z.ZodString;
+        version: z.ZodNumber;
+        policy: z.ZodEnum<{
+            CreateUpdateAndDelete: "CreateUpdateAndDelete";
+            CreateAndUpdate: "CreateAndUpdate";
+            CreateOnly: "CreateOnly";
+        }>;
+        label: z.ZodString;
+        op: z.ZodLiteral<"AddItemVersion">;
     }, z.core.$strip>], "op">>;
 }, z.core.$strip>;
 export type OperationIr = z.infer<typeof OperationIrSchema>;
-//# sourceMappingURL=operations.d.ts.map

package/dist/recipe/ir/operations.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OperationIrSchema = exports.OperationSchema = exports.AppendToMultiListOpSchema = exports.CreateSiteFromTemplateOpSchema = exports.SetStandardValuesOpSchema = exports.SetBaseTemplatesOpSchema = exports.SetFieldOpSchema = exports.CreateItemOpSchema = exports.FieldValueSchema = exports.RefValueSchema = exports.PushPolicySchema = void 0;
+exports.OperationIrSchema = exports.OperationSchema = exports.AddItemVersionOpSchema = exports.AppendToMultiListOpSchema = exports.CreateSiteFromTemplateOpSchema = exports.SetStandardValuesOpSchema = exports.SetBaseTemplatesOpSchema = exports.SetFieldOpSchema = exports.CreateItemOpSchema = exports.FieldValueSchema = exports.RefValueSchema = exports.PushPolicySchema = void 0;
 const zod_1 = require("zod");
 /**
  * Operation IR — the only artifact the recipe compiler emits.
@@ -137,7 +137,23 @@ exports.CreateItemOpSchema = zod_1.z.object({
         zod_1.z.object({ kind: zod_1.z.literal("ref-recipe"), refKey: GUID }),
         zod_1.z.object({ kind: zod_1.z.literal("ref-path"), value: NON_EMPTY }),
     ]),
-    templateOf: GUID,
+    /**
+     * Template the new item conforms to. Two shapes:
+     *
+     *   - **GUID string** — the conventional case: a Sitecore built-in
+     *     template ID (see `SITECORE_TEMPLATES`), or a refKey for a
+     *     template the same push creates (the planner resolves both
+     *     against `capturedItemIds`).
+     *   - **`{kind: "ref-path", value}`** — late-resolved against a
+     *     content-tree path. Used by recipes that conform new items to
+     *     system templates whose GUIDs aren't published as a public
+     *     contract (e.g. workflow `Workflow`/`State`/`Command` templates,
+     *     webhook authorization templates). The push pipeline pre-seeds
+     *     these via the same `crossRecipeRefs` mechanism that resolves
+     *     ref-path parents: a single `getItemsByPaths` batch lookup
+     *     before planning.
+     */
+    templateOf: zod_1.z.union([GUID, zod_1.z.object({ kind: zod_1.z.literal("ref-path"), value: NON_EMPTY })]),
     name: NON_EMPTY,
     fields: zod_1.z.array(exports.FieldValueSchema),
 });
@@ -331,6 +347,42 @@ exports.AppendToMultiListOpSchema = zod_1.z.object({
      */
     appendPolicy: zod_1.z.literal("merge-unique"),
 });
+/**
+ * Add a numbered version (or a language version) to an existing item.
+ *
+ * `CreateItem` makes an item with version 1 in the default language;
+ * `SetField` writes a field on an *assumed-existing* `(language, version)`.
+ * Neither *creates* a version. Story-seed content recipes — which author
+ * en v1/v2/v3, fr v1, … — need this op to materialise the version slots
+ * the per-version `SetField` ops then fill.
+ *
+ * `version` declares intent: "version N should exist in `language`."
+ * Sitecore assigns numbered versions sequentially, so the executor
+ * reconciles — it adds versions until the item has at least `version` of
+ * them in `language`. Idempotent: a no-op when the version already
+ * exists, which is what lets a re-push converge cleanly. When `language`
+ * has no versions yet, the executor creates that language version too.
+ *
+ * Emitted in version order by the content-item compiler, between the
+ * `CreateItem` op and the per-version `SetField` ops.
+ */
+exports.AddItemVersionOpSchema = zod_1.z.object({
+    op: zod_1.z.literal("AddItemVersion"),
+    ...BaseOpFields,
+    /** RefKey of the target item — resolves to a Sitecore itemId at execute time. */
+    itemRefKey: GUID,
+    /**
+     * Language whose version stack this op extends (ISO code, e.g. `en`,
+     * `fr`). When the language has no versions yet, the executor creates
+     * the language version as part of adding version 1.
+     */
+    language: zod_1.z.string().min(1),
+    /**
+     * The numbered version this op ensures exists (1-based). The executor
+     * adds versions until the item has at least this many in `language`.
+     */
+    version: zod_1.z.number().int().positive(),
+});
 exports.OperationSchema = zod_1.z.discriminatedUnion("op", [
     exports.CreateItemOpSchema,
     exports.SetFieldOpSchema,
@@ -338,6 +390,7 @@ exports.OperationSchema = zod_1.z.discriminatedUnion("op", [
     exports.SetStandardValuesOpSchema,
     exports.CreateSiteFromTemplateOpSchema,
     exports.AppendToMultiListOpSchema,
+    exports.AddItemVersionOpSchema,
 ]);
 exports.OperationIrSchema = zod_1.z.object({
     schemaVersion: zod_1.z.literal("1"),

package/dist/recipe/ir/sitecore-templates.d.ts

@@ -175,6 +175,24 @@ export declare const AVAILABLE_RENDERINGS_FIELDS: {
  * conforms to this template.
  */
 export declare const PLACEHOLDER_TEMPLATE_ID = "d2a6884c-04d5-4089-a64e-d27ca9d68d4c";
+/**
+ * SXA `Placeholder Settings Folder` template
+ * (`/sitecore/templates/Foundation/JSS Experience Accelerator/Placeholder
+ * Settings/Placeholder Settings Folder`). The organisational folder
+ * inside a Placeholder Settings tree — recipe-defined placeholder
+ * grouping folders conform to this so they inherit its `__Standard
+ * Values` Insert Options (`Placeholder` + `Placeholder Settings
+ * Folder`), giving authors the right right-click → Insert UX without
+ * scai having to stamp `__Masters` explicitly.
+ *
+ * Verified against sandbox tenant (`xmc-lizsitecore088b-…`) on
+ * 2026-05-15 via Authoring API introspection — the `Placeholder
+ * Settings` root and its `Partial Design` child both conform to it, and
+ * the template's SV carries
+ * `__Masters = {D2A6884C-…}|{52288E39-…}` (see
+ * `scripts/_recon-page-template.cjs`).
+ */
+export declare const PLACEHOLDER_SETTINGS_FOLDER_TEMPLATE_ID = "52288e39-7830-4694-b62d-32a54c6ef7ba";
 /**
  * Fields of the Sitecore `Placeholder` template that recipes interact
  * with:
@@ -249,6 +267,60 @@ export declare const STANDARD_TEMPLATE_ID = "1930bbeb-7805-471a-a3be-4858ac7cf69
  * dialog stayed empty in Pages.
  */
 export declare const SXA_HEADLESS_PARAMS_BASE_TEMPLATES: readonly ["4247aad4-ebde-4994-998f-e067a51b1fe4", "44a022db-56d3-419a-b43b-e27e4d8e9c41", "3db3eb10-f8d0-4cc9-be26-18ce7b139ec8"];
+/**
+ * SXA Headless page base templates — what a recipe-emitted page template
+ * must inherit so XM Cloud Pages recognises items conforming to it as
+ * authorable pages: they pick up the layout/presentation fields, the
+ * navigation facet, taxonomy tagging, the page-design binding, and
+ * sitemap metadata.
+ *
+ * This is exactly the base set the OOTB per-site `Page` template
+ * carries. Captured 2026-05-15 by walking the `__Base template` chain of
+ * `/sitecore/templates/Project/demo-registry/Page` on the sandbox tenant
+ * (`xmc-lizsitecore088b-…`) via Authoring API introspection — see
+ * `scripts/_recon-page-template.cjs`. All five are SXA Foundation
+ * templates, so the GUIDs are stable across tenants (same identity model
+ * as `SXA_COMPONENT_BASE_TEMPLATES`).
+ *
+ *   - `Base Page`  ({47151711-26CA-434E-8132-D3E0B7D26683}) —
+ *     `/sitecore/templates/Foundation/JSS Experience Accelerator/Multisite/Base Page`.
+ *     The SXA Headless page base; chains in the EXA `Page` →
+ *     Standard template, so the Layout / Appearance / Publishing
+ *     sections all arrive transitively.
+ *   - `_Navigable`  ({371D5FBB-5498-4D94-AB2B-E3B70EEBE78C}) —
+ *     navigation facet: `NavigationTitle`, `ChangeFrequency`, `Priority`.
+ *   - `_Taggable`  ({F39A594A-7BC9-4DB0-BAA1-88543409C1F9}) —
+ *     taxonomy tagging facet.
+ *   - `_Designable`  ({6650FB34-7EA1-4245-A919-5CC0F002A6D7}) —
+ *     carries the `Page Design` Droplink field (the per-item
+ *     page-design override). The default template→design binding is
+ *     the `TemplatesMapping` aggregate on the Page Designs root, not
+ *     this field — see `compileRecipeSet`.
+ *   - `_Sitemap`  ({4414A1F9-826A-4647-8DF4-ED6A95E64C43}) —
+ *     sitemap metadata facet.
+ */
+export declare const SXA_HEADLESS_PAGE_BASE_TEMPLATES: readonly ["47151711-26ca-434e-8132-d3e0b7d26683", "371d5fbb-5498-4d94-ab2b-e3b70eebe78c", "f39a594a-7bc9-4db0-baa1-88543409c1f9", "6650fb34-7ea1-4245-a919-5cc0f002a6d7", "4414a1f9-826a-4647-8df4-ed6a95e64c43"];
+/**
+ * `Page Design` field on the SXA `_Designable` facet — a Droplink whose
+ * Source is `query:$pageDesigns//*[@@templatename='Page Design']`. The
+ * per-item page-design override; recipe-emitted page templates leave it
+ * unset (the default binding flows through the Page Designs root's
+ * `TemplatesMapping`). Captured in the same 2026-05-15 recon pass.
+ */
+export declare const PAGE_DESIGN_FIELD_ID = "24171bf1-c0e1-480e-be76-4c0a1876f916";
+/**
+ * SXA Headless JSON `Layout` definition item (`/sitecore/layout/Layouts/
+ * Project/.../JSON Layout`). A page's `__Renderings` field wraps its
+ * device element with `l="{this}"` — `<d id="{device}" l="{layout}" />`.
+ * Recipe-emitted page templates stamp it on the `__Standard Values`
+ * layout shell so pages conforming to them render through the headless
+ * JSON layout pipeline.
+ *
+ * Captured 2026-05-15 from the `Page` template's `__Standard Values`
+ * `__Renderings` field on the sandbox tenant. SXA-shipped item, stable
+ * GUID across tenants.
+ */
+export declare const SXA_JSON_LAYOUT_ID = "96e5f4ba-a2cf-4a4c-a4e7-64da88226362";
 /**
  * Stable system-field GUIDs that recipes need to write.
  * Auto-generated metadata fields (__Created, __Updated, __Revision, __Owner)
@@ -283,6 +355,14 @@ export declare const TEMPLATE_FIELD_FIELDS: {
      * value, not per-language). GUID is the well-known Sitecore built-in.
      */
     readonly SHARED: "be351a73-fcb0-4213-93fa-c302d8ab4f51";
+    /**
+     * `Unversioned` toggle on a Template Field — `"1"` makes the field's
+     * value per-language but shared across numbered versions (vs `SHARED`,
+     * which is one value for the whole item). Verified against the live
+     * `test` tenant via Authoring API introspection on 2026-05-15. GUID is
+     * the well-known Sitecore built-in.
+     */
+    readonly UNVERSIONED: "39847666-389d-409b-95bd-f2016f11eed5";
 };
 /**
  * Sitecore layout fields. `__Renderings` carries the shared layout
@@ -452,4 +532,10 @@ export declare const FOLDER_ICON = "office/16x16/folder.png";
  * icon through template-level inheritance.
  */
 export declare const ENUMERATION_ICON = "office/32x32/keyboard_key_e.png";
-//# sourceMappingURL=sitecore-templates.d.ts.map
+/**
+ * Icon for recipe-emitted page templates — matches the icon the OOTB
+ * SXA Headless `Page` template carries (`Office/32x32/document_text.png`,
+ * verified 2026-05-15 on the sandbox tenant), so page templates read as
+ * pages — not generic data templates — in the content-tree.
+ */
+export declare const PAGE_TEMPLATE_ICON = "Office/32x32/document_text.png";