joycraft 1.3.0 → 1.5.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.
Files changed (33) hide show
  1. package/README.md +154 -4
  2. package/dist/joycraft-release.json +1 -1
  3. package/package.json +3 -3
  4. package/payload/.agents/skills/joycraft-context/SKILL.md +5 -6
  5. package/payload/.agents/skills/joycraft-decompose/SKILL.md +9 -8
  6. package/payload/.agents/skills/joycraft-entry/SKILL.md +8 -19
  7. package/payload/.agents/skills/joycraft-implement/SKILL.md +16 -17
  8. package/payload/.agents/skills/joycraft-session-end/SKILL.md +10 -15
  9. package/payload/.agents/skills/joycraft-testing/SKILL.md +3 -9
  10. package/payload/.agents/skills/joycraft-verify/SKILL.md +20 -21
  11. package/payload/.claude/agents/joycraft-implementer.md +5 -5
  12. package/payload/.claude/agents/joycraft-reviewer.md +3 -6
  13. package/payload/.joycraft/contracts/types.d.ts +18 -0
  14. package/payload/.joycraft/references/architecture.md +2 -4
  15. package/payload/.joycraft/references/completion.md +16 -21
  16. package/payload/.joycraft/references/context.md +11 -34
  17. package/payload/.joycraft/references/dispatch.md +7 -40
  18. package/payload/.joycraft/references/gates.md +60 -0
  19. package/payload/.joycraft/references/retro.md +6 -15
  20. package/payload/.joycraft/references/settings.md +6 -3
  21. package/payload/.joycraft/references/setup.md +4 -4
  22. package/payload/.joycraft/references/testing.md +21 -21
  23. package/payload/.joycraft/references/worktrees.md +1 -1
  24. package/payload/.joycraft/runtime/completion.mjs +92 -6
  25. package/payload/.joycraft/runtime/dispatch-preflight.mjs +1 -1
  26. package/payload/.joycraft/runtime/dispatch-start.mjs +61 -4
  27. package/payload/.joycraft/runtime/evidence.mjs +134 -0
  28. package/payload/.joycraft/runtime/gate.mjs +308 -0
  29. package/payload/.joycraft/runtime/identity.mjs +5 -1
  30. package/payload/.joycraft/runtime/queue-check.mjs +355 -0
  31. package/payload/.joycraft/runtime/status.mjs +46 -5
  32. package/payload/PIN +31 -28
  33. package/payload/scripts/export.mjs +5 -2
@@ -47,6 +47,7 @@ export function validateReview({ root = process.cwd(), report, state, reportPath
47
47
  validateIndependentReview(report);
48
48
  requireValue(['PASS', 'FAIL', 'UNVERIFIED'].includes(report.verdict), 'Report verdict must be PASS, FAIL or UNVERIFIED');
49
49
  requireValue(Array.isArray(report.unresolved) && report.unresolved.every(nonempty), 'Report unresolved findings must be an array of nonempty strings');
50
+ validateFindings(report, state.spec.verification.criteria);
50
51
  requireValue(nonempty(report.createdAt) && Number.isFinite(Date.parse(report.createdAt)), 'Report needs a valid createdAt timestamp');
51
52
  requireValue(Array.isArray(report.flows) && report.flows.length > 0, 'Report needs flow evidence');
52
53
  const subject = report.subject;
@@ -71,8 +72,53 @@ export function validateReview({ root = process.cwd(), report, state, reportPath
71
72
  }
72
73
  }
73
74
 
75
+ const refused = error => Object.assign(error, { exitCode: 2 });
76
+ const findingClasses = ['blocking', 'decision-needed', 'follow-up'];
77
+ const findingOrigins = ['new', 'pre-existing', 'unknown'];
78
+ const findingFields = ['id', 'class', 'origin', 'criterion', 'at', 'summary', 'assumption'];
79
+
80
+ /**
81
+ * The optional `findings` list keeps the report at schemaVersion 1; a report
82
+ * without it is read as before. A malformed finding is refused with exit 2 and
83
+ * the field named, so the reviewer can correct the report.
84
+ */
85
+ function validateFindings(report, criteria) {
86
+ if (report.findings === undefined) return;
87
+ const check = (condition, field, message) => { if (!condition) throw refused(new Error(`Report ${field} ${message}; correct the report and run check-report again`)); };
88
+ check(Array.isArray(report.findings), 'findings', 'must be an array');
89
+ const ids = new Set();
90
+ report.findings.forEach((finding, index) => {
91
+ const at = `findings[${index}]`;
92
+ check(isObject(finding), at, 'must be an object');
93
+ for (const key of Object.keys(finding)) check(findingFields.includes(key), `${at}.${key}`, `is not a finding field (${findingFields.join(', ')})`);
94
+ check(nonempty(finding.id) && !ids.has(finding.id), `${at}.id`, 'must be a nonempty id, unique in the report');
95
+ ids.add(finding.id);
96
+ check(findingClasses.includes(finding.class), `${at}.class`, `must be ${findingClasses.join(', ')}`);
97
+ check(findingOrigins.includes(finding.origin), `${at}.origin`, `must be ${findingOrigins.join(', ')}`);
98
+ check(nonempty(finding.summary), `${at}.summary`, 'must be a nonempty string');
99
+ for (const key of ['criterion', 'at', 'assumption']) check(finding[key] === undefined || nonempty(finding[key]), `${at}.${key}`, 'must be a nonempty string when given');
100
+ check(finding.criterion === undefined || criteria.some(item => item.id === finding.criterion), `${at}.criterion`, `names no criterion of this spec: ${finding.criterion}`);
101
+ check(finding.class === 'follow-up' || finding.criterion !== undefined || finding.at !== undefined, `${at}.criterion`, `or .at is required for a ${finding.class} finding`);
102
+ });
103
+ }
104
+
105
+ const findingPlace = finding => [finding.criterion && `criterion ${finding.criterion}`, finding.at].filter(Boolean).join(', ');
106
+
107
+ /** A blocking or decision-needed finding refuses completion with exit 2; a follow-up never does. */
108
+ function refuseHeldFindings(report, specId) {
109
+ const named = cls => (report.findings ?? []).filter(finding => finding.class === cls).map(finding => `${finding.id} (${findingPlace(finding)})`);
110
+ const blocking = named('blocking');
111
+ const decisions = named('decision-needed');
112
+ const reasons = [
113
+ ...(blocking.length ? [`blocking finding ${blocking.join(', ')}: fix it and get a fresh review`] : []),
114
+ ...(decisions.length ? [`decision-needed finding ${decisions.join(', ')}: spec ${specId} stays in-review and only its dependents wait; continue independent specs, ask the user, then get a fresh review`] : []),
115
+ ];
116
+ if (reasons.length) throw refused(new Error(`Report has ${reasons.join('; ')}`));
117
+ }
118
+
74
119
  function validatePassingReport(root, report, state, reportPath) {
75
120
  validateReview({ root, report, state, reportPath });
121
+ refuseHeldFindings(report, state.spec.id);
76
122
  requireValue(report.verdict === 'PASS', 'Report verdict must be PASS; FAIL or UNVERIFIED cannot complete a spec');
77
123
  requireValue(report.unresolved.length === 0, 'Report has unresolved review findings');
78
124
  }
@@ -130,13 +176,13 @@ export function recover({ root = process.cwd(), queuePath }) {
130
176
  return { status: 'restored', queuePath, specId: journal.specId };
131
177
  }
132
178
 
133
- async function writeCompletion({ root, queuePath, specId, state, metadataKey, metadata, validate, stableFiles }) {
179
+ async function writeCompletion({ root, queuePath, specId, state, status = 'done', metadataKey, metadata, validate, stableFiles }) {
134
180
  const updatedQueue = structuredClone(state.queue);
135
- Object.assign(updatedQueue.specs.find(spec => spec.id === specId), { status: 'done', [metadataKey]: metadata });
181
+ Object.assign(updatedQueue.specs.find(spec => spec.id === specId), { status, [metadataKey]: metadata });
136
182
  const journal = {
137
183
  schemaVersion: 1, queuePath, specId,
138
184
  files: [
139
- { path: state.specPath, before: state.specBytes, after: Buffer.from(state.status.replace('done')) },
185
+ { path: state.specPath, before: state.specBytes, after: Buffer.from(state.status.replace(status)) },
140
186
  { path: queuePath, before: state.queueBytes, after: Buffer.from(`${JSON.stringify(updatedQueue, null, 2)}\n`) },
141
187
  ].map(file => ({ path: file.path, before: { sha256: sha256(file.before), base64: file.before.toString('base64') }, after: { sha256: sha256(file.after), base64: file.after.toString('base64') } })),
142
188
  };
@@ -144,12 +190,14 @@ async function writeCompletion({ root, queuePath, specId, state, metadataKey, me
144
190
  try { saveExclusive(pendingFile, `${JSON.stringify(journal, null, 2)}\n`); } catch (error) {
145
191
  throw new Error(`${error.message}. ${recoveryHint(queuePath)}`);
146
192
  }
193
+ let written = 0;
147
194
  try {
148
195
  for (const stable of stableFiles) requireValue(sha256(readLocal(root, stable.path)) === stable.sha256, `${stable.label} changed during completion`);
149
196
  for (const file of journal.files) requireValue(sha256(readLocal(root, file.path)) === file.before.sha256, `Completion conflict: ${file.path} changed during validation`);
150
197
  validate(state);
151
198
  for (const file of journal.files) {
152
199
  requireValue(sha256(readLocal(root, file.path)) === file.before.sha256, `Completion conflict: ${file.path} changed before write`);
200
+ written += 1;
153
201
  replaceFile(root, file.path, Buffer.from(file.after.base64, 'base64'));
154
202
  }
155
203
  // Catch overlapping worker edits during the two writes before accepting them.
@@ -158,6 +206,12 @@ async function writeCompletion({ root, queuePath, specId, state, metadataKey, me
158
206
  validate(readQueue({ root, queuePath, specId }));
159
207
  unlinkSync(pendingFile);
160
208
  } catch (error) {
209
+ // Before the first write there is nothing to restore; a kept journal would
210
+ // only block the queue, or fail recovery over another writer's edit.
211
+ if (written === 0) {
212
+ unlinkSync(pendingFile);
213
+ throw new Error(`${error.message}. Neither status file was written.`);
214
+ }
161
215
  let restoration = 'The original statuses were restored.';
162
216
  try { restore(root, journal); } catch (restoreError) { restoration = restoreError.message; }
163
217
  throw new Error(`${error.message}. ${restoration} ${recoveryHint(queuePath)}`);
@@ -186,6 +240,35 @@ export async function complete({ root = process.cwd(), queuePath, specId, report
186
240
  return { status: 'done', unchanged: false, acceptedReport, implementationRevision: report.subject.implementationRevision };
187
241
  }
188
242
 
243
+ /**
244
+ * Move a todo spec whose dependencies are done to in-review: both status
245
+ * surfaces in one journaled write, plus a `submitted` record that subject
246
+ * bindings leave out, like status. An in-review spec is left unchanged. A
247
+ * criterion with no [AC:id] test is returned as a warning, never a refusal.
248
+ * Every refusal carries exitCode 2.
249
+ */
250
+ export async function submit({ root = process.cwd(), queuePath, specId }) {
251
+ try {
252
+ queuePath = relativePath(queuePath);
253
+ assertNoJournal(root, queuePath);
254
+ const state = readQueue({ root, queuePath, specId });
255
+ if (state.spec.status === 'in-review') return { status: 'in-review', unchanged: true, untraced: [] };
256
+ requireValue(state.spec.status === 'todo', `Spec ${specId} is done; submit moves only a todo spec to in-review`);
257
+ const requireDependencies = current => {
258
+ const unmet = current.spec.depends_on.filter(id => current.queue.specs.find(spec => spec.id === id).status !== 'done');
259
+ requireValue(unmet.length === 0, `Spec ${specId} depends on spec ${unmet.join(', spec ')}, which is not done`);
260
+ };
261
+ requireDependencies(state);
262
+ const { traceSpec } = await import('./trace.mjs');
263
+ const { untraced } = traceSpec({ root, queuePath, specId });
264
+ await writeCompletion({
265
+ root, queuePath, specId, state, status: 'in-review', metadataKey: 'submitted', metadata: { at: new Date().toISOString() },
266
+ stableFiles: [], validate: requireDependencies,
267
+ });
268
+ return { status: 'in-review', unchanged: false, untraced };
269
+ } catch (error) { throw refused(error); }
270
+ }
271
+
189
272
  /**
190
273
  * The native host attests the instruction text before this helper runs. Local
191
274
  * JSON cannot authenticate that a human said it, so this validates only the
@@ -457,13 +540,13 @@ export async function acceptWaiver({ root = process.cwd(), queuePath, specId, wa
457
540
 
458
541
  function argumentsFor(argv) {
459
542
  const [command, ...args] = argv;
460
- requireValue(['snapshot', 'scope', 'complete', 'finalize-review', 'accept-owner', 'accept-waiver', 'recover'].includes(command), 'Usage: completion.mjs scope --queue <path> --spec <id> | snapshot --queue <path> --spec <id> --out <subject.json> | complete|finalize-review --queue <path> --spec <id> --report <report.json> | accept-owner --queue <path> --spec <id> --decision <decision.json> | accept-waiver --queue <path> --spec <id> --waiver <waiver.json> [--report <report.json>] | recover --queue <path>');
543
+ requireValue(['snapshot', 'scope', 'submit', 'complete', 'finalize-review', 'accept-owner', 'accept-waiver', 'recover'].includes(command), 'Usage: completion.mjs scope|submit --queue <path> --spec <id> | snapshot --queue <path> --spec <id> --out <subject.json> | complete|finalize-review --queue <path> --spec <id> --report <report.json> | accept-owner --queue <path> --spec <id> --decision <decision.json> | accept-waiver --queue <path> --spec <id> --waiver <waiver.json> [--report <report.json>] | recover --queue <path>');
461
544
  const flags = {};
462
545
  for (let i = 0; i < args.length; i += 2) {
463
546
  requireValue(['--queue', '--spec', '--out', '--report', '--decision', '--waiver'].includes(args[i]) && nonempty(args[i + 1]) && flags[args[i]] === undefined, `Invalid or duplicate argument: ${args[i]}`);
464
547
  flags[args[i]] = args[i + 1];
465
548
  }
466
- const expected = command === 'recover' ? ['--queue'] : command === 'scope' ? ['--queue', '--spec'] : ['--queue', '--spec', command === 'snapshot' ? '--out' : command === 'accept-owner' ? '--decision' : command === 'accept-waiver' ? '--waiver' : '--report'];
549
+ const expected = command === 'recover' ? ['--queue'] : command === 'scope' || command === 'submit' ? ['--queue', '--spec'] : ['--queue', '--spec', command === 'snapshot' ? '--out' : command === 'accept-owner' ? '--decision' : command === 'accept-waiver' ? '--waiver' : '--report'];
467
550
  const optional = command === 'accept-waiver' ? ['--report'] : [];
468
551
  requireValue(expected.every(flag => flags[flag] !== undefined) && Object.keys(flags).every(flag => expected.includes(flag) || optional.includes(flag)), `Missing or unexpected arguments for ${command}`);
469
552
  if (command !== 'recover') requireValue(/^(?:0|[1-9]\d*)$/.test(flags['--spec']) && Number.isSafeInteger(Number(flags['--spec'])), 'Spec ID must be a nonnegative integer');
@@ -487,6 +570,9 @@ export async function main(argv = process.argv.slice(2)) {
487
570
  assertNoJournal(root, queuePath);
488
571
  const current = snapshot({ root, queuePath, specId: Number(flags['--spec']) });
489
572
  result = { queuePath: current.queuePath, specId: current.specId, changeScope: current.binding?.changeScope ?? null };
573
+ } else if (command === 'submit') {
574
+ result = await submit({ root, queuePath, specId: Number(flags['--spec']) });
575
+ for (const id of result.untraced) process.stderr.write(`Warning: criterion ${id} has no [AC:${id}] test in the spec's check inputs\n`);
490
576
  } else if (command === 'recover') result = recover({ root, queuePath });
491
577
  else if (command === 'accept-waiver') result = await acceptWaiver({ root, queuePath, specId: Number(flags['--spec']), waiverPath: flags['--waiver'], reportPath: flags['--report'] });
492
578
  else if (command === 'accept-owner') result = await acceptOwner({ root, queuePath, specId: Number(flags['--spec']), decisionPath: flags['--decision'] });
@@ -496,5 +582,5 @@ export async function main(argv = process.argv.slice(2)) {
496
582
  }
497
583
 
498
584
  if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
499
- main().catch(error => { process.stderr.write(`Completion stopped: ${error.message}\n`); process.exitCode = 1; });
585
+ main().catch(error => { process.stderr.write(`Completion stopped: ${error.message}\n`); process.exitCode = error.exitCode ?? 1; });
500
586
  }
@@ -544,5 +544,5 @@ export async function main(argv = process.argv.slice(2)) {
544
544
  }
545
545
 
546
546
  if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
547
- main().catch(error => { process.stderr.write(`Dispatch stopped: ${error.message}\n`); process.exitCode = 1; });
547
+ main().catch(error => { process.stderr.write(`Dispatch stopped: ${error.message}\n`); process.exitCode = error.exitCode ?? 1; });
548
548
  }
@@ -2,10 +2,50 @@ import { execFileSync } from 'node:child_process';
2
2
  import { existsSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs';
3
3
  import path from 'node:path';
4
4
  import { pathToFileURL } from 'node:url';
5
+ import { assertReviewAllowed, visibleReports } from './completion.mjs';
5
6
  import { readLease } from './coordinator.mjs';
6
7
  import { prepareDispatch } from './dispatch-preflight.mjs';
7
8
  import { traceSpec } from './trace.mjs';
8
- import { localPath, readQueue, relativePath, requireValue, validateNativeActor } from './identity.mjs';
9
+ import { canonical, isObject, localPath, readLocal, readQueue, relativePath, requireValue, sha256, snapshot, validateNativeActor } from './identity.mjs';
10
+
11
+ export const reviewLimit = 3;
12
+
13
+ /** A review round is one distinct set of reviewed inputs: each bound input's
14
+ * path and normalized sha256. HEAD is left out (implementationRevision, and so
15
+ * subject.identity), so a commit that changes no input keeps the round. Status
16
+ * is already outside the normalized queue and spec hashes. Returns null for a
17
+ * report with no bound inputs. */
18
+ export function reviewRoundKey(subject) {
19
+ const inputs = subject?.inputs;
20
+ if (!Array.isArray(inputs) || inputs.length === 0
21
+ || !inputs.every(input => isObject(input) && typeof input.path === 'string' && typeof input.sha256 === 'string')) return null;
22
+ const bound = inputs.map(input => ({ path: input.path, sha256: input.sha256 }))
23
+ .sort((left, right) => left.path.localeCompare(right.path, 'en'));
24
+ return `inputs:${sha256(canonical(bound))}`;
25
+ }
26
+
27
+ /** Earlier reviews of one spec, keyed by reviewRoundKey: repeat reviews of one
28
+ * set of inputs are one round. A report with no bound inputs is its own round,
29
+ * keyed by its path. The spec's own accepted PASS report is not a round. Reports
30
+ * are read from the worker root and the coordinator root, where visibleReports
31
+ * looks for them. */
32
+ function earlierReviews({ roots, queuePath, spec }) {
33
+ const rounds = new Map();
34
+ for (const root of roots) {
35
+ for (const { path: file, report } of visibleReports({ root, queuePath, specId: spec.id })) {
36
+ const accepted = spec.acceptedReport;
37
+ if (report.verdict === 'PASS' && accepted?.path === file && sha256(readLocal(root, file)) === accepted.sha256) continue;
38
+ const shown = root === roots[0] ? file : path.join(root, file);
39
+ const key = reviewRoundKey(report.subject) ?? `path:${file}`;
40
+ rounds.set(key, [...(rounds.get(key) ?? []), shown]);
41
+ }
42
+ }
43
+ return rounds;
44
+ }
45
+
46
+ class ReviewLimitError extends Error {
47
+ constructor(message) { super(message); this.exitCode = 2; }
48
+ }
9
49
 
10
50
  // The native hook runtime is optional; without it, startup takes the manual path.
11
51
  async function hookRuntime() {
@@ -40,7 +80,7 @@ export async function startDispatch(options, nativeEvent) {
40
80
  const rel = path.relative(root, parent);
41
81
  requireValue(rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel), 'Packet output parent must stay inside the worker root');
42
82
  requireValue(gitIgnored(root, outPath), `Packet output must be git-ignored so it never becomes a scope path: ${outPath}; use .joycraft/local/packets/`);
43
- const { queue } = readQueue({ root, queuePath: options.queuePath, specId: options.specId });
83
+ const { queue, queuePath, spec, specPath } = readQueue({ root, queuePath: options.queuePath, specId: options.specId });
44
84
  requireValue(options.role === 'implementer' || options.role === 'reviewer', 'Task startup role must be implementer or reviewer');
45
85
  // A claimed queue takes work only from its coordinator, so a second session's
46
86
  // instructions cannot reach this worker. An unclaimed queue keeps 1.0.0 behavior.
@@ -48,9 +88,26 @@ export async function startDispatch(options, nativeEvent) {
48
88
  requireValue(!lease || options.coordinatorSession === lease.sessionId,
49
89
  lease && `Queue ${queue.feature} is coordinated by session ${lease.sessionId}${lease.host ? ` on ${lease.host}` : ''}; pass --coordinator-session ${lease.sessionId} only when that session dispatched this task`);
50
90
  const coordinator = lease ? { sessionId: lease.sessionId, ...(lease.host ? { host: lease.host } : {}) } : null;
91
+ // A spec gets at most three reviews. A done spec keeps its earlier behavior, and
92
+ // a no-review waiver keeps its own refusal, so both are checked first.
93
+ let rounds;
94
+ if (options.role === 'reviewer' && spec.status !== 'done') {
95
+ const roots = [root];
96
+ if (options.coordinatorRoot !== undefined && existsSync(options.coordinatorRoot)) {
97
+ const coordinatorRoot = realpathSync(options.coordinatorRoot);
98
+ if (coordinatorRoot !== root) roots.push(coordinatorRoot);
99
+ }
100
+ for (const each of roots) assertReviewAllowed({ root: each, queuePath });
101
+ rounds = earlierReviews({ roots, queuePath, spec });
102
+ if (rounds.size > reviewLimit || (rounds.size === reviewLimit && !rounds.has(reviewRoundKey(snapshot({ root, queuePath, specId: spec.id }))))) {
103
+ throw new ReviewLimitError(`Review limit reached: ${queue.feature} spec ${spec.id} (${specPath}) has had ${rounds.size} reviews of different reviewed inputs (${[...rounds.values()].flat().join(', ')}); the limit is ${reviewLimit}. Do not start another review. Record the open findings under "## Decision needed" in ${specPath}, leave the spec in-review, and continue with independent ready work.`);
104
+ }
105
+ }
51
106
  // Change scope is opt-in per spec: startup never writes it, and a reviewer
52
107
  // without one reviews against the verification inputs alone.
53
108
  const packet = prepareDispatch({ ...options, outPath: output });
109
+ const review = rounds === undefined ? {}
110
+ : { reviewRound: rounds.size + (rounds.has(reviewRoundKey(packet.subject)) ? 0 : 1), reviewLimit };
54
111
  const runtime = await hookRuntime();
55
112
  const config = runtime ? await runtime.readConfig(root) : { enabled: false };
56
113
  const hooks = config.enabled
@@ -62,7 +119,7 @@ export async function startDispatch(options, nativeEvent) {
62
119
  try { const { criteria, untraced, unknownTags, missingFiles, note } = traceSpec({ root, queuePath: options.queuePath, specId: options.specId }); trace = { criteria, untraced, unknownTags, missingFiles, ...(note ? { note } : {}) }; }
63
120
  catch (error) { trace = { error: error.message }; }
64
121
  }
65
- return { schemaVersion: 1, packetPath: outPath, packet, hooks, coordinator, ...(trace ? { trace } : {}),
122
+ return { schemaVersion: 1, packetPath: outPath, packet, hooks, coordinator, ...review, ...(trace ? { trace } : {}),
66
123
  ready: !config.enabled || hooks.eligible === true };
67
124
  }
68
125
 
@@ -109,5 +166,5 @@ export async function main(argv = process.argv.slice(2)) {
109
166
  }
110
167
 
111
168
  if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
112
- main().catch(error => { process.stderr.write(`Task startup stopped: ${error.message}\n`); process.exitCode = 1; });
169
+ main().catch(error => { process.stderr.write(`Task startup stopped: ${error.message}\n`); process.exitCode = error instanceof ReviewLimitError ? 2 : 1; });
113
170
  }
@@ -1,3 +1,10 @@
1
+ import { execFileSync, spawn } from 'node:child_process';
2
+ import { createHash } from 'node:crypto';
3
+ import { closeSync, createReadStream, existsSync, fsyncSync, mkdirSync, openSync, realpathSync, unlinkSync } from 'node:fs';
4
+ import os from 'node:os';
5
+ import path from 'node:path';
6
+ import { pathToFileURL } from 'node:url';
7
+
1
8
  const kinds = new Set(['runtime', 'visual', 'structural']);
2
9
  const methods = new Set(['test', 'command', 'browser', 'manual', 'source']);
3
10
  const results = new Set(['PASS', 'FAIL', 'UNVERIFIED']);
@@ -139,3 +146,130 @@ export function validateEvidence(report, criteria) {
139
146
  }
140
147
  return { ok: errors.length === 0, errors };
141
148
  }
149
+
150
+ export const defaultTimeoutMs = 300000;
151
+ const graceMs = 2000;
152
+ const usage = 'Usage: evidence.mjs run --receipt <path> [--timeout-ms <n>] -- <command> [args...]';
153
+
154
+ const refusal = message => Object.assign(new Error(message), { exitCode: 2 });
155
+ const refuse = (condition, message) => { if (!condition) throw refusal(message); };
156
+
157
+ function gitIgnored(root, relative) {
158
+ try {
159
+ execFileSync('git', ['check-ignore', '-q', '--', relative], { cwd: root, stdio: 'ignore' });
160
+ return true;
161
+ } catch { return false; } // 1: not ignored; anything else: git cannot say, so not ignored.
162
+ }
163
+
164
+ /** Signal the process group led by pid; false once the group is gone. */
165
+ function signalGroup(pid, signal) {
166
+ try { process.kill(-pid, signal); return true; } catch (error) {
167
+ if (error.code === 'ESRCH' || error.code === 'EPERM') return false;
168
+ throw error;
169
+ }
170
+ }
171
+
172
+ /** SIGTERM the group, then SIGKILL whatever is left after the grace period. */
173
+ async function endGroup(pid) {
174
+ if (!signalGroup(pid, 'SIGTERM')) return;
175
+ for (const deadline = Date.now() + graceMs; Date.now() < deadline;) {
176
+ await new Promise(resolve => setTimeout(resolve, 50));
177
+ if (!signalGroup(pid, 0)) return;
178
+ }
179
+ signalGroup(pid, 'SIGKILL');
180
+ }
181
+
182
+ /** A new receipt path inside the project that git ignores or that sits in a
183
+ * feature folder under the configured features home. Refuses with exit 2. */
184
+ async function receiptFile(root, receipt) {
185
+ const { localPath, relativePath } = await import('./identity.mjs');
186
+ let relative, file;
187
+ try { relative = relativePath(receipt); file = localPath(root, relative, true); }
188
+ catch (error) { throw refusal(`Receipt must be a new project-relative path inside the project: ${error.message}`); }
189
+ refuse(!existsSync(file), `Receipt already exists: ${relative}; use a fresh receipt path`);
190
+ const { workPaths } = await import('./config.mjs');
191
+ let features;
192
+ try { features = workPaths(root).features.split('/'); } catch (error) { throw refusal(error.message); }
193
+ const parts = relative.split('/');
194
+ const featureFolder = parts.length > features.length + 1 && features.every((part, index) => parts[index] === part)
195
+ && existsSync(path.join(root, ...parts.slice(0, features.length + 1)));
196
+ refuse(featureFolder || gitIgnored(root, relative),
197
+ `Receipt must be git-ignored or inside a feature folder under ${features.join('/')}/: ${relative}`);
198
+ mkdirSync(path.dirname(file), { recursive: true });
199
+ const inside = path.relative(realpathSync(root), realpathSync(path.dirname(file)));
200
+ refuse(inside === '' || (inside !== '..' && !inside.startsWith(`..${path.sep}`) && !path.isAbsolute(inside)), `Receipt must stay inside the project: ${relative}`);
201
+ return { relative, file };
202
+ }
203
+
204
+ /**
205
+ * Run the project's own command once, without a shell, with CI=1 and a time
206
+ * limit. The child's stdout and stderr both go straight to one new receipt
207
+ * file, in the order the child wrote them, as `cmd > receipt 2>&1` would.
208
+ * Returns the observation's `command` and `receipts`, plus `timedOut`,
209
+ * `timeoutMs` and the ending `signal` when there was one. A timeout ends the
210
+ * child's process group (POSIX) or the child (Windows) and gives exitCode null.
211
+ * Every refusal happens before the child starts and carries exitCode 2.
212
+ */
213
+ export async function runEvidence({ root = process.cwd(), receipt, timeoutMs = defaultTimeoutMs, argv }) {
214
+ refuse(Array.isArray(argv) && argv.length > 0 && argv.every(value => typeof value === 'string') && argv[0] !== '', `A command is needed after --. ${usage}`);
215
+ refuse(Number.isSafeInteger(timeoutMs) && timeoutMs > 0 && timeoutMs <= 2 ** 31 - 1, `--timeout-ms must be a whole number of milliseconds from 1 to ${2 ** 31 - 1}`);
216
+ const { relative, file } = await receiptFile(root, receipt);
217
+ let fd;
218
+ try { fd = openSync(file, 'wx', 0o644); }
219
+ catch (error) { throw refusal(error.code === 'EEXIST' ? `Receipt already exists: ${relative}; use a fresh receipt path` : `Cannot create receipt ${relative}: ${error.message}`); }
220
+ const posix = process.platform !== 'win32';
221
+ let child;
222
+ try {
223
+ child = spawn(argv[0], argv.slice(1), { cwd: root, env: { ...process.env, CI: '1' }, stdio: ['ignore', fd, fd], detached: posix, windowsHide: true });
224
+ await new Promise((resolve, reject) => { child.once('spawn', resolve); child.once('error', reject); });
225
+ } catch (error) {
226
+ closeSync(fd);
227
+ unlinkSync(file);
228
+ throw refusal(`Could not start ${argv[0]}: ${error.message}`);
229
+ }
230
+ // The child runs in its own group, so pass on a stop that reaches only this process.
231
+ const stop = signal => { if (posix) signalGroup(child.pid, 'SIGKILL'); else child.kill('SIGKILL'); process.exit(128 + (os.constants.signals[signal] ?? 1)); };
232
+ const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
233
+ for (const signal of signals) process.on(signal, stop);
234
+ let timedOut = false;
235
+ const exited = new Promise(resolve => child.once('exit', (code, signal) => resolve({ code, signal })));
236
+ const timer = setTimeout(() => { timedOut = true; if (posix) endGroup(child.pid); else child.kill('SIGKILL'); }, timeoutMs);
237
+ const { code, signal } = await exited;
238
+ clearTimeout(timer);
239
+ // Leftover processes in the group would keep writing to the receipt after it is hashed.
240
+ if (posix) await endGroup(child.pid);
241
+ for (const each of signals) process.off(each, stop);
242
+ try { fsyncSync(fd); } finally { closeSync(fd); }
243
+ const digest = createHash('sha256');
244
+ for await (const chunk of createReadStream(file)) digest.update(chunk);
245
+ return {
246
+ command: { argv: [...argv], exitCode: timedOut ? null : code },
247
+ receipts: [{ path: relative, sha256: digest.digest('hex') }],
248
+ timedOut, timeoutMs, ...(signal ? { signal } : {}),
249
+ };
250
+ }
251
+
252
+ export async function main(args = process.argv.slice(2)) {
253
+ const [command, ...rest] = args;
254
+ refuse(command === 'run', usage);
255
+ const end = rest.indexOf('--');
256
+ refuse(end !== -1, `A command is needed after --. ${usage}`);
257
+ const flags = {};
258
+ for (let index = 0; index < end; index += 2) {
259
+ const key = rest[index]; const value = rest[index + 1];
260
+ refuse(['--receipt', '--timeout-ms'].includes(key) && index + 1 < end && typeof value === 'string' && value !== '' && flags[key] === undefined, `Invalid or duplicate argument: ${key}. ${usage}`);
261
+ flags[key] = value;
262
+ }
263
+ refuse(flags['--receipt'] !== undefined, `--receipt is required. ${usage}`);
264
+ refuse(flags['--timeout-ms'] === undefined || /^[1-9]\d*$/.test(flags['--timeout-ms']), '--timeout-ms must be a whole number of milliseconds');
265
+ const result = await runEvidence({ receipt: flags['--receipt'], argv: rest.slice(end + 1),
266
+ timeoutMs: flags['--timeout-ms'] === undefined ? defaultTimeoutMs : Number(flags['--timeout-ms']) });
267
+ process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
268
+ return result;
269
+ }
270
+
271
+ // Node runs the main module from its real path; resolve symlinks before comparing.
272
+ const invoked = (() => { try { return realpathSync(process.argv[1]); } catch { return null; } })();
273
+ if (invoked && import.meta.url === pathToFileURL(invoked).href) {
274
+ main().catch(error => { process.stderr.write(`Evidence run stopped: ${error.message}\n`); process.exitCode = error.exitCode ?? 1; });
275
+ }