gcf-board 0.20.0 → 0.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -6,6 +6,7 @@ A local web board for game projects on [GCF](../gcf-aif-ext): the items by statu
6
6
 
7
7
  - Node.js ≥ 22.18
8
8
  - [`ai-factory`](https://www.npmjs.com/package/ai-factory) installed globally, and in each project [`gcf-aif-ext`](../gcf-aif-ext) ≥ 0.18 (`gcf board --json` with `schema: 4`: the columns, the moves, the item's fields, the blocks and the Help terms come from it as data)
9
+ - for 0.21: `gcf-aif-ext` ≥ 0.23 for **amend** (an older core offers no such move)
9
10
  - for 0.20: `gcf-aif-ext` ≥ 0.22 for **Changes** (an older core shows neither the screen nor its marker)
10
11
  - for runs: [`gcf-harness-aif-ext`](../gcf-harness-aif-ext) ≥ 0.11 (every board run opens its chat: `--chat`, `gcf-harness chat`; it waits the project's answer time) and Claude Code (`claude -p`); ≥ 0.12 to wait for the usage limit's reset and for queued runs (`--wait-limit`)
11
12
  - for the project chat: `gcf-aif-ext` ≥ 0.12 (`domain.chat`, `agent.rules`) and Claude Code
@@ -42,6 +43,9 @@ The board knows no domain by name: the project's board read gives its columns, m
42
43
  - **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, **needs N** and **needed by N**. 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. Pointing at a card (or focusing it from the keyboard) lights up the cards it needs and the cards that need it, each saying how, and dims the rest. The toolbar (board 0.9.0, core 0.13.0) searches ids and titles, keeps **waiting for me**, filters by the fields the domain marks `filter` (GCF: type, gate, severity, system, milestone; several values at once, each a chip to take off) and lays the board out in lanes by a field it marks `group` (system, parent, milestone): an item with two systems stands in both lanes, one with none in **none**, a parent lane is named by the feature's title. The mouse drags the board sideways from its empty space; the wheel over a column with no scroll of its own pans it.
43
44
  - **An item** (a window over the screen, dragged by its head; a page on a phone; board 0.14.0): its **Status** (why it is blocked or waits, its fields, its dependencies; it opens there when it is blocked or waits), its file (the front matter folded, a `key:` body by sections), its plan and its run log as it grows, its **Lessons**, 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. **Dependencies**: what it needs that has not ended in history (an item with its column, a design unit with its TBDs or the questions that block it, a graveyard line, an unknown id) and the items that need it, each a link; **Edit…** opens the picker of the board's items and design units (search by id and title, or type an id), and Save sends the `depends` move's adds and removes. **History** (core 0.13.0): its moves newest first, when, which, who (a run, your session, you; unknown on a commit older than the framework's marks), the commit and its subject; then its runs, as on the Runs screen. **Related**: its feature's other children, and the graveyard lines tagged with its system ("did we kill this before?"). An item that ended opens from **Ended** with its History.
44
45
  - **Runs** (harness 0.13.0): what runs now with the run's model and effort, its last log lines, **Whole log** and **Stop**; the queue with what each item will run on; the past runs of the harness's run log, newest first, 50 at a time: start, end, mode, cost, and per item its result word, the reason word for word, cost, tokens, turns, handoffs, a broken step and what it ran on. **log** opens the part of the item's log that run wrote, **chat** that run's chat. Every start the operator asks for (Run selected, Run next, a drop on running, this screen) asks first with a model and effort picker for that run only (**default: each item's own**); the drawer's Run is one click. An older harness shows the active runs only, and the dialog has no pickers. The API: `GET /api/p/<project>/runs/past?limit=` (`gcf-harness runs --json`; 404 without a harness that keeps them), `GET …/item/<id>/history` (`{id, moves, runs}`), `GET …/log/<id>?from=&to=` (a past run's part, once: `{text, cut}`, at most its last 2 MB; without `from` and `to` the log as it grows), `POST …/run` with `model` and `effort`, `POST …/inbox/<entry>/draft` (`{thread, created}`).
46
+ - **Log** (board 0.20.1, gcf-session 0.18.1): a subagent's lines say so (`subagent:`, `subagent tool:`, `subagent tool error:`), drawn as the main agent's kinds; the pulse's current action names a subagent's call as one.
47
+ - **Amend** (board 0.21.0, core 0.23.0): under "more" on a card: the form opens on its text, shows old and new lines before the move, and refuses an edit made meanwhile with the text you typed kept beside it. A chat agent's proposal shows the same lines. During that card's run it is refused, and the proposal offers **Send to the run**, to a live session only.
48
+ - **Run again** (board 0.20.1): an item a main batch has ended, blocked for one, can be run again while the batch goes on: it queues behind the batch. An item the batch works or has yet to reach is still refused with `already running from this board`, and so is every item of a worktree batch until that batch ends.
45
49
  - **Changes** (board 0.20.0, core 0.22.0): what is not committed and how it differs, view only: the agent commits. The header's `● 7 changed` counts the main checkout, and says `run writing in main` while a run works there; the screen switches between the main checkout and each run's worktree. A text file opens its diff, a picture its before and after; a binary file, the project's `no_diff:` globs (one glob a line in Settings), links, submodules, nested repositories and Git LFS files are listed and open nothing. It follows a move, a commit or an add at once, a save in an editor within 30 s.
46
50
  - **Drag**:
47
51
  - a ready card into **running** starts its run;
@@ -152,7 +152,7 @@ const headOf = (dir) => new Promise((resolve) => execFile('git', ['rev-parse', '
152
152
  /** Whether the usage limit holds for the account now (decision 22): Draft waits for its reset. */
153
153
  const limitHolds = (q) => q?.info.status === 'rejected' && (q.info.resetsAt ?? 0) * 1000 > Date.now();
154
154
  /** The ISO time a file was last written, or null when it is not there. */
155
- /** The last `tool: …` line of a run log's last 16 KB, without its clock; null without one. */
155
+ /** The last call of a run log's last 16 KB, a subagent's too, without its clock; null without one. */
156
156
  export function doingOf(file) {
157
157
  let text = '';
158
158
  try {
@@ -174,7 +174,7 @@ export function doingOf(file) {
174
174
  const line = text
175
175
  .split(/\r?\n/)
176
176
  .reverse()
177
- .find((l) => /(^|\] )tool: /.test(l));
177
+ .find((l) => /(^|\] )(subagent )?tool: /.test(l));
178
178
  return line ? line.replace(/^\[[^\]]*\] /, '').slice(0, 200) : null;
179
179
  }
180
180
  const activeAt = (file) => {
@@ -555,11 +555,15 @@ export function createApp(o) {
555
555
  const body = await bodyOf(req, CHAT_BODY_MAX);
556
556
  await withUploads(p.path, body);
557
557
  const line = chatInput(body, await unitsFor(p, body));
558
+ // A decision for the run itself: a run ended meanwhile hands it to no other agent.
559
+ const liveOnly = body.live_only === true;
558
560
  let harness;
559
561
  try {
560
562
  harness = await harnessOf(p);
561
563
  }
562
564
  catch (e) {
565
+ if (liveOnly)
566
+ throw new HttpError(409, 'no live session takes it: no harness here');
563
567
  // No harness, so no run: a message goes to the item's thread all the same.
564
568
  const t = line.type === 'say' ? await toThread(p, m[2], line) : null;
565
569
  if (t)
@@ -589,7 +593,7 @@ export function createApp(o) {
589
593
  return send(res, 202, { ok: true });
590
594
  // No live run session: a message goes to the item's thread of the project chat (AD-49).
591
595
  // An item the board read knows: a stale or mistyped id gets no thread.
592
- const t = r.code === 3 && line.type === 'say' ? await toThread(p, m[2], line) : null;
596
+ const t = r.code === 3 && line.type === 'say' && !liveOnly ? await toThread(p, m[2], line) : null;
593
597
  if (t)
594
598
  return send(res, 202, t);
595
599
  const why = briefError(r.err || r.out).replace(/^[\w-]+ chat: /, '');
@@ -830,6 +834,29 @@ export function createApp(o) {
830
834
  });
831
835
  },
832
836
  ],
837
+ [
838
+ // What a fix of an item's text would change (core 0.23): its `--dry-run --json`, for the
839
+ // form and an agent's proposal. A POST: the text may run past a URL's limit.
840
+ 'POST',
841
+ /^\/api\/p\/([^/]+)\/item\/([a-z0-9][a-z0-9-]*)\/amend\/preview$/,
842
+ async (req, res, m) => {
843
+ const p = await projectOf(m[1]);
844
+ const asked = await bodyOf(req, CHAT_BODY_MAX);
845
+ const { moves } = domains.get(p.name) ?? (await boardOf(p)).domain;
846
+ if (!moves.amend?.preview)
847
+ throw new HttpError(404, 'this core has no preview of a fix');
848
+ const b = {
849
+ cmd: 'amend',
850
+ id: m[2],
851
+ ...Object.fromEntries(['text', 'add', 'title', 'from'].filter((k) => asked[k]).map((k) => [k, asked[k]])),
852
+ };
853
+ const args = [...moveArgs(b, moves), '--dry-run', '--json'];
854
+ const r = await cli(p, args, undefined, moveInput(b, moves));
855
+ if (!r.ok)
856
+ throw new HttpError(400, briefError(r.err || r.out));
857
+ send(res, 200, jsonOf(r, 'item amend --dry-run'));
858
+ },
859
+ ],
833
860
  [
834
861
  // The hand edits a `dirty` refusal names (core 0.20): the staged part and the part not
835
862
  // staged, read by `gcf edits diff`. Paths under gcf/ only, as the refusal gives them.
@@ -44,22 +44,27 @@ function globalRoots() {
44
44
  return roots;
45
45
  }
46
46
  /**
47
- * The refusal an operator reads: the core throws, and node prints the stack under an
48
- * `Error: <message>` header, every line of the message (a git failure's cause comes after its
49
- * first line). Anything else is shown as it came.
47
+ * The refusal an operator reads: core 0.22.2 prints its words alone, shown as they came. An
48
+ * older core throws, and node prints the stack under an `Error: <message>` header, every line of
49
+ * the message (a git failure's cause comes after its first line).
50
50
  */
51
51
  export function briefError(err) {
52
52
  // The core's machine line is for the board (refusalOf), not for the operator to read.
53
53
  const words = err.replace(REFUSAL_LINE, '');
54
- const m = words.match(/^\w*Error: ([\s\S]*?)\r?\n {4}at /m) ?? words.match(/^\w*Error: (.+)$/m);
54
+ // Only node's crash opens with its frame or its header: an `Error: …` line further down belongs
55
+ // to the words (a hook's output a refusal quotes).
56
+ const crash = /^(.+:\d+|\w*Error: .*)\r?$/.test(words.trimStart().split('\n', 1)[0]);
57
+ const m = crash
58
+ ? (words.match(/^\w*Error: ([\s\S]*?)\r?\n {4}at /m) ?? words.match(/^\w*Error: (.+)$/m))
59
+ : null;
55
60
  return (m?.[1] ?? words).replaceAll('\r', '').trim();
56
61
  }
57
62
  const REFUSAL_LINE = /^gcf-refusal: .*(\r?\n)?/gm;
58
63
  /**
59
64
  * The core's machine refusal in a command's error (core 0.20): its last `gcf-refusal: {…}`
60
- * line, read as data, never its words. Only `dirty` is known; a path not under `gcf/`, or one
61
- * climbing out of it, is left out (the edits commands refuse it too). Undefined for an older
62
- * core, a broken line or no path left.
65
+ * line, read as data, never its words. Only the codes of `Refusal` are known; a path not under
66
+ * `gcf/`, or one climbing out of it, is left out (the edits commands refuse it too). Undefined
67
+ * for an older core, a broken line or no path left.
63
68
  */
64
69
  export function refusalOf(err) {
65
70
  const last = [...err.matchAll(/^gcf-refusal: (.+?)\r?$/gm)].at(-1)?.[1];
@@ -73,6 +78,8 @@ export function refusalOf(err) {
73
78
  return undefined;
74
79
  }
75
80
  const { code, paths, left } = (data ?? {});
81
+ if (code === 'running' || code === 'stale')
82
+ return { code };
76
83
  if (!Array.isArray(paths))
77
84
  return undefined;
78
85
  const safe = (a) => (Array.isArray(a) ? a : []).filter(gatePath);
@@ -63,15 +63,24 @@ async function readChanges(project, w) {
63
63
  // The first read names the files: the next poll has no stamp of them, and reads once more.
64
64
  if (read?.watch && !w.files.length)
65
65
  w.files = [read.watch.index, read.watch.head];
66
- if (busy || read) {
67
- const event = { type: 'changes', count: read ? read.count : null };
68
- w.last = `data: ${JSON.stringify(event)}\n\n`;
69
- for (const c of w.clients)
70
- c.write(w.last);
71
- }
66
+ w.last = `data: ${JSON.stringify(markerEvent(busy, read))}\n\n`;
67
+ for (const c of w.clients)
68
+ c.write(w.last);
72
69
  } while (w.again && changesWatches.get(project) === w);
73
70
  w.reading = false;
74
71
  }
72
+ /**
73
+ * What the marker says: a run's work, or the count. `unknown` when the read failed, or when the
74
+ * project is not in git, whose count of 0 would read as a clean checkout: said, not left out, as
75
+ * a page still shows what the last read told it.
76
+ */
77
+ export function markerEvent(busy, read) {
78
+ if (busy)
79
+ return { type: 'changes', count: null };
80
+ return read && read.base !== null
81
+ ? { type: 'changes', count: read.count }
82
+ : { type: 'changes', count: null, unknown: true };
83
+ }
75
84
  /** A project's files moved, or a run began or ended: read its marker if a page shows it. */
76
85
  export function signalChanges(project) {
77
86
  const w = changesWatches.get(project);
@@ -333,6 +333,9 @@ export function stalled(ok, result) {
333
333
  if (!ok && result === null)
334
334
  return true;
335
335
  const items = result?.items ?? [];
336
+ // A card left code uncommitted: the next batch would be built on it (harness 0.22).
337
+ if (items.some((i) => i.left?.length))
338
+ return true;
336
339
  return (items.length > 0 && items.every((i) => /another run works in the main/.test(i.error ?? '')));
337
340
  }
338
341
  /**
@@ -654,10 +657,28 @@ export function adoptRuns(entry, p) {
654
657
  changed(p.name);
655
658
  void pilot(p.name);
656
659
  }
660
+ /**
661
+ * Whether a main run has ended `id`: its lock names the item it works now, one later in its batch.
662
+ * No such word, and the run still holds the id.
663
+ * shortcut: a worktree batch holds an ended item until the batch ends, as no file says it ended;
664
+ * upgrade when one does.
665
+ */
666
+ function gonePast(p, run, id) {
667
+ if (run.mode !== 'main')
668
+ return false;
669
+ try {
670
+ const lock = path.join(p.path, '.gcf-session', 'runs', '.main-run.lock');
671
+ const now = readFileSync(lock, 'utf8').split('\n')[1]?.trim() ?? '';
672
+ return run.ids.indexOf(now) > run.ids.indexOf(id);
673
+ }
674
+ catch {
675
+ return false;
676
+ }
677
+ }
657
678
  /** A 409 for the ids a run of this board drives or queues: a second click on the same card. */
658
679
  export function busyCheck(p, ids) {
659
680
  const { active: going, queued } = runsOf(p.name);
660
- const busy = ids.filter((id) => queued.includes(id) || going.some((r) => r.ids.includes(id)));
681
+ const busy = ids.filter((id) => queued.includes(id) || going.some((r) => r.ids.includes(id) && !gonePast(p, r, id)));
661
682
  if (busy.length)
662
683
  throw new HttpError(409, `already running from this board: ${busy.join(', ')}`);
663
684
  }
@@ -799,7 +820,8 @@ function piloted(project, ok, result) {
799
820
  const stopped = items.filter((i) => /stopped/.test(`${i.result ?? ''} ${i.error ?? ''}`));
800
821
  // A timeout or a usage limit cut a session a rerun is meant to go on with.
801
822
  const cut = (i) => i.limit_resets !== undefined || /timed out/.test(`${i.result ?? ''} ${i.error ?? ''}`);
802
- const none = items.filter((i) => !MOVED.test(i.result ?? 'merged') && !cut(i));
823
+ // `skipped`: no session looked at it, so its next ask is no repeat of this one.
824
+ const none = items.filter((i) => !MOVED.test(i.result ?? 'merged') && !cut(i) && i.result !== 'skipped');
803
825
  for (const i of none)
804
826
  s.guard[i.id] = guardHash(s.p.path, i.id);
805
827
  if (stopped.length)
@@ -807,7 +829,7 @@ function piloted(project, ok, result) {
807
829
  const failed = items.filter((i) => ['error', 'conflict'].includes(i.result ?? ''));
808
830
  if (!ok || failed.length)
809
831
  return off('error', `a run failed${failed.length ? `: ${failed.map((i) => i.id).join(', ')}` : ''}`);
810
- if (none.length === items.length)
832
+ if (none.length && none.length === items.filter((i) => i.result !== 'skipped').length)
811
833
  off('no-move', `a run of ${items.map((i) => i.id).join(', ')} made no move`);
812
834
  }
813
835
  /** Whether the project is idle for the autopilot: no run, no queue, no pause. */
@@ -19,6 +19,8 @@ export function runModeOf(board, id, asked) {
19
19
  const own = board.items.find((i) => i.id === id)?.run_mode;
20
20
  return own === 'main' || own === 'worktree' ? own : board.run_mode;
21
21
  }
22
+ /** A refusal whose paths a board can show and fix. */
23
+ export const editsRefusal = (r) => (r && 'paths' in r ? r : undefined);
22
24
  /**
23
25
  * What is left of a refusal's `named` paths after `gcf edits` refused them as `clean`: the ones
24
26
  * still edited, none when another card's Commit or Discard took them all. Null: not that