joycraft 0.6.6 → 0.6.8

package/README.md

@@ -8,7 +8,7 @@
 
 ## What is Joycraft?
 
-Joycraft is a CLI tool that installs structured development skills into [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and [OpenAI Codex](https://openai.com/codex), along with behavioral boundaries, templates, and documentation structure. It takes any project from unstructured prompting to autonomous spec-driven development.
+Joycraft is a CLI tool that installs structured development skills into [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenAI Codex](https://openai.com/codex), and [Pi](https://github.com/earendil-works/pi-coding-agent), along with behavioral boundaries, templates, and documentation structure. It takes any project from unstructured prompting to autonomous spec-driven development — and on Pi, to fully headless spec execution.
 
 ### The core idea
 
@@ -31,7 +31,27 @@ Most developers plateau at Level 2. Joycraft's job is to move you up.
 
 ### Platform support
 
-Joycraft supports both **Claude Code** and **OpenAI Codex** out of the box. Running `npx joycraft init` installs skills to both `.claude/skills/` and `.agents/skills/` — no flags, no configuration. Both platforms get the same structured workflows, adapted for each tool's invocation model (`/joycraft-*` for Claude Code, `$joycraft-*` for Codex).
+Joycraft supports **Claude Code**, **OpenAI Codex**, and **Pi** out of the box. Running `npx joycraft init` auto-detects which harnesses your project uses and installs the matching skills — no flags, no configuration:
+
+| Harness | Skills installed to | Invocation |
+|---------|---------------------|------------|
+| Claude Code | `.claude/skills/` | `/joycraft-*` |
+| Codex | `.agents/skills/` (+ `AGENTS.md`) | `$joycraft-*` |
+| Pi | `.pi/skills/` (+ pipeline runtime, see below) | `/skill:joycraft-*` |
+
+All three get the same structured workflows, adapted for each tool's invocation model. Codex and Pi surfaces install when their directory (`.agents/` or `.pi/`) is present in the project.
+
+### Headless spec execution (Pi)
+
+Pi is the one harness where the workflow can run **fully autonomously** — no human keystrokes between specs. Beyond the skills, `init` installs a pipeline runtime to `.pi/scripts/joycraft/` whose driver, `joycraft-implement-loop`, runs an entire feature's spec queue end to end:
+
+```
+next-spec → pi -p "/skill:joycraft-implement <spec>" → pi -p "/skill:joycraft-spec-done <spec>" → repeat
+```
+
+Each spec runs in **one fresh OS process** (`pi -p`), so the context isolation is the process boundary itself — verified, not in-conversation trickery. The loop is fail-fast (stops and names the failing spec) and runs `session-end` exactly once when the queue is exhausted.
+
+This is what Claude Code and Codex can't do out of the box: an unattended `interview → PR` line where the machine does everything convergent in between. It is Pi-specific by design — the driver targets Pi with a BYO API key or open-weight model (Commercial/API terms, no automation restriction); pointing a consumer Claude/ChatGPT *subscription* at an automated loop would violate those tools' terms.
 
 ## Quick Start
 
@@ -52,7 +72,8 @@ Joycraft auto-detects your tech stack and creates:
 
 - **CLAUDE.md** with behavioral boundaries (Always / Ask First / Never) and correct build/test/lint commands
 - **AGENTS.md** for Codex compatibility
-- **15 skills** installed to `.claude/skills/` (Claude Code) and `.agents/skills/` (Codex) — see [Which skill do I need?](#which-skill-do-i-need) below
+- **19 skills** installed to `.claude/skills/` (Claude Code), `.agents/skills/` (Codex), and `.pi/skills/` (Pi) — see [Which skill do I need?](#which-skill-do-i-need) below
+- **Pi pipeline runtime** in `.pi/scripts/joycraft/` (when `.pi/` is present) — the headless spec-execution driver and its helpers
 - **docs/** structure: `docs/context/` is created up front; feature work lands in `docs/features/<slug>/{brief.md, research.md, design.md, specs/}` and deferred work in `docs/backlog/` — these are created lazily by the skills that write to them
 - **Context documents** in `docs/context/`: production map, dangerous assumptions, decision log, institutional knowledge, and troubleshooting guide
 - **Templates** including atomic spec, feature brief, implementation plan, boundary framework, and workflow templates for scenario generation and autofix loops

package/dist/chunk-63OWWRAJ.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+// src/version.ts
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { join, dirname } from "path";
+import { createHash } from "crypto";
+var STATE_PATH = join(".claude", ".joycraft", "state.json");
+var LEGACY_VERSION_FILE = ".joycraft-version";
+var HASH_LENGTH = 16;
+function hashContent(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+function truncateHash(hash) {
+  return hash.slice(0, HASH_LENGTH);
+}
+function readVersion(dir) {
+  const filePath = join(dir, STATE_PATH);
+  if (!existsSync(filePath)) return null;
+  try {
+    const raw = readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.version === "string" && typeof parsed.files === "object") {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function writeVersion(dir, version, files) {
+  const filePath = join(dir, STATE_PATH);
+  const truncated = {};
+  for (const [path, hash] of Object.entries(files)) {
+    truncated[path] = truncateHash(hash);
+  }
+  const data = { version, files: truncated };
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+function getLevel(dir) {
+  const hasAutofix = existsSync(join(dir, ".github", "workflows", "autofix.yml"));
+  if (!hasAutofix) return 4;
+  const claudeMdPath = join(dir, "CLAUDE.md");
+  if (!existsSync(claudeMdPath)) return 4;
+  const content = readFileSync(claudeMdPath, "utf-8");
+  return content.includes("## External Validation") ? 5 : 4;
+}
+
+export {
+  STATE_PATH,
+  LEGACY_VERSION_FILE,
+  hashContent,
+  truncateHash,
+  readVersion,
+  writeVersion,
+  getLevel
+};
+//# sourceMappingURL=chunk-63OWWRAJ.js.map

package/dist/chunk-63OWWRAJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/version.ts"],"sourcesContent":["import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';\nimport { join, dirname } from 'node:path';\nimport { createHash } from 'node:crypto';\n\n/**\n * Project-relative path to Joycraft's upgrade-state file.\n *\n * Hidden inside `.claude/` — the dir `init` always creates for every harness —\n * directly analogous to npm's own hidden lockfile at\n * `node_modules/.package-lock.json`. Never at the repo root, never committed\n * (init/upgrade gitignore it). The old root location was `.joycraft-version`\n * (see LEGACY_VERSION_FILE); `upgrade` migrates it on first run.\n */\nexport const STATE_PATH = join('.claude', '.joycraft', 'state.json');\n\n/** The pre-relocation root path. Kept only so `upgrade` can migrate it. */\nexport const LEGACY_VERSION_FILE = '.joycraft-version';\n\n/**\n * Length we truncate stored hashes to. Full SHA-256 is 64 hex chars; 16 hex\n * (64 bits) is ample to detect customization across ~100 managed files and\n * shrinks the state ~4×. Compare truncated-on-both-sides (see upgrade.ts).\n */\nconst HASH_LENGTH = 16;\n\nexport interface VersionInfo {\n  version: string;\n  files: Record<string, string>;\n}\n\nexport function hashContent(content: string): string {\n  return createHash('sha256').update(content).digest('hex');\n}\n\n/** Truncate a (full) content hash to the stored length. Idempotent for already-short input. */\nexport function truncateHash(hash: string): string {\n  return hash.slice(0, HASH_LENGTH);\n}\n\nexport function readVersion(dir: string): VersionInfo | null {\n  const filePath = join(dir, STATE_PATH);\n  if (!existsSync(filePath)) return null;\n  try {\n    const raw = readFileSync(filePath, 'utf-8');\n    const parsed = JSON.parse(raw);\n    if (typeof parsed.version === 'string' && typeof parsed.files === 'object') {\n      return parsed as VersionInfo;\n    }\n    return null;\n  } catch {\n    return null;\n  }\n}\n\nexport function writeVersion(dir: string, version: string, files: Record<string, string>): void {\n  const filePath = join(dir, STATE_PATH);\n  // Store truncated hashes — single source of truth for the on-disk shape.\n  const truncated: Record<string, string> = {};\n  for (const [path, hash] of Object.entries(files)) {\n    truncated[path] = truncateHash(hash);\n  }\n  const data: VersionInfo = { version, files: truncated };\n  mkdirSync(dirname(filePath), { recursive: true });\n  writeFileSync(filePath, JSON.stringify(data, null, 2) + '\\n', 'utf-8');\n}\n\n/**\n * Detect the current Joycraft harness level for a project directory.\n * Returns 5 if Level 5 artifacts (autofix workflow + External Validation) are present, 4 otherwise.\n */\nexport function getLevel(dir: string): number {\n  const hasAutofix = existsSync(join(dir, '.github', 'workflows', 'autofix.yml'));\n  if (!hasAutofix) return 4;\n  const claudeMdPath = join(dir, 'CLAUDE.md');\n  if (!existsSync(claudeMdPath)) return 4;\n  const content = readFileSync(claudeMdPath, 'utf-8');\n  return content.includes('## External Validation') ? 5 : 4;\n}\n"],"mappings":";;;AAAA,SAAS,cAAc,eAAe,YAAY,iBAAiB;AACnE,SAAS,MAAM,eAAe;AAC9B,SAAS,kBAAkB;AAWpB,IAAM,aAAa,KAAK,WAAW,aAAa,YAAY;AAG5D,IAAM,sBAAsB;AAOnC,IAAM,cAAc;AAOb,SAAS,YAAY,SAAyB;AACnD,SAAO,WAAW,QAAQ,EAAE,OAAO,OAAO,EAAE,OAAO,KAAK;AAC1D;AAGO,SAAS,aAAa,MAAsB;AACjD,SAAO,KAAK,MAAM,GAAG,WAAW;AAClC;AAEO,SAAS,YAAY,KAAiC;AAC3D,QAAM,WAAW,KAAK,KAAK,UAAU;AACrC,MAAI,CAAC,WAAW,QAAQ,EAAG,QAAO;AAClC,MAAI;AACF,UAAM,MAAM,aAAa,UAAU,OAAO;AAC1C,UAAM,SAAS,KAAK,MAAM,GAAG;AAC7B,QAAI,OAAO,OAAO,YAAY,YAAY,OAAO,OAAO,UAAU,UAAU;AAC1E,aAAO;AAAA,IACT;AACA,WAAO;AAAA,EACT,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEO,SAAS,aAAa,KAAa,SAAiB,OAAqC;AAC9F,QAAM,WAAW,KAAK,KAAK,UAAU;AAErC,QAAM,YAAoC,CAAC;AAC3C,aAAW,CAAC,MAAM,IAAI,KAAK,OAAO,QAAQ,KAAK,GAAG;AAChD,cAAU,IAAI,IAAI,aAAa,IAAI;AAAA,EACrC;AACA,QAAM,OAAoB,EAAE,SAAS,OAAO,UAAU;AACtD,YAAU,QAAQ,QAAQ,GAAG,EAAE,WAAW,KAAK,CAAC;AAChD,gBAAc,UAAU,KAAK,UAAU,MAAM,MAAM,CAAC,IAAI,MAAM,OAAO;AACvE;AAMO,SAAS,SAAS,KAAqB;AAC5C,QAAM,aAAa,WAAW,KAAK,KAAK,WAAW,aAAa,aAAa,CAAC;AAC9E,MAAI,CAAC,WAAY,QAAO;AACxB,QAAM,eAAe,KAAK,KAAK,WAAW;AAC1C,MAAI,CAAC,WAAW,YAAY,EAAG,QAAO;AACtC,QAAM,UAAU,aAAa,cAAc,OAAO;AAClD,SAAO,QAAQ,SAAS,wBAAwB,IAAI,IAAI;AAC1D;","names":[]}

package/dist/chunk-JVRMYMBC.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+// src/gitignore.ts
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+function ensureGitignoreEntry(targetDir, line) {
+  const gitignorePath = join(targetDir, ".gitignore");
+  if (!existsSync(gitignorePath)) {
+    writeFileSync(gitignorePath, line + "\n", "utf-8");
+    return true;
+  }
+  const current = readFileSync(gitignorePath, "utf-8");
+  const already = current.split("\n").some((l) => l.trim() === line.trim());
+  if (already) return false;
+  const sep = current.length > 0 && !current.endsWith("\n") ? "\n" : "";
+  writeFileSync(gitignorePath, current + sep + line + "\n", "utf-8");
+  return true;
+}
+
+// src/package-version.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join as join2 } from "path";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+function getPackageVersion() {
+  const pkgPath = join2(__dirname, "..", "package.json");
+  const raw = readFileSync2(pkgPath, "utf-8");
+  const pkg = JSON.parse(raw);
+  if (typeof pkg.version !== "string" || pkg.version.length === 0) {
+    throw new Error(`Joycraft package.json at ${pkgPath} is missing a version field`);
+  }
+  return pkg.version;
+}
+
+export {
+  ensureGitignoreEntry,
+  getPackageVersion
+};
+//# sourceMappingURL=chunk-JVRMYMBC.js.map

package/dist/chunk-JVRMYMBC.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/gitignore.ts","../src/package-version.ts"],"sourcesContent":["import { existsSync, readFileSync, writeFileSync } from 'node:fs';\nimport { join } from 'node:path';\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 adds `line` if no\n * existing line matches it exactly (after trimming). Returns true if it wrote.\n *\n * Used by both `init` (to gitignore the relocated state file) and `upgrade`'s\n * legacy-migration step (so migrated projects also stop committing the state).\n */\nexport function ensureGitignoreEntry(targetDir: string, line: string): boolean {\n  const gitignorePath = join(targetDir, '.gitignore');\n\n  if (!existsSync(gitignorePath)) {\n    writeFileSync(gitignorePath, line + '\\n', 'utf-8');\n    return true;\n  }\n\n  const current = readFileSync(gitignorePath, 'utf-8');\n  const already = current.split('\\n').some((l) => l.trim() === line.trim());\n  if (already) return false;\n\n  // Append on its own line, 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 + line + '\\n', 'utf-8');\n  return true;\n}\n","import { readFileSync } from 'node:fs';\nimport { fileURLToPath } from 'node:url';\nimport { dirname, join } from 'node:path';\n\nconst __dirname = dirname(fileURLToPath(import.meta.url));\n\nexport function getPackageVersion(): string {\n  const pkgPath = join(__dirname, '..', 'package.json');\n  const raw = readFileSync(pkgPath, 'utf-8');\n  const pkg = JSON.parse(raw) as { version?: unknown };\n  if (typeof pkg.version !== 'string' || pkg.version.length === 0) {\n    throw new Error(`Joycraft package.json at ${pkgPath} is missing a version field`);\n  }\n  return pkg.version;\n}\n"],"mappings":";;;AAAA,SAAS,YAAY,cAAc,qBAAqB;AACxD,SAAS,YAAY;AAYd,SAAS,qBAAqB,WAAmB,MAAuB;AAC7E,QAAM,gBAAgB,KAAK,WAAW,YAAY;AAElD,MAAI,CAAC,WAAW,aAAa,GAAG;AAC9B,kBAAc,eAAe,OAAO,MAAM,OAAO;AACjD,WAAO;AAAA,EACT;AAEA,QAAM,UAAU,aAAa,eAAe,OAAO;AACnD,QAAM,UAAU,QAAQ,MAAM,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,MAAM,KAAK,KAAK,CAAC;AACxE,MAAI,QAAS,QAAO;AAGpB,QAAM,MAAM,QAAQ,SAAS,KAAK,CAAC,QAAQ,SAAS,IAAI,IAAI,OAAO;AACnE,gBAAc,eAAe,UAAU,MAAM,OAAO,MAAM,OAAO;AACjE,SAAO;AACT;;;AC7BA,SAAS,gBAAAA,qBAAoB;AAC7B,SAAS,qBAAqB;AAC9B,SAAS,SAAS,QAAAC,aAAY;AAE9B,IAAM,YAAY,QAAQ,cAAc,YAAY,GAAG,CAAC;AAEjD,SAAS,oBAA4B;AAC1C,QAAM,UAAUA,MAAK,WAAW,MAAM,cAAc;AACpD,QAAM,MAAMD,cAAa,SAAS,OAAO;AACzC,QAAM,MAAM,KAAK,MAAM,GAAG;AAC1B,MAAI,OAAO,IAAI,YAAY,YAAY,IAAI,QAAQ,WAAW,GAAG;AAC/D,UAAM,IAAI,MAAM,4BAA4B,OAAO,6BAA6B;AAAA,EAClF;AACA,SAAO,IAAI;AACb;","names":["readFileSync","join"]}