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.
Files changed (29) hide show
  1. package/README.md +57 -16
  2. package/dist/cli.js +50 -9
  3. package/dist/cli.js.map +1 -1
  4. package/dist/joycraft-release.json +1 -1
  5. package/package.json +3 -3
  6. package/payload/.agents/skills/joycraft-cleanup/SKILL.md +81 -34
  7. package/payload/.agents/skills/joycraft-context/SKILL.md +30 -4
  8. package/payload/.agents/skills/joycraft-entry/SKILL.md +19 -8
  9. package/payload/.agents/skills/joycraft-session-end/SKILL.md +8 -3
  10. package/payload/.joycraft/assets/artifacts/kit.css +8 -0
  11. package/payload/.joycraft/assets/artifacts/kit.js +163 -21
  12. package/payload/.joycraft/assets/artifacts/transports.js +14 -3
  13. package/payload/.joycraft/references/artifacts.md +21 -2
  14. package/payload/.joycraft/references/cleanup.md +109 -3
  15. package/payload/.joycraft/references/context.md +64 -2
  16. package/payload/.joycraft/references/doc-cleanup-LICENSE.md +23 -0
  17. package/payload/.joycraft/references/knowledge.md +58 -0
  18. package/payload/.joycraft/references/setup.md +128 -138
  19. package/payload/.joycraft/references/update.md +5 -3
  20. package/payload/.joycraft/runtime/artifacts/decisions.mjs +16 -5
  21. package/payload/.joycraft/runtime/artifacts/server.mjs +14 -1
  22. package/payload/.joycraft/runtime/cleanup.mjs +95 -8
  23. package/payload/.joycraft/runtime/config.mjs +5 -3
  24. package/payload/.joycraft/runtime/review-tools.mjs +55 -8
  25. package/payload/.joycraft/runtime/update-check.mjs +38 -8
  26. package/payload/.joycraft/runtime/wiring.mjs +156 -0
  27. package/payload/.joycraft/templates/joycraft.yaml +2 -0
  28. package/payload/.joycraft/templates/project-context.md +6 -1
  29. package/payload/PIN +25 -22
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 this project. If the project is new or empty,
23
- ask me what I want to build.
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 in
69
- the decision log. It updates an existing document; it does not make a copy.
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. Give your agent meeting notes, a photo of a whiteboard or a
78
- screenshot, and ask it to add what matters to the project context. This gives the
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 three checks for you:
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 orphaned pages, and pages whose code changed. Ask your agent
127
- to "clean up the docs" and it shows the fixes for your approval.
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, add a note if you want, and save. The answers
137
- go into the brief, so the agent does not ask again.
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 1.0 adds no
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
- what changed and asks: update now, not now, or turn off. On a yes, it does the update
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
- out(opts.json, result2, [
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
- out(opts.json, plan, formatPlan(plan));
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
- out(opts.json, { status: "noop", exitCode: 0, version: plan.to.joycraft, hosts, plan }, `Joycraft ${plan.to.joycraft} is up to date for ${hosts.join(", ")}.`);
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
- out(opts.json, { status: "applied", exitCode: 0, version: plan.to.joycraft, hosts, ...result }, [
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
- out(opts.json, result, !result.installed ? "Joycraft is not installed here." : [
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
  });