@playcraft/cli 0.0.44 → 0.0.46

package/project-templates/threejs/.claude/hooks/validate-atom-tree-selection.mjs

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+/**
+ * Atom-tree selection validator.
+ *
+ * Validates docs/atom-tree.json as the single structured handoff:
+ * - meta.selectedAtoms is a compact selected skill list
+ * - selected atoms exist in the local skills registry
+ * - selected atoms come from meta.skillsMatch.items when a match snapshot exists
+ *
+ * Exit 0 = pass
+ * Exit 2 = block
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+function parseHookInput(raw) {
+  if (!raw.trim()) return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+function normalizeRole(s) {
+  return String(s || '')
+    .toLowerCase()
+    .replace(/\s+/g, '-')
+    .replace(/_/g, '-');
+}
+
+function detectRole(input) {
+  const candidates = [
+    input.agent_type,
+    input.agent_name,
+    input.subagent_name,
+    input.subagent_type,
+    input.subagent,
+    input.role,
+  ].filter(Boolean);
+
+  for (const c of candidates) {
+    const n = normalizeRole(String(c));
+    if (
+      n === 'game-designer' ||
+      n.includes('game-designer') ||
+      n === 'skill-selector' ||
+      n.includes('skill-selector') ||
+      n === 'ref-flow' ||
+      n.includes('ref-flow')
+    ) {
+      return 'atom-tree-producer';
+    }
+  }
+
+  const blobs = [input.last_assistant_message, input.last_message, input.message, input.output]
+    .filter(Boolean)
+    .join('\n');
+  if (
+    /---\s*PLAYCRAFT_STOP\s*---/i.test(blobs) &&
+    /role:\s*(game-designer|skill-selector|ref-flow)\b/i.test(blobs)
+  ) {
+    return 'atom-tree-producer';
+  }
+  if (
+    /docs\/atom-tree\.json/i.test(blobs) &&
+    /---\s*PLAYCRAFT_STOP\s*---/i.test(blobs)
+  ) {
+    return 'atom-tree-producer';
+  }
+  return null;
+}
+
+function loadSkillAtomIds(projectDir) {
+  const dirs = [];
+  const envPaths = process.env.AGENT_SKILLS_PATHS?.split(',').map((p) => p.trim()).filter(Boolean) ?? [];
+  dirs.push(...envPaths);
+
+  for (const rel of [
+    ['node_modules', '@playcraft', 'skills', 'playcraft-skills'],
+    ['node_modules', '@playcraft', 'skills', 'skills'],
+  ]) {
+    const candidate = path.join(projectDir, ...rel);
+    if (fs.existsSync(candidate)) dirs.push(candidate);
+  }
+
+  const ids = new Set();
+  for (const dir of dirs) {
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) continue;
+    for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (!ent.isDirectory()) continue;
+      const manifestPath = path.join(dir, ent.name, 'manifest.json');
+      if (!fs.existsSync(manifestPath)) continue;
+      try {
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+        if (manifest.atomId) ids.add(manifest.atomId);
+      } catch {
+        // skip
+      }
+    }
+  }
+  return ids;
+}
+
+function collectTreeAtomRefs(value, refs = new Set()) {
+  if (!value || typeof value !== 'object') return refs;
+  if (Array.isArray(value)) {
+    for (const item of value) collectTreeAtomRefs(item, refs);
+    return refs;
+  }
+  const atom = value.atom;
+  if (typeof atom === 'string') refs.add(atom);
+  else if (atom && typeof atom === 'object') {
+    if (typeof atom.id === 'string') refs.add(atom.id);
+    if (typeof atom.substitute === 'string') refs.add(atom.substitute);
+  }
+  for (const child of Object.values(value)) collectTreeAtomRefs(child, refs);
+  return refs;
+}
+
+function validateInline(projectDir) {
+  const jsonPath = path.join(projectDir, 'docs', 'atom-tree.json');
+  const errors = [];
+  const warnings = [];
+
+  if (!fs.existsSync(jsonPath)) {
+    errors.push('缺少 docs/atom-tree.json（从 templates/atom-tree.template.json 创建）');
+    return { errors, warnings };
+  }
+
+  let tree;
+  try {
+    tree = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+  } catch (e) {
+    errors.push(`atom-tree.json 解析失败：${e.message}`);
+    return { errors, warnings };
+  }
+
+  const selectedAtoms = tree?.meta?.selectedAtoms;
+  if (!Array.isArray(selectedAtoms)) {
+    errors.push('meta.selectedAtoms 须为字符串数组');
+    return { errors, warnings };
+  }
+
+  const skillIndex = loadSkillAtomIds(projectDir);
+  if (skillIndex.size === 0) {
+    errors.push('未找到 skills 库（请 npm install @playcraft/skills 或设置 AGENT_SKILLS_PATHS）');
+    return { errors, warnings };
+  }
+
+  const snapshotIds = new Set((tree?.meta?.skillsMatch?.items ?? []).map((i) => i.atomId).filter(Boolean));
+  const seen = new Set();
+  for (const raw of selectedAtoms) {
+    const ref = typeof raw === 'string' ? raw.trim() : '';
+    if (!ref || ref.startsWith('{{')) continue;
+    if (seen.has(ref)) errors.push(`meta.selectedAtoms 重复：${ref}`);
+    seen.add(ref);
+    if (ref.startsWith('playcraft-')) {
+      errors.push(`禁止 playcraft-* 平台 skill：${ref}`);
+    } else if (!skillIndex.has(ref)) {
+      errors.push(`selected atom 不在 skills 库：${ref}`);
+    } else if (snapshotIds.size > 0 && !snapshotIds.has(ref)) {
+      errors.push(`selected atom ${ref} 不在 meta.skillsMatch.items 中`);
+    }
+  }
+
+  const treeRefs = collectTreeAtomRefs({
+    engine: tree.engine,
+    remixSpec: tree?.meta?.remixSpec,
+    globals: tree.globals,
+    scenes: tree.scenes,
+    review: tree.review,
+  });
+  for (const ref of treeRefs) {
+    if (!skillIndex.has(ref)) errors.push(`atom-tree 引用未知 atom：${ref}`);
+  }
+
+  if (selectedAtoms.length === 0) {
+    warnings.push('meta.selectedAtoms 为空 — 请先运行 playcraft skills select-atom');
+  }
+  if (!(tree?.meta?.skillsMatch?.items?.length > 0)) {
+    warnings.push('meta.skillsMatch.items 为空 — 请先 playcraft skills init-atom-tree');
+  }
+
+  return { errors, warnings };
+}
+
+function runCliValidator(projectDir) {
+  const r = spawnSync('playcraft', ['skills', 'validate-atom-tree-selection', '--project-dir', projectDir], {
+    encoding: 'utf8',
+    cwd: projectDir,
+  });
+  return { status: r.status ?? 1, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
+}
+
+/**
+ * Auto-link selected atom skills into .claude/skills/ so the agent never has to
+ * run `playcraft skills link` by hand. Idempotent + pruning; failures are advisory.
+ */
+function autoLinkSelectedAtoms(projectDir) {
+  const jsonPath = path.join(projectDir, 'docs', 'atom-tree.json');
+  if (!fs.existsSync(jsonPath)) return;
+  let selectedAtoms = [];
+  try {
+    const tree = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+    selectedAtoms = Array.isArray(tree?.meta?.selectedAtoms) ? tree.meta.selectedAtoms : [];
+  } catch {
+    return;
+  }
+  const real = selectedAtoms
+    .map((s) => (typeof s === 'string' ? s.trim() : ''))
+    .filter((s) => s && !s.startsWith('{{'));
+  if (real.length === 0) return;
+
+  const r = spawnSync(
+    'playcraft',
+    ['skills', 'link', '--from-atom-tree', '--prune', '--project-dir', projectDir],
+    { encoding: 'utf8', cwd: projectDir },
+  );
+  if (r.status === 0) {
+    const summary = (r.stdout || '').trim().split('\n').filter(Boolean).slice(-3).join(' ');
+    process.stderr.write(`[playcraft-atom-tree] auto-linked selected skills → .claude/skills/${summary ? ` (${summary})` : ''}\n`);
+  } else {
+    const detail = (r.stderr || r.stdout || r.error?.message || `exit ${r.status}`).toString().trim().split('\n').slice(-2).join(' ');
+    process.stderr.write(`[playcraft-atom-tree] warn: auto-link skipped — ${detail}\n`);
+  }
+}
+
+function emitBlock(reason) {
+  const payload = { decision: 'block', reason };
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+  process.stderr.write(`[playcraft-atom-tree] ${reason}\n`);
+  process.exit(2);
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+export { detectRole, validateInline };
+
+async function main() {
+  const stdin = await readStdin();
+  const input = parseHookInput(stdin);
+
+  const hookEvent = input.hook_event || input.event || '';
+  const isPostToolUse = /post.?tool/i.test(hookEvent) || /Write|Edit/i.test(input.tool_name || '');
+
+  if (!isPostToolUse) {
+    const role = detectRole(input);
+    if (role !== 'atom-tree-producer') process.exit(0);
+  }
+
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.env.CURSOR_PROJECT_DIR || process.cwd();
+  const inline = validateInline(projectDir);
+  for (const w of inline.warnings) process.stderr.write(`[playcraft-atom-tree] warn: ${w}\n`);
+  if (inline.errors.length > 0) {
+    emitBlock(inline.errors.join('; '));
+  }
+
+  const cli = runCliValidator(projectDir);
+  if (cli.status !== 0 && (cli.stderr || cli.stdout)) {
+    const detail = (cli.stderr || cli.stdout).trim() || 'playcraft skills validate-atom-tree-selection failed';
+    emitBlock(detail);
+  }
+
+  // Selection is valid — automatically link selected atom skills so the agent
+  // does not need to run `playcraft skills link` manually.
+  autoLinkSelectedAtoms(projectDir);
+
+  process.exit(0);
+}
+
+main().catch((err) => {
+  process.stderr.write(`[playcraft-atom-tree] ${err.message}\n`);
+  process.exit(2);
+});