gcf-board 0.24.1 → 0.26.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.25: `gcf-aif-ext` ≥ 0.27 for **Push** and **Pull** on Changes and the header's `↑N` (an older core shows no strip)
9
10
  - for 0.23: `gcf-aif-ext` ≥ 0.25 and `gcf-harness-aif-ext` ≥ 0.24 for **Play** (an older core shows no bar)
10
11
  - for 0.22: `gcf-aif-ext` ≥ 0.24 and `gcf-harness-aif-ext` ≥ 0.23 for the **shelved** chip (an older pair stops a main batch at a card's loose code, as before)
11
12
  - for 0.21: `gcf-aif-ext` ≥ 0.23 for **amend** (an older core offers no such move)
@@ -49,7 +50,7 @@ The board knows no domain by name: the project's board read gives its columns, m
49
50
  - **Play** (board 0.24.0, core 0.26.0): a card waiting for play shows its build (one per code, `Same build as` when shared), **Play** per target of `play:` that builds first when there is none, **Stop** and **Change** (find again with agent, edit, build again), on its run's end card, in its window and on Playtest; **Set up** opens a chat thread whose agent finds the commands, **by hand** opens the form; **Play main** and **Build main** play the checkout as it is; a verdict stops the card's player and removes a build no other card holds.
50
51
  - **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.
51
52
  - **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.
52
- - **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.
53
+ - **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. Board 0.25 with core 0.27 adds **Push** on the main tab: how far the branch is ahead and behind its remote, the commits that go out and who made each, Push after a confirm, Pull when the remote moved on, both fast-forward only and never a force; `↑N` in the header counts what is not pushed. 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.
53
54
  - **Drag**:
54
55
  - a ready card into **running** starts its run;
55
56
  - a blocked or parked card into **ready** unblocks it;
@@ -24,7 +24,7 @@ import { isUpload, saveUpload, UPLOAD_MAX } from './upload.js';
24
24
  import { addProject, homeDir, listProjects, projectOf, removeProject, yoloFile, } from './registry.js';
25
25
  import { allThemes } from './themes.js';
26
26
  import { askIfDue, askUsage, configureUsage, lastUsage } from './usage.js';
27
- import { activeRuns, adoptRuns, busyCheck, keepProjects, sweepRuns, closeReport, forgetProject, resumeQueue, holdProject, retryWaiting, runsOf, setAutopilot, startRun, unqueue, whileClickBuilds, } from './runs.js';
27
+ import { activeRuns, adoptRuns, busyCheck, keepProjects, sweepRuns, closeReport, forgetProject, resumeQueue, holdProject, retryWaiting, runsOf, setAutopilot, startRun, unqueue, ticketState, watchTickets, } from './runs.js';
28
28
  import { acceptProposal, agentDefaults, agentPresets, chatCard, deniedGroupIn, lastDeniedOf, lastRunEnd, chatOf, entryTalk, listTalks, openTalk, pickTalk, prepareTalk, startDesign, startTalk, stopTalk, talkEntry, talkId, talkLive, talkSaid, talkWaits, watchTalks, writeTalk, } from './talks.js';
29
29
  import { accountSettings, saveAccountSettings, threadDir, threadOfEntry } from 'gcf-session';
30
30
  const send = (res, status, body) => {
@@ -75,9 +75,43 @@ const treeArgs = (url) => {
75
75
  return tree && tree !== 'main' ? [`--worktree=${tree}`] : [];
76
76
  };
77
77
  /** Parse the JSON a command printed, or say what it printed instead. */
78
- // How long the board waits for a build: the core ends it by the project's `dod_timeout_min`, and
79
- // the board must not cut it sooner, on POSIX with its engine still going.
80
- const PLAY_BUILD_MS = 24 * 60 * 60_000;
78
+ // A start that installs on a device (`launches`) takes longer than the CLI's two minutes.
79
+ const PLAY_START_MS = 30 * 60_000;
80
+ const WORD_RE = /^[\w][\w-]*$/;
81
+ // A device id goes into a shell command: the core takes only these characters (d5).
82
+ const DEVICE_RE = /^\w[\w.:-]*$/;
83
+ /** The core's command for a Play route, its body checked: words where words go. */
84
+ export function playArgs(what, body) {
85
+ const word = (v, name, re = WORD_RE) => {
86
+ if (typeof v !== 'string' || !re.test(v))
87
+ throw new HttpError(400, `${name} is one word`);
88
+ return v;
89
+ };
90
+ const flag = (v, name) => {
91
+ if (v !== undefined && typeof v !== 'boolean')
92
+ throw new HttpError(400, `${name} is true or false`);
93
+ return v === true;
94
+ };
95
+ // A card, or the checkout as it is ("Play main", docs/Play-Setup-Plan.md d30).
96
+ const who = () => (flag(body.main, 'main') ? ['--main'] : [word(body.id, 'id')]);
97
+ if (what === 'stop')
98
+ return ['gcf', 'playtest', 'stop', '--json'];
99
+ if (what === 'devices')
100
+ return ['gcf', 'playtest', 'devices', word(body.target, 'target'), '--json'];
101
+ if (what === 'build')
102
+ return [
103
+ ...['gcf', 'playtest', 'build', ...who(), '--queue', '--json'],
104
+ // "Build again" (d23): a snapshot of the same code is replaced, not taken.
105
+ ...(flag(body.fresh, 'fresh') ? ['--fresh'] : []),
106
+ ];
107
+ return [
108
+ ...['gcf', 'playtest', 'start', ...who(), '--queue', '--json'],
109
+ ...['--target', word(body.target, 'target')],
110
+ ...(body.device === undefined || body.device === null
111
+ ? []
112
+ : ['--device', word(body.device, 'device', DEVICE_RE)]),
113
+ ];
114
+ }
81
115
  function jsonOf(r, what) {
82
116
  try {
83
117
  return JSON.parse(r.out);
@@ -105,6 +139,7 @@ const questionText = (b, move, id) => {
105
139
  /** The core lists 2000 rows at most, so a Commit ticks no more. */
106
140
  const CHANGE_PATHS_MAX = 2000;
107
141
  const COMMIT_TIMEOUT_MS = 600_000;
142
+ export const PUSH_TIMEOUT_MS = 150_000;
108
143
  /** The most paths one edits diff takes: a refusal past this many is read in the console. */
109
144
  const EDIT_PATHS_MAX = 2000;
110
145
  /** The same for an older core, each path an argument (core 0.20.1). */
@@ -755,39 +790,40 @@ export function createApp(o) {
755
790
  [
756
791
  // Playing a card: the project's own commands, so POSTs with their Origin checked. A refusal
757
792
  // comes back as an error with its words; a build that failed is an answer (`ok: false`).
793
+ // A build, and a start with no build yet, go on a ticket (docs/Handoff-Plan.md d6, d9):
794
+ // the core starts its own waiter and answers `{ticket}` at once, which outlives this board.
758
795
  'POST',
759
- /^\/api\/p\/([^/]+)\/play\/(build|start|stop)$/,
796
+ /^\/api\/p\/([^/]+)\/play\/(build|start|stop|devices)$/,
760
797
  async (req, res, m) => {
761
798
  const p = await projectOf(m[1]);
762
- const body = await bodyOf(req);
763
- const word = (v, what) => {
764
- if (typeof v !== 'string' || !/^[\w][\w-]*$/.test(v))
765
- throw new HttpError(400, `${what} is one word`);
766
- return v;
767
- };
768
- const flag = (v, what) => {
769
- if (v !== undefined && typeof v !== 'boolean')
770
- throw new HttpError(400, `${what} is true or false`);
771
- return v === true;
772
- };
773
- // A card, or the checkout as it is ("Play main", docs/Play-Setup-Plan.md d30).
774
- const who = () => (flag(body.main, 'main') ? ['--main'] : [word(body.id, 'id')]);
775
- const args = m[2] === 'stop'
776
- ? ['gcf', 'playtest', 'stop', '--json']
777
- : m[2] === 'build'
778
- ? [
779
- ...['gcf', 'playtest', 'build', ...who(), '--json'],
780
- // "Build again" (d23): a snapshot of the same code is replaced, not taken.
781
- ...(flag(body.fresh, 'fresh') ? ['--fresh'] : []),
782
- ]
783
- : [
784
- ...['gcf', 'playtest', 'start', ...who(), '--json'],
785
- ...['--target', word(body.target, 'target')],
786
- ];
787
- // A build of a real game takes minutes.
788
- const r = m[2] === 'build'
789
- ? await whileClickBuilds(p, () => cli(p, args, PLAY_BUILD_MS))
790
- : await cli(p, args);
799
+ const args = playArgs(m[2], await bodyOf(req));
800
+ watchTickets(p);
801
+ const r = await cli(p, args, m[2] === 'start' ? PLAY_START_MS : undefined);
802
+ broadcast({ type: 'board', project: p.name });
803
+ try {
804
+ send(res, 200, JSON.parse(r.out));
805
+ }
806
+ catch {
807
+ throw new HttpError(409, briefError(r.err || r.out));
808
+ }
809
+ },
810
+ ],
811
+ [
812
+ // A ticket as it stands: waiting, building, or done with what its waiter ended with (d6).
813
+ 'GET',
814
+ /^\/api\/p\/([^/]+)\/play\/queue\/(\d+)$/,
815
+ async (_req, res, m) => {
816
+ const p = await projectOf(m[1]);
817
+ send(res, 200, ticketState(p.path, Number(m[2])));
818
+ },
819
+ ],
820
+ [
821
+ // The operator's Cancel of a ticket (d6): a waiting one goes, a building one is stopped.
822
+ 'DELETE',
823
+ /^\/api\/p\/([^/]+)\/play\/queue\/(\d+)$/,
824
+ async (_req, res, m) => {
825
+ const p = await projectOf(m[1]);
826
+ const r = await cli(p, ['gcf', 'playtest', 'cancel', m[2], '--json']);
791
827
  broadcast({ type: 'board', project: p.name });
792
828
  try {
793
829
  send(res, 200, JSON.parse(r.out));
@@ -1093,6 +1129,22 @@ export function createApp(o) {
1093
1129
  : { ok: false, err: briefError(r.err || r.out) });
1094
1130
  },
1095
1131
  ],
1132
+ [
1133
+ // Push and Pull on Changes (`gcf changes push|pull`, core 0.27): no body, fast-forward only.
1134
+ // The core stops git at 90 s; the route waits past that for its words.
1135
+ 'POST',
1136
+ /^\/api\/p\/([^/]+)\/changes\/(push|pull)$/,
1137
+ async (_req, res, m) => {
1138
+ const p = await projectOf(m[1]);
1139
+ const r = await cli(p, ['gcf', 'changes', m[2], '--json'], PUSH_TIMEOUT_MS);
1140
+ broadcast({ type: 'board', project: p.name });
1141
+ const err = r.err || r.out;
1142
+ const refusal = r.ok ? undefined : refusalOf(err);
1143
+ send(res, 200, r.ok
1144
+ ? { ok: true, ...jsonOf(r, `gcf changes ${m[2]}`) }
1145
+ : { ok: false, err: briefError(err), ...(refusal && { refusal }) });
1146
+ },
1147
+ ],
1096
1148
  [
1097
1149
  'GET',
1098
1150
  /^\/api\/p\/([^/]+)\/changes\/diff$/,
@@ -60,6 +60,8 @@ export function briefError(err) {
60
60
  return (m?.[1] ?? words).replaceAll('\r', '').trim();
61
61
  }
62
62
  const REFUSAL_LINE = /^gcf-refusal: .*(\r?\n)?/gm;
63
+ // Push and Pull's refusals with no data (core 0.27).
64
+ const PUSH_CODES = ['no-remote', 'behind', 'diverged', 'rejected', 'auth', 'timeout'];
63
65
  /**
64
66
  * The core's machine refusal in a command's error (core 0.20): its last `gcf-refusal: {…}`
65
67
  * line, read as data, never its words. Only the codes of `Refusal` are known; a path not under
@@ -77,11 +79,18 @@ export function refusalOf(err) {
77
79
  catch {
78
80
  return undefined;
79
81
  }
80
- const { code, paths, left, reason } = (data ?? {});
82
+ const { code, paths, left, reason, remotes } = (data ?? {});
81
83
  if (code === 'running' || code === 'stale')
82
84
  return { code };
83
85
  if (code === 'shelve')
84
86
  return { code, reason: typeof reason === 'string' ? reason : '' };
87
+ if (PUSH_CODES.includes(code))
88
+ return { code: code };
89
+ if (code === 'no-upstream')
90
+ return {
91
+ code,
92
+ remotes: Array.isArray(remotes) ? remotes.filter((r) => typeof r === 'string') : [],
93
+ };
85
94
  if (!Array.isArray(paths))
86
95
  return undefined;
87
96
  const safe = (a) => (Array.isArray(a) ? a : []).filter(gatePath);
@@ -77,9 +77,10 @@ async function readChanges(project, w) {
77
77
  export function markerEvent(busy, read) {
78
78
  if (busy)
79
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 };
80
+ if (!read || read.base === null)
81
+ return { type: 'changes', count: null, unknown: true };
82
+ const ahead = read.branch?.ahead;
83
+ return { type: 'changes', count: read.count, ...(ahead && { ahead }) };
83
84
  }
84
85
  /** A project's files moved, or a run began or ended: read its marker if a page shows it. */
85
86
  export function signalChanges(project) {
@@ -29,21 +29,94 @@ const BEAT_STALE_MS = 90_000;
29
29
  // A board that stops leaves its runs going: killing one would lose its integrate step.
30
30
  const active = new Set();
31
31
  const queues = new Map();
32
- // The projects whose folder a click build holds: a run now would only be refused, and a refused
33
- // run stalls the queue and turns the autopilot off. They wait for it instead.
34
- const clickBuilds = new Set();
35
- /** Run a click build with the project's runs held back; they go when it ends. */
36
- export async function whileClickBuilds(p, build) {
37
- clickBuilds.add(p.name);
32
+ /** The project's build tickets in their order, from its files: they outlive a board's restart. */
33
+ export function buildTickets(dir) {
34
+ const runs = path.join(dir, '.gcf-session', 'runs');
35
+ let names;
38
36
  try {
39
- return await build();
37
+ names = readdirSync(runs).filter((n) => /^\.build-\d+\.json$/.test(n));
40
38
  }
41
- finally {
42
- clickBuilds.delete(p.name);
43
- advance(p.name);
44
- setImmediate(() => void pilot(p.name));
39
+ catch {
40
+ return [];
41
+ }
42
+ const tickets = [];
43
+ for (const name of names)
44
+ try {
45
+ const t = JSON.parse(readFileSync(path.join(runs, name), 'utf8'));
46
+ if (Number.isInteger(t.n) && pidAlive(Number(t.pid)))
47
+ tickets.push(t);
48
+ }
49
+ catch {
50
+ // Being written: the next look reads it.
51
+ }
52
+ return tickets.sort((a, b) => a.n - b.n);
53
+ }
54
+ // shortcut: a waiter's pid that Windows gave to another process keeps its ticket alive, and runs
55
+ // held, until that process ends; a heartbeat on the ticket would tell them apart.
56
+ const pidAlive = (pid) => {
57
+ try {
58
+ process.kill(pid, 0);
59
+ return true;
60
+ }
61
+ catch (e) {
62
+ return e.code === 'EPERM';
63
+ }
64
+ };
65
+ // The projects whose folder a build by click holds or waits for: a run now would only be refused,
66
+ // and a refused run stalls the queue and turns the autopilot off. They wait for it instead.
67
+ const clickBuilding = (project) => {
68
+ const dir = paths.get(project);
69
+ const held = dir !== undefined && buildTickets(dir).length > 0;
70
+ // Seen here first (a short ticket between two looks): its end still lets the queue go on.
71
+ if (held && !ticketed.has(project))
72
+ ticketed.set(project, '');
73
+ return held;
74
+ };
75
+ // What the tickets of a project were at the last look (their number, building, after): when the
76
+ // last goes, its queue goes on; any change redraws its board.
77
+ const ticketed = new Map();
78
+ const TICKETS_EVERY_MS = 1000;
79
+ let ticketTimer = null;
80
+ /**
81
+ * Ticket `n` of a project: waiting or building while its waiter lives, done with its outcome
82
+ * (`.build-<n>.out.json`), or gone: a dead waiter left none.
83
+ */
84
+ export function ticketState(dir, n) {
85
+ const t = buildTickets(dir).find((x) => x.n === n);
86
+ if (t)
87
+ return { ticket: n, state: t.building ? 'building' : 'waiting', after: t.after ?? null };
88
+ try {
89
+ const out = JSON.parse(readFileSync(path.join(dir, '.gcf-session', 'runs', `.build-${n}.out.json`), 'utf8'));
90
+ return { ticket: n, state: 'done', ...out };
91
+ }
92
+ catch {
93
+ return { ticket: n, state: 'gone', ok: false, problem: 'its waiter ended without a word' };
45
94
  }
46
95
  }
96
+ /** A ticket's end lets the project's queue and autopilot go on, as a click build's end did. */
97
+ function lookAtTickets() {
98
+ for (const [project, dir] of paths) {
99
+ const tickets = buildTickets(dir);
100
+ const sign = tickets.map((t) => `${t.n}:${t.building === true}:${t.after ?? ''}`).join(',');
101
+ if (tickets.length ? ticketed.get(project) === sign : !ticketed.has(project))
102
+ continue;
103
+ if (tickets.length)
104
+ ticketed.set(project, sign);
105
+ else {
106
+ ticketed.delete(project);
107
+ advance(project);
108
+ setImmediate(() => void pilot(project));
109
+ }
110
+ broadcast({ type: 'board', project });
111
+ }
112
+ }
113
+ /** Watch the project's build tickets from now on (a click opened one, or a board started again). */
114
+ export function watchTickets(p) {
115
+ paths.set(p.name, p.path);
116
+ ticketTimer ??= setInterval(lookAtTickets, TICKETS_EVERY_MS);
117
+ ticketTimer.unref();
118
+ lookAtTickets();
119
+ }
47
120
  // Projects whose queue waits after a failure the next run would repeat (`stalled`).
48
121
  const paused = new Set();
49
122
  // The projects the operator holds (Hold-Plan d20): no queued or autopilot run starts; the
@@ -209,7 +282,8 @@ function queuedOf(v) {
209
282
  /** The state a board before this one kept of project `p`: its queue, pause, reports and trace. */
210
283
  function restore(entry, p) {
211
284
  loaded ??= readSaved();
212
- paths.set(p.name, p.path);
285
+ // Tickets outlive a board's restart: their end lets the restored queue go on.
286
+ watchTickets(p);
213
287
  if (loaded === 'bad') {
214
288
  trace(p.name, 'queue-lost', `${stateFile()} could not be read (kept as queue.json.bad): the board starts with no queue`);
215
289
  // Said once: the next project starts empty with no line of its own.
@@ -326,7 +400,7 @@ function limited(run, result) {
326
400
  function advance(project) {
327
401
  if (adopting.has(project))
328
402
  return;
329
- if (paused.has(project) || projectHolds.has(project) || clickBuilds.has(project))
403
+ if (paused.has(project) || projectHolds.has(project) || clickBuilding(project))
330
404
  return;
331
405
  if (activeRuns(project).some((r) => r.mode === 'main'))
332
406
  return;
@@ -866,7 +940,7 @@ export function startRun(entry, p, ids, mode = 'worktree', fresh = false, harnes
866
940
  busyCheck(p, ids);
867
941
  const { active: going } = runsOf(p.name);
868
942
  // A paused queue holds a new main run too: it would repeat the failure, and jump the queue.
869
- const held = paused.has(p.name) || clickBuilds.has(p.name);
943
+ const held = paused.has(p.name) || clickBuilding(p.name);
870
944
  if (mode === 'main' && (held || going.some((r) => r.mode === 'main'))) {
871
945
  queues.set(p.name, [
872
946
  ...(queues.get(p.name) ?? []),
@@ -1025,7 +1099,7 @@ export const reserveText = (r) => r?.weekly
1025
1099
  /** Whether the project is idle for the autopilot: no run, no queue to go, no pause. */
1026
1100
  const idle = (project) => !paused.has(project) &&
1027
1101
  !projectHolds.has(project) &&
1028
- !clickBuilds.has(project) &&
1102
+ !clickBuilding(project) &&
1029
1103
  !activeRuns(project).length &&
1030
1104
  !queues.get(project)?.some((q) => !q.waiting);
1031
1105
  /** Main's loose work outside gcf/ a main batch would carry; none when the gate cannot say. */