gcf-board 0.0.0-stage → 0.2.0

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);
+});

package/dist/server/moves.js

@@ -0,0 +1,125 @@
+// The moves a board may run, each one `ai-factory gcf` command (Methodology §4.1, §11). Anything
+// else is refused: the board is a view, the commands own every rule. An operator's text goes
+// as one `--flag=value` argument, so no word of it reads as a flag.
+import { HttpError } from './http-error.js';
+const SLUG = /^[a-z0-9][a-z0-9-]*$/;
+function id(b, key = 'id') {
+    const v = b[key];
+    if (typeof v !== 'string' || !SLUG.test(v))
+        throw new HttpError(400, `${key} must be a lowercase hyphen slug`);
+    return v;
+}
+function text(b, key) {
+    const v = b[key];
+    if (v === undefined || v === null || v === '')
+        return undefined;
+    if (typeof v !== 'string')
+        throw new HttpError(400, `${key} must be text`);
+    return v;
+}
+function required(b, key) {
+    const v = text(b, key)?.trim();
+    if (!v)
+        throw new HttpError(400, `${key} is required`);
+    return v;
+}
+function oneOf(b, key, allowed) {
+    const v = b[key];
+    if (typeof v !== 'string' || !allowed.includes(v))
+        throw new HttpError(400, `${key} must be ${allowed.join(' | ')}`);
+    return v;
+}
+const opt = (b, key, flag = key) => {
+    const v = text(b, key);
+    return v === undefined ? [] : [`--${flag}=${v}`];
+};
+const many = (b, key) => {
+    const v = b[key];
+    if (v === undefined)
+        return [];
+    if (!Array.isArray(v) || v.some((x) => typeof x !== 'string'))
+        throw new HttpError(400, `${key} must be a list of text`);
+    return v.filter(Boolean).map((x) => `--${key}=${x}`);
+};
+/** `--remove` / `--no-remove` when the operator chose; the command's default otherwise. */
+const remove = (b) => b.remove === true ? ['--remove'] : b.remove === false ? ['--no-remove'] : [];
+const NEW_ITEM_OPTIONS = [
+    'gate',
+    'title',
+    'parent',
+    'system',
+    'depends',
+    'severity',
+    'blocked',
+    'from',
+    'reopens',
+    'milestone',
+    'release',
+    'channel',
+    'model',
+    'effort',
+];
+const MOVES = {
+    submit: (b) => ['submit', id(b)],
+    close: (b) => ['close', id(b), ...many(b, 'constraint')],
+    verdict: (b) => [
+        'verdict',
+        id(b),
+        oneOf(b, 'verdict', ['keep', 'tune', 'kill']),
+        ...opt(b, 'note'),
+        ...opt(b, 'tags'),
+        ...many(b, 'constraint'),
+        ...remove(b),
+    ],
+    decide: (b) => [
+        'decide',
+        id(b),
+        oneOf(b, 'choice', ['go', 'no', 'wontfix', 'known', 'close', 'continue', 'kill']),
+        ...opt(b, 'reason'),
+        ...remove(b),
+    ],
+    block: (b) => ['block', id(b), `--reason=${required(b, 'reason')}`],
+    unblock: (b) => ['unblock', id(b), ...opt(b, 'note')],
+    drop: (b) => [
+        'drop',
+        id(b),
+        `--reason=${required(b, 'reason')}`,
+        ...opt(b, 'tags'),
+        ...remove(b),
+    ],
+    'item-new': (b) => [
+        'item',
+        'new',
+        id(b),
+        `--type=${required(b, 'type')}`,
+        ...NEW_ITEM_OPTIONS.flatMap((k) => opt(b, k)),
+        '--commit',
+    ],
+    // `--` does not hold through ai-factory's nested commands: the text goes as one `--text=`.
+    'inbox-add': (b) => [
+        'inbox',
+        'add',
+        ...opt(b, 'source'),
+        '--commit',
+        `--text=${required(b, 'text')}`,
+    ],
+    '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) {
+    const cmd = typeof b.cmd === 'string' && Object.hasOwn(MOVES, b.cmd) ? b.cmd : null;
+    if (!cmd)
+        throw new HttpError(400, `unknown move: ${String(b.cmd)}`);
+    return ['gcf', ...MOVES[cmd](b)];
+}
+/** The ids of a run: one slug each, at least one. */
+export function runIds(b) {
+    const ids = b.ids;
+    if (!Array.isArray(ids) || !ids.length)
+        throw new HttpError(400, 'ids must be a non-empty list');
+    return [...new Set(ids.map((v) => id({ id: v })))];
+}

package/dist/server/registry.js

@@ -0,0 +1,65 @@
+// The projects a board shows: `~/.gcf/projects.json`, `{projects: [{name, path}]}`. The name is
+// the project's address in the API; the path is taken only here, never from a later request.
+import { existsSync } from 'node:fs';
+import { mkdir, readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { writeAtomic } from './atomic.js';
+import { HttpError } from './http-error.js';
+/** The board's own directory; GCF_BOARD_HOME moves it (tests, a second board). */
+export const homeDir = () => process.env.GCF_BOARD_HOME ?? path.join(os.homedir(), '.gcf');
+const registryFile = () => path.join(homeDir(), 'projects.json');
+const NAME = /^[a-z0-9][a-z0-9-]*$/;
+export async function listProjects() {
+    if (!existsSync(registryFile()))
+        return [];
+    const data = JSON.parse(await readFile(registryFile(), 'utf8'));
+    return Array.isArray(data?.projects) ? data.projects : [];
+}
+async function save(projects) {
+    await mkdir(homeDir(), { recursive: true });
+    await writeAtomic(registryFile(), `${JSON.stringify({ projects }, null, 2)}\n`);
+}
+// Changes run one after another: two adds at once would each write the list without the other.
+let queue = Promise.resolve();
+const serial = (change) => {
+    const next = queue.then(change, change);
+    queue = next.catch(() => { });
+    return next;
+};
+const nameOf = (dir) => path
+    .basename(dir)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'project';
+/** Register a project that has `gcf/`; its name defaults to its folder's. */
+export const addProject = (dir, name) => serial(() => add(dir, name));
+export const removeProject = (name) => serial(() => remove(name));
+async function add(dir, name) {
+    const abs = path.resolve(dir);
+    if (!existsSync(path.join(abs, 'gcf')))
+        throw new HttpError(400, `${abs} has no gcf/: run ai-factory gcf init there first`);
+    const projects = await listProjects();
+    const same = (p) => path.relative(p.path, abs) === '';
+    if (projects.some(same))
+        throw new HttpError(409, `${abs} is on the board already`);
+    const project = { name: name ?? nameOf(abs), path: abs };
+    if (!NAME.test(project.name))
+        throw new HttpError(400, 'a project name is a lowercase hyphen slug, e.g. zombie-puzzle');
+    if (projects.some((p) => p.name === project.name))
+        throw new HttpError(409, `the name ${project.name} is taken: give another`);
+    await save([...projects, project]);
+    return project;
+}
+async function remove(name) {
+    const projects = await listProjects();
+    if (!projects.some((p) => p.name === name))
+        throw new HttpError(404, `no project ${name}`);
+    await save(projects.filter((p) => p.name !== name));
+}
+export async function projectOf(name) {
+    const p = (await listProjects()).find((x) => x.name === name);
+    if (!p)
+        throw new HttpError(404, `no project ${name}`);
+    return p;
+}

package/dist/server/runs.js

@@ -0,0 +1,91 @@
+// 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 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);
+/** 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,
+        shell: false,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    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 end = (ok, message = '') => {
+        // A spawn that fails fires both error and close: one end only.
+        if (!active.delete(run))
+            return;
+        let result = null;
+        try {
+            result = JSON.parse(out);
+        }
+        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() });
+        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) };
+}

package/dist/shared/board.js

@@ -0,0 +1,11 @@
+// The read model of `ai-factory gcf board --json` (Methodology §11): the board refuses a schema
+// it does not know. Types only, plus the version this board reads.
+export const BOARD_SCHEMA = 1;
+export const STATUSES = [
+    'ready',
+    'blocked',
+    'awaiting-verdict',
+    'awaiting-decision',
+    'unplayed',
+    'parked',
+];