@playcraft/cli 0.1.24 → 0.1.25

package/project-template-v2/skills/_shared/scripts/todo-add.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * todo:add — add a todo to the pool.
+ *
+ * Write权限由 hook(后续)按 spec.stage.canWriteTodo 白名单校验;本脚本只负责写入。
+ *
+ * Usage:
+ *   npm run todo:add -- id=core-action-v1 role=developer title="tap feedback" \
+ *     goal="player can tap a target and see progress" context="Scope and implementation notes..." \
+ *     acceptance="feedback visible;progress+1" verifier=verify:contract \
+ *     requiredContext="docs/design.md#core-loop;skills/example/SKILL.md" \
+ *     contextReuse=core-loop \
+ *     createdBy=game-designer
+ */
+import { resolve } from 'node:path';
+import fs from 'node:fs';
+import { addTodo, readState } from './state-store.mjs';
+
+const TODO_ID_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), kv: {} };
+  for (const arg of argv) {
+    if (arg === '--') continue;
+    if (arg.startsWith('--root=')) { opts.root = arg.slice('--root='.length); continue; }
+    if (arg === '--help' || arg === '-h') {
+      console.log('Usage: todo-add.mjs [--root=.] id=<kebab-id> role=<role> title="..." [goal="..."] (context="..."|contextFile=<path>) [acceptance="a;b"] [requiredContext="x;y"] [contextReuse="<key-or-note>"] [verifier=verify:contract] [createdBy=<role>]');
+      console.log('  id format: lowercase kebab-case, e.g. core-loop, setup-engine, firstwin-harness. This keeps todo ids stable for dispatch and todo index rows.');
+      process.exit(0);
+    }
+    const m = arg.match(/^([a-zA-Z0-9_]+)=([\s\S]*)$/);
+    if (m) opts.kv[m[1]] = m[2];
+  }
+  return opts;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const root = resolve(opts.root);
+  if (!opts.kv.id) { console.error('[todo:add] id= is required'); process.exit(1); }
+  if (!String(opts.kv.title || '').trim()) {
+    console.error('[todo:add] title= is required');
+    process.exit(1);
+  }
+  if (!TODO_ID_PATTERN.test(opts.kv.id)) {
+    console.error('[todo:add] id must be lowercase kebab-case: /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/');
+    console.error('           examples: core-loop, setup-engine, firstwin-harness');
+    process.exit(1);
+  }
+  const currentState = readState(root);
+  const currentIteration = Number(currentState.pipeline?.iteration) || 1;
+  if ((currentState.todos || []).some((todo) => (
+    todo.id === opts.kv.id && Number(todo.iteration ?? currentIteration) === currentIteration
+  ))) {
+    console.error(`[todo:add] id "${opts.kv.id}" already exists in iteration ${currentIteration}`);
+    process.exit(1);
+  }
+  let context = opts.kv.context || '';
+  if (opts.kv.contextFile) {
+    const contextPath = resolve(root, opts.kv.contextFile);
+    try {
+      context = fs.readFileSync(contextPath, 'utf8');
+    } catch (error) {
+      console.error(`[todo:add] failed to read contextFile: ${error.message}`);
+      process.exit(1);
+    }
+  }
+  if (!context.trim()) {
+    console.error('[todo:add] context or contextFile is required; it must preserve the full task slice semantics.');
+    process.exit(1);
+  }
+  const state = addTodo(root, {
+    id: opts.kv.id,
+    role: opts.kv.role || 'developer',
+    title: opts.kv.title || '',
+    goal: opts.kv.goal || '',
+    context,
+    requiredContext: opts.kv.requiredContext || [],
+    contextReuse: opts.kv.contextReuse || '',
+    acceptance: opts.kv.acceptance || [],
+    verifier: opts.kv.verifier || 'verify:contract',
+    createdBy: opts.kv.createdBy || 'unknown',
+  });
+  const todo = state.todos.find((t) => t.id === opts.kv.id);
+  console.log(`[todo:add] ${todo.id} (${todo.role}) added by ${todo.createdBy}`);
+}
+
+main();

package/project-template-v2/skills/_shared/scripts/todo-get.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * todo:get — orchestrator/debug helper for inspecting todo state.
+ *
+ * Usage:
+ *   npm run todo:get
+ *   npm run todo:get -- core-action-v1
+ *   npm run todo:get -- id=core-action-v1 --json
+ */
+
+import { resolve } from 'node:path';
+import { readState } from './state-store.mjs';
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), id: '', json: false, allIterations: false };
+  for (const arg of argv) {
+    if (arg === '--') continue;
+    if (arg.startsWith('--root=')) { opts.root = arg.slice('--root='.length); continue; }
+    if (arg === '--json') { opts.json = true; continue; }
+    if (arg === '--all') { opts.allIterations = true; continue; }
+    if (arg === '--help' || arg === '-h') {
+      console.log('Usage: todo-get.mjs [--root=.] [id|id=<id>] [--json] [--all]');
+      console.log('  No id: compact queue summary. With id: full todo context for orchestrator/debug inspection.');
+      process.exit(0);
+    }
+    const m = arg.match(/^([a-zA-Z0-9_]+)=([\s\S]*)$/);
+    if (m && m[1] === 'id') opts.id = m[2];
+    else if (!arg.startsWith('-') && !opts.id) opts.id = arg;
+  }
+  return opts;
+}
+
+function summarizeTodo(todo) {
+  return {
+    id: todo.id,
+    iteration: todo.iteration,
+    stage: todo.stage,
+    role: todo.role,
+    title: todo.title,
+    goal: todo.goal,
+    status: todo.status,
+    contextReuse: todo.contextReuse || '',
+    verifier: todo.verifier || '',
+  };
+}
+
+function currentIterationTodos(state, allIterations) {
+  if (allIterations) return state.todos || [];
+  const iteration = Number(state.pipeline?.iteration) || 1;
+  return (state.todos || []).filter((todo) => Number(todo.iteration ?? iteration) === iteration);
+}
+
+function findTodo(state, id) {
+  const iteration = Number(state.pipeline?.iteration) || 1;
+  return (state.todos || []).find((todo) => todo.id === id && Number(todo.iteration ?? iteration) === iteration)
+    ?? (state.todos || []).find((todo) => todo.id === id)
+    ?? null;
+}
+
+function listText(state, todos) {
+  const iteration = Number(state.pipeline?.iteration) || 1;
+  if (!todos.length) return `TODO Pool (iteration ${iteration})\n\n_no todos_`;
+  const rows = todos.map((todo) => [
+    todo.id,
+    `@${todo.role}`,
+    todo.status,
+    todo.contextReuse || '-',
+    todo.title || '-',
+    todo.goal || '-',
+  ]);
+  const widths = [2, 4, 6, 12, 5, 4].map((min, idx) => (
+    Math.max(min, ...rows.map((row) => String(row[idx]).length))
+  ));
+  const line = (cols) => cols.map((col, idx) => String(col).padEnd(widths[idx])).join('  ');
+  return [
+    `TODO Pool (iteration ${iteration})`,
+    '',
+    line(['id', 'role', 'status', 'contextReuse', 'title', 'goal']),
+    line(widths.map((width) => '-'.repeat(width))),
+    ...rows.map(line),
+  ].join('\n');
+}
+
+function detailText(todo) {
+  return [
+    `TODO ${todo.id}`,
+    '',
+    `title: ${todo.title || '-'}`,
+    `role: @${todo.role}`,
+    `status: ${todo.status}`,
+    `iteration: ${todo.iteration}`,
+    `stage: ${todo.stage || '-'}`,
+    `createdBy: ${todo.createdBy || '-'}`,
+    `contextReuse: ${todo.contextReuse || '-'}`,
+    '',
+    'goal:',
+    todo.goal || '-',
+    '',
+    'requiredContext:',
+    (todo.requiredContext || []).length ? todo.requiredContext.map((item) => `- ${item}`).join('\n') : '-',
+    '',
+    'acceptance:',
+    (todo.acceptance || []).length ? todo.acceptance.map((item) => `- ${item}`).join('\n') : '-',
+    '',
+    `verifier: ${todo.verifier || '-'}`,
+    '',
+    'context:',
+    todo.context || '-',
+  ].join('\n');
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const state = readState(resolve(opts.root));
+
+  if (opts.id) {
+    const todo = findTodo(state, opts.id);
+    if (!todo) {
+      console.error(`[todo:get] todo "${opts.id}" not found`);
+      process.exit(1);
+    }
+    console.log(opts.json ? JSON.stringify(todo, null, 2) : detailText(todo));
+    return;
+  }
+
+  const todos = currentIterationTodos(state, opts.allIterations);
+  console.log(opts.json ? JSON.stringify(todos.map(summarizeTodo), null, 2) : listText(state, todos));
+}
+
+main();

package/project-template-v2/skills/_shared/scripts/todo-remove.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * todo:remove — remove a todo from the pool by id.
+ *
+ * Usage: npm run todo:remove -- id=core-action-v1
+ */
+import { resolve } from 'node:path';
+import { removeTodo } from './state-store.mjs';
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), kv: {} };
+  for (const arg of argv) {
+    if (arg === '--') continue;
+    if (arg.startsWith('--root=')) { opts.root = arg.slice('--root='.length); continue; }
+    if (arg === '--help' || arg === '-h') {
+      console.log('Usage: todo-remove.mjs [--root=.] id=<id>');
+      process.exit(0);
+    }
+    const m = arg.match(/^([a-zA-Z0-9_]+)=([\s\S]*)$/);
+    if (m) opts.kv[m[1]] = m[2];
+  }
+  return opts;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const root = resolve(opts.root);
+  if (!opts.kv.id) { console.error('[todo:remove] id= is required'); process.exit(1); }
+  removeTodo(root, opts.kv.id);
+  console.log(`[todo:remove] ${opts.kv.id} removed`);
+}
+
+main();

package/project-template-v2/skills/_shared/scripts/todo-set.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * todo:set — mark a todo's state.
+ *
+ * subagent 执行完即 status=done(调度者不复核);失败用 status=failed。
+ * 无自动晋升 —— 下一个 todo 由调度者派发(setDispatch),不在此处自动推进。
+ *
+ * Usage:
+ *   npm run todo:set -- id=core-action-v1 status=done
+ *   npm run todo:set -- id=core-action-v1 status=failed
+ */
+import { resolve } from 'node:path';
+import { markTodoState } from './state-store.mjs';
+
+const VALID = new Set(['pending', 'in_progress', 'done', 'failed']);
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), kv: {} };
+  for (const arg of argv) {
+    if (arg === '--') continue;
+    if (arg.startsWith('--root=')) { opts.root = arg.slice('--root='.length); continue; }
+    if (arg === '--help' || arg === '-h') {
+      console.log('Usage: todo-set.mjs [--root=.] id=<id> status=<pending|in_progress|done|failed>');
+      process.exit(0);
+    }
+    const m = arg.match(/^([a-zA-Z0-9_]+)=([\s\S]*)$/);
+    if (m) opts.kv[m[1]] = m[2];
+  }
+  return opts;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const root = resolve(opts.root);
+  if (!opts.kv.id) { console.error('[todo:set] id= is required'); process.exit(1); }
+  if (!VALID.has(opts.kv.status)) {
+    console.error(`[todo:set] status must be one of: ${[...VALID].join(', ')}`);
+    process.exit(1);
+  }
+  const state = markTodoState(root, opts.kv.id, {
+    status: opts.kv.status,
+  });
+  const todo = state.todos.find((t) => t.id === opts.kv.id);
+  console.log(`[todo:set] ${todo.id} → status=${todo.status}`);
+}
+
+main();

package/project-template-v2/skills/_shared/scripts/verify-asset-code-sync.mjs

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+/**
+ * Asset ↔ code consistency gate (Ring 4).
+ *
+ * Checks:
+ *  1. assets/images/tiles/* filenames match TILE_KEYS (or similar) in game code
+ *  2. load.image / load.atlas paths in game/** resolve on disk
+ *  3. Orphan tiles on disk not referenced in code → fail
+ *  4. Optional assets/asset-manifest.json runtime assets are wired in game code
+ *
+ * Exit 0 = pass, 2 = fail
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+function parseArgs(argv) {
+  let root = process.cwd();
+  for (let i = 2; i < argv.length; i += 1) {
+    if (argv[i] === '--root' || argv[i] === '--project') {
+      root = argv[i + 1] || root;
+      i += 1;
+    } else if (argv[i].startsWith('--root=')) {
+      root = argv[i].slice('--root='.length);
+    }
+  }
+  return { root: path.resolve(root) };
+}
+
+function walkTsFiles(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const name of fs.readdirSync(dir)) {
+    const full = path.join(dir, name);
+    const st = fs.statSync(full);
+    if (st.isDirectory()) walkTsFiles(full, out);
+    else if (/\.(ts|js|tsx|jsx)$/.test(name)) out.push(full);
+  }
+  return out;
+}
+
+function extractTileKeys(content) {
+  const keys = new Set();
+  const arrayMatch = content.match(/TILE_KEYS\s*=\s*\[([\s\S]*?)\]/);
+  if (arrayMatch) {
+    for (const m of arrayMatch[1].matchAll(/['"]([^'"]+)['"]/g)) {
+      keys.add(m[1]);
+    }
+  }
+  const constMatch = content.match(/const\s+TILE_KEYS\s*:\s*[^=]*=\s*\[([\s\S]*?)\]/);
+  if (constMatch) {
+    for (const m of constMatch[1].matchAll(/['"]([^'"]+)['"]/g)) {
+      keys.add(m[1]);
+    }
+  }
+  return keys;
+}
+
+function extractLoadPaths(content) {
+  const paths = new Set();
+  const re =
+    /this\.load\.(?:image|atlas|spritesheet|audio|bitmapFont)\(\s*['"][^'"]+['"]\s*,\s*['"]([^'"]+)['"]/g;
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    paths.add(m[1].replace(/^\//, ''));
+  }
+  return paths;
+}
+
+function normalizeRelPath(rel) {
+  return String(rel || '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '');
+}
+
+function pathWithoutAssets(rel) {
+  return normalizeRelPath(rel).replace(/^assets\//, '');
+}
+
+function assetStem(rel) {
+  return path.basename(normalizeRelPath(rel), path.extname(rel));
+}
+
+function loadPathMatches(loadPath, manifestPath) {
+  const load = normalizeRelPath(loadPath);
+  const manifest = normalizeRelPath(manifestPath);
+  return load === manifest || load === pathWithoutAssets(manifest) || load.endsWith(`/${pathWithoutAssets(manifest)}`);
+}
+
+function sourceReferencesAsset(source, manifestPath) {
+  const rel = normalizeRelPath(manifestPath);
+  const noAssets = pathWithoutAssets(rel);
+  const base = path.basename(rel);
+  const stem = assetStem(rel);
+  return (
+    source.includes(rel) ||
+    source.includes(noAssets) ||
+    source.includes(base) ||
+    (stem.length >= 3 && source.includes(stem))
+  );
+}
+
+function tileKeyMatchesAsset(tileKeys, manifestPath) {
+  const stem = assetStem(manifestPath);
+  const normalized = stem.replace(/^tile_/, '');
+  return [...tileKeys].some(
+    (key) => key === stem || key === normalized || stem.endsWith(`_${key}`) || stem === `tile_${key}`,
+  );
+}
+
+function resolveAssetPath(root, rel) {
+  const candidates = [
+    path.join(root, rel),
+    path.join(root, 'assets', rel.replace(/^assets\//, '')),
+    path.join(root, 'public', rel),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  return null;
+}
+
+function readAssetManifest(root, failures) {
+  const manifestPath = path.join(root, 'assets/asset-manifest.json');
+  if (!fs.existsSync(manifestPath)) return null;
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch (err) {
+    failures.push(`asset-manifest.json invalid JSON: ${err.message}`);
+    return null;
+  }
+
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    failures.push('asset-manifest.json top-level must be an object');
+    return null;
+  }
+  if (!manifest.assets || typeof manifest.assets !== 'object' || Array.isArray(manifest.assets)) {
+    failures.push('asset-manifest.json: assets must be an object keyed by numericId');
+    return null;
+  }
+
+  return manifest;
+}
+
+function validateManifestRuntimeAssets(root, manifest, sourceText, loadPaths, tileKeys, failures) {
+  if (!manifest) return;
+
+  const allowedUsage = new Set(['runtime', 'reference-only']);
+  for (const [id, entry] of Object.entries(manifest.assets || {})) {
+    if (!/^\d+$/.test(String(id))) {
+      failures.push(`asset-manifest.json: asset key "${id}" is not a numericId`);
+    }
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      failures.push(`asset-manifest.json: asset ${id} must be an object`);
+      continue;
+    }
+
+    const rel = normalizeRelPath(entry.path);
+    const usage = entry.usage || 'runtime';
+    if (!allowedUsage.has(usage)) {
+      failures.push(`asset-manifest.json: asset ${id} usage "${usage}" must be runtime or reference-only`);
+    }
+    if (!rel) {
+      failures.push(`asset-manifest.json: asset ${id} missing path`);
+      continue;
+    }
+    if (!resolveAssetPath(root, rel)) {
+      failures.push(`asset-manifest.json: asset ${id} path missing on disk: ${rel}`);
+      continue;
+    }
+
+    const loaded = [...loadPaths].some((loadPath) => loadPathMatches(loadPath, rel));
+    const referenced = sourceReferencesAsset(sourceText, rel);
+    const tileMatched = entry.role === 'tile' && tileKeyMatchesAsset(tileKeys, rel);
+
+    if (usage === 'reference-only') {
+      if (loaded) {
+        failures.push(`Runtime load references reference-only manifest asset ${id}: ${rel}`);
+      }
+      continue;
+    }
+
+    if (!loaded && !referenced && !tileMatched) {
+      failures.push(`Runtime manifest asset ${id} is not referenced by game code: ${rel}`);
+    }
+  }
+}
+
+function listTileFiles(root) {
+  const dir = path.join(root, 'assets/images/tiles');
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => /\.(webp|png|jpg)$/i.test(f))
+    .map((f) => path.basename(f, path.extname(f)));
+}
+
+function main() {
+  const { root } = parseArgs(process.argv);
+  const failures = [];
+  const gameDir = path.join(root, 'game');
+
+  const tileKeys = new Set();
+  const loadPaths = new Set();
+  const sourceChunks = [];
+  for (const file of walkTsFiles(gameDir)) {
+    const content = fs.readFileSync(file, 'utf8');
+    sourceChunks.push(content);
+    for (const k of extractTileKeys(content)) tileKeys.add(k);
+    for (const p of extractLoadPaths(content)) loadPaths.add(p);
+  }
+  const sourceText = sourceChunks.join('\n');
+
+  const tileFiles = listTileFiles(root);
+  if (tileKeys.size > 0 && tileFiles.length > 0) {
+    for (const key of tileKeys) {
+      const hasFile = tileFiles.some((f) => f === key || f === `tile_${key}` || f.endsWith(`_${key}`));
+      if (!hasFile) {
+        failures.push(`TILE_KEYS contains "${key}" but no matching file under assets/images/tiles/`);
+      }
+    }
+    for (const file of tileFiles) {
+      const normalized = file.replace(/^tile_/, '');
+      const matched = [...tileKeys].some(
+        (k) => k === file || k === normalized || file.endsWith(`_${k}`) || file === `tile_${k}`,
+      );
+      if (!matched) {
+        failures.push(`Orphan tile asset "${file}" not referenced in TILE_KEYS`);
+      }
+    }
+  }
+
+  for (const rel of loadPaths) {
+    if (!resolveAssetPath(root, rel)) {
+      failures.push(`game load path missing on disk: ${rel}`);
+    }
+  }
+
+  const referencesDir = path.join(root, 'assets/references');
+  if (fs.existsSync(referencesDir)) {
+    for (const rel of loadPaths) {
+      if (rel.includes('assets/references/') || rel.includes('references/')) {
+        failures.push(`Runtime load references reference-only asset: ${rel}`);
+      }
+    }
+  }
+
+  const manifest = readAssetManifest(root, failures);
+  validateManifestRuntimeAssets(root, manifest, sourceText, loadPaths, tileKeys, failures);
+
+  const ok = failures.length === 0;
+  const result = {
+    ok,
+    tileKeyCount: tileKeys.size,
+    tileFileCount: tileFiles.length,
+    loadPathCount: loadPaths.size,
+    manifestAssetCount: manifest ? Object.keys(manifest.assets || {}).length : 0,
+    failures,
+  };
+  console.log(JSON.stringify(result, null, 2));
+  if (ok) {
+    process.stderr.write('[verify:asset-sync] OK\n');
+  } else {
+    process.stderr.write(`[verify:asset-sync] FAIL — ${failures.length} issue(s)\n`);
+    for (const f of failures) process.stderr.write(`  ✗ ${f}\n`);
+  }
+  process.exit(ok ? 0 : 2);
+}
+
+main();