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.
- package/README.md +154 -4
- package/dist/joycraft-release.json +1 -1
- package/package.json +3 -3
- package/payload/.agents/skills/joycraft-context/SKILL.md +5 -6
- package/payload/.agents/skills/joycraft-decompose/SKILL.md +9 -8
- package/payload/.agents/skills/joycraft-entry/SKILL.md +8 -19
- package/payload/.agents/skills/joycraft-implement/SKILL.md +16 -17
- package/payload/.agents/skills/joycraft-session-end/SKILL.md +10 -15
- package/payload/.agents/skills/joycraft-testing/SKILL.md +3 -9
- package/payload/.agents/skills/joycraft-verify/SKILL.md +20 -21
- package/payload/.claude/agents/joycraft-implementer.md +5 -5
- package/payload/.claude/agents/joycraft-reviewer.md +3 -6
- package/payload/.joycraft/contracts/types.d.ts +18 -0
- package/payload/.joycraft/references/architecture.md +2 -4
- package/payload/.joycraft/references/completion.md +16 -21
- package/payload/.joycraft/references/context.md +11 -34
- package/payload/.joycraft/references/dispatch.md +7 -40
- package/payload/.joycraft/references/gates.md +60 -0
- package/payload/.joycraft/references/retro.md +6 -15
- package/payload/.joycraft/references/settings.md +6 -3
- package/payload/.joycraft/references/setup.md +4 -4
- package/payload/.joycraft/references/testing.md +21 -21
- package/payload/.joycraft/references/worktrees.md +1 -1
- package/payload/.joycraft/runtime/completion.mjs +92 -6
- package/payload/.joycraft/runtime/dispatch-preflight.mjs +1 -1
- package/payload/.joycraft/runtime/dispatch-start.mjs +61 -4
- package/payload/.joycraft/runtime/evidence.mjs +134 -0
- package/payload/.joycraft/runtime/gate.mjs +308 -0
- package/payload/.joycraft/runtime/identity.mjs +5 -1
- package/payload/.joycraft/runtime/queue-check.mjs +355 -0
- package/payload/.joycraft/runtime/status.mjs +46 -5
- package/payload/PIN +31 -28
- 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
|
|
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(
|
|
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
|
+
}
|