@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/recipe/recipe-kind.d.ts

@@ -0,0 +1,4 @@
+import type { RecipeKind } from "../sync";
+import { type Recipe } from "./schema/recipe";
+/** The `recipe` (Sitecore-item) recipe kind. */
+export declare const recipeKind: RecipeKind<Recipe[]>;

package/dist/recipe/recipe-kind.js

@@ -0,0 +1,217 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recipeKind = void 0;
+/**
+ * The `recipe` recipe kind — adapts the existing Sitecore-item recipe
+ * compiler onto the kind-agnostic `sync` engine.
+ *
+ * Unlike the simple kinds (brand-kit, brief-type, campaign), the
+ * Sitecore-item kind cannot diff with a pure helper: its planner reads
+ * remote state per-operation, because later ops resolve cross-references
+ * from earlier ops' server-assigned itemIds. `plan` therefore drives the
+ * real compile → executeIr(plan) flow and stashes the compiled
+ * `OperationIr[]` in `RecipePlan.payload` so `apply` can re-run them in
+ * apply mode without recompiling.
+ *
+ * `TRecipe` is `Recipe[]` — the recipe SET. The compiler is set-oriented
+ * (cross-recipe references and the aggregate `TemplatesMapping` IR need
+ * the whole set), so a single recipe file isn't a meaningful unit here.
+ *
+ * `readCurrent` (live items → recipe) delegates to `read-current.ts` — the
+ * reverse-projection that walks the items a compiler would have produced and
+ * reconstructs four recipe kinds (component-section, component-template,
+ * content-template, enumeration). That projection is lossy by design; see
+ * its module JSDoc for the per-kind fidelity notes.
+ *
+ * See docs/recipe-sync-architecture.md.
+ */
+const zod_1 = require("zod");
+const errors_1 = require("../shared/errors");
+const environment_1 = require("../policy/environment");
+const authoring_client_1 = require("./api/authoring-client");
+const compile_1 = require("./compile");
+const execute_1 = require("./execute");
+const marker_1 = require("./marker");
+const read_current_1 = require("./read-current");
+const recipe_1 = require("./schema/recipe");
+/**
+ * Resolve the environment, the compile-time content-tree roots, and an
+ * `AuthoringApiClient` from a `SyncContext`. Bridges the engine's
+ * `SyncContext` ({@link SyncContext.environmentName} / `configPath`) onto
+ * `resolveEnvironment` the same way `runRecipePush` resolves a tenant.
+ */
+const resolveContext = (ctx) => {
+    const { envName, environment, timeoutMs } = (0, environment_1.resolveEnvironment)({
+        config: ctx.configPath,
+        environmentName: ctx.environmentName,
+    });
+    const client = (0, authoring_client_1.createAuthoringClient)({ environment, request: { timeoutMs } });
+    // The compiler's roots come straight off the env profile — the same
+    // fields `runRecipePush` reads (it additionally honors per-invocation
+    // CLI flag overrides, which the sync engine does not expose). Per-recipe
+    // compile fns throw `INPUT_INVALID` with their own clear hints when a
+    // recipe in the set needs a root the profile leaves unset.
+    const context = {
+        templatesRoot: environment.templatesRoot ?? "",
+        renderingsRoot: environment.renderingsRoot ?? "",
+        componentsRoot: environment.componentsRoot,
+        contentModelsRoot: environment.contentModelsRoot,
+        partialDesignsRoot: environment.partialDesignsRoot,
+        pageDesignsRoot: environment.pageDesignsRoot,
+        contentItemsRoot: environment.contentItemsRoot,
+        headlessVariantsRoot: environment.headlessVariantsRoot,
+        availableRenderingsRoot: environment.availableRenderingsRoot,
+        enumerationsRoot: environment.enumerationsRoot,
+        pageTemplatesRoot: environment.pageTemplatesRoot,
+        placeholderSettingsRoot: environment.placeholderSettingsRoot,
+        pagesRoot: environment.pagesRoot,
+    };
+    return { client, context, envName };
+};
+/**
+ * Map one `PlannedAction` (the recipe executor's per-op outcome) onto a
+ * `RecipeChange` (the sync engine's element-level change):
+ *
+ *   create → create   update → update   skip → noop
+ *   error  → noop, but never silently dropped: the `summary` is
+ *            `ERROR`-prefixed and the reason is carried in `meta.error`
+ *            so callers can surface the failure.
+ */
+const actionToChange = (recipeHandle, action) => {
+    const path = `${recipeHandle}.op[${action.index}]`;
+    const label = action.operation.label;
+    if (action.status === "error") {
+        return {
+            kind: "noop",
+            path,
+            summary: `ERROR ${label}: ${action.reason ?? "unknown error"}`,
+            meta: {
+                operation: action.operation.op,
+                error: action.reason ?? "unknown error",
+            },
+        };
+    }
+    const kind = action.status === "skip" ? "noop" : action.status;
+    return {
+        kind,
+        path,
+        summary: `${label}${action.reason ? ` — ${action.reason}` : ""}`,
+        ...(action.diff && action.diff.length > 0 && { meta: { diff: action.diff } }),
+    };
+};
+/** Flatten an `ExecutionResult[]` into the sync engine's `RecipeChange[]`. */
+const resultsToChanges = (irs, results) => {
+    const changes = [];
+    for (let i = 0; i < results.length; i += 1) {
+        const handle = irs[i]?.recipeHandle ?? results[i].plan.recipeHandle;
+        for (const action of results[i].plan.actions) {
+            changes.push(actionToChange(handle, action));
+        }
+    }
+    return changes;
+};
+/**
+ * Compute the plan to converge a tenant onto a recipe set.
+ *
+ * Compiles the set to `OperationIr[]`, runs each IR through the executor
+ * in `plan` mode (no writes), maps every `PlannedAction` to a
+ * `RecipeChange`, and stashes the compiled IRs in `RecipePlan.payload`
+ * so `apply` can re-execute them without recompiling.
+ */
+const plan = async (desired, _ref, ctx) => {
+    const { client, context } = resolveContext(ctx);
+    // Stamp every CreateItem op with the `Scai Handle` identity marker
+    // before planning, so the IRs carried into `apply` (via payload) write
+    // the marker too — recipe identity travels with the compiled set.
+    const irs = (0, compile_1.compileRecipeSet)(desired, context).map(marker_1.injectHandleMarker);
+    const results = [];
+    for (const ir of irs) {
+        results.push(await (0, execute_1.executeIr)(ir, client, { mode: "plan", signal: ctx.signal }));
+    }
+    const payload = { irs };
+    return { changes: resultsToChanges(irs, results), payload };
+};
+/**
+ * Apply a plan: re-execute the IRs stashed by `plan` in `apply` mode.
+ *
+ * `applied` carries every change the executor wrote (`create` / `update`);
+ * `skipped` carries the rest (`noop`, including `ERROR`-prefixed entries
+ * — an error means nothing was written for that op). The engine has
+ * already gated on write consent before calling this.
+ */
+const apply = async (recipePlan, _ref, ctx) => {
+    const payload = recipePlan.payload;
+    if (!payload || !Array.isArray(payload.irs)) {
+        throw (0, errors_1.createScaiError)("recipe apply was called with a plan that carries no compiled IRs.", "INPUT_INVALID", {
+            hint: "Run the recipe kind's `plan` first — `apply` reuses the IRs it stashes in RecipePlan.payload.",
+        });
+    }
+    const { client } = resolveContext(ctx);
+    const results = [];
+    for (const ir of payload.irs) {
+        results.push(await (0, execute_1.executeIr)(ir, client, { mode: "apply", signal: ctx.signal }));
+    }
+    const changes = resultsToChanges(payload.irs, results);
+    return {
+        applied: changes.filter((change) => change.kind === "create" || change.kind === "update"),
+        skipped: changes.filter((change) => change.kind === "noop"),
+    };
+};
+/**
+ * Capture live Sitecore items as a recipe set — the inverse of the
+ * compile → push direction.
+ *
+ * Resolves the same env/roots/`AuthoringApiClient` bridge `plan` uses, then
+ * delegates to `readCurrentRecipes`, which walks every reverse-projectable
+ * subtree under the configured roots (`componentsRoot`, `contentModelsRoot`,
+ * `templatesRoot` fallback, `enumerationsRoot`, `partialDesignsRoot`,
+ * `pageDesignsRoot`, `pagesRoot`, `placeholderSettingsRoot`) and
+ * reconstructs nine recipe kinds: component-section, component-template,
+ * content-template, page-template, enumeration, partial-design,
+ * page-design, page, and placeholder.
+ *
+ * Returns `null` only when the environment has no recipe roots configured at
+ * all; otherwise returns the recipe array, which may be empty (roots set but
+ * trees empty). The projection is lossy — see `read-current.ts` for the
+ * per-kind fidelity notes.
+ *
+ * `ref.id` is ignored for v1: `readCurrent` pulls every reverse-projectable
+ * item under the roots. Scoping the pull to one item by name is a future
+ * refinement — the engine passes the whole-set ref today.
+ */
+const readCurrent = async (_ref, ctx) => {
+    const { client, context } = resolveContext(ctx);
+    const roots = {
+        templatesRoot: context.templatesRoot,
+        renderingsRoot: context.renderingsRoot,
+        ...(context.componentsRoot !== undefined && { componentsRoot: context.componentsRoot }),
+        ...(context.contentModelsRoot !== undefined && {
+            contentModelsRoot: context.contentModelsRoot,
+        }),
+        ...(context.pageTemplatesRoot !== undefined && {
+            pageTemplatesRoot: context.pageTemplatesRoot,
+        }),
+        ...(context.enumerationsRoot !== undefined && {
+            enumerationsRoot: context.enumerationsRoot,
+        }),
+        ...(context.partialDesignsRoot !== undefined && {
+            partialDesignsRoot: context.partialDesignsRoot,
+        }),
+        ...(context.pageDesignsRoot !== undefined && {
+            pageDesignsRoot: context.pageDesignsRoot,
+        }),
+        ...(context.pagesRoot !== undefined && { pagesRoot: context.pagesRoot }),
+        ...(context.placeholderSettingsRoot !== undefined && {
+            placeholderSettingsRoot: context.placeholderSettingsRoot,
+        }),
+    };
+    return (0, read_current_1.readCurrentRecipes)(roots, client);
+};
+/** The `recipe` (Sitecore-item) recipe kind. */
+exports.recipeKind = {
+    name: "recipe",
+    schema: zod_1.z.array(recipe_1.RecipeSchema),
+    readCurrent,
+    plan,
+    apply,
+};

package/dist/recipe/rollback-log.d.ts

@@ -0,0 +1,52 @@
+/**
+ * On-disk audit log for compensating-op rollbacks during `scai provision recipe push`.
+ *
+ * When an apply phase aborts (op error, mid-flight cancel) the executor
+ * unwinds applied actions LIFO. Each step's outcome is appended to
+ * `<runId>.jsonl` under `~/.sitecoreai/rollback/` so operators can:
+ *
+ *   - tell at a glance whether rollback completed cleanly,
+ *   - find the specific items that rollback failed on (zombie state on
+ *     the tenant — the part of "best-effort" the in-memory event count
+ *     alone obscures),
+ *   - replay the rollback manually with the captured itemIds if needed.
+ *
+ * The log is lazy: nothing is written if no rollback runs. Successful
+ * pushes leave no file. Write failures (full disk, permissions) are
+ * swallowed and surfaced through `consola.debug` — never re-thrown,
+ * because the caller is already inside a failure path that has its own
+ * reason for aborting.
+ *
+ * Override the directory via `SITECOREAI_ROLLBACK_LOG_DIR`. Matches the
+ * pattern established by `src/shared/history.ts`.
+ */
+export declare const ROLLBACK_LOG_SCHEMA_VERSION = 1;
+export interface RollbackStepLog {
+    index: number;
+    label: string;
+    status: "success" | "failed" | "skip";
+    inverse?: "deleteItem" | "updateItem";
+    itemId?: string;
+    reason?: string;
+    error?: string;
+}
+export interface RollbackSummaryLog {
+    trigger: "apply-error" | "plan-error" | "cancelled";
+    rolledBack: number;
+    errorCount: number;
+    forwardError?: string;
+}
+export interface RollbackLogger {
+    readonly runId: string;
+    readonly logPath: string;
+    /** True once at least one line has been appended to the file. */
+    readonly wasUsed: boolean;
+    recordStep(recipe: string, entry: RollbackStepLog): Promise<void>;
+    recordSummary(recipe: string, entry: RollbackSummaryLog): Promise<void>;
+}
+export declare const resolveRollbackLogDir: () => string;
+export interface CreateRollbackLoggerOptions {
+    /** Override the log directory. Falls back to `resolveRollbackLogDir()`. */
+    dir?: string;
+}
+export declare const createRollbackLogger: (runId: string, options?: CreateRollbackLoggerOptions) => RollbackLogger;

package/dist/recipe/rollback-log.js

@@ -0,0 +1,90 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRollbackLogger = exports.resolveRollbackLogDir = exports.ROLLBACK_LOG_SCHEMA_VERSION = void 0;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+const consola_1 = require("consola");
+const redact_1 = require("../shared/redact");
+/**
+ * On-disk audit log for compensating-op rollbacks during `scai provision recipe push`.
+ *
+ * When an apply phase aborts (op error, mid-flight cancel) the executor
+ * unwinds applied actions LIFO. Each step's outcome is appended to
+ * `<runId>.jsonl` under `~/.sitecoreai/rollback/` so operators can:
+ *
+ *   - tell at a glance whether rollback completed cleanly,
+ *   - find the specific items that rollback failed on (zombie state on
+ *     the tenant — the part of "best-effort" the in-memory event count
+ *     alone obscures),
+ *   - replay the rollback manually with the captured itemIds if needed.
+ *
+ * The log is lazy: nothing is written if no rollback runs. Successful
+ * pushes leave no file. Write failures (full disk, permissions) are
+ * swallowed and surfaced through `consola.debug` — never re-thrown,
+ * because the caller is already inside a failure path that has its own
+ * reason for aborting.
+ *
+ * Override the directory via `SITECOREAI_ROLLBACK_LOG_DIR`. Matches the
+ * pattern established by `src/shared/history.ts`.
+ */
+exports.ROLLBACK_LOG_SCHEMA_VERSION = 1;
+const resolveRollbackLogDir = () => process.env.SITECOREAI_ROLLBACK_LOG_DIR ?? node_path_1.default.join(node_os_1.default.homedir(), ".sitecoreai", "rollback");
+exports.resolveRollbackLogDir = resolveRollbackLogDir;
+const writeLine = async (logPath, payload) => {
+    try {
+        await promises_1.default.mkdir(node_path_1.default.dirname(logPath), { recursive: true });
+        await promises_1.default.appendFile(logPath, `${JSON.stringify(payload)}\n`, "utf8");
+        return true;
+    }
+    catch (error) {
+        consola_1.consola.debug(`Unable to append rollback log at ${logPath}: ${error instanceof Error ? error.message : String(error)}`);
+        return false;
+    }
+};
+const createRollbackLogger = (runId, options = {}) => {
+    const dir = options.dir ?? (0, exports.resolveRollbackLogDir)();
+    const logPath = node_path_1.default.join(dir, `${runId}.jsonl`);
+    let used = false;
+    const append = async (payload) => {
+        const ok = await writeLine(logPath, {
+            v: exports.ROLLBACK_LOG_SCHEMA_VERSION,
+            ts: new Date().toISOString(),
+            runId,
+            ...payload,
+        });
+        if (ok)
+            used = true;
+    };
+    const sanitize = (value) => value === undefined ? undefined : (0, redact_1.redactSecrets)(value);
+    return {
+        runId,
+        logPath,
+        get wasUsed() {
+            return used;
+        },
+        recordStep: async (recipe, entry) => append({
+            kind: "step",
+            recipe,
+            index: entry.index,
+            label: entry.label,
+            status: entry.status,
+            inverse: entry.inverse,
+            itemId: entry.itemId,
+            reason: sanitize(entry.reason),
+            error: sanitize(entry.error),
+        }),
+        recordSummary: async (recipe, entry) => append({
+            kind: "summary",
+            recipe,
+            trigger: entry.trigger,
+            rolledBack: entry.rolledBack,
+            errorCount: entry.errorCount,
+            forwardError: sanitize(entry.forwardError),
+        }),
+    };
+};
+exports.createRollbackLogger = createRollbackLogger;

package/dist/recipe/rollback.d.ts

@@ -1,5 +1,6 @@
 import type { AuthoringApiClient, UpdateItemInput } from "./api/client";
 import type { PlannedAction } from "./plan";
+import type { RollbackLogger } from "./rollback-log";
 /**
  * Best-effort rollback for partial recipe pushes.
  *
@@ -49,6 +50,17 @@ export type RollbackEvent = {
 };
 export interface RollbackOptions {
     emit?: (event: RollbackEvent) => void;
+    /**
+     * On-disk audit log. When provided, each compensating-op outcome
+     * (success/skip/failure) is appended to the run's JSONL file so an
+     * operator can audit what happened — including which items rollback
+     * itself failed on. The caller is responsible for writing the run's
+     * terminal summary line after `rollback()` returns.
+     */
+    log?: {
+        logger: RollbackLogger;
+        recipe: string;
+    };
 }
 /**
  * Produce the inverse mutation for an applied action. Returns `null` when
@@ -69,4 +81,3 @@ export declare const inverseOf: (action: PlannedAction, capturedItemIds: Readonl
  * errors so a rollback failure on op N doesn't abort rollback of op N-1.
  */
 export declare const rollback: (applied: PlannedAction[], client: AuthoringApiClient, capturedItemIds: ReadonlyMap<string, string>, options?: RollbackOptions) => Promise<RollbackResult>;
-//# sourceMappingURL=rollback.d.ts.map

package/dist/recipe/rollback.js

@@ -36,14 +36,14 @@ const inverseOf = (action, capturedItemIds) => {
         return null;
     if (action.mutation.kind === "createItem") {
         if (action.operation.op !== "CreateItem") {
-            throw (0, errors_1.createCliError)("createItem mutation expected on a CreateItem operation.", "UNKNOWN");
+            throw (0, errors_1.createScaiError)("createItem mutation expected on a CreateItem operation.", "UNKNOWN");
         }
         const itemId = capturedItemIds.get(action.operation.id);
         if (!itemId) {
             // The create dispatched but we never captured its assigned itemId —
             // refuse to roll back rather than guess. Caller treats as best-effort
             // failure and continues.
-            throw (0, errors_1.createCliError)(`Rollback: no captured itemId for createItem refKey ${action.operation.id}.`, "UNKNOWN");
+            throw (0, errors_1.createScaiError)(`Rollback: no captured itemId for createItem refKey ${action.operation.id}.`, "UNKNOWN");
         }
         return { kind: "deleteItem", itemId };
     }
@@ -56,6 +56,16 @@ const inverseOf = (action, capturedItemIds) => {
         // sites explicitly; the recipe pipeline doesn't.
         return null;
     }
+    if (action.mutation.kind === "addItemVersion") {
+        // Version-add rollback is warn-only. When the item itself was created
+        // by this push, the `createItem` inverse (deleteItem) removes the whole
+        // item — versions included — so an explicit version delete is
+        // redundant. When the item pre-existed, a half-failed push can leave an
+        // empty added version behind; that's benign (no field values written)
+        // and recoverable by hand. A precise inverse would need a
+        // `deleteItemVersion` mutation — deferred.
+        return null;
+    }
     // updateItem: each touched field reverts to its prior snapshot value.
     const priorFields = action.mutation.input.fields.map((field) => {
         const prior = findPriorValue(action.snapshot, field.fieldId, field.fieldName, field.language, field.version);
@@ -79,6 +89,20 @@ exports.inverseOf = inverseOf;
  */
 const rollback = async (applied, client, capturedItemIds, options = {}) => {
     const result = { rolledBack: 0, errors: [] };
+    const log = options.log;
+    const recordStep = async (action, status, extras) => {
+        if (!log)
+            return;
+        await log.logger.recordStep(log.recipe, {
+            index: action.index,
+            label: action.operation.label,
+            status,
+            inverse: extras.inverse?.kind,
+            itemId: extras.inverse?.kind === "deleteItem" ? extras.inverse.itemId : undefined,
+            reason: extras.reason,
+            error: extras.error,
+        });
+    };
     for (let i = applied.length - 1; i >= 0; i -= 1) {
         const action = applied[i];
         let inverse;
@@ -93,14 +117,13 @@ const rollback = async (applied, client, capturedItemIds, options = {}) => {
                 error: message,
             });
             options.emit?.({ kind: "rollback-failed", action, error: message });
+            await recordStep(action, "failed", { error: message });
             continue;
         }
         if (!inverse) {
-            options.emit?.({
-                kind: "rollback-skip",
-                action,
-                reason: "no inverse needed (no forward mutation)",
-            });
+            const reason = "no inverse needed (no forward mutation)";
+            options.emit?.({ kind: "rollback-skip", action, reason });
+            await recordStep(action, "skip", { reason });
             continue;
         }
         options.emit?.({ kind: "rollback-start", action });
@@ -113,6 +136,7 @@ const rollback = async (applied, client, capturedItemIds, options = {}) => {
             }
             result.rolledBack += 1;
             options.emit?.({ kind: "rollback-success", action });
+            await recordStep(action, "success", { inverse });
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -122,6 +146,7 @@ const rollback = async (applied, client, capturedItemIds, options = {}) => {
                 error: message,
             });
             options.emit?.({ kind: "rollback-failed", action, error: message });
+            await recordStep(action, "failed", { inverse, error: message });
             // best-effort: continue with remaining rollbacks
         }
     }

package/dist/recipe/sandbox/load.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Parent side of the recipe sandbox.
+ *
+ * `.recipe.ts` is transpiled to a plain CommonJS bundle in this (trusted)
+ * process, then run in a forked child locked down with Node's permission
+ * model — no worker threads, no `child_process`, no filesystem writes, and
+ * filesystem reads scoped to the child-script and temp directories. Only
+ * the exported recipe object crosses back over IPC. See docs/recipe-sandbox.md.
+ */
+/** Whether `.recipe.ts` loading is sandboxed. `SITECOREAI_RECIPE_SANDBOX=0` opts out. */
+export declare const isRecipeSandboxEnabled: () => boolean;
+/**
+ * Compile a `.recipe.ts` and run it in the confined sandbox child; return
+ * the exported recipe object (unvalidated — the caller validates it against
+ * the schema).
+ */
+export declare const loadRecipeInSandbox: (filePath: string) => Promise<unknown>;

package/dist/recipe/sandbox/load.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * Parent side of the recipe sandbox.
+ *
+ * `.recipe.ts` is transpiled to a plain CommonJS bundle in this (trusted)
+ * process, then run in a forked child locked down with Node's permission
+ * model — no worker threads, no `child_process`, no filesystem writes, and
+ * filesystem reads scoped to the child-script and temp directories. Only
+ * the exported recipe object crosses back over IPC. See docs/recipe-sandbox.md.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadRecipeInSandbox = exports.isRecipeSandboxEnabled = void 0;
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const errors_1 = require("../../shared/errors");
+const transpile_1 = require("./transpile");
+/** Default child timeout — a recipe only exports data; it should be quick. */
+const DEFAULT_TIMEOUT_MS = 30000;
+const resolveTimeoutMs = () => {
+    const raw = Number(process.env.SITECOREAI_RECIPE_SANDBOX_TIMEOUT_MS);
+    return Number.isInteger(raw) && raw > 0 ? raw : DEFAULT_TIMEOUT_MS;
+};
+/**
+ * Environment variables the child is allowed to inherit. Everything else —
+ * crucially every `SITECOREAI_*` secret and any ambient credential — is
+ * withheld, so a hostile recipe has nothing to exfiltrate. Deny-by-default,
+ * matching the rest of the guardrails.
+ */
+const CHILD_ENV_ALLOWLIST = [
+    "PATH",
+    "HOME",
+    "USERPROFILE",
+    "TMPDIR",
+    "TEMP",
+    "TMP",
+    "SystemRoot",
+    "APPDATA",
+    "LOCALAPPDATA",
+];
+const cleanChildEnv = () => {
+    const env = {};
+    for (const key of CHILD_ENV_ALLOWLIST) {
+        const value = process.env[key];
+        if (value !== undefined) {
+            env[key] = value;
+        }
+    }
+    return env;
+};
+// The child is a plain `.cjs` shipped beside this module (copied into
+// `dist/` by the build) — runnable under bare `node`, no TypeScript
+// toolchain, which is what lets the permission model lock it down.
+const childPath = node_path_1.default.join(__dirname, "recipe-runner.cjs");
+// Symlink-resolved paths for the `--allow-fs-read` grants: Node's
+// permission model checks the canonical path, and on macOS `os.tmpdir()`
+// (and sometimes the install dir) resolves through a symlink
+// (`/var` -> `/private/var`). A grant on the un-resolved path would miss.
+const childDir = node_fs_1.default.realpathSync(node_path_1.default.dirname(childPath));
+const tmpDir = node_fs_1.default.realpathSync(node_os_1.default.tmpdir());
+/** Node permission-model flag — renamed from `--experimental-permission` in v23.5. */
+const permissionFlag = () => {
+    const major = Number(process.versions.node.split(".")[0]);
+    return major >= 24 ? "--permission" : "--experimental-permission";
+};
+/** Whether `.recipe.ts` loading is sandboxed. `SITECOREAI_RECIPE_SANDBOX=0` opts out. */
+const isRecipeSandboxEnabled = () => process.env.SITECOREAI_RECIPE_SANDBOX !== "0";
+exports.isRecipeSandboxEnabled = isRecipeSandboxEnabled;
+/**
+ * Compile a `.recipe.ts` and run it in the confined sandbox child; return
+ * the exported recipe object (unvalidated — the caller validates it against
+ * the schema).
+ */
+const loadRecipeInSandbox = async (filePath) => {
+    const compiled = await (0, transpile_1.transpileRecipe)(node_path_1.default.resolve(filePath));
+    const bundlePath = node_path_1.default.join(tmpDir, `scai-recipe-${(0, node_crypto_1.randomUUID)()}.cjs`);
+    node_fs_1.default.writeFileSync(bundlePath, compiled, "utf8");
+    try {
+        return await runInChild(filePath, bundlePath);
+    }
+    finally {
+        node_fs_1.default.rmSync(bundlePath, { force: true });
+    }
+};
+exports.loadRecipeInSandbox = loadRecipeInSandbox;
+const runInChild = (filePath, bundlePath) => {
+    const timeoutMs = resolveTimeoutMs();
+    return new Promise((resolve, reject) => {
+        const child = (0, node_child_process_1.fork)(childPath, [bundlePath], {
+            cwd: tmpDir,
+            env: cleanChildEnv(),
+            // Lock the child down with the permission model: filesystem reads
+            // scoped to the child-script directory and the temp directory, and
+            // NO --allow-worker / --allow-child-process / --allow-fs-write. The
+            // child runs only plain pre-compiled JS, so it never needs those.
+            execArgv: [permissionFlag(), `--allow-fs-read=${childDir}`, `--allow-fs-read=${tmpDir}`],
+            // Swallow the recipe's stdout; capture stderr (carries the
+            // permission-model notice) and surface it only on failure.
+            stdio: ["ignore", "ignore", "pipe", "ipc"],
+        });
+        let stderr = "";
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        let settled = false;
+        const settle = (action) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            action();
+        };
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            settle(() => reject((0, errors_1.createScaiError)(`Loading recipe '${filePath}' timed out after ${timeoutMs} ms in the sandbox.`, "INPUT_INVALID", {
+                hint: "A recipe should only export data — check for long-running or blocking code.",
+            })));
+        }, timeoutMs);
+        child.on("message", (message) => {
+            if (message && message.ok) {
+                settle(() => resolve(message.recipe));
+                return;
+            }
+            settle(() => reject((0, errors_1.createScaiError)(`Failed to load recipe '${filePath}' in the sandbox: ${message?.error ?? "unknown error"}.`, "INPUT_INVALID", {
+                hint: "A recipe may only compute and export data — filesystem writes and process spawning are blocked in the sandbox.",
+            })));
+        });
+        child.on("error", (error) => {
+            settle(() => reject((0, errors_1.createScaiError)(`Could not start the recipe sandbox for '${filePath}': ${error.message}.`, "INPUT_INVALID", { hint: "Set SITECOREAI_RECIPE_SANDBOX=0 to load recipes in-process (less safe)." })));
+        });
+        // Fires after a successful message too (the child exits 0 once it has
+        // sent the result); `settle` makes the message win that race.
+        child.on("exit", (code, signal) => {
+            settle(() => reject((0, errors_1.createScaiError)(`The recipe sandbox for '${filePath}' exited unexpectedly ` +
+                `(code ${code ?? "null"}, signal ${signal ?? "null"})` +
+                (stderr.trim() ? `: ${stderr.trim()}` : "."), "INPUT_INVALID", { hint: "Set SITECOREAI_RECIPE_SANDBOX=0 to load recipes in-process (less safe)." })));
+        });
+    });
+};