@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/recipe/compile/workflow.js

@@ -0,0 +1,368 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileWorkflowRecipe = compileWorkflowRecipe;
+const errors_1 = require("../../shared/errors");
+const guids_1 = require("../guids");
+const operations_1 = require("../ir/operations");
+const sitecore_templates_1 = require("../ir/sitecore-templates");
+const policy_1 = require("../policy");
+const recipe_1 = require("../schema/recipe");
+const shared_1 = require("./shared");
+const uuid_1 = require("uuid");
+/**
+ * Compile a `WorkflowRecipe` to an Operation IR.
+ *
+ * Emits, in execution order:
+ *
+ *   1. Optional `Workflow Folder` group folder under
+ *      `/sitecore/system/Workflows/<group>` (when `meta.tax.group` is set).
+ *   2. The workflow item itself, conforming to Sitecore's `Workflow`
+ *      template (path-resolved at apply time via `templateOf: ref-path`).
+ *   3. One state item per `recipe.states[]`, conforming to the
+ *      `State` template; carries `Final` and `Preview` fields.
+ *   4. A `SetField` on the workflow item setting `__Initial state` to
+ *      a recipe-ref pointing at the initial state.
+ *   5. One command item per `state.commands[]`, conforming to the
+ *      `Command` template; carries `Next state`, `__Auto Publish`,
+ *      `Suppress comment`, `Appearance Evaluator Type`.
+ *   6. One action item per `state.actions[]`, conforming to either
+ *      `Webhook Submit Action` or `Webhook Validation Action`.
+ *   7. One validation item per `command.validations[]` (Webhook
+ *      Validation Action).
+ *   8. One `SetField` op per `bindings.templates[]` entry, writing the
+ *      `__Default workflow` field on each bound template's
+ *      `__Standard Values` item to a `ref-recipe` pointing at the
+ *      workflow item. Entries that look like a recipe handle resolve
+ *      via `standardValuesId(site, handle)` (the matching
+ *      `ContentTemplateRecipe` / `ComponentTemplateRecipe` must ship in
+ *      the same set). Entries that look like an absolute template path
+ *      resolve via `latePath: "<path>/__Standard Values"` so the
+ *      executor seeds the captured-itemId map on demand.
+ *
+ * Workflow-specific field GUIDs are not published as a public contract
+ * by Sitecore. The executor's `FieldValueInput.name` fallback resolves
+ * each field by name against the target item's template at apply time,
+ * so the IR carries arbitrary stable refKey GUIDs for `fieldId` plus
+ * the canonical `fieldName`. Same pattern as recipe-created fields on
+ * registry templates (see `FieldValueSchema.fieldName` comment).
+ *
+ * @throws `INPUT_INVALID` when initialState references an undeclared
+ *   state, when a command's nextState doesn't resolve, when no state is
+ *   final, or when an action declares both authorizationRef and
+ *   authorizationPath.
+ */
+function compileWorkflowRecipe(input, context, emittedFolders = new Set()) {
+    const recipe = recipe_1.WorkflowRecipeSchema.parse(input);
+    validateWorkflowRecipe(recipe);
+    const policy = (0, policy_1.defaultPolicyForRecipe)(recipe.kind);
+    const site = (0, shared_1.siteOf)(context);
+    const operations = [];
+    // 1. Optional group folder.
+    const group = recipe.meta?.tax?.group;
+    const workflowsRoot = "/sitecore/system/Workflows";
+    let parentPath = workflowsRoot;
+    let parentRef = { kind: "ref-path", value: workflowsRoot };
+    if (group) {
+        const groupRefKey = (0, guids_1.workflowGroupFolderId)(group);
+        const groupPath = (0, shared_1.joinPath)(workflowsRoot, group);
+        if (!emittedFolders.has(groupRefKey)) {
+            emittedFolders.add(groupRefKey);
+            operations.push({
+                op: "CreateItem",
+                policy: "CreateOnly",
+                label: `workflow-group:${group}`,
+                id: groupRefKey,
+                path: groupPath,
+                parent: parentRef,
+                templateOf: sitecore_templates_1.SITECORE_TEMPLATES.FOLDER,
+                name: group,
+                fields: [],
+            });
+        }
+        parentPath = groupPath;
+        parentRef = { kind: "ref-recipe", refKey: groupRefKey };
+    }
+    // 2. Workflow item.
+    const workflowRefKey = (0, guids_1.workflowId)(recipe.handle);
+    const workflowPath = (0, shared_1.joinPath)(parentPath, recipe.name);
+    operations.push({
+        op: "CreateItem",
+        policy,
+        label: `workflow:${recipe.handle}`,
+        id: workflowRefKey,
+        path: workflowPath,
+        parent: parentRef,
+        templateOf: { kind: "ref-path", value: TEMPLATE_PATHS.workflow },
+        name: recipe.name,
+        fields: [
+            (0, shared_1.versionedField)(sitecore_templates_1.SYSTEM_FIELDS.DISPLAY_NAME, { kind: "string", value: recipe.displayName }),
+        ],
+    });
+    // 3. State items.
+    for (const state of recipe.states) {
+        const stateRefKey = (0, guids_1.workflowStateId)(recipe.handle, state.key);
+        const statePath = (0, shared_1.joinPath)(workflowPath, state.name);
+        const fields = [
+            (0, shared_1.versionedField)(sitecore_templates_1.SYSTEM_FIELDS.DISPLAY_NAME, { kind: "string", value: state.displayName }),
+        ];
+        if (state.final) {
+            fields.push({
+                ...(0, shared_1.sharedField)(deriveFieldId(workflowRefKey, "Final"), { kind: "bool", value: true }),
+                fieldName: "Final",
+            });
+        }
+        if (state.preview) {
+            fields.push({
+                ...(0, shared_1.sharedField)(deriveFieldId(workflowRefKey, "Preview"), { kind: "bool", value: true }),
+                fieldName: "Preview",
+            });
+        }
+        operations.push({
+            op: "CreateItem",
+            policy,
+            label: `workflow-state:${recipe.handle}:${state.key}`,
+            id: stateRefKey,
+            path: statePath,
+            parent: { kind: "ref-recipe", refKey: workflowRefKey },
+            templateOf: { kind: "ref-path", value: TEMPLATE_PATHS.state },
+            name: state.name,
+            fields,
+        });
+    }
+    // 4. Initial state — set on the workflow item.
+    const initialStateRefKey = (0, guids_1.workflowStateId)(recipe.handle, recipe.initialState);
+    operations.push({
+        op: "SetField",
+        policy,
+        label: `workflow:${recipe.handle}:initial-state`,
+        itemRefKey: workflowRefKey,
+        fieldId: deriveFieldId(workflowRefKey, "__Initial state"),
+        fieldName: "__Initial state",
+        value: { kind: "ref-recipe", refKey: initialStateRefKey },
+    });
+    // 5. Command items + their setting fields. Command items live as
+    //    direct children of their state (not nested under an `Actions`
+    //    subfolder); validations live as direct children of the command.
+    for (const state of recipe.states) {
+        const stateRefKey = (0, guids_1.workflowStateId)(recipe.handle, state.key);
+        const statePath = (0, shared_1.joinPath)(workflowPath, state.name);
+        for (const command of state.commands) {
+            const commandRefKey = (0, guids_1.workflowCommandId)(recipe.handle, state.key, command.key);
+            const commandPath = (0, shared_1.joinPath)(statePath, command.name);
+            const nextStateRefKey = (0, guids_1.workflowStateId)(recipe.handle, command.nextState);
+            operations.push({
+                op: "CreateItem",
+                policy,
+                label: `workflow-command:${recipe.handle}:${state.key}:${command.key}`,
+                id: commandRefKey,
+                path: commandPath,
+                parent: { kind: "ref-recipe", refKey: stateRefKey },
+                templateOf: { kind: "ref-path", value: TEMPLATE_PATHS.command },
+                name: command.name,
+                fields: [
+                    (0, shared_1.versionedField)(sitecore_templates_1.SYSTEM_FIELDS.DISPLAY_NAME, {
+                        kind: "string",
+                        value: command.displayName,
+                    }),
+                    {
+                        ...(0, shared_1.sharedField)(deriveFieldId(commandRefKey, "Next state"), {
+                            kind: "ref-recipe",
+                            refKey: nextStateRefKey,
+                        }),
+                        fieldName: "Next state",
+                    },
+                    {
+                        ...(0, shared_1.sharedField)(deriveFieldId(commandRefKey, "__Auto Publish"), {
+                            kind: "bool",
+                            value: command.autoPublish,
+                        }),
+                        fieldName: "__Auto Publish",
+                    },
+                    {
+                        ...(0, shared_1.sharedField)(deriveFieldId(commandRefKey, "Suppress comment"), {
+                            kind: "bool",
+                            value: command.suppressComment,
+                        }),
+                        fieldName: "Suppress comment",
+                    },
+                    {
+                        ...(0, shared_1.sharedField)(deriveFieldId(commandRefKey, "Appearance Evaluator Type"), {
+                            kind: "string",
+                            value: command.appearanceEvaluator,
+                        }),
+                        fieldName: "Appearance Evaluator Type",
+                    },
+                ],
+            });
+            for (let idx = 0; idx < command.validations.length; idx += 1) {
+                const validation = command.validations[idx];
+                const validationRefKey = (0, guids_1.workflowCommandValidationId)(recipe.handle, state.key, command.key, idx);
+                const validationPath = (0, shared_1.joinPath)(commandPath, validation.key);
+                operations.push({
+                    op: "CreateItem",
+                    policy,
+                    label: `workflow-validation:${recipe.handle}:${state.key}:${command.key}:${validation.key}`,
+                    id: validationRefKey,
+                    path: validationPath,
+                    parent: { kind: "ref-recipe", refKey: commandRefKey },
+                    templateOf: { kind: "ref-path", value: TEMPLATE_PATHS.validationAction },
+                    name: validation.key,
+                    fields: buildActionFields(validationRefKey, validation),
+                });
+            }
+        }
+        // 6. State-level actions (submit or validation).
+        for (let idx = 0; idx < state.actions.length; idx += 1) {
+            const action = state.actions[idx];
+            const actionRefKey = (0, guids_1.workflowStateActionId)(recipe.handle, state.key, idx);
+            const actionPath = (0, shared_1.joinPath)(statePath, action.key);
+            const templatePath = action.kind === "webhook-submit"
+                ? TEMPLATE_PATHS.submitAction
+                : TEMPLATE_PATHS.validationAction;
+            operations.push({
+                op: "CreateItem",
+                policy,
+                label: `workflow-action:${recipe.handle}:${state.key}:${action.key}`,
+                id: actionRefKey,
+                path: actionPath,
+                parent: { kind: "ref-recipe", refKey: stateRefKey },
+                templateOf: { kind: "ref-path", value: templatePath },
+                name: action.key,
+                fields: buildActionFields(actionRefKey, action),
+            });
+        }
+    }
+    // 8. Bindings — point each bound template's `__Default workflow` field
+    //    at this workflow. Intra-recipe handles resolve via the SV refKey
+    //    the matching content/component-template recipe emits; absolute
+    //    template paths resolve via late-path lookup of the SV item.
+    for (const binding of recipe.bindings.templates) {
+        const isPath = binding.startsWith("/sitecore/templates/");
+        const svRefKey = isPath ? (0, guids_1.standardValuesPathRefKey)(binding) : (0, guids_1.standardValuesId)(site, binding);
+        const fieldId = deriveFieldId(svRefKey, "__Default workflow");
+        const setField = {
+            op: "SetField",
+            policy,
+            label: `workflow-binding:${recipe.handle}:${binding}`,
+            itemRefKey: svRefKey,
+            fieldId,
+            fieldName: "__Default workflow",
+            value: { kind: "ref-recipe", refKey: workflowRefKey },
+            ...(isPath ? { latePath: (0, shared_1.joinPath)(binding, "__Standard Values") } : {}),
+        };
+        operations.push(setField);
+    }
+    return operations_1.OperationIrSchema.parse({
+        schemaVersion: "1",
+        recipeHandle: recipe.handle,
+        operations,
+    });
+}
+/**
+ * Cross-field validations that can't live on the schema (Zod's
+ * `discriminatedUnion` rejects `ZodEffects` members). Mirror of
+ * `compileEnumerationRecipe`'s `default ∈ values` check.
+ */
+function validateWorkflowRecipe(recipe) {
+    const stateKeys = new Set(recipe.states.map((s) => s.key));
+    if (!stateKeys.has(recipe.initialState)) {
+        throw (0, errors_1.createScaiError)(`Workflow '${recipe.handle}' initialState='${recipe.initialState}' is not declared in states.`, "INPUT_INVALID");
+    }
+    for (const state of recipe.states) {
+        for (const command of state.commands) {
+            if (!stateKeys.has(command.nextState)) {
+                throw (0, errors_1.createScaiError)(`Workflow '${recipe.handle}' state '${state.key}' command '${command.key}' references unknown nextState '${command.nextState}'.`, "INPUT_INVALID");
+            }
+        }
+    }
+    if (!recipe.states.some((s) => s.final)) {
+        throw (0, errors_1.createScaiError)(`Workflow '${recipe.handle}' must declare at least one state with final=true.`, "INPUT_INVALID");
+    }
+    const checkAction = (action, where) => {
+        if (action.authorizationRef && action.authorizationPath) {
+            throw (0, errors_1.createScaiError)(`Workflow '${recipe.handle}' ${where}: use either authorizationRef OR authorizationPath, not both.`, "INPUT_INVALID");
+        }
+    };
+    for (const state of recipe.states) {
+        state.actions.forEach((a) => checkAction(a, `state '${state.key}' action '${a.key}'`));
+        for (const command of state.commands) {
+            command.validations.forEach((v) => checkAction(v, `state '${state.key}' command '${command.key}' validation '${v.key}'`));
+        }
+    }
+}
+const TEMPLATE_PATHS = {
+    workflow: "/sitecore/templates/System/Workflow/Workflow",
+    state: "/sitecore/templates/System/Workflow/State",
+    command: "/sitecore/templates/System/Workflow/Command",
+    submitAction: "/sitecore/templates/System/Workflow/Webhook Submit Action",
+    validationAction: "/sitecore/templates/System/Workflow/Webhook Validation Action",
+};
+/**
+ * Derive a stable refKey for a field on a workflow/state/command item.
+ * The executor's apply path uses `fieldName` for the actual mutation
+ * (system fields like `Final` and `Next state` have established tenant
+ * GUIDs we don't know); `fieldId` here is a per-(item, field) refKey
+ * that the executor's `capturedItemIds` map ignores because the field
+ * isn't itself an item.
+ */
+const FIELD_REFKEY_NAMESPACE = (0, uuid_1.v5)("workflow-field", "d6c28e9f-21f3-56ee-ada3-f2a947c3d475" // NAMESPACE_ROOT
+);
+function deriveFieldId(parentRefKey, fieldName) {
+    return (0, uuid_1.v5)(`${parentRefKey}:${fieldName}`, FIELD_REFKEY_NAMESPACE);
+}
+function buildActionFields(actionRefKey, action) {
+    const fields = [
+        {
+            ...(0, shared_1.sharedField)(deriveFieldId(actionRefKey, "Url"), {
+                kind: "string",
+                value: action.url,
+            }),
+            fieldName: "Url",
+        },
+        {
+            ...(0, shared_1.sharedField)(deriveFieldId(actionRefKey, "Enabled"), {
+                kind: "bool",
+                value: action.enabled,
+            }),
+            fieldName: "Enabled",
+        },
+        {
+            ...(0, shared_1.sharedField)(deriveFieldId(actionRefKey, "Serialization Type"), {
+                kind: "string",
+                value: action.serializationType,
+            }),
+            fieldName: "Serialization Type",
+        },
+    ];
+    if (action.description !== undefined) {
+        fields.push({
+            ...(0, shared_1.sharedField)(deriveFieldId(actionRefKey, "Description"), {
+                kind: "string",
+                value: action.description,
+            }),
+            fieldName: "Description",
+        });
+    }
+    if (action.displayName !== undefined) {
+        fields.push((0, shared_1.versionedField)(sitecore_templates_1.SYSTEM_FIELDS.DISPLAY_NAME, { kind: "string", value: action.displayName }));
+    }
+    if (action.authorizationRef) {
+        fields.push({
+            ...(0, shared_1.sharedField)(deriveFieldId(actionRefKey, "Authorization"), {
+                kind: "ref-recipe",
+                refKey: (0, guids_1.webhookAuthorizationId)(action.authorizationRef),
+            }),
+            fieldName: "Authorization",
+        });
+    }
+    else if (action.authorizationPath) {
+        fields.push({
+            ...(0, shared_1.sharedField)(deriveFieldId(actionRefKey, "Authorization"), {
+                kind: "ref-path",
+                value: action.authorizationPath,
+            }),
+            fieldName: "Authorization",
+        });
+    }
+    return fields;
+}

package/dist/recipe/compile.d.ts

@@ -3,16 +3,21 @@ import { type Recipe } from "./schema/recipe";
 import { compileComponentSectionRecipe } from "./compile/component-section";
 import { compileComponentTemplateRecipe } from "./compile/component-template";
 import { compileContentTemplateRecipe } from "./compile/content-template";
-import { compileParametersTemplateRecipe } from "./compile/parameters-template";
+import { compileDesignParametersTemplateRecipe } from "./compile/design-parameters-template";
 import { compileSectionDefinitionRecipe } from "./compile/section-definition";
 import { compilePartialDesignRecipe } from "./compile/partial-design";
 import { compilePageDesignRecipe } from "./compile/page-design";
+import { compilePageTemplateRecipe } from "./compile/page-template";
+import { compilePageRecipe } from "./compile/page";
+import { compilePlaceholderRecipe } from "./compile/placeholder";
 import { compileContentItemRecipe } from "./compile/content-item";
 import { compileSiteTemplateRecipe } from "./compile/site-template";
 import { compileSiteRecipe } from "./compile/site";
 import { compileEnumerationRecipe } from "./compile/enumeration";
+import { compileWorkflowRecipe } from "./compile/workflow";
+import { compileWebhookAuthorizationRecipe } from "./compile/webhook-authorization";
 import { type CompileContext } from "./compile/shared";
-export { compileComponentSectionRecipe, compileComponentTemplateRecipe, compileContentTemplateRecipe, compileParametersTemplateRecipe, compileSectionDefinitionRecipe, compilePartialDesignRecipe, compilePageDesignRecipe, compileContentItemRecipe, compileSiteTemplateRecipe, compileSiteRecipe, compileEnumerationRecipe, };
+export { compileComponentSectionRecipe, compileComponentTemplateRecipe, compileContentTemplateRecipe, compileDesignParametersTemplateRecipe, compileSectionDefinitionRecipe, compilePartialDesignRecipe, compilePageDesignRecipe, compilePageTemplateRecipe, compilePageRecipe, compilePlaceholderRecipe, compileContentItemRecipe, compileSiteTemplateRecipe, compileSiteRecipe, compileEnumerationRecipe, compileWorkflowRecipe, compileWebhookAuthorizationRecipe, };
 export type { CompileContext } from "./compile/shared";
 /**
  * Stable handle for the synthetic IR `compileRecipeSet` emits to write
@@ -66,6 +71,18 @@ export declare const SITE_DATA_ROOT_AGGREGATE_HANDLE = "__site-data-root__";
  * per-recipe enumeration folder templates).
  */
 export declare const ENUMERATIONS_ROOT_AGGREGATE_HANDLE = "__enumerations-root__";
+/**
+ * Stable handle for the synthetic IR `compileRecipeSet` emits to
+ * materialise the Placeholder Settings items — one per unique
+ * placeholder key declared anywhere in the set (a `PlaceholderRecipe`
+ * or an inline `ComponentTemplateRecipe.placeholders` slot). Each key's
+ * `Allowed Controls` whitelist is the union of slot-side
+ * `allowedComponents` and every component naming the key in `placedIn`.
+ *
+ * Same `__…__` compiler-synthesized convention as the other aggregate
+ * handles in this file.
+ */
+export declare const PLACEHOLDER_SETTINGS_AGGREGATE_HANDLE = "__placeholder-settings__";
 /**
  * Compile a coherent set of recipes to a list of Operation IRs.
  *
@@ -90,4 +107,3 @@ export declare const ENUMERATIONS_ROOT_AGGREGATE_HANDLE = "__enumerations-root__
 export declare function compileRecipeSet(recipes: readonly Recipe[], context: CompileContext): OperationIr[];
 /** Front-door dispatcher — accepts any registered recipe kind. */
 export declare function compileRecipe(input: Recipe, context: CompileContext): OperationIr;
-//# sourceMappingURL=compile.d.ts.map