@unotest/protocol 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to `@unotest/protocol` are documented in this file.
+
+## [0.5.0] - 2026-05-29
+
+Initial release. Shared protocol types and contracts for the `@unotest`
+ecosystem: `IRunnerAdapter`, `RunArtifact`, `WsMessage`, path constants,
+and `LockFile` types used by `@unotest/web` and `@unotest/viewer`.
+Includes `EnvFile` / `EnvVar` / `EnvUpdate` (viewer env-variable editor)
+and the `ENV_FILE` path constant.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Volkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,30 @@
+# @unotest/protocol
+
+Shared protocol types and contracts for the `@unotest` ecosystem.
+
+Consumed by:
+
+- `@unotest/web` — web (Playwright) test runner
+- `@unotest/mobile` — mobile test runner
+- `@unotest/viewer` — localhost viewer (HTTP + WS)
+
+This package contains **only**:
+
+- TypeScript types (stripped at compile time)
+- String constants (filesystem paths, kind literals)
+- Pure functions (validators, ID builders) that are browser-safe
+
+**No runtime dependencies.** No `node:fs`, no Playwright, no Zod. Anything
+that needs an environment lives in the consumer package — not here.
+
+## Key contracts
+
+- `IRunnerAdapter` — the surface `@unotest/viewer` consumes to start a
+  run without knowing which runner package it's driving. Implementations
+  live in `@unotest/web` and `@unotest/mobile`.
+- `RunRequest` — discriminated union of the run shapes the viewer can
+  ask an adapter to execute.
+- `RunArtifact` / `RunMeta` / `RunManifest` — the on-disk format
+  written by runners under `unotest/.runs/<runId>/`, read by the viewer.
+- `WsMessage` — the typed websocket event protocol from viewer-server
+  to viewer-web.

package/dist/index.d.ts

@@ -0,0 +1,666 @@
+/** User-facing project directory containing scenarios + helpers + collections. */
+declare const UNOTEST_DIR = "unotest";
+/** Subdir under `unotest/` for `.test.js` scenarios. */
+declare const E2E_SUBDIR = "e2e";
+/** Subdir under `unotest/e2e/` for reusable `snake_case` helper files. */
+declare const HELPERS_SUBDIR = "_helpers";
+/** Subdir under `unotest/e2e/` for `.yaml` collection manifests. */
+declare const COLLECTIONS_SUBDIR = "_collections";
+/** Subdir under `unotest/` for runtime run-artifact dirs (`<runId>/`).
+ *  Dot-prefix so a single `.gitignore` line covers all runtime debris
+ *  without touching user code in `unotest/e2e/`. */
+declare const RUNS_SUBDIR = ".runs";
+/** Lockfile path *relative to* `unotest/`. Project-local (multiple viewers
+ *  for different projects coexist). */
+declare const LOCK_FILE = ".viewer.lock";
+/** Server log destination when viewer is spawned detached (no terminal to
+ *  inherit stdout). Relative to `unotest/`. */
+declare const LOG_FILE = ".viewer.log";
+/** Append-only JSONL with `RunArtifact` events; lives at
+ *  `unotest/.runs/<runId>/steps.jsonl`. */
+declare const STEPS_FILE = "steps.jsonl";
+/** mtime-updated periodically by the runner; viewer treats run as
+ *  `interrupted` after `> 30s` without mtime change (per design-v0). */
+declare const HEARTBEAT_FILE = "heartbeat";
+/** Captured child-process stdout when run is spawned by viewer. */
+declare const STDOUT_FILE = "stdout.log";
+/** Captured child-process stderr when run is spawned by viewer. */
+declare const STDERR_FILE = "stderr.log";
+/** Append-only JSONL of `DbgCommand` lines written by viewer/MCP/CLI;
+ *  read by the debug-commands-watcher inside the runner-child. Lives at
+ *  `unotest/.runs/<runId>/commands.jsonl`. */
+declare const COMMANDS_FILE = "commands.jsonl";
+/** Atomically rewritten JSON with the current runtime snapshot (vars,
+ *  callStack, state, lastFailure). Producers: runner-child writes after
+ *  every step / on pause / on resume. Readers: viewer's
+ *  `GET /api/runs/:runId/runtime` and MCP `inspect_runtime`. Distinct
+ *  from the page-snapshot (semantic-DOM YAML) which lives in
+ *  failure-bundles. */
+declare const RUNTIME_FILE = "runtime.json";
+/** Per-project shared breakpoint store. Path is relative to project root
+ *  (NOT under `unotest/.runs/`). Schema: `BreakpointsFile` in
+ *  `protocol/breakpoints-file.ts`. */
+declare const DEBUGGER_FILE = "unotest/.debugger.json";
+/** Project env file edited by the viewer's env-variable editor. Relative
+ *  to project root. Surfaced as `EnvFile` (`protocol/env-file.ts`). */
+declare const ENV_FILE = "unotest/.env";
+
+interface RegexLiteral {
+    readonly kind: "regex";
+    readonly source: string;
+    /** ES5 subset — substring of `gim`, no duplicates. */
+    readonly flags: string;
+}
+/** A field whose runtime accepts either a literal string match or a
+ *  regex matcher (Playwright API convention). */
+type Matcher = string | RegexLiteral;
+declare function isRegexLiteral(v: unknown): v is RegexLiteral;
+/** Build a RegexLiteral from primitive parts. Convenience for tests
+ *  and codegen — the canonical constructor path is `@unotest/dsl`'s
+ *  `RegExpValue` (parsed from `/pattern/flags` syntax). Flag
+ *  validation is intentionally NOT duplicated here: by the time a
+ *  RegexLiteral exists, its flags have already been validated at the
+ *  DSL parse boundary, and re-validation would create two sources of
+ *  truth for the same rule. */
+declare function regexLiteral(source: string, flags?: string): RegexLiteral;
+
+declare function makeRunId(name: string): string;
+/** Strip everything that isn't safe as a directory name segment. Folder
+ *  separators in `name` collapse to `-` so scenario `auth/signin` becomes
+ *  `auth-signin` in the runId. Consecutive dashes collapse to one, and
+ *  leading/trailing dashes are trimmed so a name like `🔥 smoke 🔥` ends
+ *  up as `smoke` rather than `--smoke--`. When the result is empty
+ *  (an all-unicode-emoji name yields no safe characters), we fall back
+ *  to a literal `run` segment — uniqueness still comes from the ts +
+ *  random suffix appended by `makeRunId`. */
+declare function sanitizeRunIdSegment(name: string): string;
+
+/** Filesystem-unsafe characters in a collection name. Block-list approach
+ *  (any Unicode letter is fine — collections can be named in any
+ *  language) bounded by what `posix.join("…", `${name}.yaml`)` must keep
+ *  safe: no path separators, no Windows-reserved punctuation, no NUL /
+ *  control chars. */
+declare const COLLECTION_NAME_FORBIDDEN_RE: RegExp;
+/** Validate a collection name. Returns `null` on success, or a
+ *  human-readable reason string on failure. Shared by the viewer-server
+ *  writer (authoritative) and any client form (pre-flight) so both sides
+ *  agree on what's acceptable. Pure function — safe to bundle in the
+ *  browser. */
+declare function validateCollectionName(name: string): string | null;
+/** Parsed YAML collection manifest from `unotest/e2e/_collections/*.yaml`.
+ *  Per design-v0/decisions.md, Phase 1 keeps the manifest minimal — only
+ *  `description` and `scenarios`. No `parallel`/`env`/`retry`/`timeout`
+ *  fields until a real use-case appears. */
+interface CollectionMeta {
+    /** Filename stem (single source of truth — no `name:` field inside YAML). */
+    name: string;
+    /** Project-relative path to the `.yaml` file. */
+    path: string;
+    /** Optional one-line description from the YAML's top-level `description:`. */
+    description: string | null;
+    /** Scenario names referenced in the YAML's `scenarios:` array. Names are
+     *  scenario-meta `name` values (file stem relative to `e2e/`). Orphan
+     *  references (scenario file missing) are NOT filtered out — the viewer
+     *  surfaces them as red entries with «file not found» tooltip; running
+     *  a collection skips orphans with a warning, not blocks. */
+    scenarios: string[];
+}
+
+/** Run a single scenario by its `name` (file stem under `e2e/`). */
+interface ScenarioRunRequest {
+    kind: "scenario";
+    /** Scenario `name` — file stem relative to `unotest/e2e/`. */
+    scenario: string;
+    /** Run with browser visible (web) / device window visible (mobile).
+     *  Adapter maps this to the runner's preferred env / arg. */
+    headed?: boolean;
+    /** Spawn with debugger enabled (breakpoints from
+     *  `unotest/.debugger.json` + inline override). */
+    debug?: boolean;
+    /** Inline breakpoint override as `"line:col"` strings. Only honored
+     *  when `debug=true`. */
+    breakpoints?: string[];
+}
+/** Run a collection — the runner's CLI orchestrates scenarios inside.
+ *  Viewer doesn't see the per-scenario subprocesses; it sees one direct
+ *  child plus the artifacts each scenario writes to its own `.runs/`
+ *  dir, linked to this parent via `parentRunId` in their manifests. */
+interface CollectionRunRequest {
+    kind: "collection";
+    /** Collection `name` — filename stem under `_collections/`. */
+    collection: string;
+    /** Forward to each child scenario. */
+    headed?: boolean;
+    /** Worker count for parallel scenario execution. Default `1`
+     *  (serial). The adapter passes it to the CLI; the runner enforces. */
+    workers?: number;
+    /** Stop on first failure. Default `false` (continue-on-fail). */
+    bail?: boolean;
+}
+/** Discriminated union of every run-shape the viewer can request. */
+type RunRequest = ScenarioRunRequest | CollectionRunRequest;
+/** All `kind` literals — useful for switch-completeness checks and for
+ *  adapter `supportedKinds` lists. */
+type RunKind = RunRequest["kind"];
+
+declare const RUN_MANIFEST_FILE = "manifest.json";
+interface RunManifest {
+    /** Format-version of this manifest. Bump only on breaking schema
+     *  changes — additive optional fields don't require it. Starts at 1. */
+    schemaVersion: 1;
+    /** Identifies which RunRequest variant produced this run. */
+    kind: RunKind;
+    /** Original (un-sanitized) `ref` from the request — scenario `name`
+     *  for `kind:"scenario"`, collection `name` for `kind:"collection"`.
+     *  The `runId` directory uses a sanitized form; this carries the
+     *  human-readable original. */
+    ref: string;
+    /** Run-id of the parent collection-run when this is a child scenario
+     *  spawned inside a collection. Absent for top-level scenario-runs
+     *  and for collection-runs themselves. */
+    parentRunId?: string;
+    /** Adapter `name` that produced this run (`"@unotest/web"`,
+     *  `"@unotest/mobile"`). Lets the viewer pick rendering details for
+     *  runner-specific bundle contents without runner branches in core
+     *  logic. */
+    adapter: string;
+    /** Wallclock at runner start. Distinct from the first event's `t`
+     *  (which may have leading delay for adapter setup). */
+    startedAt: number;
+}
+
+/** The argv/env builder for a specific runner CLI. Pure functions —
+ *  no spawning, no fs access. The viewer owns the actual subprocess
+ *  lifecycle; the adapter merely tells it WHAT to spawn. */
+interface IRunnerAdapter {
+    /** Human-readable identity for logs and error messages
+     *  (e.g. `"@unotest/web"`). NOT used for control flow — viewer
+     *  must not branch on this. */
+    readonly name: string;
+    /** Which `RunRequest.kind` values this adapter can handle. Viewer
+     *  rejects unsupported kinds with `UnsupportedRunKindError` before
+     *  building argv. */
+    readonly supportedKinds: ReadonlyArray<RunKind>;
+    /** Absolute path to the bin entry that should be spawned with the
+     *  current Node binary: `spawn(process.execPath, [resolveBin(), ...buildArgs(req)])`.
+     *  Throws if the runner package isn't installed reachably from the
+     *  viewer's project root. */
+    resolveBin(): string;
+    /** Argv to pass after the bin path. Pure — depends only on `req`.
+     *  Example for web: `["e2e", "smoke", "--debug", "--break", "10:4"]`. */
+    buildArgs(req: RunRequest): string[];
+    /** Environment overrides merged on top of `process.env` by the
+     *  caller. Pure — no `process.env` reads here. Example for web:
+     *  `{ UNOTEST_HEADED: "1" }`. Worker-isolation env
+     *  (`UNOTEST_WORKER_INDEX/COUNT`) is NOT the adapter's
+     *  responsibility — see `D-C4` in the collections plan. */
+    buildEnv(req: RunRequest): NodeJS.ProcessEnv;
+}
+/** Thrown by the viewer when a `RunRequest.kind` isn't in the
+ *  adapter's `supportedKinds`. The exception filter maps to HTTP 400
+ *  with the kind name + adapter name in the message. */
+declare class UnsupportedRunKindError extends Error {
+    constructor(kind: RunKind, adapterName: string);
+}
+/** Thrown by the viewer when the configured runner package can't be
+ *  located on disk. Message names the package + how to install. */
+declare class RunnerAdapterNotFoundError extends Error {
+    constructor(packageName: string, hint: string);
+}
+/** Thrown by the viewer when `unotest.config.*` doesn't declare a
+ *  `runner:` field. Surfaces what packages exist so the user can
+ *  pick. */
+declare class RunnerNotConfiguredError extends Error {
+    constructor(message: string);
+}
+
+/** Session profile — the kind of process a tab spawns. Mirrored by the
+ *  viewer's TerminalStore.TermKind. */
+type TerminalKind = "local" | "claude" | "codex";
+interface TerminalSpawnMessage {
+    type: "spawn";
+    id: string;
+    kind: TerminalKind;
+    cols: number;
+    rows: number;
+}
+interface TerminalDataMessage {
+    type: "data";
+    id: string;
+    /** Raw bytes the user typed, forwarded to the PTY stdin. */
+    data: string;
+}
+interface TerminalResizeMessage {
+    type: "resize";
+    id: string;
+    cols: number;
+    rows: number;
+}
+interface TerminalCloseMessage {
+    type: "close";
+    id: string;
+}
+type TerminalClientMessage = TerminalSpawnMessage | TerminalDataMessage | TerminalResizeMessage | TerminalCloseMessage;
+interface TerminalOutputMessage {
+    type: "output";
+    id: string;
+    /** Raw PTY stdout/stderr bytes to write to the xterm instance. */
+    data: string;
+}
+interface TerminalExitMessage {
+    type: "exit";
+    id: string;
+    exitCode: number | null;
+}
+/** Spawn failure (e.g. `claude` not on PATH) reported to the tab so it can
+ *  print a friendly line instead of silently dying. */
+interface TerminalErrorMessage {
+    type: "error";
+    id: string;
+    message: string;
+}
+type TerminalServerMessage = TerminalOutputMessage | TerminalExitMessage | TerminalErrorMessage;
+/** The `ws` adapter routes inbound messages by an `event` envelope; both
+ *  directions use this single event name on `/ws/terminal`. */
+declare const TERMINAL_WS_EVENT = "terminal";
+
+/** Contents of `unotest/.viewer.lock`. Written by viewer-server on
+ *  startup, removed on graceful shutdown. Stale detection: `process.kill(
+ *  pid, 0)` throws ESRCH if PID is dead → lockfile is stale, safe to
+ *  overwrite. */
+interface LockFile {
+    /** PID of the viewer-server process. */
+    pid: number;
+    /** Full URL (with port) to reach the viewer. e.g. `http://localhost:5173`. */
+    url: string;
+    /** ISO 8601 timestamp of `pid` start. Used for tie-breaking and stale-age
+     *  heuristics if `kill(pid, 0)` is inconclusive. */
+    startedAt: string;
+}
+
+/** Parsed scenario metadata from the mandatory header lines
+ *  (per design-v0/decisions.md, "Test source format"):
+ *
+ *      // id-<kebab-slug>
+ *      // <human title>
+ *      // #<6-hex-color>
+ *      function test_<...>() { ... }
+ *
+ *  All three lines are required; a file without a complete header is
+ *  rejected by the discovery service as parse-error (no legacy fallback). */
+interface ScenarioMeta {
+    /** Slug from `// id-<slug>`. Stable test identity across rename. */
+    id: string;
+    /** Human-readable title from `// <text>`. */
+    title: string;
+    /** Color identifier from `// #RRGGBB`. Used only in tab headers as a
+     *  thin colored strip — NOT a status signal. */
+    color: string;
+    /** File stem relative to `unotest/e2e/`, dirs as slashes.
+     *  Examples: `smoke-welcome`, `auth/signin-flow`.
+     *  Source-of-truth identity for CLI invocations and tab keys. */
+    name: string;
+    /** Project-relative path to the source file. */
+    path: string;
+}
+
+/** Helper file metadata. Helpers live in `unotest/e2e/_helpers/**` as
+ *  `snake_case` functions (`signin_as`, `seed_user`, …). The runner
+ *  auto-discovers them; no import system in scenarios. */
+interface HelperMeta {
+    /** File stem relative to `_helpers/`, dirs as slashes. */
+    name: string;
+    /** Project-relative path to the source file. */
+    path: string;
+}
+
+/** Terminal outcome reported by the runner via `run:finished`. */
+type RunOutcome = "completed" | "failed" | "aborted" | "interrupted";
+/** Scenario-level run-id. Format opaque to consumers; treat as string. */
+type RunId = string;
+/** Common fields on every event. */
+interface RunArtifactBase {
+    /** Wallclock timestamp (Date.now()) at emit. */
+    t: number;
+}
+interface RunStartedEvent extends RunArtifactBase {
+    kind: "run:started";
+    /** Same as the `<runId>` directory name; included for self-describing
+     *  events when reassembled out-of-band. */
+    runId: RunId;
+    /** Scenario `name` (file stem relative to `e2e/`). */
+    scenario: string;
+}
+interface StepStartedEvent extends RunArtifactBase {
+    kind: "step:started";
+    /** Line number of the DSL call in the source file (1-indexed). */
+    line: number;
+    /** Column number (0-indexed). */
+    col: number;
+    /** Source text of the statement (e.g. `goto("https://…")`). */
+    text: string;
+}
+interface StepOkEvent extends RunArtifactBase {
+    kind: "step:ok";
+    /** Wall-clock duration of the step that just finished. */
+    durationMs: number;
+}
+interface StepFailEvent extends RunArtifactBase {
+    kind: "step:fail";
+    /** Human-readable error message (single line preferred). */
+    error: string;
+    /** Error class name (e.g. `"AssertionError"`, `"LocatorError"`,
+     *  `"TimeoutError"`). Lets the viewer's `ErrorCard` show a typed
+     *  pill instead of a generic "Error" label. Optional because some
+     *  thrown errors lack a meaningful class name. */
+    errorName?: string;
+    /** Project-relative path to a Playwright trace zip, if captured. */
+    trace?: string;
+}
+interface ScreenshotEvent extends RunArtifactBase {
+    kind: "screenshot";
+    /** Project-relative path to the PNG (under `unotest/.runs/<runId>/screenshot/`). */
+    path: string;
+}
+/** Emitted ONCE after a failing run when the runner has finished writing
+ *  the D-16 failure bundle to disk. Viewer's inspector reads
+ *  `bundlePath` to fetch artifacts (screenshot, semantic DOM, network,
+ *  trace) via `/api/runs/<runId>/asset?path=...`. The bundle directory
+ *  is keyed by its own id (`<scenario>__<isoDate>__<stepIdx>`) under
+ *  `.unotest/failures/`, not under `unotest/.runs/`, because the
+ *  bundle layout pre-dates per-run dirs and is still consumed by the
+ *  agent-fix MCP tools. */
+interface FailureBundleWrittenEvent extends RunArtifactBase {
+    kind: "failure-bundle:written";
+    /** Project-relative path to the bundle directory. */
+    bundlePath: string;
+    /** Project-relative path to the screenshot PNG inside the bundle,
+     *  when tier-2 capture succeeded. */
+    screenshotPath?: string;
+}
+interface RunFinishedEvent extends RunArtifactBase {
+    kind: "run:finished";
+    outcome: RunOutcome;
+}
+/** Debugger pause. Reason discriminates:
+ *   - `breakpoint` — executor halted before a statement whose `line:col` is
+ *     in `RunOptions.breakpoints`.
+ *   - `step` — `pauseRequested` flag was set by a `pause` debug command,
+ *     or the run was started in step-mode and just completed a statement.
+ *   - `failure` — executor caught an error and `pauseOnFailure` is true.
+ *
+ *  When the runner is hosting a debug session it also writes a parallel
+ *  `runtime.json` file with the same snapshot. The snapshot is included
+ *  inline here for replay / single-frame consumers that don't want to do a
+ *  separate fs read. */
+interface PausedEvent extends RunArtifactBase {
+    kind: "paused";
+    reason: "breakpoint" | "step" | "failure";
+    line: number;
+    col: number;
+    /** Inline snapshot of the runtime state at the pause point. `vars` is
+     *  per-value JSON-stringified (LocatorValue → "<Locator role=... name=...>"
+     *  human-readable string) and per-var truncated to 4KB to keep the JSONL
+     *  line manageable. `callStack` is outermost→innermost user-function frames. */
+    snapshot?: {
+        vars: Record<string, string>;
+        callStack: {
+            fn: string;
+            file: string;
+            line: number;
+        }[];
+    };
+}
+/** Emitted when execution resumes after a `paused` event. The `by` field
+ *  records which debug command unblocked it — purely informational; the
+ *  next `step:started` event carries the actual line/col. */
+interface ResumedEvent extends RunArtifactBase {
+    kind: "resumed";
+    by: "step" | "continue";
+}
+/** Discriminated union of every JSONL event the scenario runner emits. */
+type RunArtifact = RunStartedEvent | StepStartedEvent | StepOkEvent | StepFailEvent | ScreenshotEvent | FailureBundleWrittenEvent | PausedEvent | ResumedEvent | RunFinishedEvent;
+interface CollectionRunStartedEvent extends RunArtifactBase {
+    kind: "collection-run:started";
+    runId: RunId;
+    /** Collection `name` (filename stem). */
+    collection: string;
+    /** Scenario names that will be executed, in order. */
+    scenarios: string[];
+}
+interface CollectionScenarioStartedEvent extends RunArtifactBase {
+    kind: "collection-run:scenario-started";
+    /** The scenario-run-id created when this scenario started executing. */
+    scenarioRunId: RunId;
+    scenario: string;
+}
+interface CollectionScenarioFinishedEvent extends RunArtifactBase {
+    kind: "collection-run:scenario-finished";
+    scenarioRunId: RunId;
+    scenario: string;
+    outcome: RunOutcome;
+}
+interface CollectionRunFinishedEvent extends RunArtifactBase {
+    kind: "collection-run:finished";
+    outcome: RunOutcome;
+}
+type CollectionRunArtifact = CollectionRunStartedEvent | CollectionScenarioStartedEvent | CollectionScenarioFinishedEvent | CollectionRunFinishedEvent;
+
+/** Lifecycle stage as inferred by the server when listing runs. */
+type RunStatus = "running" | "passed" | "failed" | "aborted" | "interrupted";
+interface RunMeta {
+    runId: RunId;
+    kind: RunKind;
+    /** Scenario `name` (file stem under `e2e/`) for `kind:"scenario"`,
+     *  collection `name` (yaml stem) for `kind:"collection"`. */
+    ref: string;
+    /** Wallclock from the `run:started` event. */
+    startedAt: number;
+    /** Wallclock from the `run:finished` event, or null if still active. */
+    finishedAt: number | null;
+    /** Total wall-clock duration, or null if still running. */
+    durationMs: number | null;
+    /** Status derived from outcome / liveness — `running` while the run's
+     *  heartbeat is fresh and no `run:finished` has landed. */
+    status: RunStatus;
+    /** Terminal outcome from `run:finished`, or null if still running. */
+    outcome: RunOutcome | null;
+    /** Run-id of the parent collection-run when this is a child scenario
+     *  spawned inside one. Absent for top-level scenarios and for
+     *  collection-runs themselves. Populated by the writer from the
+     *  child's `manifest.json`. */
+    parentRunId?: string;
+}
+
+interface FsScenariosChangedMessage {
+    kind: "fs:scenarios-changed";
+}
+interface FsHelpersChangedMessage {
+    kind: "fs:helpers-changed";
+}
+interface FsCollectionsChangedMessage {
+    kind: "fs:collections-changed";
+}
+/** Emitted when `unotest/.debugger.json` is written by anyone (viewer
+ *  via PUT /api/breakpoints, MCP, CLI). The client's BreakpointsStore
+ *  refetches via GET /api/breakpoints so all open tabs converge on the
+ *  same BP set. */
+interface FsBreakpointsChangedMessage {
+    kind: "fs:bp-changed";
+}
+/** Emitted when a new `unotest/.runs/<runId>/` directory appears. The
+ *  browser fetches `/api/runs/<runId>` for the full snapshot. */
+interface FsRunStartedMessage {
+    kind: "fs:run-started";
+    runId: RunId;
+    scenario: string;
+}
+/** Emitted on every appended line of `unotest/.runs/<runId>/steps.jsonl`.
+ *  `event` is the parsed line. */
+interface FsRunStepMessage {
+    kind: "fs:run-step";
+    runId: RunId;
+    event: RunArtifact;
+}
+/** Same as `fs:run-step` but for collection-run-level events. */
+interface FsCollectionRunStepMessage {
+    kind: "fs:collection-run-step";
+    runId: RunId;
+    event: CollectionRunArtifact;
+}
+/** Emitted when the run's `steps.jsonl` is closed (last event was
+ *  `run:finished`) OR the heartbeat goes stale (>30s without mtime
+ *  change — viewer infers `interrupted`). */
+interface FsRunFinishedMessage {
+    kind: "fs:run-finished";
+    runId: RunId;
+    outcome: RunOutcome;
+}
+/** A single line of stdout or stderr captured from a runner child the
+ *  viewer-server spawned. Logs always carry a `runId` so the browser
+ *  attaches them to the right run-pane. */
+interface LogLineMessage {
+    kind: "log:line";
+    runId: RunId;
+    stream: "stdout" | "stderr";
+    line: string;
+}
+/** Non-fatal server error surfaced to the browser (e.g. unexpected file
+ *  format, watcher restart, child-spawn failure). Fatal server crashes
+ *  drop the WS — the browser reconnects and resyncs via REST. */
+interface ErrorMessage {
+    kind: "error";
+    message: string;
+}
+/** Discriminated union of every WS message the server emits to clients. */
+type WsMessage = FsScenariosChangedMessage | FsHelpersChangedMessage | FsCollectionsChangedMessage | FsBreakpointsChangedMessage | FsRunStartedMessage | FsRunStepMessage | FsCollectionRunStepMessage | FsRunFinishedMessage | LogLineMessage | ErrorMessage;
+/** All WS message `kind` literals as a union type — useful for handler
+ *  registries (`Record<WsMessageKind, Handler>`). */
+type WsMessageKind = WsMessage["kind"];
+
+/** Open scenario source (read-only view). Keyed by project-relative path. */
+interface ScenarioTab {
+    kind: "scenario";
+    path: string;
+}
+/** Open helper source. */
+interface HelperTab {
+    kind: "helper";
+    path: string;
+}
+/** Open collection manifest (with scenarios list + Run button). */
+interface CollectionTab {
+    kind: "collection";
+    path: string;
+}
+/** Open scenario-run (live or historical). */
+interface ScenarioRunTab {
+    kind: "scenario-run";
+    runId: RunId;
+}
+/** Open collection-run (wraps N scenario-runs). */
+interface CollectionRunTab {
+    kind: "collection-run";
+    runId: RunId;
+}
+/** Discriminated union of every open-tab shape the frontend supports. */
+type TabKind = ScenarioTab | HelperTab | CollectionTab | ScenarioRunTab | CollectionRunTab;
+/** All tab `kind` literals — useful for switch-completeness checks. */
+type TabKindName = TabKind["kind"];
+
+interface DbgCommandStep {
+    id: string;
+    cmd: "step";
+}
+interface DbgCommandContinue {
+    id: string;
+    cmd: "continue";
+}
+interface DbgCommandPause {
+    id: string;
+    cmd: "pause";
+}
+interface DbgCommandSetBp {
+    id: string;
+    cmd: "set-bp";
+    line: number;
+    col: number;
+}
+interface DbgCommandClearBp {
+    id: string;
+    cmd: "clear-bp";
+    line: number;
+    col: number;
+}
+interface DbgCommandAbort {
+    id: string;
+    cmd: "abort";
+}
+type DbgCommand = DbgCommandStep | DbgCommandContinue | DbgCommandPause | DbgCommandSetBp | DbgCommandClearBp | DbgCommandAbort;
+type DbgCommandKind = DbgCommand["cmd"];
+
+interface BreakpointEntry {
+    line: number;
+    col: number;
+}
+interface BreakpointsFile {
+    version: 1;
+    scenarios: Record<string, BreakpointEntry[]>;
+}
+
+interface EnvVar {
+    key: string;
+    value: string;
+    /** Mask in the UI (key looks like a credential). Value is still sent. */
+    secret: boolean;
+    /** Render an on/off toggle — value is exactly `"0"` or `"1"`. */
+    bool: boolean;
+    /** The line is commented out (`# KEY=VALUE`) — inactive. Shown dimmed and
+     *  read-only; never written back (stays a comment). */
+    commented: boolean;
+}
+interface EnvFile {
+    version: 1;
+    vars: EnvVar[];
+}
+/** PUT body — only values change; keys are fixed by the `.env` file. */
+interface EnvUpdate {
+    version: 1;
+    values: Record<string, string>;
+}
+
+type RuntimeState = "starting" | "running" | "paused-step" | "paused-failure" | "paused-breakpoint" | "completed" | "failed" | "aborted";
+interface RuntimeStateFile {
+    runId: string;
+    scenario: string;
+    testFn: string;
+    state: RuntimeState;
+    /** Current AST node location while running or paused; null in terminal
+     *  states (completed/failed/aborted). */
+    current: {
+        line: number;
+        col: number;
+    } | null;
+    /** Per-value JSON-stringified vars. Locator values render as
+     *  human-readable strings. Per-var truncated to 4KB. */
+    vars: Record<string, string>;
+    /** User-function frames outermost→innermost. Empty when at top level. */
+    callStack: {
+        fn: string;
+        file: string;
+        line: number;
+    }[];
+    lastFailure: {
+        line: number;
+        col: number;
+        error: {
+            message: string;
+            name?: string;
+        };
+    } | null;
+    /** Wallclock timestamp of the last write — readers use this to detect
+     *  staleness (e.g. ≥30s without update ⇒ runner died). */
+    updatedAt: number;
+}
+
+export { type BreakpointEntry, type BreakpointsFile, COLLECTIONS_SUBDIR, COLLECTION_NAME_FORBIDDEN_RE, COMMANDS_FILE, type CollectionMeta, type CollectionRunArtifact, type CollectionRunFinishedEvent, type CollectionRunRequest, type CollectionRunStartedEvent, type CollectionRunTab, type CollectionScenarioFinishedEvent, type CollectionScenarioStartedEvent, type CollectionTab, DEBUGGER_FILE, type DbgCommand, type DbgCommandAbort, type DbgCommandClearBp, type DbgCommandContinue, type DbgCommandKind, type DbgCommandPause, type DbgCommandSetBp, type DbgCommandStep, E2E_SUBDIR, ENV_FILE, type EnvFile, type EnvUpdate, type EnvVar, type ErrorMessage, type FailureBundleWrittenEvent, type FsBreakpointsChangedMessage, type FsCollectionRunStepMessage, type FsCollectionsChangedMessage, type FsHelpersChangedMessage, type FsRunFinishedMessage, type FsRunStartedMessage, type FsRunStepMessage, type FsScenariosChangedMessage, HEARTBEAT_FILE, HELPERS_SUBDIR, type HelperMeta, type HelperTab, type IRunnerAdapter, LOCK_FILE, LOG_FILE, type LockFile, type LogLineMessage, type Matcher, type PausedEvent, RUNS_SUBDIR, RUNTIME_FILE, RUN_MANIFEST_FILE, type RegexLiteral, type ResumedEvent, type RunArtifact, type RunFinishedEvent, type RunId, type RunKind, type RunManifest, type RunMeta, type RunOutcome, type RunRequest, type RunStartedEvent, type RunStatus, RunnerAdapterNotFoundError, RunnerNotConfiguredError, type RuntimeState, type RuntimeStateFile, STDERR_FILE, STDOUT_FILE, STEPS_FILE, type ScenarioMeta, type ScenarioRunRequest, type ScenarioRunTab, type ScenarioTab, type ScreenshotEvent, type StepFailEvent, type StepOkEvent, type StepStartedEvent, TERMINAL_WS_EVENT, type TabKind, type TabKindName, type TerminalClientMessage, type TerminalCloseMessage, type TerminalDataMessage, type TerminalErrorMessage, type TerminalExitMessage, type TerminalKind, type TerminalOutputMessage, type TerminalResizeMessage, type TerminalServerMessage, type TerminalSpawnMessage, UNOTEST_DIR, UnsupportedRunKindError, type WsMessage, type WsMessageKind, isRegexLiteral, makeRunId, regexLiteral, sanitizeRunIdSegment, validateCollectionName };

package/dist/index.js

@@ -0,0 +1 @@
+var _0x4525cf=_0x4e04;(function(_0x5d6d49,_0x1dfb67){var _0x2c662e={_0x34fbd2:0x174},_0x10ba75=_0x4e04,_0x32a0df=_0x5d6d49();while(!![]){try{var _0x2391dd=-parseInt(_0x10ba75(0x178))/0x1*(parseInt(_0x10ba75(0x192))/0x2)+-parseInt(_0x10ba75(0x183))/0x3+parseInt(_0x10ba75(0x176))/0x4*(parseInt(_0x10ba75(0x193))/0x5)+parseInt(_0x10ba75(0x17a))/0x6+-parseInt(_0x10ba75(0x18e))/0x7+parseInt(_0x10ba75(0x180))/0x8+parseInt(_0x10ba75(_0x2c662e._0x34fbd2))/0x9;if(_0x2391dd===_0x1dfb67)break;else _0x32a0df['push'](_0x32a0df['shift']());}catch(_0x347c47){_0x32a0df['push'](_0x32a0df['shift']());}}}(_0x1828,0xcefba));var __defProp=Object[_0x4525cf(0x17e)],__name=(_0x1dec4e,_0x3c2462)=>__defProp(_0x1dec4e,_0x4525cf(0x189),{'value':_0x3c2462,'configurable':!![]}),UNOTEST_DIR=_0x4525cf(0x17f),E2E_SUBDIR=_0x4525cf(0x19d),HELPERS_SUBDIR=_0x4525cf(0x19a),COLLECTIONS_SUBDIR='_collections',RUNS_SUBDIR=_0x4525cf(0x195),LOCK_FILE=_0x4525cf(0x186),LOG_FILE=_0x4525cf(0x17b),STEPS_FILE=_0x4525cf(0x191),HEARTBEAT_FILE='heartbeat',STDOUT_FILE=_0x4525cf(0x19c),STDERR_FILE=_0x4525cf(0x175),COMMANDS_FILE='commands.jsonl',RUNTIME_FILE='runtime.json',DEBUGGER_FILE=_0x4525cf(0x1a1),ENV_FILE=_0x4525cf(0x199);function isRegexLiteral(_0xa7c839){var _0x20ac3a={_0x44f337:0x18d,_0x2eaa9d:0x19f,_0x3e8409:0x196},_0x59e1c8=_0x4525cf;return typeof _0xa7c839==='object'&&_0xa7c839!==null&&_0xa7c839[_0x59e1c8(_0x20ac3a._0x44f337)]===_0x59e1c8(0x194)&&typeof _0xa7c839[_0x59e1c8(_0x20ac3a._0x2eaa9d)]===_0x59e1c8(0x187)&&typeof _0xa7c839[_0x59e1c8(_0x20ac3a._0x3e8409)]===_0x59e1c8(0x187);}__name(isRegexLiteral,'isRegexLiteral');function regexLiteral(_0x1f5378,_0x274fdd=''){return{'kind':'regex','source':_0x1f5378,'flags':_0x274fdd};}function _0x1828(){var _0x10562d=['y2fUBM90igXVywqGCNvUBMvYigfKyxb0zxiGiG','BgvUz3rO','zgvMAw5LuhjVCgvYDhK','Dw5VDgvZDa','oteXnZeZnKjNAfrpEa','DgvYBwLUywW','uNvUBMvYtM90q29UzMLNDxjLzevYCM9Y','ndm3mdqZzfvyuhj4','DhjPBq','BxvZDcbUB3qGyMuGiI4Iig9YiciUlIi','lNzPzxDLCI5SB2nR','C3rYAw5N','BxvZDcbUB3qGyMuGzw1WDhK','BMfTzq','BwfUAwzLC3qUANnVBG','iI4G','BwfRzvj1BKLK','A2LUza','mte3mJGZmZjSrwrjz0i','CNvU','CMvWBgfJzq','C3rLChmUANnVBMW','mZuZmJzfrwD4D3O','mtC4ndbgBMPrzfq','CMvNzxG','lNj1BNm','zMXHz3m','BxvZDcbIzsbHihn0CMLUzW','Dg9tDhjPBMC','Dw5VDgvZDc8Uzw52','x2HLBhbLCNm','BxvZDcbUB3qGy29UDgfPBIbCic8GoIaQid8GiIa8id4GFcbVCIbJB250CM9SignOyxjHy3rLCNm','C3rKB3v0lMXVzW','ztjL','DMfSAwrHDgvdB2XSzwn0Aw9UtMfTzq','C291CMnL','iIbKB2vZig5VDcbZDxbWB3j0ihj1BIbRAw5Kici','Dw5VDgvZDc8UzgvIDwDNzxiUANnVBG','uNvUBMvYqwrHChrLCK5VDezVDw5KrxjYB3i','mtiWndaWntz6AhfqqvK','C3rKzxjYlMXVzW','mtq2ogLcCgDyta','vw5ZDxbWB3j0zwrsDw5lAw5KrxjYB3i','nZHzDMnAuKO','CNvUBMvYici','mtu1odC0nKHNsNzftG','lNzPzxDLCI5SB2C'];_0x1828=function(){return _0x10562d;};return _0x1828();}__name(regexLiteral,'regexLiteral');var RAND_BYTES=0x3;function makeRunId(_0x3bad09){var _0x5b7e24={_0x5ed313:0x17d},_0x41b7df=_0x4525cf;const _0x22e4c8=sanitizeRunIdSegment(_0x3bad09),_0x329de1=Date['now']()[_0x41b7df(0x198)](0x24),_0x35ac39=new Uint8Array(RAND_BYTES);globalThis['crypto']['getRandomValues'](_0x35ac39);let _0x1296e0='';for(let _0x5f1022=0x0;_0x5f1022<_0x35ac39[_0x41b7df(_0x5b7e24._0x5ed313)];_0x5f1022++){_0x1296e0+=_0x35ac39[_0x5f1022][_0x41b7df(0x198)](0x10)['padStart'](0x2,'0');}return _0x22e4c8+'-'+_0x329de1+'-'+_0x1296e0;}__name(makeRunId,_0x4525cf(0x18c));function sanitizeRunIdSegment(_0x485dc8){var _0x129427={_0x29d8c3:0x190},_0x3fe6f1=_0x4525cf;const _0x205fe5=_0x485dc8[_0x3fe6f1(_0x129427._0x29d8c3)](/[^a-zA-Z0-9_-]+/g,'-')[_0x3fe6f1(0x190)](/-+/g,'-')[_0x3fe6f1(0x190)](/^-|-$/g,'');return _0x205fe5[_0x3fe6f1(0x17d)]>0x0?_0x205fe5:_0x3fe6f1(0x18f);}__name(sanitizeRunIdSegment,'sanitizeRunIdSegment');function _0x4e04(_0x1da389,_0x465bf7){_0x1da389=_0x1da389-0x174;var _0x182894=_0x1828();var _0x4e04bf=_0x182894[_0x1da389];if(_0x4e04['NSkCTR']===undefined){var _0x3d6318=function(_0x4cae78){var _0x4e6c75='abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789+/=';var _0x1dec4e='',_0x3c2462='';for(var _0xa7c839=0x0,_0x1f5378,_0x274fdd,_0x3bad09=0x0;_0x274fdd=_0x4cae78['charAt'](_0x3bad09++);~_0x274fdd&&(_0x1f5378=_0xa7c839%0x4?_0x1f5378*0x40+_0x274fdd:_0x274fdd,_0xa7c839++%0x4)?_0x1dec4e+=String['fromCharCode'](0xff&_0x1f5378>>(-0x2*_0xa7c839&0x6)):0x0){_0x274fdd=_0x4e6c75['indexOf'](_0x274fdd);}for(var _0x22e4c8=0x0,_0x329de1=_0x1dec4e['length'];_0x22e4c8<_0x329de1;_0x22e4c8++){_0x3c2462+='%'+('00'+_0x1dec4e['charCodeAt'](_0x22e4c8)['toString'](0x10))['slice'](-0x2);}return decodeURIComponent(_0x3c2462);};_0x4e04['zOLaWv']=_0x3d6318,_0x4e04['FehDCm']={},_0x4e04['NSkCTR']=!![];}var _0x5da670=_0x182894[0x0],_0x16228f=_0x1da389+_0x5da670,_0x3b083e=_0x4e04['FehDCm'][_0x16228f];return!_0x3b083e?(_0x4e04bf=_0x4e04['zOLaWv'](_0x4e04bf),_0x4e04['FehDCm'][_0x16228f]=_0x4e04bf):_0x4e04bf=_0x3b083e,_0x4e04bf;}var COLLECTION_NAME_FORBIDDEN_RE=/[\\/:*?"<>|\x00-\x1f]/;function validateCollectionName(_0x391586){var _0x535afd={_0x13bc86:0x197,_0x4eb493:0x185,_0x19d9cc:0x19b},_0x46cbdf=_0x4525cf;if(typeof _0x391586!==_0x46cbdf(0x187))return _0x46cbdf(_0x535afd._0x13bc86);const _0x25e716=_0x391586[_0x46cbdf(0x184)]();if(_0x25e716[_0x46cbdf(0x17d)]===0x0)return _0x46cbdf(0x188);if(_0x25e716==='.'||_0x25e716==='..')return _0x46cbdf(_0x535afd._0x4eb493);if(_0x25e716['startsWith']('.'))return'must\x20not\x20start\x20with\x20\x27.\x27';if(COLLECTION_NAME_FORBIDDEN_RE['test'](_0x25e716))return _0x46cbdf(_0x535afd._0x19d9cc);return null;}__name(validateCollectionName,_0x4525cf(0x19e));var RUN_MANIFEST_FILE=_0x4525cf(0x18a),UnsupportedRunKindError=class extends Error{static{__name(this,_0x4525cf(0x177));}constructor(_0x435e97,_0x6b153a){var _0x5b3768={_0x68d67e:0x177},_0x58838f=_0x4525cf;super(_0x58838f(0x179)+_0x6b153a+_0x58838f(0x1a0)+_0x435e97+'\x22'),this['name']=_0x58838f(_0x5b3768._0x68d67e);}},RunnerAdapterNotFoundError=class extends Error{static{__name(this,_0x4525cf(0x1a2));}constructor(_0x16bd7d,_0x3710c9){var _0x5c8352={_0x3ceb84:0x17c},_0x251254=_0x4525cf;super(_0x251254(_0x5c8352._0x3ceb84)+_0x16bd7d+_0x251254(0x18b)+_0x3710c9),this[_0x251254(0x189)]='RunnerAdapterNotFoundError';}},RunnerNotConfiguredError=class extends Error{static{__name(this,_0x4525cf(0x182));}constructor(_0x24c564){var _0x33cbe1={_0x5a8eb9:0x189},_0x17c861=_0x4525cf;super(_0x24c564),this[_0x17c861(_0x33cbe1._0x5a8eb9)]=_0x17c861(0x182);}},TERMINAL_WS_EVENT=_0x4525cf(0x181);export{COLLECTIONS_SUBDIR,COLLECTION_NAME_FORBIDDEN_RE,COMMANDS_FILE,DEBUGGER_FILE,E2E_SUBDIR,ENV_FILE,HEARTBEAT_FILE,HELPERS_SUBDIR,LOCK_FILE,LOG_FILE,RUNS_SUBDIR,RUNTIME_FILE,RUN_MANIFEST_FILE,RunnerAdapterNotFoundError,RunnerNotConfiguredError,STDERR_FILE,STDOUT_FILE,STEPS_FILE,TERMINAL_WS_EVENT,UNOTEST_DIR,UnsupportedRunKindError,isRegexLiteral,makeRunId,regexLiteral,sanitizeRunIdSegment,validateCollectionName};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@unotest/protocol",
+  "version": "0.5.0",
+  "description": "Cross-runner protocol for the @unotest ecosystem: shared TypeScript types, path constants, the IRunnerAdapter contract that lets @unotest/viewer drive @unotest/web, @unotest/mobile (and future runners) through the same surface. Pure types + pure functions only — zero runtime deps, browser-safe.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Ivan Volkov <ivan@volkov.io>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unotest/protocol.git"
+  },
+  "type": "module",
+  "packageManager": "pnpm@10.12.4",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test --test-reporter=spec 'src/**/*.test.ts'",
+    "compile": "tsup",
+    "verify": "pnpm typecheck && pnpm test",
+    "obfuscate": "node scripts/obfuscate.mjs",
+    "build": "pnpm verify && pnpm compile && pnpm obfuscate && pnpm check:tarball",
+    "prepublishOnly": "pnpm build",
+    "check:no-cyrillic": "node scripts/check-no-cyrillic.mjs",
+    "check:no-internal-refs": "node scripts/check-no-internal-refs.mjs",
+    "check:surface": "pnpm check:no-cyrillic && pnpm check:no-internal-refs",
+    "check:tarball": "node scripts/check-tarball.mjs",
+    "prepublish:check": "node scripts/prepublish-check.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "javascript-obfuscator": "^4.1.1",
+    "tsup": "^8.5.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}