joycraft 1.4.1 → 1.5.1
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 +109 -12
- package/dist/cli.js +24 -1
- package/dist/cli.js.map +1 -1
- package/dist/joycraft-release.json +1 -1
- package/package.json +3 -3
- package/payload/.agents/skills/joycraft-decompose/SKILL.md +9 -8
- package/payload/.agents/skills/joycraft-implement/SKILL.md +14 -11
- package/payload/.agents/skills/joycraft-session-end/SKILL.md +6 -3
- package/payload/.agents/skills/joycraft-testing/SKILL.md +3 -3
- package/payload/.agents/skills/joycraft-verify/SKILL.md +15 -13
- 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/completion.md +16 -21
- package/payload/.joycraft/references/gates.md +17 -17
- package/payload/.joycraft/references/testing.md +23 -23
- package/payload/.joycraft/runtime/completion.mjs +92 -6
- package/payload/.joycraft/runtime/dispatch-preflight.mjs +1 -1
- package/payload/.joycraft/runtime/evidence.mjs +136 -0
- package/payload/.joycraft/runtime/gate.mjs +51 -13
- package/payload/.joycraft/runtime/identity.mjs +5 -1
- package/payload/.joycraft/runtime/queue-check.mjs +355 -0
- package/payload/.joycraft/runtime/status.mjs +45 -4
- package/payload/PIN +20 -19
|
@@ -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
|
}
|
|
@@ -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,132 @@ 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
|
+
// The receipt is written either way; a failed, killed or timed-out command exits 1. Exit 2 is only for a refusal.
|
|
269
|
+
if (result.command.exitCode !== 0) process.exitCode = 1;
|
|
270
|
+
return result;
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
// Node runs the main module from its real path; resolve symlinks before comparing.
|
|
274
|
+
const invoked = (() => { try { return realpathSync(process.argv[1]); } catch { return null; } })();
|
|
275
|
+
if (invoked && import.meta.url === pathToFileURL(invoked).href) {
|
|
276
|
+
main().catch(error => { process.stderr.write(`Evidence run stopped: ${error.message}\n`); process.exitCode = error.exitCode ?? 1; });
|
|
277
|
+
}
|
|
@@ -61,8 +61,9 @@ export function checkGates(root = process.cwd()) {
|
|
|
61
61
|
const file = path.posix.join(path.posix.dirname(feature.queuePath), spec.file);
|
|
62
62
|
failures.push({ kind: 'unaccepted-done', feature: feature.feature, specId: spec.id, file, queuePath: feature.queuePath,
|
|
63
63
|
message: `Joycraft gate: ${feature.feature} spec ${spec.id} (${file}) is done with no accepted report, owner acceptance or waiver. `
|
|
64
|
-
+ 'Set it back to in-review in the queue and
|
|
65
|
-
+
|
|
64
|
+
+ 'Set it back to in-review in the queue and spec. Do not ask the user: it restores the true status. '
|
|
65
|
+
+ 'With no current PASS report, get an independent review, then complete it with '
|
|
66
|
+
+ `node .joycraft/runtime/completion.mjs finalize-review --queue ${feature.queuePath} --spec ${spec.id} --report <file>` });
|
|
66
67
|
}
|
|
67
68
|
}
|
|
68
69
|
const owner = new Map(status.features.flatMap(feature => feature.specs.map(row => [row.file, feature])));
|
|
@@ -78,8 +79,8 @@ export function checkGates(root = process.cwd()) {
|
|
|
78
79
|
// hook subcommand edits its text in place, so every byte it does not own keeps
|
|
79
80
|
// its value. Joycraft's hook is the one whose command is exactly hookCommand.
|
|
80
81
|
// Claude Code sends the agent back only when a Stop hook exits 2, with the
|
|
81
|
-
// reason on stderr; `check` does that
|
|
82
|
-
//
|
|
82
|
+
// reason on stderr; `check` does that. The exit code is the same when the
|
|
83
|
+
// event says stop_hook_active; only one line is added to the reason.
|
|
83
84
|
export const settingsFile = '.claude/settings.json';
|
|
84
85
|
export const hookCommand = 'node "$CLAUDE_PROJECT_DIR"/.joycraft/runtime/gate.mjs check --root "$CLAUDE_PROJECT_DIR"';
|
|
85
86
|
const hookGroup = { hooks: [{ type: 'command', command: hookCommand }] };
|
|
@@ -225,13 +226,14 @@ function readState(root) {
|
|
|
225
226
|
try { return JSON.parse(readFileSync(localPath(root, stateFile), 'utf8')); } catch { return null; }
|
|
226
227
|
}
|
|
227
228
|
|
|
228
|
-
|
|
229
|
+
// A hook added over an open problem would refuse every stop until the problem is cleared.
|
|
230
|
+
const clearFirst = 'Joycraft gate: nothing was written. Clear each problem above, then turn the gates on again.';
|
|
229
231
|
|
|
230
232
|
/** `hook --plan|--on|--off`: show, add or remove Joycraft's Stop hook in `.claude/settings.json`. */
|
|
231
233
|
export function hook(root, action) {
|
|
232
234
|
if (action !== 'off' && !claudeHost(root)) {
|
|
233
235
|
return { change: 'none', claude: false,
|
|
234
|
-
message:
|
|
236
|
+
message: 'The gate hook is for Claude Code only for now. Nothing was written. On this host, session end runs the same check.' };
|
|
235
237
|
}
|
|
236
238
|
if (action === 'off') {
|
|
237
239
|
const { file, before, data } = readSettings(root);
|
|
@@ -241,8 +243,12 @@ export function hook(root, action) {
|
|
|
241
243
|
return { file: settingsFile, change: 'none', message: `Joycraft's Stop hook is not in ${settingsFile}. Nothing was changed.` };
|
|
242
244
|
}
|
|
243
245
|
if (state?.after === before) {
|
|
244
|
-
if (state.before === null) rmSync(file); else writeFileSync(file, state.before);
|
|
245
246
|
rmSync(localPath(root, stateFile));
|
|
247
|
+
if (state.before === null) {
|
|
248
|
+
rmSync(file);
|
|
249
|
+
return { file: settingsFile, change: 'removed', message: `Removed ${settingsFile}: hook --on created it, and it held only Joycraft's Stop hook.` };
|
|
250
|
+
}
|
|
251
|
+
writeFileSync(file, state.before);
|
|
246
252
|
return { file: settingsFile, change: 'removed', message: `Removed Joycraft's Stop hook from ${settingsFile}. Every other line is as it was.` };
|
|
247
253
|
}
|
|
248
254
|
// No usable record: say what was cut, and claim nothing about the bytes before --on.
|
|
@@ -254,15 +260,19 @@ export function hook(root, action) {
|
|
|
254
260
|
}
|
|
255
261
|
const plan = planHook(root);
|
|
256
262
|
if (plan.change === 'none') return { file: settingsFile, change: 'none', message: `Joycraft's Stop hook is already in ${settingsFile}. Nothing was changed.` };
|
|
263
|
+
const problems = checkGates(root).failures.map(item => item.message);
|
|
257
264
|
if (action === 'plan') {
|
|
258
|
-
return { file: settingsFile, change: 'add', command: hookCommand, before: plan.before, after: plan.after,
|
|
259
|
-
message:
|
|
265
|
+
return { file: settingsFile, change: 'add', command: hookCommand, ...(problems.length ? { problems } : {}), before: plan.before, after: plan.after,
|
|
266
|
+
message: problems.length
|
|
267
|
+
? 'Plan only; nothing was written. hook --on refuses until the gate check finds none. Clear each problem you can by its next step, tell the user what you changed, then plan again.'
|
|
268
|
+
: `Plan only; nothing was written. Show this change to the user and run gate.mjs hook --on on their yes.` };
|
|
260
269
|
}
|
|
270
|
+
if (problems.length) return { file: settingsFile, change: 'none', problems, message: clearFirst };
|
|
261
271
|
mkdirSync(path.dirname(plan.file), { recursive: true });
|
|
262
272
|
writeFileSync(localPath(root, settingsFile, true), plan.after);
|
|
263
273
|
writeState(root, { file: settingsFile, before: plan.before, after: plan.after });
|
|
264
274
|
return { file: settingsFile, change: 'added',
|
|
265
|
-
message: `Added Joycraft's Stop hook to ${settingsFile}. Claude Code now runs the gate check each time it ends a reply.
|
|
275
|
+
message: `Added Joycraft's Stop hook to ${settingsFile}. Claude Code now runs the gate check each time it ends a reply. To turn it off, the user says "Turn off Joycraft's gates".` };
|
|
266
276
|
}
|
|
267
277
|
|
|
268
278
|
export function main(argv = process.argv.slice(2)) {
|
|
@@ -280,6 +290,12 @@ export function main(argv = process.argv.slice(2)) {
|
|
|
280
290
|
}
|
|
281
291
|
if (action === undefined) throw new Error(usage);
|
|
282
292
|
const result = hook(path.resolve(root ?? '.'), action);
|
|
293
|
+
// --on over open problems: the same exit 2 and stderr lines as the check, then what to do.
|
|
294
|
+
if (action === 'on' && result.problems) {
|
|
295
|
+
process.stderr.write(`${[...result.problems, result.message].join('\n')}\n`);
|
|
296
|
+
process.exitCode = 2;
|
|
297
|
+
return result;
|
|
298
|
+
}
|
|
283
299
|
process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
|
|
284
300
|
process.exitCode = 0;
|
|
285
301
|
return result;
|
|
@@ -295,14 +311,36 @@ export function main(argv = process.argv.slice(2)) {
|
|
|
295
311
|
}
|
|
296
312
|
const result = checkGates(path.resolve(flags.root ?? '.'));
|
|
297
313
|
const lines = [...(flags.verbose ? result.skipped.map(item => item.message) : []), ...result.failures.map(item => item.message)];
|
|
298
|
-
if (lines.length) process.stderr.write(`${lines.join('\n')}\n`);
|
|
299
314
|
process.exitCode = result.failures.length ? 2 : 0;
|
|
300
|
-
|
|
315
|
+
// Every stop is checked, also a repeated one; a repeated one only gets one more line.
|
|
316
|
+
const write = () => { if (lines.length) process.stderr.write(`${lines.join('\n')}\n`); return result; };
|
|
317
|
+
if (!result.failures.length) return write();
|
|
318
|
+
return stopEvent().then(event => {
|
|
319
|
+
if (event?.stop_hook_active === true) lines.push(blockedAgain);
|
|
320
|
+
return write();
|
|
321
|
+
});
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
const blockedAgain = 'Joycraft gate: this stop was blocked before for the same reason. Do the step now; do not ask the user again.';
|
|
325
|
+
|
|
326
|
+
/** The Stop event Claude Code writes on stdin, or null: no event within a short wait, a terminal, or not JSON. */
|
|
327
|
+
function stopEvent(waitMs = 1000) {
|
|
328
|
+
if (process.stdin.isTTY) return Promise.resolve(null);
|
|
329
|
+
return new Promise(resolve => {
|
|
330
|
+
let text = '';
|
|
331
|
+
const done = value => { clearTimeout(timer); process.stdin.removeAllListeners(); process.stdin.destroy(); resolve(value); };
|
|
332
|
+
const timer = setTimeout(() => done(null), waitMs);
|
|
333
|
+
process.stdin.setEncoding('utf8');
|
|
334
|
+
process.stdin.on('data', chunk => { text += chunk; });
|
|
335
|
+
process.stdin.on('end', () => { try { done(JSON.parse(text)); } catch { done(null); } });
|
|
336
|
+
process.stdin.on('error', () => done(null));
|
|
337
|
+
});
|
|
301
338
|
}
|
|
302
339
|
|
|
303
340
|
// Node runs the main module from its real path; a hook may name it through a symlinked project path.
|
|
304
341
|
const invoked = (() => { try { return realpathSync(process.argv[1]); } catch { return null; } })();
|
|
305
342
|
if (invoked && import.meta.url === pathToFileURL(invoked).href) {
|
|
306
343
|
const prefix = process.argv[2] === 'hook' ? 'Gate hook stopped' : 'Gate check stopped';
|
|
307
|
-
|
|
344
|
+
const stopped = error => { process.stderr.write(`${prefix}: ${error.message}\n`); process.exitCode = 1; };
|
|
345
|
+
try { Promise.resolve(main()).catch(stopped); } catch (error) { stopped(error); }
|
|
308
346
|
}
|
|
@@ -184,6 +184,9 @@ export function validateQueue(queue, { select } = {}) {
|
|
|
184
184
|
if (input.state !== undefined) requireValue(input.state === 'absent' && input.kind !== 'requirement', `Verification input ${inputPath} at index ${inputIndex} may use state: absent only for code, check or fixture inputs`);
|
|
185
185
|
}
|
|
186
186
|
if (spec.verification.changeScope !== undefined) validateChangeScope(spec.verification.changeScope, relativePath);
|
|
187
|
+
if (spec.submitted !== undefined) {
|
|
188
|
+
requireValue(isObject(spec.submitted) && Object.keys(spec.submitted).every(key => key === 'at') && nonempty(spec.submitted.at) && Number.isFinite(Date.parse(spec.submitted.at)), `Invalid submit record for spec ${spec.id}`);
|
|
189
|
+
}
|
|
187
190
|
if (spec.acceptedReport !== undefined) {
|
|
188
191
|
requireValue(isObject(spec.acceptedReport) && isSha256(spec.acceptedReport.sha256), `Invalid accepted report for spec ${spec.id}`);
|
|
189
192
|
relativePath(spec.acceptedReport.path);
|
|
@@ -240,10 +243,11 @@ export function subjectIdentity(subject) {
|
|
|
240
243
|
return sha256(canonical(fields));
|
|
241
244
|
}
|
|
242
245
|
|
|
243
|
-
/** Queue status and completion receipt metadata do not change reviewed requirements. */
|
|
246
|
+
/** Queue status, the submit record and completion receipt metadata do not change reviewed requirements. */
|
|
244
247
|
function queueSpecRequirements(spec) {
|
|
245
248
|
const requirements = { ...spec };
|
|
246
249
|
delete requirements.status;
|
|
250
|
+
delete requirements.submitted;
|
|
247
251
|
delete requirements.acceptedReport;
|
|
248
252
|
delete requirements.ownerAcceptance;
|
|
249
253
|
delete requirements.waiver;
|