@playcraft/cli 0.0.44 → 0.0.47

package/project-templates/threejs/skills/_shared/scripts/context-budget.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+/**
+ * Context budget meter — makes each agent role's "always-loaded" context cost
+ * visible, and audits the on-demand refs/skills pool so the layered design
+ * (L1 card = ownership only; refs read on demand) keeps paying off.
+ *
+ * Token cost is estimated from bytes (~4 chars/token). A file may override the
+ * estimate with `tokenCost:` frontmatter (`~5k` or `5000`); `readWhen:` is
+ * surfaced for display. Nothing needs annotating — measurement is automatic.
+ *
+ * Advisory by default (exit 0). With --strict, exits 2 if any budget is blown.
+ *
+ * Usage:
+ *   node skills/_shared/scripts/context-budget.mjs --root=.
+ *   node skills/_shared/scripts/context-budget.mjs --root=. --json
+ *   node skills/_shared/scripts/context-budget.mjs --root=. --strict --base-budget=30000
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join, resolve, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROLES = [
+  'game-designer',
+  'artist',
+  'technical-artist',
+  'developer',
+  'reviewer',
+];
+
+// Every sub-agent's First Step routes through these contract docs; count them
+// as part of each role's always-loaded base context.
+const SHARED_BASE_DOCS = ['docs/team/agent-conduct.md', 'docs/team/collaboration.md'];
+
+const DEFAULTS = { baseBudget: 30000, fileBudget: 8000 };
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), json: false, strict: false, ...DEFAULTS };
+  for (const arg of argv) {
+    if (arg.startsWith('--root=')) {
+      const v = arg.slice('--root='.length);
+      opts.root = v.startsWith('/') ? v : resolve(process.cwd(), v);
+    } else if (arg === '--json') opts.json = true;
+    else if (arg === '--strict') opts.strict = true;
+    else if (arg.startsWith('--base-budget=')) opts.baseBudget = Number(arg.split('=')[1]) || DEFAULTS.baseBudget;
+    else if (arg.startsWith('--file-budget=')) opts.fileBudget = Number(arg.split('=')[1]) || DEFAULTS.fileBudget;
+  }
+  return opts;
+}
+
+/** Rough token estimate: ~4 characters per token. */
+export function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+
+function frontmatter(text) {
+  const m = text.match(/^---\n([\s\S]*?)\n---/);
+  return m ? m[1] : '';
+}
+
+/** Parse an explicit `tokenCost:` override (`~5k` / `5000`) from frontmatter, if any. */
+function declaredTokenCost(fmText) {
+  const m = fmText.match(/tokenCost:\s*~?\s*([0-9.]+)\s*([kK])?/);
+  if (!m) return null;
+  const n = parseFloat(m[1]);
+  return Math.round(/k/i.test(m[2] || '') ? n * 1000 : n);
+}
+
+function declaredReadWhen(fmText) {
+  const m = fmText.match(/readWhen:\s*(.+)/);
+  return m ? m[1].trim().replace(/^['"]|['"]$/g, '') : null;
+}
+
+/** @returns {{ path: string, tokens: number, estimated: boolean, readWhen: string|null } | null} */
+function measure(root, rel) {
+  const abs = join(root, rel);
+  if (!existsSync(abs)) return null;
+  const text = readFileSync(abs, 'utf8');
+  const fm = frontmatter(text);
+  const declared = declaredTokenCost(fm);
+  return {
+    path: rel,
+    tokens: declared ?? estimateTokens(text),
+    estimated: declared == null,
+    readWhen: declaredReadWhen(fm),
+  };
+}
+
+function listMarkdown(root, relDir) {
+  const abs = join(root, relDir);
+  if (!existsSync(abs)) return [];
+  return readdirSync(abs)
+    .filter((f) => f.endsWith('.md'))
+    .map((f) => `${relDir}/${f}`)
+    .sort();
+}
+
+function listSkills(root) {
+  const abs = join(root, '.claude/skills');
+  if (!existsSync(abs)) return [];
+  const out = [];
+  for (const entry of readdirSync(abs, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const rel = `.claude/skills/${entry.name}/SKILL.md`;
+    if (existsSync(join(root, rel))) out.push(rel);
+  }
+  return out.sort();
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {{ baseBudget?: number, fileBudget?: number }} [opts]
+ */
+export function analyzeBudget(projectRoot, opts = {}) {
+  const root = resolve(projectRoot);
+  const baseBudget = opts.baseBudget ?? DEFAULTS.baseBudget;
+  const fileBudget = opts.fileBudget ?? DEFAULTS.fileBudget;
+
+  const sharedDocs = SHARED_BASE_DOCS.map((d) => measure(root, d)).filter(Boolean);
+  const sharedTokens = sharedDocs.reduce((s, d) => s + d.tokens, 0);
+
+  const roles = [];
+  for (const role of ROLES) {
+    const card = measure(root, `.claude/agents/${role}.md`);
+    if (!card) continue;
+    const base = card.tokens + sharedTokens;
+    roles.push({
+      role,
+      cardTokens: card.tokens,
+      sharedTokens,
+      baseTokens: base,
+      overBudget: base > baseBudget,
+    });
+  }
+
+  const refs = listMarkdown(root, '.claude/agents/refs')
+    .map((rel) => measure(root, rel))
+    .filter(Boolean)
+    .filter((f) => basename(f.path) !== 'README.md');
+  const skills = listSkills(root)
+    .map((rel) => measure(root, rel))
+    .filter(Boolean);
+
+  const onDemand = [...refs, ...skills].sort((a, b) => b.tokens - a.tokens);
+  const onDemandTotal = onDemand.reduce((s, f) => s + f.tokens, 0);
+  const heavy = onDemand.filter((f) => f.tokens > fileBudget);
+  const unscopedHeavy = heavy.filter((f) => !f.readWhen);
+
+  const warnings = [];
+  for (const r of roles) {
+    if (r.overBudget) {
+      warnings.push(
+        `role "${r.role}" base context ≈ ${r.baseTokens} tokens (> ${baseBudget} budget)`,
+      );
+    }
+  }
+  for (const f of unscopedHeavy) {
+    warnings.push(`heavy on-demand file: ${f.path} ≈ ${f.tokens} tokens (> ${fileBudget}) — consider splitting`);
+  }
+
+  return {
+    ok: warnings.length === 0,
+    root,
+    baseBudget,
+    fileBudget,
+    sharedTokens,
+    roles,
+    onDemand,
+    onDemandTotal,
+    heavy,
+    warnings,
+  };
+}
+
+function printHuman(result) {
+  console.log(`[context:budget] base-budget=${result.baseBudget} file-budget=${result.fileBudget} tokens`);
+  console.log(`shared base docs ≈ ${result.sharedTokens} tokens (loaded by every role)`);
+  console.log('\nPer-role always-loaded base context:');
+  for (const r of result.roles) {
+    const mark = r.overBudget ? '!' : ' ';
+    console.log(`  [${mark}] ${r.role.padEnd(18)} ≈ ${r.baseTokens} tokens (card ${r.cardTokens} + shared ${r.sharedTokens})`);
+  }
+  console.log(`\nOn-demand pool: ${result.onDemand.length} files ≈ ${result.onDemandTotal} tokens total`);
+  const top = result.onDemand.slice(0, 5);
+  for (const f of top) {
+    console.log(`  - ${f.path} ≈ ${f.tokens} tokens${f.estimated ? '' : ' (declared)'}`);
+  }
+  if (result.warnings.length) {
+    console.log('\nWarnings:');
+    for (const w of result.warnings) console.log(`  - ${w}`);
+  } else {
+    console.log('\nAll roles within budget.');
+  }
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const result = analyzeBudget(opts.root, opts);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printHuman(result);
+  }
+  process.exit(opts.strict && !result.ok ? 2 : 0);
+}
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  try {
+    main();
+  } catch (err) {
+    console.error(`[context:budget] ${err.message}`);
+    process.exit(1);
+  }
+}

package/project-templates/threejs/skills/_shared/scripts/create-playable.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * Copy template/ to a new playable project and run ensure-project.
+ *
+ * Usage (from workspace root):
+ *   node skills/_shared/scripts/create-playable.mjs --name=my-game
+ *   node skills/_shared/scripts/create-playable.mjs --name=my-game --no-ensure
+ */
+
+import { access, cp, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SKILLS_ROOT = resolve(__dirname, '../..');
+const REPO_ROOT = resolve(SKILLS_ROOT, '..');
+const TEMPLATE_ROOT = REPO_ROOT;
+const DEST_PARENT = dirname(REPO_ROOT);
+const COPY_EXCLUDES = new Set([
+  '.DS_Store',
+  '.git',
+  'node_modules',
+  'dist',
+  'package-lock.json',
+  'playable.ui.profile.yaml',
+  'playground',
+  'recordings',
+  'validate',
+]);
+
+function shouldCopy(src) {
+  const name = basename(src);
+  if (COPY_EXCLUDES.has(name)) return false;
+  if (src.includes(`${join('ta-workspace', 'logs')}`)) return name === '.gitkeep';
+  if (src.includes(`${join('ta-workspace', 'tmp')}`)) return name === '.gitkeep';
+  if (src.includes(`${join('focus-lab')}`)) return name === 'focus-lab' || name === '.gitkeep';
+  return true;
+}
+
+function parseArgs(argv) {
+  const opts = { name: null, ensure: true, json: false };
+  for (const arg of argv) {
+    if (arg.startsWith('--name=')) opts.name = arg.slice(7).trim();
+    else if (arg === '--no-ensure') opts.ensure = false;
+    else if (arg === '--json') opts.json = true;
+  }
+  return opts;
+}
+
+async function exists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function patchPackageJson(destRoot, name) {
+  const pkgPath = join(destRoot, 'package.json');
+  const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+  pkg.name = name;
+  pkg.description = `${name} — playable project`;
+  await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
+}
+
+async function patchProfile(destRoot, name) {
+  const profilePath = join(destRoot, 'playable.ui.profile.yaml');
+  if (!(await exists(profilePath))) return;
+  let text = await readFile(profilePath, 'utf8');
+  text = text.replace(/name: playable-template/, `name: ${name}`);
+  await writeFile(profilePath, text, 'utf8');
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (!opts.name) {
+    console.error('Usage: create-playable.mjs --name=<project-dir-name>');
+    process.exit(1);
+  }
+
+  if (!(await exists(TEMPLATE_ROOT))) {
+    console.error(`Template not found: ${TEMPLATE_ROOT}`);
+    process.exit(1);
+  }
+
+  const destRoot = resolve(DEST_PARENT, opts.name);
+  if (await exists(destRoot)) {
+    console.error(`Target already exists: ${destRoot}`);
+    process.exit(1);
+  }
+
+  await cp(TEMPLATE_ROOT, destRoot, {
+    recursive: true,
+    filter: (src) => shouldCopy(src),
+  });
+  await patchPackageJson(destRoot, opts.name);
+  await patchProfile(destRoot, opts.name);
+
+  let ensureResult = null;
+  if (opts.ensure) {
+    const ensureScript = join(SKILLS_ROOT, '_shared/scripts/ensure-project.mjs');
+    const r = spawnSync('node', [ensureScript, `--root=${destRoot}`], {
+      cwd: destRoot,
+      encoding: 'utf8',
+    });
+    ensureResult = { status: r.status, stdout: r.stdout, stderr: r.stderr };
+  }
+
+  const result = {
+    ok: true,
+    projectRoot: destRoot,
+    templateRoot: TEMPLATE_ROOT,
+    skillsRoot: SKILLS_ROOT,
+    ensure: ensureResult,
+    next: [
+      `cd ${opts.name}`,
+      'npm run dev',
+      '对 Agent：用 playable-validate 优化当前 playable',
+    ],
+  };
+
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`[create-playable] created ${destRoot}`);
+    if (ensureResult?.status === 0) {
+      console.log('[create-playable] ensure-project OK');
+    } else if (opts.ensure) {
+      console.warn('[create-playable] ensure-project had issues — run npm run ensure:project');
+    }
+    for (const step of result.next) console.log(`  → ${step}`);
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/project-templates/threejs/skills/_shared/scripts/dev-start.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * Start (or stop) the persistent preview dev server and record the real devUrl.
+ *
+ * This removes the LLM from port handling entirely (docs/harness/experiment-lessons.md §9.2):
+ * Vite runs with strictPort:false, so when 3000 is taken it auto-increments; this
+ * script parses Vite's actual `Local:` URL from the log, appends `?debug=1`, and
+ * writes it back to project-state via the same layer `state:set` uses. The agent
+ * never reads or records a port by hand.
+ *
+ * Usage:
+ *   npm run dev:start          # start server, capture real URL, write devUrl
+ *   npm run dev:stop           # stop the server started by dev:start
+ *   node skills/_shared/scripts/dev-start.mjs --root=. [--stop] [--timeout=30000]
+ *
+ * Exit 0 = server up + devUrl written (or stopped); 1 = failed to detect URL.
+ */
+
+import { openSync, closeSync, existsSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { join, resolve } from 'node:path';
+import { applyHandoffUpdates, resolveProjectStatePath } from './state-handoff.mjs';
+import { parseLocalUrl, waitForHttp } from '../../playable-record/scripts/lib/dev-server.mjs';
+
+const PID_FILE = '.playcraft-dev.pid';
+const LOG_FILE = '.playcraft-dev.log';
+const PREFERRED_URL = 'http://127.0.0.1:3000/';
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), stop: false, timeout: 30000 };
+  for (const arg of argv) {
+    if (arg === '--stop') opts.stop = true;
+    else if (arg.startsWith('--root=')) {
+      const v = arg.slice('--root='.length);
+      opts.root = v.startsWith('/') ? v : resolve(process.cwd(), v);
+    } else if (arg.startsWith('--timeout=')) opts.timeout = Number(arg.slice('--timeout='.length));
+  }
+  return opts;
+}
+
+/** Append the `?debug=1` flag that gates the on-screen one-click clear button. */
+function withDebugFlag(url) {
+  return /[?&]debug=1\b/.test(url) ? url : `${url}${url.includes('?') ? '&' : '?'}debug=1`;
+}
+
+function readPid(root) {
+  const pidPath = join(root, PID_FILE);
+  if (!existsSync(pidPath)) return null;
+  const pid = Number(readFileSync(pidPath, 'utf8').trim());
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function stopServer(root) {
+  const pid = readPid(root);
+  const pidPath = join(root, PID_FILE);
+  if (pid && isAlive(pid)) {
+    // Detached child is its own process-group leader; kill the whole group.
+    try {
+      process.kill(-pid, 'SIGTERM');
+    } catch {
+      try {
+        process.kill(pid, 'SIGTERM');
+      } catch {
+        /* already gone */
+      }
+    }
+    console.log(`[dev:stop] stopped dev server (pid ${pid})`);
+  } else {
+    console.log('[dev:stop] no running dev server recorded');
+  }
+  if (existsSync(pidPath)) rmSync(pidPath);
+}
+
+/** Poll the dev-server log file for Vite's `Local:` URL. */
+async function detectUrlFromLog(logPath, timeoutMs) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (existsSync(logPath)) {
+      const url = parseLocalUrl(readFileSync(logPath, 'utf8'));
+      if (url) return url;
+    }
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  return null;
+}
+
+async function startServer(root, timeoutMs) {
+  const existingPid = readPid(root);
+  if (existingPid && isAlive(existingPid)) {
+    const logPath = join(root, LOG_FILE);
+    const url = (existsSync(logPath) && parseLocalUrl(readFileSync(logPath, 'utf8'))) || PREFERRED_URL;
+    return finalize(root, url, existingPid, true);
+  }
+
+  const logPath = join(root, LOG_FILE);
+  const logFd = openSync(logPath, 'w');
+  const child = spawn('npm', ['run', 'dev', '--', '--host', '127.0.0.1'], {
+    cwd: root,
+    detached: true,
+    stdio: ['ignore', logFd, logFd],
+  });
+  closeSync(logFd);
+  child.unref();
+  writeFileSync(join(root, PID_FILE), String(child.pid));
+
+  const detected = await detectUrlFromLog(logPath, timeoutMs);
+  const url = detected || PREFERRED_URL;
+  try {
+    await waitForHttp(url, 10000);
+  } catch {
+    if (!detected) {
+      console.error(
+        `[dev:start] could not detect dev URL within ${timeoutMs}ms and ${PREFERRED_URL} is not reachable — check ${LOG_FILE}`,
+      );
+      return { ok: false };
+    }
+  }
+  return finalize(root, url, child.pid, false);
+}
+
+function finalize(root, baseUrl, pid, reused) {
+  const devUrl = withDebugFlag(baseUrl);
+  applyHandoffUpdates(resolveProjectStatePath(root), { devUrl });
+  console.log(`[dev:start] ${reused ? 'reusing' : 'started'} dev server (pid ${pid})`);
+  console.log(`[dev:start] devUrl recorded: ${devUrl}`);
+  return { ok: true, devUrl, pid };
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.stop) {
+    stopServer(opts.root);
+    return;
+  }
+  const result = await startServer(opts.root, opts.timeout);
+  process.exit(result.ok ? 0 : 1);
+}
+
+main().catch((err) => {
+  console.error(`[dev:start] error: ${err.message}`);
+  process.exit(1);
+});