Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. Family actions are resolved from the words alone, before any host or profile is read; `host`'s registry actions (`add`, `ls`, `show`, `use`, `rm`) have no command and run in `controller/hosts.mjs` before host selection, while its maintenance actions go through 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. 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) |
Expand Down
6 changes: 5 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ CI (`.github/workflows/ci.yml`) runs on PRs and pushes to `master`: lint and the
| Change | Also |
|---|---|
| a `vm_*` tool or action | the table in `core/boxery-tools.mjs`, not one front-end (`test/frontends.test.mjs`); map it to a `boxery` command in `test/parity.test.mjs`, or say why it has none |
| a `boxery` command or flag | its `help` in `controller/cli.mjs`'s `COMMANDS`; map it in `test/parity.test.mjs` (and, if it can run for more than a few seconds, give its entry a `status`, which reports it to the terminal: `controller/status.mjs`; the test says so for a command with neither a `status` nor a `NO_STATUS` reason); `npm run docs:cli`; review the help change, then `BOXERY_UPDATE_GOLDEN=1 node --test test/help-drift.test.mjs` (it rewrites both `boxery help` and `boxery help --all`) |
| a `boxery` command or flag | its `help` in `controller/cli.mjs`'s `COMMANDS`, plus a `contract` if it differs from ordinary selected-host/legacy-help behavior (scope, payload, terminal needs, optional/all-host routing); `test/cli-contracts.test.mjs` checks these declarations; map it in `test/parity.test.mjs` (and, if it can run for more than a few seconds, give its entry a `status`, which reports it to the terminal: `controller/status.mjs`; the test says so for a command with neither a `status` nor a `NO_STATUS` reason); `npm run docs:cli`; review the help change, then `BOXERY_UPDATE_GOLDEN=1 node --test test/help-drift.test.mjs` (it rewrites both `boxery help` and `boxery help --all`) |
| a family action (`boxery snapshot create`, `job ls`, …) | an entry in the family's `actions` naming the command whose handler it runs (no second handler; `help` is derived from that command's, with overrides only where its arguments differ), plus the same as for a command; test canonical and older spelling together in `test/cli-families.test.mjs` |
| a `boxery-host` command or flag | its help in `host/help.mjs` (`host/cli.mjs` won't load without it); `npm run docs:cli`; output formats are pinned by `test/shell/logic/host-output.sh` |
| a backend | `host/backends/NAME.sh` ([contract](host/backends/README.md)); a declaration in `backends/index.mjs` ([support contract](docs/backends.md), `test/backend-capabilities.test.mjs`); its `BOXERY_NAME_*` settings in `host/host-env.list`; tests like `test/shell/common/host-lima-backend.sh`; the README's platform lists |
Expand All @@ -47,6 +47,10 @@ 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.

`test/frontends.test.mjs` does the same for the two agent front-ends, the MCP server and the pi extension: both must list exactly the shared tool table in `core/boxery-tools.mjs`. Put a new tool or action in the table (with its `run`), not in one front-end; something only one of them can offer goes in that test's `MCP_ONLY` or `PI_ONLY` with the reason.
Expand Down
Loading
Loading