@unotest/viewer 0.25.0 → 0.26.1

package/CHANGELOG.md

@@ -1,5 +1,214 @@
 # Changelog
 
+## [0.26.1] - 2026-08-30
+
+### Patch Changes
+
+- Fix: a run started from a box's viewer stayed pending and never reached
+  the history
+
+  The viewer watched the run directories of environments it could see on
+  disk — overlay files `unotest/.env.<name>` and existing `.runs.<name>`
+  directories. A box has neither at start: environment values come from the
+  daemon, not from a file, and the runs directory appears with the first
+  run. So the viewer watched only the base root while every run was filed
+  under `.runs.<environment>`: the tab stayed PENDING, the history stayed
+  empty and the run 404-ed by its own id, until a restart happened to find
+  the directory already there. The environment a viewer was started for is
+  now known to it by definition, whatever the disk says.
+
+- Fix: a run's captured output landed outside the run's directory
+
+  `stdout.log` / `stderr.log` were written to `<runs-root>/<runId>/` while
+  the run itself lives under its date shard — two orphan directories next to
+  the shard, holding the only copy of what the child said.
+
+- Fix: a viewer started for an environment listed no runs at all
+
+  The standalone launcher read the project root, the port, the host and the
+  target from its environment — but not `UNOTEST_ENV`. A box starts one
+  viewer per environment and names it exactly that way, so every one of them
+  came up on the BASE runs directory while its runs were being filed under
+  `.runs.<environment>`: an empty history on a box that had just finished a
+  suite. Found on the first end-to-end run of the local box stand.
+
+- 9424f6b: Fix: screenshots stayed blank in the viewer when runs write to a separate
+  artifact root
+
+  A run whose artifacts do not live under the working directory — every run on
+  a box, where the sources are a disposable copy of a test bundle — emitted
+  `screenshot` events whose path was relativised against the working directory.
+  That came out as `../../../…`, which the viewer's asset route refuses to
+  serve, so every step preview rendered as a broken image. Artifact paths are
+  now relative to the artifact root, which is still the project root on every
+  local run.
+
+  The failure bundle had the mirror-image problem: it was written to
+  `.unotest/failures/` under the working directory, so on a box it landed
+  inside the bundle copy — outside the tree the viewer serves, and discarded on
+  the next bundle push. It now hangs off the artifact root too, which leaves
+  local runs byte-for-byte unchanged.
+
+  The inspector's Semantic DOM, Console, Network and Snapshot panes were dark
+  for a third reason, and this one bit local runs as well: they composed the
+  run's directory in the browser and left out the date shard runs have been
+  filed under since M-10, plus the environment suffix on a box. The viewer's
+  asset route now takes `?file=<name-relative-to-the-run-dir>` and resolves the
+  directory itself — runs root, target suffix, environment suffix and shard are
+  all things only the server knows. `?path=` stays for the whole paths the
+  server ships on run events.
+
+- Updated dependencies [9424f6b]
+  - @unotest/protocol@0.26.1
+  - @unotest/core@0.26.1
+  - @unotest/dsl@0.26.1
+
+## [0.26.0] - 2026-08-30
+
+### Minor Changes
+
+- 3eede7c: The viewer can now be hosted: it shows which test bundle an environment
+  is running, and lets you switch it.
+
+  This is the other half of `bundle push`. Nothing changes for a local
+  viewer — everything here appears only when something is hosting it.
+
+  - **The artifact root and the project root are now genuinely separate.**
+    The viewer already took `UNOTEST_ARTIFACTS_ROOT` for the run queue;
+    run discovery, the run index, snapshots, log capture and the viewer's
+    own lock file now honour it too. Locally the two are the same directory
+    and nothing moves. Where they differ — sources in a disposable copy of a
+    bundle, history in the environment beside it — the history is no longer
+    read out of (or written into) the sources.
+  - **Bundle badge in the status bar.** `main@1a2b3c4`, or `wip` for a
+    bundle packed from an uncommitted tree, with the author, the pinned
+    `@unotest/web` and who switched the environment last. Clicking it lists
+    the bundles pushed to this environment and switches to one — that runs
+    as a maintenance ticket on the host, so it waits for the environment to
+    be free instead of pulling the code out from under a running suite.
+  - **Runs remember their bundle.** `manifest.json` and `GET /api/runs`
+    carry `bundleId` (from `UNOTEST_BUNDLE_ID`, set by the host); the runs
+    list marks the ones that ran on another bundle, so "was this red run
+    even the code I am looking at?" has an answer.
+  - **The contract is a file, not a mode.** `@unotest/protocol` gains
+    `WorkspaceFile` — the host writes `unotest/.workspace.json` beside the
+    artifacts and the viewer reads it, the same way the guard's session
+    header narrows the UI. No file, no bundle UI; the viewer never learns
+    what a box is. Values of environment variables and secrets never appear
+    in it — only their names.
+  - **Queue tickets can name a bundle.** `QueueTicket.source.bundleId` is
+    recorded when a run is queued, so a run executes the code it was
+    ordered with even if the environment moved on while it waited.
+
+- dbfa36f: Your CI can now ask a box to run the suite it just pushed, and a box can
+  report the result back to GitHub.
+
+  ```sh
+  npx @unotest/web bundle push --run --env test --collection smoke
+  ```
+
+  `--run` sends the second half of the CI recipe: upload the bundle, then
+  order a run of it. Two requests rather than one flag on the upload,
+  because a bundle is _content_ — pushing an identical tree twice is normal
+  and answers `exists` — while "run it" is an event. The same split is what
+  lets a deploy script run a bundle somebody pushed hours ago.
+
+  - **The box answers as soon as the runs are queued** (202) with their run
+    ids. A suite takes minutes to hours; an HTTP request held open for that
+    long is a timeout in somebody's proxy, not a result. The ids are real
+    from the moment you get them, so a CI log can print a link into the
+    viewer straight away.
+  - **`--env <name>` is required with `--run`.** Which environments a box
+    has is the operator's decision, and guessing one would be guessing
+    which system gets tested.
+  - **Without `--collection`, the box runs what that environment normally
+    runs** — the collections its `schedules` name. Naming them explicitly is
+    the deploy-check case; leaving it out is the "same as every night" case.
+  - **`--pr <number>` coalesces.** A newer push of the same pull request
+    withdraws its older runs that are still _waiting_; a run that already
+    started is never killed. Three pushes in five minutes cost one suite.
+    `--json` reports how many were withdrawn, so "my run vanished" has an
+    answer in the log of the run that replaced it.
+  - **Refusals are typed and say what to do**: no such environment, an
+    environment belonging to another project, a bundle the box no longer
+    holds, nothing to run.
+
+  On a hosted viewer, the queue panel now names the change each machine
+  ticket belongs to (`PR #412@1a2b3c4`) instead of a row of identical "ci"
+  entries, and the history gained a **this bundle only** filter for the
+  moment you are judging the bundle in front of you rather than the last
+  month of runs.
+
+  Nothing changes for a local `npx @unotest/web viewer`: there are no
+  bundles there, so neither the badge nor the filter appears.
+
+- c43aa00: Runs of one project now take turns instead of colliding.
+
+  Until now nothing coordinated them: the viewer refused a second run with
+  HTTP 409, and that was the whole defence — a `npx @unotest/web e2e` in a
+  terminal, an agent's `run_test` and a scheduled suite would all start on
+  top of each other, driving the same browser and the same seeded database
+  at the same time. The 409 protected the UI, not the machine.
+
+  - **A filesystem queue**, in `unotest/.queue<target>[.<env>]/` beside the
+    runs root it belongs to. A run writes a ticket, waits until it is at
+    the head, takes a slot, runs, and gives the slot back. There is no
+    daemon: whoever holds the slot executes the run itself, so nothing new
+    has to be installed, started or kept alive. Only `open("wx")`, rename,
+    unlink and mtime — no `flock`, which lies on network and container
+    filesystems. A crashed producer is reaped by whoever comes next.
+  - **Every producer is in it**: the CLI (`e2e`, `collection`, `author`),
+    the viewer's Run button, and the MCP `run_test` (which spawns the CLI).
+    A collection is ONE run — its `workers` still run in parallel inside
+    it, because a child process carries its parent's lease and skips the
+    queue.
+  - **The viewer shows the queue**: the Active panel lists what is waiting,
+    including tickets a terminal or an agent wrote, with a button to take
+    any of them back out. `GET /api/queue`, `DELETE /api/queue/:ticket`,
+    and a `queue:changed` websocket message.
+  - **Config**: `queue.concurrency` (default 1) and `queue.enabled`
+    (default true) in `unotest.config`. Both the CLI and the viewer read
+    the same file, so they cannot disagree about how many slots exist.
+  - **Escape hatches**: `UNOTEST_NO_QUEUE=1` runs without queueing;
+    Ctrl-C while waiting gives up your place in line and runs nothing.
+  - **For boxes**: `UNOTEST_QUEUE_GLOBAL_DIR` + `UNOTEST_QUEUE_GLOBAL_SLOTS`
+    add a host-wide budget several environments share (a collection weighs
+    its worker count), and `UNOTEST_ARTIFACTS_ROOT` puts `.runs` / `.queue`
+    somewhere other than the directory the tests live in — so the history
+    outlives a throwaway copy of the tests.
+
+  ### Migration notes
+
+  **`POST /api/run` no longer answers 409.** Ordering a run while another
+  one is active used to fail with `ActiveRunConflictError` (HTTP 409); it
+  now succeeds and the run waits. The response changed shape with it:
+
+  ```diff
+  - { runId, kind, ref, pid, startedAt }
+  + { runId, kind, ref, status: "queued" | "running", ticket, acceptedAt }
+  ```
+
+  `runId` is still final and immediately usable — open the tab on it as
+  before — but the run may not have started yet, and `pid` is not known at
+  that point. `POST /api/runs/:runId/abort` covers both states: it
+  withdraws a waiting ticket or SIGTERMs a running child.
+
+  Anything that treated 409 as "busy, try later" should now simply order
+  the run. Anything that relied on "only one run can exist" should read
+  `GET /api/queue`. To keep the old immediate-start behaviour (without the
+  protection), set `queue.enabled: false`.
+
+### Patch Changes
+
+- Updated dependencies [3eede7c]
+- Updated dependencies [6d1c612]
+- Updated dependencies [dbfa36f]
+- Updated dependencies [c43aa00]
+- Updated dependencies [8ec4177]
+  - @unotest/protocol@0.26.0
+  - @unotest/core@0.26.0
+  - @unotest/dsl@0.26.0
+
 ## [0.25.0] - 2026-08-29
 
 ### Minor Changes

package/dist/server/main.d.ts

@@ -1,5 +1,13 @@
 import { IRunnerAdapter, IDslLanguageService, IProcessLauncher } from '@unotest/protocol';
 
+interface ViewerQueueConfig {
+    /** With queueing off, the viewer starts every run immediately — and
+     *  so does every terminal. Nothing serialises them. */
+    readonly enabled: boolean;
+    /** Runs allowed in flight for one environment. */
+    readonly concurrency: number;
+}
+
 interface RunnerEntry {
     /** Short target id derived from the runner package name —
      *  `web`/`mobile`/`unity`. Drives the UI switcher and per-target tree
@@ -38,6 +46,14 @@ interface StartViewerOptions {
      *  injects its bundled `node` + runner bin so terminal commands resolve
      *  without a system install). */
     terminalPathPrefix?: readonly string[];
+    /** Run-queue policy, read from the project's `unotest.config` by the
+     *  launcher. Omitted (the standalone bin) = the shipped default: queue
+     *  on, one run at a time. Both the viewer and the CLI must see the SAME
+     *  numbers — they share one queue directory. */
+    queue?: ViewerQueueConfig;
+    /** Absolute artifact root when it is not the project root
+     *  (`UNOTEST_ARTIFACTS_ROOT`); see `ViewerConfig.artifactsRoot`. */
+    artifactsRoot?: string;
 }
 interface ViewerHandle {
     url: string;
@@ -57,6 +73,14 @@ declare function startViewerServer(opts: StartViewerOptions): Promise<ViewerHand
  *  the installed `@unotest/*` runner packages (by name — DIP boundary
  *  intact). `UNOTEST_RUNNER_PKG` (legacy single-runner var) and
  *  `UNOTEST_TARGET` just pick which detected target is active at boot. */
+/** Everything the standalone launcher reads from its environment, in one
+ *  pure place so the plumbing is testable without starting a server.
+ *
+ *  `activeEnv` is the one that has bitten: a box starts one viewer per
+ *  environment and says which through `UNOTEST_ENV`. Dropping it left every
+ *  viewer reading the BASE runs directory while its runs were filed under
+ *  `.runs.<env>` — an empty history on a box that had just run a suite. */
+declare function viewerCliOptions(env: NodeJS.ProcessEnv, cwd: string): Omit<StartViewerOptions, "runners">;
 declare function runViewerCli(): Promise<void>;
 
-export { type RunnerEntry, type StartViewerOptions, type ViewerHandle, runViewerCli, startViewerServer };
+export { type RunnerEntry, type StartViewerOptions, type ViewerHandle, runViewerCli, startViewerServer, viewerCliOptions };