@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/shared/validate.js

@@ -4,18 +4,33 @@ exports.assertValidHost = exports.assertValidUrl = void 0;
 const errors_1 = require("./errors");
 const isNonEmpty = (value) => Boolean(value && value.trim().length > 0);
 const assertValidUrl = (value, label) => {
+    let url;
     try {
         // Allow absolute URLs only.
-        const url = new URL(value);
+        url = new URL(value);
         if (!url.protocol || !url.hostname) {
             throw new Error("Invalid URL");
         }
     }
     catch {
-        throw (0, errors_1.createCliError)(`${label} must be a valid URL.`, "INPUT_INVALID", {
+        throw (0, errors_1.createScaiError)(`${label} must be a valid URL.`, "INPUT_INVALID", {
             hint: `Provide a valid ${label.toLowerCase()} (e.g. https://example.com).`,
         });
     }
+    // Reject non-HTTPS schemes by default. http:// is permitted only when
+    // the operator sets SITECOREAI_ALLOW_HTTP=1 (dev/test only — Bearer
+    // tokens ride this URL unencrypted otherwise). file:, javascript:,
+    // ftp:, etc. are always rejected.
+    if (url.protocol !== "https:") {
+        if (url.protocol === "http:" && process.env.SITECOREAI_ALLOW_HTTP === "1") {
+            return;
+        }
+        throw (0, errors_1.createScaiError)(`${label} must use https:// (got ${url.protocol}//).`, "INPUT_INVALID", {
+            hint: url.protocol === "http:"
+                ? "Bearer tokens would be sent in cleartext. Set SITECOREAI_ALLOW_HTTP=1 only for local development."
+                : `Provide a valid ${label.toLowerCase()} starting with https://.`,
+        });
+    }
 };
 exports.assertValidUrl = assertValidUrl;
 const assertValidHost = (value, label) => {
@@ -24,7 +39,7 @@ const assertValidHost = (value, label) => {
         return;
     }
     if (!isNonEmpty(value) || /\s/.test(value)) {
-        throw (0, errors_1.createCliError)(`${label} must be a valid host.`, "INPUT_INVALID", {
+        throw (0, errors_1.createScaiError)(`${label} must be a valid host.`, "INPUT_INVALID", {
             hint: "Provide a hostname or a full URL.",
         });
     }

package/dist/sites/api/collections.d.ts

@@ -22,4 +22,3 @@ export declare const listCollections: (options: SitesApiClientOptions) => Promis
 export declare const createCollection: (options: SitesApiClientOptions, input: CreateSiteCollectionInput) => Promise<JobResponse>;
 /** Retrieve a single collection by ID. */
 export declare const retrieveCollection: (options: SitesApiClientOptions, collectionId: string) => Promise<SiteCollection>;
-//# sourceMappingURL=collections.d.ts.map

package/dist/sites/api/jobs.d.ts

@@ -28,4 +28,3 @@ export type Job = components["schemas"]["Job"] & {
 export declare const getJobStatus: (options: SitesApiClientOptions, jobHandle: string) => Promise<Job>;
 /** List all jobs in the environment. */
 export declare const listJobs: (options: SitesApiClientOptions) => Promise<Job[]>;
-//# sourceMappingURL=jobs.d.ts.map

package/dist/sites/api/languages.d.ts

@@ -19,4 +19,3 @@ export declare const listLanguages: (options: SitesApiClientOptions) => Promise<
  * "already added" as success).
  */
 export declare const addLanguage: (options: SitesApiClientOptions, input: AddLanguageModel) => Promise<Language>;
-//# sourceMappingURL=languages.d.ts.map

package/dist/sites/api/request.d.ts

@@ -21,4 +21,3 @@ export declare const sitesRequest: <TResponse>(options: SitesApiClientOptions, p
     body?: unknown;
     query?: SitesQueryRecord;
 }) => Promise<TResponse>;
-//# sourceMappingURL=request.d.ts.map

package/dist/sites/api/request.js

@@ -19,7 +19,7 @@ const types_1 = require("./types");
  *    operation and pass typed body / response generics through. Each
  *    operation gets a one-line wrapper; the transport stays generic.
  *
- * Errors map to scai's `CliError` — `NETWORK` for transport failures,
+ * Errors map to scai's `ScaiError` — `NETWORK` for transport failures,
  * `SITES_API_FAILED` for non-2xx responses with a message extracted
  * from the body when present.
  */
@@ -75,18 +75,27 @@ const sitesRequest = async (options, path, init) => {
         headers["Content-Type"] = "application/json";
         body = typeof init.body === "string" ? init.body : JSON.stringify(init.body);
     }
+    // Default 60s timeout. Override via SITECOREAI_REQUEST_TIMEOUT_MS (0 disables).
+    // Defends against slowloris / black-hole upstreams.
+    const timeoutMs = Number(process.env.SITECOREAI_REQUEST_TIMEOUT_MS ?? 60000);
+    const controller = timeoutMs > 0 ? new AbortController() : undefined;
+    const timeoutHandle = controller ? setTimeout(() => controller.abort(), timeoutMs) : undefined;
     let response;
     try {
-        response = await fetch(url, { method, headers, body });
+        response = await fetch(url, { method, headers, body, signal: controller?.signal });
     }
     catch (error) {
-        throw (0, errors_1.createCliError)((0, redact_1.redactSecrets)(`Sites API request failed: ${error instanceof Error ? error.message : String(error)}`), "NETWORK", { hint: "Check network connectivity or try again later." });
+        throw (0, errors_1.createScaiError)((0, redact_1.redactSecrets)(`Sites API request failed: ${error instanceof Error ? error.message : String(error)}`), "NETWORK", { hint: "Check network connectivity or try again later." });
+    }
+    finally {
+        if (timeoutHandle)
+            clearTimeout(timeoutHandle);
     }
     if (!response.ok) {
         const responseBody = await (0, request_1.parseJsonIfPossible)(response);
         const message = (0, request_1.extractErrorMessage)(responseBody);
         const sanitized = message ? (0, redact_1.redactSecrets)(message) : undefined;
-        throw (0, errors_1.createCliError)(sanitized ?? `Sites API request failed (${response.status})`, "SITES_API_FAILED");
+        throw (0, errors_1.createScaiError)(sanitized ?? `Sites API request failed (${response.status})`, "SITES_API_FAILED");
     }
     // 204 No Content responses (e.g. DELETE) have no body — return
     // `undefined as TResponse` and let helpers type their return as `void`

package/dist/sites/api/sites.d.ts

@@ -14,6 +14,7 @@ import type { SitesApiClientOptions } from "./types";
 export type Site = components["schemas"]["Site"];
 export type SiteTemplate = components["schemas"]["SiteTemplate"];
 export type NewSiteInput = components["schemas"]["NewSiteInput"];
+export type UpdateSiteInput = components["schemas"]["UpdateSiteInput"];
 /**
  * Codegen-typed JobResponse, extended for the runtime shape. The
  * OpenAPI spec defines only `handle`, but some Sites API deployments
@@ -36,6 +37,35 @@ export type JobResponse = components["schemas"]["JobResponse"] & {
 export declare const createSite: (options: SitesApiClientOptions, input: NewSiteInput) => Promise<JobResponse>;
 /** Retrieve a single site by ID. */
 export declare const retrieveSite: (options: SitesApiClientOptions, siteId: string) => Promise<Site>;
+/**
+ * Update mutable properties of a site (`PATCH /api/v1/sites/{siteId}`).
+ *
+ * Synchronous — returns the updated `Site`, not a job handle. Only the
+ * fields present on `patch` are changed; omit the rest. To rename a
+ * site use the dedicated Rename operation instead.
+ *
+ * The optional `environmentId` query scopes the write to a specific
+ * Content Services environment (server default: "main").
+ *
+ * `patch` is `Partial<UpdateSiteInput>` — the codegen marks
+ * `displayName`/`description` as required (spec artifact: they carry a
+ * junk `default`), but PATCH is partial by definition, so callers send
+ * only the fields they intend to change.
+ */
+export declare const updateSite: (options: SitesApiClientOptions, siteId: string, patch: Partial<UpdateSiteInput>, query?: {
+    environmentId?: string;
+}) => Promise<Site>;
+/**
+ * Associate (or clear) the brand kit linked to a site.
+ *
+ * Thin convenience over `updateSite` for the single most common
+ * brand-kit operation: pass a kit UUID to link, or `null` to detach.
+ * `brandKitId` is the id of a brand kit (see the brand
+ * area — `brand_inspect verb='list-kits'`).
+ */
+export declare const setSiteBrandKit: (options: SitesApiClientOptions, siteId: string, brandKitId: string | null, query?: {
+    environmentId?: string;
+}) => Promise<Site>;
 /** List all sites in the environment. */
 export declare const listSites: (options: SitesApiClientOptions) => Promise<Site[]>;
 /**
@@ -50,4 +80,17 @@ export declare const deleteSite: (options: SitesApiClientOptions, siteId: string
  * only knows the template's display name.
  */
 export declare const listSiteTemplates: (options: SitesApiClientOptions) => Promise<SiteTemplate[]>;
-//# sourceMappingURL=sites.d.ts.map
+export type WorkflowsStatistics = components["schemas"]["WorkflowsStatistics"];
+export type WorkflowStatistics = components["schemas"]["WorkflowStatistics"];
+export type WorkflowStateStatistics = components["schemas"]["WorkflowStateStatistics"];
+/**
+ * Fetch the per-site workflow rollup: workflows defined on the site,
+ * their states, and the count of pages in each state. Backs
+ * `scai content workflow status --site <siteId>`.
+ *
+ * Optional `environmentId` query param ("main" by default server-side)
+ * scopes to a specific Content Services environment.
+ */
+export declare const retrieveWorkflowStatistics: (options: SitesApiClientOptions, siteId: string, query?: {
+    environmentId?: string;
+}) => Promise<WorkflowsStatistics>;

package/dist/sites/api/sites.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.listSiteTemplates = exports.deleteSite = exports.listSites = exports.retrieveSite = exports.createSite = void 0;
+exports.retrieveWorkflowStatistics = exports.listSiteTemplates = exports.deleteSite = exports.listSites = exports.setSiteBrandKit = exports.updateSite = exports.retrieveSite = exports.createSite = void 0;
 const request_1 = require("./request");
 /**
  * Create a new site from a site template (async).
@@ -20,6 +20,37 @@ exports.createSite = createSite;
 /** Retrieve a single site by ID. */
 const retrieveSite = (options, siteId) => (0, request_1.sitesRequest)(options, `/api/v1/sites/${encodeURIComponent(siteId)}`);
 exports.retrieveSite = retrieveSite;
+/**
+ * Update mutable properties of a site (`PATCH /api/v1/sites/{siteId}`).
+ *
+ * Synchronous — returns the updated `Site`, not a job handle. Only the
+ * fields present on `patch` are changed; omit the rest. To rename a
+ * site use the dedicated Rename operation instead.
+ *
+ * The optional `environmentId` query scopes the write to a specific
+ * Content Services environment (server default: "main").
+ *
+ * `patch` is `Partial<UpdateSiteInput>` — the codegen marks
+ * `displayName`/`description` as required (spec artifact: they carry a
+ * junk `default`), but PATCH is partial by definition, so callers send
+ * only the fields they intend to change.
+ */
+const updateSite = (options, siteId, patch, query) => (0, request_1.sitesRequest)(options, `/api/v1/sites/${encodeURIComponent(siteId)}`, {
+    method: "PATCH",
+    body: patch,
+    ...(query?.environmentId ? { query: { environmentId: query.environmentId } } : {}),
+});
+exports.updateSite = updateSite;
+/**
+ * Associate (or clear) the brand kit linked to a site.
+ *
+ * Thin convenience over `updateSite` for the single most common
+ * brand-kit operation: pass a kit UUID to link, or `null` to detach.
+ * `brandKitId` is the id of a brand kit (see the brand
+ * area — `brand_inspect verb='list-kits'`).
+ */
+const setSiteBrandKit = (options, siteId, brandKitId, query) => (0, exports.updateSite)(options, siteId, { brandKitId }, query);
+exports.setSiteBrandKit = setSiteBrandKit;
 /** List all sites in the environment. */
 const listSites = (options) => (0, request_1.sitesRequest)(options, "/api/v1/sites");
 exports.listSites = listSites;
@@ -39,3 +70,13 @@ exports.deleteSite = deleteSite;
  */
 const listSiteTemplates = (options) => (0, request_1.sitesRequest)(options, "/api/v1/sites/templates");
 exports.listSiteTemplates = listSiteTemplates;
+/**
+ * Fetch the per-site workflow rollup: workflows defined on the site,
+ * their states, and the count of pages in each state. Backs
+ * `scai content workflow status --site <siteId>`.
+ *
+ * Optional `environmentId` query param ("main" by default server-side)
+ * scopes to a specific Content Services environment.
+ */
+const retrieveWorkflowStatistics = (options, siteId, query) => (0, request_1.sitesRequest)(options, `/api/v1/sites/${encodeURIComponent(siteId)}/statistics/workflow`, query?.environmentId ? { query: { environmentId: query.environmentId } } : undefined);
+exports.retrieveWorkflowStatistics = retrieveWorkflowStatistics;

package/dist/sites/api/types.d.ts

@@ -26,4 +26,3 @@ export type SitesRequestInit = {
 /** Query-value shape — Sites API operations either take no query params or simple key/value pairs. */
 export type SitesQueryValue = string | number | boolean;
 export type SitesQueryRecord = Record<string, SitesQueryValue | SitesQueryValue[] | undefined>;
-//# sourceMappingURL=types.d.ts.map

package/dist/sites/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Public entry for `@sitecoreai-labs/sitecoreai-cli/unstable/sites`.
+ *
+ * Sites API client surface. The Sites API is XM Cloud's CRUD proxy for
+ * sites, collections, languages, hosts, and related resources at
+ * `https://xmapps-api.sitecorecloud.io`. Spec is pinned at
+ * `./api/openapi.yaml` and types are regenerated via `pnpm sites:codegen`.
+ *
+ * The `recipe` entry also re-exports the recipe-required subset of these
+ * via `createSitesApiClient` — that pair is the higher-level interface
+ * the recipe planner depends on. This entry exposes the per-resource
+ * primitives directly for callers that don't need the recipe seam.
+ *
+ * **Status**: UNSTABLE. Ships under `./unstable/sites` and carries no
+ * SemVer stability promise — the per-resource primitives may change in
+ * any release. The recipe planner's pinned subset (reached via
+ * `createSitesApiClient` on the stable `./recipe` entry) is unaffected.
+ */
+export type { SitesApiClientOptions, SitesRequestInit, SitesQueryValue, SitesQueryRecord, } from "./api/types";
+export { DEFAULT_SITES_API_BASE } from "./api/types";
+export { sitesRequest } from "./api/request";
+export { createSite, retrieveSite, listSites, updateSite, setSiteBrandKit, deleteSite, listSiteTemplates, retrieveWorkflowStatistics, type Site, type SiteTemplate, type NewSiteInput, type UpdateSiteInput, type JobResponse, type WorkflowsStatistics, type WorkflowStatistics, type WorkflowStateStatistics, } from "./api/sites";
+export { listCollections, createCollection, retrieveCollection, type SiteCollection, type CreateSiteCollectionInput, } from "./api/collections";
+export { listLanguages, addLanguage, type Language, type AddLanguageModel } from "./api/languages";
+export { getJobStatus, listJobs, type Job } from "./api/jobs";

package/dist/sites/index.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * Public entry for `@sitecoreai-labs/sitecoreai-cli/unstable/sites`.
+ *
+ * Sites API client surface. The Sites API is XM Cloud's CRUD proxy for
+ * sites, collections, languages, hosts, and related resources at
+ * `https://xmapps-api.sitecorecloud.io`. Spec is pinned at
+ * `./api/openapi.yaml` and types are regenerated via `pnpm sites:codegen`.
+ *
+ * The `recipe` entry also re-exports the recipe-required subset of these
+ * via `createSitesApiClient` — that pair is the higher-level interface
+ * the recipe planner depends on. This entry exposes the per-resource
+ * primitives directly for callers that don't need the recipe seam.
+ *
+ * **Status**: UNSTABLE. Ships under `./unstable/sites` and carries no
+ * SemVer stability promise — the per-resource primitives may change in
+ * any release. The recipe planner's pinned subset (reached via
+ * `createSitesApiClient` on the stable `./recipe` entry) is unaffected.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listJobs = exports.getJobStatus = exports.addLanguage = exports.listLanguages = exports.retrieveCollection = exports.createCollection = exports.listCollections = exports.retrieveWorkflowStatistics = exports.listSiteTemplates = exports.deleteSite = exports.setSiteBrandKit = exports.updateSite = exports.listSites = exports.retrieveSite = exports.createSite = exports.sitesRequest = exports.DEFAULT_SITES_API_BASE = void 0;
+var types_1 = require("./api/types");
+Object.defineProperty(exports, "DEFAULT_SITES_API_BASE", { enumerable: true, get: function () { return types_1.DEFAULT_SITES_API_BASE; } });
+var request_1 = require("./api/request");
+Object.defineProperty(exports, "sitesRequest", { enumerable: true, get: function () { return request_1.sitesRequest; } });
+var sites_1 = require("./api/sites");
+Object.defineProperty(exports, "createSite", { enumerable: true, get: function () { return sites_1.createSite; } });
+Object.defineProperty(exports, "retrieveSite", { enumerable: true, get: function () { return sites_1.retrieveSite; } });
+Object.defineProperty(exports, "listSites", { enumerable: true, get: function () { return sites_1.listSites; } });
+Object.defineProperty(exports, "updateSite", { enumerable: true, get: function () { return sites_1.updateSite; } });
+Object.defineProperty(exports, "setSiteBrandKit", { enumerable: true, get: function () { return sites_1.setSiteBrandKit; } });
+Object.defineProperty(exports, "deleteSite", { enumerable: true, get: function () { return sites_1.deleteSite; } });
+Object.defineProperty(exports, "listSiteTemplates", { enumerable: true, get: function () { return sites_1.listSiteTemplates; } });
+Object.defineProperty(exports, "retrieveWorkflowStatistics", { enumerable: true, get: function () { return sites_1.retrieveWorkflowStatistics; } });
+var collections_1 = require("./api/collections");
+Object.defineProperty(exports, "listCollections", { enumerable: true, get: function () { return collections_1.listCollections; } });
+Object.defineProperty(exports, "createCollection", { enumerable: true, get: function () { return collections_1.createCollection; } });
+Object.defineProperty(exports, "retrieveCollection", { enumerable: true, get: function () { return collections_1.retrieveCollection; } });
+var languages_1 = require("./api/languages");
+Object.defineProperty(exports, "listLanguages", { enumerable: true, get: function () { return languages_1.listLanguages; } });
+Object.defineProperty(exports, "addLanguage", { enumerable: true, get: function () { return languages_1.addLanguage; } });
+var jobs_1 = require("./api/jobs");
+Object.defineProperty(exports, "getJobStatus", { enumerable: true, get: function () { return jobs_1.getJobStatus; } });
+Object.defineProperty(exports, "listJobs", { enumerable: true, get: function () { return jobs_1.listJobs; } });

package/dist/sync/aggregate-kinds.d.ts

@@ -0,0 +1,7 @@
+import type { RecipeKind } from "../sync";
+/**
+ * Every enumerable recipe kind, in display order. Add a row when a new
+ * kind ships a `list` implementation — both `scai sync` and the
+ * `recipe_sync` MCP tool pick it up automatically.
+ */
+export declare const ENUMERABLE_RECIPE_KINDS: ReadonlyArray<RecipeKind<unknown>>;

package/dist/sync/aggregate-kinds.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENUMERABLE_RECIPE_KINDS = void 0;
+/**
+ * The recipe kinds the cross-domain aggregate (`scai sync` / the
+ * `recipe_sync` MCP tool) fans out over.
+ *
+ * `aggregate.ts` is deliberately domain-free so the engine never cycles
+ * with `@/brand` / `@/brief`. This file is the single, deliberately
+ * domain-AWARE exception: it names the concrete kinds the aggregate
+ * covers, so the CLI command and the MCP tool import ONE list instead
+ * of each hand-maintaining their own copy (the drift that let `sync`
+ * coverage diverge between the two surfaces).
+ *
+ * Not re-exported from `./index` — importing the barrel must stay
+ * domain-free. Consumers import this module by its explicit path.
+ *
+ * Only kinds that implement `RecipeKind.list` (can enumerate their own
+ * instances) belong here. File-authored component/page/site recipes
+ * have nothing to enumerate and stay with `provision recipe`.
+ */
+const recipe_1 = require("../brand/recipe");
+const recipe_2 = require("../brief/recipe");
+/**
+ * Every enumerable recipe kind, in display order. Add a row when a new
+ * kind ships a `list` implementation — both `scai sync` and the
+ * `recipe_sync` MCP tool pick it up automatically.
+ */
+exports.ENUMERABLE_RECIPE_KINDS = [
+    recipe_1.brandKitKind,
+    recipe_2.briefTypeKind,
+];

package/dist/sync/aggregate.d.ts

@@ -0,0 +1,100 @@
+import { type PlanSummary } from "./plan";
+import { type SyncMode } from "./engine";
+import type { RecipeKind, SyncContext } from "./kind";
+/** Default workspace directory for aggregate recipe files. */
+export declare const DEFAULT_SYNC_DIR = ".scai/sync";
+/** Slugify an instance id for a recipe filename. */
+export declare const slugifyRecipeId: (value: string) => string;
+/** One recipe captured by `aggregatePull`. */
+export interface AggregatePullItem {
+    id: string;
+    file: string;
+}
+/** Per-kind outcome of `aggregatePull`. */
+export interface AggregatePullKind {
+    kind: string;
+    pulled: AggregatePullItem[];
+    /** Set when the kind could not enumerate itself (e.g. no credential). */
+    skipped?: string;
+}
+/** Structured result of `aggregatePull`. */
+export interface AggregatePullResult {
+    dir: string;
+    kinds: AggregatePullKind[];
+    total: number;
+}
+/**
+ * Enumerate every instance of every enumerable kind and capture each as
+ * a recipe file under `<dir>/<kind>/<slug>.yaml`. A kind that cannot
+ * enumerate itself (no credential for this environment) is recorded as
+ * `skipped` rather than failing the whole run.
+ */
+export declare const aggregatePull: (kinds: ReadonlyArray<RecipeKind<unknown>>, ctx: SyncContext, options?: {
+    dir?: string;
+}) => Promise<AggregatePullResult>;
+/** Drift classification of one recipe in `aggregateStatus`. */
+export type AggregateDriftStatus = "in-sync" | "drift" | "error";
+/** One recipe's drift status. */
+export interface AggregateStatusItem {
+    id: string;
+    status: AggregateDriftStatus;
+    /** Plan tally — present when `status` is `drift`. */
+    summary?: PlanSummary;
+    /** Failure message — present when `status` is `error`. */
+    error?: string;
+}
+/** Per-kind outcome of `aggregateStatus`. */
+export interface AggregateStatusKind {
+    kind: string;
+    items: AggregateStatusItem[];
+}
+/** Structured result of `aggregateStatus`. */
+export interface AggregateStatusResult {
+    dir: string;
+    kinds: AggregateStatusKind[];
+    /** Count of recipes that drifted from the environment. */
+    drifted: number;
+}
+/**
+ * Diff every recipe file in the workspace against the environment. A
+ * kind with no workspace files is omitted from the result.
+ */
+export declare const aggregateStatus: (kinds: ReadonlyArray<RecipeKind<unknown>>, ctx: SyncContext, options?: {
+    dir?: string;
+}) => Promise<AggregateStatusResult>;
+/** Outcome of pushing one recipe in `aggregatePush`. */
+export type AggregatePushStatus = "applied" | "in-sync" | "planned" | "error";
+/** One recipe's push outcome. */
+export interface AggregatePushItem {
+    id: string;
+    status: AggregatePushStatus;
+    /** Changes written — present when `status` is `applied`. */
+    appliedCount?: number;
+    /** Changes that a non-dry-run would write — present when `status` is `planned`. */
+    plannedCount?: number;
+    /** Failure message — present when `status` is `error`. */
+    error?: string;
+}
+/** Per-kind outcome of `aggregatePush`. */
+export interface AggregatePushKind {
+    kind: string;
+    items: AggregatePushItem[];
+}
+/** Structured result of `aggregatePush`. */
+export interface AggregatePushResult {
+    dir: string;
+    mode: SyncMode;
+    kinds: AggregatePushKind[];
+    /** Total changes written across every recipe (zero in `what-if` mode). */
+    applied: number;
+}
+/**
+ * Converge every recipe file in the workspace onto the environment. In
+ * `what-if` mode nothing is written — each recipe reports its planned
+ * change count instead. A kind with no workspace files is omitted.
+ */
+export declare const aggregatePush: (kinds: ReadonlyArray<RecipeKind<unknown>>, ctx: SyncContext, options: {
+    dir?: string;
+    mode: SyncMode;
+    prune?: boolean;
+}) => Promise<AggregatePushResult>;

package/dist/sync/aggregate.js

@@ -0,0 +1,173 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aggregatePush = exports.aggregateStatus = exports.aggregatePull = exports.slugifyRecipeId = exports.DEFAULT_SYNC_DIR = void 0;
+/**
+ * The cross-domain recipe aggregate — pull / diff / push every
+ * enumerable recipe kind into one workspace directory.
+ *
+ * `syncPull`/`syncDiff`/`syncPush` in `./engine` each operate on ONE
+ * instance of ONE kind. The aggregate fans them out across a set of
+ * kinds and every instance each kind enumerates.
+ *
+ * Kind-agnostic: the caller supplies the kinds to cover, so this module
+ * stays free of any concrete domain import (no cycle with `@/brand`,
+ * `@/brief`, …). Only kinds that implement `RecipeKind.list` participate;
+ * the rest are reported as skipped. Workspace layout is
+ * `<dir>/<kind-name>/<slug(id)>.yaml`.
+ *
+ * Presentation-free: every function returns a structured result. The
+ * caller (CLI command, MCP tool, embedding SDK consumer) decides how to
+ * render it.
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const errors_1 = require("../shared/errors");
+const io_1 = require("./io");
+const plan_1 = require("./plan");
+const engine_1 = require("./engine");
+/** Default workspace directory for aggregate recipe files. */
+exports.DEFAULT_SYNC_DIR = ".scai/sync";
+/** Slugify an instance id for a recipe filename. */
+const slugifyRecipeId = (value) => value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "item";
+exports.slugifyRecipeId = slugifyRecipeId;
+/** Every recipe carries a `name` — its `KindRef.id`. */
+const recipeId = (recipe) => String(recipe.name ?? "");
+/** Recipe files under a kind's workspace subdirectory. */
+const recipeFilesFor = (dir, kindName) => {
+    const kindDir = node_path_1.default.join(dir, kindName);
+    if (!node_fs_1.default.existsSync(kindDir)) {
+        return [];
+    }
+    return node_fs_1.default
+        .readdirSync(kindDir)
+        .filter((file) => file.endsWith(".yaml") || file.endsWith(".yml") || file.endsWith(".json"))
+        .map((file) => node_path_1.default.join(kindDir, file));
+};
+/**
+ * Enumerate every instance of every enumerable kind and capture each as
+ * a recipe file under `<dir>/<kind>/<slug>.yaml`. A kind that cannot
+ * enumerate itself (no credential for this environment) is recorded as
+ * `skipped` rather than failing the whole run.
+ */
+const aggregatePull = async (kinds, ctx, options = {}) => {
+    const dir = options.dir ?? exports.DEFAULT_SYNC_DIR;
+    const results = [];
+    let total = 0;
+    for (const kind of kinds) {
+        if (!kind.list) {
+            continue;
+        }
+        let refs;
+        try {
+            refs = await kind.list(ctx);
+        }
+        catch (error) {
+            results.push({ kind: kind.name, pulled: [], skipped: (0, errors_1.toScaiError)(error).message });
+            continue;
+        }
+        const pulled = [];
+        for (const ref of refs) {
+            const recipe = await (0, engine_1.syncPull)(kind, ref, ctx);
+            if (!recipe) {
+                continue;
+            }
+            const file = node_path_1.default.join(dir, kind.name, `${(0, exports.slugifyRecipeId)(ref.id)}.yaml`);
+            (0, io_1.writeRecipe)(file, recipe);
+            pulled.push({ id: ref.id, file });
+            total += 1;
+        }
+        results.push({ kind: kind.name, pulled });
+    }
+    return { dir, kinds: results, total };
+};
+exports.aggregatePull = aggregatePull;
+/**
+ * Diff every recipe file in the workspace against the environment. A
+ * kind with no workspace files is omitted from the result.
+ */
+const aggregateStatus = async (kinds, ctx, options = {}) => {
+    const dir = options.dir ?? exports.DEFAULT_SYNC_DIR;
+    const results = [];
+    let drifted = 0;
+    for (const kind of kinds) {
+        const files = recipeFilesFor(dir, kind.name);
+        if (files.length === 0) {
+            continue;
+        }
+        const items = [];
+        for (const file of files) {
+            const recipe = (0, io_1.loadRecipe)(file, kind.schema);
+            const id = recipeId(recipe);
+            try {
+                const plan = await (0, engine_1.syncDiff)(kind, recipe, { kind: kind.name, id }, ctx);
+                if ((0, plan_1.planIsNoop)(plan)) {
+                    items.push({ id, status: "in-sync" });
+                }
+                else {
+                    items.push({ id, status: "drift", summary: (0, plan_1.summarizePlan)(plan) });
+                    drifted += 1;
+                }
+            }
+            catch (error) {
+                items.push({ id, status: "error", error: (0, errors_1.toScaiError)(error).message });
+            }
+        }
+        results.push({ kind: kind.name, items });
+    }
+    return { dir, kinds: results, drifted };
+};
+exports.aggregateStatus = aggregateStatus;
+/**
+ * Converge every recipe file in the workspace onto the environment. In
+ * `what-if` mode nothing is written — each recipe reports its planned
+ * change count instead. A kind with no workspace files is omitted.
+ */
+const aggregatePush = async (kinds, ctx, options) => {
+    const dir = options.dir ?? exports.DEFAULT_SYNC_DIR;
+    const results = [];
+    let applied = 0;
+    for (const kind of kinds) {
+        const files = recipeFilesFor(dir, kind.name);
+        if (files.length === 0) {
+            continue;
+        }
+        const items = [];
+        for (const file of files) {
+            const recipe = (0, io_1.loadRecipe)(file, kind.schema);
+            const id = recipeId(recipe);
+            try {
+                const outcome = await (0, engine_1.syncPush)(kind, recipe, { kind: kind.name, id }, ctx, {
+                    mode: options.mode,
+                    prune: Boolean(options.prune),
+                });
+                if (outcome.result) {
+                    items.push({ id, status: "applied", appliedCount: outcome.result.applied.length });
+                    applied += outcome.result.applied.length;
+                }
+                else if ((0, plan_1.planIsNoop)(outcome.plan)) {
+                    items.push({ id, status: "in-sync" });
+                }
+                else {
+                    const tally = (0, plan_1.summarizePlan)(outcome.plan);
+                    items.push({
+                        id,
+                        status: "planned",
+                        plannedCount: tally.create + tally.update + tally.delete,
+                    });
+                }
+            }
+            catch (error) {
+                items.push({ id, status: "error", error: (0, errors_1.toScaiError)(error).message });
+            }
+        }
+        results.push({ kind: kind.name, items });
+    }
+    return { dir, mode: options.mode, kinds: results, applied };
+};
+exports.aggregatePush = aggregatePush;

package/dist/sync/engine.d.ts

@@ -0,0 +1,28 @@
+import type { ApplyResult, KindRef, RecipeKind, SyncContext } from "./kind";
+import { type RecipePlan } from "./plan";
+/** `what-if` prints the plan and writes nothing; `apply` converges. */
+export type SyncMode = "what-if" | "apply";
+export interface PushOptions {
+    mode: SyncMode;
+    /**
+     * Include `delete` changes. Off by default — `push` is additive, so a
+     * recipe omitting an element does not remove it from the remote.
+     */
+    prune?: boolean;
+}
+export interface PushOutcome {
+    /** The plan that was computed (deletes filtered out unless `prune`). */
+    plan: RecipePlan;
+    /** The apply result — `null` under `what-if` or for a no-op plan. */
+    result: ApplyResult | null;
+}
+/** Capture live remote state as a recipe (`sync pull`). */
+export declare const syncPull: <T>(kind: RecipeKind<T>, ref: KindRef, ctx: SyncContext) => Promise<T | null>;
+/** Compute the plan to converge `ref` onto `desired` (`sync diff`). */
+export declare const syncDiff: <T>(kind: RecipeKind<T>, desired: T, ref: KindRef, ctx: SyncContext) => Promise<RecipePlan>;
+/**
+ * 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.
+ */
+export declare const syncPush: <T>(kind: RecipeKind<T>, desired: T, ref: KindRef, ctx: SyncContext, options: PushOptions) => Promise<PushOutcome>;