directionallylocal 0.2.0 → 0.4.0

package/dist/laptop/setup.js

@@ -0,0 +1,301 @@
+import { execFile } from "node:child_process";
+import { access as fileAccess, readdir, readFile } from "node:fs/promises";
+import { homedir, hostname } from "node:os";
+import { join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { TtyPrompter } from "../prompt.js";
+import { palette, PlainUi, TerminalUi } from "../ui.js";
+import { loadRemotes, normalizeServerUrl, REMOTE_NAME_RE, remotesPath, saveRemote } from "./config.js";
+import { confirm, gatherKeys } from "./credentials.js";
+import { bootstrap, INSTALL_URL, installOnServer, pairLaptop, serverNeeds } from "./remote-install.js";
+import { checkServer, describeHost, discoverKeys, hostOf, parseSshConfig, parseTarget, realSshExec, SshAuthError } from "./ssh.js";
+import { openRemote, withConnections } from "./tunnel.js";
+const RUN_EXAMPLE = 'dl run "fix the flaky checkout test"';
+export async function setupWizard(deps) {
+    const c = palette(deps.color);
+    deps.write(`\n  ${c.bold("Directionally Local")}\n  Background coding agents. Where should they run?\n\n`);
+    deps.write(`  ${c.cyan("1")}  ${"On this computer".padEnd(22)} ${c.dim("start now · nothing to rent · pauses when this computer sleeps")}\n`);
+    deps.write(`  ${c.cyan("2")}  ${"On my own server".padEnd(22)} ${c.dim("keeps going when your laptop is closed · needs SSH access")}\n\n`);
+    const ui = deps.newUi();
+    let where = await pick(ui, deps.prompter, "Where", "1 or 2 · Enter for 1", { "1": "local", "2": "server" });
+    ui.answered("Where", where === "local" ? "On this computer" : "On my own server");
+    if (where === "local" && !deps.localSetup) {
+        ui.line("info", "On this computer", "coming soon");
+        if (!(await confirm(ui, deps.prompter, "Set up on your own server instead?"))) {
+            deps.write(`\n  ${c.dim("Nothing changed. Run")} dl setup ${c.dim("when you're ready.")}\n\n`);
+            return undefined;
+        }
+        ui.answered("Where", "On my own server");
+        where = "server";
+    }
+    if (where === "local") {
+        const keysUi = deps.newUi();
+        const answers = await gatherKeys(["github", "openrouter"], { ui: keysUi, prompter: deps.prompter, sources: deps.sources });
+        keysUi.finish();
+        const remote = await deps.localSetup({ ui: deps.newUi(), prompter: deps.prompter, answers: { openrouterKey: answers.openrouterKey, githubToken: answers.githubToken } });
+        await saveRemote(remote, deps.remotesFile ?? remotesPath());
+        finishScreen(deps.newUi(), undefined);
+        return remote;
+    }
+    return setUpServer(deps);
+}
+async function setUpServer(deps) {
+    const home = deps.sources.home;
+    const sshDir = join(home, ".ssh");
+    const hosts = parseSshConfig(await deps.sources.readFile(join(sshDir, "config")) ?? "", home);
+    // 1. Which server, and can we get in?
+    const chosen = await chooseServer(deps, hosts);
+    const { access, facts } = await reachServer(deps, sshDir, deps.identityFile ? { ...chosen.access, identityFile: deps.identityFile } : chosen.access, chosen.display);
+    // 2. Install dl there, then ask only for the keys it still lacks.
+    await bootstrap(access, facts, deps.ssh, deps.newUi(), deps.installUrl);
+    const needs = await serverNeeds(access, facts, deps.ssh);
+    if (needs.includes("tailscale"))
+        throw new Error("The server asked for Tailscale, but this setup reaches it over SSH; update dl on the server and run dl setup again.");
+    const keysUi = deps.newUi();
+    const answers = await gatherKeys(needs, { ui: keysUi, prompter: deps.prompter, sources: deps.sources });
+    if (needs.length === 0)
+        keysUi.line("done", "Keys", "already on the server");
+    keysUi.finish();
+    // 3. The install itself, its checklist replayed here.
+    const { capacity } = await installOnServer(access, facts, deps.ssh, answers, deps.newUi);
+    // 4. A credential for this laptop, checked through the tunnel every command will use. Each
+    // `dl pair` makes a new credential on the server, so a re-run keeps the saved one if it works.
+    const remotesFile = deps.remotesFile ?? remotesPath();
+    const saved = (await loadRemotes(remotesFile)).find((entry) => sameServer(entry, access));
+    let remote;
+    if (saved && await stillWorks({ ...saved, ssh: access }, deps.open))
+        remote = { ...saved, ssh: access };
+    if (!remote) {
+        const pairing = await pairLaptop(access, facts, deps.ssh, `${laptopName(deps.hostname)} (dl)`);
+        remote = {
+            name: saved?.name ?? await remoteName(access, remotesFile, chosen.alias ?? facts.hostname),
+            url: normalizeServerUrl(pairing.url),
+            token: pairing.token,
+            credentialId: pairing.credentialId,
+            expiresAt: pairing.expiresAt,
+            addedAt: (deps.now?.() ?? new Date()).toISOString(),
+            ssh: access,
+        };
+    }
+    const connectedUi = deps.newUi();
+    const paired = remote;
+    await withConnections(deps.open, async (connections) => {
+        try {
+            await (await connections.client(paired)).health();
+        }
+        catch (error) {
+            connectedUi.line("failed", "This laptop", "couldn't reach the server's API through SSH");
+            throw new Error(`The server is set up, but this laptop couldn't reach it through an SSH tunnel: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    });
+    await saveRemote(remote, remotesFile);
+    connectedUi.line("done", "This laptop", `connected as ${remote.name}`);
+    connectedUi.finish();
+    finishScreen(deps.newUi(), capacity);
+    return remote;
+}
+async function chooseServer(deps, hosts) {
+    const c = palette(deps.color);
+    const ui = deps.newUi();
+    if (hosts.length > 0) {
+        deps.write(`\n  ${c.dim("Your servers in ~/.ssh/config:")}\n`);
+        hosts.forEach((host, index) => deps.write(`  ${c.cyan(String(index + 1))}  ${host.alias.padEnd(22)} ${c.dim(describeHost(host))}\n`));
+        deps.write(`  ${c.cyan(String(hosts.length + 1))}  Another server\n\n`);
+    }
+    else {
+        deps.write("\n");
+    }
+    const hint = hosts.length > 0 ? `1-${hosts.length + 1}, or user@host[:port]` : "user@host[:port], e.g. root@203.0.113.10";
+    for (let attempt = 1;; attempt++) {
+        let answer = (await deps.prompter.text(ui.prompt("Server", hint))).trim();
+        const index = /^\d+$/.test(answer) ? Number(answer) - 1 : -1;
+        const host = hosts[index];
+        if (host) {
+            ui.answered("SSH", host.alias);
+            return {
+                alias: host.alias,
+                access: { target: host.alias },
+                display: `${host.user ? `${host.user}@` : ""}${host.hostName ?? host.alias}${host.port && host.port !== 22 ? `:${host.port}` : ""}`,
+            };
+        }
+        if (index === hosts.length && hosts.length > 0) {
+            ui.answered("SSH", "another server");
+            answer = (await deps.prompter.text(ui.prompt("Server address", "user@host[:port], e.g. root@203.0.113.10"))).trim();
+        }
+        try {
+            const access = parseTarget(answer);
+            ui.answered("SSH", access.target);
+            return { access, display: `${access.target}${access.port ? `:${access.port}` : ""}` };
+        }
+        catch (error) {
+            if (attempt >= 3)
+                throw error;
+            ui.rejected(`${error.message}. Try again.`);
+        }
+    }
+}
+/**
+ * Connects and checks the server. If it refuses the default keys (ssh's own: the agent and
+ * ~/.ssh/id_*), each key pair in ~/.ssh is tried in turn with -i, without asking: auth
+ * refusals come back fast, so this takes seconds. Only when none works does it stop, with
+ * what to do. A key named with --identity is the only one tried.
+ */
+async function reachServer(deps, sshDir, first, target) {
+    const home = deps.sources.home;
+    const ui = deps.newUi();
+    ui.plan([{ id: "ssh", label: "Server" }]);
+    ui.start("ssh", target);
+    const tried = [];
+    let searching = false;
+    let newHostKey = false;
+    const attempt = async (access) => {
+        try {
+            return await checkServer(access, deps.ssh, target);
+        }
+        catch (error) {
+            if (error instanceof SshAuthError) {
+                newHostKey ||= error.newHostKey;
+                if (access.identityFile)
+                    tried.push(access.identityFile);
+                return undefined;
+            }
+            if (searching)
+                ui.plan([{ id: "ssh", label: "Server" }]);
+            ui.fail("ssh", "can't set up here");
+            ui.finish();
+            throw error;
+        }
+    };
+    let access = first;
+    let facts = await attempt(access);
+    if (!facts && !first.identityFile) {
+        const keys = discoverKeys(sshDir, await deps.sources.listDir(sshDir));
+        searching = keys.length > 0;
+        if (searching)
+            ui.plan([{ id: "keys", label: "Trying your SSH keys…" }]);
+        for (const key of keys) {
+            access = { ...first, identityFile: key };
+            ui.start("keys", tilde(key, home));
+            facts = await attempt(access);
+            if (facts)
+                break;
+        }
+    }
+    if (searching)
+        ui.plan([{ id: "ssh", label: "Server" }]);
+    if (!facts) {
+        ui.fail("ssh", first.identityFile ? `${tilde(first.identityFile, home)} not accepted` : tried.length > 0 ? "none of your SSH keys was accepted" : "SSH key not accepted");
+        ui.finish();
+        throw noKeyWorks(first, tried, discoverKeys(sshDir, await deps.sources.listDir(sshDir)), home);
+    }
+    const display = `${facts.user}@${target.replace(/^[^@]*@/, "")}`;
+    ui.done("ssh", access.identityFile ? `${display} with ${tilde(access.identityFile, home)} · ${facts.os} · ${facts.arch}` : `${display}  ${facts.os} · ${facts.arch}`);
+    ui.finish();
+    if (facts.newHostKey || newHostKey)
+        deps.newUi().line("info", "New server", "first connection: trusted its host key (accept-new)");
+    return { access, facts };
+}
+/** Every key was refused: what to do next, with this server and this laptop's own key filled in. */
+function noKeyWorks(access, tried, keys, home) {
+    const port = access.port ? `-p ${access.port} ` : "";
+    const key = keys[0] ? tilde(keys[0], home) : undefined;
+    const lines = [
+        access.identityFile
+            ? `${access.target} didn't accept ${tilde(access.identityFile, home)}.`
+            : `${access.target} didn't accept this computer's SSH keys (${["the default ones", ...tried.map((file) => tilde(file, home))].join(", ")}).`,
+        "  Add your public key to the server (it asks for the password once):",
+        ...(key ? [] : ["     ssh-keygen -t ed25519"]),
+        `     ssh-copy-id -i ${key ?? "~/.ssh/id_ed25519"}.pub ${port}${access.target}`,
+        "  If your key has a passphrase, load it first with: ssh-add",
+        "  Or name the key this server takes: dl setup --identity ~/.ssh/KEY",
+    ];
+    return new Error(lines.join("\n"));
+}
+function tilde(path, home) {
+    return path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path;
+}
+function sameServer(remote, access) {
+    return remote.ssh?.target === access.target && remote.ssh.port === access.port;
+}
+async function stillWorks(remote, open) {
+    return withConnections(open, async (connections) => {
+        await (await connections.client(remote)).health();
+        return true;
+    }).catch(() => false);
+}
+/**
+ * What this laptop calls the server: the ~/.ssh/config alias the user picked, else the
+ * server's own hostname, else its address (203-0-113-10). Unique unless it's this same server.
+ */
+async function remoteName(access, remotesFile, preferred) {
+    const host = hostOf(access.target).toLowerCase();
+    const fromAddress = /^\d+(\.\d+){3}$/.test(host) || host.includes(":") ? host.replace(/[.:]/g, "-") : host.split(".")[0] ?? "";
+    const name = [preferred, fromAddress].map((label) => serverLabel(label ?? "")).find((label) => label !== undefined) ?? "server";
+    const remotes = await loadRemotes(remotesFile);
+    for (let n = 1;; n++) {
+        const candidate = n === 1 ? name : `${name}-${n}`;
+        const existing = remotes.find((remote) => remote.name === candidate);
+        if (!existing || sameServer(existing, access))
+            return candidate;
+    }
+}
+/** A hostname as a server name (lowercase, dashes, room for a -2), or undefined if nothing usable is left. */
+export function serverLabel(text) {
+    const label = text.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 36).replace(/-+$/, "");
+    return REMOTE_NAME_RE.test(label) && label !== "localhost" ? label : undefined;
+}
+function finishScreen(ui, capacity) {
+    ui.ready(capacity ? `Ready · fits ~${capacity} agents at once (estimate)` : "Ready", [
+        { label: "From any GitHub repository", value: RUN_EXAMPLE },
+        { label: "See progress, then check out the result", value: "dl runs\ndl pull ID" },
+    ]);
+}
+function laptopName(name) {
+    return name.replace(/\.local$/, "").replace(/[^\p{L}\p{N} ._'()@-]/gu, "-").slice(0, 40) || "laptop";
+}
+async function pick(ui, prompter, label, hint, choices) {
+    const values = Object.values(choices);
+    for (let attempt = 1;; attempt++) {
+        const answer = (await prompter.text(ui.prompt(label, hint))).trim();
+        const choice = answer === "" ? values[0] : choices[answer];
+        if (choice)
+            return choice;
+        if (attempt >= 3)
+            throw new Error(`Pick one of ${Object.keys(choices).join(", ")}`);
+        ui.rejected(`Type ${Object.keys(choices).join(" or ")}.`);
+    }
+}
+/** `dl setup` with the real terminal, ssh, gh, and filesystem. */
+export async function setup(options) {
+    const { io, terminal } = options;
+    const color = io.color === true;
+    const execFileAsync = promisify(execFile);
+    const home = homedir();
+    let identityFile;
+    if (options.identityFile !== undefined) {
+        // The private key, even when the .pub next to it was named.
+        identityFile = resolve(options.identityFile.replace(/^~(?=$|\/)/, home).replace(/\.pub$/, ""));
+        await fileAccess(identityFile).catch(() => { throw new Error(`No SSH key at ${options.identityFile} (--identity takes the private key, e.g. ~/.ssh/id_ed25519)`); });
+    }
+    await setupWizard({
+        newUi: () => terminal ? new TerminalUi(io.out, undefined, color) : new PlainUi(io.out),
+        prompter: new TtyPrompter(),
+        write: io.out,
+        color,
+        ssh: realSshExec,
+        open: openRemote,
+        sources: {
+            env: process.env,
+            home,
+            readFile: (path) => readFile(path, "utf8").catch(() => undefined),
+            listDir: (path) => readdir(path).catch(() => []),
+            gh: () => execFileAsync("gh", ["auth", "token"], { timeout: 5000 }).then(({ stdout }) => stdout.trim() || undefined, () => undefined),
+            fetch: globalThis.fetch,
+        },
+        hostname: hostname(),
+        installUrl: process.env.DL_INSTALL_URL || INSTALL_URL,
+        ...(options.localSetup ? { localSetup: options.localSetup } : {}),
+        ...(identityFile ? { identityFile } : {}),
+    });
+    return 0;
+}

package/dist/laptop/ssh.js

@@ -0,0 +1,216 @@
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+/**
+ * The concrete hosts in an ssh config. Wildcard and negated patterns are defaults, not
+ * places to connect to, so they're skipped; `Match` blocks are ignored. ssh takes the first
+ * value it finds for each option, so a host's own block wins, then global or `Host *` lines.
+ */
+export function parseSshConfig(text, home) {
+    const blocks = [];
+    const global = {};
+    let current = global;
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const match = /^(\S+?)(?:\s*=\s*|\s+)(.+)$/.exec(line);
+        if (!match)
+            continue;
+        const key = match[1].toLowerCase();
+        const value = match[2].trim();
+        if (key === "host") {
+            const block = { patterns: value.split(/\s+/).map(unquote), settings: {} };
+            blocks.push(block);
+            current = block.settings;
+            continue;
+        }
+        if (key === "match") {
+            current = undefined;
+            continue;
+        }
+        if (!current)
+            continue;
+        const setting = unquote(value);
+        if (key === "hostname")
+            current.hostName ??= setting;
+        else if (key === "user")
+            current.user ??= setting;
+        else if (key === "identityfile")
+            current.identityFile ??= expandHome(setting, home);
+        else if (key === "port" && /^\d+$/.test(setting))
+            current.port ??= Number(setting);
+    }
+    const defaults = { ...global };
+    for (const block of blocks) {
+        if (!block.patterns.includes("*"))
+            continue;
+        for (const [key, value] of Object.entries(block.settings))
+            defaults[key] ??= value;
+    }
+    const hosts = new Map();
+    for (const block of blocks) {
+        for (const pattern of block.patterns) {
+            if (/[*?!]/.test(pattern) || hosts.has(pattern))
+                continue;
+            const host = { alias: pattern };
+            for (const source of [block.settings, defaults]) {
+                for (const [key, value] of Object.entries(source))
+                    host[key] ??= value;
+            }
+            hosts.set(pattern, host);
+        }
+    }
+    return [...hosts.values()];
+}
+/** How a config host reads in a list: root@203.0.113.10, or with a port when it isn't 22. */
+export function describeHost(host) {
+    const port = host.port && host.port !== 22 ? `:${host.port}` : "";
+    return `${host.user ? `${host.user}@` : ""}${host.hostName ?? host.alias}${port}`;
+}
+/** Private keys in ~/.ssh: the files that have a matching .pub next to them. */
+export function discoverKeys(sshDir, names) {
+    const present = new Set(names);
+    const preferred = ["id_ed25519", "id_ecdsa", "id_rsa"];
+    return names
+        .filter((name) => !name.endsWith(".pub") && present.has(`${name}.pub`))
+        .sort((a, b) => rank(a) - rank(b) || a.localeCompare(b))
+        .map((name) => join(sshDir, name));
+    function rank(name) {
+        const index = preferred.indexOf(name);
+        return index === -1 ? preferred.length : index;
+    }
+}
+/** `user@host`, `host`, `user@host:2222`, or `user@[2001:db8::1]:2222` as typed by the user. */
+export function parseTarget(input) {
+    const text = input.trim().replace(/^ssh\s+/, "");
+    const match = /^(?:([A-Za-z0-9._-]+)@)?(\[[0-9A-Fa-f:.]+\]|[A-Za-z0-9._-]+)(?::(\d{1,5}))?$/.exec(text);
+    if (!match || match[2].startsWith("-"))
+        throw new Error(`"${input.trim()}" isn't a server address; type it like root@203.0.113.10 or root@box.example.com:2222`);
+    const host = match[2].replace(/^\[(.*)\]$/, "$1");
+    const port = match[3] ? Number(match[3]) : undefined;
+    if (port !== undefined && (port < 1 || port > 65535))
+        throw new Error(`${port} isn't a port`);
+    return { target: `${match[1] ? `${match[1]}@` : ""}${host}`, ...(port && port !== 22 ? { port } : {}) };
+}
+/** Options for every non-interactive ssh: no password prompts, a bounded wait, and trust on first use. */
+export function sshOptions(access) {
+    if (access.target.startsWith("-"))
+        throw new Error(`Not a server: ${access.target}`);
+    return [
+        "-o", "BatchMode=yes",
+        "-o", "ConnectTimeout=10",
+        "-o", "StrictHostKeyChecking=accept-new",
+        ...(access.port ? ["-p", String(access.port)] : []),
+        // With a chosen key, offer only it: an agent full of keys can hit the server's MaxAuthTries first.
+        ...(access.identityFile ? ["-i", access.identityFile, "-o", "IdentitiesOnly=yes"] : []),
+    ];
+}
+/** The command line people would type for this server, for messages. */
+export function sshCommandLine(access) {
+    return ["ssh", ...(access.port ? ["-p", String(access.port)] : []), ...(access.identityFile ? ["-i", access.identityFile] : []), access.target].join(" ");
+}
+export const realSshExec = (access, command, options = {}) => new Promise((resolve, reject) => {
+    const child = spawn("ssh", [...sshOptions(access), access.target, command], {
+        stdio: ["pipe", "pipe", "pipe"],
+        ...(options.signal ? { signal: options.signal } : {}),
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", lines((chunk) => { stdout += chunk; }, options.onStdoutLine));
+    child.stderr.on("data", lines((chunk) => { stderr += chunk; }, options.onStderrLine));
+    child.on("error", (error) => reject(error.code === "ENOENT" ? new Error("ssh isn't installed on this computer") : error));
+    child.on("close", (code) => resolve({ code: code ?? 255, stdout, stderr }));
+    // Always close stdin: a remote command reading it would otherwise wait forever.
+    child.stdin.on("error", () => { });
+    child.stdin.end(options.input ?? "");
+});
+/** Collects a stream's text and calls back once per complete line. */
+export function lines(collect, onLine) {
+    let pending = "";
+    return (chunk) => {
+        const text = chunk.toString();
+        collect(text);
+        if (!onLine)
+            return;
+        pending += text;
+        const parts = pending.split("\n");
+        pending = parts.pop() ?? "";
+        for (const part of parts)
+            onLine(part.replace(/\r$/, ""));
+    };
+}
+/** The server refused our keys; the wizard tries the others in ~/.ssh. */
+export class SshAuthError extends Error {
+    access;
+    newHostKey;
+    constructor(access, detail, newHostKey = false) {
+        super(`The server didn't accept this computer's SSH key (${detail}).`);
+        this.access = access;
+        this.newHostKey = newHostKey;
+        this.name = "SshAuthError";
+    }
+}
+const SUPPORTED_OS = new Set(["ubuntu 22.04", "ubuntu 24.04", "debian 12"]);
+// One round trip: who we are, the OS, the CPU, whether we can become root without a password,
+// and the server's own name (what the laptop calls it unless ~/.ssh/config already names it).
+const PROBE = 'id -u; id -un; . /etc/os-release; echo "$ID $VERSION_ID"; uname -m; ' +
+    'if [ "$(id -u)" = 0 ]; then echo root; elif sudo -n true 2>/dev/null; then echo sudo; else echo nosudo; fi; ' +
+    'hostname -s 2>/dev/null || cat /etc/hostname 2>/dev/null';
+/** Connects once and checks the server can take an install: a supported OS, and root or passwordless sudo. */
+export async function checkServer(access, ssh, display) {
+    const result = await ssh(access, PROBE);
+    const newHostKey = /Permanently added/i.test(result.stderr);
+    if (result.code === 255 || result.stdout.trim() === "") {
+        const detail = lastLine(result.stderr) || `ssh exited with ${result.code}`;
+        if (/Permission denied|Too many authentication failures|no mutual signature|Authentication failed/i.test(result.stderr)) {
+            throw new SshAuthError(access, detail, newHostKey);
+        }
+        if (/Host key verification failed|REMOTE HOST IDENTIFICATION HAS CHANGED/i.test(result.stderr)) {
+            throw new Error(`${display}'s SSH host key changed since this computer last connected, so it stopped (that can mean someone is in the middle). If you rebuilt the server, remove the old key with: ssh-keygen -R ${hostOf(access.target)}`);
+        }
+        throw new Error(`Couldn't reach ${display} over SSH: ${detail}\n  Check that this works: ${sshCommandLine(access)}`);
+    }
+    const [uid, user, osLine, arch, privilege, name] = result.stdout.trim().split("\n").map((line) => line.trim());
+    const os = formatOs(osLine ?? "");
+    const facts = {
+        user: user || "?",
+        root: uid === "0",
+        sudo: privilege === "sudo",
+        os,
+        arch: arch === "aarch64" ? "arm64" : arch || "?",
+        newHostKey,
+        ...(name ? { hostname: name } : {}),
+    };
+    if (!facts.root && !facts.sudo) {
+        throw new Error([
+            `${facts.user} on ${display} isn't root and can't use sudo without a password, and setup needs one of them.`,
+            `  Either connect as root (root@${hostOf(access.target)}), or let ${facts.user} use sudo without a password:`,
+            `     echo '${facts.user} ALL=(ALL) NOPASSWD:ALL' | sudo tee /etc/sudoers.d/${facts.user}`,
+        ].join("\n"));
+    }
+    if (!SUPPORTED_OS.has((osLine ?? "").toLowerCase().replace(/"/g, ""))) {
+        throw new Error(`${display} runs ${os || "an unknown system"}; Directionally Local needs Ubuntu 22.04, Ubuntu 24.04, or Debian 12.`);
+    }
+    return facts;
+}
+function formatOs(line) {
+    const [id = "", version = ""] = line.replace(/"/g, "").split(/\s+/);
+    const names = { ubuntu: "Ubuntu", debian: "Debian" };
+    return `${names[id] ?? id} ${version}`.trim();
+}
+export function hostOf(target) {
+    return target.slice(target.lastIndexOf("@") + 1);
+}
+function lastLine(text) {
+    return text.trim().split("\n").filter((line) => !/Permanently added/i.test(line)).at(-1)?.trim() ?? "";
+}
+function unquote(value) {
+    return value.length >= 2 && value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1) : value;
+}
+function expandHome(path, home) {
+    return path.replace(/^~(?=$|\/)/, home).replace(/%d/g, home);
+}
+/** Single-quotes a value for the remote shell. */
+export function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}

package/dist/laptop/tunnel.js

@@ -0,0 +1,120 @@
+import { spawn } from "node:child_process";
+import { connect, createServer } from "node:net";
+import { RemoteClient } from "./client.js";
+import { sshCommandLine, sshOptions } from "./ssh.js";
+const realSpawn = (args) => spawn("ssh", args, { stdio: ["ignore", "ignore", "pipe"] });
+/** The ssh arguments for a tunnel from a local port to the server's loopback port. */
+export function tunnelArgs(access, localPort, remotePort) {
+    return ["-N", "-o", "ExitOnForwardFailure=yes", ...sshOptions(access), "-L", `127.0.0.1:${localPort}:127.0.0.1:${remotePort}`, access.target];
+}
+export function createOpener(options = {}) {
+    const spawnTunnel = options.spawn ?? realSpawn;
+    const freePort = options.freePort ?? pickFreePort;
+    const accepts = options.accepts ?? acceptsConnections;
+    const timeoutMs = options.timeoutMs ?? 20_000;
+    const pollMs = options.pollMs ?? 100;
+    return async (remote) => {
+        if (!remote.ssh)
+            return { url: remote.url, close: async () => { } };
+        const access = remote.ssh;
+        const remotePort = Number(new URL(remote.url).port || 80);
+        const port = await freePort();
+        const child = spawnTunnel(tunnelArgs(access, port, remotePort));
+        let stderr = "";
+        child.stderr?.on("data", (chunk) => { stderr += chunk.toString(); });
+        let exited = child.exitCode !== null;
+        child.once("exit", () => { exited = true; });
+        // If this process ends without closing the tunnel (an uncaught error), take ssh with it.
+        const onExit = () => { if (!exited)
+            child.kill("SIGTERM"); };
+        process.once("exit", onExit);
+        const close = async () => {
+            process.off("exit", onExit);
+            if (exited)
+                return;
+            const gone = new Promise((resolve) => {
+                child.once("exit", () => resolve());
+                setTimeout(resolve, 2000).unref?.();
+            });
+            child.kill("SIGTERM");
+            await gone;
+        };
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            if (exited) {
+                await close();
+                const detail = stderr.trim().split("\n").at(-1)?.trim();
+                throw new Error(`Couldn't open an SSH tunnel to ${remote.name} (${access.target})${detail ? `: ${detail}` : ""}\n  Check that this works: ${sshCommandLine(access)}`);
+            }
+            if (await accepts(port))
+                return { url: `http://127.0.0.1:${port}`, close };
+            if (Date.now() >= deadline) {
+                await close();
+                throw new Error(`Timed out after ${Math.round(timeoutMs / 1000)}s opening an SSH tunnel to ${remote.name} (${access.target}).\n  Check that this works: ${sshCommandLine(access)}`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollMs));
+        }
+    };
+}
+export const openRemote = createOpener();
+/**
+ * The endpoints one command uses: at most one tunnel per server, reused across its
+ * requests, all closed when the command ends (commands close it in `finally`, which also
+ * runs when Ctrl-C aborts a watch).
+ */
+export class Connections {
+    opener;
+    open = new Map();
+    constructor(opener = openRemote) {
+        this.opener = opener;
+    }
+    async client(remote) {
+        let endpoint = this.open.get(remote.name);
+        if (!endpoint) {
+            endpoint = this.opener(remote);
+            this.open.set(remote.name, endpoint);
+        }
+        return new RemoteClient((await endpoint).url, remote.token);
+    }
+    async close() {
+        const endpoints = [...this.open.values()];
+        this.open.clear();
+        await Promise.all(endpoints.map((endpoint) => endpoint.then((entry) => entry.close(), () => { })));
+    }
+}
+/** Runs `work` with a fresh set of connections and always closes them. */
+export async function withConnections(opener, work) {
+    const connections = new Connections(opener);
+    try {
+        return await work(connections);
+    }
+    finally {
+        await connections.close();
+    }
+}
+/** A port nothing listens on right now (the OS picks it; ssh binds it a moment later). */
+export function pickFreePort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.unref();
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            const port = typeof address === "object" && address ? address.port : 0;
+            server.close(() => port ? resolve(port) : reject(new Error("no free port")));
+        });
+    });
+}
+export function acceptsConnections(port) {
+    return new Promise((resolve) => {
+        const socket = connect({ host: "127.0.0.1", port });
+        const done = (ok) => {
+            socket.removeAllListeners();
+            socket.destroy();
+            resolve(ok);
+        };
+        socket.setTimeout(1000, () => done(false));
+        socket.once("connect", () => done(true));
+        socket.once("error", () => done(false));
+    });
+}