@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.1

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

@@ -45,4 +45,3 @@ export declare const renderSourceFields: (fields: SourceFields, resolveHandle: (
  * `ref-source-fields`.
  */
 export declare const sourceFieldsNeedHandleResolution: (fields: SourceFields) => boolean;
-//# sourceMappingURL=source-fields.d.ts.map

package/dist/recipe/tasks/compile.d.ts

@@ -1,6 +1,6 @@
 import { type RecipeCompileOptions } from "./shared";
 /**
- * `scai recipe compile` — pure-logic: recipe (.ts or .json) → Operation IR JSON.
+ * `scai provision recipe compile` — pure-logic: recipe (.ts or .json) → Operation IR JSON.
  *
  * Resolves inputs from `--input` (single file) or the config `recipes`
  * glob (zero-to-many files). Writes one IR per recipe at
@@ -11,4 +11,3 @@ import { type RecipeCompileOptions } from "./shared";
  * lands in a different tenant tree.
  */
 export declare const runRecipeCompile: (options: RecipeCompileOptions) => Promise<void>;
-//# sourceMappingURL=compile.d.ts.map

package/dist/recipe/tasks/compile.js

@@ -5,13 +5,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runRecipeCompile = void 0;
 const node_path_1 = __importDefault(require("node:path"));
-const config_1 = require("../../config");
+const root_config_1 = require("../../config/root-config");
 const errors_1 = require("../../shared/errors");
 const compile_1 = require("../compile");
 const io_1 = require("../io");
 const shared_1 = require("./shared");
 /**
- * `scai recipe compile` — pure-logic: recipe (.ts or .json) → Operation IR JSON.
+ * `scai provision recipe compile` — pure-logic: recipe (.ts or .json) → Operation IR JSON.
  *
  * Resolves inputs from `--input` (single file) or the config `recipes`
  * glob (zero-to-many files). Writes one IR per recipe at
@@ -23,11 +23,22 @@ const shared_1 = require("./shared");
  */
 const runRecipeCompile = async (options) => {
     const logger = (0, shared_1.toLogger)(options);
-    const root = (0, config_1.readRootConfiguration)(options.config ?? process.cwd(), options.environmentName);
-    // Resolve parent paths from CLI flags or active env profile (when given).
+    const root = (0, root_config_1.readRootConfiguration)(options.config ?? process.cwd(), options.environmentName);
     const envName = options.environmentName ?? root.defaultEnvironment;
     const environment = envName ? root.environments[envName] : undefined;
-    const { templatesRoot, renderingsRoot } = (0, shared_1.resolveRecipeRoots)(options, environment, envName ?? "(no environment)");
+    const { files, source } = await (0, shared_1.resolveRecipeInputs)(options, root);
+    if (options.output && files.length > 1) {
+        throw (0, errors_1.createScaiError)("--output cannot be combined with multi-file compile.", "INPUT_INVALID", {
+            hint: "Compile a single recipe with --input <file> --output <ir>, or omit --output to write per-recipe IRs to <dir>/<handle>.ir.json.",
+        });
+    }
+    // Load every recipe up front so the templatesRoot / renderingsRoot
+    // requirement can be scoped to what the set actually compiles — a
+    // workflow- / webhook-authorization-only set creates its items under
+    // hardcoded /sitecore/system roots and needs neither.
+    const loaded = await Promise.all(files.map(async (file) => ({ file, recipe: await (0, io_1.loadRecipe)(file) })));
+    // Resolve parent paths from CLI flags or active env profile (when given).
+    const { templatesRoot, renderingsRoot } = (0, shared_1.resolveRecipeRoots)(options, environment, envName ?? "(no environment)", (0, shared_1.recipeSetNeedsRoots)(loaded.map((entry) => entry.recipe)));
     // Phase 2 per-site folder layout roots — optional. When unset the
     // compiler falls back to `templatesRoot` for both, which means
     // section-aware components nest under templatesRoot (mid-migration
@@ -44,15 +55,15 @@ const runRecipeCompile = async (options) => {
     const headlessVariantsRoot = options.headlessVariantsRoot ?? environment?.headlessVariantsRoot;
     const availableRenderingsRoot = options.availableRenderingsRoot ?? environment?.availableRenderingsRoot;
     const enumerationsRoot = options.enumerationsRoot ?? environment?.enumerationsRoot;
-    const { files, source } = await (0, shared_1.resolveRecipeInputs)(options, root);
-    if (options.output && files.length > 1) {
-        throw (0, errors_1.createCliError)("--output cannot be combined with multi-file compile.", "INPUT_INVALID", {
-            hint: "Compile a single recipe with --input <file> --output <ir>, or omit --output to write per-recipe IRs to <dir>/<handle>.ir.json.",
-        });
-    }
+    // Page-level roots. `pageTemplatesRoot` falls back to `templatesRoot`
+    // inside the compiler; `placeholderSettingsRoot` has no fallback —
+    // `buildPlaceholderSettingsAggregate` errors when a set declares
+    // placeholders but the root is unset.
+    const pageTemplatesRoot = environment?.pageTemplatesRoot;
+    const placeholderSettingsRoot = environment?.placeholderSettingsRoot;
+    const pagesRoot = environment?.pagesRoot;
     const results = [];
-    for (const file of files) {
-        const recipe = await (0, io_1.loadRecipe)(file);
+    for (const { file, recipe } of loaded) {
         const ir = (0, compile_1.compileRecipe)(recipe, {
             templatesRoot,
             renderingsRoot,
@@ -64,6 +75,9 @@ const runRecipeCompile = async (options) => {
             headlessVariantsRoot,
             availableRenderingsRoot,
             enumerationsRoot,
+            pageTemplatesRoot,
+            placeholderSettingsRoot,
+            pagesRoot,
         });
         const outputPath = options.output ?? (0, io_1.defaultIrPath)(recipe.handle, node_path_1.default.dirname(node_path_1.default.resolve(file)));
         await (0, io_1.writeIr)(outputPath, ir);

package/dist/recipe/tasks/diff.d.ts

@@ -1,7 +1,7 @@
 import type { ExecutionResult } from "../execute";
 import type { RecipePushOptions } from "./shared";
 /**
- * `scai recipe diff` — read-only "what would change" against a tenant.
+ * `scai provision recipe diff` — read-only "what would change" against a tenant.
  *
  * Drives the same input resolution, in-memory compile, and planner
  * as `recipe push`, but read-only by construction: `whatIf` is forced
@@ -14,4 +14,3 @@ import type { RecipePushOptions } from "./shared";
  */
 export type RecipeDiffOptions = Omit<RecipePushOptions, "whatIf" | "allowWrite">;
 export declare const runRecipeDiff: (options: RecipeDiffOptions) => Promise<ExecutionResult[]>;
-//# sourceMappingURL=diff.d.ts.map

package/dist/recipe/tasks/placeholder-allow.d.ts

@@ -50,4 +50,3 @@ export interface PlaceholderAllowOptions {
  *     other matches still apply.
  */
 export declare const applyPlaceholderAllowControls: (options: PlaceholderAllowOptions) => Promise<PlaceholderAllowResult>;
-//# sourceMappingURL=placeholder-allow.d.ts.map

package/dist/recipe/tasks/placeholder-allow.js

@@ -55,8 +55,7 @@ const collectPlaceholders = async (client, roots) => {
         if (!item)
             return;
         if (isPlaceholder(item)) {
-            const keyField = item.fields.find((f) => normaliseGuid(f.fieldId) ===
-                normaliseGuid(sitecore_templates_1.PLACEHOLDER_FIELDS.PLACEHOLDER_KEY));
+            const keyField = item.fields.find((f) => normaliseGuid(f.fieldId) === normaliseGuid(sitecore_templates_1.PLACEHOLDER_FIELDS.PLACEHOLDER_KEY));
             const placeholderKey = keyField?.value?.trim();
             if (placeholderKey) {
                 found.push({ item, placeholderKey });
@@ -76,8 +75,7 @@ const collectPlaceholders = async (client, roots) => {
     return found;
 };
 const findAllowedControlsValue = (item) => {
-    const field = item.fields.find((f) => normaliseGuid(f.fieldId) ===
-        normaliseGuid(sitecore_templates_1.PLACEHOLDER_FIELDS.ALLOWED_CONTROLS));
+    const field = item.fields.find((f) => normaliseGuid(f.fieldId) === normaliseGuid(sitecore_templates_1.PLACEHOLDER_FIELDS.ALLOWED_CONTROLS));
     return field?.value ?? "";
 };
 const splitMultilist = (value) => value
@@ -143,9 +141,7 @@ const applyPlaceholderAllowControls = async (options) => {
         const keys = recipe.placedIn ?? [];
         if (keys.length === 0)
             continue;
-        const sectionName = recipe.section
-            ? sectionsByHandle.get(recipe.section.handle)
-            : undefined;
+        const sectionName = recipe.section ? sectionsByHandle.get(recipe.section.handle) : undefined;
         const renderingItemId = await resolveRenderingItemId(client, renderingsRoot, recipe, sectionName);
         if (!renderingItemId) {
             unresolvedRecipeHandles.push(recipe.handle);

package/dist/recipe/tasks/plan.d.ts

@@ -1,11 +1,10 @@
 import { type Plan } from "../plan";
 import { type RecipePlanOptions } from "./shared";
 /**
- * `scai recipe plan` — read-then-diff against a tenant, no mutations.
+ * `scai provision recipe plan` — read-then-diff against a tenant, no mutations.
  *
- * Operates on a pre-compiled IR file (the artifact from `scai recipe
- * compile`). For the recipe-source workflow, use `scai recipe push
+ * Operates on a pre-compiled IR file (the artifact from `scai provision recipe
+ * compile`). For the recipe-source workflow, use `scai provision recipe push
  * --what-if` instead — it compiles in-memory and runs the planner.
  */
 export declare const runRecipePlan: (options: RecipePlanOptions) => Promise<Plan>;
-//# sourceMappingURL=plan.d.ts.map

package/dist/recipe/tasks/plan.js

@@ -10,18 +10,18 @@ const io_1 = require("../io");
 const plan_1 = require("../plan");
 const shared_1 = require("./shared");
 /**
- * `scai recipe plan` — read-then-diff against a tenant, no mutations.
+ * `scai provision recipe plan` — read-then-diff against a tenant, no mutations.
  *
- * Operates on a pre-compiled IR file (the artifact from `scai recipe
- * compile`). For the recipe-source workflow, use `scai recipe push
+ * Operates on a pre-compiled IR file (the artifact from `scai provision recipe
+ * compile`). For the recipe-source workflow, use `scai provision recipe push
  * --what-if` instead — it compiles in-memory and runs the planner.
  */
 const runRecipePlan = async (options) => {
     const logger = (0, shared_1.toLogger)(options);
     const tenant = (0, shared_1.resolveTenant)(options);
     if (!options.input) {
-        throw (0, errors_1.createCliError)("--input <ir.json> is required for `recipe plan`.", "INPUT_INVALID", {
-            hint: "Run `scai recipe compile` first, or use `scai recipe push --what-if` to plan from a recipe source.",
+        throw (0, errors_1.createScaiError)("--input <ir.json> is required for `recipe plan`.", "INPUT_INVALID", {
+            hint: "Run `scai provision recipe compile` first, or use `scai provision recipe push --what-if` to plan from a recipe source.",
         });
     }
     const ir = await (0, io_1.loadIr)(options.input);

package/dist/recipe/tasks/prune-defaults.d.ts

@@ -2,7 +2,7 @@ import { Logger } from "../../shared/logger";
 import type { AuthoringApiClient } from "../api/client";
 import { type RecipeTenantOptions } from "./shared";
 /**
- * `scai recipe prune-defaults` — remove the SXA Headless OOTB content
+ * `scai provision recipe prune-defaults` — remove the SXA Headless OOTB content
  * that ships with every fresh site under `Available Renderings`,
  * `Headless Variants`, and the per-site `Data` bucket. Registry installs
  * ship their own renderings, variants, and datasources; the OOTB folders
@@ -87,4 +87,3 @@ interface PruneCoreOptions {
 export declare const pruneDefaultsAgainstClient: (options: PruneCoreOptions) => Promise<PruneAction[]>;
 export declare const runRecipePruneDefaults: (options: RecipePruneDefaultsOptions) => Promise<RecipePruneDefaultsResult>;
 export {};
-//# sourceMappingURL=prune-defaults.d.ts.map

package/dist/recipe/tasks/prune-defaults.js

@@ -4,7 +4,7 @@ exports.runRecipePruneDefaults = exports.pruneDefaultsAgainstClient = void 0;
 const errors_1 = require("../../shared/errors");
 const shared_1 = require("./shared");
 /**
- * `scai recipe prune-defaults` — remove the SXA Headless OOTB content
+ * `scai provision recipe prune-defaults` — remove the SXA Headless OOTB content
  * that ships with every fresh site under `Available Renderings`,
  * `Headless Variants`, and the per-site `Data` bucket. Registry installs
  * ship their own renderings, variants, and datasources; the OOTB folders
@@ -73,7 +73,7 @@ const buildTargets = (availableRenderingsRoot, headlessVariantsRoot, contentItem
 /**
  * Detect the Authoring GraphQL "item is gone" response. The shared
  * graphql.ts wrapper joins all error.message strings into a single
- * `Authoring GraphQL errors: <messages>` payload on a NETWORK CliError;
+ * `Authoring GraphQL errors: <messages>` payload on a NETWORK ScaiError;
  * we match the canonical Sitecore phrasing that fires when an itemId
  * doesn't resolve at delete time.
  */
@@ -81,8 +81,7 @@ const isItemNotFoundError = (error) => {
     if (!(error instanceof Error))
         return false;
     const message = error.message;
-    return (message.includes("was not found") ||
-        message.includes("may have been deleted by another user"));
+    return (message.includes("was not found") || message.includes("may have been deleted by another user"));
 };
 /**
  * Pure(ish) deletion loop — exposed for unit tests so they can drive
@@ -90,7 +89,7 @@ const isItemNotFoundError = (error) => {
  * threading a full sitecoreai.cli.json through `resolveTenant`.
  */
 const pruneDefaultsAgainstClient = async (options) => {
-    const { client, availableRenderingsRoot, headlessVariantsRoot, contentItemsRoot, whatIf, logger } = options;
+    const { client, availableRenderingsRoot, headlessVariantsRoot, contentItemsRoot, whatIf, logger, } = options;
     const targets = buildTargets(availableRenderingsRoot, headlessVariantsRoot, contentItemsRoot);
     const actions = [];
     for (const target of targets) {
@@ -116,7 +115,7 @@ const pruneDefaultsAgainstClient = async (options) => {
         catch (error) {
             // Authoring GraphQL surfaces concurrent-delete as a "was not found"
             // / "may have been deleted by another user" message wrapped in a
-            // NETWORK CliError. Treat as a clean skip — the post-condition
+            // NETWORK ScaiError. Treat as a clean skip — the post-condition
             // (item gone) is satisfied either way.
             if (isItemNotFoundError(error)) {
                 actions.push({ ...target, status: "missing", itemId: existing.itemId });
@@ -147,7 +146,7 @@ const runRecipePruneDefaults = async (options) => {
         ]
             .filter(Boolean)
             .join(", ");
-        throw (0, errors_1.createCliError)(`Recipe prune-defaults missing root path(s): ${missing} not configured for environment '${tenant.envName}'.`, "INPUT_INVALID", {
+        throw (0, errors_1.createScaiError)(`Recipe prune-defaults missing root path(s): ${missing} not configured for environment '${tenant.envName}'.`, "INPUT_INVALID", {
             hint: `Add 'headlessVariantsRoot', 'availableRenderingsRoot', and 'contentItemsRoot' to envProfiles.${tenant.envName} in sitecoreai.cli.json (or pass --headless-variants-root / --available-renderings-root / --content-items-root).`,
         });
     }

package/dist/recipe/tasks/push.d.ts

@@ -1,7 +1,7 @@
 import { type ExecutionResult } from "../execute";
 import { type RecipePushOptions } from "./shared";
 /**
- * `scai recipe push` — apply recipes to a tenant.
+ * `scai provision recipe push` — apply recipes to a tenant.
  *
  * Input resolution:
  *   - `--input <file>` — single recipe (`.recipe.ts/.recipe.json`) or IR
@@ -15,4 +15,3 @@ import { type RecipePushOptions } from "./shared";
  * events in JSON mode; renders a per-op summary in human mode.
  */
 export declare const runRecipePush: (options: RecipePushOptions) => Promise<ExecutionResult[]>;
-//# sourceMappingURL=push.d.ts.map

package/dist/recipe/tasks/push.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runRecipePush = void 0;
+const node_crypto_1 = require("node:crypto");
 const node_path_1 = __importDefault(require("node:path"));
 const cli_tasks_1 = require("../../shared/cli-tasks");
 const errors_1 = require("../../shared/errors");
@@ -15,6 +16,7 @@ const guids_1 = require("../guids");
 const io_1 = require("../io");
 const execute_1 = require("../execute");
 const placeholder_allow_1 = require("./placeholder-allow");
+const rollback_log_1 = require("../rollback-log");
 const shared_1 = require("./shared");
 const DEFAULT_PLAN_CONCURRENCY = 4;
 /**
@@ -62,7 +64,7 @@ const collectPrefetchPaths = (irs, crossRecipeRefs) => {
     return out;
 };
 /**
- * `scai recipe push` — apply recipes to a tenant.
+ * `scai provision recipe push` — apply recipes to a tenant.
  *
  * Input resolution:
  *   - `--input <file>` — single recipe (`.recipe.ts/.recipe.json`) or IR
@@ -88,9 +90,13 @@ const runRecipePush = async (options) => {
     const tenant = (0, shared_1.resolveTenant)(options, { pathItemIdCache });
     const isDryRun = Boolean(options.whatIf);
     if (!isDryRun) {
-        (0, shared_1.ensureAllowWrite)(tenant.root, tenant.envName, options.allowWrite);
+        (0, shared_1.ensureAllowWrite)(tenant.root, tenant.envName, options.allowWrite, "recipe-push");
     }
-    const { templatesRoot, renderingsRoot } = (0, shared_1.resolveRecipeRoots)(options, tenant.environment, tenant.envName);
+    // One rollback-log scope per `recipe push` invocation. The file at
+    // `~/.sitecoreai/rollback/<runId>.jsonl` is created lazily by the
+    // logger on first write — successful pushes leave no file behind.
+    const rollbackRunId = (0, node_crypto_1.randomUUID)();
+    const rollbackLog = (0, rollback_log_1.createRollbackLogger)(rollbackRunId);
     // Phase 2 per-site folder layout roots — optional at the envProfile
     // level. When unset the compiler falls back to `templatesRoot` for
     // both, which means section-aware components nest under templatesRoot
@@ -119,6 +125,12 @@ const runRecipePush = async (options) => {
     // Per-site enumerations bucket — required for EnumerationRecipe
     // compilation and for any field carrying `sitecore.enumHandle`.
     const enumerationsRoot = options.enumerationsRoot ?? tenant.environment.enumerationsRoot;
+    // Page-level roots. `pageTemplatesRoot` falls back to `templatesRoot`
+    // in the compiler; `placeholderSettingsRoot` is required when the set
+    // declares any placeholder (standalone or inline).
+    const pageTemplatesRoot = tenant.environment.pageTemplatesRoot;
+    const placeholderSettingsRoot = tenant.environment.placeholderSettingsRoot;
+    const pagesRoot = tenant.environment.pagesRoot;
     const { files, source } = await (0, shared_1.resolveRecipeInputs)(options, tenant.root);
     const results = [];
     const allEvents = [];
@@ -147,6 +159,12 @@ const runRecipePush = async (options) => {
         }
     }
     const recipes = await (0, cli_tasks_1.mapWithConcurrency)(recipeFiles, (f) => (0, io_1.loadRecipe)(f));
+    // Resolve templatesRoot / renderingsRoot now that the recipe kinds are
+    // known: a set built only from workflow / webhook-authorization recipes
+    // — which create items under hardcoded /sitecore/system roots — needs
+    // neither. An IR-only push has an empty `recipes` and skips the
+    // requirement too; pre-compiled IRs carry their roots baked in.
+    const { templatesRoot, renderingsRoot } = (0, shared_1.resolveRecipeRoots)(options, tenant.environment, tenant.envName, (0, shared_1.recipeSetNeedsRoots)(recipes));
     const compiled = (0, compile_1.compileRecipeSet)(recipes, {
         templatesRoot,
         renderingsRoot,
@@ -158,6 +176,9 @@ const runRecipePush = async (options) => {
         headlessVariantsRoot,
         availableRenderingsRoot,
         enumerationsRoot,
+        pageTemplatesRoot,
+        placeholderSettingsRoot,
+        pagesRoot,
     });
     const loadedIrs = await (0, cli_tasks_1.mapWithConcurrency)(irFiles, (f) => (0, io_1.loadIr)(f));
     const irs = [
@@ -167,8 +188,16 @@ const runRecipePush = async (options) => {
     const crossRecipeRefs = new Map();
     for (const { ir } of irs) {
         for (const op of ir.operations) {
-            if (op.op === "CreateItem")
+            if (op.op === "CreateItem") {
                 crossRecipeRefs.set(op.id, op.path);
+                // templateOf: ref-path needs the same lookup-before-plan seed
+                // path-parent resolution uses. Compute the deterministic
+                // refKey + the target path; the executor's
+                // `getItemsByPaths` batch picks it up alongside parent paths.
+                if (typeof op.templateOf !== "string" && op.templateOf.kind === "ref-path") {
+                    crossRecipeRefs.set((0, guids_1.templatePathRefKey)(op.templateOf.value), op.templateOf.value);
+                }
+            }
         }
     }
     // Seed the synthetic Page Designs root refKey so the cross-recipe
@@ -191,14 +220,14 @@ const runRecipePush = async (options) => {
     if (hasSiteOp) {
         const accessToken = await (0, auth_1.getAccessToken)(tenant.environment);
         if (!accessToken) {
-            throw (0, errors_1.createCliError)(`Failed to mint a Sites API access token for environment '${tenant.envName}'. Run 'scai login' or set client credentials, then retry.`, "AUTH_REQUIRED");
+            throw (0, errors_1.createScaiError)(`Failed to mint a Sites API access token for environment '${tenant.envName}'. Run 'scai setup login' or set client credentials, then retry.`, "AUTH_REQUIRED");
         }
         sitesClient = (0, sites_client_1.createSitesApiClient)({ accessToken });
     }
     // Recipe-source files (vs pre-compiled `.ir.json`) are kept in scope
     // for the post-IR placeholder-allow phase. Pre-compiled IRs lose
     // their source-recipe handle/section/name → can't drive placeholder
-    // resolution; for those, callers should run `scai deploy placeholders`
+    // resolution; for those, callers should run `scai provision deploy placeholders`
     // separately if needed.
     const sourceRecipes = recipes;
     // ─── Optional recipe-hash skip ────────────────────────────────────────
@@ -219,6 +248,9 @@ const runRecipePush = async (options) => {
         headlessVariantsRoot,
         availableRenderingsRoot,
         enumerationsRoot,
+        pageTemplatesRoot,
+        placeholderSettingsRoot,
+        pagesRoot,
     });
     const irsToExecute = [];
     const cachedSkips = [];
@@ -276,11 +308,18 @@ const runRecipePush = async (options) => {
     const planConcurrency = options.planConcurrency ?? DEFAULT_PLAN_CONCURRENCY;
     const runOne = async (ir) => (0, execute_1.executeIr)(ir, tenant.client, {
         mode: isDryRun ? "plan" : "apply",
-        emit: (event) => allEvents.push({ recipe: ir.recipeHandle, event }),
+        emit: (event) => {
+            allEvents.push({ recipe: ir.recipeHandle, event });
+            options.emit?.({ recipe: ir.recipeHandle, event });
+        },
+        signal: options.signal,
         crossRecipeRefs,
         sitesClient,
         pathItemIdCache,
         pathSnapshotCache,
+        // Dry-run never rolls back, so the logger is a no-op there. Pass
+        // it through anyway — the conditional lives inside the executor.
+        rollbackLog,
     });
     const renderResult = (ir, result) => {
         if (logger.isJson())
@@ -370,6 +409,9 @@ const runRecipePush = async (options) => {
             }
         }
     }
+    if (rollbackLog.wasUsed && !logger.isJson()) {
+        logger.warn(`Rollback audit log written to ${rollbackLog.logPath}`);
+    }
     if (logger.isJson()) {
         logger.json({
             command: "recipe.push",
@@ -377,6 +419,9 @@ const runRecipePush = async (options) => {
             source,
             whatIf: isDryRun,
             placeholderAllowControls: placeholderAllowSummary ?? undefined,
+            rollbackLog: rollbackLog.wasUsed
+                ? { runId: rollbackLog.runId, path: rollbackLog.logPath }
+                : undefined,
             results: results.map((r) => ({
                 recipeHandle: r.plan.recipeHandle,
                 summary: r.summary,

package/dist/recipe/tasks/shared.d.ts

@@ -1,8 +1,8 @@
 import { Logger } from "../../shared/logger";
-import { type EnvironmentConfiguration, type RootConfiguration } from "../../config";
+import type { EnvironmentConfiguration, RootConfiguration } from "../../config/types";
 import type { AuthoringApiClient } from "../api/client";
 /**
- * Shared option shapes for the three `scai recipe` tasks.
+ * Shared option shapes for the three `scai provision recipe` tasks.
  *
  * All three honor the standard verbosity options (`--quiet`, `--json`,
  * `--log-file`). Plan and push additionally need an environment to talk
@@ -97,6 +97,24 @@ export interface RecipePushOptions extends RecipeTenantOptions {
      * sequentially — within a push, mutations land in topological order.
      */
     planConcurrency?: number;
+    /**
+     * Optional progress callback. Receives per-recipe execution events
+     * as they happen (op-start / op-result / apply-start / apply-success
+     * / apply-error / site-job-poll / rollback events). Used by external
+     * orchestrators (e.g. `scai mcp serve`) to forward live progress to
+     * a client. The CLI logger does not need this — it observes the same
+     * events via its own internal collator.
+     */
+    emit?: (event: {
+        recipe: string;
+        event: import("../execute").ExecutionEvent;
+    }) => void;
+    /**
+     * Cooperative cancellation. When the signal fires, the executor
+     * stops between operations, rolls back applied mutations, and the
+     * per-recipe `ExecutionResult.aborted` is set to true.
+     */
+    signal?: AbortSignal;
 }
 export declare const toLogger: (options: RecipeCommonOptions) => Logger;
 export interface ResolvedTenant {
@@ -108,6 +126,19 @@ export interface ResolvedTenant {
 export declare const resolveTenant: (options: RecipeTenantOptions, clientOptions?: {
     pathItemIdCache?: Map<string, string>;
 }) => ResolvedTenant;
+/**
+ * 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.
+ */
+export declare const recipeSetNeedsRoots: (recipes: readonly {
+    kind: string;
+}[]) => boolean;
 /**
  * Resolve the recipe parent paths that the compiler will use for top-level
  * template + rendering items.
@@ -118,7 +149,13 @@ export declare const resolveTenant: (options: RecipeTenantOptions, clientOptions
  *      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
@@ -128,7 +165,7 @@ export declare const resolveTenant: (options: RecipeTenantOptions, clientOptions
 export declare const resolveRecipeRoots: (options: {
     templatesRoot?: string;
     renderingsRoot?: string;
-}, environment: EnvironmentConfiguration | undefined, envName: string) => {
+}, environment: EnvironmentConfiguration | undefined, envName: string, required?: boolean) => {
     templatesRoot: string;
     renderingsRoot: string;
 };
@@ -148,5 +185,4 @@ export declare const resolveRecipeInputs: (options: {
     input?: string;
     config?: string;
 }, root: RootConfiguration) => Promise<RecipeInputResolution>;
-export declare const ensureAllowWrite: (root: RootConfiguration, envName: string, override?: boolean) => void;
-//# sourceMappingURL=shared.d.ts.map
+export { ensureAllowWrite } from "../../policy/allow-write";