@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.1

package/dist/recipe/tasks/shared.js

@@ -3,25 +3,54 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ensureAllowWrite = exports.resolveRecipeInputs = exports.resolveRecipeRoots = exports.resolveTenant = exports.toLogger = void 0;
+exports.ensureAllowWrite = exports.resolveRecipeInputs = exports.resolveRecipeRoots = exports.recipeSetNeedsRoots = exports.resolveTenant = exports.toLogger = void 0;
 const node_path_1 = __importDefault(require("node:path"));
 const fast_glob_1 = __importDefault(require("fast-glob"));
 const logger_1 = require("../../shared/logger");
 const errors_1 = require("../../shared/errors");
-const env_1 = require("../../shared/env");
+const environment_1 = require("../../policy/environment");
 const authoring_client_1 = require("../api/authoring-client");
 const toLogger = (options) => new logger_1.Logger(Boolean(options.verbose), Boolean(options.trace), Boolean(options.json), Boolean(options.quiet), options.logFile ?? process.env.SITECOREAI_LOG_FILE);
 exports.toLogger = toLogger;
 const resolveTenant = (options, clientOptions) => {
-    const { envName, environment, root, timeoutMs } = (0, env_1.resolveEnvironment)(options);
+    const { envName, environment, root, timeoutMs } = (0, environment_1.resolveEnvironment)(options);
+    // Carry the org-scoped automation client's non-secret `clientId` from
+    // the root config so the auth layer can pair it with the org-client
+    // secret in the keychain (the tier-3 fallback for org-level profiles).
+    const orgClientId = environment.organizationId
+        ? root.orgClients[environment.organizationId]?.clientId
+        : undefined;
     const client = (0, authoring_client_1.createAuthoringClient)({
-        environment,
+        environment: { ...environment, orgClientId },
         request: { timeoutMs },
         ...(clientOptions?.pathItemIdCache && { pathItemIdCache: clientOptions.pathItemIdCache }),
     });
     return { envName, environment, root, client };
 };
 exports.resolveTenant = resolveTenant;
+/**
+ * Recipe kinds whose compilers create items under hardcoded
+ * `/sitecore/system/*` roots and never read `templatesRoot` /
+ * `renderingsRoot`:
+ *   - `workflow`              → `/sitecore/system/Workflows`
+ *   - `webhook-authorization` → `/sitecore/system/Settings/Webhooks/Authorizations`
+ *
+ * A recipe set built only from these kinds can compile, plan, and push
+ * with neither root configured — see `recipeSetNeedsRoots`.
+ */
+const ROOTLESS_RECIPE_KINDS = new Set(["workflow", "webhook-authorization"]);
+/**
+ * Whether a recipe set needs `templatesRoot` / `renderingsRoot` resolved.
+ *
+ * True when at least one recipe creates template / rendering items —
+ * every kind except `ROOTLESS_RECIPE_KINDS`. An empty set (e.g. a push
+ * fed only pre-compiled `.ir.json` inputs, which carry their roots baked
+ * in) needs neither. New recipe kinds default to *needing* roots; add a
+ * kind to `ROOTLESS_RECIPE_KINDS` only once its compiler is confirmed to
+ * ignore both roots.
+ */
+const recipeSetNeedsRoots = (recipes) => recipes.some((recipe) => !ROOTLESS_RECIPE_KINDS.has(recipe.kind));
+exports.recipeSetNeedsRoots = recipeSetNeedsRoots;
 /**
  * Resolve the recipe parent paths that the compiler will use for top-level
  * template + rendering items.
@@ -32,23 +61,35 @@ exports.resolveTenant = resolveTenant;
  *      sitecoreai.cli.json (env-overrides via
  *      `SITECOREAI_ENV_<NAME>_TEMPLATES_ROOT` / `_RENDERINGS_ROOT` apply
  *      at config-load time before this helper runs)
- *   3. Throws `INPUT_INVALID` with a hint pointing at the envProfile shape
+ *   3. When `required`, throws `INPUT_INVALID` with a hint pointing at
+ *      the envProfile shape. When not required (a workflow- /
+ *      webhook-authorization-only set, or an IR-only push), missing
+ *      roots resolve to `""` — the compilers in play never read them.
+ *
+ * Pass `required` from `recipeSetNeedsRoots(recipes)` once the set's
+ * recipe kinds are known.
  *
  * Tenant-specific because each site has its own
  * `/sitecore/templates/Project/<site>/Components` location. Putting roots
  * in config keeps the orchestrator's `recipe push` invocation
  * config-driven (no plan-schema fields, no extra arg plumbing).
  */
-const resolveRecipeRoots = (options, environment, envName) => {
+const resolveRecipeRoots = (options, environment, envName, required = true) => {
     const templatesRoot = options.templatesRoot ?? environment?.templatesRoot;
     const renderingsRoot = options.renderingsRoot ?? environment?.renderingsRoot;
+    if (!required) {
+        // The recipe set in play never reads these roots — pass through
+        // whatever's configured, or "" so the requirement doesn't block a
+        // set that doesn't need it.
+        return { templatesRoot: templatesRoot ?? "", renderingsRoot: renderingsRoot ?? "" };
+    }
     if (!templatesRoot || !renderingsRoot) {
         const missing = !templatesRoot && !renderingsRoot
             ? "both roots"
             : !templatesRoot
                 ? "templatesRoot"
                 : "renderingsRoot";
-        throw (0, errors_1.createCliError)(`Recipe parent path missing: ${missing} not configured for environment '${envName}'.`, "INPUT_INVALID", {
+        throw (0, errors_1.createScaiError)(`Recipe parent path missing: ${missing} not configured for environment '${envName}'.`, "INPUT_INVALID", {
             hint: `Add 'templatesRoot' and 'renderingsRoot' to envProfiles.${envName} in sitecoreai.cli.json (or pass --templates-root / --renderings-root).`,
         });
     }
@@ -68,27 +109,34 @@ const resolveRecipeInputs = async (options, root) => {
         return { files: [node_path_1.default.resolve(options.input)], source: "input-flag" };
     }
     const configDir = node_path_1.default.dirname(root.physicalPath);
-    const matched = await (0, fast_glob_1.default)(root.recipes, { cwd: configDir, absolute: true });
+    // followSymbolicLinks: false defends against an attacker-planted symlink
+    // in recipes/ pointing at /etc/, ~/.aws/, or any other sensitive TS file
+    // — those files would otherwise be executed by tsx when the recipe gets
+    // loaded (.recipe.ts is code, not data).
+    const matched = await (0, fast_glob_1.default)(root.recipes, {
+        cwd: configDir,
+        absolute: true,
+        followSymbolicLinks: false,
+    });
+    // Defense in depth: reject any resolved path that escapes the config
+    // directory (e.g. via `..` segments in the glob input).
+    const escaped = matched.filter((p) => node_path_1.default.relative(configDir, p).startsWith(".."));
+    if (escaped.length > 0) {
+        throw (0, errors_1.createScaiError)(`Recipe glob resolved to ${escaped.length} path(s) outside the config directory: ${escaped.slice(0, 3).join(", ")}${escaped.length > 3 ? `, +${escaped.length - 3} more` : ""}.`, "INPUT_INVALID", {
+            hint: "Recipe paths must live under the directory containing sitecoreai.cli.json.",
+        });
+    }
     if (matched.length === 0) {
-        throw (0, errors_1.createCliError)(`No recipe files matched the config glob: ${root.recipes.join(", ")}.`, "INPUT_INVALID", {
+        throw (0, errors_1.createScaiError)(`No recipe files matched the config glob: ${root.recipes.join(", ")}.`, "INPUT_INVALID", {
             hint: "Pass --input <recipe-file>, or update the `recipes` glob in sitecoreai.cli.json.",
         });
     }
     return { files: matched.sort(), source: "config-glob" };
 };
 exports.resolveRecipeInputs = resolveRecipeInputs;
-const ensureAllowWrite = (root, envName, override) => {
-    const environment = root.environments[envName];
-    if (override || environment?.allowWrite) {
-        return;
-    }
-    const envKey = envName
-        .trim()
-        .toUpperCase()
-        .replace(/[^A-Z0-9]+/g, "_")
-        .replace(/^_+|_+$/g, "");
-    throw (0, errors_1.createCliError)(`Environment ${envName} is not configured to allow writing data.`, "INPUT_INVALID", {
-        hint: `Set allowWrite in sitecoreai.cli.json, set SITECOREAI_ENV_${envKey}_ALLOW_WRITE=true, or pass --allow-write.`,
-    });
-};
-exports.ensureAllowWrite = ensureAllowWrite;
+// Re-exported from the shared gate so `recipe push` goes through the
+// same workspace-policy enforcement (ceiling, caller context, the
+// `recipe-push` destructive tier) as every other write path. The
+// recipe-local copy that used to live here predated the policy layer.
+var allow_write_1 = require("../../policy/allow-write");
+Object.defineProperty(exports, "ensureAllowWrite", { enumerable: true, get: function () { return allow_write_1.ensureAllowWrite; } });

package/dist/recipe/unstable.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Unstable recipe API — `import { ... } from "@sitecoreai-labs/sitecoreai-cli/recipe/unstable"`.
+ *
+ * The recipe **composition kinds** — `ContentItem`, `PageDesign`,
+ * `PartialDesign`, `SiteRecipe`, `SiteTemplate` — are present in the source
+ * and usable, but they are NOT part of the 0.1.0 stability promise. Their
+ * schemas, types, and compilers may change shape between minor releases
+ * without a major bump. They graduate to the stable `./recipe` entry in a
+ * follow-up release (see `.changeset/recipes-graduation.md`).
+ *
+ * The five stable recipe kinds — `ComponentTemplate`, `ContentTemplate`,
+ * `ComponentSection`, `DesignParametersTemplate`, `Enumeration` — and all
+ * shared recipe infrastructure (the `RecipeSchema` umbrella, `compileRecipe`,
+ * the planner/executor, GUID derivation, IR) stay on the stable `./recipe`
+ * entry.
+ */
+export { ContentItemRecipeSchema, PageDesignRecipeSchema, PartialDesignRecipeSchema, SiteGroupingSchema, SiteRecipeSchema, SiteTemplateDictionaryEntrySchema, SiteTemplateRecipeSchema, SiteTemplateTaxonomyEntrySchema, type ContentItemRecipe, type PageDesignRecipe, type PartialDesignRecipe, type SiteGrouping, type SiteRecipe, type SiteTemplateDictionaryEntry, type SiteTemplateRecipe, type SiteTemplateTaxonomyEntry, } from "./schema/recipe";
+export { compileContentItemRecipe, compilePageDesignRecipe, compilePartialDesignRecipe, compileSiteRecipe, compileSiteTemplateRecipe, } from "./compile";

package/dist/recipe/unstable.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Unstable recipe API — `import { ... } from "@sitecoreai-labs/sitecoreai-cli/recipe/unstable"`.
+ *
+ * The recipe **composition kinds** — `ContentItem`, `PageDesign`,
+ * `PartialDesign`, `SiteRecipe`, `SiteTemplate` — are present in the source
+ * and usable, but they are NOT part of the 0.1.0 stability promise. Their
+ * schemas, types, and compilers may change shape between minor releases
+ * without a major bump. They graduate to the stable `./recipe` entry in a
+ * follow-up release (see `.changeset/recipes-graduation.md`).
+ *
+ * The five stable recipe kinds — `ComponentTemplate`, `ContentTemplate`,
+ * `ComponentSection`, `DesignParametersTemplate`, `Enumeration` — and all
+ * shared recipe infrastructure (the `RecipeSchema` umbrella, `compileRecipe`,
+ * the planner/executor, GUID derivation, IR) stay on the stable `./recipe`
+ * entry.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileSiteTemplateRecipe = exports.compileSiteRecipe = exports.compilePartialDesignRecipe = exports.compilePageDesignRecipe = exports.compileContentItemRecipe = exports.SiteTemplateTaxonomyEntrySchema = exports.SiteTemplateRecipeSchema = exports.SiteTemplateDictionaryEntrySchema = exports.SiteRecipeSchema = exports.SiteGroupingSchema = exports.PartialDesignRecipeSchema = exports.PageDesignRecipeSchema = exports.ContentItemRecipeSchema = void 0;
+// Composition-kind schemas + types ----------------------------------------
+var recipe_1 = require("./schema/recipe");
+Object.defineProperty(exports, "ContentItemRecipeSchema", { enumerable: true, get: function () { return recipe_1.ContentItemRecipeSchema; } });
+Object.defineProperty(exports, "PageDesignRecipeSchema", { enumerable: true, get: function () { return recipe_1.PageDesignRecipeSchema; } });
+Object.defineProperty(exports, "PartialDesignRecipeSchema", { enumerable: true, get: function () { return recipe_1.PartialDesignRecipeSchema; } });
+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; } });
+// Composition-kind compilers ----------------------------------------------
+var compile_1 = require("./compile");
+Object.defineProperty(exports, "compileContentItemRecipe", { enumerable: true, get: function () { return compile_1.compileContentItemRecipe; } });
+Object.defineProperty(exports, "compilePageDesignRecipe", { enumerable: true, get: function () { return compile_1.compilePageDesignRecipe; } });
+Object.defineProperty(exports, "compilePartialDesignRecipe", { enumerable: true, get: function () { return compile_1.compilePartialDesignRecipe; } });
+Object.defineProperty(exports, "compileSiteRecipe", { enumerable: true, get: function () { return compile_1.compileSiteRecipe; } });
+Object.defineProperty(exports, "compileSiteTemplateRecipe", { enumerable: true, get: function () { return compile_1.compileSiteTemplateRecipe; } });

package/dist/recipe/validate.d.ts

@@ -14,21 +14,46 @@ import type { Recipe } from "./schema/recipe";
  *     params[*].sitecore.sourceTypes[*]   → any template-bearing recipe
  *     insertOptions[*]                    → any template-bearing recipe
  *
+ *   ComponentTemplateRecipe
+ *     placeholders[*].allowedComponents[*]→ ComponentTemplateRecipe
+ *
  *   ContentItemRecipe
  *     templateType                        → any template-bearing recipe
  *     fields[*].link-internal.ref         → any recipe
  *     fields[*].reference.refs[*]         → any recipe
  *
+ *   PageTemplateRecipe
+ *     fields[*].sitecore.sourceTypes[*]   → any template-bearing recipe
+ *     insertOptions[*]                    → PageTemplateRecipe
+ *     layout.placeholders[*][*].componentHandle           → ComponentTemplateRecipe
+ *     layout.placeholders[*][*].datasourceRef.handle      → ContentItemRecipe
+ *
+ *   PlaceholderRecipe
+ *     allowedComponents[*]                → ComponentTemplateRecipe
+ *
+ *   PageRecipe
+ *     template                            → PageTemplateRecipe
+ *     fields[*].link-internal.ref          → any recipe
+ *     fields[*].reference.refs[*]          → any recipe
+ *     layout.placeholders[*][*].componentHandle      → ComponentTemplateRecipe
+ *     layout.placeholders[*][*].datasourceRef.handle → ContentItemRecipe
+ *
  *   PartialDesignRecipe
  *     layout.placeholders[*][*].componentHandle           → ComponentTemplateRecipe
  *     layout.placeholders[*][*].datasourceRef.handle      → ContentItemRecipe
  *
  *   PageDesignRecipe
- *     appliesTo[*]                        → ContentTemplateRecipe (page templates)
+ *     appliesTo[*]                        → PageTemplateRecipe
  *     partials[*]                         → PartialDesignRecipe
  *     layout.placeholders[*][*].componentHandle           → ComponentTemplateRecipe
  *     layout.placeholders[*][*].datasourceRef.handle      → ContentItemRecipe
  *
+ * Beyond reference resolution this also checks **placement legality** —
+ * a layout placement into a recipe-defined placeholder whose
+ * `Allowed Controls` whitelist doesn't include the component is reported
+ * as a `PlacementViolation` — and flags a placeholder `key` declared by
+ * more than one recipe.
+ *
  * Cycle detection covers `insertOptions` chains
  * (`ComponentTemplate.insertOptions → ContentTemplate.insertOptions → …`)
  * — the only place the current schema permits transitive recipe-to-recipe
@@ -77,11 +102,36 @@ export interface FieldShapeError {
     /** Operator-readable explanation. */
     message: string;
 }
+/**
+ * A layout placement that drops a component into a recipe-defined
+ * placeholder whose `Allowed Controls` whitelist doesn't include it —
+ * the "what's allowed in a placeholder" enforcement.
+ *
+ * Only raised for placeholders the recipe set itself defines (a
+ * `PlaceholderRecipe` or an inline `ComponentTemplateRecipe.placeholders`
+ * slot) AND that carry a non-empty whitelist. Placements into
+ * pre-existing tenant placeholders, or into recipe-defined placeholders
+ * with an empty (unrestricted) whitelist, are not checkable here and
+ * pass.
+ */
+export interface PlacementViolation {
+    /** Handle of the recipe that holds the offending layout. */
+    fromRecipe: string;
+    /** Dotted path to the placement — `layout.placeholders./header.0`. */
+    fromField: string;
+    /** The component handle being placed. */
+    componentHandle: string;
+    /** The placeholder key it was placed into. */
+    placeholderKey: string;
+    /** The component handles the placeholder's whitelist does allow. */
+    allowedComponents: readonly string[];
+}
 export interface ValidationResult {
     unresolvedHandles: UnresolvedHandle[];
     duplicateHandles: DuplicateHandle[];
     cycles: CyclicReference[];
     fieldShapeErrors: FieldShapeError[];
+    placementViolations: PlacementViolation[];
 }
 export declare const isValid: (result: ValidationResult) => boolean;
 /**
@@ -100,4 +150,3 @@ export declare function validateRecipeSet(recipes: readonly Recipe[]): Validatio
  * should hard-stop before compilation when the recipe set is malformed.
  */
 export declare function validateRecipeSetOrThrow(recipes: readonly Recipe[]): void;
-//# sourceMappingURL=validate.d.ts.map

package/dist/recipe/validate.js

@@ -5,11 +5,17 @@ exports.formatValidationErrors = formatValidationErrors;
 exports.validateRecipeSet = validateRecipeSet;
 exports.validateRecipeSetOrThrow = validateRecipeSetOrThrow;
 const errors_1 = require("../shared/errors");
-const TEMPLATE_KINDS = ["component-template", "content-template"];
+const TEMPLATE_KINDS = [
+    "component-template",
+    "content-template",
+    "page-template",
+];
 const COMPONENT_TEMPLATE_KINDS = ["component-template"];
 const CONTENT_TEMPLATE_KINDS = ["content-template"];
+const PAGE_TEMPLATE_KINDS = ["page-template"];
+const PAGE_KINDS = ["page"];
 const CONTENT_ITEM_KINDS = ["content-item"];
-const PARAMETERS_TEMPLATE_KINDS = ["parameters-template"];
+const PARAMETERS_TEMPLATE_KINDS = ["design-parameters-template"];
 const SECTION_DEFINITION_KINDS = ["section-definition"];
 const PARTIAL_DESIGN_KINDS = ["partial-design"];
 const PAGE_DESIGN_KINDS = ["page-design"];
@@ -18,7 +24,10 @@ const ANY_KINDS = [
     "component-template",
     "content-template",
     "content-item",
-    "parameters-template",
+    "page-template",
+    "page",
+    "placeholder",
+    "design-parameters-template",
     "section-definition",
     "partial-design",
     "page-design",
@@ -26,7 +35,8 @@ const ANY_KINDS = [
 const isValid = (result) => result.unresolvedHandles.length === 0 &&
     result.duplicateHandles.length === 0 &&
     result.cycles.length === 0 &&
-    result.fieldShapeErrors.length === 0;
+    result.fieldShapeErrors.length === 0 &&
+    result.placementViolations.length === 0;
 exports.isValid = isValid;
 /**
  * Render a `ValidationResult` as a multi-line, human-readable error
@@ -49,6 +59,9 @@ function formatValidationErrors(result) {
     for (const err of result.fieldShapeErrors) {
         lines.push(`${err.fromRecipe} → ${err.fromField}: ${err.message}`);
     }
+    for (const v of result.placementViolations) {
+        lines.push(`${v.fromRecipe} → ${v.fromField}: '${v.componentHandle}' is not allowed in placeholder '${v.placeholderKey}' (allowed: ${v.allowedComponents.join(", ") || "none"}).`);
+    }
     return lines.join("\n");
 }
 /**
@@ -94,6 +107,79 @@ function validateRecipeSet(recipes) {
             });
         }
     };
+    const placementViolations = [];
+    // Pre-pass: collect recipe-defined placeholder keys and their resolved
+    // `Allowed Controls` whitelists — standalone `PlaceholderRecipe` plus
+    // inline `ComponentTemplateRecipe.placeholders`, then `placedIn`
+    // pushes. Mirrors `buildPlaceholderSettingsAggregate` in `compile.ts`
+    // so the legality check sees the same allow-sets the compiler emits.
+    const placeholderAllow = new Map();
+    const placeholderDefiners = new Map();
+    const declarePlaceholder = (key, byRecipe) => {
+        placeholderDefiners.set(key, [...(placeholderDefiners.get(key) ?? []), byRecipe]);
+        let set = placeholderAllow.get(key);
+        if (!set) {
+            set = new Set();
+            placeholderAllow.set(key, set);
+        }
+        return set;
+    };
+    for (const recipe of recipes) {
+        if (recipe.kind === "placeholder") {
+            const set = declarePlaceholder(recipe.key, recipe.handle);
+            for (const handle of recipe.allowedComponents ?? [])
+                set.add(handle);
+        }
+        else if (recipe.kind === "component-template") {
+            for (const slot of recipe.placeholders ?? []) {
+                const set = declarePlaceholder(slot.key, recipe.handle);
+                for (const handle of slot.allowedComponents ?? [])
+                    set.add(handle);
+            }
+        }
+    }
+    for (const recipe of recipes) {
+        if (recipe.kind !== "component-template")
+            continue;
+        for (const key of recipe.placedIn ?? []) {
+            placeholderAllow.get(key)?.add(recipe.handle);
+        }
+    }
+    // A placeholder key declared by 2+ recipes is ambiguous — both would
+    // derive the same Placeholder Settings item GUID. Flag it once.
+    for (const [key, definers] of placeholderDefiners) {
+        if (definers.length > 1) {
+            fieldShapeErrors.push({
+                fromRecipe: definers[0],
+                fromField: "placeholder key",
+                message: `placeholder key '${key}' is declared by multiple recipes (${definers.join(", ")}) — a key maps to exactly one Placeholder Settings item; declare it once.`,
+            });
+        }
+    }
+    /**
+     * Check every placement in a layout against the placeholder allow-set.
+     * Only flags placements into recipe-defined placeholders with a
+     * non-empty whitelist — pre-existing tenant placeholders and
+     * unrestricted (empty-whitelist) ones can't be checked and pass.
+     */
+    const checkLayoutPlacements = (fromRecipe, placeholders) => {
+        for (const [phKey, placements] of Object.entries(placeholders)) {
+            const allow = placeholderAllow.get(phKey);
+            if (!allow || allow.size === 0)
+                continue;
+            placements.forEach((placement, idx) => {
+                if (!allow.has(placement.componentHandle)) {
+                    placementViolations.push({
+                        fromRecipe,
+                        fromField: `layout.placeholders.${phKey}.${idx}`,
+                        componentHandle: placement.componentHandle,
+                        placeholderKey: phKey,
+                        allowedComponents: [...allow].sort((a, b) => a.localeCompare(b)),
+                    });
+                }
+            });
+        }
+    };
     for (const recipe of recipes) {
         switch (recipe.kind) {
             case "component-template":
@@ -122,8 +208,13 @@ function validateRecipeSet(recipes) {
                 recipe.availableIn?.forEach((handle, idx) => {
                     checkRef(recipe.handle, `availableIn.${idx}`, handle, SECTION_DEFINITION_KINDS);
                 });
+                (recipe.placeholders ?? []).forEach((slot, idx) => {
+                    slot.allowedComponents?.forEach((handle, aIdx) => {
+                        checkRef(recipe.handle, `placeholders.${idx}.allowedComponents.${aIdx}`, handle, COMPONENT_TEMPLATE_KINDS);
+                    });
+                });
                 break;
-            case "parameters-template":
+            case "design-parameters-template":
                 recipe.params.forEach((param, idx) => {
                     param.sitecore?.sourceTypes?.forEach((handle, sIdx) => {
                         checkRef(recipe.handle, `params.${idx}.sitecore.sourceTypes.${sIdx}`, handle, TEMPLATE_KINDS);
@@ -166,10 +257,11 @@ function validateRecipeSet(recipes) {
                         }
                     });
                 }
+                checkLayoutPlacements(recipe.handle, recipe.layout.placeholders);
                 break;
             case "page-design":
                 recipe.appliesTo.forEach((handle, idx) => {
-                    checkRef(recipe.handle, `appliesTo.${idx}`, handle, CONTENT_TEMPLATE_KINDS);
+                    checkRef(recipe.handle, `appliesTo.${idx}`, handle, PAGE_TEMPLATE_KINDS);
                 });
                 recipe.partials.forEach((handle, idx) => {
                     checkRef(recipe.handle, `partials.${idx}`, handle, PARTIAL_DESIGN_KINDS);
@@ -183,11 +275,62 @@ function validateRecipeSet(recipes) {
                             }
                         });
                     }
+                    checkLayoutPlacements(recipe.handle, recipe.layout.placeholders);
+                }
+                break;
+            case "page-template":
+                (recipe.fields ?? []).forEach((field, idx) => {
+                    field.sitecore?.sourceTypes?.forEach((handle, sIdx) => {
+                        checkRef(recipe.handle, `fields.${idx}.sitecore.sourceTypes.${sIdx}`, handle, TEMPLATE_KINDS);
+                    });
+                });
+                recipe.insertOptions?.forEach((handle, idx) => {
+                    checkRef(recipe.handle, `insertOptions.${idx}`, handle, PAGE_TEMPLATE_KINDS);
+                });
+                if (recipe.layout) {
+                    for (const [phKey, placements] of Object.entries(recipe.layout.placeholders)) {
+                        placements.forEach((placement, idx) => {
+                            checkRef(recipe.handle, `layout.placeholders.${phKey}.${idx}.componentHandle`, placement.componentHandle, COMPONENT_TEMPLATE_KINDS);
+                            if (placement.datasourceRef?.kind === "shared") {
+                                checkRef(recipe.handle, `layout.placeholders.${phKey}.${idx}.datasourceRef.handle`, placement.datasourceRef.handle, CONTENT_ITEM_KINDS);
+                            }
+                        });
+                    }
+                    checkLayoutPlacements(recipe.handle, recipe.layout.placeholders);
+                }
+                break;
+            case "placeholder":
+                (recipe.allowedComponents ?? []).forEach((handle, idx) => {
+                    checkRef(recipe.handle, `allowedComponents.${idx}`, handle, COMPONENT_TEMPLATE_KINDS);
+                });
+                break;
+            case "page":
+                checkRef(recipe.handle, "template", recipe.template, PAGE_TEMPLATE_KINDS);
+                for (const [fieldName, value] of Object.entries(recipe.fields ?? {})) {
+                    if (value.shape === "link-internal") {
+                        checkRef(recipe.handle, `fields.${fieldName}.ref`, value.ref, ANY_KINDS);
+                    }
+                    else if (value.shape === "reference") {
+                        value.refs.forEach((handle, idx) => {
+                            checkRef(recipe.handle, `fields.${fieldName}.refs.${idx}`, handle, ANY_KINDS);
+                        });
+                    }
+                }
+                if (recipe.layout) {
+                    for (const [phKey, placements] of Object.entries(recipe.layout.placeholders)) {
+                        placements.forEach((placement, idx) => {
+                            checkRef(recipe.handle, `layout.placeholders.${phKey}.${idx}.componentHandle`, placement.componentHandle, COMPONENT_TEMPLATE_KINDS);
+                            if (placement.datasourceRef?.kind === "shared") {
+                                checkRef(recipe.handle, `layout.placeholders.${phKey}.${idx}.datasourceRef.handle`, placement.datasourceRef.handle, CONTENT_ITEM_KINDS);
+                            }
+                        });
+                    }
+                    checkLayoutPlacements(recipe.handle, recipe.layout.placeholders);
                 }
                 break;
             case "site-template":
                 recipe.pageTemplates.forEach((handle, idx) => {
-                    checkRef(recipe.handle, `pageTemplates.${idx}`, handle, CONTENT_TEMPLATE_KINDS);
+                    checkRef(recipe.handle, `pageTemplates.${idx}`, handle, PAGE_TEMPLATE_KINDS);
                 });
                 recipe.pageDesigns.forEach((handle, idx) => {
                     checkRef(recipe.handle, `pageDesigns.${idx}`, handle, PAGE_DESIGN_KINDS);
@@ -196,15 +339,15 @@ function validateRecipeSet(recipes) {
                     for (const [parentHandle, allowedChildren] of Object.entries(recipe.insertOptionsMatrix)) {
                         // The KEY is itself a page-template handle. Validate it too —
                         // a typo in the key would silently never apply at apply time.
-                        checkRef(recipe.handle, `insertOptionsMatrix.${parentHandle}`, parentHandle, CONTENT_TEMPLATE_KINDS);
+                        checkRef(recipe.handle, `insertOptionsMatrix.${parentHandle}`, parentHandle, PAGE_TEMPLATE_KINDS);
                         allowedChildren.forEach((childHandle, idx) => {
-                            checkRef(recipe.handle, `insertOptionsMatrix.${parentHandle}.${idx}`, childHandle, CONTENT_TEMPLATE_KINDS);
+                            checkRef(recipe.handle, `insertOptionsMatrix.${parentHandle}.${idx}`, childHandle, PAGE_TEMPLATE_KINDS);
                         });
                     }
                 }
                 if (recipe.templatesToDesigns) {
                     for (const [templateHandle, designHandle] of Object.entries(recipe.templatesToDesigns)) {
-                        checkRef(recipe.handle, `templatesToDesigns.${templateHandle} (key)`, templateHandle, CONTENT_TEMPLATE_KINDS);
+                        checkRef(recipe.handle, `templatesToDesigns.${templateHandle} (key)`, templateHandle, PAGE_TEMPLATE_KINDS);
                         checkRef(recipe.handle, `templatesToDesigns.${templateHandle}`, designHandle, PAGE_DESIGN_KINDS);
                     }
                 }
@@ -212,9 +355,7 @@ function validateRecipeSet(recipes) {
             case "site":
                 checkRef(recipe.handle, "siteTemplate", recipe.siteTemplate, SITE_TEMPLATE_KINDS);
                 if (recipe.initialHome !== undefined) {
-                    // PageRecipe doesn't exist yet — accept any kind. When
-                    // PageRecipe lands, narrow this to PAGE_RECIPE_KINDS.
-                    checkRef(recipe.handle, "initialHome", recipe.initialHome, ANY_KINDS);
+                    checkRef(recipe.handle, "initialHome", recipe.initialHome, PAGE_KINDS);
                 }
                 // Cross-field shape: SiteRecipe must specify exactly one of
                 // collectionId or collectionName. The Zod schema can't enforce
@@ -238,7 +379,13 @@ function validateRecipeSet(recipes) {
         }
     }
     const cycles = detectInsertOptionsCycles(index, recipes);
-    return { unresolvedHandles: unresolved, duplicateHandles, cycles, fieldShapeErrors };
+    return {
+        unresolvedHandles: unresolved,
+        duplicateHandles,
+        cycles,
+        fieldShapeErrors,
+        placementViolations,
+    };
 }
 /**
  * DFS over `insertOptions` edges. Each unique cycle is reported once,
@@ -292,6 +439,6 @@ function detectInsertOptionsCycles(index, recipes) {
 function validateRecipeSetOrThrow(recipes) {
     const result = validateRecipeSet(recipes);
     if (!(0, exports.isValid)(result)) {
-        throw (0, errors_1.createCliError)(`Recipe set validation failed:\n${formatValidationErrors(result)}`, "INPUT_INVALID");
+        throw (0, errors_1.createScaiError)(`Recipe set validation failed:\n${formatValidationErrors(result)}`, "INPUT_INVALID");
     }
 }

package/dist/scripting/connect.d.ts

@@ -0,0 +1,24 @@
+import { type HygieneApiClient } from "../hygiene/api/client";
+/**
+ * Unified client for ad-hoc TypeScript scripting against a configured
+ * scai environment. The intent: replace one-shot imports from `@/`-path
+ * internals with a stable, ergonomic entry point that handles env
+ * resolution, auth, and client lifecycle in one call.
+ *
+ * Stability contract: the shape of `ScaiClient` and the `connect`
+ * signature are part of the public surface. Internal area clients
+ * (currently just `hygiene`) are exposed by reference — their own
+ * stability contract lives in `scai/hygiene`. Adding a new area client
+ * here is a public-API decision.
+ */
+export interface ScaiClient {
+    envName: string;
+    hygiene: HygieneApiClient;
+}
+export interface ConnectOptions {
+    /** Environment name from `sitecoreai.cli.json`. Defaults to `defaultEnvProfile`. */
+    envName?: string;
+    /** Override the config file path (directory or full path). Defaults to `process.cwd()`. */
+    configPath?: string;
+}
+export declare const connect: (options?: ConnectOptions) => ScaiClient;

package/dist/scripting/connect.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.connect = void 0;
+const environment_1 = require("../policy/environment");
+const client_1 = require("../hygiene/api/client");
+const connect = (options = {}) => {
+    const resolved = (0, environment_1.resolveEnvironment)({
+        config: options.configPath,
+        environmentName: options.envName,
+    });
+    const hygiene = (0, client_1.createHygieneApiClient)({
+        environment: resolved.environment,
+        request: resolved.timeoutMs ? { timeoutMs: resolved.timeoutMs } : undefined,
+    });
+    return { envName: resolved.envName, hygiene };
+};
+exports.connect = connect;

package/dist/scripting/helpers/multilist.d.ts

@@ -0,0 +1,26 @@
+import type { ScaiClient } from "../connect";
+export interface RemoveRefArgs {
+    itemId: string;
+    fieldName: string;
+    /** GUID to remove. Matched case-insensitively, with or without braces. */
+    refToRemove: string;
+    /** When false (default), no mutation is made — returns the diff only. */
+    allowWrite?: boolean;
+}
+export interface RemoveRefResult {
+    changed: boolean;
+    before: string;
+    after: string;
+    /** True when the helper made the wire call. False on dry-run or no-op. */
+    applied: boolean;
+}
+/**
+ * Remove a specific GUID from a multilist-shaped field on a single
+ * item. The match is case-insensitive and brace-tolerant — both
+ * `{ABC...}` and `abc...` shapes resolve to the same entry.
+ *
+ * Returns `changed: true` when the GUID was present in the field
+ * (regardless of `allowWrite`). `applied: true` only when the
+ * mutation actually reached the Authoring API.
+ */
+export declare const removeRef: (client: ScaiClient, args: RemoveRefArgs) => Promise<RemoveRefResult>;