@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/dist/src/onboard/steps/ssh.js

@@ -0,0 +1,300 @@
+// ssh preflight — the FIRST thing the VM route does, and the reason
+// it is first is one specific failure mode.
+//
+// THE PASSPHRASE TRAP. An ssh key with a passphrase and no agent does not
+// fail: it PROMPTS. A prompt inside a wizard has nowhere to appear and nobody
+// to type into it, so what the operator sees is the deploy stopping dead,
+// halfway through an Ansible run, with no output and no explanation. That is
+// the single worst thing this route can do, and it is closed here in two ways:
+//
+//   1. STRUCTURALLY — every ssh this wizard runs, in this step and in the ssh
+//      transport (transport.ts), carries `-o BatchMode=yes`. BatchMode makes
+//      ssh refuse to ask: no passphrase prompt, no password prompt, no host-key
+//      question. A key that would have prompted fails instantly with a message
+//      instead of hanging forever with none. There is no code path in
+//      onboarding that builds an ssh command without it — `sshArgv` is the only
+//      builder, and it always prepends the options.
+//   2. IN THE OPEN — this step probes the alias, the agent and a real
+//      connection BEFORE anything is minted, written or deployed, and when the
+//      agent is empty it hands the operator the exact command to run IN THEIR
+//      OWN SHELL. It cannot run `ssh-add` for them: the passphrase prompt
+//      belongs to their terminal, not ours. Saying so plainly is the whole
+//      point.
+//
+// Everything else here follows from that: the alias must be one ssh actually
+// knows, the controller must have ansible-playbook (the deploy dies without
+// it), and remote sudo must be passwordless (the playbook runs `become: true`,
+// and a sudo password prompt is the same hang wearing a different hat).
+import { sshIdentityLines, sshAgentUnavailable, sshConfigRows, SSH_HOST_KEY_FAILURE, SSH_DNS_FAILURE, SSH_TIMEOUT_FAILURE, SSH_ROUTE_FAILURE, } from "../../ssh-observation.js";
+import { CHOICE_KEYS } from "../choices.js";
+import { shellQuote } from "../../tui/remote.js";
+import { SSH_ALIAS_RE, TOPOLOGY_STEP_ID, sshAliasOf, topologyOf } from "./topology.js";
+export const SSH_PREFLIGHT_STEP_ID = "ssh_preflight";
+/** Resolved login user, recorded for the inventory's `ansible_user`. */
+export const SSH_USER_CHOICE_KEY = CHOICE_KEYS.sshUser;
+/**
+ * The options EVERY onboarding ssh carries.
+ *
+ * `BatchMode=yes` is the load-bearing one (see the header): it turns every
+ * would-be prompt into an immediate, explained failure. `ConnectTimeout` keeps
+ * an unreachable box from eating the engine runner's whole budget.
+ */
+export const SSH_BATCH_OPTS = ["-o", "BatchMode=yes", "-o", "ConnectTimeout=10"];
+/** The ONE ssh command builder in onboarding. Remote argv is quoted
+ * into a single command string, because ssh hands its arguments to a remote
+ * shell rather than execing them. */
+export function sshArgv(host, remote) {
+    return [...SSH_BATCH_OPTS, host, remote.map(shellQuote).join(" ")];
+}
+/** How the same command reads when the operator types it themselves. */
+export function sshCommandLine(host, remote) {
+    return `ssh ${host} ${remote.map(shellQuote).join(" ")}`;
+}
+/**
+ * `ssh-add -l`, read totally. Exit 0 = identities listed, 1 = the agent is
+ * running but empty, 2 = there is no agent to talk to. Anything else is
+ * "unknown", which is never reported as a failure on its own — the connection
+ * probe is the authority, and this only shapes the advice it gives.
+ */
+export function parseSshAddList(code, stdout, stderr) {
+    const text = `${stdout}\n${stderr}`;
+    if (code === 0) {
+        const lines = sshIdentityLines(stdout);
+        return {
+            kind: "keys",
+            count: lines.length,
+            detail: lines.length === 1 ? "1 key" : `${lines.length} keys`,
+        };
+    }
+    if (/no identities/i.test(text))
+        return { kind: "empty", count: 0, detail: "the agent is running but holds no keys" };
+    if (sshAgentUnavailable(code, text)) {
+        return { kind: "no-agent", count: 0, detail: "no ssh agent is reachable from this shell" };
+    }
+    return {
+        kind: "unknown",
+        count: 0,
+        detail: (stderr || stdout).trim().slice(0, 200) || `ssh-add -l exited ${code}`,
+    };
+}
+/** Classify an ssh failure from its own words. Pure — the step turns this into
+ * advice, and the tests drive every branch without an ssh anywhere. */
+export function classifySshFailure(stderr) {
+    const t = stderr.toLowerCase();
+    if (SSH_DNS_FAILURE.test(t) || /nodename nor servname/.test(t))
+        return "no-such-host";
+    if (SSH_HOST_KEY_FAILURE.test(t))
+        return "host-key";
+    if (/permission denied|no supported authentication|too many authentication failures|publickey/.test(t))
+        return "auth";
+    if (SSH_TIMEOUT_FAILURE.test(t) || /timed out|timeout/.test(t))
+        return "timeout";
+    if (SSH_ROUTE_FAILURE.test(t))
+        return "refused";
+    return "unknown";
+}
+/** The commands that load a key into the agent, run in the operator's own
+ * shell — starting an agent first when there is none. One rendering for every
+ * check that hands them out. */
+export function agentLoadCommands(agent) {
+    return agent.kind === "no-agent"
+        ? '    eval "$(ssh-agent -s)"\n    ssh-add ~/.ssh/id_ed25519'
+        : "    ssh-add ~/.ssh/id_ed25519";
+}
+/**
+ * The remedy, in the operator's own shell, for a failed connection. `agent`
+ * shapes it because the same "Permission denied (publickey)" means two very
+ * different things depending on whether the agent is empty (your key is not
+ * loaded — the passphrase case) or full (the server does not have your key).
+ */
+export function connectionAdvice(failure, agent, alias) {
+    const batch = "Every ssh this wizard runs carries -o BatchMode=yes, so it fails in the open instead of hanging on a prompt you cannot see.";
+    switch (failure) {
+        case "no-such-host":
+            return (`ssh cannot resolve "${alias}" at all. Fix: it must be a name ssh knows — either a real hostname/IP, or a Host entry in ` +
+                `~/.ssh/config. Check with:\n    ssh -G ${alias} | head -3\nand try \`ssh ${alias}\` in your own shell until that works; ` +
+                "then run this step again.");
+        case "host-key":
+            return ('ssh refused on the host key. That is deliberate: BatchMode never answers the "are you sure you want to continue ' +
+                `connecting?" question for you. Fix, in your own shell:\n    ssh ${alias} true\naccept the fingerprint once (or fix a ` +
+                `changed key with \`ssh-keygen -R ${alias}\`), then run this step again. ${batch}`);
+        case "auth":
+            return agent.kind === "keys"
+                ? `the connection reached ${alias} and it rejected your key (${agent.detail} loaded). Fix: the PUBLIC half of one of ` +
+                    `those keys must be in ~/.ssh/authorized_keys on ${alias}. \`ssh-copy-id ${alias}\` does it if you can log in ` +
+                    `another way. ${batch}`
+                : `your ssh agent has no usable key (${agent.detail}), so ${alias} had nothing to authenticate with. THIS IS THE ` +
+                    "PASSPHRASE CASE, and it is the one that would otherwise hang a deploy halfway through:\n\n" +
+                    `${agentLoadCommands(agent)}\n` +
+                    "\nRun that IN YOUR OWN SHELL — the passphrase prompt belongs to your terminal and this wizard must never try to " +
+                    `type into it. (Use the path of your own key if it is not id_ed25519.) Then run this step again. ${batch}`;
+        case "timeout":
+            return `the connection to ${alias} timed out. Fix: is the machine up, and is port 22 reachable from here (firewall, VPN, bastion)? ${batch}`;
+        case "refused":
+            return `${alias} refused the connection. Fix: sshd must be running and reachable on the port your config uses. ${batch}`;
+        default:
+            return (`ssh failed and did not say anything this step recognises. Fix: run \`ssh ${alias} true\` in your own shell — its ` +
+                `message is the one to act on. ${batch}`);
+    }
+}
+async function run(runner, cmd, args) {
+    return runner.run(cmd, [...args]);
+}
+export function sshPreflightStep(opts = {}) {
+    const probeSudo = opts.probeSudo ?? true;
+    async function probe(ctx) {
+        const alias = sshAliasOf(ctx.choices);
+        if (alias === "" || !SSH_ALIAS_RE.test(alias)) {
+            return {
+                ok: false,
+                checks: [
+                    {
+                        name: "alias",
+                        ok: false,
+                        detail: `no ssh alias is recorded — run the ${TOPOLOGY_STEP_ID} step with choice: "vm" and ssh_host: "<alias>" first`,
+                    },
+                ],
+            };
+        }
+        const { runner } = ctx.adapters;
+        const checks = [];
+        // 1. is there an ssh at all?
+        const version = await run(runner, "ssh", ["-V"]);
+        if (version.code !== 0) {
+            checks.push({
+                name: "ssh-binary",
+                ok: false,
+                detail: `\`ssh -V\` exited ${version.code} (${(version.stderr || version.stdout).trim() || "no output"}) — Fix: install an OpenSSH client`,
+            });
+            return { ok: false, checks };
+        }
+        checks.push({
+            name: "ssh-binary",
+            ok: true,
+            detail: (version.stderr || version.stdout).trim().split("\n")[0] ?? "ssh present",
+        });
+        // 2. does ssh know this alias, and as what?
+        const resolved = await run(runner, "ssh", ["-G", alias]);
+        if (resolved.code !== 0) {
+            checks.push({
+                name: "alias",
+                ok: false,
+                detail: `\`ssh -G ${alias}\` exited ${resolved.code}: ${(resolved.stderr || resolved.stdout).trim().slice(0, 300) || "no output"} — ` +
+                    "Fix: that usually means ~/.ssh/config has an error, or the alias is not a name ssh can use at all",
+            });
+            return { ok: false, checks };
+        }
+        const facts = parseSshConfig(resolved.stdout);
+        if (facts.user !== "")
+            ctx.recordChoice(CHOICE_KEYS.sshUser, facts.user);
+        checks.push({
+            name: "alias",
+            ok: true,
+            detail: `${alias} → ${facts.user ? `${facts.user}@` : ""}${facts.hostname || alias}:${facts.port || "22"}` +
+                (facts.hostname === alias
+                    ? " (no ~/.ssh/config Host entry matched, so ssh treats the alias as the hostname itself)"
+                    : ""),
+        });
+        // 3+4. What the agent holds, and then the authority: a real,
+        // non-interactive connection. The CONNECTION decides — an empty agent is
+        // perfectly fine when the key has no passphrase, and the agent line exists
+        // to shape the advice, never to fail the step on its own.
+        const agentRaw = await run(runner, "ssh-add", ["-l"]);
+        const agent = parseSshAddList(agentRaw.code, agentRaw.stdout, agentRaw.stderr);
+        const connect = await run(runner, "ssh", sshArgv(alias, ["true"]));
+        const connected = connect.code === 0;
+        checks.push({
+            name: "ssh-agent",
+            ok: agent.kind === "keys" || connected,
+            detail: agent.kind === "keys"
+                ? `your ssh agent holds ${agent.detail} — a passphrase-protected key can be used without ever prompting`
+                : connected
+                    ? `${agent.detail}, and the connection below still succeeded — so your key has no passphrase and needs no agent`
+                    : `${agent.detail}. If your key has a passphrase this fails the connection below rather than prompting, which is ` +
+                        "deliberate. Load it in your own shell:\n" +
+                        agentLoadCommands(agent),
+        });
+        if (!connected) {
+            const failure = classifySshFailure(connect.stderr || connect.stdout);
+            checks.push({
+                name: "connection",
+                ok: false,
+                detail: `\`${sshCommandLine(alias, ["true"])}\` failed (exit ${connect.code}): ` +
+                    `${(connect.stderr || connect.stdout).trim().split("\n").slice(-2).join(" ").slice(0, 240) || "no output"}\n\n` +
+                    connectionAdvice(failure, agent, alias),
+            });
+            return { ok: false, checks };
+        }
+        checks.push({
+            name: "connection",
+            ok: true,
+            detail: `\`${sshCommandLine(alias, ["true"])}\` succeeded without prompting for anything — the deploy cannot hang on a passphrase`,
+        });
+        // 5. passwordless sudo: the playbook runs as root on the box, and a sudo
+        //    password prompt is the same hang in different clothes.
+        if (probeSudo) {
+            const sudo = await run(runner, "ssh", sshArgv(alias, ["sudo", "-n", "true"]));
+            checks.push(sudo.code === 0
+                ? {
+                    name: "remote-sudo",
+                    ok: true,
+                    detail: `sudo on ${alias} works without a password — the Ansible deploy can install packages and run Docker`,
+                }
+                : {
+                    name: "remote-sudo",
+                    ok: false,
+                    detail: `\`sudo -n true\` on ${alias} exited ${sudo.code} (${(sudo.stderr || sudo.stdout).trim().slice(0, 200) || "no output"}). ` +
+                        "The deploy runs as root on that machine (packages, Docker, the container), and a sudo PASSWORD PROMPT would hang " +
+                        "it exactly the way an ssh passphrase would. Fix: give your login passwordless sudo there — on most clouds that is " +
+                        "already true for the default user; otherwise add a sudoers line for it. (You can also deploy by hand with " +
+                        "`ansible-playbook --ask-become-pass`, but then the wizard cannot drive it for you.)",
+                });
+        }
+        // 6. the controller side: the deploy is an ansible-playbook run.
+        const ansible = await run(runner, "ansible-playbook", ["--version"]);
+        checks.push(ansible.code === 0
+            ? {
+                name: "ansible",
+                ok: true,
+                detail: (ansible.stdout || ansible.stderr).trim().split("\n")[0] ??
+                    "ansible-playbook present",
+            }
+            : {
+                name: "ansible",
+                ok: false,
+                detail: `\`ansible-playbook --version\` exited ${ansible.code} — the deploy IS an Ansible run from this machine, and ` +
+                    "scripts/deploy.sh refuses without it. Fix: install Ansible here (`pipx install ansible`, `pip install --user " +
+                    "ansible`, or your package manager). Nothing needs to be installed on the server by hand — the playbook does that.",
+            });
+        return {
+            ok: checks.every((c) => c.ok),
+            checks,
+            data: { alias, user: facts.user, hostname: facts.hostname },
+        };
+    }
+    return {
+        id: SSH_PREFLIGHT_STEP_ID,
+        title: "ssh: prove the alias, the agent and the passphrase trap — before anything is deployed",
+        explain: "The very first thing the server route does, and deliberately so. It checks that ssh knows your alias, that your agent " +
+            "holds a usable key, that a real connection succeeds without prompting for anything, that sudo on that machine needs no " +
+            "password, and that this machine has Ansible. The one worth explaining out loud: a passphrase-protected key with no agent " +
+            "does not fail, it PROMPTS — and a prompt inside a deploy is an invisible hang. Every ssh here uses BatchMode, so it fails " +
+            "in the open instead, and when the agent is empty this step hands them the exact `ssh-add` line to run in their OWN shell.",
+        order: 22,
+        enabled: (choices) => topologyOf(choices) === "vm",
+        run: probe,
+        verify: probe,
+    };
+}
+/** `ssh -G <alias>` prints one lowercase `key value` per line. */
+export function parseSshConfig(stdout) {
+    const facts = { hostname: "", user: "", port: "" };
+    for (const [key, value] of sshConfigRows(stdout)) {
+        if (key !== "hostname" && key !== "user" && key !== "port")
+            continue;
+        if (facts[key] === "")
+            facts[key] = value;
+    }
+    return facts;
+}
+//# sourceMappingURL=ssh.js.map

package/dist/src/onboard/steps/ssh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssh.js","sourceRoot":"","sources":["../../../../src/onboard/steps/ssh.ts"],"names":[],"mappings":"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"}

package/dist/src/onboard/steps/topology.js

@@ -0,0 +1,291 @@
+// Topology — the wizard's first real question, and the one that
+// decides what the rest of the wizard even is.
+//
+// WHY IT SITS AT ORDER 20, between preflight (10) and LLM auth (30):
+//
+//   * preflight (10) is not a question at all — it establishes that this
+//     machine can run *anything* (Node, Docker, a uid to build images with).
+//     It has to come first because a machine that cannot run Docker cannot run
+//     either topology, and asking someone to choose between two things they
+//     cannot have is not a question, it is a trap.
+//   * topology (20) comes next because every later step reads it: LLM auth's
+//     honest "how many browser logins are coming" answer differs by route,
+//     the ingress step's recommended default differs, config_fill only asks
+//     for an ssh alias on the VM route, and the whole bring-up tail is either
+//     `docker compose up` here or the Ansible deploy over there. Asking it
+//     later would mean asking questions whose answers we would then throw
+//     away.
+//   * the ssh preflight (22) follows IMMEDIATELY on the VM route — see
+//     ssh.ts. The alias and the agent are proven before a single credential is
+//     minted or a single config key written, because a dead alias found at
+//     deploy time has already cost the operator the entire interview.
+//
+// BOTH ANSWERS ARE FIRST-CLASS. "A VM or server over ssh" is advertised as
+// the always-on recommendation (it is not the "advanced" path), and
+// "this computer" is a complete, supported installation — the trade is stated
+// in the operator's own terms and then they pick.
+//
+// SWITCHING IS A GUIDED, EXPLICIT ACT. A re-run that names a different
+// topology does NOT silently reconfigure: it refuses once, says exactly what
+// changes and what is left running where, and demands the confirmation phrase.
+// The engine then does the rest by itself — the steps that belong to the old
+// route go `disabled`, the new route's steps are pending, and the shared tail
+// (verification, proof, the flip) re-verifies against the new transport and is
+// demoted if it no longer holds. Nothing is torn down behind the operator's
+// back: a stack on the machine they are switching away from keeps running
+// until they stop it, and this step says so.
+import { CHOICE_KEYS, TOPOLOGY_CHOICES, memberOf } from "../choices.js";
+export const TOPOLOGY_STEP_ID = "topology";
+/** The one place the topology is recorded — an alias of the shared key, so
+ * this step and every reader name the same declaration (src/onboard/choices.ts). */
+export const TOPOLOGY_CHOICE_KEY = CHOICE_KEYS.topology;
+/** The ssh alias of the review host, recorded on the VM route. config_fill's
+ * `[tui] ssh_host` question reads this key (its `from` list), so the operator
+ * is never asked for the same alias twice. */
+export const SSH_ALIAS_CHOICE_KEY = CHOICE_KEYS.sshAlias;
+/** The recorded topology. Absent ⇒ "local", the compose path, so a checklist
+ * that never recorded a topology keeps its meaning. */
+export function topologyOf(choices) {
+    return choices[TOPOLOGY_CHOICE_KEY] === "vm" ? "vm" : "local";
+}
+/** Was a topology ever actually recorded? (`topologyOf` defaults; this does
+ * not — switching has to be able to tell "unset" from "local".) */
+export function topologyRecorded(choices) {
+    const raw = choices[TOPOLOGY_CHOICE_KEY];
+    return typeof raw === "string" ? memberOf(TOPOLOGY_CHOICES, raw) : null;
+}
+export function sshAliasOf(choices) {
+    const raw = choices[SSH_ALIAS_CHOICE_KEY];
+    return typeof raw === "string" ? raw.trim() : "";
+}
+/** An ssh alias as it appears in ~/.ssh/config — a Host name, not a URL.
+ * Never a leading dash: ssh would read it as an option, not the destination. */
+export const SSH_ALIAS_RE = /^[A-Za-z0-9._][A-Za-z0-9._-]*$/;
+const TOPOLOGY_OPTION_METADATA = {
+    vm: {
+        headline: "A VM or server over ssh — RECOMMENDED, because a reviewer that is asleep reviews nothing",
+        tradeoffs: [
+            "it is on 24/7: pull requests opened while you sleep, while your laptop is shut, or while you are on a plane still get reviewed",
+            "you bring the box (any ssh-reachable Linux machine — a cheap cloud VM is plenty); the wizard does not create one for you",
+            "setup rides the same Ansible deploy the maintainers use, with every one of its preflights: clean tree, version-pin coherence, disk space, and a refusal while the bot is not drained and idle (no review rounds running)",
+            "your operator TUI reaches it over ssh, so you need an ssh alias and a key your agent can use — checked in the very next step, before anything is built",
+            "the recommended webhook ingress here is a named Cloudflare tunnel on your own domain: a permanent hostname, no rotation",
+        ],
+    },
+    local: {
+        headline: "This computer — everything in Docker on the machine you are sitting at",
+        tradeoffs: [
+            "nothing else to own: `docker compose up` and the whole system is here — daemon, memory engine, tunnel",
+            "it reviews only while this machine is awake and the containers are running; close the lid and the reviewer stops",
+            "zero third-party signup on the default path: the quick tunnel needs no account, and the daemon re-points its own webhook URL when that hostname rotates",
+            "the honest way to try QuickReview, and a perfectly good permanent setup for one person on a desktop that stays on",
+            "you can switch to a server later by re-running this step — the answers you gave (repo, App, keys) are kept",
+        ],
+    },
+};
+export const TOPOLOGY_OPTIONS = TOPOLOGY_CHOICES.map((id) => ({
+    id,
+    ...TOPOLOGY_OPTION_METADATA[id],
+}));
+/** The offer text — what the guide reads out when nothing is recorded yet. */
+export function renderTopologyOptions() {
+    return TOPOLOGY_OPTIONS.map((o) => [`${o.id}: ${o.headline}`, ...o.tradeoffs.map((t) => `    - ${t}`)].join("\n")).join("\n\n");
+}
+/** Not "yes": changing where the system lives is worth a sentence. */
+export const TOPOLOGY_SWITCH_CONFIRMATION = "SWITCH TOPOLOGY";
+export function isSwitchConfirmation(value) {
+    return typeof value === "string" && value.trim().toUpperCase() === TOPOLOGY_SWITCH_CONFIRMATION;
+}
+/** What changes when the operator moves between the two routes — read out
+ * BEFORE the switch, never after it. */
+export function switchConsequences(from, to) {
+    const lines = [
+        `You recorded "${from}" earlier and are now asking for "${to}". That is a real change of where your reviewer lives, so it is`,
+        "an explicit act rather than a quiet re-configuration. What happens:",
+        "",
+        to === "vm"
+            ? "  • the compose steps (bring the stack up) stop applying; the Ansible deploy over ssh takes their place"
+            : "  • the ssh steps (ssh preflight, inventory, deploy) stop applying; `docker compose up` on this machine takes their place",
+        "  • verification, the proof round and the go-live decision stay — they simply run against the new host, and any of them",
+        "    that no longer holds there is marked unfinished again the next time the checklist re-verifies",
+        "  • everything you have already answered is kept: the repo, the GitHub App, the labels, the memory keys, your config",
+        to === "vm"
+            ? "  • the ssh alias and a usable key are checked in the very next step, before anything is deployed"
+            : "  • the TUI moves back to talking to local Docker; `[tui] ssh_host` stops being used",
+        "",
+        from === "local"
+            ? "  • NOTHING IS TORN DOWN. Containers already running on this machine keep running until you stop them yourself"
+            : "  • NOTHING IS TORN DOWN. Anything already deployed on the server keeps running until you stop it yourself",
+        "    (`docker compose down` here, or stopping the container on the server).",
+        "",
+        `If that is what you want, call this step again with choice: "${to}" and confirm: "${TOPOLOGY_SWITCH_CONFIRMATION}".`,
+    ];
+    return lines.join("\n");
+}
+function choiceOf(input) {
+    const raw = String(input.choice ?? "")
+        .trim()
+        .toLowerCase();
+    if (raw === "vm" || raw === "server" || raw === "ssh")
+        return "vm";
+    if (raw === "local" || raw === "laptop" || raw === "this_computer")
+        return "local";
+    return null;
+}
+function aliasOf(input, choices) {
+    const raw = input.ssh_host ?? input.alias;
+    const typed = typeof raw === "string" ? raw.trim() : "";
+    return typed !== "" ? typed : sshAliasOf(choices);
+}
+function offerCheck() {
+    return {
+        name: "choice",
+        ok: false,
+        detail: "Read both of these out, in this order, and let them pick. Neither answer is the advanced one.\n\n" +
+            `${renderTopologyOptions()}\n\n` +
+            'Then call this step again with choice: "vm" (and ssh_host: "<the alias from your ~/.ssh/config>") or choice: "local".',
+    };
+}
+export function topologyStep() {
+    return {
+        id: TOPOLOGY_STEP_ID,
+        title: "Where should your reviewer live?",
+        explain: "The first real question, and it steers everything after it. Two answers, both fully supported: a VM or server you " +
+            "reach over ssh — the always-on recommendation, because a reviewer that is asleep reviews nothing — or this computer, " +
+            "in Docker, which needs no server at all and is the honest way to try the system. Call this tool with no arguments to " +
+            "get both options with their real trade-offs, read them out, then call it again with their answer. On the server route " +
+            "ask for the ssh alias at the same time: it is the only extra thing that route needs from them.",
+        order: 20,
+        parameters: {
+            type: "object",
+            properties: {
+                choice: {
+                    type: "string",
+                    enum: TOPOLOGY_CHOICES,
+                    description: 'Where the reviewer will run: "vm" (a VM/server over ssh) or "local" (this computer). Omit to read out both options.',
+                },
+                ssh_host: {
+                    type: "string",
+                    description: 'VM route only: the ssh alias of that machine, exactly as you would type it after `ssh`. Ignored for "local".',
+                },
+                confirm: {
+                    type: "string",
+                    description: `Only needed when CHANGING an already-recorded topology: the words ${TOPOLOGY_SWITCH_CONFIRMATION}.`,
+                },
+            },
+        },
+        async run(ctx) {
+            const choice = choiceOf(ctx.input);
+            const recorded = topologyRecorded(ctx.choices);
+            if (choice === null) {
+                const checks = [offerCheck()];
+                if (recorded !== null) {
+                    checks.push({
+                        name: "recorded",
+                        ok: true,
+                        detail: `"${recorded}" is recorded from an earlier run — calling this step with the same answer changes nothing.`,
+                    });
+                }
+                return { ok: false, checks };
+            }
+            // Switching: explicit, guided, and never a side effect of a re-run.
+            if (recorded !== null && recorded !== choice && !isSwitchConfirmation(ctx.input.confirm)) {
+                return {
+                    ok: false,
+                    checks: [{ name: "switch", ok: false, detail: switchConsequences(recorded, choice) }],
+                };
+            }
+            const switching = recorded !== null && recorded !== choice;
+            const checks = [];
+            if (choice === "vm") {
+                const alias = aliasOf(ctx.input, ctx.choices);
+                if (alias === "") {
+                    return {
+                        ok: false,
+                        checks: [
+                            {
+                                name: "ssh-alias",
+                                ok: false,
+                                detail: "the server route needs the ssh alias of that machine — the name you would type after `ssh`, as it appears in " +
+                                    '~/.ssh/config. Call this step again with choice: "vm" and ssh_host: "<alias>". (If you normally type a full ' +
+                                    "user@host, add a Host entry for it in ~/.ssh/config first: the deploy, the TUI and the memory forward all use " +
+                                    "that one name.)",
+                            },
+                        ],
+                    };
+                }
+                if (!SSH_ALIAS_RE.test(alias)) {
+                    return {
+                        ok: false,
+                        checks: [
+                            {
+                                name: "ssh-alias",
+                                ok: false,
+                                detail: `"${alias}" is not an ssh alias — an alias is letters, digits, dots, dashes and underscores (a Host name from ` +
+                                    "~/.ssh/config), not a URL, not user@host and not a command. Nothing was recorded.",
+                            },
+                        ],
+                    };
+                }
+                ctx.recordChoice(CHOICE_KEYS.sshAlias, alias);
+                checks.push({
+                    name: "ssh-alias",
+                    ok: true,
+                    detail: `${alias} recorded — the deploy, the operator TUI and the memory forward all use this one name, and the very next ` +
+                        "step proves it works (alias, agent, and the passphrase trap) before anything is built or deployed",
+                });
+            }
+            ctx.recordChoice(CHOICE_KEYS.topology, choice);
+            const option = TOPOLOGY_OPTIONS.find((o) => o.id === choice);
+            checks.unshift({ name: "topology", ok: true, detail: `${option.id} — ${option.headline}` });
+            if (switching) {
+                checks.push({
+                    name: "switch",
+                    ok: true,
+                    detail: `switched from "${recorded}" to "${choice}" on your explicit confirmation. Nothing was torn down: whatever is ` +
+                        "already running where you came from keeps running until you stop it. Run the checklist status next — the steps " +
+                        "that belong to the other route now show as skipped, and anything that no longer holds here is unfinished again.",
+                });
+            }
+            return {
+                ok: true,
+                checks,
+                data: { topology: choice, recorded_at: ctx.adapters.clock().toISOString() },
+            };
+        },
+        async verify(ctx) {
+            const recorded = topologyRecorded(ctx.choices);
+            if (recorded === null) {
+                return {
+                    ok: false,
+                    checks: [
+                        {
+                            name: "topology",
+                            ok: false,
+                            detail: "no topology recorded yet — run this step: it is the question the rest of the wizard is shaped by",
+                        },
+                    ],
+                };
+            }
+            const checks = [
+                {
+                    name: "topology",
+                    ok: true,
+                    detail: `${recorded} — ${TOPOLOGY_OPTIONS.find((o) => o.id === recorded).headline}`,
+                },
+            ];
+            if (recorded === "vm") {
+                const alias = sshAliasOf(ctx.choices);
+                checks.push(alias !== ""
+                    ? { name: "ssh-alias", ok: true, detail: `${alias} recorded as the review host` }
+                    : {
+                        name: "ssh-alias",
+                        ok: false,
+                        detail: 'the VM route is recorded but no ssh alias is — run this step again with choice: "vm" and ssh_host: "<alias>"',
+                    });
+            }
+            return { ok: checks.every((c) => c.ok), checks };
+        },
+    };
+}
+//# sourceMappingURL=topology.js.map

package/dist/src/onboard/steps/topology.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topology.js","sourceRoot":"","sources":["../../../../src/onboard/steps/topology.ts"],"names":[],"mappings":"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"}