joycraft 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/README.md +54 -0
  2. package/dist/joycraft-release.json +1 -1
  3. package/package.json +3 -3
  4. package/payload/.agents/skills/joycraft-cleanup/SKILL.md +41 -0
  5. package/payload/.agents/skills/joycraft-entry/SKILL.md +10 -0
  6. package/payload/.agents/skills/joycraft-implement/SKILL.md +14 -2
  7. package/payload/.agents/skills/joycraft-session-end/SKILL.md +10 -4
  8. package/payload/.agents/skills/joycraft-verify/SKILL.md +4 -0
  9. package/payload/.claude/agents/joycraft-implementer.md +7 -1
  10. package/payload/.claude/agents/joycraft-reviewer.md +9 -0
  11. package/payload/.joycraft/references/archive.md +17 -0
  12. package/payload/.joycraft/references/cleanup.md +35 -0
  13. package/payload/.joycraft/references/context.md +5 -0
  14. package/payload/.joycraft/references/dispatch.md +6 -1
  15. package/payload/.joycraft/references/setup.md +30 -1
  16. package/payload/.joycraft/references/testing.md +10 -0
  17. package/payload/.joycraft/references/workflow.md +5 -0
  18. package/payload/.joycraft/references/worktrees.md +26 -0
  19. package/payload/.joycraft/runtime/archive.mjs +35 -15
  20. package/payload/.joycraft/runtime/cleanup.mjs +149 -0
  21. package/payload/.joycraft/runtime/config.mjs +191 -0
  22. package/payload/.joycraft/runtime/context/search.mjs +5 -3
  23. package/payload/.joycraft/runtime/coordinator.mjs +169 -0
  24. package/payload/.joycraft/runtime/dispatch-start.mjs +18 -3
  25. package/payload/.joycraft/runtime/review-tools.json +7 -0
  26. package/payload/.joycraft/runtime/status.mjs +97 -0
  27. package/payload/.joycraft/runtime/trace.mjs +79 -0
  28. package/payload/.joycraft/runtime/worktrees.mjs +201 -0
  29. package/payload/.joycraft/templates/joycraft.yaml +19 -0
  30. package/payload/PIN +28 -19
@@ -0,0 +1,149 @@
1
+ import { execFileSync } from 'node:child_process';
2
+ import { existsSync, readFileSync, readdirSync } from 'node:fs';
3
+ import path from 'node:path';
4
+ import { pathToFileURL } from 'node:url';
5
+ import { parseYaml, readConfig } from './config.mjs';
6
+ import { requireValue } from './identity.mjs';
7
+ import { projectStatus } from './status.mjs';
8
+ import { listWorktrees } from './worktrees.mjs';
9
+
10
+ // A report-only sweep for stale project knowledge. Every check is deterministic:
11
+ // files, links, frontmatter and Git history. It never edits a file; the
12
+ // joycraft-cleanup skill proposes fixes and applies only the approved ones.
13
+ const entryFiles = ['AGENTS.md', 'CLAUDE.md'];
14
+
15
+ function markdownFiles(root, folder, skip = []) {
16
+ const out = [];
17
+ const walk = relative => {
18
+ if (skip.includes(relative)) return;
19
+ let entries;
20
+ try { entries = readdirSync(path.join(root, relative), { withFileTypes: true }); } catch { return; }
21
+ for (const entry of entries) {
22
+ const child = `${relative}/${entry.name}`;
23
+ if (entry.isDirectory()) walk(child);
24
+ else if (entry.isFile() && entry.name.endsWith('.md')) out.push(child);
25
+ }
26
+ };
27
+ walk(folder);
28
+ return out.sort();
29
+ }
30
+
31
+ const read = (root, file) => { try { return readFileSync(path.join(root, file), 'utf8'); } catch { return null; } };
32
+
33
+ /** Markdown links (checked for existence) and backticked project paths (references only). */
34
+ export function references(file, text) {
35
+ const dir = path.posix.dirname(file);
36
+ const links = [], mentions = [];
37
+ // Blank out fenced code so examples are not read as links; keep line numbers.
38
+ text = text.replace(/^(```|~~~)[^\n]*\n[\s\S]*?^\1[^\n]*$/gm, block => block.replace(/[^\n]/g, ' '));
39
+ const lineOf = index => text.slice(0, index).split('\n').length;
40
+ const add = (raw, index) => {
41
+ const target = raw.split('#')[0];
42
+ if (!target || /^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith('/')) return;
43
+ let decoded = target;
44
+ try { decoded = decodeURI(target); } catch { /* keep the raw text when an escape is malformed */ }
45
+ links.push({ target: path.posix.normalize(path.posix.join(dir, decoded)), line: lineOf(index) });
46
+ };
47
+ for (const match of text.matchAll(/\[[^\]]*\]\((?:<([^>]+)>|([^)\s]+))(?:\s+"[^"]*")?\)/g)) add(match[1] ?? match[2], match.index);
48
+ for (const match of text.matchAll(/^ {0,3}\[[^\]]+\]:\s+(?:<([^>]+)>|(\S+))/gm)) add(match[1] ?? match[2], match.index);
49
+ for (const match of text.matchAll(/`([A-Za-z0-9_.\/-]+\.md)`/g)) {
50
+ if (match[1].includes('/')) mentions.push({ target: path.posix.normalize(match[1]), line: text.slice(0, match.index).split('\n').length });
51
+ }
52
+ return { links, mentions };
53
+ }
54
+
55
+ function frontmatter(text) {
56
+ const block = /^(?:\uFEFF)?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
57
+ if (!block) return null;
58
+ try { return parseYaml(block[1]); } catch (error) { return { unreadable: error.message.replace(/^joycraft\.yaml /, '') }; }
59
+ }
60
+
61
+ const inside = (file, folder) => file === folder || file.startsWith(`${folder}/`);
62
+
63
+ function git(root, args) {
64
+ return execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
65
+ }
66
+
67
+ /** Context pages whose mapped code changed in commits after the page last changed. */
68
+ function impactDrift(root, impact, findings, skipped) {
69
+ if (impact.length === 0) return;
70
+ try { git(root, ['rev-parse', '--verify', 'HEAD']); } catch { skipped.push({ check: 'impact-drift', reason: 'Not a Git repository with commits.' }); return; }
71
+ for (const entry of impact) {
72
+ for (const doc of entry.docs) {
73
+ if (!existsSync(path.join(root, doc))) { findings.push({ check: 'impact-drift', path: doc, detail: `Mapped to ${entry.source} in joycraft.yaml, but the page does not exist.`, fix: 'Create the page or remove it from cleanup.impact.' }); continue; }
74
+ const last = git(root, ['log', '-1', '--format=%H', '--', doc]);
75
+ if (!last) { skipped.push({ check: 'impact-drift', path: doc, reason: 'The page has no commit yet.' }); continue; }
76
+ const commits = git(root, ['log', '--format=%h', `${last}..HEAD`, '--', `:(glob)${entry.source}`]).split('\n').filter(Boolean);
77
+ if (commits.length) {
78
+ const files = [...new Set(git(root, ['diff', '--name-only', last, 'HEAD', '--', `:(glob)${entry.source}`]).split('\n').filter(Boolean))];
79
+ findings.push({ check: 'impact-drift', path: doc, detail: `${commits.length} commit(s) changed ${entry.source} after this page last changed: ${files.slice(0, 8).join(', ')}${files.length > 8 ? ', …' : ''}.`, fix: 'Read the changed code and update the page, or commit the page unchanged if it is still true.', commits });
80
+ }
81
+ }
82
+ }
83
+ }
84
+
85
+ /** Report stale working material, link problems, unmapped pages and code drift. */
86
+ export function cleanupReport({ root = process.cwd(), now = Date.now() } = {}) {
87
+ const config = readConfig(root);
88
+ const { features, archive, context } = config.paths;
89
+ const findings = [], skipped = [];
90
+
91
+ const status = projectStatus({ root });
92
+ for (const item of status.readyToArchive) {
93
+ findings.push({ check: 'unarchived', path: item.folder, detail: `Every spec is done, but the feature is still in ${features}.${item.openDecisions.length ? ` Open decisions: ${item.openDecisions.join(', ')}.` : ''}`, fix: 'Archive it at session end (archive.mjs), after carrying durable facts into the context home.' });
94
+ }
95
+ for (const item of status.drift) findings.push({ check: 'status-drift', path: item.file, detail: `Queue says ${item.queue}, frontmatter says ${item.frontmatter}.`, fix: item.fixable ? 'Run status.mjs --fix.' : item.reason });
96
+
97
+ const pages = markdownFiles(root, context, [features, archive]);
98
+ const authorities = [...entryFiles.filter(file => existsSync(path.join(root, file))), ...pages];
99
+ const referenced = new Set();
100
+ const deprecated = new Set();
101
+ for (const page of pages) {
102
+ const meta = frontmatter(read(root, page) ?? '');
103
+ if (meta?.unreadable) { findings.push({ check: 'frontmatter-unreadable', path: page, detail: `Frontmatter uses YAML that cleanup cannot read (${meta.unreadable}), so its status and stale_after are not checked.`, fix: 'Use plain key: value lines, lists and quoted strings in the frontmatter.' }); continue; }
104
+ if (meta?.status === 'deprecated') deprecated.add(page);
105
+ const staleAfter = meta?.stale_after == null ? NaN : Date.parse(String(meta.stale_after));
106
+ if (Number.isFinite(staleAfter) && staleAfter <= now) findings.push({ check: 'stale-after', path: page, detail: `stale_after ${meta.stale_after} has passed.`, fix: 'Recheck the page against its sources, then move stale_after forward or mark it deprecated.' });
107
+ }
108
+ for (const file of authorities) {
109
+ const text = read(root, file) ?? '';
110
+ const { links, mentions } = references(file, text);
111
+ for (const ref of [...links, ...mentions]) {
112
+ if (ref.target !== file) referenced.add(ref.target);
113
+ if (inside(ref.target, features) || inside(ref.target, archive)) {
114
+ findings.push({ check: 'working-link', path: file, line: ref.line, detail: `Links to ${ref.target}, which is ${inside(ref.target, archive) ? 'history' : 'working material'}, not current knowledge.`, fix: `Move the fact it relies on into ${context}/ and link that instead.` });
115
+ }
116
+ if (deprecated.has(ref.target)) findings.push({ check: 'deprecated-link', path: file, line: ref.line, detail: `Links to ${ref.target}, which is marked status: deprecated.`, fix: 'Link the current page instead, or drop the link.' });
117
+ }
118
+ for (const ref of links) {
119
+ if (!existsSync(path.join(root, ref.target))) findings.push({ check: 'broken-link', path: file, line: ref.line, detail: `Links to ${ref.target}, which does not exist.`, fix: 'Fix the link or remove it.' });
120
+ }
121
+ }
122
+ for (const page of pages) {
123
+ if (!referenced.has(page)) findings.push({ check: 'orphan', path: page, detail: `Nothing in ${entryFiles.join(', ')} or ${context}/ links to this page, so agents may never read it.`, fix: 'Add it to the context map with a "read when", or merge it into a linked page.' });
124
+ }
125
+
126
+ impactDrift(root, config.cleanup.impact, findings, skipped);
127
+
128
+ try {
129
+ for (const tree of listWorktrees({ root, sizes: false }).trees.filter(tree => tree.owner !== 'joycraft')) {
130
+ findings.push({ check: 'unknown-worktree', path: tree.path, detail: `A linked worktree${tree.branch ? ` on ${tree.branch}` : ''} that worktrees.mjs did not create.`, fix: 'Check it for unmerged work, then remove it with git worktree remove.' });
131
+ }
132
+ } catch { skipped.push({ check: 'unknown-worktree', reason: 'Not a Git repository.' }); }
133
+
134
+ const counts = Object.fromEntries([...new Set(findings.map(item => item.check))].map(check => [check, findings.filter(item => item.check === check).length]));
135
+ return { config: config.source ?? 'defaults', paths: config.paths, counts, findings, skipped };
136
+ }
137
+
138
+ export async function main(argv = process.argv.slice(2)) {
139
+ const index = argv.indexOf('--root');
140
+ requireValue(argv.length === 0 || (argv.length === 2 && index === 0), 'Usage: cleanup.mjs [--root <project>]');
141
+ const result = cleanupReport({ root: path.resolve(index === 0 ? argv[1] : '.') });
142
+ process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
143
+ if (result.findings.length) process.exitCode = 2;
144
+ return result;
145
+ }
146
+
147
+ if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
148
+ main().catch(error => { process.stderr.write(`Cleanup stopped: ${error.message}\n`); process.exitCode = 1; });
149
+ }
@@ -0,0 +1,191 @@
1
+ import { existsSync, readFileSync } from 'node:fs';
2
+ import path from 'node:path';
3
+ import { pathToFileURL } from 'node:url';
4
+ import { isObject, relativePath, requireValue } from './identity.mjs';
5
+
6
+ // joycraft.yaml is project-owned: Joycraft reads it and never rewrites it. The
7
+ // parser accepts a small YAML subset (maps, lists, scalars, flow lists) and names
8
+ // the line of anything else, so a typo never silently changes behavior.
9
+ export const configFile = 'joycraft.yaml';
10
+ export const defaults = Object.freeze({
11
+ paths: Object.freeze({ features: 'docs/features', archive: 'docs/archive', context: 'docs/context' }),
12
+ hooks: Object.freeze({}),
13
+ cleanup: Object.freeze({ impact: Object.freeze([]) }),
14
+ });
15
+
16
+ function scalar(text, line) {
17
+ const value = text.trim();
18
+ if (value === '') return null;
19
+ if (/^"(?:[^"\\]|\\.)*"$/.test(value)) return JSON.parse(value);
20
+ if (/^'(?:[^']|'')*'$/.test(value)) return value.slice(1, -1).replaceAll("''", "'");
21
+ requireValue(!/^["']/.test(value), `${configFile} line ${line}: a quoted value must end with its closing quote and nothing after it: ${value}`);
22
+ if (/^\[.*\]$/.test(value)) {
23
+ const inner = value.slice(1, -1).trim();
24
+ return inner === '' ? [] : splitFlow(inner, line).map(item => scalar(item, line));
25
+ }
26
+ requireValue(!/^[{&*!|>%@`]/.test(value), `${configFile} line ${line}: unsupported YAML syntax: ${value}`);
27
+ if (value === 'true' || value === 'false') return value === 'true';
28
+ if (value === 'null' || value === '~') return null;
29
+ if (/^-?\d+(?:\.\d+)?$/.test(value)) return Number(value);
30
+ return value;
31
+ }
32
+
33
+ function splitFlow(inner, line) {
34
+ const items = [];
35
+ let current = '', quote = null;
36
+ for (const char of inner) {
37
+ if (quote) { current += char; if (char === quote) quote = null; continue; }
38
+ if (char === '"' || char === "'") { quote = char; current += char; continue; }
39
+ requireValue(char !== '[' && char !== '{', `${configFile} line ${line}: nested flow collections are not supported`);
40
+ if (char === ',') { items.push(current); current = ''; continue; }
41
+ current += char;
42
+ }
43
+ requireValue(quote === null, `${configFile} line ${line}: unterminated quote`);
44
+ items.push(current);
45
+ return items;
46
+ }
47
+
48
+ const stripComment = text => {
49
+ let quote = null;
50
+ for (let index = 0; index < text.length; index += 1) {
51
+ const char = text[index];
52
+ if (quote === '"' && char === '\\') { index += 1; continue; }
53
+ if (quote) { if (char === quote) quote = null; continue; }
54
+ if (char === '"' || char === "'") quote = char;
55
+ else if (char === '#' && (index === 0 || /\s/.test(text[index - 1]))) return text.slice(0, index);
56
+ }
57
+ return text;
58
+ };
59
+
60
+ /** Parse the supported YAML subset into plain objects. */
61
+ export function parseYaml(text) {
62
+ const lines = text.replace(/^\uFEFF/, '').split(/\r?\n/).map((raw, index) => ({ raw: stripComment(raw).replace(/\s+$/, ''), number: index + 1 }))
63
+ .filter(entry => entry.raw.trim() !== '');
64
+ if (lines[0]?.raw.trim() === '---') lines.shift();
65
+ for (const entry of lines) requireValue(entry.raw.trim() !== '---' && entry.raw.trim() !== '...', `${configFile} line ${entry.number}: only one YAML document is supported`);
66
+ for (const entry of lines) requireValue(!entry.raw.includes('\t'), `${configFile} line ${entry.number}: use spaces, not tabs`);
67
+ let position = 0;
68
+ const indentOf = entry => entry.raw.length - entry.raw.trimStart().length;
69
+
70
+ function block(indent) {
71
+ const first = lines[position];
72
+ return first.raw.trimStart().startsWith('- ') || first.raw.trim() === '-' ? list(indent) : map(indent);
73
+ }
74
+
75
+ function map(indent, target = {}) {
76
+ while (position < lines.length && indentOf(lines[position]) === indent && !lines[position].raw.trimStart().startsWith('-')) {
77
+ const { raw, number } = lines[position];
78
+ const match = /^([A-Za-z0-9_.-]+):(?:\s+(.*))?$/.exec(raw.trim());
79
+ requireValue(match, `${configFile} line ${number}: expected "key: value"`);
80
+ const [, key, rest] = match;
81
+ requireValue(!Object.hasOwn(target, key), `${configFile} line ${number}: duplicate key ${key}`);
82
+ position += 1;
83
+ if (rest !== undefined && rest.trim() !== '') target[key] = scalar(rest, number);
84
+ else if (position < lines.length && indentOf(lines[position]) > indent) target[key] = block(indentOf(lines[position]));
85
+ else if (position < lines.length && indentOf(lines[position]) === indent && /^-(\s|$)/.test(lines[position].raw.trimStart())) target[key] = list(indent);
86
+ else target[key] = null;
87
+ }
88
+ requireValue(position >= lines.length || indentOf(lines[position]) <= indent, `${configFile} line ${lines[position]?.number}: unexpected indentation`);
89
+ return target;
90
+ }
91
+
92
+ function list(indent) {
93
+ const items = [];
94
+ while (position < lines.length && indentOf(lines[position]) === indent && /^-(\s|$)/.test(lines[position].raw.trimStart())) {
95
+ const { raw, number } = lines[position];
96
+ const rest = raw.trimStart().slice(1);
97
+ if (rest.trim() === '') {
98
+ position += 1;
99
+ requireValue(position < lines.length && indentOf(lines[position]) > indent, `${configFile} line ${number}: empty list item`);
100
+ items.push(block(indentOf(lines[position])));
101
+ } else if (/^\s+[A-Za-z0-9_.-]+:(\s|$)/.test(rest)) {
102
+ // "- key: value" starts a map whose remaining keys align with the first key.
103
+ const itemIndent = indent + 1 + (rest.length - rest.trimStart().length);
104
+ lines[position] = { raw: `${' '.repeat(itemIndent)}${rest.trimStart()}`, number };
105
+ items.push(map(itemIndent));
106
+ } else { items.push(scalar(rest, number)); position += 1; }
107
+ }
108
+ return items;
109
+ }
110
+
111
+ if (lines.length === 0) return {};
112
+ requireValue(indentOf(lines[0]) === 0, `${configFile} line ${lines[0].number}: the first key must not be indented`);
113
+ const result = block(0);
114
+ requireValue(position === lines.length, `${configFile} line ${lines[position]?.number}: unexpected content`);
115
+ return result;
116
+ }
117
+
118
+ const known = { paths: ['features', 'archive', 'context'], hooks: ['afterArchive'], cleanup: ['impact'] };
119
+
120
+ /** Read joycraft.yaml (or return defaults) and validate every known field. */
121
+ export function readConfig(root = process.cwd()) {
122
+ const file = path.join(root, configFile);
123
+ if (!existsSync(file)) return { source: null, ...structuredClone(defaults) };
124
+ const parsed = parseYaml(readFileSync(file, 'utf8'));
125
+ requireValue(isObject(parsed), `${configFile} must be a map of settings`);
126
+ for (const [section, value] of Object.entries(parsed)) {
127
+ requireValue(Object.hasOwn(known, section), `${configFile}: unknown section ${section}; known sections are ${Object.keys(known).join(', ')}`);
128
+ requireValue(value === null || isObject(value), `${configFile}: ${section} must be a map`);
129
+ for (const key of Object.keys(value ?? {})) requireValue(known[section].includes(key), `${configFile}: unknown setting ${section}.${key}`);
130
+ }
131
+ const paths = { ...defaults.paths };
132
+ for (const [key, value] of Object.entries(parsed.paths ?? {})) {
133
+ requireValue(typeof value === 'string', `${configFile}: paths.${key} must be a project-relative folder`);
134
+ paths[key] = relativePath(value.replace(/\/+$/, ''));
135
+ }
136
+ const folders = Object.values(paths);
137
+ requireValue(new Set(folders).size === folders.length, `${configFile}: paths.features, paths.archive and paths.context must differ`);
138
+ // The work folders may sit inside the context home (e.g. context: docs); nothing else may nest.
139
+ for (const [ak, a] of Object.entries(paths)) for (const [bk, b] of Object.entries(paths)) {
140
+ requireValue(a === b || !b.startsWith(`${a}/`) || (ak === 'context' && bk !== 'context'), `${configFile}: ${b} cannot sit inside ${a}`);
141
+ }
142
+ const hooks = {};
143
+ if (parsed.hooks?.afterArchive != null) {
144
+ requireValue(typeof parsed.hooks.afterArchive === 'string' && parsed.hooks.afterArchive.trim(), `${configFile}: hooks.afterArchive must be a command`);
145
+ hooks.afterArchive = parsed.hooks.afterArchive;
146
+ }
147
+ const impact = parsed.cleanup?.impact ?? [];
148
+ requireValue(Array.isArray(impact), `${configFile}: cleanup.impact must be a list`);
149
+ for (const [index, entry] of impact.entries()) {
150
+ requireValue(isObject(entry) && typeof entry.source === 'string' && Array.isArray(entry.docs) && entry.docs.every(doc => typeof doc === 'string'),
151
+ `${configFile}: cleanup.impact item ${index + 1} needs source (a glob) and docs (a list of files)`);
152
+ checkGlob(entry.source, `cleanup.impact item ${index + 1} source`);
153
+ }
154
+ return { source: configFile, paths, hooks, cleanup: { impact: impact.map(entry => ({ source: entry.source, docs: entry.docs.map(relativePath) })) } };
155
+ }
156
+
157
+ /** Project-relative work folders for a project. */
158
+ export const workPaths = root => readConfig(root).paths;
159
+
160
+ /** Globs support only *, ** and ?, which Git pathspecs and globToRegExp read the same way. */
161
+ export function checkGlob(glob, label = 'glob') {
162
+ requireValue(typeof glob === 'string' && glob.trim() && !/[[\]{}!\\]/.test(glob), `${configFile}: ${label} may use only *, ** and ? as wildcards: ${glob}`);
163
+ return glob;
164
+ }
165
+
166
+ /** Convert a path glob (`*` within a segment, `**` across segments) to a RegExp. */
167
+ export function globToRegExp(glob) {
168
+ let pattern = '';
169
+ for (let index = 0; index < glob.length; index += 1) {
170
+ const char = glob[index];
171
+ if (char === '*' && glob[index + 1] === '*') {
172
+ index += 1;
173
+ if (glob[index + 1] === '/') { index += 1; pattern += '(?:.*/)?'; } else pattern += '.*';
174
+ } else if (char === '*') pattern += '[^/]*';
175
+ else if (char === '?') pattern += '[^/]';
176
+ else pattern += char.replace(/[.+^${}()|[\]\\]/g, '\\$&');
177
+ }
178
+ return new RegExp(`^${pattern}$`);
179
+ }
180
+
181
+ export async function main(argv = process.argv.slice(2)) {
182
+ const index = argv.indexOf('--root');
183
+ requireValue(argv.length === 0 || (argv.length === 2 && index === 0), 'Usage: config.mjs [--root <project>]');
184
+ const result = readConfig(path.resolve(index === 0 ? argv[1] : '.'));
185
+ process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
186
+ return result;
187
+ }
188
+
189
+ if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
190
+ main().catch(error => { process.stderr.write(`Config stopped: ${error.message}\n`); process.exitCode = 1; });
191
+ }
@@ -4,6 +4,7 @@ import { constants } from 'node:fs';
4
4
  import { lstat, open, realpath } from 'node:fs/promises';
5
5
  import { isAbsolute, join, relative, sep } from 'node:path';
6
6
  import { promisify } from 'node:util';
7
+ import { workPaths } from '../config.mjs';
7
8
 
8
9
  const exec = promisify(execFile);
9
10
  export const MAX_FILE_BYTES = 512 * 1024;
@@ -29,8 +30,8 @@ export function excludedReason(path) {
29
30
  return null;
30
31
  }
31
32
 
32
- function archivedReason(path, includeArchive) {
33
- return !includeArchive && (path === 'docs/archive' || path.startsWith('docs/archive/')) ? 'archived-context' : null;
33
+ function archivedReason(path, includeArchive, archive = 'docs/archive') {
34
+ return !includeArchive && (path === archive || path.startsWith(`${archive}/`)) ? 'archived-context' : null;
34
35
  }
35
36
 
36
37
  function keywords(query) {
@@ -101,6 +102,7 @@ async function readSafeFile(root, path) {
101
102
 
102
103
  /** Discover references without following symlinks or reading ignored/private paths. */
103
104
  export async function findCandidates({ query, paths, includeArchive = false }, { root = process.cwd() } = {}) {
105
+ const archiveFolder = workPaths(root).archive;
104
106
  if (typeof query !== 'string' || !query.trim() || Buffer.byteLength(query) > 4000) throw new Error('invalid-query: supply 1–4000 UTF-8 bytes');
105
107
  if (paths !== undefined && (!Array.isArray(paths) || !paths.length || paths.some(path => !safeRelativePath(path)))) throw new Error('invalid-paths: use project-relative files or directories');
106
108
  if (typeof includeArchive !== 'boolean') throw new Error('invalid-include-archive: use a boolean');
@@ -116,7 +118,7 @@ export async function findCandidates({ query, paths, includeArchive = false }, {
116
118
  const candidates = [], omitted = [], unreadable = [];
117
119
  const selections = paths && [...new Set(paths)];
118
120
  for (const path of inventory) {
119
- const archive = archivedReason(path, includeArchive);
121
+ const archive = archivedReason(path, includeArchive, archiveFolder);
120
122
  if (archive) { omitted.push({ path, reason: archive }); continue; }
121
123
  const exclusion = excludedReason(path);
122
124
  if (exclusion) { omitted.push({ path, reason: exclusion }); continue; }
@@ -0,0 +1,169 @@
1
+ import { execFileSync } from 'node:child_process';
2
+ import { closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
3
+ import path from 'node:path';
4
+ import { pathToFileURL } from 'node:url';
5
+ import { isObject, nonempty, parseJson, readLocal, relativePath, requireValue, validateQueue } from './identity.mjs';
6
+
7
+ // One session coordinates a queue at a time. The lease is a coordination record
8
+ // that every worker tree of the repository can read; it is not authentication.
9
+ export const staleMinutesDefault = 30;
10
+
11
+ /** The main working tree, which all linked worker trees share. */
12
+ export function mainTree(root) {
13
+ let listing;
14
+ try { listing = execFileSync('git', ['worktree', 'list', '--porcelain'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }); }
15
+ catch { return realpathSync(root); }
16
+ const first = /^worktree (.+)$/m.exec(listing);
17
+ return first && existsSync(first[1]) ? realpathSync(first[1]) : realpathSync(root);
18
+ }
19
+
20
+ const leaseRelative = feature => `.joycraft/local/coordinators/${feature}.json`;
21
+ const isSlug = feature => /^[a-z0-9][a-z0-9-]*$/.test(feature ?? '');
22
+
23
+ export function leasePath(root, feature) {
24
+ requireValue(isSlug(feature), 'A coordinator lease needs a queue feature that is a lowercase slug');
25
+ return path.join(mainTree(root), leaseRelative(feature));
26
+ }
27
+
28
+ /** Serialize a read-modify-write of a small local record with an exclusive lock file. */
29
+ export function withLock(file, action, { waitMs = 5000 } = {}) {
30
+ const lock = `${file}.lock`;
31
+ mkdirSync(path.dirname(file), { recursive: true });
32
+ const deadline = Date.now() + waitMs;
33
+ for (;;) {
34
+ try { closeSync(openSync(lock, 'wx')); break; } catch (error) {
35
+ if (error.code !== 'EEXIST') throw error;
36
+ // A lock older than the wait limit belongs to a process that died mid-write.
37
+ try { if (Date.now() - statSync(lock).mtimeMs > waitMs) { unlinkSync(lock); continue; } } catch { continue; }
38
+ requireValue(Date.now() < deadline, `Another Joycraft process holds ${path.basename(lock)}; try again`);
39
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
40
+ }
41
+ }
42
+ try { return action(); } finally { rmSync(lock, { force: true }); }
43
+ }
44
+
45
+ /** No lease can exist for a feature name that is not a slug, so 1.0.0 queues keep working. */
46
+ export function readLease(root, feature) {
47
+ if (!isSlug(feature)) return null;
48
+ const file = leasePath(root, feature);
49
+ if (!existsSync(file)) return null;
50
+ const lease = parseJson(readFileSync(file), leaseRelative(feature));
51
+ requireValue(isObject(lease) && lease.schemaVersion === 1 && nonempty(lease.sessionId), `Unsupported coordinator lease: ${leaseRelative(feature)}`);
52
+ return lease;
53
+ }
54
+
55
+ /** Create the main checkout's .joycraft/local as a self-ignoring folder before anything is written in it. */
56
+ export function ensureLocal(root) {
57
+ const local = path.join(mainTree(root), '.joycraft/local');
58
+ if (!existsSync(local)) {
59
+ mkdirSync(local, { recursive: true, mode: 0o700 });
60
+ writeFileSync(path.join(local, '.gitignore'), '*\n', { flag: 'wx', mode: 0o600 });
61
+ }
62
+ }
63
+
64
+ function writeLease(root, feature, lease) {
65
+ const file = leasePath(root, feature);
66
+ ensureLocal(root);
67
+ mkdirSync(path.dirname(file), { recursive: true });
68
+ writeFileSync(file, `${JSON.stringify(lease, null, 2)}\n`);
69
+ }
70
+
71
+ export function queueFeature(root, queuePath) {
72
+ queuePath = relativePath(queuePath);
73
+ const queue = parseJson(readLocal(root, queuePath), queuePath);
74
+ validateQueue(queue, { select: () => false });
75
+ return { feature: queue.feature, queuePath };
76
+ }
77
+
78
+ const isStale = (lease, now, staleMinutes) => now - Date.parse(lease.heartbeatAt) >= staleMinutes * 60_000;
79
+ const holder = lease => `session ${lease.sessionId}${lease.host ? ` on ${lease.host}` : ''}`;
80
+
81
+ /** Claim a queue. A live lease held by another session blocks the claim unless takeOver is set. */
82
+ export function claim(options) {
83
+ const { feature } = queueFeature(options.root ?? process.cwd(), options.queuePath);
84
+ ensureLocal(options.root ?? process.cwd());
85
+ return withLock(leasePath(options.root ?? process.cwd(), feature), () => claimLocked(options));
86
+ }
87
+
88
+ function claimLocked({ root = process.cwd(), queuePath, session, host, takeOver = false, staleMinutes = staleMinutesDefault, now = Date.now() }) {
89
+ requireValue(nonempty(session), 'Claiming a queue needs the active host --session ID');
90
+ const { feature, queuePath: queue } = queueFeature(root, queuePath);
91
+ const current = readLease(root, feature);
92
+ const at = new Date(now).toISOString();
93
+ if (current && current.sessionId === session) {
94
+ const lease = { ...current, heartbeatAt: at };
95
+ writeLease(root, feature, lease);
96
+ return { claimed: true, renewed: true, lease };
97
+ }
98
+ if (current && !takeOver) {
99
+ const stale = isStale(current, now, staleMinutes);
100
+ throw new Error(`Queue ${feature} is coordinated by ${holder(current)} (last heartbeat ${current.heartbeatAt}${stale ? ', stale' : ''}). Work under that session, or rerun with --take-over if it has ended.`);
101
+ }
102
+ const lease = {
103
+ schemaVersion: 1, feature, queuePath: queue, sessionId: session, ...(nonempty(host) ? { host } : {}),
104
+ root: path.relative(mainTree(root), realpathSync(root)) || '.', claimedAt: at, heartbeatAt: at,
105
+ ...(current ? { previous: { sessionId: current.sessionId, ...(current.host ? { host: current.host } : {}), heartbeatAt: current.heartbeatAt, stale: isStale(current, now, staleMinutes), takenOverAt: at } } : {}),
106
+ };
107
+ writeLease(root, feature, lease);
108
+ return { claimed: true, renewed: false, lease };
109
+ }
110
+
111
+ function requireHolder(root, queuePath, session) {
112
+ const { feature } = queueFeature(root, queuePath);
113
+ const lease = readLease(root, feature);
114
+ requireValue(lease, `Queue ${feature} has no coordinator lease`);
115
+ requireValue(lease.sessionId === session, `Queue ${feature} is coordinated by ${holder(lease)}, not session ${session}`);
116
+ return { feature, lease };
117
+ }
118
+
119
+ export function heartbeat({ root = process.cwd(), queuePath, session, now = Date.now() }) {
120
+ const { feature } = queueFeature(root, queuePath);
121
+ ensureLocal(root);
122
+ return withLock(leasePath(root, feature), () => {
123
+ const { lease } = requireHolder(root, queuePath, session);
124
+ const next = { ...lease, heartbeatAt: new Date(now).toISOString() };
125
+ writeLease(root, feature, next);
126
+ return { lease: next };
127
+ });
128
+ }
129
+
130
+ export function release({ root = process.cwd(), queuePath, session }) {
131
+ const { feature } = queueFeature(root, queuePath);
132
+ ensureLocal(root);
133
+ return withLock(leasePath(root, feature), () => {
134
+ requireHolder(root, queuePath, session);
135
+ rmSync(leasePath(root, feature));
136
+ return { released: true, feature };
137
+ });
138
+ }
139
+
140
+ export function show({ root = process.cwd(), queuePath, staleMinutes = staleMinutesDefault, now = Date.now() }) {
141
+ const { feature } = queueFeature(root, queuePath);
142
+ const lease = readLease(root, feature);
143
+ return { feature, lease, stale: lease ? isStale(lease, now, staleMinutes) : null };
144
+ }
145
+
146
+ export async function main(argv = process.argv.slice(2)) {
147
+ const [command, ...rest] = argv;
148
+ const flags = {};
149
+ for (let index = 0; index < rest.length; index += 1) {
150
+ if (rest[index] === '--take-over') { flags[rest[index]] = true; continue; }
151
+ flags[rest[index]] = rest[index + 1]; index += 1;
152
+ }
153
+ const root = path.resolve(flags['--root'] ?? '.');
154
+ const staleMinutes = flags['--stale-minutes'] === undefined ? staleMinutesDefault : Number(flags['--stale-minutes']);
155
+ requireValue(Number.isFinite(staleMinutes) && staleMinutes > 0, '--stale-minutes must be a positive number');
156
+ const options = { root, queuePath: flags['--queue'], session: flags['--session'], staleMinutes };
157
+ let result;
158
+ if (command === 'claim') result = claim({ ...options, host: flags['--host'], takeOver: flags['--take-over'] === true });
159
+ else if (command === 'heartbeat') result = heartbeat(options);
160
+ else if (command === 'release') result = release(options);
161
+ else if (command === 'show') result = show(options);
162
+ else throw new Error('Usage: coordinator.mjs claim --queue <queue> --session <id> [--host <host>] [--take-over] | heartbeat|release --queue <queue> --session <id> | show --queue <queue> [--root <project>] [--stale-minutes <n>]');
163
+ process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
164
+ return result;
165
+ }
166
+
167
+ if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
168
+ main().catch(error => { process.stderr.write(`Coordinator stopped: ${error.message}\n`); process.exitCode = 1; });
169
+ }
@@ -2,7 +2,9 @@ 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 { readLease } from './coordinator.mjs';
5
6
  import { prepareDispatch } from './dispatch-preflight.mjs';
7
+ import { traceSpec } from './trace.mjs';
6
8
  import { localPath, readQueue, relativePath, requireValue, validateNativeActor } from './identity.mjs';
7
9
 
8
10
  // The native hook runtime is optional; without it, startup takes the manual path.
@@ -38,8 +40,14 @@ export async function startDispatch(options, nativeEvent) {
38
40
  const rel = path.relative(root, parent);
39
41
  requireValue(rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel), 'Packet output parent must stay inside the worker root');
40
42
  requireValue(gitIgnored(root, outPath), `Packet output must be git-ignored so it never becomes a scope path: ${outPath}; use .joycraft/local/packets/`);
41
- readQueue({ root, queuePath: options.queuePath, specId: options.specId });
43
+ const { queue } = readQueue({ root, queuePath: options.queuePath, specId: options.specId });
42
44
  requireValue(options.role === 'implementer' || options.role === 'reviewer', 'Task startup role must be implementer or reviewer');
45
+ // A claimed queue takes work only from its coordinator, so a second session's
46
+ // instructions cannot reach this worker. An unclaimed queue keeps 1.0.0 behavior.
47
+ const lease = readLease(root, queue.feature);
48
+ requireValue(!lease || options.coordinatorSession === lease.sessionId,
49
+ 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
+ const coordinator = lease ? { sessionId: lease.sessionId, ...(lease.host ? { host: lease.host } : {}) } : null;
43
51
  // Change scope is opt-in per spec: startup never writes it, and a reviewer
44
52
  // without one reviews against the verification inputs alone.
45
53
  const packet = prepareDispatch({ ...options, outPath: output });
@@ -48,7 +56,13 @@ export async function startDispatch(options, nativeEvent) {
48
56
  const hooks = config.enabled
49
57
  ? { enabled: true, ...await runtime.bindPreparedSource({ event: nativeEvent, packetPath: outPath }) }
50
58
  : { enabled: false, eligible: false, reason: runtime ? 'hooks-disabled' : 'hooks-not-installed' };
51
- return { schemaVersion: 1, packetPath: outPath, packet, hooks,
59
+ // The reviewer sees which criteria have a tagged test. It reports; it never blocks startup.
60
+ let trace;
61
+ if (options.role === 'reviewer') {
62
+ try { const { criteria, untraced, unknownTags, missingFiles, note } = traceSpec({ root, queuePath: options.queuePath, specId: options.specId }); trace = { criteria, untraced, unknownTags, missingFiles, ...(note ? { note } : {}) }; }
63
+ catch (error) { trace = { error: error.message }; }
64
+ }
65
+ return { schemaVersion: 1, packetPath: outPath, packet, hooks, coordinator, ...(trace ? { trace } : {}),
52
66
  ready: !config.enabled || hooks.eligible === true };
53
67
  }
54
68
 
@@ -66,7 +80,7 @@ export async function main(argv = process.argv.slice(2)) {
66
80
  const flags = {};
67
81
  const allowed = new Set(['--worker-root', '--expected-manifest', '--queue', '--spec', '--role', '--implementer-session',
68
82
  '--implementer-host', '--implementer-agent', '--out', '--brief', '--capabilities', '--coordinator', '--parallel',
69
- '--access', '--base-revision', '--native-session', '--native-agent', '--native-host']);
83
+ '--access', '--base-revision', '--native-session', '--native-agent', '--native-host', '--coordinator-session']);
70
84
  for (let index = 0; index < argv.length; index += 2) {
71
85
  const key = argv[index]; const value = argv[index + 1];
72
86
  requireValue(allowed.has(key) && typeof value === 'string' && value && !value.startsWith('--') && flags[key] === undefined,
@@ -86,6 +100,7 @@ export async function main(argv = process.argv.slice(2)) {
86
100
  outPath: flags['--out'], briefPath: flags['--brief'], availableCapabilities: flags['--capabilities'].split(',').filter(Boolean),
87
101
  coordinatorRoot: flags['--coordinator'], parallel: flags['--parallel'] === undefined ? undefined : flags['--parallel'] === 'true',
88
102
  access: flags['--access'], baseRevision: flags['--base-revision'], nativeHost: flags['--native-host'],
103
+ coordinatorSession: flags['--coordinator-session'],
89
104
  }, { cwd: flags['--worker-root'], session_id: flags['--native-session'], ...(flags['--native-agent'] ? { agent_id: flags['--native-agent'] } : {}) });
90
105
  const { packet, ...status } = result;
91
106
  process.stdout.write(`${JSON.stringify(status, null, 2)}\n`);
@@ -30,5 +30,12 @@
30
30
  "test-runner": { "label": "Project test runner", "scope": "project", "size": "declared by the project", "sudo": false },
31
31
  "curl": { "label": "HTTP check (curl)", "scope": "system", "size": "built in on macOS", "sudo": false,
32
32
  "steps": ["Install curl with your system package manager"], "evidence": "curl -sS <url>" }
33
+ },
34
+ "optIn": {
35
+ "doc-detective": { "label": "Doc Detective (docs as tests)", "scope": "project", "size": "several hundred MB with browsers and drivers (estimate)", "sudo": false,
36
+ "license": "AGPL-3.0", "fits": "Docs that are step-by-step procedures: commands, API calls, UI clicks, links",
37
+ "notFor": "Conceptual or rules prose; checking that unit tests match a spec",
38
+ "steps": ["Ask the user first: it downloads browsers and drivers and is AGPL-3.0", "Run `npx doc-detective` once to try it, or add it as a dev dependency", "Mark test steps in the procedure docs (see https://docs.doc-detective.com)"],
39
+ "evidence": "npx doc-detective --input <docs-folder>" }
33
40
  }
34
41
  }