@unotest/protocol 0.32.0 → 0.35.0

package/CHANGELOG.md

@@ -1,5 +1,341 @@
 # Changelog
 
+## [0.35.0] - 2026-09-15
+
+### Patch Changes
+
+- 79c99ab: A box can now say "I cannot judge this token yet" instead of "your token is
+  wrong".
+
+  A box rented from the fleet accepts tokens the cloud signed for it, and it
+  checks every one against the operator's revocation list. Until that list has
+  reached the box — the minutes between it coming up and its first update tick
+  — there is nothing to check against, so such a token is refused. That is not
+  the same refusal as a bad credential: the answer is to send the SAME token
+  again shortly, never to mint another.
+
+  `BoxReadErrorCode` gains `revocation-list-unavailable` for it, and a refusal
+  body may carry `retryAfterSeconds` (the box sends `Retry-After` with the same
+  number). The push and run answers gain the same code, plus `ambiguous-project`
+  for a cloud-minted push token that names no project on a box that serves
+  several. Nothing changes for the tokens a person or a CI job mints on the box
+  itself.
+
+- dee96a1: A box can now say "this token has expired" instead of "your token is wrong".
+
+  Tokens the cloud signs for a rented box live thirty days. Until now a box
+  refused an expired one with the same blanket `unauthorized` it gives a
+  forgery, so the CLI could not tell "ask the cloud for another pair and
+  retry" from "this credential will never work", and an expired pair looked
+  revoked.
+
+  The read, push, run and values answers gain the code `expired` for it. A box
+  sends it only for a token its operator key really signed, of the right kind,
+  for that box — the signature, the kind and the box are all checked before
+  the expiry is — so nothing a guesser sends can produce it. It is also
+  decided before the revocation list is consulted: a box that has not received
+  a list yet still answers `expired` rather than asking for the same dead
+  token again.
+
+  Two codes that a box could already send are now accepted when parsing a run
+  or values answer, which had been left out of those two readers:
+  `revocation-list-unavailable` and `ambiguous-project`.
+
+## [0.34.0] - 2026-09-07
+
+### Patch Changes
+
+- 32a495e: Failure artifacts survive a run that is isolated from its own artifact root.
+
+  A run executed inside a container sees only what is mounted into it. The
+  failure bundle's directory is derived from the artifact root, which on such
+  a run is not one of those mounts — so it could not be created, and a failed
+  test produced no screenshot, no trace and no page HTML at all. Worse, that
+  one error took the always-on copies in the run directory down with it: both
+  sinks shared a single try, so the artifact that does not depend on the
+  bundle was lost too.
+
+  Two changes. `UNOTEST_FAILURES_ROOT` now says where bundles live, for
+  whoever spawns the run to point at a directory it can actually write
+  (unset, everything behaves exactly as before). And the two sinks are
+  independent: an unusable bundle root no longer costs you the run
+  directory's screenshot and page HTML.
+
+  The viewer serves failure assets from either layout, so a bundle written
+  inside the environment's runs tree renders like a local one.
+
+- c6b91bb: From `init` to a paid box without copying a token: `login`, `box create`,
+  and the tokens that keep themselves fresh.
+
+  Three new commands sign this machine in to unotest cloud — the account
+  that rents boxes — and rent one:
+
+  - `login` runs the device flow (RFC 8628): it prints a link and a code,
+    opens the browser when there is one, and waits for the approval. The
+    key is kept in `~/.config/unotest/credentials.json` (mode 0600,
+    `XDG_CONFIG_HOME` honoured) and is never printed, not even with
+    `--json`. `UNOTEST_CLOUD_TOKEN` in the environment wins over the file,
+    which is how a CI job signs in. `logout` revokes the key on the server
+    when the cloud can be reached and removes it locally always; `whoami`
+    says who, where the key came from, and the balance (exit 77 when not
+    signed in).
+  - `box create [name] [--size s|m|l] [--topup <eur>]` creates a box named
+    after the project (its package name, as a slug), with the environments
+    the project runs locally (`unotest/.env` and every `unotest/.env.<name>`,
+    their `APP_BASE_URL` or the config's `baseUrl` as the target). When the
+    balance will not cover the first hour it prints a Stripe Checkout link,
+    opens it when it can, and waits for the payment. Then it waits for the
+    box, mints its cloud-signed push and read tokens, writes
+    `UNOTEST_BOX_URL` to `unotest/.env` and `UNOTEST_BOX_TOKEN` +
+    `UNOTEST_BOX_READ_TOKEN` to `unotest/.secrets` (through the same
+    structure-preserving writer the viewer's Variables panel uses, with
+    `.gitignore` guarded the way `init` guards it), pushes the suite —
+    retrying with backoff while a fresh box has no revocation list yet —
+    and prints the viewer's address. Exit codes for an agent driving it
+    without a terminal: 75 the payment was not confirmed in time (nothing
+    created, nothing charged), 76 the terms of service are not accepted
+    (a person must, in a browser), 77 not signed in. No prompt is ever
+    shown without a TTY.
+    `--picker` rents the box with the Picker; `UNOTEST_GROUNDER_MODE=remote`
+    and `UNOTEST_GROUNDER_REMOTE_URL` then go to `unotest/.env` and
+    `UNOTEST_GROUNDER_REMOTE_TOKEN` to `unotest/.secrets` — the names the MCP
+    server reads — so intents ground on the box with no further setup. A
+    box without the Picker leaves those keys alone. The last line of
+    `create` is the next step: the complete `bundle push --run --env …
+--collection …` when the project has exactly one environment and one
+    collection, the viewer's address plus the command with placeholders
+    otherwise.
+  - `box access [name]` re-mints the pair and rewrites the two files;
+    `box status` and `box destroy` (asks on a terminal, `--yes` elsewhere)
+    are thin wrappers. The name defaults to the box `UNOTEST_BOX_URL`
+    points at (`acme.box.unotest.com` → `acme`).
+
+  Cloud-signed box tokens live thirty days. When a box answers that one
+  has expired, `bundle push` and the `box …` read commands re-mint the
+  pair through the cloud and retry once, provided a cloud login is at
+  hand; without one they say to run `login && box access`. The box a
+  re-mint is for is the one the project points at, named from its address
+  or, when the address spells no name (a stand behind an IP), by the same
+  default `create` used — so a lab box re-mints like any other. A `--box`
+  naming somewhere else is said to be somewhere else rather than blamed on
+  a missing login. A box that has
+  not yet received its revocation list is told apart from a real refusal
+  and retried; a token the box calls revoked is never re-minted quietly.
+  `bundle push` now also reads the push token from `unotest/.secrets`,
+  where `box create` puts it (then `unotest/.env`, for suites set up by
+  hand), so nothing has to be exported after the setup.
+
+  The MCP server knows the state too. While the project points at no box,
+  `box_envs`, `box_runs`, `box_run` and the other box tools answer
+  `{state: "no-box", next, why}` instead of an error, and `run_test`
+  carries the same `boxSuggestion` exactly once per server — after the
+  first local run that passes — so an agent offers the box at the moment
+  it is worth something and never nags. The box tools re-mint an expired
+  cloud-signed read token the way the CLI does, through the composition
+  root, and `unotest/.secrets` is read on every call: a pair written by
+  `box create` while the server runs is used by the next call. On a
+  Picker box, `ground_element` (and intent locators) whose picker token
+  the grounder refuses re-mint it once through the cloud and hand the new
+  token to the running client; a refusal that cannot be mended answers
+  `{state: "picker-token-refused", next: "npx @unotest/web box access",
+why}`, and a grounder that has not read its revocation list yet answers
+  `{state: "retry-shortly", retryAfterSeconds}`. Box tokens are checked
+  before the network: cloud-signed ones by their whole shape (`unos_…`), a
+  push token in the read variable (and the reverse) is named as the wrong
+  kind, anything else as not a token.
+
+  A renewal the cloud itself refuses is its own answer, not the cloud's.
+  When a box or the grounder says a cloud-signed token is stale and the
+  `/access` call that would replace it is refused in turn — no such box,
+  the box not ready, too many live pairs, the cloud unreachable — every
+  surface says that the credentials could not be renewed and keeps the
+  cloud's refusal as the cause. The CLI prints one line and exits with the
+  code that refusal earns; the grounding tools answer
+  `{state: "picker-token-refused", next, why}` as before, so an intent is
+  never answered with a sentence about boxes.
+
+  `init` ends with one line saying how to run the suite on a box; the
+  "mint a read token in the guard" advice in the box commands' refusals
+  now points at `login` and `box access` instead. `UNOTEST_CLOUD_URL`
+  points the CLI at a stand or a fake cloud; nobody sets it otherwise.
+
+  `@unotest/protocol`: `replaceEnvVar` (an in-place value replacement the
+  new upsert builds on), `BOX_PUSH_TOKEN_PREFIX` / `BOX_SIGNED_TOKEN_PREFIX`
+  / `BOX_SIGNED_TOKEN`, and `UNOTEST_BOX_URL`, `UNOTEST_GROUNDER_MODE`,
+  `UNOTEST_GROUNDER_REMOTE_URL` listed among the runner-config keys so they
+  file under the Runner section of `unotest/.env`.
+
+  `@unotest/grounder-client`: `GrounderHttpClientOptions.token` may be a
+  function yielding the current bearer; `GrounderRemoteError` carries the
+  grounder's `retryAfterSeconds`, and the error codes gain
+  `revocation-list-unavailable`.
+
+## [0.33.0] - 2026-09-06
+
+### Minor Changes
+
+- 2abfd4d: Box: every run is announced — Slack, Telegram, or a webhook of your own — and the channels are managed from the guard.
+
+  A box now tells people how its runs went, whoever started them: the
+  schedule's ticks, a pull request's check, somebody pressing Run in the
+  viewer, a terminal inside the container. The daemon reads each run's own
+  journal, so the three producers are one source; the run's manifest says
+  what set it off — `trigger: { kind: "schedule" | "ci" | "manual" | "cli",
+by? }`, written by the runner from `UNOTEST_RUN_TRIGGER` /
+  `UNOTEST_RUN_ACTOR` (a box sets them for its scheduled and CI runs, the
+  viewer for a run ordered from its UI; a terminal sets nothing and reads as
+  `cli`).
+
+  A scheduled series is announced on a **change of state**: `failed` after
+  `afterFailures` red ticks in a row, `recovered`, `still-failing` at a rule's
+  `repeatEvery`, `not-run` when the suite could not run at all (no bundle, a
+  bundle that does not install) — daily by default. A run somebody ordered is
+  announced on its own, `failed` or `passed`, every time. A withdrawn or
+  aborted run says nothing; a run whose journal stops and whose heartbeat goes
+  cold is `interrupted`.
+
+  Channels, rules, mutes and quiet hours live on the box and are managed from
+  the guard's `/_guard/notifications` page (or `boxd notify …`): a channel's
+  secret is set once and never shown again, a rule picks environments,
+  triggers, events and channels, a series or the whole project can be muted
+  until a time, and quiet hours hold reminders and `passed` back until the
+  morning. A generic webhook receives the event as JSON (`version: 1`, the
+  box named, the `trigger`) with `X-Unotest-Event` and, when the channel has
+  a secret, `X-Unotest-Signature: sha256=<hex>` — HMAC-SHA256 over the raw
+  body, the scheme GitHub uses — plus any headers the channel declares.
+
+  `@unotest/protocol`: `RunManifest.trigger` and the trigger helpers
+  (`runTriggerFromEnv`, `runTriggerEnv`, `manifestTrigger`); the session-door
+  paths, views and parsers of the notifications API (`boxNotifyProjectPath`,
+  `boxNotifyChannelPath`, `boxNotifyRulePath`, `boxNotifySeriesPath`,
+  `boxNotifyMutePath`, `boxNotifyQuietHoursPath`, `boxNotifyPreviewPath`,
+  `BoxNotifyProjectView`, …). The first draft of this feature (channels
+  declared in the box config, secrets by field) never shipped; this replaces
+  it whole.
+
+- 5d1bde3: Run isolation, stage 1: a box no longer executes a test bundle inside its
+  own daemon.
+
+  box-runner (new, private): the run sidecar — the only service on a box
+  holding the docker socket, and the only one that starts a container. Three
+  authenticated routes on the `box` network (`POST /runs`, `GET
+/runs/:id/stream` NDJSON, `DELETE /runs/:id`), a shared secret compared in
+  constant time, and an API that cannot be told anything about how a
+  container is built: no path, image, network, user, mount or flag. A request
+  names a project, an environment, a bundle, a scenario and the environment's
+  values; the bind sources are derived from the first three, resolved with
+  `realpath` and re-checked against the projects root, and must already
+  exist. The container is created over the Docker Engine API (pinned
+  `v1.43`) straight over the socket — no `docker` binary in the image and no
+  client dependency, and a container that is a JSON document has no place
+  for a value to become a flag. A daemon that refuses or is not there comes
+  back as `502 {reason}` before the run is accepted, or as an `error` event
+  on the stream after — never as a run that "exited with code null". An
+  environment variable the box does not forward is named in the sidecar's
+  log rather than dropped silently. A run gets the bundle tree read-only as its working directory, the
+  environment's `unotest/.runs.<env>` read-write, a `noexec` tmpfs `/tmp`,
+  a read-only rootfs, all capabilities dropped, `no-new-privileges`, its own
+  uid in boxd's group, memory/pids/cpu limits clamped to both the operator's ceilings and the
+  host's own size (docker refuses a container bigger than the machine
+  instead of clamping it), a 512 MB `/dev/shm`
+  (docker's default 64 MB kills Chromium mid-page; the host's IPC namespace
+  is deliberately not borrowed), and the `runs` network only. The container engine is an interface, so every rule is asserted on
+  the container that would have reached docker — including the cases where
+  the answer is no container at all.
+
+  boxd: running the SUITE is its own contract (`IScenarioRunner`), separate
+  from running a command (`ICommandRunner`, still the daemon's own `npm ci`
+  and viewers). `ContainerScenarioRunner` talks to the sidecar,
+  `ProcessScenarioRunner` keeps the old child-process shape for a box without
+  docker; `BOXD_RUNNER_KIND=container|process` chooses, and half a container
+  configuration refuses to start. Reading a bundle's schedules
+  (`unotest-web schedules --json`) executes the project's config module, so it
+  goes the same way. A run's environment is built from named parts
+  (`run-environment.ts`) instead of inheriting `process.env`, and its debug
+  tree is pointed at the run's own directory rather than the read-only
+  sources. New metrics
+  `boxd_run_container_total{outcome}` and `boxd_run_container_start_seconds`.
+  An environment's runs directory is created by the daemon with `2775`, so
+  the run's uid may write into it and the daemon's group may read it back.
+
+  box-kit: `secretsMatch` (constant-time secret comparison, moved out of
+  dist-service), `splitLines`, and `envNumber` / `envPositiveNumber` — the
+  env-reading rule the box-side services share.
+
+  `npm ci` of a bundle is a container of its own (`kind: "install"`): the
+  bundle tree is its only mount and it is writable, there is no environment
+  and no artifacts directory in reach, and a dependency's install scripts
+  RUN — a native module builds or fetches its binary as usual. That is what
+  running them inside the daemon could never allow. The container's last
+  steps, only on success, check the tree against the box's size cap, set
+  the final modes on what the install created and write the install marker
+  — each with an exit code of its own, so the daemon's log names the step
+  that failed — so a killed or oversized
+  install leaves a tree the box will not mount; a failed install takes the
+  tree with it. The daemon no longer passes `--ignore-scripts` and no
+  longer walks the tree afterwards.
+
+  The daemon runs with `umask 002` and clears `node_modules` before each
+  install, so a tree it created is one the install container (another uid
+  in its group) can actually write.
+
+  An install that fails KEEPS the tree, unmarked: nothing mounts it and the
+  next attempt reinstalls in place (`npm ci` wipes `node_modules` itself).
+  And a bundle directory holding a manifest with neither an archive nor a
+  tree behind it no longer counts as "this box has it" — a push of the same
+  content brings it back instead of being answered `already had this exact
+bundle`.
+
+  web: `bundle push` and the docs say that a dependency's install scripts
+  run on a box, in isolation — the earlier advice to vendor them is gone.
+
+  A run ordered in the viewer now goes through the daemon's queue instead
+  of being spawned by the viewer.
+
+  `POST/GET/DELETE /api/box/envs/<project>/<env>/runs[/<runId>]` (paths and
+  wire types in `@unotest/protocol`) takes a `manual` ticket like every
+  other producer. Two callers may use it, and neither is taken on its word:
+  the guard, proving it is the guard with a shared secret from `box-init`
+  (the actor header is read only next to it — a viewer container could
+  otherwise claim to be any admin), and a viewer, with a per-environment
+  token the daemon minted when it started that viewer plus a short-lived
+  single-use ticket the guard signed over WHO clicked. The guard gates the
+  route under `admin` and requires an `Origin` on a mutation; the daemon
+  checks the token's environment, the ticket's environment and its `jti`
+  against the path.
+
+  `@unotest/viewer` gets `BoxdRunner`: on a box the Run button orders and
+  the Stop button asks the daemon, and the progress still comes from the
+  run's journal on disk. A local viewer spawns as it always did — the
+  composition root picks by whether a box handed it credentials.
+
+### Patch Changes
+
+- b3e1220: Box notifications: a webhook channel's header values are credentials.
+
+  The notifications API and the guard's page now see a webhook's headers
+  as names with `{ set: true }` — the values (the receiver's
+  `Authorization`, most of the time) are never read back, like the signing
+  secret. The edit form lists the names; typing a value after one replaces
+  the set, names alone keep it. `/api/box/notify` is the guard's own route:
+  it is no longer reachable through the session proxy for any role — a
+  readonly session could previously list every project's channels with
+  their headers.
+
+- b3e1220: Box notifications: the webhook signature now covers a timestamp.
+
+  Every webhook delivery carries `X-Unotest-Timestamp` (Unix milliseconds,
+  when it was sent), and `X-Unotest-Signature` is HMAC-SHA256 over
+  `<timestamp>.<raw body>` rather than the body alone — GitHub's scheme
+  with a timestamp in front, so a delivery captured on the wire cannot be
+  replayed to the receiver once its window (five minutes, documented) has
+  passed. The GitHub webhook the box receives is unchanged: that is
+  GitHub's contract.
+
+  The `by` of a CI-triggered run (`push a1b2c3d (branch)`) is cut at 200
+  characters — a branch name is the pusher's input, and it must not balloon
+  the run's manifest and every notification the run produces.
+
 ## [0.32.0] - 2026-09-05
 
 ### Minor Changes