@unotest/core 0.19.0 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # Changelog
 
+## [0.21.0] - 2026-08-25
+
+### Patch Changes
+
+- 174d27e: feat: environments are first-class in the viewer — a switcher, per-env run history
+
+  **Run artifacts are laid out per environment, as folders.** Each
+  environment's history lives in its own root, mirroring the env-file
+  scheme: `unotest/.runs` (base), `unotest/.runs.<env>` (e.g.
+  `.runs.staging` for `--env staging` / `UNOTEST_ENV=staging`); the axes
+  compose — `.runs-mobile.staging`. Indexes (`_day.jsonl`, `_latest.json`)
+  are per-env automatically: switching environments is a change of root,
+  not a filter and not a rebuild. Old runs stay in `.runs` (= base), no
+  migration needed. `runsDirFor` / `projectRunsRoot` / `projectRunDirFor`
+  gained an optional `envName` parameter; the run manifest carries `env`
+  for self-description. Make sure your `.gitignore` uses the wildcard
+  form — `unotest/.runs*/` (`init` already writes it that way for new
+  projects).
+
+  **The viewer knows about environments.** A new switcher sits at the top
+  of the Variables panel and in the status bar: base plus every
+  environment discovered from `unotest/.env.<name>` / `.secrets.<name>`
+  (`.env.example` and other templates do not count). The active
+  environment is server-side (`GET/POST /api/environments`), and all tabs
+  converge via the `env:changed` WS message:
+
+  - the Variables panel shows layers WITH the active environment's
+    overlay (previously base only); values coming from `.env.<name>`
+    carry a badge; an edit goes to the file where the key is defined; new
+    variables go to base;
+  - Overview and the Runs list show only the active environment — tiles
+    are colored by the latest run in that environment;
+  - a run started from the viewer gets the active environment's
+    `UNOTEST_ENV` (`RunRequest.env` is a per-request override);
+  - a run opened from another environment still resolves by runId across
+    all `.runs*` roots.
+
+  MCP: `run_test {env}` already switched the child process's environment;
+  its artifacts are now correctly found by the server in `.runs.<env>`
+  (inspect/step/attach/list_runtimes scan all roots).
+
+  Four fixes uncovered while shaking this down:
+
+  - **The `--env` overlay actually reaches the run.** Long-lived hosts
+    (viewer, MCP server) flattened the base `.env` into their own
+    `process.env` on `loadConfig`; children inherited it as ambient
+    (ambient beats files) — the overlay's `APP_BASE_URL` was silently
+    clobbered by the base value. The viewer now rolls its env back after
+    loading the config; MCP spawns children from a clean pre-flatten
+    snapshot.
+  - **Pause/Abort from the viewer work again.** Debug commands were
+    written to the flat `<root>/<runId>/commands.jsonl`, while runs have
+    lived in date shards since 0.19 — the write 404'd and abort was
+    silently ignored. Order fixed too: SIGTERM to the own process first
+    (tests AND collections), then the command file.
+  - **A collection no longer "dies" in the UI after 30 seconds.** The
+    parent run wrote no heartbeat — the monitor declared it interrupted,
+    the row vanished from ACTIVE and the tail detached. The orchestrator
+    now maintains the heartbeat (shared machinery in `@unotest/core`),
+    and the viewer additionally treats a flowing steps.jsonl as a sign of
+    life (compatibility with older runners).
+  - **No phantom `failed` after a clean exit.** The "child exited without
+    artifacts" check looked at the flat path and fired bogus
+    `run-finished: failed` events plus an error toast on every exit.
+
+- Updated dependencies [174d27e]
+  - @unotest/protocol@0.21.0
+  - @unotest/dsl@0.21.0
+
+## [0.20.0] - 2026-08-24
+
+### Patch Changes
+
+- Updated dependencies [7957469]
+- Updated dependencies [c6efd92]
+  - @unotest/protocol@0.20.0
+  - @unotest/dsl@0.20.0
+
 ## [0.19.0] - 2026-08-23
 
 ## [0.18.0] - 2026-08-23

package/dist/index.d.ts

@@ -24,10 +24,9 @@ interface JsonlRunArtifactWriterOptions {
 }
 declare class JsonlRunArtifactWriter implements IRunArtifactWriter {
     private readonly stepsPath;
-    private readonly heartbeatPath;
     private readonly nowFn;
     private readonly redactor;
-    private heartbeatTimer;
+    private readonly heartbeat;
     private closed;
     /** Tracks whether a `run:finished` event has been emitted. close()
      *  synthesizes one with outcome='aborted' if not — covers abort-paths
@@ -42,7 +41,6 @@ declare class JsonlRunArtifactWriter implements IRunArtifactWriter {
     constructor(opts: JsonlRunArtifactWriterOptions);
     emit(event: RunArtifact): Promise<void>;
     close(): Promise<void>;
-    private touchHeartbeat;
 }
 /** Convenience: create `runDir`, emit `run:started`, return a writer
  *  ready for subsequent events. Callers compute `runDir` themselves —
@@ -55,6 +53,19 @@ declare function createRunArtifactWriter(opts: {
     redactor?: ArtifactRedactor;
 }): Promise<IRunArtifactWriter>;
 
+interface RunHeartbeat {
+    /** Bump the file's mtime now (creating it if missing). */
+    touch(): Promise<void>;
+    /** Stop bumping and BACKDATE the file so liveness readers see the run
+     *  as stale immediately — "had a heartbeat, now stale" stays distinct
+     *  from "never started (no heartbeat)". Idempotent. */
+    stop(): Promise<void>;
+}
+declare function startRunHeartbeat(runDir: string, opts?: {
+    intervalMs?: number;
+    nowFn?: () => number;
+}): RunHeartbeat;
+
 interface WriteManifestInput {
     /** Absolute path to the run dir (`unotest/.runs<suffix>/<runId>/`).
      *  Created if absent. */
@@ -248,4 +259,4 @@ declare class UnotestError extends Error {
     constructor(message: string, context?: Record<string, unknown>);
 }
 
-export { type ArtifactRedactor, type DebugCommandsWatcherDeps, type DebugControlTarget, type DebugWatcherLogger, type E2EFlags, type GitignoreUpdate, type IRunArtifactWriter, JsonlRunArtifactWriter, type JsonlRunArtifactWriterOptions, type RuntimeExecState, type RuntimeInspection, type RuntimeInspectionInput, type RuntimeStateExtra, type RuntimeStateWriter, type RuntimeStateWriterDeps, UnotestError, type WriteManifestInput, type WriteRunSourcesInput, appendUniqueLines, applyEnvLayers, buildRuntimeInspection, createRunArtifactWriter, createRuntimeStateWriter, currentLocation, extractCallStack, levenshteinDistance, parseE2EFlags, readDebuggerBreakpoints, readEnvFile, readEnvLayers, startDebugCommandsWatcher, suggestClosest, toProtocolRuntimeState, writeRunManifest, writeRunSources };
+export { type ArtifactRedactor, type DebugCommandsWatcherDeps, type DebugControlTarget, type DebugWatcherLogger, type E2EFlags, type GitignoreUpdate, type IRunArtifactWriter, JsonlRunArtifactWriter, type JsonlRunArtifactWriterOptions, type RunHeartbeat, type RuntimeExecState, type RuntimeInspection, type RuntimeInspectionInput, type RuntimeStateExtra, type RuntimeStateWriter, type RuntimeStateWriterDeps, UnotestError, type WriteManifestInput, type WriteRunSourcesInput, appendUniqueLines, applyEnvLayers, buildRuntimeInspection, createRunArtifactWriter, createRuntimeStateWriter, currentLocation, extractCallStack, levenshteinDistance, parseE2EFlags, readDebuggerBreakpoints, readEnvFile, readEnvLayers, startDebugCommandsWatcher, startRunHeartbeat, suggestClosest, toProtocolRuntimeState, writeRunManifest, writeRunSources };

package/dist/index.js

@@ -2,18 +2,64 @@ var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
 // src/run-artifact-writer.ts
-import { HEARTBEAT_FILE, STEPS_FILE } from "@unotest/protocol";
-import { appendFile, mkdir, utimes, writeFile } from "fs/promises";
+import { STEPS_FILE } from "@unotest/protocol";
+import { appendFile, mkdir } from "fs/promises";
+import { join as join2 } from "path";
+
+// src/heartbeat.ts
+import { HEARTBEAT_FILE } from "@unotest/protocol";
+import { utimes, writeFile } from "fs/promises";
 import { join } from "path";
+function startRunHeartbeat(runDir, opts = {}) {
+  const path = join(runDir, HEARTBEAT_FILE);
+  const nowFn = opts.nowFn ?? Date.now;
+  const intervalMs = opts.intervalMs ?? 5e3;
+  let stopped = false;
+  let timer = null;
+  const touch = /* @__PURE__ */ __name(async () => {
+    if (stopped) return;
+    const ts = nowFn();
+    try {
+      await writeFile(path, "", { flag: "a" });
+      await utimes(path, new Date(ts), new Date(ts));
+    } catch {
+    }
+  }, "touch");
+  if (intervalMs > 0) {
+    void touch();
+    timer = setInterval(() => {
+      void touch();
+    }, intervalMs);
+    timer.unref();
+  }
+  return {
+    touch,
+    async stop() {
+      if (stopped) return;
+      stopped = true;
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+      try {
+        const stale = new Date(nowFn() - 36e5);
+        await utimes(path, stale, stale);
+      } catch {
+      }
+    }
+  };
+}
+__name(startRunHeartbeat, "startRunHeartbeat");
+
+// src/run-artifact-writer.ts
 var JsonlRunArtifactWriter = class {
   static {
     __name(this, "JsonlRunArtifactWriter");
   }
   stepsPath;
-  heartbeatPath;
   nowFn;
   redactor;
-  heartbeatTimer = null;
+  heartbeat;
   closed = false;
   /** Tracks whether a `run:finished` event has been emitted. close()
    *  synthesizes one with outcome='aborted' if not — covers abort-paths
@@ -26,18 +72,13 @@ var JsonlRunArtifactWriter = class {
    *  HAD a real failure, the user just gave up at the pause. */
   sawStepFail = false;
   constructor(opts) {
-    this.stepsPath = join(opts.runDir, STEPS_FILE);
-    this.heartbeatPath = join(opts.runDir, HEARTBEAT_FILE);
+    this.stepsPath = join2(opts.runDir, STEPS_FILE);
     this.nowFn = opts.nowFn ?? Date.now;
     this.redactor = opts.redactor;
-    const interval = opts.heartbeatIntervalMs ?? 5e3;
-    if (interval > 0) {
-      void this.touchHeartbeat();
-      this.heartbeatTimer = setInterval(() => {
-        void this.touchHeartbeat();
-      }, interval);
-      this.heartbeatTimer.unref();
-    }
+    this.heartbeat = startRunHeartbeat(opts.runDir, {
+      intervalMs: opts.heartbeatIntervalMs ?? 5e3,
+      nowFn: this.nowFn
+    });
   }
   async emit(event) {
     if (this.closed) return;
@@ -68,24 +109,7 @@ var JsonlRunArtifactWriter = class {
       this.runFinishedEmitted = true;
     }
     this.closed = true;
-    if (this.heartbeatTimer) {
-      clearInterval(this.heartbeatTimer);
-      this.heartbeatTimer = null;
-    }
-    try {
-      const stale = new Date(this.nowFn() - 36e5);
-      await utimes(this.heartbeatPath, stale, stale);
-    } catch {
-    }
-  }
-  async touchHeartbeat() {
-    if (this.closed) return;
-    const ts = this.nowFn();
-    try {
-      await writeFile(this.heartbeatPath, "", { flag: "a" });
-      await utimes(this.heartbeatPath, new Date(ts), new Date(ts));
-    } catch {
-    }
+    await this.heartbeat.stop();
   }
 };
 async function createRunArtifactWriter(opts) {
@@ -107,10 +131,10 @@ __name(createRunArtifactWriter, "createRunArtifactWriter");
 // src/run-manifest-writer.ts
 import { RUN_MANIFEST_FILE } from "@unotest/protocol";
 import { mkdir as mkdir2, rename, writeFile as writeFile2 } from "fs/promises";
-import { join as join2 } from "path";
+import { join as join3 } from "path";
 async function writeRunManifest(input) {
   await mkdir2(input.runDir, { recursive: true });
-  const dest = join2(input.runDir, RUN_MANIFEST_FILE);
+  const dest = join3(input.runDir, RUN_MANIFEST_FILE);
   const tmp = `${dest}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
   await writeFile2(tmp, JSON.stringify(input.manifest, null, 2), "utf8");
   await rename(tmp, dest);
@@ -122,10 +146,10 @@ import {
   RUN_SOURCES_FILE
 } from "@unotest/protocol";
 import { mkdir as mkdir3, rename as rename2, writeFile as writeFile3 } from "fs/promises";
-import { dirname, join as join3 } from "path";
+import { dirname, join as join4 } from "path";
 async function writeRunSources(input) {
   await mkdir3(input.runDir, { recursive: true });
-  const dest = join3(input.runDir, RUN_SOURCES_FILE);
+  const dest = join4(input.runDir, RUN_SOURCES_FILE);
   const tmp = `${dest}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
   await mkdir3(dirname(tmp), { recursive: true });
   await writeFile3(tmp, JSON.stringify(input.sources, null, 2), "utf8");
@@ -211,9 +235,9 @@ __name(truncate, "truncate");
 // src/runtime-state-writer.ts
 import { RUNTIME_FILE } from "@unotest/protocol";
 import { rename as rename3, writeFile as writeFile4 } from "fs/promises";
-import { join as join4 } from "path";
+import { join as join5 } from "path";
 function createRuntimeStateWriter(deps) {
-  const path = join4(deps.runDir, RUNTIME_FILE);
+  const path = join5(deps.runDir, RUNTIME_FILE);
   const tmpPath = `${path}.tmp`;
   const throttleMs = deps.throttleMs ?? 50;
   const now = deps.nowFn ?? Date.now;
@@ -467,9 +491,9 @@ __name(suggestClosest, "suggestClosest");
 // src/debugger-file.ts
 import { debuggerFileFor } from "@unotest/protocol";
 import { existsSync, readFileSync } from "fs";
-import { join as join5 } from "path";
+import { join as join6 } from "path";
 function readDebuggerBreakpoints(cwd, suffix, scenarioName) {
-  const filePath = join5(cwd, debuggerFileFor(suffix));
+  const filePath = join6(cwd, debuggerFileFor(suffix));
   if (!existsSync(filePath)) return [];
   try {
     const raw = readFileSync(filePath, "utf8");
@@ -517,7 +541,7 @@ import {
   parseEnvContent
 } from "@unotest/protocol";
 import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 function readEnvFile(absPath) {
   if (!existsSync2(absPath)) return {};
   try {
@@ -530,7 +554,7 @@ __name(readEnvFile, "readEnvFile");
 function readEnvLayers(projectRoot, suffix, envName) {
   const out = {};
   for (const rel of envLayerFilesFor(suffix, envName)) {
-    Object.assign(out, readEnvFile(join6(projectRoot, rel)));
+    Object.assign(out, readEnvFile(join7(projectRoot, rel)));
   }
   return out;
 }
@@ -578,6 +602,7 @@ export {
   readEnvFile,
   readEnvLayers,
   startDebugCommandsWatcher,
+  startRunHeartbeat,
   suggestClosest,
   toProtocolRuntimeState,
   writeRunManifest,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unotest/core",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Shared runner-side utilities for the @unotest ecosystem: JSONL run-artifact writer (steps.jsonl + heartbeat), atomic run-manifest + run-sources writers, atomic runtime-state writer with a protocol-normalizing runtime-inspection helper, layered .env reader/applier (target + environment axes), idempotent .gitignore updater. Used by @unotest/web and @unotest/mobile; depends on @unotest/protocol plus a type-only import of @unotest/dsl/executor event types (M-20). Unlike protocol (pure data), this package owns the thin filesystem layer both runners need.",
   "license": "MIT",
   "publishConfig": {
@@ -29,8 +29,8 @@
   ],
   "dependencies": {
     "chokidar": "^4.0.3",
-    "@unotest/dsl": "^0.19.0",
-    "@unotest/protocol": "^0.19.0"
+    "@unotest/dsl": "^0.21.0",
+    "@unotest/protocol": "^0.21.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",