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
package/README.md
CHANGED
|
@@ -19,8 +19,10 @@ Install Joycraft in this project.
|
|
|
19
19
|
2. Ask me which coding agents I use in this project (default: you). Then run
|
|
20
20
|
`npx joycraft@latest init . --harness <agents> --yes`.
|
|
21
21
|
If it finds Joycraft 0.7, stop and show me its migration plan.
|
|
22
|
-
3. Use the joycraft-entry skill to set up
|
|
23
|
-
|
|
22
|
+
3. Use the joycraft-entry skill to set up Joycraft's context map. Read the project's
|
|
23
|
+
docs, interview me about what the repo cannot tell you, then show me the
|
|
24
|
+
AGENTS.md and CLAUDE.md changes on a page before you write them. If the project
|
|
25
|
+
is new or empty, ask me what I want to build.
|
|
24
26
|
4. Run `node .joycraft/runtime/review-tools.mjs plan --root .`. Tell me which tools
|
|
25
27
|
you need to check your own work, which ones I have, and which ones are missing.
|
|
26
28
|
Ask me before you install anything.
|
|
@@ -63,10 +65,22 @@ says when to read it. The documents live in `docs/context/`: what the project is
|
|
|
63
65
|
who it is for, the decisions you made and why. Before each piece of work, the agent
|
|
64
66
|
uses the map to find the documents and the code that apply.
|
|
65
67
|
|
|
68
|
+
**After you install, the agent builds the map with you.** It reads your docs, gives
|
|
69
|
+
each one a role, checks what they claim against the code, and asks you what the repo
|
|
70
|
+
cannot tell it. Then it shows you the AGENTS.md and CLAUDE.md changes on a page and
|
|
71
|
+
writes them only on your yes. In a large project it maps the main docs first and
|
|
72
|
+
the rest of the project as work reaches it. If Joycraft is not wired into AGENTS.md
|
|
73
|
+
yet, `init`, `update` and `doctor` say so, and the agent sets it up before any other
|
|
74
|
+
Joycraft work.
|
|
75
|
+
|
|
66
76
|
The map grows with the project:
|
|
67
77
|
|
|
68
|
-
- **New facts go to one home.** When you decide something, the agent records it
|
|
69
|
-
|
|
78
|
+
- **New facts go to one home.** When you decide something, the agent records it
|
|
79
|
+
where it belongs and gives a new document a row in the map. It updates an
|
|
80
|
+
existing document; it does not make a copy.
|
|
81
|
+
- **The map says what is true now.** A changed fact is rewritten in place. The
|
|
82
|
+
reason goes to the decision log and old versions stay in Git and the archive, so
|
|
83
|
+
a fresh session reads the current state instead of replaying history.
|
|
70
84
|
- **Finished work becomes history.** A completed feature moves to `docs/archive/`.
|
|
71
85
|
The agent can check it later to catch a regression.
|
|
72
86
|
- **Mistakes become lessons.** When the checking agent fails a spec, the cause can
|
|
@@ -74,8 +88,10 @@ The map grows with the project:
|
|
|
74
88
|
- **Ideas for later stay visible.** A choice you put off is marked "backlogged". It
|
|
75
89
|
stays out of the current work, but it is not lost.
|
|
76
90
|
|
|
77
|
-
You can feed it too.
|
|
78
|
-
|
|
91
|
+
You can feed it too. Say "add this to the project context", "remove that rule" or
|
|
92
|
+
"what does the map say about billing", or give your agent meeting notes, a photo of
|
|
93
|
+
a whiteboard or a screenshot. It puts each fact in its home, keeps the map right, and
|
|
94
|
+
shows you the change first. This gives the
|
|
79
95
|
agent both views: the whole project and the detail of the current step.
|
|
80
96
|
|
|
81
97
|
### What in `docs/` is current
|
|
@@ -108,11 +124,16 @@ cleanup:
|
|
|
108
124
|
docs: [docs/context/auction-rules.md]
|
|
109
125
|
```
|
|
110
126
|
|
|
111
|
-
The file is yours: Joycraft reads it and never rewrites it.
|
|
127
|
+
The file is yours: Joycraft reads it and never rewrites it. Run
|
|
128
|
+
`node .joycraft/runtime/config.mjs` to see the settings in effect.
|
|
129
|
+
|
|
130
|
+
The `afterArchive` command gets `JOYCRAFT_FEATURE`, `JOYCRAFT_ARCHIVE_PATH` and
|
|
131
|
+
`JOYCRAFT_SOURCE_PATH` in its environment. Use it to update a wiki or run a doc
|
|
132
|
+
audit. If the command fails, the archive stays done and the archive CLI exits 3.
|
|
112
133
|
|
|
113
134
|
### Keeping the workspace clean
|
|
114
135
|
|
|
115
|
-
At the end of a session the agent runs
|
|
136
|
+
At the end of a session the agent runs these checks for you:
|
|
116
137
|
|
|
117
138
|
- `node .joycraft/runtime/status.mjs` finds specs whose text disagrees with the queue,
|
|
118
139
|
and features that are finished but not archived.
|
|
@@ -123,18 +144,34 @@ At the end of a session the agent runs three checks for you:
|
|
|
123
144
|
so a second session's instructions do not reach the first session's workers.
|
|
124
145
|
- `node .joycraft/runtime/cleanup.mjs` reports stale or unreachable project
|
|
125
146
|
knowledge: finished features not archived, context pages that link to working
|
|
126
|
-
material, broken or
|
|
127
|
-
|
|
147
|
+
material, broken, missing or unmapped pages, an AGENTS.md over its word budget,
|
|
148
|
+
and pages whose code changed.
|
|
149
|
+
- The doc audit, based on [doc-cleanup](https://github.com/aka-luan/doc-cleanup),
|
|
150
|
+
runs at every session end without being asked. It covers AGENTS.md, CLAUDE.md, the
|
|
151
|
+
docs the session changed and the pages they link; after a feature is archived, the
|
|
152
|
+
whole project. It checks each claim against the code, keeps your rules and traps,
|
|
153
|
+
puts its findings on the session-end page, and changes nothing until you approve.
|
|
154
|
+
Ask your agent to "clean up the docs" for a full audit at any time.
|
|
155
|
+
- `node .joycraft/runtime/wiring.mjs` reports whether AGENTS.md has the Joycraft
|
|
156
|
+
lines and a real context map, and whether CLAUDE.md imports it.
|
|
128
157
|
|
|
129
158
|
Tests name the acceptance criterion they check, `[AC:<criterion-id>]`, so the
|
|
130
|
-
reviewing agent can see which criteria have a test.
|
|
159
|
+
reviewing agent can see which criteria have a test. A criterion with no test is a
|
|
160
|
+
finding for the reviewer, not an automatic FAIL.
|
|
161
|
+
|
|
162
|
+
If your docs are step-by-step procedures, the agent can offer
|
|
163
|
+
[Doc Detective](https://docs.doc-detective.com) to run them as tests. It is opt-in:
|
|
164
|
+
the agent says what it does not cover and installs nothing without your yes.
|
|
131
165
|
|
|
132
166
|
## Answering questions: the decision page
|
|
133
167
|
|
|
134
168
|
When the agent needs you to choose between options, it shows the questions on a
|
|
135
169
|
decision page instead of in chat. Each question shows its context, its options and
|
|
136
|
-
what it affects. You pick an answer,
|
|
137
|
-
|
|
170
|
+
what it affects. You pick an answer, or "Something else" and say what you want, add
|
|
171
|
+
a note if you want, and save. You can add or change a note after saving. If the
|
|
172
|
+
brief changes while the page is open, the page names the questions that changed and
|
|
173
|
+
keeps your other answers. The answers go into the brief, so the agent does not ask
|
|
174
|
+
again.
|
|
138
175
|
|
|
139
176
|
Sometimes the agent forgets and lists the options in chat. Then say:
|
|
140
177
|
|
|
@@ -163,14 +200,17 @@ project:
|
|
|
163
200
|
adds to them and never removes them.
|
|
164
201
|
|
|
165
202
|
All of it lives in your repository. Joycraft collects no data and does not call an AI
|
|
166
|
-
model itself. Its only network use is the version check below. Joycraft
|
|
167
|
-
hooks and changes no agent settings.
|
|
203
|
+
model itself. Its only network use is the version check below. Joycraft adds no
|
|
204
|
+
agent hooks and changes no agent settings. The `afterArchive` command above runs only
|
|
205
|
+
if you set it.
|
|
168
206
|
|
|
169
207
|
## Updates
|
|
170
208
|
|
|
171
209
|
At the start of a session, your agent checks npm for a newer Joycraft, at most once a
|
|
172
210
|
day. The check sends no project data. If there is a new version, the agent tells you
|
|
173
|
-
|
|
211
|
+
whether it is a patch, a minor release or a migration, lists each release since
|
|
212
|
+
yours, and asks: update now, not now, or turn off. Automatic updates apply only
|
|
213
|
+
patches. On a yes, it does the update
|
|
174
214
|
for you, checks the result, and tells you what is different. A new major version is
|
|
175
215
|
always your choice.
|
|
176
216
|
|
|
@@ -222,6 +262,7 @@ should forget:
|
|
|
222
262
|
- **Theo Browne** ([t3.gg](https://t3.gg)): measure which notes an agent actually reads, and keep `AGENTS.md` short and directional.
|
|
223
263
|
- **Lauren** (Cursor): prefer fixes in this order: architecture, then lint and CI, then skills and rules, then asking a human.
|
|
224
264
|
- **Robert C. Martin**: impose values, not disciplines.
|
|
265
|
+
- **aka-luan** ([doc-cleanup](https://github.com/aka-luan/doc-cleanup), MIT), brought to Joycraft by **David Moshal**: Joycraft's doc audit follows its method. Treat every doc claim as a hypothesis and the code as the evidence.
|
|
225
266
|
|
|
226
267
|
The levels this project aims at are Dan Shapiro's. See [The levels](docs/guides/levels.md).
|
|
227
268
|
|
package/dist/cli.js
CHANGED
|
@@ -10,6 +10,7 @@ import { createInterface } from "readline/promises";
|
|
|
10
10
|
// src/install-v1.ts
|
|
11
11
|
import { copyFileSync, existsSync as existsSync2, lstatSync, mkdirSync, readFileSync as readFileSync2, renameSync, rmSync, writeFileSync } from "fs";
|
|
12
12
|
import { dirname as dirname2, join as join2, resolve, sep } from "path";
|
|
13
|
+
import { pathToFileURL } from "url";
|
|
13
14
|
|
|
14
15
|
// src/payload.ts
|
|
15
16
|
import { createHash } from "crypto";
|
|
@@ -243,6 +244,33 @@ function recordedHosts(dir) {
|
|
|
243
244
|
const hosts = manifest?.hosts?.filter((host) => HOSTS.includes(host));
|
|
244
245
|
return hosts?.length ? hosts : null;
|
|
245
246
|
}
|
|
247
|
+
var WIRING_SENTENCE = "Set up Joycraft's context map";
|
|
248
|
+
var WIRING_MODULE = ".joycraft/runtime/wiring.mjs";
|
|
249
|
+
async function checkWiring(dir, { hosts } = {}) {
|
|
250
|
+
const root = resolve(dir);
|
|
251
|
+
const path = join2(payloadRoot(), WIRING_MODULE);
|
|
252
|
+
if (!existsSync2(path)) return null;
|
|
253
|
+
try {
|
|
254
|
+
const module = await import(pathToFileURL(path).href);
|
|
255
|
+
if (typeof module.checkWiring !== "function") return null;
|
|
256
|
+
const result = module.checkWiring(root, hosts ? { hosts } : {});
|
|
257
|
+
if (!result || !Array.isArray(result.findings)) return null;
|
|
258
|
+
return { wired: result.findings.length === 0, findings: result.findings, advice: Array.isArray(result.advice) ? result.advice : [] };
|
|
259
|
+
} catch {
|
|
260
|
+
return null;
|
|
261
|
+
}
|
|
262
|
+
}
|
|
263
|
+
function formatWiring(wiring, indent = "", { planned = false } = {}) {
|
|
264
|
+
if (!wiring) return [];
|
|
265
|
+
const advice = wiring.advice.map((item) => `${indent}Not mapped yet: ${item.areas?.length ? item.areas.join(", ") : item.detail}`);
|
|
266
|
+
if (wiring.wired) return advice;
|
|
267
|
+
return [
|
|
268
|
+
planned ? `${indent}After this install, the project's entry files will still need wiring up:` : `${indent}Joycraft is installed, but this project's entry files are not wired up yet:`,
|
|
269
|
+
...wiring.findings.map((finding) => `${indent} - ${finding.detail}`),
|
|
270
|
+
`${indent}Joycraft does not edit AGENTS.md or CLAUDE.md itself. Give your agent this sentence:`,
|
|
271
|
+
`${indent} "${WIRING_SENTENCE}"`
|
|
272
|
+
];
|
|
273
|
+
}
|
|
246
274
|
|
|
247
275
|
// src/legacy-07.ts
|
|
248
276
|
import { copyFileSync as copyFileSync2, existsSync as existsSync3, lstatSync as lstatSync2, mkdirSync as mkdirSync2, readdirSync, readFileSync as readFileSync3, renameSync as renameSync2, rmdirSync, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
|
|
@@ -1576,10 +1604,12 @@ async function install(dir, opts, mode) {
|
|
|
1576
1604
|
}
|
|
1577
1605
|
if (!await approved(opts, formatLegacyPlan(plan2, false), "Migrate to Joycraft 1.0?")) return;
|
|
1578
1606
|
const result2 = migrateLegacy(plan2, { keep });
|
|
1579
|
-
|
|
1607
|
+
const wiring2 = await checkWiring(root);
|
|
1608
|
+
out(opts.json, { ...result2, wiring: wiring2 }, [
|
|
1580
1609
|
`Migrated to Joycraft ${plan2.install.to.joycraft}. ${result2.archived.length} 0.7 file(s) archived in ${result2.backup}/.`,
|
|
1581
1610
|
...result2.keptCustom.length ? [`Kept in place: ${result2.keptCustom.join(", ")}`] : [],
|
|
1582
|
-
`Undo with: npx joycraft@latest rollback
|
|
1611
|
+
`Undo with: npx joycraft@latest rollback`,
|
|
1612
|
+
...formatWiring(wiring2)
|
|
1583
1613
|
].join("\n"));
|
|
1584
1614
|
return;
|
|
1585
1615
|
}
|
|
@@ -1592,20 +1622,28 @@ async function install(dir, opts, mode) {
|
|
|
1592
1622
|
const hosts = await chooseHosts(root, opts);
|
|
1593
1623
|
const plan = planInstall(root, hosts);
|
|
1594
1624
|
if (opts.plan) {
|
|
1595
|
-
|
|
1625
|
+
const wiring2 = await checkWiring(root, { hosts });
|
|
1626
|
+
out(opts.json, { ...plan, wiring: wiring2 }, [formatPlan(plan), ...formatWiring(wiring2, " ", { planned: true })].join("\n"));
|
|
1596
1627
|
return;
|
|
1597
1628
|
}
|
|
1598
1629
|
if (!plan.actions.some((action) => action.kind !== "conflict") && !plan.gitignore.length) {
|
|
1599
|
-
|
|
1630
|
+
const wiring2 = await checkWiring(root);
|
|
1631
|
+
out(
|
|
1632
|
+
opts.json,
|
|
1633
|
+
{ status: "noop", exitCode: 0, version: plan.to.joycraft, hosts, plan, wiring: wiring2 },
|
|
1634
|
+
[`Joycraft ${plan.to.joycraft} is up to date for ${hosts.join(", ")}.`, ...formatWiring(wiring2)].join("\n")
|
|
1635
|
+
);
|
|
1600
1636
|
return;
|
|
1601
1637
|
}
|
|
1602
1638
|
if (!await approved(opts, formatPlan(plan), installed ? "Update Joycraft?" : "Install Joycraft?")) return;
|
|
1603
1639
|
const result = applyInstall(plan);
|
|
1604
|
-
|
|
1640
|
+
const wiring = await checkWiring(root);
|
|
1641
|
+
out(opts.json, { status: "applied", exitCode: 0, version: plan.to.joycraft, hosts, ...result, wiring }, [
|
|
1605
1642
|
`${installed ? "Updated" : "Installed"} Joycraft ${plan.to.joycraft} for ${hosts.join(", ")}: ${result.written.length} written, ${result.removed.length} removed.`,
|
|
1606
1643
|
...result.backup ? [`Previous files are in ${result.backup}/.`] : [],
|
|
1607
1644
|
...result.conflicts.map((path) => `Kept your file (not installed): ${path}`),
|
|
1608
|
-
...installed ? [] : ["Next: open your coding agent here and say what you want to build. Joycraft sets up the rest."]
|
|
1645
|
+
...installed || wiring?.findings.length ? [] : ["Next: open your coding agent here and say what you want to build. Joycraft sets up the rest."],
|
|
1646
|
+
...formatWiring(wiring)
|
|
1609
1647
|
].join("\n"));
|
|
1610
1648
|
}
|
|
1611
1649
|
var program = new Command();
|
|
@@ -1635,12 +1673,15 @@ program.command("rollback").description("Undo a 0.7 \u2192 1.0 migration from it
|
|
|
1635
1673
|
process.exitCode = 1;
|
|
1636
1674
|
}
|
|
1637
1675
|
});
|
|
1638
|
-
program.command("doctor").description("Check the Joycraft install against its manifest").argument("[dir]", "Project directory", ".").option("--json", "Print machine-readable output").action((dir, opts) => {
|
|
1676
|
+
program.command("doctor").description("Check the Joycraft install against its manifest").argument("[dir]", "Project directory", ".").option("--json", "Print machine-readable output").action(async (dir, opts) => {
|
|
1639
1677
|
const result = doctor(dir);
|
|
1640
|
-
|
|
1678
|
+
const wiring = result.installed ? await checkWiring(dir) : null;
|
|
1679
|
+
out(opts.json, { ...result, wiring }, !result.installed ? "Joycraft is not installed here." : [
|
|
1641
1680
|
`Joycraft ${result.tag}: ${result.ok ? "ok" : "needs attention"}`,
|
|
1642
1681
|
...result.missing.map((path) => ` missing: ${path}`),
|
|
1643
|
-
...result.edited.map((path) => ` edited: ${path}`)
|
|
1682
|
+
...result.edited.map((path) => ` edited: ${path}`),
|
|
1683
|
+
...(wiring?.findings ?? []).map((finding) => ` advice (${finding.path}): ${finding.detail}`),
|
|
1684
|
+
...wiring?.findings.length ? [` To wire it up, tell your agent: "${WIRING_SENTENCE}"`] : []
|
|
1644
1685
|
].join("\n"));
|
|
1645
1686
|
if (!result.ok) process.exitCode = 1;
|
|
1646
1687
|
});
|