gcf-board 0.1.0 → 0.2.1

package/README.md

@@ -6,7 +6,8 @@ A local web board for game projects on [GCF](../gcf-aif-ext): the items by statu
 
 - 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`)
+- for runs: [`gcf-harness-aif-ext`](../gcf-harness-aif-ext) ≥ 0.8 and Claude Code (`claude -p`)
+- gcf-board 0.2 needs `gcf-aif-ext` ≥ 0.7 (priority, questions, session marks, `run_mode`)
 
 ## Run
 
@@ -16,7 +17,15 @@ 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**.
+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**.
+
+**Desktop shortcut**: run once
+
+```bash
+gcf-board shortcut                 # or: gcf-board shortcut --port 4400
+```
+
+It puts **GCF Board** on the desktop (Windows: a shortcut whose server console starts minimized; macOS: `GCF Board.command`; Linux: an application entry). Double-click it: the board starts and opens, or opens if it already runs. Run the command again after moving Node.js.
 
 ## What it does
 
@@ -28,7 +37,14 @@ It prints `http://127.0.0.1:4317/?t=<token>`: open that URL once. It sets a cook
   - 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.
+- **Run**: **run** on an item, or select ready cards and **Run selected**. It starts `ai-factory gcf-harness run <ids> --json` in the project's run mode:
+  - `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.
+- **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.
 - **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`.

package/dist/server/app.js

@@ -13,7 +13,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 { activeRuns, startRun } from './runs.js';
+import { 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));
@@ -83,6 +83,14 @@ export function createApp(o) {
                 watchers.set(p.name, watchProject(p));
     };
     const cli = (p, args, timeout) => runCli(o.entry, p.path, args, timeout);
+    /** `gcf board --json` of a project, refused when its schema is not the one this board reads. */
+    const boardOf = async (p) => {
+        const board = jsonOf(await cli(p, ['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');
+        return board;
+    };
     const routes = [
         ['GET', /^\/api\/events$/, async (_req, res) => subscribe(res)],
         ['GET', /^\/api\/projects$/, async (_req, res) => send(res, 200, await listProjects())],
@@ -113,11 +121,9 @@ export function createApp(o) {
             '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);
+                const p = await projectOf(m[1]);
+                // The board's own runs ride along: what it started and what waits in its queue.
+                send(res, 200, { ...(await boardOf(p)), runs: runsOf(p.name) });
             },
         ],
         [
@@ -167,14 +173,44 @@ export function createApp(o) {
         [
             'GET',
             /^\/api\/p\/([^/]+)\/runs$/,
-            async (_req, res, m) => send(res, 200, activeRuns((await projectOf(m[1])).name)),
+            async (_req, res, m) => send(res, 200, runsOf((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 ids = runIds(await bodyOf(req));
+                send(res, 202, startRun(o.entry, p, ids, (await boardOf(p)).run_mode));
+            },
+        ],
+        [
+            // The gate's pick: which ready items can run together now, by priority.
+            'GET',
+            /^\/api\/p\/([^/]+)\/next$/,
+            async (_req, res, m, url) => {
+                const count = String(Math.max(1, Math.min(20, Number(url.searchParams.get('count')) || 1)));
+                const r = await cli(await projectOf(m[1]), ['gcf-harness', 'next', count, '--json']);
+                send(res, 200, jsonOf(r, 'gcf-harness next'));
+            },
+        ],
+        [
+            'POST',
+            /^\/api\/p\/([^/]+)\/stop$/,
+            async (req, res, m) => {
+                const p = await projectOf(m[1]);
+                const [id] = runIds({ ids: [(await bodyOf(req)).id] });
+                const r = await cli(p, ['gcf-harness', 'stop', id]);
+                broadcast({ type: 'board', project: p.name });
+                send(res, 200, { ok: r.ok, out: r.out.trim(), err: briefError(r.err) });
+            },
+        ],
+        [
+            'DELETE',
+            /^\/api\/p\/([^/]+)\/queue\/([a-z0-9][a-z0-9-]*)$/,
+            async (_req, res, m) => {
+                unqueue((await projectOf(m[1])).name, m[2]);
+                send(res, 200, { ok: true });
             },
         ],
     ];

package/dist/server/desktop.js

@@ -0,0 +1,67 @@
+// The board without a console: open it in the browser, and a desktop shortcut that starts it.
+import { chmodSync, mkdirSync, writeFileSync } from 'node:fs';
+import { spawn, spawnSync } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+const NAME = 'GCF Board';
+/** Open a URL in the default browser; best effort, the URL is printed anyway. */
+export function openInBrowser(url) {
+    const [cmd, args] = process.platform === 'win32'
+        ? ['cmd', ['/c', 'start', '""', url]]
+        : process.platform === 'darwin'
+            ? ['open', [url]]
+            : ['xdg-open', [url]];
+    try {
+        spawn(cmd, args, { detached: true, stdio: 'ignore', windowsHide: true }).unref();
+    }
+    catch {
+        // No browser to open: the operator opens the printed URL.
+    }
+}
+/** A PowerShell single-quoted string: a quote inside is doubled. */
+const psQuote = (s) => `'${s.replaceAll("'", "''")}'`;
+export function shortcutPlan(platform, node, main, port) {
+    const args = ['--port', String(port)];
+    if (platform === 'win32')
+        return {
+            // A .lnk is a binary file: WScript.Shell writes it. Minimized: the server's console stays out
+            // of the way.
+            powershell: [
+                `$d = [Environment]::GetFolderPath('Desktop')`,
+                `$s = (New-Object -ComObject WScript.Shell).CreateShortcut((Join-Path $d '${NAME}.lnk'))`,
+                `$s.TargetPath = ${psQuote(node)}`,
+                `$s.Arguments = ${psQuote(`"${main}" ${args.join(' ')}`)}`,
+                `$s.WindowStyle = 7`,
+                `$s.Description = 'Start the GCF board and open it in the browser'`,
+                `$s.Save()`,
+                `Join-Path $d '${NAME}.lnk'`,
+            ].join('; '),
+        };
+    const command = `"${node}" "${main}" ${args.join(' ')}`;
+    if (platform === 'darwin')
+        return {
+            file: path.join(os.homedir(), 'Desktop', `${NAME}.command`),
+            text: `#!/bin/sh\nexec ${command}\n`,
+        };
+    return {
+        file: path.join(os.homedir(), '.local', 'share', 'applications', 'gcf-board.desktop'),
+        text: `[Desktop Entry]\nType=Application\nName=${NAME}\nExec=${command}\nTerminal=false\n` +
+            'Categories=Development;\n',
+    };
+}
+/** Write the shortcut for this machine; returns where it is. */
+export function createShortcut(main, port) {
+    const plan = shortcutPlan(process.platform, process.execPath, main, port);
+    if ('powershell' in plan) {
+        const r = spawnSync('powershell', ['-NoProfile', '-Command', plan.powershell], {
+            encoding: 'utf8',
+        });
+        if (r.status !== 0)
+            throw new Error(`the shortcut was not made: ${r.stderr.trim()}`);
+        return r.stdout.trim();
+    }
+    mkdirSync(path.dirname(plan.file), { recursive: true });
+    writeFileSync(plan.file, plan.text);
+    chmodSync(plan.file, 0o755);
+    return plan.file;
+}

package/dist/server/main.js

@@ -1,6 +1,7 @@
 #!/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.
+// `gcf-board [--port <n>] [--no-open]`: 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 path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -8,6 +9,7 @@ import { parseArgs } from 'node:util';
 import { boardToken } from './auth.js';
 import { aiFactoryEntry } from './cli.js';
 import { createApp } from './app.js';
+import { createShortcut, openInBrowser } from './desktop.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
@@ -20,14 +22,37 @@ function webDir() {
         : path.resolve(HERE, '..', 'web');
 }
 async function main() {
-    const { values } = parseArgs({ options: { port: { type: 'string', default: '4317' } } });
+    const { values, positionals } = parseArgs({
+        allowPositionals: true,
+        options: {
+            port: { type: 'string', default: '4317' },
+            'no-open': { type: 'boolean', default: false },
+        },
+    });
     const port = Number(values.port);
     if (!Number.isInteger(port) || port < 1 || port > 65535)
         throw new Error('--port is a number from 1 to 65535');
+    if (positionals[0] === 'shortcut') {
+        console.log(`gcf-board: shortcut ${createShortcut(fileURLToPath(import.meta.url), port)}`);
+        return;
+    }
+    if (positionals.length)
+        throw new Error(`unknown command: ${positionals.join(' ')}`);
     const token = await boardToken();
+    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.
+        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: http://127.0.0.1:${port}/?t=${token}`);
+        console.log(`gcf-board: ${url}`);
+        open();
     });
 }
 main().catch((e) => {

package/dist/server/moves.js

@@ -105,6 +105,9 @@ const MOVES = {
     ],
     'inbox-drop': (b) => ['inbox', 'drop', id(b), '--commit'],
     'phase-next': (b) => ['phase', 'next', ...opt(b, 'reason')],
+    // A column's new order after a drag: ranks 1, 2, 3… in one commit.
+    prioritize: (b) => ['prioritize', ...runIds(b)],
+    'question-answer': (b) => ['question', 'answer', id(b), `--text=${required(b, 'text')}`],
 };
 /** The `ai-factory` arguments of a move, or a 400 naming what is wrong. */
 export function moveArgs(b) {

package/dist/server/runs.js

@@ -1,19 +1,42 @@
 // Runs the board started: `ai-factory gcf-harness run <ids> --json`, one process per batch, held
 // by the server until every agent session ends. A run started from a console shows on the
-// board too (its lock makes the item `running`); only its final report is not here.
+// board too (its lock or session mark makes the item `running`); only its report is not here.
+// 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 { 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();
 export const activeRuns = (project) => [...active].filter((r) => r.project === project);
-/** Start a batch; its end is a `run` event with the harness report, or what went wrong. */
-export function startRun(entry, p, ids) {
-    // A second click on the same card: the harness would refuse it on its lock, noisily.
-    const busy = ids.filter((id) => activeRuns(p.name).some((r) => r.ids.includes(id)));
-    if (busy.length)
-        throw new HttpError(409, `already running from this board: ${busy.join(', ')}`);
-    const run = { project: p.name, ids, started: new Date().toISOString() };
+/** What runs and what waits, for a project. */
+export const runsOf = (project) => ({
+    active: activeRuns(project),
+    queued: (queues.get(project) ?? []).flatMap((q) => q.ids),
+});
+/** Take an item out of the queue before its run starts. */
+export function unqueue(project, id) {
+    const queue = (queues.get(project) ?? [])
+        .map((q) => ({ ...q, ids: q.ids.filter((x) => x !== id) }))
+        .filter((q) => q.ids.length);
+    queues.set(project, queue);
+    broadcast({ type: 'board', project });
+}
+/**
+ * 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.
+ */
+export function stalled(ok, result) {
+    if (!ok && result === null)
+        return true;
+    const items = result?.items ?? [];
+    return (items.length > 0 && items.every((i) => /another run works in the main/.test(i.error ?? '')));
+}
+function spawnRun({ entry, p, ids }, mode) {
+    const run = { project: p.name, ids, started: new Date().toISOString(), mode };
     active.add(run);
     const child = spawn(process.execPath, [entry, 'gcf-harness', 'run', ...ids, '--json'], {
         cwd: p.path,
@@ -37,10 +60,32 @@ export function startRun(entry, p, ids) {
         catch {
             // No report: the error says why.
         }
-        broadcast({ type: 'run', project: p.name, ids, ok, result, err: (err + message).trim() });
+        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() });
         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));
     return run;
 }
+/**
+ * Start a batch in the project's run mode, or queue it behind the main run going on. Its end
+ * is a `run` event with the harness report, or what went wrong.
+ */
+export function startRun(entry, p, ids, mode = 'worktree') {
+    // A second click on the same card: the harness would refuse it on its lock, noisily.
+    const { active: going, queued } = runsOf(p.name);
+    const busy = ids.filter((id) => queued.includes(id) || going.some((r) => r.ids.includes(id)));
+    if (busy.length)
+        throw new HttpError(409, `already running from this board: ${busy.join(', ')}`);
+    if (mode === 'main' && going.some((r) => r.mode === 'main')) {
+        queues.set(p.name, [...(queues.get(p.name) ?? []), { entry, p, ids, mode }]);
+        broadcast({ type: 'board', project: p.name });
+        return { queued: ids };
+    }
+    return { started: spawnRun({ entry, p, ids, mode }, mode) };
+}