@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/sync/engine.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncPush = exports.syncDiff = exports.syncPull = void 0;
+/**
+ * The `sync` engine — kind-agnostic pull / diff / push over any
+ * `RecipeKind`. The engine owns the write-consent gate, so individual
+ * kinds never decide whether they are allowed to write.
+ *
+ * See docs/recipe-sync-architecture.md.
+ */
+const errors_1 = require("../shared/errors");
+const plan_1 = require("./plan");
+/** Capture live remote state as a recipe (`sync pull`). */
+const syncPull = (kind, ref, ctx) => kind.readCurrent(ref, ctx);
+exports.syncPull = syncPull;
+/** Compute the plan to converge `ref` onto `desired` (`sync diff`). */
+const syncDiff = (kind, desired, ref, ctx) => kind.plan(desired, ref, ctx);
+exports.syncDiff = syncDiff;
+/**
+ * Converge `ref` onto `desired` (`sync push`). Honors the write gate:
+ * `what-if` returns the plan without calling `apply`, and a no-op plan
+ * short-circuits the same way.
+ */
+const syncPush = async (kind, desired, ref, ctx, options) => {
+    const fullPlan = await (0, exports.syncDiff)(kind, desired, ref, ctx);
+    const plan = options.prune
+        ? fullPlan
+        : { changes: fullPlan.changes.filter((change) => change.kind !== "delete") };
+    if (options.mode === "what-if" || (0, plan_1.planIsNoop)(plan)) {
+        return { plan, result: null };
+    }
+    if (ctx.signal?.aborted) {
+        throw (0, errors_1.createScaiError)("Sync cancelled before apply", "CANCELLED");
+    }
+    const result = await kind.apply(plan, ref, ctx);
+    return { plan, result };
+};
+exports.syncPush = syncPush;

package/dist/sync/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The `sync` engine — the kind-agnostic spine that pulls, diffs, and
+ * pushes recipes against live Sitecore environments.
+ *
+ * A recipe kind (brand-kit, component, page, site, brief, campaign)
+ * implements {@link RecipeKind}; the engine functions below drive it.
+ *
+ * See docs/recipe-sync-architecture.md for the recipe / sync model.
+ */
+export type { ChangeKind, PlanSummary, RecipeChange, RecipePlan } from "./plan";
+export { planIsNoop, summarizePlan, writingChanges } from "./plan";
+export type { ApplyResult, KindRef, RecipeKind, SyncContext } from "./kind";
+export type { PushOptions, PushOutcome, SyncMode } from "./engine";
+export { syncDiff, syncPull, syncPush } from "./engine";
+export { loadRecipe, writeRecipe } from "./io";
+export { getKind, listKinds, registerKind } from "./registry";
+export { aggregatePull, aggregateStatus, aggregatePush, slugifyRecipeId, DEFAULT_SYNC_DIR, } from "./aggregate";
+export type { AggregatePullItem, AggregatePullKind, AggregatePullResult, AggregateDriftStatus, AggregateStatusItem, AggregateStatusKind, AggregateStatusResult, AggregatePushStatus, AggregatePushItem, AggregatePushKind, AggregatePushResult, } from "./aggregate";

package/dist/sync/index.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SYNC_DIR = exports.slugifyRecipeId = exports.aggregatePush = exports.aggregateStatus = exports.aggregatePull = exports.registerKind = exports.listKinds = exports.getKind = exports.writeRecipe = exports.loadRecipe = exports.syncPush = exports.syncPull = exports.syncDiff = exports.writingChanges = exports.summarizePlan = exports.planIsNoop = void 0;
+var plan_1 = require("./plan");
+Object.defineProperty(exports, "planIsNoop", { enumerable: true, get: function () { return plan_1.planIsNoop; } });
+Object.defineProperty(exports, "summarizePlan", { enumerable: true, get: function () { return plan_1.summarizePlan; } });
+Object.defineProperty(exports, "writingChanges", { enumerable: true, get: function () { return plan_1.writingChanges; } });
+var engine_1 = require("./engine");
+Object.defineProperty(exports, "syncDiff", { enumerable: true, get: function () { return engine_1.syncDiff; } });
+Object.defineProperty(exports, "syncPull", { enumerable: true, get: function () { return engine_1.syncPull; } });
+Object.defineProperty(exports, "syncPush", { enumerable: true, get: function () { return engine_1.syncPush; } });
+var io_1 = require("./io");
+Object.defineProperty(exports, "loadRecipe", { enumerable: true, get: function () { return io_1.loadRecipe; } });
+Object.defineProperty(exports, "writeRecipe", { enumerable: true, get: function () { return io_1.writeRecipe; } });
+var registry_1 = require("./registry");
+Object.defineProperty(exports, "getKind", { enumerable: true, get: function () { return registry_1.getKind; } });
+Object.defineProperty(exports, "listKinds", { enumerable: true, get: function () { return registry_1.listKinds; } });
+Object.defineProperty(exports, "registerKind", { enumerable: true, get: function () { return registry_1.registerKind; } });
+// --- Cross-domain aggregate ---------------------------------------------
+var aggregate_1 = require("./aggregate");
+Object.defineProperty(exports, "aggregatePull", { enumerable: true, get: function () { return aggregate_1.aggregatePull; } });
+Object.defineProperty(exports, "aggregateStatus", { enumerable: true, get: function () { return aggregate_1.aggregateStatus; } });
+Object.defineProperty(exports, "aggregatePush", { enumerable: true, get: function () { return aggregate_1.aggregatePush; } });
+Object.defineProperty(exports, "slugifyRecipeId", { enumerable: true, get: function () { return aggregate_1.slugifyRecipeId; } });
+Object.defineProperty(exports, "DEFAULT_SYNC_DIR", { enumerable: true, get: function () { return aggregate_1.DEFAULT_SYNC_DIR; } });

package/dist/sync/io.d.ts

@@ -0,0 +1,8 @@
+import type { ZodType } from "zod";
+/**
+ * Read, parse, and schema-validate a recipe file. YAML is a superset of
+ * JSON, so `.yaml`, `.yml`, and `.json` all parse through the same path.
+ */
+export declare const loadRecipe: <T>(filePath: string, schema: ZodType<T>) => T;
+/** Serialize a recipe to a file — JSON when the path ends `.json`, else YAML. */
+export declare const writeRecipe: (filePath: string, recipe: unknown) => void;

package/dist/sync/io.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeRecipe = exports.loadRecipe = void 0;
+/**
+ * Recipe file I/O for the `sync` engine — load a recipe from a YAML or
+ * JSON file and validate it against a kind's schema, or serialize a
+ * captured recipe back to disk.
+ *
+ * See docs/recipe-sync-architecture.md.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const yaml_1 = require("yaml");
+const errors_1 = require("../shared/errors");
+/**
+ * Read, parse, and schema-validate a recipe file. YAML is a superset of
+ * JSON, so `.yaml`, `.yml`, and `.json` all parse through the same path.
+ */
+const loadRecipe = (filePath, schema) => {
+    let raw;
+    try {
+        raw = (0, node_fs_1.readFileSync)(filePath, "utf8");
+    }
+    catch (error) {
+        throw (0, errors_1.createScaiError)(`Cannot read recipe file "${filePath}"`, "INPUT_INVALID", {
+            hint: error instanceof Error ? error.message : undefined,
+        });
+    }
+    let parsed;
+    try {
+        parsed = (0, yaml_1.parse)(raw);
+    }
+    catch (error) {
+        throw (0, errors_1.createScaiError)(`Recipe file "${filePath}" is not valid YAML/JSON`, "INPUT_INVALID", {
+            hint: error instanceof Error ? error.message : undefined,
+        });
+    }
+    const result = schema.safeParse(parsed);
+    if (!result.success) {
+        throw (0, errors_1.createScaiError)(`Recipe file "${filePath}" failed schema validation`, "INPUT_INVALID", {
+            details: result.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`),
+        });
+    }
+    return result.data;
+};
+exports.loadRecipe = loadRecipe;
+/** Serialize a recipe to a file — JSON when the path ends `.json`, else YAML. */
+const writeRecipe = (filePath, recipe) => {
+    const serialized = (0, node_path_1.extname)(filePath) === ".json" ? `${JSON.stringify(recipe, null, 2)}\n` : (0, yaml_1.stringify)(recipe);
+    (0, node_fs_1.writeFileSync)(filePath, serialized, "utf8");
+};
+exports.writeRecipe = writeRecipe;

package/dist/sync/kind.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The `RecipeKind` contract — the seam every declarative surface
+ * (brand-kit, component, page, site, brief, campaign) implements so the
+ * `sync` engine can pull, diff, and push it.
+ *
+ * `TRecipe` is the kind's clean, schema'd shape. The SAME type describes
+ * desired state (a recipe file) and current state (`readCurrent`), so
+ * `diff` always compares like with like.
+ *
+ * See docs/recipe-sync-architecture.md.
+ */
+import type { ZodType } from "zod";
+import type { Logger } from "../shared/logger";
+import type { RecipeChange, RecipePlan } from "./plan";
+/** Identifies one instance of a recipe kind on a remote environment. */
+export interface KindRef {
+    /** The recipe kind, e.g. `brand-kit`. */
+    kind: string;
+    /** Kind-specific identifier of the instance (a kit id, a site name…). */
+    id: string;
+}
+/** Ambient context handed to a kind's operations. */
+export interface SyncContext {
+    /** Environment profile the operation runs against. */
+    environmentName: string;
+    /** Base directory for resolving `sitecoreai.cli.json`. Defaults to cwd. */
+    configPath?: string;
+    /**
+     * Optional progress sink. The CLI passes a `Logger`; surfaces like the
+     * MCP server omit it (their progress goes through their own channel).
+     */
+    logger?: Logger;
+    /** Cancellation — kinds making HTTP calls should forward this. */
+    signal?: AbortSignal;
+}
+/** Outcome of applying a plan. */
+export interface ApplyResult {
+    /** Changes that were written to the remote. */
+    applied: RecipeChange[];
+    /** Changes deliberately not written (e.g. filtered deletes). */
+    skipped: RecipeChange[];
+}
+/** One declarative surface the `sync` engine can operate on. */
+export interface RecipeKind<TRecipe> {
+    /** Stable kind name. Used by the registry, CLI, and MCP. */
+    readonly name: string;
+    /**
+     * Validates a recipe. Also feeds the CLI (file validation) and the MCP
+     * tool input schema — the schema is the single source of truth.
+     */
+    readonly schema: ZodType<TRecipe>;
+    /**
+     * Capture live remote state as a recipe. Resolves `null` when the
+     * instance does not exist yet (a `push` would then create it).
+     */
+    readCurrent(ref: KindRef, ctx: SyncContext): Promise<TRecipe | null>;
+    /**
+     * Compute the plan to converge `ref` onto `desired`.
+     *
+     * May do I/O. Simple kinds implement this as `readCurrent` followed by
+     * a pure diff; the recipe (Sitecore-item) kind reads remote state
+     * per-operation while planning, so `plan` cannot be a pure function.
+     */
+    plan(desired: TRecipe, ref: KindRef, ctx: SyncContext): Promise<RecipePlan>;
+    /**
+     * Apply a plan to the remote. Must be idempotent: re-running after a
+     * successful apply produces an all-`noop` plan. The engine has already
+     * gated on write consent before calling this.
+     */
+    apply(plan: RecipePlan, ref: KindRef, ctx: SyncContext): Promise<ApplyResult>;
+    /**
+     * Enumerate every instance of this kind on the remote, as `KindRef`s.
+     *
+     * Optional. Kinds backed by a remote collection (brand kits, brief
+     * types) implement it so the cross-domain `scai sync` aggregate can
+     * pull them all. File-authored kinds (the Sitecore-item recipe) have
+     * nothing to enumerate and omit it — the aggregate skips them.
+     */
+    list?(ctx: SyncContext): Promise<KindRef[]>;
+}

package/dist/sync/kind.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/sync/plan.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Plan types for the `sync` engine — the diff between a desired recipe
+ * and live remote state.
+ *
+ * Pure leaf module: no I/O, no domain imports. `diff` implementations
+ * produce a `RecipePlan`; the engine and CLI consume it.
+ *
+ * See docs/recipe-sync-architecture.md.
+ */
+/** What a single change does to one element of a recipe. */
+export type ChangeKind = "create" | "update" | "delete" | "noop";
+/** One element-level change in a sync plan. */
+export interface RecipeChange {
+    kind: ChangeKind;
+    /** Dotted path to the element, e.g. `sections.voice.tone`. */
+    path: string;
+    /** One-line, human-readable description of the change. */
+    summary: string;
+    /** Prior value — present when the change replaces or removes something. */
+    before?: unknown;
+    /** Intended value — present when the change creates or replaces something. */
+    after?: unknown;
+    /**
+     * Kind-specific structured data — set by `diff`, read by `apply` so
+     * `apply` can act on a change without re-parsing the `path` string.
+     */
+    meta?: Record<string, unknown>;
+}
+/** The full set of changes needed to converge a target onto a recipe. */
+export interface RecipePlan {
+    changes: RecipeChange[];
+    /**
+     * Kind-private plan→apply handoff. A kind whose `plan` already did
+     * expensive work (compilation, IR construction) may stash that work
+     * here so `apply` can reuse it without recomputing. The engine never
+     * inspects this field — it is opaque transport between one kind's
+     * `plan` and the same kind's `apply`. Simple kinds (brand-kit,
+     * brief-type, campaign) leave it unset; the recipe (Sitecore-item)
+     * kind uses it to carry its compiled `OperationIr[]`.
+     */
+    payload?: unknown;
+}
+/** Per-`ChangeKind` tally of a plan's changes. */
+export interface PlanSummary {
+    create: number;
+    update: number;
+    delete: number;
+    noop: number;
+}
+/** Count a plan's changes by kind. */
+export declare const summarizePlan: (plan: RecipePlan) => PlanSummary;
+/** A plan is a no-op when nothing would actually be written. */
+export declare const planIsNoop: (plan: RecipePlan) => boolean;
+/** The changes that would write to the remote (everything but `noop`). */
+export declare const writingChanges: (plan: RecipePlan) => RecipeChange[];

package/dist/sync/plan.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * Plan types for the `sync` engine — the diff between a desired recipe
+ * and live remote state.
+ *
+ * Pure leaf module: no I/O, no domain imports. `diff` implementations
+ * produce a `RecipePlan`; the engine and CLI consume it.
+ *
+ * See docs/recipe-sync-architecture.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writingChanges = exports.planIsNoop = exports.summarizePlan = void 0;
+/** Count a plan's changes by kind. */
+const summarizePlan = (plan) => {
+    const summary = { create: 0, update: 0, delete: 0, noop: 0 };
+    for (const change of plan.changes) {
+        summary[change.kind] += 1;
+    }
+    return summary;
+};
+exports.summarizePlan = summarizePlan;
+/** A plan is a no-op when nothing would actually be written. */
+const planIsNoop = (plan) => plan.changes.every((change) => change.kind === "noop");
+exports.planIsNoop = planIsNoop;
+/** The changes that would write to the remote (everything but `noop`). */
+const writingChanges = (plan) => plan.changes.filter((change) => change.kind !== "noop");
+exports.writingChanges = writingChanges;

package/dist/sync/registry.d.ts

@@ -0,0 +1,7 @@
+import type { RecipeKind } from "./kind";
+/** Register a recipe kind. Throws on a duplicate name. */
+export declare const registerKind: <T>(kind: RecipeKind<T>) => void;
+/** Look up a registered kind, or throw a hinted error when it is absent. */
+export declare const getKind: (name: string) => RecipeKind<unknown>;
+/** Names of all registered kinds, sorted. */
+export declare const listKinds: () => string[];

package/dist/sync/registry.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listKinds = exports.getKind = exports.registerKind = void 0;
+/**
+ * Registry of recipe kinds — maps a kind name to its `RecipeKind`
+ * implementation so the CLI and MCP can dispatch generically.
+ *
+ * Kinds register themselves at startup via a side-effect import. The
+ * stored value type is erased to `unknown` at the registry boundary;
+ * callers that know a kind statically should import its `RecipeKind`
+ * directly rather than going through `getKind`.
+ */
+const errors_1 = require("../shared/errors");
+const kinds = new Map();
+/** Register a recipe kind. Throws on a duplicate name. */
+const registerKind = (kind) => {
+    if (kinds.has(kind.name)) {
+        throw (0, errors_1.createScaiError)(`Recipe kind '${kind.name}' is already registered`, "UNKNOWN");
+    }
+    kinds.set(kind.name, kind);
+};
+exports.registerKind = registerKind;
+/** Look up a registered kind, or throw a hinted error when it is absent. */
+const getKind = (name) => {
+    const kind = kinds.get(name);
+    if (!kind) {
+        throw (0, errors_1.createScaiError)(`Unknown recipe kind '${name}'`, "INPUT_INVALID", {
+            hint: `Known kinds: ${(0, exports.listKinds)().join(", ") || "(none registered)"}`,
+        });
+    }
+    return kind;
+};
+exports.getKind = getKind;
+/** Names of all registered kinds, sorted. */
+const listKinds = () => [...kinds.keys()].sort();
+exports.listKinds = listKinds;

package/dist/webhooks/api/client.d.ts

@@ -0,0 +1,134 @@
+import type { EnvironmentConfiguration } from "../../config/types";
+import { type WebhookRequestOptions } from "./graphql";
+import { type WebhookTemplateResolver } from "./templates";
+/**
+ * Authoring GraphQL operations for the Sitecore webhook content tree.
+ *
+ * Webhooks in XM Cloud are content items, not a dedicated API surface.
+ * This client wraps `createItem` / `updateItem` / `deleteItem` against
+ * `/sitecore/system/Webhooks` (event handlers) and the workflow
+ * `Actions` subtree (submit/validation actions). See
+ * `templates.ts` for the runtime template ID + event-type catalog
+ * resolution.
+ */
+export declare const DEFAULT_WEBHOOK_HANDLERS_ROOT = "/sitecore/system/Webhooks";
+export declare const WEBHOOK_FIELD_DESCRIPTION = "Description";
+export declare const WEBHOOK_FIELD_URL = "Url";
+export declare const WEBHOOK_FIELD_EVENTS = "Events";
+export declare const WEBHOOK_FIELD_ENABLED = "Enabled";
+export declare const WEBHOOK_FIELD_AUTHORIZATION = "Authorization";
+export declare const WEBHOOK_FIELD_SERIALIZATION_TYPE = "Serialization Type";
+export type WebhookSerializationType = "JSON" | "XML";
+export interface WebhookHandlerSummary {
+    itemId: string;
+    name: string;
+    path: string;
+    templateName: string | null;
+}
+export interface WebhookHandlerFieldsMap {
+    description: string | null;
+    url: string | null;
+    /** Raw multilist field — pipe-delimited list of event-type item IDs. */
+    eventsRaw: string | null;
+    /** Resolved event-type display names (e.g. `item:saved`), best-effort. */
+    events: string[];
+    enabled: boolean;
+    authorizationItemId: string | null;
+    serializationType: string | null;
+}
+export interface WebhookHandlerDetail extends WebhookHandlerSummary {
+    fields: WebhookHandlerFieldsMap;
+}
+export interface CreateEventHandlerInput {
+    /** Sitecore item name for the new handler. */
+    name: string;
+    url: string;
+    /** Event-type display names (`item:saved`, `publish:end`, …). Resolved to catalog GUIDs at create time. */
+    events: readonly string[];
+    enabled?: boolean;
+    description?: string;
+    /** Absolute path to an existing Authorization item, e.g. `/sitecore/system/Settings/Webhooks/Authorizations/CI Bearer`. */
+    authorizationPath?: string;
+    serializationType?: WebhookSerializationType;
+    /** Override the default `/sitecore/system/Webhooks` parent. */
+    parentPath?: string;
+}
+export interface CreateWorkflowActionInput {
+    /** Sitecore item name for the new action item (e.g. `Notify Reviewer`). */
+    name: string;
+    url: string;
+    /**
+     * Absolute path to the workflow state OR command under which the
+     * action's `Actions` subfolder lives. The action item itself is
+     * created at `<stateOrCommandPath>/Actions/<name>`; the `Actions`
+     * folder is expected to exist already (created automatically by
+     * Sitecore when the state/command is added).
+     */
+    stateOrCommandPath: string;
+    description?: string;
+    enabled?: boolean;
+    authorizationPath?: string;
+    serializationType?: WebhookSerializationType;
+}
+export type WebhookEventTypeCategory = "item" | "publish";
+export interface WebhookEventTypeSummary {
+    /** Event-type display name (e.g. `item:saved`, `publish:end`). */
+    name: string;
+    /** Catalog item GUID. Stable per tenant; not a Sitecore-published contract. */
+    itemId: string;
+    /** Catalog branch the item lives under. */
+    category: WebhookEventTypeCategory;
+    /** Full content-tree path of the catalog item. */
+    path: string;
+}
+export interface WebhookApiClient {
+    /**
+     * List webhook event handler items under the given root (default
+     * `/sitecore/system/Webhooks`). Walks direct children. Items whose
+     * template is `Webhook Event Handler` are returned; folder items are
+     * walked one level deeper.
+     */
+    listEventHandlers(options?: {
+        rootPath?: string;
+        enabledOnly?: boolean;
+    }): Promise<WebhookHandlerSummary[]>;
+    /** Fetch a single handler item with all configuration fields. */
+    getEventHandler(input: {
+        itemId?: string;
+        path?: string;
+    }): Promise<WebhookHandlerDetail | null>;
+    /**
+     * Create a Webhook Event Handler item (for item/publish events).
+     * Resolves event-name strings to catalog GUIDs and the template ID
+     * via runtime lookups (cached per client instance).
+     */
+    createEventHandler(input: CreateEventHandlerInput): Promise<WebhookHandlerSummary>;
+    /** Create a Webhook Submit Action under a workflow state's `Actions` folder. */
+    createWorkflowSubmitAction(input: CreateWorkflowActionInput): Promise<WebhookHandlerSummary>;
+    /** Create a Webhook Validation Action under a workflow command's `Actions` folder. */
+    createWorkflowValidationAction(input: CreateWorkflowActionInput): Promise<WebhookHandlerSummary>;
+    /** Delete any webhook item by ID or path. */
+    deleteWebhookItem(input: {
+        itemId?: string;
+        path?: string;
+    }): Promise<void>;
+    /**
+     * List event-type catalog items the tenant exposes — the strings
+     * callers pass to `createEventHandler({ events: [...] })`. Walks
+     * `/sitecore/system/Settings/Webhooks/Event Types/{Item,Publish}` and
+     * returns each catalog item's display name + GUID + category. The
+     * catalog is per-tenant (Sitecore base content seeds it, customers
+     * can extend it); resolve at runtime rather than baking a static
+     * union into the SDK.
+     */
+    listEventTypes(options?: {
+        category?: WebhookEventTypeCategory;
+    }): Promise<WebhookEventTypeSummary[]>;
+    /** Underlying template resolver, exposed for testing and cross-task use. */
+    readonly templates: WebhookTemplateResolver;
+}
+export interface WebhookClientOptions {
+    environment: EnvironmentConfiguration;
+    request?: WebhookRequestOptions;
+}
+export declare const createWebhookApiClient: (options: WebhookClientOptions) => WebhookApiClient;