gcf-aif-ext 0.32.0 → 0.34.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/context.js CHANGED
@@ -2,7 +2,9 @@ import { mkdir, readFile, readdir } from 'node:fs/promises';
2
2
  import { existsSync } from 'node:fs';
3
3
  import path from 'node:path';
4
4
  import { listItems, listSystems, readConfig, tokensEst } from './gcf-paths.js';
5
- import { fieldOf } from './question-fields.js';
5
+ import { buildLedger } from './ledger.js';
6
+ import { provenanceOf } from './design.js';
7
+ import { d2States, verdictMatchers } from './d2-states.js';
6
8
  import { atomicWrite } from './safe-path.js';
7
9
  import { ownerOf } from './session-mark.js';
8
10
 
@@ -20,7 +22,7 @@ export async function writeReadset(projectDir, ctx, env = process.env) {
20
22
  /**
21
23
  * Readset assembly — the whole command is deterministic (GCF-PRD §9.1, §10.1):
22
24
  * PILLARS + LIVE.md + touched systems + the item + its parent + its depends + graveyard tag hits +
23
- * D2 assumptions whose sys overlaps. Never over_budget-throws: the caller gates.
25
+ * D2 assumptions whose sys overlaps or the item cites. Never over_budget-throws: the caller gates.
24
26
  */
25
27
  export async function buildContext(projectDir, itemId) {
26
28
  const root = path.join(path.resolve(projectDir), 'gcf');
@@ -34,7 +36,7 @@ export async function buildContext(projectDir, itemId) {
34
36
  const itemText =
35
37
  `${item.data.id} ${item.data.title ?? ''} ${systems.join(' ')} ${item.body}`.toLowerCase();
36
38
  const graveyard_hits = await graveyardHits(root, itemText);
37
- const d2 = await d2Assumptions(root, systems);
39
+ const { d2, fired } = await d2Assumptions(projectDir, config, item, systems);
38
40
 
39
41
  const extraTokens = tokensEst(graveyard_hits.join('\n')) + tokensEst(d2.join('\n'));
40
42
  const total_tokens_est = files.reduce((sum, f) => sum + f.tokens_est, 0) + extraTokens;
@@ -44,6 +46,8 @@ export async function buildContext(projectDir, itemId) {
44
46
  files,
45
47
  graveyard_hits,
46
48
  d2,
49
+ // The ids in d2 whose trigger fired with no answer: the human's call now (GCF-PRD §7.3).
50
+ d2_fired: fired,
47
51
  total_tokens_est,
48
52
  budget: config.context_budget,
49
53
  over_budget: total_tokens_est > config.context_budget,
@@ -111,18 +115,27 @@ async function graveyardHits(root, itemText) {
111
115
  return hits;
112
116
  }
113
117
 
114
- /** D2 assumptions whose sys: overlaps the item's systems (GCF-PRD §9.1). */
115
- async function d2Assumptions(root, systems) {
116
- const oqFile = path.join(root, 'open-questions.md');
117
- if (!existsSync(oqFile)) return [];
118
- const records = (await readFile(oqFile, 'utf8')).split(/\n(?=- id:)/);
119
-
120
- return records
121
- .filter((rec) => /^\s*-?\s*id:/m.test(rec) && /^D2\b/.test(fieldOf(rec, 'class') ?? ''))
122
- .filter((rec) => {
123
- const sys = fieldOf(rec, 'sys') ?? '';
118
+ /**
119
+ * D2 assumptions whose sys: overlaps the item's systems (GCF-PRD §9.1), and the ones the item
120
+ * cites as `assumed: q-NNN` whatever their sys:; `fired`, the unanswered ones whose until: fired.
121
+ */
122
+ async function d2Assumptions(projectDir, config, item, systems) {
123
+ const file = path.join(path.resolve(projectDir), 'gcf', 'open-questions.md');
124
+ const text = existsSync(file) ? await readFile(file, 'utf8') : '';
125
+ // The ledger reads every design doc: built only when a D2 can fire by a verdict.
126
+ if (!/^\s*class:\s*D2\b/m.test(text)) return { d2: [], fired: [] };
127
+ const ledger = /verdict\(/.test(text) ? await buildLedger(projectDir) : null;
128
+ const states = await d2States(projectDir, {
129
+ fired: verdictMatchers(projectDir, ledger, ledger?.items ?? []),
130
+ limit: config.question_stale_after_commits,
131
+ });
132
+ const cited = new Set(provenanceOf(item.body).map((r) => r.assumed));
133
+ const picked = states.filter(
134
+ (q) => q.d2 && (cited.has(q.id) || systems.some((s) => (q.sys ?? '').includes(s))),
135
+ );
124
136
 
125
- return systems.some((s) => sys.includes(s));
126
- })
127
- .map((rec) => rec.trim());
137
+ return {
138
+ d2: picked.map((q) => q.text),
139
+ fired: picked.filter((q) => q.status === 'stale').map((q) => q.id),
140
+ };
128
141
  }
@@ -0,0 +1,208 @@
1
+ // The state and age of each record of gcf/open-questions.md, and whether an until trigger fired
2
+ // (GCF-PRD §7.3, §7.4): the audit, the board and the readset read them alike. It imports no
3
+ // work-ops.js: context.js reads it, and audit-core → work-ops → plan-check → context is a cycle.
4
+ import { readFile } from 'node:fs/promises';
5
+ import { existsSync } from 'node:fs';
6
+ import path from 'node:path';
7
+ import { spawnSync } from 'node:child_process';
8
+ import { fieldOf } from './question-fields.js';
9
+
10
+ export function git(args, cwd) {
11
+ // A blame of a long file overflows the 1 MiB default, and an overflow reads as a git failure.
12
+ const res = spawnSync('git', args, {
13
+ windowsHide: true,
14
+ cwd,
15
+ encoding: 'utf8',
16
+ maxBuffer: 64 * 1024 * 1024,
17
+ });
18
+
19
+ return res.status === 0 ? res.stdout.trim() : null;
20
+ }
21
+
22
+ export const UNTIL_RE =
23
+ /\[until:\s*(verdict\([a-z0-9-]+\)|retune\([a-z0-9-]+\)|manual\([^)]*\))\]/g;
24
+ const D2_UNTIL_RE = /^(verdict\([a-z0-9-]+\)|retune\([a-z0-9-]+\)|manual\([^)]*\))/;
25
+ // The two markers GCF writes itself (systems-doc.js purposeLines, gcf-adopt): no human's manual().
26
+ export const PLACEHOLDER_RE = /\[until:\s*manual\((?:purpose of|first verdict touching) [^)]+\)\]/;
27
+ const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
28
+ // An uncommitted line blames to the all-zero hash: it is new, not old.
29
+ const isUncommitted = (hash) => /^0+$/.test(hash);
30
+
31
+ /**
32
+ * Each line of `rel` with the commit that last changed it beyond whitespace (-w: a respaced or
33
+ * re-ended CRLF/LF line keeps the commit that wrote it), or null for an untracked file or
34
+ * outside a repository.
35
+ */
36
+ export function blameLines(projectDir, rel) {
37
+ const blame = git(['blame', '-w', '--porcelain', '--', rel], projectDir);
38
+ if (blame === null) return null;
39
+ const lines = [];
40
+ let hash = '';
41
+ for (const line of blame.split('\n')) {
42
+ const head = line.match(/^([0-9a-f]{40,64}) \d+ \d+/);
43
+ if (head) hash = head[1];
44
+ else if (line.startsWith('\t')) lines.push({ hash, text: line.slice(1).replace(/\r$/, '') });
45
+ }
46
+
47
+ return lines;
48
+ }
49
+
50
+ /** Commits since `hash`, memoized; null when the ref no longer resolves. */
51
+ function commitsSince(projectDir) {
52
+ const ages = new Map();
53
+
54
+ return (hash) => {
55
+ if (!ages.has(hash)) {
56
+ const raw = git(['rev-list', '--count', `${hash}..HEAD`], projectDir);
57
+ // Number(null) is 0, "fresh" — the one answer that must never be guessed.
58
+ ages.set(hash, raw === null ? null : Number(raw));
59
+ }
60
+
61
+ return ages.get(hash);
62
+ };
63
+ }
64
+
65
+ /**
66
+ * Whether a verdict fired. `verdict(id)` reads the files, as the ledger does (GCF-PRD §5.8): a
67
+ * keep or kill left a history or graveyard line, a tune left the item's tune_count. `retune(sys,
68
+ * birth)` reads the tune verdicts' subjects after `birth`, the commit that wrote the record: a
69
+ * tune before it is the one the record already knows. An uncommitted record is new, so open.
70
+ * With no birth (no blame: no repository, an untracked file) it guesses as before: an item of
71
+ * the subsystem with a tune_count, or any tune in the log.
72
+ */
73
+ export function verdictMatchers(projectDir, ledger, items) {
74
+ const tuned = items.filter((c) => (c.data.tune_count ?? 0) > 0);
75
+ const logs = new Map();
76
+ const verdictLog = (birth) => {
77
+ if (!logs.has(birth)) {
78
+ const range = birth ? [`${birth}..HEAD`] : [];
79
+ const args = ['log', '--basic-regexp', '--grep', '^gcf(verdict):', '--format=%s', ...range];
80
+ logs.set(birth, git(args, projectDir) ?? '');
81
+ }
82
+
83
+ return logs.get(birth);
84
+ };
85
+
86
+ // `tune <id> → <sys>,<sys>` and maybe ` (played on: …)` (work-ops.js verdictItemUnlocked).
87
+ const tuneOf = (system) =>
88
+ new RegExp(`^gcf\\(verdict\\): tune .*→ (?:\\S*,)?${escapeRe(system)}(?:,| \\(|$)`, 'm');
89
+
90
+ return {
91
+ verdict: (id) =>
92
+ ledger.where(id).terminal.some((t) => t !== 'done') || tuned.some((c) => c.data.id === id),
93
+ /** @param {string} system @param {string} [birth] */
94
+ retune: (system, birth) => {
95
+ if (birth) return !isUncommitted(birth) && tuneOf(system).test(verdictLog(birth));
96
+
97
+ return (
98
+ tuned.some((c) => (c.data.system ?? []).includes(system)) ||
99
+ tuneOf(system).test(verdictLog(birth))
100
+ );
101
+ },
102
+ };
103
+ }
104
+
105
+ /**
106
+ * A question as the board and its Design screen show it: an unanswered D2 whose trigger fired
107
+ * (`fired`), or of `manual(...)` or no trigger past the age limit (`aged`, `commits` its age), is
108
+ * the Operator's decision now (Until-Records-Plan d3). An agent writes every question record:
109
+ * its origin is one.
110
+ */
111
+ export function questionRow(q, state) {
112
+ const fired = state?.status === 'stale';
113
+ const aged = Boolean(state?.d2 && state.aged);
114
+ const decision = /^D1\b/.test(q.class ?? '') || fired || aged;
115
+
116
+ return {
117
+ ...q,
118
+ category: decision ? 'decision' : 'assumption',
119
+ origin: 'agent',
120
+ fired,
121
+ aged,
122
+ ...(aged && { commits: state.commits }),
123
+ };
124
+ }
125
+
126
+ /** `stale` (fired), `open` or `manual`; `birth` as for retune. */
127
+ export function untilStatus(trigger, fired, birth) {
128
+ if (trigger.startsWith('verdict(')) {
129
+ return fired.verdict(trigger.slice(8, -1)) ? 'stale' : 'open';
130
+ }
131
+
132
+ if (trigger.startsWith('retune(')) {
133
+ return fired.retune(trigger.slice(7, -1), birth) ? 'stale' : 'open';
134
+ }
135
+
136
+ return 'manual';
137
+ }
138
+
139
+ /**
140
+ * Every record of open-questions.md with its state: `trigger` a D2's until (null for a D1 or
141
+ * none); `status` a D2's `answered`, `stale`, `open` or `manual` (null for a D1 or no trigger);
142
+ * `commits` since the commit that wrote its `- id:` line (undefined with no such commit: an
143
+ * uncommitted record, no blame; null when that commit no longer resolves); `aged` an unanswered
144
+ * record the human owes past `limit` commits — a D1, or a D2 with `manual(...)` or no trigger
145
+ * (GCF-PRD §7.4): an acting D2 waits for its trigger, a fired one is a stale until record.
146
+ * shortcut: a blame, a git log and a rev-list per call, the board's included; cache by HEAD
147
+ * when the board's refresh feels it.
148
+ */
149
+ export async function d2States(projectDir, { fired, limit }) {
150
+ const file = path.join(path.resolve(projectDir), 'gcf', 'open-questions.md');
151
+ if (!existsSync(file)) return [];
152
+ const text = noBom(await readFile(file, 'utf8')).replace(/\r\n/g, '\n');
153
+ const at = { fired, limit, births: birthsOf(projectDir), since: commitsSince(projectDir) };
154
+
155
+ return text.split(/\n(?=- id:)/).flatMap((rec) => {
156
+ const id = rec.match(/^- id:\s*(\S+)/)?.[1];
157
+
158
+ return id ? [recordState(id, rec, at)] : [];
159
+ });
160
+ }
161
+
162
+ const BOM = String.fromCharCode(0xfeff);
163
+ const noBom = (s) => (s.startsWith(BOM) ? s.slice(1) : s);
164
+
165
+ /** The commit that wrote each record's `- id:` line, or null without a blame. */
166
+ function birthsOf(projectDir) {
167
+ const blamed = blameLines(projectDir, 'gcf/open-questions.md');
168
+ if (!blamed) return null;
169
+ const births = new Map();
170
+ for (const { hash, text } of blamed) {
171
+ const id = noBom(text).match(/^- id:\s*(\S+)/)?.[1];
172
+ if (id) births.set(id, hash);
173
+ }
174
+
175
+ return births;
176
+ }
177
+
178
+ function recordState(id, rec, { fired, limit, births, since }) {
179
+ const d2 = /^D2\b/.test(fieldOf(rec, 'class') ?? '');
180
+ const answered = Boolean(fieldOf(rec, 'answer'));
181
+ const trigger = d2 ? triggerOf(rec) : null;
182
+ // No blame: no birth, retune as before; a record the blame does not show is uncommitted.
183
+ const birth = births ? (births.get(id) ?? '0') : undefined;
184
+ const status = statusOf({ d2, answered, trigger }, fired, birth);
185
+ const commits = birth && !isUncommitted(birth) ? since(birth) : undefined;
186
+ const owed = !answered && (!trigger || status === 'manual');
187
+
188
+ return {
189
+ id,
190
+ d2,
191
+ trigger,
192
+ status,
193
+ commits,
194
+ aged: owed && isOld(commits, limit),
195
+ sys: fieldOf(rec, 'sys'),
196
+ text: rec.trim(),
197
+ };
198
+ }
199
+
200
+ const triggerOf = (rec) => fieldOf(rec, 'until')?.match(D2_UNTIL_RE)?.[1] ?? null;
201
+ // No commit to age from is fresh; a commit that no longer resolves is never guessed fresh.
202
+ const isOld = (commits, limit) => commits !== undefined && (commits === null || commits > limit);
203
+
204
+ function statusOf({ d2, answered, trigger }, fired, birth) {
205
+ if (d2 && answered) return 'answered';
206
+
207
+ return trigger ? untilStatus(trigger, fired, birth) : null;
208
+ }
@@ -44,7 +44,7 @@ import { buildLedger } from './ledger.js';
44
44
  import { deriveId } from './id.js';
45
45
  import { renamePillar } from './pillars.js';
46
46
  import { dirtyPaths, restoreFromHead } from './git.js';
47
- import { blocksOf, putBlock } from './systems-doc.js';
47
+ import { blocksOf, fillPurpose, purposeTarget, putBlock } from './systems-doc.js';
48
48
 
49
49
  // The work stage writes these blocks: a unit in design/ has not reached them.
50
50
  const WORK_ONLY = ['contract', 'interactions', 'tuning', 'notes'];
@@ -556,6 +556,27 @@ const noteOf = (p) =>
556
556
  // Nothing of the bundle applied: no commit to make.
557
557
  class NothingApplied extends Error {}
558
558
 
559
+ /**
560
+ * The subsystems of the design/<s>.md among `files` whose systems doc still waits on its purpose
561
+ * and gets it from this move (fillPurpose), each with that doc. `parts`: a bundle's, whose system
562
+ * part is the purpose the move is about to write.
563
+ * @param {string} root
564
+ * @param {string[]} files
565
+ * @param {{kind: string, name: string, text: string}[]} [parts]
566
+ */
567
+ async function purposeFills(root, files, parts = []) {
568
+ const fills = new Map();
569
+ for (const f of files) {
570
+ const s = path.basename(f, '.md');
571
+ if (path.dirname(f) !== path.join(root, 'design') || !SLUG_RE.test(s) || fills.has(s)) continue;
572
+ const part = parts.find((p) => p.kind === 'system' && p.name === s);
573
+ const doc = await purposeTarget(root, s, part?.text);
574
+ if (doc) fills.set(s, doc);
575
+ }
576
+
577
+ return fills;
578
+ }
579
+
559
580
  /**
560
581
  * Bring `text` in through the import and commit what it wrote. `strict`: a part the import
561
582
  * reports refuses the whole move. Files with changes not recorded yet refuse it up front: the
@@ -573,8 +594,9 @@ async function bundleMove(
573
594
  { key, items = [], strict = false, draft = false, commit = true },
574
595
  ) {
575
596
  const root = path.join(path.resolve(projectDir), 'gcf');
597
+ const { parts } = parseBundle(text);
576
598
  // Only the names a write may take (bundle.js validName): no other path gets staged.
577
- const files = parseBundle(text).parts.flatMap((p) => {
599
+ const files = parts.flatMap((p) => {
578
600
  if (p.kind === 'doc')
579
601
  return Object.hasOwn(DOC_FILES, p.name) ? [path.join(root, DOC_FILES[p.name])] : [];
580
602
  const sys = p.kind === 'system' ? p.name : p.system;
@@ -583,7 +605,8 @@ async function bundleMove(
583
605
  ? [path.join(root, 'design', `${sys}.md`)]
584
606
  : [];
585
607
  });
586
- const touched = [...new Set([...files, path.join(root, 'backlog.md')])];
608
+ const fills = await purposeFills(root, files, parts);
609
+ const touched = [...new Set([...files, path.join(root, 'backlog.md'), ...fills.values()])];
587
610
  const rel = (f) => path.relative(path.resolve(projectDir), f).replaceAll('\\', '/');
588
611
  // A form's save over an agent's draft of its own file takes the draft along (decision 35): the
589
612
  // operator saw it in the form. Another file's changes would ride along unseen.
@@ -611,6 +634,7 @@ async function bundleMove(
611
634
  if (strict && refused.length)
612
635
  throw new Error(refused.map((p) => `${p.outcome} ${p.part}: ${noteOf(p)}`).join('\n'));
613
636
  if (!result.applied.length) throw new NothingApplied();
637
+ for (const s of fills.keys()) await fillPurpose(root, s);
614
638
  },
615
639
  });
616
640
 
@@ -690,16 +714,21 @@ async function commitUnlocked(projectDir, { message = null, commit = true } = {}
690
714
  }
691
715
 
692
716
  const abs = files.map((f) => path.join(path.resolve(projectDir), f));
717
+ const root = path.join(path.resolve(projectDir), 'gcf');
718
+ const fills = await purposeFills(root, abs);
693
719
  const why = oneLine(message) || 'record the design';
694
720
  const hash = await commitMove(projectDir, `gcf(design): ${why}`, {
695
- files: abs,
721
+ files: [...abs, ...fills.values()],
696
722
  inputs: abs,
697
- mutate: async () => {},
723
+ mutate: async () => {
724
+ for (const s of fills.keys()) await fillPurpose(root, s);
725
+ },
698
726
  commit,
699
727
  key: 'design-commit',
700
728
  });
729
+ const rel = (f) => path.relative(path.resolve(projectDir), f).replaceAll('\\', '/');
701
730
 
702
- return { files, hash };
731
+ return { files: [...files, ...[...fills.values()].map(rel)], hash };
703
732
  }
704
733
 
705
734
  // What an agent's draft writes (decision 35), and so what `design discard` may take back: not an
@@ -760,7 +789,8 @@ export async function designState(projectDir, { report, questions, items }) {
760
789
  const units = new Set(report.units.map((u) => u.id));
761
790
  const sources = await sourcesOf(root);
762
791
  const asked = questions.filter((q) => isDesignQuestion(q, units));
763
- const open = asked.filter((q) => /^D1\b/.test(q.class ?? '') && !q.answer);
792
+ // The board's rows (d2-states.js questionRow): a fired or aged D2 waits on the Operator too.
793
+ const open = asked.filter((q) => q.category === 'decision' && !q.answer);
764
794
  const pillars = recordsIn(pillarsText, 'pillars').map((p) => ({
765
795
  id: p.id ?? null,
766
796
  // The few words the operator knows it by (decision 34); an old file has none.
package/lib/git.js CHANGED
@@ -119,7 +119,18 @@ export const GATE_SCOPE = [
119
119
  export function dirtyGcf(projectDir, skip = []) {
120
120
  const res = spawnSync(
121
121
  'git',
122
- ['-c', 'core.quotePath=false', 'status', '--porcelain', '-z', '-uall', '--', ...GATE_SCOPE],
122
+ // No index.lock: a move waiting behind a run asks this each second, and would break its commit.
123
+ [
124
+ '--no-optional-locks',
125
+ '-c',
126
+ 'core.quotePath=false',
127
+ 'status',
128
+ '--porcelain',
129
+ '-z',
130
+ '-uall',
131
+ '--',
132
+ ...GATE_SCOPE,
133
+ ],
123
134
  { windowsHide: true, cwd: projectDir, encoding: 'utf8' },
124
135
  );
125
136
  if (res.status !== 0) return [];
@@ -152,12 +163,16 @@ export function dirtyGcf(projectDir, skip = []) {
152
163
 
153
164
  /**
154
165
  * The refusal of a move that uncommitted gcf/ edits stop: `dirty` with `paths` (dirtyGcf) when
155
- * there are any, so a board offers to show, commit or discard them; else the words alone.
166
+ * there are any, so a board offers to show, commit or discard them; else the words alone. `move`
167
+ * names the move it stops: one that waits behind a main run says it (lib/main-lock.js).
156
168
  * @param {string[]} paths
157
169
  * @param {string} message
170
+ * @param {{message: string, items?: string[]}} move
158
171
  */
159
- export const dirtyRefusal = (paths, message) =>
160
- paths.length ? refusal('dirty', { paths }, message) : new Error(message);
172
+ export const dirtyRefusal = (paths, message, move) =>
173
+ Object.assign(paths.length ? refusal('dirty', { paths }, message) : new Error(message), {
174
+ move: { ...move, items: move.items ?? [] },
175
+ });
161
176
 
162
177
  /** A path from the project with `/`, from an absolute one or one already relative. */
163
178
  const relOf = (projectDir, p) =>
@@ -288,7 +303,12 @@ export function commitPaths(projectDir, message, paths, move = {}) {
288
303
  // nothing: no pathspec.
289
304
  const real = paths.filter((p) => existsSync(p) || inHead(projectDir, p));
290
305
 
291
- return commitOnly(projectDir, message, real, ['-m', message, ...moveTrailers(move)]);
306
+ try {
307
+ return commitOnly(projectDir, message, real, ['-m', message, ...moveTrailers(move)]);
308
+ } catch (e) {
309
+ if (e.move) e.move.items = move.items ?? [];
310
+ throw e;
311
+ }
292
312
  }
293
313
 
294
314
  /**
@@ -327,6 +347,7 @@ export function commitOnly(projectDir, message, paths, msg) {
327
347
  loose,
328
348
  `cannot record ${message} while gcf/ holds uncommitted changes: ${loose.join(', ')} — ` +
329
349
  'commit or discard them, then try again',
350
+ { message },
330
351
  );
331
352
  }
332
353
 
package/lib/main-lock.js CHANGED
@@ -4,13 +4,28 @@
4
4
  // holds it across the merge and the move it records.
5
5
  import { AsyncLocalStorage } from 'node:async_hooks';
6
6
  import { link, mkdir, readFile, stat, unlink, writeFile } from 'node:fs/promises';
7
- import { readFileSync } from 'node:fs';
7
+ import {
8
+ existsSync,
9
+ mkdirSync,
10
+ readdirSync,
11
+ readFileSync,
12
+ renameSync,
13
+ rmSync,
14
+ writeFileSync,
15
+ } from 'node:fs';
8
16
  import { randomUUID } from 'node:crypto';
9
17
  import path from 'node:path';
18
+ // Not `process.stdin.isTTY`: reading it opens stdin, which may keep a piped command alive.
19
+ import { isatty } from 'node:tty';
20
+ import { dirtyGcf, moveBy } from './git.js';
21
+ import { refusal } from './refusal.js';
10
22
 
11
23
  const chain = new AsyncLocalStorage();
12
24
  const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
13
25
 
26
+ /** How often a move waiting behind a main run looks at gcf/, and how long a claim yields to one. */
27
+ export const waitTiming = { pollMs: 1000, yieldMs: 5000 };
28
+
14
29
  export const lockFile = (projectDir) =>
15
30
  path.join(path.resolve(projectDir), '.gcf-session', 'main.lock');
16
31
 
@@ -179,10 +194,187 @@ async function clearStale(file, text) {
179
194
  * @returns {Promise<T>}
180
195
  */
181
196
  export async function withMainLock(projectDir, fn, { waitMs = 60000 } = {}) {
182
- const file = lockFile(projectDir);
183
197
  const held = chain.getStore() ?? new Set();
184
- if (held.has(file)) return fn();
198
+ if (held.has(lockFile(projectDir))) return fn();
199
+ const once = () => holding(projectDir, held, fn, waitMs);
200
+ if (!mayWait()) return once();
201
+
202
+ // The operator's move stopped by a main run's gcf/ edits waits for them, without the lock (the
203
+ // run's own moves need it), then goes again from its first read (docs/Main-Run-Moves-Plan.md).
204
+ const wait = waiter(projectDir);
205
+ try {
206
+ for (;;) {
207
+ try {
208
+ return await once();
209
+ } catch (e) {
210
+ await wait(e);
211
+ }
212
+ }
213
+ } finally {
214
+ wait.end();
215
+ }
216
+ }
217
+
218
+ /**
219
+ * Only the operator waits, from a terminal or a board that knows its move (`GCF_MOVE_TAG`): a
220
+ * session's or a script's command is killed by its caller's timeout, maybe mid-commit.
221
+ */
222
+ const mayWait = () => moveBy() === 'operator' && (isatty(0) || Boolean(process.env.GCF_MOVE_TAG));
223
+
224
+ const TOKEN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
225
+
226
+ /**
227
+ * The card a live main run works now; null with none, or when the lock holds the token of a
228
+ * build, a push or a play: their edits are no run's that a commit of it would clear.
229
+ */
230
+ function mainRunCard(projectDir) {
231
+ try {
232
+ const file = path.join(path.resolve(projectDir), '.gcf-session', 'runs', `${MAIN_RUN}.lock`);
233
+ const [pid, item] = readFileSync(file, 'utf8')
234
+ .split('\n')
235
+ .map((s) => s.trim());
236
+ const n = Number(pid);
237
+
238
+ return item && !TOKEN.test(item) && n > 0 && n !== process.pid && alive(n) ? item : null;
239
+ } catch {
240
+ return null;
241
+ }
242
+ }
185
243
 
244
+ const waitingDir = (projectDir) => path.join(path.resolve(projectDir), '.gcf-session', 'waiting');
245
+
246
+ /**
247
+ * The records of moves waiting behind a main run (`.gcf-session/waiting/<pid>.json`), each with
248
+ * its `pid` and `file`. A record whose process died is left over: it is removed, not listed.
249
+ * @returns {Array<{pid: number, file: string, message?: string, items?: string[],
250
+ * tag?: string | null, behind?: string, paths?: string[], cancel?: string, going?: boolean}>}
251
+ */
252
+ export function liveWaiting(projectDir) {
253
+ const dir = waitingDir(projectDir);
254
+ let names;
255
+ try {
256
+ names = readdirSync(dir);
257
+ } catch {
258
+ return [];
259
+ }
260
+
261
+ return names.flatMap((name) => {
262
+ const pid = Number(/^(\d+)\.json$/.exec(name)?.[1]);
263
+ if (!pid) return [];
264
+ const file = path.join(dir, name);
265
+ if (!alive(pid)) {
266
+ rmSync(file, { force: true });
267
+
268
+ return [];
269
+ }
270
+
271
+ try {
272
+ return [{ ...JSON.parse(readFileSync(file, 'utf8')), pid, file }];
273
+ } catch {
274
+ return [];
275
+ }
276
+ });
277
+ }
278
+
279
+ /**
280
+ * The wait of one move: `wait(e)` rethrows a failure that is no main run's `dirty` refusal;
281
+ * else it keeps its record, tells once, and resolves when the refusal's paths are clean. It
282
+ * rethrows the refusal when the run is gone, and refuses on a cancel file. Its record says
283
+ * `going` once the paths cleared and the move goes again. `wait.end()` removes the record and
284
+ * the cancel file, on every way out of the move.
285
+ */
286
+ function waiter(projectDir) {
287
+ const dir = waitingDir(projectDir);
288
+ const record = path.join(dir, `${process.pid}.json`);
289
+ const cancel = process.env.GCF_MOVE_CANCEL || path.join(dir, `${process.pid}.cancel`);
290
+ let told = false;
291
+
292
+ /** @param {any} e */
293
+ const wait = async (e) => {
294
+ const card = e?.refusal?.code === 'dirty' ? mainRunCard(projectDir) : null;
295
+ if (!card) throw e;
296
+ const { paths } = e.refusal;
297
+ const { message = 'the move', items = [] } = e.move ?? {};
298
+ const tag = process.env.GCF_MOVE_TAG || null;
299
+ const keep = (going = false) => {
300
+ // Whole or not at all: a reader never parses half a record.
301
+ writeFileSync(
302
+ `${record}.tmp`,
303
+ JSON.stringify({ message, items, tag, behind: card, paths, cancel, going }),
304
+ );
305
+ renameSync(`${record}.tmp`, record);
306
+ };
307
+
308
+ mkdirSync(dir, { recursive: true });
309
+ if (!told) {
310
+ // A cancel a dead move of this pid left behind is no cancel of this one.
311
+ rmSync(cancel, { force: true });
312
+ }
313
+
314
+ keep();
315
+ if (!told) {
316
+ told = true;
317
+ process.stderr.write(
318
+ `${message} waits: the run of ${card} holds gcf/ edits (${paths.join(', ')}); it goes ` +
319
+ 'when they are committed. Nothing is written while it waits.\n' +
320
+ `gcf-waiting: ${JSON.stringify({ behind: card, paths })}\n`,
321
+ );
322
+ }
323
+
324
+ if (!(await cleared(card, paths, message))) throw e;
325
+ // It goes again: a Cancel from now on comes too late (the board answers "already recorded").
326
+ keep(true);
327
+ };
328
+
329
+ /** True once `paths` are clean, false when the run is gone with them still dirty. */
330
+ const cleared = async (card, paths, message) => {
331
+ // shortcut: one `git status` a second per waiting move, cheap for a few; watch gcf/ when
332
+ // many moves wait at once.
333
+ for (;;) {
334
+ await sleep(waitTiming.pollMs);
335
+ if (existsSync(cancel)) {
336
+ rmSync(cancel, { force: true });
337
+ throw refusal(
338
+ 'cancelled',
339
+ {},
340
+ `${message}: cancelled while it waited behind the run of ${card} — nothing was recorded`,
341
+ );
342
+ }
343
+
344
+ const dirty = new Set(dirtyGcf(projectDir));
345
+ if (!paths.some((p) => dirty.has(p))) return true;
346
+ // Gone with its edits left: they are no run's now, and today's refusal names them.
347
+ if (!mainRunCard(projectDir)) return false;
348
+ }
349
+ };
350
+
351
+ // A cancel that came as it went is no cancel of a later move under the same pid.
352
+ wait.end = () => {
353
+ rmSync(record, { force: true });
354
+ rmSync(cancel, { force: true });
355
+ };
356
+
357
+ return wait;
358
+ }
359
+
360
+ /**
361
+ * A card's claim lets a waiting move go first (docs/Main-Run-Moves-Plan.md d4): after a run's
362
+ * last commit gcf/ is clean, and a claim would soil it again before the move's next look. Only
363
+ * when every waiting move's paths are clean already, and for `waitTiming.yieldMs` at most.
364
+ */
365
+ export async function yieldToWaiting(projectDir) {
366
+ const waits = liveWaiting(projectDir);
367
+ if (!waits.length) return;
368
+ const dirty = new Set(dirtyGcf(projectDir));
369
+ if (waits.some((w) => (w.paths ?? []).some((p) => dirty.has(p)))) return;
370
+ const until = Date.now() + waitTiming.yieldMs;
371
+ while (Date.now() < until && waits.some((w) => existsSync(w.file) && alive(w.pid)))
372
+ await sleep(100);
373
+ }
374
+
375
+ /** Take the main lock, run `fn` under it, let it go. */
376
+ async function holding(projectDir, held, fn, waitMs) {
377
+ const file = lockFile(projectDir);
186
378
  await mkdir(path.dirname(file), { recursive: true });
187
379
  const token = randomUUID();
188
380
  const until = Date.now() + waitMs;