From 371da8a6b30685bc248cb817ed54bc0a784655e1 Mon Sep 17 00:00:00 2001 From: NovusEdge Date: Sat, 3 Oct 2026 12:51:02 +0300 Subject: [PATCH] docs: fix v0.7.0 reference drift; prepare v0.7.1 The CLI reference still described usage errors as printing the full usage text, listed down-on-a-stopped-VM as exit 1, and omitted stoat help and the ssh booting exit. The JSON reference described not_found, cannot_reach and access_denied by their pre-v0.7.0 cases and had no History entry for limit_reached. The v0.7.1 CHANGELOG entry also corrects two lines of the v0.7.0 notes. Signed-off-by: NovusEdge --- CHANGELOG.md | 21 +++++++++++++++++++++ docs/reference/cli.md | 12 +++++++----- docs/reference/json.md | 15 ++++++++++++--- flake.nix | 2 +- 4 files changed, 41 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 724c281..c3d6792 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,26 @@ # Changelog +## v0.7.1 + +Documentation only; no code changes from v0.7.0 apart from a bubbletea bump +(2.0.9 to 2.0.10). + +### Fixes + +- The CLI reference said a usage error prints the full usage text. It prints + the error, the command's usage line and a pointer to `--help`, as it has + since v0.7.0. `stoat help ` is documented. +- The exit-code table listed `stoat down` on a stopped VM as exit 1. It exits + 0, as the `down` section says. +- `stoat ssh` documents exit 1 for a VM whose sshd does not answer yet. +- The JSON reference describes `not_found`, `cannot_reach` and + `access_denied` with the cases v0.7.0 added, and its History section records + `limit_reached`, `needed_mb` and `available_mb`. +- Two corrections to the v0.7.0 notes below. `cannot_reach` was not a new + code: it existed for `wait`, and v0.7.0 extended it to a guest command whose + ssh connection failed. For `stoat logs`, `-n` is the short form of + `--lines`; the spelling kept as a hidden alias is `--n`. + ## v0.7.0 A usability pass for people and for agents, driven by two audits that used diff --git a/docs/reference/cli.md b/docs/reference/cli.md index ffd83f9..7effa68 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -96,7 +96,8 @@ order, when given no VM argument. A bare VM argument resolves against | [`help`](#stoat-help) | Show the usage message | 0 | An unknown command, missing VM name, or extra argument is a **usage error** -(exit 2). Stoat prints the error and full usage text to stderr. The +(exit 2). Stoat prints the error, the command's usage line, and a pointer to +its `--help` to stderr. The client-specific `mcp` flags are documented in [the MCP reference](mcp.md). ## `stoat ls` @@ -407,7 +408,7 @@ unparsed, or when you need `--json`. `-q` is accepted but has no effect (there is no chatter to suppress before the process is replaced). `--json` is refused outright: `syscall.Exec` destroys the process image, so there is no "after" in which to write a result line; the error message points at `stoat --json exec -- ` for a single command, or `ssh_port`/`ssh_user` from `stoat --json ls` to build your own connection. -**Exit codes:** 0 is not actually observed on success: the process image is gone. 1 if the VM can't be loaded, `ssh` isn't found on `$PATH`, or `exec` itself fails to launch. 2 under `--json`, always (see above). +**Exit codes:** 0 is not actually observed on success: the process image is gone. 1 if the VM can't be loaded, its sshd doesn't answer within 3 seconds (stoat prints ` is booting; run stoat wait `), `ssh` isn't found on `$PATH`, or `exec` itself fails to launch. 2 under `--json`, always (see above). ## `stoat ssh-command ` @@ -941,7 +942,7 @@ Prints the build's version string as `stoat `. Equivalent to the top-le ## `stoat help` -Prints the full usage message (subcommands, global flags, exit codes) to stdout. The same text is printed to stderr, alongside the specific error, whenever a usage error occurs. +Prints the full usage message (subcommands, global flags, exit codes) to stdout. `stoat help ` prints that command's help instead, the same text as `stoat --help`. **Exit codes:** always 0. @@ -950,10 +951,11 @@ Prints the full usage message (subcommands, global flags, exit codes) to stdout. | Code | Meaning | Examples | |---|---|---| | `0` | Success | VM started/stopped, provisioned, deleted; `doctor` found nothing wrong | -| `1` | Runtime failure | Unknown VM name, VM already stopped for `down`, VM running for `rm`, ssh unreachable during provision, `doctor` found an issue, `rm` confirmation declined | +| `1` | Runtime failure | Unknown VM name, VM running for `rm`, ssh unreachable during provision, `doctor` found an issue, `rm` confirmation declined | | `2` | Usage error | Unknown subcommand, missing/extra arguments, an unparseable flag, `update` given no flags, `check-recipes` given no names | -A usage error (2) prints the complaint and full usage text to stderr. A runtime +A usage error (2) prints the complaint, the command's usage line, and a pointer +to its `--help` to stderr. A runtime failure (1) prints `stoat: : ` to stderr. Without `--json`, `exec` instead returns the guest command's status from 0 through 255. See [`stoat exec`](#stoat-exec-name-command). diff --git a/docs/reference/json.md b/docs/reference/json.md index 302c388..3b7bb3f 100644 --- a/docs/reference/json.md +++ b/docs/reference/json.md @@ -116,7 +116,7 @@ bump the contract version. Do not write code that requires them. | Code | Meaning | |---|---| -| `not_found` | no such VM | +| `not_found` | no such VM, or no such snapshot, guest, image, recipe, background job, guest path, or `stoat.toml` entry | | `broken` | the VM's `vm.toml` will not parse | | `name_taken` | a VM by that name already exists | | `invalid_spec` | the request itself is malformed | @@ -129,7 +129,7 @@ bump the contract version. Do not write code that requires them. | `no_disk` | the VM has no qcow2 (a live VM has none) | | `immutable_field` | `update` was asked to change a field that cannot change | | `disk_shrink` | a disk can only grow | -| `cannot_reach` | `wait` was asked for a state this VM can never reach | +| `cannot_reach` | `wait` was asked for a state this VM can never reach, or a guest command could not connect because the running VM's sshd does not answer yet (it is booting; `wait` first) | | `unknown_log` | bad `--which` | | `qemu_missing` | `qemu-system-x86_64` is not on `PATH` | | `kvm_unusable` | `/dev/kvm` cannot be opened; the user is usually not in the `kvm` group | @@ -148,7 +148,7 @@ bump the contract version. Do not write code that requires them. | `canceled` | the context was cancelled | | `usage` | a bad flag, a missing argument, an unknown subcommand | | `confirmation_required` | a destructive command was run without `-y` | -| `access_denied` | MCP guest access was refused because the VM's `agent_access` level is too low | +| `access_denied` | MCP guest access was refused because the VM's `agent_access` level is too low (including `write_file` with `as_root` below `exec`), or the guest refused a path the ssh user cannot read or write | | `rate_limited` | MCP refused a tool call because its per-tool or shared rate bucket was exhausted | | `limit_reached` | a configured limit or the host's free memory refuses the operation; a RAM refusal adds `needed_mb` and `available_mb` | | `lock_out_of_date` | a project declaration is not pinned in `stoat.lock` | @@ -647,6 +647,15 @@ The contract stays 3. and `shared_mount`. The MCP server gained `list_snapshots` and `delete_snapshot`. The contract stays 3. +v0.7.0 added the `limit_reached` code and the `needed_mb` and `available_mb` +error fields, which appear only on a RAM refusal. The same release widened +three existing codes: `not_found` covers missing guest paths, job ids, +recipes and images as well as VMs; `cannot_reach` covers a guest command +whose ssh connection failed while the VM boots; and `access_denied` covers a +guest path the ssh user cannot use. Before v0.7.0 those cases answered +`internal`, or reported success with exit code 255. No code changed its +meaning for a case it already covered, so the contract stays 3. + ## Capability discovery stoat capabilities [VM] --json returns a report with schema 1 in the usual diff --git a/flake.nix b/flake.nix index 4ae08fe..333a23d 100644 --- a/flake.nix +++ b/flake.nix @@ -28,7 +28,7 @@ # `git describe` isn't available in the nix build sandbox, so pin a # version string here; bump on release the same way release.yml's # ${GITHUB_REF_NAME} does for the tarball builds. - version = "0.7.0"; + version = "0.7.1"; in { default = pkgs.buildGoModule {