gcf-board 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleg (VirtualMaestro)
+
+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

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# gcf-board
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A local web board for game projects on [GCF](../gcf-aif-ext): the items by status, the phase, WIP, the inbox, the playtest session, what was accepted and what was killed — and buttons that run the same `ai-factory gcf` commands an operator runs in a console. The board is a view: it stores nothing, and without it the work goes on in the console unchanged (Methodology §11).
+
+## Requirements
+
+- Node.js ≥ 22.18
+- [`ai-factory`](https://www.npmjs.com/package/ai-factory) installed globally, and in each project [`gcf-aif-ext`](../gcf-aif-ext) ≥ 0.6 (`gcf board --json` with `schema: 1`)
+- for runs: [`gcf-harness-aif-ext`](../gcf-harness-aif-ext) ≥ 0.7 and Claude Code (`claude -p`)
+
+## Run
+
+```bash
+npm i -g gcf-board
+gcf-board                # http://127.0.0.1:4317
+gcf-board --port 4400
+```
+
+It prints `http://127.0.0.1:4317/?t=<token>`: open that URL once. It sets a cookie, and the plain address works after that. Add a project by its folder (one that has `gcf/`) under **Projects**.
+
+## What it does
+
+- **Board**: columns ready, running, blocked, awaiting-verdict, awaiting-decision, unplayed, parked. A card shows the type, the gate, the plan progress (`2/5`), the severity, `verified`, the model.
+- **An item**: its file, its plan and its run log as it grows, and the moves the core offers for it (`items[].moves`, Methodology §4.1): verdict, decide, block, unblock, drop, close, submit. The board keeps only each move's form; the core still checks the rest itself, and the board shows its answer.
+- **Drag**:
+  - a ready card into **running** starts its run;
+  - a blocked or parked card into **ready** unblocks it;
+  - a card onto **graveyard** drops it.
+  
+  Every other move is a button.
+- **Run**: **run** on an item, or select ready cards and **Run selected**. It starts `ai-factory gcf-harness run <ids> --json`: one worktree and one agent session per item, then the integrator. A run asks first: it spends the subscription.
+- **New item**: `gcf item new … --commit`. The item's `model` and `effort` go to its run.
+- **Inbox**: add, erase, or turn an entry into an item. Open questions are listed there too.
+- **Playtest**: `gcf playtest session` with the checklist grouped by subsystem; keep, tune or kill each item from the list. **Build** runs `dod.build`. A note goes to the inbox as `--source playtest`.
+- **Ended**: history (accepted) and graveyard (killed, dropped, won't-fix).
+
+The page updates by itself: the server watches each project's `gcf/` and `.gcf-session/runs/`.
+
+## Security
+
+The board starts agents that write code and commit: whoever can talk to it runs code on this machine.
+
+- It listens on `127.0.0.1` only.
+- Every request needs this machine's token, kept in `~/.gcf/board-token`; delete that file to make a new one.
+- A request must also name host `127.0.0.1` or `localhost` with the board's port.
+- A change must come from the board's own page (`Origin`). This blocks another site in the same browser.
+- Commands run without a shell: the operator's text reaches `ai-factory` as one argument, never as a command line.
+- The API shows only item files, plans and run logs inside a project.
+
+Do not put the port on a network. Remote and phone access is planned for v2, behind its own authentication.
+
+## Files
+
+- `~/.gcf/projects.json`: the projects on the board, `{projects: [{name, path}]}`.
+- `~/.gcf/board-token`: the token.
+- `GCF_BOARD_HOME` moves both; `GCF_BOARD_AIF` points at another `ai-factory` entry script.
+
+## Roadmap (v2)
+
+- **Chat with Claude in a project**:
+  - `claude -p --output-format stream-json`;
+  - a choice of model and effort;
+  - permission prompts answered from the board through a `PermissionRequest` hook;
+  - resume a session.
+- **Phone and remote access**: Tailscale or Claude Remote Control, with their own authentication; push notifications when an item blocks or waits for a verdict.
+
+## Develop
+
+```bash
+npm install
+npm test            # server and web tests on Node's type stripping
+npm run typecheck
+npm run build       # vite → dist/web, tsc → dist/server
+node dist/server/main.js --port 4318
+```

package/dist/server/app.js

@@ -0,0 +1,220 @@
+// The board's HTTP server: the page, and an API that is a thin layer over `ai-factory gcf`.
+// Reads: projects, the board, a shown file, a run log, the playtest session. Writes: a project
+// on the board, a move, a run. Every write is a command of the framework.
+import { createServer } from 'node:http';
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { BOARD_SCHEMA } from '../shared/board.js';
+import { admit, COOKIE, hostAllowed, tokenInUrl } from './auth.js';
+import { briefError, runCli } from './cli.js';
+import { broadcast, subscribe, watchProject } from './events.js';
+import { followLog, readShown } from './files.js';
+import { HttpError } from './http-error.js';
+import { moveArgs, runIds } from './moves.js';
+import { addProject, listProjects, projectOf, removeProject } from './registry.js';
+import { activeRuns, startRun } from './runs.js';
+const send = (res, status, body) => {
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify(body));
+};
+async function bodyOf(req) {
+    // Bytes first, text once: a letter cut between two chunks stays whole.
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > 1_000_000)
+            throw new HttpError(413, 'request too large');
+        chunks.push(chunk);
+    }
+    const raw = Buffer.concat(chunks).toString('utf8');
+    try {
+        const v = raw ? JSON.parse(raw) : {};
+        if (typeof v !== 'object' || v === null || Array.isArray(v))
+            throw new Error('not an object');
+        return v;
+    }
+    catch {
+        throw new HttpError(400, 'the body must be a JSON object');
+    }
+}
+/** Parse the JSON a command printed, or say what it printed instead. */
+function jsonOf(r, what) {
+    try {
+        return JSON.parse(r.out);
+    }
+    catch {
+        throw new HttpError(502, `ai-factory ${what} gave no report: ${(r.err || r.out).trim()}`);
+    }
+}
+const TYPES = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.json': 'application/json',
+    '.ico': 'image/x-icon',
+    '.woff2': 'font/woff2',
+};
+/** A file of the built page; any other path is the page itself (the page routes). */
+async function sendPage(res, web, pathname) {
+    let decoded = '';
+    try {
+        decoded = decodeURIComponent(pathname);
+    }
+    catch {
+        throw new HttpError(400, 'a path that is not valid percent-encoding');
+    }
+    const rel = path.normalize(decoded).replace(/^([/\\])+/, '');
+    let file = path.join(web, rel);
+    if (!file.startsWith(web) || !existsSync(file) || rel === '')
+        file = path.join(web, 'index.html');
+    if (!existsSync(file))
+        throw new HttpError(500, `the page is not built: ${web} has no index.html`);
+    res.writeHead(200, { 'content-type': TYPES[path.extname(file)] ?? 'application/octet-stream' });
+    res.end(await readFile(file));
+}
+export function createApp(o) {
+    const watchers = new Map();
+    const watchAll = async () => {
+        for (const p of await listProjects())
+            if (!watchers.has(p.name))
+                watchers.set(p.name, watchProject(p));
+    };
+    const cli = (p, args, timeout) => runCli(o.entry, p.path, args, timeout);
+    const routes = [
+        ['GET', /^\/api\/events$/, async (_req, res) => subscribe(res)],
+        ['GET', /^\/api\/projects$/, async (_req, res) => send(res, 200, await listProjects())],
+        [
+            'POST',
+            /^\/api\/projects$/,
+            async (req, res) => {
+                const b = await bodyOf(req);
+                if (typeof b.path !== 'string')
+                    throw new HttpError(400, 'path is required');
+                const name = typeof b.name === 'string' && b.name ? b.name : undefined;
+                const p = await addProject(b.path, name);
+                await watchAll();
+                send(res, 201, p);
+            },
+        ],
+        [
+            'DELETE',
+            /^\/api\/projects\/([^/]+)$/,
+            async (_req, res, m) => {
+                await removeProject(m[1]);
+                watchers.get(m[1])?.();
+                watchers.delete(m[1]);
+                send(res, 200, { ok: true });
+            },
+        ],
+        [
+            'GET',
+            /^\/api\/p\/([^/]+)\/board$/,
+            async (_req, res, m) => {
+                const board = jsonOf(await cli(await projectOf(m[1]), ['gcf', 'board', '--json']), 'gcf board');
+                if (board.schema !== BOARD_SCHEMA)
+                    throw new HttpError(502, `gcf board gives schema ${board.schema ?? 'none'}, this board reads ${BOARD_SCHEMA}: ` +
+                        'update gcf-aif-ext and gcf-board together');
+                send(res, 200, board);
+            },
+        ],
+        [
+            'GET',
+            /^\/api\/p\/([^/]+)\/file$/,
+            async (_req, res, m, url) => {
+                const p = await projectOf(m[1]);
+                send(res, 200, { text: await readShown(p.path, url.searchParams.get('path') ?? '') });
+            },
+        ],
+        [
+            'GET',
+            /^\/api\/p\/([^/]+)\/log\/([a-z0-9][a-z0-9-]*)$/,
+            async (_req, res, m) => {
+                followLog((await projectOf(m[1])).path, m[2], res);
+            },
+        ],
+        [
+            'GET',
+            /^\/api\/p\/([^/]+)\/playtest$/,
+            async (_req, res, m) => {
+                const r = await cli(await projectOf(m[1]), ['gcf', 'playtest', 'session', '--json']);
+                send(res, 200, jsonOf(r, 'gcf playtest session'));
+            },
+        ],
+        [
+            // A build runs the project's own command: a write, so a POST with its Origin checked.
+            'POST',
+            /^\/api\/p\/([^/]+)\/playtest\/build$/,
+            async (_req, res, m) => {
+                const args = ['gcf', 'playtest', 'session', '--json', '--build'];
+                // A build of a real game takes minutes.
+                const r = await cli(await projectOf(m[1]), args, 30 * 60_000);
+                send(res, 200, jsonOf(r, 'gcf playtest session --build'));
+            },
+        ],
+        [
+            'POST',
+            /^\/api\/p\/([^/]+)\/move$/,
+            async (req, res, m) => {
+                const p = await projectOf(m[1]);
+                const r = await cli(p, moveArgs(await bodyOf(req)));
+                broadcast({ type: 'board', project: p.name });
+                send(res, 200, { ok: r.ok, out: r.out.trim(), err: briefError(r.err) });
+            },
+        ],
+        [
+            'GET',
+            /^\/api\/p\/([^/]+)\/runs$/,
+            async (_req, res, m) => send(res, 200, activeRuns((await projectOf(m[1])).name)),
+        ],
+        [
+            'POST',
+            /^\/api\/p\/([^/]+)\/run$/,
+            async (req, res, m) => {
+                const p = await projectOf(m[1]);
+                send(res, 202, startRun(o.entry, p, runIds(await bodyOf(req))));
+            },
+        ],
+    ];
+    const handle = async (req, res) => {
+        const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+        const visit = req.method === 'GET' && !url.pathname.startsWith('/api/');
+        if (visit && hostAllowed(req, o.port) && tokenInUrl(url, o.token)) {
+            res.writeHead(302, {
+                'set-cookie': `${COOKIE}=${o.token}; HttpOnly; SameSite=Strict; Path=/`,
+                // Always the root: a path like `//elsewhere` would send the browser off the board.
+                location: '/',
+            });
+            res.end();
+            return;
+        }
+        const gate = admit(req, o.port, o.token);
+        if (!gate.ok) {
+            send(res, gate.status, { error: gate.message });
+            return;
+        }
+        for (const [method, re, route] of routes) {
+            const m = url.pathname.match(re);
+            if (m && req.method === method)
+                return route(req, res, m, url);
+        }
+        if (url.pathname.startsWith('/api/'))
+            throw new HttpError(404, `no ${req.method} ${url.pathname}`);
+        await sendPage(res, o.web, url.pathname);
+    };
+    const server = createServer((req, res) => {
+        handle(req, res).catch((e) => {
+            if (res.headersSent)
+                return res.end();
+            send(res, e instanceof HttpError ? e.status : 500, { error: e.message });
+        });
+    });
+    server.on('listening', () => void watchAll());
+    server.on('close', () => {
+        for (const stop of watchers.values())
+            stop();
+    });
+    return server;
+}

package/dist/server/atomic.js

@@ -0,0 +1,7 @@
+import { rename, writeFile } from 'node:fs/promises';
+/** Write a file whole or not at all: a crash mid-write leaves the old one, never a torn one. */
+export async function writeAtomic(file, text, mode) {
+    const tmp = `${file}.${process.pid}.tmp`;
+    await writeFile(tmp, text, { mode });
+    await rename(tmp, file);
+}

package/dist/server/auth.js

@@ -0,0 +1,52 @@
+// The board starts agents that commit and push: whoever talks to it runs code on this machine.
+// It listens on 127.0.0.1 only, and every request needs the token printed at start (kept in a
+// cookie after the first visit). Host and Origin are checked too: a page in another tab can
+// reach 127.0.0.1 (DNS rebinding, a cross-site POST), but it cannot fake those headers.
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { writeAtomic } from './atomic.js';
+import { homeDir } from './registry.js';
+export const COOKIE = 'gcf_board';
+// An empty or short token would let everyone in: such a file is replaced.
+const STRONG = /^[0-9a-f]{48}$/;
+/** The token of this machine's board: made once, kept in `~/.gcf/board-token`. */
+export async function boardToken() {
+    const file = path.join(homeDir(), 'board-token');
+    const kept = existsSync(file) ? (await readFile(file, 'utf8')).trim() : '';
+    if (STRONG.test(kept))
+        return kept;
+    const token = randomBytes(24).toString('hex');
+    await mkdir(homeDir(), { recursive: true });
+    await writeAtomic(file, `${token}\n`, 0o600);
+    return token;
+}
+const same = (a, b) => b.length > 0 && a.length === b.length && timingSafeEqual(Buffer.from(a), Buffer.from(b));
+function cookieOf(req) {
+    for (const part of (req.headers.cookie ?? '').split(';')) {
+        const [k, ...v] = part.trim().split('=');
+        if (k === COOKIE)
+            return v.join('=');
+    }
+    return '';
+}
+const hostsOf = (port) => [`127.0.0.1:${port}`, `localhost:${port}`];
+export const hostAllowed = (req, port) => hostsOf(port).includes(req.headers.host ?? '');
+/** Whether a request may go on: its Host, its Origin on a write, its token. */
+export function admit(req, port, token) {
+    const hosts = hostsOf(port);
+    if (!hostAllowed(req, port))
+        return { ok: false, status: 403, message: 'the board answers 127.0.0.1 and localhost only' };
+    const write = !['GET', 'HEAD'].includes(req.method ?? 'GET');
+    const origin = req.headers.origin;
+    if (write && !(origin && hosts.some((h) => origin === `http://${h}`)))
+        return { ok: false, status: 403, message: 'a change comes from the board page only' };
+    if (!same(cookieOf(req), token))
+        return { ok: false, status: 401, message: 'open the URL gcf-board printed at start' };
+    return { ok: true };
+}
+/** `?t=<token>` on a page: the visit that sets the cookie. */
+export function tokenInUrl(url, token) {
+    return same(url.searchParams.get('t') ?? '', token);
+}

package/dist/server/cli.js

@@ -0,0 +1,61 @@
+// The board runs the same `ai-factory` the operator runs, never a shell: the arguments carry the
+// operator's own words (a reason, a note), and node gets them one by one.
+import { execSync, spawn, spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * The JS entry of the `ai-factory` CLI: GCF_BOARD_AIF, or the bin of the global package. The
+ * global one is found through `npm root -g`, a fixed command line: the shell Windows needs for
+ * npm.cmd sees nothing of the operator's.
+ */
+export function aiFactoryEntry() {
+    if (process.env.GCF_BOARD_AIF)
+        return process.env.GCF_BOARD_AIF;
+    const root = execSync('npm root -g', { encoding: 'utf8' }).trim();
+    const dir = path.join(root, 'ai-factory');
+    const pkg = JSON.parse(readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    const bin = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.['ai-factory'];
+    if (!bin)
+        throw new Error(`${dir} has no ai-factory bin: install it with npm i -g ai-factory`);
+    return path.join(dir, bin);
+}
+/**
+ * The line of a refusal an operator reads: the core throws, and node prints the stack under
+ * an `Error: <message>` line. Anything else is shown as it came.
+ */
+export function briefError(err) {
+    return err.match(/^\w*Error: (.+)$/m)?.[1].trim() ?? err.trim();
+}
+/** Run `ai-factory <args>` in a project; a move can wait up to a minute on gcf's main lock. */
+export function runCli(entry, cwd, args, timeoutMs = 120_000) {
+    return new Promise((resolve) => {
+        const child = spawn(process.execPath, [entry, ...args], {
+            cwd,
+            shell: false,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        // A decoder per stream: a Cyrillic letter cut between two chunks stays one letter.
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        let out = '';
+        let err = '';
+        child.stdout.on('data', (d) => (out += d));
+        child.stderr.on('data', (d) => (err += d));
+        const timer = setTimeout(() => {
+            err += `\nstopped after ${timeoutMs / 1000} s`;
+            // On Windows a kill stops node alone: a build it started (Unity) would go on.
+            if (process.platform === 'win32' && child.pid)
+                spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
+            else
+                child.kill();
+        }, timeoutMs);
+        child.on('error', (e) => {
+            clearTimeout(timer);
+            resolve({ ok: false, code: null, out, err: e.message });
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            resolve({ ok: code === 0, code, out, err });
+        });
+    });
+}

package/dist/server/events.js

@@ -0,0 +1,56 @@
+// Server-sent events: a project's `gcf/` or its run locks changed, a run the board started ended.
+// The page reads the board again on each one; the event carries no state of its own.
+import { watch, watchFile, unwatchFile } from 'node:fs';
+import path from 'node:path';
+const clients = new Set();
+/** Open an event stream on `res`. */
+export function openStream(res) {
+    res.writeHead(200, {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-cache',
+        connection: 'keep-alive',
+    });
+    res.write(': open\n\n');
+    // A proxy or a sleeping laptop drops an idle stream: a comment line keeps it.
+    const ping = setInterval(() => res.write(': ping\n\n'), 25_000);
+    res.on('close', () => clearInterval(ping));
+    return res;
+}
+export function subscribe(res) {
+    clients.add(openStream(res));
+    res.on('close', () => clients.delete(res));
+}
+export function broadcast(event) {
+    const line = `data: ${JSON.stringify(event)}\n\n`;
+    for (const c of clients)
+        c.write(line);
+}
+/**
+ * Watch a project: `gcf/` (every move writes there) and `.gcf-session/runs` (a run's lock comes
+ * and goes). The runs directory may not exist yet, so it is polled, not watched. Bursts of
+ * writes make one event. Returns the stop.
+ */
+export function watchProject(p, debounceMs = 300) {
+    let timer = null;
+    const fire = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => broadcast({ type: 'board', project: p.name }), debounceMs);
+    };
+    let gcf = null;
+    try {
+        gcf = watch(path.join(p.path, 'gcf'), { recursive: true }, fire);
+        gcf.on('error', () => gcf?.close());
+    }
+    catch {
+        // gcf/ is gone: the board read shows the error, nothing to watch.
+    }
+    const runs = path.join(p.path, '.gcf-session', 'runs');
+    watchFile(runs, { interval: 1500 }, fire);
+    return () => {
+        gcf?.close();
+        unwatchFile(runs, fire);
+        if (timer)
+            clearTimeout(timer);
+    };
+}

package/dist/server/files.js

@@ -0,0 +1,97 @@
+// The files a board shows: an item, its plan, its run log. Only those shapes, only inside the
+// project, symlinks resolved: the API is not a way to read the disk.
+import { realpath, readFile, stat, open } from 'node:fs/promises';
+import path from 'node:path';
+import { StringDecoder } from 'node:string_decoder';
+import { HttpError } from './http-error.js';
+import { openStream } from './events.js';
+const SHOWN = [
+    /^gcf\/[\w./-]+\.md$/,
+    /^\.ai-factory\/(archive\/)?plans\/[\w.-]+\.md$/,
+    /^\.gcf-session\/runs\/[\w.-]+\.log$/,
+];
+const MAX = 1024 * 1024;
+/** The absolute path of a shown file, or a 403. */
+export async function shownFile(root, rel) {
+    if (!SHOWN.some((r) => r.test(rel)) || rel.split('/').includes('..'))
+        throw new HttpError(403, `${rel} is not a file the board shows`);
+    const file = path.join(root, rel);
+    const real = await realpath(file).catch(() => {
+        throw new HttpError(404, `${rel} does not exist`);
+    });
+    const inside = path.relative(await realpath(root), real);
+    if (inside.startsWith('..') || path.isAbsolute(inside))
+        throw new HttpError(403, `${rel} leads outside the project`);
+    return real;
+}
+/** The text of a shown file; a large one is cut to its last megabyte. */
+export async function readShown(root, rel) {
+    const file = await shownFile(root, rel);
+    const { size } = await stat(file);
+    if (size <= MAX)
+        return readFile(file, 'utf8');
+    const tail = (await readBytes(file, size - MAX, size)).toString('utf8');
+    return `…(first ${size - MAX} bytes cut)\n${tail}`;
+}
+async function readBytes(file, from, to) {
+    const fh = await open(file, 'r');
+    try {
+        const buf = Buffer.alloc(to - from);
+        const { bytesRead } = await fh.read(buf, 0, buf.length, from);
+        return buf.subarray(0, bytesRead);
+    }
+    finally {
+        await fh.close();
+    }
+}
+/** Whether a file that exists resolves inside the project: a log may be a symlink. */
+async function inside(root, file) {
+    const real = await realpath(file).catch(() => null);
+    if (!real)
+        return false;
+    const rel = path.relative(await realpath(root), real);
+    return !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+/**
+ * Follow the run log of `id` as it grows: its last 256 KB first, then every new chunk, polled
+ * each second (a log on another disk does not always fire a watch). A log that shrank was
+ * started again: a `reset` event tells the page to drop what it holds, then it is read from its
+ * start. One decoder for the stream: a letter cut between two reads stays whole.
+ */
+export function followLog(root, id, res) {
+    const file = path.join(root, '.gcf-session', 'runs', `${id}.log`);
+    openStream(res);
+    let pos = -1;
+    let decoder = new StringDecoder('utf8');
+    const pump = async () => {
+        if (!(await inside(root, file)))
+            return;
+        const { size } = await stat(file);
+        if (pos < 0)
+            pos = Math.max(0, size - 256 * 1024);
+        if (size < pos) {
+            pos = 0;
+            decoder = new StringDecoder('utf8');
+            res.write('event: reset\ndata: ""\n\n');
+        }
+        if (size === pos)
+            return;
+        const chunk = decoder.write(await readBytes(file, pos, size));
+        pos = size;
+        if (chunk)
+            res.write(`data: ${JSON.stringify(chunk)}\n\n`);
+    };
+    let busy = false;
+    const tick = async () => {
+        if (busy)
+            return;
+        busy = true;
+        // A log removed between two reads is read again on the next tick.
+        await pump()
+            .catch(() => { })
+            .finally(() => (busy = false));
+    };
+    void tick();
+    const timer = setInterval(tick, 1000);
+    res.on('close', () => clearInterval(timer));
+}

package/dist/server/http-error.js

@@ -0,0 +1,8 @@
+/** An error the server answers with its own status, its message shown to the operator. */
+export class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}

package/dist/server/main.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// `gcf-board [--port <n>]`: the board on http://127.0.0.1:<port>, 4317 by default. It prints the
+// URL with this machine's token; open that one, the plain address answers 401.
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { boardToken } from './auth.js';
+import { aiFactoryEntry } from './cli.js';
+import { createApp } from './app.js';
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * The built page: `dist/web` beside `server/` when run from the source (the source `web/` is
+ * not built), `web/` beside `dist/server/` in the package.
+ */
+function webDir() {
+    const fromSource = path.resolve(HERE, '..', 'dist', 'web');
+    return existsSync(path.join(fromSource, 'index.html'))
+        ? fromSource
+        : path.resolve(HERE, '..', 'web');
+}
+async function main() {
+    const { values } = parseArgs({ options: { port: { type: 'string', default: '4317' } } });
+    const port = Number(values.port);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new Error('--port is a number from 1 to 65535');
+    const token = await boardToken();
+    const app = createApp({ entry: aiFactoryEntry(), token, port, web: webDir() });
+    app.listen(port, '127.0.0.1', () => {
+        console.log(`gcf-board: http://127.0.0.1:${port}/?t=${token}`);
+    });
+}
+main().catch((e) => {
+    console.error(`gcf-board: ${e.message}`);
+    process.exit(1);
+});