From 8fb60eaffd3df6393c85ae2bf0889ba36403142f Mon Sep 17 00:00:00 2001 From: Ben Vinegar <2153+benvinegar@users.noreply.github.com> Date: Mon, 9 Nov 2026 11:16:08 -0500 Subject: [PATCH 1/2] feat(cli): list read-only inventories across all hosts --- ARCHITECTURE.md | 2 +- controller/all-hosts.mjs | 82 ++++++++++++++++++ controller/cli.mjs | 42 ++++++--- controller/leases.mjs | 10 ++- controller/ls.mjs | 14 ++- docs/cli.md | 32 +++---- test/cli-all-hosts.test.mjs | 139 ++++++++++++++++++++++++++++++ test/cli-contracts.test.mjs | 10 +++ test/cli-families.test.mjs | 8 +- test/fixtures/boxery-help-all.txt | 20 ++--- test/fixtures/boxery-help.txt | 4 +- test/help-drift.test.mjs | 12 +++ 12 files changed, 322 insertions(+), 53 deletions(-) create mode 100644 controller/all-hosts.mjs create mode 100644 test/cli-all-hosts.test.mjs diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 7066e91..e2a7c47 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -69,7 +69,7 @@ VM (Ubuntu 24.04; XFCE desktop unless --headless) | `guests/linux.mjs`, `guests/index.mjs` | agent machine and host | What's inside a VM, per guest OS: the agent's home and project, boxery's config and grants directories. `core/` and `host/` both import it instead of keeping their own copies; it imports nothing. Only `linux` exists ([plan](docs/plans/2026-11-03-guest-os-seam.md)) | | `mcp/boxery-mcp.mjs` | agent machine (stdio) or host (HTTP) | MCP server. stdio, or Streamable HTTP at `/mcp` (bearer token required, optional Tailscale user allowlist, Origin check; meant for `tailscale serve`, never funnel). Sessions keep their own host and VM. `vm_view` + `mcp/desktop-view.html` give MCP Apps clients a live desktop | | `extension/index.ts` | agent machine | pi extension: explicit `vm_*` tools next to pi's built-ins (which stay local), `--vm NAME/new/pool`, `--vm-host`, `/vm` commands, throwaway VMs and leases tied to the pi session | -| `controller/boxery` + `controller/*.mjs` | agent machine | The CLI. `controller/boxery` is a small Bash shim (it finds Node and passes arguments on byte for byte, like `host/boxery-host`); `controller/cli.mjs` parses commands and runs the same core code MCP and pi do. Its `COMMANDS` table is the one definition of routing and help (and of which long commands report their progress to the terminal, as OSC 7501 on stderr when it is a terminal: a `status` on the entry, run by `controller/status.mjs`): a command has a `run` handler, and a command family (`host`, `snapshot`, `agent`, `job`, `access`, `lease`; `pool` and `runners` parse their own actions) has `actions`, each naming an existing command whose handler it runs, so `boxery job ls` and `boxery jobs` are one code path and the older spellings need no second table. Commands carry an optional `contract` beside their handlers: selected-host or controller scope, help/payload boundaries, optional host selection, all-host listings, SSH-qualified targets and terminal needs. Ordinary commands use selected-host/legacy-help defaults; aliases and family actions inherit their handler's contract. Approval is conditional when granting (`new`, `fork`, `grant`, `agent-forward`); only `attach` unconditionally needs a terminal on stdin, after argument validation. Family actions are resolved before any host or profile is read; `host` registry actions (`add`, `ls`, `show`, `use`, `rm`) explicitly declare `scope: "registry"` and run before host selection. Registry scope is not an offline guarantee: `host add DEST` contacts DEST. Host maintenance uses the ordinary selected-host path. The code behind the commands: `core/lifecycle.mjs` (new/fork/rm/start/stop/resize/snap/revert/pin/pool/patch, listings), `core/leases.mjs`, `core/grants.mjs`, `vm_copy` (`cp`), `core/versions.mjs`. What only the CLI has: argument parsing and output formats (unchanged, [cli.md](docs/cli.md)), `/dev/tty` grant approval (`controller/grants.mjs`), terminal commands (`ssh`, `attach`, `desktop`, `forward`, `run`, jobs in `controller/jobs.mjs`, `runners once` with your `gh` login), and the host registry's CLI (`controller/hosts.mjs`: `setup`, `host add/ls/show/use/rm`, over `core/registry.mjs`, which `vm_manage host_add/host_rm` use too). Profiles: `core/profile.mjs` (config, `hostRun` to boxery-host, ssh_config, shared connections) and `core/ssh-config.mjs` (quoting and the ssh_config text). A profile `config` that only assigns the controller's settings (`HOST`, `HOST_BIN`, `HOST_PROFILE`, `IDENTITY`, `GRANT_CONFIRM`, as `setup` writes them) is parsed; any other config is sourced by bash (`set -eu`, with `$CONF_DIR` and the defaults set), and its exported environment reaches host commands. `test/ssh-config.test.mjs` holds the ssh_config text and quoting to the Bash controller's (`test/fixtures/bash-profile.sh`), word for word. Each profile's `ssh_config`: `*.boxery` → `ProxyCommand ssh HOST boxery-host connect %h %p`, ControlMaster, per-lease identities, per-VM `ForwardAgent` | +| `controller/boxery` + `controller/*.mjs` | agent machine | The CLI. `controller/boxery` is a small Bash shim (it finds Node and passes arguments on byte for byte, like `host/boxery-host`); `controller/cli.mjs` parses commands and runs the same core code MCP and pi do. Its `COMMANDS` table is the one definition of routing and help (and of which long commands report their progress to the terminal, as OSC 7501 on stderr when it is a terminal: a `status` on the entry, run by `controller/status.mjs`): a command has a `run` handler, and a command family (`host`, `snapshot`, `agent`, `job`, `access`, `lease`; `pool` and `runners` parse their own actions) has `actions`, each naming an existing command whose handler it runs, so `boxery job ls` and `boxery jobs` are one code path and the older spellings need no second table. Commands carry an optional `contract` beside their handlers: selected-host or controller scope, help/payload boundaries, optional host selection, all-host listings, SSH-qualified targets and terminal needs. Ordinary commands use selected-host/legacy-help defaults; aliases and family actions inherit their handler's contract. Approval is conditional when granting (`new`, `fork`, `grant`, `agent-forward`); only `attach` unconditionally needs a terminal on stdin, after argument validation. Family actions are resolved before any host or profile is read; `host` registry actions (`add`, `ls`, `show`, `use`, `rm`) explicitly declare `scope: "registry"` and run before host selection. Registry scope is not an offline guarantee: `host add DEST` contacts DEST. Host maintenance uses the ordinary selected-host path. Read-only host-wide text listings use `controller/all-hosts.mjs`, sharing host ordering, same-host deduplication and headings with `controller/ls.mjs`; JSON and explicit `--host` remain single-host, and mutating actions stay selected-host. The code behind the commands: `core/lifecycle.mjs` (new/fork/rm/start/stop/resize/snap/revert/pin/pool/patch, listings), `core/leases.mjs`, `core/grants.mjs`, `vm_copy` (`cp`), `core/versions.mjs`. What only the CLI has: argument parsing and output formats (unchanged, [cli.md](docs/cli.md)), `/dev/tty` grant approval (`controller/grants.mjs`), terminal commands (`ssh`, `attach`, `desktop`, `forward`, `run`, jobs in `controller/jobs.mjs`, `runners once` with your `gh` login), and the host registry's CLI (`controller/hosts.mjs`: `setup`, `host add/ls/show/use/rm`, over `core/registry.mjs`, which `vm_manage host_add/host_rm` use too). Profiles: `core/profile.mjs` (config, `hostRun` to boxery-host, ssh_config, shared connections) and `core/ssh-config.mjs` (quoting and the ssh_config text). A profile `config` that only assigns the controller's settings (`HOST`, `HOST_BIN`, `HOST_PROFILE`, `IDENTITY`, `GRANT_CONFIRM`, as `setup` writes them) is parsed; any other config is sourced by bash (`set -eu`, with `$CONF_DIR` and the defaults set), and its exported environment reaches host commands. `test/ssh-config.test.mjs` holds the ssh_config text and quoting to the Bash controller's (`test/fixtures/bash-profile.sh`), word for word. Each profile's `ssh_config`: `*.boxery` → `ProxyCommand ssh HOST boxery-host connect %h %p`, ControlMaster, per-lease identities, per-VM `ForwardAgent` | | `host/boxery-host` + `host/*.mjs` | control plane | Backend-agnostic VM manager. Bash entry point; `connect` stays in Bash so the ProxyCommand never pays Node startup; everything else is Node. Ownership per module: [host-modules.md](docs/host-modules.md) | | `host/backends/*.sh` | control plane | Hypervisor effects only, one allowlisted function per process, arguments as argv ([contract](host/backends/README.md)). libvirt, Lima and exe.dev are stable; Cloud Hypervisor, boat.dev and OpenShell are experimental | | `proxy/boxery-proxy.mjs` | control plane | Credential proxy: checks the per-VM token, applies per-route method/path allowlists, body/concurrency/time limits, injects the real credential, refuses WebSocket upgrades (clients use SSE) | diff --git a/controller/all-hosts.mjs b/controller/all-hosts.mjs new file mode 100644 index 0000000..98bc228 --- /dev/null +++ b/controller/all-hosts.mjs @@ -0,0 +1,82 @@ +// Text-only, read-only listings. The CLI keeps explicit --host and JSON on their original paths. +import { withHost } from "../core/boxery-core.mjs"; +import { hostRun } from "../core/profile.mjs"; +import { leaseText } from "./leases.mjs"; +import { controllerVersion, skewNote } from "../core/versions.mjs"; +import { hostHeading, listedHosts } from "./ls.mjs"; +import { needHost, note, quit, say, select, usage } from "./lib.mjs"; +/** @import { Selected } from "./lib.mjs" */ + +/** Whether this invocation is a read-only host-wide listing (not a VM or a mutation). + * @param {string} command @param {string[]} args */ +export function isListing(command, args) { + if (args.includes("--json")) return false; + if (command === "pool") return args[0] === "ls"; + if (command === "runners") return !args.length || args[0] === "status"; + if (command === "upgrade-host") { + // A flag-looking ref/value is not an action selector. Never fan out a real upgrade. + for (let i = 0; i < args.length; i++) { + if (args[i] === "--ref" || args[i] === "--wait") i++; + else if (args[i] === "--check") return true; + } + return false; + } + return ["leases", "images", "version", "shapes", "capabilities", "backends"].includes(command); +} + +/** Print a multi-host listing, returning false to retain the original single-host path. + * @param {Selected} s @param {string} command @param {string[]} args */ +export async function allHostsListing(s, command, args) { + if (["leases", "version", "shapes"].includes(command) && args.length) usage(command); + const hosts = listedHosts(s); + if (hosts.length <= 1) return false; + const controller = controllerVersion(); + if (command === "version") say(`controller ${controller.version}${controller.describe ? ` (${controller.describe})` : ""}`); + const sections = await Promise.all(hosts.map(async (h) => { + let text = "", notes = "", error = null; + try { + const hs = h.name === s.host.name ? s : await select(h.name, h.dir); + needHost(hs); + await withHost(hs.host, async () => { + if (command === "leases") { + text = leaseText(); + return; + } + const hostCommand = command === "upgrade-host" ? "upgrade" : command; + text = await hostRun([hostCommand, ...(command === "version" ? ["--json"] : args)], { + host: hs.host, config: hs.config, + onData: (d, from) => { if (from === "stderr") notes += d.toString("utf8"); }, + }); + if (command === "version") { + const h = JSON.parse(text); + if (typeof h.version !== "string") throw new Error("invalid host version response"); + text = `host ${h.version}${h.describe ? ` (${h.describe})` : ""} ${h.install ?? "unknown"} install [${hs.host.name}]`; + const skew = skewNote(controller, h, hs.host.name); + if (skew) notes += `boxery: ${skew}\n`; + } + }); + } catch (e) { error = /** @type {Error} */ (e); } + return { name: h.name, heading: hostHeading(h, s), text, notes, error }; + })); + if (command === "images") { + // Keep the host's table columns and add provenance, with just one header. + const width = Math.max(4, ...sections.map((sec) => sec.name.length)); + const row = (/** @type {string} */ host, /** @type {string} */ text) => `${host.padEnd(width)} ${text}`; + const header = sections.filter((sec) => !sec.error).map((sec) => sec.text.split("\n")[0]).find((line) => /^IMAGE(?:\s|$)/.test(line)); + say(row("HOST", header ?? "IMAGE")); + for (const sec of sections) { + if (sec.error) { say(row(sec.name, "(images failed: see below)")); continue; } + const lines = sec.text.split("\n"); + if (/^IMAGE(?:\s|$)/.test(lines[0] ?? "")) lines.shift(); + for (const line of lines.filter(Boolean)) say(row(sec.name, line)); + } + } else { + say(sections.map((sec) => `${sec.heading}\n${sec.error ? `(${command} failed: see below)` : sec.text}`).join("\n\n")); + } + for (const sec of sections) { + if (sec.error) note(`boxery: ${sec.name}: ${sec.error.message.replace(/^boxery: /, "") || `${command} failed`}`); + else if (sec.notes.trim()) note(sec.notes.trim().split("\n").map((l) => l.replace(/^(==> )?/, `$1${sec.name}: `)).join("\n")); + } + if (sections.some((sec) => sec.error)) quit(1); + return true; +} diff --git a/controller/cli.mjs b/controller/cli.mjs index 2bc9de4..13200e7 100644 --- a/controller/cli.mjs +++ b/controller/cli.mjs @@ -319,7 +319,8 @@ async function cmdSsh(s, [name = "", ...rest]) { * selected; `registry` (a family action only) edits this machine's registry, though `host add DEST` contacts DEST. * - noHost: the refusal when --host is given to a command that has no host to select. * - hostOptional: with no --host and no default host, `local` runs instead of a handler needing a host. - * - allHosts: without --host, the handler lists every host (it is told: its third argument). + * - allHosts: without --host, read-only text listings span hosts (all-hosts.mjs; ls uses its third argument). + * JSON, VM-name commands and mutating actions retain their selected-host handlers. * - vmAtHost: the first word may be NAME@HOST, which selects HOST like --host. * - help: how -h/--help is told from payload. `legacy`: a leading flag, or one word then the flag (snap demo * --help). `leading`: only a leading flag; after that the words are the command's (run demo --help). `self`: @@ -491,7 +492,8 @@ export const COMMANDS = { }, }, shapes: { - help: { group: "more", summary: "VM sizes defined on the host (* = default)", usage: ["shapes [--json]"], flags: [JSON_FLAG], docs: "shapes.md" }, + contract: { allHosts: true }, + help: { group: "more", summary: "VM sizes on every host (* = default; --host NAME: one)", usage: ["shapes [--json]"], details: ["A section per host. --host NAME or --json selects one host."], flags: [JSON_FLAG], docs: "shapes.md" }, run: async (s, args) => { needHost(s); if (!(args.length === 0 || (args.length === 1 && args[0] === "--json"))) usage("shapes"); await hostPass(s, ["shapes", ...args]); }, }, @@ -524,7 +526,8 @@ export const COMMANDS = { }, }, images: { - help: { group: "legacy", summary: "every snapshot on the host (new NAME --from VM@SNAP uses one)", usage: ["images [--json]"], flags: [JSON_FLAG] }, + contract: { allHosts: true }, + help: { group: "legacy", summary: "snapshots on every host, with HOST column (--host NAME: one)", usage: ["images [--json]"], details: ["Snapshots usable by new NAME --from VM@SNAP, with a HOST column. --host NAME or --json selects one host, without the extra column."], flags: [JSON_FLAG] }, run: async (s, args) => hostPass(s, ["images", ...args]), }, @@ -740,7 +743,8 @@ export const COMMANDS = { run: async (s, args) => { needHost(s); await (await import("./leases.mjs")).leaseCommand(s, "release", args); }, }, leases: { - help: { group: "legacy", summary: "your leases", usage: ["leases [--json]"], flags: [JSON_FLAG], docs: "pool.md" }, + contract: { allHosts: true }, + help: { group: "legacy", summary: "your leases on every host (--host NAME: one)", usage: ["leases [--json]"], details: ["Locally held leases, a section per host; no host is contacted. --host NAME or --json selects one host."], flags: [JSON_FLAG], docs: "pool.md" }, run: async (s, args) => (await import("./leases.mjs")).leaseCommand(s, "leases", args), }, lease: { @@ -753,15 +757,17 @@ export const COMMANDS = { actions: { acquire: { command: "acquire" }, renew: { command: "renew" }, release: { command: "release" }, ls: { command: "leases" } }, }, pool: { - help: { group: "families", summary: "manage the shared pool of leasable VMs (admin)", usage: ["pool add NAME", "pool rm NAME [--force]", "pool ls [--json]"], list: "pool add|rm|ls", docs: "pool.md" }, + contract: { allHosts: true }, + help: { group: "families", summary: "manage the shared pool of leasable VMs (admin)", details: ["ls lists every host unless --host NAME or --json is given. add and rm stay on the selected host."], usage: ["pool add NAME", "pool rm NAME [--force]", "pool ls [--json]"], list: "pool add|rm|ls", docs: "pool.md" }, status: { vm: 1, when: (a) => a[0] === "add" }, // add captures the VM's clean snapshot (a restart on Lima); rm and ls are quick run: async (s, args) => { needHost(s); await lc(() => lifecycle.pool(args, passthrough())); }, }, runners: { + contract: { allHosts: true }, help: { group: "families", summary: "GitHub Actions runners on pool VMs", list: "runners once|status|...", usage: ["runners once [--repo OWNER/REPO | --org ORG] [--vms NAME,...] [--labels L,...] [--group ID]", "runners status [--json] | start | stop | token < FILE", "runners config [--repo OWNER/REPO | --org ORG] [--vms NAME,...] [--count N] [--labels L,...] ..."], - details: ["once: a local runner. One job on a fresh pool VM, registered with your gh login; nothing is stored on the host. --repo defaults to this directory's repo.", "status, start, stop, config, token: host runners (admin). The host keeps runners waiting, with its own GitHub token."], + details: ["once: a local runner. One job on a fresh pool VM, registered with your gh login; nothing is stored on the host. --repo defaults to this directory's repo.", "status, start, stop, config, token: host runners (admin). The host keeps runners waiting, with its own GitHub token. status lists every host unless --host NAME or --json is given; other actions stay on the selected host."], docs: "github-runners.md", }, // GitHub Actions runners on the host's pool (docs/github-runners.md): `once` (local runners) runs here with @@ -776,15 +782,16 @@ export const COMMANDS = { // ------------------------------------------------ host & diagnostics version: { - help: { group: "more", summary: "controller and host versions; warns when the host is behind", usage: ["version [--json]"], details: ["boxery --version and boxery -V are the same as boxery version."], flags: [JSON_FLAG], seeAlso: ["host upgrade"] }, + help: { group: "more", summary: "controller and every host's version; warns per host", usage: ["version [--json]"], details: ["boxery --version and boxery -V are the same as boxery version. --host NAME or --json selects one host; otherwise each host has a section after the controller."], flags: [JSON_FLAG], seeAlso: ["host upgrade"] }, run: async (s, args) => cmdVersion(s, args), local: (args) => cmdVersion(null, args), - contract: { hostOptional: true }, + contract: { hostOptional: true, allHosts: true }, }, "upgrade-host": { + contract: { allHosts: true }, help: { group: "legacy", summary: "update boxery on the host and restart its services", usage: ["upgrade-host [--check] [--ref REF] [--wait S] [--reinit]"], - details: ["Waits for in-flight VM operations and rolls back if checks fail."], + details: ["Waits for in-flight VM operations and rolls back if checks fail. --check lists every host unless --host NAME is given; real upgrades stay on the selected host."], flags: [["--check", "Only report the install, its target version and profiles"], ["--ref REF", "Upgrade to this git ref or npm version"], ["--wait S", "Wait up to S seconds for in-flight operations"], ["--reinit", "Re-run init for every profile even when up to date"]], docs: "install.md#upgrading", }, @@ -792,11 +799,13 @@ export const COMMANDS = { run: cmdUpgradeHost, }, backends: { - help: { group: "legacy", summary: "backend support, requirements and capabilities", usage: ["backends [--json]"], flags: [JSON_FLAG], docs: "backends.md" }, + contract: { allHosts: true }, + help: { group: "legacy", summary: "backend support and capabilities on every host", usage: ["backends [--json]"], details: ["Requirements and capability declarations, a section per host. --host NAME or --json selects one host."], flags: [JSON_FLAG], docs: "backends.md" }, run: async (s, args) => hostPass(s, ["backends", ...args]), }, capabilities: { - help: { group: "legacy", summary: "the selected host's platform and capabilities", usage: ["capabilities [--json | --check]"], flags: [JSON_FLAG, ["--check", "Run the backend preflight; fails when a requirement is missing"]], docs: "backends.md" }, + contract: { allHosts: true }, + help: { group: "legacy", summary: "every host's platform and capabilities (--host NAME: one)", usage: ["capabilities [--json | --check]"], details: ["A section per host, including --check. --host NAME or --json selects one host."], flags: [JSON_FLAG, ["--check", "Run the backend preflight; fails when a requirement is missing"]], docs: "backends.md" }, run: async (s, args) => hostPass(s, ["capabilities", ...args]), }, backend: { @@ -922,13 +931,20 @@ async function main(argv) { } } const entry = COMMANDS[cmd]; - // Plain `ls` lists every host; --host NAME ls just that one. + // All-host text listings retain the original path with --host or --json. const command = "run" in entry ? entry.run : undefined; if (!command) throw new CliError(unknownCommand(COMMANDS, word), 2); const s = await select(name, dir); await withHost(s.host, async () => { await refreshSshConfig({ host: s.host, warn: note }); - await reporting(cmd, "status" in entry ? entry.status : undefined, args, () => command(s, args, { allHosts: !!contract.allHosts && !explicit })); + await reporting(cmd, "status" in entry ? entry.status : undefined, args, async () => { + const allHosts = !!contract.allHosts && !explicit; + if (allHosts && cmd !== "ls") { + const listings = await import("./all-hosts.mjs"); + if (listings.isListing(cmd, args) && await listings.allHostsListing(s, cmd, args)) return; + } + return command(s, args, { allHosts }); + }); }); } diff --git a/controller/leases.mjs b/controller/leases.mjs index e66751b..7ef43b8 100644 --- a/controller/leases.mjs +++ b/controller/leases.mjs @@ -27,6 +27,12 @@ function parse(a, flags) { return out; } +/** Text listing of this profile's locally held leases. */ +export function leaseText() { + const now = Math.floor(Date.now() / 1000), all = localLeases(); + return all.map((r) => `${r.name.padEnd(16)} ${(r.expires > now ? `${r.expires - now}s` : "expired").padEnd(10)} ${r.id}`).join("\n") || "(no leases)"; +} + /** @param {Selected} _s @param {"acquire" | "renew" | "release" | "leases"} command @param {string[]} args */ export async function leaseCommand(_s, command, args) { const abort = new AbortController(); @@ -72,9 +78,7 @@ export async function leaseCommand(_s, command, args) { const rows = leaseRows().map((r) => JSON.stringify(r)); return say(rows.length ? `[\n${rows.join(",\n")}\n]` : "[]"); } - const now = Math.floor(Date.now() / 1000), all = localLeases(); - if (!all.length) return say("(no leases)"); - for (const r of all) say(`${r.name.padEnd(16)} ${(r.expires > now ? `${r.expires - now}s` : "expired").padEnd(10)} ${r.id}`); + return say(leaseText()); } } } diff --git a/controller/ls.mjs b/controller/ls.mjs index 74301dd..55a2345 100644 --- a/controller/ls.mjs +++ b/controller/ls.mjs @@ -46,9 +46,7 @@ export async function ls(s, args, how) { return; } const sections = await Promise.all(hosts.map(async (h) => { - const where = [h.backend, h.destination && (h.destination === "local" ? "on this machine" : `on ${h.destination}`)].filter(Boolean).join(" "); - const names = [h.name === s.host.name ? "default" : "", h.also.length ? `also ${h.also.map((o) => o.name).join(", ")}` : ""].filter(Boolean).join("; "); - const heading = `${h.name}${names ? ` (${names})` : ""}${where ? `: ${where}` : ""}`; + const heading = hostHeading(h, s); try { const hs = h.name === s.host.name ? s : await select(h.name, h.dir); if (!hs.config.host) die(`not configured; run: boxery setup user@host|local --name ${h.name}`); @@ -62,7 +60,7 @@ export async function ls(s, args, how) { /** The hosts to list, the default first; another name registered for a host already listed (same_as) is * the same host, listed once. Only the selected host when the registry can't be read. @param {Selected} s */ -function listedHosts(s) { +export function listedHosts(s) { let hosts; try { hosts = describeHosts(); } catch (e) { warn(`listing ${s.host.name} only: ${/** @type {Error} */ (e).message}`); return []; } /** @type {(typeof hosts[number] & { also: typeof hosts })[]} */ @@ -74,6 +72,14 @@ function listedHosts(s) { return shown; } +/** The shared section heading for read-only all-host listings. + * @param {ReturnType[number]} h @param {Selected} s */ +export function hostHeading(h, s) { + const where = [h.backend, h.destination && (h.destination === "local" ? "on this machine" : `on ${h.destination}`)].filter(Boolean).join(" "); + const names = [h.name === s.host.name ? "default" : "", h.also.length ? `also ${h.also.map((o) => o.name).join(", ")}` : ""].filter(Boolean).join("; "); + return `${h.name}${names ? ` (${names})` : ""}${where ? `: ${where}` : ""}`; +} + /** The grants other names for a section's host gave its VMs: each name keeps its own (in its profile * directory), and only one name is listed. @param {Section} sec @param {string} dir @param {import("../core/boxery-core.mjs").HostDescription[]} also */ function addGrantsOf(sec, dir, also) { diff --git a/docs/cli.md b/docs/cli.md index c22b678..02b4d30 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -31,7 +31,7 @@ The everyday commands stay top level: `new`, `ls`, `start`, `stop`, `rm`, `resiz | `runners` | GitHub Actions runners | `once`, `status`, … | - **The same commands.** A family action runs its older spelling's code: same arguments and flags, output, `--json` fields, exit statuses and signals, and the same host selection. Older spellings keep working, without a warning, so scripts need no change. Only usage errors differ: they show the spelling you typed. -- **`host` has two kinds of action.** `add`, `ls`, `show`, `use` and `rm` manage this machine's registry of hosts and refuse `--host`. `add NAME DEST` runs setup on its explicit destination; importing `--config-dir` and the other registry actions stay local. Maintenance actions (`build-base`, `upgrade`, `proxy-log`, `backend`, `backends`, `capabilities`) use the selected host, the default or `--host NAME`: `boxery --host lab host upgrade --check`. +- **`host` has two kinds of action.** `add`, `ls`, `show`, `use` and `rm` manage this machine's registry of hosts and refuse `--host`. `add NAME DEST` runs setup on its explicit destination; importing `--config-dir` and the other registry actions stay local. Mutating maintenance actions (`build-base`, `upgrade`) and `proxy-log`/`backend` use the selected host, the default or `--host NAME`. Read-only `upgrade --check`, `backends` and `capabilities` list every host unless scoped: `boxery --host lab host upgrade --check`. - **`access ls` only lists.** It takes `NAME [--json]` and nothing else, so `access ls demo apply` is a usage error, not a push. Pushing the grants again is `access apply`. Grant approval is unchanged ([Grants](#grants)). - **`snapshot images`** lists the snapshots `new NAME --from VM@SNAP` can start from; it is not another kind of saved state. `fork` copies a VM's current disk; `snapshot create` saves one to come back to. - **Mistakes.** An unknown action names the family's actions (`unknown snapshot action: restroe (did you mean restore?); actions: …`) and exits 2, before any host, profile or grant is read. @@ -50,16 +50,18 @@ boxery host show hornet boxery host use laptop boxery --host hornet ls boxery --host hornet lease acquire # pool lease on that host -boxery --host hornet host upgrade --check # maintenance acts on the selected host +boxery --host hornet host upgrade --check # --host scopes this read-only check boxery host rm hornet # forget only; preserves VMs and profile data ``` Without `--host`, `ls` lists every registered host's VMs under one header, a section each (the default host first, each headed by its name, backend and where it runs); names for the same host (`same_as` in `host ls --json`) are listed once, headed `(also NAME)`, with each name's grants. The hosts are asked at once; one that can't be reached shows `(ls failed: see below)`, its error follows the table on stderr, the others are still listed, and `ls` exits 1. `--host NAME ls` lists that host's alone, without a heading, and so does `ls` when only one host is registered. `ls --json` is always one host's VMs (the default's, or `--host NAME`'s). See [Named hosts](hosts.md) for isolation, imports, precedence and safe removal. `--host NAME` precedes the command and also scopes grants and lease keys. +The read-only commands `lease ls`, `pool ls`, `version`, `shapes`, `host capabilities`, `host backends`, `host upgrade --check` and `runners status` also list every host without `--host`, using the same sections, default-first ordering and same-host deduplication as `ls`. `snapshot images` instead adds a `HOST` column to its table. Older spellings (`leases`, `images`, `capabilities`, `backends`, `upgrade-host --check`) behave identically. With only one host, output stays unchanged. `--host NAME` and `--json` always mean one host (the selected default for JSON without `--host`). Unreachable hosts do not hide the others: their errors follow the output on stderr and the command exits 1 once. `lease ls` reads local lease records only and does not contact hosts. `version` prints the controller once, then each host's version, warning separately for each host that is behind. Real upgrades, mutating commands and commands taking a VM name remain on the selected host. + ### Backend discovery `boxery host backends [--json]` lists backend platform support, requirements and capabilities. -`boxery host capabilities [--json | --check]` assesses the selected **host**, not the controller. +`boxery host capabilities [--json | --check]` assesses each **host**, not the controller; `--host NAME` or `--json` selects one. Both are also available as the top-level `backends` and `capabilities`, and directly as `boxery-host` commands. Agents use `vm_info {action:"capabilities"}`. See the [metadata contract](backends.md) for supported versus tested configurations and conditional features. Setup checks @@ -101,7 +103,7 @@ boxery snapshot ls demo [--json] boxery snapshot restore demo before-refactor # VM keeps its name, address and token boxery new demo2 --from demo@before-refactor # a new VM from a snapshot boxery snapshot rm demo before-refactor -boxery snapshot images [--json] # every snapshot on the host (with AGE and GUEST, like ls) +boxery snapshot images [--json] # snapshots on every host (HOST, AGE and GUEST columns) ``` `snap`, `snaps`, `revert`, `snap-rm` and `images` are the older spellings of `snapshot create`, `ls`, `restore`, `rm` and `images`, and do the same. @@ -254,7 +256,7 @@ boxery host backend # the host's VM backend; recorded f boxery host upgrade [--check] [--ref REF] # update boxery on the host (see Install → Upgrading) ``` -These `host` actions act on the selected host (`--host NAME`, else the default); `proxy-log`, `backend` and `upgrade-host` are the older spellings. `shapes` and `pin` stay top level. +`proxy-log`, `backend` and real upgrades act on the selected host (`--host NAME`, else the default); `upgrade --check` lists every host unless scoped. `version` also lists every host unless `--host NAME` or `--json` is given; `proxy-log`, `backend` and `upgrade-host` are the older spellings. `shapes` and `pin` stay top level. ### Terminal status @@ -342,8 +344,8 @@ Generated from the help `boxery help --all` shows (`controller/cli.mjs`); edit i | `boxery host upgrade [--check] [--ref REF] [--wait S] [--reinit]` | Update boxery on the host and restart its services [→](install.md#upgrading) | | `boxery host proxy-log [N]` | Recent LLM and edge (http: grant) requests on the host | | `boxery host backend` | The host's VM backend (recorded for host ls) | -| `boxery host backends [--json]` | Backend support, requirements and capabilities [→](backends.md) | -| `boxery host capabilities [--json \| --check]` | The selected host's platform and capabilities [→](backends.md) | +| `boxery host backends [--json]` | Backend support and capabilities on every host [→](backends.md) | +| `boxery host capabilities [--json \| --check]` | Every host's platform and capabilities (--host NAME: one) [→](backends.md) | **boxery snapshot — saved VM disk states: create, restore, list, delete** @@ -353,7 +355,7 @@ Generated from the help `boxery help --all` shows (`controller/cli.mjs`); edit i | `boxery snapshot ls NAME [--json]` | List a VM's snapshots | | `boxery snapshot restore NAME SNAP` | Restore a VM to a snapshot (keeps its name, address and token) | | `boxery snapshot rm NAME SNAP` | Delete a snapshot | -| `boxery snapshot images [--json]` | Every snapshot on the host (new NAME --from VM@SNAP uses one) | +| `boxery snapshot images [--json]` | Snapshots on every host, with HOST column (--host NAME: one) | **boxery agent — persistent coding-agent sessions in a VM** @@ -388,15 +390,15 @@ Generated from the help `boxery help --all` shows (`controller/cli.mjs`); edit i | `boxery lease acquire [--ttl S] [--wait S] [--holder H]` | Lease a VM from the shared pool (prints NAME LEASE_ID) [→](pool.md) | | `boxery lease renew NAME [--ttl S]` | Extend your lease [→](pool.md) | | `boxery lease release NAME` | Give a leased VM back (it is reset to its clean snapshot) [→](pool.md) | -| `boxery lease ls [--json]` | Your leases [→](pool.md) | +| `boxery lease ls [--json]` | Your leases on every host (--host NAME: one) [→](pool.md) | **More** | Command | What it does | |---|---| | `boxery pin NAME [--from-guest]` | Re-pin a VM's ssh host key (VMs made before keys were pinned) [→](security.md#vm-host-keys) | -| `boxery shapes [--json]` | VM sizes defined on the host (* = default) [→](shapes.md) | -| `boxery version [--json]` | Controller and host versions; warns when the host is behind | +| `boxery shapes [--json]` | VM sizes on every host (* = default; --host NAME: one) [→](shapes.md) | +| `boxery version [--json]` | Controller and every host's version; warns per host | **Older spellings (still work; the same commands as the family actions)** @@ -407,7 +409,7 @@ Generated from the help `boxery help --all` shows (`controller/cli.mjs`); edit i | `boxery snaps NAME [--json]` | List a VM's snapshots (= snapshot ls) | | `boxery revert NAME SNAP` | Restore a VM to a snapshot (keeps its name, address and token) (= snapshot restore) | | `boxery snap-rm NAME SNAP` | Delete a snapshot (= snapshot rm) | -| `boxery images [--json]` | Every snapshot on the host (new NAME --from VM@SNAP uses one) (= snapshot images) | +| `boxery images [--json]` | Snapshots on every host, with HOST column (--host NAME: one) (= snapshot images) | | `boxery sessions NAME [--json]` | List a VM's tmux sessions (= agent ls) | | `boxery jobs NAME [--json]`
`boxery jobs NAME --prune [--older-than 7d] [--json]` | List background jobs (run --bg starts one) (= job ls) [→](#background-command-jobs) | | `boxery logs NAME JOB [-f] [--lines N] [--bytes N] [--strip-ansi]` | Show a job's output (the last 200 lines) (= job logs) [→](#background-command-jobs) | @@ -420,10 +422,10 @@ Generated from the help `boxery help --all` shows (`controller/cli.mjs`); edit i | `boxery acquire [--ttl S] [--wait S] [--holder H]` | Lease a VM from the shared pool (prints NAME LEASE_ID) (= lease acquire) [→](pool.md) | | `boxery renew NAME [--ttl S]` | Extend your lease (= lease renew) [→](pool.md) | | `boxery release NAME` | Give a leased VM back (it is reset to its clean snapshot) (= lease release) [→](pool.md) | -| `boxery leases [--json]` | Your leases (= lease ls) [→](pool.md) | +| `boxery leases [--json]` | Your leases on every host (--host NAME: one) (= lease ls) [→](pool.md) | | `boxery upgrade-host [--check] [--ref REF] [--wait S] [--reinit]` | Update boxery on the host and restart its services (= host upgrade) [→](install.md#upgrading) | -| `boxery backends [--json]` | Backend support, requirements and capabilities (= host backends) [→](backends.md) | -| `boxery capabilities [--json \| --check]` | The selected host's platform and capabilities (= host capabilities) [→](backends.md) | +| `boxery backends [--json]` | Backend support and capabilities on every host (= host backends) [→](backends.md) | +| `boxery capabilities [--json \| --check]` | Every host's platform and capabilities (--host NAME: one) (= host capabilities) [→](backends.md) | | `boxery backend` | The host's VM backend (recorded for host ls) (= host backend) | | `boxery proxy-log [N]` | Recent LLM and edge (http: grant) requests on the host (= host proxy-log) | diff --git a/test/cli-all-hosts.test.mjs b/test/cli-all-hosts.test.mjs new file mode 100644 index 0000000..f2e9e51 --- /dev/null +++ b/test/cli-all-hosts.test.mjs @@ -0,0 +1,139 @@ +// Real CLI, isolated registry and host stubs. No SSH or real host state. +import assert from "node:assert/strict"; +import { spawnSync } from "node:child_process"; +import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { after, beforeEach, test } from "node:test"; +import { registerHost } from "./fixtures/register-host.mjs"; +import { isListing } from "../controller/all-hosts.mjs"; + +const root = mkdtempSync(path.join(tmpdir(), "boxery-all-hosts-")); +const home = path.join(root, "registry"), calls = path.join(root, "calls"), hostbin = path.join(root, "host"); +const profile = (/** @type {string} */ name) => path.join(root, name); +writeFileSync(hostbin, `#!/usr/bin/env node +import { appendFileSync } from 'node:fs'; +const args = process.argv.slice(2), name = process.env.STUB_NAME; +appendFileSync(${JSON.stringify(calls)}, JSON.stringify({name, args}) + '\\n'); +if (process.env.FAIL_HOST === name) { console.error('unreachable fixture host'); process.exit(255); } +if (args[0] === 'help') { console.log('known-hosts NAME'); process.exit(); } +if (args[0] === 'version') console.log(JSON.stringify({version:'0.1.0',describe:null,install:'npm'})); +else if (args.includes('--json')) console.log(JSON.stringify({name, args})); +else if (args[0] === 'images') console.log('IMAGE CREATED SIZE AGE GUEST\\n' + name + '@s1 2026-01-01 1GiB 1d current'); +else { console.log(name + ': ' + args.join(' ')); console.error('==> fixture note'); } +`); +chmodSync(hostbin, 0o755); +for (const name of ["alpha", "beta", "gamma"]) { + registerHost(home, name, profile(name)); + writeFileSync(path.join(profile(name), "config"), `HOST=local\nHOST_BIN='${hostbin}'\nexport STUB_NAME=${name}\n`); + writeFileSync(path.join(profile(name), "backend"), "fake\n"); +} +// Same-directory alias must not cause a second call or a second section. +registerHost(home, "beta-alias", profile("beta")); +const env = { ...process.env, HOME: path.join(root, "home"), BOXERY_HOME: home, NO_COLOR: "1" }; +/** @param {string[]} args @param {NodeJS.ProcessEnv} [extra] */ +function run(args, extra = {}) { + return spawnSync(path.resolve(import.meta.dirname, "../controller/boxery"), args, { env: { ...env, ...extra }, encoding: "utf8", input: "", timeout: 20_000 }); +} +const hostCalls = () => readFileSync(calls, "utf8").trim().split("\n").filter(Boolean).map((l) => JSON.parse(l)).filter((c) => c.args[0] !== "help"); +after(() => rmSync(root, { recursive: true, force: true })); +beforeEach(() => { writeFileSync(calls, ""); writeFileSync(path.join(home, "default-host"), "beta\n"); }); + +const LISTINGS = [["lease", "ls"], ["leases"], ["pool", "ls"], ["version"], ["shapes"], ["host", "capabilities"], ["capabilities"], ["host", "backends"], ["backends"], ["host", "upgrade", "--check"], ["upgrade-host", "--check"], ["runners", "status"], ["runners"]]; +test("read-only text listings share ls headings, default-first order and alias deduplication", () => { + for (const args of LISTINGS) { + writeFileSync(calls, ""); + const r = run(args); + assert.equal(r.status, 0, `${args}: ${r.stderr}`); + assert.match(r.stdout, /beta \(default; also beta-alias\): fake on this machine/); + assert.match(r.stdout, /alpha: fake on this machine/); + assert.match(r.stdout, /gamma: fake on this machine/); + assert.ok(r.stdout.indexOf("beta (") < r.stdout.indexOf("alpha:")); + if (args[0] !== "lease" && args[0] !== "leases") { + assert.deepEqual(hostCalls().map((c) => c.name).sort(), ["alpha", "beta", "gamma"]); + } + if (args[0] === "version") { + assert.match(r.stdout, /^controller /); + assert.equal((r.stdout.match(/host 0.1.0/g) ?? []).length, 3); + assert.equal((r.stderr.match(/is older than this controller/g) ?? []).length, 3); + } + } +}); + +test("snapshot images and images have one HOST table header, not host sections", () => { + for (const args of [["snapshot", "images"], ["images"]]) { + const r = run(args); + assert.equal(r.status, 0, r.stderr); + assert.match(r.stdout, /^HOST\s+IMAGE\s+CREATED/); + assert.equal((r.stdout.match(/IMAGE/g) ?? []).length, 1); + for (const name of ["alpha", "beta", "gamma"]) assert.match(r.stdout, new RegExp(`^${name}\\s+${name}@s1`, "m")); + assert.doesNotMatch(r.stdout, /default|also beta-alias/); + } +}); + +test("unreachable hosts do not hide other hosts, and produce one final failure", () => { + for (const args of [...LISTINGS.filter((a) => !["lease", "leases"].includes(a[0])), ["snapshot", "images"]]) { + const r = run(args, { FAIL_HOST: "beta" }); + assert.equal(r.status, 1, `${args}: ${r.stderr}`); + assert.match(r.stdout, /alpha/); + assert.match(r.stdout, /gamma/); + assert.match(r.stdout, /failed: see below/); + if (args[0] === "snapshot") assert.match(r.stdout, /^HOST\s+IMAGE/); + assert.equal((r.stderr.match(/unreachable fixture host/g) ?? []).length, 1); + assert.match(r.stderr, /boxery: beta:/); + } +}); + +test("--host preserves single-host output; JSON always selects one host", () => { + for (const args of [...LISTINGS, ["snapshot", "images"]]) { + writeFileSync(calls, ""); + const r = run(["--host", "alpha", ...args]); + assert.equal(r.status, 0, `${args}: ${r.stderr}`); + assert.doesNotMatch(r.stdout, /default|on this machine|HOST\s+IMAGE/); + assert.ok(hostCalls().every((c) => c.name === "alpha")); + if (args.includes("--check") || (args[0] === "runners" && args.length === 1)) continue; + writeFileSync(calls, ""); + const json = run([...args, "--json"]); + assert.equal(json.status, 0, `${args}: ${json.stderr}`); + JSON.parse(json.stdout); + assert.ok(hostCalls().every((c) => c.name === "beta")); + } +}); + +test("one registered host keeps the original output without headings or HOST column", () => { + const registry = path.join(home, "host-registry"); + const saved = ["alpha", "gamma", "beta-alias"].map((name) => [name, readFileSync(path.join(registry, name), "utf8")]); + try { + for (const [name] of saved) rmSync(path.join(registry, name)); + for (const args of [...LISTINGS, ["images"]]) { + const r = run(args); + assert.equal(r.status, 0, r.stderr); + assert.doesNotMatch(r.stdout, /default|on this machine|HOST\s+IMAGE/); + } + } finally { for (const [name, value] of saved) writeFileSync(path.join(registry, name), value); } +}); + +test("leases remain profile-local and are listed without contacting any host", () => { + for (const name of ["alpha", "gamma"]) { + const dir = path.join(profile(name), "leases"); mkdirSync(dir, { recursive: true }); + const id = `l-${(name === "alpha" ? "a" : "c").repeat(32)}`; + writeFileSync(path.join(dir, `${id}.lease`), `name=pool-${name}\nid=${id}\nexpires=9999999999\n`); + } + const r = run(["lease", "ls"], { FAIL_HOST: "alpha" }); + assert.equal(r.status, 0, r.stderr); + assert.match(r.stdout, /pool-alpha/); + assert.match(r.stdout, /pool-gamma/); + assert.equal(hostCalls().length, 0); +}); + +test("mutations and VM-name commands never opt into the listing path", () => { + for (const [command, args] of /** @type {[string, string[]][]} */ ([["upgrade-host", []], ["upgrade-host", ["--ref", "master"]], ["upgrade-host", ["--ref", "--check"]], ["upgrade-host", ["--wait", "--check"]], ["pool", ["add", "demo"]], ["pool", ["rm", "demo"]], ["runners", ["start"]], ["runners", ["stop"]], ["runners", ["once"]], ["snaps", ["demo"]], ["renew", ["demo"]], ["capabilities", ["--json"]]])) assert.equal(isListing(command, args), false); + assert.equal(isListing("upgrade-host", ["--ref", "master", "--check"]), true); + for (const args of [["host", "upgrade"], ["pool", "add", "demo"], ["pool", "rm", "demo"], ["runners", "start"]]) { + writeFileSync(calls, ""); + const r = run(args); + assert.equal(r.status, 0, r.stderr); + assert.ok(hostCalls().length > 0); + assert.ok(hostCalls().every((c) => c.name === "beta")); + } +}); diff --git a/test/cli-contracts.test.mjs b/test/cli-contracts.test.mjs index bba0388..7a48545 100644 --- a/test/cli-contracts.test.mjs +++ b/test/cli-contracts.test.mjs @@ -49,6 +49,16 @@ test("every command has exactly one way to run, and a contract that says only wh assert.deepEqual(contractOf("list"), contractOf("ls"), "an alias has its command's contract"); }); +test("only host-wide listings opt into all-host dispatch, inherited by family actions", () => { + assert.deepEqual(commands.filter(([, , c]) => c.allHosts).map(([name]) => name).sort(), + ["ls", "leases", "pool", "images", "version", "shapes", "capabilities", "backends", "upgrade-host", "runners"].sort()); + for (const [family, action] of [["lease", "ls"], ["snapshot", "images"], ["host", "capabilities"], ["host", "backends"], ["host", "upgrade"]]) { + const entry = COMMANDS[family]; + assert.ok("actions" in entry && entry.actions); + assert.equal(actionContract(entry.actions[action]).allHosts, true, `${family} ${action}`); + } +}); + test("every family action runs a host command, or declares itself a registry action with its refusal", () => { for (const [f, a, x, c] of actions) { const label = `${f} ${a}`; diff --git a/test/cli-families.test.mjs b/test/cli-families.test.mjs index b2d386f..52e0e14 100644 --- a/test/cli-families.test.mjs +++ b/test/cli-families.test.mjs @@ -126,7 +126,7 @@ test("every family action does what its older spelling does: output, status, ssh rmSync(sshLog, { force: true }); rmSync(path.join(root, "host.calls"), { force: true }); const r = run(args, extra); // (a usage error names the command as it was typed: the families' own spelling is checked below) - return clockless({ r: { ...r, stderr: r.stderr.replace(/^boxery: usage: [\s\S]*$/, "boxery: usage: …") }, ssh: sshCalls(), host: calls().filter((c) => !c.endsWith(": help")), state: state() }); + return clockless({ r: { ...r, stderr: r.stderr.replace(/^boxery: usage: [\s\S]*$/, "boxery: usage: …") }, ssh: sshCalls(), host: calls().filter((c) => !c.endsWith(": help")).sort(), state: state() }); }; const a = observe(family), b = observe(older); assert.equal(a, b, `boxery ${family.join(" ")} differs from boxery ${older.join(" ")}`); @@ -211,11 +211,9 @@ test("malformed actions say what the family has, before any host, ssh or saved s assert.deepEqual(state(), before); }); -test("host: registry actions need no host and refuse --host; maintenance actions run on the selected host", () => { - // maintenance: the default host, or --host NAME's: never the other +test("host: registry refuses --host; read-only checks list hosts; explicit maintenance stays selected", () => { assert.equal(run(["host", "upgrade", "--check"]).status, 0); - assert.deepEqual(calls().map((c) => c.split(": ")[0]), [profile("alpha"), profile("alpha")]); - assert.deepEqual(calls().map((c) => c.split(": ")[1]), ["version --json", "upgrade --check"]); + assert.deepEqual(calls().sort(), [`${profile("alpha")}: upgrade --check`, `${profile("beta")}: upgrade --check`]); rmSync(path.join(root, "host.calls")); assert.equal(run(["--host", "beta", "host", "upgrade", "--check"]).status, 0); assert.deepEqual(calls().map((c) => c.split(": ")[0]), [profile("beta"), profile("beta")]); diff --git a/test/fixtures/boxery-help-all.txt b/test/fixtures/boxery-help-all.txt index 54cc52b..82a5568 100644 --- a/test/fixtures/boxery-help-all.txt +++ b/test/fixtures/boxery-help-all.txt @@ -47,15 +47,15 @@ boxery host — named hosts, and maintenance of the selected host: host upgrade Update boxery on the host and restart its services host proxy-log [N] Recent LLM and edge (http: grant) requests on the host host backend The host's VM backend (recorded for host ls) - host backends Backend support, requirements and capabilities - host capabilities The selected host's platform and capabilities + host backends Backend support and capabilities on every host + host capabilities Every host's platform and capabilities (--host NAME: one) boxery snapshot — saved VM disk states: create, restore, list, delete: snapshot create NAME [SNAP] Snapshot a VM's disk (Lima restarts a running VM) snapshot ls NAME List a VM's snapshots snapshot restore NAME SNAP Restore a VM to a snapshot (keeps its name, address and token) snapshot rm NAME SNAP Delete a snapshot - snapshot images Every snapshot on the host (new NAME --from VM@SNAP uses one) + snapshot images Snapshots on every host, with HOST column (--host NAME: one) boxery agent — persistent coding-agent sessions in a VM: agent attach NAME [AGENT] Attach to an agent in a persistent tmux session @@ -78,12 +78,12 @@ boxery lease — borrow a VM from the shared pool: lease acquire Lease a VM from the shared pool (prints NAME LEASE_ID) lease renew NAME Extend your lease lease release NAME Give a leased VM back (it is reset to its clean snapshot) - lease ls Your leases + lease ls Your leases on every host (--host NAME: one) More: pin NAME Re-pin a VM's ssh host key (VMs made before keys were pinned) - shapes VM sizes defined on the host (* = default) - version Controller and host versions; warns when the host is behind + shapes VM sizes on every host (* = default; --host NAME: one) + version Controller and every host's version; warns per host Older spellings (still work; the same commands as the family actions): build-base Build the host's desktop base image (one time, ~3 min) (= host build-base) @@ -91,7 +91,7 @@ Older spellings (still work; the same commands as the family actions): snaps NAME List a VM's snapshots (= snapshot ls) revert NAME SNAP Restore a VM to a snapshot (keeps its name, address and token) (= snapshot restore) snap-rm NAME SNAP Delete a snapshot (= snapshot rm) - images Every snapshot on the host (new NAME --from VM@SNAP uses one) (= snapshot images) + images Snapshots on every host, with HOST column (--host NAME: one) (= snapshot images) sessions NAME List a VM's tmux sessions (= agent ls) jobs NAME List background jobs (run --bg starts one) (= job ls) logs NAME JOB Show a job's output (the last 200 lines) (= job logs) @@ -104,10 +104,10 @@ Older spellings (still work; the same commands as the family actions): acquire Lease a VM from the shared pool (prints NAME LEASE_ID) (= lease acquire) renew NAME Extend your lease (= lease renew) release NAME Give a leased VM back (it is reset to its clean snapshot) (= lease release) - leases Your leases (= lease ls) + leases Your leases on every host (--host NAME: one) (= lease ls) upgrade-host Update boxery on the host and restart its services (= host upgrade) - backends Backend support, requirements and capabilities (= host backends) - capabilities The selected host's platform and capabilities (= host capabilities) + backends Backend support and capabilities on every host (= host backends) + capabilities Every host's platform and capabilities (--host NAME: one) (= host capabilities) backend The host's VM backend (recorded for host ls) (= host backend) proxy-log [N] Recent LLM and edge (http: grant) requests on the host (= host proxy-log) diff --git a/test/fixtures/boxery-help.txt b/test/fixtures/boxery-help.txt index f3091a1..8ffb4f4 100644 --- a/test/fixtures/boxery-help.txt +++ b/test/fixtures/boxery-help.txt @@ -39,8 +39,8 @@ Command families (boxery FAMILY --help): More: pin NAME Re-pin a VM's ssh host key (VMs made before keys were pinned) - shapes VM sizes defined on the host (* = default) - version Controller and host versions; warns when the host is behind + shapes VM sizes on every host (* = default; --host NAME: one) + version Controller and every host's version; warns per host Options: --host NAME Run COMMAND on a host other than the default (boxery host use) diff --git a/test/help-drift.test.mjs b/test/help-drift.test.mjs index 967f8f4..d9e42fd 100644 --- a/test/help-drift.test.mjs +++ b/test/help-drift.test.mjs @@ -227,6 +227,18 @@ test("seeAlso names commands; docs links point at real headings", () => { } }); +test("all-host listing help explains how to retain one-host output", () => { + for (const name of ["leases", "images", "version", "shapes", "capabilities", "backends", "pool", "runners"]) { + const e = COMMANDS[name]; + assert.ok("help" in e); + const details = (e.help.details ?? []).join(" "); + assert.match(details, /--host NAME/, name); + assert.match(details, /--json/, name); + } + assert.ok("help" in COMMANDS["upgrade-host"]); + assert.match(COMMANDS["upgrade-host"].help.details?.join(" ") ?? "", /--check lists every host/); +}); + test("summaries are one short line", () => { for (const [name, h] of everyHelp) { assert.ok(h.summary.length <= 66, `${name}: summary over 66 characters; put the rest in details`); From 83b075fa227d0aea8308ed48900b38f1e1d7eee9 Mon Sep 17 00:00:00 2001 From: Ben Vinegar <2153+benvinegar@users.noreply.github.com> Date: Mon, 9 Nov 2026 11:16:08 -0500 Subject: [PATCH 2/2] fix(cli): group upgrade-host --check output under each host --- controller/all-hosts.mjs | 5 +++++ docs/cli.md | 2 +- test/cli-all-hosts.test.mjs | 14 ++++++++++++++ 3 files changed, 20 insertions(+), 1 deletion(-) diff --git a/controller/all-hosts.mjs b/controller/all-hosts.mjs index 98bc228..a985625 100644 --- a/controller/all-hosts.mjs +++ b/controller/all-hosts.mjs @@ -47,6 +47,11 @@ export async function allHostsListing(s, command, args) { host: hs.host, config: hs.config, onData: (d, from) => { if (from === "stderr") notes += d.toString("utf8"); }, }); + if (command === "upgrade-host") { + // Only --check reaches this listing path; its report is written to stderr. + text = notes.trim(); + notes = ""; + } if (command === "version") { const h = JSON.parse(text); if (typeof h.version !== "string") throw new Error("invalid host version response"); diff --git a/docs/cli.md b/docs/cli.md index 02b4d30..03e901a 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -56,7 +56,7 @@ boxery host rm hornet # forget only; preserves VMs and pro Without `--host`, `ls` lists every registered host's VMs under one header, a section each (the default host first, each headed by its name, backend and where it runs); names for the same host (`same_as` in `host ls --json`) are listed once, headed `(also NAME)`, with each name's grants. The hosts are asked at once; one that can't be reached shows `(ls failed: see below)`, its error follows the table on stderr, the others are still listed, and `ls` exits 1. `--host NAME ls` lists that host's alone, without a heading, and so does `ls` when only one host is registered. `ls --json` is always one host's VMs (the default's, or `--host NAME`'s). See [Named hosts](hosts.md) for isolation, imports, precedence and safe removal. `--host NAME` precedes the command and also scopes grants and lease keys. -The read-only commands `lease ls`, `pool ls`, `version`, `shapes`, `host capabilities`, `host backends`, `host upgrade --check` and `runners status` also list every host without `--host`, using the same sections, default-first ordering and same-host deduplication as `ls`. `snapshot images` instead adds a `HOST` column to its table. Older spellings (`leases`, `images`, `capabilities`, `backends`, `upgrade-host --check`) behave identically. With only one host, output stays unchanged. `--host NAME` and `--json` always mean one host (the selected default for JSON without `--host`). Unreachable hosts do not hide the others: their errors follow the output on stderr and the command exits 1 once. `lease ls` reads local lease records only and does not contact hosts. `version` prints the controller once, then each host's version, warning separately for each host that is behind. Real upgrades, mutating commands and commands taking a VM name remain on the selected host. +The read-only commands `lease ls`, `pool ls`, `version`, `shapes`, `host capabilities`, `host backends`, `host upgrade --check` and `runners status` also list every host without `--host`, using the same sections, default-first ordering and same-host deduplication as `ls`. `snapshot images` instead adds a `HOST` column to its table. Older spellings (`leases`, `images`, `capabilities`, `backends`, `upgrade-host --check`) behave identically. With only one host, output stays unchanged. `--host NAME` and `--json` always mean one host (the selected default for JSON without `--host`). Unreachable hosts do not hide the others: their errors follow the output on stderr and the command exits 1 once. `lease ls` reads local lease records only and does not contact hosts. `host upgrade --check` prints each host's report under its heading, without host-name prefixes. `version` prints the controller once, then each host's version, warning separately for each host that is behind. Real upgrades, mutating commands and commands taking a VM name remain on the selected host. ### Backend discovery diff --git a/test/cli-all-hosts.test.mjs b/test/cli-all-hosts.test.mjs index f2e9e51..5c5bdba 100644 --- a/test/cli-all-hosts.test.mjs +++ b/test/cli-all-hosts.test.mjs @@ -19,6 +19,7 @@ if (process.env.FAIL_HOST === name) { console.error('unreachable fixture host'); if (args[0] === 'help') { console.log('known-hosts NAME'); process.exit(); } if (args[0] === 'version') console.log(JSON.stringify({version:'0.1.0',describe:null,install:'npm'})); else if (args.includes('--json')) console.log(JSON.stringify({name, args})); +else if (args[0] === 'upgrade' && args.includes('--check')) console.error('==> fetching origin\\n==> up to date at v0.12.0\\n==> profiles: ' + name); else if (args[0] === 'images') console.log('IMAGE CREATED SIZE AGE GUEST\\n' + name + '@s1 2026-01-01 1GiB 1d current'); else { console.log(name + ': ' + args.join(' ')); console.error('==> fixture note'); } `); @@ -60,6 +61,19 @@ test("read-only text listings share ls headings, default-first order and alias d } }); +test("upgrade checks group stderr-only reports under each host without prefixes", () => { + for (const args of [["upgrade-host", "--check"], ["host", "upgrade", "--check"]]) { + const r = run(args); + assert.equal(r.status, 0, r.stderr); + assert.doesNotMatch(r.stderr, /==>|fetching origin|up to date|profiles:/); + assert.equal(r.stdout, [ + "beta (default; also beta-alias): fake on this machine", + "alpha: fake on this machine", + "gamma: fake on this machine", + ].map((heading, i) => `${heading}\n==> fetching origin\n==> up to date at v0.12.0\n==> profiles: ${["beta", "alpha", "gamma"][i]}`).join("\n\n") + "\n"); + } +}); + test("snapshot images and images have one HOST table header, not host sections", () => { for (const args of [["snapshot", "images"], ["images"]]) { const r = run(args);