@sitecoreai-labs/sitecoreai-cli 0.1.2 → 0.2.1

package/dist/recipe/schema/recipe.js

@@ -1,8 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RecipeSchema = exports.WorkflowRecipeSchema = exports.WebhookAuthorizationRecipeSchema = exports.EnumerationRecipeSchema = exports.EnumerationValueSchema = exports.SiteRecipeSchema = exports.SiteGroupingSchema = exports.SiteTemplateRecipeSchema = exports.SiteTemplateTaxonomyEntrySchema = exports.SiteTemplateDictionaryEntrySchema = exports.PageDesignRecipeSchema = exports.PartialDesignRecipeSchema = exports.PageRecipeSchema = exports.PageTemplateRecipeSchema = exports.LayoutSchema = exports.ComponentPlacementSchema = exports.ContentItemRecipeSchema = exports.ContentVersionSchema = exports.ContentVariantSchema = exports.ContentTranslationSchema = exports.ContentFieldValueSchema = exports.SectionDefinitionRecipeSchema = exports.DesignParametersTemplateRecipeSchema = exports.ContentTemplateRecipeSchema = exports.RecipeMetaSchema = exports.RecipeMetaTaxSchema = exports.ComponentTemplateRecipeSchema = exports.ComponentSectionRecipeSchema = exports.RecipeDatasourceSchema = exports.RenderingDatasourceLocationSchema = exports.PlaceholderRecipeSchema = exports.PlaceholderDefinitionSchema = exports.RenderingVariantDefinitionSchema = exports.DesignParameterSchema = exports.FieldDefinitionSchema = exports.SitecoreFieldAugmentSchema = void 0;
+exports.RecipeSchema = exports.WorkflowRecipeSchema = exports.WebhookAuthorizationRecipeSchema = exports.EnumerationRecipeSchema = exports.EnumerationValueSchema = exports.SiteRecipeSchema = exports.SiteGroupingSchema = exports.SiteTemplateRecipeSchema = exports.SiteTemplateTaxonomyEntrySchema = exports.SiteTemplateDictionaryEntrySchema = exports.PageDesignRecipeSchema = exports.PartialDesignRecipeSchema = exports.PageRecipeSchema = exports.PageTemplateRecipeSchema = exports.LayoutSchema = exports.ComponentPlacementSchema = exports.ContentItemRecipeSchema = exports.ContentVersionSchema = exports.ContentVariantSchema = exports.ContentTranslationSchema = exports.ContentFieldValueSchema = exports.SectionDefinitionRecipeSchema = exports.DesignParametersTemplateRecipeSchema = exports.ContentTemplateRecipeSchema = exports.RecipeMetaSchema = exports.RecipeMetaTaxSchema = exports.ComponentTemplateRecipeSchema = exports.ComponentSectionRecipeSchema = exports.RecipeDatasourceSchema = exports.RenderingDatasourceLocationSchema = exports.PlaceholderRecipeSchema = exports.PlaceholderDefinitionSchema = exports.RenderingVariantDefinitionSchema = exports.DesignParameterSchema = exports.FieldDefinitionSchema = exports.SitecoreFieldAugmentSchema = exports.SitecoreFieldSourceSchema = void 0;
 const zod_1 = require("zod");
 const field_types_1 = require("./field-types");
+/**
+ * Multi-segment folder path accepted by `location.folder` /
+ * `placeholder.folder`. Two wire shapes:
+ *
+ *   Array form (canonical):    `["Theme", "Color"]`
+ *   Slash-string form (legacy): `"Theme/Color"`
+ *
+ * Both normalize to `string[]` after parsing. The registry moved its
+ * recipe schema to array form because the slash-string was implicit
+ * and fragile to author through Agent Studio (no IDE help for the
+ * segments inside the string); scai accepts both so old recipes keep
+ * working and new ones use the explicit shape. Empty segments
+ * (`""` / `"a//b"`) after split + trim are filtered out so callers
+ * don't have to remember to clean them.
+ *
+ * Downstream consumers (compile/enumeration, compile/placeholder,
+ * read-current) all see `string[]` and don't need to split anything
+ * themselves.
+ */
+const FolderPath = zod_1.z
+    .union([zod_1.z.string().min(1), zod_1.z.array(zod_1.z.string().min(1)).min(1)])
+    .transform((value) => {
+    const segments = (Array.isArray(value) ? value : value.split("/")).map((s) => s.trim());
+    return segments.filter((s) => s.length > 0);
+})
+    .pipe(zod_1.z.array(zod_1.z.string().min(1)).min(1));
 /**
  * Recipe author surface — what users hand-author for one Sitecore template.
  *
@@ -41,48 +67,77 @@ const field_types_1 = require("./field-types");
  */
 const HANDLE_PATTERN = /^[a-z][a-z0-9-]*@[0-9]+$/;
 /**
- * Sitecore-side override on a field or param. Defaults apply when omitted.
+ * The picker-scope source ("Sitecore's Source field") expressed as a
+ * discriminated union over the two real modes:
  *
- * The picker-scope concept (Sitecore's `Source` field) is expressed as
- * three composable structured fields rather than a stringly-typed
- * mini-language. They combine: e.g. `sourceScope` + `sourceTypes` becomes
- * `DataSource=<path>&IncludeTemplatesForSelection={GUID},...` on emit.
+ *   - `filter` — composable structured fields. `types` is a picker
+ *     filter restricting which recipe-defined templates appear; `query`
+ *     is a Sitecore Query; `scope` is a fixed content-tree path. They
+ *     combine, e.g. `scope + types` → `DataSource=<path>&IncludeTemplatesForSelection=...`.
+ *   - `raw` — verbatim Source string, the escape hatch. Use when the
+ *     structured surface doesn't fit (e.g. a bare path Treelist source
+ *     like `/sitecore/content/Tags`).
+ *
+ * Previously the four fields were peers on `SitecoreFieldAugment` with
+ * a `.refine` enforcing the mutex; the union makes the constraint
+ * structural so JSON Schema's `oneOf` expresses it natively and Agent
+ * Studio can't emit an invalid combination. See
+ * `docs/recipe-schema-audit.md` (A1).
+ */
+exports.SitecoreFieldSourceSchema = zod_1.z.discriminatedUnion("kind", [
+    zod_1.z.object({
+        kind: zod_1.z.literal("filter"),
+        types: zod_1.z
+            .array(zod_1.z.string())
+            .min(1)
+            .optional()
+            .describe("Picker filter: restrict to items conforming to one of these recipe handles. Compiler resolves each handle to its deterministic template GUID and emits `IncludeTemplatesForSelection={GUID},{GUID}`."),
+        query: zod_1.z
+            .string()
+            .optional()
+            .describe("Where to look: a Sitecore Query (e.g. `$site/*[@@name='Data']`). Standalone becomes `query:<query>`; combined with `types` becomes `DataSource=query:<query>&IncludeTemplatesForSelection=...`."),
+        scope: zod_1.z
+            .string()
+            .optional()
+            .describe("Where to look: a fixed Sitecore content-tree path. Emitted as `DataSource=<path>`, alone or combined with `types`."),
+    }),
+    zod_1.z.object({
+        kind: zod_1.z.literal("raw"),
+        value: zod_1.z
+            .string()
+            .min(1)
+            .describe("Verbatim Sitecore Source string. Escape hatch for Source shapes that don't fit the `filter` mode (e.g. a bare path Treelist source like `/sitecore/content/Tags`)."),
+    }),
+]);
+/**
+ * Sitecore-side override on a field or param. Defaults apply when
+ * omitted.
  *
- *   sourceTypes   — "picker filter": only items of these recipe handles.
- *   sourceQuery   — "where to look": a Sitecore Query (e.g. `$site/...`).
- *   sourceScope   — "where to look": a fixed content-tree path.
- *   sourceRaw     — escape hatch; verbatim Source string (mutually exclusive
- *                   with the structured fields).
+ * `source` carries the picker-scope shape as a discriminated union
+ * (`filter` | `raw`) — see `SitecoreFieldSourceSchema`. Internal
+ * scai code converts to a flat `SourceFields` bag via
+ * `augmentSourceToFields()` before passing to `renderSourceFields()`.
+ */
+/**
+ * Defensive guard: pre-A1 recipes carried `sourceTypes` / `sourceQuery` /
+ * `sourceScope` / `sourceRaw` as peer optional fields on the augment.
+ * After A1 the picker scope lives inside a discriminated `source`
+ * union. Without this guard Zod's default `.strip()` would silently
+ * drop the legacy keys and produce a parsed augment with no `source`
+ * — losing author intent quietly. Reject explicitly with a migration
+ * pointer instead.
  */
+const LEGACY_SOURCE_KEYS = ["sourceTypes", "sourceQuery", "sourceScope", "sourceRaw"];
 exports.SitecoreFieldAugmentSchema = zod_1.z
     .object({
     /** Override the default shape→Sitecore type mapping. */
     type: field_types_1.SitecoreFieldTypeSchema.optional(),
     /**
-     * Picker filter: restrict to items conforming to one of these recipe
-     * handles. Compiler resolves each handle to its deterministic template
-     * GUID and emits `IncludeTemplatesForSelection={GUID},{GUID}`.
+     * Picker scope — discriminated union of two modes: `filter`
+     * (composable `types` / `query` / `scope`) or `raw` (verbatim
+     * Source string). See `SitecoreFieldSourceSchema`.
      */
-    sourceTypes: zod_1.z.array(zod_1.z.string()).optional(),
-    /**
-     * Where to look: a Sitecore Query (e.g. `$site/*[@@name='Data']`).
-     * Standalone, becomes the entire Source as `query:<query>` (the
-     * shorthand Sitecore evaluates directly for Droplist-style fields).
-     * Combined with `sourceTypes`, becomes `DataSource=query:<query>&...`.
-     */
-    sourceQuery: zod_1.z.string().optional(),
-    /**
-     * Where to look: a fixed Sitecore content-tree path. Emitted as
-     * `DataSource=<path>`, alone or combined with `sourceTypes`.
-     */
-    sourceScope: zod_1.z.string().optional(),
-    /**
-     * Escape hatch: verbatim Source string. Mutually exclusive with the
-     * structured fields above. Use when you need a Source form that
-     * doesn't fit the structured surface (e.g. a bare path Treelist
-     * source like `/sitecore/content/Tags`).
-     */
-    sourceRaw: zod_1.z.string().optional(),
+    source: exports.SitecoreFieldSourceSchema.optional(),
     /** Author-facing hint surfaced in the CMS. */
     hint: zod_1.z.string().optional(),
     /** Required marker (translates to a Sitecore validation rule). */
@@ -126,10 +181,21 @@ exports.SitecoreFieldAugmentSchema = zod_1.z
      */
     storage: zod_1.z.enum(["versioned", "unversioned", "shared"]).optional(),
 })
-    .refine((v) => v.sourceRaw === undefined ||
-    (v.sourceTypes === undefined && v.sourceQuery === undefined && v.sourceScope === undefined), {
-    message: "sourceRaw is mutually exclusive with sourceTypes/sourceQuery/sourceScope",
-    path: ["sourceRaw"],
+    .passthrough()
+    .superRefine((augment, ctx) => {
+    // Pre-A1 recipes carried sourceTypes/sourceQuery/sourceScope/sourceRaw
+    // as peer fields; the new shape is `source: { kind, ... }`. Without
+    // `.passthrough()` Zod's default `.strip()` would drop those keys
+    // before the refine runs; with passthrough they survive to here and
+    // we reject loudly with a migration pointer.
+    const legacyPresent = LEGACY_SOURCE_KEYS.filter((key) => augment[key] !== undefined);
+    if (legacyPresent.length > 0) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: [legacyPresent[0]],
+            message: `Legacy source field(s) [${legacyPresent.join(", ")}] are no longer accepted on \`sitecore\`. Move them into the new \`source\` discriminated union: \`source: { kind: "filter", types/query/scope }\` or \`source: { kind: "raw", value }\`. See docs/recipe-schema-audit.md (A1).`,
+        });
+    }
 });
 exports.FieldDefinitionSchema = zod_1.z.object({
     name: zod_1.z.string().min(1),
@@ -209,7 +275,7 @@ exports.PlaceholderDefinitionSchema = zod_1.z.object({
      * Insert Options. Recipes naming the same folder share it. Omit → the
      * item lands flat at the root.
      */
-    folder: zod_1.z.string().min(1).optional(),
+    folder: FolderPath.optional(),
     /**
      * SXA dynamic placeholder. When true the host rendering must also set
      * `dynamicPlaceholders: true` so SXA generates per-instance keys; the
@@ -268,7 +334,7 @@ exports.PlaceholderRecipeSchema = zod_1.z.object({
      * Settings Folder` template (inheriting its Insert Options). Recipes
      * naming the same folder share it. Omit → flat at the root.
      */
-    folder: zod_1.z.string().min(1).optional(),
+    folder: FolderPath.optional(),
     /** SXA dynamic placeholder — see `PlaceholderDefinitionSchema.dynamic`. */
     dynamic: zod_1.z.boolean().default(false),
     /**
@@ -405,7 +471,8 @@ exports.ComponentSectionRecipeSchema = zod_1.z.object({
      */
     sortOrder: zod_1.z.number().int().optional(),
 });
-exports.ComponentTemplateRecipeSchema = zod_1.z.object({
+exports.ComponentTemplateRecipeSchema = zod_1.z
+    .object({
     kind: zod_1.z.literal("component-template"),
     schemaVersion: zod_1.z.literal("1"),
     /** Stable identifier of the form `<kebab-name>@<major>`, e.g. `cta-button@1`. */
@@ -557,7 +624,14 @@ exports.ComponentTemplateRecipeSchema = zod_1.z.object({
      * `autoCreate` / `dynamicPlaceholders` — useful for the rare case
      * where you need to force a specific value.
      */
-    otherProperties: zod_1.z.record(zod_1.z.string(), zod_1.z.string()).optional(),
+    otherProperties: zod_1.z
+        .record(zod_1.z.string(), zod_1.z.string())
+        .optional()
+        .describe("Free-form key/value pairs encoded into the rendering's `OtherProperties` URL-encoded shared field. Reserved keys `IsAutoDatasourceRendering` and `IsRenderingsWithDynamicPlaceholders` should normally be set via the typed `datasource.autoCreate` and `dynamicPlaceholders` shortcuts — overriding here silently wins and is intended only for the rare escape-hatch case."),
+})
+    .refine((recipe) => !(recipe.parameters !== undefined && recipe.params.length > 0), {
+    message: "Set either `parameters` (external template ref) or inline `params`, not both — the compiler ignores `params` when `parameters` is set, which silently drops author intent. Pick one form per recipe.",
+    path: ["params"],
 });
 /**
  * A content-only template. Has fields but no rendering — exists as a data
@@ -664,11 +738,21 @@ exports.DesignParametersTemplateRecipeSchema = zod_1.z.object({
     /** Defaults to "Office/32x32/document.png" if omitted. */
     icon: zod_1.z.string().optional(),
     /**
-     * Section name under which this parameters template lands —
-     * `Components/<section>/Presentation Parameters/<name>`. Required:
+     * Reference to a `ComponentSectionRecipe` whose section folders this
+     * parameters template lands under —
+     * `Components/<section.name>/Presentation Parameters/<name>`. Required:
      * presentation parameters are organised per-section by convention.
+     *
+     * Compile errors INPUT_INVALID if `section.handle` doesn't resolve to
+     * a `ComponentSectionRecipe` in the same recipe set. Matches the
+     * shape used by `ComponentTemplateRecipe.section` — `{ handle }` ref,
+     * not a bare section name string.
      */
-    section: zod_1.z.string().min(1),
+    section: zod_1.z.object({
+        handle: zod_1.z.string().regex(HANDLE_PATTERN, {
+            message: "section.handle must match `<kebab-name>@<major>`",
+        }),
+    }),
     params: zod_1.z.array(exports.DesignParameterSchema).default([]),
 });
 /**
@@ -1486,7 +1570,7 @@ exports.EnumerationRecipeSchema = zod_1.z.object({
     location: zod_1.z
         .object({
         scope: zod_1.z.enum(["site", "siteCollection"]),
-        folder: zod_1.z.string().min(1).optional(),
+        folder: FolderPath.optional(),
     })
         .optional(),
     values: zod_1.z.array(exports.EnumerationValueSchema).min(1),

package/dist/recipe/schema/source-fields.d.ts

@@ -45,3 +45,23 @@ export declare const renderSourceFields: (fields: SourceFields, resolveHandle: (
  * `ref-source-fields`.
  */
 export declare const sourceFieldsNeedHandleResolution: (fields: SourceFields) => boolean;
+/**
+ * Convert the author-surface `SitecoreFieldSource` discriminated union
+ * to the flat `SourceFields` bag the renderer + IR consume. Internal
+ * adapter — author surface stays union-shaped (clean for JSON Schema
+ * and Agent Studio), compiler internals stay flat-shaped (clean for
+ * `renderSourceFields` and the `ref-source-fields` IR op).
+ *
+ * Returns an empty bag when `source` is undefined, so callers can
+ * unconditionally invoke this and feed the result to
+ * `renderSourceFields` / `sourceFieldsNeedHandleResolution`.
+ */
+export declare const augmentSourceToFields: (source: {
+    kind: "filter";
+    types?: readonly string[];
+    query?: string;
+    scope?: string;
+} | {
+    kind: "raw";
+    value: string;
+} | undefined) => SourceFields;

package/dist/recipe/schema/source-fields.js

@@ -25,7 +25,7 @@
  * `/sitecore/content/Tags` Treelist source) use `sourceRaw`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sourceFieldsNeedHandleResolution = exports.renderSourceFields = void 0;
+exports.augmentSourceToFields = exports.sourceFieldsNeedHandleResolution = exports.renderSourceFields = void 0;
 const formatGuidCurly = (guid) => `{${guid.toUpperCase()}}`;
 /**
  * Compose structured source fields into the Sitecore-encoded Source string.
@@ -77,3 +77,27 @@ exports.renderSourceFields = renderSourceFields;
  */
 const sourceFieldsNeedHandleResolution = (fields) => Array.isArray(fields.sourceTypes) && fields.sourceTypes.length > 0;
 exports.sourceFieldsNeedHandleResolution = sourceFieldsNeedHandleResolution;
+/**
+ * Convert the author-surface `SitecoreFieldSource` discriminated union
+ * to the flat `SourceFields` bag the renderer + IR consume. Internal
+ * adapter — author surface stays union-shaped (clean for JSON Schema
+ * and Agent Studio), compiler internals stay flat-shaped (clean for
+ * `renderSourceFields` and the `ref-source-fields` IR op).
+ *
+ * Returns an empty bag when `source` is undefined, so callers can
+ * unconditionally invoke this and feed the result to
+ * `renderSourceFields` / `sourceFieldsNeedHandleResolution`.
+ */
+const augmentSourceToFields = (source) => {
+    if (!source)
+        return {};
+    if (source.kind === "raw") {
+        return { sourceRaw: source.value };
+    }
+    return {
+        sourceTypes: source.types,
+        sourceQuery: source.query,
+        sourceScope: source.scope,
+    };
+};
+exports.augmentSourceToFields = augmentSourceToFields;

package/dist/recipe/validate.d.ts

@@ -10,8 +10,8 @@ import type { Recipe } from "./schema/recipe";
  * Reference inventory checked:
  *
  *   ComponentTemplateRecipe / ContentTemplateRecipe
- *     fields[*].sitecore.sourceTypes[*]   → any template-bearing recipe
- *     params[*].sitecore.sourceTypes[*]   → any template-bearing recipe
+ *     fields[*].sitecore.source.types[*]   → any template-bearing recipe
+ *     params[*].sitecore.source.types[*]  → any template-bearing recipe
  *     insertOptions[*]                    → any template-bearing recipe
  *
  *   ComponentTemplateRecipe
@@ -23,7 +23,7 @@ import type { Recipe } from "./schema/recipe";
  *     fields[*].reference.refs[*]         → any recipe
  *
  *   PageTemplateRecipe
- *     fields[*].sitecore.sourceTypes[*]   → any template-bearing recipe
+ *     fields[*].sitecore.source.types[*]   → any template-bearing recipe
  *     insertOptions[*]                    → PageTemplateRecipe
  *     layout.placeholders[*][*].componentHandle           → ComponentTemplateRecipe
  *     layout.placeholders[*][*].datasourceRef.handle      → ContentItemRecipe

package/dist/recipe/validate.js

@@ -5,6 +5,16 @@ exports.formatValidationErrors = formatValidationErrors;
 exports.validateRecipeSet = validateRecipeSet;
 exports.validateRecipeSetOrThrow = validateRecipeSetOrThrow;
 const errors_1 = require("../shared/errors");
+/**
+ * The picker-scope handles to validate on a `SitecoreFieldAugment`.
+ * Empty when the augment is absent OR uses the `raw` source mode
+ * (verbatim Source string; nothing to resolve).
+ */
+const sourceTypesOf = (augment) => {
+    if (augment?.source?.kind !== "filter")
+        return [];
+    return augment.source.types ?? [];
+};
 const TEMPLATE_KINDS = [
     "component-template",
     "content-template",
@@ -184,13 +194,13 @@ function validateRecipeSet(recipes) {
         switch (recipe.kind) {
             case "component-template":
                 recipe.fields.forEach((field, idx) => {
-                    field.sitecore?.sourceTypes?.forEach((handle, sIdx) => {
-                        checkRef(recipe.handle, `fields.${idx}.sitecore.sourceTypes.${sIdx}`, handle, TEMPLATE_KINDS);
+                    sourceTypesOf(field.sitecore).forEach((handle, sIdx) => {
+                        checkRef(recipe.handle, `fields.${idx}.sitecore.source.types.${sIdx}`, handle, TEMPLATE_KINDS);
                     });
                 });
                 recipe.params.forEach((param, idx) => {
-                    param.sitecore?.sourceTypes?.forEach((handle, sIdx) => {
-                        checkRef(recipe.handle, `params.${idx}.sitecore.sourceTypes.${sIdx}`, handle, TEMPLATE_KINDS);
+                    sourceTypesOf(param.sitecore).forEach((handle, sIdx) => {
+                        checkRef(recipe.handle, `params.${idx}.sitecore.source.types.${sIdx}`, handle, TEMPLATE_KINDS);
                     });
                 });
                 recipe.insertOptions?.forEach((handle, idx) => {
@@ -216,8 +226,8 @@ function validateRecipeSet(recipes) {
                 break;
             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);
+                    sourceTypesOf(param.sitecore).forEach((handle, sIdx) => {
+                        checkRef(recipe.handle, `params.${idx}.sitecore.source.types.${sIdx}`, handle, TEMPLATE_KINDS);
                     });
                 });
                 break;
@@ -227,8 +237,8 @@ function validateRecipeSet(recipes) {
                 break;
             case "content-template":
                 recipe.fields.forEach((field, idx) => {
-                    field.sitecore?.sourceTypes?.forEach((handle, sIdx) => {
-                        checkRef(recipe.handle, `fields.${idx}.sitecore.sourceTypes.${sIdx}`, handle, TEMPLATE_KINDS);
+                    sourceTypesOf(field.sitecore).forEach((handle, sIdx) => {
+                        checkRef(recipe.handle, `fields.${idx}.sitecore.source.types.${sIdx}`, handle, TEMPLATE_KINDS);
                     });
                 });
                 recipe.insertOptions?.forEach((handle, idx) => {
@@ -280,8 +290,8 @@ function validateRecipeSet(recipes) {
                 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);
+                    sourceTypesOf(field.sitecore).forEach((handle, sIdx) => {
+                        checkRef(recipe.handle, `fields.${idx}.sitecore.source.types.${sIdx}`, handle, TEMPLATE_KINDS);
                     });
                 });
                 recipe.insertOptions?.forEach((handle, idx) => {

package/dist/sync/aggregate-kinds.js

@@ -29,4 +29,5 @@ const recipe_2 = require("../brief/recipe");
 exports.ENUMERABLE_RECIPE_KINDS = [
     recipe_1.brandKitKind,
     recipe_2.briefTypeKind,
+    recipe_2.briefInstanceKind,
 ];

package/dist/sync/aggregate.js

@@ -102,7 +102,7 @@ const aggregateStatus = async (kinds, ctx, options = {}) => {
         }
         const items = [];
         for (const file of files) {
-            const recipe = (0, io_1.loadRecipe)(file, kind.schema);
+            const recipe = await (0, io_1.loadRecipe)(file, kind.schema);
             const id = recipeId(recipe);
             try {
                 const plan = await (0, engine_1.syncDiff)(kind, recipe, { kind: kind.name, id }, ctx);
@@ -139,7 +139,7 @@ const aggregatePush = async (kinds, ctx, options) => {
         }
         const items = [];
         for (const file of files) {
-            const recipe = (0, io_1.loadRecipe)(file, kind.schema);
+            const recipe = await (0, io_1.loadRecipe)(file, kind.schema);
             const id = recipeId(recipe);
             try {
                 const outcome = await (0, engine_1.syncPush)(kind, recipe, { kind: kind.name, id }, ctx, {

package/dist/sync/io.d.ts

@@ -1,8 +1,18 @@
 import type { ZodType } from "zod";
 /**
- * Read, parse, and schema-validate a recipe file. YAML is a superset of
- * JSON, so `.yaml`, `.yml`, and `.json` all parse through the same path.
+ * Read, parse, and schema-validate a recipe file. The on-disk format is
+ * picked from the file extension:
+ *
+ *   - `.ts` / `.tsx` / `.mts` / `.cts` → transpiled + executed in the
+ *     recipe sandbox; the default export (or first named export) is
+ *     Zod-parsed.
+ *   - everything else → read as text and run through the YAML parser
+ *     (which also accepts JSON).
+ *
+ * Async because the TypeScript path forks a child process. All current
+ * call sites already run inside `async` task runners or commander
+ * `command.action(async …)` handlers.
  */
-export declare const loadRecipe: <T>(filePath: string, schema: ZodType<T>) => T;
+export declare const loadRecipe: <T>(filePath: string, schema: ZodType<T>) => Promise<T>;
 /** Serialize a recipe to a file — JSON when the path ends `.json`, else YAML. */
 export declare const writeRecipe: (filePath: string, recipe: unknown) => void;

package/dist/sync/io.js

@@ -2,21 +2,56 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.writeRecipe = exports.loadRecipe = void 0;
 /**
- * Recipe file I/O for the `sync` engine — load a recipe from a YAML or
- * JSON file and validate it against a kind's schema, or serialize a
- * captured recipe back to disk.
+ * Recipe file I/O for the `sync` engine — load a recipe from a YAML,
+ * JSON, or TypeScript file and validate it against a kind's schema, or
+ * serialize a captured recipe back to disk.
  *
- * See docs/recipe-sync-architecture.md.
+ * Three on-disk formats are supported, all kinds, one loader:
+ *
+ *   - `.ts` / `.tsx` / `.mts` / `.cts` — TypeScript source. Loaded via
+ *     the sandboxed transpile path (`@/sync/typescript-recipe`) so a
+ *     hostile authored recipe cannot run with scai's privileges.
+ *     Authors get Zod-derived `satisfies` checks at write time.
+ *   - `.yaml` / `.yml` — YAML.
+ *   - `.json` — JSON (parsed through the YAML parser; YAML is a superset).
+ *
+ * See docs/recipe-sync-architecture.md and docs/recipe-sandbox.md.
  */
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const yaml_1 = require("yaml");
 const errors_1 = require("../shared/errors");
+const typescript_recipe_1 = require("./typescript-recipe");
 /**
- * Read, parse, and schema-validate a recipe file. YAML is a superset of
- * JSON, so `.yaml`, `.yml`, and `.json` all parse through the same path.
+ * Read, parse, and schema-validate a recipe file. The on-disk format is
+ * picked from the file extension:
+ *
+ *   - `.ts` / `.tsx` / `.mts` / `.cts` → transpiled + executed in the
+ *     recipe sandbox; the default export (or first named export) is
+ *     Zod-parsed.
+ *   - everything else → read as text and run through the YAML parser
+ *     (which also accepts JSON).
+ *
+ * Async because the TypeScript path forks a child process. All current
+ * call sites already run inside `async` task runners or commander
+ * `command.action(async …)` handlers.
  */
-const loadRecipe = (filePath, schema) => {
+const loadRecipe = async (filePath, schema) => {
+    const parsed = (0, typescript_recipe_1.isTypeScriptRecipePath)(filePath)
+        ? await (0, typescript_recipe_1.loadTypeScriptRecipe)(filePath)
+        : parseYamlOrJsonRecipe(filePath);
+    const result = schema.safeParse(parsed);
+    if (!result.success) {
+        throw (0, errors_1.createScaiError)(`Recipe file "${filePath}" failed schema validation`, "INPUT_INVALID", {
+            details: result.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`),
+        });
+    }
+    return result.data;
+};
+exports.loadRecipe = loadRecipe;
+/** Read and YAML-parse a recipe file. YAML is a superset of JSON, so
+ * `.yaml`, `.yml`, and `.json` all go through the same path. */
+const parseYamlOrJsonRecipe = (filePath) => {
     let raw;
     try {
         raw = (0, node_fs_1.readFileSync)(filePath, "utf8");
@@ -26,24 +61,15 @@ const loadRecipe = (filePath, schema) => {
             hint: error instanceof Error ? error.message : undefined,
         });
     }
-    let parsed;
     try {
-        parsed = (0, yaml_1.parse)(raw);
+        return (0, yaml_1.parse)(raw);
     }
     catch (error) {
         throw (0, errors_1.createScaiError)(`Recipe file "${filePath}" is not valid YAML/JSON`, "INPUT_INVALID", {
             hint: error instanceof Error ? error.message : undefined,
         });
     }
-    const result = schema.safeParse(parsed);
-    if (!result.success) {
-        throw (0, errors_1.createScaiError)(`Recipe file "${filePath}" failed schema validation`, "INPUT_INVALID", {
-            details: result.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`),
-        });
-    }
-    return result.data;
 };
-exports.loadRecipe = loadRecipe;
 /** Serialize a recipe to a file — JSON when the path ends `.json`, else YAML. */
 const writeRecipe = (filePath, recipe) => {
     const serialized = (0, node_path_1.extname)(filePath) === ".json" ? `${JSON.stringify(recipe, null, 2)}\n` : (0, yaml_1.stringify)(recipe);

package/dist/sync/typescript-recipe.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared `.recipe.ts` loader.
+ *
+ * Authored recipes (CMS, brand-kit, agents, campaigns, briefs, etc.) all
+ * load through this path so end users can write `.recipe.ts` files with
+ * Zod-derived types and `satisfies` checks. The transpile + sandboxed
+ * execute machinery is owned by `@/recipe/sandbox` — this module is the
+ * thin wrapper that picks between the confined child and the legacy
+ * in-process tsx loader, and is consumed by both:
+ *
+ *   - `src/sync/io.ts:loadRecipe` (schema-aware loader used by brand,
+ *     agents, campaigns, briefs, …)
+ *   - `src/recipe/io.ts:loadRecipe` (CMS recipe discriminated-union loader)
+ *
+ * Output is unvalidated — callers Zod-parse the returned value. See
+ * docs/recipe-sandbox.md.
+ */
+/** Whether the given file path should be loaded via the TypeScript path. */
+export declare const isTypeScriptRecipePath: (filePath: string) => boolean;
+/**
+ * Load a `.recipe.ts` (or `.tsx`/`.mts`/`.cts`) file and return its
+ * exported recipe value. By default the file is loaded in a confined
+ * child process (see docs/recipe-sandbox.md) so a hostile recipe cannot
+ * run with scai's full privileges. `SITECOREAI_RECIPE_SANDBOX=0` forces
+ * the legacy in-process loader (useful for debugging — the warning lands
+ * on stderr so JSON-mode CLI streams are not corrupted).
+ *
+ * The result is unvalidated: callers Zod-parse it.
+ */
+export declare const loadTypeScriptRecipe: (filePath: string) => Promise<unknown>;