@sitecoreai-labs/sitecoreai-cli 0.0.4

package/dist/recipe/plan.js

@@ -0,0 +1,565 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPlan = exports.buildAction = void 0;
+const sitecore_templates_1 = require("./ir/sitecore-templates");
+const ref_encoding_1 = require("./api/ref-encoding");
+const lookupField = (remote, fieldId, fieldName, language, version) => remote.fields.find((f) => {
+    // Match by name when the IR carries one — recipe-created field GUIDs
+    // are IR-internal refKeys that don't match the tenant's actual GUIDs,
+    // so name is the only reliable selector. Else match by GUID (system
+    // fields' GUIDs are real Sitecore built-ins).
+    const idMatches = fieldName
+        ? f.name === fieldName
+        : f.fieldId.toLowerCase() === fieldId.toLowerCase();
+    return (idMatches &&
+        // Sitecore Authoring GraphQL doesn't return per-field language/version
+        // on the basic `Item.fields` query — `f.language`/`f.version` are
+        // typically undefined. Match only when the recipe's filter is also
+        // undefined or when the API DID return them (custom integrations).
+        (language === undefined || f.language === undefined || f.language === language) &&
+        (version === undefined || f.version === undefined || f.version === version));
+});
+/** Resolve every recipe-ref / source-prefix in a field value list. */
+const resolveAll = (fields, capturedItemIds) => fields.map((field) => ({
+    ...field,
+    value: (0, ref_encoding_1.resolveRecipeRefs)(field.value, capturedItemIds),
+}));
+const computeFieldDrift = (desired, remote, capturedItemIds) => {
+    const drift = [];
+    for (const field of desired) {
+        const resolvedValue = (0, ref_encoding_1.resolveRecipeRefs)(field.value, capturedItemIds);
+        const want = (0, ref_encoding_1.renderRefValue)(resolvedValue);
+        const found = lookupField(remote, field.fieldId, field.fieldName, field.language, field.version);
+        if (!found) {
+            drift.push({
+                fieldId: field.fieldId,
+                before: null,
+                after: want,
+                language: field.language,
+                version: field.version,
+            });
+            continue;
+        }
+        if (found.value !== want) {
+            drift.push({
+                fieldId: field.fieldId,
+                before: found.value,
+                after: want,
+                language: field.language,
+                version: field.version,
+            });
+        }
+    }
+    return drift;
+};
+/**
+ * Resolve a CreateItem op's parent ref to a Sitecore itemId.
+ *
+ * Sitecore's `createItem` requires `parent: ID!` (a GUID). Path-only
+ * parents (`ref-path`) are looked up via `getItem({ path })` and cached
+ * in `capturedItemIds` keyed by the path string itself. Recipe-internal
+ * `ref-recipe` parents resolve via the same map keyed by their refKey,
+ * populated as parent ops apply.
+ *
+ * Returns `unresolvedRefKey` only when a `ref-recipe` parent's CreateItem
+ * has not yet captured an itemId (plan-mode against an empty tenant
+ * before applies happen).
+ */
+const resolveCreateItemParent = (op, capturedItemIds) => {
+    if (op.parent.kind === "ref-path") {
+        const cached = capturedItemIds.get(op.parent.value);
+        if (cached)
+            return { resolved: cached };
+        // Plan-mode fallback when the path lookup returned null (tenant
+        // doesn't have it yet, or we're testing without a live tenant).
+        return { resolved: op.parent.value };
+    }
+    const itemId = capturedItemIds.get(op.parent.refKey);
+    if (itemId) {
+        return { resolved: itemId };
+    }
+    // Plan-mode preview fallback: when the parent's CreateItem hasn't run
+    // yet (captured map empty), derive the parent path from op.path. Apply-
+    // mode normally fills the captured map before children dispatch, so this
+    // branch is mostly for `recipe plan` output.
+    const trail = `/${op.name}`;
+    if (op.path.endsWith(trail)) {
+        const parentPath = op.path.slice(0, -trail.length);
+        if (parentPath) {
+            return { resolved: parentPath };
+        }
+    }
+    return { unresolvedRefKey: op.parent.refKey };
+};
+/** Resolve a CreateItem op's templateOf — usually a constant Sitecore GUID,
+ *  but the SV item case has it as the recipe's own template refKey. */
+const resolveTemplateOf = (op, capturedItemIds) => {
+    // If templateOf matches a refKey in our captured map, resolve it.
+    // Otherwise it's a known Sitecore built-in GUID and we use as-is.
+    const captured = capturedItemIds.get(op.templateOf);
+    if (captured) {
+        return { resolved: captured };
+    }
+    // Known Sitecore built-in (Template, Section, Field, Folder, Rendering, etc.).
+    return { resolved: op.templateOf };
+};
+const planCreateItem = (op, remote, index, capturedItemIds) => {
+    if (!remote) {
+        const parent = resolveCreateItemParent(op, capturedItemIds);
+        if ("unresolvedRefKey" in parent) {
+            return {
+                index,
+                operation: op,
+                status: "skip",
+                reason: `Parent ref ${parent.unresolvedRefKey} not yet captured (parent's CreateItem hasn't run).`,
+            };
+        }
+        const tpl = resolveTemplateOf(op, capturedItemIds);
+        if ("unresolvedRefKey" in tpl) {
+            return {
+                index,
+                operation: op,
+                status: "skip",
+                reason: `templateOf ref ${tpl.unresolvedRefKey} not yet captured.`,
+            };
+        }
+        // Plan-mode preview tolerates unresolved field refs: we report status
+        // create, but omit the mutation snapshot until apply-mode actually
+        // captures the dependent itemIds. Apply-mode populates the captured
+        // map as it goes, so by the time a child op runs its parents' refs
+        // are present and resolveAll succeeds.
+        let resolvedFields;
+        try {
+            resolvedFields = resolveAll(op.fields, capturedItemIds);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                index,
+                operation: op,
+                status: "create",
+                reason: `Plan preview: ${message}`,
+            };
+        }
+        return {
+            index,
+            operation: op,
+            status: "create",
+            mutation: {
+                kind: "createItem",
+                input: {
+                    parent: parent.resolved,
+                    templateId: tpl.resolved,
+                    name: op.name,
+                    fields: resolvedFields,
+                },
+            },
+        };
+    }
+    if (op.policy === "CreateOnly") {
+        return {
+            index,
+            operation: op,
+            status: "skip",
+            reason: "Item already exists and policy is CreateOnly.",
+        };
+    }
+    const drift = computeFieldDrift(op.fields, remote, capturedItemIds);
+    if (drift.length === 0) {
+        return {
+            index,
+            operation: op,
+            status: "skip",
+            reason: "Item exists and all tracked fields match.",
+        };
+    }
+    const driftedSet = new Set(drift.map((d) => `${d.fieldId}:${d.language ?? ""}:${d.version ?? ""}`));
+    const fieldsToSet = resolveAll(op.fields.filter((f) => driftedSet.has(`${f.fieldId}:${f.language ?? ""}:${f.version ?? ""}`)), capturedItemIds);
+    return {
+        index,
+        operation: op,
+        status: "update",
+        diff: drift,
+        mutation: {
+            kind: "updateItem",
+            input: { itemId: remote.itemId, fields: fieldsToSet },
+        },
+    };
+};
+const planUpdateOp = (index, op, itemRefKey, desiredFields, policy, remote, capturedItemIds) => {
+    if (!remote) {
+        return {
+            index,
+            operation: op,
+            status: "skip",
+            reason: `Target item (refKey ${itemRefKey}) not yet captured/created.`,
+        };
+    }
+    const drift = computeFieldDrift(desiredFields, remote, capturedItemIds);
+    if (drift.length === 0) {
+        return {
+            index,
+            operation: op,
+            status: "skip",
+            reason: "Field already at desired value.",
+        };
+    }
+    if (policy === "CreateOnly") {
+        const allBlankBefore = drift.every((d) => d.before === null || d.before === "");
+        if (!allBlankBefore) {
+            return {
+                index,
+                operation: op,
+                status: "skip",
+                reason: "Field already set; CreateOnly policy preserves CMS edits.",
+            };
+        }
+    }
+    return {
+        index,
+        operation: op,
+        status: "update",
+        diff: drift,
+        mutation: {
+            kind: "updateItem",
+            input: {
+                itemId: remote.itemId,
+                fields: resolveAll(desiredFields, capturedItemIds),
+            },
+        },
+    };
+};
+const setFieldDesired = (op) => [
+    {
+        fieldId: op.fieldId,
+        fieldName: op.fieldName,
+        language: op.language,
+        version: op.version,
+        value: op.value,
+    },
+];
+const setBaseTemplatesDesired = (op) => [
+    {
+        fieldId: sitecore_templates_1.SYSTEM_FIELDS.BASE_TEMPLATE,
+        value: { kind: "ref-guid-list", values: op.baseTemplates },
+    },
+];
+const setStandardValuesDesired = (op) => [
+    {
+        fieldId: sitecore_templates_1.SYSTEM_FIELDS.STANDARD_VALUES,
+        value: { kind: "ref-recipe", refKey: op.standardValuesRefKey },
+    },
+];
+/**
+ * Compute the lookup selector for a given op. CreateItem looks up by
+ * path; update-style ops look up by the captured itemId for their target
+ * refKey. Returns `null` when the captured map doesn't have the refKey
+ * yet — that signals the planner to skip.
+ */
+const lookupSelector = (op, capturedItemIds) => {
+    if (op.op === "CreateItem") {
+        return { path: op.path };
+    }
+    if (op.op === "CreateSiteFromTemplate") {
+        // Site idempotency lookup goes through SitesApiClient.listSites, not
+        // Authoring API getItem; planCreateSite handles the lookup itself.
+        return null;
+    }
+    let refKey;
+    if (op.op === "SetField" || op.op === "SetBaseTemplates") {
+        refKey = op.itemRefKey;
+    }
+    else if (op.op === "SetStandardValues") {
+        refKey = op.templateRefKey;
+    }
+    else {
+        // AppendToMultiList — target item is keyed by itemRefKey, same as SetField.
+        refKey = op.itemRefKey;
+    }
+    const itemId = capturedItemIds.get(refKey);
+    return itemId ? { itemId } : null;
+};
+/**
+ * Plan a single op against the current remote state. Exposed so the
+ * executor's apply mode can interleave plan-and-apply per-op (each op's
+ * plan sees the cascading effect of earlier ops' applies — required for
+ * idempotency: a second push must see no drift on update-style ops whose
+ * targets the first push created).
+ *
+ * Updates `capturedItemIds` when `getItem(by path)` finds an existing
+ * item (so subsequent ops can resolve refs without dispatching).
+ *
+ * When a `pathSnapshotCache` is provided (workspace prefetch), each
+ * `getItem({ path })` call short-circuits to the cached value when the
+ * path is already known — `null` means "checked and missing", a
+ * `RemoteItem` means "use this snapshot". Non-path lookups (by itemId)
+ * still hit the wire.
+ */
+const buildAction = async (index, op, client, capturedItemIds, sitesClient, pathSnapshotCache) => {
+    const cachedReadByPath = async (path) => {
+        if (pathSnapshotCache?.has(path)) {
+            return pathSnapshotCache.get(path) ?? null;
+        }
+        const remote = await client.getItem({ path });
+        pathSnapshotCache?.set(path, remote);
+        return remote;
+    };
+    // Late-path resolution: SetField ops whose target is materialised
+    // mid-push (e.g. dictionary phrases under a CreateSiteFromTemplate)
+    // carry an optional `latePath`. If the op's itemRefKey isn't yet in
+    // the captured map AND a latePath is set, do an on-demand getItem
+    // lookup to seed the map BEFORE lookupSelector runs. Without this,
+    // lookupSelector sees no captured itemId and the SetField skips
+    // with "not yet captured/created" — even though the item exists.
+    if ((op.op === "SetField" || op.op === "AppendToMultiList") &&
+        op.latePath &&
+        !capturedItemIds.has(op.itemRefKey)) {
+        const lateRemote = await cachedReadByPath(op.latePath);
+        if (lateRemote) {
+            capturedItemIds.set(op.itemRefKey, lateRemote.itemId);
+        }
+    }
+    const selector = lookupSelector(op, capturedItemIds);
+    const remote = await (async () => {
+        if (!selector)
+            return null;
+        if (selector.path)
+            return cachedReadByPath(selector.path);
+        return client.getItem(selector);
+    })();
+    if (op.op === "CreateItem" && remote) {
+        capturedItemIds.set(op.id, remote.itemId);
+    }
+    // For CreateItem with a path-only parent (top-level items like the
+    // configured templatesRoot/renderingsRoot), resolve the parent path to
+    // its Sitecore-assigned itemId once and cache it on the captured map
+    // keyed by path. The Authoring API requires `parent: ID!` (GUID) on
+    // createItem; passing a path errors with "String→Guid" conversion.
+    if (op.op === "CreateItem" && op.parent.kind === "ref-path") {
+        const parentPath = op.parent.value;
+        if (!capturedItemIds.has(parentPath)) {
+            const parentRemote = await cachedReadByPath(parentPath);
+            if (parentRemote) {
+                capturedItemIds.set(parentPath, parentRemote.itemId);
+            }
+        }
+    }
+    const action = await (async () => {
+        switch (op.op) {
+            case "CreateItem":
+                return planCreateItem(op, remote, index, capturedItemIds);
+            case "SetField":
+                return planUpdateOp(index, op, op.itemRefKey, setFieldDesired(op), op.policy, remote, capturedItemIds);
+            case "SetBaseTemplates":
+                return planUpdateOp(index, op, op.itemRefKey, setBaseTemplatesDesired(op), op.policy, remote, capturedItemIds);
+            case "SetStandardValues":
+                return planUpdateOp(index, op, op.templateRefKey, setStandardValuesDesired(op), op.policy, remote, capturedItemIds);
+            case "CreateSiteFromTemplate":
+                return planCreateSite(index, op, capturedItemIds, sitesClient);
+            case "AppendToMultiList":
+                return planAppendToMultiList(index, op, remote, capturedItemIds);
+        }
+    })();
+    return { ...action, snapshot: remote };
+};
+exports.buildAction = buildAction;
+/**
+ * Parse a Sitecore multi-list field value (pipe-separated GUIDs, each
+ * either bare or curly-wrapped) into a normalised lowercase, no-curly
+ * GUID set. Tolerates extra whitespace / empty entries from operator
+ * edits.
+ */
+const parseMultiList = (value) => {
+    if (!value)
+        return [];
+    return value
+        .split("|")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0)
+        .map((s) => s.replace(/^\{|\}$/g, "").toLowerCase());
+};
+const formatMultiList = (guids) => guids.map((g) => `{${g.toUpperCase()}}`).join("|");
+/**
+ * Plan an `AppendToMultiList` op. Reads the target's current field
+ * value, computes the union with the desired values (resolving recipe
+ * refs first), and emits an updateItem mutation only when the merge
+ * adds something new — otherwise a skip with a clear reason.
+ */
+const planAppendToMultiList = (index, op, remote, capturedItemIds) => {
+    if (!remote) {
+        return {
+            index,
+            operation: op,
+            status: "skip",
+            reason: `Target item (refKey ${op.itemRefKey}) not yet captured — section definition may not exist or path lookup hasn't run.`,
+        };
+    }
+    // Resolve every desired value into a concrete GUID. ref-recipe entries
+    // resolve via the captured map; ref-guid entries pass through.
+    const desired = [];
+    for (const entry of op.values) {
+        if (entry.kind === "ref-guid") {
+            desired.push(entry.value.toLowerCase());
+        }
+        else {
+            const itemId = capturedItemIds.get(entry.refKey);
+            if (!itemId) {
+                return {
+                    index,
+                    operation: op,
+                    status: "skip",
+                    reason: `AppendToMultiList: refKey ${entry.refKey} not yet captured — producer recipe hasn't landed.`,
+                };
+            }
+            desired.push(itemId.toLowerCase());
+        }
+    }
+    // Read the current field value — match by name when carried (recipe-
+    // defined fields), else by GUID (system fields).
+    const found = remote.fields.find((f) => {
+        const idMatches = op.fieldName
+            ? f.name === op.fieldName
+            : f.fieldId.toLowerCase() === op.fieldId.toLowerCase();
+        return idMatches;
+    });
+    const existing = parseMultiList(found?.value ?? null);
+    const existingSet = new Set(existing);
+    const additions = desired.filter((g) => !existingSet.has(g));
+    if (additions.length === 0) {
+        return {
+            index,
+            operation: op,
+            status: "skip",
+            reason: "All desired values already present in multi-list (merge-unique).",
+        };
+    }
+    const merged = [...existing, ...additions];
+    const updatedField = {
+        fieldId: op.fieldId,
+        ...(op.fieldName !== undefined && { fieldName: op.fieldName }),
+        value: { kind: "string", value: formatMultiList(merged) },
+    };
+    return {
+        index,
+        operation: op,
+        status: "update",
+        diff: [
+            {
+                fieldId: op.fieldId,
+                before: found?.value ?? null,
+                after: formatMultiList(merged),
+            },
+        ],
+        mutation: {
+            kind: "updateItem",
+            input: { itemId: remote.itemId, fields: [updatedField] },
+        },
+    };
+};
+/**
+ * Plan a `CreateSiteFromTemplate` op. Idempotency lookup goes through
+ * `SitesApiClient.listSites` (filter by name) — the Sites API doesn't
+ * resolve site instances by Sitecore content-tree path the way Authoring
+ * API does for items.
+ *
+ * Outcomes:
+ *   - sitesClient missing → status: error (executor was not threaded one)
+ *   - templateRefKey not yet captured → status: skip (the SiteTemplate
+ *     hasn't been pushed; cross-recipe ref pre-seeding will pick it up
+ *     on the next push)
+ *   - site already exists with the same name → status: skip; capture
+ *     the existing site's itemId so subsequent SetField overrides resolve
+ *   - site doesn't exist → status: create; mutation `createSite` carries
+ *     a fully-resolved NewSiteInput plus the op's siteRefKey
+ *
+ * "Already exists with a different template" is NOT detected here —
+ * Sites API doesn't expose a clean way to read a site's template
+ * back. If a same-named site references a different template, the
+ * push silently treats it as "skip"; operators must delete and re-push
+ * to switch templates. Tracked as a follow-up.
+ */
+const planCreateSite = async (index, op, capturedItemIds, sitesClient) => {
+    if (!sitesClient) {
+        return {
+            index,
+            operation: op,
+            status: "error",
+            reason: "CreateSiteFromTemplate requires a SitesApiClient — none was provided to the executor.",
+        };
+    }
+    const templateId = capturedItemIds.get(op.templateRefKey);
+    if (!templateId) {
+        return {
+            index,
+            operation: op,
+            status: "skip",
+            reason: `siteTemplate refKey ${op.templateRefKey} not yet captured (push the SiteTemplate first or via cross-recipe ref).`,
+        };
+    }
+    const sites = await sitesClient.listSites();
+    const existing = sites.find((s) => s.name === op.siteName);
+    if (existing?.id) {
+        capturedItemIds.set(op.siteRefKey, existing.id);
+        return {
+            index,
+            operation: op,
+            status: "skip",
+            reason: `Site '${op.siteName}' already exists.`,
+        };
+    }
+    const input = {
+        siteName: op.siteName,
+        templateId,
+        language: op.language,
+        ...(op.displayName !== undefined && { displayName: op.displayName }),
+        ...(op.description !== undefined && { description: op.description }),
+        ...(op.hostName !== undefined && { hostName: op.hostName }),
+        ...(op.collectionId !== undefined && { collectionId: op.collectionId }),
+        ...(op.collectionName !== undefined && { collectionName: op.collectionName }),
+        ...(op.collectionDisplayName !== undefined && {
+            collectionDisplayName: op.collectionDisplayName,
+        }),
+        ...(op.collectionDescription !== undefined && {
+            collectionDescription: op.collectionDescription,
+        }),
+    };
+    return {
+        index,
+        operation: op,
+        status: "create",
+        mutation: { kind: "createSite", input, siteRefKey: op.siteRefKey },
+    };
+};
+const buildPlan = async (ir, client, options = {}) => {
+    const actions = [];
+    const summary = { create: 0, update: 0, skip: 0, error: 0 };
+    const capturedItemIds = options.capturedItemIds ?? new Map();
+    for (let index = 0; index < ir.operations.length; index += 1) {
+        const op = ir.operations[index];
+        options.emit?.({ kind: "op-start", index, operation: op });
+        let action;
+        try {
+            action = await (0, exports.buildAction)(index, op, client, capturedItemIds, options.sitesClient, options.pathSnapshotCache);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            action = {
+                index,
+                operation: op,
+                status: "error",
+                reason: message,
+            };
+            options.emit?.({ kind: "op-error", index, operation: op, error: message });
+        }
+        summary[action.status] += 1;
+        actions.push(action);
+        options.emit?.({ kind: "op-result", action });
+    }
+    return {
+        schemaVersion: "1",
+        recipeHandle: ir.recipeHandle,
+        actions,
+        summary,
+    };
+};
+exports.buildPlan = buildPlan;

package/dist/recipe/policy.d.ts

@@ -0,0 +1,43 @@
+import type { Operation, PushPolicy } from "./ir/operations";
+import type { Recipe } from "./schema/recipe";
+/**
+ * Policy assignment for compiler-emitted operations.
+ *
+ * Phase 1: every op a recipe emits is `CreateAndUpdate` — the registry is
+ * the source of truth for templates, sections, fields, renderings, and
+ * variants. Authors should not edit those in the CMS; if they do, a
+ * registry deploy overwrites.
+ *
+ * Phase 3 (datasource items, page items) introduces `CreateOnly`: the
+ * registry seeds initial content, the CMS owns it thereafter. The
+ * `policyFor` switch is the single seam to add that distinction without
+ * rewriting every emission site in `compile.ts`.
+ */
+/**
+ * The kind of op being emitted. Phase 1 only has `template-structure`
+ * ops; Phase 3+ adds `datasource-item` and `page-item`. Phase 4 adds
+ * `composition-structure` for partials and page designs (registry-owned
+ * compositional artifacts, like component templates — `CreateAndUpdate`).
+ */
+export type OpPurpose = "template-structure" | "composition-structure" | "datasource-item" | "page-item";
+export declare const purposeForRecipe: (kind: Recipe["kind"]) => OpPurpose;
+/**
+ * Policy assignment, given the purpose of the op being emitted. Phase 1
+ * collapses to a single value; future phases add branches here.
+ */
+export declare const policyFor: (purpose: OpPurpose) => PushPolicy;
+/**
+ * Convenience: the default policy a recipe of the given kind should attach
+ * to every op it emits. Compiler call site:
+ *
+ *   const policy = defaultPolicyForRecipe(recipe.kind);
+ *   operations.push({ op: "CreateItem", policy, ... });
+ */
+export declare const defaultPolicyForRecipe: (kind: Recipe["kind"]) => PushPolicy;
+/**
+ * Type guard for narrowing op kinds — exposed so consumers (planner,
+ * executor, telemetry) can dispatch on policy without re-implementing the
+ * mapping.
+ */
+export declare const policyForOp: (op: Operation) => PushPolicy;
+//# sourceMappingURL=policy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/recipe/policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAE9C;;;;;;;;;;;;GAYG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GACjB,oBAAoB,GACpB,uBAAuB,GACvB,iBAAiB,GACjB,WAAW,CAAC;AA0ChB,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,CAAC,MAAM,CAAC,KAAG,SAAyC,CAAC;AAElG;;;GAGG;AACH,eAAO,MAAM,SAAS,GAAI,SAAS,SAAS,KAAG,UAS9C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,GAAI,MAAM,MAAM,CAAC,MAAM,CAAC,KAAG,UAC3B,CAAC;AAEpC;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,IAAI,SAAS,KAAG,UAAuB,CAAC"}

package/dist/recipe/policy.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.policyForOp = exports.defaultPolicyForRecipe = exports.policyFor = exports.purposeForRecipe = void 0;
+const PURPOSE_BY_RECIPE_KIND = {
+    // Component sections own organisational folders that components live
+    // under (templates section folder, renderings section folder, etc.).
+    // Registry-owned structure — CreateAndUpdate so re-pushes can update
+    // the section's display name / icon / sort order.
+    "component-section": "template-structure",
+    "component-template": "template-structure",
+    "content-template": "template-structure",
+    "content-item": "datasource-item",
+    // Standalone parameters templates and the synthesised inline-hoisted
+    // ones share the same policy as component templates — they're
+    // registry-owned and should overwrite tenant edits.
+    "parameters-template": "template-structure",
+    // Section definitions are typically tenant-pre-existing; the
+    // compiler emits AppendToMultiList ops against them rather than
+    // CreateItem. Treat as composition-structure so any future
+    // `CreateItem` for a missing section definition lands with the
+    // CreateAndUpdate policy.
+    "section-definition": "composition-structure",
+    "partial-design": "composition-structure",
+    "page-design": "composition-structure",
+    // Site templates are registry-owned brand definitions — the template
+    // item itself + its structural metadata (insert options, designs, etc.)
+    // are template-structure-shaped. Compiler implementation lands in
+    // composition-recipes-site-branches.md Milestone C.
+    "site-template": "composition-structure",
+    // Site instances are operator-driven — the site item is created via
+    // Sites API and its grouping / overrides are operator overrides on
+    // top of the template defaults. Treat as composition-structure for
+    // policy purposes; per-op CreateOnly vs CreateAndUpdate gets
+    // refined when the executor lands (Milestone D).
+    site: "composition-structure",
+    // Enumerations are registry-owned vocabulary. CreateAndUpdate so
+    // re-pushes flip displayName edits and add/remove value items as
+    // the recipe evolves. Authors who need extra values can add them
+    // to the recipe and re-push; CMS edits to enumeration items get
+    // overwritten.
+    enumeration: "template-structure",
+};
+const purposeForRecipe = (kind) => PURPOSE_BY_RECIPE_KIND[kind];
+exports.purposeForRecipe = purposeForRecipe;
+/**
+ * Policy assignment, given the purpose of the op being emitted. Phase 1
+ * collapses to a single value; future phases add branches here.
+ */
+const policyFor = (purpose) => {
+    switch (purpose) {
+        case "template-structure":
+        case "composition-structure":
+            return "CreateAndUpdate";
+        case "datasource-item":
+        case "page-item":
+            return "CreateOnly";
+    }
+};
+exports.policyFor = policyFor;
+/**
+ * Convenience: the default policy a recipe of the given kind should attach
+ * to every op it emits. Compiler call site:
+ *
+ *   const policy = defaultPolicyForRecipe(recipe.kind);
+ *   operations.push({ op: "CreateItem", policy, ... });
+ */
+const defaultPolicyForRecipe = (kind) => (0, exports.policyFor)((0, exports.purposeForRecipe)(kind));
+exports.defaultPolicyForRecipe = defaultPolicyForRecipe;
+/**
+ * Type guard for narrowing op kinds — exposed so consumers (planner,
+ * executor, telemetry) can dispatch on policy without re-implementing the
+ * mapping.
+ */
+const policyForOp = (op) => op.policy;
+exports.policyForOp = policyForOp;