@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/config/types.d.ts

@@ -33,40 +33,141 @@ export type EnvironmentRecipeRoots = {
     contentModels?: string;
     partialDesigns?: string;
     pageDesigns?: string;
+    pageTemplates?: string;
+    pages?: string;
     contentItems?: string;
     headlessVariants?: string;
     availableRenderings?: string;
     enumerations?: string;
+    /** Walk roots for resolving `placedIn` against pre-existing placeholders. */
     placeholderSettings?: string[];
+    /** Create root for recipe-defined Placeholder Settings items. */
+    placeholderSettingsCreate?: string;
 };
+/**
+ * Non-secret metadata for a scai-minted automation client. Per
+ * `docs/credentials.md` the config file is a readable inventory of every
+ * configured credential: it carries the client's `clientId`, display
+ * `name`, and `mintedAt` timestamp. Only the client **secret** lives in
+ * the OS keychain — never here. Used both for the env-scoped client (the
+ * `automationClient` block on an env profile) and the org-scoped client
+ * (an `orgClients[orgId]` entry).
+ */
+export type AutomationClientMetadata = {
+    /** OAuth client id of the scai-minted automation client. */
+    clientId: string;
+    /** Display name of the client in the Cloud Portal (the `scai-*` name). */
+    name?: string;
+    /** ISO timestamp the client was minted. */
+    mintedAt?: string;
+};
+/**
+ * A named environment profile.
+ *
+ * Per `docs/credentials.md` an env profile carries **environment
+ * identity only** — `organizationId` / `projectId` / `environmentId` /
+ * `host` / `authority` / `audience` / `environmentType` — plus the
+ * **non-secret metadata** of the credentials configured for it. It does
+ * **not** carry credential secrets: the automation client is minted by
+ * `scai setup client create` and only its secret is stored in the OS
+ * keychain; its non-secret parts (`clientId` / `name` / `mintedAt`) live
+ * in the `automationClient` block here. The brand key is registered into
+ * the separate `brand[orgId]` block.
+ *
+ * `clientId` + `useClientCredentials` remain **only** as the documented
+ * bring-your-own-client escape hatch (the operator supplies their own
+ * automation client; its secret comes from
+ * `SITECOREAI_ENV_<ENV>_CLIENT_SECRET`, resolved at the auth layer and
+ * never stored here). `accessToken` / `refreshToken` / `deployToken` are
+ * token-cache metadata, not credentials — the CLI writes tokens to the
+ * keychain and only reads these legacy fields for back-compat with
+ * configs written by earlier versions. `deployTokenExpiresIn` /
+ * `deployTokenLastUpdated` record the cached deploy token's freshness so
+ * the auto-wizard can decide whether a re-login is due.
+ */
 export type EnvironmentConfiguration = {
     name?: string;
     host?: string;
     authority?: string;
     environmentType?: "cm" | "eh";
     allowWrite?: boolean;
+    /**
+     * When `true`, MCP write tools refuse to operate against this
+     * environment even when the host has cleared their own
+     * write-confirmation UX. Use for production-shaped environments
+     * where every destructive op must originate from a human-driven CLI
+     * call (`--allow-write`) and never from an MCP-elevated context. The
+     * gate fires at the MCP tool boundary — direct CLI use is
+     * unaffected.
+     *
+     * Defaults to `false` (MCP elevation allowed).
+     */
+    denyMcpElevation?: boolean;
+    /** @deprecated Token-cache metadata. Tokens live in the OS keychain; read for back-compat only. */
     accessToken?: string;
+    /** @deprecated Token-cache metadata. Tokens live in the OS keychain; read for back-compat only. */
     refreshToken?: string;
+    /** @deprecated Token-cache metadata. Tokens live in the OS keychain; read for back-compat only. */
     refreshTokenParameters?: Record<string, string>;
+    /** @deprecated Token-cache metadata. Tokens live in the OS keychain; read for back-compat only. */
     expiresIn?: number | null;
+    /** @deprecated Token-cache metadata. Tokens live in the OS keychain; read for back-compat only. */
     lastUpdated?: string | null;
+    /** @deprecated Token-cache metadata. The deploy token lives in the OS keychain; read for back-compat only. */
     deployToken?: string;
+    /**
+     * `expires_in` (seconds) of the cached deploy token. Freshness
+     * metadata — not a credential — recorded so the auto-wizard's expiry
+     * check can decide whether a re-login is due. Paired with
+     * `deployTokenLastUpdated`. The token string itself lives in the OS
+     * keychain (`deploy:<env>` slot).
+     */
     deployTokenExpiresIn?: number | null;
+    /**
+     * ISO timestamp of the last deploy-token mint. Paired with
+     * `deployTokenExpiresIn`; see that field.
+     */
     deployTokenLastUpdated?: string | null;
     editingHostEnvironmentIds?: string[];
     organizationId?: string;
     tenantId?: string;
     projectId?: string;
     environmentId?: string;
+    /**
+     * Bring-your-own-client escape hatch: the OAuth client id of an
+     * automation client the operator supplies themselves, instead of
+     * letting `scai setup client create` mint one. Pair with
+     * `useClientCredentials: true`; the matching secret comes from the
+     * `SITECOREAI_ENV_<ENV>_CLIENT_SECRET` environment variable, resolved
+     * at the auth layer — it is never stored on the env profile.
+     */
     clientId?: string;
-    clientSecret?: string;
+    /**
+     * Bring-your-own-client escape hatch toggle: when `true`, scai uses
+     * the operator-supplied `clientId` + `SITECOREAI_ENV_<ENV>_CLIENT_SECRET`
+     * client-credentials grant instead of an interactive device login.
+     */
     useClientCredentials?: boolean;
+    /**
+     * Non-secret metadata of the **env-scoped** automation client scai
+     * minted for this environment via `scai setup client create <env>`.
+     * Per `docs/credentials.md` the config file is the readable inventory
+     * of configured credentials: this records the minted client's
+     * `clientId`, `name`, and `mintedAt`. The matching **secret** lives in
+     * the OS keychain (`cm-client:<env>` slot) — never here.
+     *
+     * Distinct from the bring-your-own-client `clientId` /
+     * `useClientCredentials` pair above: that hatch is for an operator-
+     * supplied client; `automationClient` is for the one scai itself
+     * mints.
+     */
+    automationClient?: AutomationClientMetadata;
     variables?: Record<string, string>;
     audience?: string;
     ref?: string;
     cacheAuthenticationToken?: boolean;
     /**
-     * Sitecore parent path under which `scai recipe compile|push` creates
+     * Sitecore parent path under which `scai provision recipe compile|push` creates
      * template items. Tenant-specific because each site has its own
      * `/sitecore/templates/Project/<site>/Components` location.
      *
@@ -74,14 +175,14 @@ export type EnvironmentConfiguration = {
      */
     templatesRoot?: string;
     /**
-     * Sitecore parent path under which `scai recipe compile|push` creates
+     * Sitecore parent path under which `scai provision recipe compile|push` creates
      * rendering items. Tenant-specific.
      *
      * Used as fallback when the CLI flag `--renderings-root` is not passed.
      */
     renderingsRoot?: string;
     /**
-     * Sitecore parent path under which `scai recipe compile|push` creates
+     * Sitecore parent path under which `scai provision recipe compile|push` creates
      * component template items in the per-site folder layout
      * (`<componentsRoot>/<section>/<Component>`). When unset, the compiler
      * falls back to `templatesRoot` and emits the legacy flat layout.
@@ -93,7 +194,7 @@ export type EnvironmentConfiguration = {
      */
     componentsRoot?: string;
     /**
-     * Sitecore parent path under which `scai recipe compile|push` creates
+     * Sitecore parent path under which `scai provision recipe compile|push` creates
      * content-template items
      * (`<contentModelsRoot>/<group>/<name>` when grouped, flat otherwise).
      * When unset, content templates fall back to `templatesRoot` — which
@@ -103,7 +204,7 @@ export type EnvironmentConfiguration = {
      */
     contentModelsRoot?: string;
     /**
-     * Sitecore parent path under which `scai recipe compile|push` creates
+     * Sitecore parent path under which `scai provision recipe compile|push` creates
      * partial-design items (Phase 4). Typically
      * `/sitecore/content/<site>/Presentation/Partial Designs`.
      *
@@ -111,7 +212,7 @@ export type EnvironmentConfiguration = {
      */
     partialDesignsRoot?: string;
     /**
-     * Sitecore parent path under which `scai recipe compile|push` creates
+     * Sitecore parent path under which `scai provision recipe compile|push` creates
      * page-design items (Phase 4). Typically
      * `/sitecore/content/<site>/Presentation/Page Designs`.
      *
@@ -121,7 +222,7 @@ export type EnvironmentConfiguration = {
      */
     pageDesignsRoot?: string;
     /**
-     * Sitecore parent path under which `scai recipe compile|push` creates
+     * Sitecore parent path under which `scai provision recipe compile|push` creates
      * shared content items (Phase 4). Typically
      * `/sitecore/content/<site>/Data` or a sub-bucket.
      *
@@ -129,7 +230,7 @@ export type EnvironmentConfiguration = {
      */
     contentItemsRoot?: string;
     /**
-     * Sitecore parent path under which `scai recipe compile|push` creates
+     * Sitecore parent path under which `scai provision recipe compile|push` creates
      * SXA Headless rendering variants. Typically
      * `/sitecore/content/<siteCollection>/<site>/Presentation/Headless Variants`.
      *
@@ -146,7 +247,7 @@ export type EnvironmentConfiguration = {
      */
     headlessVariantsRoot?: string;
     /**
-     * Sitecore parent path under which `scai recipe compile|push` creates
+     * Sitecore parent path under which `scai provision recipe compile|push` creates
      * SXA `Available Renderings` section items. Typically
      * `/sitecore/content/<siteCollection>/<site>/Presentation/Available Renderings`.
      *
@@ -185,24 +286,118 @@ export type EnvironmentConfiguration = {
      */
     placeholderSettingsRoots?: string[];
     /**
-     * Preferred nested form of the 11 `*Root` fields above. When set,
+     * Sitecore parent path under which `scai provision recipe compile|push`
+     * CREATES recipe-defined Placeholder Settings items — one per unique
+     * placeholder key from a `PlaceholderRecipe` or an inline
+     * `ComponentTemplateRecipe.placeholders` slot. Typically
+     * `/sitecore/content/<site>/Presentation/Placeholder Settings`.
+     *
+     * Distinct from `placeholderSettingsRoots` (plural) above: that list
+     * is WALKED at apply time to find PRE-EXISTING tenant placeholders for
+     * `placedIn` allow-control patching; this single path is where the
+     * compiler MATERIALISES recipe-owned placeholders. Operators usually
+     * set this to a path inside one of the walk roots.
+     *
+     * Required when the recipe set declares any placeholder; the compiler
+     * throws INPUT_INVALID with a hint when needed but missing.
+     */
+    placeholderSettingsRoot?: string;
+    /**
+     * Sitecore parent path under which `scai provision recipe compile|push`
+     * creates `PageTemplateRecipe` items — typically
+     * `/sitecore/templates/Project/<site>`. Optional; falls back to
+     * `templatesRoot` when unset.
+     */
+    pageTemplatesRoot?: string;
+    /**
+     * Sitecore content-tree root under which `scai provision recipe
+     * compile|push` creates `PageRecipe` items — typically
+     * `/sitecore/content/<tenant>/<site>/Home`. Optional; only
+     * `PageRecipe` compilation requires it.
+     */
+    pagesRoot?: string;
+    /**
+     * Preferred nested form of the `*Root` fields above. When set,
      * `readRootConfiguration` flattens entries into the matching flat
      * fields before internal consumers read them. New configs should
      * use this shape — it scales as new recipe-tree roots get added
      * without bloating each env profile.
      */
     recipeRoots?: EnvironmentRecipeRoots;
+    /**
+     * Production-tier marker. Read by `scai content publish` to decide between
+     * the simple `[y/N]` confirmation path and the two-step typed-scope-
+     * token flow. Auto-flags `true` when the env name matches `/prod/i`
+     * or `/^live/i`; set explicitly to `false` to override the heuristic
+     * (e.g. an env named `prod-test` that isn't really production).
+     */
+    production?: boolean;
+    /**
+     * Permits `scai content publish all` (whole-tenant republish) from CI on
+     * this env. Default is human-only. Only honored when `production`
+     * is true; otherwise has no effect.
+     */
+    allowFullRepublish?: boolean;
+    /**
+     * CI pipeline identifiers allowed to run `scai content publish` against
+     * this env. The CLI/library compares the runtime principal's
+     * pipeline ID against this list; an empty/unset list means
+     * human-only.
+     */
+    allowedCiPipelines?: string[];
+};
+/**
+ * Brand credential record, keyed by Sitecore organization ID — the
+ * credential `scai brand` (Brand Management, Review, Documents,
+ * Pipeline) authenticates with.
+ *
+ * Backed by a Sitecore "AI APIs key" created in Cloud Portal → Stream
+ * → Admin → AI APIs keys: bound to a single org (confirmed
+ * one-org-per-credential), carrying its own scope set (`ai.org.brd:r/w`,
+ * `ai.org.docs:r/w`, `ai.orgs.br:gen`). It is one of scai's two
+ * credential kinds — distinct from the automation client (the deploy /
+ * cm clients minted by `scai setup client create`); the automation
+ * client cannot do brand work and vice versa. **Not minted by scai** —
+ * the operator creates the AI APIs key in Cloud Portal and registers it
+ * with `scai setup client register-brand`. The `clientSecret` is never
+ * stored on disk — it lives only in the OS keychain. Token cache
+ * timings here are advisory; the cached access token is also in the
+ * keychain.
+ */
+export type BrandCredential = {
+    clientId: string;
+    audience?: string;
+    authority?: string;
+    tokenExpiresIn?: number | null;
+    tokenLastUpdated?: string | null;
 };
 export type RootConfiguration = {
     modules: string[];
     serialization: SerializationRootConfiguration;
     settings: Settings;
     environments: Record<string, EnvironmentConfiguration>;
+    /** Brand credentials, keyed by Sitecore `organizationId`. */
+    brand: Record<string, BrandCredential>;
+    /**
+     * Non-secret metadata of the scai-minted **org-scoped** automation
+     * clients, keyed by Sitecore `organizationId`. One per org, shared by
+     * every env profile in it. The matching secret lives in the OS
+     * keychain (`org-client:<orgId>` slot) — never here.
+     */
+    orgClients: Record<string, AutomationClientMetadata>;
     physicalPath: string;
+    /**
+     * Active environment name: the configured `defaultEnvProfile`, or the
+     * literal `"default"` when none is set. Use `defaultEnvProfile` (raw,
+     * `undefined` when unset) to tell a real default apart from the
+     * fallback — the `"default"` placeholder is not a real env profile.
+     */
     defaultEnvironment: string;
+    /** The raw `defaultEnvProfile` from the config file; `undefined` when unset. */
+    defaultEnvProfile?: string;
     /**
      * Globs (relative to the project root) that locate `.recipe.ts` /
-     * `.recipe.json` files for `scai recipe compile|plan|push`. When the
+     * `.recipe.json` files for `scai provision recipe compile|plan|push`. When the
      * commands run without `--input`, they fall back to this glob set.
      * Defaults to `["recipes/**\/*.recipe.ts"]` if unset.
      */
@@ -215,6 +410,27 @@ export type RootConfigurationFile = {
     settings?: Partial<Settings>;
     envProfiles?: Record<string, EnvironmentConfiguration>;
     defaultEnvProfile?: string;
+    /**
+     * Brand credentials, keyed by Sitecore `organizationId`. Stored
+     * separately from `envProfiles` because the AI APIs key is org-scoped,
+     * not env-scoped — multiple env profiles in the same org share one
+     * credential.
+     */
+    brand?: Record<string, BrandCredential>;
+    /**
+     * @deprecated Legacy name for `brand` (the block was called `aiSkills`
+     * before the rename). Read for back-compat with configs written by
+     * older CLI versions; the CLI always writes `brand` going forward.
+     */
+    aiSkills?: Record<string, BrandCredential>;
+    /**
+     * Non-secret metadata of the scai-minted **org-scoped** automation
+     * clients, keyed by Sitecore `organizationId`. Stored separately from
+     * `envProfiles` because the org client is org-scoped, not env-scoped —
+     * every env profile in the same org shares one. The matching secret
+     * lives in the OS keychain (`org-client:<orgId>` slot), never here.
+     */
+    orgClients?: Record<string, AutomationClientMetadata>;
     /** Globs locating recipe files. See `RootConfiguration.recipes`. */
     recipes?: string[];
     [key: string]: unknown;
@@ -242,4 +458,3 @@ export declare const DEFAULT_SERIALIZATION: SerializationRootConfiguration;
 export declare const DEFAULT_SETTINGS: Settings;
 export declare const DEFAULT_ENVIRONMENT = "default";
 export declare const DEFAULT_RECIPES_GLOBS: string[];
-//# sourceMappingURL=types.d.ts.map

package/dist/config/types.js

@@ -10,7 +10,7 @@ exports.DEFAULT_SERIALIZATION = {
     excludedFields: [],
 };
 exports.DEFAULT_SETTINGS = {
-    telemetryEnabled: false,
+    telemetryEnabled: true,
     cacheAuthenticationToken: true,
     versionComparisonEnabled: true,
     apiClientTimeoutInMinutes: 5,

package/dist/config/validation.d.ts

@@ -1,10 +1,7 @@
 import type { ErrorObject } from "ajv";
-export declare const validateRootConfig: import("ajv-draft-04").ValidateFunction<{
-    [x: string]: {};
-}>;
+export declare const validateRootConfig: import("ajv-draft-04").ValidateFunction<unknown>;
 export declare const validateModuleConfig: import("ajv-draft-04").ValidateFunction<{
     [x: string]: {};
 }>;
 export declare const formatValidationErrors: (errors: ErrorObject[]) => string[];
 export declare const readJsonFile: <T>(filePath: string) => T;
-//# sourceMappingURL=validation.d.ts.map

package/dist/content/api/version-fields.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Version-level field read/write helpers for the Authoring GraphQL
+ * surface.
+ *
+ * Used by `scai content version *` and `scai content publish unpublish` to
+ * read/write the three publish-state fields Sitecore exposes per
+ * version:
+ *
+ *   - `__Never publish` (boolean — stored as "1" / "")
+ *   - `__Valid from`    (datetime — ISO 8601 string)
+ *   - `__Valid to`      (datetime — ISO 8601 string)
+ *
+ * Distinct from `src/recipe/api/authoring-client.ts:updateItem` for
+ * two reasons:
+ *
+ *   1. Recipe pushes write **item-level** fields (no version/language
+ *      qualifier on the mutation input) — fine for shared fields and
+ *      "the only version" usage, but never targets a specific version.
+ *      The publish-state fields are versioned, so the mutation needs
+ *      `language` and `version` on the input.
+ *   2. Recipe pushes go through `dispatchMutation` with rollback,
+ *      retries, and idempotent-create fallback. The content-state
+ *      verbs are explicit single-version writes with audit-log gating;
+ *      they don't want the recipe push path's behavior.
+ *
+ * Mutation shape verified against the Authoring GraphQL schema
+ * (XM Cloud, 2026-05-14) — `UpdateItemInput` accepts `language` /
+ * `version` alongside `itemId` and `fields`, and the version-scoped
+ * write only touches the targeted version.
+ */
+import type { EnvironmentConfiguration } from "../../config/types";
+import { type AuthoringRequestOptions } from "../../recipe/api/graphql";
+/**
+ * Sitecore boolean fields are stored as a string: `"1"` for true and
+ * an empty string for false. This is the wire form `updateItem`
+ * accepts and `getItem` returns. Anyone consuming `__Never publish`
+ * from a remote read should canonicalize via {@link parseBoolean}.
+ */
+export declare const SITECORE_BOOLEAN_TRUE = "1";
+export declare const SITECORE_BOOLEAN_FALSE = "";
+export declare const FIELD_NEVER_PUBLISH = "__Never publish";
+export declare const FIELD_VALID_FROM = "__Valid from";
+export declare const FIELD_VALID_TO = "__Valid to";
+/**
+ * The set of publish-state fields scai reads/writes per version. Kept
+ * as a tuple so the type system can narrow on field names elsewhere.
+ */
+export declare const PUBLISH_STATE_FIELDS: readonly ["__Never publish", "__Valid from", "__Valid to"];
+export type PublishStateFieldName = (typeof PUBLISH_STATE_FIELDS)[number];
+export interface VersionFieldValue {
+    name: string;
+    value: string;
+}
+export interface VersionFieldsSnapshot {
+    itemId: string;
+    name: string;
+    path: string;
+    language: string;
+    /** Sitecore-assigned version number (1-indexed). */
+    version: number;
+    /** Every field on the version, keyed by display name. Includes both
+     *  versioned and shared fields — caller is responsible for filtering
+     *  to the publish-state subset if that's all it needs. */
+    fields: VersionFieldValue[];
+}
+/**
+ * Parse Sitecore's wire form for booleans. Returns:
+ *   - `true`  for "1"
+ *   - `false` for "" or "0" or undefined
+ *   - the raw value's truthiness for anything else (defensive)
+ */
+export declare const parseBoolean: (raw: string | undefined | null) => boolean;
+/**
+ * Format a boolean for the wire ("1" / "").
+ */
+export declare const formatBoolean: (value: boolean) => string;
+/**
+ * Look up a single field on a snapshot. Returns the stored value or
+ * `null` when the field isn't present on the version (Sitecore treats
+ * absent versioned fields as effectively empty; we surface that
+ * distinction to the audit trail as `null` so an operator can tell
+ * apart "was explicitly empty" from "wasn't there at all").
+ */
+export declare const findField: (snapshot: VersionFieldsSnapshot, name: string) => string | null;
+export interface ReadVersionFieldsOptions {
+    itemId: string;
+    language: string;
+    /** Specific version (1-indexed). Undefined → latest. */
+    version?: number;
+    request?: AuthoringRequestOptions;
+}
+/**
+ * Read the version-state fields for `(itemId, language, version?)`.
+ * Throws `INPUT_INVALID` if the item or the requested version doesn't
+ * exist — the caller is responsible for path → itemId resolution
+ * before invoking this helper (use the existing
+ * `resolveItemPathsToIds`).
+ */
+export declare const readVersionFields: (environment: EnvironmentConfiguration, options: ReadVersionFieldsOptions) => Promise<VersionFieldsSnapshot>;
+export interface WriteVersionFieldsOptions {
+    itemId: string;
+    language: string;
+    /** Required — the specific version to write. Use `readVersionFields`
+     *  first to resolve "latest" → a concrete number, then pass it back
+     *  here so the write is unambiguous if a new version is created
+     *  between read and write. */
+    version: number;
+    fields: VersionFieldValue[];
+    request?: AuthoringRequestOptions;
+}
+/**
+ * Write `fields` to the version at `(itemId, language, version)`.
+ *
+ * Disables retries — the Authoring GraphQL endpoint has no
+ * idempotency-key mechanism, so retrying a write that already
+ * succeeded server-side would double-apply. Same reasoning the recipe
+ * runtime uses for `writeRequest` (see `authoring-client.ts`).
+ */
+export declare const writeVersionFields: (environment: EnvironmentConfiguration, options: WriteVersionFieldsOptions) => Promise<void>;
+/**
+ * Resolve a content-tree path to its itemId via the Authoring API.
+ * Single-path convenience around the read query — the publishing
+ * surface's `resolveItemPathsToIds` is batched + multi-path; for the
+ * `content version *` verbs (one item at a time) the single-path
+ * shape is clearer.
+ *
+ * Returns the canonical itemId without curly braces.
+ */
+export declare const resolveSinglePathToId: (environment: EnvironmentConfiguration, path: string, request?: AuthoringRequestOptions) => Promise<string>;