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/README.md CHANGED
@@ -345,8 +345,8 @@ The run layer of the methodology. Update both extensions together — `gcf-harne
345
345
  - `gcf phase` and `gcf phase next [--reason]` — the project phase (prototype → vertical-slice → alpha → beta → release → live), kept as `phase:` in the `LIVE.md` frontmatter, with exit criteria checked in code. `item new` and `take` refuse a type the phase does not take. **A project with no phase yet is in prototype, and a prototype takes no `asset` item**: move the phase on (`gcf phase next --reason "…"`) if your game is past it. A `phases:` list in `config.yml` replaces the set.
346
346
  - A release item carries `version:` and `channel:` (`item new <id> --type release --release 1.0.0 --channel steam`); its end writes the `release:` block of `LIVE.md`. `item new --milestone <name>` tags an item with a milestone of `game.md` (any slug without `game.md`); `design check` reports (does not block) an item whose milestone `game.md` does not list, and the board read gives the list as `design.milestones`.
347
347
  - `gcf playtest session` — where main stands and a checklist per item: its build, what to check, how to get there, what to feel.
348
- - `gcf playtest build <id> [--from <worktree>] [--fresh]`, `build --main [--fresh]`, `start <id>|--main --target <name>`, `stop`, `status`, `setup` — one build per code under `.gcf-session/snaps/<key>/`, held by a card's link `.gcf-session/builds/<id>.json` or the checkout's `snaps/main.link.json`, and its player, from `play:` in `gcf/config.yml`; a verdict stops the card's player and removes the build once no other card holds it. `setup` refuses an output git does not ignore. On Windows the project's commands (`play:`, `dod.*`) run with Git's `bin` first in PATH, so `bash` is Git's, not System32's WSL launcher. The deny group `run-play` keeps a run's agent from building; a chat thread may build on the human's ask.
349
- - `gcf playtest build <id> --wait|--queue`, `start <id> --target <t> [--device <id>] --wait|--queue`, `cancel <ticket>`, `devices <target>` — a build while a run works in the checkout waits on a ticket `.gcf-session/runs/.build-<n>.json` instead of a refusal; a main run lets it in between its cards by `.gcf-session/.main-run.yield`; `--queue` starts its own waiter and prints `{ticket}`; `cancel` takes a waiting ticket out or stops a build. `play.builds` names the project's builds (one in this release), each with its `plays_on` rows; a target names its `build`, the rows it serves (`for`), its `devices` script and `launches`
348
+ - `gcf playtest build <id> [--from <worktree>] [--fresh]`, `build --main [--fresh]`, `start <id>|--main --target <name>`, `stop`, `status`, `setup` — one build per code under `.gcf-session/snaps/<key>/`, held by a card's link `.gcf-session/builds/<id>.<build>.<profile>.json` or the checkout's `snaps/main.<build>.<profile>.link.json`, and its player, from `play:` in `gcf/config.yml`; a verdict stops the card's player and removes the build once no other card holds it. `setup` refuses an output git does not ignore. On Windows the project's commands (`play:`, `dod.*`) run with Git's `bin` first in PATH, so `bash` is Git's, not System32's WSL launcher. The deny group `run-play` keeps a run's agent from building; a chat thread may build on the human's ask.
349
+ - `gcf playtest build <id> --wait|--queue`, `start <id> --target <t> [--device <id>] --wait|--queue`, `cancel <ticket>`, `devices <target>` — a build while a run works in the checkout waits on a ticket `.gcf-session/runs/.build-<n>.json` instead of a refusal; a main run lets it in between its cards by `.gcf-session/.main-run.yield`; `--queue` starts its own waiter and prints `{ticket}`; `cancel` takes a waiting ticket out or stops a build. `play.builds` names the project's builds, each with one command or `{debug, release}` and its `plays_on` rows; `--of <build>` and `--profile release` pick one (else the card's build: `play.auto_build` when its `play_on` names it or none, else the first it names, in debug); a card whose code has left HEAD builds in `.gcf-session/buildtree` at its own commit; `setup --of <build> [--profile release] --build <cmd>`, `--auto-build`, `--remove-build`, a target's `--target-build`; a target names its `build`, the rows it serves (`for`), its `devices` script and `launches`
350
350
  - `gcf play-notes <id> [--template]`, `gcf item show <id>` — the agent's `## Play notes` in a card's plan, and the handoff the core reads from it and the card: outcome, main question, Play by platform, what changed, what to try, what waits; also `items[].handoff` of `gcf board --json`
351
351
  - `gcf worktree <id>`, `gcf verify <id> --mark`, `gcf integrate [<id>…]` — an item in its own worktree, the `GCF-Verified` trailer, the merge into main and the item's move. Every committed move now holds `.gcf-session/main.lock`.
352
352
  - `gcf board [--json]` — everything a board shows in one read.
package/commands/gcf.js CHANGED
@@ -377,13 +377,15 @@ function registerAudit(gcf) {
377
377
  });
378
378
  }
379
379
 
380
- /** An item's build on the sheet: its commit, what goes on, why it failed. */
381
- function buildLine(b) {
382
- if (!b) return [];
383
- if (b.building) return [' build: being built'];
384
- if (b.ok) return [` build: ${b.commit ?? 'no commit'}, ${b.source}, ${b.built_at}`];
385
-
386
- return [` build failed: ${b.problem.split('\n')[0]}`];
380
+ /** An item's builds on the sheet: each one's commit, what goes on, why it failed. */
381
+ function buildLines(builds) {
382
+ return (builds ?? []).map((b) => {
383
+ const which = `${b.build} ${b.profile}`;
384
+ if (b.building) return ` build ${which}: being built`;
385
+ if (b.ok) return ` build ${which}: ${b.commit ?? 'no commit'}, ${b.source}, ${b.built_at}`;
386
+
387
+ return ` build ${which} failed: ${b.problem.split('\n')[0]}`;
388
+ });
387
389
  }
388
390
 
389
391
  /** The sheet's head: where main stands, and why the checkout may not be main. */
@@ -403,7 +405,7 @@ function itemLines(c, linesOf) {
403
405
  if (c.handoff && linesOf) return linesOf(c.id, c.handoff).map((l) => ` ${l}`);
404
406
 
405
407
  return [
406
- ...buildLine(c.build),
408
+ ...buildLines(c.builds),
407
409
  ` check: ${c.question}`,
408
410
  ...(c.play_on?.length ? [` play on: ${c.play_on.join('; ')}`] : []),
409
411
  ...c.reach.map((r) => ` try: ${r}`),
@@ -522,7 +524,9 @@ const ticketLine = (q) => {
522
524
  const then = q.job.start ? ` then ${q.job.start.target}` : '';
523
525
  const state = q.building ? 'building' : q.after ? `waits after ${q.after}` : 'waits';
524
526
 
525
- return `ticket ${q.ticket}: ${q.job.build ?? 'main'}${then}, ${state}`;
527
+ const which = q.job.of ? ` ${q.job.of} ${q.job.profile ?? 'debug'}` : '';
528
+
529
+ return `ticket ${q.ticket}: ${q.job.build ?? 'main'}${which}${then}, ${state}`;
526
530
  };
527
531
 
528
532
  /** The player's line and the targets of `playtest status`. */
@@ -547,6 +551,8 @@ function registerPlayBuild(playtest, jsonOf) {
547
551
  .option('--main', 'the checkout with its uncommitted edits, not a card')
548
552
  .option('--fresh', 'build even when a snapshot of this code is there, and replace it')
549
553
  .option('--from <worktree>', "the card's worktree, for a run whose code is not in main yet")
554
+ .option('--of <build>', "which build of play.builds: else the card's own, else auto_build")
555
+ .option('--profile <profile>', 'debug (the default) or release')
550
556
  .option('--wait', 'a busy checkout is waited for on a ticket, in this process')
551
557
  .option('--queue', 'a ticket and its own waiter: prints {ticket} and ends at once')
552
558
  .option('--json', 'machine output')
@@ -555,8 +561,9 @@ function registerPlayBuild(playtest, jsonOf) {
555
561
  const fresh = Boolean(o.fresh);
556
562
  const main = oneOf(id, o.main);
557
563
  if (main && o.from) throw new Error("--from names a card's worktree: not with --main");
564
+ const which = { of: o.of ?? null, profile: o.profile ?? null };
558
565
  if (o.queue) {
559
- const job = { build: main ? null : id, from: o.from ?? null, fresh };
566
+ const job = { build: main ? null : id, from: o.from ?? null, fresh, ...which };
560
567
  const q = await play.queueJob(process.cwd(), job);
561
568
 
562
569
  return out(jsonOf(o), q, (x) => `ticket ${x.ticket}: the build waits its turn`);
@@ -564,9 +571,9 @@ function registerPlayBuild(playtest, jsonOf) {
564
571
 
565
572
  const wait = Boolean(o.wait);
566
573
  const r = main
567
- ? await play.buildMain(process.cwd(), { fresh, wait })
568
- : await play.buildItem(process.cwd(), id, { from: o.from ?? null, fresh, wait });
569
- const who = id ?? 'main';
574
+ ? await play.buildMain(process.cwd(), { fresh, wait, ...which })
575
+ : await play.buildItem(process.cwd(), id, { from: o.from ?? null, fresh, wait, ...which });
576
+ const who = `${id ?? 'main'} ${r.build} ${r.profile}`;
570
577
  out(jsonOf(o), r, (b) =>
571
578
  b.ok
572
579
  ? `built ${who} at ${b.commit?.slice(0, 7) ?? 'no commit'}, ${b.size} bytes` +
@@ -581,20 +588,22 @@ function registerPlayBuild(playtest, jsonOf) {
581
588
  .option('--main', "the checkout's snapshot, not a card's")
582
589
  .requiredOption('--target <name>', 'a target of play.targets')
583
590
  .option('--device <id>', "a device of the target's devices answer: {device} in its commands")
591
+ .option('--profile <profile>', "the target's build in debug (the default) or release")
584
592
  .option('--wait', 'no build yet: build it on a ticket first, then start (this process waits)')
585
593
  .option('--queue', 'no build yet: a ticket and its own waiter; prints {ticket} at once')
586
594
  .option('--json', 'machine output')
587
595
  .action(async (id, o) => {
588
596
  const play = await lib('play');
589
597
  const who = oneOf(id, o.main) ? null : id;
590
- if (o.queue && !play.hasBuildOf(process.cwd(), who)) {
591
- const start = { target: o.target, device: o.device ?? null };
598
+ const profile = o.profile ?? null;
599
+ if (o.queue && !(await play.hasBuildOf(process.cwd(), who, o.target, profile))) {
600
+ const start = { target: o.target, device: o.device ?? null, profile };
592
601
  const q = await play.queueJob(process.cwd(), { build: who, start });
593
602
 
594
603
  return out(jsonOf(o), q, (x) => `ticket ${x.ticket}: the build waits, the start after it`);
595
604
  }
596
605
 
597
- const how = { wait: Boolean(o.wait), device: o.device ?? null };
606
+ const how = { wait: Boolean(o.wait), device: o.device ?? null, profile };
598
607
  const r = await play.startPlay(process.cwd(), who, o.target, how);
599
608
  out(jsonOf(o), r, startLine);
600
609
  });
@@ -650,9 +659,14 @@ function registerPlay(playtest) {
650
659
  playtest
651
660
  .command('setup')
652
661
  .description("How the project builds and starts its game (play: in config.yml; the operator's)")
662
+ .option('--of <build>', 'the build the next options set (a new name adds one)')
653
663
  .option('--build <cmd>', 'the command that builds the game')
664
+ .option('--profile <profile>', 'whose command --build gives: debug or release')
654
665
  .option('--output <folder>', 'where it builds to: inside the project, ignored by git')
655
- .option('--target <name>', 'the target the next three options set')
666
+ .option('--auto-build <build>', "the build a run's card gets when its play_on names none")
667
+ .option('--remove-build <build>', 'take a build away')
668
+ .option('--target <name>', 'the target the next options set')
669
+ .option('--target-build <build>', 'the build the target plays')
656
670
  .option('--start <cmd>', 'starts the game: {dir} the snapshot, {port} a free port, {lan}')
657
671
  .option('--open <text>', 'what to open: a URL or words, with the same placeholders')
658
672
  .option('--stop <cmd>', 'runs after the player stops')
@@ -671,7 +685,10 @@ function registerPlay(playtest) {
671
685
  .action(async (o) => {
672
686
  await operatorOnly('playtest setup');
673
687
  const r = await (await lib('play')).setupPlay(process.cwd(), { ...o, open: o.open });
674
- console.log(`play: ${r.play.build} into ${r.play.output}${shortHash(r.hash)}`);
688
+ const builds = Object.entries(r.play.builds).map(
689
+ ([n, b]) => `${n} (${Object.keys(b.profiles).join(', ')}) into ${b.output}`,
690
+ );
691
+ console.log(`play: ${builds.join('; ')}${shortHash(r.hash)}`);
675
692
  for (const w of r.play.warnings) console.log(`warning: ${w}`);
676
693
  });
677
694
  }
package/extension.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
3
3
  "name": "gcf-aif-ext",
4
- "version": "0.28.0",
4
+ "version": "0.29.1",
5
5
  "description": "Game Context Framework for AI Factory",
6
6
  "skills": [
7
7
  "skills/gcf-init",
@@ -102,7 +102,7 @@ const sameRule = (a, b) => a?.kind === b?.kind && a?.pattern === b?.pattern;
102
102
  const shell = (...patterns) => patterns.map((pattern) => ({ kind: 'shell', pattern }));
103
103
  const files = (kind, ...globs) => globs.map((pattern) => ({ kind, pattern }));
104
104
 
105
- /** @type {{ id: string, label: string, on: boolean, rules: Rule[] }[]} */
105
+ /** @type {{ id: string, label: string, on: boolean, run_only?: boolean, rules: Rule[] }[]} */
106
106
  export const DENY_GROUPS = [
107
107
  {
108
108
  id: 'git-history',
package/lib/board.js CHANGED
@@ -27,12 +27,12 @@ import { designCheck, designUnits } from './design-check.js';
27
27
  import { designState } from './design-parts.js';
28
28
  import { gatePolicy } from './gates.js';
29
29
  import { milestoneState } from './milestone-state.js';
30
- import { buildOf, linksOf, playFacts } from './play.js';
30
+ import { itemBuilds, linksOf, playFacts } from './play.js';
31
31
  import { handoffOf } from './handoff.js';
32
32
 
33
33
  // The version of the JSON below (Methodology §11): a board refuses one it does not know. Bump it
34
34
  // when a field changes meaning or goes away; a new field does not bump it.
35
- export const BOARD_SCHEMA = 4;
35
+ export const BOARD_SCHEMA = 5;
36
36
 
37
37
  /**
38
38
  * Plan progress `{tasks, done}` from its checkboxes and the plan's project path, both null
@@ -330,7 +330,7 @@ async function handoffPart(projectDir, id, read) {
330
330
  }
331
331
 
332
332
  async function itemOf(projectDir, c, { verified, shelved, ledger, harness, config, links }) {
333
- const build = buildOf(projectDir, String(c.data.id), c.data.status, links);
333
+ const builds = itemBuilds(projectDir, String(c.data.id), c.data.status, links);
334
334
  const id = String(c.data.id);
335
335
  // A trailer counts only while the item waits on main for its integrate.
336
336
  const ready = c.data.status === 'ready' && verified.has(id);
@@ -372,13 +372,13 @@ async function itemOf(projectDir, c, { verified, shelved, ledger, harness, confi
372
372
  running,
373
373
  verified: ready,
374
374
  harness,
375
- building: Boolean(build?.building),
375
+ building: builds.some((b) => b.building),
376
376
  }),
377
377
  file: `gcf/work/${c.name}`,
378
378
  ...(await attachmentsOf(projectDir, id)),
379
379
  log: logOf(projectDir, id),
380
- // Its build to play (docs/Play-Setup-Plan.md), null while it has none.
381
- build,
380
+ // Its builds to play, one per build and profile it has (docs/Handoff-Plan.md t17, schema 5).
381
+ builds,
382
382
  // What a card that waits hands to the operator (docs/Handoff-Plan.md d4): read from its plan.
383
383
  ...(await handoffPart(projectDir, id, { ledger, config, links })),
384
384
  // Filled by board() from the inbox.
@@ -55,7 +55,7 @@ export function ticketsOf(projectDir) {
55
55
 
56
56
  return readdirSync(runsOf(dir))
57
57
  .map((name) => TICKET_RE.exec(name))
58
- .filter(Boolean)
58
+ .filter((m) => m !== null)
59
59
  .map((m) => readTicket(dir, Number(m[1])))
60
60
  .filter((t) => t && alive(t.pid))
61
61
  .sort((a, b) => a.n - b.n);
@@ -92,7 +92,10 @@ export function ticketSet(dir, n, fields) {
92
92
  return t;
93
93
  }
94
94
 
95
- /** The ticket goes with what its waiter ended with; a yield naming it lets its run go on. */
95
+ /**
96
+ * The ticket goes with what its waiter ended with; a yield naming it lets its run go on.
97
+ * @param {Record<string, unknown> | null} [outcome]
98
+ */
96
99
  export function ticketClose(projectDir, n, outcome = null) {
97
100
  const dir = path.resolve(projectDir);
98
101
  if (outcome) writeJson(outcomeFile(dir, n), { n, at: new Date().toISOString(), ...outcome });
@@ -128,13 +131,13 @@ function byYield(dir, n) {
128
131
 
129
132
  /**
130
133
  * Enter the checkout for ticket `n` under the main lock: by the run's yield that names this ticket
131
- * while that run lives, or by a claim when nobody holds it. `from`: a worktree build needs no
132
- * checkout, only its turn. Null: not yet.
134
+ * while that run lives, or by a claim when nobody holds it. `free`: a worktree build, or one in
135
+ * the build folder of a worktree project, needs no checkout, only its turn. Null: not yet.
133
136
  * @returns {Promise<null | 'gone' | {release: (() => Promise<void>) | null, yielded: boolean}>}
134
137
  */
135
- async function entered(dir, n, from) {
138
+ async function entered(dir, n, free) {
136
139
  if (ticketsOf(dir)[0]?.n !== n) return null;
137
- if (from) return { release: null, yielded: false };
140
+ if (free) return { release: null, yielded: false };
138
141
  const yielded = byYield(dir, n);
139
142
  if (yielded) return yielded;
140
143
  dropDeadYield(dir);
@@ -148,10 +151,10 @@ async function entered(dir, n, from) {
148
151
  * is marked `building` before a cancel can see it waiting; one still waiting names what it waits
149
152
  * behind. Its file is written only here and by a cancel, so a cancel's removal stays.
150
153
  */
151
- async function enter(dir, n, from) {
154
+ async function enter(dir, n, free) {
152
155
  return withMainLock(dir, async () => {
153
156
  if (cancelled(dir, n)) return 'gone';
154
- const got = await entered(dir, n, from);
157
+ const got = await entered(dir, n, free);
155
158
  const after = got ? null : aheadOf(dir, n);
156
159
  if (got || readTicket(dir, n)?.after !== after)
157
160
  ticketSet(dir, n, got ? { building: true, after: null } : { after });
@@ -170,10 +173,10 @@ function dropDeadYield(dir) {
170
173
  * Wait for ticket `n`'s turn; its removal (a cancel) ends the wait with an error. `after` on the
171
174
  * ticket says what it waits behind.
172
175
  */
173
- export async function waitTurn(projectDir, n, { from = null } = {}) {
176
+ export async function waitTurn(projectDir, n, { free = false } = {}) {
174
177
  const dir = path.resolve(projectDir);
175
178
  for (;;) {
176
- const got = await enter(dir, n, from);
179
+ const got = await enter(dir, n, free);
177
180
  if (got === 'gone') throw new Error(CANCELLED);
178
181
  if (got) return got;
179
182
  await sleep(POLL_MS);
@@ -219,6 +219,10 @@ async function locate(root, kind, name, type) {
219
219
  * `gcf design part <kind> <name>`: one part as a form shows it. `base` is the hash a save sends
220
220
  * back, so an edit made meanwhile is reported, not overwritten. `type` gives the fields of a
221
221
  * unit not written yet.
222
+ * @param {string} projectDir
223
+ * @param {string} kind
224
+ * @param {string} name
225
+ * @param {{type?: string | null}} [opts]
222
226
  */
223
227
  export async function designPart(projectDir, kind, name, { type = null } = {}) {
224
228
  const root = path.join(path.resolve(projectDir), 'gcf');
@@ -340,6 +344,7 @@ function pillarIds(part, given) {
340
344
  const now = part.fields.find((f) => f.key === 'pillars')?.value ?? [];
341
345
  const before = Array.isArray(now) ? now : [];
342
346
  const taken = new Set([...before, ...given].map((p) => p?.id).filter(Boolean));
347
+ /** @type {[string, string][]} */
343
348
  const renames = [];
344
349
  const records = given.map((p) => {
345
350
  if (!p || typeof p !== 'object') return p;
@@ -400,6 +405,13 @@ async function newUnitId(projectDir, kind, title, type) {
400
405
  return deriveId(oneLine(title), (await buildLedger(projectDir)).known, type);
401
406
  }
402
407
 
408
+ /**
409
+ * @param {string} projectDir
410
+ * @param {string} kind
411
+ * @param {string | null | undefined} given
412
+ * @param {{fields?: Record<string, any> | null, text?: string | null, base?: string | null,
413
+ * system?: string | null, type?: string | null, title?: string | null, commit?: boolean}} opts
414
+ */
403
415
  async function saveUnlocked(
404
416
  projectDir,
405
417
  kind,
@@ -455,7 +467,8 @@ async function saveUnlocked(
455
467
  ? skeleton(specs, { id: name, type: part.type, system: owner, title })
456
468
  : '';
457
469
  let lines = start ? start.split('\n') : [];
458
- for (const [key, value] of Object.entries(edits)) {
470
+ // `fields` is given when `text` is not (checked above).
471
+ for (const [key, value] of Object.entries(/** @type {Record<string, any>} */ (edits))) {
459
472
  const spec = specs.find((s) => s.key === key);
460
473
  if (!spec) throw new Error(`${key} is not a field of ${kind} ${name}`);
461
474
  const field = part.fields.find((f) => f.key === key);
@@ -471,7 +484,7 @@ async function saveUnlocked(
471
484
  next = await withManualAnswers(next, changedKeys(part.text, next), part.type);
472
485
  if (part.exists && hashOf(next) === part.base) return { applied: [], hash: null };
473
486
  // The base goes into the marker line: anything but a hash would break the bundle's shape.
474
- if (part.exists && !/^[0-9a-f]{8}$/.test(base))
487
+ if (part.exists && !/^[0-9a-f]{8}$/.test(/** @type {string} */ (base)))
475
488
  throw new Error(`--base is the 8-hex hash gcf design part gave: ${base}`);
476
489
  const marker = [
477
490
  `<!-- gcf:part ${kind} ${name}`,
@@ -518,6 +531,10 @@ class NothingApplied extends Error {}
518
531
  * Bring `text` in through the import and commit what it wrote. `strict`: a part the import
519
532
  * reports refuses the whole move. Files with changes not recorded yet refuse it up front: the
520
533
  * commit would carry them under the edit's name.
534
+ * @param {string} projectDir
535
+ * @param {string} message
536
+ * @param {string} text
537
+ * @param {{key: string, items?: string[], strict?: boolean, draft?: boolean, commit?: boolean}} opts
521
538
  */
522
539
  async function bundleMove(
523
540
  projectDir,
@@ -549,6 +566,7 @@ async function bundleMove(
549
566
  `${loose.join(', ')} holds changes not recorded yet: record the design first (gcf ` +
550
567
  `design commit)`,
551
568
  );
569
+ /** @type {Awaited<ReturnType<typeof importBundle>>} */
552
570
  let result = { applied: [], report: [] };
553
571
  try {
554
572
  const hash = await commitMove(projectDir, message, {
package/lib/devices.js CHANGED
@@ -84,7 +84,8 @@ const tailOf = (text) => text.trimEnd().split(/\r?\n/).slice(-20).join('\n');
84
84
  /**
85
85
  * `gcf playtest devices <target>`: what the target's script finds, each device placed under a row
86
86
  * of `plays_on` it fits, or why not.
87
- * @returns {Promise<{target: string, rows: object[], devices: object[], unavailable?: string,
87
+ * @returns {Promise<{target: string, rows: object[], devices: Array<Record<string, any>>,
88
+ * unavailable?: string,
88
89
  * problem?: string, tail?: string}>}
89
90
  */
90
91
  export async function devicesOf(projectDir, targetName, { ms = DEVICES_MS } = {}) {
package/lib/domain.js CHANGED
@@ -779,9 +779,24 @@ const BLOCK_SPECS = {
779
779
  help: 'How this project builds and starts its game: cards on the same code share one build',
780
780
  args: ['gcf', 'playtest', 'setup'],
781
781
  fields: [
782
+ // docs/Handoff-Plan.md t16, t18: which build the next fields set, and whose command.
783
+ text('of', 'Build name: the one the next fields set; a new name adds a build'),
782
784
  text('build', 'Build command'),
785
+ {
786
+ key: 'profile',
787
+ label: 'Whose command it is',
788
+ kind: 'choice',
789
+ options: [
790
+ { value: 'debug', label: 'debug: the default' },
791
+ { value: 'release', label: 'release: the build players get' },
792
+ ],
793
+ },
783
794
  text('output', 'Folder it builds to: inside the project, ignored by git'),
795
+ text('auto_build', "The build a run's card gets when its play_on names none", {
796
+ flag: 'auto-build',
797
+ }),
784
798
  text('target', 'Target name'),
799
+ text('target_build', 'The build the target plays', { flag: 'target-build' }),
785
800
  text('start', 'Start command: {dir} the build, {port} a free port, {lan} this machine'),
786
801
  text('open', 'What to open: a URL or words'),
787
802
  text('stop', 'Command after the player stops'),
package/lib/gates.js CHANGED
@@ -12,8 +12,9 @@ const AGENT_DECIDES = ['spike', 'decision'];
12
12
  /**
13
13
  * The gates in force for `item` (its frontmatter): the project's, or every item gate on its
14
14
  * second value (`skip_gates: true`) or on `wait` (`false`). `milestone` is the project's only.
15
- * @param {{gates: Record<string, string>}} config readConfig's
15
+ * @param {Record<string, any>} config readConfig's (its `gates`)
16
16
  * @param {Record<string, any> | null} [item]
17
+ * @returns {Record<string, string>}
17
18
  */
18
19
  export function gatePolicy(config, item = null) {
19
20
  const skip = item?.skip_gates;
package/lib/git.js CHANGED
@@ -267,7 +267,7 @@ function commitRefusal(message, out) {
267
267
  * @param {string} projectDir
268
268
  * @param {string} message
269
269
  * @param {string[]} paths
270
- * @param {{key?: string, items?: string[]}} [move]
270
+ * @param {{key?: string, items?: string[], proposal?: string}} [move]
271
271
  */
272
272
  export function commitPaths(projectDir, message, paths, move = {}) {
273
273
  const staged = paths.filter((p) => existsSync(p) || tracked(projectDir, p));
package/lib/handoff.js CHANGED
@@ -6,7 +6,7 @@ import { spawnSync } from 'node:child_process';
6
6
  import path from 'node:path';
7
7
  import { firstBullet, readConfig, scalarOf } from './gcf-paths.js';
8
8
  import { buildLedger } from './ledger.js';
9
- import { buildOf, lanAddress, playOf, queueOf } from './play.js';
9
+ import { defaultBuild, itemBuilds, lanAddress, playOf, queueOf } from './play.js';
10
10
  import { planPasses, planTicks } from './plan-check.js';
11
11
  import { listQuestions } from './questions.js';
12
12
  import { recordsOf } from './verdict-fs.js';
@@ -14,7 +14,7 @@ import { serves } from './devices.js';
14
14
  import { planTextOf, playNotesOf, playNotesProblems, rowsFor } from './play-notes.js';
15
15
 
16
16
  /** A row's state without asking devices: what is set up and built (the panel asks the rest). */
17
- function rowOf(play, build, built, row) {
17
+ function rowOf(play, build, ok, row) {
18
18
  const entry = Object.entries(play.targets).find(([, t]) => serves(t, build, row));
19
19
  const base = {
20
20
  device: row.device,
@@ -26,7 +26,7 @@ function rowOf(play, build, built, row) {
26
26
  note: row.note ?? null,
27
27
  };
28
28
  if (!entry) return { ...base, status: 'not set up' };
29
- if (!built?.ok) return { ...base, status: 'not built' };
29
+ if (!ok) return { ...base, status: 'not built' };
30
30
  const t = entry[1];
31
31
  if (t.devices) return { ...base, status: 'built' };
32
32
  // This computer plays what has no devices script.
@@ -40,8 +40,11 @@ function rowOf(play, build, built, row) {
40
40
  return { ...base, status: 'not detected', address: t.open.replaceAll('{lan}', lanAddress()) };
41
41
  }
42
42
 
43
- /** Play by platform (block 2): each build of the card's `play_on` by each row of its `plays_on`. */
44
- function playBlock(play, item, build, notes) {
43
+ /**
44
+ * Play by platform (block 2): each build of the card's `play_on` by each row of its `plays_on`.
45
+ * `built`: each profile of the build the card has a snapshot or an attempt of.
46
+ */
47
+ function playBlock(play, item, builds, notes) {
45
48
  if (!play) return [];
46
49
  const all = Object.keys(play.builds);
47
50
  const playOn = item.data.play_on ?? [];
@@ -51,16 +54,26 @@ function playBlock(play, item, build, notes) {
51
54
  ?.note || null;
52
55
 
53
56
  return names.map((b) => {
54
- // Step 1 has one build: the card's build is of it.
55
- const built = build?.ok ? { profile: null, ok: true } : null;
57
+ const built = builds
58
+ .filter((x) => x.build === b)
59
+ .map((x) => ({
60
+ profile: x.profile,
61
+ ok: x.ok,
62
+ built_at: x.built_at,
63
+ building: x.building,
64
+ cold: x.cold,
65
+ problem: x.problem,
66
+ }));
67
+ const ok = built.some((x) => x.ok);
56
68
  const rows = play.builds[b].plays_on;
57
69
 
58
70
  return {
59
71
  build: b,
72
+ profiles: Object.keys(play.builds[b].profiles),
60
73
  built,
61
74
  rows: rows.length
62
- ? rows.map((r) => rowOf(play, b, built, { ...r, note: noteOf(b, r) }))
63
- : targetRows(play, b, built),
75
+ ? rows.map((r) => rowOf(play, b, ok, { ...r, note: noteOf(b, r) }))
76
+ : targetRows(play, b, ok),
64
77
  };
65
78
  });
66
79
  }
@@ -69,7 +82,7 @@ function playBlock(play, item, build, notes) {
69
82
  * A build with no `plays_on` yet (a setup from before them): a row per target of it, so Play
70
83
  * stays where the Play bar had it. `device: any`: no row of the core's says which.
71
84
  */
72
- function targetRows(play, build, built) {
85
+ function targetRows(play, build, ok) {
73
86
  return Object.entries(play.targets)
74
87
  .filter(([, t]) => t.build === build)
75
88
  .map(([name, t]) => ({
@@ -80,20 +93,31 @@ function targetRows(play, build, built) {
80
93
  target: name,
81
94
  devices: [],
82
95
  note: null,
83
- status: !built?.ok ? 'not built' : t.devices ? 'built' : 'ready',
96
+ status: !ok ? 'not built' : t.devices ? 'built' : 'ready',
84
97
  }));
85
98
  }
86
99
 
100
+ /** The card's own build: the one a run gives it (`defaultBuild`), debug; else the first it has. */
101
+ function ownBuild(play, item, builds) {
102
+ const name = play ? defaultBuild(play, item.data.play_on) : null;
103
+
104
+ return (
105
+ builds.find((b) => b.build === name && b.profile === 'debug') ??
106
+ builds.find((b) => b.build === name) ??
107
+ builds[0] ??
108
+ null
109
+ );
110
+ }
111
+
87
112
  /** The outcome (block 0): where the card stands, its build, a ticket that waits for it. */
88
- function outcomeOf(item, play, build, queue) {
89
- const name = play ? Object.keys(play.builds)[0] : null;
113
+ function outcomeOf(item, build, queue) {
90
114
  const ticket = queue.find((q) => q.job.build === item.data.id);
91
115
 
92
116
  return {
93
117
  word: item.data.status,
94
118
  build: build && {
95
- name,
96
- profile: null,
119
+ name: build.build,
120
+ profile: build.profile,
97
121
  ok: build.ok,
98
122
  built_at: build.built_at,
99
123
  building: build.building,
@@ -175,7 +199,7 @@ function playedBlocks(c) {
175
199
  const n = c.notes;
176
200
 
177
201
  return {
178
- play: c.decision ? null : playBlock(c.play, c.item, c.build, n),
202
+ play: c.decision ? null : playBlock(c.play, c.item, c.builds, n),
179
203
  try: c.decision ? null : (n?.try ?? []),
180
204
  try_from_behavior: recordsOf(c.item.body, 'behavior')
181
205
  .map((r) => r.input)
@@ -218,7 +242,7 @@ function outcomeLine(o) {
218
242
  : b.building
219
243
  ? 'building'
220
244
  : b.ok
221
- ? `build ${b.name} ${b.built_at ?? ''}${b.stale ? ` (old: ${b.problem})` : ''}`
245
+ ? `build ${b.name} ${b.profile} ${b.built_at ?? ''}${b.stale ? ` (old: ${b.problem})` : ''}`
222
246
  : `no build: ${b.problem}`;
223
247
 
224
248
  return `outcome: ${o.word} · ${build}${o.queued ? ` · ticket ${o.queued} waits` : ''}`;
@@ -261,6 +285,11 @@ export function handoffLines(id, h) {
261
285
  /**
262
286
  * Blocks 0-7 of card `id`'s handoff, or null when it has none (it waits for nothing). `links`:
263
287
  * the snapshots' links, read once for a whole board.
288
+ * @param {string} projectDir
289
+ * @param {string} id
290
+ * @param {{ledger?: Awaited<ReturnType<typeof buildLedger>> | null,
291
+ * config?: Record<string, any> | null,
292
+ * links?: ReturnType<typeof import('./play.js').linksOf>}} [opts]
264
293
  */
265
294
  export async function handoffOf(projectDir, id, { ledger = null, config = null, links } = {}) {
266
295
  const dir = path.resolve(projectDir);
@@ -275,12 +304,13 @@ export async function handoffOf(projectDir, id, { ledger = null, config = null,
275
304
  decision,
276
305
  play: await playIn(dir, config),
277
306
  notes: playNotesOf(text),
278
- build: decision ? null : buildOf(dir, id, item.data.status, links),
307
+ builds: decision ? [] : itemBuilds(dir, id, item.data.status, links),
279
308
  };
309
+ c.build = ownBuild(c.play, item, c.builds);
280
310
  const question = questionOf(item, c.notes, decision);
281
311
 
282
312
  return {
283
- outcome: outcomeOf(item, c.play, c.build, queueOf(dir)),
313
+ outcome: outcomeOf(item, c.build, queueOf(dir)),
284
314
  question,
285
315
  changed: (item.data.live?.changes ?? []).map((x) => x.summary).filter(Boolean),
286
316
  ...playedBlocks(c),
@@ -64,6 +64,15 @@ export const DETAIL = /^[a-z0-9][a-z0-9-]{0,29}$/;
64
64
 
65
65
  // `set_by`: the origins that may file it; `question`: a question record only (D1, D2), never an
66
66
  // entry. `details`: the closed list, or null for a free one. `later`: whether Later may hold it.
67
+ /**
68
+ * @param {string} id
69
+ * @param {string} label
70
+ * @param {string} help
71
+ * @param {number} rank
72
+ * @param {string} group
73
+ * @param {string[]} setBy
74
+ * @param {{details?: string[] | null, later?: boolean}} [opts]
75
+ */
67
76
  const row = (id, label, help, rank, group, setBy, { details = null, later = true } = {}) => ({
68
77
  id,
69
78
  label,
package/lib/inbox.js CHANGED
@@ -82,6 +82,7 @@ export function fromOld({ source, tags = [], kind, item }) {
82
82
  const laterOk = BASE_CATEGORIES.find((c) => c.id === category)?.later ?? true;
83
83
  const later = words.includes('later') && laterOk;
84
84
  const rest = words.filter((t) => t !== 'later');
85
+ /** @type {string | null} */
85
86
  let detail = null;
86
87
  if (lesson) detail = LESSON_KINDS.includes(String(kind)) ? String(kind) : 'other';
87
88
  else if (rest.length) {
@@ -239,6 +240,12 @@ function freeId(root, seed, taken) {
239
240
  }
240
241
  }
241
242
 
243
+ /**
244
+ * planAdd's options.
245
+ * @typedef {{category?: string, detail?: string | null, origin?: string, item?: string | null,
246
+ * by?: string, vocab?: typeof BASE_VOCABULARY, now?: string, taken?: Set<string>}} AddOpts
247
+ */
248
+
242
249
  /**
243
250
  * The origin of a new entry: `origin` when given, else who makes the move (`by`, moveBy). An
244
251
  * agent's run or session files as `agent` only: the channel, not the writer, says where it
@@ -258,6 +265,9 @@ function originOf(origin, by) {
258
265
  * A new entry's plan: its file and how to write it. Its id hashes the text and the moment
259
266
  * (`now`), so two branches never collide; a clash in this folder hashes again. The category
260
267
  * must be one its origin may file in `vocab`; a lesson's detail is its kind.
268
+ * @param {string} root
269
+ * @param {string} text
270
+ * @param {AddOpts} [opts]
261
271
  */
262
272
  export function planAdd(
263
273
  root,
@@ -328,6 +338,10 @@ async function planChange(root, id, change) {
328
338
  * Entry `id` moved to `category` (its own when none) with `detail` (none when the category
329
339
  * changes and no detail is given). The operator moves it to any category but a question's and
330
340
  * `unsorted`; an agent only to one it may file. Its origin stays: it says where it came from.
341
+ * @param {string} root
342
+ * @param {string} id
343
+ * @param {{category?: string, detail?: string | null, by?: string,
344
+ * vocab?: typeof BASE_VOCABULARY}} [opts]
331
345
  */
332
346
  export async function planCategory(
333
347
  root,
@@ -433,7 +447,12 @@ export async function planTake(root, id, toDir) {
433
447
  };
434
448
  }
435
449
 
436
- /** Add an entry at once (planAdd), the operator's note unless `opts` say; returns it. */
450
+ /**
451
+ * Add an entry at once (planAdd), the operator's note unless `opts` say; returns it.
452
+ * @param {string} root
453
+ * @param {string} text
454
+ * @param {AddOpts} [opts]
455
+ */
437
456
  export async function addInbox(root, text, opts = {}) {
438
457
  const plan = planAdd(root, text, { by: 'operator', category: 'note', ...opts });
439
458
  await plan.apply();