@amenophis1er/foreman 0.1.0

package/src/services.test.ts

@@ -0,0 +1,53 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { ServiceRegistry, parseServicePath, portOpen, proxyToService, servicePath } from './services.js';
+
+test('service paths round-trip and reject junk', () => {
+  assert.equal(servicePath('run-1', 8934), '/svc/run-1/8934/');
+  assert.deepEqual(parseServicePath('/svc/run-1/8934/'), { runId: 'run-1', port: 8934, rest: '/' });
+  assert.deepEqual(parseServicePath('/svc/run-1/8934/css/a.css'), { runId: 'run-1', port: 8934, rest: '/css/a.css' });
+  assert.deepEqual(parseServicePath('/svc/run-1/8934'), { runId: 'run-1', port: 8934, rest: '/' });
+  assert.equal(parseServicePath('/svc/run-1/abc/'), null);
+  assert.equal(parseServicePath('/svc/run-1/70000/'), null);
+  assert.equal(parseServicePath('/svcx/run-1/80/'), null);
+});
+
+test('registry: declared pairs only, one entry per port, lookup by port', () => {
+  const r = new ServiceRegistry();
+  const a = r.register('run-1', 8934, 'preview');
+  assert.equal(a.path, '/svc/run-1/8934/');
+  r.register('run-1', 8934, 'preview again');
+  assert.equal(r.list('run-1').length, 1);
+  assert.equal(r.list('run-1')[0].label, 'preview again');
+  assert.equal(r.has('run-1', 8934), true);
+  assert.equal(r.has('run-1', 9000), false);
+  assert.deepEqual(r.runsFor(8934), ['run-1']);
+});
+
+test('proxyToService streams a response and reports a dead port as 502', async () => {
+  const upstream = http.createServer((req, res) => {
+    res.writeHead(200, { 'content-type': 'text/plain', 'x-seen-prefix': String(req.headers['x-forwarded-prefix']) });
+    res.end(`hello ${req.url}`);
+  });
+  await new Promise<void>((r) => upstream.listen(0, '127.0.0.1', r));
+  const port = (upstream.address() as { port: number }).port;
+  assert.equal(await portOpen(port), true);
+  const front = http.createServer((req, res) => proxyToService(req, res, port, '/a/b', '?x=1', '/svc/run-1/' + port + '/'));
+  await new Promise<void>((r) => front.listen(0, '127.0.0.1', r));
+  const fport = (front.address() as { port: number }).port;
+  try {
+    const r = await fetch(`http://127.0.0.1:${fport}/anything`);
+    assert.equal(r.status, 200);
+    assert.equal(await r.text(), 'hello /a/b?x=1');
+    assert.equal(r.headers.get('x-seen-prefix'), '/svc/run-1/' + port + '/');
+    upstream.close();
+    await new Promise((r2) => setTimeout(r2, 50));
+    const dead = await fetch(`http://127.0.0.1:${fport}/anything`);
+    assert.equal(dead.status, 502);
+    assert.match(await dead.text(), /Nothing is answering/);
+    assert.equal(await portOpen(port), false);
+  } finally {
+    front.close();
+  }
+});

package/src/services.ts

@@ -0,0 +1,102 @@
+/**
+ * Services the crew exposes: a dev server it started to test its work, made
+ * reachable through Foreman's own address — so the human on the phone can
+ * open it over the tailnet without the agent opening a port to the world.
+ *
+ * The proxy is deliberately narrow. Only ports a run declared, only on
+ * loopback, only under `/svc/<run>/<port>/`. Nothing is guessed: a request
+ * for an undeclared pair is a 404, a declared service that is down is a 502
+ * with a sentence, never a hang.
+ */
+import http from 'node:http';
+import net from 'node:net';
+
+export interface ExposedService {
+  port: number;
+  label: string;
+  /** `/svc/<runId>/<port>/` — the path under Foreman's origin. */
+  path: string;
+  since: number;
+}
+
+export const SVC_PREFIX = '/svc/';
+const HOP_BY_HOP = new Set(['connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'te', 'trailer', 'transfer-encoding', 'upgrade', 'host']);
+
+export function servicePath(runId: string, port: number): string {
+  return `${SVC_PREFIX}${encodeURIComponent(runId)}/${port}/`;
+}
+
+/** `/svc/<run>/<port>/rest` → its parts, or null. The rest keeps its leading slash. */
+export function parseServicePath(pathname: string): { runId: string; port: number; rest: string } | null {
+  const m = /^\/svc\/([^/]+)\/(\d{2,5})(\/.*)?$/.exec(pathname);
+  if (!m) return null;
+  const port = Number(m[2]);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) return null;
+  return { runId: decodeURIComponent(m[1]), port, rest: m[3] ?? '/' };
+}
+
+/** Something is accepting connections on 127.0.0.1:port right now. */
+export function portOpen(port: number, timeoutMs = 800): Promise<boolean> {
+  return new Promise((resolve) => {
+    const s = net.connect({ host: '127.0.0.1', port });
+    const done = (v: boolean) => { s.destroy(); resolve(v); };
+    s.setTimeout(timeoutMs, () => done(false));
+    s.once('connect', () => done(true));
+    s.once('error', () => done(false));
+  });
+}
+
+export class ServiceRegistry {
+  private byRun = new Map<string, ExposedService[]>();
+
+  register(runId: string, port: number, label: string): ExposedService {
+    const list = this.byRun.get(runId) ?? [];
+    const existing = list.find((s) => s.port === port);
+    if (existing) { existing.label = label || existing.label; return existing; }
+    const svc: ExposedService = { port, label: label || `port ${port}`, path: servicePath(runId, port), since: Date.now() };
+    this.byRun.set(runId, [...list, svc]);
+    return svc;
+  }
+
+  list(runId: string): ExposedService[] { return this.byRun.get(runId) ?? []; }
+
+  has(runId: string, port: number): boolean { return this.list(runId).some((s) => s.port === port); }
+
+  /** Which run declared this port, if any — for sub-resource requests that only carry a Referer. */
+  runsFor(port: number): string[] {
+    return [...this.byRun.entries()].filter(([, l]) => l.some((s) => s.port === port)).map(([id]) => id);
+  }
+}
+
+/**
+ * Streams one request to 127.0.0.1:port and its response back. `rest` is the
+ * path the service sees; Foreman's prefix is passed along in a header for
+ * apps that know how to honour it.
+ */
+export function proxyToService(
+  req: http.IncomingMessage, res: http.ServerResponse,
+  port: number, rest: string, search: string, prefix: string,
+): void {
+  const headers: Record<string, string | string[]> = {};
+  for (const [k, v] of Object.entries(req.headers)) {
+    if (v !== undefined && !HOP_BY_HOP.has(k.toLowerCase())) headers[k] = v;
+  }
+  headers.host = `127.0.0.1:${port}`;
+  headers['x-forwarded-prefix'] = prefix;
+  headers['x-forwarded-host'] = String(req.headers.host ?? '');
+  const up = http.request({ host: '127.0.0.1', port, method: req.method, path: rest + search, headers }, (r) => {
+    const out: Record<string, string | string[] | number> = {};
+    for (const [k, v] of Object.entries(r.headers)) {
+      if (v !== undefined && !HOP_BY_HOP.has(k.toLowerCase())) out[k] = v;
+    }
+    res.writeHead(r.statusCode ?? 502, out);
+    r.pipe(res);
+  });
+  up.setTimeout(30_000, () => up.destroy(new Error('timeout')));
+  up.on('error', (err) => {
+    if (res.headersSent) { res.destroy(); return; }
+    res.writeHead(502, { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' });
+    res.end(`Nothing is answering on 127.0.0.1:${port} (${err.message}). The service the crew exposed may have stopped with its run.`);
+  });
+  req.pipe(up);
+}

package/src/sse-events.test.ts

@@ -0,0 +1,83 @@
+/**
+ * Every event the server emits must be one the client listens for.
+ *
+ * An EventSource delivers only the named events it has a listener for. A
+ * name the server emits but the client never subscribed to is not an error
+ * anywhere — the frame arrives, is dropped, and the UI shows it only after a
+ * reload replays the log. Thirteen events shipped that way in a single day,
+ * each looking fine on replay, before a human noticed a picker that never
+ * appeared. This test is the contract that stops it recurring: emit a new
+ * name, and `SSE_EVENTS` in ui/src/sse.ts must grow in the same change.
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const SRC = here;
+const SSE_TS = path.resolve(here, '..', 'ui', 'src', 'sse.ts');
+
+/** Server files that can emit: everything under src/ except tests and the ported gateway. */
+function serverFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const name of readdirSync(dir)) {
+    const p = path.join(dir, name);
+    if (statSync(p).isDirectory()) {
+      if (name === 'gateway') continue; // proxies bytes; emits nothing to the UI
+      out.push(...serverFiles(p));
+    } else if (p.endsWith('.ts') && !p.endsWith('.test.ts')) {
+      out.push(p);
+    }
+  }
+  return out;
+}
+
+/**
+ * Names passed as the first argument to an emitter. Matches the shapes in use:
+ * `this.emit('x'`, `turn.emit('x'`, `emit('x'`, `makeChatEmitter(id)('x'`,
+ * `broadcastChat(id, 'x'` (a frame without a log line), and
+ * the ternary `emit(isResume ? 'run_resumed' : 'run_started'` — the whole
+ * first-argument expression is taken and every quoted name in it counts. A
+ * name assembled from strings would not be caught; none exist, and the
+ * comment on SSE_EVENTS says not to start.
+ */
+function emittedNames(): Set<string> {
+  const names = new Set<string>();
+  const re = /(?:\bemit|makeChatEmitter\([^)]*\))\(\s*([^,]+),|\bbroadcastChat\(\s*[^,]+,\s*([^,]+),/g;
+  for (const file of serverFiles(SRC)) {
+    const text = readFileSync(file, 'utf8');
+    for (const m of text.matchAll(re)) {
+      for (const q of (m[1] ?? m[2] ?? '').matchAll(/'([a-z_]+)'/g)) names.add(q[1]);
+    }
+  }
+  return names;
+}
+
+function subscribedNames(): Set<string> {
+  const text = readFileSync(SSE_TS, 'utf8');
+  const block = text.slice(text.indexOf('SSE_EVENTS = ['), text.indexOf('] as const'));
+  return new Set([...block.matchAll(/'([a-z_]+)'/g)].map((m) => m[1]));
+}
+
+test('every event the server emits has a client listener', () => {
+  const emitted = emittedNames();
+  const subscribed = subscribedNames();
+  assert.ok(emitted.size > 20, `sanity: expected to find many emits, found ${emitted.size}`);
+  const missing = [...emitted].filter((n) => !subscribed.has(n)).sort();
+  assert.deepEqual(missing, [],
+    `emitted by the server but never delivered to the UI (add to SSE_EVENTS in ui/src/sse.ts): ${missing.join(', ')}`);
+});
+
+test('the client does not listen for names nothing emits', () => {
+  // The reverse is only a hygiene check, so it warns through the message
+  // rather than failing on a name emitted from somewhere this scan cannot see.
+  const emitted = emittedNames();
+  const subscribed = subscribedNames();
+  const dead = [...subscribed].filter((n) => !emitted.has(n)).sort();
+  // Known: `models_changed` is emitted from a place outside the emit() shapes
+  // (a server broadcast helper). Anything else is worth a look.
+  const unexplained = dead.filter((n) => n !== 'models_changed');
+  assert.deepEqual(unexplained, [], `subscribed but apparently never emitted: ${unexplained.join(', ')}`);
+});

package/src/store.test.ts

@@ -0,0 +1,119 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { RunStore, newRunId } from './store.js';
+import type { RunMeta } from './types.js';
+
+function meta(id: string, over: Partial<RunMeta> = {}): RunMeta {
+  return {
+    id, folder: '/tmp/x', mission: 'test', budgetUsd: 5,
+    status: 'running', costUsd: 0, createdAt: Date.now(), workers: [],
+    ...over,
+  };
+}
+
+async function tmpStore(): Promise<{ store: RunStore; root: string }> {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'foreman-store-'));
+  return { store: new RunStore(root), root };
+}
+
+test('newRunId is sortable by creation time and well-formed', () => {
+  const a = newRunId(1000);
+  const b = newRunId(2000);
+  assert.match(a, /^[0-9]{13}-[0-9a-f]{8}$/);
+  assert.ok(a < b);
+});
+
+test('create, append, read round-trip preserves order', async () => {
+  const { store, root } = await tmpStore();
+  const id = newRunId();
+  await store.createRun(meta(id));
+  // Fire-and-forget appends must still land in order.
+  for (let i = 0; i < 20; i++) void store.append(id, { ts: i, event: 'e', data: { i } });
+  await store.append(id, { ts: 99, event: 'last', data: null });
+
+  const events = await store.readEvents(id);
+  assert.equal(events.length, 21);
+  assert.deepEqual(events.map((e) => e.ts).slice(0, 5), [0, 1, 2, 3, 4]);
+  assert.equal(events.at(-1)?.event, 'last');
+  await rm(root, { recursive: true, force: true });
+});
+
+test('listRuns returns newest first and skips junk', async () => {
+  const { store, root } = await tmpStore();
+  const a = newRunId(1000);
+  const b = newRunId(2000);
+  await store.createRun(meta(a));
+  await store.createRun(meta(b));
+  const runs = await store.listRuns();
+  assert.deepEqual(runs.map((r) => r.id), [b, a]);
+  await rm(root, { recursive: true, force: true });
+});
+
+test('sweepOrphans finishes running runs and appends a terminal event', async () => {
+  const { store, root } = await tmpStore();
+  const orphan = newRunId(1000);
+  const finished = newRunId(2000);
+  await store.createRun(meta(orphan));
+  await store.createRun(meta(finished, { status: 'done' }));
+
+  const swept = await store.sweepOrphans();
+  assert.deepEqual(swept, [orphan]);
+
+  const m = await store.readMeta(orphan);
+  assert.equal(m?.status, 'interrupted');
+  assert.ok(m?.endedAt);
+  const events = await store.readEvents(orphan);
+  assert.equal(events.at(-1)?.event, 'run_finished');
+
+  // Idempotent: nothing left to sweep.
+  assert.deepEqual(await store.sweepOrphans(), []);
+  await rm(root, { recursive: true, force: true });
+});
+
+test('readEvents drops a torn trailing line', async () => {
+  const { store, root } = await tmpStore();
+  const id = newRunId();
+  await store.createRun(meta(id));
+  await store.append(id, { ts: 1, event: 'ok', data: null });
+  const { appendFile } = await import('node:fs/promises');
+  await appendFile(path.join(root, 'runs', id, 'events.jsonl'), '{"ts":2,"event":"torn'); // no newline, invalid JSON
+  const events = await store.readEvents(id);
+  assert.equal(events.length, 1);
+  assert.equal(events[0].event, 'ok');
+  await rm(root, { recursive: true, force: true });
+});
+
+test('run ids are validated before touching the filesystem', async () => {
+  const { store } = await tmpStore();
+  await assert.rejects(() => store.readEvents('../../etc/passwd' as string));
+});
+
+test('projects: add is idempotent per folder, remove keeps others', async () => {
+  const { store, root } = await tmpStore();
+  const a = await store.addProject('/tmp/proj-a');
+  const b = await store.addProject('/tmp/proj-b', 'Custom Name');
+  const aAgain = await store.addProject('/tmp/proj-a');
+
+  assert.equal(a.id, aAgain.id);
+  assert.equal(a.name, 'proj-a');
+  assert.equal(b.name, 'Custom Name');
+  assert.equal((await store.listProjects()).length, 2);
+  assert.deepEqual(await store.getProject(a.id), a);
+
+  assert.equal(await store.removeProject(a.id), true);
+  assert.equal(await store.removeProject(a.id), false);
+  assert.deepEqual((await store.listProjects()).map((p) => p.id), [b.id]);
+  await rm(root, { recursive: true, force: true });
+});
+
+test('projects: concurrent adds do not lose writes', async () => {
+  const { store, root } = await tmpStore();
+  await Promise.all(
+    Array.from({ length: 8 }, (_, i) => store.addProject(`/tmp/conc-${i}`)),
+  );
+  assert.equal((await store.listProjects()).length, 8);
+  await rm(root, { recursive: true, force: true });
+});