gcf-board 0.2.1 → 0.2.5

package/README.md

@@ -15,6 +15,7 @@ A local web board for game projects on [GCF](../gcf-aif-ext): the items by statu
 npm i -g gcf-board
 gcf-board                # http://127.0.0.1:4317
 gcf-board --port 4400
+gcf-board --version      # the installed version
 ```
 
 It opens the board in your browser (the URL with the token, `http://127.0.0.1:4317/?t=<token>`, is printed too; `--no-open` skips the browser). Started again while it runs, it just opens the running board. Add a project by its folder (one that has `gcf/`) under **Projects**.
@@ -41,7 +42,7 @@ It puts **GCF Board** on the desktop (Windows: a shortcut whose server console s
   - `run_mode: worktree`: one worktree and one agent session per item, all at once, then the integrator;
   - `run_mode: main`: one item at a time in the project folder. A run asked for meanwhile waits in the board's **queue**; **remove from queue** takes it out.
 
-  A run asks first: it spends the subscription. **Stop** on a running item ends its session; the item stays ready and its work is kept. A queued main run that the next one would repeat (the harness did not start, or another run works the checkout) pauses the queue; the next run that works resumes it. The queue lives in the board's memory: a board restart forgets it.
+  A run asks first: it spends the subscription. **Stop** on a running item ends its session; the item stays ready and its work is kept. A queued main run that the next one would repeat (the harness did not start, or another run works the checkout) pauses the queue: the header shows **queue paused — resume**; fix the cause, then resume. A card marked **interrupted** had a run that stopped (a timeout, a stop, a crash): run it again and the run resumes its work. When a run ends, a toast lists each item's result. The queue lives in the board's memory: a board restart forgets it.
 - **Run next N independent**: the framework's gate picks the ready items that can run together now, by priority, and the board runs them after asking.
 - **Priority**: drop a ready card on another to put it before; the column's ranks are committed (`gcf prioritize`).
 - **Questions**: each D1 shows its question and proposed answer; **Answer** writes yours into its record (`gcf question answer`), and the next agent on its units puts it in place.
@@ -57,7 +58,8 @@ The page updates by itself: the server watches each project's `gcf/` and `.gcf-s
 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.
+- The token, kept in `~/.gcf/board-token`, opens the board once per server start; delete that file to make a new one. The browser then holds a session cookie that dies with the server: a browser sends a `127.0.0.1` cookie to every local port, so the cookie is never the token.
+- Started while another program holds its port, it refuses rather than hand the token to that program.
 - 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.

package/dist/server/app.js

@@ -1,8 +1,9 @@
 // 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 { randomBytes } from 'node:crypto';
 import { createServer } from 'node:http';
-import { existsSync } from 'node:fs';
+import { existsSync, statSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { BOARD_SCHEMA } from '../shared/board.js';
@@ -13,7 +14,7 @@ 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 { runsOf, startRun, unqueue } from './runs.js';
+import { resumeQueue, runsOf, startRun, unqueue } from './runs.js';
 const send = (res, status, body) => {
     res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
     res.end(JSON.stringify(body));
@@ -67,9 +68,12 @@ async function sendPage(res, web, pathname) {
         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');
+    const root = path.resolve(web);
+    let file = path.resolve(root, rel);
+    const inside = path.relative(root, file);
+    const out = !inside || inside.startsWith('..') || path.isAbsolute(inside);
+    if (out || !existsSync(file) || statSync(file).isDirectory())
+        file = path.join(root, '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' });
@@ -205,6 +209,14 @@ export function createApp(o) {
                 send(res, 200, { ok: r.ok, out: r.out.trim(), err: briefError(r.err) });
             },
         ],
+        [
+            'POST',
+            /^\/api\/p\/([^/]+)\/queue\/resume$/,
+            async (_req, res, m) => {
+                resumeQueue((await projectOf(m[1])).name);
+                send(res, 200, { ok: true });
+            },
+        ],
         [
             'DELETE',
             /^\/api\/p\/([^/]+)\/queue\/([a-z0-9][a-z0-9-]*)$/,
@@ -214,19 +226,22 @@ export function createApp(o) {
             },
         ],
     ];
+    // The cookie holds this process's own session, never the token: a browser sends a cookie of
+    // 127.0.0.1 to every local port, and a session dies with the server, the token does not.
+    const session = randomBytes(24).toString('hex');
     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=/`,
+                'set-cookie': `${COOKIE}=${session}; 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);
+        const gate = admit(req, o.port, session);
         if (!gate.ok) {
             send(res, gate.status, { error: gate.message });
             return;
@@ -247,7 +262,8 @@ export function createApp(o) {
             send(res, e instanceof HttpError ? e.status : 500, { error: e.message });
         });
     });
-    server.on('listening', () => void watchAll());
+    // A broken projects.json must not take the server down: the page shows the error instead.
+    server.on('listening', () => watchAll().catch((e) => console.error(`gcf-board: ${e.message}`)));
     server.on('close', () => {
         for (const stop of watchers.values())
             stop();

package/dist/server/cli.js

@@ -1,7 +1,7 @@
 // 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 { existsSync, 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
@@ -11,14 +11,37 @@ import path from 'node:path';
 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 dir = globalRoots()
+        .map((root) => path.join(root, 'ai-factory'))
+        .find((d) => existsSync(path.join(d, 'package.json')));
+    if (!dir)
+        throw new Error('ai-factory is not installed globally: npm i -g 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);
 }
+/**
+ * Where global packages live: what `npm root -g` says, then the folders beside this node. A
+ * shortcut starts the board with a PATH that may have no npm (fnm, volta, nvm); the node it
+ * runs keeps its global packages next to itself.
+ */
+function globalRoots() {
+    const roots = [];
+    try {
+        roots.push(execSync('npm root -g', { encoding: 'utf8', stdio: 'pipe' }).trim());
+    }
+    catch {
+        // No npm on PATH: the folders beside this node still hold the global packages.
+    }
+    const bin = path.dirname(process.execPath);
+    roots.push(path.join(bin, 'node_modules'), path.join(bin, '..', 'lib', 'node_modules'));
+    // npm's default prefix on Windows.
+    if (process.env.APPDATA)
+        roots.push(path.join(process.env.APPDATA, 'npm', 'node_modules'));
+    return roots;
+}
 /**
  * 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.

package/dist/server/desktop.js

@@ -56,8 +56,10 @@ export function createShortcut(main, port) {
         const r = spawnSync('powershell', ['-NoProfile', '-Command', plan.powershell], {
             encoding: 'utf8',
         });
+        if (r.error)
+            throw new Error(`the shortcut needs PowerShell: ${r.error.message}`);
         if (r.status !== 0)
-            throw new Error(`the shortcut was not made: ${r.stderr.trim()}`);
+            throw new Error(`the shortcut was not made: ${(r.stderr ?? '').trim()}`);
         return r.stdout.trim();
     }
     mkdirSync(path.dirname(plan.file), { recursive: true });

package/dist/server/main.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-// `gcf-board [--port <n>] [--no-open]`: the board on http://127.0.0.1:<port>, 4317 by default,
+// `gcf-board [--port <n>] [--no-open] [--version]`: the board on http://127.0.0.1:<port>, 4317 by default,
 // opened in the browser with this machine's token. A board already on the port is opened, not
 // started twice. `gcf-board shortcut [--port <n>]` puts a desktop shortcut that does the same.
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
@@ -21,14 +21,41 @@ function webDir() {
         ? fromSource
         : path.resolve(HERE, '..', 'web');
 }
+/** This package's version: package.json sits above `server/` in the source, above `dist/server/` when installed. */
+function version() {
+    for (const up of ['..', path.join('..', '..')]) {
+        const file = path.resolve(HERE, up, 'package.json');
+        if (existsSync(file))
+            return JSON.parse(readFileSync(file, 'utf8')).version;
+    }
+    return 'unknown';
+}
+/** Whether a gcf-board answers on the port: it refuses a request without its cookie, by name. */
+async function isBoard(port) {
+    try {
+        const res = await fetch(`http://127.0.0.1:${port}/api/projects`, {
+            signal: AbortSignal.timeout(2000),
+        });
+        const body = (await res.json().catch(() => ({})));
+        return res.status === 401 && /gcf-board/.test(String(body.error));
+    }
+    catch {
+        return false;
+    }
+}
 async function main() {
     const { values, positionals } = parseArgs({
         allowPositionals: true,
         options: {
             port: { type: 'string', default: '4317' },
             'no-open': { type: 'boolean', default: false },
+            version: { type: 'boolean', short: 'v', default: false },
         },
     });
+    if (values.version) {
+        console.log(version());
+        return;
+    }
     const port = Number(values.port);
     if (!Number.isInteger(port) || port < 1 || port > 65535)
         throw new Error('--port is a number from 1 to 65535');
@@ -42,16 +69,23 @@ async function main() {
     const url = `http://127.0.0.1:${port}/?t=${token}`;
     const open = () => !values['no-open'] && openInBrowser(url);
     const app = createApp({ entry: aiFactoryEntry(), token, port, web: webDir() });
-    app.on('error', (e) => {
-        if (e.code !== 'EADDRINUSE')
-            throw e;
-        // A second start, from the shortcut most likely: the board runs already, show it.
+    app.on('error', async (e) => {
+        if (e.code !== 'EADDRINUSE') {
+            console.error(`gcf-board: cannot listen on port ${port}: ${e.message}`);
+            process.exit(1);
+        }
+        // A second start, from the shortcut most likely: the board runs already, show it. Another
+        // program on the port must not get the token in a URL.
+        if (!(await isBoard(port))) {
+            console.error(`gcf-board: port ${port} is taken by another program: gcf-board --port <n>`);
+            process.exit(1);
+        }
         console.log(`gcf-board: already running on port ${port}, opening it`);
         open();
         setTimeout(() => process.exit(0), 500);
     });
     app.listen(port, '127.0.0.1', () => {
-        console.log(`gcf-board: ${url}`);
+        console.log(`gcf-board ${version()}: ${url}`);
         open();
     });
 }

package/dist/server/registry.js

@@ -13,7 +13,13 @@ const NAME = /^[a-z0-9][a-z0-9-]*$/;
 export async function listProjects() {
     if (!existsSync(registryFile()))
         return [];
-    const data = JSON.parse(await readFile(registryFile(), 'utf8'));
+    let data;
+    try {
+        data = JSON.parse(await readFile(registryFile(), 'utf8'));
+    }
+    catch {
+        throw new HttpError(500, `${registryFile()} is not JSON: fix it or delete it`);
+    }
     return Array.isArray(data?.projects) ? data.projects : [];
 }
 async function save(projects) {

package/dist/server/runs.js

@@ -4,17 +4,35 @@
 // In `run_mode: main` the checkout takes one run at a time: a run asked for meanwhile waits in
 // the project's queue and starts when the one before it ends.
 import { spawn } from 'node:child_process';
+import { briefError } from './cli.js';
 import { broadcast } from './events.js';
 import { HttpError } from './http-error.js';
 // A board that stops leaves its runs going: killing one would lose its integrate step.
 const active = new Set();
 const queues = new Map();
+// Projects whose queue waits after a failure the next run would repeat (`stalled`).
+const paused = new Set();
 export const activeRuns = (project) => [...active].filter((r) => r.project === project);
-/** What runs and what waits, for a project. */
+/** What runs and what waits, for a project; a paused queue waits for `resumeQueue`. */
 export const runsOf = (project) => ({
     active: activeRuns(project),
     queued: (queues.get(project) ?? []).flatMap((q) => q.ids),
+    paused: paused.has(project),
 });
+/** Start the next queued batch when the checkout is free: after a run, or on the operator's resume. */
+function advance(project) {
+    if (paused.has(project) || activeRuns(project).some((r) => r.mode === 'main'))
+        return;
+    const next = queues.get(project)?.shift();
+    if (next)
+        spawnRun(next, next.mode);
+}
+/** The operator resumes a paused queue (after fixing what stopped it). */
+export function resumeQueue(project) {
+    paused.delete(project);
+    advance(project);
+    broadcast({ type: 'board', project });
+}
 /** Take an item out of the queue before its run starts. */
 export function unqueue(project, id) {
     const queue = (queues.get(project) ?? [])
@@ -26,8 +44,7 @@ export function unqueue(project, id) {
 /**
  * Whether a main run ended in a way the next one would repeat: no report at all (the harness
  * did not start), or every item refused because another run works the checkout. The queue
- * then waits instead of draining into the same error; a run started by hand that works
- * resumes it.
+ * then waits instead of draining into the same error, until the operator resumes it.
  */
 export function stalled(ok, result) {
     if (!ok && result === null)
@@ -60,13 +77,22 @@ function spawnRun({ entry, p, ids }, mode) {
         catch {
             // No report: the error says why.
         }
-        const paused = mode === 'main' && queues.get(p.name)?.length && stalled(ok, result);
-        const why = paused ? '\nthe queue is paused: the next run starts after a run that works' : '';
-        broadcast({ type: 'run', project: p.name, ids, ok, result, err: (err + message + why).trim() });
+        const stop = mode === 'main' && queues.get(p.name)?.length && stalled(ok, result);
+        if (stop)
+            paused.add(p.name);
+        const why = stop ? '\nthe queue is paused: fix the cause, then resume it on the board' : '';
+        const brief = err && briefError(err);
+        broadcast({
+            type: 'run',
+            project: p.name,
+            ids,
+            ok,
+            result,
+            err: (brief + message + why).trim(),
+        });
+        if (mode === 'main')
+            advance(p.name);
         broadcast({ type: 'board', project: p.name });
-        const next = mode === 'main' && !paused ? queues.get(p.name)?.shift() : undefined;
-        if (next)
-            spawnRun(next, next.mode);
     };
     child.on('error', (e) => end(false, e.message));
     child.on('close', (code) => end(code === 0));