joycraft 1.1.1 → 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 +95 -8
- package/payload/.joycraft/runtime/config.mjs +5 -3
- package/payload/.joycraft/runtime/review-tools.mjs +55 -8
- package/payload/.joycraft/runtime/update-check.mjs +38 -8
- package/payload/.joycraft/runtime/wiring.mjs +156 -0
- package/payload/.joycraft/templates/joycraft.yaml +2 -0
- package/payload/.joycraft/templates/project-context.md +6 -1
- package/payload/PIN +25 -22
|
@@ -10,7 +10,7 @@ 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) {
|
|
@@ -117,7 +117,7 @@ export function parseYaml(text) {
|
|
|
117
117
|
return result;
|
|
118
118
|
}
|
|
119
119
|
|
|
120
|
-
const known = { paths: ['features', 'archive', 'context'], hooks: ['afterArchive'], cleanup: ['impact'] };
|
|
120
|
+
const known = { paths: ['features', 'archive', 'context'], hooks: ['afterArchive'], cleanup: ['impact', 'entryWords'] };
|
|
121
121
|
|
|
122
122
|
/** Read joycraft.yaml (or return defaults) and validate every known field. */
|
|
123
123
|
export function readConfig(root = process.cwd()) {
|
|
@@ -153,7 +153,9 @@ export function readConfig(root = process.cwd()) {
|
|
|
153
153
|
`${configFile}: cleanup.impact item ${index + 1} needs source (a glob) and docs (a list of files)`);
|
|
154
154
|
checkGlob(entry.source, `cleanup.impact item ${index + 1} source`);
|
|
155
155
|
}
|
|
156
|
-
|
|
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 } };
|
|
157
159
|
}
|
|
158
160
|
|
|
159
161
|
/** Project-relative work folders for a project. */
|
|
@@ -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) {
|
|
@@ -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
|
+
}
|
|
@@ -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.
|
package/payload/PIN
CHANGED
|
@@ -1,52 +1,54 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schemaVersion": 1,
|
|
3
3
|
"source": "joycraft-prototype",
|
|
4
|
-
"tag": "field-
|
|
5
|
-
"commit": "
|
|
4
|
+
"tag": "field-14",
|
|
5
|
+
"commit": "a23fc6943b2937f66e72d6feec3d686c16b7b846",
|
|
6
6
|
"files": {
|
|
7
|
-
".agents/skills/joycraft-cleanup/SKILL.md": "
|
|
8
|
-
".agents/skills/joycraft-context/SKILL.md": "
|
|
7
|
+
".agents/skills/joycraft-cleanup/SKILL.md": "99ce785e551be33412ac7a99ce44585a9b2be4440617caac273680383b4f7057",
|
|
8
|
+
".agents/skills/joycraft-context/SKILL.md": "e2f85baa47058fd61811fdb60d0cb41fb3f505f3957812d929db95bb99124f1b",
|
|
9
9
|
".agents/skills/joycraft-decompose/SKILL.md": "a24c9d9cf2dc7af4b99ad67575b64b9d0c99818044f7fafc3a5243dc4c557b5f",
|
|
10
|
-
".agents/skills/joycraft-entry/SKILL.md": "
|
|
10
|
+
".agents/skills/joycraft-entry/SKILL.md": "5b9f58369259def87b5b3c0dffa6383e93a0f4844b971d85b594f422cd5398ac",
|
|
11
11
|
".agents/skills/joycraft-implement/SKILL.md": "075832c85f6bff177eca45f5ce4412f6a6661fe9be9213674ddc2f74c2dc211e",
|
|
12
12
|
".agents/skills/joycraft-retro/SKILL.md": "156f36cb047604c734bf273bd02822d964b6af86619ed6c2a30fa6d79eb9a986",
|
|
13
13
|
".agents/skills/joycraft-retro/agents/openai.yaml": "f0eb4732261635f41e08f0bbe9a931d62fd8ac645149d3406e6fc7e16a81750b",
|
|
14
|
-
".agents/skills/joycraft-session-end/SKILL.md": "
|
|
14
|
+
".agents/skills/joycraft-session-end/SKILL.md": "55bcf6099d52abe1f7b4a0de376333f435a7154aae4690d679948f9f837702fa",
|
|
15
15
|
".agents/skills/joycraft-testing/SKILL.md": "89e983b285099c38821dc807311b27d450e6dec9fb691cd687ca74332b091157",
|
|
16
16
|
".agents/skills/joycraft-ui-slice/SKILL.md": "fcb5f109c9bd23d4afe5b47d19c90fd34485754ce9061c64bce1ae2ce0376484",
|
|
17
17
|
".agents/skills/joycraft-ui-slice/scripts/serve.mjs": "c16858800b6fbe6f7a3a21b21e785ad70c9a89a3fe970bc08701fefeac5042fa",
|
|
18
18
|
".agents/skills/joycraft-verify/SKILL.md": "f18eda5910e1ca5c312f5185b0dbceb4dc09fb9d73951e64410b5d59db046511",
|
|
19
19
|
".claude/agents/joycraft-implementer.md": "30b26779bd49d2d66758bcb26442e78755b018a3830ac52ff634ebf057ce1cc5",
|
|
20
20
|
".claude/agents/joycraft-reviewer.md": "488b1923115257dbe966bbe4717d21f95900b18cff68febd848e1f8f362a9d37",
|
|
21
|
-
".joycraft/assets/artifacts/kit.css": "
|
|
22
|
-
".joycraft/assets/artifacts/kit.js": "
|
|
23
|
-
".joycraft/assets/artifacts/transports.js": "
|
|
21
|
+
".joycraft/assets/artifacts/kit.css": "b3481214b73fa8919708075e97aae60ed42dda386c8837129ee153099adf5b43",
|
|
22
|
+
".joycraft/assets/artifacts/kit.js": "5de876e66536ad1e10ad6dc65d775c6d0a59540c81c5b48b5d4239fbdbf0569a",
|
|
23
|
+
".joycraft/assets/artifacts/transports.js": "318e97895468b47f07febc913d3a6e100b0ad19b78b3a4fc51bebc488e67c25d",
|
|
24
24
|
".joycraft/contracts/types.d.ts": "5c4e654ea929778c586bc6cce44e60dc031578b2414dd1b8161359cf9f424b41",
|
|
25
25
|
".joycraft/references/architecture.md": "52eaaa4b88053481c9f8cad2418ea0f1db880184c3a50c95901f30f24be75852",
|
|
26
26
|
".joycraft/references/archive.md": "7deca056a93b21c97d82633bcdf5acf6c77bf2c59b2430e648f665923c020794",
|
|
27
|
-
".joycraft/references/artifacts.md": "
|
|
28
|
-
".joycraft/references/cleanup.md": "
|
|
27
|
+
".joycraft/references/artifacts.md": "f9ae6d86f604eea7424b97076aad91bec0f6b69e4c4d6954f86d2b15fb531f66",
|
|
28
|
+
".joycraft/references/cleanup.md": "aa784c63442a289c67de359d82c78abca3aa8cab5b5e2d91fcd731b45c209003",
|
|
29
29
|
".joycraft/references/completion.md": "7df48664861f41e2e503a828e97d6b6f615745591a3f47f17d196fa4d24a122d",
|
|
30
|
-
".joycraft/references/context.md": "
|
|
30
|
+
".joycraft/references/context.md": "df72d3b59d55f0d9741234d4a3d7b56532f560d787c88d5d8630d954472bc430",
|
|
31
31
|
".joycraft/references/delivery.md": "1afc417ee3922ebf5e84c0ae87796d6cb6305679c0257ed38a35f396949de5e8",
|
|
32
32
|
".joycraft/references/dispatch.md": "b80d6899c52b7c003012fdfc774be271773213b7fedc37f4c247b431cdf8207d",
|
|
33
|
+
".joycraft/references/doc-cleanup-LICENSE.md": "a9e210590e2d0ebf719fe3801f1c0fda8f940af28656ff36e908c4315d94f886",
|
|
34
|
+
".joycraft/references/knowledge.md": "a08a117a5d0ae65a45dfd8ab3f3da92dd3c7aeedaa09ae1d71ddf3d6528c7f95",
|
|
33
35
|
".joycraft/references/recurring-failures.md": "7080f6c55492bc19c2897f4f0b128a830a71cdb516678c79ff6e97ffa1dc6b86",
|
|
34
36
|
".joycraft/references/retro.md": "f359eae19747777fb4687c1bc7eb280f0319ae629ee62913346e60fc56551562",
|
|
35
|
-
".joycraft/references/setup.md": "
|
|
37
|
+
".joycraft/references/setup.md": "54800d023afa6fe4153dbd0d17b3453d570e31ba416df9fde054e9aa2e333c71",
|
|
36
38
|
".joycraft/references/testing.md": "7a0be4a5424f0fac89cba6e896c66a50948e31332bb7f032f688d72a203e4f4d",
|
|
37
|
-
".joycraft/references/update.md": "
|
|
39
|
+
".joycraft/references/update.md": "95569e44fe36af52b9d72bc6b64b36745fcfc5d31b9b4d91f10e6bed40a0e987",
|
|
38
40
|
".joycraft/references/workflow.md": "ed4a6618ab3288ea213691e4485f580d8348f717b6e663d29fbb570541e42c2c",
|
|
39
41
|
".joycraft/references/worktrees.md": "fb18af0cd76d4e3c5d5b892a7ae10946f21f189e642243235c188b571635f735",
|
|
40
42
|
".joycraft/runtime/archive.mjs": "c153f5407fe6abffe5cf9655b0ff40db2254712a1bfee429dad93251bb7d0121",
|
|
41
43
|
".joycraft/runtime/artifacts/cli.mjs": "d30152e6829e07d9c7ff6ceedbfa6813931674d8529778f62b0d64e3a4049ab0",
|
|
42
|
-
".joycraft/runtime/artifacts/decisions.mjs": "
|
|
44
|
+
".joycraft/runtime/artifacts/decisions.mjs": "fda4289eb0b7059906e0bd03b6078d1ff6fa45e23a495630721ee84ee84e0f1d",
|
|
43
45
|
".joycraft/runtime/artifacts/model.mjs": "fbe44d37049759387ecc02ba2580c94e26e6c5cb8cac3dcbcc79aeab3b75756b",
|
|
44
46
|
".joycraft/runtime/artifacts/preferences.mjs": "9165e1c753aa8533affe976cacecb135b0ee3cc9f455f5f80b1568103bb49fd6",
|
|
45
47
|
".joycraft/runtime/artifacts/render.mjs": "488673cab94fa6bfde223c2c41650f8e183f7ac0be3840d371ee057d95ea0fa5",
|
|
46
|
-
".joycraft/runtime/artifacts/server.mjs": "
|
|
47
|
-
".joycraft/runtime/cleanup.mjs": "
|
|
48
|
+
".joycraft/runtime/artifacts/server.mjs": "0c787812ffbea22c3edb7cb7281e95f54e44da4361f57ac9906487e7b5e6f8e9",
|
|
49
|
+
".joycraft/runtime/cleanup.mjs": "9a10dfd27c12f807c71f407352f1526fdb9b4632c523a965952f65d1b7af158c",
|
|
48
50
|
".joycraft/runtime/completion.mjs": "11635b11eb7df90398a69b6d41f96d9c7b9d2dc2255ae4a4a129562d46572ec1",
|
|
49
|
-
".joycraft/runtime/config.mjs": "
|
|
51
|
+
".joycraft/runtime/config.mjs": "72a536f3453dd73f65fdc243e2a13b562eee5a7ba59528adca4bde684307036a",
|
|
50
52
|
".joycraft/runtime/context/cli.mjs": "40adc206c8c3b7f4f5bedffb097d9ae1b0718f0586a055796e4987e9c3088eee",
|
|
51
53
|
".joycraft/runtime/context/index.mjs": "5a69d33d9a1a66ef23301e952ecb1ec427ff4b0baf408ede67a2600d3f2a173c",
|
|
52
54
|
".joycraft/runtime/context/search.mjs": "e32a42ba9b168ca7c68fed46d47a79250c27aa4c07c0835feae084b5d1e0d0ca",
|
|
@@ -60,18 +62,19 @@
|
|
|
60
62
|
".joycraft/runtime/redact.mjs": "cc8c0fe5e8d8fe78116ef126f6eee757a247739084e19c342bcf09a2b06524bc",
|
|
61
63
|
".joycraft/runtime/retro.mjs": "6f3664b0d50c12d4f2d8eef4b4d0d62897939d03e45860d4dcf35c0f5f92677c",
|
|
62
64
|
".joycraft/runtime/review-tools.json": "c00e4209d67fd655a351946509a2aba2ee287dbaa0a1ad60c22e1286de0b4893",
|
|
63
|
-
".joycraft/runtime/review-tools.mjs": "
|
|
65
|
+
".joycraft/runtime/review-tools.mjs": "2df0d7da93a62b06aa938c40499a564c1e87c5471b51f62478c675a9d488c0cc",
|
|
64
66
|
".joycraft/runtime/scope.mjs": "e2cdd929596246bf24e18850698db440119badc7068a3c5beab03ded45abbd65",
|
|
65
67
|
".joycraft/runtime/status.mjs": "0e1d2cc23f8d847ae14e8fc2dd909910d6b5655a0bb0305355f6f4d9709f1e33",
|
|
66
68
|
".joycraft/runtime/trace.mjs": "b7924f759b07991f4135698df9c32654631a325957f0f8de5c2ca1262c0a836a",
|
|
67
|
-
".joycraft/runtime/update-check.mjs": "
|
|
69
|
+
".joycraft/runtime/update-check.mjs": "987b65605a26ea71b6417fda7b48753980e0d8afa20eadbd527143850a93319e",
|
|
70
|
+
".joycraft/runtime/wiring.mjs": "e08bcc604d40560f260edbc3499a4481a1efa7c7d2fa80545caa858827404667",
|
|
68
71
|
".joycraft/runtime/worktrees.mjs": "d463e1df5735550acf4f3a0e6f96f723d8f55806ba64d38190163d0cc0154f03",
|
|
69
72
|
".joycraft/templates/README.md": "56a166d0729e8b6c3bcb098afb8145006259357087fd8b1f1f343d9a2b4d36e0",
|
|
70
73
|
".joycraft/templates/artifact.json": "fda5f7c32516d6ab094ee0e8506d84a1a0d6d4d0f49048b01aa392c619996f05",
|
|
71
74
|
".joycraft/templates/brief.md": "03479342500570aba9fb206beef6f6049fd180bec814dd8001987174aecfef25",
|
|
72
75
|
".joycraft/templates/decisions.md": "49e0c9b3efe51d1c2e87345fcefe23ef0579e524d50febef8ef43a35141c8002",
|
|
73
|
-
".joycraft/templates/joycraft.yaml": "
|
|
74
|
-
".joycraft/templates/project-context.md": "
|
|
76
|
+
".joycraft/templates/joycraft.yaml": "32ec8e9987030485f2a29d9231b2b15c310470d2f1269550e56c4dde0133becf",
|
|
77
|
+
".joycraft/templates/project-context.md": "cf2455fef663e647962495175fa6a7a44301c4047eecff5811d9c91e21d9e266",
|
|
75
78
|
".joycraft/templates/queue.json": "88f922b6cc47b80befc27df86a143d6bae0b30869c46d712958b64291e5ebcc2",
|
|
76
79
|
".joycraft/templates/spec.md": "5f4b1490c2ba2e47ced1ef5b369fe3e41386eb61386c42c7a561b1e8af02ea5e",
|
|
77
80
|
".joycraft/templates/ui-slice.html": "0c3cf45709ff37815f8f0550b4b9431cb935589b282d40e8688b310a91de2274",
|