gcf-aif-ext 0.27.0 → 0.28.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.
@@ -0,0 +1,189 @@
1
+ // The agent's part of a card's handoff to play (docs/Handoff-Plan.md d3): `## Play notes` in the
2
+ // card's plan, written before the commit of gcf-run's step 16, in main and in a worktree alike. The
3
+ // core reads it mechanically and checks its form; what is missing is a warning, never a refusal.
4
+ // The rest of the handoff the core reads live (lib/handoff.js).
5
+ import { existsSync, readFileSync } from 'node:fs';
6
+ import path from 'node:path';
7
+ import { readConfig } from './gcf-paths.js';
8
+ import { buildLedger } from './ledger.js';
9
+ import { playOf } from './play.js';
10
+
11
+ const HEAD_RE = /^## Play notes[ \t]*\r?$/m;
12
+ const SECTIONS = {
13
+ question: 'Question',
14
+ try: 'Try',
15
+ rows: 'Rows',
16
+ watch_out: 'Watch out',
17
+ notes: 'Notes',
18
+ };
19
+ const ROW_RE = /^[-*]\s+(\w[\w-]*)\s+([\w-]+)(?:\s+([\w-]+))?\s*:\s*(.*)$/;
20
+
21
+ /** The section's lines, up to the next heading of level 1 or 2 (as `## Outcome` is read). */
22
+ function blockOf(text) {
23
+ const at = String(text ?? '').search(HEAD_RE);
24
+ if (at < 0) return null;
25
+ const lines = text.slice(at).split(/\r?\n/).slice(1);
26
+ const end = lines.findIndex((l) => /^#{1,2} /.test(l));
27
+
28
+ return end < 0 ? lines : lines.slice(0, end);
29
+ }
30
+
31
+ /** A list's items: a bullet starts one, a line under it goes on with it. */
32
+ function itemsOf(lines) {
33
+ const items = [];
34
+ for (const line of lines) {
35
+ const m = /^\s*[-*]\s+(.*)$/.exec(line);
36
+ if (m) items.push(m[1].trim());
37
+ else if (line.trim() && items.length) items[items.length - 1] += ` ${line.trim()}`;
38
+ else if (line.trim()) items.push(line.trim());
39
+ }
40
+
41
+ return items.filter(Boolean);
42
+ }
43
+
44
+ /**
45
+ * The plan's `## Play notes`, or null when it has none.
46
+ * @returns {null | {question: string[], try: string[], rows: Array<{build: string, device: string,
47
+ * os: string | null, note: string}>, bad_rows: string[], watch_out: string[], notes: string,
48
+ * unknown: string[]}}
49
+ */
50
+ export function playNotesOf(planText) {
51
+ const block = blockOf(planText);
52
+ if (!block) return null;
53
+ const { parts, unknown } = partsOf(block);
54
+ const rows = [];
55
+ const badRows = [];
56
+ for (const line of parts.rows.filter((l) => l.trim())) {
57
+ const m = ROW_RE.exec(line.trim());
58
+ if (m) rows.push({ build: m[1], device: m[2], os: m[3] ?? null, note: m[4].trim() });
59
+ else badRows.push(line.trim());
60
+ }
61
+
62
+ return {
63
+ question: itemsOf(parts.question),
64
+ try: itemsOf(parts.try),
65
+ rows,
66
+ bad_rows: badRows,
67
+ watch_out: itemsOf(parts.watch_out),
68
+ notes: parts.notes.join('\n').trim(),
69
+ unknown,
70
+ };
71
+ }
72
+
73
+ /** The lines under each `### ` heading; a heading the format lacks goes to `unknown`. */
74
+ function partsOf(block) {
75
+ const parts = Object.fromEntries(Object.keys(SECTIONS).map((k) => [k, []]));
76
+ const unknown = [];
77
+ let key = null;
78
+ for (const line of block) {
79
+ const h = /^###\s+(.+?)\s*$/.exec(line);
80
+ if (!h) {
81
+ if (key) parts[key].push(line);
82
+ continue;
83
+ }
84
+
85
+ key = Object.keys(SECTIONS).find((k) => SECTIONS[k].toLowerCase() === h[1].toLowerCase());
86
+ if (!key) unknown.push(h[1]);
87
+ }
88
+
89
+ return { parts, unknown };
90
+ }
91
+
92
+ /** The plan of card `item`, its text or '' when it has none. */
93
+ export function planTextOf(projectDir, item) {
94
+ const file = path.join(projectDir, item.data.plan ?? `.ai-factory/plans/${item.data.id}.md`);
95
+
96
+ return existsSync(file) ? readFileSync(file, 'utf8') : '';
97
+ }
98
+
99
+ /**
100
+ * The rows a card's handoff has: each build of its `play_on` (none: every build) by each row of
101
+ * that build's `plays_on`.
102
+ * @returns {Array<{build: string, device: string, os: string | null}>}
103
+ */
104
+ export function rowsFor(play, playOn) {
105
+ if (!play) return [];
106
+ const names = Object.keys(play.builds);
107
+ const builds = playOn?.length ? playOn.filter((b) => names.includes(b)) : names;
108
+
109
+ return builds.flatMap((b) =>
110
+ play.builds[b].plays_on.map((r) => ({ build: b, device: r.device, os: r.os ?? null })),
111
+ );
112
+ }
113
+
114
+ const rowKey = (r) => `${r.build} ${r.device}${r.os ? ` ${r.os}` : ''}`;
115
+
116
+ /** `gcf play-notes <id> --template`: the section with the card's rows filled in. */
117
+ export async function playNotesTemplate(projectDir, id) {
118
+ const dir = path.resolve(projectDir);
119
+ const item = (await buildLedger(dir)).item(id);
120
+ if (!item) throw new Error(`${id} is not on the board`);
121
+ const rows = rowsFor(playOf(await readConfig(path.join(dir, 'gcf'))), item.data.play_on);
122
+
123
+ return [
124
+ '## Play notes',
125
+ '',
126
+ '### Question',
127
+ '- ',
128
+ '',
129
+ '### Try',
130
+ '- ',
131
+ '',
132
+ '### Rows',
133
+ ...(rows.length ? rows.map((r) => `- ${rowKey(r)}: `) : ['- ']),
134
+ '',
135
+ '### Watch out',
136
+ '- ',
137
+ '',
138
+ '### Notes',
139
+ '',
140
+ ].join('\n');
141
+ }
142
+
143
+ /**
144
+ * What the section lacks, one warning each: the form and what is in it, not its language.
145
+ * @param {ReturnType<typeof playNotesOf>} notes
146
+ * @param {Array<{build: string, device: string, os: string | null}>} rows the card's rows
147
+ */
148
+ export function playNotesProblems(notes, rows) {
149
+ if (!notes) return ['the plan has no ## Play notes: ai-factory gcf play-notes <id> --template'];
150
+ const problems = notes.unknown.map((h) => `## Play notes has no section ### ${h}`);
151
+ if (!notes.question.length) problems.push('### Question is empty');
152
+ if (!notes.try.length) problems.push('### Try is empty');
153
+ for (const line of notes.bad_rows)
154
+ problems.push(`### Rows: not "<build> <device> [os]: …": ${line}`);
155
+ const known = new Set(rows.map(rowKey));
156
+ for (const r of notes.rows)
157
+ if (!known.has(rowKey(r))) problems.push(`### Rows: ${rowKey(r)} is no row of this card`);
158
+ const noted = new Set(notes.rows.filter((r) => r.note).map(rowKey));
159
+ for (const r of rows)
160
+ if (!noted.has(rowKey(r))) problems.push(`### Rows: ${rowKey(r)} has no note`);
161
+
162
+ return problems;
163
+ }
164
+
165
+ /** The card's notes and their warnings, from its plan in `projectDir` (main or its worktree). */
166
+ export async function playNotesCheck(projectDir, item) {
167
+ const dir = path.resolve(projectDir);
168
+ let play = null;
169
+ try {
170
+ play = playOf(await readConfig(path.join(dir, 'gcf')));
171
+ } catch {
172
+ // A broken play: is its own command's to report; the rows are unknown then.
173
+ }
174
+
175
+ const notes = playNotesOf(planTextOf(dir, item));
176
+
177
+ return { notes, warnings: playNotesProblems(notes, rowsFor(play, item.data.play_on)) };
178
+ }
179
+
180
+ /** The plan's text without `## Play notes`: a move back to `ready` takes it (d3). */
181
+ export function withoutPlayNotes(text) {
182
+ const lines = String(text).split(/(?<=\n)/);
183
+ const at = lines.findIndex((l) => /^## Play notes[ \t]*\r?\n?$/.test(l));
184
+ if (at < 0) return text;
185
+ const rest = lines.slice(at + 1).findIndex((l) => /^#{1,2} /.test(l));
186
+ const end = rest < 0 ? lines.length : at + 1 + rest;
187
+
188
+ return lines.slice(0, at).join('') + lines.slice(end).join('');
189
+ }
package/lib/play-on.js ADDED
@@ -0,0 +1,42 @@
1
+ // A card's `play_on` and `played_on` name builds of `play.builds` (docs/Handoff-Plan.md d8). Seen
2
+ // where the config and game.md are: one card file alone cannot tell a build from a typo.
3
+ import { playOf } from './play.js';
4
+
5
+ const FIELDS = ['play_on', 'played_on'];
6
+
7
+ /**
8
+ * What the cards' build names lack. A line of game.md `platforms` (the old form) or a line of
9
+ * words is a warning until Set up translates it; one word that names no build is an error. A
10
+ * project with no `play:` (or a broken one: its own command says so) has no names to check.
11
+ * @param {{data: object}[]} items
12
+ * @param {string[]} platforms the `platforms` lines of game.md
13
+ * @returns {{errors: string[], warnings: string[]}}
14
+ */
15
+ export function playOnIssues(items, config, platforms = []) {
16
+ const issues = { errors: [], warnings: [] };
17
+ let play;
18
+ try {
19
+ play = playOf(config);
20
+ } catch {
21
+ return issues;
22
+ }
23
+
24
+ if (!play) return issues;
25
+ const names = Object.keys(play.builds);
26
+ const values = items.flatMap((c) =>
27
+ FIELDS.flatMap((field) =>
28
+ [c.data[field] ?? []].flat().map((v) => ({ id: c.data.id, field, v })),
29
+ ),
30
+ );
31
+ for (const { id, field, v } of values) {
32
+ if (typeof v !== 'string' || names.includes(v)) continue;
33
+ if (/\s/.test(v.trim()) || platforms.includes(v))
34
+ issues.warnings.push(
35
+ `${id}: ${field} "${v}" is a line of platforms, not a build: name one of ` +
36
+ `${names.join(', ')} (a Set up pass translates it)`,
37
+ );
38
+ else issues.errors.push(`${id}: ${field} names no build: ${v} (${names.join(', ')})`);
39
+ }
40
+
41
+ return issues;
42
+ }