@unotest/viewer 0.31.0 → 0.33.0

package/CHANGELOG.md

@@ -1,5 +1,291 @@
 # Changelog
 
+## [0.33.0] - 2026-09-06
+
+### Minor Changes
+
+- 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.
+
+- 348aba7: Run isolation, stage 2b and 3: an environment's viewer runs in a
+  container of its own, and a box ships the sidecar in its compose stack.
+
+  The viewer was the last thing on a box that executed a bundle's code next
+  to the daemon's state: it runs the UI, the language service and the
+  linter out of the bundle's own `node_modules`. It is now a container the
+  run sidecar starts and the daemon asks for — `POST /viewers`, one per
+  environment, addressed by a name both services derive
+  (`unotest-viewer-<project>-<env>-<8 hex>`, port 7788).
+
+  Each viewer gets a NETWORK of its own with exactly two other containers
+  attached: the guard, which proxies people at it, and the daemon, which it
+  orders runs from. Not the sidecar's network, not the runs network, and
+  above all not another viewer's — a viewer has no authentication of its
+  own, and two on one network would be two containers of untrusted code
+  with a route to each other. That network is INTERNAL: a viewer's server
+  makes no outbound call, so it gets none, while the network a run joins
+  stays open because a test drives an application. The name of a viewer and
+  its network is a function of the project/environment PAIR rather than of
+  the string they join to, so two environments whose names concatenate the
+  same way cannot end up sharing one. Its mounts are the bundle tree read-only and
+  the environment's `unotest/` read-write (the run history it renders and
+  the queue it withdraws tickets from); the environment's secrets and its
+  `current` link sit in the directory above and are mounted by nobody. Its
+  environment is assembled by the daemon — the target, the environment's
+  variables and secrets, its own credential — and the daemon's own
+  `process.env` no longer travels.
+
+  **Editing a suite's files from the viewer on a box no longer works**: the
+  sources are read-only there. Such edits never survived the next `bundle
+push` anyway, which replaced the tree. Everything else in the UI is
+  unchanged.
+
+  Readiness is the docker daemon's own healthcheck, probed inside the
+  container and read through the sidecar — the daemon no longer waits on a
+  lock file, and nothing dials a viewer from the process holding the docker
+  socket. A viewer's output is streamed into the daemon's log and
+  reattached when the stream drops. A container whose bundle and values
+  still match is ADOPTED across a restart of either service, keeping the
+  credential it was born with; one whose environment is gone is stopped,
+  with its network and its token. The sidecar recognises its own containers
+  by label, never by name alone, and enforces its own ceiling on how many
+  viewers may exist (`BOX_RUNNER_MAX_VIEWERS`) — boxd knows how many
+  environments there are right up until boxd is the thing that was
+  compromised.
+
+  A run somebody stopped now ENDS in the viewer instead of hanging.
+  Stopping a run stops its container gracefully (SIGTERM, then SIGKILL
+  after `BOX_RUNNER_STOP_GRACE_SECONDS`, default 10) so the suite writes
+  the terminal event of its own journal; if it could not — the grace ran
+  out, the machine died — the daemon appends it. The same grace applies to
+  a run killed on its timeout, so a run's budget is the timeout plus the
+  grace.
+
+  A viewer that dies is noticed in about a second and replaced: the log
+  stream the daemon holds open ends with the container, and the 404 that
+  answers its immediate reattach is the signal. The route comes out of the
+  table at once — the guard then says the environment has no viewer instead
+  of proxying at a dead address — and a fresh container is started, on the
+  same backoff the daemon uses for everything else it cannot reach.
+
+  A restart of the sidecar is no longer an outage. While it cannot be
+  reached the daemon keeps the routes it published (the viewer containers
+  are up, and the guard reaches them directly) and tries again with a short
+  backoff instead of waiting for its next five-minute sweep. Editing a file
+  in the viewer on a box now answers 403 with the reason — the sources are
+  read-only there — rather than a blank 500.
+
+  The viewer no longer collapses the daemon's refusals into a blank 500:
+  the box's own status and reason reach the browser, so "that click has
+  already been used" (409), "the box cannot verify the caller" (503) and
+  "the box daemon is not answering" (503) are told apart by the person who
+  clicked.
+
+  Deployment: `compose.yaml` gains the `runner` service (the only holder of
+  the docker socket, the release ships its bundled `box-runner.mjs` beside
+  `boxd.mjs`), fixed container names for the guard and the daemon, a
+  `box_secrets` volume whose secrets `box-init` generates, and a one-off
+  migration of the projects tree to the group layout an install container
+  needs. Two values an operator fills in: `BOX_PROJECTS_HOST_DIR` (a bind
+  source is resolved by the docker daemon on the host) and `BOX_DOCKER_GID`.
+  Step by step in `docs/manuals/box-run-isolation-cutover.md`.
+
+### Patch Changes
+
+- 9158968: Viewer: a run that started before the page was reloaded is shown again.
+
+  The live sidebar was rebuilt from WebSocket events only, and those speak
+  from the moment the page connects — a collection already in progress
+  never re-sent its `started` event, so after a reload it was missing from
+  ACTIVE, then reappeared nameless with no scenario list once its next
+  scenario began, while its children showed up one by one. On load, and on
+  an environment or target switch, the viewer now asks the server which
+  runs are live and replays each one's journal into the same state the
+  live stream feeds, so a reload mid-run shows the collection with its
+  name, scenarios and progress.
+
+- b3e1220: Viewer: a session that may not edit variables does not see credential-shaped
+  values, nor the project's absolute path.
+
+  Behind the guard, a readonly session could read `GET /api/variables` and
+  get every box variable's value — `PASSWORD=…` included when the operator
+  had pushed it as a variable rather than a secret. The viewer now reads the
+  capabilities the guard stamps on each request: when the caller cannot edit
+  variables, a value whose name matches `PASSWORD | PASSWD | SECRET | TOKEN |
+KEY | CREDENTIAL` is sent empty and flagged `secret`, and `GET /api/targets`
+  leaves out `projectRoot`. Display-masking by capability, not authorization —
+  a viewer without a proxy in front is unchanged, and the guard still refuses
+  every write.
+
+- bd6b7ba: Viewer: a collection run no longer shows up nameless and without scenarios.
+
+  The journal tailer moved its cursor to the end of the file even when the
+  last line was still being written, so the half already on disk was lost
+  and the other half was later read as garbage. The longest line in a
+  journal is `collection-run:started` with the scenario list, so that was
+  the one it usually caught: the run appeared under its id instead of its
+  collection name, with "collection has no scenarios" and a `2/0 done`
+  counter. The cursor now stops at the last complete line and the rest is
+  read on the next change.
+
+- 8846a06: Viewer: a run started the moment the viewer came up is shown, not lost
+  until the next change.
+
+  Watching a directory becomes live a moment after the watcher reports it
+  is ready, and a run directory created inside that gap was not merely
+  late — it was invisible until something else changed in the same day,
+  which in a quiet environment is the next run. Measured at 1-3% on macOS
+  with a busy machine, and the window is exactly "open the viewer, start a
+  run". The viewer now proves the watch delivers before it declares itself
+  up: it creates a directory of its own and waits to hear about it, so
+  boot completes on evidence rather than on a promise. A tree it cannot
+  write to, or a probe that never comes back, costs a warning in the log
+  and boots as before.
+
+  A directory whose name starts with a dot is never reported as a run — an
+  editor's leftovers, or the watcher's own probe, can no longer appear in
+  the run list as a phantom.
+
+  Run queue: a waiter whose process paused is no longer mistaken for dead
+  — the queue stamps its own files with its own clock.
+
+  A run waiting for a slot proves it is alive by touching its ticket, and
+  what it is judged against was the modification time the filesystem
+  wrote: on a network share that is the server's clock, and against a
+  machine busy enough to keep a process off the CPU, a ticket written a
+  moment ago could look like it belonged to a process that died. The queue
+  now stamps every file it creates with the same clock it judges them by.
+
+- Updated dependencies [2abfd4d]
+- Updated dependencies [b3e1220]
+- Updated dependencies [b3e1220]
+- Updated dependencies [5d1bde3]
+- Updated dependencies [8846a06]
+  - @unotest/protocol@0.33.0
+  - @unotest/core@0.33.0
+  - @unotest/dsl@0.33.0
+
+## [0.32.0] - 2026-09-05
+
+### Minor Changes
+
+- 442fadf: `npx @unotest/web box …` reads a box's results from a terminal: `box envs` lists the environments a read token may look at, `box runs` their history (`--latest` collapses it to one line per scenario with its failing streak), `box run <id>` explains one run — the failure, the soft steps, the judge's verdicts — `box queue` shows who is waiting, and `box screenshot` saves a frame the run captured.
+
+  `box run --download` fetches the run's `*.unotest.zip` into `.unotest/box/` and unpacks its failure bundle into `.unotest/failures/`, where `list_failures`, `get_failure_*` and `agent_fix` already look — so a run that failed on a box is debugged with the commands a local failure is. `--no-screenshots` asks the box itself to leave the step frames out (`GET /api/runs/:id/export?screenshots=0`), which is what makes the download smaller rather than only the disk.
+
+  Reading needs a personal read token in `UNOTEST_BOX_READ_TOKEN`; the project's `UNOTEST_BOX_TOKEN` still pushes bundles and values and cannot read runs.
+
+  The viewer publishes its archive reader as `@unotest/viewer/snapshot`, so the three places that open a `*.unotest.zip` — its server, its browser bundle and now the CLI — share one implementation and one message for a file that is not an archive.
+
+- 442fadf: `BoxReadClient` reads a box's runs — environments, run history, one run's whole journal, a collection's children, the queue, a run's export zip and its individual artifacts — over the same HTTP routes a browser uses, authenticated with the personal read token in `UNOTEST_BOX_READ_TOKEN`. Every refusal arrives as a typed `BoxReadError` whose `kind` says what to do next, so throttling is never mistaken for a rejected token and a live run's export says "wait" rather than looking like a broken box. Configuration mistakes surface when a read is attempted rather than at startup, so a stale token in a project's `.env` cannot stop a local run that never touches a box.
+
+  The viewer gains a `@unotest/viewer/wire` entry point exporting its HTTP contract types (the runs page, a run's full snapshot, the queue payload and the snapshot manifest), so a client can name the shapes it parses instead of keeping a second copy of them.
+
+### Patch Changes
+
+- 8aa0f30: Protocol contract for reading a box's run results with a personal read token: `UNOTEST_BOX_READ_TOKEN` (distinct from the project's `UNOTEST_BOX_TOKEN`, which stays a write credential for bundles and environment values), the `X-Unotest-Environment: <project>/<environment>` header every bearer request names its own environment with, the `/_guard/api/envs` listing and its `BoxReadEnvironment` entry, and typed refusals (`unauthorized`, `forbidden`, `unknown-environment`, `not-found`, `rate-limited`, `run-in-progress`, `unavailable`, `malformed`) with parsers that reject anything that is not a box answering. Throttling gets a code of its own rather than an `unauthorized` carrying `Retry-After`: a rejected token means mint a new one, a throttled one means wait and resend the same one. The viewer's `ViewerEnvOption` is now that same protocol type rather than a second copy of it. An environment whose viewer is still starting — the common state right after a bundle push — answers `unavailable` rather than looking like an unreachable box, so the advice is to wait rather than to check the address.
+- 8aa0f30: A run exported as `*.unotest.zip` now carries everything needed to diagnose it away from the machine that produced it: `stdout.log` and `stderr.log` (previously dropped, which left the one artifact that explains a runner crash outside the bundle), the failing page's `page.html` reachable through the manifest, and the run's step screenshots — declared in a new `manifest.screenshots` list, because an importer keeps only what the manifest names and a frame absent from it did not survive the round trip.
+- Updated dependencies [8aa0f30]
+- Updated dependencies [047ca68]
+- Updated dependencies [047ca68]
+- Updated dependencies [047ca68]
+  - @unotest/protocol@0.32.0
+  - @unotest/dsl@0.32.0
+  - @unotest/core@0.32.0
+
 ## [0.31.0] - 2026-09-04
 
 ### Minor Changes

package/dist/server/main.d.ts

@@ -1,5 +1,17 @@
 import { IRunnerAdapter, IDslLanguageService, IProcessLauncher } from '@unotest/protocol';
 
+/** What a BOX handed this viewer so it can order runs from the daemon
+ *  instead of spawning them itself. Present only there: a local viewer
+ *  owns its runs, and a box's viewer owns none. */
+interface ViewerBoxConfig {
+    /** The daemon, on the box's own network — never a public address. */
+    readonly daemonUrl: string;
+    /** This viewer's own credential, minted when it started. It says WHICH
+     *  environment is asking; who clicked is a separate, signed claim. */
+    readonly token: string;
+    readonly project: string;
+    readonly environment: string;
+}
 interface BoxInjectedNames {
     /** Non-secret: the viewer has their values in its own environment. */
     readonly variables: readonly string[];
@@ -82,6 +94,14 @@ declare function startViewerServer(opts: StartViewerOptions): Promise<ViewerHand
 /** The box's injected-variable names, when a box supervisor set them.
  *  Both lists come together or not at all; an environment with no secrets
  *  still has a target URL, so "set" means the variables list is present. */
+/** The credentials a BOX hands its viewer so it can order runs from the
+ *  daemon: where the daemon is, this viewer's own token, and which
+ *  project and environment it speaks for. All four or nothing — a token
+ *  with no address is a viewer that cannot ask, and an address with no
+ *  token is one that will be refused, and neither is a shape a box ever
+ *  produces. A local viewer has none of them and spawns its own runs, as
+ *  it always did. */
+declare function boxRunnerFrom(env: NodeJS.ProcessEnv): ViewerBoxConfig | undefined;
 declare function boxInjectedFrom(env: NodeJS.ProcessEnv): BoxInjectedNames | undefined;
 /** Everything the standalone launcher reads from its environment, in one
  *  pure place so the plumbing is testable without starting a server.
@@ -93,4 +113,4 @@ declare function boxInjectedFrom(env: NodeJS.ProcessEnv): BoxInjectedNames | und
 declare function viewerCliOptions(env: NodeJS.ProcessEnv, cwd: string): Omit<StartViewerOptions, "runners">;
 declare function runViewerCli(): Promise<void>;
 
-export { type RunnerEntry, type StartViewerOptions, type ViewerHandle, boxInjectedFrom, runViewerCli, startViewerServer, viewerCliOptions };
+export { type RunnerEntry, type StartViewerOptions, type ViewerHandle, boxInjectedFrom, boxRunnerFrom, runViewerCli, startViewerServer, viewerCliOptions };