wavework 0.0.0-stage → 0.1.0

package/templates/dashboard/record.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+// Pipeline run recorder: appends events of /next-task* runs to a store shared by all worktrees.
+// CLI: record.mjs <event> [--run <id>] [--key value ...]. Never fails loudly (exit 0 always).
+// Importable: resolveStoreDir, findRunByCwd, recordEvent, readRun, listRuns, EVENT_TYPES.
+import { execFileSync } from 'node:child_process';
+import {
+  appendFileSync, closeSync, mkdirSync, openSync, readdirSync, readFileSync,
+  realpathSync, renameSync, writeFileSync, constants,
+} from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const STORE_ENV = 'WAVEWORK_PIPELINE_STORE';
+export const EVENT_TYPES = [
+  'run-start', 'run-end', 'step-start', 'step-end', 'child-start', 'child-end',
+  'review', 'tests', 'finding', 'agent',
+];
+const RUN_KINDS = ['next-task', 'beads', 'batch'];
+const RUN_STATUSES = ['running', 'done', 'blocked', 'failed'];
+const NUMERIC = new Set([
+  'wave', 'round', 'mustFix', 'passed', 'failed', 'duration', 'durationMs',
+  'tokensIn', 'tokensOut', 'tokensCacheRead', 'tokensCacheWrite', 'cost',
+]);
+const LIST = new Set(['units']);
+export const RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+/** Store directory: $WAVEWORK_PIPELINE_STORE, else <git common dir>/pipeline-runs. Throws if neither works. */
+export function resolveStoreDir({ cwd = process.cwd(), env = process.env } = {}) {
+  if (env[STORE_ENV]) return path.resolve(env[STORE_ENV]);
+  const out = execFileSync('git', ['rev-parse', '--git-common-dir'], {
+    cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+  }).trim();
+  return path.join(path.resolve(cwd, out), 'pipeline-runs');
+}
+
+function real(p) {
+  try { return realpathSync(p); } catch { return path.resolve(p); }
+}
+
+function within(dir, cwd) {
+  const rel = path.relative(dir, cwd);
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+export function readRun(storeDir, id) {
+  if (typeof id !== 'string' || !RUN_ID.test(id)) return null;
+  try { return JSON.parse(readFileSync(path.join(storeDir, id, 'run.json'), 'utf8')); } catch { return null; }
+}
+
+export function listRuns(storeDir) {
+  let names;
+  try { names = readdirSync(storeDir); } catch { return []; }
+  return names.map((n) => readRun(storeDir, n)).filter(Boolean);
+}
+
+/** The running run whose worktree contains cwd (deepest worktree wins), or null. */
+export function findRunByCwd(cwd, { storeDir = resolveStoreDir({ cwd }) } = {}) {
+  const target = real(cwd);
+  let best = null;
+  let bestLen = -1;
+  for (const run of listRuns(storeDir)) {
+    if (run.status !== 'running' || !run.worktree) continue;
+    const wt = real(run.worktree);
+    if (within(wt, target) && wt.length > bestLen) { best = run; bestLen = wt.length; }
+  }
+  return best;
+}
+
+function writeRunJson(storeDir, id, run) {
+  const dir = path.join(storeDir, id);
+  const tmp = path.join(dir, `.run.json.${process.pid}.${Date.now()}.tmp`);
+  writeFileSync(tmp, JSON.stringify(run, null, 2) + '\n');
+  renameSync(tmp, path.join(dir, 'run.json'));
+}
+
+function appendLine(file, obj) {
+  // One write call with O_APPEND: lines from parallel processes do not interleave.
+  const fd = openSync(file, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT, 0o644);
+  try { appendFileSync(fd, JSON.stringify(obj) + '\n'); } finally { closeSync(fd); }
+}
+
+/** Records one event. `fields` are the event's data (without ts/type). Returns the written event. */
+export function recordEvent(storeDir, runId, type, fields = {}, now = new Date()) {
+  if (!EVENT_TYPES.includes(type)) throw new Error(`unknown event type: ${type}`);
+  if (!RUN_ID.test(runId || '')) throw new Error(`invalid run id: ${runId}`);
+  const ts = now.toISOString();
+  mkdirSync(path.join(storeDir, runId), { recursive: true });
+  const event = { ...fields, ts, type, run: runId };
+  appendLine(path.join(storeDir, runId, 'events.jsonl'), event);
+
+  if (type === 'run-start') {
+    const kind = RUN_KINDS.includes(fields.kind) ? fields.kind : 'next-task';
+    writeRunJson(storeDir, runId, {
+      id: runId, kind, units: fields.units ?? [], parent: fields.parent ?? null,
+      branch: fields.branch ?? null, worktree: fields.worktree ?? null,
+      status: 'running', started: ts, ended: null,
+    });
+  } else if (type === 'run-end') {
+    const run = readRun(storeDir, runId) ?? { id: runId, started: null };
+    const status = RUN_STATUSES.includes(fields.status) && fields.status !== 'running' ? fields.status : 'done';
+    writeRunJson(storeDir, runId, { ...run, status, ended: ts });
+  }
+  return event;
+}
+
+/** Parses `--key value` pairs; numeric and list fields are coerced, bare flags become true. */
+export function parseArgs(args) {
+  const out = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (!a.startsWith('--')) continue;
+    const key = a.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    const next = args[i + 1];
+    let value = true;
+    if (next !== undefined && !next.startsWith('--')) { value = next; i++; }
+    if (typeof value === 'string') {
+      if (LIST.has(key)) value = value.split(',').map((s) => s.trim()).filter(Boolean);
+      else if (NUMERIC.has(key) && value.trim() !== '' && Number.isFinite(Number(value))) value = Number(value);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+/** CLI entry. Returns the exit code, which is always 0. */
+export function main(argv, { cwd = process.cwd(), env = process.env, stderr = console.error } = {}) {
+  try {
+    const [type, ...rest] = argv;
+    if (!type) throw new Error(`usage: record.mjs <${EVENT_TYPES.join('|')}> --run <id> [--key value ...]`);
+    const { run, ...fields } = parseArgs(rest);
+    const storeDir = resolveStoreDir({ cwd, env });
+    let runId = typeof run === 'string' ? run : undefined;
+    if (!runId) runId = findRunByCwd(cwd, { storeDir })?.id;
+    if (!runId) throw new Error('no --run given and no running run for this directory');
+    recordEvent(storeDir, runId, type, fields);
+  } catch (e) {
+    stderr(`pipeline-record: ${e?.message ?? String(e)}`);
+  }
+  return 0;
+}
+
+if (process.argv[1] && real(process.argv[1]) === real(fileURLToPath(import.meta.url))) {
+  process.exitCode = main(process.argv.slice(2));
+}

package/templates/dashboard/server.mjs

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+// Pipeline dashboard server: JSON API over the run store, SSE live updates, CI status, static UI.
+// Node built-ins only. Binds 127.0.0.1. See README "Server/API".
+import { readFileSync, readdirSync, realpathSync, statSync, watch as fsWatch } from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createCiLookup } from './lib/ci.mjs';
+import { deriveTimeline } from './lib/derive.mjs';
+import { projectName, readSettings, resolvePort } from './lib/settings.mjs';
+import { resolveTokensFile } from './lib/tokens.mjs';
+import { RUN_ID, listRuns, readRun, resolveStoreDir } from './record.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+// This folder is <repo>/.claude/wavework/dashboard, so the checkout root is three levels up.
+const REPO_ROOT = path.resolve(HERE, '..', '..', '..');
+const MIME = {
+  '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8', '.json': 'application/json; charset=utf-8', '.svg': 'image/svg+xml',
+  '.png': 'image/png', '.ico': 'image/x-icon', '.woff2': 'font/woff2', '.map': 'application/json; charset=utf-8',
+};
+
+function readEvents(storeDir, id) {
+  if (!RUN_ID.test(id)) return [];
+  let text;
+  try { text = readFileSync(path.join(storeDir, id, 'events.jsonl'), 'utf8'); } catch { return []; }
+  const out = [];
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    try { out.push(JSON.parse(line)); } catch { /* partial or corrupt line: skip */ }
+  }
+  return out;
+}
+
+function sendJson(res, status, body) {
+  const data = JSON.stringify(body);
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+  res.end(data);
+}
+
+function sendText(res, status, type, text) {
+  res.writeHead(status, { 'content-type': type, 'cache-control': 'no-cache' });
+  res.end(text);
+}
+
+function sendFile(res, file) {
+  let data;
+  try { data = readFileSync(file); } catch { return sendJson(res, 404, { error: 'not found' }); }
+  res.writeHead(200, { 'content-type': MIME[path.extname(file).toLowerCase()] ?? 'application/octet-stream', 'cache-control': 'no-cache' });
+  res.end(data);
+}
+
+/** Maps a URL path to a file inside publicDir, or null. Rejects traversal, NULs and symlinks leaving publicDir. */
+function resolvePublic(publicDir, rawPath) {
+  let decoded;
+  try { decoded = decodeURIComponent(rawPath); } catch { return { status: 400 }; }
+  if (decoded.includes('\0') || decoded.includes('\\')) return { status: 400 };
+  const rel = decoded === '/' ? 'index.html' : decoded.replace(/^\/+/, '');
+  if (rel.split('/').includes('..')) return { status: 400 };
+  const base = path.resolve(publicDir);
+  const candidate = path.resolve(base, rel);
+  if (!candidate.startsWith(base + path.sep)) return { status: 400 };
+  try {
+    const realBase = realpathSync(base);
+    const real = realpathSync(candidate);
+    if (!real.startsWith(realBase + path.sep) || !statSync(real).isFile()) return { status: 404 };
+    return { file: real };
+  } catch { return { status: 404 }; }
+}
+
+function snapshot(storeDir) {
+  const snap = new Map();
+  let names;
+  try { names = readdirSync(storeDir); } catch { return snap; }
+  for (const n of names) {
+    if (!RUN_ID.test(n)) continue;
+    const sig = ['run.json', 'events.jsonl'].map((f) => {
+      try { const s = statSync(path.join(storeDir, n, f)); return `${s.mtimeMs}:${s.size}`; } catch { return '-'; }
+    }).join('|');
+    snap.set(n, sig);
+  }
+  return snap;
+}
+
+/**
+ * Calls onChange(runId) when a store file changes. fs.watch (recursive) is only the trigger; the run id comes
+ * from diffing store snapshots, because filename reporting differs per platform. Falls back to polling.
+ */
+function watchStore(storeDir, onChange, { mode = 'auto', pollMs = 1000 } = {}) {
+  let watcher = null;
+  let timer = null;
+  let debounce = null;
+  let closed = false;
+  let prev = snapshot(storeDir);
+  const diff = () => {
+    const next = snapshot(storeDir);
+    for (const [id, sig] of next) if (prev.get(id) !== sig) onChange(id);
+    prev = next;
+  };
+  if (mode !== 'poll') {
+    try {
+      watcher = fsWatch(storeDir, { recursive: true }, () => {
+        clearTimeout(debounce);
+        debounce = setTimeout(diff, 20);
+      });
+      watcher.on('error', () => { watcher?.close(); watcher = null; if (!closed) startPolling(); });
+    } catch { watcher = null; }
+  }
+  function startPolling() {
+    if (timer || closed) return;
+    timer = setInterval(diff, pollMs);
+    timer.unref?.();
+  }
+  if (!watcher) startPolling();
+  return () => {
+    closed = true;
+    watcher?.close();
+    clearTimeout(debounce);
+    if (timer) clearInterval(timer);
+  };
+}
+
+export function createServer({
+  storeDir = resolveStoreDir(), port = resolvePort(HERE),
+  publicDir = path.join(HERE, 'public'),
+  // The project's own tokens CSS: a fixed absolute path, or a function returning it (or null) per request.
+  tokensPath = () => resolveTokensFile(REPO_ROOT, readSettings(HERE).tokensFile),
+  project = projectName(REPO_ROOT),
+  ghRunner, ciRefreshMs = 15_000, watch = 'auto', pollMs = 1000,
+} = {}) {
+  const ci = createCiLookup({ ghRunner, refreshMs: ciRefreshMs });
+  const sse = new Set();
+
+  /** A batch still `running` whose members have all ended is reported as ended (blocked if any member is blocked/failed). */
+  const withBatchStatus = (run, all) => {
+    if (run.status !== 'running') return run;
+    const members = all.filter((r) => r.parent === run.id);
+    if (members.length === 0 || members.some((m) => m.status === 'running')) return run;
+    const bad = members.some((m) => m.status === 'blocked' || m.status === 'failed');
+    const ended = members.map((m) => m.ended).filter(Boolean).sort().pop() ?? null;
+    return { ...run, status: bad ? 'blocked' : 'done', ended };
+  };
+
+  const summary = (run) => {
+    const timeline = deriveTimeline(run, readEvents(storeDir, run.id));
+    return { ...run, totals: timeline.totals };
+  };
+
+  function listSummaries() {
+    const raw = listRuns(storeDir);
+    const all = raw.map((r) => summary(withBatchStatus(r, raw)));
+    const newest = (a, b) => (b.started ?? '').localeCompare(a.started ?? '');
+    const ids = new Set(all.map((r) => r.id));
+    const kids = new Map();
+    const top = [];
+    for (const r of all) {
+      if (r.parent && ids.has(r.parent)) {
+        if (!kids.has(r.parent)) kids.set(r.parent, []);
+        kids.get(r.parent).push(r);
+      } else top.push(r);
+    }
+    return top.sort(newest).map((r) => ({ ...r, children: (kids.get(r.id) ?? []).sort(newest) }));
+  }
+
+  async function runDetail(id) {
+    const stored = readRun(storeDir, id);
+    if (!stored) return null;
+    const run = withBatchStatus(stored, listRuns(storeDir));
+    const events = readEvents(storeDir, id);
+    const timeline = deriveTimeline(run, events);
+    return { run, events, timeline, ci: timeline.sha ? await ci.lookup(timeline.sha) : null };
+  }
+
+  async function handle(req, res) {
+    const host = req.headers.host ?? '';
+    const p = server.address()?.port;
+    if (host !== `127.0.0.1:${p}` && host !== `localhost:${p}`) return sendJson(res, 403, { error: 'forbidden host' });
+    if (req.method !== 'GET' && req.method !== 'HEAD') return sendJson(res, 405, { error: 'method not allowed' });
+    // Raw path on purpose: new URL() would normalize %2e%2e/.. segments before we can reject them.
+    const rawPath = (req.url ?? '/').split('?')[0].split('#')[0];
+
+    // root: the checkout this server runs from, so the SessionStart hook can replace a server whose worktree was deleted.
+    if (rawPath === '/api/health') return sendJson(res, 200, { ok: true, root: HERE });
+    // project: the repo directory name, shown in the UI title.
+    if (rawPath === '/api/info') return sendJson(res, 200, { project });
+    if (rawPath === '/api/runs') return sendJson(res, 200, listSummaries());
+    if (rawPath === '/api/events') {
+      res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
+      res.write(': connected\n\n');
+      sse.add(res);
+      res.on('close', () => sse.delete(res));
+      return undefined;
+    }
+    if (rawPath.startsWith('/api/runs/')) {
+      let id;
+      try { id = decodeURIComponent(rawPath.slice('/api/runs/'.length)); } catch { return sendJson(res, 400, { error: 'invalid run id' }); }
+      if (!RUN_ID.test(id)) return sendJson(res, 400, { error: 'invalid run id' });
+      const detail = await runDetail(id);
+      return detail ? sendJson(res, 200, detail) : sendJson(res, 404, { error: 'run not found' });
+    }
+    if (rawPath.startsWith('/api/')) return sendJson(res, 404, { error: 'not found' });
+    if (rawPath === '/tokens.css') {
+      // Optional project theme, loaded after the default theme. Nothing configured: an empty stylesheet.
+      const file = typeof tokensPath === 'function' ? tokensPath() : tokensPath;
+      if (!file) return sendText(res, 200, 'text/css; charset=utf-8', '/* no project tokens configured */\n');
+      return sendFile(res, file);
+    }
+    const r = resolvePublic(publicDir, rawPath);
+    if (r.file) return sendFile(res, r.file);
+    return sendJson(res, r.status, { error: r.status === 400 ? 'bad request' : 'not found' });
+  }
+
+  const server = http.createServer((req, res) => {
+    handle(req, res).catch(() => { if (!res.headersSent) sendJson(res, 500, { error: 'internal error' }); else res.end(); });
+  });
+  let stopWatch = null;
+  let keepAlive = null;
+
+  return {
+    get port() { return server.address()?.port; },
+    address: () => server.address(),
+    listen() {
+      return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, '127.0.0.1', () => {
+          server.off('error', reject);
+          stopWatch = watchStore(storeDir, (id) => {
+            for (const res of sse) res.write(`event: run-changed\ndata: ${JSON.stringify({ id })}\n\n`);
+          }, { mode: watch, pollMs });
+          keepAlive = setInterval(() => { for (const res of sse) res.write(': ping\n\n'); }, 25_000);
+          keepAlive.unref();
+          resolve(server.address());
+        });
+      });
+    },
+    close() {
+      return new Promise((resolve) => {
+        stopWatch?.();
+        clearInterval(keepAlive);
+        for (const res of sse) res.end();
+        sse.clear();
+        server.close(() => resolve());
+        server.closeAllConnections?.();
+      });
+    },
+  };
+}
+
+if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+  const s = createServer();
+  s.listen().then(() => {
+    console.log(`pipeline dashboard: http://127.0.0.1:${s.port}`);
+  }).catch((e) => { console.error(`pipeline dashboard: ${e.message}`); process.exitCode = 1; });
+}

package/templates/dashboard-config.json

@@ -0,0 +1 @@
+{{dashboardConfigJson}}