joycraft 0.7.17 → 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/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-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-YLWBDXF4.js +0 -3999
- package/dist/chunk-YLWBDXF4.js.map +0 -1
- package/dist/chunk-Z5JFEGWG.js +0 -563
- package/dist/chunk-Z5JFEGWG.js.map +0 -1
- package/dist/init-O2QC5X57.js +0 -60
- package/dist/init-O2QC5X57.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-LYHS4FBH.js +0 -21
- package/dist/update-LYHS4FBH.js.map +0 -1
- package/dist/update-check-YT765NE7.js +0 -36
- package/dist/update-check-YT765NE7.js.map +0 -1
- package/dist/upgrade-GMP6JQ52.js +0 -28
- package/dist/upgrade-GMP6JQ52.js.map +0 -1
|
@@ -0,0 +1,331 @@
|
|
|
1
|
+
import { execFileSync } from 'node:child_process';
|
|
2
|
+
import { existsSync, lstatSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
|
|
3
|
+
import { homedir } from 'node:os';
|
|
4
|
+
import path from 'node:path';
|
|
5
|
+
import { pathToFileURL } from 'node:url';
|
|
6
|
+
|
|
7
|
+
// One catalog for detection, the setup plan and the public docs.
|
|
8
|
+
export const catalog = JSON.parse(readFileSync(new URL('./review-tools.json', import.meta.url), 'utf8'));
|
|
9
|
+
const sectionHeading = '## Review loop';
|
|
10
|
+
const marker = /<!-- joycraft:review-loop v1 (\{.*\}) -->/;
|
|
11
|
+
const webDeps = ['next', 'vite', 'react-dom', 'vue', 'svelte', '@sveltejs/kit', 'astro', 'nuxt', '@remix-run/react', 'solid-js', '@angular/core', 'gatsby'];
|
|
12
|
+
const apiDeps = ['express', 'fastify', 'koa', 'hono', '@nestjs/core', '@hapi/hapi'];
|
|
13
|
+
const devServer = /\b(vite|next dev|nuxt dev|astro dev|webpack serve|react-scripts start|ng serve)\b/;
|
|
14
|
+
|
|
15
|
+
const read = file => { try { return readFileSync(file, 'utf8'); } catch { return null; } };
|
|
16
|
+
const isDir = dir => { try { return lstatSync(dir).isDirectory(); } catch { return false; } };
|
|
17
|
+
const json = text => { try { return JSON.parse(text); } catch { return null; } };
|
|
18
|
+
const listDir = dir => { try { return readdirSync(dir); } catch { return []; } };
|
|
19
|
+
|
|
20
|
+
function workspaceDirs(root) {
|
|
21
|
+
const manifest = json(read(path.join(root, 'package.json')));
|
|
22
|
+
const globs = [...(Array.isArray(manifest?.workspaces) ? manifest.workspaces : manifest?.workspaces?.packages ?? [])];
|
|
23
|
+
const pnpm = read(path.join(root, 'pnpm-workspace.yaml'));
|
|
24
|
+
// Only the top-level `packages:` list; other keys hold unrelated lists.
|
|
25
|
+
const block = pnpm && /^packages:\s*\n((?:[ \t]+.*\n?|[ \t]*\n)*)/m.exec(pnpm);
|
|
26
|
+
if (block) for (const match of block[1].matchAll(/^\s*-\s*['"]?([^'"\n#]+?)['"]?\s*$/gm)) globs.push(match[1]);
|
|
27
|
+
const dirs = [];
|
|
28
|
+
for (const glob of globs.filter(item => !item.startsWith('!') && !['.', './'].includes(item))) {
|
|
29
|
+
if (glob.endsWith('/*')) {
|
|
30
|
+
const parent = glob.slice(0, -2);
|
|
31
|
+
for (const name of listDir(path.join(root, parent)).sort()) if (isDir(path.join(root, parent, name))) dirs.push(path.posix.join(parent, name));
|
|
32
|
+
} else if (!glob.includes('*') && isDir(path.join(root, glob))) dirs.push(glob);
|
|
33
|
+
}
|
|
34
|
+
return [...new Set(dirs)];
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** Categories for one package directory, from its manifests and project files only. */
|
|
38
|
+
export function classifyPackage(dir) {
|
|
39
|
+
const found = new Set();
|
|
40
|
+
const manifest = json(read(path.join(dir, 'package.json')));
|
|
41
|
+
const deps = { ...manifest?.dependencies, ...manifest?.devDependencies };
|
|
42
|
+
const has = name => Object.hasOwn(deps, name);
|
|
43
|
+
if (has('expo')) found.add('expo');
|
|
44
|
+
else if (has('react-native')) found.add('react-native');
|
|
45
|
+
if (has('electron')) found.add('electron');
|
|
46
|
+
if (!found.has('expo') && !found.has('react-native') && !found.has('electron')
|
|
47
|
+
&& (webDeps.some(has) || Object.values(manifest?.scripts ?? {}).some(script => devServer.test(String(script))))) found.add('web');
|
|
48
|
+
if (apiDeps.some(has)) found.add('api');
|
|
49
|
+
const pubspec = read(path.join(dir, 'pubspec.yaml'));
|
|
50
|
+
if (pubspec && /^\s*flutter\s*:/m.test(pubspec)) found.add('flutter');
|
|
51
|
+
const names = listDir(dir);
|
|
52
|
+
const swift = read(path.join(dir, 'Package.swift'));
|
|
53
|
+
if (!found.has('flutter') && !found.has('react-native') && !found.has('expo')
|
|
54
|
+
&& (names.some(name => /\.(xcodeproj|xcworkspace)$/.test(name)) || (swift && /\.(iOS|macOS)\s*\(/.test(swift)))) found.add('ios');
|
|
55
|
+
const gradle = ['build.gradle', 'build.gradle.kts', 'app/build.gradle', 'app/build.gradle.kts'].map(file => read(path.join(dir, file))).filter(Boolean).join('\n');
|
|
56
|
+
if (!found.has('flutter') && !found.has('react-native') && !found.has('expo') && /com\.android\./.test(gradle)) found.add('android');
|
|
57
|
+
const python = ['pyproject.toml', 'requirements.txt', 'setup.py'].map(file => read(path.join(dir, file))).filter(Boolean).join('\n');
|
|
58
|
+
if (/\b(fastapi|flask|django|starlette)\b/i.test(python)) found.add('api');
|
|
59
|
+
const cargo = read(path.join(dir, 'Cargo.toml')) ?? '';
|
|
60
|
+
if (/^\s*(axum|actix-web|rocket|warp)\s*=/m.test(cargo)) found.add('api');
|
|
61
|
+
const go = read(path.join(dir, 'go.mod')) ?? '';
|
|
62
|
+
if (/(gin-gonic\/gin|labstack\/echo|gofiber\/fiber|go-chi\/chi)/.test(go)) found.add('api');
|
|
63
|
+
const anyManifest = manifest || python || cargo || go || swift || pubspec || gradle;
|
|
64
|
+
if (!found.size && anyManifest) found.add('cli-library');
|
|
65
|
+
return [...found];
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/** Each package of a project with its categories. A workspace root without its own app is not a package. */
|
|
69
|
+
export function detectProjects(root) {
|
|
70
|
+
const packages = workspaceDirs(root).map(dir => ({ path: dir, categories: classifyPackage(path.join(root, dir)) }))
|
|
71
|
+
.filter(entry => entry.categories.length);
|
|
72
|
+
const own = classifyPackage(root);
|
|
73
|
+
const workspaceOnly = packages.length && own.every(category => category === 'cli-library');
|
|
74
|
+
return [...(workspaceOnly || !own.length ? [] : [{ path: '.', categories: own }]), ...packages];
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
export function packageManager(dir, root = dir) {
|
|
78
|
+
for (const base of [dir, root]) {
|
|
79
|
+
if (existsSync(path.join(base, 'pnpm-lock.yaml'))) return { name: 'pnpm', add: ['pnpm', 'add', '-D'], exec: ['pnpm', 'exec'] };
|
|
80
|
+
if (existsSync(path.join(base, 'yarn.lock'))) return { name: 'yarn', add: ['yarn', 'add', '-D'], exec: ['yarn'] };
|
|
81
|
+
if (existsSync(path.join(base, 'bun.lockb')) || existsSync(path.join(base, 'bun.lock'))) return { name: 'bun', add: ['bun', 'add', '-d'], exec: ['bunx'] };
|
|
82
|
+
}
|
|
83
|
+
return { name: 'npm', add: ['npm', 'install', '-D'], exec: ['npx'] };
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/** Read-only probe: run a version or list command with no shell. Never installs. */
|
|
87
|
+
export function defaultRun(command, args) {
|
|
88
|
+
try { return { ok: true, stdout: execFileSync(command, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 10000 }) }; }
|
|
89
|
+
catch { return { ok: false, stdout: '' }; }
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
const firstVersion = text => /\d+(?:\.\d+)+/.exec(text)?.[0] ?? null;
|
|
93
|
+
|
|
94
|
+
function playwrightBrowsers(env, home) {
|
|
95
|
+
const roots = env.PLAYWRIGHT_BROWSERS_PATH ? [env.PLAYWRIGHT_BROWSERS_PATH]
|
|
96
|
+
: [path.join(home, 'Library/Caches/ms-playwright'), path.join(home, '.cache/ms-playwright')];
|
|
97
|
+
return roots.some(dir => listDir(dir).some(name => name.startsWith('chromium')));
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
function probe(id, { dir, root, run, env, home }) {
|
|
101
|
+
const manifest = json(read(path.join(dir, 'package.json')));
|
|
102
|
+
const deps = { ...manifest?.dependencies, ...manifest?.devDependencies };
|
|
103
|
+
switch (id) {
|
|
104
|
+
case 'playwright': {
|
|
105
|
+
if (deps.cypress) return { status: 'present', version: String(deps.cypress), via: 'Cypress (already in the project)' };
|
|
106
|
+
const names = ['@playwright/test', 'playwright'];
|
|
107
|
+
const installed = names.flatMap(name => [dir, root].map(base => json(read(path.join(base, 'node_modules', name, 'package.json'))))).find(Boolean);
|
|
108
|
+
const declared = names.map(name => deps[name]).find(Boolean);
|
|
109
|
+
if (!declared && !installed) return { status: 'missing' };
|
|
110
|
+
if (!playwrightBrowsers(env, home)) return { status: 'missing', version: installed?.version ?? null, note: 'browser not downloaded' };
|
|
111
|
+
return { status: 'present', version: installed?.version ?? String(declared) };
|
|
112
|
+
}
|
|
113
|
+
case 'xcode': { const out = run('xcodebuild', ['-version']); return out.ok ? { status: 'present', version: firstVersion(out.stdout) } : { status: 'missing' }; }
|
|
114
|
+
case 'ios-simulator': {
|
|
115
|
+
const out = run('xcrun', ['simctl', 'list', 'runtimes']);
|
|
116
|
+
const line = out.ok ? out.stdout.split('\n').find(row => /^iOS \d/.test(row.trim())) : null;
|
|
117
|
+
return line ? { status: 'present', version: firstVersion(line) } : { status: 'missing' };
|
|
118
|
+
}
|
|
119
|
+
case 'android-sdk': { const out = run('adb', ['version']); return out.ok ? { status: 'present', version: firstVersion(out.stdout) } : { status: 'missing' }; }
|
|
120
|
+
case 'android-emulator': {
|
|
121
|
+
const out = run('emulator', ['-list-avds']);
|
|
122
|
+
return out.ok && out.stdout.trim() ? { status: 'present', version: null, note: out.stdout.trim().split('\n')[0] } : { status: 'missing' };
|
|
123
|
+
}
|
|
124
|
+
case 'flutter': { const out = run('flutter', ['--version']); return out.ok ? { status: 'present', version: firstVersion(out.stdout) } : { status: 'missing' }; }
|
|
125
|
+
case 'react-native-cli': case 'expo-cli': {
|
|
126
|
+
const name = catalog.tools[id].package;
|
|
127
|
+
return deps[name] ? { status: 'present', version: String(deps[name]) } : { status: 'missing' };
|
|
128
|
+
}
|
|
129
|
+
case 'curl': { const out = run('curl', ['--version']); return out.ok ? { status: 'present', version: firstVersion(out.stdout) } : { status: 'missing' }; }
|
|
130
|
+
case 'test-runner': {
|
|
131
|
+
const declared = manifest?.scripts?.test ? `${packageManager(dir, root).name} test`
|
|
132
|
+
: existsSync(path.join(dir, 'Cargo.toml')) ? 'cargo test'
|
|
133
|
+
: existsSync(path.join(dir, 'go.mod')) ? 'go test ./...'
|
|
134
|
+
: ['pyproject.toml', 'requirements.txt', 'setup.py'].some(file => existsSync(path.join(dir, file))) ? 'python3 -m pytest' : null;
|
|
135
|
+
return declared ? { status: 'present', version: null, note: `${declared} (declared, unrun)` } : { status: 'missing', note: 'no test command declared' };
|
|
136
|
+
}
|
|
137
|
+
default: return { status: 'not-needed' };
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
function toolsFor(categories, dir) {
|
|
142
|
+
const ids = new Set();
|
|
143
|
+
for (const category of categories) {
|
|
144
|
+
for (const id of catalog.categories[category].tools) ids.add(id);
|
|
145
|
+
if (catalog.categories[category].mobile) {
|
|
146
|
+
const ios = isDir(path.join(dir, 'ios')); const android = isDir(path.join(dir, 'android'));
|
|
147
|
+
if (ios || !android) for (const id of catalog.categories.ios.tools) ids.add(id);
|
|
148
|
+
if (android || !ios) for (const id of catalog.categories.android.tools) ids.add(id);
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
return [...ids];
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
function startCommand(dir, root, categories) {
|
|
155
|
+
const scripts = json(read(path.join(dir, 'package.json')))?.scripts ?? {};
|
|
156
|
+
const pm = packageManager(dir, root).name;
|
|
157
|
+
const script = ['dev', 'start', 'ios', 'android'].find(name => scripts[name]);
|
|
158
|
+
if (script) return `${pm} run ${script} (package.json, unrun)`;
|
|
159
|
+
if (categories.includes('android')) return './gradlew installDebug (unrun)';
|
|
160
|
+
if (categories.includes('ios')) return 'xcodebuild build (scheme not established)';
|
|
161
|
+
if (categories.includes('flutter')) return 'flutter run (unrun)';
|
|
162
|
+
return 'not established';
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
/** 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 => {
|
|
168
|
+
const dir = path.join(root, entry.path);
|
|
169
|
+
const tools = toolsFor(entry.categories, dir).map(id => {
|
|
170
|
+
const spec = catalog.tools[id];
|
|
171
|
+
let result = probe(id, { dir, root, run, env, home });
|
|
172
|
+
if (result.status === 'missing' && spec.hostAlternative && hostTools.includes(spec.hostAlternative)) {
|
|
173
|
+
result = { status: 'present', version: null, via: `the host's built-in ${spec.hostAlternative}` };
|
|
174
|
+
}
|
|
175
|
+
const pm = packageManager(dir, root);
|
|
176
|
+
const install = result.status !== 'missing' ? null : spec.scope === 'project' && id === 'playwright'
|
|
177
|
+
? { scope: 'project', commands: [[...pm.add, '@playwright/test'], [...pm.exec, 'playwright', 'install', 'chromium']], size: spec.size, sudo: false }
|
|
178
|
+
: spec.scope === 'project' && spec.package ? { scope: 'project', commands: [[...pm.add, spec.package]], size: spec.size, sudo: false }
|
|
179
|
+
: spec.scope === 'project' ? { scope: 'user', steps: ['Declare a test command for this package'], size: spec.size, sudo: false }
|
|
180
|
+
: { scope: 'user', steps: spec.steps, size: spec.size, sudo: spec.sudo };
|
|
181
|
+
return { id, label: spec.label, ...result, ...(install ? { install } : {}),
|
|
182
|
+
evidence: spec.evidence ? spec.evidence.replace('{exec}', pm.exec.join(' ')) : null };
|
|
183
|
+
});
|
|
184
|
+
return { path: entry.path, categories: entry.categories, start: startCommand(dir, root, entry.categories), tools };
|
|
185
|
+
});
|
|
186
|
+
return { schemaVersion: 1, packages };
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
const statusText = tool => tool.status === 'present' ? `present${tool.version ? ` ${tool.version}` : ''}${tool.via ? ` (${tool.via})` : ''}`
|
|
190
|
+
: tool.status === 'skipped' ? 'skipped' : `missing${tool.note ? ` (${tool.note})` : ''}`;
|
|
191
|
+
|
|
192
|
+
/** One table and at most one question, decision first. */
|
|
193
|
+
export function renderPlan(plan, changes = null) {
|
|
194
|
+
const lines = ['Review loop plan', '', '| Package | Kind | Tool | Status | To install |', '|---|---|---|---|---|'];
|
|
195
|
+
for (const entry of plan.packages) for (const tool of entry.tools) {
|
|
196
|
+
const install = tool.install?.commands ? `\`${tool.install.commands.map(command => command.join(' ')).join(' && ')}\` (${tool.install.size})`
|
|
197
|
+
: tool.install ? `you: ${tool.install.steps.join('; ')} (${tool.install.size}${tool.install.sudo ? ', needs sudo' : ''})` : '';
|
|
198
|
+
lines.push(`| ${entry.path} | ${entry.categories.map(category => catalog.categories[category].label).join(', ')} | ${tool.label} | ${statusText(tool)} | ${install} |`);
|
|
199
|
+
}
|
|
200
|
+
if (changes) lines.push('', `Changed since the recorded Review loop: ${changes.join('; ')}.`);
|
|
201
|
+
const local = missingProjectTools(plan);
|
|
202
|
+
if (local.length) lines.push('', `Install the missing project-local tools (${local.map(item => `${item.tool.label} in ${item.path}`).join(', ')}), skip them, or choose per tool?`);
|
|
203
|
+
if (plan.packages.some(entry => entry.tools.some(tool => tool.install?.scope === 'user'))) lines.push('', 'The tools marked "you" need your own install; Joycraft will not run them.');
|
|
204
|
+
return lines.join('\n');
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
export function missingProjectTools(plan) {
|
|
208
|
+
return plan.packages.flatMap(entry => entry.tools.filter(tool => tool.install?.scope === 'project').map(tool => ({ path: entry.path, tool })));
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
/** Run project-local installs the user approved. System tools are never installed here. */
|
|
212
|
+
export function installProjectTools(root, plan, { approved, tools = null, run = (command, args, cwd) => execFileSync(command, args, { cwd, stdio: 'inherit' }) }) {
|
|
213
|
+
if (approved !== true) throw new Error('Install needs the user\'s yes in this conversation');
|
|
214
|
+
const ran = [];
|
|
215
|
+
for (const { path: dir, tool } of missingProjectTools(plan)) {
|
|
216
|
+
if (tools && !tools.includes(tool.id)) continue;
|
|
217
|
+
for (const [command, ...args] of tool.install.commands) { run(command, args, path.join(root, dir)); ran.push([command, ...args].join(' ')); }
|
|
218
|
+
}
|
|
219
|
+
return ran;
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
function recorded(root) {
|
|
223
|
+
const text = read(path.join(root, 'AGENTS.md'));
|
|
224
|
+
const match = text && marker.exec(text);
|
|
225
|
+
return match ? json(match[1]) : null;
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
const summary = (plan, skipped = []) => Object.fromEntries(plan.packages.map(entry => [entry.path, {
|
|
229
|
+
categories: entry.categories,
|
|
230
|
+
tools: Object.fromEntries(entry.tools.map(tool => [tool.id, skipped.includes(tool.id) && tool.status === 'missing' ? 'skipped' : tool.status])),
|
|
231
|
+
}]));
|
|
232
|
+
|
|
233
|
+
/** Differences between this detection and the recorded Review loop; null when nothing is recorded. */
|
|
234
|
+
export function reviewLoopChanges(root, plan) {
|
|
235
|
+
const before = recorded(root);
|
|
236
|
+
if (!before) return null;
|
|
237
|
+
const now = summary(plan);
|
|
238
|
+
const changes = [];
|
|
239
|
+
for (const [pkg, entry] of Object.entries(now)) {
|
|
240
|
+
const old = before.packages?.[pkg];
|
|
241
|
+
if (!old) { changes.push(`new ${entry.categories.join(', ')} package ${pkg}`); continue; }
|
|
242
|
+
for (const category of entry.categories) if (!old.categories.includes(category)) changes.push(`${pkg} is now also ${category}`);
|
|
243
|
+
for (const [id, status] of Object.entries(entry.tools)) {
|
|
244
|
+
const was = old.tools[id];
|
|
245
|
+
if (was === undefined) changes.push(`${pkg} needs ${catalog.tools[id].label}`);
|
|
246
|
+
else if (was !== status && !(was === 'skipped' && status === 'missing')) changes.push(`${catalog.tools[id].label} in ${pkg}: ${was} -> ${status}`);
|
|
247
|
+
}
|
|
248
|
+
}
|
|
249
|
+
for (const pkg of Object.keys(before.packages ?? {})) if (!now[pkg]) changes.push(`package ${pkg} is gone`);
|
|
250
|
+
return changes;
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
/** Plan only what changed: an unchanged recorded loop asks nothing. */
|
|
254
|
+
export function planForSetup(root, options) {
|
|
255
|
+
const plan = reviewLoopPlan(root, options);
|
|
256
|
+
const changes = reviewLoopChanges(root, plan);
|
|
257
|
+
return { plan, changes, ask: changes === null || changes.length > 0, text: changes && !changes.length ? 'Review loop unchanged.' : renderPlan(plan, changes) };
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
/** Write the chosen setup to AGENTS.md under `## Review loop`, replacing only that section. */
|
|
261
|
+
export function recordReviewLoop(root, plan, { skipped = [] } = {}) {
|
|
262
|
+
const rows = ['| Package | Tool | Start the app | Take the evidence |', '|---|---|---|---|'];
|
|
263
|
+
const unverified = [];
|
|
264
|
+
for (const entry of plan.packages) {
|
|
265
|
+
for (const tool of entry.tools) {
|
|
266
|
+
const skip = skipped.includes(tool.id) && tool.status === 'missing';
|
|
267
|
+
if ((skip || tool.status === 'missing') && entry.categories.some(category => catalog.categories[category].ui)) unverified.push(entry.path);
|
|
268
|
+
rows.push(`| ${entry.path} | ${tool.label}: ${skip ? 'skipped' : statusText(tool)} | ${entry.start} | ${tool.evidence ?? (tool.note ?? 'not applicable')} |`);
|
|
269
|
+
}
|
|
270
|
+
}
|
|
271
|
+
const section = [sectionHeading, '',
|
|
272
|
+
'Recorded by Joycraft setup. The implementer, reviewer and UI checks use these tools and commands.', '',
|
|
273
|
+
...rows,
|
|
274
|
+
...([...new Set(unverified)].length ? ['', `UI claims in ${[...new Set(unverified)].join(', ')} stay UNVERIFIED in review reports until the missing tools are set up.`] : []),
|
|
275
|
+
'', `<!-- joycraft:review-loop v1 ${JSON.stringify({ packages: summary(plan, skipped) })} -->`, ''].join('\n');
|
|
276
|
+
const file = path.join(root, 'AGENTS.md');
|
|
277
|
+
const text = read(file);
|
|
278
|
+
if (text === null) { writeFileSync(file, `${section}`); return { created: true }; }
|
|
279
|
+
const start = text.indexOf(`\n${sectionHeading}\n`);
|
|
280
|
+
if (start < 0 && !text.startsWith(`${sectionHeading}\n`)) {
|
|
281
|
+
writeFileSync(file, `${text}${text.endsWith('\n') ? '' : '\n'}\n${section}`);
|
|
282
|
+
return { created: false };
|
|
283
|
+
}
|
|
284
|
+
const from = text.startsWith(`${sectionHeading}\n`) ? 0 : start + 1;
|
|
285
|
+
const next = text.slice(from + sectionHeading.length).search(/\n## /);
|
|
286
|
+
const end = next < 0 ? text.length : from + sectionHeading.length + next + 1;
|
|
287
|
+
writeFileSync(file, `${text.slice(0, from)}${section}${end < text.length ? `\n${text.slice(end)}` : ''}`);
|
|
288
|
+
return { created: false };
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
/** The recorded section text, for worker and reviewer packets. */
|
|
292
|
+
export function reviewLoopSection(root) {
|
|
293
|
+
const text = read(path.join(root, 'AGENTS.md'));
|
|
294
|
+
if (!text) return null;
|
|
295
|
+
const start = text.startsWith(`${sectionHeading}\n`) ? 0 : text.indexOf(`\n${sectionHeading}\n`) + 1;
|
|
296
|
+
if (start === 0 && !text.startsWith(`${sectionHeading}\n`)) return null;
|
|
297
|
+
const next = text.slice(start + sectionHeading.length).search(/\n## /);
|
|
298
|
+
return text.slice(start, next < 0 ? undefined : start + sectionHeading.length + next).trim();
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
export async function main(argv = process.argv.slice(2)) {
|
|
302
|
+
const [command, ...rest] = argv;
|
|
303
|
+
const flags = {};
|
|
304
|
+
for (let index = 0; index < rest.length; index += 1) {
|
|
305
|
+
if (rest[index] === '--yes') { flags['--yes'] = true; continue; }
|
|
306
|
+
flags[rest[index]] = rest[index + 1]; index += 1;
|
|
307
|
+
}
|
|
308
|
+
const root = path.resolve(flags['--root'] ?? '.');
|
|
309
|
+
const list = value => (value ? value.split(',').filter(Boolean) : []);
|
|
310
|
+
const options = { hostTools: list(flags['--host-tools']) };
|
|
311
|
+
if (command === 'plan') {
|
|
312
|
+
const { text, ask } = planForSetup(root, options);
|
|
313
|
+
process.stdout.write(`${text}\n`);
|
|
314
|
+
return { ask };
|
|
315
|
+
}
|
|
316
|
+
if (command === 'install') {
|
|
317
|
+
const ran = installProjectTools(root, reviewLoopPlan(root, options), { approved: flags['--yes'] === true, tools: flags['--tools'] ? list(flags['--tools']) : null });
|
|
318
|
+
process.stdout.write(`${JSON.stringify({ ran }, null, 2)}\n`);
|
|
319
|
+
return ran;
|
|
320
|
+
}
|
|
321
|
+
if (command === 'record') {
|
|
322
|
+
const result = recordReviewLoop(root, reviewLoopPlan(root, options), { skipped: list(flags['--skip']) });
|
|
323
|
+
process.stdout.write(`${JSON.stringify(result)}\n`);
|
|
324
|
+
return result;
|
|
325
|
+
}
|
|
326
|
+
throw new Error('Usage: review-tools.mjs plan|install|record --root <project> [--host-tools browser,simulator] [--tools playwright --yes] [--skip playwright]');
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
|
|
330
|
+
main().catch(error => { process.stderr.write(`Review tools stopped: ${error.message}\n`); process.exitCode = 1; });
|
|
331
|
+
}
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
import { execFileSync } from 'node:child_process';
|
|
2
|
+
import { existsSync } from 'node:fs';
|
|
3
|
+
import path from 'node:path';
|
|
4
|
+
|
|
5
|
+
const fullCommit = value => typeof value === 'string' && /^[a-f0-9]{40}$/.test(value);
|
|
6
|
+
|
|
7
|
+
function required(condition, message) {
|
|
8
|
+
if (!condition) throw new Error(message);
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
function git(root, args) {
|
|
12
|
+
try {
|
|
13
|
+
return execFileSync('git', args, { cwd: root, encoding: 'buffer', stdio: ['ignore', 'pipe', 'pipe'] });
|
|
14
|
+
} catch (error) {
|
|
15
|
+
const detail = error.stderr?.toString('utf8').trim();
|
|
16
|
+
throw new Error(`Git scope check failed${detail ? `: ${detail}` : ''}`);
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
function nulFields(bytes) {
|
|
21
|
+
const values = bytes.toString('utf8').split('\0');
|
|
22
|
+
values.pop();
|
|
23
|
+
return values;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** Parse Git's NUL-delimited --name-status format without losing unusual names. */
|
|
27
|
+
function nameStatus(bytes, stage) {
|
|
28
|
+
const values = nulFields(bytes);
|
|
29
|
+
const result = [];
|
|
30
|
+
for (let index = 0; index < values.length;) {
|
|
31
|
+
const raw = values[index++];
|
|
32
|
+
required(raw, 'Git emitted an empty name-status record');
|
|
33
|
+
const status = raw[0];
|
|
34
|
+
required('ACDMRTUXB'.includes(status), `Unsupported Git change status: ${raw}`);
|
|
35
|
+
if (status === 'R' || status === 'C') {
|
|
36
|
+
const beforePath = values[index++];
|
|
37
|
+
const path = values[index++];
|
|
38
|
+
required(beforePath !== undefined && path !== undefined, `Incomplete Git ${status} record`);
|
|
39
|
+
result.push({ path, beforePath, status, stage });
|
|
40
|
+
} else {
|
|
41
|
+
const path = values[index++];
|
|
42
|
+
required(path !== undefined, `Incomplete Git ${status} record`);
|
|
43
|
+
result.push({ path, status, stage });
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
return result;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
function trackedChanges(root, baseRevision) {
|
|
50
|
+
// The first view establishes actual base-to-worktree changes. The other two
|
|
51
|
+
// retain index/worktree state for review without parsing line-delimited Git.
|
|
52
|
+
const actual = nameStatus(git(root, ['diff', '--name-status', '-z', '--find-renames', baseRevision, '--']), 'actual');
|
|
53
|
+
// Index/worktree state is relative to HEAD, not the captured base. Comparing
|
|
54
|
+
// --cached to the base would mislabel ordinary committed base-to-HEAD work as
|
|
55
|
+
// staged when the review starts from an older explicit implementation base.
|
|
56
|
+
const staged = nameStatus(git(root, ['diff', '--cached', '--name-status', '-z', '--find-renames', 'HEAD', '--']), 'staged');
|
|
57
|
+
const unstaged = nameStatus(git(root, ['diff', '--name-status', '-z', '--find-renames', '--']), 'unstaged');
|
|
58
|
+
const markers = new Map();
|
|
59
|
+
for (const record of [...staged, ...unstaged]) {
|
|
60
|
+
for (const name of [record.path, record.beforePath].filter(Boolean)) {
|
|
61
|
+
const current = markers.get(name) ?? new Set();
|
|
62
|
+
current.add(record.stage);
|
|
63
|
+
markers.set(name, current);
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
return actual.map(record => {
|
|
67
|
+
const stages = [...new Set([...(markers.get(record.path) ?? []), ...(markers.get(record.beforePath) ?? [])])].sort();
|
|
68
|
+
return { ...record, stages: stages.length === 0 ? ['committed'] : stages };
|
|
69
|
+
});
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
function untrackedChanges(root) {
|
|
73
|
+
return nulFields(git(root, ['ls-files', '--others', '--exclude-standard', '-z'])).map(path => ({ path, status: 'U', stages: ['untracked'] }));
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
export function validateChangeScope(value, relativePath) {
|
|
77
|
+
required(value !== null && typeof value === 'object' && !Array.isArray(value), 'verification.changeScope must be an object');
|
|
78
|
+
required(Object.keys(value).every(key => key === 'baseRevision' || key === 'exclusions'), 'verification.changeScope has an unknown field');
|
|
79
|
+
required(fullCommit(value.baseRevision), 'verification.changeScope.baseRevision must be an explicit full 40-character Git commit SHA; origin/main and inferred bases are not accepted');
|
|
80
|
+
const exclusions = value.exclusions ?? [];
|
|
81
|
+
required(Array.isArray(exclusions), 'verification.changeScope.exclusions must be an array when supplied');
|
|
82
|
+
const names = new Set();
|
|
83
|
+
for (const [index, entry] of exclusions.entries()) {
|
|
84
|
+
required(entry !== null && typeof entry === 'object' && !Array.isArray(entry), `verification.changeScope.exclusions[${index}] must be an object`);
|
|
85
|
+
required(Object.keys(entry).every(key => key === 'path' || key === 'reason'), `verification.changeScope.exclusions[${index}] has an unknown field`);
|
|
86
|
+
const file = relativePath(entry.path);
|
|
87
|
+
required(!names.has(file), `verification.changeScope has duplicate exclusion: ${file}`);
|
|
88
|
+
names.add(file);
|
|
89
|
+
required(typeof entry.reason === 'string' && entry.reason.trim().length > 0, `verification.changeScope.exclusions[${index}].reason must be nonempty`);
|
|
90
|
+
}
|
|
91
|
+
return { baseRevision: value.baseRevision, ...(exclusions.length === 0 ? {} : { exclusions: exclusions.map(entry => ({ path: relativePath(entry.path), reason: entry.reason })) }) };
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
export function captureChangeScope({ root = process.cwd(), changeScope, relativePath, inputs, artifactPaths = [], topologyIgnoredPaths = [] }) {
|
|
95
|
+
const declared = validateChangeScope(changeScope, relativePath);
|
|
96
|
+
try { required(git(root, ['cat-file', '-e', `${declared.baseRevision}^{commit}`]).length === 0, ''); } catch { throw new Error(`verification.changeScope.baseRevision is not an available commit: ${declared.baseRevision}`); }
|
|
97
|
+
const actual = [...trackedChanges(root, declared.baseRevision), ...untrackedChanges(root)];
|
|
98
|
+
const inputsByPath = new Map(inputs.map(input => [relativePath(input.path), input.state ?? 'present']));
|
|
99
|
+
const exclusions = new Set([...(declared.exclusions ?? []).map(entry => entry.path), ...artifactPaths.map(relativePath)]);
|
|
100
|
+
const ignored = new Set(topologyIgnoredPaths.map(relativePath));
|
|
101
|
+
const relevant = [];
|
|
102
|
+
for (const item of actual) {
|
|
103
|
+
const targetState = inputsByPath.get(item.path);
|
|
104
|
+
const previousState = item.beforePath === undefined ? undefined : inputsByPath.get(item.beforePath);
|
|
105
|
+
const relevantInput = targetState !== undefined || previousState !== undefined;
|
|
106
|
+
if (relevantInput) {
|
|
107
|
+
// Queue/spec status and completion metadata have their own normalized
|
|
108
|
+
// input binding. Excluding their Git topology avoids staling a report
|
|
109
|
+
// merely because complete() writes those two status surfaces.
|
|
110
|
+
if (ignored.has(item.path) || (item.beforePath !== undefined && ignored.has(item.beforePath))) continue;
|
|
111
|
+
if (item.status === 'D') {
|
|
112
|
+
required(targetState === 'absent', `Relevant verification input was deleted: ${item.path}; declare it with state: absent or take a fresh review`);
|
|
113
|
+
relevant.push({ path: item.path, status: item.status, stages: item.stages, state: 'deleted' });
|
|
114
|
+
} else if (item.beforePath !== undefined) {
|
|
115
|
+
required(targetState === 'present' && previousState === 'absent' && existsSync(path.join(root, item.path)), `Relevant verification input was renamed from ${item.beforePath} to ${item.path}; bind the new path and declare the old non-requirement input state: absent`);
|
|
116
|
+
relevant.push({ path: item.path, beforePath: item.beforePath, status: item.status, stages: item.stages, state: 'present' });
|
|
117
|
+
} else {
|
|
118
|
+
required(targetState === 'present' && existsSync(path.join(root, item.path)), `Relevant verification input is absent: ${item.path}; only an explicitly absent non-requirement input may be deleted`);
|
|
119
|
+
relevant.push({ path: item.path, status: item.status, stages: item.stages, state: 'present' });
|
|
120
|
+
}
|
|
121
|
+
} else {
|
|
122
|
+
required(exclusions.has(item.path), `Changed path is outside verification inputs: ${item.path}; add it to verification.changeScope.exclusions with a reason or include it as a verification input`);
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
return { baseRevision: declared.baseRevision, paths: relevant };
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/** Dispatcher-facing name: validates and captures the current Git topology. */
|
|
129
|
+
export const checkScope = captureChangeScope;
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Daily check for a newer Joycraft. Prints nothing unless there is something to say,
|
|
3
|
+
// and never fails a session. The request is the package metadata only.
|
|
4
|
+
import { lstatSync, mkdirSync, openSync, closeSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
|
|
5
|
+
import { join, resolve } from 'node:path';
|
|
6
|
+
import { pathToFileURL } from 'node:url';
|
|
7
|
+
|
|
8
|
+
const registry = 'https://registry.npmjs.org/joycraft/latest';
|
|
9
|
+
const day = 24 * 60 * 60 * 1000;
|
|
10
|
+
const retryAfter = 60 * 60 * 1000;
|
|
11
|
+
const snoozeFor = 7 * day;
|
|
12
|
+
const lockFor = 10_000;
|
|
13
|
+
const deadline = 2_000;
|
|
14
|
+
const stable = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
|
|
15
|
+
const policies = ['notify', 'auto-safe', 'off'];
|
|
16
|
+
|
|
17
|
+
const readJson = path => {
|
|
18
|
+
try {
|
|
19
|
+
const value = JSON.parse(readFileSync(path, 'utf8'));
|
|
20
|
+
return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
|
|
21
|
+
} catch { return {}; }
|
|
22
|
+
};
|
|
23
|
+
|
|
24
|
+
/** Return the path of a file in .joycraft/local, or null when a parent is a link. */
|
|
25
|
+
function localPath(root, name) {
|
|
26
|
+
let current = resolve(root);
|
|
27
|
+
for (const part of ['.joycraft', 'local']) {
|
|
28
|
+
current = join(current, part);
|
|
29
|
+
try { if (!lstatSync(current).isDirectory()) return null; }
|
|
30
|
+
catch (error) {
|
|
31
|
+
if (error.code !== 'ENOENT') return null;
|
|
32
|
+
mkdirSync(current);
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
return join(current, name);
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
function writeLocal(root, name, value) {
|
|
39
|
+
const path = localPath(root, name);
|
|
40
|
+
if (!path) return false;
|
|
41
|
+
const temporary = `${path}.${process.pid}`;
|
|
42
|
+
writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`);
|
|
43
|
+
renameSync(temporary, path);
|
|
44
|
+
return true;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
export function isNewer(candidate, installed) {
|
|
48
|
+
const a = candidate.match(stable), b = installed.match(stable);
|
|
49
|
+
if (!a || !b) return false;
|
|
50
|
+
for (let i = 1; i <= 3; i += 1) if (BigInt(a[i]) !== BigInt(b[i])) return BigInt(a[i]) > BigInt(b[i]);
|
|
51
|
+
return false;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
const updateKind = (latest, installed) => latest.split('.')[0] === installed.split('.')[0] ? 'patch' : 'migration';
|
|
55
|
+
const oneLine = value => typeof value === 'string' ? value.replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 300) : '';
|
|
56
|
+
|
|
57
|
+
function holdLock(root) {
|
|
58
|
+
const path = localPath(root, 'update-check.lock');
|
|
59
|
+
if (!path) return null;
|
|
60
|
+
try { if (Date.now() - statSync(path).mtimeMs > lockFor) unlinkSync(path); } catch { /* no lock yet */ }
|
|
61
|
+
try { closeSync(openSync(path, 'wx')); return () => { try { unlinkSync(path); } catch { /* already gone */ } }; }
|
|
62
|
+
catch { return null; }
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** One network read per day; concurrent sessions and failures fall back to the cache. */
|
|
66
|
+
async function latestRelease(root, { fetcher, now }) {
|
|
67
|
+
const cachePath = localPath(root, 'update-check.json');
|
|
68
|
+
if (!cachePath) return null;
|
|
69
|
+
const cache = readJson(cachePath);
|
|
70
|
+
if (typeof cache.fetchedAt === 'number' && now - cache.fetchedAt < day) return cache;
|
|
71
|
+
if (typeof cache.failedAt === 'number' && now - cache.failedAt < retryAfter) return cache;
|
|
72
|
+
const release = holdLock(root);
|
|
73
|
+
if (!release) return cache;
|
|
74
|
+
try {
|
|
75
|
+
const response = await fetcher(registry, { signal: AbortSignal.timeout(deadline), headers: { accept: 'application/json' } });
|
|
76
|
+
if (!response.ok) throw new Error(`registry ${response.status}`);
|
|
77
|
+
const metadata = await response.json();
|
|
78
|
+
if (typeof metadata?.version !== 'string' || !stable.test(metadata.version)) throw new Error('not a stable release');
|
|
79
|
+
const notes = metadata.joycraft?.release === metadata.version ? metadata.joycraft : {};
|
|
80
|
+
const fresh = { fetchedAt: now, version: metadata.version, summary: oneLine(notes.summary), autoSafeEligible: notes.autoSafeEligible === true };
|
|
81
|
+
writeLocal(root, 'update-check.json', fresh);
|
|
82
|
+
return fresh;
|
|
83
|
+
} catch {
|
|
84
|
+
writeLocal(root, 'update-check.json', { ...cache, failedAt: now });
|
|
85
|
+
return cache;
|
|
86
|
+
} finally { release(); }
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
export async function check(root, { fetcher = fetch, now = Date.now() } = {}) {
|
|
90
|
+
const installed = readJson(join(root, '.joycraft/installation.json')).joycraft;
|
|
91
|
+
if (typeof installed !== 'string' || !stable.test(installed)) return null;
|
|
92
|
+
const { update = {} } = readJson(join(root, '.joycraft/local/preferences.json'));
|
|
93
|
+
const policy = policies.includes(update.policy) ? update.policy : 'notify';
|
|
94
|
+
if (policy === 'off') return null;
|
|
95
|
+
const cache = await latestRelease(root, { fetcher, now });
|
|
96
|
+
const latest = cache?.version;
|
|
97
|
+
if (typeof latest !== 'string' || !isNewer(latest, installed)) return null;
|
|
98
|
+
if (update.snoozed?.version === latest && now < update.snoozed.until) return null;
|
|
99
|
+
const kind = updateKind(latest, installed);
|
|
100
|
+
const summary = cache.summary || 'See the changelog for what changed.';
|
|
101
|
+
if (update.pin === true) return { action: 'note', installed, latest, kind, message: `Joycraft ${latest} is available. This project stays on ${installed} by choice.` };
|
|
102
|
+
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}). ${summary}` };
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
function savePreference(root, change) {
|
|
107
|
+
const path = localPath(root, 'preferences.json');
|
|
108
|
+
if (!path) throw new Error('.joycraft/local is not a plain directory');
|
|
109
|
+
const preferences = readJson(path);
|
|
110
|
+
return writeLocal(root, 'preferences.json', { ...preferences, update: change(preferences.update ?? {}) });
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
export const snooze = (root, version, now = Date.now()) => {
|
|
114
|
+
if (!stable.test(version ?? '')) throw new Error('Snooze needs a version');
|
|
115
|
+
return savePreference(root, update => ({ ...update, snoozed: { version, until: now + snoozeFor } }));
|
|
116
|
+
};
|
|
117
|
+
|
|
118
|
+
export const setPolicy = (root, policy) => {
|
|
119
|
+
if (!policies.includes(policy)) throw new Error(`Policy must be one of: ${policies.join(', ')}`);
|
|
120
|
+
return savePreference(root, update => ({ ...update, policy }));
|
|
121
|
+
};
|
|
122
|
+
|
|
123
|
+
export const setPin = (root, pin) => savePreference(root, update => ({ ...update, pin }));
|
|
124
|
+
|
|
125
|
+
export async function main(argv, root = process.cwd(), options) {
|
|
126
|
+
const [command = 'check', value] = argv;
|
|
127
|
+
if (command === 'check') {
|
|
128
|
+
let result = null;
|
|
129
|
+
try { result = await check(root, options); } catch { /* a version check never stops a session */ }
|
|
130
|
+
if (result) console.log(JSON.stringify(result, null, 2));
|
|
131
|
+
return result;
|
|
132
|
+
}
|
|
133
|
+
if (command === 'snooze') return snooze(root, value);
|
|
134
|
+
if (command === 'policy') return setPolicy(root, value);
|
|
135
|
+
if (command === 'pin') return setPin(root, true);
|
|
136
|
+
if (command === 'unpin') return setPin(root, false);
|
|
137
|
+
throw new Error('Use check, snooze <version>, policy notify|auto-safe|off, pin or unpin');
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
|
|
141
|
+
main(process.argv.slice(2)).catch(error => { console.error(`Update check stopped: ${error.message}`); process.exitCode = 1; });
|
|
142
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
# Queue template location
|
|
2
|
+
|
|
3
|
+
Copy `queue.json` to
|
|
4
|
+
`docs/features/<slug>/specs/.joycraft-spec-queue.json`. Spec filenames in its
|
|
5
|
+
`file` fields remain relative to that `specs/` directory; verification paths are
|
|
6
|
+
project-relative. Replace the example feature and paths with the current brief
|
|
7
|
+
and spec locations before dispatch.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schemaVersion": 1,
|
|
3
|
+
"artifactId": "example-feature-review",
|
|
4
|
+
"title": "Example feature review",
|
|
5
|
+
"summary": "Choose the collection presentation after comparing the current and proposed views.",
|
|
6
|
+
"decisionIds": ["presentation"],
|
|
7
|
+
"comparisons": [
|
|
8
|
+
{
|
|
9
|
+
"title": "Collection presentation",
|
|
10
|
+
"decisionId": "presentation",
|
|
11
|
+
"images": [
|
|
12
|
+
{
|
|
13
|
+
"path": "docs/features/example-feature/screens/rows.png",
|
|
14
|
+
"label": "Compact rows",
|
|
15
|
+
"alt": "Example collection rendered as compact rows",
|
|
16
|
+
"caption": "Best when scan speed matters."
|
|
17
|
+
},
|
|
18
|
+
{
|
|
19
|
+
"path": "docs/features/example-feature/screens/cards.png",
|
|
20
|
+
"label": "Visual cards",
|
|
21
|
+
"alt": "Example collection rendered as visual cards",
|
|
22
|
+
"caption": "Best when imagery carries the choice."
|
|
23
|
+
}
|
|
24
|
+
]
|
|
25
|
+
}
|
|
26
|
+
],
|
|
27
|
+
"reviews": [
|
|
28
|
+
{
|
|
29
|
+
"path": "docs/features/example-feature/specs/review-1.report.json",
|
|
30
|
+
"title": "Recorded implementation review"
|
|
31
|
+
}
|
|
32
|
+
]
|
|
33
|
+
}
|