@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/serialization/tasks/users.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.syncUsersPush = exports.syncUsersPull = void 0;
-const sitecore_api_1 = require("../sitecore-api");
-const filesystem_store_1 = require("../filesystem-store");
+const users_1 = require("../api/users");
+const users_2 = require("../filesystem-store/users");
 const shared_1 = require("./shared");
 const roles_1 = require("./roles");
 const profilePropsEqual = (left, right) => {
@@ -28,22 +28,22 @@ const syncUsersPull = async (root, module, environmentName, logger) => {
     }
     const apiTimeoutMs = (0, shared_1.resolveApiTimeoutMs)(root);
     const predicates = module.users.map((user) => ({ domain: user.domain, pattern: user.pattern }));
-    const sourceUsers = await (0, sitecore_api_1.fetchUsers)(root.environments[environmentName], predicates, {
+    const sourceUsers = await (0, users_1.fetchUsers)(root.environments[environmentName], predicates, {
         timeoutMs: apiTimeoutMs,
     });
-    const destUsers = await (0, filesystem_store_1.readUsersFromFilesystem)(root, module);
+    const destUsers = await (0, users_2.readUsersFromFilesystem)(root, module);
     const destMap = new Map(destUsers.map((user) => [user.userName.toLowerCase(), user]));
     for (const user of sourceUsers) {
         const existing = destMap.get(user.userName.toLowerCase());
         if (!existing || !usersEqual(existing, user)) {
-            await (0, filesystem_store_1.writeUserToFilesystem)(root, module, user);
+            await (0, users_2.writeUserToFilesystem)(root, module, user);
         }
     }
     if (root.serialization.removeOrphansForUsers) {
         const sourceNames = new Set(sourceUsers.map((user) => user.userName.toLowerCase()));
         for (const dest of destUsers) {
             if (!sourceNames.has(dest.userName.toLowerCase())) {
-                await (0, filesystem_store_1.removeUserFromFilesystem)(dest.serializedItemId);
+                await (0, users_2.removeUserFromFilesystem)(dest.serializedItemId);
             }
         }
     }
@@ -56,8 +56,8 @@ const syncUsersPush = async (root, module, environmentName, logger) => {
     }
     const apiTimeoutMs = (0, shared_1.resolveApiTimeoutMs)(root);
     const predicates = module.users.map((user) => ({ domain: user.domain, pattern: user.pattern }));
-    const sourceUsers = await (0, filesystem_store_1.readUsersFromFilesystem)(root, module);
-    const destinationUsers = await (0, sitecore_api_1.fetchUsers)(root.environments[environmentName], predicates, {
+    const sourceUsers = await (0, users_2.readUsersFromFilesystem)(root, module);
+    const destinationUsers = await (0, users_1.fetchUsers)(root.environments[environmentName], predicates, {
         timeoutMs: apiTimeoutMs,
     });
     const destMap = new Map(destinationUsers.map((user) => [user.userName.toLowerCase(), user]));
@@ -81,7 +81,7 @@ const syncUsersPush = async (root, module, environmentName, logger) => {
         }
     }
     if (commands.length > 0) {
-        await (0, sitecore_api_1.pushUserCommands)(root.environments[environmentName], commands, {
+        await (0, users_1.pushUserCommands)(root.environments[environmentName], commands, {
             timeoutMs: apiTimeoutMs,
         });
     }

package/dist/serialization/tasks/validate.d.ts

@@ -2,4 +2,3 @@ import type { CommonOptions } from "./types";
 export declare const runValidate: (options: CommonOptions & {
     fix?: boolean;
 }) => Promise<void>;
-//# sourceMappingURL=validate.d.ts.map

package/dist/serialization/tasks/validate.js

@@ -1,13 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runValidate = void 0;
-const filesystem_store_1 = require("../filesystem-store");
+const items_1 = require("../filesystem-store/items");
 const shared_1 = require("./shared");
 const runValidate = async (options) => {
     const logger = (0, shared_1.toLogger)(options);
     const { modules } = await (0, shared_1.loadConfigAndModules)(options);
     const subtrees = modules.flatMap((module) => module.items.includes);
-    const { metadata } = await (0, filesystem_store_1.loadFilesystemItems)(subtrees);
+    const { metadata } = await (0, items_1.loadFilesystemItems)(subtrees);
     const seenIds = new Set();
     let hasErrors = false;
     let duplicateCount = 0;

package/dist/serialization/tasks/watch.d.ts

@@ -1,3 +1,2 @@
 import type { WatchOptions } from "./types";
 export declare const runWatch: (options: WatchOptions) => Promise<void>;
-//# sourceMappingURL=watch.d.ts.map

package/dist/serialization/tasks/watch.js

@@ -4,8 +4,9 @@ exports.runWatch = void 0;
 const path_provider_1 = require("../path-provider");
 const item_path_1 = require("../item-path");
 const field_filter_1 = require("../field-filter");
-const sitecore_api_1 = require("../sitecore-api");
-const filesystem_store_1 = require("../filesystem-store");
+const history_1 = require("../api/history");
+const items_1 = require("../api/items");
+const items_2 = require("../filesystem-store/items");
 const shared_1 = require("./shared");
 const pull_1 = require("./pull");
 const runWatch = async (options) => {
@@ -21,13 +22,13 @@ const runWatch = async (options) => {
     for (const [database, subtrees] of subtreesByDb) {
         pathProviders.set(database, new path_provider_1.FilesystemPathProvider(subtrees));
     }
-    let timestamp = await (0, sitecore_api_1.fetchHistoryTimestamp)(root.environments[envName], {
+    let timestamp = await (0, history_1.fetchHistoryTimestamp)(root.environments[envName], {
         timeoutMs: apiTimeoutMs,
     });
     logger.info("Watcher is online! Changes made to serialized items will be automatically pulled.", "magenta");
     while (true) {
         await new Promise((resolve) => setTimeout(resolve, 2000));
-        const result = await (0, sitecore_api_1.fetchHistoryEntries)(root.environments[envName], timestamp, {
+        const result = await (0, history_1.fetchHistoryEntries)(root.environments[envName], timestamp, {
             timeoutMs: apiTimeoutMs,
         });
         timestamp = result.timestamp;
@@ -52,10 +53,10 @@ const runWatch = async (options) => {
                     templateId: "",
                     path: itemPath,
                 };
-                await (0, filesystem_store_1.removeItemFromFilesystem)(provider, metadata);
+                await (0, items_2.removeItemFromFilesystem)(provider, metadata);
                 if (entry.oldPath) {
                     const oldItemPath = item_path_1.ItemPath.fromPathString(entry.oldPath);
-                    await (0, filesystem_store_1.removeItemFromFilesystem)(provider, {
+                    await (0, items_2.removeItemFromFilesystem)(provider, {
                         id: entry.id,
                         parentId: "",
                         templateId: "",
@@ -65,9 +66,9 @@ const runWatch = async (options) => {
                 continue;
             }
             const filter = (0, field_filter_1.createFieldFilterSet)(root.serialization.excludedFields, []);
-            const data = await (0, sitecore_api_1.fetchItemData)(root.environments[envName], entry.database, entry.id, "SingleItem", filter, { timeoutMs: apiTimeoutMs });
+            const data = await (0, items_1.fetchItemData)(root.environments[envName], entry.database, entry.id, "SingleItem", filter, { timeoutMs: apiTimeoutMs });
             if (data.length > 0) {
-                await (0, filesystem_store_1.writeItemToFilesystem)(provider, data[0]);
+                await (0, items_2.writeItemToFilesystem)(provider, data[0]);
             }
         }
     }

package/dist/serialization/tree-spec.d.ts

@@ -48,4 +48,3 @@ export declare class FilesystemTreeSpec extends TreeSpec {
     validate(): void;
 }
 export declare const parseItemPathMatch: (value: string) => ItemPathMatchLike;
-//# sourceMappingURL=tree-spec.d.ts.map

package/dist/serialization/tree-spec.js

@@ -30,7 +30,7 @@ class TreeSpecRule {
     }
     validateInternal(parent, validateScopes) {
         if (!parent) {
-            throw (0, errors_1.createCliError)("TreeSpecRule parent is required.", "CONFIG_INVALID");
+            throw (0, errors_1.createScaiError)("TreeSpecRule parent is required.", "CONFIG_INVALID");
         }
         if (validateScopes) {
             this.validateScopes(parent);
@@ -43,27 +43,27 @@ class TreeSpecRule {
             this.validateItemPathMatch(parent, this.path);
             return;
         }
-        throw (0, errors_1.createCliError)(`Subtree ${parent.path} has a rule with no path.`, "CONFIG_INVALID");
+        throw (0, errors_1.createScaiError)(`Subtree ${parent.path} has a rule with no path.`, "CONFIG_INVALID");
     }
     validateScopes(parent) {
         if (!this.scope) {
-            throw (0, errors_1.createCliError)(`${parent.path} has rule ${this.path?.toPathString()} without scope.`, "CONFIG_INVALID");
+            throw (0, errors_1.createScaiError)(`${parent.path} has rule ${this.path?.toPathString()} without scope.`, "CONFIG_INVALID");
         }
         if (parent.scope === TreeScope.SingleItem) {
-            throw (0, errors_1.createCliError)(`${parent.path} has scope ${TreeScope.SingleItem} and rules are defined.`, "CONFIG_INVALID");
+            throw (0, errors_1.createScaiError)(`${parent.path} has scope ${TreeScope.SingleItem} and rules are defined.`, "CONFIG_INVALID");
         }
         if (parent.scope === TreeScope.ItemAndChildren &&
             (this.scope === TreeRuleScope.ItemAndDescendants ||
                 this.scope === TreeRuleScope.ItemAndChildren)) {
-            throw (0, errors_1.createCliError)(`${parent.path} has scope ${TreeScope.ItemAndChildren} and rule ${this.path.toPathString()} has scope ${this.scope}.`, "CONFIG_INVALID");
+            throw (0, errors_1.createScaiError)(`${parent.path} has scope ${TreeScope.ItemAndChildren} and rule ${this.path.toPathString()} has scope ${this.scope}.`, "CONFIG_INVALID");
         }
     }
     validateItemPath(parent, itemPath) {
         if (itemPath.isDescendantOrSelfOf(parent.path)) {
-            throw (0, errors_1.createCliError)(`Subtree path ${parent.path} contained rule for ${this.path.toPathString()}, which is absolute.`, "CONFIG_INVALID");
+            throw (0, errors_1.createScaiError)(`Subtree path ${parent.path} contained rule for ${this.path.toPathString()}, which is absolute.`, "CONFIG_INVALID");
         }
         if (itemPath.count === 0) {
-            throw (0, errors_1.createCliError)(`Subtree path ${parent.path} contained rule for /, which is the root item.`, "CONFIG_INVALID");
+            throw (0, errors_1.createScaiError)(`Subtree path ${parent.path} contained rule for /, which is the root item.`, "CONFIG_INVALID");
         }
         const parentRelative = itemPath.createParentPath();
         if (!parentRelative) {
@@ -72,7 +72,7 @@ class TreeSpecRule {
         let currentParentPath = parent.path.concatenate(parentRelative);
         while (!currentParentPath.equals(parent.path) && currentParentPath.count > 0) {
             if (!parent.includesPath(currentParentPath)) {
-                throw (0, errors_1.createCliError)(`Subtree path ${parent.path} contained rule for ${this.path.toPathString()}, but ancestor path ${currentParentPath} was not included.`, "CONFIG_INVALID");
+                throw (0, errors_1.createScaiError)(`Subtree path ${parent.path} contained rule for ${this.path.toPathString()}, but ancestor path ${currentParentPath} was not included.`, "CONFIG_INVALID");
             }
             const nextParent = currentParentPath.createParentPath();
             if (!nextParent) {
@@ -84,10 +84,10 @@ class TreeSpecRule {
     validateItemPathMatch(parent, itemPathMatch) {
         const matchValue = itemPathMatch.toPathString();
         if (!matchValue.endsWith("*")) {
-            throw (0, errors_1.createCliError)(`Subtree ${parent.path} contained path match rule ${matchValue} without trailing '*'.`, "CONFIG_INVALID");
+            throw (0, errors_1.createScaiError)(`Subtree ${parent.path} contained path match rule ${matchValue} without trailing '*'.`, "CONFIG_INVALID");
         }
         if (this.scope === TreeRuleScope.SingleItem || this.scope === TreeRuleScope.ItemAndChildren) {
-            throw (0, errors_1.createCliError)(`Subtree ${parent.path} contained wildcard rule ${matchValue} with invalid scope ${this.scope}.`, "CONFIG_INVALID");
+            throw (0, errors_1.createScaiError)(`Subtree ${parent.path} contained wildcard rule ${matchValue} with invalid scope ${this.scope}.`, "CONFIG_INVALID");
         }
     }
 }
@@ -95,7 +95,7 @@ exports.TreeSpecRule = TreeSpecRule;
 class FilesystemTreeSpecRule extends TreeSpecRule {
     validate(parent) {
         if (!parent) {
-            throw (0, errors_1.createCliError)("FilesystemTreeSpecRule parent is required.", "CONFIG_INVALID");
+            throw (0, errors_1.createScaiError)("FilesystemTreeSpecRule parent is required.", "CONFIG_INVALID");
         }
         if (!this.alias) {
             super.validate(parent);
@@ -103,13 +103,13 @@ class FilesystemTreeSpecRule extends TreeSpecRule {
         }
         this.validateInternal(parent, false);
         if (this.scope) {
-            throw (0, errors_1.createCliError)(`Subtree ${parent.path} contained rule for ${this.path.toPathString()} with alias and scope.`, "CONFIG_INVALID");
+            throw (0, errors_1.createScaiError)(`Subtree ${parent.path} contained rule for ${this.path.toPathString()} with alias and scope.`, "CONFIG_INVALID");
         }
         if (this.path instanceof item_path_1.ItemPathMatch) {
-            throw (0, errors_1.createCliError)(`Subtree ${parent.path} contained match rule ${this.path.toPathString()} that also had an alias.`, "CONFIG_INVALID");
+            throw (0, errors_1.createScaiError)(`Subtree ${parent.path} contained match rule ${this.path.toPathString()} that also had an alias.`, "CONFIG_INVALID");
         }
         if (!/^[A-Za-z0-9 \-_]+$/.test(this.alias)) {
-            throw (0, errors_1.createCliError)(`Subtree ${parent.path} rule for ${this.path.toPathString()} has invalid alias '${this.alias}'.`, "CONFIG_INVALID");
+            throw (0, errors_1.createScaiError)(`Subtree ${parent.path} rule for ${this.path.toPathString()} has invalid alias '${this.alias}'.`, "CONFIG_INVALID");
         }
     }
 }
@@ -122,11 +122,11 @@ class TreeSpec {
     }
     validate() {
         if (!this.path || this.path.count === 0) {
-            throw (0, errors_1.createCliError)("TreeSpec path is null or empty.", "CONFIG_INVALID");
+            throw (0, errors_1.createScaiError)("TreeSpec path is null or empty.", "CONFIG_INVALID");
         }
         for (const rule of this.rules) {
             if (!rule.path) {
-                throw (0, errors_1.createCliError)("TreeSpec rule path is null or empty.", "CONFIG_INVALID");
+                throw (0, errors_1.createScaiError)("TreeSpec rule path is null or empty.", "CONFIG_INVALID");
             }
             rule.validate(this);
         }
@@ -160,7 +160,7 @@ class TreeSpec {
                 case TreeRuleScope.SingleItem:
                 case TreeRuleScope.ItemAndChildren: {
                     if (!(rule.path instanceof item_path_1.ItemPath)) {
-                        throw (0, errors_1.createCliError)("Cannot determine relative path to wildcard.", "CONFIG_INVALID");
+                        throw (0, errors_1.createScaiError)("Cannot determine relative path to wildcard.", "CONFIG_INVALID");
                     }
                     const ruleRelativePath = relativePath.createRelativePathFrom(rule.path);
                     if (!ruleRelativePath) {
@@ -211,13 +211,13 @@ class FilesystemTreeSpec extends TreeSpec {
     validate() {
         super.validate();
         if (!this.name) {
-            throw (0, errors_1.createCliError)(`Subtree name was null or empty for path ${this.path}.`, "CONFIG_INVALID");
+            throw (0, errors_1.createScaiError)(`Subtree name was null or empty for path ${this.path}.`, "CONFIG_INVALID");
         }
         if (!this.database) {
-            throw (0, errors_1.createCliError)(`Subtree ${this.name} database was null or empty.`, "CONFIG_INVALID");
+            throw (0, errors_1.createScaiError)(`Subtree ${this.name} database was null or empty.`, "CONFIG_INVALID");
         }
         if (!this.physicalPath) {
-            throw (0, errors_1.createCliError)(`Subtree ${this.name} physicalPath was null or empty.`, "CONFIG_INVALID");
+            throw (0, errors_1.createScaiError)(`Subtree ${this.name} physicalPath was null or empty.`, "CONFIG_INVALID");
         }
         const aliasSet = new Set();
         for (const rule of this.rules) {
@@ -225,7 +225,7 @@ class FilesystemTreeSpec extends TreeSpec {
                 continue;
             }
             if (aliasSet.has(rule.alias.toLowerCase())) {
-                throw (0, errors_1.createCliError)(`Duplicate path alias '${rule.alias}' in subtree ${this.name}.`, "CONFIG_INVALID");
+                throw (0, errors_1.createScaiError)(`Duplicate path alias '${rule.alias}' in subtree ${this.name}.`, "CONFIG_INVALID");
             }
             aliasSet.add(rule.alias.toLowerCase());
         }

package/dist/serialization/types.d.ts

@@ -72,4 +72,3 @@ export type HistoryEntry = {
     oldPath?: string | null;
     changeType: "Create" | "UpdateOrRename" | "Move" | "Recycle";
 };
-//# sourceMappingURL=types.d.ts.map

package/dist/serialization/wildcard.d.ts

@@ -1,3 +1,2 @@
 export declare const isWildcard: (candidate: string) => boolean;
 export declare const isWildcardMatch: (input: string, wildcards: string, caseSensitive?: boolean) => boolean;
-//# sourceMappingURL=wildcard.d.ts.map

package/dist/serialization/wildcard.js

@@ -4,14 +4,14 @@ exports.isWildcardMatch = exports.isWildcard = void 0;
 const errors_1 = require("../shared/errors");
 const isWildcard = (candidate) => {
     if (candidate == null) {
-        throw (0, errors_1.createCliError)("Wildcard candidate is null or undefined.", "INPUT_INVALID");
+        throw (0, errors_1.createScaiError)("Wildcard candidate is null or undefined.", "INPUT_INVALID");
     }
     return candidate.includes("*") || candidate.includes("?");
 };
 exports.isWildcard = isWildcard;
 const isWildcardMatch = (input, wildcards, caseSensitive = false) => {
     if (input == null) {
-        throw (0, errors_1.createCliError)("Input is null or undefined.", "INPUT_INVALID");
+        throw (0, errors_1.createScaiError)("Input is null or undefined.", "INPUT_INVALID");
     }
     if ((0, exports.isWildcard)(wildcards)) {
         const escaped = wildcards.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");

package/dist/serialization/yaml.d.ts

@@ -6,4 +6,3 @@ export declare const writeRoleYaml: (role: RoleData) => string;
 export declare const readRoleYamlFromString: (content: string, serializedItemId?: string) => RoleData;
 export declare const readUserYamlFromString: (content: string, serializedItemId?: string) => UserData;
 export declare const writeUserYaml: (user: UserData) => string;
-//# sourceMappingURL=yaml.d.ts.map

package/dist/serialization/yaml.js

@@ -49,7 +49,7 @@ class YamlWriter {
     }
     writeBeginListItem(key, value) {
         if (this.indent < YamlWriter.indentSpaces) {
-            throw (0, errors_1.createCliError)("Indent is at minimum. You must indent to support a list.", "UNKNOWN");
+            throw (0, errors_1.createScaiError)("Indent is at minimum. You must indent to support a list.", "UNKNOWN");
         }
         const prefix = " ".repeat(this.indent - YamlWriter.indentSpaces);
         this.chunks.push(`${prefix}- ${key}: ${value}\n`);

package/dist/shared/browser.d.ts

@@ -1,2 +1 @@
 export declare const openBrowser: (url: string) => boolean;
-//# sourceMappingURL=browser.d.ts.map

package/dist/shared/cli-options.d.ts

@@ -14,4 +14,3 @@ export type CommonOptions = {
     quiet?: boolean;
     logFile?: string;
 };
-//# sourceMappingURL=cli-options.d.ts.map

package/dist/shared/cli-tasks.d.ts

@@ -3,7 +3,7 @@
  * deploy-specific belongs in `src/deploy/tasks/shared.ts`; anything
  * serialization-specific belongs in `src/serialization/tasks/shared.ts`.
  */
-import type { RootConfiguration } from "../config";
+import type { RootConfiguration } from "../config/types";
 import { Logger } from "../shared/logger";
 import type { CommonOptions } from "./cli-options";
 export declare const toLogger: (options: CommonOptions) => Logger;
@@ -35,4 +35,3 @@ export declare const resolveApiTimeoutMs: (root: RootConfiguration) => number |
  * API. Pass a lower limit when each task hits the same upstream.
  */
 export declare const mapWithConcurrency: <T, R>(items: readonly T[], fn: (item: T, index: number) => Promise<R>, concurrency?: number) => Promise<R[]>;
-//# sourceMappingURL=cli-tasks.d.ts.map

package/dist/shared/cli-tasks.js

@@ -20,14 +20,14 @@ const applyIfDefined = (target, key, value) => {
     }
 };
 exports.applyIfDefined = applyIfDefined;
-const inputError = (message, hint) => (0, errors_1.createCliError)(message, "INPUT_INVALID", hint ? { hint } : {});
+const inputError = (message, hint) => (0, errors_1.createScaiError)(message, "INPUT_INVALID", hint ? { hint } : {});
 exports.inputError = inputError;
 const confirmDestructive = async (message, force) => {
     if (force) {
         return true;
     }
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
-        throw (0, errors_1.createCliError)("Confirmation required for destructive action.", "INPUT_INVALID", {
+        throw (0, errors_1.createScaiError)("Confirmation required for destructive action.", "INPUT_INVALID", {
             hint: "Re-run with --force to skip the confirmation prompt.",
         });
     }

package/dist/shared/client-credential.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Automation-client secret resolution — the single place every API
+ * auth path resolves a `clientId` + `clientSecret` pair from.
+ *
+ * Per `docs/credentials.md` the config file holds every credential's
+ * **non-secret metadata** (`clientId`, `name`, `mintedAt`); the OS
+ * keychain holds **only secrets**. So a `clientId` always comes from the
+ * config and the matching `clientSecret` from the keychain. Resolution
+ * walks three tiers:
+ *
+ *   1. `SITECOREAI_ENV_<ENV>_CLIENT_SECRET` (or the global
+ *      `SITECOREAI_CLIENT_SECRET`) environment variable — the
+ *      bring-your-own-client escape hatch. Paired with a `clientId` from
+ *      the env profile (or `SITECOREAI_ENV_<ENV>_CLIENT_ID`).
+ *   2. The scai-minted env-scoped automation client: `clientId` from the
+ *      env profile's `automationClient` block, secret from the OS
+ *      keychain (`cm-client:<env>`).
+ *   3. The scai-minted org-scoped automation client: `clientId` from the
+ *      root config's `orgClients[orgId]` block, secret from the OS
+ *      keychain (`org-client:<orgId>`). The fallback for org-level
+ *      profiles with no project/environment of their own.
+ *
+ * Lives in `shared/` (a leaf module): it depends only on the keychain
+ * wrapper and `process.env`, never on `config/`. Callers pass the
+ * non-secret `clientId`s — already read from the resolved config — in.
+ */
+/**
+ * Tier 1 of secret resolution: the `SITECOREAI_ENV_<ENV>_CLIENT_SECRET`
+ * environment variable, falling back to the global
+ * `SITECOREAI_CLIENT_SECRET`. This is the bring-your-own-client escape
+ * hatch — the operator supplies their own automation client and feeds
+ * its secret in via the environment, never the config file.
+ *
+ * Returns `undefined` when neither variable is set.
+ */
+export declare const resolveEnvClientSecret: (envName: string) => string | undefined;
+/** A resolved automation-client credential pair. */
+export interface ResolvedClientCredential {
+    clientId: string;
+    clientSecret: string;
+    /** Which tier supplied the credential — useful for diagnostics. */
+    source: "env-var" | "cm-client" | "org-client";
+}
+export interface ResolveClientCredentialOptions {
+    /**
+     * Env-profile name — keys tier 1's `SITECOREAI_ENV_<ENV>_*` env vars
+     * and tier 2's `cm-client:<env>` keychain slot. Optional: an org-scoped
+     * caller (brief, campaign) may have no env profile, in which case
+     * tiers 1 and 2 are skipped and only tier 3 (the org-scoped client)
+     * can resolve.
+     */
+    envName?: string;
+    /**
+     * `clientId` from the env profile (the bring-your-own-client escape
+     * hatch). Pairs with the tier-1 env-var secret when set.
+     */
+    clientId?: string;
+    /**
+     * `clientId` of the scai-minted env-scoped automation client — read
+     * from the env profile's `automationClient` block. Pairs with the
+     * tier-2 `cm-client:<env>` keychain secret.
+     */
+    automationClientId?: string;
+    /** Organization id — keys the tier-3 `org-client:<orgId>` slot. */
+    organizationId?: string;
+    /**
+     * `clientId` of the scai-minted org-scoped automation client — read
+     * from the root config's `orgClients[orgId]` block. Pairs with the
+     * tier-3 `org-client:<orgId>` keychain secret.
+     */
+    orgClientId?: string;
+}
+/**
+ * Resolve a full `{ clientId, clientSecret }` automation-client pair via
+ * the three-tier chain (env var → env-scoped keychain client → org-scoped
+ * keychain client). `clientId` and `clientSecret` are always taken as a
+ * matched pair from whichever tier supplies the secret.
+ *
+ * Returns `undefined` when no tier yields a usable pair — the caller
+ * decides how to surface the missing credential.
+ */
+export declare const resolveClientCredential: (options: ResolveClientCredentialOptions) => Promise<ResolvedClientCredential | undefined>;

package/dist/shared/client-credential.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * Automation-client secret resolution — the single place every API
+ * auth path resolves a `clientId` + `clientSecret` pair from.
+ *
+ * Per `docs/credentials.md` the config file holds every credential's
+ * **non-secret metadata** (`clientId`, `name`, `mintedAt`); the OS
+ * keychain holds **only secrets**. So a `clientId` always comes from the
+ * config and the matching `clientSecret` from the keychain. Resolution
+ * walks three tiers:
+ *
+ *   1. `SITECOREAI_ENV_<ENV>_CLIENT_SECRET` (or the global
+ *      `SITECOREAI_CLIENT_SECRET`) environment variable — the
+ *      bring-your-own-client escape hatch. Paired with a `clientId` from
+ *      the env profile (or `SITECOREAI_ENV_<ENV>_CLIENT_ID`).
+ *   2. The scai-minted env-scoped automation client: `clientId` from the
+ *      env profile's `automationClient` block, secret from the OS
+ *      keychain (`cm-client:<env>`).
+ *   3. The scai-minted org-scoped automation client: `clientId` from the
+ *      root config's `orgClients[orgId]` block, secret from the OS
+ *      keychain (`org-client:<orgId>`). The fallback for org-level
+ *      profiles with no project/environment of their own.
+ *
+ * Lives in `shared/` (a leaf module): it depends only on the keychain
+ * wrapper and `process.env`, never on `config/`. Callers pass the
+ * non-secret `clientId`s — already read from the resolved config — in.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveClientCredential = exports.resolveEnvClientSecret = void 0;
+const keychain_1 = require("./keychain");
+/**
+ * Normalize an env-profile name into the `SITECOREAI_ENV_<ENV>_*` key
+ * segment — uppercased, non-alphanumerics collapsed to `_`. Mirrors the
+ * normalization `config/env-overrides.ts` applies; kept local so this
+ * leaf module has no `config/` dependency.
+ */
+const normalizeEnvKey = (name) => name
+    .trim()
+    .toUpperCase()
+    .replace(/[^A-Z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+const readEnvVar = (key) => {
+    const value = process.env[key];
+    if (value && value.trim().length > 0) {
+        return value.trim();
+    }
+    return undefined;
+};
+/**
+ * Tier 1 of secret resolution: the `SITECOREAI_ENV_<ENV>_CLIENT_SECRET`
+ * environment variable, falling back to the global
+ * `SITECOREAI_CLIENT_SECRET`. This is the bring-your-own-client escape
+ * hatch — the operator supplies their own automation client and feeds
+ * its secret in via the environment, never the config file.
+ *
+ * Returns `undefined` when neither variable is set.
+ */
+const resolveEnvClientSecret = (envName) => readEnvVar(`SITECOREAI_ENV_${normalizeEnvKey(envName)}_CLIENT_SECRET`) ??
+    readEnvVar("SITECOREAI_CLIENT_SECRET");
+exports.resolveEnvClientSecret = resolveEnvClientSecret;
+/**
+ * Tier 1's matching `clientId`: the `SITECOREAI_ENV_<ENV>_CLIENT_ID`
+ * environment variable, falling back to the global `SITECOREAI_CLIENT_ID`.
+ * Used only when the env profile itself carries no `clientId`.
+ */
+const resolveEnvClientId = (envName) => readEnvVar(`SITECOREAI_ENV_${normalizeEnvKey(envName)}_CLIENT_ID`) ??
+    readEnvVar("SITECOREAI_CLIENT_ID");
+/**
+ * Resolve a full `{ clientId, clientSecret }` automation-client pair via
+ * the three-tier chain (env var → env-scoped keychain client → org-scoped
+ * keychain client). `clientId` and `clientSecret` are always taken as a
+ * matched pair from whichever tier supplies the secret.
+ *
+ * Returns `undefined` when no tier yields a usable pair — the caller
+ * decides how to surface the missing credential.
+ */
+const resolveClientCredential = async (options) => {
+    // Tier 1: bring-your-own-client — secret from the environment, id from
+    // the env profile or the matching `SITECOREAI_*_CLIENT_ID` env var.
+    // Skipped entirely when there is no env profile to key the env vars by.
+    const envSecret = options.envName ? (0, exports.resolveEnvClientSecret)(options.envName) : undefined;
+    if (envSecret && options.envName) {
+        const clientId = options.clientId ?? resolveEnvClientId(options.envName);
+        if (clientId) {
+            return { clientId, clientSecret: envSecret, source: "env-var" };
+        }
+    }
+    // Tier 2: env-scoped automation client minted by `scai setup client
+    // create`. The `clientId` comes from the env profile's
+    // `automationClient` block; the secret from the keychain.
+    if (options.automationClientId && options.envName) {
+        const cmSecret = await (0, keychain_1.getCmClientSecret)(options.envName);
+        if (cmSecret) {
+            return {
+                clientId: options.automationClientId,
+                clientSecret: cmSecret,
+                source: "cm-client",
+            };
+        }
+    }
+    // Tier 3: org-scoped automation client — the fallback for org-level
+    // profiles with no project/environment of their own. The `clientId`
+    // comes from the root config's `orgClients[orgId]` block; the secret
+    // from the keychain.
+    if (options.organizationId && options.orgClientId) {
+        const orgSecret = await (0, keychain_1.getOrgClientSecret)(options.organizationId);
+        if (orgSecret) {
+            return {
+                clientId: options.orgClientId,
+                clientSecret: orgSecret,
+                source: "org-client",
+            };
+        }
+    }
+    return undefined;
+};
+exports.resolveClientCredential = resolveClientCredential;

package/dist/shared/concurrency.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Bounded-concurrency async iteration helper. Used to parallelize
+ * I/O-bound network calls (e.g. `fetchItemData` for each item in a
+ * serialization pull) without blasting unbounded request fans out at
+ * Sitecore — which would hit rate limits, exhaust local sockets, or
+ * blow up memory holding too many in-flight Response bodies.
+ *
+ * Results preserve input order. The first failure aborts: pending
+ * tasks are not started, in-flight tasks are awaited then their
+ * results discarded.
+ *
+ * Default concurrency is 8 (conservative for typical XM Cloud rate
+ * limits). Override via `SITECOREAI_HTTP_CONCURRENCY`.
+ */
+export declare const DEFAULT_CONCURRENCY = 8;
+export declare const resolveDefaultConcurrency: () => number;
+export interface MapWithConcurrencyOptions {
+    concurrency?: number;
+}
+export declare const mapWithConcurrency: <T, R>(items: readonly T[], worker: (item: T, index: number) => Promise<R>, options?: MapWithConcurrencyOptions) => Promise<R[]>;