gcf-aif-ext 0.24.0 → 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/lib/play.js ADDED
@@ -0,0 +1,1022 @@
1
+ // Playing a finished card (docs/Play-Plan.md, docs/Play-Setup-Plan.md): a build is a snapshot of
2
+ // the code under `.gcf-session/snaps/<key>/`, which no later run or build touches; a card holds it
3
+ // by its link `.gcf-session/builds/<id>.json`, the checkout by `snaps/main.link.json`, and cards on
4
+ // the same code share one. One running player per project. How to build and start the game is the
5
+ // project's (`play:` in gcf/config.yml); the commands are opaque here, so a browser, a phone and a
6
+ // desktop differ only by their words.
7
+ import { spawn, spawnSync } from 'node:child_process';
8
+ import { createHash } from 'node:crypto';
9
+ import { closeSync, existsSync, openSync, readdirSync, readFileSync } from 'node:fs';
10
+ import { lstatSync, renameSync, rmSync, writeFileSync } from 'node:fs';
11
+ import { cp, mkdir, open, rm } from 'node:fs/promises';
12
+ import net from 'node:net';
13
+ import os from 'node:os';
14
+ import path from 'node:path';
15
+ import YAML from 'yaml';
16
+ import { configDoc } from './config-set.js';
17
+ import { readConfig } from './gcf-paths.js';
18
+ import { isValidId } from './id.js';
19
+ import { buildLedger } from './ledger.js';
20
+ import { alive, claimMainRun, MAIN_RUN, runHolder, withMainLock } from './main-lock.js';
21
+ import { atomicWrite, renameRetrying } from './safe-path.js';
22
+ import { commitMove } from './unit-ops.js';
23
+ import { failureOf, killTree, runCommand } from './verify.js';
24
+
25
+ export const NOT_SET_UP =
26
+ 'how to play is not set up: ai-factory gcf playtest setup --build <cmd> --output <folder> ' +
27
+ '--target <name> --start <cmd> --open <text>';
28
+
29
+ // Whether the start's port answers, and how long a process with no port must live to count.
30
+ const PORT_WAIT_MS = 15000;
31
+ const ALIVE_WAIT_MS = 2000;
32
+ const STOP_WAIT_MS = 15000;
33
+ // A held file on Windows lets go a moment after its process ends.
34
+ const RM = { recursive: true, force: true, maxRetries: 5, retryDelay: 200 };
35
+
36
+ // The checkout as it is ("Play main"): no item id, so no card's files can take its name.
37
+ const MAIN = ':main';
38
+ const session = (dir) => path.join(dir, '.gcf-session');
39
+ const buildsOf = (dir) => path.join(session(dir), 'builds');
40
+ const snapsOf = (dir) => path.join(session(dir), 'snaps');
41
+ const snapOf = (dir, key) => path.join(snapsOf(dir), key);
42
+ const snapFactsOf = (dir, key) => path.join(snapsOf(dir), `${key}.json`);
43
+ /** A holder's own files: a card's under `builds/`, the checkout's beside the snapshots. */
44
+ const ownOf = (dir, who, ext) =>
45
+ who === MAIN ? path.join(snapsOf(dir), `main.${ext}`) : path.join(buildsOf(dir), `${who}.${ext}`);
46
+ /** A holder as words, and in a file's name. */
47
+ const nameOf = (who) => (who === MAIN ? 'main' : who);
48
+ const linkOf = (dir, who) => ownOf(dir, who, who === MAIN ? 'link.json' : 'json');
49
+ const attemptOf = (dir, who) => ownOf(dir, who, 'attempt.json');
50
+ const logOf = (dir, who) => ownOf(dir, who, 'log');
51
+ const playerFile = (dir) => path.join(session(dir), 'play.json');
52
+ const playerLog = (dir) => path.join(session(dir), 'play.log');
53
+ const leftovers = /^.+\.(?:tmp|old)-(\d+)$/;
54
+ /**
55
+ * A snapshot's name: the code's, and for a dirty tree also its holder's: `-<id>` for a card,
56
+ * `.main` for the checkout, which no card id can spell (a card may be called `main`).
57
+ */
58
+ const KEY_RE = /^[0-9a-f]{16}(?:-[a-z0-9]+(?:-[a-z0-9]+)*|\.main)?$/;
59
+ const CLEAN_KEY = /^[0-9a-f]{16}$/;
60
+ // A link that cannot be read: nobody knows which snapshot it holds, so it holds them all (d24).
61
+ const UNREAD = Object.freeze({ unread: true });
62
+
63
+ function readJson(file) {
64
+ try {
65
+ return JSON.parse(readFileSync(file, 'utf8'));
66
+ } catch {
67
+ return null;
68
+ }
69
+ }
70
+
71
+ const listOf = (folder) => (existsSync(folder) ? readdirSync(folder, { withFileTypes: true }) : []);
72
+
73
+ /** A rename from a synchronous path: Windows holds a fresh file for a moment (a scanner). */
74
+ function renameHeld(from, to) {
75
+ for (let attempt = 1; ; attempt++) {
76
+ try {
77
+ return renameSync(from, to);
78
+ } catch (e) {
79
+ if (!['EPERM', 'EACCES', 'EBUSY'].includes(e.code) || attempt >= 10) throw e;
80
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
81
+ }
82
+ }
83
+ }
84
+
85
+ /** A file written whole, from a synchronous path. */
86
+ function writeJsonSync(file, value) {
87
+ const tmp = `${file}.tmp-${process.pid}`;
88
+ writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
89
+ renameHeld(tmp, file);
90
+ }
91
+
92
+ const needText = (where, v) => {
93
+ if (typeof v !== 'string' || !v.trim())
94
+ throw new Error(`gcf/config.yml: ${where} must be a command or a text`);
95
+ };
96
+
97
+ /**
98
+ * `play:` of a config, checked; null when the project has none. `output` stays inside the project:
99
+ * it is copied from there, and a path out of it would copy anything.
100
+ * @returns {{build: string, output: string, targets: Record<string, {start: string, open: string,
101
+ * stop?: string}>} | null}
102
+ */
103
+ export function playOf(config) {
104
+ const play = config.play;
105
+ if (play === undefined || play === null) return null;
106
+ if (typeof play !== 'object' || Array.isArray(play))
107
+ throw new Error('gcf/config.yml: play must map build:, output: and targets:');
108
+ needText('play.build', play.build);
109
+ needOutput(play.output);
110
+ const targets = play.targets ?? {};
111
+ needTargets(targets);
112
+
113
+ return { build: play.build, output: play.output, targets };
114
+ }
115
+
116
+ function needOutput(output) {
117
+ needText('play.output', output);
118
+ const parts = String(output).split(/[\\/]/);
119
+ if (path.isAbsolute(output) || /^[A-Za-z]:/.test(output) || parts.includes('..'))
120
+ throw new Error(`gcf/config.yml: play.output must lie inside the project: ${output}`);
121
+ }
122
+
123
+ function needTargets(targets) {
124
+ if (typeof targets !== 'object' || Array.isArray(targets))
125
+ throw new Error('gcf/config.yml: play.targets must map a name to start: and open:');
126
+ for (const [name, t] of Object.entries(targets)) {
127
+ if (!/^\w[\w-]*$/.test(name)) throw new Error(`a target's name is one word: ${name}`);
128
+ if (typeof t !== 'object' || t === null)
129
+ throw new Error(`gcf/config.yml: play.targets.${name} must map start: and open:`);
130
+ needText(`play.targets.${name}.start`, t.start);
131
+ needText(`play.targets.${name}.open`, t.open);
132
+ if (t.stop !== undefined) needText(`play.targets.${name}.stop`, t.stop);
133
+ }
134
+ }
135
+
136
+ const projectPlay = async (dir) => {
137
+ const play = playOf(await readConfig(path.join(dir, 'gcf')));
138
+ if (!play) throw new Error(NOT_SET_UP);
139
+
140
+ return play;
141
+ };
142
+
143
+ const needId = (id) => {
144
+ if (!isValidId(id)) throw new Error(`${id} is no item id`);
145
+ };
146
+
147
+ /** A path as one word of a shell command. */
148
+ const quoted = (p) =>
149
+ process.platform === 'win32' ? `"${p}"` : `"${p.replace(/(["\\$`])/g, '\\$1')}"`;
150
+
151
+ /** The machine's address on its network, for a phone on the same one. */
152
+ function lanAddress() {
153
+ for (const list of Object.values(os.networkInterfaces()))
154
+ for (const a of list ?? []) if (a.family === 'IPv4' && !a.internal) return a.address;
155
+
156
+ return 'localhost';
157
+ }
158
+
159
+ const fill = (text, { dir, port, lan }) =>
160
+ text
161
+ .replaceAll('{dir}', () => dir)
162
+ .replaceAll('{port}', String(port))
163
+ .replaceAll('{lan}', lan);
164
+
165
+ /** Every file under `dir` with its stamp and size; none when it does not exist. */
166
+ function treeOf(dir) {
167
+ const files = new Map();
168
+ const walk = (at) => {
169
+ for (const e of readdirSync(at, { withFileTypes: true })) {
170
+ const p = path.join(at, e.name);
171
+ if (e.isDirectory()) walk(p);
172
+ else {
173
+ // Its own stamp: a link that points nowhere yet is a file of the build too.
174
+ const s = lstatSync(p);
175
+ files.set(p, { stamp: `${s.mtimeMs}:${s.size}`, size: s.size });
176
+ }
177
+ }
178
+ };
179
+
180
+ if (existsSync(dir)) walk(dir);
181
+
182
+ return files;
183
+ }
184
+
185
+ const refreshed = (before, after) => [...after].some(([p, f]) => before.get(p)?.stamp !== f.stamp);
186
+
187
+ const gitOut = (cwd, args) => {
188
+ // A big project lists far past the 1 MB a spawn holds by default; past it git's answer is lost.
189
+ const res = spawnSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
190
+
191
+ return res.status === 0 ? res.stdout : null;
192
+ };
193
+
194
+ // The framework's own files: no build's, so neither a change of them nor a commit of them makes
195
+ // another game. One list for the dirty check and the snapshot's key.
196
+ const NOT_CODE = ['gcf', 'GLOSSARY.md', '.gcf-session'];
197
+
198
+ /**
199
+ * The key of the code HEAD holds, the framework's files left out (d29), and of how it is built: a
200
+ * verdict or an inbox commit keeps it, a new `play.build` or `play.output` does not. Null with no
201
+ * commit. 16 hex: a path on Windows stays short. The top level alone: a folder's entry is the hash
202
+ * of all it holds, and every file the key leaves out is at the top.
203
+ */
204
+ function codeOf(cwd, play) {
205
+ const out = gitOut(cwd, ['ls-tree', '-z', 'HEAD']);
206
+ if (out === null) return null;
207
+ const code = out
208
+ .split('\0')
209
+ .filter(Boolean)
210
+ .filter((l) => !NOT_CODE.includes(l.slice(l.indexOf('\t') + 1)));
211
+
212
+ return createHash('sha256')
213
+ .update([...code, play.build, play.output].join('\0'))
214
+ .digest('hex')
215
+ .slice(0, 16);
216
+ }
217
+
218
+ /** The snapshot's key: the code's alone when the tree is clean, else its holder's own too. */
219
+ function keyOf(cwd, who, loose, play) {
220
+ const code = codeOf(cwd, play);
221
+ if (code && !loose.length) return code;
222
+
223
+ return `${code ?? '0'.repeat(16)}${who === MAIN ? '.main' : `-${who}`}`;
224
+ }
225
+
226
+ /** What git sees changed or new, each path once; gcf/ and the run's own files are no build's. */
227
+ function looseOf(cwd) {
228
+ const out = gitOut(cwd, [
229
+ ...['--no-optional-locks', 'status', '--porcelain', '-z', '-uall', '--', '.'],
230
+ ...NOT_CODE.map((n) => `:(exclude)${n}`),
231
+ ]);
232
+ const parts = (out ?? '').split('\0').filter(Boolean);
233
+ const paths = [];
234
+ // A rename or a copy gives its old path as the next part: the new one names it.
235
+ for (let i = 0; i < parts.length; i++) {
236
+ paths.push(parts[i].slice(3));
237
+ if (/^(?:[RC].|.[RC])/.test(parts[i])) i++;
238
+ }
239
+
240
+ return paths;
241
+ }
242
+
243
+ /** The end of a log, as it is: what the operator reads when a command fails. */
244
+ function tailOf(file) {
245
+ try {
246
+ const text = readFileSync(file, 'utf8');
247
+
248
+ return text.trimEnd().split(/\r?\n/).slice(-20).join('\n');
249
+ } catch {
250
+ return '';
251
+ }
252
+ }
253
+
254
+ const withTail = (problem, file) => {
255
+ const tail = tailOf(file);
256
+
257
+ return tail ? `${problem}\n${tail}` : problem;
258
+ };
259
+
260
+ /** Who may be built without `--from`: what waits for play, in the checkout's own code. */
261
+ const PLAYABLE = ['awaiting-verdict', 'unplayed'];
262
+
263
+ /** Why item `id` may not get this build now, or null. A card still in its worktree is `ready`. */
264
+ async function statusProblem(dir, id, from) {
265
+ const item = (await buildLedger(dir)).item(id);
266
+ if (!item) return `${id} is not on the board`;
267
+ const status = item.data.status;
268
+ if (from ? status === 'ready' : PLAYABLE.includes(status)) return null;
269
+
270
+ return `${id} is ${status}: a build of it would be of no use now`;
271
+ }
272
+
273
+ /**
274
+ * The folder a build by click runs in: nothing may work there meanwhile. A harness run's own build
275
+ * goes under the lock that run holds.
276
+ */
277
+ async function holdCheckout(dir, id) {
278
+ const holder = runHolder(dir, MAIN_RUN);
279
+ if (holder && process.env.GCF_RUN_OWNER === `run:${holder}`) return { own: true, release: null };
280
+ // Under the main lock: an integrate that passed its check of the run lock ends first, and the
281
+ // next one sees this claim.
282
+ const release = holder ? null : await withMainLock(dir, () => claimMainRun(dir));
283
+ if (!release)
284
+ throw new Error(
285
+ `a run works in the main checkout: a build of ${id} now would take its unfinished work; ` +
286
+ 'build when it ends',
287
+ );
288
+
289
+ return { own: false, release };
290
+ }
291
+
292
+ /**
293
+ * Every holder's link: a card's id, or MAIN, to its link; UNREAD for one that cannot be read. A
294
+ * link of the old layout (a card's facts, no `snap`) holds nothing: a sweep takes it.
295
+ * @returns {Map<string, {snap?: string, released?: boolean, source?: string} | typeof UNREAD>}
296
+ */
297
+ export function linksOf(projectDir) {
298
+ const dir = path.resolve(projectDir);
299
+ const links = new Map();
300
+ const read = (who, file) => {
301
+ const link = readJson(file);
302
+ // A name that is no snapshot's would point a delete anywhere: such a link holds nothing.
303
+ const bad = link && typeof link.snap === 'string' && !KEY_RE.test(link.snap);
304
+ links.set(who, link === null ? UNREAD : bad ? { ...link, snap: null } : link);
305
+ };
306
+
307
+ for (const e of listOf(buildsOf(dir))) {
308
+ const id = e.isFile() && !e.name.endsWith('.attempt.json') && /^(.+)\.json$/.exec(e.name)?.[1];
309
+ if (id && isValidId(id)) read(id, path.join(buildsOf(dir), e.name));
310
+ }
311
+
312
+ if (existsSync(linkOf(dir, MAIN))) read(MAIN, linkOf(dir, MAIN));
313
+
314
+ return links;
315
+ }
316
+
317
+ const holds = (link, key) => link === UNREAD || (link.snap === key && link.released !== true);
318
+ /** Whether snapshot `key` has a holder: an unreleased link to it, or a link nobody can read. */
319
+ const held = (links, key) => [...links.values()].some((l) => holds(l, key));
320
+
321
+ /**
322
+ * Remove snapshot `key`, its facts last: a removal that failed halfway is repeated by a sweep.
323
+ * Under the main lock it only moves aside: a big one takes long to delete, and every move would
324
+ * wait for it. A player of it stops first: its files are going.
325
+ */
326
+ function dropSnap(dir, key) {
327
+ // Only a snapshot's own name: `""` or `..` would take the whole folder or more.
328
+ if (!KEY_RE.test(key)) return;
329
+ if (playerOf(dir)?.snap === key) stopPlay(dir);
330
+ const target = snapOf(dir, key);
331
+ if (existsSync(target)) {
332
+ const old = `${target}.old-${process.pid}`;
333
+ rmSync(old, RM);
334
+ renameHeld(target, old);
335
+ // A failure leaves it to a sweep, once this process is gone.
336
+ void rm(old, RM).catch(() => {});
337
+ }
338
+
339
+ rmSync(snapFactsOf(dir, key), { force: true });
340
+ }
341
+
342
+ /** A holder's attempt goes with it, unless a build for it is under way right now. */
343
+ function dropAttempt(dir, who, { log = false } = {}) {
344
+ if (building(readJson(attemptOf(dir, who)))) return;
345
+ rmSync(attemptOf(dir, who), { force: true });
346
+ if (log) rmSync(logOf(dir, who), { force: true });
347
+ }
348
+
349
+ /**
350
+ * Point `who` at snapshot `key`; the snapshot it held before goes when nobody else holds it.
351
+ * Under the main lock.
352
+ */
353
+ function linkTo(dir, who, key, source) {
354
+ const was = linksOf(dir).get(who);
355
+ writeJsonSync(linkOf(dir, who), {
356
+ id: who === MAIN ? null : who,
357
+ snap: key,
358
+ at: new Date().toISOString(),
359
+ source,
360
+ });
361
+ if (was && was !== UNREAD && was.snap && was.snap !== key && !held(linksOf(dir), was.snap))
362
+ dropSnap(dir, was.snap);
363
+ }
364
+
365
+ /**
366
+ * Remove what nobody needs any more (d24): a released link, the link of a card off the board, a
367
+ * folder of the old layout, a snapshot nobody holds, leftovers of a dead process. Under the main
368
+ * lock. A held file waits for the next sweep; a card file that cannot be read says nothing of who
369
+ * left the board, so nothing goes by it; while a link cannot be read, no snapshot goes.
370
+ */
371
+ async function sweep(dir) {
372
+ const ledger = await buildLedger(dir).catch(() => null);
373
+ const ids = sweepFolders(dir);
374
+ const links = linksOf(dir);
375
+ const gone = (id) =>
376
+ ledger !== null && !ledger.item(id) && !existsSync(path.join(dir, 'gcf', 'work', `${id}.md`));
377
+ for (const id of ids) {
378
+ const link = links.get(id);
379
+ if (link === UNREAD) continue;
380
+ const left = gone(id);
381
+ if (left || (link && (link.released === true || typeof link.snap !== 'string'))) {
382
+ rmSync(linkOf(dir, id), { force: true });
383
+ if (left) dropAttempt(dir, id, { log: true });
384
+ }
385
+ }
386
+
387
+ const now = linksOf(dir);
388
+ if ([...now.values()].includes(UNREAD)) return;
389
+ const keys = new Set(
390
+ listOf(snapsOf(dir))
391
+ .map((e) => e.name.replace(/\.json$/, ''))
392
+ .filter((k) => KEY_RE.test(k)),
393
+ );
394
+ for (const key of keys) if (!held(now, key)) dropSnap(dir, key);
395
+ }
396
+
397
+ /** A snapshot of the old layout goes; a player an older core started from it stops first. */
398
+ function dropOld(dir, id) {
399
+ const p = playerOf(dir);
400
+ if (p?.id === id && !p.snap) stopPlay(dir);
401
+ void rm(path.join(buildsOf(dir), id), RM).catch(() => {});
402
+ }
403
+
404
+ /**
405
+ * Leftovers of a dead process go, and the folders of the old layout (`builds/<id>/`), which no
406
+ * link reaches. Not awaited: the main lock is held here, and every move would wait for a big one.
407
+ * @returns {Set<string>} the ids that have files under `builds/`
408
+ */
409
+ function sweepFolders(dir) {
410
+ const ids = new Set();
411
+ const drop = (folder, name) => void rm(path.join(folder, name), RM).catch(() => {});
412
+ for (const folder of [buildsOf(dir), snapsOf(dir)])
413
+ for (const e of listOf(folder)) {
414
+ const left = leftovers.exec(e.name);
415
+ if (left && !alive(Number(left[1]))) drop(folder, e.name);
416
+ if (left) continue;
417
+
418
+ if (folder !== buildsOf(dir)) continue;
419
+ if (e.isDirectory()) dropOld(dir, e.name);
420
+ const id = e.name.replace(/(\.attempt)?\.(json|log)$/, '');
421
+ if (e.isFile() && isValidId(id)) ids.add(id);
422
+ }
423
+
424
+ return ids;
425
+ }
426
+
427
+ const building = (attempt) => attempt?.building === true && alive(attempt.pid);
428
+
429
+ /**
430
+ * The card's play has ended (a verdict, a drop): its player stops and its link goes; its snapshot
431
+ * goes too when no other card holds it (d24). After the move's commit, so it never fails the move:
432
+ * the problem comes back as words, and the mark `released` makes a later sweep repeat what a held
433
+ * file refused. A card that a tune sends back stays on the board, and only the mark tells this link
434
+ * from a fresh one.
435
+ * @returns {string | null}
436
+ */
437
+ export function releaseBuild(projectDir, id) {
438
+ // The id comes from a card's frontmatter, and a recursive delete follows: a slug, nothing else.
439
+ if (!isValidId(id)) return null;
440
+ const dir = path.resolve(projectDir);
441
+ try {
442
+ if (playerOf(dir)?.id === id) stopPlay(dir);
443
+ const file = linkOf(dir, id);
444
+ const link = readJson(file);
445
+ if (link) writeJsonSync(file, { ...link, released: true });
446
+ rmSync(file, { force: true });
447
+ dropAttempt(dir, id);
448
+ if (typeof link?.snap === 'string' && !held(linksOf(dir), link.snap)) dropSnap(dir, link.snap);
449
+ } catch (e) {
450
+ return `the build of ${id} stays on the disk for now: ${e.message}`;
451
+ }
452
+
453
+ return null;
454
+ }
455
+
456
+ /**
457
+ * Put a finished build in place of snapshot `key` and point `who` at it, or throw and leave the old
458
+ * one with its facts. A card whose status moved on meanwhile (a verdict needs no wait for a build)
459
+ * takes nothing. `reuse`: a build of the same code that ended meanwhile serves this one, and this
460
+ * one is thrown away (d23).
461
+ * @returns {Promise<{refused: string} | {facts: object}>}
462
+ */
463
+ async function publish(dir, { who, key, tmp, facts, source, from, reuse }) {
464
+ const target = snapOf(dir, key);
465
+ const old = `${target}.old-${process.pid}`;
466
+ const done = await withMainLock(dir, async () => {
467
+ if (who !== MAIN) {
468
+ const problem = await statusProblem(dir, who, from);
469
+ if (problem) return { refused: problem };
470
+ }
471
+
472
+ const there = reuse && readJson(snapFactsOf(dir, key));
473
+ if (there && existsSync(target) && held(linksOf(dir), key)) {
474
+ linkTo(dir, who, key, source);
475
+
476
+ return { facts: there };
477
+ }
478
+
479
+ if (playerOf(dir)?.snap === key) stopPlay(dir);
480
+ const had = existsSync(target);
481
+ if (had) await renameRetrying(target, old);
482
+ try {
483
+ await renameRetrying(tmp, target);
484
+ await atomicWrite(snapFactsOf(dir, key), `${JSON.stringify(facts, null, 2)}\n`);
485
+ } catch (e) {
486
+ await rm(target, RM).catch(() => {});
487
+ if (had) await renameRetrying(old, target);
488
+ throw e;
489
+ }
490
+
491
+ linkTo(dir, who, key, source);
492
+
493
+ return { facts };
494
+ });
495
+ // Out of the lock: a big snapshot takes a while to delete. A failure leaves it to a sweep.
496
+ await rm(old, RM).catch(() => {});
497
+
498
+ return done;
499
+ }
500
+
501
+ /**
502
+ * Build card `id` with `play.build`, or link it to the snapshot of the same code another card
503
+ * holds (d23); the old snapshot stays until a new one has replaced it. `from`: the card's worktree,
504
+ * whose code is still its alone. `fresh`: build even when a snapshot of this code is there, and
505
+ * replace it. A failed build is no error: it comes back as `problem`, and the card goes on without
506
+ * one.
507
+ * @returns {Promise<{id: string, ok: boolean, problem?: string, dirtied?: string[]}>}
508
+ */
509
+ export async function buildItem(projectDir, id, { from = null, fresh = false } = {}) {
510
+ needId(id);
511
+ const dir = path.resolve(projectDir);
512
+ const play = await projectPlay(dir);
513
+ const cwd = from ? path.resolve(from) : dir;
514
+ if (from && cwd !== path.join(session(dir), 'worktrees', id))
515
+ throw new Error(`--from names the worktree of ${id}, not ${from}`);
516
+ const problem = await statusProblem(dir, id, from);
517
+ if (problem) throw new Error(problem);
518
+ const hold = from ? { own: true, release: null } : await holdCheckout(dir, id);
519
+ try {
520
+ return await runBuild(dir, cwd, play, { who: id, from, own: hold.own, fresh });
521
+ } finally {
522
+ await hold.release?.();
523
+ if (hold.release) await mergeWaiting(dir);
524
+ }
525
+ }
526
+
527
+ /**
528
+ * Build the checkout as it is, uncommitted edits too (d30): "Play main" after the operator's own
529
+ * changes. A clean tree whose code a card's snapshot already holds takes that one, unless `fresh`.
530
+ */
531
+ export async function buildMain(projectDir, { fresh = false } = {}) {
532
+ const dir = path.resolve(projectDir);
533
+ const play = await projectPlay(dir);
534
+ const hold = await holdCheckout(dir, 'main');
535
+ try {
536
+ return await runBuild(dir, dir, play, { who: MAIN, from: null, own: hold.own, fresh });
537
+ } finally {
538
+ await hold.release?.();
539
+ if (hold.release) await mergeWaiting(dir);
540
+ }
541
+ }
542
+
543
+ /**
544
+ * What a worktree run left verified while this click held the checkout: that run has ended, and no
545
+ * other would merge it until the next one starts. A refusal leaves it for that one.
546
+ */
547
+ async function mergeWaiting(dir) {
548
+ // Here, not on top: integrate reaches this module through the moves it records.
549
+ const { integrate, verifiedBranches } = await import('./integrate.js');
550
+ try {
551
+ if (verifiedBranches(dir).length) await integrate(dir);
552
+ } catch {
553
+ // It must not take the build's answer with it: the next run's integrate reports it.
554
+ }
555
+ }
556
+
557
+ /** What a build or a link answers: the holder, the snapshot's facts, and how it came. */
558
+ const answerOf = (who, key, facts, source) => ({
559
+ ...(who === MAIN ? { main: true } : { id: who }),
560
+ ok: true,
561
+ ...facts,
562
+ snap: key,
563
+ source,
564
+ });
565
+
566
+ async function runBuild(dir, cwd, play, { who, from, own, fresh }) {
567
+ const started = new Date().toISOString();
568
+ await mkdir(buildsOf(dir), { recursive: true });
569
+ await mkdir(snapsOf(dir), { recursive: true });
570
+ const loose = looseOf(cwd);
571
+ const key = keyOf(cwd, who, loose, play);
572
+ const source = who === MAIN ? 'main' : own ? 'run' : 'click';
573
+ // A dirty tree's snapshot is nobody else's, and not this holder's next time either (d22).
574
+ const reuse = !fresh && CLEAN_KEY.test(key);
575
+ const linked = await withMainLock(dir, async () => {
576
+ await sweep(dir);
577
+ if (who !== MAIN) {
578
+ const problem = await statusProblem(dir, who, from);
579
+ if (problem) throw new Error(problem);
580
+ }
581
+
582
+ const was = readJson(attemptOf(dir, who));
583
+ if (building(was) && was.pid !== process.pid)
584
+ throw new Error(`${nameOf(who)} is being built (pid ${was.pid}): wait until that build ends`);
585
+ const there = reuse && readJson(snapFactsOf(dir, key));
586
+ if (there && existsSync(snapOf(dir, key)) && held(linksOf(dir), key)) {
587
+ linkTo(dir, who, key, source);
588
+ dropAttempt(dir, who);
589
+
590
+ // Nothing ran here: what another build changed is not this one's to report.
591
+ return answerOf(who, key, { ...there, dirtied: [] }, source);
592
+ }
593
+
594
+ writeJsonSync(attemptOf(dir, who), { pid: process.pid, building: true, at: started });
595
+
596
+ return null;
597
+ });
598
+ if (linked) return linked;
599
+ const failed = (problem) => {
600
+ writeJsonSync(attemptOf(dir, who), { pid: process.pid, problem, at: started });
601
+
602
+ return {
603
+ ...(who === MAIN ? { main: true } : { id: who }),
604
+ ok: false,
605
+ problem,
606
+ log: logOf(dir, who),
607
+ };
608
+ };
609
+
610
+ // Its holder in the name too: two holders may build the same code in one process.
611
+ const tmp = path.join(
612
+ snapsOf(dir),
613
+ `${key}.${who === MAIN ? 'checkout' : `card-${who}`}.tmp-${process.pid}`,
614
+ );
615
+ const at = { who, key, source, loose, from, reuse, tmp, failed };
616
+ try {
617
+ return await buildAndPublish(dir, cwd, play, at);
618
+ } catch (e) {
619
+ return failed(e.message);
620
+ } finally {
621
+ await rm(tmp, RM).catch(() => {});
622
+ }
623
+ }
624
+
625
+ /** Whether git ignores `output`: a build there must not show up as the project's change. */
626
+ const ignored = (cwd, output) =>
627
+ // The slash: a rule for folders only must match a folder not built yet.
628
+ spawnSync('git', ['check-ignore', '-q', `${output}/`], { cwd }).status === 0;
629
+
630
+ async function buildAndPublish(dir, cwd, play, at) {
631
+ const { who, key, source, loose, from, reuse, tmp, failed } = at;
632
+ const output = path.join(cwd, play.output);
633
+ if (!ignored(cwd, play.output))
634
+ return failed(`play.output ${play.output} is not ignored by git: add it to .gitignore`);
635
+ const before = treeOf(output);
636
+ const commit = gitOut(cwd, ['rev-parse', 'HEAD'])?.trim() ?? null;
637
+ const minutes = (await readConfig(path.join(dir, 'gcf'))).dod_timeout_min ?? 0;
638
+ const log = await open(logOf(dir, who), 'w');
639
+ let res;
640
+ try {
641
+ res = await runCommand(play.build, cwd, ['ignore', log.fd, log.fd], minutes * 60000);
642
+ } finally {
643
+ await log.close();
644
+ }
645
+
646
+ const why = failureOf('play.build', play.build, minutes, res);
647
+ if (why) return failed(withTail(why, logOf(dir, who)));
648
+ const after = treeOf(output);
649
+ // A build that wrote nothing new must not stand in for this commit.
650
+ if (!refreshed(before, after))
651
+ return failed(`the build did not update ${play.output}: no new file there`);
652
+ const dirtied = looseOf(cwd).filter((p) => !loose.includes(p));
653
+ // Its links as they are: made absolute they would point back into `output`, at a later build.
654
+ await cp(output, tmp, { recursive: true, verbatimSymlinks: true });
655
+ const facts = {
656
+ key,
657
+ commit,
658
+ built_at: new Date().toISOString(),
659
+ dirty: loose.length > 0,
660
+ dirtied,
661
+ size: [...after.values()].reduce((sum, f) => sum + f.size, 0),
662
+ };
663
+ const done = await publish(dir, { who, key, tmp, facts, source, from, reuse });
664
+ rmSync(attemptOf(dir, who), { force: true });
665
+ // Not a failed build: the card has moved on, and nobody waits for this one.
666
+ if (done.refused) return { id: who, ok: false, problem: done.refused, moved_on: true };
667
+
668
+ // What this build changed, even when another one's snapshot serves (a main batch stops on it).
669
+ return answerOf(who, key, { ...done.facts, dirtied }, source);
670
+ }
671
+
672
+ /** The running player's record as it stands, or null; a dead one reads as none. Reads only. */
673
+ export function playerOf(projectDir) {
674
+ const dir = path.resolve(projectDir);
675
+ const p = readJson(playerFile(dir));
676
+
677
+ // shortcut: a reused pid passes for the player; a check of the process's name, if it happens.
678
+ return p && alive(p.pid) ? p : null;
679
+ }
680
+
681
+ /** A target's `stop`: what its start left behind (`adb reverse`) outlives its process. */
682
+ const runStop = (dir, command) =>
683
+ spawnSync(command, {
684
+ cwd: dir,
685
+ shell: true,
686
+ stdio: 'ignore',
687
+ timeout: STOP_WAIT_MS,
688
+ windowsHide: true,
689
+ });
690
+
691
+ /**
692
+ * Stop the player, or only the one playing card `id`, then run its `stop`. A start that launched
693
+ * and ended has no player and no `stop`: what it left is its own.
694
+ * @returns {object | null} what stopped
695
+ */
696
+ export function stopPlay(projectDir, { id = null } = {}) {
697
+ const dir = path.resolve(projectDir);
698
+ const p = readJson(playerFile(dir));
699
+ if (!p || (id && p.id !== id)) return null;
700
+ if (alive(p.pid)) killTree(p.pid);
701
+ if (p.stop) runStop(dir, p.stop);
702
+ rmSync(playerFile(dir), { force: true });
703
+
704
+ return p;
705
+ }
706
+
707
+ /** The operator's stop: under the lock a start holds, or it misses the player that start makes. */
708
+ export const stopPlayLocked = (projectDir) =>
709
+ withMainLock(path.resolve(projectDir), async () => stopPlay(projectDir));
710
+
711
+ const freePort = () =>
712
+ new Promise((resolve, reject) => {
713
+ const s = net.createServer();
714
+ s.on('error', reject);
715
+ s.listen(0, '127.0.0.1', () => {
716
+ const { port } = /** @type {net.AddressInfo} */ (s.address());
717
+ s.close(() => resolve(port));
718
+ });
719
+ });
720
+
721
+ const answers = (port) =>
722
+ new Promise((resolve) => {
723
+ const c = net.connect({ port, host: 'localhost' });
724
+ c.once('connect', () => {
725
+ c.destroy();
726
+ resolve(true);
727
+ });
728
+ c.once('error', () => resolve(false));
729
+ });
730
+
731
+ /** How a started process turned out: it ended, it answers on its port, or it is merely alive. */
732
+ function outcomeOf(child, port) {
733
+ return new Promise((resolve) => {
734
+ let done = false;
735
+ const end = (r) => {
736
+ done = true;
737
+ resolve(r);
738
+ };
739
+
740
+ child.once('error', (error) => end({ state: 'error', why: error.message }));
741
+ child.once('exit', (status, signal) =>
742
+ end(
743
+ status === 0 ? { state: 'launched' } : { state: 'error', why: `exit ${status ?? signal}` },
744
+ ),
745
+ );
746
+ const until = Date.now() + (port ? PORT_WAIT_MS : ALIVE_WAIT_MS);
747
+ const look = async () => {
748
+ if (done) return;
749
+ if (port && (await answers(port))) return done || end({ state: 'running' });
750
+ if (done) return;
751
+ if (Date.now() < until) return void setTimeout(look, 200);
752
+ end(port ? { state: 'silent' } : { state: 'running' });
753
+ };
754
+
755
+ setTimeout(look, port ? 100 : ALIVE_WAIT_MS);
756
+ });
757
+ }
758
+
759
+ // A small keeper between this process and the shell. On Windows a child that is not detached dies
760
+ // with its parent (libuv's job object), and what a detached shell starts writes nothing to the log.
761
+ const KEEPER =
762
+ "const c = require('node:child_process').spawn(process.argv[1], " +
763
+ "{ shell: true, stdio: ['ignore', 1, 2], windowsHide: true });" +
764
+ "c.on('error', () => process.exit(1));" +
765
+ "c.on('exit', (status) => process.exit(status ?? 1));";
766
+
767
+ /** Start a command cut loose from this process, its output in the player's log. */
768
+ function launch(dir, command) {
769
+ const log = openSync(playerLog(dir), 'w');
770
+ try {
771
+ const child = spawn(process.execPath, ['-e', KEEPER, command], {
772
+ cwd: dir,
773
+ detached: true,
774
+ stdio: ['ignore', log, log],
775
+ windowsHide: true,
776
+ });
777
+ child.unref();
778
+
779
+ return child;
780
+ } finally {
781
+ closeSync(log);
782
+ }
783
+ }
784
+
785
+ /** Write the player's record; a player with none could not be stopped, so it goes. */
786
+ function recordPlayer(dir, record) {
787
+ try {
788
+ writeJsonSync(playerFile(dir), record);
789
+ } catch (e) {
790
+ killTree(record.pid);
791
+ throw e;
792
+ }
793
+ }
794
+
795
+ /**
796
+ * Play the snapshot card `id` holds on `target`; `id` null: the checkout's ("Play main"). One
797
+ * player per project: the last one stops first. The process is cut loose from its caller, so a
798
+ * board's restart does not end the game. A process that ends with 0 has launched what it launches:
799
+ * nothing is left to stop.
800
+ */
801
+ export async function startPlay(projectDir, id, targetName) {
802
+ if (id !== null) needId(id);
803
+ const dir = path.resolve(projectDir);
804
+ const play = await projectPlay(dir);
805
+ const target = Object.hasOwn(play.targets, targetName) ? play.targets[targetName] : null;
806
+ if (!target)
807
+ throw new Error(
808
+ `no target ${targetName}: ${Object.keys(play.targets).join(', ') || 'none set up'}`,
809
+ );
810
+
811
+ // Held to the end: a verdict meanwhile waits, or it would miss the player this start records.
812
+ return withMainLock(dir, async () => {
813
+ await sweep(dir);
814
+ const key = heldKey(dir, id);
815
+ const snapshot = snapOf(dir, key);
816
+ stopPlay(dir);
817
+ const port = await freePort();
818
+ const lan = lanAddress();
819
+ // `{dir}/game.exe` is one word: Windows' shell takes no name after a closing quote.
820
+ const inCommand = (text) =>
821
+ fill(
822
+ text
823
+ .replace(/"\{dir\}([^"]*)"/g, (_, tail) => quoted(snapshot + tail))
824
+ .replace(/\{dir\}([\\/][^\s"'&|<>;()]*)?/g, (_, tail = '') => quoted(snapshot + tail)),
825
+ { dir: quoted(snapshot), port, lan },
826
+ );
827
+ const open = fill(target.open, { dir: snapshot, port, lan });
828
+ const child = launch(dir, inCommand(target.start));
829
+ const url = /^https?:\/\//.test(open) ? open : null;
830
+ const stop = target.stop ? { stop: inCommand(target.stop) } : {};
831
+ const started = new Date().toISOString();
832
+ const main = id === null ? { main: true } : {};
833
+ const record = { pid: child.pid, id, ...main, snap: key, target: targetName, port, open, url };
834
+ // Before the wait: a starter killed in it must not leave a player nobody can stop.
835
+ recordPlayer(dir, { ...record, started, ...stop });
836
+ const end = await outcomeOf(child, target.start.includes('{port}') ? port : null);
837
+ const undo = () => target.stop && runStop(dir, inCommand(target.stop));
838
+ if (end.state === 'running') return { state: 'running', ...record, started, ...stop };
839
+ rmSync(playerFile(dir), { force: true });
840
+ if (end.state === 'launched')
841
+ return { state: 'launched', id, ...main, target: targetName, open, url };
842
+ if (end.state === 'silent') killTree(child.pid);
843
+ undo();
844
+ const why = end.state === 'silent' ? `did not answer on port ${port}` : `failed (${end.why})`;
845
+ throw new Error(withTail(`play.targets.${targetName}.start ${why}`, playerLog(dir)));
846
+ });
847
+ }
848
+
849
+ /** The snapshot card `id` holds, or the checkout's for null; none throws what to do. */
850
+ function heldKey(dir, id) {
851
+ const link = readJson(linkOf(dir, id ?? MAIN));
852
+ const key = KEY_RE.test(link?.snap ?? '') && !link.released ? link.snap : null;
853
+ if (key && existsSync(snapOf(dir, key)) && existsSync(snapFactsOf(dir, key))) return key;
854
+ throw new Error(
855
+ id
856
+ ? `${id} has no build: ai-factory gcf playtest build ${id}`
857
+ : 'main has no build: ai-factory gcf playtest build --main',
858
+ );
859
+ }
860
+
861
+ const NO_FACTS = {
862
+ key: null,
863
+ commit: null,
864
+ built_at: null,
865
+ source: null,
866
+ dirty: false,
867
+ dirtied: [],
868
+ size: null,
869
+ shared_with: [],
870
+ };
871
+
872
+ /**
873
+ * Why the card's last attempt gave no build, or null. One marked as going by a process now gone was
874
+ * taken by a stop or a crash, and could not say so.
875
+ */
876
+ function attemptProblem(attempt, going) {
877
+ if (going) return attempt.problem ?? null;
878
+
879
+ return attempt?.building === true
880
+ ? 'the last build was stopped before it ended'
881
+ : (attempt?.problem ?? null);
882
+ }
883
+
884
+ /**
885
+ * A holder's snapshot and its attempt, read only. `shared_with`: the other cards that hold the
886
+ * same snapshot (d27).
887
+ */
888
+ function heldBuild(dir, who, links) {
889
+ const link = links.get(who);
890
+ const key = link && link !== UNREAD && !link.released ? link.snap : null;
891
+ const facts = key && existsSync(snapOf(dir, key)) ? readJson(snapFactsOf(dir, key)) : null;
892
+ const attempt = readJson(attemptOf(dir, who));
893
+ const going = building(attempt);
894
+ const problem = attemptProblem(attempt, going);
895
+ if (!facts && !going && !problem) return null;
896
+ const shared = [...links]
897
+ .filter(([w, l]) => facts && w !== who && w !== MAIN && l !== UNREAD && holds(l, key))
898
+ .map(([w]) => w)
899
+ .sort();
900
+
901
+ return {
902
+ ...NO_FACTS,
903
+ ...facts,
904
+ ...(facts ? { key, source: link.source ?? null, shared_with: shared } : {}),
905
+ ok: Boolean(facts),
906
+ building: going,
907
+ problem,
908
+ };
909
+ }
910
+
911
+ /**
912
+ * What a board and a chat show of the card: its snapshot, or the attempt under way or failed.
913
+ * `links`: linksOf once for a whole board.
914
+ */
915
+ export function buildOf(projectDir, id, status, links = linksOf(projectDir)) {
916
+ const dir = path.resolve(projectDir);
917
+ // A card back at work has no build to offer, unless one goes for it in its worktree right now.
918
+ if (status === 'ready' && !building(readJson(attemptOf(dir, id)))) return null;
919
+
920
+ return heldBuild(dir, id, links);
921
+ }
922
+
923
+ /**
924
+ * How the project plays, read only: its `play:` whole (d26), the checkout's snapshot (d30) and the
925
+ * running player; null with no `play:`.
926
+ */
927
+ export function playFacts(projectDir, config) {
928
+ let play;
929
+ try {
930
+ play = playOf(config);
931
+ } catch (e) {
932
+ const none = { build: null, output: null, targets: [], main: null, running: null };
933
+
934
+ return { problem: e.message, ...none };
935
+ }
936
+
937
+ if (!play) return null;
938
+ const dir = path.resolve(projectDir);
939
+ const p = playerOf(dir);
940
+
941
+ return {
942
+ problem: null,
943
+ build: play.build,
944
+ output: play.output,
945
+ targets: Object.entries(play.targets).map(([name, t]) => ({
946
+ name,
947
+ start: t.start,
948
+ open: t.open,
949
+ stop: t.stop ?? null,
950
+ })),
951
+ main: heldBuild(dir, MAIN, linksOf(dir)),
952
+ running: p
953
+ ? {
954
+ id: p.id,
955
+ main: p.main === true,
956
+ snap: p.snap ?? null,
957
+ target: p.target,
958
+ open: p.open,
959
+ url: p.url,
960
+ started: p.started,
961
+ }
962
+ : null,
963
+ };
964
+ }
965
+
966
+ /** `gcf playtest status`: a dead player's record and what no card needs go, then the facts. */
967
+ export async function playStatus(projectDir) {
968
+ const dir = path.resolve(projectDir);
969
+ await withMainLock(dir, async () => {
970
+ await sweep(dir);
971
+ if (existsSync(playerFile(dir)) && !playerOf(dir)) stopPlay(dir);
972
+ });
973
+
974
+ return playFacts(dir, await readConfig(path.join(dir, 'gcf')));
975
+ }
976
+
977
+ /**
978
+ * `gcf playtest setup`: how the project builds and starts its game, committed as `gcf(config)`.
979
+ * Only what is given changes. Checked as a whole before it is written.
980
+ * @param {{build?: string, output?: string, target?: string, start?: string, open?: string,
981
+ * stop?: string, removeTarget?: string, commit?: boolean}} opts
982
+ */
983
+ export async function setupPlay(projectDir, opts) {
984
+ const dir = path.resolve(projectDir);
985
+ const { build, output, target, start, open: words, stop, removeTarget, commit = true } = opts;
986
+ if (target !== undefined && !/^\w[\w-]*$/.test(target))
987
+ throw new Error(`a target's name is one word: ${target}`);
988
+ if (target === undefined && [start, words, stop].some((v) => v !== undefined))
989
+ throw new Error('--start, --open and --stop belong to a --target');
990
+ // Now, not at the first build minutes later (d21).
991
+ if (output !== undefined) needOutput(output);
992
+ if (output !== undefined && !ignored(dir, output))
993
+ throw new Error(`play.output ${output} is not ignored by git: add it to .gitignore`);
994
+ const file = path.join(dir, 'gcf', 'config.yml');
995
+ const hash = await commitMove(dir, 'gcf(config): play', {
996
+ files: [file],
997
+ commit,
998
+ key: 'config',
999
+ mutate: async () => {
1000
+ const doc = configDoc(existsSync(file) ? readFileSync(file, 'utf8') : '');
1001
+ const set = (keys, v) => v !== undefined && doc.setIn(['play', ...keys], v);
1002
+ if (!YAML.isMap(doc.getIn(['play'], true))) doc.setIn(['play'], doc.createNode({}));
1003
+ set(['build'], build);
1004
+ set(['output'], output);
1005
+ if (target !== undefined) {
1006
+ if (!YAML.isMap(doc.getIn(['play', 'targets'], true)))
1007
+ doc.setIn(['play', 'targets'], doc.createNode({}));
1008
+ if (!YAML.isMap(doc.getIn(['play', 'targets', target], true)))
1009
+ doc.setIn(['play', 'targets', target], doc.createNode({}));
1010
+ set(['targets', target, 'start'], start);
1011
+ set(['targets', target, 'open'], words);
1012
+ set(['targets', target, 'stop'], stop);
1013
+ }
1014
+
1015
+ if (removeTarget !== undefined) doc.deleteIn(['play', 'targets', removeTarget]);
1016
+ playOf(doc.toJS());
1017
+ await atomicWrite(file, doc.toString());
1018
+ },
1019
+ });
1020
+
1021
+ return { hash, play: playOf(await readConfig(path.join(dir, 'gcf'))) };
1022
+ }