gcf-aif-ext 0.28.0 → 0.29.1

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 CHANGED
@@ -46,14 +46,51 @@ const buildsOf = (dir) => path.join(session(dir), 'builds');
46
46
  const snapsOf = (dir) => path.join(session(dir), 'snaps');
47
47
  const snapOf = (dir, key) => path.join(snapsOf(dir), key);
48
48
  const snapFactsOf = (dir, key) => path.join(snapsOf(dir), `${key}.json`);
49
- /** A holder's own files: a card's under `builds/`, the checkout's beside the snapshots. */
50
- const ownOf = (dir, who, ext) =>
51
- who === MAIN ? path.join(snapsOf(dir), `main.${ext}`) : path.join(buildsOf(dir), `${who}.${ext}`);
52
49
  /** A holder as words, and in a file's name. */
53
50
  const nameOf = (who) => (who === MAIN ? 'main' : who);
54
- const linkOf = (dir, who) => ownOf(dir, who, who === MAIN ? 'link.json' : 'json');
55
- const attemptOf = (dir, who) => ownOf(dir, who, 'attempt.json');
56
- const logOf = (dir, who) => ownOf(dir, who, 'log');
51
+ /**
52
+ * A slot: what holds one snapshot — a card or the checkout, by one build and one profile
53
+ * (docs/Handoff-Plan.md t16, t18). Its files are named `<holder>.<build>.<profile>`: no part of
54
+ * it has a dot.
55
+ * @typedef {{who: string, build: string, profile: string}} Slot
56
+ */
57
+ const stemOf = (s) => `${nameOf(s.who)}.${s.build}.${s.profile}`;
58
+ /** A slot as a key of a map: a space is in none of its parts. */
59
+ const slotKey = (s) => `${s.who} ${s.build} ${s.profile}`;
60
+ const whoOfKey = (k) => k.split(' ')[0];
61
+
62
+ /** A slot's own files: a card's under `builds/`, the checkout's beside the snapshots. */
63
+ const ownOf = (dir, s, ext) =>
64
+ path.join(s.who === MAIN ? snapsOf(dir) : buildsOf(dir), `${stemOf(s)}.${ext}`);
65
+ const linkOf = (dir, s) => ownOf(dir, s, s.who === MAIN ? 'link.json' : 'json');
66
+ const attemptOf = (dir, s) => ownOf(dir, s, 'attempt.json');
67
+ const logOf = (dir, s) => ownOf(dir, s, 'log');
68
+ const SLOT_FILE =
69
+ /^([a-z0-9]+(?:-[a-z0-9]+)*)\.(\w[\w-]*)\.(debug|release)\.(json|link\.json|attempt\.json|log)$/;
70
+
71
+ /** The slot a file of `builds/` or `snaps/` belongs to, or null (a snapshot, another layout's). */
72
+ function slotOfFile(name, snaps) {
73
+ const m = SLOT_FILE.exec(name);
74
+ if (!m) return null;
75
+ const [, holder, build, profile, ext] = m;
76
+ if (snaps ? holder !== 'main' || ext === 'json' : ext === 'link.json' || !isValidId(holder))
77
+ return null;
78
+
79
+ return { slot: { who: snaps ? MAIN : holder, build, profile }, ext };
80
+ }
81
+
82
+ /** The slots of `who` that have a file: a link, an attempt or a log. */
83
+ function slotsOf(dir, who) {
84
+ const snaps = who === MAIN;
85
+ const seen = new Map();
86
+ for (const e of listOf(snaps ? snapsOf(dir) : buildsOf(dir))) {
87
+ const s = e.isFile() && slotOfFile(e.name, snaps)?.slot;
88
+ if (s && s.who === who) seen.set(slotKey(s), s);
89
+ }
90
+
91
+ return [...seen.values()];
92
+ }
93
+
57
94
  const playerFile = (dir) => path.join(session(dir), 'play.json');
58
95
  const playerLog = (dir) => path.join(session(dir), 'play.log');
59
96
  const leftovers = /^.+\.(?:tmp|old)-(\d+)$/;
@@ -64,6 +101,7 @@ const leftovers = /^.+\.(?:tmp|old)-(\d+)$/;
64
101
  const KEY_RE = /^[0-9a-f]{16}(?:-[a-z0-9]+(?:-[a-z0-9]+)*|\.main)?$/;
65
102
  const CLEAN_KEY = /^[0-9a-f]{16}$/;
66
103
  // A link that cannot be read: nobody knows which snapshot it holds, so it holds them all (d24).
104
+ /** @type {Readonly<{unread: true, snap?: undefined, released?: undefined, source?: undefined}>} */
67
105
  const UNREAD = Object.freeze({ unread: true });
68
106
 
69
107
  function readJson(file) {
@@ -142,14 +180,32 @@ function rowOf(where, row, keys, warnings) {
142
180
  return out;
143
181
  }
144
182
 
145
- /** One build's entry: its command, its output, the rows it plays on. */
183
+ /** A build's profiles (docs/Handoff-Plan.md t18): debug always; release when it has its own. */
184
+ export const PROFILES = ['debug', 'release'];
185
+
186
+ /** A build's command, one or by profile, as `{debug, release?}`. */
187
+ function profilesOf(where, build) {
188
+ if (!isMap(build)) {
189
+ needText(`${where}.build`, build);
190
+
191
+ return { debug: build };
192
+ }
193
+
194
+ for (const k of Object.keys(build))
195
+ if (!PROFILES.includes(k))
196
+ throw new Error(`gcf/config.yml: ${where}.build: a profile is debug or release, not ${k}`);
197
+ if (build.debug === undefined) throw new Error(`gcf/config.yml: ${where}.build needs debug:`);
198
+ for (const [k, v] of Object.entries(build)) needText(`${where}.build.${k}`, v);
199
+
200
+ return { ...build };
201
+ }
202
+
203
+ /** One build's entry: its command by profile, its output, the rows it plays on. */
146
204
  function buildEntry(name, b, warnings) {
147
205
  const where = `play.builds.${name}`;
148
206
  if (!NAME_RE.test(name)) throw new Error(`a build's name is one word: ${name}`);
149
207
  if (!isMap(b)) throw new Error(`gcf/config.yml: ${where} must map build:, output: and plays_on:`);
150
- if (typeof b.build === 'object' && b.build !== null)
151
- throw new Error(`gcf/config.yml: ${where}.build: profiles come with step 2, give one command`);
152
- needText(`${where}.build`, b.build);
208
+ const profiles = profilesOf(where, b.build);
153
209
  needOutput(b.output, `${where}.output`);
154
210
  const rows = b.plays_on ?? [];
155
211
  if (!Array.isArray(rows)) throw new Error(`gcf/config.yml: ${where}.plays_on must list rows`);
@@ -158,19 +214,19 @@ function buildEntry(name, b, warnings) {
158
214
  throw new Error(`gcf/config.yml: ${where}.plays_on[${i}] needs a device`);
159
215
 
160
216
  return {
161
- build: b.build,
217
+ profiles,
162
218
  output: b.output,
163
219
  plays_on: rows.map((row, i) => rowOf(`${where}.plays_on[${i}]`, row, ROW_KEYS, warnings)),
164
220
  };
165
221
  }
166
222
 
167
- /** The builds of `play:`: `builds:` with one entry, or the old `build:`, `output:` as `default`. */
223
+ /** The builds of `play:`: `builds:`, or the old `build:`, `output:` as `default`. */
168
224
  function buildsIn(play, warnings) {
169
225
  if (play.builds === undefined) {
170
- needText('play.build', play.build);
226
+ const profiles = profilesOf('play', play.build);
171
227
  needOutput(play.output);
172
228
 
173
- return { default: { build: play.build, output: play.output, plays_on: [] } };
229
+ return { default: { profiles, output: play.output, plays_on: [] } };
174
230
  }
175
231
 
176
232
  if (play.build !== undefined || play.output !== undefined)
@@ -180,20 +236,18 @@ function buildsIn(play, warnings) {
180
236
  throw new Error('gcf/config.yml: play.builds must map a name to build: and output:');
181
237
  const names = Object.keys(builds);
182
238
  if (names.length === 0) throw new Error('gcf/config.yml: play.builds names no build');
183
- if (names.length > 1)
184
- throw new Error('gcf/config.yml: play.builds: several builds come with step 2, keep one');
185
239
 
186
240
  return Object.fromEntries(names.map((n) => [n, buildEntry(n, builds[n], warnings)]));
187
241
  }
188
242
 
189
243
  /**
190
244
  * `play:` of a config, checked; null when the project has none. `output` stays inside the project:
191
- * it is copied from there, and a path out of it would copy anything. One build in step 1
192
- * (docs/Handoff-Plan.md d1, d2): `build` and `output` are its own, for a reader of the old form.
193
- * @returns {{build: string, output: string, builds: Record<string, {build: string, output: string,
194
- * plays_on: object[]}>, auto_build: string, targets: Record<string, {start: string, open: string,
195
- * stop?: string, build: string, for?: object, devices?: string, launches?: boolean}>,
196
- * warnings: string[]} | null}
245
+ * it is copied from there, and a path out of it would copy anything. `auto_build`: the build a
246
+ * run's card gets when its `play_on` does not say otherwise (docs/Handoff-Plan.md t16, t20).
247
+ * @returns {{builds: Record<string, {profiles: {debug: string, release?: string}, output: string,
248
+ * plays_on: object[]}>, auto_build: string, targets: Record<string, {start: string,
249
+ * open: string, stop?: string, build: string, for?: object, devices?: string,
250
+ * launches?: boolean}>, warnings: string[]} | null}
197
251
  */
198
252
  export function playOf(config) {
199
253
  const play = config.play;
@@ -202,25 +256,49 @@ export function playOf(config) {
202
256
  throw new Error('gcf/config.yml: play must map builds: and targets:');
203
257
  const warnings = [];
204
258
  const builds = buildsIn(play, warnings);
205
- const [only] = Object.keys(builds);
206
- const auto = play.auto_build ?? only;
259
+ const [first] = Object.keys(builds);
260
+ const auto = play.auto_build ?? first;
207
261
  if (!Object.hasOwn(builds, auto))
208
262
  throw new Error(`gcf/config.yml: play.auto_build names no build: ${auto}`);
209
263
  const targets = play.targets ?? {};
210
264
  needTargets(targets, builds, warnings);
211
265
 
212
266
  return {
213
- build: builds[only].build,
214
- output: builds[only].output,
215
267
  builds,
216
268
  auto_build: auto,
217
269
  targets: Object.fromEntries(
218
- Object.entries(targets).map(([n, t]) => [n, { ...t, build: t.build ?? only }]),
270
+ Object.entries(targets).map(([n, t]) => [n, { ...t, build: t.build ?? first }]),
219
271
  ),
220
272
  warnings,
221
273
  };
222
274
  }
223
275
 
276
+ /**
277
+ * The build a card gets when none is named: `auto_build` when its `play_on` names it or names no
278
+ * build, else the first build its `play_on` names (docs/Handoff-Plan.md t16, t20).
279
+ */
280
+ export function defaultBuild(play, playOn = []) {
281
+ const on = [playOn ?? []].flat().filter((n) => Object.hasOwn(play.builds, n));
282
+
283
+ return !on.length || on.includes(play.auto_build) ? play.auto_build : on[0];
284
+ }
285
+
286
+ /**
287
+ * What one build does: its name, its profile, its command and output. An unknown name, or a
288
+ * profile the build has no command for, refuses.
289
+ * @returns {{name: string, profile: string, command: string, output: string}}
290
+ */
291
+ export function specOf(play, name, profile = 'debug') {
292
+ if (!Object.hasOwn(play.builds, name))
293
+ throw new Error(`no build ${name}: ${Object.keys(play.builds).join(', ')}`);
294
+ const b = play.builds[name];
295
+ if (!PROFILES.includes(profile)) throw new Error(`a profile is debug or release: ${profile}`);
296
+ if (b.profiles[profile] === undefined)
297
+ throw new Error(`${name} has no ${profile} profile: its build is one command`);
298
+
299
+ return { name, profile, command: b.profiles[profile], output: b.output };
300
+ }
301
+
224
302
  function needOutput(output, where = 'play.output') {
225
303
  needText(where, output);
226
304
  const parts = String(output).split(/[\\/]/);
@@ -314,11 +392,11 @@ const NOT_CODE = ['gcf', 'GLOSSARY.md', '.gcf-session'];
314
392
 
315
393
  /**
316
394
  * The key of the code HEAD holds, the framework's files left out (d29), and of how it is built: a
317
- * verdict or an inbox commit keeps it, a new `play.build` or `play.output` does not. Null with no
318
- * commit. 16 hex: a path on Windows stays short. The top level alone: a folder's entry is the hash
319
- * of all it holds, and every file the key leaves out is at the top.
395
+ * verdict or an inbox commit keeps it, another build, profile, command or output does not. Null
396
+ * with no commit. 16 hex: a path on Windows stays short. The top level alone: a folder's entry is
397
+ * the hash of all it holds, and every file the key leaves out is at the top.
320
398
  */
321
- function codeOf(cwd, play) {
399
+ function codeOf(cwd, spec) {
322
400
  const out = gitOut(cwd, ['ls-tree', '-z', 'HEAD']);
323
401
  if (out === null) return null;
324
402
  const code = out
@@ -327,24 +405,24 @@ function codeOf(cwd, play) {
327
405
  .filter((l) => !NOT_CODE.includes(l.slice(l.indexOf('\t') + 1)));
328
406
 
329
407
  return createHash('sha256')
330
- .update([...code, play.build, play.output].join('\0'))
408
+ .update([...code, spec.name, spec.profile, spec.command, spec.output].join('\0'))
331
409
  .digest('hex')
332
410
  .slice(0, 16);
333
411
  }
334
412
 
335
413
  /** The snapshot's key: the code's alone when the tree is clean, else its holder's own too. */
336
- function keyOf(cwd, who, loose, play) {
337
- const code = codeOf(cwd, play);
414
+ function keyOf(cwd, who, loose, spec) {
415
+ const code = codeOf(cwd, spec);
338
416
  if (code && !loose.length) return code;
339
417
 
340
418
  return `${code ?? '0'.repeat(16)}${who === MAIN ? '.main' : `-${who}`}`;
341
419
  }
342
420
 
343
421
  /** What git sees changed or new, each path once; gcf/ and the run's own files are no build's. */
344
- function looseOf(cwd) {
422
+ function looseOf(cwd, also = []) {
345
423
  const out = gitOut(cwd, [
346
424
  ...['--no-optional-locks', 'status', '--porcelain', '-z', '-uall', '--', '.'],
347
- ...NOT_CODE.map((n) => `:(exclude)${n}`),
425
+ ...[...NOT_CODE, ...also].map((n) => `:(exclude)${n}`),
348
426
  ]);
349
427
  const parts = (out ?? '').split('\0').filter(Boolean);
350
428
  const paths = [];
@@ -376,10 +454,15 @@ const withTail = (problem, file) => {
376
454
 
377
455
  /** Who may be built without `--from`: what waits for play, in the checkout's own code. */
378
456
  const PLAYABLE = ['awaiting-verdict', 'unplayed'];
457
+ const itemIn = async (dir, id) => (await buildLedger(dir)).item(id);
379
458
 
380
459
  /** Why item `id` may not get this build now, or null. A card still in its worktree is `ready`. */
381
460
  async function statusProblem(dir, id, from) {
382
- const item = (await buildLedger(dir)).item(id);
461
+ return problemOf(await itemIn(dir, id), id, from);
462
+ }
463
+
464
+ /** `statusProblem` of a card read already. */
465
+ function problemOf(item, id, from) {
383
466
  if (!item) return `${id} is not on the board`;
384
467
  const status = item.data.status;
385
468
  if (from ? status === 'ready' : PLAYABLE.includes(status)) return null;
@@ -407,26 +490,26 @@ async function holdCheckout(dir, id) {
407
490
  }
408
491
 
409
492
  /**
410
- * Every holder's link: a card's id, or MAIN, to its link; UNREAD for one that cannot be read. A
411
- * link of the old layout (a card's facts, no `snap`) holds nothing: a sweep takes it.
493
+ * Every slot's link, by `slotKey`; UNREAD for one that cannot be read. Links of the old layout
494
+ * (`builds/<id>.json`, `snaps/main.link.json`: no build, no profile) hold nothing: a sweep takes
495
+ * them, and Play builds again (docs/Handoff-Plan.md t16).
412
496
  * @returns {Map<string, {snap?: string, released?: boolean, source?: string} | typeof UNREAD>}
413
497
  */
414
498
  export function linksOf(projectDir) {
415
499
  const dir = path.resolve(projectDir);
416
500
  const links = new Map();
417
- const read = (who, file) => {
418
- const link = readJson(file);
419
- // A name that is no snapshot's would point a delete anywhere: such a link holds nothing.
420
- const bad = link && typeof link.snap === 'string' && !KEY_RE.test(link.snap);
421
- links.set(who, link === null ? UNREAD : bad ? { ...link, snap: null } : link);
422
- };
423
-
424
- for (const e of listOf(buildsOf(dir))) {
425
- const id = e.isFile() && !e.name.endsWith('.attempt.json') && /^(.+)\.json$/.exec(e.name)?.[1];
426
- if (id && isValidId(id)) read(id, path.join(buildsOf(dir), e.name));
427
- }
428
-
429
- if (existsSync(linkOf(dir, MAIN))) read(MAIN, linkOf(dir, MAIN));
501
+ for (const [folder, snaps] of /** @type {[string, boolean][]} */ ([
502
+ [buildsOf(dir), false],
503
+ [snapsOf(dir), true],
504
+ ]))
505
+ for (const e of listOf(folder)) {
506
+ const f = e.isFile() && slotOfFile(e.name, snaps);
507
+ if (!f || f.ext !== (snaps ? 'link.json' : 'json')) continue;
508
+ const link = readJson(path.join(folder, e.name));
509
+ // A name that is no snapshot's would point a delete anywhere: such a link holds nothing.
510
+ const bad = link && typeof link.snap === 'string' && !KEY_RE.test(link.snap);
511
+ links.set(slotKey(f.slot), link === null ? UNREAD : bad ? { ...link, snap: null } : link);
512
+ }
430
513
 
431
514
  return links;
432
515
  }
@@ -456,21 +539,23 @@ function dropSnap(dir, key) {
456
539
  rmSync(snapFactsOf(dir, key), { force: true });
457
540
  }
458
541
 
459
- /** A holder's attempt goes with it, unless a build for it is under way right now. */
460
- function dropAttempt(dir, who, { log = false } = {}) {
461
- if (building(readJson(attemptOf(dir, who)))) return;
462
- rmSync(attemptOf(dir, who), { force: true });
463
- if (log) rmSync(logOf(dir, who), { force: true });
542
+ /** A slot's attempt goes with it, unless a build for it is under way right now. */
543
+ function dropAttempt(dir, slot, { log = false } = {}) {
544
+ if (building(readJson(attemptOf(dir, slot)))) return;
545
+ rmSync(attemptOf(dir, slot), { force: true });
546
+ if (log) rmSync(logOf(dir, slot), { force: true });
464
547
  }
465
548
 
466
549
  /**
467
- * Point `who` at snapshot `key`; the snapshot it held before goes when nobody else holds it.
550
+ * Point `slot` at snapshot `key`; the snapshot it held before goes when nobody else holds it.
468
551
  * Under the main lock.
469
552
  */
470
- function linkTo(dir, who, key, source) {
471
- const was = linksOf(dir).get(who);
472
- writeJsonSync(linkOf(dir, who), {
473
- id: who === MAIN ? null : who,
553
+ function linkTo(dir, slot, key, source) {
554
+ const was = linksOf(dir).get(slotKey(slot));
555
+ writeJsonSync(linkOf(dir, slot), {
556
+ id: slot.who === MAIN ? null : slot.who,
557
+ build: slot.build,
558
+ profile: slot.profile,
474
559
  snap: key,
475
560
  at: new Date().toISOString(),
476
561
  source,
@@ -479,26 +564,38 @@ function linkTo(dir, who, key, source) {
479
564
  dropSnap(dir, was.snap);
480
565
  }
481
566
 
567
+ /** Whether the config no longer has the slot's build or profile; unknown with no config read. */
568
+ const unsetIn = (play, s) =>
569
+ play !== null &&
570
+ (!Object.hasOwn(play.builds, s.build) || play.builds[s.build].profiles[s.profile] === undefined);
571
+
482
572
  /**
483
- * Remove what nobody needs any more (d24): a released link, the link of a card off the board, a
484
- * folder of the old layout, a snapshot nobody holds, leftovers of a dead process. Under the main
485
- * lock. A held file waits for the next sweep; a card file that cannot be read says nothing of who
486
- * left the board, so nothing goes by it; while a link cannot be read, no snapshot goes.
573
+ * Remove what nobody needs any more (d24): a released link, the link of a card off the board or of
574
+ * a build or profile the config no longer has, the files of the old layouts, a snapshot nobody
575
+ * holds, leftovers of a dead process. Under the main lock. A held file waits for the next sweep; a
576
+ * card file that cannot be read says nothing of who left the board, so nothing goes by it; while a
577
+ * link cannot be read, no snapshot goes.
487
578
  */
488
579
  async function sweep(dir) {
489
580
  sweepTickets(dir);
490
581
  const ledger = await buildLedger(dir).catch(() => null);
491
- const ids = sweepFolders(dir);
582
+ const play = await readConfig(path.join(dir, 'gcf'))
583
+ .then(playOf)
584
+ .catch(() => null);
585
+ const slots = sweepFolders(dir);
492
586
  const links = linksOf(dir);
493
587
  const gone = (id) =>
494
- ledger !== null && !ledger.item(id) && !existsSync(path.join(dir, 'gcf', 'work', `${id}.md`));
495
- for (const id of ids) {
496
- const link = links.get(id);
588
+ id !== MAIN &&
589
+ ledger !== null &&
590
+ !ledger.item(id) &&
591
+ !existsSync(path.join(dir, 'gcf', 'work', `${id}.md`));
592
+ for (const s of slots) {
593
+ const link = links.get(slotKey(s));
497
594
  if (link === UNREAD) continue;
498
- const left = gone(id);
595
+ const left = gone(s.who) || unsetIn(play, s);
499
596
  if (left || (link && (link.released === true || typeof link.snap !== 'string'))) {
500
- rmSync(linkOf(dir, id), { force: true });
501
- if (left) dropAttempt(dir, id, { log: true });
597
+ rmSync(linkOf(dir, s), { force: true });
598
+ if (left) dropAttempt(dir, s, { log: true });
502
599
  }
503
600
  }
504
601
 
@@ -519,33 +616,45 @@ function dropOld(dir, id) {
519
616
  void rm(path.join(buildsOf(dir), id), RM).catch(() => {});
520
617
  }
521
618
 
619
+ // A holder's files before builds and profiles (core 0.28): `<id>.json`, `main.link.json`, ….
620
+ const OLD_FILE = /^([a-z0-9]+(?:-[a-z0-9]+)*)\.(json|link\.json|attempt\.json|log)$/;
621
+
522
622
  /**
523
- * Leftovers of a dead process go, and the folders of the old layout (`builds/<id>/`), which no
524
- * link reaches. Not awaited: the main lock is held here, and every move would wait for a big one.
525
- * @returns {Set<string>} the ids that have files under `builds/`
623
+ * Leftovers of a dead process go, the folders of the old layout (`builds/<id>/`), which no link
624
+ * reaches, and a holder's files from before builds and profiles. Not awaited: the main lock is
625
+ * held here, and every move would wait for a big one.
626
+ * @returns {Slot[]} the slots that have files
526
627
  */
527
628
  function sweepFolders(dir) {
528
- const ids = new Set();
529
- const drop = (folder, name) => void rm(path.join(folder, name), RM).catch(() => {});
629
+ const slots = new Map();
530
630
  for (const folder of [buildsOf(dir), snapsOf(dir)])
531
631
  for (const e of listOf(folder)) {
532
- const left = leftovers.exec(e.name);
533
- if (left && !alive(Number(left[1]))) drop(folder, e.name);
534
- if (left) continue;
535
-
536
- if (folder !== buildsOf(dir)) continue;
537
- if (e.isDirectory()) dropOld(dir, e.name);
538
- const id = e.name.replace(/(\.attempt)?\.(json|log)$/, '');
539
- if (e.isFile() && isValidId(id)) ids.add(id);
632
+ const s = sweepEntry(dir, folder, e);
633
+ if (s) slots.set(slotKey(s), s);
540
634
  }
541
635
 
542
- return ids;
636
+ return [...slots.values()];
637
+ }
638
+
639
+ /** One entry of `builds/` or `snaps/` swept; the slot it belongs to, or null. */
640
+ function sweepEntry(dir, folder, e) {
641
+ const snaps = folder === snapsOf(dir);
642
+ const drop = () => void rm(path.join(folder, e.name), RM).catch(() => {});
643
+ const left = leftovers.exec(e.name);
644
+ if (left && !alive(Number(left[1]))) drop();
645
+ if (left) return null;
646
+ if (!snaps && e.isDirectory()) dropOld(dir, e.name);
647
+ if (!e.isFile()) return null;
648
+ const old = OLD_FILE.exec(e.name);
649
+ if (old && (snaps ? old[1] === 'main' : isValidId(old[1]))) drop();
650
+
651
+ return slotOfFile(e.name, snaps)?.slot ?? null;
543
652
  }
544
653
 
545
654
  const building = (attempt) => attempt?.building === true && alive(attempt.pid);
546
655
 
547
656
  /**
548
- * The card's play has ended (a verdict, a drop): its player stops and its link goes; its snapshot
657
+ * The card's play has ended (a verdict, a drop): its player stops and its links go; each snapshot
549
658
  * goes too when no other card holds it (d24). After the move's commit, so it never fails the move:
550
659
  * the problem comes back as words, and the mark `released` makes a later sweep repeat what a held
551
660
  * file refused. A card that a tune sends back stays on the board, and only the mark tells this link
@@ -558,12 +667,15 @@ export function releaseBuild(projectDir, id) {
558
667
  const dir = path.resolve(projectDir);
559
668
  try {
560
669
  if (playerOf(dir)?.id === id) stopPlay(dir);
561
- const file = linkOf(dir, id);
562
- const link = readJson(file);
563
- if (link) writeJsonSync(file, { ...link, released: true });
564
- rmSync(file, { force: true });
565
- dropAttempt(dir, id);
566
- if (typeof link?.snap === 'string' && !held(linksOf(dir), link.snap)) dropSnap(dir, link.snap);
670
+ for (const slot of slotsOf(dir, id)) {
671
+ const file = linkOf(dir, slot);
672
+ const link = readJson(file);
673
+ if (link) writeJsonSync(file, { ...link, released: true });
674
+ rmSync(file, { force: true });
675
+ dropAttempt(dir, slot);
676
+ if (typeof link?.snap === 'string' && !held(linksOf(dir), link.snap))
677
+ dropSnap(dir, link.snap);
678
+ }
567
679
  } catch (e) {
568
680
  return `the build of ${id} stays on the disk for now: ${e.message}`;
569
681
  }
@@ -584,22 +696,22 @@ async function refusedNow(dir, who, from, ticket) {
584
696
  }
585
697
 
586
698
  /**
587
- * Put a finished build in place of snapshot `key` and point `who` at it, or throw and leave the old
588
- * one with its facts. A card whose status moved on meanwhile (a verdict needs no wait for a build)
589
- * takes nothing. `reuse`: a build of the same code that ended meanwhile serves this one, and this
590
- * one is thrown away (d23).
591
- * @returns {Promise<{refused: string} | {facts: object}>}
699
+ * Put a finished build in place of snapshot `key` and point `slot` at it, or throw and leave the
700
+ * old one with its facts. A card whose status moved on meanwhile (a verdict needs no wait for a
701
+ * build) takes nothing. `reuse`: a build of the same code that ended meanwhile serves this one, and
702
+ * this one is thrown away (d23).
703
+ * @returns {Promise<{refused?: string, stopped?: boolean, facts?: Record<string, any>}>}
592
704
  */
593
- async function publish(dir, { who, key, tmp, facts, source, from, reuse, ticket }) {
705
+ async function publish(dir, { slot, key, tmp, facts, source, from, reuse, ticket }) {
594
706
  const target = snapOf(dir, key);
595
707
  const old = `${target}.old-${process.pid}`;
596
708
  const done = await withMainLock(dir, async () => {
597
- const refused = await refusedNow(dir, who, from, ticket);
709
+ const refused = await refusedNow(dir, slot.who, from, ticket);
598
710
  if (refused) return refused;
599
711
 
600
712
  const there = reuse && readJson(snapFactsOf(dir, key));
601
713
  if (there && existsSync(target) && held(linksOf(dir), key)) {
602
- linkTo(dir, who, key, source);
714
+ linkTo(dir, slot, key, source);
603
715
 
604
716
  return { facts: there };
605
717
  }
@@ -616,7 +728,7 @@ async function publish(dir, { who, key, tmp, facts, source, from, reuse, ticket
616
728
  throw e;
617
729
  }
618
730
 
619
- linkTo(dir, who, key, source);
731
+ linkTo(dir, slot, key, source);
620
732
 
621
733
  return { facts };
622
734
  });
@@ -627,49 +739,77 @@ async function publish(dir, { who, key, tmp, facts, source, from, reuse, ticket
627
739
  }
628
740
 
629
741
  /**
630
- * Build card `id` with `play.build`, or link it to the snapshot of the same code another card
631
- * holds (d23); the old snapshot stays until a new one has replaced it. `from`: the card's worktree,
632
- * whose code is still its alone. `fresh`: build even when a snapshot of this code is there, and
633
- * replace it. `wait`: a busy checkout is waited for on a ticket, not refused (docs/Handoff-Plan.md
634
- * d6); `ticket`: the one a caller opened, and closes. A failed build is no error: it comes back as
635
- * `problem`, and the card goes on without one.
742
+ * What a build of `who` builds: the build `of` names, else the card's own (`defaultBuild`), else
743
+ * `auto_build` for the checkout; the profile given, else debug.
744
+ */
745
+ function specFor(play, item, { of = null, profile = null }) {
746
+ return specOf(play, of ?? defaultBuild(play, item?.data.play_on), profile ?? 'debug');
747
+ }
748
+
749
+ /**
750
+ * Build card `id` (one build of it, one profile: docs/Handoff-Plan.md t16, t18), or link it to the
751
+ * snapshot of the same code another card holds (d23); the old snapshot stays until a new one has
752
+ * replaced it. `from`: the card's worktree, whose code is still its alone. `fresh`: build even when
753
+ * a snapshot of this code is there, and replace it. `of`, `profile`: which build and profile, else
754
+ * the card's own build in debug. `wait`: a busy checkout is waited for on a ticket, not refused
755
+ * (d6); `ticket`: the one a caller opened, and closes. A card whose code has left the checkout is
756
+ * built in the build folder (t19). A failed build is no error: it comes back as `problem`, and the
757
+ * card goes on without one.
636
758
  * @returns {Promise<{id: string, ok: boolean, problem?: string, dirtied?: string[]}>}
637
759
  */
638
760
  export async function buildItem(projectDir, id, opts = {}) {
639
761
  const { from = null, fresh = false } = opts;
640
762
  needId(id);
641
763
  const dir = path.resolve(projectDir);
642
- await projectPlay(dir);
643
764
  const cwd = from ? path.resolve(from) : dir;
644
765
  if (from && cwd !== path.join(session(dir), 'worktrees', id))
645
766
  throw new Error(`--from names the worktree of ${id}, not ${from}`);
646
- const problem = await statusProblem(dir, id, from);
767
+ const item = await itemIn(dir, id);
768
+ const first = specFor(await projectPlay(dir), item, opts);
769
+ const problem = problemOf(item, id, from);
647
770
  if (problem) throw new Error(problem);
771
+ const free = !from && (await freeOfCheckout(dir, id, item));
772
+ const job = { build: id, of: first.name, profile: first.profile, from, fresh, free };
648
773
 
649
- return holding(dir, id, { ...opts, job: { build: id, from, fresh } }, async (hold) => {
774
+ return holding(dir, id, { ...opts, free, job }, async (hold) => {
650
775
  // Read again after a wait: the config and the card may have changed meanwhile.
651
- const play = await projectPlay(dir);
652
- const again = await statusProblem(dir, id, from);
776
+ const spec = specOf(await projectPlay(dir), first.name, first.profile);
777
+ const now = await itemIn(dir, id);
778
+ const again = problemOf(now, id, from);
653
779
  if (again) throw new Error(again);
654
- if (!from) await needCardCode(dir, id);
780
+ const tree = from
781
+ ? null
782
+ : await treeFor(dir, id, {
783
+ item: now,
784
+ checkout: hold.checkout,
785
+ output: spec.output,
786
+ ticket: hold.n,
787
+ });
788
+ try {
789
+ const at = { who: id, from, own: hold.own, fresh, ticket: hold.n, cold: tree?.cold };
655
790
 
656
- return runBuild(dir, cwd, play, { who: id, from, own: hold.own, fresh, ticket: hold.n });
791
+ return await runBuild(dir, tree?.cwd ?? cwd, spec, at);
792
+ } finally {
793
+ tree?.release();
794
+ }
657
795
  });
658
796
  }
659
797
 
660
798
  /**
661
799
  * Build the checkout as it is, uncommitted edits too (d30): "Play main" after the operator's own
662
800
  * changes. A clean tree whose code a card's snapshot already holds takes that one, unless `fresh`.
801
+ * `of`, `profile`: which build and profile, else `auto_build` in debug.
663
802
  */
664
803
  export async function buildMain(projectDir, opts = {}) {
665
804
  const { fresh = false } = opts;
666
805
  const dir = path.resolve(projectDir);
667
- await projectPlay(dir);
806
+ const first = specFor(await projectPlay(dir), null, opts);
807
+ const job = { build: null, of: first.name, profile: first.profile, fresh };
668
808
 
669
- return holding(dir, MAIN, { ...opts, job: { build: null, fresh } }, async (hold) => {
670
- const play = await projectPlay(dir);
809
+ return holding(dir, MAIN, { ...opts, job }, async (hold) => {
810
+ const spec = specOf(await projectPlay(dir), first.name, first.profile);
671
811
 
672
- return runBuild(dir, dir, play, {
812
+ return runBuild(dir, dir, spec, {
673
813
  who: MAIN,
674
814
  from: null,
675
815
  own: hold.own,
@@ -683,25 +823,33 @@ export async function buildMain(projectDir, opts = {}) {
683
823
  * Run `fn` holding what a build of `who` needs. A harness run's own build goes under the lock its
684
824
  * run holds; without `wait` or `ticket` a busy checkout refuses, as before the queue; with them
685
825
  * the build waits its turn on a ticket (lib/build-queue.js). A ticket this opened, this closes.
826
+ * `free`: a build in the build folder of a project that runs its cards in worktrees takes its turn
827
+ * without the checkout (docs/Handoff-Plan.md t19). `fn` learns whether it holds the checkout.
686
828
  */
687
829
  async function holding(dir, who, opts, fn) {
688
- const { from = null, wait = false, ticket = null, job } = opts;
689
- if (ownRun(dir) || (!wait && ticket === null)) return holdingNow(dir, who, from, fn);
690
- const n = ticket ?? (await ticketOpen(dir, job));
830
+ const { from = null, ticket = null } = opts;
831
+ if (ownRun(dir) || (!opts.wait && ticket === null))
832
+ return holdingNow(dir, who, { from, free: opts.free }, fn);
833
+ const n = ticket ?? (await ticketOpen(dir, opts.job));
691
834
  try {
692
- const got = await waitTurn(dir, n, { from });
693
- try {
694
- return await fn({ own: Boolean(from), n });
695
- } finally {
696
- await got.release?.();
697
- // A run that yielded merges its own; a claim of the checkout leaves what waited to this one.
698
- if (got.release && !got.yielded) await mergeWaiting(dir);
699
- }
835
+ return await onTicket(dir, n, { own: Boolean(from), free: Boolean(from || opts.free) }, fn);
700
836
  } finally {
701
837
  if (ticket === null) ticketClose(dir, n);
702
838
  }
703
839
  }
704
840
 
841
+ /** `fn` once ticket `n` has its turn: with the checkout, or with no need of it (`free`). */
842
+ async function onTicket(dir, n, { own, free }, fn) {
843
+ const got = await waitTurn(dir, n, { free });
844
+ try {
845
+ return await fn({ own, n, checkout: !free });
846
+ } finally {
847
+ await got.release?.();
848
+ // A run that yielded merges its own; a claim of the checkout leaves what waited to this one.
849
+ if (got.release && !got.yielded) await mergeWaiting(dir);
850
+ }
851
+ }
852
+
705
853
  /** Whether this process belongs to the main run that holds the checkout: it waits for nobody. */
706
854
  const ownRun = (dir) => {
707
855
  const holder = runHolder(dir, MAIN_RUN);
@@ -709,27 +857,43 @@ const ownRun = (dir) => {
709
857
  return holder !== null && process.env.GCF_RUN_OWNER === `run:${holder}`;
710
858
  };
711
859
 
712
- /** The hold as before the queue: a busy checkout refuses. */
713
- async function holdingNow(dir, who, from, fn) {
714
- const hold = from ? { own: true, release: null } : await holdCheckout(dir, nameOf(who));
860
+ /**
861
+ * The hold as before the queue: a busy checkout refuses. A build that needs no checkout (`free`:
862
+ * the build folder of a worktree project) takes none; the build folder's own claim keeps it.
863
+ */
864
+ async function holdingNow(dir, who, { from, free = false }, fn) {
865
+ const hold =
866
+ from || free ? { own: Boolean(from), release: null } : await holdCheckout(dir, nameOf(who));
715
867
  try {
716
- return await fn({ ...hold, n: null });
868
+ return await fn({ ...hold, n: null, checkout: !from && !free });
717
869
  } finally {
718
870
  await hold.release?.();
719
871
  if (hold.release) await mergeWaiting(dir);
720
872
  }
721
873
  }
722
874
 
875
+ /** The commit that holds card `id`'s code: its close for an unplayed one, else `since`. */
876
+ function cardCode(dir, id, item) {
877
+ const at = item?.data.status === 'unplayed' ? unplayedCloseCommit(dir, id) : item?.data.since;
878
+ if (!at || gitOut(dir, ['cat-file', '-e', `${at}^{commit}`]) === null) return null;
879
+
880
+ return String(at);
881
+ }
882
+
883
+ /** Whether the checkout's HEAD holds the code of commit `at`; plans and gcf/ are no code. */
884
+ const headHolds = (dir, at) => codeTree(dir, 'HEAD') === codeTree(dir, at);
885
+
723
886
  /**
724
- * A card's build in the checkout builds the checkout's code: refused when that is no longer the
725
- * card's (docs/Handoff-Plan.md d7). `.ai-factory/` is left out: the moves commit plans there.
887
+ * Whether card `id`'s build needs nothing of the checkout: its code has left it, and the project
888
+ * runs its cards in worktrees. In `run_mode: main` such a build still waits for the boundary
889
+ * between a run's cards (docs/Handoff-Plan.md t19).
726
890
  */
727
- async function needCardCode(dir, id) {
728
- const item = (await buildLedger(dir)).item(id);
729
- const at = item?.data.status === 'unplayed' ? unplayedCloseCommit(dir, id) : item?.data.since;
730
- if (!at || gitOut(dir, ['cat-file', '-e', `${at}^{commit}`]) === null) return;
731
- if (codeTree(dir, 'HEAD') !== codeTree(dir, at))
732
- throw new Error(`the code of ${id} has left the folder: Build main builds what is there now`);
891
+ async function freeOfCheckout(dir, id, item) {
892
+ const mode =
893
+ item?.data.run_mode ?? (await readConfig(path.join(dir, 'gcf'))).run_mode ?? 'worktree';
894
+ const at = mode === 'worktree' ? cardCode(dir, id, item) : null;
895
+
896
+ return at !== null && !headHolds(dir, at);
733
897
  }
734
898
 
735
899
  /** The top of a commit's tree without the framework's files and the plans. */
@@ -743,6 +907,85 @@ function codeTree(cwd, rev) {
743
907
  .join('\0');
744
908
  }
745
909
 
910
+ const treeDir = (dir) => path.join(session(dir), 'buildtree');
911
+ const treeClaim = (dir) => path.join(session(dir), 'buildtree.json');
912
+
913
+ /**
914
+ * Where card `id` is built: the checkout while it holds the card's code and this build holds the
915
+ * checkout, else the build folder at the card's commit (docs/Handoff-Plan.md t19). Null: the
916
+ * checkout. `cold`: the build folder was made now, so a project's caches are built from nothing.
917
+ * @returns {Promise<{cwd: string, cold: boolean, release: () => void} | null>}
918
+ */
919
+ async function treeFor(dir, id, { item, checkout, output, ticket = null }) {
920
+ const at = cardCode(dir, id, item);
921
+ if (at === null) {
922
+ if (!checkout) throw new Error(`the code of ${id} is not known: build it again`);
923
+
924
+ return null;
925
+ }
926
+
927
+ if (checkout && headHolds(dir, at)) return null;
928
+ const release = await claimTree(dir, ticket);
929
+ try {
930
+ return { ...treeAt(dir, at, output), release };
931
+ } catch (e) {
932
+ release();
933
+ throw e;
934
+ }
935
+ }
936
+
937
+ /**
938
+ * The build folder for this process. Busy: a build on a ticket waits for it, any other refuses.
939
+ */
940
+ async function claimTree(dir, ticket = null) {
941
+ for (;;) {
942
+ const got = await withMainLock(dir, async () => {
943
+ const pid = Number(readJson(treeClaim(dir))?.pid);
944
+ if (pid && pid !== process.pid && alive(pid)) return pid;
945
+ writeJsonSync(treeClaim(dir), { pid: process.pid });
946
+
947
+ return () => rmSync(treeClaim(dir), { force: true });
948
+ });
949
+ if (typeof got === 'function') return got;
950
+ // A ticket waits for the folder, as it waits for its turn; a cancel ends the wait.
951
+ if (ticket === null)
952
+ throw new Error(`the build folder is busy (pid ${got}): build when that ends`);
953
+ if (cancelled(dir, ticket)) throw new Error(CANCELLED);
954
+ await new Promise((r) => setTimeout(r, 300));
955
+ }
956
+ }
957
+
958
+ /** git in `cwd`, or an error with its words. */
959
+ function gitMust(cwd, args) {
960
+ // A caller's GIT_DIR or GIT_WORK_TREE (a hook) would point a clean at its own folder.
961
+ const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !/^GIT_/.test(k)));
962
+ const res = spawnSync('git', args, { cwd, env, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
963
+ if (res.status !== 0)
964
+ throw new Error(`git ${args[0]} in the build folder failed: ${(res.stderr || '').trim()}`);
965
+ }
966
+
967
+ /**
968
+ * The build folder at commit `at`: a detached worktree of the project, made once and kept, so a
969
+ * project's ignored caches stay warm. What a killed build left goes: the checkout is forced and
970
+ * what git does not track and does not ignore is cleaned, but the build's `output`: an older
971
+ * commit may not ignore it yet. Never the project's folder.
972
+ * @returns {{cwd: string, cold: boolean}}
973
+ */
974
+ function treeAt(dir, at, output) {
975
+ const tree = treeDir(dir);
976
+ const cold = !existsSync(path.join(tree, '.git'));
977
+ if (cold) {
978
+ gitOut(dir, ['worktree', 'prune']);
979
+ rmSync(tree, RM);
980
+ gitMust(dir, ['worktree', 'add', '--detach', '--force', tree, at]);
981
+ }
982
+
983
+ gitMust(tree, ['checkout', '--detach', '--force', at]);
984
+ gitMust(tree, ['clean', '-ffd', '-e', `/${output.replaceAll('\\', '/')}/`]);
985
+
986
+ return { cwd: tree, cold };
987
+ }
988
+
746
989
  /**
747
990
  * What a worktree run left verified while this click held the checkout: that run has ended, and no
748
991
  * other would merge it until the next one starts. A refusal leaves it for that one.
@@ -757,21 +1000,25 @@ async function mergeWaiting(dir) {
757
1000
  }
758
1001
  }
759
1002
 
760
- /** What a build or a link answers: the holder, the snapshot's facts, and how it came. */
761
- const answerOf = (who, key, facts, source) => ({
762
- ...(who === MAIN ? { main: true } : { id: who }),
1003
+ /** What a build or a link answers: the holder, the build and profile, the facts, how it came. */
1004
+ const answerOf = (slot, key, facts, source) => ({
1005
+ ...(slot.who === MAIN ? { main: true } : { id: slot.who }),
1006
+ build: slot.build,
1007
+ profile: slot.profile,
763
1008
  ok: true,
764
1009
  ...facts,
765
1010
  snap: key,
766
1011
  source,
767
1012
  });
768
1013
 
769
- async function runBuild(dir, cwd, play, { who, from, own, fresh, ticket = null }) {
1014
+ async function runBuild(dir, cwd, spec, { who, from, own, fresh, ticket = null, cold = false }) {
1015
+ const slot = { who, build: spec.name, profile: spec.profile };
770
1016
  const started = new Date().toISOString();
771
- await mkdir(buildsOf(dir), { recursive: true });
772
- await mkdir(snapsOf(dir), { recursive: true });
773
- const loose = looseOf(cwd);
774
- const key = keyOf(cwd, who, loose, play);
1017
+ for (const d of [buildsOf(dir), snapsOf(dir)]) await mkdir(d, { recursive: true });
1018
+ // The build folder's output: the project ignores it, its older commit may not.
1019
+ const inTree = cwd === treeDir(dir);
1020
+ const loose = looseOf(cwd, inTree ? [spec.output] : []);
1021
+ const key = keyOf(cwd, who, loose, spec);
775
1022
  const source = who === MAIN ? 'main' : own ? 'run' : 'click';
776
1023
  // A dirty tree's snapshot is nobody else's, and not this holder's next time either (d22).
777
1024
  const reuse = !fresh && CLEAN_KEY.test(key);
@@ -782,31 +1029,41 @@ async function runBuild(dir, cwd, play, { who, from, own, fresh, ticket = null }
782
1029
  if (problem) throw new Error(problem);
783
1030
  }
784
1031
 
785
- const was = readJson(attemptOf(dir, who));
1032
+ const was = readJson(attemptOf(dir, slot));
786
1033
  if (building(was) && was.pid !== process.pid)
787
- throw new Error(`${nameOf(who)} is being built (pid ${was.pid}): wait until that build ends`);
1034
+ throw new Error(
1035
+ `${nameOf(who)} ${spec.name} ${spec.profile} is being built (pid ${was.pid}): ` +
1036
+ 'wait until that build ends',
1037
+ );
788
1038
  const there = reuse && readJson(snapFactsOf(dir, key));
789
1039
  if (there && existsSync(snapOf(dir, key)) && held(linksOf(dir), key)) {
790
- linkTo(dir, who, key, source);
791
- dropAttempt(dir, who);
1040
+ linkTo(dir, slot, key, source);
1041
+ dropAttempt(dir, slot);
792
1042
 
793
1043
  // Nothing ran here: what another build changed is not this one's to report.
794
- return answerOf(who, key, { ...there, dirtied: [] }, source);
1044
+ return answerOf(slot, key, { ...there, dirtied: [] }, source);
795
1045
  }
796
1046
 
797
- writeJsonSync(attemptOf(dir, who), { pid: process.pid, building: true, at: started });
1047
+ writeJsonSync(attemptOf(dir, slot), {
1048
+ pid: process.pid,
1049
+ building: true,
1050
+ at: started,
1051
+ ...(cold ? { cold: true } : {}),
1052
+ });
798
1053
 
799
1054
  return null;
800
1055
  });
801
1056
  if (linked) return linked;
802
1057
  const failed = (problem) => {
803
- writeJsonSync(attemptOf(dir, who), { pid: process.pid, problem, at: started });
1058
+ writeJsonSync(attemptOf(dir, slot), { pid: process.pid, problem, at: started });
804
1059
 
805
1060
  return {
806
1061
  ...(who === MAIN ? { main: true } : { id: who }),
1062
+ build: spec.name,
1063
+ profile: spec.profile,
807
1064
  ok: false,
808
1065
  problem,
809
- log: logOf(dir, who),
1066
+ log: logOf(dir, slot),
810
1067
  };
811
1068
  };
812
1069
 
@@ -815,9 +1072,9 @@ async function runBuild(dir, cwd, play, { who, from, own, fresh, ticket = null }
815
1072
  snapsOf(dir),
816
1073
  `${key}.${who === MAIN ? 'checkout' : `card-${who}`}.tmp-${process.pid}`,
817
1074
  );
818
- const at = { who, key, source, loose, from, reuse, tmp, failed, ticket };
1075
+ const at = { slot, key, source, loose, from, reuse, tmp, failed, ticket, inTree };
819
1076
  try {
820
- return await buildAndPublish(dir, cwd, play, at);
1077
+ return await buildAndPublish(dir, cwd, spec, at);
821
1078
  } catch (e) {
822
1079
  return failed(e.message);
823
1080
  } finally {
@@ -826,12 +1083,12 @@ async function runBuild(dir, cwd, play, { who, from, own, fresh, ticket = null }
826
1083
  }
827
1084
 
828
1085
  /**
829
- * `play.build` with its output in the holder's log. A ticket's cancel kills its tree, and the log
830
- * says so (docs/Handoff-Plan.md d6).
1086
+ * The build's command with its output in the slot's log. A ticket's cancel kills its tree, and the
1087
+ * log says so (docs/Handoff-Plan.md d6).
831
1088
  */
832
- async function buildCommand(dir, cwd, play, { who, ticket, minutes }) {
833
- const log = await open(logOf(dir, who), 'w');
834
- const run = runCommand(play.build, cwd, ['ignore', log.fd, log.fd], minutes * 60000);
1089
+ async function buildCommand(dir, cwd, spec, { slot, ticket, minutes }) {
1090
+ const log = await open(logOf(dir, slot), 'w');
1091
+ const run = runCommand(spec.command, cwd, ['ignore', log.fd, log.fd], minutes * 60000);
835
1092
  let stopped = false;
836
1093
  const watch =
837
1094
  ticket === null
@@ -857,41 +1114,53 @@ const ignored = (cwd, output) =>
857
1114
  // The slash: a rule for folders only must match a folder not built yet.
858
1115
  spawnSync('git', ['check-ignore', '-q', `${output}/`], { cwd }).status === 0;
859
1116
 
860
- async function buildAndPublish(dir, cwd, play, at) {
861
- const { who, key, source, loose, from, reuse, tmp, failed, ticket } = at;
862
- const output = path.join(cwd, play.output);
863
- if (!ignored(cwd, play.output))
864
- return failed(`play.output ${play.output} is not ignored by git: add it to .gitignore`);
1117
+ async function buildAndPublish(dir, cwd, spec, at) {
1118
+ const { slot, key, source, loose, from, reuse, tmp, failed, ticket, inTree } = at;
1119
+ const where = `play.builds.${spec.name}`;
1120
+ const output = path.join(cwd, spec.output);
1121
+ if (!ignored(inTree ? dir : cwd, spec.output))
1122
+ return failed(`${where}.output ${spec.output} is not ignored by git: add it to .gitignore`);
865
1123
  const before = treeOf(output);
866
1124
  const commit = gitOut(cwd, ['rev-parse', 'HEAD'])?.trim() ?? null;
867
1125
  const minutes = (await readConfig(path.join(dir, 'gcf'))).dod_timeout_min ?? 0;
868
- const res = await buildCommand(dir, cwd, play, { who, ticket, minutes });
1126
+ const res = await buildCommand(dir, cwd, spec, { slot, ticket, minutes });
869
1127
  if (res.stopped) return failed(CANCELLED);
870
- const why = failureOf('play.build', play.build, minutes, res);
871
- if (why) return failed(withTail(why, logOf(dir, who)));
1128
+ const why = failureOf(`${where}.build`, spec.command, minutes, res);
1129
+ if (why) return failed(withTail(why, logOf(dir, slot)));
872
1130
  const after = treeOf(output);
873
1131
  // A build that wrote nothing new must not stand in for this commit.
874
1132
  if (!refreshed(before, after))
875
- return failed(`the build did not update ${play.output}: no new file there`);
876
- const dirtied = looseOf(cwd).filter((p) => !loose.includes(p));
1133
+ return failed(`the build did not update ${spec.output}: no new file there`);
1134
+ const dirtied = looseOf(cwd, inTree ? [spec.output] : []).filter((p) => !loose.includes(p));
877
1135
  // Its links as they are: made absolute they would point back into `output`, at a later build.
878
1136
  await cp(output, tmp, { recursive: true, verbatimSymlinks: true });
879
1137
  const facts = {
880
1138
  key,
1139
+ build: spec.name,
1140
+ profile: spec.profile,
881
1141
  commit,
882
1142
  built_at: new Date().toISOString(),
883
1143
  dirty: loose.length > 0,
884
1144
  dirtied,
1145
+ in_tree: inTree,
885
1146
  size: [...after.values()].reduce((sum, f) => sum + f.size, 0),
886
1147
  };
887
- const done = await publish(dir, { who, key, tmp, facts, source, from, reuse, ticket });
1148
+ const done = await publish(dir, { slot, key, tmp, facts, source, from, reuse, ticket });
888
1149
  if (done.stopped) return failed(CANCELLED);
889
- rmSync(attemptOf(dir, who), { force: true });
1150
+ rmSync(attemptOf(dir, slot), { force: true });
890
1151
  // Not a failed build: the card has moved on, and nobody waits for this one.
891
- if (done.refused) return { id: who, ok: false, problem: done.refused, moved_on: true };
1152
+ if (done.refused)
1153
+ return {
1154
+ id: slot.who,
1155
+ build: spec.name,
1156
+ profile: spec.profile,
1157
+ ok: false,
1158
+ problem: done.refused,
1159
+ moved_on: true,
1160
+ };
892
1161
 
893
1162
  // What this build changed, even when another one's snapshot serves (a main batch stops on it).
894
- return answerOf(who, key, { ...done.facts, dirtied }, source);
1163
+ return answerOf(slot, key, { ...done.facts, dirtied }, source);
895
1164
  }
896
1165
 
897
1166
  /** The running player's record as it stands, or null; a dead one reads as none. Reads only. */
@@ -1021,20 +1290,23 @@ function recordPlayer(dir, record) {
1021
1290
  }
1022
1291
 
1023
1292
  /**
1024
- * Play the snapshot card `id` holds on `target`; `id` null: the checkout's ("Play main"). One
1025
- * player per project: the last one stops first. The process is cut loose from its caller, so a
1026
- * board's restart does not end the game. A process that ends with 0 has launched what it launches:
1027
- * nothing is left to stop. With no build, `wait` or `ticket` builds it on a ticket first and starts
1028
- * after it, in this process; without them it refuses, as before (docs/Handoff-Plan.md d9).
1293
+ * Play the snapshot card `id` holds on `target`; `id` null: the checkout's ("Play main"). The
1294
+ * target's build, in `profile` (debug when none: docs/Handoff-Plan.md t18). One player per
1295
+ * project: the last one stops first. The process is cut loose from its caller, so a board's
1296
+ * restart does not end the game. A process that ends with 0 has launched what it launches: nothing
1297
+ * is left to stop. With no build, `wait` or `ticket` builds it on a ticket first and starts after
1298
+ * it, in this process; without them it refuses, as before (docs/Handoff-Plan.md d9).
1029
1299
  */
1030
1300
  export async function startPlay(projectDir, id, targetName, opts = {}) {
1031
- const { wait = false, ticket = null, device = null } = opts;
1301
+ const { wait, ticket = null } = opts;
1032
1302
  if (id !== null) needId(id);
1033
1303
  const dir = path.resolve(projectDir);
1034
- targetOf(await projectPlay(dir), targetName);
1035
- const how = { target: targetName, device };
1036
- if ((!wait && ticket === null) || hasBuild(dir, id)) return startNow(dir, id, how);
1037
- const n = ticket ?? (await ticketOpen(dir, { build: id, start: how }));
1304
+ const play = await projectPlay(dir);
1305
+ const spec = specOf(play, targetOf(play, targetName).build, opts.profile ?? 'debug');
1306
+ const how = { target: targetName, device: opts.device ?? null, profile: spec.profile };
1307
+ const slot = { who: id ?? MAIN, build: spec.name, profile: spec.profile };
1308
+ if ((!wait && ticket === null) || hasBuild(dir, slot)) return startNow(dir, id, how);
1309
+ const n = ticket ?? (await ticketOpen(dir, await startJob(dir, id, spec, how)));
1038
1310
  try {
1039
1311
  return await buildThenStart(dir, id, how, n);
1040
1312
  } finally {
@@ -1042,8 +1314,17 @@ export async function startPlay(projectDir, id, targetName, opts = {}) {
1042
1314
  }
1043
1315
  }
1044
1316
 
1317
+ /** A start's ticket: its build and profile, and whether it needs the checkout. */
1318
+ async function startJob(dir, id, spec, how) {
1319
+ const free = id !== null && (await freeOfCheckout(dir, id, await itemIn(dir, id)));
1320
+
1321
+ return { build: id, of: spec.name, profile: spec.profile, free, start: how };
1322
+ }
1323
+
1045
1324
  async function buildThenStart(dir, id, how, n) {
1046
- const b = await (id === null ? buildMain(dir, { ticket: n }) : buildItem(dir, id, { ticket: n }));
1325
+ const of = targetOf(await projectPlay(dir), how.target).build;
1326
+ const opts = { ticket: n, of, profile: how.profile };
1327
+ const b = await (id === null ? buildMain(dir, opts) : buildItem(dir, id, opts));
1047
1328
  if (!b.ok) throw new Error(`the build for this play failed: ${b.problem}`);
1048
1329
  if (cancelled(dir, n)) throw new Error(CANCELLED);
1049
1330
 
@@ -1084,25 +1365,35 @@ function targetOf(play, targetName) {
1084
1365
  return target;
1085
1366
  }
1086
1367
 
1087
- const hasBuild = (dir, id) => {
1368
+ const hasBuild = (dir, slot) => {
1088
1369
  try {
1089
- return Boolean(heldKey(dir, id));
1370
+ return Boolean(heldKey(dir, slot));
1090
1371
  } catch {
1091
1372
  return false;
1092
1373
  }
1093
1374
  };
1094
1375
 
1095
- /** Whether card `id` (null: the checkout) has a snapshot to play now. */
1096
- export const hasBuildOf = (projectDir, id) => hasBuild(path.resolve(projectDir), id);
1376
+ /**
1377
+ * Whether card `id` (null: the checkout) has a snapshot to play on `targetName` now: of the
1378
+ * target's build, in `profile` (debug when none).
1379
+ */
1380
+ export async function hasBuildOf(projectDir, id, targetName, profile = null) {
1381
+ const dir = path.resolve(projectDir);
1382
+ const play = await projectPlay(dir);
1383
+ const build = targetOf(play, targetName).build;
1384
+
1385
+ return hasBuild(dir, { who: id ?? MAIN, build, profile: profile ?? 'debug' });
1386
+ }
1097
1387
 
1098
1388
  /** The start itself, on the snapshot there is. */
1099
- async function startNow(dir, id, { target: targetName, device: deviceId = null }) {
1389
+ async function startNow(dir, id, { target: targetName, device: deviceId = null, profile }) {
1100
1390
  const play = await projectPlay(dir);
1101
1391
  const target = targetOf(play, targetName);
1102
1392
  const device = await deviceFor(dir, targetName, target, deviceId);
1393
+ const slot = { who: id ?? MAIN, build: target.build, profile: profile ?? 'debug' };
1103
1394
  // Held to the end: a verdict meanwhile waits, or it would miss the player this start records.
1104
1395
  const started = await withMainLock(dir, () =>
1105
- startLocked(dir, id, { targetName, target, device }),
1396
+ startLocked(dir, id, { targetName, target, device, slot }),
1106
1397
  );
1107
1398
 
1108
1399
  return started.launching ? awaitLaunch(dir, started) : started;
@@ -1120,15 +1411,16 @@ function commandOf(snapshot, at) {
1120
1411
  );
1121
1412
  }
1122
1413
 
1123
- /** What a player plays: its build, and the device when it has one. */
1124
- const playsOn = (target, device) => ({
1125
- build: target.build,
1414
+ /** What a player plays: its build and profile, and the device when it has one. */
1415
+ const playsOn = (slot, device) => ({
1416
+ build: slot.build,
1417
+ profile: slot.profile,
1126
1418
  ...(device ? { device: device.id, device_name: device.name } : {}),
1127
1419
  });
1128
1420
 
1129
- async function startLocked(dir, id, { targetName, target, device }) {
1421
+ async function startLocked(dir, id, { targetName, target, device, slot }) {
1130
1422
  await sweep(dir);
1131
- const key = heldKey(dir, id);
1423
+ const key = heldKey(dir, slot);
1132
1424
  const snapshot = snapOf(dir, key);
1133
1425
  stopPlay(dir);
1134
1426
  const port = await freePort();
@@ -1145,7 +1437,7 @@ async function startLocked(dir, id, { targetName, target, device }) {
1145
1437
  const url = /^https?:\/\/[^\s]+/.exec(open)?.[0] ?? null;
1146
1438
  const stop = target.stop ? { stop: inCommand(target.stop) } : {};
1147
1439
  const main = id === null ? { main: true } : {};
1148
- const on = playsOn(target, device);
1440
+ const on = playsOn(slot, device);
1149
1441
  const record = {
1150
1442
  pid: child.pid,
1151
1443
  id,
@@ -1208,15 +1500,16 @@ async function awaitLaunch(dir, { child, exited, record, targetName }) {
1208
1500
  throw new Error(withTail(`play.targets.${targetName}.start failed (${end.why})`, playerLog(dir)));
1209
1501
  }
1210
1502
 
1211
- /** The snapshot card `id` holds, or the checkout's for null; none throws what to do. */
1212
- function heldKey(dir, id) {
1213
- const link = readJson(linkOf(dir, id ?? MAIN));
1503
+ /** The snapshot a slot holds; none throws what to do. */
1504
+ function heldKey(dir, slot) {
1505
+ const link = readJson(linkOf(dir, slot));
1214
1506
  const key = KEY_RE.test(link?.snap ?? '') && !link.released ? link.snap : null;
1215
1507
  if (key && existsSync(snapOf(dir, key)) && existsSync(snapFactsOf(dir, key))) return key;
1508
+ const which = `--of ${slot.build}${slot.profile === 'debug' ? '' : ` --profile ${slot.profile}`}`;
1509
+ const arg = slot.who === MAIN ? '--main' : slot.who;
1216
1510
  throw new Error(
1217
- id
1218
- ? `${id} has no build: ai-factory gcf playtest build ${id}`
1219
- : 'main has no build: ai-factory gcf playtest build --main',
1511
+ `${nameOf(slot.who)} has no build of ${slot.build} ${slot.profile}: ` +
1512
+ `ai-factory gcf playtest build ${arg} ${which}`,
1220
1513
  );
1221
1514
  }
1222
1515
 
@@ -1227,13 +1520,14 @@ const NO_FACTS = {
1227
1520
  source: null,
1228
1521
  dirty: false,
1229
1522
  dirtied: [],
1523
+ in_tree: false,
1230
1524
  size: null,
1231
1525
  shared_with: [],
1232
1526
  };
1233
1527
 
1234
1528
  /**
1235
- * Why the card's last attempt gave no build, or null. One marked as going by a process now gone was
1236
- * taken by a stop or a crash, and could not say so.
1529
+ * Why the slot's last attempt gave no build, or null. One marked as going by a process now gone
1530
+ * was taken by a stop or a crash, and could not say so.
1237
1531
  */
1238
1532
  function attemptProblem(attempt, going) {
1239
1533
  if (going) return attempt.problem ?? null;
@@ -1244,44 +1538,60 @@ function attemptProblem(attempt, going) {
1244
1538
  }
1245
1539
 
1246
1540
  /**
1247
- * A holder's snapshot and its attempt, read only. `shared_with`: the other cards that hold the
1248
- * same snapshot (d27).
1541
+ * A slot's snapshot and its attempt, read only, or null when it has neither. `shared_with`: the
1542
+ * other cards that hold the same snapshot (d27). `cold`: a build going in a build folder made for
1543
+ * it, so it builds a project's caches from nothing.
1249
1544
  */
1250
- function heldBuild(dir, who, links) {
1251
- const link = links.get(who);
1545
+ function heldBuild(dir, slot, links) {
1546
+ const mine = slotKey(slot);
1547
+ const link = links.get(mine);
1252
1548
  const key = link && link !== UNREAD && !link.released ? link.snap : null;
1253
1549
  const facts = key && existsSync(snapOf(dir, key)) ? readJson(snapFactsOf(dir, key)) : null;
1254
- const attempt = readJson(attemptOf(dir, who));
1550
+ const attempt = readJson(attemptOf(dir, slot));
1255
1551
  const going = building(attempt);
1256
1552
  const problem = attemptProblem(attempt, going);
1257
1553
  if (!facts && !going && !problem) return null;
1258
1554
  const shared = [...links]
1259
- .filter(([w, l]) => facts && w !== who && w !== MAIN && l !== UNREAD && holds(l, key))
1260
- .map(([w]) => w)
1261
- .sort();
1555
+ .filter(
1556
+ ([k, l]) => facts && k !== mine && whoOfKey(k) !== MAIN && l !== UNREAD && holds(l, key),
1557
+ )
1558
+ .map(([k]) => whoOfKey(k));
1262
1559
 
1263
1560
  return {
1264
1561
  ...NO_FACTS,
1265
1562
  ...facts,
1266
- ...(facts ? { key, source: link.source ?? null, shared_with: shared } : {}),
1563
+ build: slot.build,
1564
+ profile: slot.profile,
1565
+ ...(facts
1566
+ ? { key, source: link.source ?? null, shared_with: [...new Set(shared)].sort() }
1567
+ : {}),
1267
1568
  ok: Boolean(facts),
1268
1569
  building: going,
1570
+ cold: going && attempt.cold === true,
1269
1571
  problem,
1270
1572
  };
1271
1573
  }
1272
1574
 
1273
1575
  /**
1274
- * What a board and a chat show of the card: its snapshot, or the attempt under way or failed.
1275
- * `links`: linksOf once for a whole board.
1576
+ * What a board and a chat show of a card (`id`; MAIN: the checkout): each build and profile it has
1577
+ * a snapshot or an attempt of, by build then profile (docs/Handoff-Plan.md t17). A card back at
1578
+ * work has none to offer, unless one goes for it in its worktree right now. `links`: linksOf once
1579
+ * for a whole board.
1580
+ * @returns {Array<Record<string, any>>}
1276
1581
  */
1277
- export function buildOf(projectDir, id, status, links = linksOf(projectDir)) {
1582
+ export function itemBuilds(projectDir, id, status, links = linksOf(projectDir)) {
1278
1583
  const dir = path.resolve(projectDir);
1279
- // A card back at work has no build to offer, unless one goes for it in its worktree right now.
1280
- if (status === 'ready' && !building(readJson(attemptOf(dir, id)))) return null;
1281
1584
 
1282
- return heldBuild(dir, id, links);
1585
+ return slotsOf(dir, id)
1586
+ .filter((s) => status !== 'ready' || building(readJson(attemptOf(dir, s))))
1587
+ .map((s) => heldBuild(dir, s, links))
1588
+ .filter(Boolean)
1589
+ .sort((a, b) => a.build.localeCompare(b.build) || a.profile.localeCompare(b.profile));
1283
1590
  }
1284
1591
 
1592
+ /** The checkout's builds ("Play main"), as `itemBuilds` gives a card's. */
1593
+ export const mainBuilds = (projectDir, links) => itemBuilds(projectDir, MAIN, null, links);
1594
+
1285
1595
  /** The build tickets in their order, as a board shows them (lib/build-queue.js). */
1286
1596
  export const queueOf = (dir) =>
1287
1597
  ticketsOf(dir).map((t) => ({
@@ -1294,17 +1604,18 @@ export const queueOf = (dir) =>
1294
1604
  }));
1295
1605
 
1296
1606
  /**
1297
- * How the project plays, read only: its `play:` whole (d26), the checkout's snapshot (d30) and the
1298
- * running player; null with no `play:`.
1607
+ * How the project plays, read only: its `play:` whole (d26), the checkout's snapshots (d30) and
1608
+ * the running player; null with no `play:`. Board schema 5: builds by name with their profiles,
1609
+ * `main` a list like a card's `builds`.
1299
1610
  */
1300
1611
  export function playFacts(projectDir, config) {
1301
1612
  let play;
1302
1613
  try {
1303
1614
  play = playOf(config);
1304
1615
  } catch (e) {
1305
- const none = { build: null, output: null, builds: [], auto_build: null, targets: [] };
1616
+ const none = { builds: [], auto_build: null, targets: [], warnings: [], main: [] };
1306
1617
 
1307
- return { problem: e.message, ...none, warnings: [], main: null, running: null, queue: [] };
1618
+ return { problem: e.message, ...none, running: null, queue: [] };
1308
1619
  }
1309
1620
 
1310
1621
  if (!play) return null;
@@ -1313,8 +1624,6 @@ export function playFacts(projectDir, config) {
1313
1624
 
1314
1625
  return {
1315
1626
  problem: null,
1316
- build: play.build,
1317
- output: play.output,
1318
1627
  builds: Object.entries(play.builds).map(([name, b]) => ({ name, ...b })),
1319
1628
  auto_build: play.auto_build,
1320
1629
  warnings: play.warnings,
@@ -1328,7 +1637,7 @@ export function playFacts(projectDir, config) {
1328
1637
  devices: t.devices ?? null,
1329
1638
  launches: t.launches === true,
1330
1639
  })),
1331
- main: heldBuild(dir, MAIN, linksOf(dir)),
1640
+ main: mainBuilds(dir, linksOf(dir)),
1332
1641
  queue: queueOf(dir),
1333
1642
  running: p
1334
1643
  ? {
@@ -1336,6 +1645,8 @@ export function playFacts(projectDir, config) {
1336
1645
  main: p.main === true,
1337
1646
  snap: p.snap ?? null,
1338
1647
  target: p.target,
1648
+ build: p.build ?? null,
1649
+ profile: p.profile ?? null,
1339
1650
  open: p.open,
1340
1651
  url: p.url,
1341
1652
  started: p.started,
@@ -1355,62 +1666,114 @@ export async function playStatus(projectDir) {
1355
1666
  return playFacts(dir, await readConfig(path.join(dir, 'gcf')));
1356
1667
  }
1357
1668
 
1358
- const TARGET_FIELDS = ['start', 'words', 'stop', 'for', 'devices', 'launches'];
1669
+ const TARGET_FIELDS = ['start', 'words', 'stop', 'for', 'devices', 'launches', 'targetBuild'];
1670
+ const BUILD_FIELDS = ['build', 'output', 'playsOn', 'profile'];
1671
+
1672
+ /** The names a setup gives: each one word. */
1673
+ function needNames(o) {
1674
+ for (const [what, name] of [
1675
+ ["a target's", o.target],
1676
+ ["a build's", o.of],
1677
+ ["a build's", o.autoBuild],
1678
+ ["a build's", o.targetBuild],
1679
+ ["a build's", o.removeBuild],
1680
+ ])
1681
+ if (name !== undefined && !NAME_RE.test(name))
1682
+ throw new Error(`${what} name is one word: ${name}`);
1683
+ }
1359
1684
 
1360
1685
  /** What a setup may not be: checked before anything is written. */
1361
1686
  function needSetup(dir, o) {
1362
- if (o.target !== undefined && !NAME_RE.test(o.target))
1363
- throw new Error(`a target's name is one word: ${o.target}`);
1687
+ needNames(o);
1364
1688
  if (o.target === undefined && TARGET_FIELDS.some((k) => o[k] !== undefined))
1365
1689
  throw new Error(
1366
- '--start, --open, --stop, --for, --devices and --launches belong to a --target',
1690
+ '--start, --open, --stop, --for, --devices, --launches, --target-build belong to a --target',
1367
1691
  );
1692
+ if (o.profile !== undefined && !PROFILES.includes(o.profile))
1693
+ throw new Error(`a profile is debug or release: ${o.profile}`);
1694
+ if (o.profile !== undefined && o.build === undefined)
1695
+ throw new Error('--profile names whose command --build gives');
1368
1696
  // Now, not at the first build minutes later (d21).
1369
1697
  if (o.output !== undefined) needOutput(o.output);
1370
1698
  if (o.output !== undefined && !ignored(dir, o.output))
1371
- throw new Error(`play.output ${o.output} is not ignored by git: add it to .gitignore`);
1699
+ throw new Error(`play output ${o.output} is not ignored by git: add it to .gitignore`);
1372
1700
  }
1373
1701
 
1374
- /**
1375
- * Where `--build`, `--output` and `--plays-on` go (docs/Handoff-Plan.md d2): into the one build of
1376
- * `builds:`, whatever its name; else into the old `build:` and `output:`, which `--plays-on` turns
1377
- * into `builds.default`.
1378
- */
1379
- function buildPath(doc, playsOn) {
1380
- const old = doc.toJS().play ?? {};
1381
- const names = isMap(old.builds) ? Object.keys(old.builds) : null;
1382
- if (names?.length === 1) return ['play', 'builds', names[0]];
1383
- // Several builds: the one to set is named with step 2; playOf refuses play.build beside them.
1384
- if (playsOn === undefined || old.builds !== undefined) return ['play'];
1702
+ /** The old `build:`, `output:` moved into `builds.default`. */
1703
+ function intoBuilds(doc, old) {
1385
1704
  doc.setIn(
1386
1705
  ['play', 'builds'],
1387
1706
  doc.createNode({ default: { build: old.build, output: old.output } }),
1388
1707
  );
1389
1708
  doc.deleteIn(['play', 'build']);
1390
1709
  doc.deleteIn(['play', 'output']);
1710
+ }
1711
+
1712
+ /**
1713
+ * Where `--build`, `--output`, `--plays-on` and `--profile` go: into the build `--of` names (the
1714
+ * old form becomes `builds.default` first); else into the one build of `builds:`, whatever its name
1715
+ * (docs/Handoff-Plan.md d2); else into the old `build:` and `output:`, which `--plays-on` turns
1716
+ * into `builds.default`. Several builds and no `--of` refuse.
1717
+ */
1718
+ function buildPath(doc, o) {
1719
+ const old = doc.toJS().play ?? {};
1720
+ const names = isMap(old.builds) ? Object.keys(old.builds) : null;
1721
+ if (o.of !== undefined) return namedBuild(doc, o.of, old, names);
1722
+ if (names?.length === 1) return ['play', 'builds', names[0]];
1723
+ if (names && names.length > 1 && BUILD_FIELDS.some((k) => o[k] !== undefined))
1724
+ throw new Error(`several builds (${names.join(', ')}): name the one to set with --of`);
1725
+ if (o.playsOn === undefined || names) return ['play'];
1726
+ intoBuilds(doc, old);
1391
1727
 
1392
1728
  return ['play', 'builds', 'default'];
1393
1729
  }
1394
1730
 
1731
+ /** The build `--of` names, made when it is new; the old form becomes `builds.default` first. */
1732
+ function namedBuild(doc, name, old, names) {
1733
+ if (!names && (old.build !== undefined || old.output !== undefined)) intoBuilds(doc, old);
1734
+ mapAt(doc, ['play', 'builds']);
1735
+ mapAt(doc, ['play', 'builds', name]);
1736
+
1737
+ return ['play', 'builds', name];
1738
+ }
1739
+
1395
1740
  const mapAt = (doc, keys) => {
1396
1741
  if (!YAML.isMap(doc.getIn(keys, true))) doc.setIn(keys, doc.createNode({}));
1397
1742
  };
1398
1743
 
1744
+ /**
1745
+ * A build's command: one for all (no `--profile`; a build by profile gets it as debug), or the
1746
+ * profile's, which turns one command into `{debug: <it>}` first (docs/Handoff-Plan.md t18).
1747
+ */
1748
+ function setCommand(doc, at, cmd, profile) {
1749
+ const keys = [...at, 'build'];
1750
+ const byProfile = YAML.isMap(doc.getIn(keys, true));
1751
+ if (profile === undefined) return doc.setIn(byProfile ? [...keys, 'debug'] : keys, cmd);
1752
+ if (!byProfile) {
1753
+ const one = doc.getIn(keys);
1754
+ doc.setIn(keys, doc.createNode(one === undefined ? {} : { debug: one }));
1755
+ }
1756
+
1757
+ doc.setIn([...keys, profile], cmd);
1758
+ }
1759
+
1399
1760
  /** config.yml's text with `play:` changed as given; what is not given stays. */
1400
1761
  function playDoc(text, o) {
1401
1762
  const doc = configDoc(text);
1402
1763
  mapAt(doc, ['play']);
1403
- const at = buildPath(doc, o.playsOn);
1404
1764
  const set = (keys, v) => v !== undefined && doc.setIn(keys, doc.createNode(v));
1405
- set([...at, 'build'], o.build);
1765
+ if (o.removeBuild !== undefined) doc.deleteIn(['play', 'builds', o.removeBuild]);
1766
+ const at = buildPath(doc, o);
1767
+ if (o.build !== undefined) setCommand(doc, at, o.build, o.profile);
1406
1768
  set([...at, 'output'], o.output);
1407
1769
  set([...at, 'plays_on'], o.playsOn);
1770
+ set(['play', 'auto_build'], o.autoBuild);
1408
1771
  if (o.target !== undefined) {
1409
1772
  const t = ['play', 'targets', o.target];
1410
1773
  mapAt(doc, ['play', 'targets']);
1411
1774
  mapAt(doc, t);
1412
- for (const [k, field] of [['start'], ['words', 'open'], ['stop'], ['for'], ['devices']])
1413
- set([...t, field ?? k], o[k]);
1775
+ const fields = [['start'], ['words', 'open'], ['stop'], ['for'], ['devices']];
1776
+ for (const [k, field] of [...fields, ['targetBuild', 'build']]) set([...t, field ?? k], o[k]);
1414
1777
  if (o.launches !== undefined) doc.setIn([...t, 'launches'], o.launches);
1415
1778
  }
1416
1779
 
@@ -1422,9 +1785,10 @@ function playDoc(text, o) {
1422
1785
  /**
1423
1786
  * `gcf playtest setup`: how the project builds and starts its game, committed as `gcf(config)`.
1424
1787
  * Only what is given changes. Checked as a whole before it is written.
1425
- * @param {{build?: string, output?: string, playsOn?: object[], target?: string, start?: string,
1426
- * open?: string, stop?: string, for?: object, devices?: string, launches?: boolean,
1427
- * removeTarget?: string, commit?: boolean}} opts
1788
+ * @param {{of?: string, build?: string, profile?: string, output?: string, playsOn?: object[],
1789
+ * autoBuild?: string, removeBuild?: string, target?: string, targetBuild?: string,
1790
+ * start?: string, open?: string, stop?: string, for?: object, devices?: string,
1791
+ * launches?: boolean, removeTarget?: string, commit?: boolean}} opts
1428
1792
  */
1429
1793
  export async function setupPlay(projectDir, opts) {
1430
1794
  const dir = path.resolve(projectDir);
@@ -1463,9 +1827,10 @@ const WAITER_START_MS = 90000;
1463
1827
  /** Do ticket `n`'s job: a build, or a build then a start (d9). */
1464
1828
  function jobOf(dir, job, n) {
1465
1829
  if (job.start) return startPlay(dir, job.build, job.start.target, { ...job.start, ticket: n });
1466
- if (job.build === null) return buildMain(dir, { fresh: job.fresh, ticket: n });
1830
+ const o = { fresh: job.fresh, ticket: n, of: job.of ?? null, profile: job.profile ?? null };
1831
+ if (job.build === null) return buildMain(dir, o);
1467
1832
 
1468
- return buildItem(dir, job.build, { from: job.from ?? null, fresh: job.fresh, ticket: n });
1833
+ return buildItem(dir, job.build, { ...o, from: job.from ?? null });
1469
1834
  }
1470
1835
 
1471
1836
  /**
@@ -1491,23 +1856,32 @@ export async function runTicket(projectDir, n) {
1491
1856
  return outcome;
1492
1857
  }
1493
1858
 
1859
+ /** A job with its build and profile named, and whether it needs the checkout. */
1860
+ async function fullJob(dir, play, job, item) {
1861
+ const spec = job.start
1862
+ ? specOf(play, targetOf(play, job.start.target).build, job.start.profile ?? 'debug')
1863
+ : specFor(play, item, job);
1864
+ const free = job.build !== null && !job.from && (await freeOfCheckout(dir, job.build, item));
1865
+ const start = job.start ? { start: { ...job.start, profile: spec.profile } } : {};
1866
+
1867
+ return { ...job, of: spec.name, profile: spec.profile, free, ...start };
1868
+ }
1869
+
1494
1870
  /**
1495
1871
  * `--queue` (docs/Handoff-Plan.md d6): the ticket, and its waiter started cut loose from this
1496
1872
  * process; the ticket's number at once. What the job cannot be is refused here, not in the waiter.
1497
- * @param {{build: string | null, from?: string | null, fresh?: boolean, start?: {target: string}}}
1498
- * job
1873
+ * The ticket names its build and profile; `free` tells a main run that it needs no checkout.
1874
+ * @param {{build: string | null, of?: string | null, profile?: string | null,
1875
+ * from?: string | null, fresh?: boolean, start?: {target: string, profile?: string | null}}} job
1499
1876
  */
1500
1877
  export async function queueJob(projectDir, job) {
1501
1878
  const dir = path.resolve(projectDir);
1502
1879
  const play = await projectPlay(dir);
1503
- if (job.start) targetOf(play, job.start.target);
1504
- if (job.build !== null) {
1505
- needId(job.build);
1506
- const problem = await statusProblem(dir, job.build, job.from ?? null);
1507
- if (problem) throw new Error(problem);
1508
- }
1509
-
1510
- const n = await ticketOpen(dir, job);
1880
+ if (job.build !== null) needId(job.build);
1881
+ const item = job.build === null ? null : await itemIn(dir, job.build);
1882
+ const problem = job.build === null ? null : problemOf(item, job.build, job.from ?? null);
1883
+ if (problem) throw new Error(problem);
1884
+ const n = await ticketOpen(dir, await fullJob(dir, play, job, item));
1511
1885
  // Not the run's: a waiter that inherited a run's owner would build past its own ticket.
1512
1886
  const { GCF_RUN_OWNER: _owner, ...env } = process.env;
1513
1887
  const child = spawn(process.execPath, [WAITER, dir, String(n)], {