@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/commands/brand/kits.js

@@ -0,0 +1,361 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBrandKitsCommand = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const commander_1 = require("commander");
+const shared_1 = require("../shared");
+const brand_1 = require("../../brand");
+const credential_1 = require("../../brand/credential");
+const cli_tasks_1 = require("../../shared/cli-tasks");
+const writeJson = (value) => {
+    process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+};
+const createListKitsCommand = () => {
+    const command = new commander_1.Command("list")
+        .description("List brand kits in the active organization.")
+        .addOption(new commander_1.Option("--page-number <n>", "1-based page number"))
+        .addOption(new commander_1.Option("--page-size <n>", "Items per page"))
+        .addOption(new commander_1.Option("--format <kind>", "Output format").choices(["text", "json"]).default("text"));
+    (0, shared_1.addEnvironmentOption)(command);
+    (0, shared_1.addConfigOption)(command);
+    (0, shared_1.addVerbosityOptions)(command);
+    command.addOption(new commander_1.Option("--org-id <id>", "Override orgId from env profile"));
+    command.action(async (options) => {
+        const logger = (0, cli_tasks_1.toLogger)(options);
+        const client = (0, credential_1.resolveBrandClient)(options);
+        const response = await (0, brand_1.listBrandKits)({
+            client,
+            pageNumber: options.pageNumber ? Number(options.pageNumber) : undefined,
+            pageSize: options.pageSize ? Number(options.pageSize) : undefined,
+        });
+        if (options.format === "json") {
+            writeJson(response);
+            return;
+        }
+        logger.info(`${response.totalCount} kit(s) (page ${response.pageNumber ?? 1}, size ${response.pageSize ?? response.data.length})`);
+        for (const kit of response.data) {
+            logger.info(`  ${kit.id}  ${kit.name ?? "(unnamed)"}  [${kit.status ?? "?"}]${kit.industry ? `  ${kit.industry}` : ""}`);
+        }
+    });
+    return command;
+};
+const createGetKitCommand = () => {
+    const command = new commander_1.Command("get")
+        .description("Retrieve a single brand kit by ID.")
+        .argument("<kitId>", "Brand kit UUID")
+        .addOption(new commander_1.Option("--format <kind>", "Output format").choices(["text", "json"]).default("text"));
+    (0, shared_1.addEnvironmentOption)(command);
+    (0, shared_1.addConfigOption)(command);
+    (0, shared_1.addVerbosityOptions)(command);
+    command.addOption(new commander_1.Option("--org-id <id>", "Override orgId from env profile"));
+    command.action(async (kitId, options) => {
+        const logger = (0, cli_tasks_1.toLogger)(options);
+        const client = (0, credential_1.resolveBrandClient)(options);
+        const kit = await (0, brand_1.getBrandKit)({ client, brandKitId: kitId });
+        if (options.format === "json") {
+            writeJson(kit);
+            return;
+        }
+        logger.info(`${kit.name ?? "(unnamed)"} — ${kit.id}`);
+        logger.info(`  status:      ${kit.status ?? "?"}`);
+        if (kit.industry)
+            logger.info(`  industry:    ${kit.industry}`);
+        if (kit.brandName && kit.brandName !== kit.name)
+            logger.info(`  brand name:  ${kit.brandName}`);
+        if (kit.description)
+            logger.info(`  description: ${kit.description}`);
+        if (kit.createdOn)
+            logger.info(`  created:     ${kit.createdOn}`);
+        if (kit.updatedOn)
+            logger.info(`  updated:     ${kit.updatedOn}`);
+    });
+    return command;
+};
+const createSectionsCommand = () => {
+    const command = new commander_1.Command("sections")
+        .description("List section names + IDs of a brand kit.")
+        .argument("<kitId>", "Brand kit UUID")
+        .addOption(new commander_1.Option("--format <kind>", "Output format").choices(["text", "json"]).default("text"));
+    (0, shared_1.addEnvironmentOption)(command);
+    (0, shared_1.addConfigOption)(command);
+    (0, shared_1.addVerbosityOptions)(command);
+    command.addOption(new commander_1.Option("--org-id <id>", "Override orgId from env profile"));
+    command.action(async (kitId, options) => {
+        const logger = (0, cli_tasks_1.toLogger)(options);
+        const client = (0, credential_1.resolveBrandClient)(options);
+        const sections = await (0, brand_1.listBrandKitSections)({ client, brandKitId: kitId });
+        if (options.format === "json") {
+            writeJson(sections);
+            return;
+        }
+        if (sections.length === 0) {
+            logger.info(`No sections yet — kit needs BrandIngestion + EnrichSections pipelines to populate.`);
+            return;
+        }
+        logger.info(`${sections.length} section(s):`);
+        const nameW = Math.max(...sections.map((s) => (s.name ?? "").length));
+        for (const s of sections.sort((a, b) => (a.order ?? 0) - (b.order ?? 0))) {
+            const order = s.order !== undefined ? `${s.order}.` : " ";
+            logger.info(`  ${order.padStart(3)} ${(s.name ?? "(unnamed)").padEnd(nameW)}  ${s.id}`);
+        }
+    });
+    return command;
+};
+const createFieldsCommand = () => {
+    const command = new commander_1.Command("fields")
+        .description("List subsections (fields) within a section.")
+        .argument("<kitId>", "Brand kit UUID")
+        .argument("<sectionId>", "Section UUID")
+        .addOption(new commander_1.Option("--format <kind>", "Output format").choices(["text", "json"]).default("text"));
+    (0, shared_1.addEnvironmentOption)(command);
+    (0, shared_1.addConfigOption)(command);
+    (0, shared_1.addVerbosityOptions)(command);
+    command.addOption(new commander_1.Option("--org-id <id>", "Override orgId from env profile"));
+    command.action(async (kitId, sectionId, options) => {
+        const logger = (0, cli_tasks_1.toLogger)(options);
+        const client = (0, credential_1.resolveBrandClient)(options);
+        const fields = await (0, brand_1.listBrandKitFields)({
+            client,
+            brandKitId: kitId,
+            sectionId,
+        });
+        if (options.format === "json") {
+            writeJson(fields);
+            return;
+        }
+        if (fields.length === 0) {
+            logger.info("No fields in this section.");
+            return;
+        }
+        logger.info(`${fields.length} field(s):`);
+        for (const f of fields.sort((a, b) => (a.order ?? 0) - (b.order ?? 0))) {
+            const order = f.order !== undefined ? `${f.order}.` : " ";
+            const ai = f.aiEditable ? "ai" : "  ";
+            logger.info(`  ${order.padStart(3)} ${ai} ${f.name ?? "(unnamed)"}  ${f.id}`);
+            if (f.intent) {
+                logger.info(`       intent: ${f.intent}`);
+            }
+            if (f.value !== undefined && f.value !== "") {
+                const preview = typeof f.value === "string"
+                    ? f.value.length > 200
+                        ? `${f.value.slice(0, 200)}…`
+                        : f.value
+                    : Array.isArray(f.value)
+                        ? f.value.length === 0
+                            ? "(empty array)"
+                            : `(${f.value.length} entries) ${f.value
+                                .slice(0, 3)
+                                .map((e) => e.name)
+                                .join(" · ")}${f.value.length > 3 ? " · …" : ""}`
+                        : "(non-string value)";
+                logger.info(`       value:  ${preview}`);
+            }
+        }
+    });
+    return command;
+};
+const createCreateKitCommand = () => {
+    const command = new commander_1.Command("create")
+        .description("Create a new brand kit. Lands in draft until published.")
+        .argument("<name>", "Display name for the kit")
+        .addOption(new commander_1.Option("--description <text>", "Human description"))
+        .addOption(new commander_1.Option("--industry <label>", "Industry label"))
+        .addOption(new commander_1.Option("--brand-name <name>", "Brand name (defaults to display name)"))
+        .addOption(new commander_1.Option("--company-name <name>", "Company name (if different)"))
+        .addOption(new commander_1.Option("--logo <url>", "PNG logo URL"))
+        .addOption(new commander_1.Option("--format <kind>", "Output format").choices(["text", "json"]).default("text"));
+    (0, shared_1.addEnvironmentOption)(command);
+    (0, shared_1.addConfigOption)(command);
+    (0, shared_1.addVerbosityOptions)(command);
+    command.addOption(new commander_1.Option("--org-id <id>", "Override orgId from env profile"));
+    command.action(async (name, options) => {
+        const logger = (0, cli_tasks_1.toLogger)(options);
+        const client = (0, credential_1.resolveBrandClient)(options);
+        const kit = await (0, brand_1.createBrandKit)({
+            client,
+            name,
+            description: options.description,
+            industry: options.industry,
+            brandName: options.brandName,
+            companyName: options.companyName,
+            logo: options.logo,
+        });
+        if (options.format === "json") {
+            writeJson(kit);
+            return;
+        }
+        logger.info(`Created kit ${kit.id}`, "green");
+        logger.info(`  status:   ${kit.status ?? "?"}`);
+        logger.info(`  name:     ${kit.name}`);
+        if (kit.industry)
+            logger.info(`  industry: ${kit.industry}`);
+        logger.info(`\nNext: publish + ingest with \`scai brand seed\` or run the individual steps manually.`);
+    });
+    return command;
+};
+const createPublishKitCommand = () => {
+    const command = new commander_1.Command("publish")
+        .description("Mark a brand kit as published. Required before pipelines populate sections.")
+        .argument("<kitId>", "Brand kit UUID")
+        .addOption(new commander_1.Option("--format <kind>", "Output format").choices(["text", "json"]).default("text"));
+    (0, shared_1.addEnvironmentOption)(command);
+    (0, shared_1.addConfigOption)(command);
+    (0, shared_1.addVerbosityOptions)(command);
+    command.addOption(new commander_1.Option("--org-id <id>", "Override orgId from env profile"));
+    command.action(async (kitId, options) => {
+        const logger = (0, cli_tasks_1.toLogger)(options);
+        const client = (0, credential_1.resolveBrandClient)(options);
+        const kit = await (0, brand_1.publishBrandKit)({ client, brandKitId: kitId });
+        if (options.format === "json") {
+            writeJson(kit);
+            return;
+        }
+        logger.info(`Kit ${kit.id} is now ${kit.status}.`, "green");
+    });
+    return command;
+};
+const createDeleteKitCommand = () => {
+    const command = new commander_1.Command("delete")
+        .description("Delete a brand kit. Destructive — requires --force or interactive confirmation.")
+        .argument("<kitId>", "Brand kit UUID")
+        .addOption(new commander_1.Option("-f, --force", "Skip the confirmation prompt"));
+    (0, shared_1.addEnvironmentOption)(command);
+    (0, shared_1.addConfigOption)(command);
+    (0, shared_1.addVerbosityOptions)(command);
+    command.addOption(new commander_1.Option("--org-id <id>", "Override orgId from env profile"));
+    command.action(async (kitId, options) => {
+        const logger = (0, cli_tasks_1.toLogger)(options);
+        const client = (0, credential_1.resolveBrandClient)(options);
+        // Show what we're about to delete.
+        const kit = await (0, brand_1.getBrandKit)({ client, brandKitId: kitId });
+        logger.info(`About to delete: ${kit.name} (${kit.id}) [${kit.status}]`);
+        const proceed = await (0, cli_tasks_1.confirmDestructive)(`Delete brand kit '${kit.name}' (${kit.id})?`, options.force);
+        if (!proceed) {
+            logger.info("Aborted.");
+            return;
+        }
+        await (0, brand_1.deleteBrandKit)({ client, brandKitId: kitId });
+        logger.info(`Deleted kit ${kitId}.`, "green");
+    });
+    return command;
+};
+/**
+ * Parse a `value` argument for `set-field`. The CLI accepts three
+ * forms, in order of precedence:
+ *   1. `--value-file <path>` — read raw text from disk (best for
+ *      multi-line content; the file is treated as a UTF-8 string).
+ *   2. `--value-json <json>` — parsed as JSON. Right shape for
+ *      `array` and `richArray` fields (passing a JSON array).
+ *   3. `--value <text>` — inline string (best for short `text` fields).
+ *
+ * Exactly one must be set; passing zero or multiple is a user error.
+ */
+const parseFieldValueArg = (options) => {
+    const provided = [
+        options.value !== undefined ? "--value" : null,
+        options.valueJson !== undefined ? "--value-json" : null,
+        options.valueFile !== undefined ? "--value-file" : null,
+    ].filter((x) => x !== null);
+    if (provided.length === 0) {
+        throw (0, cli_tasks_1.inputError)("No field value supplied.", "Pass --value <text> for text fields, --value-json '<json>' for array/richArray fields, or --value-file <path>.");
+    }
+    if (provided.length > 1) {
+        throw (0, cli_tasks_1.inputError)(`Multiple value sources passed: ${provided.join(", ")}.`, "Pick one of --value, --value-json, --value-file.");
+    }
+    if (options.valueFile !== undefined) {
+        if (!node_fs_1.default.existsSync(options.valueFile)) {
+            throw (0, cli_tasks_1.inputError)(`Value file not found: ${options.valueFile}.`);
+        }
+        return node_fs_1.default.readFileSync(options.valueFile, "utf8");
+    }
+    if (options.valueJson !== undefined) {
+        try {
+            return JSON.parse(options.valueJson);
+        }
+        catch (err) {
+            throw (0, cli_tasks_1.inputError)(`Failed to parse --value-json: ${err instanceof Error ? err.message : String(err)}.`, 'Example for array fields: --value-json \'[{"name":"First entry"},{"name":"Second"}]\'');
+        }
+    }
+    return options.value;
+};
+const createSetFieldCommand = () => {
+    const command = new commander_1.Command("set-field")
+        .description("Directly write a brand kit subsection (field) value, bypassing the AI enrichment pipeline.")
+        .argument("<kitId>", "Brand kit UUID")
+        .argument("<sectionId>", "Section UUID (from `scai brand kits sections <kitId>`)")
+        .argument("<fieldId>", "Field UUID (from `scai brand kits fields <kitId> <sectionId>`)")
+        .addOption(new commander_1.Option("--value <text>", "Inline text value (for `text` fields)"))
+        .addOption(new commander_1.Option("--value-json <json>", "JSON-encoded value (for `array` / `richArray` fields)"))
+        .addOption(new commander_1.Option("--value-file <path>", "Read value text from this file"))
+        .addOption(new commander_1.Option("--verified", "Mark the field as operator-verified"))
+        .addOption(new commander_1.Option("--no-verified", "Clear the verified flag"))
+        .addOption(new commander_1.Option("--ai-editable", "Allow the enrichment pipeline to overwrite this field"))
+        .addOption(new commander_1.Option("--no-ai-editable", "Lock the field against pipeline overwrites"))
+        .addOption(new commander_1.Option("--intent <text>", "Update the AI-facing intent string"))
+        .addOption(new commander_1.Option("--format <kind>", "Output format").choices(["text", "json"]).default("text"));
+    (0, shared_1.addEnvironmentOption)(command);
+    (0, shared_1.addConfigOption)(command);
+    (0, shared_1.addVerbosityOptions)(command);
+    command.addOption(new commander_1.Option("--org-id <id>", "Override orgId from env profile"));
+    command.action(async (kitId, sectionId, fieldId, options) => {
+        const logger = (0, cli_tasks_1.toLogger)(options);
+        const client = (0, credential_1.resolveBrandClient)(options);
+        const value = parseFieldValueArg(options);
+        const updated = await (0, brand_1.updateBrandKitField)({
+            client,
+            brandKitId: kitId,
+            sectionId,
+            fieldId,
+            value,
+            verified: options.verified,
+            aiEditable: options.aiEditable,
+            intent: options.intent,
+        });
+        if (options.format === "json") {
+            writeJson(updated);
+            return;
+        }
+        logger.info(`Updated field ${updated.name} (${updated.id}).`, "green");
+        logger.info(`  type:     ${updated.type ?? "?"}`);
+        logger.info(`  verified: ${updated.verified === true ? "true" : "false"}`);
+        const preview = typeof updated.value === "string"
+            ? updated.value.length > 200
+                ? `${updated.value.slice(0, 200)}…`
+                : updated.value
+            : `(${Array.isArray(updated.value) ? `${updated.value.length} entries` : "object"})`;
+        logger.info(`  value:    ${preview}`);
+    });
+    return command;
+};
+/**
+ * `scai brand kits …` — both read- and write-side brand kit operations.
+ *   - `list`      : org-wide kit list
+ *   - `get`       : single kit by ID
+ *   - `sections`  : list sections (name + ID) of a kit
+ *   - `fields`    : list subsections within a section
+ *   - `create`    : create a new draft kit
+ *   - `publish`   : mark a kit as published (required for pipelines)
+ *   - `set-field` : direct PATCH of a field value (the fallback for
+ *     AI-generated kits whose PDF didn't survive Sitecore's parser —
+ *     see `scai://help/brand-kit-generation`)
+ *   - `delete`    : remove a kit (destructive; `-f` to skip prompt)
+ *
+ * All read commands support `--format text|json`. Use `--format json`
+ * for machine-readable output when piping into other tools.
+ */
+const createBrandKitsCommand = () => {
+    const command = new commander_1.Command("kits").description("Brand kit operations (list, get, sections, fields, create, publish, set-field, delete).");
+    command.addCommand(createListKitsCommand());
+    command.addCommand(createGetKitCommand());
+    command.addCommand(createSectionsCommand());
+    command.addCommand(createFieldsCommand());
+    command.addCommand(createCreateKitCommand());
+    command.addCommand(createPublishKitCommand());
+    command.addCommand(createSetFieldCommand());
+    command.addCommand(createDeleteKitCommand());
+    return command;
+};
+exports.createBrandKitsCommand = createBrandKitsCommand;

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

@@ -0,0 +1,13 @@
+import { Command } from "commander";
+/**
+ * `scai brand review <files...>` — evaluate file content against a
+ * Sitecore brand kit. Streams text rows as files complete,
+ * or aggregates into JSON / SARIF for `--format` consumers. The
+ * SARIF + `--threshold` combination is the headline CI gate.
+ *
+ * Cost note: every reviewed file is one paid AI inference call. The
+ * `--limit` guardrail (default 1000) prevents accidental fan-out
+ * against a giant repo; pass `--force` to override after seeing the
+ * `--what-if` projection.
+ */
+export declare const createBrandReviewCommand: () => Command;

package/dist/commands/brand/review.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBrandReviewCommand = void 0;
+const commander_1 = require("commander");
+const shared_1 = require("../shared");
+const review_1 = require("../../brand/tasks/review");
+const parseInt5 = (value) => {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed)) {
+        throw new Error(`Invalid integer: ${value}`);
+    }
+    return parsed;
+};
+/**
+ * `scai brand review <files...>` — evaluate file content against a
+ * Sitecore brand kit. Streams text rows as files complete,
+ * or aggregates into JSON / SARIF for `--format` consumers. The
+ * SARIF + `--threshold` combination is the headline CI gate.
+ *
+ * Cost note: every reviewed file is one paid AI inference call. The
+ * `--limit` guardrail (default 1000) prevents accidental fan-out
+ * against a giant repo; pass `--force` to override after seeing the
+ * `--what-if` projection.
+ */
+const createBrandReviewCommand = () => {
+    const command = new commander_1.Command("review")
+        .description("Evaluate file content against a Sitecore brand kit. Streams text, or aggregates into JSON / SARIF.")
+        .argument("[files...]", "Files to review. Mixed with --glob results.");
+    (0, shared_1.addEnvironmentOption)(command);
+    (0, shared_1.addConfigOption)(command);
+    (0, shared_1.addVerbosityOptions)(command);
+    command
+        .addOption(new commander_1.Option("--org-id <id>", "Override the orgId resolved from the env profile."))
+        .addOption(new commander_1.Option("--kit <id>", "Brand kit ID to evaluate against.").makeOptionMandatory(false))
+        .addOption(new commander_1.Option("--section-id <id>", "Restrict to a section UUID (repeatable, comma-separated). Use <sectionId>:<fieldId> to narrow to a subsection. List section IDs with the Brand Management API.").argParser(shared_1.collectList))
+        .addOption(new commander_1.Option("--glob <pattern>", "Glob pattern(s) to expand").argParser(shared_1.collectList))
+        .addOption(new commander_1.Option("--threshold <score>", "Fail (exit 1) if any score is below this value (1–5).").argParser(parseInt5))
+        .addOption(new commander_1.Option("--concurrency <n>", "Parallel in-flight reviews (default 4)").argParser(parseInt5))
+        .addOption(new commander_1.Option("--fail-fast", "Stop scheduling on first failure (in-flight requests drain)."))
+        .addOption(new commander_1.Option("--format <kind>", "Output format")
+        .choices(["text", "json", "sarif"])
+        .default("text"))
+        .addOption(new commander_1.Option("--output <path>", "Write the report to this file instead of stdout."))
+        .addOption(new commander_1.Option("--limit <n>", "Maximum files to review without --force (default 1000)").argParser(parseInt5))
+        .addOption(new commander_1.Option("--force", "Bypass the --limit guardrail"))
+        .addOption(new commander_1.Option("--what-if", "Print the resolved file list + count and exit without calling the API."));
+    command.addHelpText("after", "\nExamples:\n" +
+        "  $ scai brand review content/about.md --kit <kitId>\n" +
+        "  $ scai brand review --glob 'content/**/*.md' --kit <kitId> --threshold 4\n" +
+        "  $ scai brand review --glob 'content/**/*.md' --kit <kitId> --threshold 4 \\\n" +
+        "      --format sarif --output brand.sarif\n" +
+        "\nCI gate (GitHub Actions):\n" +
+        "  - run: scai brand review --glob 'content/**/*.md' --kit <kitId> \\\n" +
+        "         --threshold 4 --format sarif --output brand.sarif\n" +
+        "  - uses: github/codeql-action/upload-sarif@v3\n" +
+        "    with: { sarif_file: brand.sarif }\n");
+    command.action(async (files, flags) => {
+        const result = await (0, review_1.runBrandReview)({ ...flags, inputs: files ?? [] });
+        if (result.exitCode !== 0) {
+            process.exitCode = result.exitCode;
+        }
+    });
+    return command;
+};
+exports.createBrandReviewCommand = createBrandReviewCommand;

package/dist/commands/brand/seed.d.ts

@@ -0,0 +1,9 @@
+import { Command } from "commander";
+/**
+ * `scai brand seed` — create a brand kit, either:
+ *   - `--url <pdf>`  : the full ingest + enrich pipeline on a hosted
+ *                      PDF ([[project-scai-brand-kit-seed-recipe]]).
+ *   - `--file <json>`: a kit-shaped recipe applied directly (no PDF,
+ *                      no AI pipeline) — round-trips with `sync pull`.
+ */
+export declare const createBrandSeedCommand: () => Command;

package/dist/commands/brand/seed.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBrandSeedCommand = void 0;
+const commander_1 = require("commander");
+const shared_1 = require("../shared");
+const root_config_1 = require("../../config/root-config");
+const brand_1 = require("../../brand");
+const credential_1 = require("../../brand/credential");
+const recipe_1 = require("../../brand/recipe");
+const sync_1 = require("../../sync");
+const cli_tasks_1 = require("../../shared/cli-tasks");
+/**
+ * `--url` path: drive a brand kit from "doesn't exist" to "has
+ * populated sections" by running the full ingest + enrich pipeline on
+ * a hosted PDF. Triggers two paid AI pipeline runs (~5–15 min).
+ */
+const seedFromUrl = async (options, logger) => {
+    if (!options.name) {
+        throw (0, cli_tasks_1.inputError)("--name is required when seeding from --url.");
+    }
+    const client = (0, credential_1.resolveBrandClient)(options);
+    const source = { url: options.url ?? "" };
+    const onProgress = (event) => {
+        if (options.format === "json") {
+            // Streaming progress to stderr keeps stdout clean for the
+            // final JSON payload.
+            process.stderr.write(`${JSON.stringify({ ...event, ts: new Date().toISOString() })}\n`);
+        }
+        else {
+            logger.info(`[+${event.elapsedSec.toString().padStart(3)}s] ${event.stage}: ${event.message}`);
+        }
+    };
+    const result = await (0, brand_1.seedBrandKit)({
+        client,
+        name: options.name,
+        source,
+        description: options.description,
+        industry: options.industry,
+        pollIntervalSec: options.pollIntervalSec ? Number(options.pollIntervalSec) : undefined,
+        timeoutSec: options.timeoutSec ? Number(options.timeoutSec) : undefined,
+        onProgress,
+    });
+    if (options.format === "json") {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+        return;
+    }
+    logger.info(`\n✓ Seeded kit ${result.kit.id} in ${result.elapsedSec}s`, "green");
+    logger.info(`  ${result.sections.length} section(s):`);
+    for (const s of result.sections.sort((a, b) => (a.order ?? 0) - (b.order ?? 0))) {
+        logger.info(`    ${s.order ?? "?"}. ${s.name}`);
+    }
+    logger.info(`\nReady for Brand Review. Try:\n  scai brand review <file.md> --kit ${result.kit.id} --threshold 4`);
+};
+/**
+ * `--file` path: seed a kit straight from a kit-shaped recipe file —
+ * the same `BrandKitRecipe` shape `brand sync pull` emits and
+ * `brand sync push` consumes. No PDF, no AI pipeline: the recipe's
+ * section content is written directly via the converge engine. A kit
+ * named after the recipe is created if absent, or updated to match.
+ */
+const seedFromFile = async (options, logger) => {
+    const configPath = options.config ?? process.cwd();
+    // Resolve a concrete env name for the sync context — explicit flag,
+    // configured default, or the sole env profile. The sync engine's
+    // brand-client resolver needs a real environment, not the phantom
+    // "default" that an unset defaultEnvProfile would otherwise yield.
+    const { envName } = (0, root_config_1.resolveActiveEnvironment)(configPath, options.environmentName);
+    const ctx = {
+        environmentName: envName,
+        configPath,
+        logger,
+    };
+    const recipe = (0, sync_1.loadRecipe)(options.file ?? "", recipe_1.brandKitKind.schema);
+    const outcome = await (0, sync_1.syncPush)(recipe_1.brandKitKind, recipe, { kind: recipe_1.brandKitKind.name, id: recipe.name }, ctx, { mode: "apply", prune: false });
+    if (options.format === "json") {
+        process.stdout.write(JSON.stringify({ recipe: recipe.name, plan: outcome.plan, result: outcome.result }, null, 2) +
+            "\n");
+        return;
+    }
+    if (outcome.result) {
+        logger.info(`✓ Seeded kit '${recipe.name}' from ${options.file} — ` +
+            `${outcome.result.applied.length} change(s) applied, ${outcome.result.skipped.length} skipped.`, "green");
+    }
+    else {
+        logger.info(`Kit '${recipe.name}' already matches ${options.file} — nothing to do.`, "green");
+    }
+};
+/**
+ * `scai brand seed` — create a brand kit, either:
+ *   - `--url <pdf>`  : the full ingest + enrich pipeline on a hosted
+ *                      PDF ([[project-scai-brand-kit-seed-recipe]]).
+ *   - `--file <json>`: a kit-shaped recipe applied directly (no PDF,
+ *                      no AI pipeline) — round-trips with `sync pull`.
+ */
+const createBrandSeedCommand = () => {
+    const command = new commander_1.Command("seed")
+        .description("Create a brand kit — from a PDF (--url, full ingest+enrich pipeline, ~5–15 min) " +
+        "or from a kit-shaped recipe file (--file, applied directly).")
+        .addOption(new commander_1.Option("--name <name>", "Display name for the new kit (required with --url)"))
+        .addOption(new commander_1.Option("--url <url>", "Public HTTPS URL to a PDF Sitecore's edge can reach"))
+        .addOption(new commander_1.Option("--file <path>", "Kit-shaped recipe file (.yaml / .json) — the `sync pull` shape"))
+        .addOption(new commander_1.Option("--description <text>", "Kit description (--url path only)"))
+        .addOption(new commander_1.Option("--industry <label>", "Industry label (--url path only)"))
+        .addOption(new commander_1.Option("--poll-interval-sec <n>", "Section poll interval in seconds (default 15)"))
+        .addOption(new commander_1.Option("--timeout-sec <n>", "Max seconds to wait for sections to populate (default 900 / 15min)"))
+        .addOption(new commander_1.Option("--format <kind>", "Output format").choices(["text", "json"]).default("text"));
+    (0, shared_1.addEnvironmentOption)(command);
+    (0, shared_1.addConfigOption)(command);
+    (0, shared_1.addVerbosityOptions)(command);
+    command.addOption(new commander_1.Option("--org-id <id>", "Override orgId from env profile"));
+    command.addHelpText("after", [
+        "",
+        "Examples:",
+        "  $ scai brand seed --name 'Acme' --url https://acme.example/brand.pdf",
+        "  $ scai brand seed --file acme.brandkit.yaml",
+        "",
+        "`--file` takes the same recipe `scai brand sync pull` writes — the two round-trip.",
+        "",
+    ].join("\n"));
+    command.action(async (options) => {
+        const logger = (0, cli_tasks_1.toLogger)(options);
+        if (options.url && options.file) {
+            throw (0, cli_tasks_1.inputError)("Pass either --url (PDF) or --file (kit recipe), not both.");
+        }
+        if (options.file) {
+            await seedFromFile(options, logger);
+            return;
+        }
+        if (!options.url) {
+            throw (0, cli_tasks_1.inputError)("A source is required: --url <pdfUrl> for the ingest pipeline, or --file <kit.json>.", "scai brand seed --name <name> --url <pdfUrl>   |   scai brand seed --file <kit.json>");
+        }
+        await seedFromUrl(options, logger);
+    });
+    return command;
+};
+exports.createBrandSeedCommand = createBrandSeedCommand;

package/dist/commands/brand/sync.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `scai brand sync` — pull, diff, and push a brand kit as a declarative
+ * recipe. The recipe / sync model — see docs/recipe-sync-architecture.md.
+ *
+ *   pull  capture a live brand kit into a recipe file
+ *   diff  show the plan to converge a kit onto a recipe
+ *   push  apply that plan (dry-run unless --allow-write)
+ */
+import { Command } from "commander";
+/** `scai brand sync` — the recipe pull / diff / push verbs for brand kits. */
+export declare const createBrandSyncCommand: () => Command;