@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/policy/schema.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Zod schemas validating the on-disk policy JSON.
+ *
+ * Two artifacts (see docs/policy-and-guardrails.md):
+ *   - the user-global workspace policy (`~/.sitecoreai/policy.json`)
+ *   - the optional repo policy (`<repo>/scai.policy.json`)
+ *
+ * The hand-derived TypeScript shapes live in `./types`, inferred from
+ * these schemas so the two can never drift.
+ */
+import { z } from "zod";
+/** Operation risk tiers, ascending. See `./types` for the ordering helpers. */
+export declare const riskTierSchema: z.ZodEnum<{
+    read: "read";
+    write: "write";
+    destructive: "destructive";
+    mint: "mint";
+}>;
+/** How an environment came to be enrolled — surfaced by `scai policy show`. */
+export declare const enrollSourceSchema: z.ZodEnum<{
+    "setup-login": "setup-login";
+    "mcp-serve": "mcp-serve";
+    "setup-init": "setup-init";
+    "policy-init": "policy-init";
+    "policy-allow": "policy-allow";
+}>;
+/**
+ * The pinned tenant identity of an enrolled environment. Every field is
+ * optional — an org-level profile has no project/environment — and
+ * enforcement compares only the fields the pin actually carries.
+ */
+export declare const envIdentitySchema: z.ZodObject<{
+    organizationId: z.ZodOptional<z.ZodString>;
+    projectId: z.ZodOptional<z.ZodString>;
+    environmentId: z.ZodOptional<z.ZodString>;
+    host: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const policyEnvironmentSchema: z.ZodObject<{
+    identity: z.ZodObject<{
+        organizationId: z.ZodOptional<z.ZodString>;
+        projectId: z.ZodOptional<z.ZodString>;
+        environmentId: z.ZodOptional<z.ZodString>;
+        host: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    ceiling: z.ZodEnum<{
+        read: "read";
+        write: "write";
+        destructive: "destructive";
+        mint: "mint";
+    }>;
+    enrolledAt: z.ZodString;
+    enrolledVia: z.ZodEnum<{
+        "setup-login": "setup-login";
+        "mcp-serve": "mcp-serve";
+        "setup-init": "setup-init";
+        "policy-init": "policy-init";
+        "policy-allow": "policy-allow";
+    }>;
+    mintCredentials: z.ZodOptional<z.ZodBoolean>;
+    ciWrites: z.ZodOptional<z.ZodBoolean>;
+    stepUpMinutes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** The user-global workspace policy — the hard ceiling. */
+export declare const workspacePolicySchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    environments: z.ZodRecord<z.ZodString, z.ZodObject<{
+        identity: z.ZodObject<{
+            organizationId: z.ZodOptional<z.ZodString>;
+            projectId: z.ZodOptional<z.ZodString>;
+            environmentId: z.ZodOptional<z.ZodString>;
+            host: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        ceiling: z.ZodEnum<{
+            read: "read";
+            write: "write";
+            destructive: "destructive";
+            mint: "mint";
+        }>;
+        enrolledAt: z.ZodString;
+        enrolledVia: z.ZodEnum<{
+            "setup-login": "setup-login";
+            "mcp-serve": "mcp-serve";
+            "setup-init": "setup-init";
+            "policy-init": "policy-init";
+            "policy-allow": "policy-allow";
+        }>;
+        mintCredentials: z.ZodOptional<z.ZodBoolean>;
+        ciWrites: z.ZodOptional<z.ZodBoolean>;
+        stepUpMinutes: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * The optional repo policy. May only NARROW the workspace policy — drop
+ * environments from the allowlist, lower ceilings — never widen.
+ */
+export declare const repoPolicySchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    allowEnvironments: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    environments: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        ceiling: z.ZodOptional<z.ZodEnum<{
+            read: "read";
+            write: "write";
+            destructive: "destructive";
+            mint: "mint";
+        }>>;
+        mintCredentials: z.ZodOptional<z.ZodBoolean>;
+        ciWrites: z.ZodOptional<z.ZodBoolean>;
+        stepUpMinutes: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const parseWorkspacePolicy: (raw: unknown, source: string) => {
+    version: 1;
+    environments: Record<string, {
+        identity: {
+            organizationId?: string | undefined;
+            projectId?: string | undefined;
+            environmentId?: string | undefined;
+            host?: string | undefined;
+        };
+        ceiling: "read" | "write" | "destructive" | "mint";
+        enrolledAt: string;
+        enrolledVia: "setup-login" | "mcp-serve" | "setup-init" | "policy-init" | "policy-allow";
+        mintCredentials?: boolean | undefined;
+        ciWrites?: boolean | undefined;
+        stepUpMinutes?: number | undefined;
+    }>;
+};
+export declare const parseRepoPolicy: (raw: unknown, source: string) => {
+    version: 1;
+    allowEnvironments?: string[] | undefined;
+    environments?: Record<string, {
+        ceiling?: "read" | "write" | "destructive" | "mint" | undefined;
+        mintCredentials?: boolean | undefined;
+        ciWrites?: boolean | undefined;
+        stepUpMinutes?: number | undefined;
+    }> | undefined;
+};

package/dist/policy/schema.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * Zod schemas validating the on-disk policy JSON.
+ *
+ * Two artifacts (see docs/policy-and-guardrails.md):
+ *   - the user-global workspace policy (`~/.sitecoreai/policy.json`)
+ *   - the optional repo policy (`<repo>/scai.policy.json`)
+ *
+ * The hand-derived TypeScript shapes live in `./types`, inferred from
+ * these schemas so the two can never drift.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRepoPolicy = exports.parseWorkspacePolicy = exports.repoPolicySchema = exports.workspacePolicySchema = exports.policyEnvironmentSchema = exports.envIdentitySchema = exports.enrollSourceSchema = exports.riskTierSchema = void 0;
+const zod_1 = require("zod");
+const errors_1 = require("../shared/errors");
+/** Operation risk tiers, ascending. See `./types` for the ordering helpers. */
+exports.riskTierSchema = zod_1.z.enum(["read", "write", "destructive", "mint"]);
+/** How an environment came to be enrolled — surfaced by `scai policy show`. */
+exports.enrollSourceSchema = zod_1.z.enum([
+    "setup-login",
+    "mcp-serve",
+    "setup-init",
+    "policy-init",
+    "policy-allow",
+]);
+/**
+ * The pinned tenant identity of an enrolled environment. Every field is
+ * optional — an org-level profile has no project/environment — and
+ * enforcement compares only the fields the pin actually carries.
+ */
+exports.envIdentitySchema = zod_1.z.object({
+    organizationId: zod_1.z.string().min(1).optional(),
+    projectId: zod_1.z.string().min(1).optional(),
+    environmentId: zod_1.z.string().min(1).optional(),
+    host: zod_1.z.string().min(1).optional(),
+});
+exports.policyEnvironmentSchema = zod_1.z.object({
+    identity: exports.envIdentitySchema,
+    ceiling: exports.riskTierSchema,
+    enrolledAt: zod_1.z.string().min(1),
+    enrolledVia: exports.enrollSourceSchema,
+    /** Phase 2 — may `scai setup client create` mint a client here. */
+    mintCredentials: zod_1.z.boolean().optional(),
+    /** Phase 2 — may a CI caller perform write/destructive ops here. */
+    ciWrites: zod_1.z.boolean().optional(),
+    /** Phase 3 — destructive/mint ops require a deploy token minted within this many minutes. */
+    stepUpMinutes: zod_1.z.number().int().positive().optional(),
+});
+/** The user-global workspace policy — the hard ceiling. */
+exports.workspacePolicySchema = zod_1.z.object({
+    version: zod_1.z.literal(1),
+    environments: zod_1.z.record(zod_1.z.string(), exports.policyEnvironmentSchema),
+});
+/**
+ * The optional repo policy. May only NARROW the workspace policy — drop
+ * environments from the allowlist, lower ceilings — never widen.
+ */
+exports.repoPolicySchema = zod_1.z.object({
+    version: zod_1.z.literal(1),
+    allowEnvironments: zod_1.z.array(zod_1.z.string().min(1)).optional(),
+    environments: zod_1.z
+        .record(zod_1.z.string(), zod_1.z.object({
+        ceiling: exports.riskTierSchema.optional(),
+        mintCredentials: zod_1.z.boolean().optional(),
+        ciWrites: zod_1.z.boolean().optional(),
+        stepUpMinutes: zod_1.z.number().int().positive().optional(),
+    }))
+        .optional(),
+});
+const formatIssues = (error) => error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`);
+const parseWorkspacePolicy = (raw, source) => {
+    const result = exports.workspacePolicySchema.safeParse(raw);
+    if (!result.success) {
+        throw (0, errors_1.createScaiError)(`Invalid workspace policy at ${source}.`, "CONFIG_INVALID", {
+            hint: "Fix the file, or run 'scai policy init' to regenerate it.",
+            details: formatIssues(result.error),
+        });
+    }
+    return result.data;
+};
+exports.parseWorkspacePolicy = parseWorkspacePolicy;
+const parseRepoPolicy = (raw, source) => {
+    const result = exports.repoPolicySchema.safeParse(raw);
+    if (!result.success) {
+        throw (0, errors_1.createScaiError)(`Invalid repo policy at ${source}.`, "CONFIG_INVALID", {
+            hint: "Fix scai.policy.json — it may only narrow the workspace policy.",
+            details: formatIssues(result.error),
+        });
+    }
+    return result.data;
+};
+exports.parseRepoPolicy = parseRepoPolicy;

package/dist/policy/store.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Sync read / atomic write of the policy artifacts. Sync because the
+ * enforcement chokepoint (`resolveEnvironment`) is itself sync.
+ */
+import type { RepoPolicy, WorkspacePolicy } from "./types";
+/**
+ * Read the user-global workspace policy. Returns `null` when no policy
+ * file exists — callers treat that as "unmanaged mode": enforcement is a
+ * no-op until the operator runs `scai setup login`, `scai mcp serve`, or
+ * `scai policy init`. A present-but-corrupt file fails closed (throws
+ * `CONFIG_INVALID`) rather than silently disabling the guardrail.
+ */
+export declare const readWorkspacePolicy: () => WorkspacePolicy | null;
+/** Read the optional repo policy sitting next to the config file. */
+export declare const readRepoPolicy: (configRootDir: string) => RepoPolicy | null;
+/**
+ * Write the user-global workspace policy. Atomic (temp file + rename) so
+ * a crash mid-write can't leave a half-written policy that would
+ * fail-closed every later command. Returns the path written, or `null`
+ * when no policy directory is resolvable (Vitest without
+ * `SITECOREAI_POLICY_HOME`).
+ */
+export declare const writeWorkspacePolicy: (policy: WorkspacePolicy) => string | null;
+/** Whether the workspace is "managed" — a user-global policy file exists. */
+export declare const isManaged: () => boolean;

package/dist/policy/store.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * Sync read / atomic write of the policy artifacts. Sync because the
+ * enforcement chokepoint (`resolveEnvironment`) is itself sync.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isManaged = exports.writeWorkspacePolicy = exports.readRepoPolicy = exports.readWorkspacePolicy = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const errors_1 = require("../shared/errors");
+const schema_1 = require("./schema");
+const paths_1 = require("./paths");
+const readJson = (file) => {
+    let text;
+    try {
+        text = node_fs_1.default.readFileSync(file, "utf8");
+    }
+    catch (error) {
+        throw (0, errors_1.createScaiError)(`Unable to read ${file}.`, "CONFIG_INVALID", {
+            hint: "Check that the file is readable.",
+            details: [error instanceof Error ? error.message : String(error)],
+        });
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw (0, errors_1.createScaiError)(`${file} is not valid JSON.`, "CONFIG_INVALID", {
+            hint: "Fix the file, or run 'scai policy init' to regenerate the workspace policy.",
+            details: [error instanceof Error ? error.message : String(error)],
+        });
+    }
+};
+/**
+ * Read the user-global workspace policy. Returns `null` when no policy
+ * file exists — callers treat that as "unmanaged mode": enforcement is a
+ * no-op until the operator runs `scai setup login`, `scai mcp serve`, or
+ * `scai policy init`. A present-but-corrupt file fails closed (throws
+ * `CONFIG_INVALID`) rather than silently disabling the guardrail.
+ */
+const readWorkspacePolicy = () => {
+    const file = (0, paths_1.resolveUserPolicyPath)();
+    if (!file || !node_fs_1.default.existsSync(file)) {
+        return null;
+    }
+    return (0, schema_1.parseWorkspacePolicy)(readJson(file), file);
+};
+exports.readWorkspacePolicy = readWorkspacePolicy;
+/** Read the optional repo policy sitting next to the config file. */
+const readRepoPolicy = (configRootDir) => {
+    const file = (0, paths_1.resolveRepoPolicyPath)(configRootDir);
+    if (!node_fs_1.default.existsSync(file)) {
+        return null;
+    }
+    return (0, schema_1.parseRepoPolicy)(readJson(file), file);
+};
+exports.readRepoPolicy = readRepoPolicy;
+/**
+ * Write the user-global workspace policy. Atomic (temp file + rename) so
+ * a crash mid-write can't leave a half-written policy that would
+ * fail-closed every later command. Returns the path written, or `null`
+ * when no policy directory is resolvable (Vitest without
+ * `SITECOREAI_POLICY_HOME`).
+ */
+const writeWorkspacePolicy = (policy) => {
+    const file = (0, paths_1.resolveUserPolicyPath)();
+    if (!file) {
+        return null;
+    }
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    node_fs_1.default.writeFileSync(tmp, `${JSON.stringify(policy, null, 2)}\n`, "utf8");
+    node_fs_1.default.renameSync(tmp, file);
+    return file;
+};
+exports.writeWorkspacePolicy = writeWorkspacePolicy;
+/** Whether the workspace is "managed" — a user-global policy file exists. */
+const isManaged = () => {
+    const file = (0, paths_1.resolveUserPolicyPath)();
+    return Boolean(file && node_fs_1.default.existsSync(file));
+};
+exports.isManaged = isManaged;

package/dist/policy/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Workspace-policy types — the operator-owned guardrail layer that bounds
+ * which Sitecore environments scai may operate against.
+ *
+ * The file shapes are inferred from the Zod schemas in `./schema` so the
+ * validator and the types can never drift; the helpers below
+ * (`EffectivePolicy`, the risk-tier ordering) are hand-written because
+ * they describe runtime results, not on-disk JSON.
+ *
+ * See docs/policy-and-guardrails.md for the design.
+ */
+import type { z } from "zod";
+import type { envIdentitySchema, policyEnvironmentSchema, repoPolicySchema, riskTierSchema, workspacePolicySchema } from "./schema";
+/**
+ * Operation risk tiers, ascending. Phase 1 records a `ceiling` per
+ * environment but enforces only enrollment + identity; `destructive` and
+ * `mint` gain enforcement in Phase 2.
+ */
+export type RiskTier = z.infer<typeof riskTierSchema>;
+/** The pinned identity (tenant triple + host) of an enrolled environment. */
+export type EnvIdentity = z.infer<typeof envIdentitySchema>;
+/** One enrolled environment in the user-global workspace policy. */
+export type PolicyEnvironment = z.infer<typeof policyEnvironmentSchema>;
+/** The user-global workspace policy — `~/.sitecoreai/policy.json`. */
+export type WorkspacePolicy = z.infer<typeof workspacePolicySchema>;
+/** The optional repo policy — `<repo>/scai.policy.json`. */
+export type RepoPolicy = z.infer<typeof repoPolicySchema>;
+/** How an environment came to be enrolled. */
+export type EnrollSource = PolicyEnvironment["enrolledVia"];
+/** Risk tiers in ascending order — the array index is the rank. */
+export declare const RISK_TIERS: readonly ["read", "write", "destructive", "mint"];
+/** The resolved, layered verdict for a single environment. */
+export interface EffectivePolicy {
+    /** False when no user-global policy file exists — "unmanaged mode". */
+    managed: boolean;
+    /** Whether the environment is on the effective (layered) allowlist. */
+    enrolled: boolean;
+    /** Effective ceiling — the intersection of the user-global and repo layers. */
+    ceiling: RiskTier;
+    /** Pinned identity, or `null` when the environment is not enrolled. */
+    identity: EnvIdentity | null;
+    /** Phase 2 — whether `scai setup client create` may mint here (post repo-narrowing). */
+    mintCredentials: boolean;
+    /** Phase 2 — whether a CI caller may write/destructive here (post repo-narrowing). */
+    ciWrites: boolean;
+    /** Phase 3 — freshness window (minutes) for destructive/mint ops; `undefined` = no requirement. */
+    stepUpMinutes: number | undefined;
+}
+/** Rank of a tier (`read` = 0, `mint` = 3). */
+export declare const riskRank: (tier: RiskTier) => number;
+/** The lower (more restrictive) of two tiers. */
+export declare const minTier: (a: RiskTier, b: RiskTier) => RiskTier;

package/dist/policy/types.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Workspace-policy types — the operator-owned guardrail layer that bounds
+ * which Sitecore environments scai may operate against.
+ *
+ * The file shapes are inferred from the Zod schemas in `./schema` so the
+ * validator and the types can never drift; the helpers below
+ * (`EffectivePolicy`, the risk-tier ordering) are hand-written because
+ * they describe runtime results, not on-disk JSON.
+ *
+ * See docs/policy-and-guardrails.md for the design.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.minTier = exports.riskRank = exports.RISK_TIERS = void 0;
+/** Risk tiers in ascending order — the array index is the rank. */
+exports.RISK_TIERS = ["read", "write", "destructive", "mint"];
+/** Rank of a tier (`read` = 0, `mint` = 3). */
+const riskRank = (tier) => exports.RISK_TIERS.indexOf(tier);
+exports.riskRank = riskRank;
+/** The lower (more restrictive) of two tiers. */
+const minTier = (a, b) => ((0, exports.riskRank)(a) <= (0, exports.riskRank)(b) ? a : b);
+exports.minTier = minTier;

package/dist/program.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The scai Commander program tree — assembled here, with **no
+ * import-time side effects**, so it can be consumed both by the CLI
+ * entrypoint (`src/cli.ts`, which runs it) and by tooling that only
+ * needs to inspect the command structure (`scripts/generate-commands-doc.ts`).
+ *
+ * `src/cli.ts` keeps the runtime concerns — argv normalization, the
+ * auto-wizard, telemetry, the force-exit teardown — and calls
+ * `createProgram` to build the tree. Anything that adds a top-level
+ * command group belongs here.
+ */
+import { Command } from "commander";
+/** Env snapshot the shell REPL restores between sub-invocations. */
+export type RunCliOptions = {
+    baseEnv?: Record<string, string | undefined>;
+    skipBanner?: boolean;
+    shellMode?: boolean;
+};
+/**
+ * The CLI runner — `src/cli.ts` supplies the real implementation. The
+ * shell command needs a callback to re-enter the CLI for each typed
+ * line; `createProgram` threads it through without importing the
+ * entrypoint (which would re-trigger its side effects).
+ */
+export type RunCli = (argv: string[], options?: RunCliOptions) => Promise<void>;
+/**
+ * Build the full nested Commander tree. The CLI surface is organized by
+ * product area, not flat — each parent below is a namespace, and the
+ * leaf command builders are unchanged (only where they attach).
+ *
+ * Pure: no side effects beyond constructing `Command` objects.
+ */
+export declare const createProgram: (runCli: RunCli, options?: {
+    shellMode?: boolean;
+}) => Command;

package/dist/program.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * The scai Commander program tree — assembled here, with **no
+ * import-time side effects**, so it can be consumed both by the CLI
+ * entrypoint (`src/cli.ts`, which runs it) and by tooling that only
+ * needs to inspect the command structure (`scripts/generate-commands-doc.ts`).
+ *
+ * `src/cli.ts` keeps the runtime concerns — argv normalization, the
+ * auto-wizard, telemetry, the force-exit teardown — and calls
+ * `createProgram` to build the tree. Anything that adds a top-level
+ * command group belongs here.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProgram = void 0;
+const commander_1 = require("commander");
+const package_json_1 = __importDefault(require("../package.json"));
+const audit_1 = require("./commands/audit");
+const brand_1 = require("./commands/brand");
+const cleanup_1 = require("./commands/cleanup");
+const serialization_1 = require("./commands/serialization");
+const status_1 = require("./commands/status");
+const login_1 = require("./commands/login");
+const deploy_1 = require("./commands/deploy");
+const explain_1 = require("./commands/explain");
+const health_1 = require("./commands/health");
+const history_1 = require("./commands/history");
+const init_1 = require("./commands/init");
+const logout_1 = require("./commands/logout");
+const setup_client_1 = require("./commands/setup-client");
+const mcp_1 = require("./commands/mcp");
+const policy_1 = require("./commands/policy");
+const brief_1 = require("./commands/brief");
+const campaign_1 = require("./commands/campaign");
+const agents_1 = require("./commands/agents");
+const publish_1 = require("./commands/publish");
+const topics_1 = require("./commands/topics");
+const recipe_1 = require("./commands/recipe");
+const sync_1 = require("./commands/sync");
+const shell_1 = require("./commands/shell");
+const config_1 = require("./commands/config");
+const telemetry_1 = require("./commands/telemetry");
+const webhook_1 = require("./commands/webhook");
+const workflow_1 = require("./commands/workflow");
+const shared_1 = require("./commands/shared");
+/**
+ * Build the full nested Commander tree. The CLI surface is organized by
+ * product area, not flat — each parent below is a namespace, and the
+ * leaf command builders are unchanged (only where they attach).
+ *
+ * Pure: no side effects beyond constructing `Command` objects.
+ */
+const createProgram = (runCli, options = {}) => {
+    const program = new commander_1.Command();
+    program
+        .name("scai")
+        .description("SitecoreAI developer toolkit — deploy, serialization, recipes, publishing, and MCP")
+        .version(package_json_1.default.version, "-V, --version", "Display the CLI version");
+    // Top-level command groups. The CLI surface is organized by product
+    // area, not flat — each parent below is a namespace, and the leaf
+    // command builders are unchanged (only where they attach moved).
+    const setup = new commander_1.Command("setup").description("Configure environments and authenticate — init, login, env, logout, status");
+    setup.addCommand((0, init_1.createInitCommand)());
+    setup.addCommand((0, login_1.createLoginCommand)());
+    setup.addCommand((0, setup_client_1.createSetupClientCommand)());
+    setup.addCommand((0, logout_1.createLogoutCommand)());
+    setup.addCommand((0, status_1.createStatusCommand)());
+    const hygiene = new commander_1.Command("hygiene").description("Content quality — read-only audits, mutating cleanup, and composed diagnostics");
+    hygiene.addCommand((0, audit_1.createAuditCommand)());
+    hygiene.addCommand((0, cleanup_1.createCleanupCommand)());
+    hygiene.addCommand((0, explain_1.createExplainCommand)());
+    // `webhook` nests under `workflow`; the old standalone `content`
+    // wrapper is dropped — its only child (`version`) attaches directly.
+    const workflow = (0, workflow_1.createWorkflowCommand)();
+    workflow.addCommand((0, webhook_1.createWebhookCommand)());
+    const content = new commander_1.Command("content").description("Operate on content items — publish and workflow handlers");
+    content.addCommand((0, publish_1.createPublishCommand)());
+    content.addCommand(workflow);
+    // `content version` (per-version publish-state fields — __Never publish,
+    // __Valid from / __Valid to) is intentionally NOT registered yet. Those
+    // fields only make sense once content items (pages, etc.) can be authored
+    // through the CLI; today they only arrive via recipes, so a lone
+    // version-state verb is more confusing than useful. The SDK
+    // (src/content/api/version-fields.ts) and `hygiene cleanup versions` both
+    // stay — only this CLI command group is hidden until item primitives land.
+    // content.addCommand(createContentVersionCommand());
+    content.addHelpText("after", "\nRoadmap: `scai content sites` and `scai content pages` — XM Cloud\n" +
+        "site and page management — are planned, not yet shipped. See docs/roadmap.md.\n");
+    // `brief`, `campaign`, `brand`, and `agents` are unstable surfaces —
+    // reverse-engineered, no SemVer stability promise. `markUnstable`
+    // stamps the `[unstable]` help marker, the stability note, and the
+    // per-invocation stderr warning onto each group.
+    const ops = new commander_1.Command("ops").description("Sitecore Content Operations — briefs and campaigns");
+    ops.addCommand((0, shared_1.markUnstable)((0, brief_1.createBriefCommand)(), "scai ops brief"));
+    ops.addCommand((0, shared_1.markUnstable)((0, campaign_1.createCampaignCommand)(), "scai ops campaign"));
+    const provision = new commander_1.Command("provision").description("Provision environments and content-as-code — deploy, serialization, recipes");
+    provision.addCommand((0, deploy_1.createDeployCommand)());
+    provision.addCommand((0, serialization_1.createSerializationCommand)());
+    provision.addCommand((0, recipe_1.createRecipeCommand)());
+    provision.addHelpText("after", "\nRoadmap: `scai provision iar` — package content as Items-as-Resources\n" +
+        "(IAR) — is planned, not yet shipped. See docs/roadmap.md.\n");
+    const cli = new commander_1.Command("cli").description("CLI tooling — config, diagnostics, history, REPL");
+    cli.addCommand((0, config_1.createConfigCommand)());
+    cli.addCommand((0, health_1.createHealthCommand)());
+    cli.addCommand((0, history_1.createHistoryCommand)());
+    cli.addCommand((0, shell_1.createShellCommand)(runCli));
+    cli.addCommand((0, telemetry_1.createTelemetryCommand)());
+    cli.addCommand((0, topics_1.createTopicsCommand)());
+    program.addCommand(setup);
+    program.addCommand((0, policy_1.createPolicyCommand)());
+    program.addCommand(hygiene);
+    program.addCommand(content);
+    program.addCommand(ops);
+    program.addCommand((0, shared_1.markUnstable)((0, brand_1.createBrandCommand)(), "scai brand"));
+    program.addCommand((0, shared_1.markUnstable)((0, agents_1.createAgentsCommand)(), "scai agents"));
+    program.addCommand(provision);
+    program.addCommand((0, sync_1.createSyncCommand)());
+    // `mcp` stays top-level: `scai mcp serve` is wired into external MCP
+    // client configs, so its path must not move under a group.
+    program.addCommand((0, mcp_1.createMcpCommand)());
+    program.addCommand(cli);
+    program.showHelpAfterError(true);
+    program.showSuggestionAfterError(true);
+    if (options.shellMode) {
+        program.exitOverride();
+    }
+    return program;
+};
+exports.createProgram = createProgram;

package/dist/publishing/api/auth.d.ts

@@ -0,0 +1,49 @@
+import type { SitecoreApiClientOptions } from "../../serialization/api/types";
+/**
+ * OAuth scopes the SAI Publishing API requires.
+ *
+ * Per the Publishing API architect (2026-05-14):
+ *
+ *   - Every Sitecore Cloud **environment** has its own automation
+ *     client (Cloud Portal → Environments → [env] → Automation
+ *     Clients). Env-level clients carry the tenant-tier `.t` scopes
+ *     below by default. ORG-level clients (used for org/project/env
+ *     management) do NOT.
+ *   - The api-docs page lists both `.a` (admin-tier, for Pages-UI
+ *     user tokens with Organization Owner role) and `.t` (tenant-
+ *     tier, for automation clients). Use `.t` for any flow whose
+ *     credentials are scoped to a single environment.
+ *
+ *   - `xmcpub.jobs.t:r` — read publishing jobs
+ *   - `xmcpub.jobs.t:w` — create / cancel publishing jobs
+ *   - `xmcpub.queue:r`  — read the publish queue
+ *
+ * Audience: `https://api.sitecorecloud.io` (standard).
+ */
+export declare const PUBLISHING_SCOPES_REQUESTED: readonly ["xmcpub.jobs.t:r", "xmcpub.jobs.t:w", "xmcpub.queue:r"];
+export interface AcquirePublishingTokenOptions {
+    envName: string;
+    environment: SitecoreApiClientOptions;
+}
+/**
+ * Returns a Bearer JWT for the SAI Publishing API.
+ *
+ * Resolution order, cheapest first:
+ *
+ *   1. Cached publishing token in the keychain — set by a previous
+ *      successful mint via this function. Reused until expiry / clear.
+ *   2. The deploy token in the keychain, IF its scope claim already
+ *      includes `xmcpub.jobs.t:*`. This is the zero-config path:
+ *      operators who logged in interactively against an env-level
+ *      automation client get a single token covering both deploy
+ *      and publishing scopes (scai's default scope set requests
+ *      both — see `SCAI_API_SCOPES`).
+ *   3. Fresh M2M mint via the env's `clientId` + `clientSecret`,
+ *      explicitly requesting publishing scopes. Cached on success.
+ *
+ * Refuses with `AUTH_REQUIRED` when none of these paths produces a
+ * token carrying the required scopes. The error message decodes the
+ * granted-scope set and infers the credential class so operators know
+ * whether they need an env-level client or just need to re-login.
+ */
+export declare const acquirePublishingToken: (options: AcquirePublishingTokenOptions) => Promise<string>;