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