gcf-aif-ext 0.29.0 → 0.29.2

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.
Files changed (50) hide show
  1. package/commands/gcf.js +114 -57
  2. package/extension.json +1 -1
  3. package/hooks/pre-commit.js +2 -0
  4. package/lib/agent-permissions.js +7 -4
  5. package/lib/audit-core.js +28 -18
  6. package/lib/board.js +1 -1
  7. package/lib/build-queue.js +5 -2
  8. package/lib/changes.js +1 -0
  9. package/lib/commit-files.js +2 -1
  10. package/lib/commit-move.js +114 -0
  11. package/lib/config-doc.js +22 -0
  12. package/lib/config-set.js +34 -39
  13. package/lib/design-check.js +8 -3
  14. package/lib/design-parts.js +123 -74
  15. package/lib/devices.js +5 -9
  16. package/lib/edits.js +7 -3
  17. package/lib/frozen.js +24 -0
  18. package/lib/gate.js +1 -1
  19. package/lib/gates.js +2 -1
  20. package/lib/gcf-paths.js +13 -10
  21. package/lib/git.js +19 -5
  22. package/lib/handoff.js +6 -1
  23. package/lib/history.js +1 -1
  24. package/lib/inbox-categories.js +37 -35
  25. package/lib/inbox.js +65 -34
  26. package/lib/integrate.js +7 -12
  27. package/lib/ledger.js +1 -1
  28. package/lib/lessons.js +4 -1
  29. package/lib/metrics.js +1 -0
  30. package/lib/migrate.js +1 -1
  31. package/lib/milestone-state.js +1 -1
  32. package/lib/phase.js +1 -1
  33. package/lib/pillars.js +1 -1
  34. package/lib/play-notes.js +4 -0
  35. package/lib/play-on.js +2 -1
  36. package/lib/play.js +36 -9
  37. package/lib/playtest-list.js +1 -1
  38. package/lib/push.js +9 -5
  39. package/lib/questions.js +4 -2
  40. package/lib/session-mark.js +21 -2
  41. package/lib/shelf.js +1 -0
  42. package/lib/systems-doc.js +31 -20
  43. package/lib/unit-ops.js +31 -109
  44. package/lib/validate-item.js +1 -2
  45. package/lib/verdict-fs.js +2 -1
  46. package/lib/verify-stamp.js +6 -1
  47. package/lib/verify.js +6 -2
  48. package/lib/work-ops.js +126 -86
  49. package/package.json +1 -1
  50. package/templates/agents-block.md +3 -0
package/lib/git.js CHANGED
@@ -46,6 +46,7 @@ const IN_PROGRESS = [
46
46
  /** The name of the merge or sequencer operation in progress, or null. */
47
47
  export function operationInProgress(projectDir) {
48
48
  const gitDir = spawnSync('git', ['rev-parse', '--git-dir'], {
49
+ windowsHide: true,
49
50
  cwd: projectDir,
50
51
  encoding: 'utf8',
51
52
  });
@@ -63,6 +64,7 @@ export const literal = (projectDir, p) => `:(literal)${relOf(projectDir, p)}`;
63
64
 
64
65
  const tracked = (projectDir, p) =>
65
66
  spawnSync('git', ['ls-files', '--error-unmatch', '--', literal(projectDir, p)], {
67
+ windowsHide: true,
66
68
  cwd: projectDir,
67
69
  stdio: 'ignore',
68
70
  }).status === 0;
@@ -70,6 +72,7 @@ const tracked = (projectDir, p) =>
70
72
  /** Whether the last commit holds `p`: a file only staged is not in it. */
71
73
  export const inHead = (projectDir, p) =>
72
74
  spawnSync('git', ['ls-tree', '--name-only', 'HEAD', '--', p], {
75
+ windowsHide: true,
73
76
  cwd: projectDir,
74
77
  encoding: 'utf8',
75
78
  }).stdout?.trim() !== '';
@@ -83,6 +86,7 @@ export function dirtyPaths(projectDir, paths) {
83
86
  // writing that file anew would commit away every line the deleted file held.
84
87
  if (!paths.length) return [];
85
88
  const res = spawnSync('git', ['status', '--porcelain', '--', ...paths], {
89
+ windowsHide: true,
86
90
  cwd: projectDir,
87
91
  encoding: 'utf8',
88
92
  });
@@ -116,11 +120,12 @@ export function dirtyGcf(projectDir, skip = []) {
116
120
  const res = spawnSync(
117
121
  'git',
118
122
  ['-c', 'core.quotePath=false', 'status', '--porcelain', '-z', '-uall', '--', ...GATE_SCOPE],
119
- { cwd: projectDir, encoding: 'utf8' },
123
+ { windowsHide: true, cwd: projectDir, encoding: 'utf8' },
120
124
  );
121
125
  if (res.status !== 0) return [];
122
126
  // Porcelain paths are the repository's: a project inside a bigger repository is a prefix in.
123
127
  const prefix = spawnSync('git', ['rev-parse', '--show-prefix'], {
128
+ windowsHide: true,
124
129
  cwd: projectDir,
125
130
  encoding: 'utf8',
126
131
  }).stdout.trim();
@@ -166,7 +171,8 @@ const relOf = (projectDir, p) =>
166
171
  * @param {string[]} files
167
172
  */
168
173
  export function restoreFromHead(projectDir, files) {
169
- const git = (...args) => spawnSync('git', args, { cwd: projectDir, encoding: 'utf8' });
174
+ const git = (...args) =>
175
+ spawnSync('git', args, { windowsHide: true, cwd: projectDir, encoding: 'utf8' });
170
176
  const must = (...args) => {
171
177
  const r = git(...args);
172
178
  if (r.status !== 0) throw new Error(`git ${args.join(' ')}: ${r.stderr.trim()}`);
@@ -267,12 +273,16 @@ function commitRefusal(message, out) {
267
273
  * @param {string} projectDir
268
274
  * @param {string} message
269
275
  * @param {string[]} paths
270
- * @param {{key?: string, items?: string[]}} [move]
276
+ * @param {{key?: string, items?: string[], proposal?: string}} [move]
271
277
  */
272
278
  export function commitPaths(projectDir, message, paths, move = {}) {
273
279
  const staged = paths.filter((p) => existsSync(p) || tracked(projectDir, p));
274
280
  for (const p of staged)
275
- spawnSync('git', ['add', '--', literal(projectDir, p)], { cwd: projectDir, stdio: 'ignore' });
281
+ spawnSync('git', ['add', '--', literal(projectDir, p)], {
282
+ windowsHide: true,
283
+ cwd: projectDir,
284
+ stdio: 'ignore',
285
+ });
276
286
  // A staged deletion (`git rm`) is off the disk and out of the index, but HEAD holds it: its
277
287
  // path commits the deletion. A file staged but never committed and now deleted matches
278
288
  // nothing: no pathspec.
@@ -302,6 +312,7 @@ export function commitOnly(projectDir, message, paths, msg) {
302
312
  ...(long ? ['--pathspec-from-file=-', '--pathspec-file-nul'] : ['--', ...only]),
303
313
  ],
304
314
  {
315
+ windowsHide: true,
305
316
  cwd: projectDir,
306
317
  encoding: 'utf8',
307
318
  ...(long && { input: only.map((p) => `${p}\0`).join('') }),
@@ -322,6 +333,7 @@ export function commitOnly(projectDir, message, paths, msg) {
322
333
  if (res.status !== 0) throw commitRefusal(message, out);
323
334
 
324
335
  return spawnSync('git', ['rev-parse', 'HEAD'], {
336
+ windowsHide: true,
325
337
  cwd: projectDir,
326
338
  encoding: 'utf8',
327
339
  }).stdout.trim();
@@ -341,6 +353,7 @@ export function snapshotIndex(cwd, files) {
341
353
  let stdout = '';
342
354
  for (const part of inParts(rels)) {
343
355
  const res = spawnSync('git', ['ls-files', '-s', '-z', '--', ...part], {
356
+ windowsHide: true,
344
357
  cwd,
345
358
  encoding: 'utf8',
346
359
  });
@@ -349,6 +362,7 @@ export function snapshotIndex(cwd, files) {
349
362
  }
350
363
 
351
364
  const prefix = spawnSync('git', ['rev-parse', '--show-prefix'], {
365
+ windowsHide: true,
352
366
  cwd,
353
367
  encoding: 'utf8',
354
368
  }).stdout.trim();
@@ -385,7 +399,7 @@ export function restoreIndex(snapshot) {
385
399
  `${entry.mode},${entry.blob},${snapshot.prefix}${rel}`,
386
400
  ]
387
401
  : ['update-index', '--force-remove', '--', rel];
388
- const res = spawnSync('git', args, { cwd: snapshot.cwd, encoding: 'utf8' });
402
+ const res = spawnSync('git', args, { windowsHide: true, cwd: snapshot.cwd, encoding: 'utf8' });
389
403
  const reason = (res.stderr || '').trim() || res.error?.message;
390
404
  if (res.status !== 0)
391
405
  errors.push(new Error(`could not restore the index entry of ${rel}: ${reason}`));
package/lib/handoff.js CHANGED
@@ -134,7 +134,7 @@ function saidOf(projectDir, id) {
134
134
  const res = spawnSync(
135
135
  'git',
136
136
  ['log', '-1', '--format=%s', '--fixed-strings', `--grep=gcf(submit): ${id}`],
137
- { cwd: projectDir, encoding: 'utf8' },
137
+ { windowsHide: true, cwd: projectDir, encoding: 'utf8' },
138
138
  );
139
139
  const m = /\((agent: [^)]*)\)\s*$/.exec(res.stdout?.trim() ?? '');
140
140
 
@@ -285,6 +285,11 @@ export function handoffLines(id, h) {
285
285
  /**
286
286
  * Blocks 0-7 of card `id`'s handoff, or null when it has none (it waits for nothing). `links`:
287
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]
288
293
  */
289
294
  export async function handoffOf(projectDir, id, { ledger = null, config = null, links } = {}) {
290
295
  const dir = path.resolve(projectDir);
package/lib/history.js CHANGED
@@ -90,7 +90,7 @@ export function itemHistory(projectDir, id, { limit = HISTORY_MAX } = {}) {
90
90
  const res = spawnSync(
91
91
  'git',
92
92
  ['log', `--format=%h${FS}%cI${FS}%s${FS}%b${RS}`, '--fixed-strings', '--grep=gcf(', '--'],
93
- { cwd: projectDir, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 },
93
+ { windowsHide: true, cwd: projectDir, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 },
94
94
  );
95
95
  if (res.status !== 0) return [];
96
96
  const moves = [];
@@ -64,7 +64,14 @@ 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
- const row = (id, label, help, rank, group, setBy, { details = null, later = true } = {}) => ({
67
+ /**
68
+ * @param {string} id
69
+ * @param {string} label
70
+ * @param {string} help
71
+ * @param {{rank: number, group: string, setBy: string[], details?: string[] | null,
72
+ * later?: boolean}} opts
73
+ */
74
+ const row = (id, label, help, { rank, group, setBy, details = null, later = true }) => ({
68
75
  id,
69
76
  label,
70
77
  help,
@@ -81,50 +88,40 @@ export const BASE_CATEGORIES = [
81
88
  'decision',
82
89
  'Decision needed',
83
90
  'A question only you can answer; the work it holds waits for your answer',
84
- 1,
85
- 'needs-you',
86
- ['question'],
87
- { later: false },
91
+ { rank: 1, group: 'needs-you', setBy: ['question'], later: false },
88
92
  ),
89
93
  row(
90
94
  'failure',
91
95
  'Check failed',
92
96
  'An automatic check broke on the main line: a CI job, a build, a scheduled test',
93
- 2,
94
- 'needs-you',
95
- ['automation'],
96
- { later: false },
97
+ { rank: 2, group: 'needs-you', setBy: ['automation'], later: false },
97
98
  ),
98
99
  row(
99
100
  'request',
100
101
  'Agent request',
101
102
  'What only a person can give: a file, an asset, an account, an access',
102
- 3,
103
- 'needs-you',
104
- ['agent'],
103
+ { rank: 3, group: 'needs-you', setBy: ['agent'] },
105
104
  ),
106
- row('bug', 'Bug', 'The product does what a rule or a test says it must not', 4, 'to-sort', [
107
- 'you',
108
- 'agent',
109
- 'automation',
110
- ]),
105
+ row('bug', 'Bug', 'The product does what a rule or a test says it must not', {
106
+ rank: 4,
107
+ group: 'to-sort',
108
+ setBy: ['you', 'agent', 'automation'],
109
+ }),
111
110
  row(
112
111
  'finding',
113
112
  'Finding',
114
113
  "A remark about the code or the project: a risk, debt, an analyzer's warning, a slow path",
115
- 6,
116
- 'to-sort',
117
- ['agent', 'automation'],
118
- ),
119
- row(
120
- 'unsorted',
121
- 'Not sorted',
122
- 'An entry from before the categories: give it one',
123
- 7,
124
- 'to-sort',
125
- [],
114
+ { rank: 6, group: 'to-sort', setBy: ['agent', 'automation'] },
126
115
  ),
127
- row('lesson', 'Lesson', "What got in an agent's way in its run", 8, 'agent-feedback', ['agent'], {
116
+ row('unsorted', 'Not sorted', 'An entry from before the categories: give it one', {
117
+ rank: 7,
118
+ group: 'to-sort',
119
+ setBy: [],
120
+ }),
121
+ row('lesson', 'Lesson', "What got in an agent's way in its run", {
122
+ rank: 8,
123
+ group: 'agent-feedback',
124
+ setBy: ['agent'],
128
125
  details: LESSON_KINDS,
129
126
  }),
130
127
  // No Later either (the operator, 2026-10-22): it waits folded already, an answer moves it.
@@ -132,13 +129,18 @@ export const BASE_CATEGORIES = [
132
129
  'assumption',
133
130
  'Assumption to check',
134
131
  'A decision an agent took and works with; overrule it if it is wrong',
135
- 9,
136
- 'agent-feedback',
137
- ['question'],
138
- { later: false },
132
+ { rank: 9, group: 'agent-feedback', setBy: ['question'], later: false },
139
133
  ),
140
- row('idea', 'Idea', 'A change someone proposes, not decided', 10, 'ideas', ['you', 'agent']),
141
- row('note', 'Note', 'A reminder, a plan, a reference', 11, 'ideas', ['you']),
134
+ row('idea', 'Idea', 'A change someone proposes, not decided', {
135
+ rank: 10,
136
+ group: 'ideas',
137
+ setBy: ['you', 'agent'],
138
+ }),
139
+ row('note', 'Note', 'A reminder, a plan, a reference', {
140
+ rank: 11,
141
+ group: 'ideas',
142
+ setBy: ['you'],
143
+ }),
142
144
  ];
143
145
 
144
146
  /**
package/lib/inbox.js CHANGED
@@ -65,6 +65,19 @@ const OLD_SOURCES = {
65
65
  operator: ['note', 'you'],
66
66
  };
67
67
 
68
+ const laterOf = (category) => BASE_CATEGORIES.find((c) => c.id === category)?.later ?? true;
69
+
70
+ /** An old entry's detail: a lesson's kind, else its first tag when it reads as one (taken off). */
71
+ function oldDetail(lesson, kind, rest) {
72
+ if (lesson) return LESSON_KINDS.includes(String(kind)) ? String(kind) : 'other';
73
+ if (!rest.length) return null;
74
+ const word = rest[0].replaceAll(':', '-').slice(0, 30).replace(/-+$/, '');
75
+ if (!DETAIL.test(word)) return null;
76
+ rest.shift();
77
+
78
+ return word;
79
+ }
80
+
68
81
  /**
69
82
  * The frontmatter of an entry from before the categories (`source`, `tags`, a lesson's `kind`
70
83
  * and `item`) as the categories have it, with what did not fit (Board-PRD §2.6 Migration): the
@@ -79,19 +92,10 @@ export function fromOld({ source, tags = [], kind, item }) {
79
92
  if (!category || !Array.isArray(tags)) return null;
80
93
  const words = tags.map(String);
81
94
  // Later only where its category may go there: an old CI failure never did.
82
- const laterOk = BASE_CATEGORIES.find((c) => c.id === category)?.later ?? true;
95
+ const laterOk = laterOf(category);
83
96
  const later = words.includes('later') && laterOk;
84
97
  const rest = words.filter((t) => t !== 'later');
85
- let detail = null;
86
- if (lesson) detail = LESSON_KINDS.includes(String(kind)) ? String(kind) : 'other';
87
- else if (rest.length) {
88
- const word = rest[0].replaceAll(':', '-').slice(0, 30).replace(/-+$/, '');
89
- if (DETAIL.test(word)) {
90
- detail = word;
91
- rest.shift();
92
- }
93
- }
94
-
98
+ const detail = oldDetail(lesson, kind, rest);
95
99
  const lostLater = words.includes('later') && !laterOk ? ['later (never on its category)'] : [];
96
100
 
97
101
  return {
@@ -239,6 +243,12 @@ function freeId(root, seed, taken) {
239
243
  }
240
244
  }
241
245
 
246
+ /**
247
+ * planAdd's options.
248
+ * @typedef {{category?: string, detail?: string | null, origin?: string, item?: string | null,
249
+ * by?: string, vocab?: typeof BASE_VOCABULARY, now?: string, taken?: Set<string>}} AddOpts
250
+ */
251
+
242
252
  /**
243
253
  * The origin of a new entry: `origin` when given, else who makes the move (`by`, moveBy). An
244
254
  * agent's run or session files as `agent` only: the channel, not the writer, says where it
@@ -254,10 +264,24 @@ function originOf(origin, by) {
254
264
  return origin;
255
265
  }
256
266
 
267
+ /** Refuse filing an entry into category `c` from `from`: a question's, or one it may not file. */
268
+ function refuseFiling(vocab, c, from) {
269
+ if (questionOnly(c))
270
+ throw new Error(`a ${c.id} is an open question, not an entry: ai-factory gcf question add`);
271
+ if (!c.set_by.includes(from))
272
+ throw new Error(
273
+ `${from} files no ${c.id}: ${fileableBy(vocab, from).join(' | ') || 'none'} ` +
274
+ '(ai-factory gcf inbox categories)',
275
+ );
276
+ }
277
+
257
278
  /**
258
279
  * A new entry's plan: its file and how to write it. Its id hashes the text and the moment
259
280
  * (`now`), so two branches never collide; a clash in this folder hashes again. The category
260
281
  * must be one its origin may file in `vocab`; a lesson's detail is its kind.
282
+ * @param {string} root
283
+ * @param {string} text
284
+ * @param {AddOpts} [opts]
261
285
  */
262
286
  export function planAdd(
263
287
  root,
@@ -282,13 +306,7 @@ export function planAdd(
282
306
  );
283
307
  const c = categoryOf(vocab, category);
284
308
  const from = originOf(origin, by);
285
- if (questionOnly(c))
286
- throw new Error(`a ${c.id} is an open question, not an entry: ai-factory gcf question add`);
287
- if (!c.set_by.includes(from))
288
- throw new Error(
289
- `${from} files no ${c.id}: ${fileableBy(vocab, from).join(' | ') || 'none'} ` +
290
- '(ai-factory gcf inbox categories)',
291
- );
309
+ refuseFiling(vocab, c, from);
292
310
  checkDetail(c, detail);
293
311
  if (item !== null && !isValidId(item)) throw new Error(`${item} is not an item id`);
294
312
  const id = freeId(root, `${now}\n${clean}`, taken);
@@ -324,10 +342,29 @@ async function planChange(root, id, change) {
324
342
  return plan;
325
343
  }
326
344
 
345
+ /** Refuse moving an entry into category `c`: a question's, an old one's, or one `actor` may not. */
346
+ function refuseMoveInto(vocab, c, actor) {
347
+ if (questionOnly(c) || !c.set_by.length)
348
+ throw new Error(
349
+ `no entry moves into ${c.id}: ` +
350
+ (c.set_by.length
351
+ ? 'it is an open question'
352
+ : 'it is for entries from before the categories'),
353
+ );
354
+ if (actor === 'agent' && !c.set_by.includes('agent'))
355
+ throw new Error(
356
+ `an agent moves no entry into ${c.id}: ${fileableBy(vocab, 'agent').join(' | ')}`,
357
+ );
358
+ }
359
+
327
360
  /**
328
361
  * Entry `id` moved to `category` (its own when none) with `detail` (none when the category
329
362
  * changes and no detail is given). The operator moves it to any category but a question's and
330
363
  * `unsorted`; an agent only to one it may file. Its origin stays: it says where it came from.
364
+ * @param {string} root
365
+ * @param {string} id
366
+ * @param {{category?: string, detail?: string | null, by?: string,
367
+ * vocab?: typeof BASE_VOCABULARY}} [opts]
331
368
  */
332
369
  export async function planCategory(
333
370
  root,
@@ -339,18 +376,7 @@ export async function planCategory(
339
376
 
340
377
  return planChange(root, id, (e) => {
341
378
  const c = categoryOf(vocab, category ?? e.category);
342
- const actor = actorOrigin(by);
343
- if (questionOnly(c) || !c.set_by.length)
344
- throw new Error(
345
- `no entry moves into ${c.id}: ` +
346
- (c.set_by.length
347
- ? 'it is an open question'
348
- : 'it is for entries from before the categories'),
349
- );
350
- if (actor === 'agent' && !c.set_by.includes('agent'))
351
- throw new Error(
352
- `an agent moves no entry into ${c.id}: ${fileableBy(vocab, 'agent').join(' | ')}`,
353
- );
379
+ refuseMoveInto(vocab, c, actorOrigin(by));
354
380
  const next = detail === undefined ? (c.id === e.category ? e.detail : null) : detail || null;
355
381
  checkDetail(c, next);
356
382
  if (c.id === e.category && next === e.detail)
@@ -433,7 +459,12 @@ export async function planTake(root, id, toDir) {
433
459
  };
434
460
  }
435
461
 
436
- /** Add an entry at once (planAdd), the operator's note unless `opts` say; returns it. */
462
+ /**
463
+ * Add an entry at once (planAdd), the operator's note unless `opts` say; returns it.
464
+ * @param {string} root
465
+ * @param {string} text
466
+ * @param {AddOpts} [opts]
467
+ */
437
468
  export async function addInbox(root, text, opts = {}) {
438
469
  const plan = planAdd(root, text, { by: 'operator', category: 'note', ...opts });
439
470
  await plan.apply();
@@ -452,9 +483,9 @@ export async function dropInbox(root, id) {
452
483
  */
453
484
  export function untrackedEntries(projectDir) {
454
485
  const list = (args) =>
455
- (spawnSync('git', args, { cwd: projectDir, encoding: 'utf8' }).stdout ?? '').split(
456
- String.fromCharCode(0),
457
- );
486
+ (
487
+ spawnSync('git', args, { windowsHide: true, cwd: projectDir, encoding: 'utf8' }).stdout ?? ''
488
+ ).split(String.fromCharCode(0));
458
489
  // Never committed: not tracked at all, or only staged.
459
490
  const names = [
460
491
  ...list(['ls-files', '--others', '--exclude-standard', '-z', '--', 'gcf/inbox']),
package/lib/integrate.js CHANGED
@@ -2,7 +2,7 @@
2
2
  // branch is ready once its tip carries the trailer `GCF-Verified: <id>` — readiness lives in git,
3
3
  // not in memory. `integrate` merges such a branch into main and records the item's move there,
4
4
  // under the main lock; without an id it picks up every verified branch a dead run left behind.
5
- import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
5
+ import { readFile, writeFile } from 'node:fs/promises';
6
6
  import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
7
7
  import { spawnSync } from 'node:child_process';
8
8
  import path from 'node:path';
@@ -17,6 +17,7 @@ import { agentDecideProblem } from './gates.js';
17
17
  import { isValidId } from './id.js';
18
18
  import { writeIndex } from './index-gen.js';
19
19
  import { moveTrailers, restoreIndex, snapshotIndex } from './git.js';
20
+ import { excludeSession } from './session-mark.js';
20
21
 
21
22
  const TRAILER = 'GCF-Verified';
22
23
  export const branchOf = (id) => `work/${id}`;
@@ -24,23 +25,13 @@ export const worktreeOf = (projectDir, id) =>
24
25
  path.join(path.resolve(projectDir), '.gcf-session', 'worktrees', id);
25
26
 
26
27
  function git(cwd, args, { check = true } = {}) {
27
- const res = spawnSync('git', args, { cwd, encoding: 'utf8' });
28
+ const res = spawnSync('git', args, { windowsHide: true, cwd, encoding: 'utf8' });
28
29
  const err = (res.stderr || res.stdout || '').trim();
29
30
  if (check && res.status !== 0) throw new Error(`git ${args.join(' ')} failed: ${err}`);
30
31
 
31
32
  return { ok: res.status === 0, out: (res.stdout ?? '').trim(), err };
32
33
  }
33
34
 
34
- /** `.gcf-session/` stays out of `git status` without a tracked .gitignore change. */
35
- export async function excludeSession(projectDir) {
36
- const common = path.resolve(projectDir, git(projectDir, ['rev-parse', '--git-common-dir']).out);
37
- const file = path.join(common, 'info', 'exclude');
38
- const text = existsSync(file) ? await readFile(file, 'utf8') : '';
39
- if (text.split(/\r?\n/).includes('/.gcf-session/')) return;
40
- await mkdir(path.dirname(file), { recursive: true });
41
- await appendFile(file, `${text && !text.endsWith('\n') ? '\n' : ''}/.gcf-session/\n`);
42
- }
43
-
44
35
  const METRICS = ':(exclude)gcf/.metrics';
45
36
 
46
37
  /** A worktree's own audit and context lines in gcf/.metrics are no work to keep: dropped. */
@@ -57,6 +48,8 @@ function dropLogs(dir) {
57
48
  * past the commit gate like a merge that needs no hand (git runs no pre-commit for it). `card`,
58
49
  * when given, may stop it too: main's text wins, the human's (a fix made while the branch waited).
59
50
  * True when the merge is done; false leaves the caller to abort it.
51
+ * @param {string} dir
52
+ * @param {string | null} [card]
60
53
  */
61
54
  async function mergedPastIndex(dir, card = null) {
62
55
  const unmerged = git(dir, ['diff', '--name-only', '--diff-filter=U'], { check: false })
@@ -129,6 +122,7 @@ async function syncWithMain(projectDir, dir, id) {
129
122
  git(dir, ['merge', '--no-edit', '-m', `gcf(sync): ${main}`, main], { check: false });
130
123
  const card = `gcf/work/${id}.md`;
131
124
  let res = merge();
125
+ /** @type {(() => void) | null} */
132
126
  let putBack = null;
133
127
  if (!res.ok && cardAloneHolds(dir, main, card)) {
134
128
  putBack = holdCard(dir, card);
@@ -295,6 +289,7 @@ function movedSinceMerge(projectDir, id) {
295
289
  * it took. Lines may be bullets. Empty when the plan has none.
296
290
  */
297
291
  export function planOutcome(text) {
292
+ /** @type {{decide: string | null, reason: string, assume: string[]}} */
298
293
  const out = { decide: null, reason: '', assume: [] };
299
294
  const at = String(text ?? '').search(/^## Outcome[ \t]*$/m);
300
295
  if (at < 0) return out;
package/lib/ledger.js CHANGED
@@ -25,7 +25,7 @@ async function recordLines(root, name) {
25
25
  }
26
26
 
27
27
  const gitOut = (args, cwd) => {
28
- const res = spawnSync('git', args, { cwd, encoding: 'utf8' });
28
+ const res = spawnSync('git', args, { windowsHide: true, cwd, encoding: 'utf8' });
29
29
 
30
30
  return res.status === 0 ? res.stdout : null;
31
31
  };
package/lib/lessons.js CHANGED
@@ -155,7 +155,10 @@ export async function addLessons(root, id, lessons) {
155
155
  return plan.entries;
156
156
  }
157
157
 
158
- /** The lessons of a JSON file: an array, as the harness writes it. */
158
+ /**
159
+ * The lessons of a JSON file: an array, as the harness writes it.
160
+ * @public gcf.js imports lib modules by name at run time, out of knip's sight.
161
+ */
159
162
  export async function lessonsFile(file) {
160
163
  try {
161
164
  return JSON.parse(await readFile(file, 'utf8'));
package/lib/metrics.js CHANGED
@@ -9,6 +9,7 @@ import path from 'node:path';
9
9
  /** gcf/.metrics of the main checkout of `projectDir`; its own outside a repository. */
10
10
  export function metricsDir(projectDir) {
11
11
  const res = spawnSync('git', ['rev-parse', '--git-common-dir'], {
12
+ windowsHide: true,
12
13
  cwd: projectDir,
13
14
  encoding: 'utf8',
14
15
  });
package/lib/migrate.js CHANGED
@@ -61,7 +61,7 @@ async function historySeed(projectDir, root) {
61
61
  const res = spawnSync(
62
62
  'git',
63
63
  ['log', '-E', '--grep', '^((Revert|Reapply) ")*gcf\\((verdict|done)\\):', '--format=%as %s'],
64
- { cwd: projectDir, encoding: 'utf8' },
64
+ { windowsHide: true, cwd: projectDir, encoding: 'utf8' },
65
65
  );
66
66
  const log = res.status === 0 ? res.stdout.split('\n').filter(Boolean) : [];
67
67
  const file = path.join(root, 'history.md');
@@ -22,7 +22,7 @@ function carriedOnce(projectDir, name) {
22
22
  '--',
23
23
  'gcf/work',
24
24
  ],
25
- { cwd: projectDir, encoding: 'utf8' },
25
+ { windowsHide: true, cwd: projectDir, encoding: 'utf8' },
26
26
  );
27
27
 
28
28
  return res.status === 0 && Boolean(res.stdout.trim());
package/lib/phase.js CHANGED
@@ -7,7 +7,7 @@ import { readConfig } from './gcf-paths.js';
7
7
  import { readLiveStrict, writeLive, liveFile } from './live.js';
8
8
  import { buildLedger } from './ledger.js';
9
9
  import { ITEM_TYPES } from './validate-item.js';
10
- import { commitMove } from './unit-ops.js';
10
+ import { commitMove } from './commit-move.js';
11
11
  import { locked } from './main-lock.js';
12
12
  import { gameMilestones } from './design-check.js';
13
13
 
package/lib/pillars.js CHANGED
@@ -9,7 +9,7 @@ import { SLUG_RE, listOf, parseDesign } from './design.js';
9
9
  import { recordsIn } from './design-check.js';
10
10
  import { buildLedger } from './ledger.js';
11
11
  import { atomicWrite } from './safe-path.js';
12
- import { commitMove } from './unit-ops.js';
12
+ import { commitMove } from './commit-move.js';
13
13
  import { locked } from './main-lock.js';
14
14
 
15
15
  const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
package/lib/play-notes.js CHANGED
@@ -72,8 +72,11 @@ export function playNotesOf(planText) {
72
72
 
73
73
  /** The lines under each `### ` heading; a heading the format lacks goes to `unknown`. */
74
74
  function partsOf(block) {
75
+ /** @type {Record<string, string[]>} */
75
76
  const parts = Object.fromEntries(Object.keys(SECTIONS).map((k) => [k, []]));
77
+ /** @type {string[]} */
76
78
  const unknown = [];
79
+ /** @type {string | null | undefined} */
77
80
  let key = null;
78
81
  for (const line of block) {
79
82
  const h = /^###\s+(.+?)\s*$/.exec(line);
@@ -165,6 +168,7 @@ export function playNotesProblems(notes, rows) {
165
168
  /** The card's notes and their warnings, from its plan in `projectDir` (main or its worktree). */
166
169
  export async function playNotesCheck(projectDir, item) {
167
170
  const dir = path.resolve(projectDir);
171
+ /** @type {ReturnType<typeof playOf>} */
168
172
  let play = null;
169
173
  try {
170
174
  play = playOf(await readConfig(path.join(dir, 'gcf')));
package/lib/play-on.js CHANGED
@@ -8,11 +8,12 @@ const FIELDS = ['play_on', 'played_on'];
8
8
  * What the cards' build names lack. A line of game.md `platforms` (the old form) or a line of
9
9
  * words is a warning until Set up translates it; one word that names no build is an error. A
10
10
  * project with no `play:` (or a broken one: its own command says so) has no names to check.
11
- * @param {{data: object}[]} items
11
+ * @param {{data: Record<string, any>}[]} items
12
12
  * @param {string[]} platforms the `platforms` lines of game.md
13
13
  * @returns {{errors: string[], warnings: string[]}}
14
14
  */
15
15
  export function playOnIssues(items, config, platforms = []) {
16
+ /** @type {{errors: string[], warnings: string[]}} */
16
17
  const issues = { errors: [], warnings: [] };
17
18
  let play;
18
19
  try {