joycraft 0.7.16 → 1.0.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 +137 -156
- package/dist/cli.js +1593 -373
- package/dist/cli.js.map +1 -1
- package/dist/index.d.ts +4 -0
- package/dist/index.js +3 -0
- package/dist/index.js.map +1 -1
- package/dist/joycraft-release.json +1 -1
- package/package.json +9 -3
- package/payload/.agents/skills/joycraft-context/SKILL.md +36 -0
- package/payload/.agents/skills/joycraft-decompose/SKILL.md +68 -0
- package/payload/.agents/skills/joycraft-entry/SKILL.md +103 -0
- package/payload/.agents/skills/joycraft-implement/SKILL.md +106 -0
- package/payload/.agents/skills/joycraft-retro/SKILL.md +54 -0
- package/payload/.agents/skills/joycraft-retro/agents/openai.yaml +5 -0
- package/payload/.agents/skills/joycraft-session-end/SKILL.md +78 -0
- package/payload/.agents/skills/joycraft-testing/SKILL.md +60 -0
- package/payload/.agents/skills/joycraft-ui-slice/SKILL.md +59 -0
- package/payload/.agents/skills/joycraft-ui-slice/scripts/serve.mjs +97 -0
- package/payload/.agents/skills/joycraft-verify/SKILL.md +103 -0
- package/payload/.claude/agents/joycraft-implementer.md +31 -0
- package/payload/.claude/agents/joycraft-reviewer.md +30 -0
- package/payload/.joycraft/assets/artifacts/kit.css +102 -0
- package/payload/.joycraft/assets/artifacts/kit.js +301 -0
- package/payload/.joycraft/assets/artifacts/transports.js +236 -0
- package/payload/.joycraft/contracts/types.d.ts +185 -0
- package/payload/.joycraft/references/architecture.md +90 -0
- package/payload/.joycraft/references/archive.md +211 -0
- package/payload/.joycraft/references/artifacts.md +176 -0
- package/payload/.joycraft/references/completion.md +109 -0
- package/payload/.joycraft/references/context.md +80 -0
- package/payload/.joycraft/references/delivery.md +32 -0
- package/payload/.joycraft/references/dispatch.md +226 -0
- package/payload/.joycraft/references/recurring-failures.md +33 -0
- package/payload/.joycraft/references/retro.md +94 -0
- package/payload/.joycraft/references/setup.md +279 -0
- package/payload/.joycraft/references/testing.md +120 -0
- package/payload/.joycraft/references/update.md +44 -0
- package/payload/.joycraft/references/workflow.md +113 -0
- package/payload/.joycraft/references/worktrees.md +148 -0
- package/payload/.joycraft/runtime/archive.mjs +463 -0
- package/payload/.joycraft/runtime/artifacts/cli.mjs +61 -0
- package/payload/.joycraft/runtime/artifacts/decisions.mjs +214 -0
- package/payload/.joycraft/runtime/artifacts/model.mjs +161 -0
- package/payload/.joycraft/runtime/artifacts/preferences.mjs +127 -0
- package/payload/.joycraft/runtime/artifacts/render.mjs +21 -0
- package/payload/.joycraft/runtime/artifacts/server.mjs +40 -0
- package/payload/.joycraft/runtime/completion.mjs +300 -0
- package/payload/.joycraft/runtime/context/cli.mjs +75 -0
- package/payload/.joycraft/runtime/context/index.mjs +29 -0
- package/payload/.joycraft/runtime/context/search.mjs +149 -0
- package/payload/.joycraft/runtime/delivery.mjs +142 -0
- package/payload/.joycraft/runtime/dispatch-preflight.mjs +535 -0
- package/payload/.joycraft/runtime/dispatch-start.mjs +98 -0
- package/payload/.joycraft/runtime/evidence.mjs +137 -0
- package/payload/.joycraft/runtime/identity.mjs +486 -0
- package/payload/.joycraft/runtime/kickoff.mjs +174 -0
- package/payload/.joycraft/runtime/redact.mjs +9 -0
- package/payload/.joycraft/runtime/retro.mjs +151 -0
- package/payload/.joycraft/runtime/review-tools.json +34 -0
- package/payload/.joycraft/runtime/review-tools.mjs +331 -0
- package/payload/.joycraft/runtime/scope.mjs +129 -0
- package/payload/.joycraft/runtime/update-check.mjs +142 -0
- package/payload/.joycraft/templates/README.md +7 -0
- package/payload/.joycraft/templates/artifact.json +33 -0
- package/payload/.joycraft/templates/brief.md +35 -0
- package/payload/.joycraft/templates/decisions.md +13 -0
- package/payload/.joycraft/templates/project-context.md +36 -0
- package/payload/.joycraft/templates/queue.json +27 -0
- package/payload/.joycraft/templates/spec.md +39 -0
- package/payload/.joycraft/templates/ui-slice.html +71 -0
- package/payload/PIN +74 -0
- package/payload/scripts/export.mjs +301 -0
- package/payload/scripts/hook-paths.mjs +35 -0
- package/payload/scripts/legacy-hooks.mjs +128 -0
- package/payload/scripts/legacy-inventory.json +117 -0
- package/dist/chunk-35RQLGKM.js +0 -2167
- package/dist/chunk-35RQLGKM.js.map +0 -1
- package/dist/chunk-7BPB2IKY.js +0 -255
- package/dist/chunk-7BPB2IKY.js.map +0 -1
- package/dist/chunk-B73DPYYC.js +0 -377
- package/dist/chunk-B73DPYYC.js.map +0 -1
- package/dist/chunk-GTP7Z52K.js +0 -3942
- package/dist/chunk-GTP7Z52K.js.map +0 -1
- package/dist/chunk-K4AI6FKB.js +0 -417
- package/dist/chunk-K4AI6FKB.js.map +0 -1
- package/dist/chunk-KKDKC4FM.js +0 -115
- package/dist/chunk-KKDKC4FM.js.map +0 -1
- package/dist/chunk-OMFGDJW4.js +0 -97
- package/dist/chunk-OMFGDJW4.js.map +0 -1
- package/dist/chunk-Z5JFEGWG.js +0 -563
- package/dist/chunk-Z5JFEGWG.js.map +0 -1
- package/dist/init-MUB5CC6L.js +0 -60
- package/dist/init-MUB5CC6L.js.map +0 -1
- package/dist/init-autofix-2DMBO4QN.js +0 -122
- package/dist/init-autofix-2DMBO4QN.js.map +0 -1
- package/dist/install-manifest-EQHT4474.js +0 -37
- package/dist/install-manifest-EQHT4474.js.map +0 -1
- package/dist/release-artifact-4TL5L2ZY.js +0 -14
- package/dist/release-artifact-4TL5L2ZY.js.map +0 -1
- package/dist/release-resolver-P2H46QTU.js +0 -293
- package/dist/release-resolver-P2H46QTU.js.map +0 -1
- package/dist/telemetry-store-IBO5GRTA.js +0 -14
- package/dist/telemetry-store-IBO5GRTA.js.map +0 -1
- package/dist/update-LFLQTPUA.js +0 -19
- package/dist/update-LFLQTPUA.js.map +0 -1
- package/dist/update-check-YT765NE7.js +0 -36
- package/dist/update-check-YT765NE7.js.map +0 -1
- package/dist/upgrade-L5WERK4X.js +0 -28
- package/dist/upgrade-L5WERK4X.js.map +0 -1
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
import { createHash } from 'node:crypto';
|
|
2
|
+
import { appendFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
|
|
3
|
+
import path from 'node:path';
|
|
4
|
+
import { pathToFileURL } from 'node:url';
|
|
5
|
+
|
|
6
|
+
// The kickoff captures a founder's context in a bare project. The agent runs the
|
|
7
|
+
// conversation; this helper keeps the parts that must not drift: detection, the
|
|
8
|
+
// verbatim notes, the question budget, and the write rules.
|
|
9
|
+
export const notesPath = 'docs/context/kickoff-notes.md';
|
|
10
|
+
export const statePath = '.joycraft/local/kickoff.json';
|
|
11
|
+
export const topics = ['users-and-purpose', 'first-outcome', 'constraints', 'stack', 'non-goals', 'undecided'];
|
|
12
|
+
export const questionsPerRound = 3;
|
|
13
|
+
// Files a kickoff may create: knowledge homes and host entry files, never a manifest or source.
|
|
14
|
+
const knowledgeFile = /^(docs\/.+\.md|AGENTS\.md|CLAUDE\.md|GEMINI\.md|\.github\/copilot-instructions\.md)$/;
|
|
15
|
+
const skipDirs = new Set(['node_modules', '.git']);
|
|
16
|
+
|
|
17
|
+
const read = file => { try { return readFileSync(file, 'utf8'); } catch { return null; } };
|
|
18
|
+
|
|
19
|
+
function files(root, dir = '') {
|
|
20
|
+
const out = [];
|
|
21
|
+
let entries;
|
|
22
|
+
try { entries = readdirSync(path.join(root, dir), { withFileTypes: true }); } catch { return out; }
|
|
23
|
+
for (const entry of entries) {
|
|
24
|
+
if (skipDirs.has(entry.name)) continue;
|
|
25
|
+
const rel = dir ? `${dir}/${entry.name}` : entry.name;
|
|
26
|
+
if (entry.isDirectory()) out.push(...files(root, rel));
|
|
27
|
+
else out.push(rel);
|
|
28
|
+
}
|
|
29
|
+
return out.sort();
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** Bare: nothing outside docs/, README*, LICENSE*, host entry files and dotfiles. */
|
|
33
|
+
export function detectBare(root) {
|
|
34
|
+
const source = files(root).filter(file => !file.split('/').some(part => part.startsWith('.'))
|
|
35
|
+
&& !file.startsWith('docs/') && !/^(README|LICENSE|AGENTS\.md$|CLAUDE\.md$|GEMINI\.md$)/i.test(file));
|
|
36
|
+
return { bare: source.length === 0, source: source.slice(0, 5) };
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/** Offer automatically only on a bare project; an explicit request works anywhere. */
|
|
40
|
+
export function shouldOffer(root, { requested = false } = {}) {
|
|
41
|
+
return requested || detectBare(root).bare;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
const hash = text => createHash('sha256').update(text).digest('hex');
|
|
45
|
+
const readState = root => JSON.parse(read(path.join(root, statePath)) ?? 'null');
|
|
46
|
+
function writeState(root, state) {
|
|
47
|
+
const dir = path.join(root, path.dirname(statePath));
|
|
48
|
+
if (!existsSync(dir)) {
|
|
49
|
+
mkdirSync(dir, { recursive: true, mode: 0o700 });
|
|
50
|
+
writeFileSync(path.join(dir, '.gitignore'), '*\n', { flag: 'wx', mode: 0o600 });
|
|
51
|
+
}
|
|
52
|
+
writeFileSync(path.join(root, statePath), `${JSON.stringify(state, null, 2)}\n`);
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** Record what exists before the kickoff writes anything, so the check can prove what changed. */
|
|
56
|
+
export function startKickoff(root) {
|
|
57
|
+
const before = Object.fromEntries(files(root).map(file => [file, hash(readFileSync(path.join(root, file)))]));
|
|
58
|
+
const agents = read(path.join(root, 'AGENTS.md'));
|
|
59
|
+
const state = { schemaVersion: 1, before, agentsLines: agents ? agents.split('\n').filter(line => line.trim()) : [], answered: [], rounds: 0, done: false };
|
|
60
|
+
writeState(root, state);
|
|
61
|
+
return state;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** Append one user message verbatim; summarizing happens elsewhere, at the end. */
|
|
65
|
+
export function appendNote(root, text) {
|
|
66
|
+
const file = path.join(root, notesPath);
|
|
67
|
+
if (!existsSync(file)) {
|
|
68
|
+
mkdirSync(path.dirname(file), { recursive: true });
|
|
69
|
+
writeFileSync(file, '# Kickoff notes\n\nThe user\'s own words from the project kickoff, verbatim and in order. Summaries live in the linked context files.\n');
|
|
70
|
+
}
|
|
71
|
+
appendFileSync(file, `\n---\n\n${text.replace(/\s+$/, '')}\n`);
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/** Mark topics the user has answered and return the next round: at most three open topics, none repeated. */
|
|
75
|
+
export function nextRound(root, { answered = [], enough = false } = {}) {
|
|
76
|
+
const state = readState(root) ?? startKickoff(root);
|
|
77
|
+
for (const topic of answered) {
|
|
78
|
+
if (!topics.includes(topic)) throw new Error(`Unknown kickoff topic: ${topic}; use ${topics.join(', ')}`);
|
|
79
|
+
if (!state.answered.includes(topic)) state.answered.push(topic);
|
|
80
|
+
}
|
|
81
|
+
const open = topics.filter(topic => !state.answered.includes(topic));
|
|
82
|
+
state.done = enough || open.length === 0;
|
|
83
|
+
const ask = state.done ? [] : open.slice(0, questionsPerRound);
|
|
84
|
+
if (ask.length) state.rounds += 1;
|
|
85
|
+
writeState(root, state);
|
|
86
|
+
return { ask, open, done: state.done, rounds: state.rounds };
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
function links(text) {
|
|
90
|
+
return [...text.matchAll(/\]\(([^)#\s]+)(?:#[^)]*)?\)/g)].map(match => match[1]).filter(link => !/^[a-z]+:/i.test(link));
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/** The write rules: no scaffold or manifest, no empty file, no dangling link, existing guidance kept. */
|
|
94
|
+
export function checkKickoff(root) {
|
|
95
|
+
const state = readState(root);
|
|
96
|
+
if (!state) throw new Error('No kickoff in progress; run start first');
|
|
97
|
+
const problems = [];
|
|
98
|
+
const now = files(root);
|
|
99
|
+
for (const file of now) {
|
|
100
|
+
if (file.split('/').some(part => part.startsWith('.'))) continue;
|
|
101
|
+
if (!(file in state.before) && !knowledgeFile.test(file)) problems.push(`created ${file}: the kickoff writes knowledge files only, no scaffold or manifest`);
|
|
102
|
+
if (file in state.before && state.before[file] !== hash(readFileSync(path.join(root, file))) && !knowledgeFile.test(file)) problems.push(`changed ${file}`);
|
|
103
|
+
}
|
|
104
|
+
for (const file of now.filter(name => knowledgeFile.test(name) && !(name in state.before && state.before[name] === hash(readFileSync(path.join(root, name)))))) {
|
|
105
|
+
const text = readFileSync(path.join(root, file), 'utf8');
|
|
106
|
+
if (!text.trim() || !text.split('\n').some(line => line.trim() && !line.startsWith('#'))) problems.push(`${file} is empty`);
|
|
107
|
+
for (const link of links(text)) {
|
|
108
|
+
const target = path.posix.normalize(path.posix.join(path.posix.dirname(file), link));
|
|
109
|
+
if (target.startsWith('..') || !existsSync(path.join(root, target))) problems.push(`${file} links to missing ${link}`);
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
const agents = read(path.join(root, 'AGENTS.md'));
|
|
113
|
+
if (state.agentsLines.length) {
|
|
114
|
+
const kept = agents ? agents.split('\n') : [];
|
|
115
|
+
let at = 0;
|
|
116
|
+
for (const line of state.agentsLines) {
|
|
117
|
+
const found = kept.indexOf(line, at);
|
|
118
|
+
if (found < 0) { problems.push(`AGENTS.md lost an existing line: ${line.slice(0, 60)}`); break; }
|
|
119
|
+
at = found + 1;
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
return problems;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/** One screen: each written file and what it holds. */
|
|
126
|
+
export function summary(root) {
|
|
127
|
+
const state = readState(root);
|
|
128
|
+
if (!state) throw new Error('No kickoff in progress; run start first');
|
|
129
|
+
const lines = ['Captured in the kickoff:'];
|
|
130
|
+
for (const file of files(root).filter(name => knowledgeFile.test(name))) {
|
|
131
|
+
const text = readFileSync(path.join(root, file), 'utf8');
|
|
132
|
+
if (state.before[file] === hash(text)) continue;
|
|
133
|
+
const headings = [...text.matchAll(/^#{2,3} (.+)$/gm)].map(match => match[1]).filter(heading => heading !== 'Sources');
|
|
134
|
+
const what = file === notesPath ? [`${text.split('\n---\n').length - 1} message(s), verbatim`]
|
|
135
|
+
: headings.length ? [headings.slice(0, 6).join(', ')] : [text.split('\n').find(line => line.trim() && !line.startsWith('#'))?.slice(0, 100) ?? ''];
|
|
136
|
+
lines.push(`- ${file}${file in state.before ? ' (edited)' : ' (new)'}: ${what.join(' ')}`);
|
|
137
|
+
}
|
|
138
|
+
const open = topics.filter(topic => !state.answered.includes(topic));
|
|
139
|
+
if (open.length) lines.push(`Still open: ${open.join(', ')}.`);
|
|
140
|
+
lines.push('What should I correct before the first brief?');
|
|
141
|
+
return lines.join('\n');
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
export async function main(argv = process.argv.slice(2)) {
|
|
145
|
+
const [command, ...rest] = argv;
|
|
146
|
+
const flags = {};
|
|
147
|
+
for (let index = 0; index < rest.length; index += 1) {
|
|
148
|
+
if (['--enough', '--requested'].includes(rest[index])) { flags[rest[index]] = true; continue; }
|
|
149
|
+
flags[rest[index]] = rest[index + 1]; index += 1;
|
|
150
|
+
}
|
|
151
|
+
const root = path.resolve(flags['--root'] ?? '.');
|
|
152
|
+
requireDir(root);
|
|
153
|
+
let result;
|
|
154
|
+
if (command === 'detect') result = { ...detectBare(root), offer: shouldOffer(root, { requested: flags['--requested'] === true }) };
|
|
155
|
+
else if (command === 'start') { startKickoff(root); result = { started: true, notes: notesPath }; }
|
|
156
|
+
else if (command === 'note') { appendNote(root, readFileSync(0, 'utf8')); result = { appended: notesPath }; }
|
|
157
|
+
else if (command === 'round') result = nextRound(root, { answered: (flags['--answered'] ?? '').split(',').filter(Boolean), enough: flags['--enough'] === true });
|
|
158
|
+
else if (command === 'check') {
|
|
159
|
+
const problems = checkKickoff(root);
|
|
160
|
+
result = { ok: problems.length === 0, problems };
|
|
161
|
+
if (problems.length) process.exitCode = 2;
|
|
162
|
+
} else if (command === 'summary') { process.stdout.write(`${summary(root)}\n`); return null; }
|
|
163
|
+
else throw new Error('Usage: kickoff.mjs detect|start|note|round|check|summary --root <project> [--requested] [--answered topics] [--enough]');
|
|
164
|
+
process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
|
|
165
|
+
return result;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
function requireDir(root) {
|
|
169
|
+
if (!lstatSync(root).isDirectory()) throw new Error(`Not a directory: ${root}`);
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
|
|
173
|
+
main().catch(error => { process.stderr.write(`Kickoff stopped: ${error.message}\n`); process.exitCode = 1; });
|
|
174
|
+
}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/** Pattern redaction for common credential forms. Not comprehensive; use it on text shown or stored, never as a security boundary. */
|
|
2
|
+
export function redact(text) {
|
|
3
|
+
return String(text).replace(/-----BEGIN [^-]*(?:PRIVATE KEY|CERTIFICATE)-----[\s\S]*?(?:-----END [^-]+-----|$)/g, '[REDACTED]')
|
|
4
|
+
.replace(/\bsk[-_][A-Za-z0-9_-]{12,}\b/g, '[REDACTED]')
|
|
5
|
+
.replace(/\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|AKIA[A-Z0-9]{16}|xox[baprs]-[A-Za-z0-9-]+)\b/g, '[REDACTED]')
|
|
6
|
+
.replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, '[REDACTED]')
|
|
7
|
+
.replace(/\b(Authorization\s*[:=]\s*(?:Bearer\s+)?)[^\s'";]+/gi, '$1[REDACTED]')
|
|
8
|
+
.replace(/(["']?[A-Z0-9_]*(?:API_KEY|APIKEY|TOKEN|PASSWORD|SECRET|ACCESS_KEY)[A-Z0-9_]*["']?\s*[=:]\s*)(?:"[^"\n]*"|'[^'\n]*'|[^\s;,}\]]+)/gi, '$1[REDACTED]');
|
|
9
|
+
}
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
import { readFile, lstat, mkdir, writeFile, rename, chmod, rm } from 'node:fs/promises';
|
|
2
|
+
import { dirname, resolve } from 'node:path';
|
|
3
|
+
import { createHash, randomUUID } from 'node:crypto';
|
|
4
|
+
import { TextDecoder } from 'node:util';
|
|
5
|
+
import { redact } from './redact.mjs';
|
|
6
|
+
|
|
7
|
+
const PREVIEW_BYTES = 1_024;
|
|
8
|
+
const sha256 = value => createHash('sha256').update(value).digest('hex');
|
|
9
|
+
const plain = value => typeof value === 'string' ? value : '';
|
|
10
|
+
const safeString = value => value === null || value === undefined ? null : redact(String(value));
|
|
11
|
+
const at = (object, ...paths) => paths.map(path => path.split('.').reduce((value, key) => value && typeof value === 'object' ? value[key] : undefined, object)).find(value => value !== undefined);
|
|
12
|
+
const textBlocks = content => Array.isArray(content) ? content.filter(block => block && typeof block === 'object' && (block.type === 'text' || block.type === 'input_text' || block.type === 'output_text')).map(block => plain(block.text)).join('') : plain(content);
|
|
13
|
+
const preview = text => {
|
|
14
|
+
const safe = redact(text); const bytes = Buffer.byteLength(safe); const cut = Buffer.from(safe).subarray(0, PREVIEW_BYTES).toString('utf8');
|
|
15
|
+
return { text: cut, partial: bytes > PREVIEW_BYTES, byteCount: Buffer.byteLength(text) };
|
|
16
|
+
};
|
|
17
|
+
const stamp = record => at(record, 'timestamp', 'ts', 'time', 'payload.timestamp') ?? null;
|
|
18
|
+
|
|
19
|
+
function gap(state, kind, line, raw) { state.gaps.push({ kind, line, sha256: sha256(raw) }); }
|
|
20
|
+
function addTool(state, kind, value, line, raw, timestamp) {
|
|
21
|
+
const rawCallId = plain(at(value, 'id', 'tool_use_id', 'call_id', 'tool_call_id')) || null;
|
|
22
|
+
const callId = safeString(rawCallId);
|
|
23
|
+
const name = safeString(at(value, 'name', 'function.name'));
|
|
24
|
+
const payload = kind === 'call' ? at(value, 'input', 'arguments', 'function.arguments') : at(value, 'content', 'output', 'result');
|
|
25
|
+
const original = typeof payload === 'string' ? payload : payload === undefined ? '' : JSON.stringify(payload);
|
|
26
|
+
const observedError = at(value, 'is_error', 'isError', 'error');
|
|
27
|
+
const entry = { eventType: safeString(value.type) || (kind === 'call' ? 'tool_call' : 'tool_result'), name, callId, observedAt: safeString(timestamp), source: { line, sha256: sha256(raw) }, isError: typeof observedError === 'boolean' ? observedError : null, exitCode: Number.isInteger(at(value, 'exit_code', 'exitCode')) ? at(value, 'exit_code', 'exitCode') : null, durationMs: typeof at(value, 'duration_ms', 'durationMs') === 'number' ? at(value, 'duration_ms', 'durationMs') : null, ...(kind === 'call' ? { input: preview(original), output: null } : { input: null, output: preview(original) }) };
|
|
28
|
+
if (kind === 'call') { const key = rawCallId || `line:${line}`; const pending = state.calls.get(key) ?? []; pending.push(entry); state.calls.set(key, pending); } else {
|
|
29
|
+
const pending = rawCallId && state.calls.get(rawCallId); const call = pending?.shift();
|
|
30
|
+
if (call) { entry.name ||= call.name; call.output = entry.output; call.resultSource = entry.source; call.resultObservedAt = safeString(timestamp); }
|
|
31
|
+
else state.unmatchedResults++;
|
|
32
|
+
state.tools.push(entry);
|
|
33
|
+
}
|
|
34
|
+
if (kind === 'call') state.tools.push(entry);
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
function message(state, role, text, line, raw, timestamp, transport = 'canonical') {
|
|
38
|
+
if (!text) return;
|
|
39
|
+
state.messages.push({ role, text: redact(text), line, observedAt: safeString(timestamp), source: { line, sha256: sha256(raw) }, transport, _key: text });
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
function consumeClaude(state, record, line, raw) {
|
|
43
|
+
if (!['user', 'assistant'].includes(record.type)) return false;
|
|
44
|
+
const role = plain(at(record, 'message.role', 'role'));
|
|
45
|
+
const content = at(record, 'message.content', 'content');
|
|
46
|
+
if (role !== record.type || content === undefined) { state.unsupported++; gap(state, 'unsupported', line, raw); return true; }
|
|
47
|
+
if (!Array.isArray(content) && typeof content !== 'string') { state.unsupported++; gap(state, 'unsupported', line, raw); return true; }
|
|
48
|
+
const timestamp = stamp(record); const blocks = Array.isArray(content) ? content : [{ type: 'text', text: content }];
|
|
49
|
+
let text = '';
|
|
50
|
+
for (const block of blocks) {
|
|
51
|
+
if (!block || typeof block !== 'object') { state.unsupported++; gap(state, 'unsupported', line, raw); continue; }
|
|
52
|
+
if (block.type === 'tool_use') addTool(state, 'call', block, line, raw, timestamp);
|
|
53
|
+
else if (block.type === 'tool_result') addTool(state, 'result', block, line, raw, timestamp);
|
|
54
|
+
else if (block.type === 'thinking' || block.type === 'redacted_thinking') state.omittedReasoning++;
|
|
55
|
+
else if (block.type === 'text' && typeof block.text === 'string') text += block.text;
|
|
56
|
+
else { state.unsupported++; gap(state, 'unsupported', line, raw); }
|
|
57
|
+
}
|
|
58
|
+
message(state, role, text, line, raw, timestamp); return true;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
function consumeCodex(state, record, line, raw) {
|
|
62
|
+
const item = record.type === 'response_item' ? (record.payload ?? record.item ?? record.response_item) : null;
|
|
63
|
+
if (!item || typeof item !== 'object') return false;
|
|
64
|
+
const timestamp = stamp(record); const type = item.type;
|
|
65
|
+
if (type === 'function_call') { addTool(state, 'call', item, line, raw, timestamp); return true; }
|
|
66
|
+
if (type === 'function_call_output') { addTool(state, 'result', item, line, raw, timestamp); return true; }
|
|
67
|
+
if (type === 'reasoning') { state.omittedReasoning++; return true; }
|
|
68
|
+
if (type !== 'message') { state.unsupported++; gap(state, 'unsupported', line, raw); return true; }
|
|
69
|
+
const role = plain(item.role); const content = item.content ?? item.input_text ?? item.output_text;
|
|
70
|
+
if (item.channel === 'analysis' && role === 'assistant') { state.omittedReasoning++; return true; }
|
|
71
|
+
if (!['user', 'assistant'].includes(role)) { state.unsupported++; gap(state, 'unsupported', line, raw); return true; }
|
|
72
|
+
if (typeof content === 'string') message(state, role, content, line, raw, timestamp);
|
|
73
|
+
else if (Array.isArray(content)) { if (content.some(block => !block || typeof block !== 'object' || !['text', 'input_text', 'output_text'].includes(block.type) || typeof block.text !== 'string')) { state.unsupported++; gap(state, 'unsupported', line, raw); } message(state, role, textBlocks(content), line, raw, timestamp); }
|
|
74
|
+
else { state.unsupported++; gap(state, 'unsupported', line, raw); }
|
|
75
|
+
return true;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
function consumeEvent(state, record, line, raw) {
|
|
79
|
+
if (record.type !== 'event_msg') return false;
|
|
80
|
+
const event = record.payload ?? record.event ?? record; const type = plain(event.type);
|
|
81
|
+
if (type === 'agent_reasoning') { state.omittedReasoning++; return true; }
|
|
82
|
+
if (['token_count', 'turn_started', 'turn_completed'].includes(type)) { state.metadata++; return true; }
|
|
83
|
+
if (!['user_message', 'agent_message'].includes(type)) return false;
|
|
84
|
+
const role = type === 'user_message' ? 'user' : 'assistant';
|
|
85
|
+
const candidate = at(event, 'message', 'text', 'content');
|
|
86
|
+
const text = typeof candidate === 'string' ? candidate : textBlocks(at(event, 'message.content', 'content'));
|
|
87
|
+
if (text) message(state, role, text, line, raw, stamp(record), 'event_msg'); else { state.unsupported++; gap(state, 'unsupported', line, raw); }
|
|
88
|
+
return true;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
function routineMetadata(state, record) {
|
|
92
|
+
// These native envelopes contain delivery/accounting state, not dialogue.
|
|
93
|
+
// Keep their presence visible without treating them as missing conversation.
|
|
94
|
+
if (new Set(['session_meta', 'turn_context', 'token_count', 'rate_limits', 'response_completed', 'turn_completed']).has(record.type)) { state.metadata++; return true; }
|
|
95
|
+
return false;
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
export function prepareRecords(sourceText, { fromLine = 1, toLine, sourceSha256 } = {}) {
|
|
99
|
+
const lines = sourceText.split(/\r?\n/); if (lines.at(-1) === '') lines.pop();
|
|
100
|
+
const last = lines.length;
|
|
101
|
+
if (last === 0 && fromLine === 1 && toLine === undefined) return { messages: [], tools: [], coverage: { schemaVersion: 1, source: { sha256: sourceSha256 ?? sha256(sourceText), totalLines: 0, selectedLines: { from: null, to: null } }, counts: { parsed: 0, skipped: 0, malformed: 0, unknown: 0, unsupported: 0, metadata: 0, omittedReasoning: 0, unmatchedCalls: 0, unmatchedResults: 0, deduplicated: 0 }, gaps: [], complete: true, limits: { previewBytes: PREVIEW_BYTES, scope: 'This is a normalized selected physical-line range from one explicit source file, not full session or worker coverage.', selectedRangeOnly: true, redaction: 'Pattern redaction is applied to messages and previews; it is not comprehensive.', reasoning: 'Thinking/reasoning blocks are omitted.', deduplication: 'Only an event fallback exactly matching role, original text, and timestamp of a canonical message is deduplicated.' } } };
|
|
102
|
+
toLine ??= last;
|
|
103
|
+
if (!Number.isInteger(fromLine) || !Number.isInteger(toLine) || fromLine < 1 || toLine < fromLine || toLine > last) throw new Error('invalid-line-range');
|
|
104
|
+
const state = { messages: [], tools: [], calls: new Map(), parsed: 0, skipped: 0, malformed: 0, unknown: 0, unsupported: 0, metadata: 0, omittedReasoning: 0, unmatchedResults: 0, gaps: [] };
|
|
105
|
+
for (let index = fromLine - 1; index < toLine; index++) {
|
|
106
|
+
const raw = lines[index]; if (!raw.trim()) { state.skipped++; continue; }
|
|
107
|
+
// A UTF-8 BOM is transport framing, but still belongs to the exact source hash.
|
|
108
|
+
let record; try { record = JSON.parse(index === 0 ? raw.replace(/^\uFEFF/, '') : raw); } catch { state.malformed++; gap(state, 'malformed', index + 1, raw); continue; }
|
|
109
|
+
state.parsed++;
|
|
110
|
+
if (!record || typeof record !== 'object' || Array.isArray(record)) { state.unknown++; gap(state, 'unknown', index + 1, raw); continue; }
|
|
111
|
+
const handled = consumeClaude(state, record, index + 1, raw) || consumeCodex(state, record, index + 1, raw) || consumeEvent(state, record, index + 1, raw) || routineMetadata(state, record);
|
|
112
|
+
if (!handled) { state.unknown++; gap(state, 'unknown', index + 1, raw); }
|
|
113
|
+
}
|
|
114
|
+
// An event fallback only yields to an exact canonical transport echo with a
|
|
115
|
+
// shared timestamp. Without that binding, repeated human messages stay visible.
|
|
116
|
+
const canonical = new Set(state.messages.filter(item => item.transport === 'canonical' && item.observedAt !== null).map(item => `${item.role}\u0000${item.observedAt}\u0000${item._key}`));
|
|
117
|
+
const kept = state.messages.filter(item => item.transport !== 'event_msg' || item.observedAt === null || !canonical.has(`${item.role}\u0000${item.observedAt}\u0000${item._key}`));
|
|
118
|
+
const deduplicated = state.messages.length - kept.length;
|
|
119
|
+
const unmatchedCalls = state.tools.filter(tool => tool.input && !tool.output).length;
|
|
120
|
+
const incomplete = state.malformed > 0 || state.unknown > 0 || state.unsupported > 0;
|
|
121
|
+
return { messages: kept.map(({ transport, _key, ...item }) => item), tools: state.tools, coverage: { schemaVersion: 1, source: { sha256: sourceSha256 ?? sha256(sourceText), totalLines: last, selectedLines: { from: fromLine, to: toLine } }, counts: { parsed: state.parsed, skipped: state.skipped, malformed: state.malformed, unknown: state.unknown, unsupported: state.unsupported, metadata: state.metadata, omittedReasoning: state.omittedReasoning, unmatchedCalls, unmatchedResults: state.unmatchedResults, deduplicated }, gaps: state.gaps, complete: !incomplete, limits: { previewBytes: PREVIEW_BYTES, scope: 'This is a normalized selected physical-line range from one explicit source file, not full session or worker coverage.', selectedRangeOnly: true, redaction: 'Pattern redaction is applied to messages and previews; it is not comprehensive.', reasoning: 'Thinking/reasoning blocks are omitted.', deduplication: 'Only an event fallback exactly matching role, original text, and timestamp of a canonical message is deduplicated.' } } };
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
const markdown = messages => messages.map(item => `## ${item.role}\n\n_Source: line ${item.source.line}; sha256 ${item.source.sha256}; observedAt ${item.observedAt ?? 'unknown'}_\n\n${item.text}\n`).join('');
|
|
125
|
+
async function refusePath(path, kind) { try { await lstat(path); throw new Error(`${kind}-exists`); } catch (error) { if (error.code !== 'ENOENT') throw error; } }
|
|
126
|
+
|
|
127
|
+
export async function prepareRetro({ source, out, fromLine = 1, toLine } = {}) {
|
|
128
|
+
if (typeof source !== 'string' || typeof out !== 'string' || !source || !out) throw new Error('source-and-out-required');
|
|
129
|
+
const sourcePath = resolve(source); const outPath = resolve(out); if (sourcePath === outPath) throw new Error('output-must-not-be-source');
|
|
130
|
+
const stat = await lstat(sourcePath); if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('invalid-source');
|
|
131
|
+
await refusePath(outPath, 'output');
|
|
132
|
+
const parent = dirname(outPath); const parentStat = await lstat(parent); if (!parentStat.isDirectory() || parentStat.isSymbolicLink()) throw new Error('invalid-output-parent');
|
|
133
|
+
const sourceBytes = await readFile(sourcePath); let sourceText;
|
|
134
|
+
try { sourceText = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(sourceBytes); } catch { throw new Error('invalid-utf8-source'); }
|
|
135
|
+
const prepared = prepareRecords(sourceText, { fromLine, toLine, sourceSha256: sha256(sourceBytes) });
|
|
136
|
+
const temp = `${outPath}.tmp-${randomUUID()}`; await mkdir(temp, { mode: 0o700 });
|
|
137
|
+
try {
|
|
138
|
+
await writeFile(resolve(temp, 'conversation.md'), markdown(prepared.messages), { mode: 0o600 });
|
|
139
|
+
await writeFile(resolve(temp, 'tools.jsonl'), prepared.tools.map(value => JSON.stringify(value)).join('\n') + (prepared.tools.length ? '\n' : ''), { mode: 0o600 });
|
|
140
|
+
await writeFile(resolve(temp, 'coverage.json'), JSON.stringify(prepared.coverage, null, 2) + '\n', { mode: 0o600 });
|
|
141
|
+
await chmod(temp, 0o700); await rename(temp, outPath);
|
|
142
|
+
} catch (error) { await rm(temp, { recursive: true, force: true }); throw error; }
|
|
143
|
+
return { out: outPath, ...prepared };
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
function cli(argv) {
|
|
147
|
+
const [command, ...parts] = argv; if (command !== 'prepare') throw new Error('Usage: retro.mjs prepare --source <jsonl> --out <new-directory> [--from-line N --to-line N]');
|
|
148
|
+
const flags = {}; for (let index = 0; index < parts.length; index += 2) { if (!['--source', '--out', '--from-line', '--to-line'].includes(parts[index]) || flags[parts[index]] !== undefined || parts[index + 1] === undefined) throw new Error('invalid-arguments'); flags[parts[index]] = parts[index + 1]; }
|
|
149
|
+
return prepareRetro({ source: flags['--source'], out: flags['--out'], fromLine: flags['--from-line'] === undefined ? 1 : Number(flags['--from-line']), toLine: flags['--to-line'] === undefined ? undefined : Number(flags['--to-line']) });
|
|
150
|
+
}
|
|
151
|
+
if (import.meta.url === new URL(process.argv[1], 'file:').href) cli(process.argv.slice(2)).then(result => process.stdout.write(`${JSON.stringify({ out: result.out, coverage: result.coverage })}\n`)).catch(error => { process.stderr.write(`${error.message}\n`); process.exitCode = 1; });
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schemaVersion": 1,
|
|
3
|
+
"categories": {
|
|
4
|
+
"web": { "label": "Web app", "tools": ["playwright"], "ui": true },
|
|
5
|
+
"ios": { "label": "iOS / macOS app", "tools": ["xcode", "ios-simulator"], "ui": true },
|
|
6
|
+
"android": { "label": "Android app", "tools": ["android-sdk", "android-emulator"], "ui": true },
|
|
7
|
+
"flutter": { "label": "Flutter app", "tools": ["flutter"], "ui": true, "mobile": true },
|
|
8
|
+
"react-native": { "label": "React Native app", "tools": ["react-native-cli"], "ui": true, "mobile": true },
|
|
9
|
+
"expo": { "label": "Expo app", "tools": ["expo-cli"], "ui": true, "mobile": true },
|
|
10
|
+
"electron": { "label": "Electron / desktop app", "tools": ["playwright"], "ui": true },
|
|
11
|
+
"api": { "label": "API / backend", "tools": ["test-runner", "curl"], "ui": false },
|
|
12
|
+
"cli-library": { "label": "CLI / library", "tools": ["test-runner"], "ui": false }
|
|
13
|
+
},
|
|
14
|
+
"tools": {
|
|
15
|
+
"playwright": { "label": "Playwright + Chromium", "scope": "project", "size": "about 150 MB with Chromium", "sudo": false,
|
|
16
|
+
"hostAlternative": "browser", "evidence": "{exec} playwright test" },
|
|
17
|
+
"xcode": { "label": "Xcode (xcodebuild)", "scope": "system", "size": "about 12 GB", "sudo": true,
|
|
18
|
+
"steps": ["Install Xcode from the App Store and open it once", "Run `sudo xcodebuild -license accept` yourself"] },
|
|
19
|
+
"ios-simulator": { "label": "iOS Simulator runtime", "scope": "system", "size": "about 8 GB", "sudo": false,
|
|
20
|
+
"hostAlternative": "simulator", "steps": ["Run `xcodebuild -downloadPlatform iOS`, or Xcode > Settings > Components"],
|
|
21
|
+
"evidence": "xcrun simctl io booted screenshot <file>" },
|
|
22
|
+
"android-sdk": { "label": "Android SDK platform tools (adb)", "scope": "system", "size": "about 1 GB", "sudo": false,
|
|
23
|
+
"steps": ["Install Android Studio, then SDK Manager > SDK Platform-Tools", "Accept the SDK licenses yourself"] },
|
|
24
|
+
"android-emulator": { "label": "Android emulator image", "scope": "system", "size": "about 4 GB", "sudo": false,
|
|
25
|
+
"steps": ["Android Studio > Device Manager > create a virtual device"], "evidence": "adb exec-out screencap -p > <file>" },
|
|
26
|
+
"flutter": { "label": "Flutter SDK", "scope": "system", "size": "about 2 GB", "sudo": false,
|
|
27
|
+
"steps": ["Install the Flutter SDK (https://docs.flutter.dev/get-started/install) and run `flutter doctor`"] },
|
|
28
|
+
"react-native-cli": { "label": "React Native CLI", "scope": "project", "size": "a few MB", "sudo": false, "package": "react-native" },
|
|
29
|
+
"expo-cli": { "label": "Expo CLI", "scope": "project", "size": "a few MB", "sudo": false, "package": "expo" },
|
|
30
|
+
"test-runner": { "label": "Project test runner", "scope": "project", "size": "declared by the project", "sudo": false },
|
|
31
|
+
"curl": { "label": "HTTP check (curl)", "scope": "system", "size": "built in on macOS", "sudo": false,
|
|
32
|
+
"steps": ["Install curl with your system package manager"], "evidence": "curl -sS <url>" }
|
|
33
|
+
}
|
|
34
|
+
}
|