@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/brand/seed.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.seedBrandKit = void 0;
+const create_1 = require("./kits/create");
+const sections_1 = require("./kits/sections");
+const upload_1 = require("./documents/upload");
+const run_1 = require("./pipeline/run");
+const errors_1 = require("../shared/errors");
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * The headline composite — drive a brand kit from "doesn't exist" to
+ * "has populated sections and is ready for Brand Review" in one call.
+ *
+ * Sequence (see [[project-scai-brand-kit-seed-recipe]]):
+ *
+ *   1. createBrandKit          → draft kit
+ *   2. uploadDocument          → doc attached (status: pending)
+ *   3. publishBrandKit         → kit status: published (required!)
+ *   4. runBrandIngestionPipeline (chunks the doc)
+ *   5. runEnrichSectionsPipeline  (populates sections from chunks)
+ *   6. poll listBrandKitSections until the count goes from 0 to >0
+ *   7. return kit + doc + section list
+ *
+ * The `doc.status` going to `failed` mid-flight is misleading and
+ * NOT a real error — sections still populate via enrichment, so the
+ * composite ignores that signal and only cares about section count.
+ *
+ * Cost note: this triggers two paid AI pipeline runs. Each run takes
+ * ~5 min wall-clock. Don't loop this without consent.
+ */
+const seedBrandKit = async (options) => {
+    const start = Date.now();
+    const pollIntervalSec = options.pollIntervalSec ?? 15;
+    const timeoutSec = options.timeoutSec ?? 900;
+    const emit = (event) => {
+        options.onProgress?.({
+            ...event,
+            elapsedSec: Math.round((Date.now() - start) / 1000),
+        });
+    };
+    // 1. CREATE kit
+    emit({ stage: "createKit", message: `Creating brand kit '${options.name}'…` });
+    const createInput = {
+        client: options.client,
+        name: options.name,
+        description: options.description,
+        industry: options.industry,
+    };
+    const kit = await (0, create_1.createBrandKit)(createInput);
+    emit({ stage: "createKit", message: `Created kit ${kit.id}` });
+    // 2. UPLOAD doc(s) — one or many, before a single ingestion pass.
+    const uploadList = options.documents && options.documents.length > 0
+        ? options.documents.map((doc) => ({
+            source: { url: doc.url },
+            title: doc.title,
+            summary: doc.summary,
+        }))
+        : options.source
+            ? [
+                {
+                    source: options.source,
+                    title: options.documentTitle,
+                    summary: options.documentSummary,
+                },
+            ]
+            : [];
+    if (uploadList.length === 0) {
+        throw (0, errors_1.createScaiError)("seedBrandKit requires `source` or `documents`.", "INPUT_INVALID");
+    }
+    const documents = [];
+    for (const [index, entry] of uploadList.entries()) {
+        emit({
+            stage: "uploadDocument",
+            message: `Uploading source document ${index + 1}/${uploadList.length}…`,
+        });
+        const uploaded = await (0, upload_1.uploadDocument)({
+            client: options.client,
+            brandKitId: kit.id,
+            source: entry.source,
+            title: entry.title ?? `${options.name} Brand Guidelines`,
+            summary: entry.summary ?? `Source doc for ${options.name} brand kit (seeded via scai)`,
+            type: "brand guidelines",
+            fileType: "application/pdf",
+        });
+        documents.push(uploaded);
+        emit({ stage: "uploadDocument", message: `Uploaded document ${uploaded.id}` });
+    }
+    const document = documents[0];
+    // 3. PUBLISH kit (REQUIRED before pipelines)
+    emit({ stage: "publishKit", message: "Publishing kit…" });
+    await (0, create_1.publishBrandKit)({ client: options.client, brandKitId: kit.id });
+    emit({ stage: "publishKit", message: "Kit published" });
+    // 4. RUN brand ingestion (chunks the doc)
+    emit({ stage: "runIngestion", message: "Triggering BrandIngestionPipeline…" });
+    const ingestionRun = await (0, run_1.runBrandIngestionPipeline)({
+        client: options.client,
+        brandKitId: kit.id,
+        populateSections: true,
+        documentIds: documents.map((doc) => doc.id),
+    });
+    emit({
+        stage: "runIngestion",
+        message: `Ingestion run started: ${ingestionRun.id}`,
+    });
+    // 5. RUN enrich sections (populates section content from chunks)
+    emit({ stage: "runEnrichment", message: "Triggering EnrichSectionsPipeline…" });
+    const enrichmentRun = await (0, run_1.runEnrichSectionsPipeline)({
+        client: options.client,
+        brandKitId: kit.id,
+    });
+    emit({
+        stage: "runEnrichment",
+        message: `Enrichment run started: ${enrichmentRun.id}`,
+    });
+    // 6. POLL sections until they appear
+    const deadline = Date.now() + timeoutSec * 1000;
+    let sections = [];
+    while (Date.now() < deadline) {
+        if (options.signal?.aborted) {
+            throw new Error("seedBrandKit aborted by signal");
+        }
+        sections = await (0, sections_1.listBrandKitSections)({
+            client: options.client,
+            brandKitId: kit.id,
+        });
+        emit({
+            stage: "pollSections",
+            message: `Sections: ${sections.length}`,
+            sectionCount: sections.length,
+        });
+        if (sections.length > 0) {
+            break;
+        }
+        await sleep(pollIntervalSec * 1000);
+    }
+    if (sections.length === 0) {
+        throw new Error(`Timed out after ${timeoutSec}s waiting for sections to populate. Kit ${kit.id} is on the tenant; check status manually with \`scai brand kits sections ${kit.id}\`.`);
+    }
+    emit({
+        stage: "done",
+        message: `Seeded ${sections.length} sections for kit ${kit.id}`,
+        sectionCount: sections.length,
+    });
+    return {
+        kit,
+        document,
+        sections,
+        elapsedSec: Math.round((Date.now() - start) / 1000),
+    };
+};
+exports.seedBrandKit = seedBrandKit;

package/dist/brand/tasks/login.d.ts

@@ -0,0 +1,37 @@
+import type { CommonOptions } from "../../shared/cli-options";
+export interface BrandLoginOptions extends CommonOptions {
+    environmentName?: string;
+    orgId?: string;
+    clientId?: string;
+    clientSecret?: string;
+    authority?: string;
+    audience?: string;
+    /** Skip the overwrite confirmation when a credential already exists for this org. */
+    force?: boolean;
+}
+/**
+ * Provision a Sitecore Brand credential for a Sitecore
+ * organization. The flow is:
+ *
+ *   1. Resolve `orgId` (flag → env profile → error).
+ *   2. Detect an existing credential for this org and confirm overwrite.
+ *   3. Acquire `clientId` (flag → prompt) and `clientSecret`
+ *      (flag → prompt, masked).
+ *   4. Mint a test token against `auth.sitecorecloud.io/oauth/token`
+ *      with `audience=https://api.sitecorecloud.io`, requesting the
+ *      Brand scope set.
+ *   5. Refuse to persist the credential if the granted scopes are
+ *      missing — operators who paste the Pages/Sites automation
+ *      client by mistake get a pointed error explaining the fix
+ *      ([[project-scai-ai-skills-credential-model]]).
+ *   6. Write `brand[orgId].clientId` to `sitecoreai.cli.json`,
+ *      store the secret in the OS keychain, and cache the minted
+ *      token (keyed by orgId — multiple env profiles in the same
+ *      org share both the credential and the cached token).
+ *
+ * `--print` is intentionally not supported here — the minted token
+ * is short-lived and printing it would tempt operators to script
+ * around the keychain. Use the library surface
+ * (`acquireBrandToken`) for non-interactive automation.
+ */
+export declare const runBrandLogin: (options: BrandLoginOptions) => Promise<void>;

package/dist/brand/tasks/login.js

@@ -0,0 +1,192 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runBrandLogin = void 0;
+const root_config_1 = require("../../config/root-config");
+const auth_1 = require("../../serialization/api/auth");
+const errors_1 = require("../../shared/errors");
+const keychain_1 = require("../../shared/keychain");
+const cli_tasks_1 = require("../../shared/cli-tasks");
+const prompt_1 = require("../../shared/prompt");
+const auth_2 = require("../api/auth");
+const credential_1 = require("../credential");
+const DEFAULT_AUTHORITY = "https://auth.sitecorecloud.io";
+/**
+ * Optional scopes the login flow surfaces when present, to give the
+ * operator a complete view of what the AI APIs key carries. scai's
+ * mint request does NOT pass an explicit `scope` param — Auth0 grants
+ * whatever the client has, and we report it back.
+ */
+const KNOWN_BRAND_SCOPES = [
+    "ai.org.brd:r",
+    "ai.org.brd:w",
+    "ai.org.docs:r",
+    "ai.org.docs:w",
+    "ai.org.br:gen",
+    "ai.org:admin",
+];
+const CLOUD_PORTAL_HINT = "Create the credential in Cloud Portal → Stream → Admin → AI APIs keys → Create credential.";
+/**
+ * Provision a Sitecore Brand credential for a Sitecore
+ * organization. The flow is:
+ *
+ *   1. Resolve `orgId` (flag → env profile → error).
+ *   2. Detect an existing credential for this org and confirm overwrite.
+ *   3. Acquire `clientId` (flag → prompt) and `clientSecret`
+ *      (flag → prompt, masked).
+ *   4. Mint a test token against `auth.sitecorecloud.io/oauth/token`
+ *      with `audience=https://api.sitecorecloud.io`, requesting the
+ *      Brand scope set.
+ *   5. Refuse to persist the credential if the granted scopes are
+ *      missing — operators who paste the Pages/Sites automation
+ *      client by mistake get a pointed error explaining the fix
+ *      ([[project-scai-ai-skills-credential-model]]).
+ *   6. Write `brand[orgId].clientId` to `sitecoreai.cli.json`,
+ *      store the secret in the OS keychain, and cache the minted
+ *      token (keyed by orgId — multiple env profiles in the same
+ *      org share both the credential and the cached token).
+ *
+ * `--print` is intentionally not supported here — the minted token
+ * is short-lived and printing it would tempt operators to script
+ * around the keychain. Use the library surface
+ * (`acquireBrandToken`) for non-interactive automation.
+ */
+const runBrandLogin = async (options) => {
+    const logger = (0, cli_tasks_1.toLogger)(options);
+    const configPath = options.config ?? process.cwd();
+    const rootConfigFile = (0, root_config_1.readRootConfigurationFile)(configPath);
+    const root = (0, root_config_1.readRootConfiguration)(configPath, options.environmentName);
+    // Env name comes only from an explicit signal — `--environment-name`
+    // or a configured `defaultEnvProfile`. We deliberately do NOT fall
+    // back to `root.defaultEnvironment`, which substitutes the literal
+    // "default" when no default is configured: that masks an unset
+    // default as a missing env profile. When neither signal is present we
+    // leave `envName` undefined and let resolveBrandOrgId scan the
+    // profiles, so a single-environment config resolves with no flag.
+    const envName = options.environmentName ?? rootConfigFile.config.defaultEnvProfile;
+    const orgId = (0, credential_1.resolveBrandOrgId)(options.orgId, root.environments, envName);
+    // The env profile behind the resolved org — the named one when an env
+    // was selected, else whichever profile carries this org. Used only for
+    // the `authority` fallback below; `--authority` and the default still
+    // win/cover the no-profile case.
+    const selectedEnv = (envName ? root.environments[envName] : undefined) ??
+        Object.values(root.environments).find((e) => e.organizationId === orgId);
+    const existing = rootConfigFile.config.brand?.[orgId];
+    const isInteractive = process.stdin.isTTY && process.stdout.isTTY && process.env.SITECOREAI_NON_INTERACTIVE !== "1";
+    if (existing && !options.force) {
+        if (!isInteractive) {
+            throw (0, errors_1.createScaiError)(`A Brand credential is already configured for org '${orgId}'.`, "INPUT_INVALID", {
+                hint: "Re-run with --force to overwrite the existing credential.",
+            });
+        }
+        const overwrite = await (0, prompt_1.promptConfirm)(`A Brand credential is already configured for org '${orgId}'. Overwrite?`, false);
+        if (!overwrite) {
+            logger.info("Aborted. Existing credential left in place.");
+            return;
+        }
+    }
+    let clientId = options.clientId;
+    if (!clientId) {
+        if (!isInteractive) {
+            throw (0, cli_tasks_1.inputError)("Client ID is required.", `Pass --client-id <id> (and --client-secret <secret>). ${CLOUD_PORTAL_HINT}`);
+        }
+        logger.info(CLOUD_PORTAL_HINT);
+        clientId = await (0, prompt_1.promptText)("Client ID");
+        if (!clientId) {
+            throw (0, cli_tasks_1.inputError)("Client ID is required.");
+        }
+    }
+    let clientSecret = options.clientSecret;
+    if (!clientSecret) {
+        if (!isInteractive) {
+            throw (0, cli_tasks_1.inputError)("Client secret is required.", "Pass --client-secret <secret>, or run interactively.");
+        }
+        clientSecret = await (0, prompt_1.promptSecret)("Client Secret: ");
+    }
+    const authority = options.authority ?? selectedEnv?.authority ?? DEFAULT_AUTHORITY;
+    const audience = options.audience ?? auth_1.DEFAULT_SITECORE_API_AUDIENCE;
+    logger.info("Validating credential by minting a test token...");
+    let mintResult;
+    try {
+        // No explicit scope param — Auth0 grants whatever the AI APIs key
+        // has been issued. Requesting scopes the client wasn't granted
+        // causes Auth0 to 403 outright (verified 2026-05-14 with a
+        // partial-scope client). Permissive login is intentional: the
+        // operator may legitimately have a read-only or review-only key,
+        // and per-operation scope checks downstream will surface the
+        // exact missing scope when they go to run something.
+        mintResult = await (0, auth_1.requestClientCredentialsToken)({
+            authority,
+            clientId,
+            clientSecret,
+            audience,
+        });
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw (0, errors_1.createScaiError)(`Auth0 rejected the Brand credential for org '${orgId}'.`, "AUTH_BRAND_REQUIRED", {
+            hint: `Auth0 error: ${detail}. Verify Client ID + Client Secret. ${CLOUD_PORTAL_HINT}`,
+        });
+    }
+    if (!mintResult.accessToken) {
+        throw (0, errors_1.createScaiError)(`Sitecore did not return an access token for org '${orgId}'.`, "AUTH_BRAND_REQUIRED", { hint: CLOUD_PORTAL_HINT });
+    }
+    const grantedScopes = (0, auth_2.extractScopes)(mintResult.accessToken);
+    const hasReviewScope = grantedScopes.includes("ai.org.br:gen");
+    const knownGranted = grantedScopes.filter((s) => KNOWN_BRAND_SCOPES.includes(s));
+    const knownMissing = KNOWN_BRAND_SCOPES.filter((s) => !grantedScopes.includes(s));
+    const looksLikePagesSitesClient = grantedScopes.some((s) => s.startsWith("xmclouddeploy.") || s.startsWith("xmcpub.")) &&
+        !grantedScopes.some((s) => s.startsWith("ai.org"));
+    if (looksLikePagesSitesClient) {
+        // The credential is the wrong client class entirely — refuse to
+        // persist. A typed Pages/Sites automation client never carries
+        // any `ai.org*` scope, so it will fail every Brand call.
+        throw (0, errors_1.createScaiError)(`Credential for org '${orgId}' looks like the Pages/Sites automation client, not an AI APIs key.`, "AUTH_BRAND_REQUIRED", {
+            hint: `Granted scopes: ${grantedScopes.join(", ") || "(none)"}. ${CLOUD_PORTAL_HINT}`,
+        });
+    }
+    if (knownGranted.length === 0) {
+        // No recognizable Brand scope at all — probably the wrong
+        // client class even though it doesn't match the Pages/Sites
+        // shape. Refuse to persist to avoid storing a credential that's
+        // guaranteed to fail every operation.
+        throw (0, errors_1.createScaiError)(`Credential minted for org '${orgId}' but carries no recognized Brand scopes.`, "AUTH_BRAND_REQUIRED", {
+            hint: `Granted scopes: ${grantedScopes.join(", ") || "(none)"}. Expected at least one of: ${KNOWN_BRAND_SCOPES.join(", ")}. ${CLOUD_PORTAL_HINT}`,
+        });
+    }
+    // Persist: keychain first (secret + token), then config. If keychain
+    // fails we don't want a config record pointing at a secret-less
+    // entry.
+    const secretStored = await (0, keychain_1.setBrandClientSecret)(orgId, clientSecret);
+    if (!secretStored) {
+        throw (0, errors_1.createScaiError)("Failed to store the Brand client secret in the OS keychain.", "AUTH_BRAND_REQUIRED", {
+            hint: "Check OS keychain availability. On CI runners without a keychain, set SITECOREAI_QUIET=1 to suppress warnings and use the library surface directly.",
+        });
+    }
+    await (0, keychain_1.setBrandToken)(orgId, mintResult.accessToken);
+    const credentialRecord = {
+        clientId,
+        audience,
+        authority,
+        tokenExpiresIn: mintResult.expiresIn ?? null,
+        tokenLastUpdated: new Date().toISOString(),
+    };
+    const brand = { ...(rootConfigFile.config.brand ?? {}) };
+    brand[orgId] = credentialRecord;
+    rootConfigFile.config.brand = brand;
+    (0, root_config_1.writeRootConfigurationFile)(configPath, rootConfigFile.config);
+    // Verify the credential we just wrote can be read back, in case the
+    // keychain silently dropped it.
+    const readback = await (0, keychain_1.getBrandClientSecret)(orgId);
+    if (!readback) {
+        logger.warn("Brand client secret was written but could not be read back. Subsequent calls may need a re-login.", "yellow");
+    }
+    logger.info(`Brand credential saved for org '${orgId}'.`, "green");
+    logger.info(`Scopes granted: ${grantedScopes.join(", ") || "(none)"}`);
+    if (knownMissing.length > 0) {
+        logger.warn(`Scopes NOT on this key: ${knownMissing.join(", ")}. Operations that need these will refuse.`, "yellow");
+    }
+    if (!hasReviewScope) {
+        logger.warn("  → `scai brand review` needs `ai.org.br:gen`. Recreate the AI APIs key in Cloud Portal with that scope enabled.", "yellow");
+    }
+};
+exports.runBrandLogin = runBrandLogin;

package/dist/brand/tasks/review.d.ts

@@ -0,0 +1,111 @@
+import type { CommonOptions } from "../../shared/cli-options";
+import type { BrandReviewScore, BrandReviewSectionSelector } from "../api/types";
+import { type ReviewOutcome } from "../review/outcomes";
+import { type BrandReviewJsonReport } from "../review/format-json";
+import { type SarifReport } from "../review/format-sarif";
+export type BrandReviewFormat = "text" | "json" | "sarif";
+export interface BrandReviewCommandOptions extends CommonOptions {
+    environmentName?: string;
+    /** Override the orgId resolved from the active env profile. */
+    orgId?: string;
+    /** Positional file paths to review. Mixed with `--glob` results. */
+    inputs?: string[];
+    /** Glob pattern(s) relative to the project root. */
+    glob?: string[];
+    /** Brand kit ID to evaluate against. Required for v1. */
+    kit?: string;
+    /**
+     * Restrict the review to these brand kit section UUIDs. Each value
+     * may be a bare section UUID, or `<sectionId>:<fieldId>` to narrow
+     * to a specific subsection within that section. Section names
+     * (e.g. "Tone of Voice") are NOT accepted — name lookup lands when
+     * the Brand Management read primitives ship.
+     */
+    sectionId?: string[];
+    /** 1–5; exit non-zero if any score is below this. */
+    threshold?: number;
+    /** Parallel in-flight reviews. Defaults to 4. */
+    concurrency?: number;
+    /** Stop scheduling on first failure (in-flight still drain). */
+    failFast?: boolean;
+    /** Output format. Defaults to `text`. */
+    format?: BrandReviewFormat;
+    /** Write the formatted report to a file instead of stdout. */
+    output?: string;
+    /** Max files to review without `--force`. Defaults to 1000. */
+    limit?: number;
+    /** Bypass the `--limit` guardrail. */
+    force?: boolean;
+    /** Print the resolved file list + count and exit without calling the API. */
+    whatIf?: boolean;
+}
+export interface BrandReviewRunResult {
+    outcomes: ReviewOutcome[];
+    exitCode: number;
+    /** What scai _wrote_ — useful for tests and JSON-mode callers. */
+    report?: string;
+    json?: BrandReviewJsonReport;
+    sarif?: SarifReport;
+}
+/**
+ * Detect a file's content-format hint from its extension. The Brand
+ * Review API uses a flexible `input` map and doesn't surface a
+ * format-discriminator field today — this helper exists for callers
+ * that want a stable categorization (e.g. logging, future routing of
+ * `.json` content through an `ExtractableFile` reference instead of
+ * raw text). Returns one of `"text" | "markdown" | "json"`.
+ */
+export type InputFormatHint = "text" | "markdown" | "json";
+export declare const detectInputFormat: (filePath: string) => InputFormatHint;
+/**
+ * Parse CLI `--section-id` values into the Brand Review API's
+ * `Section[]` selector shape.
+ *
+ * Each value is either:
+ *   - `<sectionId>`              → section-level evaluation
+ *   - `<sectionId>:<fieldId>`    → field-level evaluation (multiple
+ *                                  `--section-id <sectionId>:<a>`
+ *                                  occurrences merge into one
+ *                                  `Section` entry)
+ *
+ * Multiple values for the same sectionId accumulate into the
+ * section's `fieldIds[]`. An empty / undefined input list returns
+ * `undefined` (= API evaluates every section).
+ */
+export declare const parseSectionSelectors: (raw: readonly string[] | undefined) => BrandReviewSectionSelector[] | undefined;
+/**
+ * Resolve positional file paths + glob patterns to a deduplicated,
+ * sorted list of absolute file paths. Resolution rules:
+ *
+ *   - Positional paths must exist; if any are missing the call
+ *     errors with INPUT_INVALID listing the missing entries.
+ *   - Glob patterns expand relative to `cwd`.
+ *   - Duplicates across positional+glob are removed.
+ *   - Directories and non-files are filtered out — Brand Review
+ *     operates on file content, not directory listings.
+ *
+ * Returns the resolved files in input order (positionals first,
+ * then glob hits in their natural order).
+ */
+export declare const resolveReviewInputs: (positionals: readonly string[], globs: readonly string[], cwd: string) => Promise<string[]>;
+/**
+ * Compute the CLI exit code for a batch review run.
+ *
+ *   0  → no API errors and no scores below threshold
+ *   1  → threshold violated by at least one file
+ *   7  → at least one API call failed (`BRAND_API_FAILED`)
+ *
+ * Threshold violations and API errors can co-occur — when both fire,
+ * the threshold violation wins (1) so CI failure modes are
+ * distinguishable from infrastructure failures.
+ */
+export declare const computeExitCode: (outcomes: readonly ReviewOutcome[], threshold: BrandReviewScore | undefined) => number;
+/**
+ * Run a batch Brand Review.
+ *
+ * The CLI verb is a thin wrapper around this — pass the same options
+ * and inspect the returned `BrandReviewRunResult` to drive exit
+ * codes, stdout writes, or downstream tooling. SDK consumers should
+ * use this directly (exported through `@sitecoreai-labs/sitecoreai-cli/unstable/brand`).
+ */
+export declare const runBrandReview: (options: BrandReviewCommandOptions) => Promise<BrandReviewRunResult>;