@sitecoreai-labs/sitecoreai-cli 0.0.4

package/dist/recipe/tasks/push.js

@@ -0,0 +1,417 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runRecipePush = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const cli_tasks_1 = require("../../shared/cli-tasks");
+const errors_1 = require("../../shared/errors");
+const auth_1 = require("../api/auth");
+const sites_client_1 = require("../api/sites-client");
+const cache_1 = require("../cache");
+const compile_1 = require("../compile");
+const guids_1 = require("../guids");
+const io_1 = require("../io");
+const execute_1 = require("../execute");
+const placeholder_allow_1 = require("./placeholder-allow");
+const shared_1 = require("./shared");
+const DEFAULT_PLAN_CONCURRENCY = 4;
+/**
+ * Collect every Sitecore content-tree path the executor MIGHT need to
+ * read up-front, given a set of compiled IRs and the cross-recipe ref
+ * map. Used to fan a single batched `getItemsByPaths` call out before
+ * the per-op plan loop runs.
+ *
+ * Sources:
+ *   - Every CreateItem op's target path
+ *   - Every CreateItem op's ref-path parent path (e.g. configured
+ *     templatesRoot/renderingsRoot for top-level items)
+ *   - Every cross-recipe ref's expectedPath
+ *   - Every SetField/AppendToMultiList op's optional `latePath`
+ *
+ * De-duplicates within and across IRs — a single root path shared by
+ * 5 components ends up as one prefetch entry, not 5.
+ */
+const collectPrefetchPaths = (irs, crossRecipeRefs) => {
+    const seen = new Set();
+    const out = [];
+    const add = (p) => {
+        if (!p)
+            return;
+        if (seen.has(p))
+            return;
+        seen.add(p);
+        out.push(p);
+    };
+    for (const ir of irs) {
+        for (const op of ir.operations) {
+            if (op.op === "CreateItem") {
+                add(op.path);
+                if (op.parent.kind === "ref-path")
+                    add(op.parent.value);
+            }
+            else if (op.op === "SetField" || op.op === "AppendToMultiList") {
+                add(op.latePath);
+            }
+        }
+    }
+    for (const expectedPath of crossRecipeRefs.values()) {
+        add(expectedPath);
+    }
+    return out;
+};
+/**
+ * `scai recipe push` — apply recipes to a tenant.
+ *
+ * Input resolution:
+ *   - `--input <file>` — single recipe (`.recipe.ts/.recipe.json`) or IR
+ *     (`.ir.json`). The file extension picks the path: recipes are
+ *     compiled in-memory, IRs are loaded directly.
+ *   - default: expand the config `recipes` glob and push each match in
+ *     turn (one IR per recipe; per-recipe events).
+ *
+ * Honors `--what-if` (becomes plan-only) and `--allow-write` (the
+ * scai-wide safety gate). Streams progress as `task-progress`-style
+ * events in JSON mode; renders a per-op summary in human mode.
+ */
+const runRecipePush = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    // Workspace-wide path → itemId cache. Shared between the AuthoringApiClient
+    // (for `ensurePathExists` fast-path) and the executor (for ref-path
+    // parent resolution and cross-recipe refs). Lifetime = one push.
+    const pathItemIdCache = new Map();
+    // Workspace-wide path → RemoteItem snapshot cache. Pre-populated by the
+    // bulk prefetch (single batched `getItemsByPaths` call across every
+    // CreateItem path); consulted by `buildAction` for plan-time reads.
+    const pathSnapshotCache = new Map();
+    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);
+    }
+    const { templatesRoot, renderingsRoot } = (0, shared_1.resolveRecipeRoots)(options, tenant.environment, tenant.envName);
+    // 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
+    // (mid-migration fallback) and content templates land mixed in with
+    // components. The orchestrator's ephemeral CLI config sets both.
+    const componentsRoot = options.componentsRoot ?? tenant.environment.componentsRoot;
+    const contentModelsRoot = options.contentModelsRoot ?? tenant.environment.contentModelsRoot;
+    // Phase 4 composition roots — optional at the envProfile level. The
+    // per-recipe compile fns throw with their own clear messages if a
+    // partial-design / page-design / content-item recipe is in the set
+    // but the corresponding root is unset. CLI flag overrides match the
+    // templatesRoot / renderingsRoot pattern.
+    const partialDesignsRoot = options.partialDesignsRoot ?? tenant.environment.partialDesignsRoot;
+    const pageDesignsRoot = options.pageDesignsRoot ?? tenant.environment.pageDesignsRoot;
+    const contentItemsRoot = options.contentItemsRoot ?? tenant.environment.contentItemsRoot;
+    // SXA Headless variants root — required when any recipe in the set
+    // declares variants. Compiler throws INPUT_INVALID with a clear hint
+    // if a recipe asks for variants but this root is unset; if no
+    // recipe in the set has variants, this stays unset and the
+    // compiler skips the check.
+    const headlessVariantsRoot = options.headlessVariantsRoot ?? tenant.environment.headlessVariantsRoot;
+    // SXA Available Renderings root — when set, compileRecipeSet emits
+    // a synthetic IR with one Available Renderings section per
+    // `recipe.section`, listing every rendering in that section.
+    const availableRenderingsRoot = options.availableRenderingsRoot ?? tenant.environment.availableRenderingsRoot;
+    // Per-site enumerations bucket — required for EnumerationRecipe
+    // compilation and for any field carrying `sitecore.enumHandle`.
+    const enumerationsRoot = options.enumerationsRoot ?? tenant.environment.enumerationsRoot;
+    const { files, source } = await (0, shared_1.resolveRecipeInputs)(options, tenant.root);
+    const results = [];
+    const allEvents = [];
+    // Pre-compile every recipe so we can build a workspace-wide
+    // refKey → expectedPath map. The executor uses this to seed
+    // capturedItemIds with cross-recipe references the current recipe's
+    // own ops don't produce (e.g. accordion-block's
+    // `insertOptions: ["accordion-item@1"]` references accordion-item's
+    // template, which lives in a different recipe's IR).
+    //
+    // Phase 4: recipe-source files compile through `compileRecipeSet` so
+    // cross-recipe `TemplatesMapping` contributions (every PageDesignRecipe
+    // contributes one entry per `appliesTo` template) aggregate into a
+    // single synthetic IR. Pre-compiled `.ir.json` inputs load directly —
+    // the aggregate-IR opportunity is gone for those, but the executor
+    // still applies whatever's there.
+    const recipeFiles = [];
+    const irFiles = [];
+    for (const file of files) {
+        const ext = node_path_1.default.extname(file).toLowerCase();
+        if (ext === ".json" && file.endsWith(".ir.json")) {
+            irFiles.push(file);
+        }
+        else {
+            recipeFiles.push(file);
+        }
+    }
+    const recipes = await (0, cli_tasks_1.mapWithConcurrency)(recipeFiles, (f) => (0, io_1.loadRecipe)(f));
+    const compiled = (0, compile_1.compileRecipeSet)(recipes, {
+        templatesRoot,
+        renderingsRoot,
+        componentsRoot,
+        contentModelsRoot,
+        partialDesignsRoot,
+        pageDesignsRoot,
+        contentItemsRoot,
+        headlessVariantsRoot,
+        availableRenderingsRoot,
+        enumerationsRoot,
+    });
+    const loadedIrs = await (0, cli_tasks_1.mapWithConcurrency)(irFiles, (f) => (0, io_1.loadIr)(f));
+    const irs = [
+        ...compiled.map((ir) => ({ ir })),
+        ...loadedIrs.map((ir) => ({ ir })),
+    ];
+    const crossRecipeRefs = new Map();
+    for (const { ir } of irs) {
+        for (const op of ir.operations) {
+            if (op.op === "CreateItem")
+                crossRecipeRefs.set(op.id, op.path);
+        }
+    }
+    // Seed the synthetic Page Designs root refKey so the cross-recipe
+    // `TemplatesMapping` aggregate op (emitted by `compileRecipeSet` when
+    // any page design declares `appliesTo`) resolves its target. The
+    // executor walks the path and stores the captured itemId in
+    // `capturedItemIds` before applying the SetField op. Skip the seed
+    // when `pageDesignsRoot` isn't set — without page designs in the
+    // set, the aggregate IR isn't emitted and the seed wouldn't be used
+    // anyway.
+    if (pageDesignsRoot) {
+        crossRecipeRefs.set(guids_1.PAGE_DESIGNS_ROOT_REF_KEY, pageDesignsRoot);
+    }
+    // Lazy-build a SitesApiClient only when an IR in the set needs one
+    // (i.e. carries a CreateSiteFromTemplate op). Component / partial /
+    // page-design / content-item recipes never reach Sites API — keep
+    // their push paths free of unnecessary token mints.
+    let sitesClient;
+    const hasSiteOp = irs.some(({ ir }) => ir.operations.some((op) => op.op === "CreateSiteFromTemplate"));
+    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");
+        }
+        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`
+    // separately if needed.
+    const sourceRecipes = recipes;
+    // ─── Optional recipe-hash skip ────────────────────────────────────────
+    // When `--skip-unchanged-recipes` is on, compare each compiled IR's
+    // digest against the persisted cache. Cache hits short-circuit the
+    // recipe entirely (zero plan-time reads, zero mutations); cache
+    // misses fall through to the normal execute path.
+    const configDir = node_path_1.default.dirname(tenant.root.physicalPath);
+    const recipeCache = options.skipUnchangedRecipes ? await (0, cache_1.loadRecipeCache)(configDir) : null;
+    const rootsHash = (0, cache_1.hashRoots)({
+        templatesRoot,
+        renderingsRoot,
+        componentsRoot,
+        contentModelsRoot,
+        partialDesignsRoot,
+        pageDesignsRoot,
+        contentItemsRoot,
+        headlessVariantsRoot,
+        availableRenderingsRoot,
+        enumerationsRoot,
+    });
+    const irsToExecute = [];
+    const cachedSkips = [];
+    for (const { ir } of irs) {
+        const irHash = (0, cache_1.hashIr)(ir);
+        const cached = recipeCache && (0, cache_1.cachedSkipFor)(recipeCache, tenant.envName, rootsHash, ir.recipeHandle, irHash);
+        if (cached) {
+            cachedSkips.push({ ir, irHash, entry: cached });
+            continue;
+        }
+        irsToExecute.push({ ir, irHash, cached: false });
+    }
+    // Surface cache-skips as zero-effect ExecutionResults so downstream
+    // callers (orchestrator, JSON consumers) see a uniform shape across
+    // skipped + executed recipes.
+    for (const { ir, entry } of cachedSkips) {
+        const skipSummary = { create: 0, update: 0, skip: ir.operations.length, error: 0 };
+        results.push({
+            plan: {
+                schemaVersion: "1",
+                recipeHandle: ir.recipeHandle,
+                actions: [],
+                summary: skipSummary,
+            },
+            summary: skipSummary,
+            aborted: false,
+        });
+        if (!logger.isJson()) {
+            logger.info(`Skipping ${ir.recipeHandle} on ${tenant.envName} (unchanged since ${entry?.lastApplied ?? "previous push"})`, "green");
+        }
+    }
+    // ─── Workspace prefetch ────────────────────────────────────────────────
+    // One batched `getItemsByPaths` call covering every path the executor
+    // would otherwise read sequentially. On a re-push of an existing
+    // recipe set this collapses N×ops sequential reads into ~ceil(N/25)
+    // parallel batches, then the per-op plan loop hits the cache for
+    // every read. On a first push, missing paths are cached as `null`
+    // — buildAction sees that as "checked, missing → CreateItem applies".
+    const prefetchPaths = collectPrefetchPaths(irsToExecute.map((e) => e.ir), crossRecipeRefs);
+    if (prefetchPaths.length > 0) {
+        const fetched = await tenant.client.getItemsByPaths(prefetchPaths);
+        for (const [p, item] of fetched) {
+            pathSnapshotCache.set(p, item);
+            if (item)
+                pathItemIdCache.set(p, item.itemId);
+        }
+    }
+    // ─── Plan or apply ────────────────────────────────────────────────────
+    // Plan-mode reads are pure and have no cross-recipe ordering
+    // requirements once `crossRecipeRefs` + the prefetch have populated
+    // the workspace caches — so plan-mode IRs run concurrently. Apply
+    // mode stays sequential per-IR; mutations within and across recipes
+    // can have ordering dependencies that the topological IR encoding
+    // already respects in a serial walk.
+    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 }),
+        crossRecipeRefs,
+        sitesClient,
+        pathItemIdCache,
+        pathSnapshotCache,
+    });
+    const renderResult = (ir, result) => {
+        if (logger.isJson())
+            return;
+        logger.info(`${isDryRun ? "Dry-run" : "Applying"} ${ir.recipeHandle} on ${tenant.envName}`, "cyan");
+        for (const action of result.plan.actions) {
+            logger.info(`  ${formatActionTag(action.status)} ${action.operation.label}${action.reason ? ` — ${action.reason}` : ""}`);
+        }
+        if (result.aborted && result.rollback) {
+            logger.warn(`  Push aborted at op ${result.plan.actions[result.plan.actions.length - 1]?.index ?? "?"}; rolled back ${result.rollback.rolledBack} of ${result.plan.actions.filter((a) => a.mutation).length} applied.`);
+            for (const err of result.rollback.errors) {
+                logger.warn(`  ! rollback failed at ${err.label}: ${err.error}`);
+            }
+        }
+        logger.info(`  Summary: ${result.summary.create} create / ${result.summary.update} update / ${result.summary.skip} skip${result.summary.error ? ` / ${result.summary.error} error` : ""}`, result.summary.error || result.aborted ? "yellow" : "green");
+    };
+    if (isDryRun) {
+        const planResults = await (0, cli_tasks_1.mapWithConcurrency)(irsToExecute, ({ ir }) => runOne(ir), planConcurrency);
+        for (let i = 0; i < irsToExecute.length; i += 1) {
+            const { ir } = irsToExecute[i];
+            const result = planResults[i];
+            results.push(result);
+            renderResult(ir, result);
+        }
+    }
+    else {
+        for (const { ir } of irsToExecute) {
+            const result = await runOne(ir);
+            results.push(result);
+            renderResult(ir, result);
+        }
+    }
+    // ─── Persist hash cache ────────────────────────────────────────────────
+    // Only after a successful (non-aborted, non-error) apply. Plan-mode
+    // (dry-run) doesn't update the cache — it can't validate that the
+    // tenant matches what the cache implies.
+    if (!isDryRun && options.skipUnchangedRecipes && recipeCache) {
+        for (const { ir, irHash } of irsToExecute) {
+            const result = results.find((r) => r.plan.recipeHandle === ir.recipeHandle);
+            if (!result || result.aborted || result.summary.error > 0)
+                continue;
+            (0, cache_1.recordCacheEntry)(recipeCache, tenant.envName, rootsHash, ir.recipeHandle, {
+                irHash,
+                lastApplied: new Date().toISOString(),
+                summary: {
+                    create: result.summary.create,
+                    update: result.summary.update,
+                    skip: result.summary.skip,
+                },
+            });
+        }
+        await (0, cache_1.saveRecipeCache)(configDir, recipeCache);
+    }
+    // Post-IR phase: register each component-template recipe's
+    // rendering with the placeholder slots it declares compatibility
+    // with (`recipe.placedIn: string[]`). Runs only on apply mode
+    // and only when at least one IR succeeded (a fully-aborted push
+    // shouldn't dirty unrelated placeholders). Skipped when the env
+    // profile doesn't configure `placeholderSettingsRoots` — empty list
+    // means no slots to walk.
+    const placeholderRoots = tenant.environment.placeholderSettingsRoots ?? [];
+    const anyComponentRecipeDeclaresPlaceholders = sourceRecipes.some((r) => r.kind === "component-template" && Array.isArray(r.placedIn) && r.placedIn.length > 0);
+    let placeholderAllowSummary = null;
+    if (!isDryRun &&
+        anyComponentRecipeDeclaresPlaceholders &&
+        placeholderRoots.length > 0 &&
+        results.some((r) => !r.aborted)) {
+        placeholderAllowSummary = await (0, placeholder_allow_1.applyPlaceholderAllowControls)({
+            client: tenant.client,
+            recipes: sourceRecipes,
+            renderingsRoot,
+            placeholderSettingsRoots: placeholderRoots,
+            apply: true,
+            onUpdate: (placeholderPath, added) => {
+                if (!logger.isJson()) {
+                    logger.info(`  Placeholder ${placeholderPath} ← +${added} rendering(s)`, "cyan");
+                }
+            },
+        });
+        if (!logger.isJson()) {
+            logger.info(`Placeholder allow-controls: ${placeholderAllowSummary.patched} placeholder(s) patched, ${placeholderAllowSummary.totalAdded} entry(ies) added`, placeholderAllowSummary.unmatchedPlaceholderKeys.length > 0 ? "yellow" : "green");
+            if (placeholderAllowSummary.unmatchedPlaceholderKeys.length > 0) {
+                logger.warn(`  Unmatched placeholder keys (no Placeholder Settings item with that key under any configured root): ${placeholderAllowSummary.unmatchedPlaceholderKeys.join(", ")}`);
+            }
+            if (placeholderAllowSummary.unresolvedRecipeHandles.length > 0) {
+                logger.warn(`  Recipes whose rendering item couldn't be resolved (skipped from placeholder registration): ${placeholderAllowSummary.unresolvedRecipeHandles.join(", ")}`);
+            }
+        }
+    }
+    if (logger.isJson()) {
+        logger.json({
+            command: "recipe.push",
+            environment: tenant.envName,
+            source,
+            whatIf: isDryRun,
+            placeholderAllowControls: placeholderAllowSummary ?? undefined,
+            results: results.map((r) => ({
+                recipeHandle: r.plan.recipeHandle,
+                summary: r.summary,
+                aborted: r.aborted,
+                rollback: r.rollback ?? null,
+            })),
+            events: allEvents.map(({ recipe, event }) => ({
+                recipe,
+                kind: event.kind,
+                index: "index" in event ? event.index : "action" in event ? event.action.index : undefined,
+                label: "operation" in event
+                    ? event.operation.label
+                    : "action" in event
+                        ? event.action.operation.label
+                        : undefined,
+                status: "action" in event ? event.action.status : undefined,
+                reason: "action" in event ? event.action.reason : undefined,
+                diff: "action" in event ? event.action.diff : undefined,
+                mutation: "action" in event ? event.action.mutation : undefined,
+                error: "error" in event ? event.error : undefined,
+            })),
+        });
+    }
+    return results;
+};
+exports.runRecipePush = runRecipePush;
+const formatActionTag = (status) => {
+    switch (status) {
+        case "create":
+            return "[+]";
+        case "update":
+            return "[~]";
+        case "skip":
+            return "[ ]";
+        case "error":
+            return "[!]";
+    }
+};

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

@@ -0,0 +1,152 @@
+import { Logger } from "../../shared/logger";
+import { type EnvironmentConfiguration, type RootConfiguration } from "../../config";
+import type { AuthoringApiClient } from "../api/client";
+/**
+ * Shared option shapes for the three `scai recipe` tasks.
+ *
+ * All three honor the standard verbosity options (`--quiet`, `--json`,
+ * `--log-file`). Plan and push additionally need an environment to talk
+ * to a tenant; compile is pure-logic and doesn't.
+ */
+export interface RecipeCommonOptions {
+    config?: string;
+    verbose?: boolean;
+    trace?: boolean;
+    quiet?: boolean;
+    json?: boolean;
+    logFile?: string;
+    nonInteractive?: boolean;
+}
+export interface RecipeCompileOptions extends RecipeCommonOptions {
+    /** Single recipe file path. Defaults to the config `recipes` glob. */
+    input?: string;
+    output?: string;
+    /** Override `templatesRoot` from the env profile. */
+    templatesRoot?: string;
+    /** Override `renderingsRoot` from the env profile. */
+    renderingsRoot?: string;
+    /** Override `componentsRoot` from the env profile (Phase 2 layout). */
+    componentsRoot?: string;
+    /** Override `contentModelsRoot` from the env profile (Phase 2 layout). */
+    contentModelsRoot?: string;
+    /** Override `partialDesignsRoot` from the env profile (Phase 4). */
+    partialDesignsRoot?: string;
+    /** Override `pageDesignsRoot` from the env profile (Phase 4). */
+    pageDesignsRoot?: string;
+    /** Override `contentItemsRoot` from the env profile (Phase 4). */
+    contentItemsRoot?: string;
+    /** Override `headlessVariantsRoot` from the env profile. */
+    headlessVariantsRoot?: string;
+    /** Override `availableRenderingsRoot` from the env profile. */
+    availableRenderingsRoot?: string;
+    /** Override `enumerationsRoot` from the env profile. */
+    enumerationsRoot?: string;
+    /**
+     * Active env profile to source `templatesRoot` / `renderingsRoot`
+     * defaults from when the flags are not passed. Required for compile
+     * since compile is otherwise environment-agnostic.
+     */
+    environmentName?: string;
+}
+export interface RecipeTenantOptions extends RecipeCommonOptions {
+    environmentName?: string;
+}
+export interface RecipePlanOptions extends RecipeTenantOptions {
+    /** Single IR file path. Defaults to the config `recipes` glob (compiled in-memory). */
+    input?: string;
+    output?: string;
+}
+export interface RecipePushOptions extends RecipeTenantOptions {
+    /** Single recipe file path. Defaults to the config `recipes` glob. */
+    input?: string;
+    /** Override `templatesRoot` from the env profile. */
+    templatesRoot?: string;
+    /** Override `renderingsRoot` from the env profile. */
+    renderingsRoot?: string;
+    /** Override `componentsRoot` from the env profile (Phase 2 layout). */
+    componentsRoot?: string;
+    /** Override `contentModelsRoot` from the env profile (Phase 2 layout). */
+    contentModelsRoot?: string;
+    /** Override `partialDesignsRoot` from the env profile (Phase 4). */
+    partialDesignsRoot?: string;
+    /** Override `pageDesignsRoot` from the env profile (Phase 4). */
+    pageDesignsRoot?: string;
+    /** Override `contentItemsRoot` from the env profile (Phase 4). */
+    contentItemsRoot?: string;
+    /** Override `headlessVariantsRoot` from the env profile. */
+    headlessVariantsRoot?: string;
+    /** Override `availableRenderingsRoot` from the env profile. */
+    availableRenderingsRoot?: string;
+    /** Override `enumerationsRoot` from the env profile. */
+    enumerationsRoot?: string;
+    whatIf?: boolean;
+    allowWrite?: boolean;
+    /**
+     * When true, skip recipes whose compiled IR digest + env-profile roots
+     * digest both match the persisted `.scai/recipe-cache.json` entry from
+     * the previous successful push. Speedups re-pushes of an unchanged
+     * recipe set on warm tenants. Off by default — out-of-band CMS edits
+     * to recipe-owned items aren't auto-redetected until either the recipe
+     * source changes or the cache is invalidated.
+     */
+    skipUnchangedRecipes?: boolean;
+    /**
+     * Plan-mode parallelism across recipes. Plan reads are pure (no
+     * mutations, no shared mutable refs across recipes), so plan-mode
+     * IRs can run concurrently. Defaults to 4. Apply-mode always runs
+     * sequentially — within a push, mutations land in topological order.
+     */
+    planConcurrency?: number;
+}
+export declare const toLogger: (options: RecipeCommonOptions) => Logger;
+export interface ResolvedTenant {
+    envName: string;
+    environment: EnvironmentConfiguration;
+    root: RootConfiguration;
+    client: AuthoringApiClient;
+}
+export declare const resolveTenant: (options: RecipeTenantOptions, clientOptions?: {
+    pathItemIdCache?: Map<string, string>;
+}) => ResolvedTenant;
+/**
+ * Resolve the recipe parent paths that the compiler will use for top-level
+ * template + rendering items.
+ *
+ * Lookup order:
+ *   1. `--templates-root` / `--renderings-root` CLI flags
+ *   2. `envProfiles[<name>].templatesRoot` / `.renderingsRoot` from
+ *      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
+ *
+ * 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).
+ */
+export declare const resolveRecipeRoots: (options: {
+    templatesRoot?: string;
+    renderingsRoot?: string;
+}, environment: EnvironmentConfiguration | undefined, envName: string) => {
+    templatesRoot: string;
+    renderingsRoot: string;
+};
+export interface RecipeInputResolution {
+    files: string[];
+    source: "input-flag" | "config-glob";
+}
+/**
+ * Resolve the recipe files a task should operate on. Precedence:
+ *   1. `--input <file>` if provided (single file).
+ *   2. `recipes` globs from sitecoreai.cli.json (zero, one, or many files).
+ *
+ * Returns absolute paths. Throws `INPUT_INVALID` when neither path resolves
+ * to any files — telling the user how to fix it.
+ */
+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

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

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../src/recipe/tasks/shared.ts"],"names":[],"mappings":"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"}

package/dist/recipe/tasks/shared.js

@@ -0,0 +1,94 @@
+"use strict";
+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;
+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 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 client = (0, authoring_client_1.createAuthoringClient)({
+        environment,
+        request: { timeoutMs },
+        ...(clientOptions?.pathItemIdCache && { pathItemIdCache: clientOptions.pathItemIdCache }),
+    });
+    return { envName, environment, root, client };
+};
+exports.resolveTenant = resolveTenant;
+/**
+ * Resolve the recipe parent paths that the compiler will use for top-level
+ * template + rendering items.
+ *
+ * Lookup order:
+ *   1. `--templates-root` / `--renderings-root` CLI flags
+ *   2. `envProfiles[<name>].templatesRoot` / `.renderingsRoot` from
+ *      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
+ *
+ * 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 templatesRoot = options.templatesRoot ?? environment?.templatesRoot;
+    const renderingsRoot = options.renderingsRoot ?? environment?.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", {
+            hint: `Add 'templatesRoot' and 'renderingsRoot' to envProfiles.${envName} in sitecoreai.cli.json (or pass --templates-root / --renderings-root).`,
+        });
+    }
+    return { templatesRoot, renderingsRoot };
+};
+exports.resolveRecipeRoots = resolveRecipeRoots;
+/**
+ * Resolve the recipe files a task should operate on. Precedence:
+ *   1. `--input <file>` if provided (single file).
+ *   2. `recipes` globs from sitecoreai.cli.json (zero, one, or many files).
+ *
+ * Returns absolute paths. Throws `INPUT_INVALID` when neither path resolves
+ * to any files — telling the user how to fix it.
+ */
+const resolveRecipeInputs = async (options, root) => {
+    if (options.input) {
+        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 });
+    if (matched.length === 0) {
+        throw (0, errors_1.createCliError)(`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;