@wootsup/yt-builder-mcp 1.12.0 → 2.1.0

package/dist/setup-wizard.js

@@ -1,75 +1,16 @@
-/**
- * Interactive setup wizard for `@wootsup/yt-builder-mcp`.
- *
- * `runWizard()` accepts a {@link WizardDeps} bag so unit tests can drive
- * a deterministic prompt → validate → probe → write → handshake sequence
- * without touching real subprocesses or filesystems.
- *
- * After the Round-1 audit I5 fix, this file is the wizard ALGORITHM only:
- *   - `WizardDeps` and its result types live in `setup-wizard-types.ts`.
- *   - Default real-I/O implementations + `rollbackWrites` + `majorMinor`
- *     live in `setup-wizard-defaults.ts`.
- *   - The CLI dispatcher + main-guard live in `setup-cli.ts`.
- *
- * @license MIT
- */
-import { cancel, log, note, outro, spinner } from '@clack/prompts';
-import { supportsSystemCa } from './diagnostics/ca-trust.js';
-import { hasProxyConfigured } from './net/proxy-dispatcher.js';
-import { JoomlaPlatform, WordPressPlatform, } from './platform/index.js';
-import { SERVER_NAME, SERVER_VERSION } from './server.js';
-import { buildCaEnv } from './setup-ca-env.js';
-import { buildNpxSpec } from './setup-npx-spec.js';
-import { DEFAULT_WIZARD_DEPS, rollbackWrites, } from './setup-wizard-defaults.js';
-// Re-export the public surface so `import { runWizard, WizardDeps } from
-// './setup-wizard.js'` continues to work without touching the split files.
+import { cancel, log, outro } from '@clack/prompts';
+import { JoomlaPlatform, WordPressPlatform } from './platform/index.js';
+import { SERVER_VERSION } from './server.js';
+import { attemptCaRecovery } from './setup/ca-recovery.js';
+import { RegistryWriteFailure, REGISTRY_SITE_MISSING_REMEDY, } from './setup/registry-remedy.js';
+import { resolveHostPlatform } from './setup/host-platform.js';
+import { installClientConfigs } from './setup/install-configs.js';
+import { announcePhase, runStep } from './setup/phases.js';
+import { resolveSiteId } from './sites/schema.js';
+import { DEFAULT_WIZARD_DEPS, rollbackWrites } from './setup-wizard-defaults.js';
 export { DEFAULT_WIZARD_DEPS, majorMinor } from './setup-wizard-defaults.js';
-// 1.0.2 Wave-R Part 2: renamed `yootheme-builder` → `yt-builder-mcp`
-// to match the package slug + REST namespace + GitHub repo + skill
-// folder. Pre-1.0.1 installs (alpha-tester only, per Thomas 2026-05-23)
-// would land their server under the old key; no migration logic is
-// shipped because there were no production installs to migrate. If
-// someone re-runs setup they'll get a fresh `yt-builder-mcp` entry +
-// the legacy `yootheme-builder` entry stays dormant (harmless, points
-// at the same npm package).
-const SERVER_KEY = 'yt-builder-mcp';
-/**
- * G-E #6 — the honest outcome message when the operator chose the OS trust store
- * (`--use-system-ca`). Node only consults that store when (re)started with the
- * flag, which the WRITTEN config does but the setup process did NOT — so we can
- * never validate it in-process. We say so plainly instead of reporting a false ❌.
- */
-const SYSTEM_CA_DEFERRED_MESSAGE = '✅ Configured to use the OS trust store (--use-system-ca) — this takes effect when ' +
-    "your AI client next launches the server. The current setup process can't validate it in-process.";
-/**
- * Honest outcome when the health probe failed with an opaque TIMEOUT and we
- * auto-attempted the OS-trust-store recovery (a TLS-inspecting corporate proxy
- * whose CA chain can't be built hangs into a 30s timeout rather than a clean
- * cert error). Like {@link SYSTEM_CA_DEFERRED_MESSAGE}, system mode can't be
- * validated in-process — but a timeout is ALSO ambiguous (it can be a genuine
- * proxy/VPN reachability problem), so we keep the proxy/VPN guidance visible:
- * if the next launch still fails, the cause was reachability, not the CA.
- */
-const TIMEOUT_SYSTEM_CA_DEFERRED_MESSAGE = '✅ The connection timed out — a TLS-inspecting corporate proxy can hang the handshake this way, so the ' +
-    'server was configured to use the OS trust store (--use-system-ca), validated when your AI client next ' +
-    'launches the server. If it still fails after restart, the timeout was a reachability problem instead: ' +
-    'the site may be internal (VPN needed) or require a proxy (set HTTPS_PROXY). Never disables TLS verification.';
-/**
- * Run the interactive setup wizard. Returns a process exit-code so the
- * outer dispatcher can `process.exit(rc)` cleanly.
- *
- * Exit codes:
- *   0  — success (configs written, handshake OK)
- *   1  — invalid input that prevents proceeding
- *   2  — health probe failed and user declined to continue
- *   3  — auth probe failed and user declined to continue
- *   4  — write failed; configs rolled back
- *   5  — handshake failed; configs rolled back
- *   130 — user cancelled (matches the SIGINT convention)
- */
 export async function runWizard(deps = DEFAULT_WIZARD_DEPS) {
     const logFn = deps.log ?? ((line) => process.stderr.write(`${line}\n`));
-    // 1. Detect clients + collect answers.
     const detected = deps.detectClients();
     const answers = await deps.prompt({ detected });
     if (answers === null)
@@ -78,216 +19,96 @@ export async function runWizard(deps = DEFAULT_WIZARD_DEPS) {
         logFn('Both the WordPress URL and the Bearer key are required.');
         return 1;
     }
-    // 1b. Resolve the host platform EXACTLY ONCE, up-front, so every probe
-    //     AND the written config target the correct REST namespace (WordPress
-    //     `/wp-json/...` vs Joomla `/api/index.php/...`). This is the fix for
-    //     the silent-WordPress class: an origin-only Joomla URL used to fall
-    //     through to `/wp-json` at every probe and at runtime.
-    //
-    //     Resolution order:
-    //       1. `--platform` flag (answers.platform) WINS — no probe.
-    //       2. `deps.resolvePlatform` (URL-shape → Joomla-first runtime probe)
-    //          → a concrete kind, or `null` when it cannot decide.
-    //       3. On `null`: PROMPT (interactive) via `deps.promptPlatform`, else
-    //          warn + fall back to WordPress (non-interactive back-compat).
-    //     We never probe per-request afterwards — the resolved Platform is
-    //     threaded into all probes below.
-    let resolvedKind;
-    if (answers.platform !== undefined) {
-        resolvedKind = answers.platform;
-    }
-    else {
-        const detected = deps.resolvePlatform !== undefined
-            ? await deps.resolvePlatform(answers.wpUrl)
-            : null;
-        if (detected !== null) {
-            resolvedKind = detected;
-        }
-        else if (deps.promptPlatform !== undefined) {
-            const picked = await deps.promptPlatform();
-            if (picked === null) {
-                cancel('Setup cancelled.');
-                return 130;
-            }
-            resolvedKind = picked;
-        }
-        else {
-            resolvedKind = 'wordpress';
-            logFn(`Could not auto-detect the platform for ${answers.wpUrl} — defaulting to WordPress. `
-                + 'Re-run with `--platform joomla` if this is a Joomla install.');
-        }
-    }
+    const resolvedKind = await resolveHostPlatform({ answers, deps, logFn });
+    if (resolvedKind === null)
+        return 130;
     const resolvedPlatform = resolvedKind === 'joomla'
         ? new JoomlaPlatform(answers.wpUrl)
         : new WordPressPlatform(answers.wpUrl);
-    // 2a. Identity probe (no auth) — confirms the URL hosts our plugin
-    //     and cross-checks against the URL the user entered. Optional
-    //     dep for back-compat: missing field = skip (older WizardDeps
-    //     bags + pre-6.5 plugins don't expose it).
-    if (deps.probeIdentity !== undefined) {
-        const idSpinner = spinner();
-        idSpinner.start('Verifying plugin identity…');
-        const identity = await deps.probeIdentity(answers.wpUrl, resolvedPlatform);
-        if (identity.ok) {
-            const summary = identity.siteurl !== undefined
-                ? `Plugin identified at ${identity.siteurl}.`
-                : 'Plugin identified.';
-            idSpinner.stop(summary);
-            if (identity.siteurl !== undefined && identity.siteurl !== answers.wpUrl) {
-                log.warn(`URL mismatch: you entered ${answers.wpUrl} but the plugin reports its canonical URL as ${identity.siteurl}. ` +
-                    `Using the URL you entered — fix the mismatch if you get auth errors.`);
-            }
+    if (deps.saveResume !== undefined) {
+        try {
+            await deps.saveResume({
+                url: answers.wpUrl,
+                platform: resolvedKind,
+                clients: answers.selectedClients,
+            });
         }
-        else {
-            idSpinner.stop('Identity probe failed.');
+        catch (e) {
+            logFn(`Could not save the setup resume file: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    announcePhase('Checking');
+    const probeIdentity = deps.probeIdentity;
+    if (probeIdentity !== undefined) {
+        const identity = await runStep({
+            running: 'Verifying plugin identity…',
+            run: async () => probeIdentity(answers.wpUrl, resolvedPlatform),
+            verdict: (r) => r.ok
+                ? {
+                    ok: true,
+                    message: r.siteurl !== undefined
+                        ? `Plugin identified at ${r.siteurl}.`
+                        : 'Plugin identified.',
+                }
+                : { ok: false, message: 'Identity probe failed.' },
+        });
+        if (!identity.ok) {
             log.warn(`Identity probe: ${identity.error ?? 'unknown'} (continuing — older plugins lack this endpoint).`);
         }
+        else if (identity.siteurl !== undefined && identity.siteurl !== answers.wpUrl) {
+            log.warn(`URL mismatch: you entered ${answers.wpUrl} but the plugin reports its canonical URL as ${identity.siteurl}. ` +
+                `Using the URL you entered — fix the mismatch if you get auth errors.`);
+        }
     }
-    // The CA choice the wizard ends up writing into the env block. Seeded from
-    // any non-interactive `--ca` / `--ca=system` answer, then possibly set by
-    // the interactive CA prompt (G-D #6) when a probe hits a TLS-trust error.
     let caChoice = {
         ...(answers.caCertPath !== undefined ? { caCertPath: answers.caCertPath } : {}),
         ...(answers.caMode !== undefined ? { caMode: answers.caMode } : {}),
     };
     const nodeVersion = deps.nodeVersion ?? process.version;
-    // 2b. Health probe (no auth).
-    const healthSpinner = spinner();
-    healthSpinner.start('Probing plugin health…');
-    let health = await deps.probeHealth(answers.wpUrl, resolvedPlatform);
+    const now = deps.now ?? (() => performance.now());
+    const healthProbeStartedAt = now();
+    let health = await runStep({
+        running: 'Probing plugin health…',
+        run: async () => deps.probeHealth(answers.wpUrl, resolvedPlatform),
+        verdict: (r) => r.ok
+            ? {
+                ok: true,
+                message: r.pluginVersion !== undefined
+                    ? `Plugin reachable (v${r.pluginVersion}).`
+                    : 'Plugin reachable.',
+            }
+            : { ok: false, message: 'Plugin probe failed.' },
+    });
+    const healthProbeMs = now() - healthProbeStartedAt;
+    let timeoutMs;
+    if (healthProbeMs > 5000 && (health.ok || health.timeout === true)) {
+        const seconds = Math.round(healthProbeMs / 1000);
+        const message = health.ok
+            ? `Site took ${seconds}s to answer. Raise the timeout to 30s? (default 15s)`
+            : `No answer within ${seconds}s. Raise the timeout to 30s? (default 15s)`;
+        const raise = await deps.confirmContinue(message);
+        if (raise)
+            timeoutMs = 30_000;
+    }
     let auth;
-    // Set once the operator picked the OS trust store (--use-system-ca) and the
-    // post-CA re-probe failed: the OS store can't be validated in THIS process,
-    // so we defer validation to the next server launch instead of treating the
-    // (false-negative) failure as a reason to discard the correct config.
     let systemCaDeferred = false;
-    if (health.ok) {
-        healthSpinner.stop(health.pluginVersion !== undefined
-            ? `Plugin reachable (v${health.pluginVersion}).`
-            : 'Plugin reachable.');
-    }
-    else {
-        healthSpinner.stop('Plugin probe failed.');
-        // G-D #6/#8 — a TLS chain-of-trust failure is the corporate
-        // TLS-inspection signature. Offer to self-configure the CA (OS trust
-        // store on a supporting Node, or a .pem path), write it into the env
-        // block, and RE-PROBE so the operator sees ✅/❌ now instead of a silent
-        // first-tool-call timeout. Only when a CA prompt is wired AND none was
-        // already supplied non-interactively.
-        const caAlreadyChosen = caChoice.caCertPath !== undefined || caChoice.caMode !== undefined;
-        if (health.caTrust === true && deps.promptCa !== undefined && !caAlreadyChosen) {
-            log.warn(`Corporate TLS-inspection detected: ${health.error ?? 'the TLS certificate could not be verified'}`);
-            const systemCaSupported = supportsSystemCa(nodeVersion);
-            const picked = await deps.promptCa({ systemCaSupported });
-            if (picked === null) {
-                cancel('Setup cancelled.');
-                return 130;
-            }
-            if (picked.choice !== 'skip') {
-                caChoice =
-                    picked.choice === 'system'
-                        ? { caMode: 'system' }
-                        : { caCertPath: picked.path };
-                // Re-probe with the CA applied at runtime. When no dedicated
-                // re-prober is wired, fall back to the ordinary probes (the
-                // choice is still recorded into the env block either way).
-                const reSpinner = spinner();
-                reSpinner.start('Re-checking the connection with the CA applied…');
-                if (deps.applyAndReProbe !== undefined) {
-                    const re = await deps.applyAndReProbe({ wpUrl: answers.wpUrl, bearer: answers.bearer, choice: picked, platform: resolvedPlatform });
-                    health = re.health;
-                    auth = re.auth;
-                }
-                else {
-                    health = await deps.probeHealth(answers.wpUrl, resolvedPlatform);
-                    auth = await deps.probeAuth(answers.wpUrl, answers.bearer, resolvedPlatform);
-                }
-                // G-E #6 honesty fix: the OS trust store is consulted ONLY when
-                // Node is (re)started with --use-system-ca — which the WRITTEN
-                // config does, but THIS setup process was not. So an in-process
-                // re-probe in system mode is a guaranteed false-negative: a ❌
-                // here would (on decline) discard the CORRECT config. Treat a
-                // system-mode re-probe failure as "configured, validates at next
-                // launch" — write the config and skip the generic/auth/handshake
-                // in-process checks (which would hit the same untrusted CA). File
-                // (.pem) mode DOES validate in-process (undici Agent trusts the
-                // CA), so it keeps the honest ✅/❌ verdict.
-                if (picked.choice === 'system' && !health.ok) {
-                    systemCaDeferred = true;
-                    reSpinner.stop('OS trust store configured (--use-system-ca).');
-                    logFn(SYSTEM_CA_DEFERRED_MESSAGE);
-                }
-                else {
-                    reSpinner.stop(health.ok ? '✅ connected — CA trusted.' : `❌ still failing: ${health.error ?? 'unknown'}`);
-                }
-            }
-        }
-        // Timeout → OS-trust-store auto-bake (customer corporate-CA timeout gap).
-        // A TLS-inspecting corporate proxy whose root CA chain can't be built
-        // often hangs the handshake into an OPAQUE 30s timeout rather than a
-        // clean cert code — so `health.caTrust` is false and the CA prompt above
-        // never fires, leaving the operator to set NODE_OPTIONS=--use-system-ca
-        // by hand. When the probe failed with a TIMEOUT, this Node can read the
-        // OS trust store (Node ≥ 22.15), and NO CA was chosen yet, attempt the
-        // SAME system-CA recovery the caTrust branch does: bake caMode:'system'
-        // and RE-PROBE. `--use-system-ca` only ADDS the OS store (never disables
-        // TLS), so attempting it on a timeout is safe even if the timeout turns
-        // out to be a genuine proxy/VPN issue — the re-probe just fails again and
-        // the proxy/VPN guidance is still shown. Like the caTrust branch, system
-        // mode can't validate in-process, so a still-failing re-probe defers
-        // validation to next launch (the written config is correct) rather than
-        // discarding it; the ambiguity (CA vs reachability) is surfaced honestly.
-        const caChosenSoFar = caChoice.caCertPath !== undefined || caChoice.caMode !== undefined;
-        if (!health.ok && health.timeout === true && !caChosenSoFar && supportsSystemCa(nodeVersion)) {
-            log.warn(`The connection timed out — attempting the OS trust store (--use-system-ca) in case a corporate TLS-inspection proxy is hanging the TLS handshake: ${health.error ?? 'timeout'}`);
-            caChoice = { caMode: 'system' };
-            const reSpinner = spinner();
-            reSpinner.start('Re-checking the connection with --use-system-ca applied…');
-            if (deps.applyAndReProbe !== undefined) {
-                const re = await deps.applyAndReProbe({
-                    wpUrl: answers.wpUrl,
-                    bearer: answers.bearer,
-                    choice: { choice: 'system' },
-                    platform: resolvedPlatform,
-                });
-                health = re.health;
-                auth = re.auth;
-            }
-            else {
-                health = await deps.probeHealth(answers.wpUrl, resolvedPlatform);
-                auth = await deps.probeAuth(answers.wpUrl, answers.bearer, resolvedPlatform);
-            }
-            if (health.ok) {
-                reSpinner.stop('✅ connected — OS trust store resolved the timeout.');
-            }
-            else {
-                // System mode can't validate in-process (the OS store is only
-                // read when Node restarts WITH the flag). Defer validation to the
-                // next launch instead of discarding the (now correct) config —
-                // but keep the proxy/VPN guidance visible for the ambiguous case.
-                systemCaDeferred = true;
-                reSpinner.stop('OS trust store configured (--use-system-ca).');
-                logFn(TIMEOUT_SYSTEM_CA_DEFERRED_MESSAGE);
-            }
-        }
-        else if (!health.ok && health.timeout === true && !caChosenSoFar && !supportsSystemCa(nodeVersion)) {
-            // Below the system-CA floor we cannot write a flag the target Node
-            // would reject. Warn to supply a .pem instead (the only CA option on
-            // an old Node), then fall through to the generic continue decision.
-            // Route through BOTH the clack UI and the logFn sink so the warning is
-            // capturable in non-TTY / test contexts (mirrors the P0.1 below-floor
-            // branch). Intentionally does NOT name the OS-trust-store flag (the
-            // whole point is that it's unavailable on this Node).
-            const warnPem = `The connection timed out and this Node (${nodeVersion}) is below 22.15, so the OS trust store cannot be read. ` +
-                'If a corporate TLS-inspection proxy is the cause, re-run setup with `--ca <path-to-corp-root-ca.pem>` ' +
-                '(export your corporate root CA to a .pem). Otherwise the site may need a VPN/proxy. Never disable TLS verification.';
-            log.warn(warnPem);
-            logFn(warnPem);
-        }
-        // If the connection is still down after the (optional) CA step, fall
-        // through to the generic continue-anyway decision — UNLESS system-CA was
-        // configured, where validation is deferred to next launch and the (false-
-        // negative) in-process failure must not discard the config.
+    if (!health.ok) {
+        const recovered = await attemptCaRecovery({
+            answers,
+            deps,
+            platform: resolvedPlatform,
+            nodeVersion,
+            caChoice,
+            health,
+            logFn,
+        });
+        if (recovered.cancelled === true)
+            return 130;
+        caChoice = recovered.caChoice;
+        health = recovered.health;
+        if (recovered.auth !== undefined)
+            auth = recovered.auth;
+        systemCaDeferred = recovered.systemCaDeferred;
         if (!health.ok && !systemCaDeferred) {
             log.error(`Could not reach the plugin: ${health.error ?? 'unknown'}`);
             const cont = await deps.confirmContinue('Continue anyway and write the config? (You can fix this later.)');
@@ -297,20 +118,14 @@ export async function runWizard(deps = DEFAULT_WIZARD_DEPS) {
             }
         }
     }
-    // 3. Auth probe (Bearer). Skip when the CA re-probe already produced an
-    //    auth result (avoids a redundant round-trip on the corporate path), or
-    //    when system-CA validation is deferred (an in-process auth probe would
-    //    hit the same untrusted-CA false-negative and discard the config).
     if (auth === undefined && !systemCaDeferred) {
-        const authSpinner = spinner();
-        authSpinner.start('Verifying Bearer key…');
-        auth = await deps.probeAuth(answers.wpUrl, answers.bearer, resolvedPlatform);
-        if (auth.ok) {
-            authSpinner.stop('Bearer key accepted.');
-        }
-        else {
-            authSpinner.stop('Bearer probe failed.');
-        }
+        auth = await runStep({
+            running: 'Verifying Bearer key…',
+            run: async () => deps.probeAuth(answers.wpUrl, answers.bearer, resolvedPlatform),
+            verdict: (r) => r.ok
+                ? { ok: true, message: 'Bearer key accepted.' }
+                : { ok: false, message: 'Bearer probe failed.' },
+        });
     }
     const authOk = auth?.ok ?? false;
     if (!authOk && !systemCaDeferred) {
@@ -321,130 +136,41 @@ export async function runWizard(deps = DEFAULT_WIZARD_DEPS) {
             return 3;
         }
     }
-    // 4. Write configs. Track previous content for rollback.
-    //
-    // Wave 7 (2026-05-24): write BOTH env-var names so the config works
-    // with every release line — pre-Wave-7 servers only know
-    // YTB_MCP_WP_URL; Wave-7+ servers prefer YTB_MCP_SITE_URL but still
-    // honour the legacy alias. The wizard intentionally writes both so a
-    // wizard-rendered config never needs editing after an npm upgrade.
-    //
-    // Slice 3 (proxy flip): YTB_MCP_MODE=proxy makes the Node package a thin
-    // stdio<->HTTP proxy to the plugin's own PHP MCP endpoint
-    // (${site}/wp-json/yt-builder-mcp/mcp). resolveMode() reads YTB_MCP_SITE_URL
-    // + YTB_MCP_BEARER_TOKEN verbatim; the legacy WP_URL key is harmless (read
-    // only by the fat loader). Flip YTB_MCP_MODE off to fall back to fat.
-    // Corporate TLS-inspection: trust the chosen root CA natively. `buildCaEnv`
-    // resolves the right key for the strategy + Node version: a `.pem` path →
-    // NODE_EXTRA_CA_CERTS (any Node); OS trust store → NODE_OPTIONS=--use-system-ca
-    // (Node ≥ 22.15, else warn to use a .pem). Never disables verification.
-    // Pass an empty `currentEnv` so the WRITTEN config's NODE_OPTIONS is a clean
-    // `--use-system-ca` for the MCP server's own runtime — not the operator's
-    // current shell NODE_OPTIONS (which is irrelevant to the spawned server).
-    //
-    // P0.1 (default-on CA bake) — the install-blocker customer hit: a DEFAULT
-    // `setup` (no `--ca` flag) against a corporate-proxied / TLS-inspected site
-    // baked NOTHING, so the very first `/mcp` connect hung 30s on the untrusted
-    // CA. Make the bake default-on: when the operator gave NO explicit CA choice
-    // AND we have a corporate-network signal (a forward proxy is configured, OR
-    // the health probe reported a TLS chain-of-trust failure), auto-select the
-    // OS trust store on a supporting Node (Node ≥ 22.15 → NODE_OPTIONS=
-    // --use-system-ca, zero-export). On an older Node we can't write a flag it
-    // would reject, so we leave the env untouched and warn the operator to
-    // re-run with `--ca <corp-root-ca.pem>`. Idempotent: `withSystemCaFlag`
-    // dedupes the flag. An explicit `--ca` / interactive CA choice always wins
-    // (this only fills the gap when the operator chose nothing).
-    const caExplicit = caChoice.caCertPath !== undefined || caChoice.caMode !== undefined;
-    if (!caExplicit) {
-        const proxyPresent = hasProxyConfigured(deps.processEnv ?? process.env);
-        const tlsTrustFailure = health.caTrust === true;
-        if (proxyPresent || tlsTrustFailure) {
-            const reason = proxyPresent
-                ? 'a corporate forward proxy (HTTP(S)_PROXY) is configured'
-                : 'the site presented an untrusted (TLS-inspection) certificate';
-            if (supportsSystemCa(nodeVersion)) {
-                caChoice = { caMode: 'system' };
-                const baked = `Corporate network detected (${reason}) — baking NODE_OPTIONS=--use-system-ca so the server trusts your OS / corporate root CA store. Re-run with \`--ca <path-to-corp-root-ca.pem>\` to pin a specific .pem instead. Never disables TLS verification.`;
-                // Route through BOTH the clack UI (human, interactive) and the
-                // logFn sink (stderr / captured in tests + non-TTY installs).
-                log.info(baked);
-                logFn(baked);
-            }
-            else {
-                const warnPem = `Corporate network detected (${reason}), but this Node (${nodeVersion}) is below 22.15 and cannot read the OS trust store (--use-system-ca). Re-run setup with \`--ca <path-to-corp-root-ca.pem>\` (export your corporate root CA to a .pem). Never disable TLS verification.`;
-                log.warn(warnPem);
-                logFn(warnPem);
-            }
-        }
-    }
-    const caEnv = buildCaEnv(caChoice, nodeVersion, {});
-    for (const w of caEnv.warnings)
-        log.warn(w);
-    // customer gap #15 — pin the npx version when requested (`--pin` /
-    // YTB_MCP_VERSION); default is the floating @latest the update-notifier
-    // expects. A malformed pin degrades to floating with a warning.
-    const npx = buildNpxSpec(SERVER_NAME, answers.versionPin);
-    if (npx.error !== undefined)
-        log.warn(npx.error);
-    if (npx.pinned) {
-        log.info(`Pinning the MCP server to ${npx.spec} (air-gapped / reproducible). Re-run setup without --pin to float to the latest.`);
-    }
-    const serverConfig = {
-        command: 'npx',
-        args: ['-y', npx.spec],
-        env: {
-            YTB_MCP_SITE_URL: answers.wpUrl,
-            YTB_MCP_WP_URL: answers.wpUrl,
-            YTB_MCP_BEARER_TOKEN: answers.bearer,
-            YTB_MCP_MODE: 'proxy',
-            // Persist the resolved platform so the runtime proxy (proxy/mode.ts)
-            // routes to the Joomla `/api/index.php/...` `/mcp` endpoint instead
-            // of silently assuming the WordPress `/wp-json/...` one. Shared
-            // contract with Slice A: values are 'wordpress' | 'joomla'.
-            YTB_MCP_PLATFORM: resolvedKind,
-            ...caEnv.env,
-        },
-    };
-    const writes = [];
-    let writeFailed = false;
-    for (const id of answers.selectedClients) {
-        const result = await deps.writeClient(id, SERVER_KEY, serverConfig);
-        writes.push(result);
-        if (!result.ok) {
-            writeFailed = true;
-            break;
-        }
-    }
-    const summary = writes
-        .map((r) => r.ok
-        ? `  ✓ ${r.label}: configured`
-        : `  ✗ ${r.label}: FAILED (${r.error ?? 'unknown'})`)
-        .join('\n');
-    note(summary, 'Results');
-    if (writeFailed) {
-        log.error('Write failed — rolling back any partial writes.');
-        await rollbackWrites(writes, logFn);
+    announcePhase('Installing');
+    const installed = await installClientConfigs({
+        answers,
+        deps,
+        resolvedKind,
+        caChoice,
+        health,
+        nodeVersion,
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        logFn,
+    });
+    if (installed.writeFailed)
         return 4;
-    }
-    // 5. Dist-tag handshake (only when auth probe succeeded — there's
-    // no point handshaking with a known-bad token).
+    const writes = installed.writes;
     if (authOk) {
-        const hsSpinner = spinner();
-        hsSpinner.start('Verifying dist-tag handshake…');
-        const hs = await deps.handshake(answers.wpUrl, answers.bearer, SERVER_VERSION, resolvedPlatform);
+        const hs = await runStep({
+            running: 'Verifying dist-tag handshake…',
+            run: async () => deps.handshake(answers.wpUrl, answers.bearer, SERVER_VERSION, resolvedPlatform),
+            verdict: (r) => {
+                if (!r.ok)
+                    return { ok: false, message: 'Handshake failed.' };
+                return {
+                    ok: true,
+                    message: r.warning !== undefined ? 'Handshake OK (with warning).' : 'Handshake OK.',
+                };
+            },
+        });
         if (!hs.ok) {
-            hsSpinner.stop('Handshake failed.');
             log.error(`Handshake failed after writing configs: ${hs.error ?? 'unknown'}. Rolling back.`);
             await rollbackWrites(writes, logFn);
+            cancel('Setup stopped: the handshake failed and the client configs were rolled back.');
             return 5;
         }
-        if (hs.warning !== undefined) {
-            hsSpinner.stop('Handshake OK (with warning).');
+        if (hs.warning !== undefined)
             log.warn(hs.warning);
-        }
-        else {
-            hsSpinner.stop('Handshake OK.');
-        }
     }
     else if (systemCaDeferred) {
         log.info('Skipping the live handshake — the OS trust store is validated when the MCP server next launches.');
@@ -452,33 +178,62 @@ export async function runWizard(deps = DEFAULT_WIZARD_DEPS) {
     else {
         log.warn('Skipping handshake because the Bearer probe failed.');
     }
-    // W9 — persist the answers to the multi-site sites.json registry
-    // when the dispatcher wired a `persistSite` callback. We do this
-    // AFTER the handshake passes so the sites.json never contains a
-    // site that failed the probe. Optional hook so pre-W9 callers
-    // (and tests that drive the wizard without sites.json) skip the
-    // write transparently.
+    let persistFailed = false;
     if (deps.persistSite !== undefined && writes.every((r) => r.ok)) {
         try {
-            // Persist the RESOLVED platform (not 'auto') so sites.json records
-            // the concrete kind the wizard decided on — deterministic routing
-            // on the next boot, no re-probe.
-            await deps.persistSite({ ...answers, platform: resolvedKind });
+            const receipt = await deps.persistSite({ ...answers, platform: resolvedKind });
+            if (typeof receipt === 'string' && receipt.length > 0)
+                log.step(receipt);
         }
         catch (e) {
             const msg = e instanceof Error ? e.message : String(e);
-            log.error(`Failed to persist site to sites.json: ${msg}`);
-            // Don't rollback the client configs — the env-var path
-            // still works; the sites.json file is an additive surface.
-            // Operator just sees the warning + can retry with `add-site`.
+            persistFailed = true;
+            const cause = msg.replace(/\.\s*$/, '');
+            log.error(`Failed to persist site to sites.json: ${cause}. `
+                + (e instanceof RegistryWriteFailure
+                    ? e.remedy
+                    : REGISTRY_SITE_MISSING_REMEDY));
         }
     }
-    if (writes.every((r) => r.ok) && (authOk || systemCaDeferred)) {
-        outro('Done — restart your AI client to load the new MCP server.');
+    if (deps.installSkill !== undefined) {
+        try {
+            await runStep({
+                running: 'Installing the skill…',
+                run: deps.installSkill,
+                verdict: (message) => ({ ok: true, message }),
+                onThrow: (message) => `Skill install skipped (${message}). Run 'yt-builder-mcp install-skill' manually.`,
+            });
+        }
+        catch {
+        }
     }
-    else {
-        outro('Setup finished with warnings. See the messages above.');
+    try {
+        deps.clearResume?.();
+    }
+    catch (e) {
+        logFn(`Could not remove the setup resume file: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (persistFailed) {
+        outro('Setup finished: your AI clients are configured, the site registry is not.');
+        return 6;
+    }
+    const cleanPass = writes.every((r) => r.ok) && (authOk || systemCaDeferred);
+    if (deps.confirmAnotherSite !== undefined && (await deps.confirmAnotherSite())) {
+        if (!cleanPass) {
+            log.warn('This site is configured, but with warnings. See the messages above.');
+        }
+        return 0;
+    }
+    if (cleanPass) {
+        await deps.printClosing?.({
+            siteId: resolveSiteId(answers.siteId),
+            url: answers.wpUrl,
+            clientLabels: writes.filter((r) => r.ok).map((r) => r.label),
+        });
     }
+    outro(cleanPass
+        ? 'Done — restart your AI client to load the new MCP server.'
+        : 'Setup finished with warnings. See the messages above.');
     return 0;
 }
 //# sourceMappingURL=setup-wizard.js.map