joycraft 0.7.9 → 0.7.11

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 CHANGED
@@ -15,6 +15,8 @@ cd /path/to/your/project
15
15
  npx joycraft@latest init
16
16
  ```
17
17
 
18
+ Joycraft is a **curated harness, not a memory system**. Everything it writes is in-repo, reviewed in your PRs, and reaped when it stops earning its keep — the opposite of hidden state that accretes until it misleads. Code is the truth about how your project works; the harness holds only what code cannot say (intent, decisions and their rationale, product direction), and `/joycraft-optimize`'s Reaper pass is what keeps it honest. If your agent already keeps its own automatic memory, a Joycraft project supersedes it: the same facts get one home that your whole team can see and review.
19
+
18
20
  ## Contents
19
21
 
20
22
  - [Install](#install) · [Use](#use) · [Upgrade](#upgrade)
@@ -27,7 +29,7 @@ npx joycraft@latest init
27
29
  - [Migration: flat → per-feature layout](docs/guides/migration-per-feature-layout.md) — the v0.6 docs move
28
30
  - [The levels](docs/guides/levels.md) — Dan Shapiro's 5 Levels, where Joycraft aims, and the credits
29
31
  - [Security](SECURITY.md) · [Guides](#guides) · [Why Joycraft?](#why-joycraft)
30
- - [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md) · [License](LICENSE)
32
+ - [Contributing](CONTRIBUTING.md) · [Acknowledgments](#acknowledgments) · [Changelog](CHANGELOG.md) · [License](LICENSE)
31
33
 
32
34
  ## Install
33
35
 
@@ -36,7 +38,7 @@ cd /path/to/your/project
36
38
  npx joycraft@latest init
37
39
  ```
38
40
 
39
- Answer two questions — which harnesses to install, and whether to commit them — and `init` does the rest: detects your stack, writes `AGENTS.md`/`CLAUDE.md` with your real build/test commands, installs the skills. Safe to re-run: it only creates missing files, never overwrites yours.
41
+ Answer a few questions — which harnesses to install, whether to commit them, and (with Claude Code) whether to turn off auto-memory for this project — and `init` does the rest: detects your stack, writes `AGENTS.md`/`CLAUDE.md` with your real build/test commands, installs the skills. Safe to re-run: it only creates missing files, never overwrites yours.
40
42
 
41
43
  `npm install -g joycraft` if you'd rather have the command on your PATH; `npx` works without it. Every step from install to first shipped feature: [Setup walkthrough](docs/guides/setup-walkthrough.md).
42
44
 
@@ -157,6 +159,17 @@ The short version:
157
159
 
158
160
  Look for [`good first issue`](https://github.com/maksutovic/joycraft/labels/good%20first%20issue) labels if you're new. Areas we'd especially love help with: stack detection for new languages, skill improvements, and documentation.
159
161
 
162
+ ## Acknowledgments
163
+
164
+ The curated-harness stance above was shaped by people thinking out loud about what agents should and shouldn't remember:
165
+
166
+ - **Mario Zechner** (creator of [Pi](https://github.com/earendil-works/pi-coding-agent)) and **Armin Ronacher** (creator of Flask) — "code is truth" and the minimal-harness thesis: no separate memory system for knowledge the code already carries.
167
+ - **Theo Browne** ([t3.gg](https://t3.gg)) — the write-vs-read memory audit that turned decay into something measurable, and the case for directional rather than rule-heavy AGENTS.md content.
168
+ - **Lauren** (Cursor) — the intervention-elimination hierarchy: architecture beats lint and CI, which beat skills and rules, which beat asking a human.
169
+ - **Robert C. Martin** — impose values, not disciplines.
170
+
171
+ The levels this project aims at are Dan Shapiro's; those credits live in [The levels](docs/guides/levels.md).
172
+
160
173
  ## License
161
174
 
162
175
  MIT. See [LICENSE](LICENSE) for details.
@@ -1,4 +1,7 @@
1
1
  #!/usr/bin/env node
2
+ import {
3
+ TELEMETRY_PATH
4
+ } from "./chunk-OAC5CVHJ.js";
2
5
  import {
3
6
  DEFAULT_GITIGNORE_PROFILE,
4
7
  STATE_PATH,
@@ -23,10 +26,11 @@ function ensureGitignoreEntries(targetDir, entries) {
23
26
  return missing;
24
27
  }
25
28
  function applyGitignoreProfile(targetDir, profile) {
29
+ const machineOwned = [STATE_PATH, TELEMETRY_PATH];
26
30
  if (profile === "private") {
27
- return ensureGitignoreEntries(targetDir, [...PRIVATE_PROFILE_IGNORES, STATE_PATH]);
31
+ return ensureGitignoreEntries(targetDir, [...PRIVATE_PROFILE_IGNORES, ...machineOwned]);
28
32
  }
29
- return ensureGitignoreEntries(targetDir, [STATE_PATH]);
33
+ return ensureGitignoreEntries(targetDir, machineOwned);
30
34
  }
31
35
  function validateGitignoreFlag(flag) {
32
36
  const parsed = parseGitignoreProfile(flag);
@@ -84,4 +88,4 @@ export {
84
88
  validateGitignoreFlag,
85
89
  resolveGitignoreProfile
86
90
  };
87
- //# sourceMappingURL=chunk-RRMO5FBO.js.map
91
+ //# sourceMappingURL=chunk-BZW5DR3O.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/gitignore.ts"],"sourcesContent":["import { existsSync, readFileSync, writeFileSync } from 'node:fs';\nimport { join } from 'node:path';\nimport { createInterface } from 'node:readline';\nimport {\n STATE_PATH,\n parseGitignoreProfile,\n DEFAULT_GITIGNORE_PROFILE,\n type GitignoreProfile,\n} from './version.js';\nimport { TELEMETRY_PATH } from './telemetry-store.js';\n\n/**\n * The harness directories the `private` profile gitignores. Tracking only\n * CLAUDE.md, AGENTS.md, and docs/ means everything under these dirs stays\n * local. `.claude/` already covers the hidden state file.\n *\n * `.github/skills/joycraft-*` is gitignored, NOT `.github/` or\n * `.github/skills/` — `.github/` holds Actions workflows, issue templates,\n * and other non-harness config, and `.github/skills/` may contain the\n * user's own non-Joycraft Copilot skills.\n *\n * Single source of truth: every user-facing string that names these dirs\n * (prompts, summaries, the untrack hint, CLI help) derives from this list via\n * the constants below, so adding a harness dir can't leave stale messages.\n */\nexport const PRIVATE_PROFILE_IGNORES = ['.claude/', '.agents/', '.pi/', '.github/skills/joycraft-*/'];\n\n/** Human-readable list of the private-profile dirs, for prompts and summaries. */\nexport const PRIVATE_DIRS_DISPLAY = PRIVATE_PROFILE_IGNORES.join(', ');\n\n/** Copy-pasteable command to untrack already-committed harness files. */\nexport const PRIVATE_UNTRACK_COMMAND = `git rm -r --cached ${PRIVATE_PROFILE_IGNORES.map((d) => d.replace(/\\/$/, '')).join(' ')}`;\n\n/**\n * Append-only, create-if-absent, idempotent .gitignore writer.\n *\n * Mirrors the \"append over modify when touching user files\" principle: it never\n * rewrites, reorders, or removes existing lines — it only appends the entries\n * not already present (matched exactly, after trimming). One read + at most one\n * write per call. Returns the entries actually added (empty when everything was\n * already present).\n */\nexport function ensureGitignoreEntries(targetDir: string, entries: string[]): string[] {\n const gitignorePath = join(targetDir, '.gitignore');\n const current = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf-8') : '';\n const present = new Set(current.split('\\n').map((l) => l.trim()));\n const missing = entries.filter((e) => !present.has(e.trim()));\n if (missing.length === 0) return [];\n\n // Append on their own lines, tolerating a file that may or may not end in \\n.\n const sep = current.length > 0 && !current.endsWith('\\n') ? '\\n' : '';\n writeFileSync(gitignorePath, current + sep + missing.join('\\n') + '\\n', 'utf-8');\n return missing;\n}\n\n/** Single-entry convenience wrapper around ensureGitignoreEntries. */\nexport function ensureGitignoreEntry(targetDir: string, line: string): boolean {\n return ensureGitignoreEntries(targetDir, [line]).length > 0;\n}\n\n/**\n * Apply a gitignore profile's entries to the project's .gitignore.\n *\n * The hidden upgrade-state file (`STATE_PATH`) is tool-managed, regenerated on\n * every init/upgrade, and must never be committed — under BOTH profiles. It now\n * lives at `docs/.joycraft/state.json`; since `docs/` is always tracked, the\n * state entry is no longer covered transitively by any harness-dir ignore, so\n * both profiles list it explicitly.\n *\n * - `shared` — ignore only the hidden state file (commit the harness dirs).\n * - `private` — ignore the .claude/, .agents/, .pi/, .github/skills/joycraft-* trees AND the state file.\n *\n * Append-only and idempotent (via ensureGitignoreEntries), so re-running\n * init/upgrade never duplicates entries. Returns the list of lines actually\n * added this call.\n */\nexport function applyGitignoreProfile(targetDir: string, profile: GitignoreProfile): string[] {\n // Machine-owned files under docs/.joycraft/ — since docs/ is always tracked,\n // both profiles must list them explicitly (telemetry.json additionally holds\n // per-machine work patterns that must never publish).\n const machineOwned = [STATE_PATH, TELEMETRY_PATH];\n if (profile === 'private') {\n return ensureGitignoreEntries(targetDir, [...PRIVATE_PROFILE_IGNORES, ...machineOwned]);\n }\n // `shared`: only the machine-owned files, matching long-standing behavior.\n return ensureGitignoreEntries(targetDir, machineOwned);\n}\n\n/** A resolved profile plus how it was arrived at. */\nexport interface ResolvedGitignoreProfile {\n profile: GitignoreProfile;\n /**\n * True when the profile is an actual decision: a --gitignore flag, a\n * persisted choice, or an interactive answer. False when it is the\n * non-interactive fallback default — callers must NOT persist a fallback,\n * or the one-time prompt would be permanently suppressed for the project.\n */\n decided: boolean;\n}\n\n/** Validate a raw --gitignore flag value. Throws the user-facing error on unknown values. */\nexport function validateGitignoreFlag(flag: string): GitignoreProfile {\n const parsed = parseGitignoreProfile(flag);\n if (!parsed) {\n throw new Error(`Unknown gitignore profile '${flag}'. Use 'shared' or 'private'.`);\n }\n return parsed;\n}\n\n/**\n * Prompt for a gitignore profile. An empty answer takes the default; an\n * unrecognized answer re-asks instead of being silently coerced — a typo must\n * not get persisted as a permanent choice.\n */\nasync function promptGitignoreProfile(intro: string): Promise<GitignoreProfile> {\n const rl = createInterface({ input: process.stdin, output: process.stdout });\n console.log(intro);\n console.log(' shared — commit skills so your team gets the same workflow (default)');\n console.log(` private — gitignore ${PRIVATE_DIRS_DISPLAY}; track only CLAUDE.md, AGENTS.md, docs/`);\n return new Promise((resolve) => {\n const ask = (): void => {\n rl.question(`Profile [shared/private] (${DEFAULT_GITIGNORE_PROFILE}): `, (answer) => {\n if (answer.trim() === '') {\n rl.close();\n resolve(DEFAULT_GITIGNORE_PROFILE);\n return;\n }\n const parsed = parseGitignoreProfile(answer);\n if (parsed) {\n rl.close();\n resolve(parsed);\n return;\n }\n console.log(\n `Unrecognized answer '${answer.trim()}' — type 'shared' or 'private', or press Enter for ${DEFAULT_GITIGNORE_PROFILE}.`\n );\n ask();\n });\n };\n ask();\n });\n}\n\n/**\n * Resolve the gitignore profile by precedence — the single resolver shared by\n * init and upgrade so the two commands can never drift:\n * 1. --gitignore flag (validated; throws on unknown value)\n * 2. profile persisted in state.json (re-init / upgrade keep the prior choice)\n * 3. interactive prompt (the caller decides when prompting is allowed)\n * 4. fallback default `shared`, reported with decided=false\n */\nexport async function resolveGitignoreProfile(opts: {\n /** Raw --gitignore value from the CLI, if provided. */\n flag?: string;\n /** Profile previously persisted in state.json, if any. */\n persisted?: GitignoreProfile;\n /** Whether prompting is allowed (TTY, and the command permits interaction). */\n interactive: boolean;\n /** First line printed above the prompt; init and upgrade word it differently. */\n promptIntro: string;\n}): Promise<ResolvedGitignoreProfile> {\n if (opts.flag !== undefined) {\n return { profile: validateGitignoreFlag(opts.flag), decided: true };\n }\n if (opts.persisted) {\n return { profile: opts.persisted, decided: true };\n }\n if (opts.interactive) {\n return { profile: await promptGitignoreProfile(opts.promptIntro), decided: true };\n }\n return { profile: DEFAULT_GITIGNORE_PROFILE, decided: false };\n}\n"],"mappings":";;;;;;;;;;;AAAA,SAAS,YAAY,cAAc,qBAAqB;AACxD,SAAS,YAAY;AACrB,SAAS,uBAAuB;AAuBzB,IAAM,0BAA0B,CAAC,YAAY,YAAY,QAAQ,4BAA4B;AAG7F,IAAM,uBAAuB,wBAAwB,KAAK,IAAI;AAG9D,IAAM,0BAA0B,sBAAsB,wBAAwB,IAAI,CAAC,MAAM,EAAE,QAAQ,OAAO,EAAE,CAAC,EAAE,KAAK,GAAG,CAAC;AAWxH,SAAS,uBAAuB,WAAmB,SAA6B;AACrF,QAAM,gBAAgB,KAAK,WAAW,YAAY;AAClD,QAAM,UAAU,WAAW,aAAa,IAAI,aAAa,eAAe,OAAO,IAAI;AACnF,QAAM,UAAU,IAAI,IAAI,QAAQ,MAAM,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAChE,QAAM,UAAU,QAAQ,OAAO,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,KAAK,CAAC,CAAC;AAC5D,MAAI,QAAQ,WAAW,EAAG,QAAO,CAAC;AAGlC,QAAM,MAAM,QAAQ,SAAS,KAAK,CAAC,QAAQ,SAAS,IAAI,IAAI,OAAO;AACnE,gBAAc,eAAe,UAAU,MAAM,QAAQ,KAAK,IAAI,IAAI,MAAM,OAAO;AAC/E,SAAO;AACT;AAuBO,SAAS,sBAAsB,WAAmB,SAAqC;AAI5F,QAAM,eAAe,CAAC,YAAY,cAAc;AAChD,MAAI,YAAY,WAAW;AACzB,WAAO,uBAAuB,WAAW,CAAC,GAAG,yBAAyB,GAAG,YAAY,CAAC;AAAA,EACxF;AAEA,SAAO,uBAAuB,WAAW,YAAY;AACvD;AAeO,SAAS,sBAAsB,MAAgC;AACpE,QAAM,SAAS,sBAAsB,IAAI;AACzC,MAAI,CAAC,QAAQ;AACX,UAAM,IAAI,MAAM,8BAA8B,IAAI,+BAA+B;AAAA,EACnF;AACA,SAAO;AACT;AAOA,eAAe,uBAAuB,OAA0C;AAC9E,QAAM,KAAK,gBAAgB,EAAE,OAAO,QAAQ,OAAO,QAAQ,QAAQ,OAAO,CAAC;AAC3E,UAAQ,IAAI,KAAK;AACjB,UAAQ,IAAI,8EAAyE;AACrF,UAAQ,IAAI,8BAAyB,oBAAoB,0CAA0C;AACnG,SAAO,IAAI,QAAQ,CAAC,YAAY;AAC9B,UAAM,MAAM,MAAY;AACtB,SAAG,SAAS,6BAA6B,yBAAyB,OAAO,CAAC,WAAW;AACnF,YAAI,OAAO,KAAK,MAAM,IAAI;AACxB,aAAG,MAAM;AACT,kBAAQ,yBAAyB;AACjC;AAAA,QACF;AACA,cAAM,SAAS,sBAAsB,MAAM;AAC3C,YAAI,QAAQ;AACV,aAAG,MAAM;AACT,kBAAQ,MAAM;AACd;AAAA,QACF;AACA,gBAAQ;AAAA,UACN,wBAAwB,OAAO,KAAK,CAAC,2DAAsD,yBAAyB;AAAA,QACtH;AACA,YAAI;AAAA,MACN,CAAC;AAAA,IACH;AACA,QAAI;AAAA,EACN,CAAC;AACH;AAUA,eAAsB,wBAAwB,MASR;AACpC,MAAI,KAAK,SAAS,QAAW;AAC3B,WAAO,EAAE,SAAS,sBAAsB,KAAK,IAAI,GAAG,SAAS,KAAK;AAAA,EACpE;AACA,MAAI,KAAK,WAAW;AAClB,WAAO,EAAE,SAAS,KAAK,WAAW,SAAS,KAAK;AAAA,EAClD;AACA,MAAI,KAAK,aAAa;AACpB,WAAO,EAAE,SAAS,MAAM,uBAAuB,KAAK,WAAW,GAAG,SAAS,KAAK;AAAA,EAClF;AACA,SAAO,EAAE,SAAS,2BAA2B,SAAS,MAAM;AAC9D;","names":[]}