@pleri/olam-cli 0.1.201 → 0.1.205

package/dist/commands/setup.js

@@ -1,1374 +0,0 @@
-/**
- * olam setup — substrate-aware fresh-host wizard.
- *
- * Phase C2 of olam-operator-onboarding-parity (plan
- * ~/.claude/plans/olam-operator-onboarding-parity.md).
- *
- * Substrate-aware orchestration. Default substrate = kubernetes (k3d on all
- * platforms — macOS and Linux alike). Existing installs whose ~/.olam/config.json
- * carries host.substrate: 'compose' are protected — they continue on docker/compose
- * and see a one-line migration hint; no auto-migration.
- *
- * Kubernetes substrate phases (default for fresh installs):
- *   Phase 1:   System check     (kubectl on PATH + docker daemon + Node ≥20)
- *   Phase 1.5: Install k3d      (brew install k3d when available; else upstream install.sh)
- *   Phase 2:   olam CLI sanity  (--version returns)
- *   Phase 2.5: Provision cluster (k3d cluster create olam-dev; k3d updates ~/.kube/config)
- *   Phase 2.6: Pin kubectl context (writes host.kubectl_context_pinned = k3d-olam-dev)
- *   Phase 3:   Bootstrap        (subprocess: olam bootstrap with kubernetes substrate)
- *   Phase 3.5: K3d HTTPS bootstrap (mkcert install + TLS Secret → Traefik IngressRoute)
- *   …        same as docker thereafter
- *
- * Docker substrate phases (existing compose installs or --substrate=docker):
- *   Phase 1:   System check     (Docker daemon reachable + Node ≥20)
- *   Phase 1.5: (no-op for docker)
- *   Phase 2:   olam CLI sanity  (--version returns)
- *   Phase 2.5: (no-op for docker)
- *   Phase 3:   Bootstrap        (subprocess: olam bootstrap)
- *   Phase 3.5: (no-op for docker)
- *   Phase 4:   Shell init       (idempotent append of completion eval-line)
- *   Phase 5:   Init global config (ensure ~/.olam/config.json has host.substrate set)
- *   Phase 5a:  Skill source picker (runs unconditionally; auto-skips when sources already registered)
- *   Phase 5b:  Project sweep
- *   Phase 6:   Auth prompt      (offer interactive `olam auth login`)
- *   Phase 7:   Final verify     (subprocess: olam doctor; halt on non-zero)
- *
- * End-state prints "next steps" pointing at the 3-contract docs per
- * CLAUDE.md's "Reading order for new orgs."
- *
- * Failure semantics: setup fails fast at the first failed phase + prints
- * a named remedy. All phases are idempotent so re-running is safe.
- *
- * Flags:
- *   --substrate=<docker|kubernetes>  substrate to target (default: kubernetes; alias k3s→kubernetes)
- *   --cluster-name=<name>            k3d cluster name (default: olam-dev). Useful for operators with
- *                                    pre-existing clusters or running multiple olam stacks side-by-side.
- *   --skip-https-bootstrap           skip Phase 3.5 (operator manages TLS certs manually)
- *   --skip-shell-init                skip Phase 4 (operator manages shell rc manually)
- *   --skip-auth                      skip Phase 6 (operator will run `olam auth login` later)
- *   --yes / -y                       auto-affirm every prompt (non-interactive)
- *
- * Reversibility: clean-revert; each phase delegates to a separately-
- * tested primitive. Phase 4 keeps a `<rc>.olam-bak.<ts>` backup.
- */
-import { spawn, spawnSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import path from 'node:path';
-import { createInterface } from 'node:readline';
-import { readCliVersion } from '../cli-version.js';
-import { probeDockerDaemon, probeComposePlugin, probeKubectl, probeK3d, probeColimaKubernetesEnabled, } from '../lib/health-probes.js';
-import { discoverOfferableContexts, defaultClusterInfo, defaultGetContexts, defaultIsIdle, } from '../lib/k8s-context-discovery.js';
-import { appendIdempotent, resolveShellRc } from '../lib/shell-rc.js';
-import { applyKubectlContextPin, findProjectRoot, runGlobalInit } from './init.js';
-import { ensureTlsInstalled } from './services-tls.js';
-import { printError, printHeader, printInfo, printSuccess, printWarning } from '../output.js';
-import { pickSkillSourcePhase, formatPostSetupSuggestion, } from './setup-phase-5a-skill-source.js';
-import { runProjectSweepPhase } from './setup-phase-5b-project-sweep.js';
-import { runKgHookPhase } from './setup-phase-8-kg-hook.js';
-import { runMemoryBridgePhase } from './setup-phase-9-memory-bridge.js';
-import { OLAM_CONFIG_PATH, writeConfig } from '../lib/config.js';
-import { migrateSecretIfNeeded, KNOWN_SECRET_NAMES } from '@olam/core/src/secrets/paths.js';
-import { resolveKubectlContext } from '../lib/kubectl-context.js';
-const REQUIRED_NODE_MAJOR = 20;
-/** k3d cluster name provisioned by olam setup --substrate=kubernetes. */
-export const SETUP_K3D_CLUSTER_NAME = 'olam-dev';
-const NEXT_STEPS_DOCS_DOCKER = [
-    'https://github.com/pleri/olam/blob/main/docs/architecture/devbox-contract.md  — image contract',
-    'https://github.com/pleri/olam/blob/main/docs/architecture/manifest-spec.md    — per-repo .adb.yaml schema',
-    'https://github.com/pleri/olam/blob/main/docs/architecture/config-spec.md      — workspace .olam/config.yaml schema',
-];
-const NEXT_STEPS_DOCS_KUBERNETES = [
-    'https://github.com/pleri/olam/blob/main/docs/architecture/devbox-contract.md  — image contract',
-    'https://github.com/pleri/olam/blob/main/docs/architecture/manifest-spec.md    — per-repo .adb.yaml schema',
-    'https://github.com/pleri/olam/blob/main/docs/architecture/config-spec.md      — workspace .olam/config.yaml schema',
-    'https://github.com/pleri/olam/blob/main/docs/k8s/SETUP.md                     — k3d operator guide',
-];
-// ── Default deps ───────────────────────────────────────────────────────
-const defaultSpawn = (cmd, args) => new Promise((resolve) => {
-    const child = spawn(cmd, [...args], { stdio: 'inherit' });
-    child.on('exit', (code) => resolve({ status: code }));
-    child.on('error', () => resolve({ status: 1 }));
-});
-const defaultPrompt = (question, defaultYes) => {
-    // MEDIUM fix (Phase C CP3): non-TTY stdin (CI pipeline forgot `--yes`,
-    // or `olam setup < /dev/null`) would otherwise hang on `readline.question`
-    // forever with no diagnostic. When stdin is not a TTY, fall back to the
-    // default answer with a stderr hint so the operator knows what happened.
-    if (!process.stdin.isTTY) {
-        process.stderr.write(`[olam setup] non-TTY stdin detected; using default answer (${defaultYes ? 'yes' : 'no'}). `
-            + `Re-run with \`--yes\` for explicit non-interactive mode.\n`);
-        return Promise.resolve(defaultYes);
-    }
-    return new Promise((resolve) => {
-        const rl = createInterface({ input: process.stdin, output: process.stdout });
-        const suffix = defaultYes ? ' [Y/n]: ' : ' [y/N]: ';
-        rl.question(`${question}${suffix}`, (answer) => {
-            rl.close();
-            const t = answer.trim().toLowerCase();
-            if (t === '')
-                resolve(defaultYes);
-            else if (t === 'y' || t === 'yes')
-                resolve(true);
-            else if (t === 'n' || t === 'no')
-                resolve(false);
-            else
-                resolve(defaultYes);
-        });
-        // Belt-and-braces: if stdin closes mid-prompt (EOF), resolve with default.
-        rl.on('close', () => resolve(defaultYes));
-    });
-};
-/** k3d / DNS-label name validation — same rules k3d enforces. */
-const CLUSTER_NAME_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
-/**
- * Validate the --cluster-name value.
- * Returns an error message when invalid, or null when valid.
- */
-export function validateClusterName(name) {
-    if (name.length === 0)
-        return 'cluster name must not be empty';
-    if (name.length > 63)
-        return 'cluster name must be ≤63 characters (DNS label limit)';
-    if (!CLUSTER_NAME_RE.test(name)) {
-        return (`cluster name '${name}' is invalid — must match ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$ `
-            + '(lowercase alphanumeric, hyphens allowed in the middle)');
-    }
-    return null;
-}
-/**
- * Resolve the effective cluster name.
- * Explicit opt takes priority; falls back to the constant default.
- */
-function resolveClusterName(opts) {
-    return opts.clusterName ?? SETUP_K3D_CLUSTER_NAME;
-}
-// ── Substrate resolution ───────────────────────────────────────────────────
-/** Migration hint printed once when an existing docker/compose install is detected. */
-export const DOCKER_MIGRATION_HINT = 'olam: detected existing docker stack — continuing on docker. '
-    + 'To migrate to k3d, run: olam upgrade --substrate=kubernetes (available in a future release).';
-/**
- * Resolve the effective substrate: explicit opt has highest priority, then
- * auto-detect from ~/.olam/config.json (or override path), then default
- * 'kubernetes' for fresh installs.
- *
- * The --substrate=k3s alias normalises to 'kubernetes'.
- *
- * Existing-install guard: when the config has host.substrate='compose' (the
- * old docker default) and no explicit flag is provided, the wizard continues
- * on 'docker' and prints a one-line migration hint. No auto-migration.
- */
-function resolveSubstrate(opts, deps) {
-    if (opts.substrate === 'kubernetes')
-        return 'kubernetes';
-    if (opts.substrate === 'docker')
-        return 'docker';
-    // Auto-detect from config file
-    const configPath = deps.configPath ?? OLAM_CONFIG_PATH;
-    if (existsSync(configPath)) {
-        try {
-            const raw = readFileSync(configPath, 'utf8');
-            const parsed = JSON.parse(raw);
-            const host = parsed.host;
-            if (host?.substrate === 'kubernetes')
-                return 'kubernetes';
-            if (host?.substrate === 'compose') {
-                // Existing docker/compose install — protect it from the default flip.
-                process.stderr.write(DOCKER_MIGRATION_HINT + '\n');
-                return 'docker';
-            }
-        }
-        catch {
-            // malformed config — fall through to new default
-        }
-    }
-    // Fresh install (no config file, or unrecognised substrate) → new default
-    return 'kubernetes';
-}
-const SUBSTRATE_CHOICES = [
-    {
-        label: 'Docker Desktop (recommended)',
-        substrate: 'docker',
-        preferredRuntime: 'docker-desktop',
-    },
-    {
-        label: 'Colima',
-        substrate: 'docker',
-        preferredRuntime: 'colima',
-    },
-    {
-        label: 'Kubernetes (k3d on Docker Desktop)',
-        substrate: 'kubernetes',
-        preferredRuntime: 'docker-desktop',
-    },
-    {
-        label: 'Kubernetes (k3d on Colima)',
-        substrate: 'kubernetes',
-        preferredRuntime: 'colima',
-    },
-    {
-        label: 'Kubernetes (external context already pinned)',
-        substrate: 'kubernetes',
-        preferredRuntime: 'external-k8s',
-        requirePinnedContext: true,
-    },
-];
-/** Default (first) choice — Docker Desktop. */
-const DEFAULT_SUBSTRATE_CHOICE = SUBSTRATE_CHOICES[0];
-/**
- * Narrows the picker-internal `SetupSubstrate` to the config-schema `Substrate`.
- * `'docker'` in the picker maps to `'compose'` in the config (they name the same
- * non-kubernetes stack; the config schema predates the picker rename).
- */
-function toConfigSubstrate(s) {
-    return s === 'docker' ? 'compose' : 'kubernetes';
-}
-/**
- * Phase 0 — Substrate picker.
- *
- * Asks the operator which container runtime + substrate they want to use.
- * Writes `host.substrate` and `host.preferred_runtime` to ~/.olam/config.json.
- *
- * Skip conditions (all silent — return { ok: true, skipped: true }):
- *   - opts.substrate is already set    → "--substrate=<value> passed"
- *   - opts.skipSubstratePicker         → "--skip-substrate-picker"
- *   - config already has both fields   → "already configured (<runtime>)"
- *   - !process.stdin.isTTY && !opts.yes → uses docker-desktop default
- *   - opts.yes                         → uses docker-desktop default
- */
-/**
- * Return a comma-joined list of up to 5 available kubectl context names.
- * Used to populate the error message when the operator enters an unknown context.
- */
-function listAvailableContexts() {
-    const r = spawnSync('kubectl', ['config', 'get-contexts', '-o', 'name'], {
-        encoding: 'utf-8',
-        stdio: 'pipe',
-    });
-    if (r.status !== 0 || !r.stdout.trim())
-        return '(none found)';
-    const names = r.stdout.trim().split('\n').map((n) => n.trim()).filter(Boolean);
-    const preview = names.slice(0, 5);
-    return preview.join(', ') + (names.length > 5 ? `, … (+${names.length - 5} more)` : '');
-}
-export async function phase0SubstratePicker(opts, deps) {
-    // Skip: explicit --substrate= on the command line
-    if (opts.substrate !== undefined) {
-        return {
-            ok: true,
-            skipped: true,
-            message: `skipped — --substrate=${opts.substrate} passed`,
-        };
-    }
-    // Skip: explicit --skip-substrate-picker
-    if (opts.skipSubstratePicker) {
-        return { ok: true, skipped: true, message: 'skipped via --skip-substrate-picker' };
-    }
-    // Skip: already configured in config file
-    const configPath = deps.configPath ?? OLAM_CONFIG_PATH;
-    if (existsSync(configPath)) {
-        try {
-            const raw = readFileSync(configPath, 'utf8');
-            const parsed = JSON.parse(raw);
-            const host = parsed.host;
-            if (host?.substrate !== undefined
-                && host?.preferred_runtime !== undefined) {
-                return {
-                    ok: true,
-                    skipped: true,
-                    message: `skipped — substrate already configured (${host.preferred_runtime})`,
-                };
-            }
-        }
-        catch {
-            // malformed config — proceed to picker
-        }
-    }
-    // Non-TTY without --yes → use default silently
-    if (!process.stdin.isTTY && !opts.yes) {
-        writeConfig({ host: { substrate: toConfigSubstrate(DEFAULT_SUBSTRATE_CHOICE.substrate), preferred_runtime: DEFAULT_SUBSTRATE_CHOICE.preferredRuntime } }, { configPath: deps.configPath });
-        return {
-            ok: true,
-            skipped: true,
-            message: 'skipped (non-TTY); using docker-desktop default',
-        };
-    }
-    // --yes mode → use default silently (write config, print summary)
-    if (opts.yes) {
-        writeConfig({ host: { substrate: toConfigSubstrate(DEFAULT_SUBSTRATE_CHOICE.substrate), preferred_runtime: DEFAULT_SUBSTRATE_CHOICE.preferredRuntime } }, { configPath: deps.configPath });
-        process.stdout.write(`  ✓ Phase 0: substrate=${DEFAULT_SUBSTRATE_CHOICE.substrate} runtime=${DEFAULT_SUBSTRATE_CHOICE.preferredRuntime}\n`);
-        return {
-            ok: true,
-            message: `substrate=${DEFAULT_SUBSTRATE_CHOICE.substrate} runtime=${DEFAULT_SUBSTRATE_CHOICE.preferredRuntime}`,
-        };
-    }
-    // Interactive picker via @inquirer/prompts select (same pattern as Phase 5a).
-    // Lazy-load only when deps don't inject the prompt functions — keeps the
-    // import out of the test path and avoids the eager-import overhead.
-    const resolvedSelectFn = deps.selectPromptFn
-        ?? (await import('@inquirer/prompts')).select;
-    const choices = SUBSTRATE_CHOICES.map((c, i) => ({
-        value: String(i),
-        name: c.label,
-    }));
-    const pickedIndex = await resolvedSelectFn({
-        message: 'Choose your container runtime + substrate:',
-        choices,
-    });
-    const choice = SUBSTRATE_CHOICES[Number(pickedIndex)] ?? DEFAULT_SUBSTRATE_CHOICE;
-    // Special handling: external context requires kubectl_context_pinned to be set
-    if (choice.requirePinnedContext) {
-        // Check whether the config already has it
-        let hasPinnedContext = false;
-        if (existsSync(configPath)) {
-            try {
-                const raw = readFileSync(configPath, 'utf8');
-                const parsed = JSON.parse(raw);
-                const host = parsed.host;
-                hasPinnedContext = typeof host?.kubectl_context_pinned === 'string'
-                    && host.kubectl_context_pinned.length > 0;
-            }
-            catch {
-                // ignore
-            }
-        }
-        if (!hasPinnedContext) {
-            // Prompt for context name + validate
-            const resolvedInputFn = deps.inputPromptFn
-                ?? (await import('@inquirer/prompts')).input;
-            const contextName = await resolvedInputFn({
-                message: 'Enter your kubectl context name (e.g. lima-k3s, gke_proj_region_cluster):',
-                validate: (v) => {
-                    if (v.trim().length === 0)
-                        return 'Context name must not be empty';
-                    const name = v.trim();
-                    // Sanitize to prevent jsonpath injection via embedded quotes.
-                    const escaped = name.replace(/"/g, '\\"');
-                    // Use jsonpath — `get-contexts <name>` exits 0 even for missing contexts
-                    // (it just prints an empty table). jsonpath prints the name when found,
-                    // empty string when not found.
-                    const r = spawnSync('kubectl', ['config', 'view', '-o', `jsonpath={.contexts[?(@.name=="${escaped}")].name}`], { stdio: 'pipe', encoding: 'utf-8' });
-                    if (r.status !== 0) {
-                        return 'kubectl not available — verify kubectl is installed and re-run setup';
-                    }
-                    if (r.stdout.trim() !== name) {
-                        return (`Context "${name}" not found in kubeconfig. `
-                            + `Available: ${listAvailableContexts()}`);
-                    }
-                    return true;
-                },
-            });
-            writeConfig({
-                host: {
-                    substrate: toConfigSubstrate(choice.substrate),
-                    preferred_runtime: choice.preferredRuntime,
-                    kubectl_context_pinned: contextName.trim(),
-                },
-            }, { configPath: deps.configPath });
-            process.stdout.write(`  ✓ Phase 0: substrate=${choice.substrate} runtime=${choice.preferredRuntime} context=${contextName.trim()}\n`);
-            return {
-                ok: true,
-                message: `substrate=${choice.substrate} runtime=${choice.preferredRuntime} context=${contextName.trim()}`,
-            };
-        }
-    }
-    writeConfig({ host: { substrate: toConfigSubstrate(choice.substrate), preferred_runtime: choice.preferredRuntime } }, { configPath: deps.configPath });
-    process.stdout.write(`  ✓ Phase 0: substrate=${choice.substrate} runtime=${choice.preferredRuntime}\n`);
-    return {
-        ok: true,
-        message: `substrate=${choice.substrate} runtime=${choice.preferredRuntime}`,
-    };
-}
-/**
- * Phase 0.5 — Detect existing reachable kubeconfig contexts (ADR 021).
- *
- * Only runs when substrate=kubernetes. On docker substrate, returns no-op.
- *
- * Behaviour:
- *   1. --reuse-cluster=<name> provided → validate reachability of that context.
- *      If reachable, skip Phase 1.5 + 2.5 and pin Phase 2.6 to this context.
- *      If unreachable, fail fast with actionable error.
- *   2. --yes mode: if reachable idle contexts exist, print an info line and
- *      continue to k3d provision (backward compat — --yes defaults to NO reuse).
- *   3. Interactive: prompt for each offerable context; operator chooses.
- *
- * Returns a PhaseResult extended with an optional `reuseContext` field.
- * When `reuseContext` is set, later phases skip k3d install/provision.
- */
-async function phase0_5DetectExistingContext(substrate, opts, deps) {
-    if (substrate !== 'kubernetes') {
-        return { ok: true, skipped: true, message: 'no-op for docker substrate' };
-    }
-    // --reuse-cluster=<name> explicit opt-in: validate that context.
-    if (opts.reuseCluster) {
-        const name = opts.reuseCluster;
-        const clusterInfoFn = deps.kubectlClusterInfo ?? defaultClusterInfo;
-        const probe = clusterInfoFn(name);
-        if (!probe.reachable) {
-            return {
-                ok: false,
-                message: `--reuse-cluster=${name} but context is not reachable: ${probe.error ?? 'unknown error'}`,
-                remedy: `Verify the context exists (\`kubectl config get-contexts\`) and is reachable `
-                    + `(\`kubectl --context=${name} cluster-info\`), then re-run \`olam setup --reuse-cluster=${name}\`.`,
-                reuseContext: undefined,
-            };
-        }
-        return {
-            ok: true,
-            message: `will reuse context ${name}${probe.serverUrl ? ` (${probe.serverUrl})` : ''}`,
-            reuseContext: name,
-        };
-    }
-    // Discover reachable idle contexts not owned by olam.
-    const { offerable } = discoverOfferableContexts(deps.kubeContextDeps);
-    if (offerable.length === 0) {
-        return {
-            ok: true,
-            skipped: true,
-            message: 'no idle reachable contexts detected; will provision k3d cluster',
-        };
-    }
-    // --yes mode: backward compat — default to NO reuse; print informational hint.
-    if (opts.yes) {
-        process.stdout.write(`  Detected ${offerable.length} existing Kubernetes context(s): ${offerable.join(', ')}. `
-            + `To reuse one, pass --reuse-cluster=<name>. Provisioning k3d (--yes default).\n`);
-        return {
-            ok: true,
-            skipped: true,
-            message: `idle context(s) available but --yes defaults to k3d provision; use --reuse-cluster=<name> to opt in`,
-        };
-    }
-    // Interactive: prompt for each offerable context.
-    const promptFn = deps.prompt ?? defaultPrompt;
-    for (const ctx of offerable) {
-        const reuse = await promptFn(`Detected existing Kubernetes context \`${ctx}\`. Use this cluster instead of provisioning a new k3d cluster?`, false);
-        if (reuse) {
-            return {
-                ok: true,
-                message: `operator chose to reuse context ${ctx}`,
-                reuseContext: ctx,
-            };
-        }
-    }
-    return {
-        ok: true,
-        skipped: true,
-        message: 'operator declined reuse; will provision k3d cluster',
-    };
-}
-async function phase1SystemCheck(substrate, deps) {
-    const nodeVersion = deps.nodeVersion ?? process.version;
-    const nodeMajor = parseNodeMajor(nodeVersion);
-    const nodeOk = nodeMajor !== null && nodeMajor >= REQUIRED_NODE_MAJOR;
-    if (substrate === 'kubernetes') {
-        // kubectl is required on all platforms.
-        const kubectlProbe = await probeKubectl(deps.dockerExec);
-        if (!kubectlProbe.ok) {
-            return phaseFromProbe(kubectlProbe);
-        }
-        // docker is only required when the cluster is k3d-managed (k3d runs its node
-        // containers on the operator's local docker daemon). External kubernetes clusters
-        // (K3s-on-Lima, Kind on a remote VM, GKE, AKS, kubeadm, etc.) reach the
-        // apiserver directly via kubectl and don't need a local docker daemon.
-        //
-        // Heuristic: kubectl context names that START with `k3d-` are k3d-managed
-        // (e.g. `k3d-olam-dev`, `k3d-olam-host`). Anything else (`lima-k3s`,
-        // `kind-foo`, `gke_proj_region_cluster`, custom names) is treated as external
-        // — docker is optional.
-        const ctx = resolveKubectlContext(deps.configPath);
-        const isK3dManaged = ctx.context?.startsWith('k3d-') ?? false;
-        if (isK3dManaged) {
-            const dockerProbe = await probeDockerDaemon(deps.dockerExec);
-            if (!dockerProbe.ok) {
-                return {
-                    ok: false,
-                    message: 'docker daemon required for k3d-managed cluster: ' + dockerProbe.message,
-                    remedy: dockerProbe.remedy,
-                };
-            }
-        }
-        else if (ctx.context !== undefined) {
-            // Surface that we deliberately skipped the docker check so the operator
-            // sees the decision in the phase log.
-            process.stdout.write(`  ℹ skipped docker check — kubectl context "${ctx.context}" is not k3d-managed\n`);
-        }
-        // If ctx.context is undefined (no context pinned yet), the kubectlProbe above
-        // already confirms kubectl is present; the cluster-provision phases that follow
-        // will surface the missing context error — don't double-fail here.
-        if (!nodeOk) {
-            return {
-                ok: false,
-                message: `Node.js ${nodeVersion} is too old (need ≥${REQUIRED_NODE_MAJOR})`,
-                remedy: `Install Node.js ${REQUIRED_NODE_MAJOR}+ LTS via nvm/fnm/asdf and re-run \`olam setup\`.`,
-            };
-        }
-        // ADR 021 Phase 1 Colima lint: warn when Colima has kubernetes.enabled:true
-        // on macOS. This causes k3d to conflict on the same Lima VM ports.
-        // Warning only — operator may be using --reuse-cluster=colima intentionally.
-        const platform = String(deps.osPlatform ?? process.platform);
-        const home = deps.home ?? homedir();
-        const colimaLint = probeColimaKubernetesEnabled({ platform, home });
-        if (colimaLint.ok && 'warn' in colimaLint && colimaLint.warn === true) {
-            const lintWithWarn = colimaLint;
-            printWarning(`  ⚠ ${lintWithWarn.remedy}`);
-        }
-        const dockerNote = isK3dManaged ? '; docker ready' : '';
-        return { ok: true, message: `kubectl on PATH${dockerNote}; node ${nodeVersion}` };
-    }
-    // Docker substrate (default)
-    const dockerProbe = await probeDockerDaemon(deps.dockerExec);
-    if (!dockerProbe.ok) {
-        return phaseFromProbe(dockerProbe);
-    }
-    // Verify docker compose v2 plugin. Linux operators who installed docker.io
-    // (or via `brew install docker` on macOS) without the compose plugin will
-    // hit cryptic "unknown command" errors later; fail early with a clear remedy.
-    const composeProbe = await probeComposePlugin(deps.dockerExec);
-    if (!composeProbe.ok) {
-        return phaseFromProbe(composeProbe);
-    }
-    if (!nodeOk) {
-        return {
-            ok: false,
-            message: `Node.js ${nodeVersion} is too old (need ≥${REQUIRED_NODE_MAJOR})`,
-            remedy: `Install Node.js ${REQUIRED_NODE_MAJOR}+ LTS via nvm/fnm/asdf and re-run \`olam setup\`.`,
-        };
-    }
-    return {
-        ok: true,
-        message: `${dockerProbe.message}; ${composeProbe.message}; node ${nodeVersion}`,
-    };
-}
-/**
- * Phase 1.5 — Install missing substrate tools (idempotent).
- *
- * Docker: no-op.
- * Kubernetes (all platforms): installs k3d via brew when available, else the
- * upstream install script. k3d works on both macOS and Linux — no sudo needed
- * (k3d only requires docker, which Phase 1 already confirmed).
- *
- * @param reuseContext - when set (ADR 021 Phase 0.5), skip k3d install
- */
-async function phase1_5InstallSubstrate(substrate, opts, deps, reuseContext) {
-    if (substrate === 'docker') {
-        return { ok: true, skipped: true, message: 'no-op for docker substrate' };
-    }
-    // ADR 021: when reusing an existing context, k3d install is not needed.
-    if (reuseContext) {
-        return {
-            ok: true,
-            skipped: true,
-            message: `skipped k3d install (reusing context ${reuseContext})`,
-        };
-    }
-    // k3d only runs on k3d-managed clusters (context name starts with `k3d-`).
-    // External clusters (lima-k3s, kind-*, gke_*, custom names) already have their
-    // own k8s distribution installed — k3d is irrelevant and would be misleading to
-    // install. Mirror the same heuristic used by phase1SystemCheck for consistency.
-    const ctx = resolveKubectlContext(deps.configPath);
-    const isK3dManaged = ctx.context?.startsWith('k3d-') ?? false;
-    if (!isK3dManaged && ctx.context !== undefined) {
-        return {
-            ok: true,
-            skipped: true,
-            message: `skipped k3d install — kubectl context "${ctx.context}" is not k3d-managed`,
-        };
-    }
-    const spawnFn = deps.spawnSubprocess ?? defaultSpawn;
-    const promptFn = deps.prompt ?? defaultPrompt;
-    // k3d works on both darwin and linux; one path for both.
-    // Requires docker daemon (Phase 1 already checks this).
-    const k3dProbe = await probeK3d(deps.dockerExec);
-    if (k3dProbe.ok) {
-        return { ok: true, message: `k3d already present: ${k3dProbe.message}` };
-    }
-    // Determine installer: brew when available (common on macOS, sometimes on Linux),
-    // else upstream install script (no sudo needed).
-    const hasBrew = spawnSync('command', ['-v', 'brew'], { shell: true, stdio: 'pipe' }).status === 0;
-    const useBrewMsg = hasBrew ? 'Homebrew' : 'upstream install script';
-    if (!opts.yes) {
-        const confirmed = await promptFn(`k3d is not installed. Install via ${useBrewMsg}?`, true);
-        if (!confirmed) {
-            return {
-                ok: false,
-                message: 'k3d install declined; required for kubernetes substrate',
-                remedy: 'Install manually: `brew install k3d` or curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash, '
-                    + 'then re-run `olam setup --substrate=kubernetes`.',
-            };
-        }
-    }
-    if (hasBrew) {
-        process.stdout.write('Installing k3d via Homebrew...\n');
-        const r = await spawnFn('brew', ['install', 'k3d']);
-        if (r.status !== 0) {
-            return {
-                ok: false,
-                message: `brew install k3d failed (exit ${r.status ?? 'signal'})`,
-                remedy: 'Try manually: `brew install k3d` or curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash',
-            };
-        }
-    }
-    else {
-        process.stdout.write('Installing k3d via upstream install script...\n');
-        const r = await spawnFn('bash', [
-            '-c',
-            'curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash',
-        ]);
-        if (r.status !== 0) {
-            return {
-                ok: false,
-                message: `k3d upstream install failed (exit ${r.status ?? 'signal'})`,
-                remedy: 'Install manually: https://k3d.io/v5.x/installation/',
-            };
-        }
-    }
-    // Verify k3d is now on PATH
-    const k3dCheck = await probeK3d(deps.dockerExec);
-    if (!k3dCheck.ok) {
-        return {
-            ok: false,
-            message: 'k3d still not on PATH after install — shell PATH may need updating',
-            remedy: 'Close and re-open your terminal, then re-run `olam setup --substrate=kubernetes`.',
-        };
-    }
-    return { ok: true, message: `k3d installed: ${k3dCheck.message}` };
-}
-function parseNodeMajor(version) {
-    const m = version.match(/^v?(\d+)\./);
-    if (!m)
-        return null;
-    const n = Number.parseInt(m[1], 10);
-    return Number.isFinite(n) ? n : null;
-}
-function phaseFromProbe(probe) {
-    if (probe.ok)
-        return { ok: true, message: probe.message };
-    return { ok: false, message: probe.message, remedy: probe.remedy };
-}
-/**
- * Phase 2.5 — Provision k3d cluster (all platforms).
- * No-op for docker substrate.
- * Idempotent: if the cluster already exists, logs and skips.
- * k3d updates ~/.kube/config automatically — no kubeconfig juggling needed.
- *
- * @param clusterName - resolved cluster name (default: SETUP_K3D_CLUSTER_NAME)
- * @param reuseContext - when set (ADR 021 Phase 0.5), skip cluster provision
- */
-async function phase2_5ProvisionCluster(substrate, clusterName, opts, deps, reuseContext) {
-    if (substrate === 'docker') {
-        return { ok: true, skipped: true, message: 'no-op for docker substrate' };
-    }
-    // ADR 021: when reusing an existing context, k3d cluster provision is skipped.
-    if (reuseContext) {
-        return {
-            ok: true,
-            skipped: true,
-            message: `skipped k3d cluster provision (reusing context ${reuseContext})`,
-        };
-    }
-    const spawnFn = deps.spawnSubprocess ?? defaultSpawn;
-    // k3d cluster create <clusterName> (idempotent — same on macOS and Linux)
-    // Check if cluster already exists
-    const listResult = await captureSpawn('k3d', ['cluster', 'list', '--output', 'json'], deps.dockerExec);
-    if (listResult.ok) {
-        const exists = clusterExistsInList(listResult.stdout, clusterName);
-        if (exists) {
-            return {
-                ok: true,
-                message: `cluster ${clusterName} already exists; skipping create`,
-            };
-        }
-    }
-    process.stdout.write(`Creating k3d cluster ${clusterName}...\n`);
-    // Build --volume binds. Two hostPaths in host-cp's deployment resolve to
-    // paths inside the k3d node:
-    //   1. /host/.config/gh   ← gh CLI config (optional; only bound when the
-    //                           host dir exists so fresh machines don't break)
-    //   2. /host/olam         ← operator's olam source checkout (DEV ONLY;
-    //                           opt-in via --host-cp-dev-path). Published-CLI
-    //                           consumers MUST NOT bind this — they don't
-    //                           have an olam checkout and host-cp degrades
-    //                           gracefully without it (version-status reports
-    //                           'unknown'; /api/prs runs in empty cwd).
-    const volumes = [];
-    const ghConfigDir = `${homedir()}/.config/gh`;
-    if (existsSync(ghConfigDir)) {
-        volumes.push('--volume', `${ghConfigDir}:/host/.config/gh`);
-    }
-    else {
-        process.stdout.write(`  note: ${ghConfigDir} does not exist; skipping gh-config bind. ` +
-            `Run \`gh auth login\` to enable in-world GitHub features.\n`);
-    }
-    if (opts.hostCpDevPath) {
-        if (!existsSync(opts.hostCpDevPath)) {
-            return {
-                ok: false,
-                message: `--host-cp-dev-path ${opts.hostCpDevPath} does not exist`,
-                remedy: `Provide an absolute path to a local olam source checkout, or omit --host-cp-dev-path to use the published image.`,
-            };
-        }
-        volumes.push('--volume', `${opts.hostCpDevPath}:/host/olam`);
-        process.stdout.write(`  dev-mode: mounting ${opts.hostCpDevPath} → /host/olam (host-cp will read live source)\n`);
-    }
-    // --port flags map Traefik's loadbalancer ports (80/443 inside the cluster)
-    // to host ports 8080/8443. Without these, the SPA at https://olam.local is
-    // only reachable via `kubectl port-forward svc/traefik 8443:443` — a manual
-    // step that has to stay running. With them, `https://olam.local:8443` works
-    // out of the box. k3d does NOT support adding port flags to an existing
-    // cluster (k3d-io/k3d#1147), so this only takes effect for fresh clusters;
-    // operators on pre-existing clusters need to `k3d cluster delete <name>` and
-    // re-run setup. The runbook (docs/runbooks/k3d-https-setup.md) covers it.
-    const createArgs = [
-        'cluster', 'create', clusterName,
-        ...volumes,
-        '--port', '8443:443@loadbalancer',
-        '--port', '8080:80@loadbalancer',
-        '--wait', '--timeout', '90s',
-    ];
-    const createResult = await spawnFn('k3d', createArgs);
-    if (createResult.status !== 0) {
-        return {
-            ok: false,
-            message: `k3d cluster create ${clusterName} failed (exit ${createResult.status ?? 'signal'})`,
-            remedy: `Run manually: k3d ${createArgs.join(' ')}`,
-        };
-    }
-    // Verify kubectl can reach it (k3d updates ~/.kube/config automatically)
-    const ctxResult = captureSpawnSync('kubectl', ['config', 'current-context']);
-    const ctx = ctxResult.ok ? ctxResult.stdout.trim() : '(unknown)';
-    return { ok: true, message: `cluster ${clusterName} created; context: ${ctx}` };
-}
-/** Capture-only spawn via dockerExec (no subprocess) for list/query operations. */
-async function captureSpawn(cmd, args, dockerExec) {
-    const exec = dockerExec ?? ((c, a) => {
-        const r = spawnSync(c, [...a], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
-        return { status: r.status, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
-    });
-    const r = exec(cmd, args);
-    return { ok: r.status === 0, stdout: r.stdout, stderr: r.stderr };
-}
-/** Synchronous capture spawn used for non-critical reads (cluster context). */
-function captureSpawnSync(cmd, args) {
-    const r = spawnSync(cmd, [...args], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
-    return { ok: r.status === 0, stdout: r.stdout ?? '' };
-}
-/** Parse k3d cluster list JSON and return true if clusterName is present. */
-function clusterExistsInList(json, clusterName) {
-    try {
-        const parsed = JSON.parse(json);
-        return Array.isArray(parsed) && parsed.some((c) => c.name === clusterName);
-    }
-    catch {
-        return false;
-    }
-}
-async function phase2CliSanity(deps) {
-    // CRITICAL fix (Phase C CP3): readCliVersion() is the canonical
-    // source (same helper `index.ts:55` uses for `--version`). The
-    // OLAM_CLI_VERSION env var is only assigned INSIDE the host-cp
-    // container (host-cp.ts:423); it is NEVER set in the operator's
-    // host process — relying on it would make Phase 2 fail for every
-    // operator on Day 1.
-    const version = deps.olamCliVersion ?? safeReadCliVersion();
-    if (!version || version === 'unknown') {
-        return {
-            ok: false,
-            message: 'olam CLI version not detectable',
-            remedy: 'Re-install `olam` via `npm install -g @pleri/olam-cli@stable` and re-run.',
-        };
-    }
-    // Migrate any secrets still living at ~/.olam/<name> → ~/.olam/secrets/<name>.
-    // Idempotent: no-op when the new path already exists or the old path is absent.
-    for (const name of KNOWN_SECRET_NAMES) {
-        migrateSecretIfNeeded(name);
-    }
-    return { ok: true, message: `olam ${version}` };
-}
-function safeReadCliVersion() {
-    try {
-        return readCliVersion();
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Phase 2.6 — Pin kubectl context after k3d cluster creation (or context reuse).
- * No-op for docker substrate.
- *
- * `olam upgrade` (called by bootstrap step 6/6) requires
- * host.kubectl_context_pinned in ~/.olam/config.json. On the kubernetes
- * substrate, Phase 2.5 creates the cluster (context = k3d-<cluster>),
- * but the standard `olam init` that writes this field runs in Phase 5
- * (AFTER bootstrap). This phase bridges the gap: it pins the context
- * immediately after cluster creation so bootstrap/upgrade can proceed.
- *
- * When reuseContext is set (ADR 021), pins to the reused context name
- * instead of the k3d-derived context name.
- *
- * Idempotent: applyKubectlContextPin skips when the field is already set.
- *
- * @param clusterName - resolved cluster name (default: SETUP_K3D_CLUSTER_NAME)
- * @param reuseContext - when set (ADR 021 Phase 0.5), pin to this context name
- */
-async function phase2_6PinKubectlContext(substrate, clusterName, deps, reuseContext) {
-    if (substrate !== 'kubernetes') {
-        return { ok: true, skipped: true, message: 'no-op for docker substrate' };
-    }
-    // ADR 021: reused context uses the context name directly (not k3d-prefixed).
-    // k3d names the context `k3d-<cluster-name>`; reused contexts use their own name.
-    const expectedContext = reuseContext ?? `k3d-${clusterName}`;
-    // Ensure ~/.olam/config.json exists with a valid schema before patching
-    // kubectl_context_pinned. applyKubectlContextPin preserves existing keys but
-    // starts from `{}` when the file is absent — that produces an invalid schema
-    // (`readConfig` warns and falls back to defaults, losing kubectl_context_pinned).
-    // writeConfig reads current config (or creates a valid default) and writes a
-    // schema-conformant file. The subsequent applyKubectlContextPin will then
-    // patch kubectl_context_pinned on top of that valid foundation.
-    writeConfig({ host: { substrate: 'kubernetes' } }, { configPath: deps.configPath });
-    const result = applyKubectlContextPin([expectedContext], {
-        configPath: deps.configPath,
-    });
-    if ('pinned' in result) {
-        return { ok: true, message: `kubectl context pinned: ${result.pinned}` };
-    }
-    if ('skipped' in result) {
-        return { ok: true, message: `kubectl context already pinned (${result.skipped})` };
-    }
-    // 'refused' — multiple contexts (should not happen since we pass exactly one)
-    return {
-        ok: false,
-        message: `kubectl context pin refused: ${result.refused}`,
-        remedy: `Set host.kubectl_context_pinned = ${expectedContext} in ~/.olam/config.json and re-run.`,
-    };
-}
-async function phase3Bootstrap(substrate, deps, opts) {
-    // HIGH fix (Phase C CP3): pass --skip-auth-login. `olam bootstrap`
-    // step 6 (bootstrap.ts:499-520) runs PKCE interactively by default.
-    // Phase 6 owns the operator-facing auth UX (with non-fatal recovery);
-    // letting bootstrap run auth too means double-prompt + collapses
-    // Phase 6's recovery affordance when auth fails during bootstrap.
-    //
-    // Substrate-aware: the bootstrap command reads ~/.olam/config.json for
-    // substrate dispatch. For kubernetes substrate we additionally pass
-    // --skip-cluster-create (Phase 2.5 already created it) and
-    // --skip-observability is NOT passed — bootstrap still installs observability.
-    const spawnFn = deps.spawnSubprocess ?? defaultSpawn;
-    const bootstrapArgs = ['bootstrap', '--skip-auth-login'];
-    if (substrate === 'kubernetes') {
-        // Cluster was already created by Phase 2.5; bootstrap's preflight
-        // and cluster-create steps should skip.
-        bootstrapArgs.push('--skip-cluster-create');
-    }
-    // Forward --host-cp-dev-path so direct `olam bootstrap` callers and
-    // operators who pass it through `olam setup` get consistent behavior.
-    // Phase 2.5 already consumes this for k3d cluster create; bootstrap
-    // still threads it for symmetry with the standalone bootstrap path.
-    if (substrate === 'kubernetes' && opts.hostCpDevPath) {
-        bootstrapArgs.push('--host-cp-dev-path', opts.hostCpDevPath);
-    }
-    // Forward output + pre-pull preferences to the k3s bootstrap subprocess.
-    if (substrate === 'kubernetes' && opts.verbose) {
-        bootstrapArgs.push('--verbose');
-    }
-    if (substrate === 'kubernetes' && opts.skipPrepull) {
-        bootstrapArgs.push('--skip-prepull');
-    }
-    const r = await spawnFn('olam', bootstrapArgs);
-    if (r.status === 0) {
-        return { ok: true, message: `olam bootstrap succeeded (substrate: ${substrate})` };
-    }
-    return {
-        ok: false,
-        message: `olam bootstrap exited ${r.status}`,
-        remedy: 'Re-run `olam setup` after inspecting the bootstrap error above (bootstrap is idempotent).',
-    };
-}
-export async function phase3_5K3dHttpsBootstrap(substrate, opts, _deps) {
-    if (opts.skipHttpsBootstrap) {
-        return { ok: true, skipped: true, message: 'skipped via --skip-https-bootstrap' };
-    }
-    if (substrate !== 'kubernetes') {
-        return { ok: true, skipped: true, message: 'no-op for docker substrate' };
-    }
-    // Probe for mkcert on PATH; offer to install via brew if absent on macOS.
-    const spawnFn = spawnSync;
-    const whichResult = spawnFn('which', ['mkcert'], { encoding: 'utf-8' });
-    const mkcertOnPath = whichResult.status === 0 && whichResult.stdout.trim().length > 0;
-    if (!mkcertOnPath) {
-        // Check whether brew is available.
-        const brewResult = spawnFn('which', ['brew'], { encoding: 'utf-8' });
-        const brewAvailable = brewResult.status === 0 && brewResult.stdout.trim().length > 0;
-        if (!brewAvailable) {
-            return {
-                ok: true,
-                skipped: true,
-                message: 'mkcert not installed and brew not available; SPA accessible via port-forward (HTTP/1.1 only). '
-                    + 'See docs/runbooks/k3d-https-setup.md for manual install instructions.',
-            };
-        }
-        if (!opts.yes) {
-            return {
-                ok: true,
-                skipped: true,
-                message: 'mkcert not installed; run `brew install mkcert nss` then re-run `olam setup` '
-                    + '(or `olam services tls-install`) to enable HTTPS. '
-                    + 'SPA still accessible via port-forward (HTTP/1.1 only). '
-                    + 'Use --yes to auto-install or --skip-https-bootstrap to skip permanently.',
-            };
-        }
-        // --yes is set: install mkcert via brew. stdio:'inherit' so the operator
-        // sees brew's download/install progress (otherwise it appears to hang for
-        // 30-90s on a fresh mac). Matches the Phase 1.5 k3d-install pattern.
-        process.stdout.write('Installing mkcert + nss via Homebrew (Firefox cert trust)...\n');
-        const brewInstall = spawnFn('brew', ['install', 'mkcert', 'nss'], { stdio: 'inherit' });
-        if (brewInstall.status !== 0) {
-            return {
-                ok: true,
-                skipped: true,
-                message: `brew install mkcert nss exited ${brewInstall.status}; `
-                    + 'SPA accessible via port-forward (HTTP/1.1 only). '
-                    + 'Install mkcert manually and re-run `olam services tls-install`.',
-            };
-        }
-    }
-    // mkcert is (now) available — provision the TLS Secret.
-    const result = await ensureTlsInstalled();
-    // Check /etc/hosts for olam.local.
-    let hostsWarning = '';
-    try {
-        const hostsBody = readFileSync('/etc/hosts', 'utf-8');
-        if (!/^[^#\n]*\bolam\.local\b/m.test(hostsBody)) {
-            hostsWarning =
-                " Add to /etc/hosts:  echo '127.0.0.1 olam.local' | sudo tee -a /etc/hosts";
-        }
-    }
-    catch {
-        // /etc/hosts unreadable — skip the check silently.
-    }
-    if (result.action === 'installed' || result.action === 'renewed') {
-        const urlPart = result.httpsPort !== undefined
-            ? ` SPA at https://olam.local:${result.httpsPort}.`
-            : '';
-        return {
-            ok: true,
-            message: `TLS cert ${result.action} at ${result.action === 'installed' ? 'olam-host-cp-tls' : 'olam-host-cp-tls (renewed)'};${urlPart}${hostsWarning}`,
-        };
-    }
-    if (result.action === 'skipped') {
-        return { ok: true, message: `TLS already provisioned (skipped).${hostsWarning}` };
-    }
-    // action === 'failed' — non-fatal: port-forward fallback still works.
-    return {
-        ok: true,
-        skipped: true,
-        message: `TLS install failed (non-fatal): ${result.reason ?? 'unknown error'}. `
-            + 'SPA still accessible via port-forward (HTTP/1.1 only). '
-            + 'Re-run `olam services tls-install` after fixing the issue.',
-    };
-}
-async function phase4ShellInit(opts, deps) {
-    if (opts.skipShellInit) {
-        return { ok: true, skipped: true, message: 'skipped via --skip-shell-init' };
-    }
-    const home = deps.home ?? homedir();
-    const shellEnv = deps.shellEnv ?? process.env.SHELL;
-    const rcPath = resolveShellRc(home, shellEnv);
-    if (rcPath === null) {
-        return {
-            ok: true,
-            skipped: true,
-            message: `unsupported $SHELL (${shellEnv ?? 'unset'}); add \`eval "$(olam completion <shell>)"\` to your shell rc manually`,
-        };
-    }
-    const shellBasename = path.basename(shellEnv);
-    const evalLine = `eval "$(olam completion ${shellBasename})"`;
-    const result = appendIdempotent({
-        rcPath,
-        marker: 'olam completion',
-        contentLine: evalLine,
-        clock: deps.clock,
-    });
-    if (result.status === 'no-rc-file') {
-        return {
-            ok: true,
-            skipped: true,
-            message: `${rcPath} not present; skipped (add \`${evalLine}\` to your shell rc manually)`,
-        };
-    }
-    if (result.status === 'already-present') {
-        return { ok: true, message: `${rcPath}: already configured (no change)` };
-    }
-    return {
-        ok: true,
-        message: `${rcPath}: appended (backup: ${result.backupPath})`,
-    };
-}
-async function phase5InitProject(opts, deps) {
-    // Phase 5: Init GLOBAL config — ensure ~/.olam/config.json has host.substrate set.
-    // Per-repo config (.olam/config.yaml) is `olam repos` territory; setup must not
-    // walk up to .git and write per-repo config. See CLAUDE.md: "Olam init should be
-    // GLOBAL on install, not repo-specific."
-    const globalConfigPath = deps.configPath ?? OLAM_CONFIG_PATH;
-    const result = runGlobalInit({ configPath: globalConfigPath });
-    if (!result.ok) {
-        return {
-            ok: false,
-            message: result.message,
-            remedy: 'Inspect the error above and re-run `olam setup`, or run `olam init --global` manually.',
-        };
-    }
-    if (result.alreadySet) {
-        return { ok: true, message: 'already initialised globally (no change)' };
-    }
-    return { ok: true, message: result.message };
-}
-async function phase5aSkillSource(opts, deps) {
-    if (opts.skipSkillSource) {
-        return { ok: true, skipped: true, message: 'skipped via --skip-skill-source' };
-    }
-    // Run unconditionally. pickSkillSourcePhase auto-detects existing skill sources
-    // (skips silently when ≥1 are registered) and handles the interactive TUI,
-    // non-interactive --skill-source flag, and non-TTY fallback internally.
-    // Use --skip-skill-source to opt out entirely (headless CI, manual setup later).
-    return pickSkillSourcePhase(opts, deps);
-}
-async function phase5bProjectSweep(opts, deps) {
-    return runProjectSweepPhase(opts, deps);
-}
-async function phase6Auth(opts, deps) {
-    if (opts.skipAuth) {
-        return {
-            ok: true,
-            skipped: true,
-            message: 'skipped via --skip-auth (run `olam auth login` later)',
-        };
-    }
-    const promptFn = deps.prompt ?? defaultPrompt;
-    const shouldLaunch = opts.yes
-        ? true
-        : await promptFn('`olam auth login` is interactive (PKCE browser flow, 5 min timeout). Launch now?', false);
-    if (!shouldLaunch) {
-        return {
-            ok: true,
-            skipped: true,
-            message: 'declined; run `olam auth login` later when ready',
-        };
-    }
-    const spawnFn = deps.spawnSubprocess ?? defaultSpawn;
-    const r = await spawnFn('olam', ['auth', 'login']);
-    if (r.status === 0) {
-        return { ok: true, message: 'olam auth login succeeded' };
-    }
-    // Auth login failure is recoverable + operator-driven; don't fail the phase
-    return {
-        ok: true,
-        skipped: true,
-        message: `olam auth login exited ${r.status}; re-run \`olam auth login\` after resolving`,
-    };
-}
-async function phase7Verify(opts, deps) {
-    if (opts.skipDoctor) {
-        return { ok: true, skipped: true, message: 'skipped via --skip-doctor' };
-    }
-    const spawnFn = deps.spawnSubprocess ?? defaultSpawn;
-    const r = await spawnFn('olam', ['doctor']);
-    if (r.status === 0) {
-        return { ok: true, message: 'olam doctor: all probes green' };
-    }
-    return {
-        ok: false,
-        message: `olam doctor exited ${r.status}`,
-        remedy: 'Inspect doctor output above; the specific failing probe names its remedy.',
-    };
-}
-async function phase8KgHook(opts, deps) {
-    if (opts.skipKgHook) {
-        return { ok: true, skipped: true, message: 'skipped via --skip-kg-hook' };
-    }
-    return runKgHookPhase(opts, deps);
-}
-async function phase9MemoryBridge(opts, deps) {
-    if (opts.skipMemoryBridge) {
-        return { ok: true, skipped: true, message: 'skipped via --skip-memory-bridge' };
-    }
-    return runMemoryBridgePhase(opts, deps);
-}
-// ── Orchestrator ──────────────────────────────────────────────────────
-const PHASE_TITLES = [
-    'Phase 0: Substrate picker',
-    'Phase 0.5: Detect existing k8s context',
-    'Phase 1: System check',
-    'Phase 1.5: Substrate tools install',
-    'Phase 2: olam CLI sanity',
-    'Phase 2.5: Cluster provision',
-    'Phase 2.6: Pin kubectl context',
-    'Phase 3: Bootstrap',
-    'Phase 3.5: K3d HTTPS bootstrap',
-    'Phase 4: Shell init',
-    'Phase 5: Init project',
-    'Phase 5a: Skill source picker',
-    'Phase 5b: Project sweep',
-    'Phase 6: Auth prompt',
-    'Phase 7: Final verification',
-    'Phase 8: KG hook install',
-    'Phase 9: Agent memory bridge install',
-];
-export async function runSetup(opts, deps = {}) {
-    // ── --continue mode: skip Phases 1-7, run only Phase 8 + Phase 9 ──────────
-    if (opts.continueMode) {
-        printHeader('olam setup --continue — Phase 8 + Phase 9 only');
-        const results = [];
-        let failureAt = null;
-        // Migrate secrets idempotently (same as full run).
-        for (const name of KNOWN_SECRET_NAMES) {
-            migrateSecretIfNeeded(name);
-        }
-        // Phase 8 title is at PHASE_TITLES index 15 (0=0, 0.5=1, 1=2, … 7=14, 8=15).
-        const p8Title = PHASE_TITLES[15];
-        const p9Title = PHASE_TITLES[16];
-        process.stdout.write(`\n${p8Title}\n`);
-        const p8Result = await phase8KgHook(opts, deps);
-        results.push({ name: p8Title, result: p8Result });
-        if (p8Result.ok && p8Result.skipped) {
-            printWarning(`  ⊘ ${p8Result.message}`);
-        }
-        else if (p8Result.ok) {
-            printSuccess(`  ✓ ${p8Result.message}`);
-        }
-        else {
-            printError(`  ✗ ${p8Result.message}`);
-            if (p8Result.remedy)
-                printWarning(`    remedy: ${p8Result.remedy}`);
-            failureAt = 8;
-        }
-        if (failureAt === null) {
-            process.stdout.write(`\n${p9Title}\n`);
-            const p9Result = await phase9MemoryBridge(opts, deps);
-            results.push({ name: p9Title, result: p9Result });
-            if (p9Result.ok && p9Result.skipped) {
-                printWarning(`  ⊘ ${p9Result.message}`);
-            }
-            else if (p9Result.ok) {
-                printSuccess(`  ✓ ${p9Result.message}`);
-            }
-            else {
-                printError(`  ✗ ${p9Result.message}`);
-                if (p9Result.remedy)
-                    printWarning(`    remedy: ${p9Result.remedy}`);
-                failureAt = 9;
-            }
-        }
-        process.stdout.write('\n');
-        if (failureAt !== null) {
-            printError(`Setup FAILED at Phase ${failureAt}`);
-            return { phases: results, failureAt, exitCode: 1 };
-        }
-        printSuccess('Setup --continue complete.');
-        return { phases: results, failureAt: null, exitCode: 0 };
-    }
-    // ── Full setup (Phases 0 through 9) ───────────────────────────────────────
-    // Phase 0 (substrate picker) runs eagerly BEFORE resolveSubstrate so it can
-    // write host.substrate to config — resolveSubstrate then reads the written value.
-    // We still push the result into the phases array for the SetupReport.
-    const results = [];
-    let failureAt = null;
-    const phase0Title = PHASE_TITLES[0];
-    process.stdout.write(`\n${phase0Title}\n`);
-    const phase0Result = await phase0SubstratePicker(opts, deps);
-    results.push({ name: phase0Title, result: phase0Result });
-    if (phase0Result.ok && phase0Result.skipped) {
-        printWarning(`  ⊘ ${phase0Result.message}`);
-    }
-    else if (phase0Result.ok) {
-        // Summary line already printed inside phase0SubstratePicker for non-skip path.
-    }
-    else {
-        printError(`  ✗ ${phase0Result.message}`);
-        if (phase0Result.remedy)
-            printWarning(`    remedy: ${phase0Result.remedy}`);
-        process.stdout.write('\n');
-        printError('Setup FAILED at Phase 0');
-        return { phases: results, failureAt: 0, exitCode: 1 };
-    }
-    const substrate = resolveSubstrate(opts, deps);
-    const clusterName = resolveClusterName(opts);
-    // Cluster-name flag validation (fail fast before any I/O).
-    // Only validate when the kubernetes substrate is in play — the flag is a
-    // no-op for docker and should not block docker-only operators who pass it
-    // accidentally, but we still validate the format to surface typos.
-    if (opts.clusterName !== undefined) {
-        const nameError = validateClusterName(opts.clusterName);
-        if (nameError !== null) {
-            const errResult = {
-                ok: false,
-                message: `--cluster-name: ${nameError}`,
-                remedy: 'Use a DNS-compatible name: lowercase letters, digits, hyphens in the middle. '
-                    + 'Example: olam-test, my-stack-1',
-            };
-            printError(`  ✗ ${errResult.message}`);
-            if (errResult.remedy)
-                printWarning(`    remedy: ${errResult.remedy}`);
-            return { phases: [{ name: 'Phase 0: Flag validation', result: errResult }], failureAt: 1, exitCode: 1 };
-        }
-    }
-    const bannerSubstrate = substrate === 'kubernetes' ? 'Kubernetes (k3d)' : 'Docker Compose';
-    printHeader(`olam setup — Olam local stack on ${bannerSubstrate}`);
-    process.stdout.write(`substrate: ${substrate}\n`);
-    if (substrate === 'kubernetes') {
-        process.stdout.write(`cluster:   ${clusterName}\n`);
-    }
-    // Migrate secrets from ~/.olam/<name> → ~/.olam/secrets/<name> on every
-    // setup run. Idempotent — operators who already ran setup once see no-op.
-    for (const name of KNOWN_SECRET_NAMES) {
-        migrateSecretIfNeeded(name);
-    }
-    // Phase 0.5: detect existing k8s context. Run eagerly (not in phaseFns) so
-    // we can capture reuseContext and thread it through Phases 1.5, 2.5, 2.6.
-    // We still push the result into the phases array for the SetupReport.
-    const phase0_5Title = PHASE_TITLES[1];
-    process.stdout.write(`\n${phase0_5Title}\n`);
-    const phase0_5Result = await phase0_5DetectExistingContext(substrate, opts, deps);
-    results.push({ name: phase0_5Title, result: phase0_5Result });
-    if (phase0_5Result.ok && phase0_5Result.skipped) {
-        printWarning(`  ⊘ ${phase0_5Result.message}`);
-    }
-    else if (phase0_5Result.ok) {
-        printSuccess(`  ✓ ${phase0_5Result.message}`);
-    }
-    else {
-        printError(`  ✗ ${phase0_5Result.message}`);
-        if (phase0_5Result.remedy)
-            printWarning(`    remedy: ${phase0_5Result.remedy}`);
-        process.stdout.write('\n');
-        printError('Setup FAILED at Phase 1');
-        return { phases: results, failureAt: 1, exitCode: 1 };
-    }
-    const reuseContext = phase0_5Result.reuseContext;
-    const phaseFns = [
-        () => phase1SystemCheck(substrate, deps),
-        () => phase1_5InstallSubstrate(substrate, opts, deps, reuseContext),
-        () => phase2CliSanity(deps),
-        () => phase2_5ProvisionCluster(substrate, clusterName, opts, deps, reuseContext),
-        () => phase2_6PinKubectlContext(substrate, clusterName, deps, reuseContext),
-        () => phase3Bootstrap(substrate, deps, opts),
-        () => phase3_5K3dHttpsBootstrap(substrate, opts, deps),
-        () => phase4ShellInit(opts, deps),
-        () => phase5InitProject(opts, deps),
-        () => phase5aSkillSource(opts, deps),
-        () => phase5bProjectSweep(opts, deps),
-        () => phase6Auth(opts, deps),
-        () => phase7Verify(opts, deps),
-        () => phase8KgHook(opts, deps),
-        () => phase9MemoryBridge(opts, deps),
-    ];
-    // results + failureAt were initialised above (before Phase 0).
-    // phaseFns indices correspond to PHASE_TITLES[2..] (Phase 0 = [0], Phase 0.5 = [1]).
-    for (let i = 0; i < phaseFns.length; i += 1) {
-        const name = PHASE_TITLES[i + 2];
-        process.stdout.write(`\n${name}\n`);
-        const result = await phaseFns[i]();
-        results.push({ name, result });
-        if (result.ok && result.skipped) {
-            printWarning(`  ⊘ ${result.message}`);
-        }
-        else if (result.ok) {
-            printSuccess(`  ✓ ${result.message}`);
-        }
-        else {
-            printError(`  ✗ ${result.message}`);
-            if (result.remedy)
-                printWarning(`    remedy: ${result.remedy}`);
-            failureAt = i + 2; // phaseFns[0] lands at results[2] — Phase 0 + Phase 0.5 occupy [0] + [1]
-            break;
-        }
-    }
-    process.stdout.write('\n');
-    if (failureAt !== null) {
-        printError(`Setup FAILED at Phase ${failureAt}`);
-        return { phases: results, failureAt, exitCode: 1 };
-    }
-    printSuccess('Setup complete.');
-    process.stdout.write('\nNext steps — read these in order for the 3-contract pattern:\n');
-    const nextStepsDocs = substrate === 'kubernetes' ? NEXT_STEPS_DOCS_KUBERNETES : NEXT_STEPS_DOCS_DOCKER;
-    for (const line of nextStepsDocs) {
-        printInfo('docs', line);
-    }
-    // Print the skill-source suggestion only when the operator explicitly opted out
-    // via --skip-skill-source (they asked us not to run Phase 5a at all).
-    // When Phase 5a ran unconditionally (the default), it either registered a source,
-    // found existing ones, or the operator chose "skip for now" in the interactive picker
-    // — no post-setup hint needed because the phase itself communicated the outcome.
-    if (opts.skipSkillSource) {
-        process.stdout.write(formatPostSetupSuggestion());
-    }
-    else {
-        process.stdout.write('\n');
-    }
-    return { phases: results, failureAt: null, exitCode: 0 };
-}
-export function registerSetup(program) {
-    program
-        .command('setup')
-        .description('Fresh-host onboarding wizard (k3d cluster + services, idempotent)')
-        .option('--skip-substrate-picker', 'Skip Phase 0 substrate picker (uses existing config or default). '
-        + 'For non-interactive setups where host.substrate is managed manually.')
-        .option('--substrate <substrate>', 'Target substrate: kubernetes (default, alias: k3s) or docker. '
-        + 'Auto-detected from ~/.olam/config.json when not specified.')
-        .option('--cluster-name <name>', 'k3d cluster name to create/use (kubernetes substrate only; default: olam-dev). '
-        + 'Use a different name to avoid colliding with a pre-existing olam-dev cluster, '
-        + 'to run multiple olam stacks side-by-side, or for per-run unique names in CI smoke. '
-        + 'Must be DNS-compatible: lowercase alphanumeric, hyphens allowed in the middle.')
-        .option('--reuse-cluster <name>', 'Reuse an existing kubeconfig context instead of provisioning a new k3d cluster. '
-        + 'Pair with --substrate=kubernetes. Skips Phase 1.5 (k3d install) and Phase 2.5 '
-        + '(cluster provision); Phase 2.6 pins to this context. Operator owns the cluster '
-        + 'lifecycle (teardown not handled by olam setup). '
-        + 'Example: --reuse-cluster=colima (for Colima k8s users).')
-        .option('--skip-https-bootstrap', 'Skip Phase 3.5 (do not install mkcert or provision TLS Secret; run `olam services tls-install` later)')
-        .option('--skip-shell-init', 'Skip Phase 4 (do not append to ~/.zshrc / ~/.bashrc)')
-        .option('--skip-auth', 'Skip Phase 6 (do not prompt for `olam auth login`)')
-        .option('--skip-skill-source', 'Skip Phase 5a entirely (run `olam skills source add` later; default: Phase 5a runs and auto-skips when sources already registered)')
-        .option('--skill-source <id-or-url>', 'Non-interactive Phase 5a: curated name (e.g. atlas-toolbox) or git URL (skips interactive picker)')
-        .option('--skip-project-sweep', 'Skip Phase 5b (do not walk projects directory for repo discovery)')
-        .option('--projects <path>', 'Phase 5b: project root path to walk (default: ~/Projects)')
-        .option('--dry-run', 'Phase 5b: print matches without registering or building (no side effects)')
-        .option('--exclude <glob...>', 'Phase 5b: additional skip patterns for project sweep')
-        .option('--skip-kg', 'Phase 5b: skip KG eager-build sub-step (sources still registered)')
-        .option('--skip-doctor', 'Skip Phase 7 final `olam doctor` verification (for CI or minimal setups)')
-        .option('--host-cp-dev-path <path>', 'DEV-ONLY: mount a local olam source checkout into the k3d node at '
-        + '/host/olam so host-cp reads live source. Regular operators DO NOT '
-        + 'use this — the published image is self-contained. Absolute path required.')
-        .option('-y, --yes', 'Auto-affirm every prompt (non-interactive)')
-        .option('--continue', 'Skip Phases 1-7 (initial setup) and run Phase 8 (KG hook) + Phase 9 '
-        + '(memory bridge) only. Use after `olam setup` has run once successfully.')
-        .option('--skip-kg-hook', 'Skip Phase 8 (do not install KG hook; run `olam kg install-hook --scope user` later)')
-        .option('--skip-memory-bridge', 'Skip Phase 9 (do not register agentmemory MCP; run `olam memory install` later)')
-        .option('--verbose', '[k3s] stream all bootstrap phase output sequentially instead of collapsing to live spinner lines')
-        .option('--skip-prepull', '[k3s] skip pre-pulling olam-* images into the k3d node (pods cold-pull on demand)')
-        .action(async (rawOpts) => {
-        // Normalise the --substrate flag: 'k3s' is an alias for 'kubernetes'.
-        let substrate;
-        const rawSubstrate = rawOpts.substrate;
-        if (rawSubstrate === 'k3s' || rawSubstrate === 'kubernetes') {
-            substrate = 'kubernetes';
-        }
-        else if (rawSubstrate === 'docker') {
-            substrate = 'docker';
-        }
-        else if (rawSubstrate !== undefined) {
-            process.stderr.write(`[olam setup] Unknown --substrate value '${rawSubstrate}'. `
-                + `Valid values: docker, kubernetes (alias: k3s).\n`);
-            process.exitCode = 1;
-            return;
-        }
-        // commander maps `--continue` to rawOpts.continue (reserved word in JS,
-        // but valid as an object property). Map it to continueMode to avoid
-        // shadowing the `continue` keyword in the surrounding scope.
-        const { substrate: _drop, continue: continueFlag, ...restOpts } = rawOpts;
-        void _drop;
-        const report = await runSetup({ ...restOpts, substrate, continueMode: continueFlag });
-        if (report.exitCode !== 0)
-            process.exitCode = report.exitCode;
-    });
-}
-//# sourceMappingURL=setup.js.map