@quiesco/ui 0.0.0-stage → 0.3.0

package/dist/web/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en" data-theme="dark">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="color-scheme" content="dark light">
+  <title>Quiesco</title>
+  <link rel="icon" href="data:,">
+  <script type="module" crossorigin src="./assets/index-BmpF4iJ3.js"></script>
+  <link rel="stylesheet" crossorigin href="./assets/index-Blhnqd4m.css">
+</head>
+<body>
+  <div id="root"></div>
+</body>
+</html>

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@quiesco/ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.0",
+  "description": "Quiesco test UI: run tests from the browser and watch them live (quiesco ui).",
+  "license": "MIT",
+  "author": "h2nology",
+  "keywords": [
+    "quiesco",
+    "e2e",
+    "testing",
+    "expo",
+    "react-native",
+    "ui"
+  ],
+  "homepage": "https://github.com/h2nology/quiesco/tree/main/packages/ui#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/h2nology/quiesco.git",
+    "directory": "packages/ui"
+  },
+  "bugs": {
+    "url": "https://github.com/h2nology/quiesco/issues"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@quiesco/core": "0.3.0",
+    "@quiesco/protocol": "0.3.0",
+    "ws": "8.22.1"
+  },
+  "devDependencies": {
+    "@fontsource-variable/dm-sans": "5.3.0",
+    "@fontsource-variable/jetbrains-mono": "5.3.0",
+    "@fontsource-variable/space-grotesk": "5.3.0",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@types/ws": "8.18.2",
+    "@vitejs/plugin-react": "6.1.2",
+    "playwright": "1.65.0",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "vite": "8.3.6"
+  },
+  "scripts": {
+    "build": "tsc -b && pnpm run build:web",
+    "build:web": "tsc -p web/tsconfig.json && vite build --config web/vite.config.ts",
+    "test": "vitest run"
+  }
 }

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @quiesco/ui: the test UI behind `quiesco ui` — run tests from the browser and watch them live.
+ * The CLI loads it; it is not meant to be used directly.
+ */
+export { startUiServer } from './server.js';
+export type { UiServer, UiServerOptions } from './server.js';
+export { spawnRun } from './spawn.js';
+export type { RunHandle, SpawnRunOptions } from './spawn.js';
+export { targetArgs } from './targets.js';
+export type { RunTarget } from './targets.js';
+export type { ClientMessage, NoticeCode, RunningInfo, ServerMessage, UiInfo } from './messages.js';

package/src/messages.ts

@@ -0,0 +1,44 @@
+/**
+ * Messages between the `quiesco ui` server and the browser, over a WebSocket at `/ws` (JSON, one
+ * message per frame). Types only: the web app imports them too.
+ */
+import type { RunStateSnapshot } from '@quiesco/core/run-state';
+import type { RunEvent, RunnerName, TestList } from '@quiesco/protocol';
+
+import type { RunTarget } from './targets.js';
+
+export type { RunTarget };
+
+export interface UiInfo {
+  /** The project directory's name. */
+  project: string;
+  runner: RunnerName;
+  platform: string;
+  /** Version of @quiesco/ui. */
+  version: string;
+}
+
+export type ServerMessage =
+  /** First message on a connection, with everything needed to draw the page. */
+  | { type: 'welcome'; info: UiInfo; list: TestList | null; listing: boolean; state: RunStateSnapshot; running: RunningInfo | null; output: string }
+  /** Listing the tests started (`listing: true`) or finished (with the list). */
+  | { type: 'list'; list: TestList | null; listing: boolean }
+  /** A run event from the runner (apply it to the RunState). */
+  | { type: 'event'; event: RunEvent }
+  /** A run started (`running` set) or ended (`running: null`, the final state). */
+  | { type: 'run'; running: RunningInfo | null; exitCode?: number; state?: RunStateSnapshot }
+  /** The runner's own output (stdout / stderr). */
+  | { type: 'output'; stream: 'stdout' | 'stderr'; text: string }
+  /** `code` lets the page show the notice in its language; `message` is the English text. */
+  | { type: 'notice'; level: 'info' | 'error'; code?: NoticeCode; message: string };
+
+export type NoticeCode = 'busy' | 'unknown-tests';
+
+export interface RunningInfo {
+  target: RunTarget;
+  /** The runner arguments chosen for the target. */
+  args: string[];
+  startedAt: number;
+}
+
+export type ClientMessage = { type: 'run'; target: RunTarget } | { type: 'cancel' } | { type: 'list' };

package/src/server.ts

@@ -0,0 +1,311 @@
+/**
+ * The `quiesco ui` server (P5): serves the web app, lists the tests, runs what the browser asks for
+ * (one run at a time: one device), and streams the run events to every open page.
+ *
+ * Local only: it listens on 127.0.0.1, refuses other Host / Origin headers (DNS rebinding) and requires
+ * the token from the URL it prints (kept in a cookie after the first page load). Files are served only
+ * from the artifacts directory (evidence) and the listed test files (source view).
+ */
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import http from 'node:http';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+import { RunEventServer, RunState } from '@quiesco/core';
+import type { RunEvent, RunnerName, TestList, TestRef } from '@quiesco/protocol';
+import { WebSocketServer } from 'ws';
+import type { WebSocket } from 'ws';
+
+import type { ClientMessage, NoticeCode, RunningInfo, ServerMessage, UiInfo } from './messages.js';
+import type { RunHandle } from './spawn.js';
+import { targetArgs } from './targets.js';
+import type { RunTarget } from './targets.js';
+
+export interface UiServerOptions {
+  cwd: string;
+  runner: RunnerName;
+  platform: string;
+  /** Start the runner with `args` added (the target) and `env` added (QUIESCO_EVENTS). */
+  startRun(args: string[], env: Record<string, string>, onOutput: (stream: 'stdout' | 'stderr', text: string) => void): RunHandle;
+  listTests(): Promise<TestList>;
+  /** Absolute path of the artifacts directory (evidence files). */
+  artifactsDir: string;
+  /** The built web app; null serves a minimal page (tests of the server). */
+  staticDir: string | null;
+  port?: number;
+  host?: string;
+  token?: string;
+}
+
+export interface UiServer {
+  readonly url: string;
+  readonly port: number;
+  readonly token: string;
+  close(): Promise<void>;
+}
+
+const OUTPUT_KEEP = 200_000;
+const COOKIE = 'quiesco_ui';
+const MIME: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.woff2': 'font/woff2',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.json': 'application/json; charset=utf-8',
+  '.ico': 'image/x-icon',
+};
+/** Evidence and source files: media as such, everything else as plain text (never HTML: no script). */
+function fileType(file: string): string {
+  const ext = path.extname(file).toLowerCase();
+  return ['.png', '.jpg', '.jpeg', '.webp', '.mp4', '.webm', '.json'].includes(ext) ? (MIME[ext] as string) : 'text/plain; charset=utf-8';
+}
+
+function version(): string {
+  return (createRequire(import.meta.url)('../package.json') as { version: string }).version;
+}
+
+/** `child` is `root` or inside it, after resolving symlinks. */
+function inside(root: string, child: string): boolean {
+  try {
+    const r = fs.realpathSync(root);
+    const c = fs.realpathSync(child);
+    return c === r || c.startsWith(r + path.sep);
+  } catch {
+    return false;
+  }
+}
+
+export async function startUiServer(options: UiServerOptions): Promise<UiServer> {
+  const host = options.host ?? '127.0.0.1';
+  const token = options.token ?? randomBytes(16).toString('hex');
+  const info: UiInfo = { project: path.basename(options.cwd), runner: options.runner, platform: options.platform, version: version() };
+  const state = new RunState();
+  const clients = new Set<WebSocket>();
+  let list: TestList | null = null;
+  let listing = false;
+  let relistQueued = false;
+  let running: RunningInfo | null = null;
+  let handle: RunHandle | null = null;
+  let output = '';
+  let port = 0;
+
+  const send = (ws: WebSocket, m: ServerMessage) => {
+    if (ws.readyState === ws.OPEN) ws.send(JSON.stringify(m));
+  };
+  const broadcast = (m: ServerMessage) => {
+    const data = JSON.stringify(m);
+    for (const ws of clients) if (ws.readyState === ws.OPEN) ws.send(data);
+  };
+
+  /**
+   * Running chosen tests: Vitest and Jest report the other tests of their files as skipped (filtered
+   * out). Those reports are dropped, so a test keeps its last real result, and the total is the
+   * number of chosen tests.
+   */
+  let chosen: ReadonlySet<string> | null = null;
+  const filtered = (event: RunEvent): RunEvent | null => {
+    if (chosen === null) return event;
+    if (event.type === 'run:start' || event.type === 'total:update') return { ...event, total: chosen.size, totalIsEstimate: false };
+    if ((event.type === 'test:start' || event.type === 'test:end') && !chosen.has(event.test.id)) {
+      if (event.type === 'test:start' || event.status === 'skipped') return null;
+    }
+    return event;
+  };
+  const events = new RunEventServer({
+    onEvent: (raw) => {
+      const event = filtered(raw);
+      if (event === null) return;
+      state.apply(event);
+      broadcast({ type: 'event', event });
+    },
+  });
+  await events.listen();
+
+  const knownTests = (): Map<string, TestRef> => {
+    const m = new Map<string, TestRef>();
+    for (const t of list?.tests ?? []) m.set(t.id, t);
+    for (const t of state.tests.values()) m.set(t.test.id, { ...m.get(t.test.id), ...t.test });
+    return m;
+  };
+
+  const relist = async (): Promise<void> => {
+    if (listing || running !== null) {
+      relistQueued = true;
+      return;
+    }
+    listing = true;
+    broadcast({ type: 'list', list, listing: true });
+    try {
+      list = await options.listTests();
+    } catch (e) {
+      list = { runner: options.runner, files: [], tests: [], errors: [{ message: (e as Error).message }] };
+    }
+    listing = false;
+    broadcast({ type: 'list', list, listing: false });
+    watchFiles();
+  };
+
+  const run = (target: RunTarget): { code: NoticeCode; message: string } | null => {
+    if (running !== null) return { code: 'busy', message: 'A run is already in progress (one device: one run at a time).' };
+    let args: string[];
+    try {
+      args = targetArgs(options.runner, target, knownTests());
+    } catch (e) {
+      return { code: 'unknown-tests', message: (e as Error).message };
+    }
+    output = '';
+    chosen = target.kind === 'tests' ? new Set(target.ids) : null;
+    running = { target, args, startedAt: Date.now() };
+    broadcast({ type: 'run', running });
+    const h = options.startRun(args, events.env(), (stream, text) => {
+      output = (output + text).slice(-OUTPUT_KEEP);
+      broadcast({ type: 'output', stream, text });
+    });
+    handle = h;
+    void h.exited.then(async (code) => {
+      await events.drain();
+      state.runnerExited(code);
+      running = null;
+      handle = null;
+      broadcast({ type: 'run', running: null, exitCode: code, state: state.snapshot() });
+      if (relistQueued) {
+        relistQueued = false;
+        void relist();
+      }
+    });
+    return null;
+  };
+
+  // Test files changed: list again (debounced).
+  let watchers: fs.FSWatcher[] = [];
+  let relistTimer: NodeJS.Timeout | null = null;
+  function watchFiles(): void {
+    for (const w of watchers) w.close();
+    watchers = [];
+    const dirs = new Set((list?.files ?? []).map((f) => path.dirname(path.resolve(options.cwd, f))));
+    for (const dir of dirs) {
+      try {
+        const w = fs.watch(dir, () => {
+          if (relistTimer !== null) clearTimeout(relistTimer);
+          relistTimer = setTimeout(() => void relist(), 400);
+        });
+        w.unref();
+        watchers.push(w);
+      } catch {
+        // A directory that went away: the next listing drops it.
+      }
+    }
+  }
+
+  const allowedHost = (h: string | undefined) => h !== undefined && [`127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`].includes(h);
+  const cookieToken = (req: http.IncomingMessage) => /(?:^|;\s*)quiesco_ui=([0-9a-f]+)/.exec(req.headers.cookie ?? '')?.[1];
+
+  const httpServer = http.createServer((req, res) => {
+    const url = new URL(req.url ?? '/', `http://${req.headers.host ?? host}`);
+    const headers = { 'X-Content-Type-Options': 'nosniff', 'Referrer-Policy': 'no-referrer', 'Cache-Control': 'no-store' };
+    if (!allowedHost(req.headers.host)) {
+      res.writeHead(403, headers).end('Forbidden host');
+      return;
+    }
+    const queryToken = url.searchParams.get('token');
+    const authorized = queryToken === token || cookieToken(req) === token;
+    if (!authorized) {
+      res.writeHead(401, { ...headers, 'Content-Type': 'text/plain; charset=utf-8' }).end('Open the URL quiesco ui printed (it carries the token).');
+      return;
+    }
+    const setCookie = queryToken === token ? { 'Set-Cookie': `${COOKIE}=${token}; HttpOnly; SameSite=Strict; Path=/` } : {};
+
+    if (url.pathname === '/api/file' || url.pathname === '/api/source') {
+      const p = url.searchParams.get('path') ?? '';
+      const file = path.resolve(options.cwd, p);
+      const ok =
+        url.pathname === '/api/file'
+          ? inside(options.artifactsDir, file)
+          : (list?.files ?? []).some((f) => path.resolve(options.cwd, f) === file) && inside(options.cwd, file);
+      if (!ok || !fs.existsSync(file) || !fs.statSync(file).isFile()) {
+        res.writeHead(404, headers).end('Not found');
+        return;
+      }
+      res.writeHead(200, { ...headers, 'Content-Type': fileType(file), 'Content-Security-Policy': "default-src 'none'; img-src 'self'; media-src 'self'; style-src 'unsafe-inline'" });
+      fs.createReadStream(file).pipe(res);
+      return;
+    }
+
+    const csp = `default-src 'self'; connect-src 'self' ws://${req.headers.host}; img-src 'self' data: blob:; media-src 'self'; style-src 'self' 'unsafe-inline'; font-src 'self'; frame-ancestors 'none'`;
+    if (options.staticDir === null) {
+      res.writeHead(200, { ...headers, ...setCookie, 'Content-Type': 'text/html; charset=utf-8', 'Content-Security-Policy': csp }).end('<!doctype html><title>Quiesco</title><p>Quiesco UI</p>');
+      return;
+    }
+    const rel = decodeURIComponent(url.pathname).replace(/^\/+/, '');
+    let file = path.join(options.staticDir, rel === '' ? 'index.html' : rel);
+    if (!inside(options.staticDir, file) || !fs.existsSync(file) || fs.statSync(file).isDirectory()) file = path.join(options.staticDir, 'index.html');
+    const type = MIME[path.extname(file).toLowerCase()] ?? 'application/octet-stream';
+    res.writeHead(200, { ...headers, ...setCookie, 'Content-Type': type, 'Content-Security-Policy': csp });
+    fs.createReadStream(file).pipe(res);
+  });
+
+  const wss = new WebSocketServer({ noServer: true, maxPayload: 64 * 1024 });
+  httpServer.on('upgrade', (req, socket, head) => {
+    const url = new URL(req.url ?? '/', `http://${req.headers.host ?? host}`);
+    const origin = req.headers.origin;
+    const originOk = origin === undefined || [`http://127.0.0.1:${port}`, `http://localhost:${port}`, `http://[::1]:${port}`].includes(origin);
+    const tokenOk = url.searchParams.get('token') === token || cookieToken(req) === token;
+    if (url.pathname !== '/ws' || !allowedHost(req.headers.host) || !originOk || !tokenOk) {
+      socket.write('HTTP/1.1 403 Forbidden\r\n\r\n');
+      socket.destroy();
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      clients.add(ws);
+      ws.on('close', () => clients.delete(ws));
+      ws.on('message', (data) => {
+        let m: ClientMessage;
+        try {
+          m = JSON.parse(String(data)) as ClientMessage;
+        } catch {
+          return;
+        }
+        if (m.type === 'run') {
+          const problem = run(m.target);
+          if (problem !== null) send(ws, { type: 'notice', level: 'error', ...problem });
+        } else if (m.type === 'cancel') {
+          handle?.stop();
+        } else if (m.type === 'list') {
+          void relist();
+        }
+      });
+      send(ws, { type: 'welcome', info, list, listing, state: state.snapshot(), running, output });
+    });
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    httpServer.once('error', reject);
+    httpServer.listen(options.port ?? 0, host, () => resolve());
+  });
+  port = (httpServer.address() as { port: number }).port;
+  void relist();
+
+  return {
+    url: `http://${host === '127.0.0.1' ? '127.0.0.1' : host}:${port}/?token=${token}`,
+    port,
+    token,
+    async close() {
+      handle?.stop(2000);
+      if (handle !== null) await handle.exited;
+      for (const w of watchers) w.close();
+      if (relistTimer !== null) clearTimeout(relistTimer);
+      for (const ws of clients) ws.terminate();
+      wss.close();
+      await new Promise<void>((resolve) => httpServer.close(() => resolve()));
+      await events.close();
+    },
+  };
+}

package/src/spawn.ts

@@ -0,0 +1,52 @@
+/**
+ * Start a test run as a child process: its output to a callback, stoppable as a whole (the runner runs
+ * under npx, so stopping must reach the runner and its workers, not only npx).
+ */
+import { spawn } from 'node:child_process';
+
+export interface RunHandle {
+  /** Resolves with the exit code (130 when stopped with SIGINT). */
+  readonly exited: Promise<number>;
+  /** Ctrl-C to the whole process tree; SIGKILL after `graceMs` if it is still there. */
+  stop(graceMs?: number): void;
+}
+
+export interface SpawnRunOptions {
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  onOutput: (stream: 'stdout' | 'stderr', text: string) => void;
+}
+
+const isWindows = process.platform === 'win32';
+
+export function spawnRun(command: string, args: readonly string[], options: SpawnRunOptions): RunHandle {
+  // Its own process group (POSIX), so stop() reaches npx, the runner and its workers.
+  const child = spawn(command, [...args], { cwd: options.cwd, env: options.env, stdio: ['ignore', 'pipe', 'pipe'], detached: !isWindows, shell: isWindows });
+  child.stdout.setEncoding('utf8').on('data', (t: string) => options.onOutput('stdout', t));
+  child.stderr.setEncoding('utf8').on('data', (t: string) => options.onOutput('stderr', t));
+  const exited = new Promise<number>((resolve) => {
+    child.on('error', (e) => {
+      options.onOutput('stderr', `${e.message}\n`);
+      resolve(127);
+    });
+    child.on('close', (code, signal) => resolve(code ?? (signal === 'SIGINT' ? 130 : signal !== null ? 143 : 1)));
+  });
+  const signal = (s: NodeJS.Signals) => {
+    if (child.pid === undefined || child.exitCode !== null || child.signalCode !== null) return;
+    try {
+      if (isWindows) spawn('taskkill', ['/pid', String(child.pid), '/T', ...(s === 'SIGKILL' ? ['/F'] : [])]);
+      else process.kill(-child.pid, s);
+    } catch {
+      // Already gone.
+    }
+  };
+  return {
+    exited,
+    stop(graceMs = 10_000) {
+      signal('SIGINT');
+      const timer = setTimeout(() => signal('SIGKILL'), graceMs);
+      timer.unref();
+      void exited.then(() => clearTimeout(timer));
+    },
+  };
+}

package/src/targets.ts

@@ -0,0 +1,47 @@
+/**
+ * What to run, as runner arguments (findings P0): the UI asks for all tests, one file, or some tests;
+ * each runner selects them its own way.
+ *
+ * - cucumber: `file:line[:line…]` (a Scenario line, or an Examples row's line). NOTE: cucumber-js adds
+ *   command line paths to the `paths` of its config instead of replacing them, so a config with `paths`
+ *   runs more than asked (Quiesco's init no longer writes `paths`).
+ * - vitest: `file:line` (a `test.each` line runs every row).
+ * - jest: `--runTestsByPath <files>` and `-t '^(full name|…)$'` (titles joined with spaces; Jest matches
+ *   case-insensitively, so a test with the same name in another chosen file runs too).
+ */
+import type { RunnerName, TestRef } from '@quiesco/protocol';
+
+export type RunTarget = { kind: 'all' } | { kind: 'file'; file: string } | { kind: 'tests'; ids: readonly string[] };
+
+const escapeRegExp = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** Runner arguments selecting `target`; `tests` resolves test ids to their file and line. */
+export function targetArgs(runner: RunnerName, target: RunTarget, tests: ReadonlyMap<string, TestRef>): string[] {
+  if (target.kind === 'all') return [];
+  if (target.kind === 'file') return runner === 'jest' ? ['--runTestsByPath', target.file] : [target.file];
+
+  const refs = target.ids.flatMap((id) => {
+    const t = tests.get(id);
+    return t !== undefined ? [t] : [];
+  });
+  if (refs.length === 0) throw new Error('none of the chosen tests is known (list the tests again)');
+  const byFile = new Map<string, TestRef[]>();
+  for (const t of refs) byFile.set(t.file, [...(byFile.get(t.file) ?? []), t]);
+
+  if (runner === 'jest') {
+    const names = [...new Set(refs.map((t) => escapeRegExp(t.path.join(' '))))];
+    return ['--runTestsByPath', ...byFile.keys(), '-t', `^(${names.join('|')})$`];
+  }
+  const out: string[] = [];
+  for (const [file, ts] of byFile) {
+    const lines = [...new Set(ts.flatMap((t) => (t.line !== undefined ? [t.line] : [])))].sort((a, b) => a - b);
+    if (lines.length === 0 || lines.length < ts.length) {
+      out.push(file); // a test without a line: the whole file
+    } else if (runner === 'cucumber') {
+      out.push(`${file}:${lines.join(':')}`);
+    } else {
+      for (const l of lines) out.push(`${file}:${l}`);
+    }
+  }
+  return out;
+}