@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/commands/shared.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.addPackageInstallOptions = exports.addPackageCreateOptions = exports.addValidateOptions = exports.addDiffOptions = exports.addExplainOptions = exports.addAllowFileChangesOption = exports.addSkipPullOption = exports.addPublishOptions = exports.addUseDebugSignaturesOption = exports.addForceOption = exports.addSkipValidationOption = exports.addWhatIfOption = exports.addIncludeExcludeOptions = exports.addAllowWriteOption = exports.addVerbosityOptions = exports.addEnvironmentOption = exports.addConfigOption = exports.normalizeArgs = exports.collectList = void 0;
+exports.addPackageInstallOptions = exports.addPackageCreateOptions = exports.addValidateOptions = exports.addDiffOptions = exports.addExplainOptions = exports.addAllowFileChangesOption = exports.addSkipPullOption = exports.addPublishOptions = exports.addUseDebugSignaturesOption = exports.addForceOption = exports.addSkipValidationOption = exports.markUnstable = exports.withApplyGate = exports.addApplyOption = exports.addWhatIfOption = exports.addIncludeExcludeOptions = exports.addAllowWriteOption = exports.addVerbosityOptions = exports.addOrgScopeOptions = exports.addEnvironmentOption = exports.addConfigOption = exports.normalizeArgs = exports.collectList = void 0;
 const commander_1 = require("commander");
 const splitComma = (value) => value
     .split(",")
@@ -8,30 +8,81 @@ const splitComma = (value) => value
     .filter((entry) => entry.length > 0);
 const collectList = (value, previous = []) => previous.concat(splitComma(value));
 exports.collectList = collectList;
-const normalizeArgs = (argv) => argv.map((arg) => {
-    if (arg === "-fr") {
-        return "--force";
-    }
-    if (arg === "--env" || arg === "--env-name") {
-        return "--environment-name";
-    }
-    if (arg === "-q") {
-        return "--quiet";
-    }
-    return arg;
-});
+const normalizeArgs = (argv) => {
+    // Drop a leading `--` separator (argv[2]). `pnpm dev -- <subcmd> ...`
+    // injects a literal `--` before the subcommand; commander then treats
+    // it as an end-of-options marker for the root program and routes
+    // every subsequent flag (e.g. `--what-if`) into positional args
+    // instead of parsing them. The separator carries no scai-level
+    // meaning, so strip it before commander sees it. Position 2 only:
+    // `--` later in argv (e.g. for a hypothetical pass-through arg) is
+    // preserved.
+    const cleaned = argv[2] === "--" ? [...argv.slice(0, 2), ...argv.slice(3)] : argv;
+    return cleaned.map((arg) => {
+        if (arg === "-fr") {
+            return "--force";
+        }
+        if (arg === "--env" || arg === "--env-name") {
+            return "--environment-name";
+        }
+        if (arg === "-q") {
+            return "--quiet";
+        }
+        // `ser diff` aliases that match dotnet `Sitecore.DevEx`
+        // `ser diff --source-env / --target-env [--push]`.
+        if (arg === "--source-env") {
+            return "--source";
+        }
+        if (arg === "--target-env") {
+            return "--destination";
+        }
+        return arg;
+    });
+};
 exports.normalizeArgs = normalizeArgs;
-const addConfigOption = (command) => command.addOption(new commander_1.Option("-c, --config <path>", "Path to a sitecoreai.cli.json file, or a directory containing one (walks up if not in the dir itself).").default(process.cwd()));
+const addConfigOption = (command) => command.addOption(new commander_1.Option("-c, --config <path>", "Path to a sitecoreai.cli.json file, or a directory containing one (walks up if not in the dir itself).")
+    // Second arg is the help-text label for the default. Without it
+    // Commander prints the resolved absolute cwd into `--help`, which
+    // is noise (and machine-specific). The runtime value is still
+    // `process.cwd()`.
+    .default(process.cwd(), "current directory"));
 exports.addConfigOption = addConfigOption;
 const addEnvironmentOption = (command) => command.addOption(new commander_1.Option("-n, --environment-name <name>", "Config environment name from sitecoreai.cli.json (alias: --env-name)"));
 exports.addEnvironmentOption = addEnvironmentOption;
-const addVerbosityOptions = (command) => command
-    .addOption(new commander_1.Option("-v, --verbose", "Write some additional diagnostic and performance data"))
-    .addOption(new commander_1.Option("-t, --trace", "Write more additional diagnostic and performance data"))
-    .addOption(new commander_1.Option("-q, --quiet", "Suppress non-error output"))
-    .addOption(new commander_1.Option("--json", "Output machine-readable JSON"))
-    .addOption(new commander_1.Option("--log-file <path>", "Write logs to a file"))
-    .addOption(new commander_1.Option("--non-interactive", "Disable prompts and require explicit input"));
+/**
+ * Options for an **org-scoped** command (`ops brief`, `ops campaign`,
+ * `brand`): the command acts on a Sitecore organization, not an XM Cloud
+ * environment. `--org-id` names the org directly; `-n/--environment-name`
+ * names it indirectly via an env profile's `organizationId`. Both are
+ * optional — `resolveOrganization` falls back to the sole/first env
+ * profile, so a single-environment config needs neither flag.
+ */
+const addOrgScopeOptions = (command) => {
+    (0, exports.addEnvironmentOption)(command);
+    return command.addOption(new commander_1.Option("--org-id <id>", "Sitecore organization id to act on. Overrides the env profile's organizationId."));
+};
+exports.addOrgScopeOptions = addOrgScopeOptions;
+/**
+ * Adds the shared verbosity/output flags to a command.
+ *
+ * `--non-interactive` is included by default, but commands that own
+ * their own interactivity decision (e.g. `setup login`, where the
+ * browser device flow simply cannot run headless) pass
+ * `{ nonInteractive: false }` to omit it — the flag would only ever
+ * produce a confusing error or be redundant there.
+ */
+const addVerbosityOptions = (command, options = {}) => {
+    command
+        .addOption(new commander_1.Option("-v, --verbose", "Write some additional diagnostic and performance data"))
+        .addOption(new commander_1.Option("-t, --trace", "Write more additional diagnostic and performance data"))
+        .addOption(new commander_1.Option("-q, --quiet", "Suppress non-error output"))
+        .addOption(new commander_1.Option("--json", "Output machine-readable JSON"))
+        .addOption(new commander_1.Option("--log-file <path>", "Write logs to a file"));
+    if (options.nonInteractive !== false) {
+        command.addOption(new commander_1.Option("--non-interactive", "Disable prompts and require explicit input"));
+    }
+    return command;
+};
 exports.addVerbosityOptions = addVerbosityOptions;
 const addAllowWriteOption = (command) => command.option("--allow-write", "Allow write operations for this command without updating config");
 exports.addAllowWriteOption = addAllowWriteOption;
@@ -41,6 +92,79 @@ const addIncludeExcludeOptions = (command) => command
 exports.addIncludeExcludeOptions = addIncludeExcludeOptions;
 const addWhatIfOption = (command) => command.option("-w, --what-if", "Lists commands that would be executed, without executing them");
 exports.addWhatIfOption = addWhatIfOption;
+/**
+ * `--apply` is the universal "yes really execute" flag for destructive
+ * commands. Without it, scai dry-runs as if `--what-if` were set.
+ * Agent-first: no destruction without an explicit affirmative in the
+ * command line.
+ *
+ * Pre-2026-05-14, destructive commands ran whenever the operator passed
+ * `--allow-write` (cleanup) or `--force` (deploy). That made "I forgot
+ * `--what-if`" the same keystroke as "delete." Inverting the default
+ * costs one flag for intentional mutations and removes the muscle-
+ * memory hazard for everything else.
+ */
+const addApplyOption = (command) => command.option("--apply", "Required to execute mutations. Without --apply, destructive commands dry-run as if --what-if were set.");
+exports.addApplyOption = addApplyOption;
+/**
+ * Wrap a CLI command runner with the `--apply` gate. Without `--apply`
+ * (and absent an explicit `--what-if`), the runner is invoked with
+ * `whatIf: true` so it produces a plan-only output. Emits a one-line
+ * stderr hint so operators don't wonder why no mutation happened.
+ *
+ * Use at the CLI command layer (in `.action()` handlers). Library
+ * callers (MCP tools, direct programmatic use) bypass this wrapper and
+ * are gated by their own contract (e.g. MCP's per-call `allowWrite`).
+ */
+const withApplyGate = (runner) => {
+    return async (options) => {
+        let coerced = options;
+        if (!options.apply && !options.whatIf) {
+            process.stderr.write("Dry run (no --apply flag set). Pass --apply to execute the mutation.\n");
+            coerced = { ...options, whatIf: true };
+        }
+        await runner(coerced);
+    };
+};
+exports.withApplyGate = withApplyGate;
+/**
+ * Mark a command group as an **unstable surface**.
+ *
+ * Three things happen: `[unstable]` is stamped onto the `--help`
+ * summary (so it shows both in the parent's command list and atop the
+ * group's own help), a stability note is appended to `--help`, and a
+ * one-line stderr warning is printed before any action in the group
+ * runs.
+ *
+ * Unstable areas (`brand`, `ops brief`, `ops campaign`, `agents`) are
+ * reverse-engineered from observed traffic and carry no SemVer
+ * stability promise — their commands, flags, and output may change in
+ * any release. The matching SDK subpaths live under `./unstable/*`;
+ * see the SDK stability section in the README.
+ *
+ * The `preAction` hook is inherited by every subcommand, so the warning
+ * fires once for `scai <area> <verb>` regardless of nesting depth. It
+ * writes to stderr — leaving `--json` stdout clean — and honors
+ * `--quiet`.
+ *
+ * `surface` is the user-facing command path (e.g. `"scai ops brief"`),
+ * used verbatim in both the help note and the runtime warning.
+ */
+const markUnstable = (command, surface) => {
+    command.description(`[unstable] ${command.description()}`);
+    command.addHelpText("after", `\nStability: unstable. ${surface} is reverse-engineered and carries no\n` +
+        "SemVer stability promise — its commands, flags, and output may change in\n" +
+        "any release without notice. See the SDK stability section in the README.\n");
+    command.hook("preAction", (_thisCommand, actionCommand) => {
+        if (actionCommand.opts().quiet) {
+            return;
+        }
+        process.stderr.write(`⚠ ${surface} is an unstable surface — reverse-engineered, no SemVer ` +
+            "stability promise; behavior may change without notice.\n");
+    });
+    return command;
+};
+exports.markUnstable = markUnstable;
 const addSkipValidationOption = (command) => command.option("-s, --skip-validation", "Skips filesystem integrity validation prior to syncing");
 exports.addSkipValidationOption = addSkipValidationOption;
 const addForceOption = (command) => command.option("--force", "Perform force sync. In case you have invalid includes");
@@ -60,12 +184,15 @@ const addExplainOptions = (command) => command
     .option("-d, --database <database>", "Database of the item path to explain (default: master)");
 exports.addExplainOptions = addExplainOptions;
 const addDiffOptions = (command) => command
-    .option("-s, --source <name>", "Named Sitecore endpoint to use as a source for comparison")
-    .option("-d, --destination <name>", "Named Sitecore endpoint to use as a destination for comparison")
+    .option("-s, --source <name>", "Named Sitecore endpoint to use as a source for comparison (alias: --source-env)")
+    .option("-d, --destination <name>", "Named Sitecore endpoint to use as a destination for comparison (alias: --target-env)")
     .option("-p, --path <path>", "Item path to compare (instead of include/exclude)")
     .option("--source-database <database>", "Source database (when used with --path)")
     .option("--destination-database <database>", "Destination database (when used with --path)")
-    .option("--push", "Applies the differences detected to the destination (diff + push)");
+    .option("--push", "Applies the differences detected to the destination (diff + push)")
+    .option("-w, --what-if", "With --push: builds the plan and prints it without writing to the destination")
+    .option("--allow-write", "With --push: allow writes to the destination for this invocation without updating config")
+    .option("--force", "With --push: skip the empty-source confirmation guard. Required if source has zero items.");
 exports.addDiffOptions = addDiffOptions;
 const addValidateOptions = (command) => command.option("-f, --fix", "Execute possible fix operations when validating the serialized items");
 exports.addValidateOptions = addValidateOptions;

package/dist/commands/shell.d.ts

@@ -7,4 +7,3 @@ type RunCli = (argv: string[], options?: {
 }) => Promise<void>;
 export declare const createShellCommand: (runCli: RunCli) => Command;
 export {};
-//# sourceMappingURL=shell.d.ts.map

package/dist/commands/shell.js

@@ -149,7 +149,7 @@ const createShellCommand = (runCli) => {
             rl.on("close", resolve);
         });
     });
-    command.addHelpText("after", "\nExample:\n  $ scai shell\n  scai> status\n  scai> exit\n");
+    command.addHelpText("after", "\nExample:\n  $ scai cli shell\n  scai> status\n  scai> exit\n");
     return command;
 };
 exports.createShellCommand = createShellCommand;

package/dist/commands/status.d.ts

@@ -1,3 +1,2 @@
 import { Command } from "commander";
 export declare const createStatusCommand: () => Command;
-//# sourceMappingURL=status.d.ts.map

package/dist/commands/status.js

@@ -3,13 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createStatusCommand = void 0;
 const commander_1 = require("commander");
 const shared_1 = require("./shared");
-const tasks_1 = require("../serialization/tasks");
+const status_1 = require("../serialization/tasks/env/status");
 const createStatusCommand = () => {
     const command = new commander_1.Command("status").description("Show configured Sitecore environments for this CLI");
     (0, shared_1.addConfigOption)(command);
     (0, shared_1.addVerbosityOptions)(command);
-    command.addHelpText("after", "\nExample:\n  $ scai status\n");
-    command.action(async (options) => (0, tasks_1.runStatus)(options));
+    command.addHelpText("after", "\nExample:\n  $ scai setup status\n");
+    command.action(async (options) => (0, status_1.runStatus)(options));
     return command;
 };
 exports.createStatusCommand = createStatusCommand;

package/dist/commands/sync.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `scai sync` — the cross-domain aggregate over the recipe/sync engine.
+ *
+ * `brand sync` and `ops brief sync` each pull/diff/push ONE instance at
+ * a time. `scai sync` fans those out: it enumerates every brand kit and
+ * every brief type on the environment and pulls / diffs / pushes them
+ * all, into one workspace directory.
+ *
+ * Only kinds that can enumerate themselves (`RecipeKind.list`) take
+ * part. Component / page / site recipes are file-authored — there is
+ * nothing to enumerate — so they stay with `provision recipe`.
+ *
+ * Workspace layout: <dir>/<kind-name>/<slug(id)>.yaml
+ *   .scai/sync/brand-kit/acme.yaml
+ *   .scai/sync/brief-type/creative-brief.yaml
+ *
+ * The aggregate algorithm lives in `@/sync` (`aggregatePull` /
+ * `aggregateStatus` / `aggregatePush`); this file only wires the kinds,
+ * resolves config, and renders the structured result.
+ */
+import { Command } from "commander";
+/** `scai sync` — cross-domain recipe pull / status / push. */
+export declare const createSyncCommand: () => Command;

package/dist/commands/sync.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSyncCommand = void 0;
+/**
+ * `scai sync` — the cross-domain aggregate over the recipe/sync engine.
+ *
+ * `brand sync` and `ops brief sync` each pull/diff/push ONE instance at
+ * a time. `scai sync` fans those out: it enumerates every brand kit and
+ * every brief type on the environment and pulls / diffs / pushes them
+ * all, into one workspace directory.
+ *
+ * Only kinds that can enumerate themselves (`RecipeKind.list`) take
+ * part. Component / page / site recipes are file-authored — there is
+ * nothing to enumerate — so they stay with `provision recipe`.
+ *
+ * Workspace layout: <dir>/<kind-name>/<slug(id)>.yaml
+ *   .scai/sync/brand-kit/acme.yaml
+ *   .scai/sync/brief-type/creative-brief.yaml
+ *
+ * The aggregate algorithm lives in `@/sync` (`aggregatePull` /
+ * `aggregateStatus` / `aggregatePush`); this file only wires the kinds,
+ * resolves config, and renders the structured result.
+ */
+const commander_1 = require("commander");
+const shared_1 = require("./shared");
+const root_config_1 = require("../config/root-config");
+const aggregate_kinds_1 = require("../sync/aggregate-kinds");
+const sync_1 = require("../sync");
+const cli_tasks_1 = require("../shared/cli-tasks");
+const buildContext = (options, logger) => {
+    const configPath = options.config ?? process.cwd();
+    const root = (0, root_config_1.readRootConfiguration)(configPath, options.environmentName);
+    return {
+        environmentName: options.environmentName ?? root.defaultEnvironment,
+        configPath,
+        logger,
+    };
+};
+const runPull = async (options) => {
+    const logger = (0, cli_tasks_1.toLogger)(options);
+    const ctx = buildContext(options, logger);
+    const result = await (0, sync_1.aggregatePull)(aggregate_kinds_1.ENUMERABLE_RECIPE_KINDS, ctx, { dir: options.dir });
+    for (const kind of result.kinds) {
+        logger.info(`${kind.kind}:`, "cyan");
+        if (kind.skipped) {
+            // A domain that isn't configured for this env (no credential) is
+            // skipped, not fatal — the other domains still pulled.
+            logger.warn(`  skipped — ${kind.skipped}`);
+            continue;
+        }
+        for (const item of kind.pulled) {
+            logger.info(`  pulled ${item.file}`);
+        }
+    }
+    logger.info(`Pulled ${result.total} recipe(s) into ${result.dir}.`, "green");
+};
+const runStatus = async (options) => {
+    const logger = (0, cli_tasks_1.toLogger)(options);
+    const ctx = buildContext(options, logger);
+    const result = await (0, sync_1.aggregateStatus)(aggregate_kinds_1.ENUMERABLE_RECIPE_KINDS, ctx, { dir: options.dir });
+    for (const kind of result.kinds) {
+        logger.info(`${kind.kind}:`, "cyan");
+        for (const item of kind.items) {
+            if (item.status === "in-sync") {
+                logger.info(`  = ${item.id} — in sync`);
+            }
+            else if (item.status === "drift" && item.summary) {
+                const tally = item.summary;
+                logger.info(`  ~ ${item.id} — ${tally.create} create, ${tally.update} update, ${tally.delete} delete`);
+            }
+            else {
+                logger.warn(`  ! ${item.id} — ${item.error}`);
+            }
+        }
+    }
+    logger.info(result.drifted === 0
+        ? "Everything in sync."
+        : `${result.drifted} recipe(s) drifted — \`scai sync push\` to converge.`, result.drifted === 0 ? "green" : "yellow");
+};
+const runPush = async (options) => {
+    const logger = (0, cli_tasks_1.toLogger)(options);
+    const ctx = buildContext(options, logger);
+    const mode = options.allowWrite ? "apply" : "what-if";
+    if (mode === "what-if") {
+        logger.info("Dry run — no writes. Re-run with --allow-write to converge.", "yellow");
+    }
+    const result = await (0, sync_1.aggregatePush)(aggregate_kinds_1.ENUMERABLE_RECIPE_KINDS, ctx, {
+        dir: options.dir,
+        mode,
+        prune: Boolean(options.prune),
+    });
+    for (const kind of result.kinds) {
+        logger.info(`${kind.kind}:`, "cyan");
+        for (const item of kind.items) {
+            if (item.status === "applied") {
+                logger.info(`  ✓ ${item.id} — ${item.appliedCount} change(s)`);
+            }
+            else if (item.status === "in-sync") {
+                logger.info(`  = ${item.id} — in sync`);
+            }
+            else if (item.status === "planned") {
+                logger.info(`  ~ ${item.id} — would apply ${item.plannedCount}`);
+            }
+            else {
+                logger.warn(`  ! ${item.id} — ${item.error}`);
+            }
+        }
+    }
+    if (result.mode === "apply") {
+        logger.info(`Applied ${result.applied} change(s).`, "green");
+    }
+};
+/** `scai sync` — cross-domain recipe pull / status / push. */
+const createSyncCommand = () => {
+    const command = new commander_1.Command("sync").description("Pull, diff, and push every brand kit and brief type at once — the cross-domain recipe aggregate.");
+    const dirOption = () => new commander_1.Option("--dir <path>", "Workspace directory for recipe files.").default(sync_1.DEFAULT_SYNC_DIR);
+    const pull = new commander_1.Command("pull").description("Enumerate every brand kit + brief type and capture each as a recipe file.");
+    pull.addOption(dirOption());
+    (0, shared_1.addEnvironmentOption)(pull);
+    (0, shared_1.addConfigOption)(pull);
+    (0, shared_1.addVerbosityOptions)(pull);
+    pull.action(async (options) => runPull(options));
+    const status = new commander_1.Command("status").description("Diff every recipe file in the workspace against the environment.");
+    status.addOption(dirOption());
+    (0, shared_1.addEnvironmentOption)(status);
+    (0, shared_1.addConfigOption)(status);
+    (0, shared_1.addVerbosityOptions)(status);
+    status.action(async (options) => runStatus(options));
+    const push = new commander_1.Command("push").description("Converge every recipe file in the workspace onto the environment. Dry-run unless --allow-write.");
+    push.addOption(dirOption());
+    push.addOption(new commander_1.Option("--allow-write", "Apply the plan (default is a dry-run)."));
+    push.addOption(new commander_1.Option("--prune", "Include delete changes (off by default)."));
+    (0, shared_1.addEnvironmentOption)(push);
+    (0, shared_1.addConfigOption)(push);
+    (0, shared_1.addVerbosityOptions)(push);
+    push.action(async (options) => runPush(options));
+    command.addCommand(pull);
+    command.addCommand(status);
+    command.addCommand(push);
+    command.addHelpText("after", [
+        "",
+        "Covers every recipe kind that can enumerate itself: brand kits and",
+        "brief types today. File-authored component/page/site recipes stay",
+        "with `provision recipe`.",
+        "",
+        "Examples:",
+        "  $ scai sync pull -n agents              # capture everything into .scai/sync",
+        "  $ scai sync status -n agents            # what has drifted",
+        "  $ scai sync push -n agents --allow-write",
+        "",
+    ].join("\n"));
+    return command;
+};
+exports.createSyncCommand = createSyncCommand;

package/dist/commands/telemetry.d.ts

@@ -1,3 +1,2 @@
 import { Command } from "commander";
 export declare const createTelemetryCommand: () => Command;
-//# sourceMappingURL=telemetry.d.ts.map

package/dist/commands/telemetry.js

@@ -5,13 +5,14 @@ const commander_1 = require("commander");
 const shared_1 = require("./shared");
 const telemetry_1 = require("../shared/telemetry");
 const logger_1 = require("../shared/logger");
+const buildLogger = (options) => new logger_1.Logger(Boolean(options.verbose), Boolean(options.trace), Boolean(options.json), Boolean(options.quiet), options.logFile);
 const createTelemetryCommand = () => {
     const command = new commander_1.Command("telemetry").description("Telemetry utilities");
     const status = new commander_1.Command("status").description("Show telemetry status");
     (0, shared_1.addConfigOption)(status);
     (0, shared_1.addVerbosityOptions)(status);
     status.action(async (options) => {
-        const logger = new logger_1.Logger(Boolean(options.verbose), Boolean(options.trace), Boolean(options.json), Boolean(options.quiet), options.logFile);
+        const logger = buildLogger(options);
         const statusInfo = (0, telemetry_1.getTelemetryStatus)(options.config ?? process.cwd());
         if (logger.isJson()) {
             logger.json(statusInfo);
@@ -21,8 +22,45 @@ const createTelemetryCommand = () => {
         logger.info(`Source: ${statusInfo.source}`);
         logger.info(`Endpoint: ${statusInfo.url}`);
     });
+    const enable = new commander_1.Command("enable").description("Enable anonymous usage telemetry");
+    (0, shared_1.addConfigOption)(enable);
+    (0, shared_1.addVerbosityOptions)(enable);
+    enable.action(async (options) => {
+        const logger = buildLogger(options);
+        const configPath = options.config ?? process.cwd();
+        (0, telemetry_1.setTelemetryEnabled)(configPath, true);
+        if (logger.isJson()) {
+            logger.json({ enabled: true });
+            return;
+        }
+        logger.info("Telemetry enabled.", "cyan");
+    });
+    const disable = new commander_1.Command("disable").description("Disable anonymous usage telemetry");
+    (0, shared_1.addConfigOption)(disable);
+    (0, shared_1.addVerbosityOptions)(disable);
+    disable.action(async (options) => {
+        const logger = buildLogger(options);
+        const configPath = options.config ?? process.cwd();
+        (0, telemetry_1.setTelemetryEnabled)(configPath, false);
+        if (logger.isJson()) {
+            logger.json({ enabled: false });
+            return;
+        }
+        logger.info("Telemetry disabled.", "cyan");
+    });
     command.addCommand(status);
-    command.addHelpText("after", "\nExample:\n  $ scai telemetry status\n");
+    command.addCommand(enable);
+    command.addCommand(disable);
+    command.addHelpText("after", [
+        "",
+        "Telemetry is enabled by default (opt-out). SITECOREAI_TELEMETRY=false and",
+        "the cross-tool DO_NOT_TRACK=1 env var also disable it.",
+        "",
+        "Examples:",
+        "  $ scai cli telemetry status",
+        "  $ scai cli telemetry disable",
+        "",
+    ].join("\n"));
     return command;
 };
 exports.createTelemetryCommand = createTelemetryCommand;

package/dist/commands/topics/index.d.ts

@@ -0,0 +1,5 @@
+import { Command } from "commander";
+import { type Topic } from "../../shared/topics";
+export declare const createTopicsCommand: () => Command;
+/** Exported for unit tests — pin the topic list shape. */
+export declare const __topicsForTest: Topic[];

package/dist/commands/topics/index.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__topicsForTest = exports.createTopicsCommand = void 0;
+const commander_1 = require("commander");
+const envelope_1 = require("../../shared/envelope");
+const cli_tasks_1 = require("../../shared/cli-tasks");
+const topics_1 = require("../../shared/topics");
+const shared_1 = require("../shared");
+/**
+ * `scai cli topics` — intent-based command index.
+ *
+ * `topics` groups commands by what the operator is trying to do — "why
+ * won't this delete?", "clean up after a site removal", "manage known
+ * debt" — rather than where they live in the (alphabetical) `--help`
+ * tree. This file is the CLI renderer; the curated topic data lives in
+ * `@/shared/topics` so the MCP `scai://help/topics` resource serves the
+ * exact same index.
+ */
+const printTopicList = (logger) => {
+    if (logger.isJson()) {
+        logger.json((0, envelope_1.buildScaiEnvelope)({
+            command: "topics.list",
+            environment: null,
+            data: topics_1.TOPICS.map((t) => ({ name: t.name, description: t.description })),
+        }));
+        return;
+    }
+    logger.info("scai cli topics — intent-based command index", "cyan");
+    logger.info("");
+    for (const t of topics_1.TOPICS) {
+        logger.info(`  ${t.name}`, "yellow");
+        logger.info(`    ${t.description}`, "gray");
+    }
+    logger.info("");
+    logger.info("Show one topic's commands: `scai cli topics show <name>`", "gray");
+};
+const printSingleTopic = (logger, topic) => {
+    if (logger.isJson()) {
+        logger.json((0, envelope_1.buildScaiEnvelope)({
+            command: "topics.show",
+            environment: null,
+            data: topic,
+        }));
+        return;
+    }
+    logger.info(`scai cli topics: ${topic.name}`, "cyan");
+    logger.info(`  ${topic.description}`, "gray");
+    logger.info("");
+    for (const c of topic.commands) {
+        logger.info(`  ${c.command}`, "yellow");
+        logger.info(`    ${c.description}`, "gray");
+        logger.info("");
+    }
+};
+const createTopicsCommand = () => {
+    const command = new commander_1.Command("topics").description("Show scai commands grouped by intent (e.g. 'diagnose-blocked-delete') instead of alphabetically");
+    const list = new commander_1.Command("list").description("List every topic with its one-line summary.");
+    (0, shared_1.addVerbosityOptions)(list);
+    list.action(() => {
+        // `--json` (and the other verbosity flags) are registered on `topics`
+        // as well as here, so Commander parses a post-subcommand `--json` onto
+        // the `topics` ancestor — `list.opts()` would miss it. Read the merged
+        // ancestor-inclusive view instead.
+        printTopicList((0, cli_tasks_1.toLogger)(list.optsWithGlobals()));
+    });
+    const show = new commander_1.Command("show")
+        .description("Expand one topic into its recommended-run command sequence.")
+        .argument("<name>", "Topic slug to expand — see `scai cli topics list`.");
+    (0, shared_1.addVerbosityOptions)(show);
+    show.action((name) => {
+        // See the note in `list.action` — verbosity flags can land on the
+        // `topics` ancestor, so read the merged view.
+        const logger = (0, cli_tasks_1.toLogger)(show.optsWithGlobals());
+        const topic = topics_1.TOPICS.find((t) => t.name === name);
+        if (!topic) {
+            logger.warn(`Unknown topic '${name}'. Run \`scai cli topics list\` to see the available topics.`);
+            process.exitCode = 1;
+            return;
+        }
+        printSingleTopic(logger, topic);
+    });
+    command.addCommand(list);
+    command.addCommand(show);
+    // Bare `scai cli topics` defaults to the index — the most common need.
+    (0, shared_1.addVerbosityOptions)(command);
+    command.action(() => {
+        printTopicList((0, cli_tasks_1.toLogger)(command.optsWithGlobals()));
+    });
+    command.addHelpText("after", "\nExamples:\n" +
+        "  $ scai cli topics list             # every topic + summary\n" +
+        "  $ scai cli topics show diagnose-blocked-delete\n" +
+        "  $ scai cli topics                  # same as `topics list`\n" +
+        "\nThe topic groupings are curated — they reflect workflows\n" +
+        '("why won\'t this delete?"), not the audit/cleanup directory layout.\n' +
+        "Use this when you're not sure which command to reach for; the\n" +
+        "groupings save you from grepping `--help` or reinventing a primitive\n" +
+        "that already exists.\n");
+    return command;
+};
+exports.createTopicsCommand = createTopicsCommand;
+/** Exported for unit tests — pin the topic list shape. */
+exports.__topicsForTest = topics_1.TOPICS;

package/dist/commands/webhook/create.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const createWebhookCreateCommand: () => Command;