@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.1

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

@@ -0,0 +1,41 @@
+/**
+ * Production `SitecoreApiClient` factory for the Sitecore Authoring +
+ * Management GraphQL surface.
+ *
+ * Unlike `createAuthoringClient` in `recipe/` (which adds path
+ * resolution, parent-folder auto-creation, and read-retry behavior on
+ * top of the wire calls), this factory is a thin **options-binding**
+ * wrapper around the existing function-style API:
+ *
+ *   const sc = createSitecoreApiClient({ host, accessToken });
+ *   await sc.fetchItemMetadata("master", "/sitecore/content/Home");
+ *
+ * It exists so the deploy + serialization surfaces match the recipe
+ * surface's seam shape (`create*Client(options) -> typed methods`).
+ * If you don't want the seam, the underlying functions remain exported
+ * from `serialization` and you can call them options-first directly.
+ */
+import { fetchHistoryEntries, fetchHistoryTimestamp } from "./history";
+import { executeSerializationCommands, fetchItemData, fetchItemMetadata } from "./items";
+import { checkPublishStatus, fetchPublishingTargets, publishItems } from "./publish";
+import { fetchRoles, pushRoleCommands } from "./roles";
+import type { SitecoreApiClientOptions } from "./types";
+import { fetchUsers, pushUserCommands } from "./users";
+type Tail<F> = F extends (head: SitecoreApiClientOptions, ...rest: infer R) => infer X ? (...args: R) => X : never;
+export interface SitecoreApiClient {
+    readonly options: SitecoreApiClientOptions;
+    fetchItemMetadata: Tail<typeof fetchItemMetadata>;
+    fetchItemData: Tail<typeof fetchItemData>;
+    executeSerializationCommands: Tail<typeof executeSerializationCommands>;
+    fetchHistoryTimestamp: Tail<typeof fetchHistoryTimestamp>;
+    fetchHistoryEntries: Tail<typeof fetchHistoryEntries>;
+    fetchRoles: Tail<typeof fetchRoles>;
+    pushRoleCommands: Tail<typeof pushRoleCommands>;
+    fetchUsers: Tail<typeof fetchUsers>;
+    pushUserCommands: Tail<typeof pushUserCommands>;
+    publishItems: Tail<typeof publishItems>;
+    checkPublishStatus: Tail<typeof checkPublishStatus>;
+    fetchPublishingTargets: Tail<typeof fetchPublishingTargets>;
+}
+export declare const createSitecoreApiClient: (options: SitecoreApiClientOptions) => SitecoreApiClient;
+export {};

package/dist/serialization/api/client.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSitecoreApiClient = void 0;
+/**
+ * Production `SitecoreApiClient` factory for the Sitecore Authoring +
+ * Management GraphQL surface.
+ *
+ * Unlike `createAuthoringClient` in `recipe/` (which adds path
+ * resolution, parent-folder auto-creation, and read-retry behavior on
+ * top of the wire calls), this factory is a thin **options-binding**
+ * wrapper around the existing function-style API:
+ *
+ *   const sc = createSitecoreApiClient({ host, accessToken });
+ *   await sc.fetchItemMetadata("master", "/sitecore/content/Home");
+ *
+ * It exists so the deploy + serialization surfaces match the recipe
+ * surface's seam shape (`create*Client(options) -> typed methods`).
+ * If you don't want the seam, the underlying functions remain exported
+ * from `serialization` and you can call them options-first directly.
+ */
+const history_1 = require("./history");
+const items_1 = require("./items");
+const publish_1 = require("./publish");
+const roles_1 = require("./roles");
+const users_1 = require("./users");
+const createSitecoreApiClient = (options) => ({
+    options,
+    fetchItemMetadata: (database, path, ...rest) => (0, items_1.fetchItemMetadata)(options, database, path, ...rest),
+    fetchItemData: (database, path, ...rest) => (0, items_1.fetchItemData)(options, database, path, ...rest),
+    executeSerializationCommands: (commands, ...rest) => (0, items_1.executeSerializationCommands)(options, commands, ...rest),
+    fetchHistoryTimestamp: (...rest) => (0, history_1.fetchHistoryTimestamp)(options, ...rest),
+    fetchHistoryEntries: (timestamp, ...rest) => (0, history_1.fetchHistoryEntries)(options, timestamp, ...rest),
+    fetchRoles: (predicates, ...rest) => (0, roles_1.fetchRoles)(options, predicates, ...rest),
+    pushRoleCommands: (commands, ...rest) => (0, roles_1.pushRoleCommands)(options, commands, ...rest),
+    fetchUsers: (predicates, ...rest) => (0, users_1.fetchUsers)(options, predicates, ...rest),
+    pushUserCommands: (commands, ...rest) => (0, users_1.pushUserCommands)(options, commands, ...rest),
+    publishItems: (itemIds, ...rest) => (0, publish_1.publishItems)(options, itemIds, ...rest),
+    checkPublishStatus: (publishId, ...rest) => (0, publish_1.checkPublishStatus)(options, publishId, ...rest),
+    fetchPublishingTargets: (...rest) => (0, publish_1.fetchPublishingTargets)(options, ...rest),
+});
+exports.createSitecoreApiClient = createSitecoreApiClient;

package/dist/serialization/api/graphql.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Management GraphQL transport for serialization commands.
+ *
+ * Thin wrapper over `src/shared/graphql.ts` — supplies the Management
+ * service path and label. Parallels `src/recipe/api/graphql.ts` which
+ * targets the Authoring endpoint.
+ */
+import type { SitecoreApiClientOptions } from "./types";
+import { type GraphQLRequestOptions } from "../../shared/graphql";
+export type { GraphQLRequestOptions };
+export declare const runGraphQL: <T>(environment: SitecoreApiClientOptions, query: string, variables?: Record<string, unknown>, options?: GraphQLRequestOptions) => Promise<T>;

package/dist/serialization/api/history.d.ts

@@ -0,0 +1,8 @@
+import type { SitecoreApiClientOptions } from "./types";
+import { HistoryEntry } from "../types";
+import { GraphQLRequestOptions } from "./graphql";
+export declare const fetchHistoryTimestamp: (environment: SitecoreApiClientOptions, options?: GraphQLRequestOptions) => Promise<string>;
+export declare const fetchHistoryEntries: (environment: SitecoreApiClientOptions, timestamp: string, options?: GraphQLRequestOptions) => Promise<{
+    timestamp: string;
+    entries: HistoryEntry[];
+}>;

package/dist/serialization/api/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Curated public Sitecore Management + Authoring GraphQL client surface —
+ * re-exported by `../index.ts`
+ * (`@sitecoreai-labs/sitecoreai-cli/serialization`).
+ *
+ * Source of truth for what's part of the public Sitecore Management +
+ * Authoring GraphQL client surface. Every symbol below is intentional.
+ *
+ * Internal scai callers should keep importing from sibling files
+ * (`./auth`, `./graphql`, etc.) for unstable helpers; this index file
+ * is the only path that's contract-stable.
+ */
+export type { SitecoreApiClientOptions } from "./types";
+export { createSitecoreApiClient, type SitecoreApiClient } from "./client";
+export { runGraphQL, type GraphQLRequestOptions } from "./graphql";
+export { acquireAccessToken, getAccessToken, requestClientCredentialsToken, requestPasswordToken, requestDeviceAuthorization, pollDeviceToken, DEFAULT_SITECORE_API_AUDIENCE, type AccessTokenResult, type DeviceAuthorizationResult, } from "./auth";
+export { fetchItemMetadata, fetchItemData, executeSerializationCommands } from "./items";
+export { fetchHistoryTimestamp, fetchHistoryEntries } from "./history";
+export { fetchRoles, pushRoleCommands } from "./roles";
+export { fetchUsers, pushUserCommands } from "./users";
+export { publishItems, checkPublishStatus, fetchPublishingTargets, publishItemSubtree, type PublishItemSubtreeResult, } from "./publish";
+export type { ItemData, ItemMetadata, ItemLanguage, ItemVersion, ItemFieldValue, FieldFilter, RoleData, UserData, HistoryEntry, RolePredicateItem, UserPredicateItem, } from "../types";
+export { ItemPath } from "../item-path";

package/dist/serialization/api/index.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Curated public Sitecore Management + Authoring GraphQL client surface —
+ * re-exported by `../index.ts`
+ * (`@sitecoreai-labs/sitecoreai-cli/serialization`).
+ *
+ * Source of truth for what's part of the public Sitecore Management +
+ * Authoring GraphQL client surface. Every symbol below is intentional.
+ *
+ * Internal scai callers should keep importing from sibling files
+ * (`./auth`, `./graphql`, etc.) for unstable helpers; this index file
+ * is the only path that's contract-stable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ItemPath = exports.publishItemSubtree = exports.fetchPublishingTargets = exports.checkPublishStatus = exports.publishItems = exports.pushUserCommands = exports.fetchUsers = exports.pushRoleCommands = exports.fetchRoles = exports.fetchHistoryEntries = exports.fetchHistoryTimestamp = exports.executeSerializationCommands = exports.fetchItemData = exports.fetchItemMetadata = exports.DEFAULT_SITECORE_API_AUDIENCE = exports.pollDeviceToken = exports.requestDeviceAuthorization = exports.requestPasswordToken = exports.requestClientCredentialsToken = exports.getAccessToken = exports.acquireAccessToken = exports.runGraphQL = exports.createSitecoreApiClient = void 0;
+// --- Curated client seam ------------------------------------------------
+//
+// `createSitecoreApiClient(options)` returns a typed, options-bound
+// facade over the function-style item / history / roles / users /
+// publish surface — parallels `createDeployApiClient` and
+// `createSitesApiClient`. The underlying functions remain exported
+// below for direct use.
+var client_1 = require("./client");
+Object.defineProperty(exports, "createSitecoreApiClient", { enumerable: true, get: function () { return client_1.createSitecoreApiClient; } });
+// --- Transport seam ------------------------------------------------------
+var graphql_1 = require("./graphql");
+Object.defineProperty(exports, "runGraphQL", { enumerable: true, get: function () { return graphql_1.runGraphQL; } });
+// --- Auth ----------------------------------------------------------------
+// `acquireAccessToken` is the pure OAuth flow (no keychain) added in
+// Phase A; library consumers that bring their own token cache should
+// use it. `getAccessToken` is the CLI-shaped keychain-aware wrapper.
+var auth_1 = require("./auth");
+Object.defineProperty(exports, "acquireAccessToken", { enumerable: true, get: function () { return auth_1.acquireAccessToken; } });
+Object.defineProperty(exports, "getAccessToken", { enumerable: true, get: function () { return auth_1.getAccessToken; } });
+Object.defineProperty(exports, "requestClientCredentialsToken", { enumerable: true, get: function () { return auth_1.requestClientCredentialsToken; } });
+Object.defineProperty(exports, "requestPasswordToken", { enumerable: true, get: function () { return auth_1.requestPasswordToken; } });
+Object.defineProperty(exports, "requestDeviceAuthorization", { enumerable: true, get: function () { return auth_1.requestDeviceAuthorization; } });
+Object.defineProperty(exports, "pollDeviceToken", { enumerable: true, get: function () { return auth_1.pollDeviceToken; } });
+Object.defineProperty(exports, "DEFAULT_SITECORE_API_AUDIENCE", { enumerable: true, get: function () { return auth_1.DEFAULT_SITECORE_API_AUDIENCE; } });
+// --- Item operations -----------------------------------------------------
+var items_1 = require("./items");
+Object.defineProperty(exports, "fetchItemMetadata", { enumerable: true, get: function () { return items_1.fetchItemMetadata; } });
+Object.defineProperty(exports, "fetchItemData", { enumerable: true, get: function () { return items_1.fetchItemData; } });
+Object.defineProperty(exports, "executeSerializationCommands", { enumerable: true, get: function () { return items_1.executeSerializationCommands; } });
+// --- History (poll for remote changes) ----------------------------------
+var history_1 = require("./history");
+Object.defineProperty(exports, "fetchHistoryTimestamp", { enumerable: true, get: function () { return history_1.fetchHistoryTimestamp; } });
+Object.defineProperty(exports, "fetchHistoryEntries", { enumerable: true, get: function () { return history_1.fetchHistoryEntries; } });
+// --- Roles ---------------------------------------------------------------
+var roles_1 = require("./roles");
+Object.defineProperty(exports, "fetchRoles", { enumerable: true, get: function () { return roles_1.fetchRoles; } });
+Object.defineProperty(exports, "pushRoleCommands", { enumerable: true, get: function () { return roles_1.pushRoleCommands; } });
+// --- Users ---------------------------------------------------------------
+var users_1 = require("./users");
+Object.defineProperty(exports, "fetchUsers", { enumerable: true, get: function () { return users_1.fetchUsers; } });
+Object.defineProperty(exports, "pushUserCommands", { enumerable: true, get: function () { return users_1.pushUserCommands; } });
+// --- Publishing ---------------------------------------------------------
+var publish_1 = require("./publish");
+Object.defineProperty(exports, "publishItems", { enumerable: true, get: function () { return publish_1.publishItems; } });
+Object.defineProperty(exports, "checkPublishStatus", { enumerable: true, get: function () { return publish_1.checkPublishStatus; } });
+Object.defineProperty(exports, "fetchPublishingTargets", { enumerable: true, get: function () { return publish_1.fetchPublishingTargets; } });
+Object.defineProperty(exports, "publishItemSubtree", { enumerable: true, get: function () { return publish_1.publishItemSubtree; } });
+var item_path_1 = require("../item-path");
+Object.defineProperty(exports, "ItemPath", { enumerable: true, get: function () { return item_path_1.ItemPath; } });

package/dist/serialization/api/items.d.ts

@@ -0,0 +1,7 @@
+import { ItemData, ItemMetadata } from "../types";
+import type { SitecoreApiClientOptions } from "./types";
+import { FieldFilterSet } from "../field-filter";
+import { GraphQLRequestOptions } from "./graphql";
+export declare const fetchItemMetadata: (environment: SitecoreApiClientOptions, database: string, pathOrId: string, scope: string, fieldFilter: FieldFilterSet, useDebugSignatures: boolean, options?: GraphQLRequestOptions) => Promise<ItemMetadata[]>;
+export declare const fetchItemData: (environment: SitecoreApiClientOptions, database: string, pathOrId: string, scope: string, fieldFilter: FieldFilterSet, options?: GraphQLRequestOptions) => Promise<ItemData[]>;
+export declare const executeSerializationCommands: (environment: SitecoreApiClientOptions, commands: unknown[], minimumLogLevel: string, options?: GraphQLRequestOptions) => Promise<unknown[]>;

package/dist/serialization/api/items.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeSerializationCommands = exports.fetchItemData = exports.fetchItemMetadata = void 0;
+const item_path_1 = require("../item-path");
+const signature_1 = require("../signature");
+const errors_1 = require("../../shared/errors");
+const graphql_1 = require("./graphql");
+const serializeMetadataFragment = `
+  serialize(path: $path, database: $database, scope: $scope, excludedFieldIds: $excludedFieldIds) {
+    id
+    parentId
+    templateId
+    path
+    hasChildren
+    dataSignature
+  }
+`;
+const serializeMetadataDebugFragment = serializeMetadataFragment.replace("dataSignature", "dataSignature(debug: true)");
+const serializeDataFragment = `
+  serialize(path: $path, database: $database, scope: $scope, excludedFieldIds: $excludedFieldIds) {
+    data
+  }
+`;
+const executeSerializationCommandsMutation = `
+mutation($commands: [ItemCommand], $minimumLogLevel: LogLevel) {
+  executeSerializationCommands(commands: $commands, minimumLogLevel: $minimumLogLevel) {
+    success
+    name
+    messages {
+      logLevel
+      eventID { id name }
+      message
+    }
+  }
+}`;
+const mapScope = (scope) => {
+    if (scope.toLowerCase() === "singleitem") {
+        return "SingleItem";
+    }
+    if (scope.toLowerCase() === "itemandchildren") {
+        return "ItemAndChildren";
+    }
+    if (scope.toLowerCase() === "descendantsonly") {
+        return "DescendantsOnly";
+    }
+    return "ItemAndDescendants";
+};
+const parseItemData = (data, database) => {
+    if (!data || typeof data !== "string") {
+        throw (0, errors_1.createScaiError)("GraphQL response did not contain serialized item data.", "UNKNOWN");
+    }
+    const parsed = JSON.parse(data);
+    const versions = parsed.versions?.map((version) => ({
+        language: version.language,
+        version: version.version,
+        fields: version.fields.map((field) => ({
+            fieldId: field.fieldId,
+            nameHint: field.nameHint,
+            value: field.value ?? "",
+            blobId: field.blobId ?? null,
+        })),
+    })) ?? [];
+    const item = {
+        id: parsed.id,
+        parentId: parsed.parentId,
+        templateId: parsed.templateId,
+        path: item_path_1.ItemPath.fromPathString(parsed.path.toString()),
+        name: parsed.name,
+        branchId: parsed.branchId,
+        database,
+        sharedFields: parsed.sharedFields.map((field) => ({
+            fieldId: field.fieldId,
+            nameHint: field.nameHint,
+            value: field.value ?? "",
+            blobId: field.blobId ?? null,
+        })),
+        unversionedFields: parsed.unversionedFields.map((language) => ({
+            language: language.language,
+            fields: language.fields.map((field) => ({
+                fieldId: field.fieldId,
+                nameHint: field.nameHint,
+                value: field.value ?? "",
+                blobId: field.blobId ?? null,
+            })),
+        })),
+        versions,
+        dataSignature: parsed.dataSignature,
+    };
+    if (!item.dataSignature) {
+        const base = (0, signature_1.createDataSignatureBase)(item);
+        item.dataSignature = (0, signature_1.createSignature)(base) ?? "";
+    }
+    return item;
+};
+const fetchItemMetadata = async (environment, database, pathOrId, scope, fieldFilter, useDebugSignatures, options) => {
+    const query = `query($path: String!, $database: String!, $scope: TreeScope!, $excludedFieldIds: [String]) { ${useDebugSignatures ? serializeMetadataDebugFragment : serializeMetadataFragment} }`;
+    const data = await (0, graphql_1.runGraphQL)(environment, query, {
+        path: pathOrId,
+        database,
+        scope: mapScope(scope),
+        excludedFieldIds: Array.from(fieldFilter.excludes),
+    }, options);
+    return data.serialize.map((item) => ({
+        id: item.id,
+        parentId: item.parentId,
+        templateId: item.templateId,
+        path: item_path_1.ItemPath.fromPathString(item.path),
+        hasChildren: item.hasChildren,
+        dataSignature: item.dataSignature,
+        database,
+    }));
+};
+exports.fetchItemMetadata = fetchItemMetadata;
+const fetchItemData = async (environment, database, pathOrId, scope, fieldFilter, options) => {
+    const query = `query($path: String!, $database: String!, $scope: TreeScope!, $excludedFieldIds: [String]) { ${serializeDataFragment} }`;
+    const data = await (0, graphql_1.runGraphQL)(environment, query, {
+        path: pathOrId,
+        database,
+        scope: mapScope(scope),
+        excludedFieldIds: Array.from(fieldFilter.excludes),
+    }, options);
+    return data.serialize.map((entry) => parseItemData(entry.data, database));
+};
+exports.fetchItemData = fetchItemData;
+const executeSerializationCommands = async (environment, commands, minimumLogLevel, options) => {
+    const data = await (0, graphql_1.runGraphQL)(environment, executeSerializationCommandsMutation, {
+        commands,
+        minimumLogLevel,
+    }, options);
+    return data.executeSerializationCommands;
+};
+exports.executeSerializationCommands = executeSerializationCommands;

package/dist/serialization/api/publish.d.ts

@@ -0,0 +1,43 @@
+import type { SitecoreApiClientOptions } from "./types";
+import { GraphQLRequestOptions } from "./graphql";
+export declare const publishItems: (environment: SitecoreApiClientOptions, itemIds: string[], target?: string, options?: GraphQLRequestOptions) => Promise<{
+    id: string;
+    processedCount: number;
+    stateName: string;
+}>;
+export declare const checkPublishStatus: (environment: SitecoreApiClientOptions, publishId: string, options?: GraphQLRequestOptions) => Promise<{
+    id: string;
+    processedCount: number;
+    stateName: string;
+}>;
+export declare const fetchPublishingTargets: (environment: SitecoreApiClientOptions, options?: GraphQLRequestOptions) => Promise<string[]>;
+/** Outcome of {@link publishItemSubtree}. */
+export interface PublishItemSubtreeResult {
+    /** Source item path that was published. */
+    path: string;
+    /** Source database the items were read from. */
+    database: string;
+    /** Publish target, when one was given. */
+    target?: string;
+    /** Number of items resolved under `path` and submitted to the job. */
+    itemCount: number;
+    /** The publish job receipt. */
+    job: {
+        id: string;
+        processedCount: number;
+        stateName: string;
+    };
+}
+/**
+ * Publish an item and all of its descendants in one job.
+ *
+ * Resolves every item under `path` via the Management API, then submits
+ * the whole set to the publish pipeline. Throws (`INPUT_INVALID`) when
+ * `path` resolves to no items. Composes `fetchItemMetadata` +
+ * `publishItems` so callers (CLI, MCP, embedding SDK) get the workflow
+ * rather than wiring the two raw calls themselves.
+ */
+export declare const publishItemSubtree: (environment: SitecoreApiClientOptions, path: string, options?: {
+    database?: string;
+    target?: string;
+}) => Promise<PublishItemSubtreeResult>;

package/dist/serialization/api/publish.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.publishItemSubtree = exports.fetchPublishingTargets = exports.checkPublishStatus = exports.publishItems = void 0;
+const errors_1 = require("../../shared/errors");
+const graphql_1 = require("./graphql");
+const field_filter_1 = require("../field-filter");
+const items_1 = require("./items");
+const publishMutation = `
+mutation($path: String, $languages: [String] , $itemIds : [String], $republish : Boolean, $target : String) {
+  publish(path: $path, languages: $languages, itemIds :$itemIds, republish :$republish, target :$target) {
+    id
+    processedCount
+    stateCode
+    stateName
+  }
+}`;
+const publishStatusQuery = `
+query($id: String)
+{
+  publishingStatus(id: $id)
+  {
+    id
+    processedCount
+    stateCode
+    stateName
+  }
+}`;
+const listTargetsQuery = `
+query {
+  listOfTargets
+}`;
+const publishItems = async (environment, itemIds, target, options) => {
+    const data = await (0, graphql_1.runGraphQL)(environment, publishMutation, { itemIds, target }, options);
+    return data.publish;
+};
+exports.publishItems = publishItems;
+const checkPublishStatus = async (environment, publishId, options) => {
+    const data = await (0, graphql_1.runGraphQL)(environment, publishStatusQuery, { id: publishId }, options);
+    return data.publishingStatus;
+};
+exports.checkPublishStatus = checkPublishStatus;
+const fetchPublishingTargets = async (environment, options) => {
+    const data = await (0, graphql_1.runGraphQL)(environment, listTargetsQuery, undefined, options);
+    return data.listOfTargets ?? [];
+};
+exports.fetchPublishingTargets = fetchPublishingTargets;
+/**
+ * Publish an item and all of its descendants in one job.
+ *
+ * Resolves every item under `path` via the Management API, then submits
+ * the whole set to the publish pipeline. Throws (`INPUT_INVALID`) when
+ * `path` resolves to no items. Composes `fetchItemMetadata` +
+ * `publishItems` so callers (CLI, MCP, embedding SDK) get the workflow
+ * rather than wiring the two raw calls themselves.
+ */
+const publishItemSubtree = async (environment, path, options = {}) => {
+    const database = options.database ?? "master";
+    const fieldFilter = (0, field_filter_1.createFieldFilterSet)([], []);
+    const metadata = await (0, items_1.fetchItemMetadata)(environment, database, path, "ItemAndDescendants", fieldFilter, false);
+    const itemIds = metadata.map((entry) => entry.id);
+    if (itemIds.length === 0) {
+        throw (0, errors_1.createScaiError)(`No items found under path '${path}' in database '${database}'.`, "INPUT_INVALID");
+    }
+    const job = await (0, exports.publishItems)(environment, itemIds, options.target);
+    return { path, database, target: options.target, itemCount: itemIds.length, job };
+};
+exports.publishItemSubtree = publishItemSubtree;

package/dist/serialization/api/roles.d.ts

@@ -0,0 +1,8 @@
+import type { SitecoreApiClientOptions } from "./types";
+import { RoleData } from "../types";
+import { GraphQLRequestOptions } from "./graphql";
+export declare const fetchRoles: (environment: SitecoreApiClientOptions, predicates: Array<{
+    domain: string;
+    pattern: string;
+}>, options?: GraphQLRequestOptions) => Promise<RoleData[]>;
+export declare const pushRoleCommands: (environment: SitecoreApiClientOptions, commands: unknown[], options?: GraphQLRequestOptions) => Promise<unknown[]>;

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

@@ -0,0 +1,65 @@
+/**
+ * Public option shape for the Sitecore Management + Authoring GraphQL
+ * clients. Library callers construct one of these directly. The CLI
+ * passes its full `EnvironmentConfiguration` (which structurally
+ * satisfies this interface) — no per-call adapter.
+ *
+ * Why a structural subset and not the full config: `EnvironmentConfiguration`
+ * has 30+ fields covering deploy-token caching, recipe roots, allow-write
+ * gates, tenant identifiers, etc. — none of which the GraphQL transport
+ * uses. Library callers (orchestrators, MCP servers, tests) should
+ * construct only the auth + host bits they actually need.
+ *
+ * `host` is functionally required for any API call (every transport
+ * throws `INPUT_INVALID` when it's missing), but it stays optional in
+ * the type so this interface is satisfied by `EnvironmentConfiguration`
+ * — which has it optional because the config wizard may not have set
+ * it yet at construction time.
+ */
+import type { AutomationClientMetadata } from "../../config/types";
+export interface SitecoreApiClientOptions {
+    /** CM hostname (e.g. `https://xmc-org-env.sitecorecloud.io`). */
+    host?: string;
+    /** Sitecore organization id — used to resolve org-scoped credentials. */
+    organizationId?: string;
+    /** OAuth identity authority (e.g. `https://auth.sitecorecloud.io`). */
+    authority?: string;
+    /** OAuth client id. */
+    clientId?: string;
+    /** OAuth client secret (required for client-credentials flow). */
+    clientSecret?: string;
+    /**
+     * Non-secret metadata of the scai-minted env-scoped automation client.
+     * Carried through from `EnvironmentConfiguration.automationClient` so
+     * the auth layer can pair `automationClient.clientId` with the secret
+     * it reads from the OS keychain. Only `clientId` is used here.
+     */
+    automationClient?: AutomationClientMetadata;
+    /**
+     * `clientId` of the scai-minted org-scoped automation client — read
+     * from the root config's `orgClients[organizationId]` block. The org
+     * client lives at the root of the config, not on the env profile, so
+     * a caller that wants tier-3 (org-client) resolution must populate
+     * this from the resolved `RootConfiguration`.
+     */
+    orgClientId?: string;
+    /** OAuth audience. Defaults to `https://api.sitecorecloud.io`. */
+    audience?: string;
+    /** Pre-obtained access token. Bypasses OAuth flow entirely. */
+    accessToken?: string;
+    /** Pre-obtained refresh token. */
+    refreshToken?: string;
+    /** Additional refresh-token request parameters (rarely needed). */
+    refreshTokenParameters?: Record<string, string>;
+    /** Use client-credentials flow. Defaults to false; requires `clientSecret`. */
+    useClientCredentials?: boolean;
+    /**
+     * Cache acquired tokens in the OS keychain. Defaults to true.
+     * Has no effect when `name` is unset — caching is keyed by env name.
+     * Library callers that bring their own cache should pass
+     * `cacheAuthenticationToken: false`.
+     */
+    cacheAuthenticationToken?: boolean;
+    /** Environment name; used as the keychain cache key. */
+    name?: string;
+}

package/dist/serialization/api/types.js

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

package/dist/serialization/api/users.d.ts

@@ -0,0 +1,8 @@
+import type { SitecoreApiClientOptions } from "./types";
+import { UserData } from "../types";
+import { GraphQLRequestOptions } from "./graphql";
+export declare const fetchUsers: (environment: SitecoreApiClientOptions, predicates: Array<{
+    domain: string;
+    pattern: string;
+}>, options?: GraphQLRequestOptions) => Promise<UserData[]>;
+export declare const pushUserCommands: (environment: SitecoreApiClientOptions, commands: unknown[], options?: GraphQLRequestOptions) => Promise<unknown[]>;

package/dist/serialization/commands.d.ts

@@ -45,4 +45,3 @@ export declare const buildCommandsForSubtree: (subtree: FilesystemTreeSpec, sour
 export declare const buildUpdateCommandData: (comparison: ItemComparisonResult, push: boolean) => UpdateCommandData[];
 export declare const enrichUpdateCommands: (commands: ItemCommand[], sourceData: Map<string, ItemData>, destinationData: Map<string, ItemData>, push: boolean) => void;
 export declare const enrichCreateCommands: (commands: ItemCommand[], sourceData: Map<string, ItemData>) => void;
-//# sourceMappingURL=commands.d.ts.map

package/dist/serialization/compare.d.ts

@@ -26,4 +26,3 @@ export type ItemComparisonResult = {
     changedVersions: ItemVersionComparisonResult[];
 };
 export declare const compareItems: (left: ItemData, right: ItemData) => ItemComparisonResult;
-//# sourceMappingURL=compare.d.ts.map

package/dist/serialization/context.d.ts

@@ -0,0 +1,25 @@
+import type { RootConfiguration, SerializationModuleConfiguration } from "../config/types";
+import { FilesystemTreeSpec } from "./tree-spec";
+/** Options for {@link loadConfigAndModules}. */
+export interface LoadSerializationModulesOptions {
+    /** Base directory for resolving `sitecoreai.cli.json`; defaults to cwd. */
+    config?: string;
+    /** Environment profile name; defaults to the config's default profile. */
+    environmentName?: string;
+    /** Module-namespace include filter. */
+    include?: string[];
+    /** Module-namespace exclude filter. */
+    exclude?: string[];
+}
+/**
+ * Resolve the root configuration for an environment and load every
+ * serialization module it references.
+ */
+export declare const loadConfigAndModules: (options: LoadSerializationModulesOptions) => Promise<{
+    root: RootConfiguration;
+    modules: SerializationModuleConfiguration[];
+}>;
+/** Group every module's subtrees by the database they target. */
+export declare const groupSubtreesByDatabase: (modules: SerializationModuleConfiguration[]) => Map<string, FilesystemTreeSpec[]>;
+/** Throw unless the environment is configured to allow writes. */
+export declare const ensureAllowWrite: (root: RootConfiguration, environmentName: string) => void;

package/dist/serialization/context.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureAllowWrite = exports.groupSubtreesByDatabase = exports.loadConfigAndModules = void 0;
+/**
+ * Serialization context — root config + serialization-module loading,
+ * subtree grouping by database, and the write-consent guard.
+ *
+ * This is the substantive orchestration the CLI runners (`./tasks`) and
+ * MCP tools share. It is exported from the area barrel so an SDK
+ * consumer can load the same config + module set the CLI works against.
+ *
+ * Presentation-free: no logger, no stdout, no `process.exit`.
+ */
+const root_config_1 = require("../config/root-config");
+const modules_1 = require("../config/modules");
+const errors_1 = require("../shared/errors");
+/**
+ * Resolve the root configuration for an environment and load every
+ * serialization module it references.
+ */
+const loadConfigAndModules = async (options) => {
+    const configPath = options.config ?? process.cwd();
+    const rootFile = (0, root_config_1.readRootConfigurationFile)(configPath);
+    const envName = options.environmentName ?? rootFile.config.defaultEnvProfile;
+    const root = (0, root_config_1.readRootConfiguration)(configPath, envName);
+    const modules = await (0, modules_1.readSerializationModules)(root, options.include, options.exclude);
+    return { root, modules };
+};
+exports.loadConfigAndModules = loadConfigAndModules;
+/** Group every module's subtrees by the database they target. */
+const groupSubtreesByDatabase = (modules) => {
+    const map = new Map();
+    for (const module of modules) {
+        for (const subtree of module.items.includes) {
+            if (!map.has(subtree.database)) {
+                map.set(subtree.database, []);
+            }
+            map.get(subtree.database).push(subtree);
+        }
+    }
+    return map;
+};
+exports.groupSubtreesByDatabase = groupSubtreesByDatabase;
+/** Throw unless the environment is configured to allow writes. */
+const ensureAllowWrite = (root, environmentName) => {
+    const env = root.environments[environmentName];
+    if (!env?.allowWrite) {
+        const envKey = environmentName
+            .trim()
+            .toUpperCase()
+            .replace(/[^A-Z0-9]+/g, "_")
+            .replace(/^_+|_+$/g, "");
+        throw (0, errors_1.createScaiError)(`Environment ${environmentName} is not configured to allow writing data.`, "INPUT_INVALID", {
+            hint: `Set allowWrite in sitecoreai.cli.json, set SITECOREAI_ENV_${envKey}_ALLOW_WRITE=true, or pass --allow-write.`,
+        });
+    }
+};
+exports.ensureAllowWrite = ensureAllowWrite;

package/dist/serialization/field-filter.d.ts

@@ -4,4 +4,3 @@ export type FieldFilterSet = {
 };
 export declare const createFieldFilterSet: (rootExcluded: FieldFilter[], moduleExcluded: FieldFilter[]) => FieldFilterSet;
 export declare const filterFieldIds: (filterSet: FieldFilterSet) => string[];
-//# sourceMappingURL=field-filter.d.ts.map

package/dist/serialization/filesystem-store/constants.d.ts

@@ -1,3 +1,2 @@
 export declare const ROLES_FOLDER_SUFFIX = "_roles";
 export declare const USERS_FOLDER_SUFFIX = "_users";
-//# sourceMappingURL=constants.d.ts.map