gcf-board 0.3.0 → 0.4.1

package/README.md

@@ -5,7 +5,7 @@ A local web board for game projects on [GCF](../gcf-aif-ext): the items by statu
 ## 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.9 (`gcf board --json` with `schema: 2`: the columns and the item moves come from it as data)
+- [`ai-factory`](https://www.npmjs.com/package/ai-factory) installed globally, and in each project [`gcf-aif-ext`](../gcf-aif-ext) ≥ 0.10 (`gcf board --json` with `schema: 3`: the columns, the moves, the item's fields, the blocks and the Help terms come from it as data)
 - 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`)
 
@@ -30,8 +30,10 @@ It puts **GCF Board** on the desktop (Windows: a shortcut whose server console s
 
 ## What it does
 
+The board knows no domain by name: the project's board read gives its columns, moves with their forms, item fields, blocks and Help terms (`domain`, Board-PRD decision 16). For a GCF project:
+
 - **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. A running card shows when its run log was last written (`active 12 s ago`), and `quiet 6 min` when the log has been silent for 5 minutes or more. A run's end report gives each item's cost when the agent reported it.
-- **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.
+- **An item**: its file, its plan and its run log as it grows, its fields, and the moves the core offers for it (`items[].moves`, Methodology §4.1): run, verdict, decide, block, unblock, drop, close, submit, depends. Each move's form comes from the core; 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;
@@ -47,7 +49,9 @@ It puts **GCF Board** on the desktop (Windows: a shortcut whose server console s
 - **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.
+- **New item**: `gcf item new … --commit`, its form from the core: a bug asks its severity, a release its version and channel. The item's `model` and `effort` go to its run.
+- **Help** (**?**): the domain's terms, columns, moves and field values with what each means, and the words of runs, under one filter.
+- **Settings**: the keys of `gcf/config.yml` and the agents' language (`language.ui`, `language.artifacts` of `.ai-factory/config.yaml`), each a `gcf config set` commit.
 - **Inbox**: add, erase, or turn an entry into an item. Open questions are listed there too.
 - **Lessons** (core 0.7.10, harness 0.9.2): what got in an agent's way, asked at the end of each session, lands in the inbox with its kind (`tool`, `rules`, `framework`, `template`, `other`) and its item. The inbox filters them; a card shows `N lessons`, and the drawer lists the item's lessons with the inbox's buttons. A run's report line ends with `, N lessons`, and with `— code written outside aif-implement` when a session skipped that skill.
 - **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

@@ -1,7 +1,7 @@
 // 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, the run metrics
-// (`ai-factory gcf-harness metrics`). Writes: a project
-// on the board, a move, a run. Every write is a command of the framework.
+// (`ai-factory <harness> metrics`, the domain's harness). 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, statSync } from 'node:fs';
@@ -104,6 +104,23 @@ export function createApp(o) {
     const cli = (p, args, timeout) => runCli(o.entry, p.path, args, timeout);
     // The last domain each project's board read gave: an item move is built from its form.
     const domains = new Map();
+    /**
+     * The harness of a project's domain, or a 400: its agent's runs need one. A fresh read: the
+     * harness may have been installed or removed since the last one; a read that fails (a schema
+     * mismatch mid-run) falls back on the last domain, so a Stop still stops.
+     */
+    const harnessOf = async (p) => {
+        const domain = await boardOf(p).then((b) => b.domain, (e) => {
+            const last = domains.get(p.name);
+            if (!last)
+                throw e;
+            return last;
+        });
+        const h = domain.harness;
+        if (!h)
+            throw new HttpError(400, 'this project has no harness: its items run from a console');
+        return h;
+    };
     /** `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');
@@ -194,8 +211,9 @@ export function createApp(o) {
             'GET',
             /^\/api\/p\/([^/]+)\/metrics$/,
             async (_req, res, m) => {
-                const r = await cli(await projectOf(m[1]), ['gcf-harness', 'metrics', '--json']);
-                send(res, 200, jsonOf(r, 'gcf-harness metrics'));
+                const p = await projectOf(m[1]);
+                const harness = await harnessOf(p);
+                send(res, 200, jsonOf(await cli(p, [harness, 'metrics', '--json']), `${harness} metrics`));
             },
         ],
         [
@@ -234,8 +252,11 @@ export function createApp(o) {
             async (req, res, m) => {
                 const p = await projectOf(m[1]);
                 const body = await bodyOf(req);
-                const mode = (await boardOf(p)).run_mode;
-                send(res, 202, startRun(o.entry, p, runIds(body), mode, body.fresh === true));
+                const { run_mode: mode, domain } = await boardOf(p);
+                if (!domain.harness)
+                    throw new HttpError(400, 'this project has no harness: its items run from a console');
+                const ids = runIds(body);
+                send(res, 202, startRun(o.entry, p, ids, mode, body.fresh === true, domain.harness));
             },
         ],
         [
@@ -244,8 +265,9 @@ export function createApp(o) {
             /^\/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'));
+                const p = await projectOf(m[1]);
+                const harness = await harnessOf(p);
+                send(res, 200, jsonOf(await cli(p, [harness, 'next', count, '--json']), `${harness} next`));
             },
         ],
         [
@@ -254,7 +276,7 @@ export function createApp(o) {
             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]);
+                const r = await cli(p, [await harnessOf(p), 'stop', id]);
                 broadcast({ type: 'board', project: p.name });
                 send(res, 200, { ok: r.ok, out: r.out.trim(), err: briefError(r.err) });
             },

package/dist/server/moves.js

@@ -43,61 +43,13 @@ const list = (b, key, re, what, flag = key) => {
         throw new HttpError(400, `${key} must be a list of ${what}`);
     return v.length ? [`--${flag}=${v.join(',')}`] : [];
 };
-const idList = (b, key) => list(b, key, SLUG, 'ids');
+const idList = (b, key, flag = key) => list(b, key, SLUG, 'ids', flag);
 const tagList = (b, key, flag = key) => list(b, key, TAG, 'tags', flag);
 /** `--remove` / `--no-remove` when the operator chose; the command's default otherwise. */
 const remove = (b, key = 'remove', flag = key) => b[key] === true ? [`--${flag}`] : b[key] === false ? [`--no-${flag}`] : [];
-const NEW_ITEM_OPTIONS = [
-    'gate',
-    'title',
-    'parent',
-    'system',
-    'depends',
-    'severity',
-    'blocked',
-    'from',
-    'reopens',
-    'milestone',
-    'release',
-    'channel',
-    'model',
-    'effort',
-];
 const MOVES = {
     // A session's mark taken off: the item no longer shows running (Board-PRD §3.2, kind c).
     release: (b) => ['release', id(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'),
-        ...tagList(b, 'tags'),
-        '--commit',
-        `--text=${required(b, 'text')}`,
-    ],
-    'inbox-drop': (b) => ['inbox', 'drop', id(b), '--commit'],
-    'inbox-tag': (b) => [
-        'inbox',
-        'tag',
-        id(b),
-        ...tagList(b, 'add'),
-        ...tagList(b, 'remove'),
-        '--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)],
-    // The ids an item waits for, added and removed; the core refuses an unknown id and a cycle.
-    depends: (b) => ['depends', id(b), ...idList(b, 'add'), ...idList(b, 'remove')],
-    'question-answer': (b) => ['question', 'answer', id(b), `--text=${required(b, 'text')}`],
     // One setting of gcf/config.yml; the core checks the key and the value. An empty value takes
     // a number back to its default.
     'config-set': (b) => {
@@ -120,31 +72,52 @@ const MOVES = {
         return ['permissions', ...args];
     },
 };
-/** An item's move by its domain form: the words with the item's id, then each field's flag. */
+/** Whether a field goes: one with `when` only while the field it names holds one of its values. */
+const applies = (f, b) => !f.when || f.when.is.includes(String(b[f.when.key] ?? ''));
+/** A choice: one of its options' values, or nothing. */
+function choice(f, b, flag) {
+    const v = f.required ? required(b, f.key) : text(b, f.key);
+    if (v === undefined)
+        return [];
+    if (!(f.options ?? []).some((o) => o.value === v))
+        throw new HttpError(400, `${f.key} must be one of ${(f.options ?? []).map((o) => o.value).join(', ')}`);
+    return [`--${flag}=${v}`];
+}
+/** One field's arguments; a `slug` is the target itself (`{id}`), no flag. */
+function fieldArgs(f, b) {
+    const flag = f.flag ?? f.key;
+    if (f.kind === 'slug')
+        return [];
+    if (f.kind === 'list')
+        return many(b, f.key, flag);
+    if (f.kind === 'remove')
+        return remove(b, f.key, flag);
+    if (f.kind === 'ids')
+        return idList(b, f.key, flag);
+    if (f.kind === 'tags')
+        return tagList(b, f.key, flag);
+    if (f.kind === 'choice')
+        return choice(f, b, flag);
+    return f.required ? [`--${flag}=${required(b, f.key)}`] : opt(b, f.key, flag);
+}
+/** A move by its domain form: its words with the target, then each field that goes. */
 function domainMoveArgs(spec, b) {
-    const words = spec.args.map((w) => (w === '{id}' ? id(b) : w));
-    const flags = spec.fields.flatMap((f) => {
-        const flag = f.flag ?? f.key;
-        if (f.kind === 'list')
-            return many(b, f.key, flag);
-        if (f.kind === 'remove')
-            return remove(b, f.key, flag);
-        return f.required ? [`--${flag}=${required(b, f.key)}`] : opt(b, f.key, flag);
-    });
-    return [...words, ...flags];
+    const words = spec.args.flatMap((w) => w === '{id}' ? [id(b)] : w === '{ids}' ? runIds(b) : [w]);
+    return [...words, ...spec.fields.filter((f) => applies(f, b)).flatMap((f) => fieldArgs(f, b))];
 }
 /** Whether a move is the center's own: its arguments need no domain. */
 export const isCenterMove = (cmd) => typeof cmd === 'string' && Object.hasOwn(MOVES, cmd);
 /**
  * The `ai-factory` arguments of a move, or a 400 naming what is wrong: a center move, or one of
- * `moves`, the domain's forms from the project's board read.
+ * `moves`, the domain's forms from the project's board read. An agent's move is a run, not a
+ * command: it goes through the run route.
  */
 export function moveArgs(b, moves = {}) {
     const cmd = typeof b.cmd === 'string' ? b.cmd : '';
     if (isCenterMove(cmd))
         return ['gcf', ...MOVES[cmd](b)];
-    if (Object.hasOwn(moves, cmd))
-        return ['gcf', ...domainMoveArgs(moves[cmd], b)];
+    if (Object.hasOwn(moves, cmd) && moves[cmd].kind !== 'agent')
+        return domainMoveArgs(moves[cmd], b);
     throw new HttpError(400, `unknown move: ${String(b.cmd)}`);
 }
 /** The ids of a run: one slug each, at least one. */

package/dist/server/runs.js

@@ -1,4 +1,4 @@
-// Runs the board started: `ai-factory gcf-harness run <ids> --json`, one process per batch, held
+// Runs the board started: `ai-factory <harness> run <ids> --json` (GCF: gcf-harness), 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
@@ -119,7 +119,7 @@ function schedule(run, at) {
         liftLimitPause(project);
         try {
             if (s) {
-                const r = startRun(s.run.entry, s.run.p, s.run.ids, s.run.mode);
+                const r = startRun(s.run.entry, s.run.p, s.run.ids, s.run.mode, false, s.run.harness);
                 const how = 'queued' in r ? 'wait in the queue' : 'run again';
                 trace(project, 'resume', `the usage limit reset: ${s.run.ids.join(', ')} ${how}`);
             }
@@ -232,10 +232,10 @@ function isItem(i) {
     return typeof id === 'string' && (resets == null || typeof resets === 'string');
 }
 function spawnRun(q, mode) {
-    const { entry, p, ids } = q;
+    const { entry, p, ids, harness } = q;
     const run = { project: p.name, ids, started: new Date().toISOString(), mode };
     active.add(run);
-    const args = [entry, 'gcf-harness', 'run', ...ids, '--json', ...(q.fresh ? ['--fresh'] : [])];
+    const args = [entry, harness, 'run', ...ids, '--json', ...(q.fresh ? ['--fresh'] : [])];
     const child = spawn(process.execPath, args, {
         cwd: p.path,
         shell: false,
@@ -293,9 +293,10 @@ function spawnRun(q, mode) {
 /**
  * Start a batch in the project's run mode, or queue it behind the main run going on. Its end
  * is a run report with the harness report, or what went wrong. `fresh` starts new agent
- * sessions where the harness would resume the interrupted ones.
+ * sessions where the harness would resume the interrupted ones. `harness` is the domain's
+ * (`domain.harness`); the tests take GCF's.
  */
-export function startRun(entry, p, ids, mode = 'worktree', fresh = false) {
+export function startRun(entry, p, ids, mode = 'worktree', fresh = false, harness = 'gcf-harness') {
     // 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)));
@@ -314,9 +315,9 @@ export function startRun(entry, p, ids, mode = 'worktree', fresh = false) {
     }
     // A paused queue holds a new main run too: it would repeat the failure, and jump the queue.
     if (mode === 'main' && (paused.has(p.name) || going.some((r) => r.mode === 'main'))) {
-        queues.set(p.name, [...(queues.get(p.name) ?? []), { entry, p, ids, mode, fresh }]);
+        queues.set(p.name, [...(queues.get(p.name) ?? []), { entry, p, ids, mode, fresh, harness }]);
         broadcast({ type: 'board', project: p.name });
         return { queued: ids };
     }
-    return { started: spawnRun({ entry, p, ids, mode, fresh }, mode) };
+    return { started: spawnRun({ entry, p, ids, mode, fresh, harness }, mode) };
 }

package/dist/shared/board.js

@@ -1,3 +1,3 @@
 // 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 = 2;
+export const BOARD_SCHEMA = 3;