@playcraft/cli 0.0.43 → 0.0.46

package/project-template/.claude/hooks/gate.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+/**
+ * PlayCraft Gate Hook — unified handler for growth-ring gates.
+ *
+ * Actions:
+ *   1. Run snapshot.mjs → git commit + tag in the project repository
+ *   2. Write detailed log to logs/hook.log (CWD)
+ *
+ * Claude Code / CodeBuddy version — uses CODEBUDDY_PROJECT_DIR / CLAUDE_PROJECT_DIR.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { advanceRing } from '../../skills/_shared/scripts/state-store.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const LABELS = {
+  'ring-1': 'Ring 1',
+  'ring-2': 'Ring 2',
+  'ring-3': 'Ring 3',
+  'ring-4': 'Ring 4',
+};
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function load() {
+  if (process.env.GATE_CTX) { try { return JSON.parse(process.env.GATE_CTX); } catch {} }
+  try { const r = fs.readFileSync(0,'utf8').trim(); if (r) return JSON.parse(r); } catch {}
+  return null;
+}
+
+function resolveProjectDir(ctx) {
+  const pd = ctx?.projectDir || process.env.CODEBUDDY_PROJECT_DIR || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  if (process.platform === 'win32' && /^\/[a-zA-Z]\//.test(pd))
+    return pd[1].toUpperCase() + ':' + pd.slice(2).replace(/\//g, '\\');
+  return path.resolve(pd);
+}
+
+function answer(ctx) {
+  const text = typeof ctx?.toolResponse === 'string'
+    ? ctx.toolResponse
+    : JSON.stringify(ctx?.toolResponse || '');
+  const m = text.match(/ → (.+)$/);
+  if (m) return m[1].trim();
+  return text || null;
+}
+
+function questionText(ctx) {
+  const qs = ctx?.toolInput?.questions;
+  if (!qs?.length) return '';
+  return qs.map(q => q.question || '').join('; ').slice(0, 200);
+}
+
+function headerText(ctx) {
+  const qs = ctx?.toolInput?.questions;
+  if (!qs?.length) return '';
+  const h = qs[0].header || '';
+  if (h) return h;
+  return (qs[0].question || '').slice(0, 20);
+}
+
+function sanitize(text, maxLen = 20) {
+  return (text || '')
+    .replace(/[^\w一-鿿 -]/g, '')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, maxLen)
+    .replace(/-$/, '');
+}
+
+function iterationFromGateKey(gateKey) {
+  const match = String(gateKey || '').match(/^ring-(\d)$/);
+  return match ? Number(match[1]) : null;
+}
+
+function isAcceptedAnswer(text) {
+  const value = String(text || '').toLowerCase();
+  if (!value) return false;
+  if (/(reject|decline|no|fail|拒绝|不接受|不同意|否)/i.test(value)) return false;
+  return /(accept|accepted|approve|approved|yes|pass|proceed|continue|接受|通过|同意|确认|继续)/i.test(value);
+}
+
+// ── snapshot ─────────────────────────────────────────────────────────────────
+
+function runSnapshot(projectDir, gateKey, ctx, ans) {
+  const snapScript = path.join(__dirname, '..', 'snapshot.mjs');
+
+  if (!fs.existsSync(snapScript)) {
+    console.error(`[snap] not found: ${snapScript}`);
+    return null;
+  }
+
+  const hdr = sanitize(headerText(ctx), 20);
+  const parts = ['gate', hdr];
+  if (ans) parts.push(sanitize(ans, 15));
+  const snapName = parts.filter(Boolean).join('_');
+
+  const r = spawnSync('node', [
+    snapScript, '--project', projectDir, '--name', snapName, '--force',
+  ], { encoding: 'utf8', timeout: 120_000, stdio: 'pipe' });
+
+  if (r.status !== 0) {
+    console.error(`[snap] failed: ${r.stderr?.slice(0, 200)}`);
+    return null;
+  }
+
+  const m = r.stdout.match(/Tag\s*:\s*(\S+)/);
+  const tagName = m ? m[1] : null;
+  if (tagName) console.error(`[snap] ${tagName}`);
+  return tagName;
+}
+
+// ── log ──────────────────────────────────────────────────────────────────────
+
+function writeHookLog(projectDir, entry) {
+  const logPath = path.join(projectDir, 'logs', 'hook.log');
+  const dir = path.dirname(logPath);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.appendFileSync(logPath, entry + '\n');
+}
+
+// ── main ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const ctx = load();
+  const gk = ctx?.gateKey || process.env.GATE_KEY;
+  if (!gk) return;
+
+  const pd = resolveProjectDir(ctx);
+  const label = LABELS[gk] || gk;
+  const hdr = headerText(ctx);
+  const q = questionText(ctx);
+  const ans = answer(ctx);
+  const ts = new Date().toLocaleString('zh-CN', { timeZone: 'Asia/Shanghai' });
+
+  // Snapshot
+  const tagName = runSnapshot(pd, gk, ctx, ans);
+  const iteration = iterationFromGateKey(gk);
+  let advanceStatus = 'not-applicable';
+  if (iteration && isAcceptedAnswer(ans)) {
+    try {
+      const nextState = advanceRing(pd, { iteration, accepted: true });
+      advanceStatus = `advanced to iteration ${nextState.handoff.iteration} loop ${nextState.handoff.loop}`;
+    } catch (error) {
+      advanceStatus = `blocked: ${error.message}`;
+    }
+  } else if (iteration) {
+    advanceStatus = 'not accepted';
+  }
+
+  // Detailed log entry
+  const lines = [
+    '─'.repeat(60),
+    `[${ts}] GATE ${label}`,
+    `    Header  : ${hdr || '—'}`,
+    `    Question: ${q || '—'}`,
+    `    Answer  : ${ans || '—'}`,
+    `    Snapshot: ${tagName || 'FAILED'}`,
+    `    Advance : ${advanceStatus}`,
+    '─'.repeat(60),
+  ];
+  writeHookLog(pd, lines.join('\n'));
+}
+
+main().catch(e => { process.stderr.write('[gate] ' + e.message + '\n'); process.exitCode = 1; });

package/project-template/.claude/hooks/snapshot-milestone.mjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+/**
+ * PlayCraft milestone snapshot hook.
+ *
+ * Triggered on SubagentStop. Reads project-state.md
+ * → Agent handoff YAML to detect key milestones, then runs snapshot.mjs to archive
+ * current project state.
+ *
+ * Milestones (only snapshot once each):
+ *   - ring-1-archived   iteration >= 2 or archivedRings contains ring 1
+ *   - ring-2-archived   iteration >= 3 or archivedRings contains ring 2
+ *   - ring-3-archived   iteration >= 4 or archivedRings contains ring 3
+ *   - dev-ready         devStatus: ready (Dev Preview table)
+ *   - ring-4-done       ringGateVerdict pass on iteration 4
+ *
+ * Exit 0 always — snapshot failures are non-blocking.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function resolveProjectDir() {
+  const raw =
+    process.env.CODEBUDDY_PROJECT_DIR ||
+    process.env.CLAUDE_PROJECT_DIR ||
+    process.env.CURSOR_PROJECT_DIR ||
+    process.cwd();
+  if (process.platform === 'win32' && /^\/[a-zA-Z]\//.test(raw)) {
+    return raw[1].toUpperCase() + ':' + raw.slice(2).replace(/\//g, '\\');
+  }
+  return path.resolve(raw);
+}
+
+function readProjectState(projectDir) {
+  const statePath = path.join(projectDir, 'docs', 'project-state.md');
+  if (!fs.existsSync(statePath)) return null;
+  return fs.readFileSync(statePath, 'utf8');
+}
+
+/**
+ * Parse the `## Agent handoff` YAML block from project-state.md.
+ */
+function parseHandoff(content) {
+  const fenceStart = content.indexOf('```yaml');
+  if (fenceStart === -1) return null;
+
+  const afterFence = content.indexOf('\n', fenceStart);
+  if (afterFence === -1) return null;
+
+  const fenceEnd = content.indexOf('```', afterFence);
+  if (fenceEnd === -1) return null;
+
+  const yamlBlock = content.slice(afterFence, fenceEnd);
+
+  const result = {};
+  for (const line of yamlBlock.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const colonIdx = trimmed.indexOf(':');
+    if (colonIdx === -1) continue;
+
+    const key = trimmed.slice(0, colonIdx).trim();
+    let value = trimmed.slice(colonIdx + 1).trim();
+
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+
+    if (value === 'true') result[key] = true;
+    else if (value === 'false') result[key] = false;
+    else if (value === 'null' || value === '') result[key] = null;
+    else result[key] = value;
+  }
+  return result;
+}
+
+/** @param {string} content */
+function parseIteration(content) {
+  const handoff = parseHandoff(content);
+  if (handoff?.iteration) {
+    const n = Number(handoff.iteration);
+    if (Number.isFinite(n) && n >= 1) return n;
+  }
+  const m = content.match(/^\s*iteration:\s*(\d+)\s*$/im);
+  return m ? Number(m[1]) : 1;
+}
+
+/** @param {string} content @param {number} ring */
+function hasArchivedRing(content, ring) {
+  const lineMatch = content.match(/^\s*archivedRings:\s*(.+)\s*$/im);
+  if (lineMatch && new RegExp(`\\b${ring}\\s*:`).test(lineMatch[1])) {
+    return true;
+  }
+  const tableRe = new RegExp(`^\\|\\s*${ring}\\s*\\|`, 'm');
+  return tableRe.test(content);
+}
+
+/** @param {string} content */
+function parseDevStatus(content) {
+  const m = content.match(/^\|\s*devStatus\s*\|\s*(\w+)\s*\|/im);
+  return m ? m[1].toLowerCase() : null;
+}
+
+/** @param {string} content */
+function parseRingGateVerdict(content) {
+  const m = content.match(/^\|\s*ringGateVerdict\s*\|\s*(\w+)\s*\|/im);
+  return m ? m[1].toLowerCase() : null;
+}
+
+/**
+ * Determine which milestones have been reached based on current state.
+ * @param {string} content
+ */
+function detectMilestones(content) {
+  const milestones = [];
+  const iteration = parseIteration(content);
+
+  if (iteration >= 2 || hasArchivedRing(content, 1)) {
+    milestones.push('ring-1-archived');
+  }
+  if (iteration >= 3 || hasArchivedRing(content, 2)) {
+    milestones.push('ring-2-archived');
+  }
+  if (iteration >= 4 || hasArchivedRing(content, 3)) {
+    milestones.push('ring-3-archived');
+  }
+
+  if (parseDevStatus(content) === 'ready') {
+    milestones.push('dev-ready');
+  }
+
+  if (iteration >= 4 && parseRingGateVerdict(content) === 'pass') {
+    milestones.push('ring-4-done');
+  }
+
+  return milestones;
+}
+
+function loadSnapshotState(projectDir) {
+  const statePath = path.join(projectDir, '.claude', 'hooks', '.snapshot-state.json');
+  try {
+    if (fs.existsSync(statePath)) {
+      return JSON.parse(fs.readFileSync(statePath, 'utf8'));
+    }
+  } catch {
+    // ignore
+  }
+  return {};
+}
+
+function saveSnapshotState(projectDir, state) {
+  const statePath = path.join(projectDir, '.claude', 'hooks', '.snapshot-state.json');
+  const dir = path.dirname(statePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
+}
+
+function resolveSnapshotScript() {
+  const local = path.resolve(__dirname, '..', 'snapshot.mjs');
+  if (fs.existsSync(local)) return local;
+
+  const candidate = path.resolve(__dirname, '..', '..', '..', 'snapshot.mjs');
+  if (fs.existsSync(candidate)) return candidate;
+
+  return null;
+}
+
+function runSnapshot(projectDir, label) {
+  const snapshotScript = resolveSnapshotScript();
+
+  if (!snapshotScript) {
+    process.stderr.write('[snapshot-milestone] snapshot script not found\n');
+    return false;
+  }
+
+  const result = spawnSync('node', [
+    snapshotScript,
+    '--project', projectDir,
+    '--name', label,
+    '--force',  // non-interactive hook — skip active-CLI check
+  ], {
+    encoding: 'utf8',
+    timeout: 120_000,  // git add/commit may be slower than zip
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  if (result.status !== 0) {
+    process.stderr.write(`[snapshot-milestone] snapshot failed (${label}): ${result.stderr}\n`);
+    return false;
+  }
+
+  process.stderr.write(`[snapshot-milestone] snapshot committed: ${label}\n`);
+  if (result.stdout) {
+    process.stderr.write(result.stdout);
+  }
+  return true;
+}
+
+function main() {
+  const projectDir = resolveProjectDir();
+  const content = readProjectState(projectDir);
+
+  if (!content) {
+    process.exit(0);
+  }
+
+  const currentMilestones = detectMilestones(content);
+
+  if (currentMilestones.length === 0) {
+    process.exit(0);
+  }
+
+  const snapshotState = loadSnapshotState(projectDir);
+  let anyNew = false;
+
+  for (const milestone of currentMilestones) {
+    if (snapshotState[milestone]) {
+      continue;
+    }
+
+    anyNew = true;
+    const ok = runSnapshot(projectDir, milestone);
+    if (ok) {
+      snapshotState[milestone] = new Date().toISOString();
+    }
+  }
+
+  if (anyNew) {
+    saveSnapshotState(projectDir, snapshotState);
+  }
+
+  process.exit(0);
+}
+
+main();

package/project-template/.claude/hooks/user-prompt.mjs

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+/**
+ * PlayCraft User Prompt Hook — fires on every UserPromptSubmit.
+ *
+ * Actions:
+ *   1. Increment turn counter, log to logs/hook.log
+ *   2. Snapshot (always, for full audit trail)
+ *      Output goes to ../ to avoid nesting.
+ *
+ * Claude Code / CodeBuddy version — uses CODEBUDDY_PROJECT_DIR / CLAUDE_PROJECT_DIR.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import {
+  parseHandoffBlock,
+  parseHandoffYaml,
+  resolveProjectStatePath,
+} from '../../skills/_shared/scripts/state-handoff.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function resolveProjectDir() {
+  const raw = process.env.CODEBUDDY_PROJECT_DIR || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  if (process.platform === 'win32' && /^\/[a-zA-Z]\//.test(raw))
+    return raw[1].toUpperCase() + ':' + raw.slice(2).replace(/\//g, '\\');
+  return path.resolve(raw);
+}
+
+function loadState(projectDir) {
+  const p = path.join(projectDir, '.claude', 'logs', 'session.json');
+  try { if (fs.existsSync(p)) return JSON.parse(fs.readFileSync(p, 'utf8')); }
+  catch {}
+  return { turns: 0 };
+}
+
+function saveState(projectDir, state) {
+  const d = path.join(projectDir, '.claude', 'logs');
+  fs.mkdirSync(d, { recursive: true });
+  fs.writeFileSync(path.join(d, 'session.json'), JSON.stringify(state, null, 2));
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const raw = Buffer.concat(chunks).toString('utf8');
+  try { return raw.trim() ? JSON.parse(raw) : null; }
+  catch { return null; }
+}
+
+function sanitize(text, maxLen = 20) {
+  return (text || '')
+    .replace(/[^\w一-鿿 -]/g, '')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, maxLen)
+    .replace(/-$/, '');
+}
+
+// ── snapshot ─────────────────────────────────────────────────────────────────
+
+function runSnapshot(projectDir, state, promptText) {
+  const snapScript = path.join(__dirname, '..', 'snapshot.mjs');
+
+  if (!fs.existsSync(snapScript)) {
+    console.error('[snap] script not found');
+    return null;
+  }
+
+  const prefix = sanitize(promptText, 20);
+  const snapName = prefix ? `prompt_${prefix}` : `prompt_turn-${state.turns}`;
+
+  const r = spawnSync('node', [
+    snapScript, '--project', projectDir, '--name', snapName, '--force',
+  ], { encoding: 'utf8', timeout: 120_000, stdio: 'pipe' });
+
+  if (r.status !== 0) {
+    console.error(`[snap] failed: ${r.stderr?.slice(0, 200)}`);
+    return null;
+  }
+  const m = r.stdout.match(/Tag\s*:\s*(\S+)/);
+  const tagName = m ? m[1] : null;
+  if (tagName) console.error(`[snap] ${tagName}`);
+  return tagName;
+}
+
+// ── log ──────────────────────────────────────────────────────────────────────
+
+function writeHookLog(projectDir, entry) {
+  const logPath = path.join(projectDir, 'logs', 'hook.log');
+  const dir = path.dirname(logPath);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.appendFileSync(logPath, entry + '\n');
+}
+
+// ── Ring 1 direct-path injection ─────────────────────────────────────────────
+
+function readHandoffState(projectDir) {
+  const statePath = resolveProjectStatePath(projectDir);
+  if (!fs.existsSync(statePath)) {
+    return { iteration: 1, loop: 'clarify' };
+  }
+  const block = parseHandoffBlock(fs.readFileSync(statePath, 'utf8'));
+  if (!block) {
+    return { iteration: 1, loop: 'clarify' };
+  }
+  const handoff = parseHandoffYaml(block.yaml);
+  const iteration = Number.parseInt(String(handoff.iteration || '1'), 10) || 1;
+  const loop = String(handoff.loop || 'clarify').trim().toLowerCase() || 'clarify';
+  return { iteration, loop };
+}
+
+function ring1DirectPathContext(projectDir) {
+  const { loop } = readHandoffState(projectDir);
+
+  const loopGuides = {
+    clarify:
+      '- loop=clarify: Invoke @game-designer for concise gameplay lock. After GD STOP, spawn a temporary ref-flow atom-selection subagent for compact atom-tree selection. Do NOT write docs/DESIGN.md or docs/atom-tree.json as orchestrator.',
+    build:
+      '- loop=build: If scaffold not done, ensure the temporary atom-selection subagent has stopped, then run validate-atom-tree-selection → init-template → verify:contract → verify:lifecycle. Then Invoke @developer for ring 1 build.',
+    verify:
+      '- loop=verify: After @developer STOP, run npm run ring:gate -- --iteration 1 (no @reviewer in ring 1).',
+  };
+  const loopGuide = loopGuides[loop] || loopGuides.clarify;
+
+  return `[PlayCraft Ring 1 Dispatch Path — harness auto-injected]
+iteration=1 loop=${loop}: you are the orchestrator — dispatch role subagents, do NOT inline Designer/Developer work.
+- Do NOT create internal Task lists (TaskCreate / TaskUpdate / TaskList / TaskGet / TaskOutput / TaskStop).
+- Task / @game-designer / temporary ref-flow atom-selection subagent / @developer spawn IS required when the table below says invoke.
+- First command: npm run state:get — use next_orchestrator_action + summary; do NOT open docs/project-state.md in full.
+${loopGuide}
+- Game Designer owns docs/DESIGN.md. The temporary atom-selection subagent owns compact docs/atom-tree.json. Developer owns game/ + verifiers on STOP.
+- No Ring 2+ docs, no Reviewer / Artist / TA, no record:mp4 in ring 1.
+See CLAUDE.md § Ring 1 Dispatch Path and .cursor/rules/playcraft-orchestrator.mdc.`;
+}
+
+function emitAdditionalContext(text) {
+  process.stdout.write(`${JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext: text,
+    },
+  })}\n`);
+}
+
+// ── main ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const payload = await readStdin();
+  if (!payload) return;
+  const promptText = payload.prompt || payload.user_prompt || '';
+  if (!promptText) return;
+
+  const projectDir = resolveProjectDir();
+  const state = loadState(projectDir);
+  state.turns += 1;
+  state.lastPromptAt = new Date().toISOString();
+
+  const ts = new Date().toLocaleString('zh-CN', { timeZone: 'Asia/Shanghai' });
+  const preview = promptText.replace(/\n/g, '\\n').slice(0, 300);
+
+  // Snapshot (always)
+  const tagName = runSnapshot(projectDir, state, promptText);
+  if (tagName) state.lastSnapAt = ts;
+
+  // Detailed log entry
+  const lines = [
+    '─'.repeat(60),
+    `[${ts}] PROMPT #${state.turns}`,
+    `    Input : ${preview}`,
+    `    Snapshot: ${tagName || 'FAILED'}`,
+    '─'.repeat(60),
+  ];
+  writeHookLog(projectDir, lines.join('\n'));
+
+  const { iteration } = readHandoffState(projectDir);
+  if (iteration === 1) {
+    emitAdditionalContext(ring1DirectPathContext(projectDir));
+  }
+
+  console.error(`prompt #${state.turns} logged`);
+  saveState(projectDir, state);
+}
+
+main().catch(e => { process.stderr.write('[user-prompt] ' + e.message + '\n'); process.exitCode = 1; });