diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 96df545..8bd7207 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -47,6 +47,8 @@ Types: the code is plain JavaScript typed with JSDoc comments (`/** @param {stri `boxery help`, `boxery help --all` and `boxery COMMAND [ACTION] --help` are rendered (`help/index.mjs`, through `controller/usage.mjs`) from the `help` each command carries in `controller/cli.mjs`'s `COMMANDS` table, next to its handler: a new command needs its help to exist at all. boxery-host's help is the same kind of table, in `host/help.mjs` (its handlers are in `host/cli.mjs`, which refuses to load with a command that has no help). Write the summary as one short line; longer explanations go in `details`, `flags` and `examples`, which only its own `--help` shows. `test/help-drift.test.mjs` keeps it honest: a command's help must list exactly the `--flags` its code compares against (flags the host parses are checked against `boxery-host help`), examples must use real commands and documented flags, the same holds for every `boxery-host` command, `docs` anchors must exist, the command reference in `docs/cli.md` must be current (`npm run docs:cli` regenerates it), and `boxery help` and `boxery help --all` are pinned in `test/fixtures/boxery-help.txt` and `boxery-help-all.txt` (`BOXERY_UPDATE_GOLDEN=1 node --test test/help-drift.test.mjs` rewrites it after you review the change). +Controller-owned follow-up commands use `hint(COMMAND, ARGS, {host})` from `controller/lib.mjs`: it validates the canonical command/family action against `COMMANDS`, shell-quotes arguments and retains the explicit host. Name the action explicitly (`access ls` or `access apply`, not the ambiguous legacy `grants`); keep placeholders outside argument arrays. Do not rewrite subprocess output or import controller helpers into core/MCP/pi. Shared approval messages and `BOXERY_CLI` remain compatible. + `test/cli-contracts.test.mjs` checks contracts and their inheritance, scope routing, help boundaries, optional hosts and SSH-qualified targets against an unconfigured temporary home. `test/cli-families.test.mjs` runs the real CLI against a stub `boxery-host` and a stub `ssh` in temporary profiles, and checks that every family action and its older spelling produce the same output, exit status, ssh and host calls and saved state; that help and mistakes touch no host, profile or grant; that `host`'s registry actions refuse `--host` while its maintenance actions follow it; that `access ls` is read-only; and that grant approval, grant stores and leases stay per profile. Add a pair there when you add an action. diff --git a/controller/cli.mjs b/controller/cli.mjs index a9dabfb..46683e0 100644 --- a/controller/cli.mjs +++ b/controller/cli.mjs @@ -12,7 +12,7 @@ import { refreshSshConfig } from "../core/profile.mjs"; import { literal, literalArgs, remotePath } from "../core/ssh-config.mjs"; import { controllerVersion, hostVersion, skewNote, upgradeHint } from "../core/versions.mjs"; import { backendCommand, hostCommand, setupNamed } from "./hosts.mjs"; -import { BOXERY, CliError, USAGE, VALID_SNAP, VALID_VM, commandLine, die, invokedAs, usage, hasRawBytes, hostFailed, hostPass, inherit, needHost, needVm, note, rawTail, say, select, vmSsh, vmSshCapture, warn } from "./lib.mjs"; +import { CliError, USAGE, VALID_SNAP, VALID_VM, commandLine, die, invokedAs, usage, hasRawBytes, hint, hostFailed, hostPass, inherit, needHost, needVm, note, rawTail, say, select, vmSsh, vmSshCapture, warn } from "./lib.mjs"; import { reporting } from "./status.mjs"; import { actionHelp, registerCommands, renderCommand, renderFamily, renderTop, resolve, routedThrough, unknownAction, unknownCommand } from "./usage.mjs"; /** @import { Selected } from "./lib.mjs" */ @@ -104,19 +104,19 @@ async function cmdRun(s, args) { /** @type {Buffer} */ let cwdRaw = Buffer.alloc(0); for (; i < args.length; i++) { - if (args[i] === "--cwd") { if (!args[i + 1]) runUsage(); cwd = args[++i]; cwdRaw = raw[i]; } + if (args[i] === "--cwd") { if (!args[i + 1]) runUsage(name); cwd = args[++i]; cwdRaw = raw[i]; } else if (args[i] === "--bg") bg = true; else if (args[i] === "--") { i++; break; } else break; } const argv = args.slice(i), argvRaw = raw.slice(i); - if (!argv.length) runUsage(); + if (!argv.length) runUsage(name); if (bg) { await (await grants()).reapplyQuiet(s, name); const { startJob } = await import("./jobs.mjs"); const id = await startJob(s, name, argvRaw, cwd ? cwdRaw : null); say(id); - note(`boxery: started ${id} on ${name} logs: ${BOXERY} logs ${name} ${id} -f wait: ${BOXERY} wait ${name} ${id}`); + note(`boxery: started ${id} on ${name} logs: ${hint("job logs", [name, id, "-f"])} wait: ${hint("job wait", [name, id])}`); literalNote(name, argv); return; } @@ -128,7 +128,7 @@ async function cmdRun(s, args) { if (hasRawBytes([...argvRaw, cwdRaw])) line = `eval "$(printf %s ${rawLine(argvRaw, cwd ? cwdRaw : null).toString("base64")} | base64 -d)"`; const rc = await vmSsh(s, [`${name}.boxery`, line]); // The usual mistake is a whole command line in one argument; say how to run it instead. - if (rc === 127 && /\s/.test(argv[0])) warn(`hint: run takes the command and its arguments separately; for a shell line use: ${BOXERY} run ${name} bash -c ${literal(argv[0])}`); + if (rc === 127 && /\s/.test(argv[0])) warn(`hint: run takes the command and its arguments separately; for a shell line use: ${hint("run", [name, "bash", "-c", argv[0]])}`); literalNote(name, argv); if (rc) throw new CliError("", rc); } @@ -146,8 +146,8 @@ export function runsInBackground(args) { return false; } -/** @returns {never} */ -const runUsage = () => usage("run", { hint: "a shell line: ... bash -c 'A | B'; see: boxery run --help" }); +/** @param {string} name @returns {never} */ +const runUsage = (name) => usage("run", { hint: `a shell line: ${hint("run", [name, "bash", "-c", "A | B"])}; see: ${hint("help", ["run"])}` }); /** run's remote command line as bytes, for arguments that aren't UTF-8: the same line, built from bytes. * @param {Buffer[]} argv @param {Buffer | null} cwd */ @@ -168,7 +168,7 @@ function rawLine(argv, cwd) { function literalNote(name, argv) { if (["bash", "sh", "dash", "zsh", "awk", "gawk", "mawk", "perl", "jq", "sed", "python", "python3", "node", "ruby"].includes(path.basename(argv[0]))) return; const a = argv.find((x) => x === "~" || x.startsWith("~/") || /\$[A-Z]/.test(x) || x.includes("${")); - if (a !== undefined) warn(`note: ${literal(a)} was passed literally (run does not expand ~ or $VAR); to expand it in the VM: ${BOXERY} run ${name} bash -c '…'`); + if (a !== undefined) warn(`note: ${literal(a)} was passed literally (run does not expand ~ or $VAR); to expand it in the VM: ${hint("run", [name, "bash", "-c", "…"])}`); } /** attach NAME [pi|opencode|shell] [session] @param {Selected} s @param {string[]} args @returns {Promise} */ @@ -178,7 +178,7 @@ async function cmdAttach(s, [name = "", tool = "pi", sess = tool]) { if (!Object.hasOwn(run, tool)) die(`unknown agent: ${tool} (pi, opencode or shell)`, 2); if (!/^[A-Za-z0-9._-]+$/.test(sess)) die(`invalid session name: ${sess}`); // (Without one, tmux says only "open terminal failed: not a terminal".) - if (contractOf("attach").terminal === "stdin" && !process.stdin.isTTY) die(`attach needs a terminal; for headless work use ${BOXERY} prompt ${name} "TASK" or ${BOXERY} run --bg ${name} CMD`); + if (contractOf("attach").terminal === "stdin" && !process.stdin.isTTY) die(`attach needs a terminal; for headless work use ${hint("prompt", [name])} "TASK" or ${hint("run", ["--bg", name])} CMD`); await (await grants()).reapplyQuiet(s, name); // tmux keeps the agent alive when you disconnect (laptop sleep, network change). const rc = await vmSsh(s, ["-t", `${name}.boxery`, `cd ~/project 2>/dev/null; tmux has-session -t '${sess}' 2>/dev/null || tmux new-session -d -s '${sess}' -c ~/project "bash -lc '${run[tool]}; exec bash -l'"; exec tmux attach -t '${sess}'`]); @@ -238,7 +238,7 @@ async function cmdPrompt(s, [name = "", ...words]) { printf '%s\\n' '#!/bin/bash -l' 'cd ~/project' 'pi -p "$(cat .boxery/${id}.prompt)" &1 | tee .boxery/${id}.log' 'echo "[boxery] task finished (exit \${PIPESTATUS[0]})" | tee -a .boxery/${id}.log' 'exec bash -l' > $d/${id}.sh chmod +x $d/${id}.sh; tmux new-session -d -s ${id} -c ~/project $d/${id}.sh`; await exitWith(vmSsh(s, [`${name}.boxery`, script])); - say(`started ${id} on ${name} — watch: ${BOXERY} attach ${name} pi ${id} log: ${BOXERY} run ${name} cat .boxery/${id}.log`); + say(`started ${id} on ${name} — watch: ${hint("attach", [name, "pi", id])} log: ${hint("run", [name, "cat", `.boxery/${id}.log`])}`); } /** A VM has no LLM access until it is granted, and pi without it fails at once: say so before starting a @@ -251,7 +251,7 @@ async function needPiGrant(s, name) { if (r.code) throw new CliError("", r.code); // (ssh said why) const [settings, projectSettings, models] = r.stdout.split("\x1e").slice(-3); const spec = (await import("../core/grants.mjs")).missingPiGrant(name, { settings, projectSettings, models }); - if (spec) die(`pi in ${name} needs ${spec}, which ${name} has not been granted; grant it first: ${BOXERY} grant ${name} ${spec}`); + if (spec) die(`pi in ${name} needs ${spec}, which ${name} has not been granted; grant it first: ${hint("access grant", [name, spec])}`); } /** cp FROM TO: vm_copy's own code. Needs only the profile's ssh_config, not the host. @param {Selected} s @param {string[]} args @returns {Promise} */ @@ -343,7 +343,7 @@ export const COMMANDS = { details: ["OpenShell has its own options (gateway, image, policy, providers): boxery setup local --backend openshell --help."], flags: [["--name NAME", "Register the host as NAME (default: local, or the host part of user@host)"], ["--key K.pub", "The ssh public key VMs trust (default: ~/.ssh/id_ed25519.pub, id_ecdsa.pub or id_rsa.pub; else the key your registered hosts use; else another ~/.ssh/id_*.pub)"], ["--host-bin PATH", "boxery-host on the host, when it isn't on its PATH"], ["--profile P", "Use (or create, with --backend) profile P on the host"], ["--backend B", "The backend for a new profile (boxery host backends lists them)"]], examples: [["A Linux box you reach over ssh", "boxery setup you@my-host"], ["This machine", "boxery setup local"]], - seeAlso: ["host", "build-base", "backends"], docs: "install.md", + seeAlso: ["host", "host build-base", "host backends"], docs: "install.md", }, }, host: { @@ -398,7 +398,7 @@ export const COMMANDS = { new: { help: { group: "vms", summary: "create a VM", usage: ["new NAME [--shape S] [--cpus N --mem MiB --disk GiB] [--headless [--layers L,...]] [--grant SPEC]... [--agent-forward]", "new NAME --from VM@SNAP"], - flags: [...SIZE_FLAGS, ["--headless", "No desktop (shell and agents only); needs no build-base"], ["--layers L,...", "Extra image layers for a headless VM (github-runner)"], ["--from VM@SNAP", "Start from a snapshot (boxery snapshot images lists them)"], ["--grant SPEC", "Grant access at creation (asks first; see boxery grant)"], ["--agent-forward", "Same as --grant ssh-agent"]], + flags: [...SIZE_FLAGS, ["--headless", "No desktop (shell and agents only); needs no build-base"], ["--layers L,...", "Extra image layers for a headless VM (github-runner)"], ["--from VM@SNAP", "Start from a snapshot (boxery snapshot images lists them)"], ["--grant SPEC", "Grant access at creation (asks first; see boxery access grant)"], ["--agent-forward", "Same as --grant ssh-agent"]], examples: [["A desktop VM", "boxery new demo"], ["A larger, headless one", "boxery new ci-1 --headless --shape large"], ["A GitHub Actions runner VM", "boxery new runner-1 --headless --layers github-runner"]], seeAlso: ["shapes", "fork", "rm"], docs: "cli.md#lifecycle", }, @@ -445,7 +445,7 @@ export const COMMANDS = { group: "vms", summary: "copy a VM (running or not) into new VMs, ~10 s", usage: ["fork SRC DST... [--grants] [--shape S] [--cpus N --mem MiB --disk GiB]"], details: ["Each fork has SRC's disk (not its processes) with its own hostname, LLM token, ssh keys and network identity, and SRC's size unless --shape or size flags say otherwise.", CAPTURE_NOTE], flags: [["--grants", "Give the forks SRC's grants too (asks for each)"], ...SIZE_FLAGS], - examples: [["Two copies to try two approaches", "boxery fork demo try-a try-b"]], seeAlso: ["snap", "new"], docs: "cli.md#snapshots-and-forks", + examples: [["Two copies to try two approaches", "boxery fork demo try-a try-b"]], seeAlso: ["snapshot create", "new"], docs: "cli.md#snapshots-and-forks", }, status: { vm: true }, run: async (s, args) => { needHost(s); await cmdFork(s, args); }, @@ -480,7 +480,7 @@ export const COMMANDS = { // ------------------------------------------------ snapshots snap: { - help: { group: "legacy", summary: "snapshot a VM's disk (Lima restarts a running VM)", usage: ["snap NAME [SNAP]"], details: [CAPTURE_NOTE], seeAlso: ["snaps", "revert", "snap-rm"], docs: "cli.md#snapshots-and-forks" }, + help: { group: "legacy", summary: "snapshot a VM's disk (Lima restarts a running VM)", usage: ["snap NAME [SNAP]"], details: [CAPTURE_NOTE], seeAlso: ["snapshot ls", "snapshot restore", "snapshot rm"], docs: "cli.md#snapshots-and-forks" }, status: { vm: true }, run: async (s, args) => { needHost(s); @@ -538,7 +538,7 @@ export const COMMANDS = { details: [RUN_RULES, "The exit code is the command's. A relative --cwd is under ~/project; ~/ expands in the VM; absolute paths are used as is."], flags: [["--bg", "Run as a background job; prints the job id (see boxery job ls)"], ["--cwd DIR", "Working directory"], ["--", "End run's options"]], examples: [["Args are passed as-is: quotes, $, *, ; stay literal", "boxery run demo pnpm test"], ["In ~/project/modem", "boxery run demo --cwd modem git log -1"], ["Pipes, ~, $VAR and globs need bash -c", "boxery run demo bash -c 'ls ~ | wc -l; echo $HOME'"], ["Not this: one argument is one command name (fails with a hint)", "boxery run demo 'make test'"]], - seeAlso: ["jobs", "ssh"], docs: "cli.md#shell-and-in-vm-agents", + seeAlso: ["job ls", "ssh"], docs: "cli.md#shell-and-in-vm-agents", }, status: { vm: true, when: (a) => !runsInBackground(a) }, // --bg returns at once run: async (s, args) => { needHost(s); await cmdRun(s, args); }, @@ -565,7 +565,7 @@ export const COMMANDS = { attach: { help: { group: "use", summary: "attach to an agent in a persistent tmux session", list: "attach NAME [AGENT]", usage: ["attach NAME [pi|opencode|shell] [SESSION]"], - details: ["The session keeps running when you detach (Ctrl-b d) or disconnect. It needs a terminal; for headless work use prompt or run --bg."], seeAlso: ["sessions", "prompt"], + details: ["The session keeps running when you detach (Ctrl-b d) or disconnect. It needs a terminal; for headless work use prompt or run --bg."], seeAlso: ["agent ls", "prompt"], }, run: async (s, args) => { needHost(s); await cmdAttach(s, args); }, contract: { terminal: "stdin", payload: "agent" }, @@ -596,7 +596,7 @@ export const COMMANDS = { group: "legacy", summary: "list background jobs (run --bg starts one)", usage: ["jobs NAME [--json]", "jobs NAME --prune [--older-than 7d] [--json]"], details: ["States: running, exited, or lost (it stopped without recording an exit code). exited+ means it left processes running."], flags: [JSON_FLAG, ["--prune", "Delete finished jobs and their logs"], ["--older-than D", "With --prune: only jobs older than D (e.g. 7d)"]], - seeAlso: ["run", "logs", "wait", "kill"], docs: "cli.md#background-command-jobs", + seeAlso: ["run", "job logs", "job wait", "job kill"], docs: "cli.md#background-command-jobs", }, run: async (s, args) => { needHost(s); await (await import("./jobs.mjs")).jobs(s, args); }, }, @@ -643,7 +643,7 @@ export const COMMANDS = { details: ["SPEC is one of:\n llm:chatgpt|openai|anthropic|ollama LLM access (VMs have none without it)\n github [--readonly] GitHub over HTTPS; the token stays here\n http:HOST --cmd CMD [--auth bearer|basic:USER|header:NAME] [--readonly]\n an HTTP API; the secret never enters the VM\n ssh-agent forward your ssh agent\n env:VAR [--cmd CMD] push an environment variable\n file:LOCAL[=REMOTE] push a file", "Adding access prompts on your terminal and defaults to No."], flags: [["--cmd CMD", "env: and http: grants: the command on this machine that prints the secret"], ["--auth A", "http: grants: bearer (default), basic:USER or header:NAME"], ["--readonly", "http: and github grants: GET/HEAD and git fetch only"]], examples: [["Let the VM use your Anthropic subscription", "boxery grant demo llm:anthropic"], ["Read-only GitHub", "boxery grant demo github --readonly"]], - seeAlso: ["revoke", "grants"], docs: "grants.md", + seeAlso: ["access revoke", "access ls", "access apply"], docs: "grants.md", }, run: async (s, args) => { needHost(s); await (await grants()).grant(s, args); }, contract: { terminal: "approval" }, @@ -695,7 +695,7 @@ export const COMMANDS = { help: { group: "legacy", summary: "lease a VM from the shared pool (prints NAME LEASE_ID)", usage: ["acquire [--ttl S] [--wait S] [--holder H]"], flags: [["--ttl S", "Lease length in seconds (default 1800)"], ["--wait S", "Wait up to S seconds for a free VM"], ["--holder H", "Who holds the lease, as the host shows it (default: user@machine)"]], - seeAlso: ["renew", "release", "leases"], docs: "pool.md", + seeAlso: ["lease renew", "lease release", "lease ls"], docs: "pool.md", }, status: { when: (a) => a.some((w, i) => w === "--wait" && Number(a[i + 1]) > 0) }, // only waiting for a free VM takes a while run: async (s, args) => { needHost(s); await (await import("./leases.mjs")).leaseCommand(s, "acquire", args); }, @@ -745,7 +745,7 @@ 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: ["upgrade-host"] }, + 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"] }, run: async (s, args) => cmdVersion(s, args), local: (args) => cmdVersion(null, args), contract: { hostOptional: true }, diff --git a/controller/grants.mjs b/controller/grants.mjs index 679a64d..83ebb9a 100644 --- a/controller/grants.mjs +++ b/controller/grants.mjs @@ -6,9 +6,9 @@ import { closeSync, openSync, readFileSync, readSync, writeSync } from "node:fs" import path from "node:path"; import { formatGrants, hostBackend, vmGrants } from "../core/boxery-core.mjs"; import { parseGrantArgs } from "../core/grant-approval.mjs"; -import { addGrants, applyGrants, grantCommand, grantPrompt, listGrants, revokeGrants, storedSpecs } from "../core/grants.mjs"; +import { addGrants, applyGrants, grantArgs, grantPrompt, listGrants, revokeGrants, storedSpecs } from "../core/grants.mjs"; import { reapplyPushed } from "../core/grant-operations.mjs"; -import { CliError, VALID_VM, die, needHost, needVm, note, say, usage, warn } from "./lib.mjs"; +import { CliError, VALID_VM, die, hint, needHost, needVm, note, say, usage, warn } from "./lib.mjs"; import { blockedOnPerson } from "./status.mjs"; /** @import { GrantSpec } from "../core/boxery-core.mjs" */ /** @import { Selected } from "./lib.mjs" */ @@ -42,7 +42,7 @@ function ask(s, vm, specs) { if (unattended(s)) return; let tty; try { tty = openSync("/dev/tty", "r+"); } - catch { die(`grants need a person. Ask the user to run the command below, or use vm_grant:\n${specs.map((g) => grantCommand("grant", vm, s.host.name, g)).join("\n")}`); } + catch { die(`grants need a person. Ask the user to run the command below, or use vm_grant:\n${specs.map((g) => hint("access grant", grantArgs("grant", vm, g), { host: s.host.name })).join("\n")}`); } let answer = ""; // Blocked on the person: the terminal's status says so, and Ctrl-C ends the command here (controller/status.mjs). blockedOnPerson("permission", () => { diff --git a/controller/hosts.mjs b/controller/hosts.mjs index 7046a04..556d6bb 100644 --- a/controller/hosts.mjs +++ b/controller/hosts.mjs @@ -4,7 +4,7 @@ import { describeHosts, profileFromDirectory, registeredHosts, resolveHost } from "../core/boxery-core.mjs"; import { profileConfig } from "../core/profile.mjs"; import { RegistryError, VALID_ALIAS, addHostLocked, checkedDefault, destination, isRegistered, needAlias, recordBackend, removeHostLocked, setDefault, setup, withRegistryLock } from "../core/registry.mjs"; -import { BOXERY, CliError, USAGE, die, note, say, usage } from "./lib.mjs"; +import { CliError, USAGE, die, hint, note, say, usage } from "./lib.mjs"; /** @import { HostProfile } from "../core/boxery-core.mjs" */ /** @import { RegistryIO } from "../core/registry.mjs" */ @@ -78,7 +78,7 @@ export async function setupNamed(args) { export async function backendCommand(host, args) { if (args.length) usage("backend"); const b = await recordBackend(host); - if (!b) die(`could not read the host's backend (does it predate 'boxery-host backend'? see: ${BOXERY} version)`); + if (!b) die(`could not read the host's backend (does it predate 'boxery-host backend'? see: ${hint("version")})`); say(b); } diff --git a/controller/jobs.mjs b/controller/jobs.mjs index 884ad33..3c1bb42 100644 --- a/controller/jobs.mjs +++ b/controller/jobs.mjs @@ -7,7 +7,7 @@ import path from "node:path"; import { fileURLToPath } from "node:url"; import { JOBS_NODE, VALID_JOB } from "../core/boxery-core.mjs"; import { closeMaster } from "../core/profile.mjs"; -import { CliError, die, duration, needVm, note, num, quit, say, usage, vmSsh, vmSshCapture, WAIT_LOST, WAIT_TIMEOUT, warn } from "./lib.mjs"; +import { CliError, die, duration, hint, needVm, note, num, quit, say, usage, vmSsh, vmSshCapture, WAIT_LOST, WAIT_TIMEOUT, warn } from "./lib.mjs"; /** @import { Selected } from "./lib.mjs" */ @@ -34,7 +34,7 @@ const jobsVmCapture = (s, name, args, o) => vmSshCapture(s, helper(name, args), const exit = (rc) => { if (rc) throw new CliError("", rc); }; /** @param {string | undefined} id */ -const needJob = (id) => (VALID_JOB.test(id ?? "") ? /** @type {string} */ (id) : die(`invalid job id: ${id ?? ""} (see: boxery jobs NAME)`)); +const needJob = (id) => (VALID_JOB.test(id ?? "") ? /** @type {string} */ (id) : die(`invalid job id: ${id ?? ""} (see: ${hint("job ls")} NAME)`)); /** run --bg: start ARGV (each word's bytes) in the VM as a job, in CWD (bytes, or null: ~/project); its id. * @param {Selected} s @param {string} name @param {Buffer[]} argv @param {Buffer | null} cwd */ @@ -108,7 +108,7 @@ export async function waitJob(s, [vm, job, ...rest]) { // waiting doesn't affect the job (tmux in the VM): reconnect and keep waiting, within --timeout. if (!reached) die(`cannot reach ${name}`); if (deadline != null && Date.now() / 1000 >= deadline) { warn(`cannot reach ${name}; --timeout passed (the job may still be running)`); quit(WAIT_TIMEOUT); } - if (++drops > 60) die(`cannot reach ${name}; giving up (the job may still be running: boxery jobs ${name})`); + if (++drops > 60) die(`cannot reach ${name}; giving up (the job may still be running: ${hint("job ls", [name])})`); warn(`lost the connection to ${name}; reconnecting (the job keeps running)`); await closeMaster(name); await new Promise((res) => setTimeout(res, 5000)); diff --git a/controller/leases.mjs b/controller/leases.mjs index 8a5fdd9..e66751b 100644 --- a/controller/leases.mjs +++ b/controller/leases.mjs @@ -3,7 +3,7 @@ import { execFileSync } from "node:child_process"; import { constants } from "node:os"; import { acquireLease, leaseRows, localLeases, releaseLease, renewLease } from "../core/leases.mjs"; -import { BOXERY, USAGE, die, hostFailed, note, quit, say, usage } from "./lib.mjs"; +import { USAGE, die, hint, hostFailed, note, quit, say, usage } from "./lib.mjs"; /** @import { Selected } from "./lib.mjs" */ /** Like `date`: the local format people read elsewhere in the CLI. @param {number} t unix seconds */ @@ -46,7 +46,7 @@ export async function leaseCommand(_s, command, args) { try { r = await acquireLease({ ttl: o.ttl ?? 1800, wait: o.wait ?? 0, ...(o.holder !== undefined ? { holder: o.holder } : {}) }, cli); } catch (e) { if (interrupted && /** @type {Error} */ (e).name === "AbortError") quit(interrupted); hostFailed(e); } finally { for (const [sig, h] of handlers) process.off(sig, h); } - note(`==> leased ${r.name} (lease ${r.id}, expires in ${r.expires - Math.floor(Date.now() / 1000)}s; renew with: ${BOXERY} renew ${r.name})`); + note(`==> leased ${r.name} (lease ${r.id}, expires in ${r.expires - Math.floor(Date.now() / 1000)}s; renew with: ${hint("lease renew", [r.name])})`); return say(`${r.name} ${r.id}`); } case "renew": { diff --git a/controller/lib.mjs b/controller/lib.mjs index d316422..8e5d340 100644 --- a/controller/lib.mjs +++ b/controller/lib.mjs @@ -1,6 +1,6 @@ // Shared plumbing for the controller CLI's commands (controller/cli.mjs): errors and exit codes, argument // checks, the selected host profile, and processes that share this terminal (ssh, boxery-host). -import { usageText } from "./usage.mjs"; +import { commandRef, usageText } from "./usage.mjs"; import { spawn } from "node:child_process"; import { constants } from "node:os"; import { profileFromDirectory, vmProblem, withHost } from "../core/boxery-core.mjs"; @@ -28,11 +28,16 @@ export const quit = (exitCode) => { throw new CliError("", exitCode); }; * get (core/ssh-config.mjs remoteCommand; host/util.mjs hint). (Plain ls asks every host with `boxery`: * its host output is --json, with no hints.) */ export let BOXERY = "boxery"; +let hintHost = ""; /** @param {string} explicitHost the NAME of --host NAME, or "" */ export function invokedAs(explicitHost) { + hintHost = explicitHost; BOXERY = explicitHost ? `boxery --host ${explicitHost}` : "boxery"; process.env.BOXERY_CLI = BOXERY; } +/** A canonical hint using the caller's explicit host, or a specific host for grouped output and grant requests. + * @param {string} command @param {string[]} [args] @param {{host?: string}} [options] */ +export const hint = (command, args = [], { host = hintHost } = {}) => commandRef(command, args, host ? ["--host", host] : []); /** @param {string} message */ export const warn = (message) => { process.stderr.write(`boxery: ${message}\n`); }; /** A line on stdout. @param {string} text */ diff --git a/controller/ls.mjs b/controller/ls.mjs index 6a64b87..74301dd 100644 --- a/controller/ls.mjs +++ b/controller/ls.mjs @@ -6,7 +6,7 @@ import { realpathSync } from "node:fs"; import { describeHosts, listGrants, withHost } from "../core/boxery-core.mjs"; import * as lifecycle from "../core/lifecycle.mjs"; -import { BOXERY, die, hostFailed, needHost, note, quit, say, select, usage, warn } from "./lib.mjs"; +import { die, hint, hostFailed, needHost, note, quit, say, select, usage, warn } from "./lib.mjs"; /** @import { Selected } from "./lib.mjs" */ /** A row of listVms, as docs/cli.md describes `ls --json`. @@ -119,7 +119,7 @@ function print(sections, { onlyRunning, refresh, grouped }) { const unchecked = sec.vms.filter((v) => running(v) && v.guest?.checked_at == null).map((v) => v.name); if (unchecked.length && !refresh) notes.push(`==> ${who}guest software not checked yet: ${unchecked.join(", ")} (ls --refresh reads it)`); const outdated = sec.vms.filter((v) => v.guest?.status === "outdated").map((v) => v.name); - if (outdated.length) notes.push(`==> ${who}outdated guest software on ${outdated.join(", ")}; update with: ${grouped ? `boxery --host ${sec.name}` : BOXERY} patch NAME|--all`); + if (outdated.length) notes.push(`==> ${who}outdated guest software on ${outdated.join(", ")}; update with: ${hint("patch", [], grouped ? { host: sec.name } : {})} NAME (or ${hint("patch", ["--all"], grouped ? { host: sec.name } : {})})`); } say(out.join("\n") || none); if (notes.length) note(notes.join("\n")); diff --git a/controller/usage.mjs b/controller/usage.mjs index 32770f9..51d772a 100644 --- a/controller/usage.mjs +++ b/controller/usage.mjs @@ -53,6 +53,10 @@ export const unknownCommand = (table, word) => help.unknownCommand(CLI, table, w /** The command table (cli.mjs registers it as it loads), for usage errors raised in the modules it calls. @type {Record} */ let TABLE = {}; +/** A copyable canonical command, checked against the same table used for dispatch and help. + * @param {string} command @param {string[]} [args] @param {string[]} [prefix] */ +export const commandRef = (command, args = [], prefix = []) => help.commandRef(CLI, TABLE, command, args, prefix); + /** A family's usage lines are its actions' (and its `list` the action names): filled in here, so the two can't differ. @param {Record} table */ export function registerCommands(table) { TABLE = table; diff --git a/core/grants.mjs b/core/grants.mjs index b90568d..13b8204 100644 --- a/core/grants.mjs +++ b/core/grants.mjs @@ -126,9 +126,15 @@ export function missingPiGrant(vm, { settings = "", projectSettings = "", models return `llm:${route}`; } -/** @param {"grant" | "revoke"} verb @param {string} vm @param {string} host @param {GrantSpec} g */ -export function grantCommand(verb, vm, host, g) { +/** Grant arguments shared by front-ends that choose their own command spelling. + * @param {"grant" | "revoke"} verb @param {string} vm @param {GrantSpec} g */ +export function grantArgs(verb, vm, g) { const spec = verb === "revoke" && g.kind === "file" ? `file:${g.local}` : g.spec; - return ["boxery", "--host", host, verb, vm, spec, ...(verb === "grant" ? [...(g.readonly ? ["--readonly"] : []), ...(g.cmd ? ["--cmd", g.cmd] : []), ...(g.auth ? ["--auth", g.auth] : [])] : [])].map(quoteWord).join(" "); + return [vm, spec, ...(verb === "grant" ? [...(g.readonly ? ["--readonly"] : []), ...(g.cmd ? ["--cmd", g.cmd] : []), ...(g.auth ? ["--auth", g.auth] : [])] : [])]; +} +/** Shared approval messages retain their existing command format. + * @param {"grant" | "revoke"} verb @param {string} vm @param {string} host @param {GrantSpec} g */ +export function grantCommand(verb, vm, host, g) { + return ["boxery", "--host", host, verb, ...grantArgs(verb, vm, g)].map(quoteWord).join(" "); } diff --git a/docs/cli.md b/docs/cli.md index b8dc974..a3eed09 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -430,7 +430,9 @@ Generated from the help `boxery help --all` shows (`controller/cli.mjs`); edit i `boxery-host help` lists every command; `boxery-host COMMAND --help` shows one. Generated from the same help (`host/help.mjs`); edit it there, then `npm run docs:cli`. `--profile NAME` before any command runs it in a second profile on this host (`~/.config/boxery-NAME`: its own backend, state, proxy port and services); `--profile NAME init --backend B` creates it with a free proxy port. `upgrade` keeps the code and each profile's state from before in `$BOXERY_CONF/pre-upgrade/` after a success too. -Commands in messages name what you typed. The follow-up commands `boxery` prints (`run --bg`'s logs and wait, `prompt`, `acquire`, `ls`) keep your `--host NAME`; and when `boxery` runs a host command for you, it passes `BOXERY_CLI` (`boxery`, or `boxery --host NAME` if you gave one), so a host error suggests `boxery --host lab snap-rm demo s1` rather than `boxery-host snap-rm demo s1`. Commands only boxery-host has (`init`, …) keep its name. Called directly, boxery-host names itself. +Controller-generated follow-up hints use the canonical command families (`job logs`, `job wait`, `lease renew`, `access grant`) and shell-quote dynamic arguments so they can be copied safely. They keep an explicit `--host NAME`; grant approval requests name the host even when it was the default, so another controller cannot accidentally grant on a different host. Everyday `run`, `ssh`, `attach` and `prompt` stay short. Shared approval prompts and core/host messages may still name working legacy aliases. + +When `boxery` runs a host command, it passes the unchanged `BOXERY_CLI` prefix (`boxery`, or `boxery --host NAME` if you gave one), so a host error suggests `boxery --host lab snap-rm demo s1` rather than `boxery-host snap-rm demo s1`. Commands only boxery-host has (`init`, …) keep its name. Called directly, boxery-host names itself. diff --git a/help/index.mjs b/help/index.mjs index a65ab45..7829d98 100644 --- a/help/index.mjs +++ b/help/index.mjs @@ -212,6 +212,22 @@ export function resolve(table, name) { return e.alias ? (Object.hasOwn(table, e.alias) ? e.alias : null) : name; } +/** One shell word, safe to copy literally, including empty strings and embedded quotes. @param {string} value */ +export const shellWord = (value) => /^[\w@%+=:,./-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`; + +/** A validated command reference, not a rewrite of output. Callers choose the action explicitly: grants serves + * both access ls and access apply. PREFIX is argv (e.g. --host NAME), never an executable shell fragment. + * @param {Cli} cli @param {Record} table @param {string} command + * @param {string[]} [args] @param {string[]} [prefix] */ +export function commandRef(cli, table, command, args = [], prefix = []) { + const words = command.split(" "), name = resolve(table, words[0]); + if (!name || words.length > 2 || words.some((w) => !w)) throw new Error(`unknown command reference: ${command}`); + const e = table[name]; + if (words.length === 2 && (!e.actions || !Object.hasOwn(e.actions, words[1]))) throw new Error(`unknown command reference: ${command}`); + if (cli.hidden?.includes(e.help?.group ?? "")) throw new Error(`use a canonical family action instead of ${command}`); + return [cli.program, ...prefix, name, ...words.slice(1), ...args].map(shellWord).join(" "); +} + /** The name nearest WORD, when one is close. @param {string} word @param {string[]} names */ function nearest(word, names) { return names.map((n) => /** @type {const} */ ([n, distance(word, n)])).filter(([n, d]) => d <= Math.max(1, Math.floor(n.length / 3)) || (word.length >= 3 && n.startsWith(word))).sort((a, b) => a[1] - b[1] || a[0].localeCompare(b[0]))[0]; diff --git a/test/cli-hints.test.mjs b/test/cli-hints.test.mjs new file mode 100644 index 0000000..6f94bdd --- /dev/null +++ b/test/cli-hints.test.mjs @@ -0,0 +1,89 @@ +// Copyable controller hints; no real HOME, profile, credential, SSH destination or VM. +import assert from "node:assert/strict"; +import { execFileSync, spawnSync } from "node:child_process"; +import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { after, test } from "node:test"; +import { hostTransport } from "./fixtures/host-transport.mjs"; +import { registerHost } from "./fixtures/register-host.mjs"; +import { commandRef, shellWord } from "../help/index.mjs"; + +const root = mkdtempSync(path.join(tmpdir(), "boxery-hints-")); +const home = path.join(root, "registry"), bin = path.join(root, "bin"); +const profile = (/** @type {string} */ name) => path.join(root, name); +process.env.BOXERY_HOME = home; +const { COMMANDS } = await import("../controller/cli.mjs"); +const { CLI } = await import("../controller/usage.mjs"); +const { hint, invokedAs } = await import("../controller/lib.mjs"); +const cli = path.resolve(import.meta.dirname, "../controller/boxery"); +const id = "job-20261109-000001-abcdef"; +mkdirSync(bin); +for (const name of ["alpha", "beta"]) registerHost(home, name, profile(name)); +hostTransport(root, [profile("alpha"), profile("beta")]); +writeFileSync(path.join(home, "default-host"), "alpha\n"); +writeFileSync(path.join(bin, "ssh"), `#!/usr/bin/env node +console.log(${JSON.stringify(id)}); +`); +writeFileSync(path.join(bin, "boxery"), "#!/usr/bin/env node\nconsole.log(JSON.stringify(process.argv.slice(2)));\n"); +for (const file of ["ssh", "boxery"]) chmodSync(path.join(bin, file), 0o755); +const env = { ...process.env, HOME: path.join(root, "home"), BOXERY_HOME: home, PATH: `${bin}:${process.env.PATH}`, SSH_AUTH_SOCK: "", BOXERY_STATUS: "0", NO_COLOR: "1" }; +/** @param {string[]} args */ +const run = (args) => { + const options = { env, encoding: /** @type {const} */ ("utf8"), input: "", timeout: 10_000, cwd: root, detached: true }; + return spawnSync(cli, args, options); +}; +after(() => { invokedAs(""); rmSync(root, { recursive: true, force: true }); }); + +/** A hint through a shell with a capture-only boxery executable, never a real host command. @param {string} line */ +const words = (line) => JSON.parse(execFileSync("/bin/sh", ["-c", line], { env, cwd: root, encoding: "utf8", timeout: 10_000 })); + +test("shell words round-trip empty strings, quotes, Unicode and metacharacters without execution", () => { + const values = ["", "a b", "it's", "$HOME", "$(touch SHOULD_NOT_EXIST)", "; touch SHOULD_NOT_EXIST", "line1\nline2", "@", "--help", "é"]; + const out = execFileSync("/bin/sh", ["-c", `printf '%s\\0' ${values.map(shellWord).join(" ")}`], { env, cwd: root, timeout: 10_000 }); + assert.deepEqual(out.toString().split("\0").slice(0, -1), values); + assert.equal(existsSync(path.join(root, "SHOULD_NOT_EXIST")), false); +}); + +test("references validate command paths, prefer canonical spellings, and quote every dynamic word", () => { + const args = ["demo", id, "-f", "", "a b", "'quoted'", "$HOME; false"]; + const line = commandRef(CLI, COMMANDS, "job logs", args, ["--host", "beta"]); + assert.deepEqual(words(line), ["--host", "beta", "job", "logs", ...args]); + assert.equal(commandRef(CLI, COMMANDS, "list"), "boxery ls"); + for (const ref of ["", "missing", "constructor", "job nope", "host __proto__", "job logs extra", "job logs", "run --bg"]) assert.throws(() => commandRef(CLI, COMMANDS, ref), /unknown command reference/); + for (const ref of ["jobs", "grants", "agent-forward"]) assert.throws(() => commandRef(CLI, COMMANDS, ref), /canonical family action/); +}); + +test("hint context is read at call time and supports a specific host without mutating the context", () => { + invokedAs("alpha"); + assert.equal(hint("job wait", ["demo", id]), `boxery --host alpha job wait demo ${id}`); + assert.equal(hint("lease renew", ["pool1"], { host: "beta" }), "boxery --host beta lease renew pool1"); + assert.equal(hint("version"), "boxery --host alpha version"); + invokedAs(""); + assert.equal(hint("version"), "boxery version"); +}); + +test("background-job hints use canonical actions and retain an explicit host, not the default", () => { + for (const prefix of [[], ["--host", "beta"]]) { + const r = run([...prefix, "run", "--bg", "demo", "true"]); + assert.equal(r.status, 0, r.stderr); + assert.equal(r.stdout, `${id}\n`); + const expected = ["boxery", ...prefix].join(" "); + assert.match(r.stderr, new RegExp(`logs: ${expected} job logs demo ${id} -f`)); + assert.match(r.stderr, new RegExp(`wait: ${expected} job wait demo ${id}`)); + } + assert.equal(readFileSync(path.join(home, "default-host"), "utf8"), "alpha\n"); +}); + +test("headless grant guidance is canonical, host-pinned and safely copyable; approval still refuses", () => { + const command = "printf '%s' 'a b;$HOME'"; + for (const prefix of [[], ["--host", "beta"]]) { + const r = run([...prefix, "access", "grant", "demo", "env:API_TOKEN", "--cmd", command]); + assert.equal(r.status, 1, r.stderr); + assert.match(r.stderr, /grants need a person/); + const line = r.stderr.split("\n").find((l) => l.startsWith("boxery --host ")); + assert.ok(line, r.stderr); + assert.deepEqual(words(line), ["--host", prefix.length ? "beta" : "alpha", "access", "grant", "demo", "env:API_TOKEN", "--cmd", command]); + assert.equal(existsSync(path.join(profile(prefix.length ? "beta" : "alpha"), "grants/demo")), false); + } +}); diff --git a/test/grants.test.mjs b/test/grants.test.mjs index 310cdc7..a2ea522 100644 --- a/test/grants.test.mjs +++ b/test/grants.test.mjs @@ -55,7 +55,7 @@ test("CLI without a controlling TTY refuses, including y on stdin and inherited for (const input of ["", "y\n", "yes\nyes\n"]) { const r = await headless(["grant", "demo", "ssh-agent"], input, { GRANT_CONFIRM: "off", BOXERY_ASSUME_YES: "1" }); assert.notEqual(r.code, 0); - assert.match(r.output, /grants need a person[\s\S]*vm_grant[\s\S]*boxery --host local grant demo ssh-agent/); + assert.match(r.output, /grants need a person[\s\S]*vm_grant[\s\S]*boxery --host local access grant demo ssh-agent/); assert.equal(existsSync(store), false); } }); @@ -231,7 +231,7 @@ test("text ls is drawn from ls --json: grants, pool leases and outdated guests i assert.match(r.stdout, /^pool1 +shut off +- +- +- +headless +pool free; outdated guest \(layers changed\)$/m); assert.match(r.stdout, /^pool2 +running .* leased by ben@mac, 2h left$/m); assert.match(r.stderr, /guest software not checked yet: pool2 \(ls --refresh reads it\)/); - assert.match(r.stderr, /outdated guest software on pool1; update with: boxery patch NAME\|--all/); + assert.match(r.stderr, /outdated guest software on pool1; update with: boxery patch NAME \(or boxery patch --all\)/); const running = await headless(["ls", "--running"]); assert.equal(running.code, 0, running.output); assert.doesNotMatch(running.stdout, /pool1/); diff --git a/test/help-drift.test.mjs b/test/help-drift.test.mjs index 2d1a372..967f8f4 100644 --- a/test/help-drift.test.mjs +++ b/test/help-drift.test.mjs @@ -29,10 +29,10 @@ const PARSED_IN = { }; // Flags in a handler that aren't its own options: arguments it gives ssh, gh or the VM helper. const NOT_OPTIONS = { - ssh: ["-t"], attach: ["-t"], forward: ["-o"], + ssh: ["-t"], attach: ["-t", "--bg"], forward: ["-o"], // --bg belongs to the suggested run command jobs: ["--text"], kill: ["--text"], runners: ["-c", "--hostname", "--jq", "--input"], // gh api - run: ["-h", "--help"], // its own --help, handled before NAME + run: ["-h", "--help", "-f", "-c"], // help before NAME; -f/-c belong to suggested logs/shell commands }; // Commands whose flags the host parses (passed through): their help is checked against the host's usage text. const HOST_PARSED = { patch: "patch", "upgrade-host": "upgrade", backends: "backends", capabilities: "capabilities", snaps: "snaps", images: "images", pool: "pool", runners: "runners" }; diff --git a/test/shell/controller-local.sh b/test/shell/controller-local.sh index ce95187..03a50dc 100755 --- a/test/shell/controller-local.sh +++ b/test/shell/controller-local.sh @@ -129,7 +129,7 @@ mkdir -p "$tmp/vms/w1/home/.pi/agent"; printf '{"defaultProvider": "openai-codex printf '{"providers": {"openai-codex": {"baseUrl": "http://127.0.0.1:8088/chatgpt/backend-api"}}}\n' >"$tmp/vms/w1/home/.pi/agent/models.json" printf '#!/bin/sh\nexit 0\n' >"$tmp/bin/tmux" if out=$("$A" prompt w1 say hi 2>&1); then bad "prompt without an llm grant started: $out" -elif [[ $out == *"needs llm:chatgpt"*"boxery grant w1 llm:chatgpt"* ]] && ! ls "$tmp/vms/w1/home/project/.boxery/"task-* >/dev/null 2>&1; then ok "prompt without pi's llm grant: refused, with the grant to run" +elif [[ $out == *"needs llm:chatgpt"*"boxery access grant w1 llm:chatgpt"* ]] && ! ls "$tmp/vms/w1/home/project/.boxery/"task-* >/dev/null 2>&1; then ok "prompt without pi's llm grant: refused, with the grant to run" else bad "prompt without a grant: $out"; fi # (a login script that prints something first doesn't hide pi's settings) echo "welcome to the VM" >"$tmp/vms/w1/login-output"