@sitecoreai-labs/sitecoreai-cli 0.0.4

package/dist/recipe/api/ref-encoding.d.ts

@@ -0,0 +1,38 @@
+import type { RefValue } from "../ir/operations";
+/**
+ * Render a typed `RefValue` to the canonical Sitecore string form.
+ *
+ * Sitecore field storage is always a string — the `RefValue` discriminator
+ * tells us *how* to serialize that string for Sitecore to understand it.
+ * See `plans/sitecore-relationships.md` (Reference encoding patterns) for
+ * the per-pattern serialization rules.
+ *
+ * `ref-recipe` / `ref-recipe-list` cannot be rendered directly — the
+ * executor must resolve their `refKey` against the per-run captured-itemId
+ * map first (see `resolveRecipeRefs` below). Calling `renderRefValue` on
+ * an unresolved recipe-ref is a programmer error.
+ */
+export declare const renderRefValue: (value: RefValue) => string;
+/**
+ * Substitute every `ref-recipe` / `ref-recipe-list` against the captured
+ * Sitecore itemId map. Returns a new `RefValue` with `ref-guid` /
+ * `ref-guid-list` in their place. Throws when a refKey is missing — that
+ * indicates a topological ordering bug (executor referenced an item that
+ * hadn't been created yet).
+ */
+export declare const resolveRecipeRefs: (value: RefValue, capturedItemIds: ReadonlyMap<string, string>) => RefValue;
+/**
+ * Normalise a Sitecore itemId to the canonical 8-4-4-4-12 dashed
+ * form. Authoring GraphQL returns IDs without dashes
+ * (`825b30b4b40b422e992023a1b6bda89c`), but Sitecore's Treelist
+ * field-value parser only resolves IDs in dashed form
+ * (`{825B30B4-B40B-422E-9920-23A1B6BDA89C}`). Without this, multilist
+ * field values written by `toCurly` come out as `{NODASH}` and the
+ * editor renders "Item not found" for every entry even though the
+ * items exist.
+ *
+ * Returns input unchanged (lowercased) when the value isn't a 32-hex
+ * GUID — defensive against ref values that aren't actual itemIds.
+ */
+export declare const dashifyGuid: (guid: string) => string;
+//# sourceMappingURL=ref-encoding.d.ts.map

package/dist/recipe/api/ref-encoding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref-encoding.d.ts","sourceRoot":"","sources":["../../../src/recipe/api/ref-encoding.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAGjD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,QAAQ,KAAG,MAgChD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAC5B,OAAO,QAAQ,EACf,iBAAiB,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,KAC3C,QA4EF,CAAC;AAOF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,KAAG,MAI1C,CAAC"}

package/dist/recipe/api/ref-encoding.js

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dashifyGuid = exports.resolveRecipeRefs = exports.renderRefValue = void 0;
+const errors_1 = require("../../shared/errors");
+const source_fields_1 = require("../schema/source-fields");
+/**
+ * Render a typed `RefValue` to the canonical Sitecore string form.
+ *
+ * Sitecore field storage is always a string — the `RefValue` discriminator
+ * tells us *how* to serialize that string for Sitecore to understand it.
+ * See `plans/sitecore-relationships.md` (Reference encoding patterns) for
+ * the per-pattern serialization rules.
+ *
+ * `ref-recipe` / `ref-recipe-list` cannot be rendered directly — the
+ * executor must resolve their `refKey` against the per-run captured-itemId
+ * map first (see `resolveRecipeRefs` below). Calling `renderRefValue` on
+ * an unresolved recipe-ref is a programmer error.
+ */
+const renderRefValue = (value) => {
+    switch (value.kind) {
+        case "string":
+            return value.value;
+        case "bool":
+            return value.value ? "1" : "0";
+        case "number":
+            return String(value.value);
+        case "ref-guid":
+            return toCurly(value.value);
+        case "ref-guid-list":
+            return value.values.map(toCurly).join("|");
+        case "ref-recipe":
+        case "ref-recipe-list":
+        case "ref-source-fields":
+            throw (0, errors_1.createCliError)(`Unresolved ${value.kind} cannot be rendered — call resolveRecipeRefs first.`, "UNKNOWN");
+        case "ref-path":
+            return value.value;
+        case "query":
+            return value.value;
+        case "url-string-map":
+            return Object.entries(value.entries)
+                .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+                .join("&");
+        default: {
+            const exhaustive = value;
+            throw (0, errors_1.createCliError)(`Unhandled RefValue kind: ${JSON.stringify(exhaustive)}`, "UNKNOWN");
+        }
+    }
+};
+exports.renderRefValue = renderRefValue;
+/**
+ * Substitute every `ref-recipe` / `ref-recipe-list` against the captured
+ * Sitecore itemId map. Returns a new `RefValue` with `ref-guid` /
+ * `ref-guid-list` in their place. Throws when a refKey is missing — that
+ * indicates a topological ordering bug (executor referenced an item that
+ * hadn't been created yet).
+ */
+const resolveRecipeRefs = (value, capturedItemIds) => {
+    switch (value.kind) {
+        case "ref-recipe": {
+            const itemId = capturedItemIds.get(value.refKey);
+            if (itemId)
+                return { kind: "ref-guid", value: itemId };
+            // Pass-through: when a refKey isn't in the captured map but looks
+            // like a literal Sitecore GUID (e.g. `SITECORE_TEMPLATES.FOLDER`
+            // baked into an aggregator's ref-recipe list), treat it as a
+            // literal rather than failing. Recipe-internal refKeys are also
+            // valid GUIDs in shape, so this is purely a fallback for items
+            // that don't get produced by sibling CreateItem ops — built-in
+            // templates, tenant-pre-existing items.
+            if (isGuid(value.refKey)) {
+                return { kind: "ref-guid", value: value.refKey };
+            }
+            throw (0, errors_1.createCliError)(`ref-recipe refKey ${value.refKey} not in captured map — was the producing CreateItem op skipped or did it run after this op?`, "UNKNOWN");
+        }
+        case "ref-recipe-list": {
+            const guids = [];
+            for (const refKey of value.refKeys) {
+                const itemId = capturedItemIds.get(refKey);
+                if (itemId) {
+                    guids.push(itemId);
+                    continue;
+                }
+                // Same pass-through as `ref-recipe` above — built-in Sitecore
+                // template constants and tenant-pre-existing items appear in
+                // aggregator ref-recipe-list values; honour them as literals.
+                if (isGuid(refKey)) {
+                    guids.push(refKey);
+                    continue;
+                }
+                if (value.tolerateMissing)
+                    continue;
+                throw (0, errors_1.createCliError)(`ref-recipe-list refKey ${refKey} not in captured map — was the producing CreateItem op skipped or did it run after this op?`, "UNKNOWN");
+            }
+            return { kind: "ref-guid-list", values: guids };
+        }
+        case "ref-source-fields": {
+            // Structured source fields with recipe-handle references in
+            // `sourceTypes`. Resolve each handle to its captured Sitecore
+            // itemId, then render. Recipe handles map to refKeys via
+            // `templateId(site, handle)`, which the planner registers when the
+            // referenced template's CreateItem op completes. The site name is
+            // embedded on the value at compile time — the encoder can't otherwise
+            // know which site the recipe set was compiled under.
+            const rendered = (0, source_fields_1.renderSourceFields)({
+                sourceTypes: value.sourceTypes,
+                sourceQuery: value.sourceQuery,
+                sourceScope: value.sourceScope,
+            }, (handle) => {
+                const refKey = (0, guids_1.templateId)(value.site, handle);
+                const itemId = capturedItemIds.get(refKey);
+                if (!itemId) {
+                    throw (0, errors_1.createCliError)(`ref-source-fields references handle '${handle}' (refKey ${refKey}); not yet in captured map.`, "UNKNOWN");
+                }
+                return itemId;
+            });
+            // sourceTypes is non-empty in this branch (IR validation), so
+            // renderSourceFields always returns a string.
+            return { kind: "string", value: rendered };
+        }
+        default:
+            return value;
+    }
+};
+exports.resolveRecipeRefs = resolveRecipeRefs;
+// Re-import here to avoid a circular dep with `guids.ts → ir/operations`.
+// `templateId` is a pure uuidv5 derivation; importing it lazily keeps the
+// resolver self-contained.
+const guids_1 = require("../guids");
+/**
+ * Normalise a Sitecore itemId to the canonical 8-4-4-4-12 dashed
+ * form. Authoring GraphQL returns IDs without dashes
+ * (`825b30b4b40b422e992023a1b6bda89c`), but Sitecore's Treelist
+ * field-value parser only resolves IDs in dashed form
+ * (`{825B30B4-B40B-422E-9920-23A1B6BDA89C}`). Without this, multilist
+ * field values written by `toCurly` come out as `{NODASH}` and the
+ * editor renders "Item not found" for every entry even though the
+ * items exist.
+ *
+ * Returns input unchanged (lowercased) when the value isn't a 32-hex
+ * GUID — defensive against ref values that aren't actual itemIds.
+ */
+const dashifyGuid = (guid) => {
+    const compact = guid.replace(/[{}-]/g, "").toLowerCase();
+    if (compact.length !== 32)
+        return guid.toLowerCase();
+    return `${compact.slice(0, 8)}-${compact.slice(8, 12)}-${compact.slice(12, 16)}-${compact.slice(16, 20)}-${compact.slice(20, 32)}`;
+};
+exports.dashifyGuid = dashifyGuid;
+/**
+ * True when the string is a valid Sitecore item GUID — 32 hex chars,
+ * with or without dashes, with or without curly braces. Used by the
+ * `ref-recipe` / `ref-recipe-list` resolvers to pass through literal
+ * GUIDs (built-in Sitecore template constants, tenant-pre-existing
+ * items) that aren't produced by sibling CreateItem ops.
+ */
+const isGuid = (s) => {
+    const compact = s.replace(/[{}-]/g, "");
+    return compact.length === 32 && /^[0-9a-fA-F]{32}$/.test(compact);
+};
+const toCurly = (guid) => `{${(0, exports.dashifyGuid)(guid).toUpperCase()}}`;

package/dist/recipe/api/site-discovery.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Discover SXA sites in a Sitecore CM environment via the Authoring
+ * GraphQL API.
+ *
+ * The convention this walks: each CM environment has a single tenant
+ * at `/sitecore/content/<Tenant>` with one or more sites under it at
+ * `/sitecore/content/<Tenant>/<Site>`. Tenants and sites are identified
+ * by template name match rather than hard-coded template GUIDs so
+ * the discovery is resilient across SXA / XM Cloud variants:
+ *
+ *   - Tenant: `Tenant`, `Tenant Folder`, `Headless Tenant`,
+ *     `Headless Tenant Folder`
+ *   - Site:   `Site`, `Headless Site`
+ *
+ * Two round trips minimum:
+ *   1. children of `/sitecore/content`        → candidate tenants
+ *   2. children of each tenant                → candidate sites
+ *
+ * Sites typically expose hostnames via a `Settings/Site Grouping/<grouping>`
+ * sub-item. Walking deeper for hostnames is opt-in (`includeHostnames`)
+ * because it adds an N+1 round trip per site.
+ */
+import { EnvironmentConfiguration } from "../../config";
+export type DiscoveredSite = {
+    /** Item name (URL-safe slug). Used as the SXA site name. */
+    name: string;
+    /** Display name from the item, or the item name if not set. */
+    displayName: string;
+    /** Full Sitecore content path, e.g. `/sitecore/content/MyTenant/MySite`. */
+    path: string;
+    /** Parent tenant's item name. */
+    tenantName: string;
+    /** Parent tenant's full path. */
+    tenantPath: string;
+    /** Hostnames declared by `Settings/Site Grouping/<grouping>` items.
+     *  Populated only when `includeHostnames: true` is requested. */
+    hostnames?: string[];
+};
+export type DiscoverSitesOptions = {
+    /** Resolve each site's hostnames from its Site Grouping sub-items.
+     *  Adds N+1 GraphQL round trips. Defaults to false. */
+    includeHostnames?: boolean;
+    /** Override the content root walked. Default `/sitecore/content`.
+     *  Useful for tests or for installations that nest content under a
+     *  non-default root. */
+    contentRoot?: string;
+};
+export declare const discoverSites: (environment: EnvironmentConfiguration, options?: DiscoverSitesOptions) => Promise<DiscoveredSite[]>;
+//# sourceMappingURL=site-discovery.d.ts.map

package/dist/recipe/api/site-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"site-discovery.d.ts","sourceRoot":"","sources":["../../../src/recipe/api/site-discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,UAAU,CAAC;AAGpD,MAAM,MAAM,cAAc,GAAG;IAC3B,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB;qEACiE;IACjE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC;2DACuD;IACvD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;4BAEwB;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAyGF,eAAO,MAAM,aAAa,GACxB,aAAa,wBAAwB,EACrC,UAAS,oBAAyB,KACjC,OAAO,CAAC,cAAc,EAAE,CA2B1B,CAAC"}

package/dist/recipe/api/site-discovery.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * Discover SXA sites in a Sitecore CM environment via the Authoring
+ * GraphQL API.
+ *
+ * The convention this walks: each CM environment has a single tenant
+ * at `/sitecore/content/<Tenant>` with one or more sites under it at
+ * `/sitecore/content/<Tenant>/<Site>`. Tenants and sites are identified
+ * by template name match rather than hard-coded template GUIDs so
+ * the discovery is resilient across SXA / XM Cloud variants:
+ *
+ *   - Tenant: `Tenant`, `Tenant Folder`, `Headless Tenant`,
+ *     `Headless Tenant Folder`
+ *   - Site:   `Site`, `Headless Site`
+ *
+ * Two round trips minimum:
+ *   1. children of `/sitecore/content`        → candidate tenants
+ *   2. children of each tenant                → candidate sites
+ *
+ * Sites typically expose hostnames via a `Settings/Site Grouping/<grouping>`
+ * sub-item. Walking deeper for hostnames is opt-in (`includeHostnames`)
+ * because it adds an N+1 round trip per site.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoverSites = void 0;
+const graphql_1 = require("./graphql");
+const DEFAULT_CONTENT_ROOT = "/sitecore/content";
+const TENANT_TEMPLATE_NAMES = new Set([
+    "Tenant",
+    "Tenant Folder",
+    "Headless Tenant",
+    "Headless Tenant Folder",
+]);
+const SITE_TEMPLATE_NAMES = new Set(["Site", "Headless Site"]);
+const SITE_GROUPING_NAMES = new Set(["Site Grouping"]);
+const CHILDREN_QUERY = `
+query($path: String!) {
+  item(where: { path: $path }) {
+    children {
+      nodes {
+        itemId
+        name
+        displayName
+        path
+        template {
+          name
+        }
+      }
+    }
+  }
+}`;
+const HOSTNAME_QUERY = `
+query($path: String!) {
+  item(where: { path: $path }) {
+    fields(ownFields: false) {
+      nodes {
+        name
+        value
+      }
+    }
+  }
+}`;
+const fetchChildren = async (environment, path) => {
+    const data = await (0, graphql_1.runAuthoringGraphQL)(environment, CHILDREN_QUERY, { path });
+    return data.item?.children.nodes ?? [];
+};
+const fetchHostnames = async (environment, sitePath) => {
+    // Site groupings live at <site>/Settings/Site Grouping/<grouping>
+    // and expose a `Hostname` field. Walk: site → settings → site
+    // grouping container → grouping items → collect Hostname.
+    const settings = await fetchChildren(environment, sitePath);
+    const settingsItem = settings.find((node) => node.name === "Settings");
+    if (!settingsItem)
+        return [];
+    const settingsChildren = await fetchChildren(environment, settingsItem.path);
+    const groupingContainer = settingsChildren.find((node) => SITE_GROUPING_NAMES.has(node.name));
+    if (!groupingContainer)
+        return [];
+    const groupings = await fetchChildren(environment, groupingContainer.path);
+    const hostnames = [];
+    for (const grouping of groupings) {
+        const data = await (0, graphql_1.runAuthoringGraphQL)(environment, HOSTNAME_QUERY, {
+            path: grouping.path,
+        });
+        const value = data.item?.fields.nodes.find((field) => field.name === "Hostname")?.value;
+        if (value && value.trim()) {
+            // Hostname field is typically a single hostname or `|`-separated list.
+            for (const host of value.split("|")) {
+                const trimmed = host.trim();
+                if (trimmed)
+                    hostnames.push(trimmed);
+            }
+        }
+    }
+    return hostnames;
+};
+const isTenantNode = (node) => TENANT_TEMPLATE_NAMES.has(node.template?.name ?? "");
+const isSiteNode = (node) => SITE_TEMPLATE_NAMES.has(node.template?.name ?? "");
+const discoverSites = async (environment, options = {}) => {
+    const contentRoot = options.contentRoot ?? DEFAULT_CONTENT_ROOT;
+    const tenantCandidates = await fetchChildren(environment, contentRoot);
+    // SXA convention: top-level items under /sitecore/content are tenants.
+    // Some installations have non-tenant items here too (e.g. legacy "Home")
+    // — filter by template name to skip them.
+    const tenants = tenantCandidates.filter(isTenantNode);
+    const sites = [];
+    for (const tenant of tenants) {
+        const tenantChildren = await fetchChildren(environment, tenant.path);
+        for (const child of tenantChildren) {
+            if (!isSiteNode(child))
+                continue;
+            const site = {
+                name: child.name,
+                displayName: child.displayName?.trim() || child.name,
+                path: child.path,
+                tenantName: tenant.name,
+                tenantPath: tenant.path,
+            };
+            if (options.includeHostnames) {
+                site.hostnames = await fetchHostnames(environment, child.path);
+            }
+            sites.push(site);
+        }
+    }
+    return sites;
+};
+exports.discoverSites = discoverSites;

package/dist/recipe/api/sites-client.d.ts

@@ -0,0 +1,48 @@
+import { type Job, type JobResponse, type Language, type NewSiteInput, type Site, type SiteCollection, type SiteTemplate, type SitesApiClientOptions as RawSitesApiClientOptions } from "../../sites/api";
+/**
+ * Sites API client surface for recipe execution.
+ *
+ * The recipe planner and executor depend only on this interface — they
+ * don't reach into `src/sites/api/*` directly. Production runs use
+ * `createSitesApiClient(options)`, which adapts the function-style
+ * Sites API surface into the interface; tests inject a mock — same
+ * seam either way (parallel to how `AuthoringApiClient` works).
+ *
+ * Surface is the recipe-required subset:
+ *   - `createSite` for `CreateSiteFromTemplate` ops
+ *   - `getJobStatus` for awaiting async createSite completion
+ *   - `listSites` for idempotency check (does this siteName exist?)
+ *   - `listSiteTemplates` for diagnostics (which templates are usable?)
+ *   - `listCollections` for resolving `collectionId`
+ *   - `listLanguages` + `addLanguage` for ensuring required language(s)
+ *     are present before site creation
+ *
+ * Additional Sites API operations (favourites, editor profiles, hosts,
+ * aggregation) live in `src/sites/api/*` and are not part of this
+ * recipe-execution surface — they belong to the broader CLI subcommand
+ * tree, not the push pipeline.
+ */
+export interface SitesApiClient {
+    createSite(input: NewSiteInput): Promise<JobResponse>;
+    getJobStatus(jobHandle: string): Promise<Job>;
+    listSites(): Promise<Site[]>;
+    listSiteTemplates(): Promise<SiteTemplate[]>;
+    listCollections(): Promise<SiteCollection[]>;
+    listLanguages(): Promise<Language[]>;
+    /**
+     * Add a language to the environment by ISO code (e.g. `"en"`, `"da"`,
+     * `"fr-CA"`). The Sites API distinguishes language code from
+     * regional code; the recipe push pipeline only needs to declare the
+     * language code. If the language is already present, the API
+     * surfaces a 409-style error which the executor treats as success.
+     */
+    addLanguage(languageCode: string): Promise<Language>;
+}
+/**
+ * Adapter: build a `SitesApiClient` over the function-style Sites API
+ * surface. The `options` arg carries the OAuth-resolved auth header and
+ * base URL; the underlying `sitesRequest` re-uses these per call.
+ */
+export declare const createSitesApiClient: (options: RawSitesApiClientOptions) => SitesApiClient;
+export type { Job, JobResponse, Language, NewSiteInput, Site, SiteCollection, SiteTemplate, };
+//# sourceMappingURL=sites-client.d.ts.map

package/dist/recipe/api/sites-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sites-client.d.ts","sourceRoot":"","sources":["../../../src/recipe/api/sites-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,GAAG,EACR,KAAK,WAAW,EAChB,KAAK,QAAQ,EAKb,KAAK,YAAY,EACjB,KAAK,IAAI,EACT,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,qBAAqB,IAAI,wBAAwB,EACvD,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACtD,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC9C,SAAS,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAC7B,iBAAiB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAC7C,eAAe,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAC7C,aAAa,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IACrC;;;;;;OAMG;IACH,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACtD;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAC/B,SAAS,wBAAwB,KAChC,cAQD,CAAC;AAEH,YAAY,EACV,GAAG,EACH,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,IAAI,EACJ,cAAc,EACd,YAAY,GACb,CAAC"}

package/dist/recipe/api/sites-client.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSitesApiClient = void 0;
+const api_1 = require("../../sites/api");
+/**
+ * Adapter: build a `SitesApiClient` over the function-style Sites API
+ * surface. The `options` arg carries the OAuth-resolved auth header and
+ * base URL; the underlying `sitesRequest` re-uses these per call.
+ */
+const createSitesApiClient = (options) => ({
+    createSite: (input) => (0, api_1.createSite)(options, input),
+    getJobStatus: (jobHandle) => (0, api_1.getJobStatus)(options, jobHandle),
+    listSites: () => (0, api_1.listSites)(options),
+    listSiteTemplates: () => (0, api_1.listSiteTemplates)(options),
+    listCollections: () => (0, api_1.listCollections)(options),
+    listLanguages: () => (0, api_1.listLanguages)(options),
+    addLanguage: (languageCode) => (0, api_1.addLanguage)(options, { languageCode }),
+});
+exports.createSitesApiClient = createSitesApiClient;

package/dist/recipe/cache.d.ts

@@ -0,0 +1,36 @@
+import type { OperationIr } from "./ir/operations";
+export interface RecipeCacheEntry {
+    irHash: string;
+    lastApplied: string;
+    summary: {
+        create: number;
+        update: number;
+        skip: number;
+    };
+}
+export interface RecipeCacheTenant {
+    rootsHash: string;
+    recipes: Record<string, RecipeCacheEntry>;
+}
+export interface RecipeCacheFile {
+    schemaVersion: "1";
+    tenants: Record<string, RecipeCacheTenant>;
+}
+export declare const hashIr: (ir: OperationIr) => string;
+/**
+ * Hash the env-profile roots that affect IR compilation. When any of
+ * these change, the IR shape changes and the cached `irHash` is no
+ * longer comparable — the cache entry is invalidated.
+ */
+export declare const hashRoots: (roots: Record<string, string | undefined>) => string;
+export declare const loadRecipeCache: (configDir: string) => Promise<RecipeCacheFile>;
+export declare const saveRecipeCache: (configDir: string, cache: RecipeCacheFile) => Promise<void>;
+/**
+ * Decide whether an IR can be skipped based on the cache. Returns
+ * `null` when no cached entry applies (different roots hash, missing
+ * entry, or schema mismatch); otherwise returns the cached summary
+ * to surface in the push output.
+ */
+export declare const cachedSkipFor: (cache: RecipeCacheFile, envName: string, rootsHash: string, recipeHandle: string, irHash: string) => RecipeCacheEntry | null;
+export declare const recordCacheEntry: (cache: RecipeCacheFile, envName: string, rootsHash: string, recipeHandle: string, entry: RecipeCacheEntry) => void;
+//# sourceMappingURL=cache.d.ts.map

package/dist/recipe/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/recipe/cache.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3D;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,GAAG,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC5C;AAQD,eAAO,MAAM,MAAM,GAAI,IAAI,WAAW,KAAG,MACsB,CAAC;AAEhE;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,KAAG,MAOrE,CAAC;AAQF,eAAO,MAAM,eAAe,GAAU,WAAW,MAAM,KAAG,OAAO,CAAC,eAAe,CAiBhF,CAAC;AAEF,eAAO,MAAM,eAAe,GAAU,WAAW,MAAM,EAAE,OAAO,eAAe,KAAG,OAAO,CAAC,IAAI,CAI7F,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GACxB,OAAO,eAAe,EACtB,SAAS,MAAM,EACf,WAAW,MAAM,EACjB,cAAc,MAAM,EACpB,QAAQ,MAAM,KACb,gBAAgB,GAAG,IAQrB,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAC3B,OAAO,eAAe,EACtB,SAAS,MAAM,EACf,WAAW,MAAM,EACjB,cAAc,MAAM,EACpB,OAAO,gBAAgB,KACtB,IASF,CAAC"}

package/dist/recipe/cache.js

@@ -0,0 +1,114 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordCacheEntry = exports.cachedSkipFor = exports.saveRecipeCache = exports.loadRecipeCache = exports.hashRoots = exports.hashIr = void 0;
+/**
+ * Recipe-level content-hash skip cache.
+ *
+ * Persists a per-(tenant, recipe) digest of the last successfully-applied
+ * IR alongside a digest of the env-profile roots that influence
+ * compilation. On the next push, recipes whose IR digest + roots digest
+ * both match the cached entry are treated as up-to-date and skipped
+ * entirely — no plan-time reads, no per-op round trips. Trades a
+ * narrow correctness window (out-of-band CMS edits to recipe-owned
+ * items aren't auto-redetected until the recipe source changes) for a
+ * substantial speedup on no-op re-pushes.
+ *
+ * Cache is opt-in via `--skip-unchanged-recipes`; default OFF so the
+ * existing read-then-diff semantics stay the default for human
+ * operators. The orchestrator's automated re-push path is the
+ * intended primary consumer.
+ *
+ * File location: `<configDir>/.scai/recipe-cache.json`. Always-write
+ * after a successful, non-aborted push; never persists partial state.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const CACHE_DIR = ".scai";
+const CACHE_FILE = "recipe-cache.json";
+const SCHEMA_VERSION = "1";
+const cachePath = (configDir) => node_path_1.default.join(configDir, CACHE_DIR, CACHE_FILE);
+const hashIr = (ir) => (0, node_crypto_1.createHash)("sha256").update(JSON.stringify(ir)).digest("hex");
+exports.hashIr = hashIr;
+/**
+ * Hash the env-profile roots that affect IR compilation. When any of
+ * these change, the IR shape changes and the cached `irHash` is no
+ * longer comparable — the cache entry is invalidated.
+ */
+const hashRoots = (roots) => {
+    const ordered = {};
+    for (const key of Object.keys(roots).sort()) {
+        const value = roots[key];
+        if (value !== undefined)
+            ordered[key] = value;
+    }
+    return (0, node_crypto_1.createHash)("sha256").update(JSON.stringify(ordered)).digest("hex");
+};
+exports.hashRoots = hashRoots;
+const isCacheFile = (raw) => {
+    if (!raw || typeof raw !== "object")
+        return false;
+    const file = raw;
+    return file.schemaVersion === SCHEMA_VERSION && typeof file.tenants === "object";
+};
+const loadRecipeCache = async (configDir) => {
+    const filePath = cachePath(configDir);
+    try {
+        const raw = await node_fs_1.promises.readFile(filePath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (isCacheFile(parsed))
+            return parsed;
+    }
+    catch (error) {
+        // ENOENT → first run. Anything else (corrupted JSON, stale schema)
+        // also returns an empty cache; we'd rather rebuild silently than
+        // fail the push. The next save overwrites the bad file.
+        if (error.code !== "ENOENT") {
+            // Corruption — treat as empty cache. (Could log via the caller's
+            // logger but this path is hot and shouldn't pull in a logger
+            // dependency.)
+        }
+    }
+    return { schemaVersion: SCHEMA_VERSION, tenants: {} };
+};
+exports.loadRecipeCache = loadRecipeCache;
+const saveRecipeCache = async (configDir, cache) => {
+    const filePath = cachePath(configDir);
+    await node_fs_1.promises.mkdir(node_path_1.default.dirname(filePath), { recursive: true });
+    await node_fs_1.promises.writeFile(filePath, `${JSON.stringify(cache, null, 2)}\n`, "utf8");
+};
+exports.saveRecipeCache = saveRecipeCache;
+/**
+ * Decide whether an IR can be skipped based on the cache. Returns
+ * `null` when no cached entry applies (different roots hash, missing
+ * entry, or schema mismatch); otherwise returns the cached summary
+ * to surface in the push output.
+ */
+const cachedSkipFor = (cache, envName, rootsHash, recipeHandle, irHash) => {
+    const tenant = cache.tenants[envName];
+    if (!tenant)
+        return null;
+    if (tenant.rootsHash !== rootsHash)
+        return null;
+    const entry = tenant.recipes[recipeHandle];
+    if (!entry)
+        return null;
+    if (entry.irHash !== irHash)
+        return null;
+    return entry;
+};
+exports.cachedSkipFor = cachedSkipFor;
+const recordCacheEntry = (cache, envName, rootsHash, recipeHandle, entry) => {
+    let tenant = cache.tenants[envName];
+    if (!tenant || tenant.rootsHash !== rootsHash) {
+        // Roots changed → drop all stale entries for this tenant; the
+        // next save persists only the freshly-validated ones.
+        tenant = { rootsHash, recipes: {} };
+        cache.tenants[envName] = tenant;
+    }
+    tenant.recipes[recipeHandle] = entry;
+};
+exports.recordCacheEntry = recordCacheEntry;

package/dist/recipe/compile/component-section.d.ts

@@ -0,0 +1,46 @@
+import { type OperationIr } from "../ir/operations";
+import { type ComponentSectionRecipe } from "../schema/recipe";
+import { type CompileContext } from "./shared";
+/**
+ * Compile a `ComponentSectionRecipe` to an Operation IR.
+ *
+ * Owns the three SECTION-LEVEL organisational items (one each per
+ * `(site, section.name)`):
+ *
+ *   1. Templates section folder        — `<componentsRoot>/<name>/`
+ *   4. Renderings-tree section folder  — `<renderingsRoot>/<name>/`
+ *   5. Headless Variants section       — `<headlessVariantsRoot>/<name>/`
+ *
+ * Each carries the recipe's `displayName`, `icon`, and `sortOrder`
+ * fields so the SXA editor's tree shows the section with the author's
+ * intent. `compileRecipeSet` MUST process section recipes BEFORE
+ * component recipes — the per-section sentinels seeded into
+ * `emittedFolders` here make subsequent `ensureSectionFolder` /
+ * `ensureRenderingsSectionFolder` calls from component recipes
+ * no-op-with-the-section-already-existing.
+ *
+ * The two SUBORDINATE buckets (#2 Component Folders, #3 Presentation
+ * Parameters) are NOT emitted here — they're emitted lazily by
+ * `ensureComponentFoldersBucket` / `ensurePresentationParametersBucket`
+ * when a component recipe in the section actually needs them. They live
+ * under the section folder so they inherit positional context but get
+ * the default `FOLDER_ICON` (no per-bucket rich fields by design).
+ *
+ * The Available Renderings item (#6) is emitted by the cross-recipe
+ * aggregate `buildAvailableRenderingsAggregate` in `compile.ts`; it
+ * reads sections via the same `sectionsByHandle` map and applies the
+ * section recipe's `displayName` to the toolbox label.
+ */
+export declare function compileComponentSectionRecipe(input: ComponentSectionRecipe, context: CompileContext, emittedFolders?: Set<string>): OperationIr;
+/**
+ * Look up a `ComponentSectionRecipe` by handle. Throws INPUT_INVALID
+ * with a helpful hint when a component references a section handle no
+ * `ComponentSectionRecipe` in the set provides — this is the
+ * cross-recipe validation that closes the implicit-fallback gap the
+ * old `section: string` field had.
+ *
+ * `consumerHandle` is the recipe doing the lookup (used in the error
+ * message so authors can locate the source of the bad reference).
+ */
+export declare const resolveSectionRecipe: (consumerHandle: string, sectionHandle: string, sectionsByHandle: ReadonlyMap<string, ComponentSectionRecipe> | undefined) => ComponentSectionRecipe;
+//# sourceMappingURL=component-section.d.ts.map

package/dist/recipe/compile/component-section.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-section.d.ts","sourceRoot":"","sources":["../../../src/recipe/compile/component-section.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,KAAK,WAAW,EAEjB,MAAM,kBAAkB,CAAC;AAO1B,OAAO,EACL,KAAK,sBAAsB,EAE5B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAKL,KAAK,cAAc,EACpB,MAAM,UAAU,CAAC;AAElB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,sBAAsB,EAC7B,OAAO,EAAE,cAAc,EACvB,cAAc,GAAE,GAAG,CAAC,MAAM,CAAa,GACtC,WAAW,CAyFb;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,GAC/B,gBAAgB,MAAM,EACtB,eAAe,MAAM,EACrB,kBAAkB,WAAW,CAAC,MAAM,EAAE,sBAAsB,CAAC,GAAG,SAAS,KACxE,sBAYF,CAAC"}