gcf-aif-ext 0.18.9 → 0.20.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.
@@ -1,5 +1,8 @@
1
1
  import { spawnSync } from 'node:child_process';
2
+ import { existsSync } from 'node:fs';
3
+ import { readFile } from 'node:fs/promises';
2
4
  import path from 'node:path';
5
+ import { gameMilestones } from './design-check.js';
3
6
  import { listItems, scalarOf, readConfig, firstBullet } from './gcf-paths.js';
4
7
  import { recordsOf } from './verdict-fs.js';
5
8
  import { runDod } from './verify.js';
@@ -20,11 +23,39 @@ function feelOf(body) {
20
23
  return [...feel, ...rates];
21
24
  }
22
25
 
26
+ /** The bullets of a `key:` block of a CNL-P body, each trimmed; none when it has no block. */
27
+ export function bulletsOf(body, key) {
28
+ const lines = String(body ?? '').split(/\r?\n/);
29
+ const at = lines.findIndex((l) => new RegExp(`^${key}:\\s*$`).test(l));
30
+ if (at < 0) return [];
31
+ const out = [];
32
+ for (const l of lines.slice(at + 1)) {
33
+ const m = l.match(/^- (.+)$/);
34
+ if (!m) break;
35
+ out.push(m[1].trim());
36
+ }
37
+
38
+ return out;
39
+ }
40
+
41
+ /**
42
+ * Where the game is played (docs/Autonomy-Plan.md, C): the `platforms` lines of game.md, one
43
+ * platform and input each. A hint for the operator, never a gate.
44
+ */
45
+ export async function platformsOf(root) {
46
+ const file = path.join(root, 'game.md');
47
+
48
+ return existsSync(file) ? bulletsOf(await readFile(file, 'utf8'), 'platforms') : [];
49
+ }
50
+
23
51
  /**
24
52
  * Playtest list (Methodology §5.3): every item waiting for its verdict, and every unplayed one,
25
- * with the question the play must answer.
53
+ * with the question the play must answer, its milestone and where to play it (`play_on`, else
54
+ * every line of `platforms`).
26
55
  */
27
56
  export async function playtestList(root) {
57
+ const platforms = await platformsOf(root);
58
+
28
59
  return (await listItems(root))
29
60
  .filter((c) => ['awaiting-verdict', 'unplayed'].includes(c.data.status))
30
61
  .map((c) => ({
@@ -32,6 +63,8 @@ export async function playtestList(root) {
32
63
  title: c.data.title ?? null,
33
64
  status: c.data.status,
34
65
  system: c.data.system ?? [],
66
+ milestone: c.data.milestone ?? null,
67
+ play_on: c.data.play_on ?? platforms,
35
68
  question: scalarOf(c.body, 'miss_criterion') || '(miss_criterion is empty)',
36
69
  reach: recordsOf(c.body, 'behavior')
37
70
  .map((r) => r.input)
@@ -70,9 +103,22 @@ export async function playtestSession(
70
103
  { build = false, stdio = ['ignore', 2, 2] } = {},
71
104
  ) {
72
105
  const root = path.join(path.resolve(projectDir), 'gcf');
106
+ const milestones = (await gameMilestones(root)) ?? [];
107
+ // Milestones in game.md's order, then the items with none (or one game.md no longer has).
108
+ const rank = (m) => {
109
+ const at = milestones.findIndex((x) => x.name === m);
110
+
111
+ return at < 0 ? milestones.length : at;
112
+ };
113
+
73
114
  const items = (await playtestList(root)).sort(
74
- (a, b) => (a.system[0] ?? '').localeCompare(b.system[0] ?? '') || a.id.localeCompare(b.id),
115
+ (a, b) =>
116
+ rank(a.milestone) - rank(b.milestone) ||
117
+ (a.system[0] ?? '').localeCompare(b.system[0] ?? '') ||
118
+ a.id.localeCompare(b.id),
75
119
  );
120
+ const all = await listItems(root);
121
+ const waiting = new Set(items.map((i) => i.milestone));
76
122
  // gcf/.metrics changes on every audit and context run: it does not make the build differ.
77
123
  const dirty = git(projectDir, ['status', '--porcelain', '--', '.', ':(exclude)gcf/.metrics']);
78
124
  const session = {
@@ -87,6 +133,22 @@ export async function playtestSession(
87
133
  // No commit (no repository, or none yet): the build is unknown, not clean.
88
134
  dirty: dirty === null ? null : Boolean(dirty),
89
135
  build: /** @type {Awaited<ReturnType<typeof runDod>> | null} */ (null),
136
+ // Each milestone with something to play: its goal, the question its play answers, and how
137
+ // much of it is still being built or blocked.
138
+ milestones: milestones
139
+ .filter((m) => waiting.has(m.name))
140
+ .map((m) => {
141
+ const own = all.filter((c) => c.data.milestone === m.name);
142
+ const count = (...s) => own.filter((c) => s.includes(c.data.status)).length;
143
+
144
+ return {
145
+ ...m,
146
+ to_play: count('awaiting-verdict', 'unplayed'),
147
+ building: count('ready'),
148
+ blocked: count('blocked', 'awaiting-decision'),
149
+ };
150
+ }),
151
+ platforms: await platformsOf(root),
90
152
  items,
91
153
  decisions: await decisionList(root),
92
154
  };
package/lib/questions.js CHANGED
@@ -124,3 +124,80 @@ async function answerUnlocked(projectDir, qid, answer, { commit = true } = {}) {
124
124
 
125
125
  return { id: qid, answer: text, hash };
126
126
  }
127
+
128
+ /** The next free `q-NNN` of a file's text: one past the highest number it holds. */
129
+ export function nextQuestionId(text) {
130
+ const top = Math.max(0, ...recordsOf(text).map((r) => Number(r.id.match(/^q-(\d+)$/)?.[1] ?? 0)));
131
+
132
+ return `q-${String(top + 1).padStart(3, '0')}`;
133
+ }
134
+
135
+ const oneLine = (v) =>
136
+ String(v ?? '')
137
+ .replace(/\s+/g, ' ')
138
+ .trim();
139
+
140
+ /**
141
+ * The file's text with a new record appended: `class` D1 or D2 and its fields, each one line.
142
+ * @param {string} text
143
+ * @param {Record<string, string | null | undefined>} fields
144
+ */
145
+ function withRecord(text, fields) {
146
+ const id = nextQuestionId(text);
147
+ const lines = [`- id: ${id}`];
148
+ for (const k of ['class', ...FIELDS.filter((f) => f !== 'class')])
149
+ if (oneLine(fields[k])) lines.push(` ${k}: ${oneLine(fields[k])}`);
150
+ const eol = text.includes('\r\n') ? '\r\n' : '\n';
151
+ const head = text ? text.replace(/(\r?\n)*$/, eol) : `# Open questions${eol}${eol}`;
152
+
153
+ return { id, text: head + lines.join(eol) + eol };
154
+ }
155
+
156
+ /**
157
+ * Append the records `records` to gcf/open-questions.md now, for a move that carries them in
158
+ * its own commit (`assume`): the ids they got.
159
+ * @param {string} root the gcf/ dir
160
+ * @param {Record<string, string | null | undefined>[]} records
161
+ */
162
+ export async function appendQuestions(root, records) {
163
+ const file = fileOf(root);
164
+ let text = existsSync(file) ? await readFile(file, 'utf8') : '';
165
+ const ids = [];
166
+ for (const r of records) {
167
+ if (!['D1', 'D2'].includes(r.class)) throw new Error('a question record is class D1 or D2');
168
+ if (!oneLine(r.question)) throw new Error('a question record needs its question');
169
+ const next = withRecord(text, r);
170
+ ids.push(next.id);
171
+ text = next.text;
172
+ }
173
+
174
+ if (records.length) await atomicWrite(file, text);
175
+
176
+ return ids;
177
+ }
178
+
179
+ /** The file a move carrying question records touches. */
180
+ export const questionsFile = fileOf;
181
+
182
+ /**
183
+ * An agent files a question (D1, `blocks` the units it holds) or its assumption (D2, `assumed`
184
+ * the value it took): one record, commit `gcf(question): <q-id>`.
185
+ * @type {typeof addQuestionUnlocked}
186
+ */
187
+ export const addQuestion = (projectDir, record, opts = {}) =>
188
+ locked(projectDir, opts.commit ?? true, () => addQuestionUnlocked(projectDir, record, opts));
189
+
190
+ async function addQuestionUnlocked(projectDir, record, { commit = true } = {}) {
191
+ const root = path.join(path.resolve(projectDir), 'gcf');
192
+ const file = fileOf(root);
193
+ // Under the move's lock: the id the file gives now is the one the record gets.
194
+ const id = nextQuestionId(existsSync(file) ? await readFile(file, 'utf8') : '');
195
+ const hash = await commitMove(projectDir, `gcf(question): ${id}`, {
196
+ files: [file],
197
+ mutate: () => appendQuestions(root, [record]),
198
+ commit,
199
+ key: 'question-add',
200
+ });
201
+
202
+ return { id, hash };
203
+ }
package/lib/refusal.js ADDED
@@ -0,0 +1,27 @@
1
+ // A refusal a board can act on (Rich-Chat-Plan §5): the words for people, then one machine line
2
+ // `gcf-refusal: {"code":…}` at the end of the message. The CLI prints an unhandled error whole,
3
+ // so the line reaches stderr with no wrapper around the commands; a board reads its last such
4
+ // line instead of parsing the words, which change.
5
+
6
+ export const REFUSAL_LINE = 'gcf-refusal: ';
7
+
8
+ /**
9
+ * An Error whose message ends with the machine line, with the same data in `refusal`. Paths go
10
+ * with `/` on every system (a board matches them against its own).
11
+ * @param {string} code
12
+ * @param {{paths?: string[]} & Record<string, unknown>} data
13
+ * @param {string} message
14
+ */
15
+ export function refusal(code, data, message) {
16
+ const body = {
17
+ code,
18
+ ...data,
19
+ ...(data.paths && { paths: data.paths.map((p) => p.replaceAll('\\', '/')) }),
20
+ };
21
+ const err = /** @type {Error & {refusal: typeof body}} */ (
22
+ new Error(`${message}\n${REFUSAL_LINE}${JSON.stringify(body)}`)
23
+ );
24
+ err.refusal = body;
25
+
26
+ return err;
27
+ }
package/lib/safe-path.js CHANGED
@@ -1,5 +1,6 @@
1
- import { readFile, writeFile, rename, mkdir, unlink } from 'node:fs/promises';
1
+ import { readFile, writeFile, rename, mkdir, unlink, rm } from 'node:fs/promises';
2
2
  import path from 'node:path';
3
+ import { setTimeout as sleep } from 'node:timers/promises';
3
4
  import { snapshotIndex, restoreIndex } from './git.js';
4
5
 
5
6
  /**
@@ -25,6 +26,23 @@ export function resolveInside(projectDir, target) {
25
26
  return resolved;
26
27
  }
27
28
 
29
+ // Windows refuses a rename over a file another process holds open for a moment (antivirus,
30
+ // indexer); without a retry a rollback stops halfway and leaves gcf/ half-written.
31
+ const BUSY = new Set(['EPERM', 'EACCES', 'EBUSY']);
32
+ // The board's writeAtomicSync budget: a scan of a fresh file often outlasts 200 ms.
33
+ const RENAME_TRIES = 10;
34
+
35
+ async function renameRetrying(from, to) {
36
+ for (let attempt = 1; ; attempt++) {
37
+ try {
38
+ return await rename(from, to);
39
+ } catch (err) {
40
+ if (!BUSY.has(err.code) || attempt >= RENAME_TRIES) throw err;
41
+ await sleep(50);
42
+ }
43
+ }
44
+ }
45
+
28
46
  /** Write atomically: tmp file in the same dir, then rename over the target. */
29
47
  export async function atomicWrite(file, data) {
30
48
  // pid+random: writeIndex is reachable from both the pre-commit hook and applyVerdict,
@@ -33,7 +51,7 @@ export async function atomicWrite(file, data) {
33
51
  await mkdir(path.dirname(file), { recursive: true });
34
52
  await writeFile(tmp, data, 'utf8');
35
53
  try {
36
- await rename(tmp, file);
54
+ await renameRetrying(tmp, file);
37
55
  } catch (err) {
38
56
  await unlink(tmp).catch(() => {});
39
57
  throw err;
@@ -42,10 +60,8 @@ export async function atomicWrite(file, data) {
42
60
 
43
61
  /** Put one snapshotted file back: `null` content means it did not exist before. */
44
62
  async function restoreSnapshot(file, content) {
45
- if (content === null)
46
- await unlink(file).catch((e) => {
47
- if (e.code !== 'ENOENT') throw e;
48
- });
63
+ // rm retries a held file (EBUSY, EPERM) itself; force passes one already gone.
64
+ if (content === null) await rm(file, { force: true, maxRetries: 5 });
49
65
  else await atomicWrite(file, content);
50
66
  }
51
67
 
@@ -36,6 +36,8 @@ const FROM = {
36
36
  agent: STORED,
37
37
  // Nor does where its runs go, main or a worktree.
38
38
  mode: STORED,
39
+ // Nor its card's gates: they hold its next move.
40
+ gates: STORED,
39
41
  };
40
42
 
41
43
  /** Every move an item may be offered, in the board's order. */
package/lib/unit-ops.js CHANGED
@@ -8,13 +8,13 @@ import path from 'node:path';
8
8
  import { serialize } from './frontmatter.js';
9
9
  import { CARD_TYPES, SLUG_RE, blockOrder, listOf } from './design.js';
10
10
  import { buildLedger } from './ledger.js';
11
- import { cycleMessage, designCheck, dependsGraph, pathTo } from './design-check.js';
11
+ import { cycleMessage, designCheck, dependsGraph, gameMilestones, pathTo } from './design-check.js';
12
12
  import { atomicWrite, withFileRollback } from './safe-path.js';
13
13
  import { writeIndex } from './index-gen.js';
14
- import { operationInProgress, commitPaths } from './git.js';
14
+ import { operationInProgress, commitPaths, dirtyGcf, dirtyRefusal } from './git.js';
15
15
  import { upsertBlock, openSystemDoc } from './systems-doc.js';
16
16
  import { buryLine, recordLine } from './verdict-fs.js';
17
- import { DEFAULT_GATE } from './validate-item.js';
17
+ import { defaultGate } from './validate-item.js';
18
18
  import { refuseByPhase } from './phase.js';
19
19
  import { locked, withMainLock } from './main-lock.js';
20
20
 
@@ -67,11 +67,37 @@ async function cutUnit(paths, id) {
67
67
  await atomicWrite(paths.backlog, backlogWithout(await readFile(paths.backlog, 'utf8'), id));
68
68
  }
69
69
 
70
+ /** A unit's own milestone: a name, not TBD or later. */
71
+ const ownMilestone = (h) =>
72
+ SLUG_RE.test(h.milestone ?? '') && h.milestone !== 'later' ? h.milestone : null;
73
+
74
+ /**
75
+ * The milestone each unit is taken into: its own, else the one `take --milestone` gives. A
76
+ * mechanic or a resource is played with its milestone (docs/Autonomy-Plan.md, C): while game.md
77
+ * has milestones, one without is refused.
78
+ */
79
+ function milestonesOf(units, given, milestones) {
80
+ if (given && milestones !== null && !milestones.some((m) => m.name === given))
81
+ throw new Error(
82
+ `--milestone ${given} is not a milestone of game.md: ` +
83
+ (milestones.map((m) => m.name).join(', ') || 'it lists none'),
84
+ );
85
+ const names = new Map(units.map((u) => [u.id, ownMilestone(u.header) ?? given ?? null]));
86
+ const owed = units.filter((u) => CARD_TYPES.includes(u.header.type) && !names.get(u.id));
87
+ if (owed.length && milestones?.length)
88
+ throw new Error(
89
+ `${owed.map((u) => u.id).join(', ')}: no milestone — give the one it is played with, ` +
90
+ `take --milestone <${milestones.map((m) => m.name).join(' | ')}>, or in its unit`,
91
+ );
92
+
93
+ return names;
94
+ }
95
+
70
96
  /** The frontmatter a work item starts with: the unit's header plus the fields of work. */
71
- function unitItemData(unit, today, parent) {
97
+ function unitItemData(unit, today, parent, milestone = ownMilestone(unit.header)) {
72
98
  const h = unit.header;
73
99
  const pillars = listOf(h.pillars);
74
- const gate = DEFAULT_GATE[h.type];
100
+ const gate = defaultGate(h.type, milestone);
75
101
 
76
102
  return {
77
103
  schema: 3,
@@ -86,9 +112,7 @@ function unitItemData(unit, today, parent) {
86
112
  pillars: pillars === 'TBD' ? [] : pillars,
87
113
  source: h.source,
88
114
  ...(h.reopens ? { reopens: h.reopens } : {}),
89
- ...(SLUG_RE.test(h.milestone ?? '') && h.milestone !== 'later'
90
- ? { milestone: h.milestone }
91
- : {}),
115
+ ...(milestone ? { milestone } : {}),
92
116
  ...(gate === 'verdict' ? { tune_count: 0 } : {}),
93
117
  // A child's capability is its feature's: the feature writes the one LIVE.md record.
94
118
  ...(parent ? { live: { none: 'parent' } } : {}),
@@ -97,7 +121,7 @@ function unitItemData(unit, today, parent) {
97
121
  }
98
122
 
99
123
  /** The feature `id` to group the taken units under: the live one, or a new one. */
100
- function featureFor(ledger, root, { id, unitIds, systems, today }) {
124
+ function featureFor(ledger, root, { id, unitIds, systems, today, milestone }) {
101
125
  const file = path.join(root, 'work', `${id}.md`);
102
126
  const live = ledger.item(id);
103
127
  if (live) {
@@ -118,6 +142,7 @@ function featureFor(ledger, root, { id, unitIds, systems, today }) {
118
142
  children: unitIds,
119
143
  system: [...new Set(systems)],
120
144
  depends: [],
145
+ ...(milestone ? { milestone } : {}),
121
146
  created: today,
122
147
  };
123
148
 
@@ -167,23 +192,33 @@ function refuseUnready(units, summaries) {
167
192
  export async function takeUnits(
168
193
  projectDir,
169
194
  ids,
170
- { feature = null, today = new Date().toISOString().slice(0, 10) } = {},
195
+ { feature = null, milestone = null, today = new Date().toISOString().slice(0, 10) } = {},
171
196
  ) {
172
197
  const root = path.join(path.resolve(projectDir), 'gcf');
173
198
  const ledger = await buildLedger(projectDir);
174
199
  const units = ids.map((id) => designUnitOf(ledger, id));
175
200
  refuseUnready(units, (await designCheck(projectDir)).units);
201
+ // A child of a live feature is played with the feature's milestone unless told otherwise.
202
+ const given = milestone ?? (feature ? ledger.item(feature)?.data.milestone : null) ?? null;
203
+ const names = milestonesOf(units, given, await gameMilestones(root));
176
204
  for (const u of units) await refuseByPhase(projectDir, u.header.type, u.header.reopens ?? null);
177
205
  if (feature && !ledger.item(feature)) await refuseByPhase(projectDir, 'feature');
178
206
  const writes = units.map((unit) => ({
179
207
  file: path.join(root, 'work', `${unit.id}.md`),
180
- text: serialize(unitItemData(unit, today, feature), `\n${unit.body.trim()}\n`),
208
+ text: serialize(
209
+ unitItemData(unit, today, feature, names.get(unit.id)),
210
+ `\n${unit.body.trim()}\n`,
211
+ ),
181
212
  }));
182
213
  for (const w of writes)
183
214
  if (existsSync(w.file)) throw new Error(`gcf/work/${path.basename(w.file)} already exists`);
184
215
  if (feature) {
185
216
  const systems = units.flatMap((u) => listOf(u.header.system)).filter((s) => s !== 'TBD');
186
- writes.push(featureFor(ledger, root, { id: feature, unitIds: ids, systems, today }));
217
+ // A new feature gets the milestone its units are played with: the given one, else theirs.
218
+ const own = milestone ?? [...new Set(names.values())].find(Boolean) ?? null;
219
+ writes.push(
220
+ featureFor(ledger, root, { id: feature, unitIds: ids, systems, today, milestone: own }),
221
+ );
187
222
  refuseFeatureCycle(ledger, feature, units);
188
223
  }
189
224
 
@@ -266,10 +301,15 @@ async function record(
266
301
  ? files.filter((f) => !inputs.includes(f) && uncommitted(projectDir, f))
267
302
  : [];
268
303
  if (dirty.length) {
269
- const names = dirty.map((f) => path.relative(projectDir, f)).join(', ');
270
- throw new Error(
304
+ const rels = dirty.map((f) => path.relative(projectDir, f).replaceAll('\\', '/'));
305
+ // The whole of gcf/'s edits, not only these: the gate would refuse the next one at once.
306
+ // Only when that set holds them all: a move's own file outside it (an archived plan) is no
307
+ // edit `gcf edits` takes, and a Commit of the rest would be refused again.
308
+ const all = dirtyGcf(projectDir, inputs);
309
+ throw dirtyRefusal(
310
+ rels.every((r) => all.includes(r)) ? all : [],
271
311
  `commit or stash these first (an answered unit is committed before its move), ` +
272
- `${message} would carry them: ${names}`,
312
+ `${message} would carry them: ${rels.join(', ')}`,
273
313
  );
274
314
  }
275
315
 
@@ -37,6 +37,15 @@ export const DEFAULT_GATE = {
37
37
  release: 'decision',
38
38
  };
39
39
  export const GATES = ['verdict', 'auto', 'decision'];
40
+ // A unit played with its milestone (docs/Autonomy-Plan.md, C): built, it waits unplayed for the
41
+ // milestone's play; without a milestone nothing would call it to play.
42
+ const PLAYED_WITH_MILESTONE = ['mechanic', 'resource'];
43
+
44
+ /** The gate a new item of `type` gets: DEFAULT_GATE, a soft unit with a milestone `auto`. */
45
+ export const defaultGate = (type, milestone = null) =>
46
+ PLAYED_WITH_MILESTONE.includes(type) && milestone && !['TBD', 'later'].includes(milestone)
47
+ ? 'auto'
48
+ : DEFAULT_GATE[type];
40
49
  export const SEVERITIES = ['critical', 'high', 'medium', 'low'];
41
50
  const CHANGES = ['added', 'modified', 'removed'];
42
51
 
@@ -67,6 +76,9 @@ const FIELDS = [
67
76
  'model',
68
77
  'effort',
69
78
  'run_mode',
79
+ 'skip_gates',
80
+ 'gate_why',
81
+ 'play_on',
70
82
  'version',
71
83
  'channel',
72
84
  'created',
@@ -167,6 +179,10 @@ const RULES = {
167
179
  effort: (v) => nullable(isText)(v) || 'effort must be text or null',
168
180
  run_mode: (v) =>
169
181
  nullable((x) => ['main', 'worktree'].includes(x))(v) || 'run_mode must be main | worktree',
182
+ skip_gates: (v) => typeof v === 'boolean' || 'skip_gates must be true or false',
183
+ gate_why: (v) => nullable(isText)(v) || 'gate_why must be text or null',
184
+ play_on: (v) =>
185
+ (Array.isArray(v) && v.every(isText)) || 'play_on must list lines of platforms in game.md',
170
186
  version: (v) =>
171
187
  nullable((x) => typeof x === 'string' && /^\S+$/.test(x))(v) ||
172
188
  'version must be one word of text (quote a number: "1.0")',
package/lib/verify.js CHANGED
@@ -7,7 +7,6 @@ import path from 'node:path';
7
7
  import { readConfig } from './gcf-paths.js';
8
8
  import { readLive, applyDelta } from './live.js';
9
9
  import { gateProblems } from './gate.js';
10
- import { unplayedCloseProblem } from './work-ops.js';
11
10
 
12
11
  /**
13
12
  * Every process's parent, `[pid, ppid]` (POSIX): from /proc on Linux, which a slim image has
@@ -140,7 +139,7 @@ function failureOf(key, cmd, minutes, res) {
140
139
 
141
140
  /**
142
141
  * Why the item's `live:` delta would fail its end against this checkout's LIVE.md: it does not
143
- * apply, or an unplayed close could not take it back.
142
+ * apply. A soft unit's change of a capability is no failure: its close waits for a verdict (A4).
144
143
  */
145
144
  export async function deltaProblems(projectDir, item) {
146
145
  const problems = [];
@@ -151,9 +150,6 @@ export async function deltaProblems(projectDir, item) {
151
150
  problems.push(e.message);
152
151
  }
153
152
 
154
- const unplayed = unplayedCloseProblem(item);
155
- if (unplayed) problems.push(unplayed);
156
-
157
153
  return problems;
158
154
  }
159
155