joycraft 1.1.0 → 1.1.2
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 +57 -16
- package/dist/cli.js +50 -9
- package/dist/cli.js.map +1 -1
- package/dist/joycraft-release.json +1 -1
- package/package.json +3 -3
- package/payload/.agents/skills/joycraft-cleanup/SKILL.md +81 -34
- package/payload/.agents/skills/joycraft-context/SKILL.md +30 -4
- package/payload/.agents/skills/joycraft-entry/SKILL.md +19 -8
- package/payload/.agents/skills/joycraft-session-end/SKILL.md +8 -3
- package/payload/.joycraft/assets/artifacts/kit.css +8 -0
- package/payload/.joycraft/assets/artifacts/kit.js +163 -21
- package/payload/.joycraft/assets/artifacts/transports.js +14 -3
- package/payload/.joycraft/references/artifacts.md +21 -2
- package/payload/.joycraft/references/cleanup.md +109 -3
- package/payload/.joycraft/references/context.md +64 -2
- package/payload/.joycraft/references/doc-cleanup-LICENSE.md +23 -0
- package/payload/.joycraft/references/knowledge.md +58 -0
- package/payload/.joycraft/references/setup.md +128 -138
- package/payload/.joycraft/references/update.md +5 -3
- package/payload/.joycraft/runtime/artifacts/decisions.mjs +16 -5
- package/payload/.joycraft/runtime/artifacts/server.mjs +14 -1
- package/payload/.joycraft/runtime/cleanup.mjs +114 -9
- package/payload/.joycraft/runtime/config.mjs +8 -4
- package/payload/.joycraft/runtime/coordinator.mjs +28 -5
- package/payload/.joycraft/runtime/review-tools.mjs +55 -8
- package/payload/.joycraft/runtime/status.mjs +2 -2
- package/payload/.joycraft/runtime/trace.mjs +8 -3
- package/payload/.joycraft/runtime/update-check.mjs +38 -8
- package/payload/.joycraft/runtime/wiring.mjs +156 -0
- package/payload/.joycraft/runtime/worktrees.mjs +9 -7
- package/payload/.joycraft/templates/joycraft.yaml +2 -0
- package/payload/.joycraft/templates/project-context.md +6 -1
- package/payload/PIN +29 -26
|
@@ -10,13 +10,15 @@ export const configFile = 'joycraft.yaml';
|
|
|
10
10
|
export const defaults = Object.freeze({
|
|
11
11
|
paths: Object.freeze({ features: 'docs/features', archive: 'docs/archive', context: 'docs/context' }),
|
|
12
12
|
hooks: Object.freeze({}),
|
|
13
|
-
cleanup: Object.freeze({ impact: Object.freeze([]) }),
|
|
13
|
+
cleanup: Object.freeze({ impact: Object.freeze([]), entryWords: 1000 }),
|
|
14
14
|
});
|
|
15
15
|
|
|
16
16
|
function scalar(text, line) {
|
|
17
17
|
const value = text.trim();
|
|
18
18
|
if (value === '') return null;
|
|
19
|
-
if (/^"(?:[^"\\]|\\.)*"$/.test(value))
|
|
19
|
+
if (/^"(?:[^"\\]|\\.)*"$/.test(value)) {
|
|
20
|
+
try { return JSON.parse(value); } catch { throw new Error(`${configFile} line ${line}: a double-quoted value has an escape YAML does not allow here: ${value}`); }
|
|
21
|
+
}
|
|
20
22
|
if (/^'(?:[^']|'')*'$/.test(value)) return value.slice(1, -1).replaceAll("''", "'");
|
|
21
23
|
requireValue(!/^["']/.test(value), `${configFile} line ${line}: a quoted value must end with its closing quote and nothing after it: ${value}`);
|
|
22
24
|
if (/^\[.*\]$/.test(value)) {
|
|
@@ -115,7 +117,7 @@ export function parseYaml(text) {
|
|
|
115
117
|
return result;
|
|
116
118
|
}
|
|
117
119
|
|
|
118
|
-
const known = { paths: ['features', 'archive', 'context'], hooks: ['afterArchive'], cleanup: ['impact'] };
|
|
120
|
+
const known = { paths: ['features', 'archive', 'context'], hooks: ['afterArchive'], cleanup: ['impact', 'entryWords'] };
|
|
119
121
|
|
|
120
122
|
/** Read joycraft.yaml (or return defaults) and validate every known field. */
|
|
121
123
|
export function readConfig(root = process.cwd()) {
|
|
@@ -151,7 +153,9 @@ export function readConfig(root = process.cwd()) {
|
|
|
151
153
|
`${configFile}: cleanup.impact item ${index + 1} needs source (a glob) and docs (a list of files)`);
|
|
152
154
|
checkGlob(entry.source, `cleanup.impact item ${index + 1} source`);
|
|
153
155
|
}
|
|
154
|
-
|
|
156
|
+
const entryWords = parsed.cleanup?.entryWords ?? defaults.cleanup.entryWords;
|
|
157
|
+
requireValue(Number.isInteger(entryWords) && entryWords > 0, `${configFile}: cleanup.entryWords must be a positive whole number of words`);
|
|
158
|
+
return { source: configFile, paths, hooks, cleanup: { impact: impact.map(entry => ({ source: entry.source, docs: entry.docs.map(relativePath) })), entryWords } };
|
|
155
159
|
}
|
|
156
160
|
|
|
157
161
|
/** Project-relative work folders for a project. */
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { execFileSync } from 'node:child_process';
|
|
2
|
-
import {
|
|
2
|
+
import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
|
|
3
3
|
import path from 'node:path';
|
|
4
4
|
import { pathToFileURL } from 'node:url';
|
|
5
5
|
import { isObject, nonempty, parseJson, readLocal, relativePath, requireValue, validateQueue } from './identity.mjs';
|
|
@@ -25,21 +25,44 @@ export function leasePath(root, feature) {
|
|
|
25
25
|
return path.join(mainTree(root), leaseRelative(feature));
|
|
26
26
|
}
|
|
27
27
|
|
|
28
|
+
function lockIsStale(lock, waitMs) {
|
|
29
|
+
const pid = Number(readFileSync(lock, 'utf8'));
|
|
30
|
+
if (!Number.isInteger(pid) || pid <= 0) return Date.now() - statSync(lock).mtimeMs > waitMs;
|
|
31
|
+
try { process.kill(pid, 0); return false; } catch (error) { return error.code === 'ESRCH'; }
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
// Waiters that see a stale lock take turns through a guard file, so two of them
|
|
35
|
+
// cannot both remove it and one remove the other's new lock.
|
|
36
|
+
function takeOver(lock, waitMs) {
|
|
37
|
+
const guard = `${lock}.takeover`;
|
|
38
|
+
try { writeFileSync(guard, String(process.pid), { flag: 'wx' }); } catch (error) {
|
|
39
|
+
if (error.code !== 'EEXIST') throw error;
|
|
40
|
+
try { if (Date.now() - statSync(guard).mtimeMs > waitMs) rmSync(guard, { force: true }); } catch { /* another waiter removed it */ }
|
|
41
|
+
return;
|
|
42
|
+
}
|
|
43
|
+
try { if (lockIsStale(lock, waitMs)) unlinkSync(lock); } catch { /* the holder released it */ } finally { rmSync(guard, { force: true }); }
|
|
44
|
+
}
|
|
45
|
+
|
|
28
46
|
/** Serialize a read-modify-write of a small local record with an exclusive lock file. */
|
|
29
47
|
export function withLock(file, action, { waitMs = 5000 } = {}) {
|
|
30
48
|
const lock = `${file}.lock`;
|
|
31
49
|
mkdirSync(path.dirname(file), { recursive: true });
|
|
32
50
|
const deadline = Date.now() + waitMs;
|
|
33
51
|
for (;;) {
|
|
34
|
-
try {
|
|
52
|
+
try { writeFileSync(lock, String(process.pid), { flag: 'wx' }); break; } catch (error) {
|
|
35
53
|
if (error.code !== 'EEXIST') throw error;
|
|
36
|
-
//
|
|
37
|
-
|
|
54
|
+
// The lock names its holder. Take it over only when that process is gone, or,
|
|
55
|
+
// for a lock with no readable holder, when it is older than the wait limit.
|
|
56
|
+
let stale = false;
|
|
57
|
+
try { stale = lockIsStale(lock, waitMs); } catch { continue; }
|
|
58
|
+
if (stale) { takeOver(lock, waitMs); continue; }
|
|
38
59
|
requireValue(Date.now() < deadline, `Another Joycraft process holds ${path.basename(lock)}; try again`);
|
|
39
60
|
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
|
|
40
61
|
}
|
|
41
62
|
}
|
|
42
|
-
try { return action(); } finally {
|
|
63
|
+
try { return action(); } finally {
|
|
64
|
+
try { if (readFileSync(lock, 'utf8') === String(process.pid)) unlinkSync(lock); } catch { /* already gone */ }
|
|
65
|
+
}
|
|
43
66
|
}
|
|
44
67
|
|
|
45
68
|
/** No lease can exist for a feature name that is not a slug, so 1.0.0 queues keep working. */
|
|
@@ -34,6 +34,40 @@ function workspaceDirs(root) {
|
|
|
34
34
|
return [...new Set(dirs)];
|
|
35
35
|
}
|
|
36
36
|
|
|
37
|
+
const manifestFile = /(^|\/)(package\.json|pubspec\.yaml|Package\.swift|build\.gradle(\.kts)?|pyproject\.toml|requirements\.txt|setup\.py|Cargo\.toml|go\.mod)$/;
|
|
38
|
+
const skipDir = name => name.startsWith('.') || ['node_modules', 'vendor', 'Pods', 'dist', 'build', 'target'].includes(name);
|
|
39
|
+
|
|
40
|
+
/** Project files below the root: git's view when it has one (so .gitignore holds), else a bounded walk. */
|
|
41
|
+
function projectFiles(root) {
|
|
42
|
+
try {
|
|
43
|
+
const out = execFileSync('git', ['-C', root, 'ls-files', '--cached', '--others', '--exclude-standard'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024 });
|
|
44
|
+
return out.split('\n').filter(Boolean);
|
|
45
|
+
} catch {
|
|
46
|
+
const files = [];
|
|
47
|
+
const walk = (rel, depth) => {
|
|
48
|
+
for (const name of listDir(path.join(root, rel))) {
|
|
49
|
+
const file = rel ? `${rel}/${name}` : name;
|
|
50
|
+
if (isDir(path.join(root, file))) { if (depth < 6 && !skipDir(name)) walk(file, depth + 1); } else files.push(file);
|
|
51
|
+
}
|
|
52
|
+
};
|
|
53
|
+
walk('', 0);
|
|
54
|
+
return files;
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/** Folders holding a manifest when no workspaces are declared. The shallowest wins; an Android `app/` belongs to its parent. */
|
|
59
|
+
function nestedPackageDirs(root) {
|
|
60
|
+
const dirs = new Set();
|
|
61
|
+
for (const file of projectFiles(root)) {
|
|
62
|
+
if (!manifestFile.test(file) || file.split('/').some(skipDir)) continue;
|
|
63
|
+
let dir = path.posix.dirname(file);
|
|
64
|
+
if (/build\.gradle/.test(file) && path.posix.basename(dir) === 'app') dir = path.posix.dirname(dir);
|
|
65
|
+
if (dir !== '.') dirs.add(dir);
|
|
66
|
+
}
|
|
67
|
+
const sorted = [...dirs].sort();
|
|
68
|
+
return sorted.filter(dir => !sorted.some(other => other !== dir && dir.startsWith(`${other}/`)));
|
|
69
|
+
}
|
|
70
|
+
|
|
37
71
|
/** Categories for one package directory, from its manifests and project files only. */
|
|
38
72
|
export function classifyPackage(dir) {
|
|
39
73
|
const found = new Set();
|
|
@@ -65,11 +99,19 @@ export function classifyPackage(dir) {
|
|
|
65
99
|
return [...found];
|
|
66
100
|
}
|
|
67
101
|
|
|
68
|
-
/**
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
102
|
+
/**
|
|
103
|
+
* Each package of a project with its categories. A workspace root without its own app is not a package.
|
|
104
|
+
* `packages` names the folders outright; with no workspaces and no root manifest, nested manifests are scanned.
|
|
105
|
+
*/
|
|
106
|
+
export function detectProjects(root, { packages: named = null } = {}) {
|
|
107
|
+
const outside = (named ?? []).find(dir => path.isAbsolute(dir) || dir.split(/[\\/]/).includes('..'));
|
|
108
|
+
if (outside) throw new Error(`--packages takes folders inside the project; ${outside} is not`);
|
|
72
109
|
const own = classifyPackage(root);
|
|
110
|
+
const declared = named ?? workspaceDirs(root);
|
|
111
|
+
const dirs = named || declared.length || own.length ? declared : nestedPackageDirs(root);
|
|
112
|
+
const packages = dirs.map(dir => ({ path: dir, categories: classifyPackage(path.join(root, dir)) }))
|
|
113
|
+
.filter(entry => entry.categories.length);
|
|
114
|
+
if (named) return packages;
|
|
73
115
|
const workspaceOnly = packages.length && own.every(category => category === 'cli-library');
|
|
74
116
|
return [...(workspaceOnly || !own.length ? [] : [{ path: '.', categories: own }]), ...packages];
|
|
75
117
|
}
|
|
@@ -163,8 +205,8 @@ function startCommand(dir, root, categories) {
|
|
|
163
205
|
}
|
|
164
206
|
|
|
165
207
|
/** The Review loop plan: each package, each tool it needs, and that tool's status. Probes only. */
|
|
166
|
-
export function reviewLoopPlan(root, { run = defaultRun, hostTools = [], env = process.env, home = homedir() } = {}) {
|
|
167
|
-
const packages = detectProjects(root).map(entry => {
|
|
208
|
+
export function reviewLoopPlan(root, { run = defaultRun, hostTools = [], env = process.env, home = homedir(), packages: named = null } = {}) {
|
|
209
|
+
const packages = detectProjects(root, { packages: named }).map(entry => {
|
|
168
210
|
const dir = path.join(root, entry.path);
|
|
169
211
|
const tools = toolsFor(entry.categories, dir).map(id => {
|
|
170
212
|
const spec = catalog.tools[id];
|
|
@@ -191,6 +233,10 @@ const statusText = tool => tool.status === 'present' ? `present${tool.version ?
|
|
|
191
233
|
|
|
192
234
|
/** One table and at most one question, decision first. */
|
|
193
235
|
export function renderPlan(plan, changes = null) {
|
|
236
|
+
if (!plan.packages.length) {
|
|
237
|
+
return ['Review loop plan', '', 'No packages found: no workspaces are declared and no project manifest was found below the root.',
|
|
238
|
+
'', 'Which folders hold the apps? Name them with `--packages <dir,dir>` on plan, install and record.'].join('\n');
|
|
239
|
+
}
|
|
194
240
|
const lines = ['Review loop plan', '', '| Package | Kind | Tool | Status | To install |', '|---|---|---|---|---|'];
|
|
195
241
|
for (const entry of plan.packages) for (const tool of entry.tools) {
|
|
196
242
|
const install = tool.install?.commands ? `\`${tool.install.commands.map(command => command.join(' ')).join(' && ')}\` (${tool.install.size})`
|
|
@@ -259,6 +305,7 @@ export function planForSetup(root, options) {
|
|
|
259
305
|
|
|
260
306
|
/** Write the chosen setup to AGENTS.md under `## Review loop`, replacing only that section. */
|
|
261
307
|
export function recordReviewLoop(root, plan, { skipped = [] } = {}) {
|
|
308
|
+
if (!plan.packages.length) throw new Error('No packages found, so there is nothing to record; name them with --packages <dir,dir>');
|
|
262
309
|
const rows = ['| Package | Tool | Start the app | Take the evidence |', '|---|---|---|---|'];
|
|
263
310
|
const unverified = [];
|
|
264
311
|
for (const entry of plan.packages) {
|
|
@@ -307,7 +354,7 @@ export async function main(argv = process.argv.slice(2)) {
|
|
|
307
354
|
}
|
|
308
355
|
const root = path.resolve(flags['--root'] ?? '.');
|
|
309
356
|
const list = value => (value ? value.split(',').filter(Boolean) : []);
|
|
310
|
-
const options = { hostTools: list(flags['--host-tools']) };
|
|
357
|
+
const options = { hostTools: list(flags['--host-tools']), packages: flags['--packages'] ? list(flags['--packages']) : null };
|
|
311
358
|
if (command === 'plan') {
|
|
312
359
|
const { text, ask } = planForSetup(root, options);
|
|
313
360
|
process.stdout.write(`${text}\n`);
|
|
@@ -323,7 +370,7 @@ export async function main(argv = process.argv.slice(2)) {
|
|
|
323
370
|
process.stdout.write(`${JSON.stringify(result)}\n`);
|
|
324
371
|
return result;
|
|
325
372
|
}
|
|
326
|
-
throw new Error('Usage: review-tools.mjs plan|install|record --root <project> [--host-tools browser,simulator] [--tools playwright --yes] [--skip playwright]');
|
|
373
|
+
throw new Error('Usage: review-tools.mjs plan|install|record --root <project> [--packages apps/web,apps/api] [--host-tools browser,simulator] [--tools playwright --yes] [--skip playwright]');
|
|
327
374
|
}
|
|
328
375
|
|
|
329
376
|
if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
|
|
@@ -4,7 +4,7 @@ import { pathToFileURL } from 'node:url';
|
|
|
4
4
|
import { journalPath } from './completion.mjs';
|
|
5
5
|
import { workPaths } from './config.mjs';
|
|
6
6
|
import { briefDecisionRecords, isObject, localPath, parseJson, readLocal, specStatus, validateQueue } from './identity.mjs';
|
|
7
|
-
import { listWorktrees } from './worktrees.mjs';
|
|
7
|
+
import { decide, listWorktrees } from './worktrees.mjs';
|
|
8
8
|
|
|
9
9
|
// The queue is the status authority; spec frontmatter mirrors it. This report
|
|
10
10
|
// shows where the mirror or the working folders have drifted, so a session can
|
|
@@ -34,7 +34,7 @@ function worktreeCounts(root) {
|
|
|
34
34
|
const { trees } = listWorktrees({ root, sizes: false });
|
|
35
35
|
return {
|
|
36
36
|
owned: trees.filter(tree => tree.owner === 'joycraft' && !tree.missing).length,
|
|
37
|
-
prunable: trees.filter(tree => tree.
|
|
37
|
+
prunable: trees.filter(tree => decide(tree).action === 'remove').length,
|
|
38
38
|
unknown: trees.filter(tree => tree.owner !== 'joycraft').length,
|
|
39
39
|
};
|
|
40
40
|
} catch { return null; }
|
|
@@ -11,6 +11,11 @@ const tag = /\[AC:([A-Za-z0-9_.-]+)\]/g;
|
|
|
11
11
|
|
|
12
12
|
function filesMatching(root, glob) {
|
|
13
13
|
const pattern = globToRegExp(checkGlob(glob, '--tests'));
|
|
14
|
+
return filesUnder(root, '', file => pattern.test(file));
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
// A declared folder is a literal path, so names like tests/[slug] need no glob escaping.
|
|
18
|
+
function filesUnder(root, base, keep = () => true) {
|
|
14
19
|
const out = [];
|
|
15
20
|
const walk = relative => {
|
|
16
21
|
let entries;
|
|
@@ -19,10 +24,10 @@ function filesMatching(root, glob) {
|
|
|
19
24
|
if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === '.joycraft') continue;
|
|
20
25
|
const child = relative ? `${relative}/${entry.name}` : entry.name;
|
|
21
26
|
if (entry.isDirectory()) walk(child);
|
|
22
|
-
else if (entry.isFile() &&
|
|
27
|
+
else if (entry.isFile() && keep(child)) out.push(child);
|
|
23
28
|
}
|
|
24
29
|
};
|
|
25
|
-
walk(
|
|
30
|
+
walk(base);
|
|
26
31
|
return out;
|
|
27
32
|
}
|
|
28
33
|
|
|
@@ -36,7 +41,7 @@ export function traceSpec({ root = process.cwd(), queuePath, specId, tests = []
|
|
|
36
41
|
const criteria = (spec.verification.criteria ?? []).map(item => item.id);
|
|
37
42
|
const declared = spec.verification.inputs.filter(input => input.kind === 'check' && input.state !== 'absent').map(input => relativePath(input.path));
|
|
38
43
|
// A declared check folder stands for every file inside it.
|
|
39
|
-
const expanded = declared.flatMap(file => existsSync(path.join(root, file)) && statSync(path.join(root, file)).isDirectory() ?
|
|
44
|
+
const expanded = declared.flatMap(file => existsSync(path.join(root, file)) && statSync(path.join(root, file)).isDirectory() ? filesUnder(root, file) : [file]);
|
|
40
45
|
const files = [...new Set([...expanded, ...tests.flatMap(glob => filesMatching(root, glob))])].sort();
|
|
41
46
|
const untraceableIds = criteria.filter(id => !/^[A-Za-z0-9_.-]+$/.test(id));
|
|
42
47
|
const traced = Object.fromEntries(criteria.map(id => [id, []]));
|
|
@@ -1,11 +1,14 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
// Daily check for a newer Joycraft. Prints nothing unless there is something to say,
|
|
3
|
-
// and never fails a session. The request
|
|
3
|
+
// and never fails a session. The one request reads the public package document
|
|
4
|
+
// (every version's metadata, about 25 KB compressed), never project data.
|
|
4
5
|
import { lstatSync, mkdirSync, openSync, closeSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
|
|
5
6
|
import { join, resolve } from 'node:path';
|
|
6
7
|
import { pathToFileURL } from 'node:url';
|
|
7
8
|
|
|
8
|
-
const registry = 'https://registry.npmjs.org/joycraft
|
|
9
|
+
const registry = 'https://registry.npmjs.org/joycraft';
|
|
10
|
+
const changelog = 'https://github.com/maksutovic/joycraft/blob/main/CHANGELOG.md';
|
|
11
|
+
const listed = 5;
|
|
9
12
|
const day = 24 * 60 * 60 * 1000;
|
|
10
13
|
const retryAfter = 60 * 60 * 1000;
|
|
11
14
|
const snoozeFor = 7 * day;
|
|
@@ -51,7 +54,11 @@ export function isNewer(candidate, installed) {
|
|
|
51
54
|
return false;
|
|
52
55
|
}
|
|
53
56
|
|
|
54
|
-
|
|
57
|
+
export function updateKind(latest, installed) {
|
|
58
|
+
const [major, minor] = latest.split('.'), [fromMajor, fromMinor] = installed.split('.');
|
|
59
|
+
if (BigInt(major) !== BigInt(fromMajor)) return 'migration';
|
|
60
|
+
return BigInt(minor) === BigInt(fromMinor) ? 'patch' : 'minor';
|
|
61
|
+
}
|
|
55
62
|
const oneLine = value => typeof value === 'string' ? value.replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 300) : '';
|
|
56
63
|
|
|
57
64
|
function holdLock(root) {
|
|
@@ -74,10 +81,17 @@ async function latestRelease(root, { fetcher, now }) {
|
|
|
74
81
|
try {
|
|
75
82
|
const response = await fetcher(registry, { signal: AbortSignal.timeout(deadline), headers: { accept: 'application/json' } });
|
|
76
83
|
if (!response.ok) throw new Error(`registry ${response.status}`);
|
|
77
|
-
const
|
|
78
|
-
|
|
79
|
-
const
|
|
80
|
-
|
|
84
|
+
const packument = await response.json();
|
|
85
|
+
const version = packument?.['dist-tags']?.latest;
|
|
86
|
+
const versions = packument?.versions;
|
|
87
|
+
if (typeof version !== 'string' || !stable.test(version) || !versions || typeof versions !== 'object' || !versions[version]) throw new Error('not a stable release');
|
|
88
|
+
const notesOf = key => versions[key]?.joycraft?.release === key ? versions[key].joycraft : {};
|
|
89
|
+
const releases = Object.keys(versions)
|
|
90
|
+
.filter(key => stable.test(key) && !isNewer(key, version))
|
|
91
|
+
.sort((a, b) => isNewer(a, b) ? 1 : isNewer(b, a) ? -1 : 0)
|
|
92
|
+
.map(key => ({ version: key, summary: oneLine(notesOf(key).summary) }));
|
|
93
|
+
const notes = notesOf(version);
|
|
94
|
+
const fresh = { fetchedAt: now, version, summary: oneLine(notes.summary), autoSafeEligible: notes.autoSafeEligible === true, releases };
|
|
81
95
|
writeLocal(root, 'update-check.json', fresh);
|
|
82
96
|
return fresh;
|
|
83
97
|
} catch {
|
|
@@ -99,8 +113,24 @@ export async function check(root, { fetcher = fetch, now = Date.now() } = {}) {
|
|
|
99
113
|
const kind = updateKind(latest, installed);
|
|
100
114
|
const summary = cache.summary || 'See the changelog for what changed.';
|
|
101
115
|
if (update.pin === true) return { action: 'note', installed, latest, kind, message: `Joycraft ${latest} is available. This project stays on ${installed} by choice.` };
|
|
116
|
+
const releases = sinceInstalled(cache, installed, latest);
|
|
102
117
|
const action = policy === 'auto-safe' && kind === 'patch' && cache.autoSafeEligible === true ? 'apply' : 'ask';
|
|
103
|
-
return { action, installed, latest, kind, summary, message: `Joycraft ${latest} is available (you have ${installed}; ${kind}). ${
|
|
118
|
+
return { action, installed, latest, kind, summary, releases, changelog, message: `Joycraft ${latest} is available (you have ${installed}; ${kind}). ${describe(releases)} Changelog: ${changelog}` };
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/** Releases after the installed one up to latest, newest first. A cache from before release lists holds only latest. */
|
|
122
|
+
function sinceInstalled(cache, installed, latest) {
|
|
123
|
+
const known = Array.isArray(cache.releases) ? cache.releases : [{ version: latest, summary: cache.summary }];
|
|
124
|
+
return known
|
|
125
|
+
.filter(entry => typeof entry?.version === 'string' && stable.test(entry.version) && isNewer(entry.version, installed) && !isNewer(entry.version, latest))
|
|
126
|
+
.map(entry => ({ version: entry.version, summary: oneLine(entry.summary) }))
|
|
127
|
+
.reverse();
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
function describe(releases) {
|
|
131
|
+
const shown = releases.slice(0, listed).map(entry => `${entry.version}: ${entry.summary || 'no summary.'}`.replace(/([^.!?])$/, '$1.'));
|
|
132
|
+
const more = releases.length - shown.length;
|
|
133
|
+
return `${shown.join(' ')}${more > 0 ? ` and ${more} more.` : ''}`;
|
|
104
134
|
}
|
|
105
135
|
|
|
106
136
|
function savePreference(root, change) {
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
import { readFileSync, realpathSync } from 'node:fs';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import { pathToFileURL } from 'node:url';
|
|
4
|
+
import { workPaths } from './config.mjs';
|
|
5
|
+
|
|
6
|
+
// A report-only check that the project's entry files carry Joycraft: the
|
|
7
|
+
// update-check line, a context map with at least one project row, and (when
|
|
8
|
+
// Claude Code is installed) a CLAUDE.md that imports AGENTS.md, unless AGENTS.md
|
|
9
|
+
// itself imports CLAUDE.md. It never edits a file; the agent writes the missing
|
|
10
|
+
// pieces after talking with the person. `findings` decide the exit code;
|
|
11
|
+
// `advice` (areas setup has not mapped yet) never does.
|
|
12
|
+
const read = (root, file) => { try { return readFileSync(path.join(root, file), 'utf8'); } catch { return null; } };
|
|
13
|
+
|
|
14
|
+
function claudeInstalled(root, hosts) {
|
|
15
|
+
if (Array.isArray(hosts)) return hosts.includes('claude');
|
|
16
|
+
const text = read(root, '.joycraft/installation.json');
|
|
17
|
+
if (text === null) return false;
|
|
18
|
+
try {
|
|
19
|
+
const manifest = JSON.parse(text);
|
|
20
|
+
const hosts = Array.isArray(manifest?.hosts) ? manifest.hosts : [manifest?.harness];
|
|
21
|
+
return hosts.includes('claude');
|
|
22
|
+
} catch { return false; }
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
// Lines outside fenced code, so an example in a fence is not read as the map.
|
|
26
|
+
function proseLines(text) {
|
|
27
|
+
let fence = null;
|
|
28
|
+
return text.split(/\r?\n/).map(line => {
|
|
29
|
+
const marker = /^\s*(`{3,}|~{3,})/.exec(line)?.[1];
|
|
30
|
+
if (!fence) {
|
|
31
|
+
if (!marker || (marker[0] === '`' && line.trimStart().slice(marker.length).includes('`'))) return line;
|
|
32
|
+
fence = marker;
|
|
33
|
+
} else if (marker && marker[0] === fence[0] && marker.length >= fence.length && /^\s*[`~]+\s*$/.test(line)) fence = null;
|
|
34
|
+
return '';
|
|
35
|
+
});
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/** The lines under the context map heading, up to the next heading of the same or a higher level; null when there is none. */
|
|
39
|
+
function contextMap(text) {
|
|
40
|
+
const lines = proseLines(text);
|
|
41
|
+
// Any heading whose text starts with "context map": `## Context Map (read only what you need)`.
|
|
42
|
+
const start = lines.findIndex(line => /^ {0,3}#{1,6}\s+context map\b/i.test(line));
|
|
43
|
+
if (start === -1) return null;
|
|
44
|
+
const level = /^ {0,3}(#+)/.exec(lines[start])[1].length;
|
|
45
|
+
const end = lines.findIndex((line, index) => index > start && (/^ {0,3}(#+)\s/.exec(line)?.[1].length ?? 7) <= level);
|
|
46
|
+
return lines.slice(start + 1, end === -1 ? undefined : end);
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** Reference-link definitions (`[label]: target`) outside code, keyed by lowercased label. */
|
|
50
|
+
function linkDefinitions(lines) {
|
|
51
|
+
const out = new Map();
|
|
52
|
+
for (const line of lines) {
|
|
53
|
+
const match = /^ {0,3}\[([^\]]+)\]:\s+(?:<([^>]+)>|(\S+))/.exec(line);
|
|
54
|
+
const label = match?.[1].trim().toLowerCase();
|
|
55
|
+
if (label && !out.has(label)) out.set(label, match[2] ?? match[3]);
|
|
56
|
+
}
|
|
57
|
+
return out;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* Project-relative targets of a table row: inline links, full and collapsed
|
|
62
|
+
* reference links (`[p][ref]`, `[p][]`) and backticked paths. A leading `/` means
|
|
63
|
+
* the project root.
|
|
64
|
+
*/
|
|
65
|
+
function rowTargets(row, definitions = new Map()) {
|
|
66
|
+
const raw = [
|
|
67
|
+
...[...row.matchAll(/\[[^\]]*\]\((?:<([^>]+)>|([^)\s]+))[^)]*\)/g)].map(match => match[1] ?? match[2]),
|
|
68
|
+
...[...row.matchAll(/\[([^\]]*)\]\[([^\]]*)\]/g)].map(match => definitions.get((match[2] || match[1]).trim().toLowerCase())).filter(Boolean),
|
|
69
|
+
...[...row.matchAll(/`([^`\s]+)`/g)].map(match => match[1]).filter(value => value.includes('/') || /\.[a-z0-9]+$/i.test(value)),
|
|
70
|
+
];
|
|
71
|
+
return raw.map(target => target.split('#')[0])
|
|
72
|
+
.filter(target => target && !/^[a-z][a-z0-9+.-]*:/i.test(target) && !target.startsWith('//'))
|
|
73
|
+
.map(target => target.replace(/^\/+/, ''))
|
|
74
|
+
.filter(Boolean)
|
|
75
|
+
.map(target => path.posix.normalize(target));
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
const imports = (text, file) => text !== null && proseLines(text).some(line => new RegExp(`^\\s*@(\\./)?${file.replace('.', '\\.')}\\s*$`).test(line));
|
|
79
|
+
|
|
80
|
+
/** True when AGENTS.md is CLAUDE.md (a symlink) or imports it, so Claude Code reads both without a reciprocal import. */
|
|
81
|
+
function agentsDefersToClaude(root, agents) {
|
|
82
|
+
try { if (realpathSync(path.join(root, 'AGENTS.md')) === realpathSync(path.join(root, 'CLAUDE.md'))) return true; } catch { /* either file missing */ }
|
|
83
|
+
return imports(agents, 'CLAUDE.md');
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/** Items of the `## Not yet mapped` list in the project context page: areas setup has not read yet. */
|
|
87
|
+
export function unmappedAreas(text) {
|
|
88
|
+
if (text === null) return [];
|
|
89
|
+
const lines = proseLines(text);
|
|
90
|
+
const start = lines.findIndex(line => /^ {0,3}#{1,6}\s+not yet mapped\b/i.test(line));
|
|
91
|
+
if (start === -1) return [];
|
|
92
|
+
const level = /^ {0,3}(#+)/.exec(lines[start])[1].length;
|
|
93
|
+
const areas = [];
|
|
94
|
+
for (const line of lines.slice(start + 1)) {
|
|
95
|
+
if ((/^ {0,3}(#+)\s/.exec(line)?.[1].length ?? 7) <= level) break;
|
|
96
|
+
const item = /^\s*[-*+]\s+(.+?)\s*$/.exec(line)?.[1];
|
|
97
|
+
if (item) areas.push(item);
|
|
98
|
+
}
|
|
99
|
+
return areas;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
function contextPage(root) {
|
|
103
|
+
try { return `${workPaths(root).context}/project.md`; } catch { return 'docs/context/project.md'; }
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
const outsideJoycraft = target => target !== '.joycraft' && !target.startsWith('.joycraft/') && !target.startsWith('../');
|
|
107
|
+
|
|
108
|
+
/** Report what is missing for the project to be wired up. Reads files only. */
|
|
109
|
+
export function checkWiring(root, { hosts } = {}) {
|
|
110
|
+
const findings = [];
|
|
111
|
+
const agents = read(root, 'AGENTS.md');
|
|
112
|
+
if (agents === null) {
|
|
113
|
+
findings.push({ check: 'no-agents-md', path: 'AGENTS.md', detail: 'The project has no AGENTS.md, so agents get no Joycraft lines and no context map.', fix: "Ask the agent to set up Joycraft's context map (see .joycraft/references/setup.md)." });
|
|
114
|
+
} else {
|
|
115
|
+
if (!agents.includes('update-check.mjs check')) {
|
|
116
|
+
findings.push({ check: 'no-joycraft-lines', path: 'AGENTS.md', detail: 'AGENTS.md has no `node .joycraft/runtime/update-check.mjs check` line, so sessions do not start with Joycraft.', fix: 'Add the Joycraft lines from .joycraft/references/setup.md with a targeted edit.' });
|
|
117
|
+
}
|
|
118
|
+
const map = contextMap(agents);
|
|
119
|
+
if (map === null) {
|
|
120
|
+
findings.push({ check: 'no-context-map', path: 'AGENTS.md', detail: 'AGENTS.md has no `## Context Map` heading, so agents cannot find project knowledge.', fix: 'Add a context map table that links project documents, each with a "read when".' });
|
|
121
|
+
} else {
|
|
122
|
+
const rows = map.filter(line => /^\s*\|/.test(line));
|
|
123
|
+
const definitions = linkDefinitions(proseLines(agents));
|
|
124
|
+
if (!rows.some(row => rowTargets(row, definitions).some(outsideJoycraft))) {
|
|
125
|
+
findings.push({ check: 'empty-context-map', path: 'AGENTS.md', detail: 'The context map has no row that points to a project document outside .joycraft/.', fix: 'Add rows for the project documents agents should read, each with a "read when".' });
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
if (claudeInstalled(root, hosts)) {
|
|
130
|
+
const claude = read(root, 'CLAUDE.md');
|
|
131
|
+
// An @AGENTS.md line inside a code fence is an example, not an import.
|
|
132
|
+
if (!imports(claude, 'AGENTS.md') && !(claude !== null && agentsDefersToClaude(root, agents))) {
|
|
133
|
+
findings.push({ check: 'no-claude-import', path: 'CLAUDE.md', detail: claude === null ? 'Claude Code is installed, but there is no CLAUDE.md, so Claude Code does not read AGENTS.md.' : 'Claude Code is installed, but CLAUDE.md has no `@AGENTS.md` line, so Claude Code does not read AGENTS.md.', fix: 'Add a line `@AGENTS.md` to CLAUDE.md, creating the file if needed.' });
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
const advice = [];
|
|
137
|
+
const page = contextPage(root);
|
|
138
|
+
const areas = unmappedAreas(read(root, page));
|
|
139
|
+
if (areas.length) {
|
|
140
|
+
advice.push({ check: 'unmapped-areas', path: page, areas, detail: `Setup has not read ${areas.length === 1 ? 'one area' : `${areas.length} areas`} yet: ${areas.join('; ')}.`, fix: 'When a request touches a listed area, map that area first (read it, propose rows, write on yes) and remove it from the list.' });
|
|
141
|
+
}
|
|
142
|
+
return { wired: findings.length === 0, findings, advice };
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
export async function main(argv = process.argv.slice(2)) {
|
|
146
|
+
const index = argv.indexOf('--root');
|
|
147
|
+
if (!(argv.length === 0 || (argv.length === 2 && index === 0))) throw new Error('Usage: wiring.mjs [--root <project>]');
|
|
148
|
+
const result = checkWiring(path.resolve(index === 0 ? argv[1] : '.'));
|
|
149
|
+
process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
|
|
150
|
+
if (!result.wired) process.exitCode = 2;
|
|
151
|
+
return result;
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
|
|
155
|
+
main().catch(error => { process.stderr.write(`Wiring check stopped: ${error.message}\n`); process.exitCode = 1; });
|
|
156
|
+
}
|
|
@@ -66,7 +66,7 @@ export function createWorktree({ root = process.cwd(), queuePath, specId, sessio
|
|
|
66
66
|
});
|
|
67
67
|
}
|
|
68
68
|
|
|
69
|
-
function linkedTrees(root) {
|
|
69
|
+
function linkedTrees(root, here = root) {
|
|
70
70
|
const blocks = git(root, ['worktree', 'list', '--porcelain']).split(/\n\n+/).filter(Boolean);
|
|
71
71
|
const trees = blocks.map(block => {
|
|
72
72
|
const tree = {};
|
|
@@ -76,8 +76,8 @@ function linkedTrees(root) {
|
|
|
76
76
|
}
|
|
77
77
|
return tree;
|
|
78
78
|
});
|
|
79
|
-
// The first entry is the main working tree; the
|
|
80
|
-
return trees.slice(1).filter(tree => !existsSync(tree.worktree) || realpathSync(tree.worktree) !==
|
|
79
|
+
// The first entry is the main working tree; the tree prune runs from is never listed.
|
|
80
|
+
return trees.slice(1).filter(tree => !existsSync(tree.worktree) || realpathSync(tree.worktree) !== here);
|
|
81
81
|
}
|
|
82
82
|
|
|
83
83
|
function sizeOf(target) {
|
|
@@ -113,12 +113,14 @@ function evidenceOnlyHere(root, tree, spec) {
|
|
|
113
113
|
|
|
114
114
|
/** Every linked tree with its owner, spec status, merged and clean state. */
|
|
115
115
|
export function listWorktrees({ root = process.cwd(), into = 'HEAD', sizes = true } = {}) {
|
|
116
|
-
|
|
116
|
+
const main = gitRoot(root);
|
|
117
|
+
const here = realpathSync(git(root, ['rev-parse', '--show-toplevel']).trim());
|
|
118
|
+
root = main;
|
|
117
119
|
const ledger = readLedger(root);
|
|
118
120
|
const owned = new Map(ledger.trees.map(entry => [path.resolve(root, entry.path), entry]));
|
|
119
121
|
const queues = new Map();
|
|
120
122
|
const seen = new Set();
|
|
121
|
-
const trees = linkedTrees(root).map(tree => {
|
|
123
|
+
const trees = linkedTrees(root, here).map(tree => {
|
|
122
124
|
const absolute = existsSync(tree.worktree) ? realpathSync(tree.worktree) : tree.worktree;
|
|
123
125
|
const entry = owned.get(absolute) ?? owned.get(tree.worktree);
|
|
124
126
|
if (entry) seen.add(entry.path);
|
|
@@ -137,11 +139,11 @@ export function listWorktrees({ root = process.cwd(), into = 'HEAD', sizes = tru
|
|
|
137
139
|
if (sizes) record.bytes = exists ? sizeOf(absolute) : 0;
|
|
138
140
|
return record;
|
|
139
141
|
});
|
|
140
|
-
const missing = ledger.trees.filter(entry => !seen.has(entry.path)).map(entry => ({ path: entry.path, branch: entry.branch, owner: 'joycraft', feature: entry.feature, specId: entry.specId, exists: false, missing: true }));
|
|
142
|
+
const missing = ledger.trees.filter(entry => !seen.has(entry.path) && path.resolve(root, entry.path) !== here).map(entry => ({ path: entry.path, branch: entry.branch, owner: 'joycraft', feature: entry.feature, specId: entry.specId, exists: false, missing: true }));
|
|
141
143
|
return { root, into, trees: [...trees, ...missing] };
|
|
142
144
|
}
|
|
143
145
|
|
|
144
|
-
function decide(tree) {
|
|
146
|
+
export function decide(tree) {
|
|
145
147
|
if (tree.owner === 'joycraft' && !tree.exists) return { action: 'forget', reason: 'Recorded tree no longer exists; drop the ledger entry.' };
|
|
146
148
|
if (tree.owner !== 'joycraft') return { action: 'keep', reason: 'Not created by worktrees.mjs; inspect it, then remove it with git worktree remove if it is yours.' };
|
|
147
149
|
if (tree.specStatus !== 'done') return { action: 'keep', reason: `Spec ${tree.specId} is ${tree.specStatus}; keep the tree until it is done.` };
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# <Project name>
|
|
2
2
|
|
|
3
|
-
Copy to `docs/context/project.md` during a kickoff. Delete every section that
|
|
3
|
+
Copy to `docs/context/project.md` during a kickoff or setup. Delete every section that
|
|
4
4
|
has no content yet; never leave a placeholder. Mark each statement as the
|
|
5
5
|
user's words, a decision, or an assumption.
|
|
6
6
|
|
|
@@ -27,6 +27,11 @@ What this project will not do, as the user stated it.
|
|
|
27
27
|
| Term | Meaning, in the user's words |
|
|
28
28
|
|---|---|
|
|
29
29
|
|
|
30
|
+
## Not yet mapped
|
|
31
|
+
|
|
32
|
+
- One item per project area setup has not read yet (a folder or component).
|
|
33
|
+
Remove an item once its area is mapped; keep no history here.
|
|
34
|
+
|
|
30
35
|
## Open questions
|
|
31
36
|
|
|
32
37
|
Consequential unknowns that are not decided yet. Do not write them as boundaries.
|