@wootsup/yt-builder-mcp 1.12.0 → 2.0.0

package/dist/setup-cli.js

@@ -1,31 +1,17 @@
 #!/usr/bin/env node
-/**
- * Top-level CLI dispatcher for `@wootsup/yt-builder-mcp`.
- *
- * Round-1 audit I5 fix (2026-05-22): the wizard implementation lives in
- * `setup-wizard.ts`; this file is the thin dispatcher (`runCli`) plus
- * the ESM main-guard. Both have their own deps-bag (`WizardDeps` /
- * `RunCliDeps`) so unit tests can drive them independently.
- *
- * Subcommands:
- *
- *   setup (default)   — runWizard (see `setup-wizard.ts`)
- *   install-skill     — copy the bundled skill into ~/.claude/skills/
- *                       and append a marker block to ~/AGENTS.md.
- *   --help / help     — print usage.
- *   --version / -v    — print the package version.
- *
- * Re-exports `runWizard`, `majorMinor` and the wizard public types so
- * existing callers (and tests that already import from `./setup-cli`)
- * keep working with a one-line import.
- *
- * @license MIT
- */
+import { intro } from '@clack/prompts';
 import { ALL_CLIENTS } from './clients/index.js';
 import { installSkill as defaultInstallSkill } from './install-skill.js';
-import { SERVER_VERSION } from './server.js';
+import { SERVER_NAME, SERVER_VERSION } from './server.js';
 import { confirmTTY as defaultConfirmTTY } from './setup-cli-confirm.js';
 import { defaultUninstallPrompt } from './setup-prompts.js';
+import { createBannerOnce } from './setup/banner.js';
+import { printClosingBlock } from './setup/closing.js';
+import { detectColorSupport } from './setup/banner-color.js';
+import { confirmAnotherSite as defaultConfirmAnotherSite, runMultiSiteLoop, } from './setup/multi-site-loop.js';
+import { registryDirIsWritable, registryRemedy, RegistryWriteFailure, } from './setup/registry-remedy.js';
+import { clearResumeState, confirmResume as defaultConfirmResume, readResumeState, resumeFilePathFor, writeResumeState, } from './setup/resume.js';
+import { resolveSiteId } from './sites/schema.js';
 import { DEFAULT_WIZARD_DEPS, runWizard as runWizardImpl } from './setup-wizard.js';
 import { detectInstalledClients as defaultDetectInstalled, DEFAULT_UNINSTALL_DEPS, runUninstall, } from './uninstall.js';
 import { addSiteCommand, AddSiteError, DEFAULT_ADD_SITE_DEPS, } from './sites/cli/add-site.js';
@@ -34,8 +20,6 @@ import { DEFAULT_REMOVE_SITE_DEPS, removeSiteCommand, RemoveSiteError, } from '.
 import { DEFAULT_SET_DEFAULT_DEPS, setDefaultCommand, SetDefaultError, } from './sites/cli/set-default.js';
 import { DEFAULT_TEST_SITE_DEPS, renderTestSiteLines, testSiteCommand, TestSiteError, } from './sites/cli/test-site.js';
 import { defaultSitesFilePath } from './sites/paths.js';
-// Re-export the wizard surface so consumers that imported from
-// `./setup-cli` before the I5 split keep working without changes.
 export { DEFAULT_WIZARD_DEPS, majorMinor, runWizard, } from './setup-wizard.js';
 const HELP_TEXT = `Usage: yt-builder-mcp <command> [flags]
 
@@ -147,7 +131,7 @@ Environment (when launched by an AI client):
   YTB_MCP_SITE_URL       Host CMS base URL (e.g. https://example.com).
                          Works for BOTH WordPress and Joomla.
   YTB_MCP_WP_URL         DEPRECATED alias for YTB_MCP_SITE_URL — still
-                         honoured for pre-Wave-7 configurations.
+                         honoured for configurations from before the rename.
   YTB_MCP_BEARER_TOKEN   Bearer key from:
                            - WordPress: wp-admin → Tools → "YT Builder MCP"
                            - Joomla: Administrator → Components → "YT Builder MCP"
@@ -180,17 +164,8 @@ Environment (when launched by an AI client):
 
 Documentation: https://wootsup.com/docs/mcp
 `;
-/**
- * Parse the `setup` subcommand argv tail. Pure function; does no I/O.
- *
- * Accepts both `--key value` and `--key=value` styles. Unknown flags
- * are reported as errors so typos don't silently disable validation.
- *
- * `env` (default `{}`, kept empty so the function stays pure) supplies the
- * `YTB_MCP_VERSION` fallback for the `--pin` version-pin (customer gap #15):
- * an explicit `--pin` always wins; otherwise `YTB_MCP_VERSION` is used.
- */
 export function parseSetupArgs(argv, env = {}) {
+    let helpRequested = false;
     let nonInteractive = false;
     let url = '';
     let token = '';
@@ -220,6 +195,12 @@ export function parseSetupArgs(argv, env = {}) {
         const flag = eq >= 0 ? raw.slice(0, eq) : raw;
         const inline = eq >= 0 ? raw.slice(eq + 1) : undefined;
         switch (flag) {
+            case 'help':
+            case '--help':
+            case '-h': {
+                helpRequested = true;
+                break;
+            }
             case '--non-interactive': {
                 nonInteractive = true;
                 if (inline !== undefined) {
@@ -259,9 +240,6 @@ export function parseSetupArgs(argv, env = {}) {
                 break;
             }
             case '--ca': {
-                // Corporate TLS-inspection root CA. Two strategies:
-                //   --ca=system / --ca system → OS trust store (NODE_OPTIONS=--use-system-ca)
-                //   --ca <path>               → .pem file (NODE_EXTRA_CA_CERTS=<path>)
                 const { value, nextIndex } = consumeValue('--ca', inline, i);
                 const v = value.trim();
                 if (v.toLowerCase() === 'system') {
@@ -274,7 +252,6 @@ export function parseSetupArgs(argv, env = {}) {
                 break;
             }
             case '--use-system-ca': {
-                // Alias for `--ca=system`: trust the OS store natively (no .pem).
                 caSystem = true;
                 if (inline !== undefined) {
                     errors.push('Flag --use-system-ca does not take a value.');
@@ -282,17 +259,12 @@ export function parseSetupArgs(argv, env = {}) {
                 break;
             }
             case '--pin': {
-                // customer gap #15 — pin the npx version (air-gapped / locked-down
-                // corp envs that forbid floating @latest installs).
                 const { value, nextIndex } = consumeValue('--pin', inline, i);
                 versionPin = value.trim();
                 i = nextIndex;
                 break;
             }
             case '--platform': {
-                // Explicit host platform. `auto` (or absent) → auto-detect (no
-                // hint). `wordpress` / `joomla` WINS over runtime detection so a
-                // Joomla origin-only URL is never mistaken for WordPress.
                 const { value, nextIndex } = consumeValue('--platform', inline, i);
                 const v = value.trim().toLowerCase();
                 if (v === 'wordpress' || v === 'joomla') {
@@ -312,9 +284,6 @@ export function parseSetupArgs(argv, env = {}) {
             }
         }
     }
-    // Pickup mode validation (Wave C). Pickup pairs 1:1 with nonce; when
-    // both are present, the wizard fetches token + URL from the plugin and
-    // ignores --url/--token (with a warning so typos don't go silent).
     const pickupMode = pickup !== '' || nonce !== '';
     if (pickupMode) {
         if (pickup === '')
@@ -349,15 +318,12 @@ export function parseSetupArgs(argv, env = {}) {
             }
         }
     }
-    // A .pem path and the OS-trust-store are two mutually-exclusive ways to
-    // trust the same CA — refuse the ambiguous combination rather than silently
-    // pick one.
     if (caSystem && caCertPath !== '') {
         errors.push('Pass either a CA .pem path (--ca <path>) or the OS trust store (--ca=system / --use-system-ca), not both.');
     }
-    // #15 — an explicit `--pin` wins; otherwise fall back to YTB_MCP_VERSION.
     const resolvedPin = versionPin !== '' ? versionPin : (env.YTB_MCP_VERSION ?? '').trim();
     return {
+        helpRequested,
         nonInteractive,
         url,
         token,
@@ -372,15 +338,6 @@ export function parseSetupArgs(argv, env = {}) {
         ...(platform !== undefined ? { platform } : {}),
     };
 }
-/**
- * Build a `WizardDeps` bag that answers prompts from CLI flags instead
- * of asking a human. Reuses every other dependency (probes, writes,
- * handshake) from `DEFAULT_WIZARD_DEPS` so the wizard's exit-code
- * contract (0/2/3/4/5) stays identical.
- *
- * `confirmContinue` always returns `false` — there is no human to ask,
- * so a probe failure cleanly aborts with the documented exit code.
- */
 export function buildNonInteractiveDeps(parsed, base = DEFAULT_WIZARD_DEPS) {
     const answers = {
         wpUrl: parsed.url,
@@ -395,31 +352,10 @@ export function buildNonInteractiveDeps(parsed, base = DEFAULT_WIZARD_DEPS) {
         ...base,
         prompt: async () => answers,
         confirmContinue: async () => false,
-        // No human to answer the interactive CA prompt — the CA comes from
-        // `--ca` / `--ca=system` flags (already in `answers`). Stripping the
-        // prompt keeps a CA-trust probe failure on the documented exit-code
-        // path instead of hanging on a prompt with no TTY.
         promptCa: undefined,
-        // No TTY to answer the platform fallback either. When --platform is
-        // omitted AND detection ties, the wizard warns + defaults to WordPress
-        // (the documented non-interactive back-compat) rather than hanging.
         promptPlatform: undefined,
     };
 }
-/**
- * Build a `WizardDeps` bag for the Wave-C pickup flow. The wizard's
- * `prompt` step calls `base.fetchPickup(url, nonce)` once, then
- * synthesises the `WizardAnswers` from the response — the actual answers
- * (token + canonical WordPress URL) come straight from the plugin via
- * a 256-bit one-shot nonce, never through chat history / provider logs.
- *
- * On `fetchPickup` failure the prompt resolves to `null` so the wizard
- * exits cleanly with code 130 (user-cancel equivalent — we treat
- * an unrecoverable pickup as "the conversation ends here"). The
- * thrown error is logged via the `log` dep so the operator sees why.
- *
- * `confirmContinue` returns `false` (same rationale as non-interactive).
- */
 export function buildPickupDeps(parsed, base = DEFAULT_WIZARD_DEPS) {
     const pickupUrl = parsed.pickup ?? '';
     const nonce = parsed.nonce ?? '';
@@ -456,16 +392,10 @@ export function buildPickupDeps(parsed, base = DEFAULT_WIZARD_DEPS) {
             }
         },
         confirmContinue: async () => false,
-        // Pickup is non-interactive too — no TTY for the CA / platform prompts.
         promptCa: undefined,
         promptPlatform: undefined,
     };
 }
-/**
- * Parse `add-site` flags from the tail of argv. Accepts both
- * `--key value` and `--key=value` styles. Unknown flags are reported
- * as errors so typos never silently disable validation.
- */
 export function parseAddSiteArgs(argv) {
     let url = '';
     let token = '';
@@ -646,12 +576,6 @@ const UNINSTALL_HELP = `Usage: yt-builder-mcp uninstall [--all] [--yes]\n` +
     `  yt-builder-mcp uninstall            # interactive checklist\n` +
     `  yt-builder-mcp uninstall --all      # remove everything, no prompts\n` +
     `  yt-builder-mcp remove --yes         # interactive, no final confirm\n`;
-/**
- * Parse the `uninstall` / `remove` argv tail. Pure; does no I/O. Accepts
- * only boolean flags — `--all`, `--keep-skill`, `--force`, `--yes`/`-y`,
- * `--help`/`-h`. Any value (`--all=x`) or unknown flag is an error so typos
- * don't silently change the destructive behaviour.
- */
 export function parseUninstallArgs(argv) {
     let all = false;
     let yes = false;
@@ -765,11 +689,6 @@ export async function runCli(argv, deps) {
     const resolveSitesPath = deps?.resolveSitesPath ?? (() => defaultSitesFilePath());
     const addSiteDeps = deps?.addSiteDeps ?? DEFAULT_ADD_SITE_DEPS;
     const listSitesDeps = deps?.listSitesDeps ?? DEFAULT_LIST_SITES_DEPS;
-    // W12-R2A: wire a TTY confirm hook into the destructive-subcommand
-    // deps bags. Tests that supply `removeSiteDeps`/`setDefaultDeps`
-    // directly retain full control over the confirm channel (so the
-    // existing unit-tests keep working unchanged); only the default
-    // dispatcher path gets the `defaultConfirmTTY` injection.
     const confirmHook = deps?.confirm ?? defaultConfirmTTY;
     const removeSiteDeps = deps?.removeSiteDeps
         ?? { ...DEFAULT_REMOVE_SITE_DEPS, confirm: confirmHook };
@@ -778,73 +697,126 @@ export async function runCli(argv, deps) {
     const testSiteDeps = deps?.testSiteDeps ?? DEFAULT_TEST_SITE_DEPS;
     const addSiteFromWizard = deps?.addSiteFromWizard
         ?? ((args, path) => addSiteCommand(args, path, addSiteDeps));
+    const confirmAnotherSite = deps?.confirmAnotherSite ?? defaultConfirmAnotherSite;
+    const loadResume = deps?.loadResume ?? ((path) => readResumeState(path));
+    const confirmResume = deps?.confirmResume ?? defaultConfirmResume;
+    const loadSiteIds = deps?.loadSiteIds
+        ?? (async (path) => {
+            try {
+                const file = await listSitesDeps.load(path);
+                return file.sites.map((site) => site.site_id);
+            }
+            catch {
+                return [];
+            }
+        });
     const uninstallDeps = deps?.uninstallDeps ?? DEFAULT_UNINSTALL_DEPS;
     const detectInstalled = deps?.detectInstalled ?? defaultDetectInstalled;
     const promptUninstall = deps?.promptUninstall ?? defaultUninstallPrompt;
     const [subcommand] = argv;
-    // Build a `persistSite` callback for the wizard that translates
-    // the collected WizardAnswers into an `addSiteCommand` call so the
-    // sites.json registry stays in sync with the env-var path. This is
-    // the W9 "wizard internally invokes add-site" wiring.
-    const buildPersistSite = () => {
+    const buildPersistSite = (alwaysOverwrite) => {
         return async (answers) => {
-            const siteId = (answers.siteId !== undefined && answers.siteId.length > 0)
-                ? answers.siteId
-                : 'default';
+            const siteId = resolveSiteId(answers.siteId);
             const path = resolveSitesPath();
             const args = {
                 url: answers.wpUrl,
                 token: answers.bearer,
                 siteId,
-                default: true,
-                yes: true,
-                // The wizard hands us the RESOLVED platform on `answers.platform`
-                // (see runWizard's persistSite call); fall back to 'auto' only
-                // for legacy callers that never resolved one.
+                yes: alwaysOverwrite || answers.overwriteSite === true,
                 platform: answers.platform ?? 'auto',
             };
-            await addSiteFromWizard(args, path);
-        };
-    };
-    // D1: after a SUCCESSFUL wizard (exit 0), install the skill too. A
-    // skill-install failure is NON-FATAL — warn, keep the wizard exit code.
-    const runSetupThenInstall = async (wizardDeps) => {
-        const code = await wizard(wizardDeps);
-        if (code === 0) {
+            let result;
             try {
-                const result = await install({ bundledVersion: SERVER_VERSION });
-                if (result.modifiedSkipped) {
-                    out(`yt-builder-mcp: skill left untouched at ${result.skillTargetDir} (locally modified; run 'yt-builder-mcp install-skill --force' to overwrite).`);
-                }
-                else if (result.markerAlreadyPresent) {
-                    out(`yt-builder-mcp: skill installed/refreshed at ${result.skillTargetDir}.`);
+                result = await addSiteFromWizard(args, path);
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                let readable = true;
+                try {
+                    await addSiteDeps.load(path);
                 }
-                else {
-                    out(`yt-builder-mcp: skill installed at ${result.skillTargetDir}; ${result.agentsFile} updated.`);
+                catch {
+                    readable = false;
                 }
+                throw new RegistryWriteFailure(message, registryRemedy({ readable, writable: await registryDirIsWritable(path) }));
             }
-            catch (e) {
-                const msg = e instanceof Error ? e.message : String(e);
-                err(`yt-builder-mcp: warning: skill install skipped (${msg}). Run 'yt-builder-mcp install-skill' manually.`);
+            if (result.overwritten) {
+                return `Site "${result.siteId}" updated in the registry.`;
             }
+            return result.becameDefault
+                ? `Site "${result.siteId}" added to the registry as your default site.`
+                : `Site "${result.siteId}" added to the registry.`;
+        };
+    };
+    const installSkillStep = async () => {
+        const result = await install({ bundledVersion: SERVER_VERSION });
+        if (result.modifiedSkipped) {
+            return `Skill left untouched at ${result.skillTargetDir} (locally modified; run 'yt-builder-mcp install-skill --force' to overwrite).`;
+        }
+        if (result.markerAlreadyPresent) {
+            return `Skill installed/refreshed at ${result.skillTargetDir}.`;
         }
-        return code;
+        return `Skill installed at ${result.skillTargetDir}; ${result.agentsFile} updated.`;
     };
+    const runSetupThenInstall = async (wizardDeps) => wizard({ ...wizardDeps, installSkill: installSkillStep });
     if (subcommand === undefined || subcommand === 'setup') {
         const setupArgs = argv[0] === 'setup' ? argv.slice(1) : argv;
         const parsed = parseSetupArgs(setupArgs, process.env);
-        // Surface non-fatal warnings (e.g. "--url ignored in pickup mode").
+        if (parsed.helpRequested) {
+            out(HELP_TEXT);
+            return 0;
+        }
+        const greet = createBannerOnce(out, {
+            columns: process.stdout.columns,
+            env: process.env,
+            platform: process.platform,
+            version: SERVER_VERSION,
+            interactive: !parsed.nonInteractive,
+            color: detectColorSupport(process.env, process.stdout.isTTY === true),
+        });
+        greet();
         for (const line of parsed.warnings)
             err(`yt-builder-mcp: warning: ${line}`);
         const pickupMode = (parsed.pickup ?? '') !== '' || (parsed.nonce ?? '') !== '';
-        const persistSite = buildPersistSite();
-        function withPersist(base) {
-            return { ...base, persistSite };
+        function withPersist(base, alwaysOverwrite) {
+            return {
+                ...base,
+                persistSite: buildPersistSite(alwaysOverwrite),
+                sitesFilePath: resolveSitesPath(),
+            };
+        }
+        function withResume(base, path) {
+            return {
+                ...base,
+                saveResume: async (progress) => writeResumeState(path, progress),
+                clearResume: () => { clearResumeState(path); },
+            };
+        }
+        function withResumed(base, state) {
+            const innerPrompt = base.prompt;
+            return {
+                ...base,
+                prompt: async (input) => {
+                    const answers = await innerPrompt({
+                        ...input,
+                        urlDefault: state.url,
+                        clientDefaults: state.clients,
+                    });
+                    if (answers === null)
+                        return null;
+                    return parsed.platform !== undefined
+                        ? answers
+                        : { ...answers, platform: state.platform };
+                },
+            };
+        }
+        function withSiteContext(base, context) {
+            const innerPrompt = base.prompt;
+            return {
+                ...base,
+                prompt: async (input) => innerPrompt({ ...input, ...context }),
+            };
         }
-        // #15 — when `--pin` / YTB_MCP_VERSION is set on the INTERACTIVE path,
-        // the prompt collects its own answers, so fold the pin into them after
-        // the prompt resolves. Non-interactive / pickup paths already inject the
-        // pin via their answers builders.
         function withPin(base) {
             if (parsed.versionPin === undefined)
                 return base;
@@ -860,14 +832,6 @@ export async function runCli(argv, deps) {
                 },
             };
         }
-        // G-D #6 — when `--use-system-ca` / `--ca=system` / `--ca <path>` is
-        // passed on the INTERACTIVE path, the prompt collects its own answers,
-        // so fold the CA choice into them after the prompt resolves (mirrors
-        // withPin). Without this fold an explicit CA flag on the default
-        // interactive run was a SILENT NO-OP: it was parsed then dropped before
-        // reaching the env block (only buildNonInteractiveDeps threaded it). The
-        // non-interactive / pickup paths already inject the CA via their answers
-        // builders, so this fold is the interactive-path counterpart.
         function withCa(base) {
             if (parsed.caMode === undefined && parsed.caCertPath === undefined)
                 return base;
@@ -888,13 +852,6 @@ export async function runCli(argv, deps) {
                 },
             };
         }
-        // Thread an explicit `--platform wordpress|joomla` into the interactive
-        // answers after the prompt resolves (mirrors withCa / withPin). Without
-        // this fold the flag would be a SILENT NO-OP on the default interactive
-        // run — parsed then dropped before reaching the wizard's platform
-        // resolution (only buildNonInteractiveDeps / buildPickupDeps thread it
-        // via their answers builders). `--platform auto` / absent = undefined,
-        // which lets the wizard auto-detect.
         function withPlatform(base) {
             if (parsed.platform === undefined)
                 return base;
@@ -917,7 +874,7 @@ export async function runCli(argv, deps) {
                 err(HELP_TEXT);
                 return 2;
             }
-            return runSetupThenInstall(withPersist(buildPickupDeps(parsed)));
+            return runSetupThenInstall(withPersist(buildPickupDeps(parsed), true));
         }
         if (parsed.nonInteractive) {
             if (parsed.errors.length > 0) {
@@ -926,7 +883,7 @@ export async function runCli(argv, deps) {
                 err(HELP_TEXT);
                 return 2;
             }
-            return runSetupThenInstall(withPersist(buildNonInteractiveDeps(parsed)));
+            return runSetupThenInstall(withPersist(buildNonInteractiveDeps(parsed), true));
         }
         if (parsed.errors.length > 0) {
             for (const line of parsed.errors)
@@ -934,7 +891,53 @@ export async function runCli(argv, deps) {
             err(HELP_TEXT);
             return 1;
         }
-        return runSetupThenInstall(withPlatform(withCa(withPin(withPersist(interactiveBase)))));
+        intro(`${SERVER_NAME} v${SERVER_VERSION} — setup wizard`);
+        async function readClosingRegistry() {
+            try {
+                const file = await listSitesDeps.load(resolveSitesPath());
+                return {
+                    siteIds: file.sites.map((site) => site.site_id),
+                    defaultSiteId: file.default_site_id,
+                };
+            }
+            catch {
+                return undefined;
+            }
+        }
+        const resumePath = resumeFilePathFor(resolveSitesPath());
+        const savedRun = loadResume(resumePath);
+        const resumed = savedRun !== null && (await confirmResume()) ? savedRun : null;
+        const interactiveDeps = {
+            ...withPlatform(withCa(withPin(withResume(withPersist(interactiveBase, false), resumePath)))),
+            printClosing: async (summary) => {
+                const registry = await readClosingRegistry();
+                printClosingBlock({
+                    ...summary,
+                    ...(registry !== undefined ? { registry } : {}),
+                });
+            },
+        };
+        return runMultiSiteLoop({
+            runRound: async (round) => {
+                let another = false;
+                const base = {
+                    ...interactiveDeps,
+                    confirmAnotherSite: async () => {
+                        another = await confirmAnotherSite();
+                        return another;
+                    },
+                };
+                const withContext = withSiteContext(round.first && resumed !== null ? withResumed(base, resumed) : base, {
+                    existingSiteIds: await loadSiteIds(resolveSitesPath()),
+                    siteIdDefault: round.first ? 'default' : '',
+                    repeatPass: !round.first,
+                });
+                const rc = round.first
+                    ? await runSetupThenInstall(withContext)
+                    : await wizard(withContext);
+                return { rc, another };
+            },
+        });
     }
     switch (subcommand) {
         case 'doctor': {
@@ -943,10 +946,6 @@ export async function runCli(argv, deps) {
         }
         case 'install-skill':
         case 'install': {
-            // Only `--force` is accepted here (overwrite a locally-modified
-            // skill). Reject anything else so a typo'd flag isn't silently
-            // ignored — and so the `install-skill --force` remediation that
-            // the setup-path advertises actually works.
             const tail = argv.slice(1);
             if (tail.includes('--help') || tail.includes('-h')) {
                 out(HELP_TEXT);
@@ -1002,9 +1001,6 @@ export async function runCli(argv, deps) {
                 }
                 let selection;
                 if (parsed.all) {
-                    // Non-interactive: remove from every detected client +
-                    // the skill, no prompts. `--keep-skill` opts the skill out;
-                    // `--force` overrides the modified-protection.
                     selection = {
                         clientIds: detected.map((d) => d.id),
                         removeSkill: parsed.keepSkill ? false : skillInstalled,
@@ -1018,7 +1014,6 @@ export async function runCli(argv, deps) {
                         skipFinalConfirm: parsed.yes,
                     });
                     if (picked === null) {
-                        // User cancelled — clean exit (SIGINT convention).
                         return 130;
                     }
                     selection = {
@@ -1032,7 +1027,6 @@ export async function runCli(argv, deps) {
                     return 0;
                 }
                 const result = await runUninstall(selection, uninstallDeps);
-                // Summary.
                 out('Uninstall summary:');
                 if (result.clientResults.length === 0) {
                     out('  (no AI client configs changed)');
@@ -1133,8 +1127,6 @@ export async function runCli(argv, deps) {
         case 'list-sites': {
             const tail = argv.slice(1);
             const parsed = parseIdArgs(tail, false);
-            // list-sites takes no positional id; if one slipped in it's
-            // a usage error (parseIdArgs allows zero or one).
             if (parsed.helpRequested) {
                 out(LIST_SITES_HELP);
                 return 0;
@@ -1211,9 +1203,6 @@ export async function runCli(argv, deps) {
         }
         case 'set-default': {
             const tail = argv.slice(1);
-            // W12-R2A: set-default is a routing-destructive op (every
-            // subsequent default-routed tool call lands on a different
-            // site). Allow --yes so CI can flip without a prompt.
             const parsed = parseIdArgs(tail, true);
             if (parsed.helpRequested) {
                 out(SET_DEFAULT_HELP);
@@ -1313,7 +1302,6 @@ export async function runCli(argv, deps) {
         }
     }
 }
-// ── direct CLI entry ────────────────────────────────────────────────────
 const isMain = typeof process !== 'undefined' &&
     process.argv[1] !== undefined &&
     import.meta.url === `file://${process.argv[1]}`;