@playcraft/cli 0.0.41 → 0.0.43

package/dist/atom-plan/validate-asr-coverage.js

@@ -0,0 +1,317 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const PLACEHOLDER_RE = /\{\{[^}]+\}\}/;
+const MIN_TAKEAWAY_LEN = 8;
+export const IMAGE_PRODUCTION_PREFLIGHT_HEADING = '## Image Production Preflight';
+export const ASR_COVERAGE_HEADING = '## ASR Coverage Matrix';
+export const REQUIRED_IMAGE_SKILLS = [
+    'playcraft-storyboard',
+    'playcraft-asset-state-sheet',
+    'playcraft-image-generation',
+];
+export function readSelectedMcOption(content) {
+    const m = content.match(/selectedMcOption:\s*["']?([ABC])["']?/i) ||
+        content.match(/selectedMcOption\s*=\s*([ABC])/i);
+    return m ? m[1].toUpperCase() : null;
+}
+function extractSection(content, heading) {
+    const start = content.indexOf(heading);
+    if (start === -1)
+        return '';
+    const after = content.slice(start + heading.length);
+    const next = after.search(/\n##\s+/);
+    return next === -1 ? after : after.slice(0, next);
+}
+export function parseLayoutSpecContractIds(layoutSpec) {
+    const elementIds = [];
+    const staticTextIds = [];
+    const assetSection = extractSection(layoutSpec, '## Asset Mapping');
+    for (const line of assetSection.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('|'))
+            continue;
+        if (/^\|\s*---/.test(trimmed))
+            continue;
+        if (/^\|\s*elementId/i.test(trimmed))
+            continue;
+        const parts = trimmed
+            .split('|')
+            .map((p) => p.trim())
+            .filter((_, i, arr) => i > 0 && i < arr.length - 1);
+        if (parts.length < 1)
+            continue;
+        const id = parts[0].replace(/`/g, '');
+        if (!id || id === '—' || id === '-' || PLACEHOLDER_RE.test(id))
+            continue;
+        elementIds.push(id);
+    }
+    const textSection = extractSection(layoutSpec, '### Static Text');
+    for (const line of textSection.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('|'))
+            continue;
+        if (/^\|\s*---/.test(trimmed))
+            continue;
+        if (/^\|\s*id/i.test(trimmed))
+            continue;
+        const parts = trimmed
+            .split('|')
+            .map((p) => p.trim())
+            .filter((_, i, arr) => i > 0 && i < arr.length - 1);
+        if (parts.length < 1)
+            continue;
+        const id = parts[0].replace(/`/g, '');
+        if (!id || id === '—' || PLACEHOLDER_RE.test(id))
+            continue;
+        staticTextIds.push(id);
+    }
+    return { elementIds, staticTextIds };
+}
+function isReadChecked(cell) {
+    const t = cell.trim();
+    if (/[✓✔☑]/.test(t))
+        return true;
+    if (/\[x\]/i.test(t))
+        return true;
+    if (/^(yes|done|true|read)$/i.test(t))
+        return true;
+    return false;
+}
+export function validateImageProductionPreflight(content) {
+    const errors = [];
+    const start = content.indexOf(IMAGE_PRODUCTION_PREFLIGHT_HEADING);
+    if (start === -1) {
+        return [`Missing "${IMAGE_PRODUCTION_PREFLIGHT_HEADING}" section`];
+    }
+    const after = content.slice(start + IMAGE_PRODUCTION_PREFLIGHT_HEADING.length);
+    const nextHeading = after.search(/\n##\s+/);
+    const section = nextHeading === -1 ? after : after.slice(0, nextHeading);
+    const rows = [];
+    for (const line of section.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('|'))
+            continue;
+        if (/^\|\s*---/.test(trimmed))
+            continue;
+        if (/^\|\s*Skill/i.test(trimmed))
+            continue;
+        const parts = trimmed
+            .split('|')
+            .map((p) => p.trim())
+            .filter((_, i, arr) => i > 0 && i < arr.length - 1);
+        if (parts.length < 3)
+            continue;
+        rows.push({ skill: parts[0], read: parts[1], summary: parts[2] });
+    }
+    if (rows.length === 0) {
+        errors.push(`${IMAGE_PRODUCTION_PREFLIGHT_HEADING}: table has no data rows`);
+        return errors;
+    }
+    for (const required of REQUIRED_IMAGE_SKILLS) {
+        const row = rows.find((r) => r.skill.includes(required));
+        if (!row) {
+            errors.push(`${IMAGE_PRODUCTION_PREFLIGHT_HEADING}: missing row for ${required}`);
+            continue;
+        }
+        if (!isReadChecked(row.read)) {
+            errors.push(`${IMAGE_PRODUCTION_PREFLIGHT_HEADING}: "${required}" — mark 已读 (✓)`);
+        }
+        if (!row.summary || PLACEHOLDER_RE.test(row.summary) || row.summary.length < MIN_TAKEAWAY_LEN) {
+            errors.push(`${IMAGE_PRODUCTION_PREFLIGHT_HEADING}: "${required}" — add decision summary (≥${MIN_TAKEAWAY_LEN} chars)`);
+        }
+    }
+    return errors;
+}
+export function parseCoverageMatrixRows(content) {
+    const section = extractSection(content, ASR_COVERAGE_HEADING);
+    const coverageStart = section.indexOf('### Coverage');
+    const coverageBlock = coverageStart === -1 ? section : section.slice(coverageStart);
+    const rows = [];
+    for (const line of coverageBlock.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('|'))
+            continue;
+        if (/^\|\s*---/.test(trimmed))
+            continue;
+        if (/^\|\s*Contract id/i.test(trimmed))
+            continue;
+        const parts = trimmed
+            .split('|')
+            .map((p) => p.trim())
+            .filter((_, i, arr) => i > 0 && i < arr.length - 1);
+        if (parts.length < 4)
+            continue;
+        const contractId = parts[0].replace(/`/g, '');
+        if (!contractId || PLACEHOLDER_RE.test(contractId))
+            continue;
+        const typeValues = new Set(['visual', 'audio', 'text', 'digit', 'sfx']);
+        let elementType = '';
+        let coverageLayer = '';
+        if (parts.length >= 4 && typeValues.has(parts[2]?.toLowerCase())) {
+            // id | elementType | Type | CoverageLayer | ...
+            elementType = parts[1];
+            coverageLayer = parts[3];
+        }
+        else if (parts.length >= 3 && typeValues.has(parts[1]?.toLowerCase())) {
+            // Legacy: id | Type | CoverageLayer | ...
+            coverageLayer = parts[2];
+        }
+        else {
+            elementType = parts.length >= 6 ? parts[1] : '';
+            coverageLayer = parts.length >= 4 ? parts[3] : parts[1] || '';
+        }
+        rows.push({
+            contractId,
+            elementType: elementType.replace(/`/g, ''),
+            coverageLayer: coverageLayer.toLowerCase(),
+        });
+    }
+    return rows;
+}
+export function validateSheetGridMetadata(content) {
+    const errors = [];
+    const section = extractSection(content, ASR_COVERAGE_HEADING);
+    if (!section.includes('### Sheet grid metadata')) {
+        errors.push('ASR Coverage Matrix: missing ### Sheet grid metadata table');
+        return errors;
+    }
+    const gridStart = section.indexOf('### Sheet grid metadata');
+    const gridBlock = section.slice(gridStart);
+    const gridEnd = gridBlock.search(/\n###\s+/);
+    const gridSection = gridEnd === -1 ? gridBlock : gridBlock.slice(0, gridEnd);
+    if (PLACEHOLDER_RE.test(gridSection)) {
+        errors.push('Sheet grid metadata: contains {{placeholders}} — fill real rows/cols/cell dimensions');
+    }
+    let dataRows = 0;
+    for (const line of gridSection.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('|'))
+            continue;
+        if (/^\|\s*---/.test(trimmed))
+            continue;
+        if (/^\|\s*Sheet/i.test(trimmed))
+            continue;
+        dataRows++;
+    }
+    if (dataRows < 2) {
+        errors.push('Sheet grid metadata: need at least ui + element sheet rows');
+    }
+    return errors;
+}
+export function validateCoverageRowCount(designerLog, layoutSpec) {
+    const errors = [];
+    const { elementIds, staticTextIds } = parseLayoutSpecContractIds(layoutSpec);
+    const expected = elementIds.length + staticTextIds.length;
+    const matrixRows = parseCoverageMatrixRows(designerLog);
+    if (expected === 0) {
+        errors.push('layout-spec: could not parse assetMapping/static text ids — fill Asset Mapping table');
+        return errors;
+    }
+    if (matrixRows.length < expected) {
+        errors.push(`Coverage Matrix: ${matrixRows.length} rows but layout-spec expects ${expected} (assetMapping + static text)`);
+    }
+    const contractSet = new Set([...elementIds, ...staticTextIds]);
+    const matrixIds = new Set(matrixRows.map((r) => r.contractId));
+    for (const id of contractSet) {
+        if (!matrixIds.has(id)) {
+            errors.push(`Coverage Matrix: missing row for contract id "${id}"`);
+        }
+    }
+    return errors;
+}
+export function validateTypeRepresentatives(designerLog) {
+    const errors = [];
+    const rows = parseCoverageMatrixRows(designerLog);
+    const typeLayers = new Map();
+    for (const row of rows) {
+        const type = row.elementType && row.elementType !== '—' ? row.elementType : row.contractId.split('_')[0];
+        if (!type)
+            continue;
+        if (!typeLayers.has(type))
+            typeLayers.set(type, new Set());
+        typeLayers.get(type).add(row.coverageLayer);
+    }
+    for (const [type, layers] of typeLayers) {
+        const hasRep = [...layers].some((l) => l.includes('on-asr')) || [...layers].some((l) => l.includes('mc-crop'));
+        if (!hasRep && layers.size > 0) {
+            const allExtends = [...layers].every((l) => l.includes('ta-extends') || l.includes('ta extends'));
+            if (allExtends) {
+                errors.push(`Coverage Matrix: elementType "${type}" has no on-asr or mc-crop representative`);
+            }
+        }
+    }
+    return errors;
+}
+export function validateAsrPngFiles(projectDir, option, designerLog) {
+    const errors = [];
+    const ui = path.join(projectDir, `assets/images/reference/ui_state_sheet_${option}.png`);
+    const el = path.join(projectDir, `assets/images/reference/element_state_sheet_${option}.png`);
+    const mc = path.join(projectDir, `assets/images/storyboard/master_composite_option_${option}.png`);
+    if (!fs.existsSync(mc)) {
+        errors.push(`Missing MC: assets/images/storyboard/master_composite_option_${option}.png`);
+    }
+    if (!fs.existsSync(ui)) {
+        errors.push(`Missing ASR: assets/images/reference/ui_state_sheet_${option}.png`);
+    }
+    if (!fs.existsSync(el)) {
+        errors.push(`Missing ASR: assets/images/reference/element_state_sheet_${option}.png`);
+    }
+    if (designerLog && /element_2|element_state_sheet_\w+_2\.png/i.test(designerLog)) {
+        const el2 = path.join(projectDir, `assets/images/reference/element_state_sheet_${option}_2.png`);
+        if (!fs.existsSync(el2)) {
+            errors.push(`Missing ASR overflow board: assets/images/reference/element_state_sheet_${option}_2.png`);
+        }
+    }
+    return errors;
+}
+export function validateDesignerGate2b(projectDir) {
+    const errors = [];
+    const logPath = path.join(projectDir, 'logs/designer-log.md');
+    const layoutPath = path.join(projectDir, 'docs/layout-spec.md');
+    const statePath = path.join(projectDir, 'docs/project-state.md');
+    if (!fs.existsSync(logPath)) {
+        return ['Create logs/designer-log.md before Gate #2b STOP'];
+    }
+    if (!fs.existsSync(layoutPath)) {
+        return ['Missing docs/layout-spec.md'];
+    }
+    const designerLog = fs.readFileSync(logPath, 'utf8');
+    const layoutSpec = fs.readFileSync(layoutPath, 'utf8');
+    errors.push(...validateImageProductionPreflight(designerLog));
+    if (!designerLog.includes(ASR_COVERAGE_HEADING)) {
+        errors.push(`Missing "${ASR_COVERAGE_HEADING}" section`);
+    }
+    else {
+        errors.push(...validateSheetGridMetadata(designerLog));
+        errors.push(...validateCoverageRowCount(designerLog, layoutSpec));
+        errors.push(...validateTypeRepresentatives(designerLog));
+    }
+    let option = 'A';
+    if (fs.existsSync(statePath)) {
+        const opt = readSelectedMcOption(fs.readFileSync(statePath, 'utf8'));
+        if (opt)
+            option = opt;
+    }
+    errors.push(...validateAsrPngFiles(projectDir, option, designerLog));
+    return errors;
+}
+export function validateAsrCoverageProject(projectDir) {
+    const layoutPath = path.join(projectDir, 'docs/layout-spec.md');
+    const logPath = path.join(projectDir, 'logs/designer-log.md');
+    let expectedContractRows = 0;
+    let matrixRows = 0;
+    if (fs.existsSync(layoutPath)) {
+        const ids = parseLayoutSpecContractIds(fs.readFileSync(layoutPath, 'utf8'));
+        expectedContractRows = ids.elementIds.length + ids.staticTextIds.length;
+    }
+    if (fs.existsSync(logPath)) {
+        matrixRows = parseCoverageMatrixRows(fs.readFileSync(logPath, 'utf8')).length;
+    }
+    const errors = validateDesignerGate2b(projectDir);
+    return {
+        ok: errors.length === 0,
+        errors,
+        expectedContractRows,
+        matrixRows,
+    };
+}

package/dist/commands/prad.js

@@ -0,0 +1,61 @@
+import * as fs from 'node:fs';
+import pc from 'picocolors';
+import { checkPradFile } from '../prad/check.js';
+import { explainPradPath, formatExplain } from '../prad/explain.js';
+export function registerPradCommands(program) {
+    const prad = program.command('prad').description('PRAD (PlayCraft Remix Assembly DSL) 校验与调试');
+    prad
+        .command('check')
+        .description('静态校验 atom-tree.json（PRAD 文档）')
+        .argument('[file]', 'PRAD JSON 文件', 'atom-tree.json')
+        .option('--gate <n>', 'Gate 1–4', (v) => parseInt(v, 10))
+        .option('--strict-drafts', 'draft atom 视为 error')
+        .option('--legacy', '允许缺失 pradVersion')
+        .option('--spec-dir <path>', 'PRAD spec 目录（含 spine-registry）')
+        .option('--skills-dir <path>', 'Skills 库目录')
+        .action((file, options) => {
+        if (!fs.existsSync(file)) {
+            console.error(pc.red(`File not found: ${file}`));
+            process.exit(1);
+        }
+        const result = checkPradFile(file, {
+            gate: options.gate,
+            strictDrafts: options.strictDrafts,
+            legacy: options.legacy,
+            specDir: options.specDir,
+            skillsDir: options.skillsDir,
+        });
+        for (const w of result.warnings) {
+            console.log(pc.yellow(`${w.code} [${w.path}] ${w.message}`));
+        }
+        for (const e of result.errors) {
+            console.error(pc.red(`${e.code} [${e.path}] ${e.message}`));
+        }
+        if (result.ok) {
+            console.log(pc.green('prad check: pass'));
+            process.exit(0);
+        }
+        console.error(pc.red(`prad check: fail (${result.errors.length} errors)`));
+        process.exit(1);
+    });
+    prad
+        .command('explain')
+        .description('解释 PRAD 节点 path 的上下文（slot / atom / bindAs）')
+        .argument('[file]', 'PRAD JSON 文件', 'atom-tree.json')
+        .requiredOption('--path <logicalPath>', '逻辑 path，如 scenes.entry.ui_layer.play_btn')
+        .option('--spec-dir <path>', 'PRAD spec 目录')
+        .option('--skills-dir <path>', 'Skills 库目录')
+        .action((file, options) => {
+        if (!fs.existsSync(file)) {
+            console.error(pc.red(`File not found: ${file}`));
+            process.exit(1);
+        }
+        const doc = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        const result = explainPradPath(doc, options.path, {
+            specDir: options.specDir,
+            skillsDir: options.skillsDir,
+        });
+        console.log(formatExplain(result));
+        process.exit(result.found ? 0 : 1);
+    });
+}

package/dist/commands/remix.js

@@ -120,7 +120,8 @@ async function remixEnsureStream(options) {
                 throw new Error(event.message || 'ensure-stream 返回 error 事件');
             }
             else if (event.type === 'capacity_exceeded') {
-                if (!event.candidates.length) {
+                const selectableCandidates = event.candidates.filter((c) => c.evictable !== false);
+                if (!selectableCandidates.length) {
                     throw new Error(`容量已满 (${event.current}/${event.max})，但服务端未返回可驱逐候选`);
                 }
                 const selected = await inquirer.prompt([
@@ -129,8 +130,9 @@ async function remixEnsureStream(options) {
                         name: 'slotId',
                         message: `沙箱容量已满 (${event.current}/${event.max})，请选择一个候选项继续驱逐:`,
                         choices: event.candidates.map((c) => ({
-                            name: `${c.slotId} (${c.projectId}/${c.branchName}) idle=${formatIdleSec(c.idleSec)}${c.hasUnpushedChanges ? ' [unpushed]' : ''}`,
+                            name: `${c.slotId} (${c.projectId}/${c.branchName}) status=${c.agentStatus ?? 'unknown'} idle=${formatIdleSec(c.idleSec)}${c.hasUnpushedChanges ? ' [unpushed]' : ''}`,
                             value: c.slotId,
+                            disabled: c.evictable === false ? (c.disabledReason ?? 'not evictable') : false,
                         })),
                     },
                 ]);

package/dist/commands/skills.js

@@ -20,6 +20,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseSkillRefsFromAtomPlanProject, validateAtomPlanProject } from '../atom-plan/validate-atom-plan.js';
+import { validateAsrCoverageProject } from '../atom-plan/validate-asr-coverage.js';
 import { loadConfig } from '../config.js';
 const KNOWN_ENGINES = ['phaser', 'threejs'];
 const SCORE_THRESHOLD_FULL = 8;
@@ -1352,6 +1353,29 @@ export function registerSkillsCommands(program) {
         if (!result.ok)
             process.exit(1);
     });
+    // ── validate-asr-coverage ─────────────────────────────────────────────────
+    addSkillsDirOption(skills
+        .command('validate-asr-coverage')
+        .description('校验 Gate #2b ASR Coverage Matrix、Image Production Preflight 与 ASR/MC PNG 文件')
+        .option('--project-dir <path>', '项目根目录', process.cwd())
+        .option('--json', '输出 JSON 格式')).action(async (opts) => {
+        void opts.skillsDir;
+        const result = validateAsrCoverageProject(opts.projectDir);
+        if (opts.json) {
+            process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        }
+        else if (result.ok) {
+            console.log(`\n✓ ASR coverage 校验通过（${result.matrixRows}/${result.expectedContractRows} Matrix rows）\n`);
+        }
+        else {
+            console.error('\n✗ ASR coverage 校验失败\n');
+            for (const e of result.errors)
+                console.error(`  - ${e}`);
+            console.error();
+        }
+        if (!result.ok)
+            process.exit(1);
+    });
     // ── read ──────────────────────────────────────────────────────────────────
     addSkillsDirOption(skills
         .command('read <atomId>')

package/dist/commands/tools-generation.js

@@ -2,7 +2,7 @@ import { writeFileSync, mkdirSync } from 'fs';
 import { dirname, parse, join } from 'path';
 import sharp from 'sharp';
 import { AgentApiClient } from '../utils/agent-api-client.js';
-import { MAX_REFERENCE_IMAGES, collectReferenceImagePaths, collectReferenceImagePayloads, sniffImageExtension, extensionForImageMime, resolveImageOutputPath, handleError, } from './tools-utils.js';
+import { MAX_REFERENCE_IMAGES, collectReferenceImagePaths, collectReferenceImagePayloads, sniffImageExtension, extensionForImageMime, resolveImageOutputPath, handleError, raceWithTimeout, } from './tools-utils.js';
 function isMasterCompositeStripRequest(opts) {
     if (opts.aspectRatio === '45:16')
         return true;
@@ -176,8 +176,6 @@ export function registerGenerationCommands(tools) {
             }
             const referenceImages = await collectReferenceImagePayloads(paths);
             const client = new AgentApiClient();
-            const timeoutMs = opts.timeout * 1000;
-            const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error(`Request timed out after ${opts.timeout}s. The backend task may still be running — check admin panel before re-running.`)), timeoutMs));
             const imageCount = Math.min(Math.max(1, opts.count ?? 1), 10);
             const requestPromise = client.post('/generate-image', {
                 prompt: opts.prompt,
@@ -188,7 +186,7 @@ export function registerGenerationCommands(tools) {
                 ...(modelRef ? { imageModelRef: modelRef } : {}),
                 ...(imageCount > 1 ? { imageCount } : {}),
             });
-            return Promise.race([requestPromise, timeoutPromise]);
+            return raceWithTimeout(requestPromise, opts.timeout * 1000, `Request timed out after ${opts.timeout}s. The backend task may still be running — check admin panel before re-running.`);
         };
         const enrichError = (err, modelRef) => {
             const msg = err instanceof Error ? err.message : String(err);

package/dist/commands/tools-utils.js

@@ -20,6 +20,25 @@ export function handleError(err) {
     console.error(`Error: ${msg}`);
     process.exit(1);
 }
+/**
+ * Race a promise against a timeout. Clears the timer when the promise settles so
+ * short-lived CLI processes exit immediately (uncleared timers keep Node alive).
+ */
+export async function raceWithTimeout(promise, timeoutMs, timeoutMessage) {
+    if (timeoutMs <= 0)
+        return promise;
+    let timeoutId;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => reject(new Error(timeoutMessage)), timeoutMs);
+    });
+    try {
+        return await Promise.race([promise, timeoutPromise]);
+    }
+    finally {
+        if (timeoutId !== undefined)
+            clearTimeout(timeoutId);
+    }
+}
 /** Fallback extension from API mime when magic-byte sniff fails. */
 export function extensionForImageMime(mimeType) {
     const base = mimeType.toLowerCase().split(';')[0]?.trim() ?? '';

package/dist/prad/atom-ref.js

@@ -0,0 +1,23 @@
+/** Parse entity/engine atom field (string or object). */
+export function parseAtomRef(raw) {
+    if (typeof raw === 'string') {
+        return { id: raw, resolve: 'registry' };
+    }
+    if (raw && typeof raw === 'object' && 'id' in raw) {
+        const o = raw;
+        if (typeof o.id !== 'string')
+            return null;
+        return {
+            id: o.id,
+            resolve: o.resolve ?? 'registry',
+            substitute: o.substitute,
+        };
+    }
+    return null;
+}
+export function atomIdFromInstance(raw) {
+    if (raw && typeof raw === 'object' && 'atom' in raw) {
+        return parseAtomRef(raw.atom)?.id ?? null;
+    }
+    return null;
+}