waterplane 0.0.1 → 0.1.11

package/packages/host/dist/claudebin.js

@@ -0,0 +1,113 @@
+/**
+ * Where the `claude` binary is — found, so the person does not have to.
+ *
+ * A first install had Claude Code installed but not on PATH (the native
+ * installer drops it in `~/.local/bin`, which a fresh shell may not list), and a
+ * launchd/systemd service starts with a minimal PATH on top of that. The host
+ * said "make sure it's on PATH" — a chore it can do itself. Order: the knob
+ * (`WATERPLANE_CLAUDE_BIN`), then `claude` on PATH, then the usual install
+ * locations, then plain `claude` (unchanged behaviour) with what was tried.
+ *
+ * Pure: every fact is injected (`exists`, `onPath`, `readdir`), so tests never
+ * touch the real filesystem. Synchronous checks only — no child process.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir, release } from "node:os";
+import path from "node:path";
+import { isWsl } from "./doctorwsl.js";
+const verDesc = (a, b) => {
+    const n = (s) => s.replace(/^v/, "").split(".").map((x) => Number(x) || 0);
+    const [x, y] = [n(a), n(b)];
+    for (let i = 0; i < 3; i++)
+        if ((y[i] ?? 0) !== (x[i] ?? 0))
+            return (y[i] ?? 0) - (x[i] ?? 0);
+    return 0;
+};
+export function findClaudeBin(f) {
+    if (f.knob)
+        return { bin: f.knob, source: "env", tried: [] };
+    if (f.onPath("claude"))
+        return { bin: "claude", source: "path", tried: [] };
+    const win = f.platform === "win32";
+    const p = win ? path.win32 : path.posix;
+    const env = f.env ?? {};
+    const ls = f.readdir ?? (() => []);
+    const cands = [];
+    if (win) {
+        if (env.APPDATA)
+            cands.push(p.join(env.APPDATA, "npm", "claude.cmd"));
+        cands.push(p.join(env.USERPROFILE || f.home, ".local", "bin", "claude.exe"));
+    }
+    else {
+        cands.push(p.join(f.home, ".local", "bin", "claude"), p.join(f.home, ".claude", "local", "claude"), "/opt/homebrew/bin/claude", "/usr/local/bin/claude", p.join(f.home, ".npm-global", "bin", "claude"));
+        if (env.npm_config_prefix)
+            cands.push(p.join(env.npm_config_prefix, "bin", "claude"));
+        cands.push(p.join(f.home, ".volta", "bin", "claude"), p.join(f.home, ".bun", "bin", "claude"));
+        const nvm = p.join(f.home, ".nvm", "versions", "node");
+        for (const v of [...ls(nvm)].sort(verDesc))
+            cands.push(p.join(nvm, v, "bin", "claude"));
+        const fnm = p.join(f.home, ".local", "share", "fnm", "node-versions");
+        for (const v of [...ls(fnm)].sort(verDesc))
+            cands.push(p.join(fnm, v, "installation", "bin", "claude"));
+    }
+    const tried = [];
+    for (const c of cands) {
+        tried.push(c);
+        if (f.exists(c))
+            return { bin: c, source: "found", tried };
+    }
+    const out = { bin: "claude", source: "path", tried, missing: true };
+    if (f.wsl && !win) {
+        for (const u of ls("/mnt/c/Users")) {
+            for (const rel of ["AppData/Roaming/npm/claude.cmd", ".local/bin/claude.exe"]) {
+                const w = `/mnt/c/Users/${u}/${rel}`;
+                if (f.exists(w)) {
+                    out.windowsSide = w;
+                    return out;
+                }
+            }
+        }
+    }
+    return out;
+}
+/** `/home/me/x` → `~/x`. */
+export const tilde = (s, home) => home && (s === home || s.startsWith(home + "/") || s.startsWith(home + "\\")) ? "~" + s.slice(home.length) : s;
+/** The real machine's PATH, scanned synchronously. */
+export function pathHas(name, platform) {
+    const win = platform === "win32";
+    const dirs = (process.env.PATH ?? "").split(win ? ";" : ":").filter(Boolean);
+    const names = win ? [`${name}.exe`, `${name}.cmd`, name] : [name];
+    return dirs.some((d) => names.some((n) => existsSync(path.join(d, n))));
+}
+const safeLs = (p) => { try {
+    return readdirSync(p);
+}
+catch {
+    return [];
+} };
+const safeRead = (p) => { try {
+    return readFileSync(p, "utf8");
+}
+catch {
+    return null;
+} };
+let cached = null;
+/** Resolved once per process from the real machine (the knob is read live by `claudeBin()`, not here). */
+export function claudeBinResolution() {
+    // A miss is never cached: installing claude and retrying must work without a host restart. Nor is
+    // a hit trusted blindly: a package-manager upgrade unlinks the command for minutes, so the cached
+    // answer is re-checked (one stat or PATH scan) and re-resolved when it has gone.
+    if (cached && !cached.missing && (cached.bin.includes("/") ? existsSync(cached.bin) : pathHas(cached.bin, process.platform)))
+        return cached;
+    cached = findClaudeBin({
+        env: process.env,
+        platform: process.platform,
+        home: homedir(),
+        exists: existsSync,
+        onPath: (n) => pathHas(n, process.platform),
+        readdir: safeLs,
+        wsl: process.platform === "linux" && isWsl(safeRead("/proc/version"), release()),
+    });
+    return cached;
+}
+//# sourceMappingURL=claudebin.js.map

package/packages/host/dist/claudebin.js.map

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

package/packages/host/dist/claudeconfig.d.ts

@@ -0,0 +1,23 @@
+export declare function claudeConfigDir(): string;
+/**
+ * Where the claude CLI stores a directory's conversations:
+ * `<config dir>/projects/<slug>/<conversation-uuid>.jsonl`, slug = cwd with every
+ * non-alphanumeric replaced by `-`.
+ *
+ * A slug past 200 chars is NOT that: the CLI keeps the first 200 and appends
+ * `-<hash of the full path>` (read out of the 2.x bundle; the hash is not
+ * re-derived here, so a wrong guess of it cannot happen). For such a path the
+ * folder is found by its surviving head, and ACCEPTED only when exactly one
+ * candidate holds a log naming this very cwd — two long worktrees can share
+ * their first 200 chars, and the wrong sibling is a wrong file. Nothing found
+ * (yet) or ambiguous answers the untruncated path, which does not exist, so a
+ * reader finds nothing and says so.
+ *
+ * The CLI slugs its REALPATH: a session started in `/tmp/x` (or under macOS's
+ * `/var` → `/private/var`, or a symlinked checkout) writes to
+ * `-private-tmp-x`. So when the folder for the path as given does not exist,
+ * the resolved path's is tried — found by the real-CLI smoke on 2.1.304, whose
+ * scratch repo under `/var/folders` had every log reader that builds its path
+ * from the cwd (the `AskUserQuestion` enrichment among them) reading nothing.
+ */
+export declare function claudeProjectDir(cwd: string): string;

package/packages/host/dist/claudeconfig.js

@@ -0,0 +1,118 @@
+/**
+ * The claude CLI's private directory on THIS desktop — the one definition
+ * every reader (`projects/`, `sessions/`, `settings.json`, `commands/`) goes
+ * through. `CLAUDE_CONFIG_DIR` replaces the whole directory exactly as the CLI
+ * reads it; `<PREFIX>CLAUDE_HOME` is the tests' fake-HOME knob. The rule is
+ * `@waterplane/shared`'s `claudeConfigDirOf` (the extensions share it).
+ * Read at CALL time, so a test may move it. Spawned `claude` children inherit
+ * `CLAUDE_CONFIG_DIR` untouched (`ptyenv.ts` starts from `process.env`; the
+ * tmux pane gets it explicitly, `sessions/tmux.ts`).
+ */
+import { closeSync, existsSync, openSync, readSync, readdirSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { claudeConfigDirOf, transcriptDirName, truncatedSlugPrefix } from "@waterplane/shared";
+import { env } from "./env.js";
+export function claudeConfigDir() {
+    return claudeConfigDirOf({ configDir: process.env.CLAUDE_CONFIG_DIR, testHome: env("CLAUDE_HOME"), home: homedir() });
+}
+/**
+ * Where the claude CLI stores a directory's conversations:
+ * `<config dir>/projects/<slug>/<conversation-uuid>.jsonl`, slug = cwd with every
+ * non-alphanumeric replaced by `-`.
+ *
+ * A slug past 200 chars is NOT that: the CLI keeps the first 200 and appends
+ * `-<hash of the full path>` (read out of the 2.x bundle; the hash is not
+ * re-derived here, so a wrong guess of it cannot happen). For such a path the
+ * folder is found by its surviving head, and ACCEPTED only when exactly one
+ * candidate holds a log naming this very cwd — two long worktrees can share
+ * their first 200 chars, and the wrong sibling is a wrong file. Nothing found
+ * (yet) or ambiguous answers the untruncated path, which does not exist, so a
+ * reader finds nothing and says so.
+ *
+ * The CLI slugs its REALPATH: a session started in `/tmp/x` (or under macOS's
+ * `/var` → `/private/var`, or a symlinked checkout) writes to
+ * `-private-tmp-x`. So when the folder for the path as given does not exist,
+ * the resolved path's is tried — found by the real-CLI smoke on 2.1.304, whose
+ * scratch repo under `/var/folders` had every log reader that builds its path
+ * from the cwd (the `AskUserQuestion` enrichment among them) reading nothing.
+ */
+export function claudeProjectDir(cwd) {
+    const given = projectDirFor(cwd);
+    if (existsSync(given))
+        return given;
+    let real;
+    try {
+        real = realpathSync(cwd);
+    }
+    catch {
+        return given;
+    }
+    if (real === cwd)
+        return given;
+    const resolved = projectDirFor(real);
+    return existsSync(resolved) ? resolved : given;
+}
+function projectDirFor(cwd) {
+    const projects = join(claudeConfigDir(), "projects");
+    const slug = transcriptDirName(cwd);
+    const exact = join(projects, slug);
+    const head = truncatedSlugPrefix(slug);
+    if (head === null)
+        return exact;
+    const hit = longSlugCache.get(exact);
+    if (hit && existsSync(hit))
+        return hit;
+    let found = null;
+    try {
+        for (const name of readdirSync(projects)) {
+            if (!name.startsWith(head))
+                continue;
+            const dir = join(projects, name);
+            if (!dirNamesCwd(dir, cwd))
+                continue;
+            if (found)
+                return exact; // two folders claim it: ambiguous is absent
+            found = dir;
+        }
+    }
+    catch {
+        return exact;
+    }
+    if (!found)
+        return exact;
+    longSlugCache.set(exact, found);
+    return found;
+}
+const longSlugCache = new Map();
+/** Does any of this folder's first few logs record `cwd` as its working directory? */
+function dirNamesCwd(dir, cwd) {
+    const needle = `"cwd":${JSON.stringify(cwd)}`;
+    let names;
+    try {
+        names = readdirSync(dir).filter((n) => n.endsWith(".jsonl")).slice(0, 4);
+    }
+    catch {
+        return false;
+    }
+    for (const n of names) {
+        let fd = null;
+        try {
+            fd = openSync(join(dir, n), "r");
+            const buf = Buffer.alloc(65536);
+            const got = readSync(fd, buf, 0, buf.length, 0);
+            if (buf.toString("utf8", 0, got).includes(needle))
+                return true;
+        }
+        catch { /* unreadable: not evidence */ }
+        finally {
+            if (fd !== null)
+                try {
+                    closeSync(fd);
+                }
+                catch { /* ignore */ }
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=claudeconfig.js.map

package/packages/host/dist/claudeconfig.js.map

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

package/packages/host/dist/cli/entry.d.ts

@@ -0,0 +1 @@
+export {};

package/packages/host/dist/cli/entry.js

@@ -0,0 +1,11 @@
+/**
+ * The CLI as a file to run: `node packages/host/dist/cli/entry.js <command>`. The release's
+ * generated `bin/<slug>.mjs` does the same; this one exists in a checkout too, which is what the
+ * Windows launcher runs inside WSL for a command the host's own CLI answers (`pair`).
+ */
+import { main } from "./index.js";
+const code = await main(process.argv.slice(2));
+// let a piped stdout drain before exiting
+await new Promise((r) => process.stdout.write("", r));
+process.exit(code);
+//# sourceMappingURL=entry.js.map

package/packages/host/dist/cli/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../../src/cli/entry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAElC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAC/C,0CAA0C;AAC1C,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;AACtD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC"}

package/packages/host/dist/cli/index.d.ts

@@ -0,0 +1,12 @@
+interface Identity {
+    name: string;
+    version: string;
+    commit: string | null;
+    source: "release.json" | "checkout";
+}
+/** What this install is: `release.json` when present, else a dev checkout's package.json + git. */
+export declare function identity(root?: string): Identity;
+/** The one line `version` prints, on every platform (the Windows launcher prints it too). */
+export declare function versionLine(root?: string): string;
+export declare function main(argv: string[]): Promise<number>;
+export {};

package/packages/host/dist/cli/index.js

@@ -0,0 +1,122 @@
+/**
+ * The command-line entry a release ships (`bin/<slug>.mjs` → here).
+ *
+ * `start` and `doctor` run `main.js` IN THIS PROCESS, so launchd/systemd
+ * supervise the daemon itself, not a wrapper. `service` and `update` are
+ * written by other packages and loaded lazily: a build without them says so
+ * in one line instead of failing to start.
+ *
+ * Dev checkouts keep `npm run start/doctor/restart`; those never come here. On win32 every
+ * command goes to `windows.ts`, which runs the host inside WSL.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { BRAND, nodeMeetsMin, nodeTooOldSentence } from "@waterplane/shared";
+// import.meta.dirname is undefined before Node 20.11 (the host's floor is NODE_MIN, 22.12): refuse in words, not a TypeError.
+if (!nodeMeetsMin(process.versions.node)) {
+    console.error(`[${BRAND.slug}] ${nodeTooOldSentence(process.versions.node)}`);
+    process.exit(1);
+}
+/** `packages/host/dist/cli` → the release root (or the checkout root). */
+const ROOT_DIR = resolve(import.meta.dirname, "../../../..");
+const MAIN_JS = resolve(import.meta.dirname, "../main.js");
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+const str = (v) => (typeof v === "string" && v ? v : null);
+/** `<40 hex>` or `<40 hex>-dirty` → ten characters, the suffix kept. */
+const shortCommit = (c) => (c ? c.replace(/^([0-9a-f]{10})[0-9a-f]*/, "$1") : null);
+/** What this install is: `release.json` when present, else a dev checkout's package.json + git. */
+export function identity(root = ROOT_DIR) {
+    const rel = readJson(join(root, "release.json"));
+    if (rel) {
+        return { name: str(rel.name) ?? BRAND.slug, version: str(rel.version) ?? "unknown", commit: shortCommit(str(rel.commit)), source: "release.json" };
+    }
+    const pkg = readJson(join(root, "package.json"));
+    let commit = null;
+    if (existsSync(join(root, ".git"))) {
+        try {
+            commit = execFileSync("git", ["rev-parse", "--short", "HEAD"], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || null;
+        }
+        catch { /* no git on PATH: the commit stays absent */ }
+    }
+    return { name: str(pkg?.name) ?? BRAND.slug, version: str(pkg?.version) ?? "unknown", commit, source: "checkout" };
+}
+/** The one line `version` prints, on every platform (the Windows launcher prints it too). */
+export function versionLine(root = ROOT_DIR) {
+    const id = identity(root);
+    return `${id.name} ${id.version}${id.commit ? ` (${id.commit})` : ""}${id.source === "checkout" ? " [dev checkout]" : ""}`;
+}
+const HELP = `${BRAND.slug} — ${BRAND.tagline}
+
+usage: ${BRAND.slug} <command>
+
+  start                       run the host in the foreground (default)
+  doctor [--json]             preflight checks, then exit (1 on a failure);
+                              --json: one JSON document on stdout, for scripts and agents
+  version                     name, version and commit of this install
+  service install|uninstall|status
+                              register the host with launchd / systemd
+  update [--check|--rollback|--restore-state]
+                              check for, apply, or undo a newer release (with its state)
+  pair [--port N] [--json]    mint a pairing code on this desktop's running host and
+                              print the link and code to add it from a phone
+  help                        this text
+`;
+/** Run main.js in this process. Never resolves: the daemon ends the process itself. */
+async function runDaemon(extra) {
+    // `env.ts`'s isDaemonEntry looks at argv[1]; this process IS the daemon.
+    process.argv = [process.argv[0] ?? "node", MAIN_JS, ...extra];
+    await import(MAIN_JS);
+    return await new Promise(() => { });
+}
+/** A sibling module another package writes; its absence is a sentence, not a crash. */
+async function lazy(file, what, args) {
+    const unavailable = () => { console.error(`${BRAND.slug}: the ${what} command is not available in this build.`); return 1; };
+    let m;
+    try {
+        m = (await import(file));
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND")
+            return unavailable();
+        console.error(`${BRAND.slug}: the ${what} command failed to load: ${String(e)}`);
+        return 1;
+    }
+    return typeof m.run === "function" ? m.run(args) : unavailable();
+}
+export async function main(argv) {
+    // Native Windows cannot run the host (sessions need tmux): every command goes to the launcher,
+    // which runs it inside WSL from this same install (`windows.ts`).
+    if (process.platform === "win32")
+        return (await import("./windows.js")).run(argv);
+    const [cmd = "start", ...rest] = argv;
+    switch (cmd) {
+        case "start": return runDaemon([]);
+        case "doctor": return runDaemon(["--doctor", ...rest.filter((a) => a === "--json")]);
+        case "version":
+        case "--version":
+        case "-v":
+            console.log(versionLine());
+            return 0;
+        case "service": return lazy("./service.js", "service", rest);
+        case "pair": return lazy("./pair.js", "pair", rest);
+        case "update": return lazy("./selfupdate.js", "update", rest);
+        case "help":
+        case "--help":
+        case "-h":
+            console.log(HELP);
+            return 0;
+        default:
+            console.error(`${BRAND.slug}: unknown command "${cmd}"\n\n${HELP}`);
+            return 2;
+    }
+}
+//# sourceMappingURL=index.js.map

package/packages/host/dist/cli/index.js.map

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

package/packages/host/dist/cli/pair.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `<slug> pair` — mint a pairing code on THIS desktop's running daemon and
+ * print what a phone needs: the landing URL, the deep link and the 8-character
+ * code. For a desktop nobody can show a QR on yet (a headless VM): read it over
+ * ssh, paste it into the phone's "Add a desktop".
+ *
+ * It asks the daemon over LOOPBACK (`POST /api/pair/mint`, which a loopback
+ * caller may always do) — the same route the phone's QR sheet uses, so there is
+ * one mint and one set of rules (single use, 10 minutes, hashed in memory).
+ *
+ * No terminal QR: the only QR encoder in the repo (`qrcode-generator`) is a
+ * dependency of `packages/web`, and a release's host does not carry it; a new
+ * dependency for a convenience the URL + code already cover is not worth it.
+ */
+import { type PairMintResponse } from "@waterplane/shared";
+export interface PairArgs {
+    port: number | null;
+    json: boolean;
+    help: boolean;
+}
+/** `pair [--port N] [--json] [--help]` → the options, or a sentence saying what was wrong. */
+export declare function parsePairArgs(args: string[]): PairArgs | {
+    error: string;
+};
+export declare const PAIR_HELP: string;
+/** What is printed for a minted code. Pure. */
+export declare function pairLines(m: PairMintResponse): string[];
+export declare function run(args: string[], fetchImpl?: typeof fetch): Promise<number>;

package/packages/host/dist/cli/pair.js

@@ -0,0 +1,94 @@
+/**
+ * `<slug> pair` — mint a pairing code on THIS desktop's running daemon and
+ * print what a phone needs: the landing URL, the deep link and the 8-character
+ * code. For a desktop nobody can show a QR on yet (a headless VM): read it over
+ * ssh, paste it into the phone's "Add a desktop".
+ *
+ * It asks the daemon over LOOPBACK (`POST /api/pair/mint`, which a loopback
+ * caller may always do) — the same route the phone's QR sheet uses, so there is
+ * one mint and one set of rules (single use, 10 minutes, hashed in memory).
+ *
+ * No terminal QR: the only QR encoder in the repo (`qrcode-generator`) is a
+ * dependency of `packages/web`, and a release's host does not carry it; a new
+ * dependency for a convenience the URL + code already cover is not worth it.
+ */
+import { BRAND, formatPairCode } from "@waterplane/shared";
+/** `pair [--port N] [--json] [--help]` → the options, or a sentence saying what was wrong. */
+export function parsePairArgs(args) {
+    const out = { port: null, json: false, help: false };
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--json")
+            out.json = true;
+        else if (a === "--help" || a === "-h")
+            out.help = true;
+        else if (a === "--port" || a.startsWith("--port=")) {
+            const v = a === "--port" ? args[++i] : a.slice("--port=".length);
+            const n = Number(v);
+            if (!v || !Number.isInteger(n) || n < 1 || n > 65535)
+                return { error: `--port needs a number between 1 and 65535, got "${v ?? ""}".` };
+            out.port = n;
+        }
+        else
+            return { error: `unknown option "${a}".` };
+    }
+    return out;
+}
+export const PAIR_HELP = `usage: ${BRAND.slug} pair [--port N] [--json]
+
+  Mint a single-use pairing code on this desktop's running host and print the
+  landing URL, the web app's URL, the deep link and the code. On the phone, open "Add a desktop"
+  and paste the URL (or the address and the code). The code lasts 10 minutes.
+`;
+/** What is printed for a minted code. Pure. */
+export function pairLines(m) {
+    const lines = [
+        `Pairing code   ${formatPairCode(m.code)}   (works once, expires in 10 minutes)`,
+        `Address        ${m.base.replace(/^https?:\/\//, "")}`,
+        `Web app        ${m.base}/   (open in the phone's browser: no install needed)`,
+        `Landing URL    ${m.landingUrl}`,
+        `Deep link      ${m.deepLink}`,
+    ];
+    if (m.lanBase)
+        lines.push(`LAN address    ${m.lanBase.replace(/^https?:\/\//, "")}`);
+    lines.push("", `On the phone: open the landing URL in its browser (it offers the web app and the Android app), or in ${BRAND.name} -> Hosts -> add -> pair with code, paste it (or type the address and the code).`);
+    return lines;
+}
+export async function run(args, fetchImpl = fetch) {
+    const a = parsePairArgs(args);
+    if ("error" in a) {
+        console.error(`${BRAND.slug}: pair: ${a.error}\n\n${PAIR_HELP}`);
+        return 2;
+    }
+    if (a.help) {
+        console.log(PAIR_HELP);
+        return 0;
+    }
+    let port = a.port;
+    if (port === null) {
+        // Loaded here, not at the top: `env.js` reads the .env files (so a PORT set
+        // there is honoured) and the other commands never need it.
+        const { env } = await import("../env.js");
+        port = Number(env("PORT") || 8770);
+    }
+    let r;
+    try {
+        r = await fetchImpl(`http://127.0.0.1:${port}/api/pair/mint`, { method: "POST", headers: { "content-type": "application/json" }, body: "{}" });
+    }
+    catch {
+        console.error(`${BRAND.slug}: pair: nothing answered on 127.0.0.1:${port}. Is the host running? Start it with "${BRAND.slug} start" (or pass --port).`);
+        return 1;
+    }
+    if (!r.ok) {
+        console.error(`${BRAND.slug}: pair: the host refused to mint a code (${r.status}).`);
+        return 1;
+    }
+    const m = (await r.json());
+    if (a.json)
+        console.log(JSON.stringify(m));
+    else
+        for (const l of pairLines(m))
+            console.log(l);
+    return 0;
+}
+//# sourceMappingURL=pair.js.map

package/packages/host/dist/cli/pair.js.map

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

package/packages/host/dist/cli/releasesig.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Who published a release: the host's half of the publisher signature
+ * (`scripts/release/sign-lib.mjs` is the signer's half, `deploy/install.sh.tmpl`
+ * `verify_sig` the installer's). A release carries `<file>.sig` beside
+ * `release.json` and the tarball's `.sha256`: one line, the base64 Ed25519
+ * signature over that file's EXACT bytes. The `.sha256` then binds the tarball.
+ *
+ * Pure: no network, no disk, no env. The host cannot import `scripts/`, so the
+ * verify is restated here in the same few lines as `sign-lib.verifyBytes`;
+ * `packages/host/test/releasesig.test.mjs` signs with sign-lib and verifies
+ * with this, and pins RELEASE_PUBKEY to `deploy/release-pubkey.pem`, so the two
+ * halves and the key cannot drift apart.
+ */
+import { type KeyObject } from "node:crypto";
+/**
+ * `deploy/release-pubkey.pem` as one line: the base64 of its SPKI DER (what
+ * `sign-lib.pubkeyLine` prints, and what the installer embeds). Rotating the
+ * key means changing this AND that file; the drift test fails until both move.
+ */
+export declare const RELEASE_PUBKEY = "MCowBQYDK2VwAyEAJ0/wZZFczT6F3/UdCpuBDC0lhVnNpSwxc1j+4GxoVCI=";
+/** A public key from the one-line SPKI form, refused unless it is Ed25519. */
+export declare function releaseKey(line?: string): KeyObject;
+/** True only when `sigText` (base64, surrounding whitespace ignored) is `key`'s signature of `bytes`. */
+export declare function verifySig(key: KeyObject, bytes: Uint8Array, sigText: string | null | undefined): boolean;
+/**
+ * How a download is checked: against a key, or — only when the person set
+ * `<PREFIX>INSECURE_SKIP_SIG=1` — not at all, said loudly by the caller.
+ */
+export type SigPolicy = {
+    kind: "verify";
+    key: KeyObject;
+} | {
+    kind: "skip";
+};
+/** The policy for an env value: exactly `"1"` skips; anything else verifies against `key`. */
+export declare function sigPolicy(skipValue: string | undefined, key?: KeyObject): SigPolicy;
+/**
+ * Why `name` must not be trusted, or null when its signature checks out.
+ * `sigText` null = the `.sig` could not be fetched. The sentence says what was
+ * refused; the caller adds that nothing was installed.
+ */
+export declare function sigRefusal(name: string, bytes: Uint8Array, sigText: string | null, key: KeyObject): string | null;