gcf-aif-ext 0.27.1 → 0.29.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,235 @@
1
+ // A build waits, it is not refused (docs/Handoff-Plan.md d6): a request writes a ticket
2
+ // `.gcf-session/runs/.build-<n>.json` and its waiter takes its turn. The checkout is entered by a
3
+ // claim of the main run lock when nobody holds it, or by the yield of a main run between its cards
4
+ // (`.gcf-session/.main-run.yield`: `{run, ticket}`, the builder adds its pid). The run never
5
+ // withdraws a yield: it waits until the ticket is gone or its waiter is dead. The dot keeps a
6
+ // ticket's name apart from a card's id, as `.main-run` does.
7
+ import { existsSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
8
+ import { mkdir } from 'node:fs/promises';
9
+ import path from 'node:path';
10
+ import { alive, claimMainRun, MAIN_RUN, withMainLock } from './main-lock.js';
11
+
12
+ const runsOf = (dir) => path.join(dir, '.gcf-session', 'runs');
13
+ const TICKET_RE = /^\.build-(\d+)\.json$/;
14
+ export const ticketFile = (dir, n) => path.join(runsOf(dir), `.build-${n}.json`);
15
+ /** What a queued waiter ended with: the board reads it when the ticket is gone. */
16
+ export const outcomeFile = (dir, n) => path.join(runsOf(dir), `.build-${n}.out.json`);
17
+ const seqFile = (dir) => path.join(runsOf(dir), '.build-seq');
18
+ export const yieldFile = (dir) => path.join(dir, '.gcf-session', `${MAIN_RUN}.yield`);
19
+ const POLL_MS = 300;
20
+ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
21
+ export const CANCELLED = 'stopped by the operator';
22
+
23
+ function readJson(file) {
24
+ try {
25
+ return JSON.parse(readFileSync(file, 'utf8'));
26
+ } catch {
27
+ return null;
28
+ }
29
+ }
30
+
31
+ function writeJson(file, value) {
32
+ const tmp = `${file}.tmp-${process.pid}`;
33
+ writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
34
+ // Windows holds a fresh file for a moment (a scanner): the rename tries again.
35
+ for (let attempt = 1; ; attempt++)
36
+ try {
37
+ return renameSync(tmp, file);
38
+ } catch (e) {
39
+ if (!['EPERM', 'EACCES', 'EBUSY'].includes(e.code) || attempt >= 10) throw e;
40
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
41
+ }
42
+ }
43
+
44
+ export const readTicket = (dir, n) => readJson(ticketFile(dir, n));
45
+ export const readYield = (dir) => readJson(yieldFile(dir));
46
+
47
+ /**
48
+ * The tickets in their order; one whose waiter is dead is left out (a sweep takes it).
49
+ * @returns {Array<{n: number, pid: number, job: object, at: string, after?: string | null,
50
+ * building?: boolean, cancelled?: boolean}>}
51
+ */
52
+ export function ticketsOf(projectDir) {
53
+ const dir = path.resolve(projectDir);
54
+ if (!existsSync(runsOf(dir))) return [];
55
+
56
+ return readdirSync(runsOf(dir))
57
+ .map((name) => TICKET_RE.exec(name))
58
+ .filter(Boolean)
59
+ .map((m) => readTicket(dir, Number(m[1])))
60
+ .filter((t) => t && alive(t.pid))
61
+ .sort((a, b) => a.n - b.n);
62
+ }
63
+
64
+ /** The live builder a yield let in, or null: it holds the checkout even when its run is dead. */
65
+ export function builderOf(projectDir) {
66
+ const y = readYield(path.resolve(projectDir));
67
+
68
+ return Number.isInteger(y?.builder) && y.builder !== process.pid && alive(y.builder)
69
+ ? y.builder
70
+ : null;
71
+ }
72
+
73
+ /** A ticket for `job`, numbered past every one before: a reader that saw `n` go never sees it. */
74
+ export async function ticketOpen(projectDir, job, pid = process.pid) {
75
+ const dir = path.resolve(projectDir);
76
+ await mkdir(runsOf(dir), { recursive: true });
77
+
78
+ return withMainLock(dir, async () => {
79
+ const n = (Number(readJson(seqFile(dir))?.n) || 0) + 1;
80
+ writeJson(seqFile(dir), { n });
81
+ writeJson(ticketFile(dir, n), { n, pid, job, at: new Date().toISOString(), after: null });
82
+
83
+ return n;
84
+ });
85
+ }
86
+
87
+ /** Mark ticket `n` (its waiter, a start of building): what is not in `fields` stays. */
88
+ export function ticketSet(dir, n, fields) {
89
+ const t = readTicket(dir, n);
90
+ if (t) writeJson(ticketFile(dir, n), { ...t, ...fields });
91
+
92
+ return t;
93
+ }
94
+
95
+ /** The ticket goes with what its waiter ended with; a yield naming it lets its run go on. */
96
+ export function ticketClose(projectDir, n, outcome = null) {
97
+ const dir = path.resolve(projectDir);
98
+ if (outcome) writeJson(outcomeFile(dir, n), { n, at: new Date().toISOString(), ...outcome });
99
+ rmSync(ticketFile(dir, n), { force: true });
100
+ }
101
+
102
+ /**
103
+ * What holds the checkout ahead of ticket `n`, as words for "waits: after X": the card a main run
104
+ * works, another ticket, or a build by click. Null when nothing does.
105
+ */
106
+ function aheadOf(dir, n) {
107
+ const before = ticketsOf(dir).find((t) => t.n < n);
108
+ if (before) return `ticket ${before.n}`;
109
+ const lock = path.join(runsOf(dir), `${MAIN_RUN}.lock`);
110
+ const text = existsSync(lock) ? readFileSync(lock, 'utf8').split('\n') : [];
111
+ if (!text.length || !alive(Number(text[0]))) return null;
112
+
113
+ return text[1]?.trim() ? `card ${text[1].trim()}` : 'a build';
114
+ }
115
+
116
+ /** The run's yield to ticket `n`: its builder goes in, and out with the release. */
117
+ function byYield(dir, n) {
118
+ const y = readYield(dir);
119
+ if (y?.ticket !== n || !alive(y.run) || (y.builder && alive(y.builder))) return null;
120
+ writeJson(yieldFile(dir), { ...y, builder: process.pid });
121
+ const release = async () => {
122
+ const now = readYield(dir);
123
+ if (now?.builder === process.pid) writeJson(yieldFile(dir), { ...now, builder: null });
124
+ };
125
+
126
+ return { release, yielded: true };
127
+ }
128
+
129
+ /**
130
+ * 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. `free`: a worktree build, or one in
132
+ * the build folder of a worktree project, needs no checkout, only its turn. Null: not yet.
133
+ * @returns {Promise<null | 'gone' | {release: (() => Promise<void>) | null, yielded: boolean}>}
134
+ */
135
+ async function entered(dir, n, free) {
136
+ if (ticketsOf(dir)[0]?.n !== n) return null;
137
+ if (free) return { release: null, yielded: false };
138
+ const yielded = byYield(dir, n);
139
+ if (yielded) return yielded;
140
+ dropDeadYield(dir);
141
+ const release = builderOf(dir) ? null : await claimMainRun(dir);
142
+
143
+ return release ? { release, yielded: false } : null;
144
+ }
145
+
146
+ /**
147
+ * One look under the main lock, which a cancel takes too: a cancelled ticket is gone; one let in
148
+ * is marked `building` before a cancel can see it waiting; one still waiting names what it waits
149
+ * behind. Its file is written only here and by a cancel, so a cancel's removal stays.
150
+ */
151
+ async function enter(dir, n, free) {
152
+ return withMainLock(dir, async () => {
153
+ if (cancelled(dir, n)) return 'gone';
154
+ const got = await entered(dir, n, free);
155
+ const after = got ? null : aheadOf(dir, n);
156
+ if (got || readTicket(dir, n)?.after !== after)
157
+ ticketSet(dir, n, got ? { building: true, after: null } : { after });
158
+
159
+ return got;
160
+ });
161
+ }
162
+
163
+ /** A yield whose run and builder are both dead holds nothing. */
164
+ function dropDeadYield(dir) {
165
+ const y = readYield(dir);
166
+ if (y && !alive(y.run) && !builderOf(dir)) rmSync(yieldFile(dir), { force: true });
167
+ }
168
+
169
+ /**
170
+ * Wait for ticket `n`'s turn; its removal (a cancel) ends the wait with an error. `after` on the
171
+ * ticket says what it waits behind.
172
+ */
173
+ export async function waitTurn(projectDir, n, { free = false } = {}) {
174
+ const dir = path.resolve(projectDir);
175
+ for (;;) {
176
+ const got = await enter(dir, n, free);
177
+ if (got === 'gone') throw new Error(CANCELLED);
178
+ if (got) return got;
179
+ await sleep(POLL_MS);
180
+ }
181
+ }
182
+
183
+ /**
184
+ * The operator's cancel: a waiting ticket goes, its waiter sees that and ends; a building one is
185
+ * marked `cancelled`, its waiter kills the build's tree and publishes nothing. Waits for the
186
+ * ticket to go, up to `waitMs`.
187
+ * @returns {Promise<{n: number, was: 'waiting' | 'building' | 'gone'}>}
188
+ */
189
+ export async function cancelTicket(projectDir, n, { waitMs = 15000 } = {}) {
190
+ const dir = path.resolve(projectDir);
191
+ const was = await withMainLock(dir, async () => {
192
+ const t = readTicket(dir, n);
193
+ if (!t) return 'gone';
194
+ if (t.building && alive(t.pid)) {
195
+ ticketSet(dir, n, { cancelled: true });
196
+
197
+ return 'building';
198
+ }
199
+
200
+ ticketClose(dir, n, { ok: false, problem: CANCELLED });
201
+
202
+ return 'waiting';
203
+ });
204
+ for (const until = Date.now() + waitMs; existsSync(ticketFile(dir, n)) && Date.now() < until;)
205
+ await sleep(100);
206
+
207
+ return { n, was };
208
+ }
209
+
210
+ /** Whether ticket `n` was cancelled, or is gone: a build for it must publish nothing. */
211
+ export const cancelled = (dir, n) => {
212
+ const t = readTicket(dir, n);
213
+
214
+ return !t || t.cancelled === true;
215
+ };
216
+
217
+ /**
218
+ * Tickets of dead waiters go, an old waiter's outcome too, and a yield whose run and builder are
219
+ * both dead. Under the main lock.
220
+ */
221
+ export function sweepTickets(projectDir) {
222
+ const dir = path.resolve(projectDir);
223
+ if (!existsSync(runsOf(dir))) return;
224
+ for (const name of readdirSync(runsOf(dir))) {
225
+ const m = /^\.build-\d+\.(json|out\.json)$/.exec(name);
226
+ const file = m && path.join(runsOf(dir), name);
227
+ if (file && !keeps(m[1], readJson(file))) rmSync(file, { force: true });
228
+ }
229
+
230
+ dropDeadYield(dir);
231
+ }
232
+
233
+ /** A ticket keeps while its waiter lives; an outcome, for an hour. */
234
+ const keeps = (kind, t) =>
235
+ kind === 'json' ? Boolean(t && alive(t.pid)) : Date.now() - Date.parse(t?.at ?? 0) < 3600000;
@@ -0,0 +1,5 @@
1
+ // The waiter of a `--queue` ticket (lib/build-queue.js): `node build-waiter.js <dir> <n>`.
2
+ import { runTicket } from './play.js';
3
+
4
+ const [dir, n] = process.argv.slice(2);
5
+ await runTicket(dir, Number(n));
package/lib/devices.js ADDED
@@ -0,0 +1,133 @@
1
+ // The devices a target can play on (docs/Handoff-Plan.md d5, proposal §4): its `devices` command
2
+ // prints one JSON line per device, `{"id", "name", "device", "os", "os_version"?, "model"?,
3
+ // "state", "note"?}`, or one `{"unavailable": "<why>"}`. Asked only on request: the Play panel and
4
+ // `gcf playtest devices`. Its output goes to a file, not a pipe: a daemon the script starts (adb)
5
+ // would hold an inherited pipe open on Windows.
6
+ import { mkdir, open, readFile } from 'node:fs/promises';
7
+ import path from 'node:path';
8
+ import { readConfig } from './gcf-paths.js';
9
+ import { NOT_SET_UP, playOf } from './play.js';
10
+ import { runCommand } from './verify.js';
11
+
12
+ const DEVICES_MS = 30000;
13
+ /** A device id goes into a shell command: only these characters (no quote escapes on Windows). */
14
+ // A word character first: `-x` would be an option of the device tool (`adb -s -x`).
15
+ export const DEVICE_ID_RE = /^\w[\w.:-]*$/;
16
+
17
+ /** Whether target `t` serves a row of build `build`: every field of its `for` is the row's. */
18
+ export const serves = (t, build, row) =>
19
+ t.build === build && Object.entries(t.for ?? {}).every(([k, v]) => row[k] === v);
20
+
21
+ /** -1, 0, 1: two versions as numbers with dots. */
22
+ export function versionCmp(a, b) {
23
+ const x = String(a).split('.').map(Number);
24
+ const y = String(b).split('.').map(Number);
25
+ for (let i = 0; i < Math.max(x.length, y.length); i++) {
26
+ const d = (x[i] ?? 0) - (y[i] ?? 0);
27
+ if (d) return Math.sign(d);
28
+ }
29
+
30
+ return 0;
31
+ }
32
+
33
+ /** Why device `d` does not fit row `r`, or null when it does. */
34
+ function misfit(d, r) {
35
+ if (d.device !== r.device || (r.os && d.os !== r.os) || (r.model && d.model !== r.model))
36
+ return 'another kind';
37
+ if (!r.os_min) return null;
38
+ if (!d.os_version) return `needs ${r.os ?? 'the os'} ${r.os_min}: the version is unknown`;
39
+
40
+ return versionCmp(d.os_version, r.os_min) < 0 ? `needs ${r.os ?? 'the os'} ${r.os_min}` : null;
41
+ }
42
+
43
+ /** The row a device fits, or why none. */
44
+ function placeOf(d, rows) {
45
+ if (!d.device || !d.os) return { row: null, fits: false, why: 'could not be matched' };
46
+ const results = rows.map((r, i) => ({ i, why: misfit(d, r) }));
47
+ const fit = results.find((x) => x.why === null);
48
+ if (fit) return { row: fit.i, fits: true, why: null };
49
+ const near = results.find((x) => x.why !== 'another kind');
50
+
51
+ return {
52
+ row: near?.i ?? null,
53
+ fits: false,
54
+ why: near?.why ?? 'no row of this build is its kind',
55
+ };
56
+ }
57
+
58
+ /** A line of the script's output as a device, checked. */
59
+ function deviceOf(v, rows) {
60
+ const text = (k) => (typeof v[k] === 'string' ? v[k] : null);
61
+ const d = {
62
+ id: text('id'),
63
+ name: text('name') ?? String(v.id ?? '?'),
64
+ device: text('device'),
65
+ os: text('os'),
66
+ os_version: v.os_version == null ? null : String(v.os_version),
67
+ model: text('model'),
68
+ state: text('state') ?? 'unknown',
69
+ note: text('note'),
70
+ };
71
+ const place = placeOf(d, rows);
72
+ const idOk = d.id !== null && DEVICE_ID_RE.test(d.id);
73
+
74
+ return {
75
+ ...d,
76
+ ...place,
77
+ ...(idOk ? {} : { why: 'the id does not fit', fits: false }),
78
+ play: idOk && place.fits && d.state === 'ready',
79
+ };
80
+ }
81
+
82
+ const tailOf = (text) => text.trimEnd().split(/\r?\n/).slice(-20).join('\n');
83
+
84
+ /**
85
+ * `gcf playtest devices <target>`: what the target's script finds, each device placed under a row
86
+ * of `plays_on` it fits, or why not.
87
+ * @returns {Promise<{target: string, rows: object[], devices: object[], unavailable?: string,
88
+ * problem?: string, tail?: string}>}
89
+ */
90
+ export async function devicesOf(projectDir, targetName, { ms = DEVICES_MS } = {}) {
91
+ const dir = path.resolve(projectDir);
92
+ const play = playOf(await readConfig(path.join(dir, 'gcf')));
93
+ if (!play) throw new Error(NOT_SET_UP);
94
+ const t = Object.hasOwn(play.targets, targetName) ? play.targets[targetName] : null;
95
+ if (!t) throw new Error(`no target ${targetName}: ${Object.keys(play.targets).join(', ')}`);
96
+ const rows = play.builds[t.build].plays_on.filter((r) => serves(t, t.build, r));
97
+ const base = { target: targetName, rows, devices: [] };
98
+ if (!t.devices) return { ...base, problem: `${targetName} has no devices command` };
99
+
100
+ const log = path.join(dir, '.gcf-session', `devices-${targetName}.log`);
101
+ await mkdir(path.dirname(log), { recursive: true });
102
+ const fh = await open(log, 'w');
103
+ let res;
104
+ try {
105
+ res = await runCommand(t.devices, dir, ['ignore', fh.fd, fh.fd], ms);
106
+ } finally {
107
+ await fh.close();
108
+ }
109
+
110
+ return { ...base, ...parsed(t.devices, res, await readFile(log, 'utf8'), rows) };
111
+ }
112
+
113
+ /** The script's answer: its devices, its "unavailable", or why it failed with its tail. */
114
+ function parsed(command, res, text, rows) {
115
+ const fail = (why) => ({ problem: `devices ${why}: ${command}`, tail: tailOf(text) });
116
+ if (res.timedOut) return fail(`timed out after ${DEVICES_MS / 1000} s`);
117
+ if (res.error || res.status !== 0)
118
+ return fail(`failed (${res.error?.message ?? `exit ${res.status}`})`);
119
+ const lines = text.split(/\r?\n/).filter((l) => l.trim());
120
+ const values = [];
121
+ for (const line of lines) {
122
+ try {
123
+ values.push(JSON.parse(line));
124
+ } catch {
125
+ return fail(`printed a line that is no JSON (${line.slice(0, 80)})`);
126
+ }
127
+ }
128
+
129
+ const off = values.find((v) => typeof v?.unavailable === 'string');
130
+ if (off) return { unavailable: off.unavailable };
131
+
132
+ return { devices: values.map((v) => deviceOf(v, rows)) };
133
+ }
package/lib/domain.js CHANGED
@@ -44,7 +44,7 @@ const GATE_HELP = {
44
44
  const REASON = { key: 'reason', label: 'Reason', kind: 'longtext', required: true };
45
45
  const REMOVE = { key: 'remove', label: 'Removal item for its code', kind: 'remove' };
46
46
  const CONSTRAINT = { key: 'constraint', label: 'Constraint lines', kind: 'list' };
47
- // Where the operator played it: lines of game.md's platforms, a note for the history (Plan, C).
47
+ // Where the operator played it: names of play.builds, a note for the history (Handoff-Plan d8).
48
48
  const PLAYED_ON = { key: 'played_on', flag: 'played-on', label: 'Played on', kind: 'list' };
49
49
  // close and submit need a green gcf verify of the code as it is now; the operator may say why
50
50
  // they go without one, and the reason goes into the move's commit.
@@ -779,12 +779,36 @@ 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'),
803
+ // docs/Handoff-Plan.md t1: the rows the build plays on, and what the target serves of them.
804
+ {
805
+ key: 'plays_on',
806
+ flag: 'plays-on',
807
+ label: 'Rows the build plays on, one a line: device: phone, os: android, os_min: 10',
808
+ kind: 'list',
809
+ },
810
+ text('for', 'The rows the target serves: device: phone, os: android'),
811
+ text('devices', 'Command that lists its devices, a JSON line each'),
788
812
  ],
789
813
  propose: true,
790
814
  },
@@ -842,7 +866,7 @@ const FIELDS = [
842
866
  { key: 'run_mode', label: 'run mode', kind: 'text', edit: 'mode' },
843
867
  { key: 'skip_gates', label: 'gates', kind: 'text', help: "Its card's gates", edit: 'gates' },
844
868
  { key: 'gate_why', label: 'why its own stop', kind: 'text' },
845
- { key: 'play_on', label: 'play on', kind: 'list', help: 'Where to play it: lines of platforms' },
869
+ { key: 'play_on', label: 'play on', kind: 'list', help: 'Builds to play it on' },
846
870
  { key: 'tune_count', label: 'tune', kind: 'text', help: 'Tune verdicts so far', card: true },
847
871
  {
848
872
  key: 'waits_for',
@@ -1010,6 +1034,7 @@ const CHANGES = [
1010
1034
  'playtest start',
1011
1035
  'playtest stop',
1012
1036
  'playtest setup',
1037
+ 'playtest cancel',
1013
1038
  ];
1014
1039
 
1015
1040
  // The project chat of a GCF project (AD-5, AD-6): its skill, and the commands it asks for.