@playcraft/cli 0.0.44 → 0.0.46

package/dist/commands/tools-detect.js

@@ -0,0 +1,56 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, relative, resolve, sep } from 'node:path';
+import { AgentApiClient } from '../utils/agent-api-client.js';
+import { handleError } from './tools-utils.js';
+function makeClient(opts) {
+    if (opts.apiUrl || opts.token) {
+        if (opts.apiUrl)
+            process.env.PLAYCRAFT_API_URL = opts.apiUrl;
+        if (opts.token)
+            process.env.PLAYCRAFT_SANDBOX_TOKEN = opts.token;
+    }
+    return new AgentApiClient();
+}
+export async function runDetect(opts) {
+    const imagePath = resolve(opts.image);
+    const outputPath = resolve(opts.output);
+    const relSourcePath = relative(process.cwd(), imagePath).split(sep).join('/');
+    const sourcePath = relSourcePath && !relSourcePath.startsWith('..') ? relSourcePath : basename(imagePath);
+    const imageBase64 = readFileSync(imagePath).toString('base64');
+    const client = makeClient({ apiUrl: opts.apiUrl, token: opts.token });
+    const result = await client.post('/detect', {
+        imageBase64,
+        sourcePath,
+        prompts: opts.prompt.length > 0 ? opts.prompt : undefined,
+    });
+    const payload = {
+        detections: result.detections.map((det) => ({
+            sourcePath: det.sourcePath ?? sourcePath,
+            frame: det.frame ?? null,
+            box: det.box,
+            className: det.className,
+            confidence: det.confidence,
+        })),
+    };
+    mkdirSync(dirname(outputPath), { recursive: true });
+    writeFileSync(outputPath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+    console.log(`[tools detect] ${payload.detections.length} detections → ${outputPath}`);
+}
+export function registerDetectCommand(tools) {
+    tools
+        .command('detect')
+        .description('Backend SAM3 detect → JSON for npm run verify:vision -- --detections')
+        .requiredOption('--image <path>', 'Screenshot or asset path')
+        .option('--output <path>', 'Detections JSON output', 'validate/vision/detections.json')
+        .option('--api-url <url>', 'Backend API URL override')
+        .option('--token <token>', 'PAT or sandbox token override')
+        .option('--prompt <text>', 'Open-vocab SAM3 prompt (repeatable)', (value, prev) => [...prev, value], [])
+        .action(async (opts) => {
+        try {
+            await runDetect(opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+}

package/dist/commands/tools-generation.js

@@ -388,6 +388,7 @@ export function registerGenerationCommands(tools) {
         .requiredOption('--prompt <text>', 'BGM 描述，如 "轻快休闲游戏配乐"')
         .option('--style <style>', '音乐风格，如 casual / epic / sci-fi / retro')
         .option('--bpm <bpm>', '目标 BPM', parseInt)
+        .option('--fallback-placeholder', 'On API failure (503/missing key), skip hard fail with explicit placeholder guidance')
         .requiredOption('--output <path>', '保存路径，如 ./assets/audio/bgm.mp3')
         .action(async (opts) => {
         try {
@@ -411,6 +412,26 @@ export function registerGenerationCommands(tools) {
             console.log(`  └─ Generation metadata: ${opts.output.replace(/\.[^.]+$/, '.json')}`);
         }
         catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            const apiUnavailable = /503|MuleRouter|API key|No MuleRouter/i.test(msg);
+            if (apiUnavailable) {
+                console.error(`Error: ${msg}`);
+                console.error('Hint: BGM API unavailable — run `npm run placeholder:gen-audio` or re-run with --fallback-placeholder');
+                if (opts.fallbackPlaceholder) {
+                    mkdirSync(dirname(opts.output), { recursive: true });
+                    writeFileSync(opts.output.replace(/\.[^.]+$/, '.placeholder.json'), JSON.stringify({
+                        type: 'bgm',
+                        placeholder: true,
+                        reason: msg,
+                        output: opts.output,
+                        suggestedCommand: 'npm run placeholder:gen-audio',
+                        generatedAt: new Date().toISOString(),
+                    }, null, 2));
+                    console.warn(`⚠️  Wrote placeholder marker — generate audio before Ring Gate: ${opts.output}`);
+                    return;
+                }
+                process.exit(1);
+            }
             handleError(e);
         }
     });

package/dist/commands/tools-video-review.js

@@ -0,0 +1,100 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { AgentApiClient } from '../utils/agent-api-client.js';
+import { handleError } from './tools-utils.js';
+function makeClient(opts) {
+    if (opts.apiUrl)
+        process.env.PLAYCRAFT_API_URL = opts.apiUrl;
+    if (opts.token)
+        process.env.PLAYCRAFT_SANDBOX_TOKEN = opts.token;
+    return new AgentApiClient();
+}
+function fileToBase64DataUrl(path) {
+    const data = readFileSync(resolve(path));
+    const mimeType = path.toLowerCase().endsWith('.webm')
+        ? 'video/webm'
+        : path.toLowerCase().endsWith('.mov')
+            ? 'video/quicktime'
+            : 'video/mp4';
+    return `data:${mimeType};base64,${data.toString('base64')}`;
+}
+function parseContext(raw) {
+    if (!raw)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`--context-json is not valid JSON: ${e.message}`);
+    }
+}
+function readContextFile(path) {
+    if (!path)
+        return undefined;
+    const text = readFileSync(resolve(path), 'utf8');
+    // Naive extraction of key sections from DESIGN.md
+    const designSummary = extractSection(text, 'Game Concept', 'Summary') || extractSection(text, '设计概要', '核心玩法');
+    const hook = extractSection(text, 'Hook', 'First Action') || extractSection(text, 'Hook', '核心操作');
+    const firstAction = extractSection(text, 'First Action', 'CTA') || extractSection(text, '核心操作', 'CTA');
+    const ctaText = extractSection(text, 'CTA', 'Endcard') || extractSection(text, 'CTA', '结束画面');
+    return {
+        designSummary,
+        hook,
+        firstAction,
+        ctaText,
+    };
+}
+function extractSection(text, startMarker, endMarker) {
+    const startIdx = text.indexOf(startMarker);
+    if (startIdx < 0)
+        return undefined;
+    const endIdx = text.indexOf(endMarker, startIdx + startMarker.length);
+    const slice = text.slice(startIdx + startMarker.length, endIdx > 0 ? endIdx : undefined);
+    return slice.replace(/^[\s\n:：]+|[\s\n]+$/g, '').slice(0, 400) || undefined;
+}
+export async function runVideoReview(opts) {
+    const videoPath = resolve(opts.video);
+    const outputPath = resolve(opts.output);
+    const context = opts.contextJson ? parseContext(opts.contextJson) : readContextFile(opts.contextFile);
+    const ring = opts.ring ? Number.parseInt(opts.ring, 10) : undefined;
+    const request = {
+        videoBase64: fileToBase64DataUrl(videoPath),
+        sourcePath: videoPath,
+        context,
+        ...(opts.model && { model: opts.model }),
+        ...(opts.provider && { provider: opts.provider }),
+        ...(opts.tier && { tier: opts.tier }),
+        ...(ring && { ring }),
+    };
+    const client = makeClient({ apiUrl: opts.apiUrl, token: opts.token });
+    const result = await client.post('/analyze-video', request);
+    mkdirSync(dirname(outputPath), { recursive: true });
+    writeFileSync(outputPath, `${JSON.stringify(result, null, 2)}\n`, 'utf8');
+    console.log(`[tools analyze-video] ok=${result.ok} findings=${result.findings.length} → ${outputPath}`);
+    for (const f of result.findings) {
+        console.log(`  ${f.status.toUpperCase()} ${f.severity} ${f.className}: ${f.message.slice(0, 120)}`);
+    }
+}
+export function registerVideoReviewCommand(tools) {
+    tools
+        .command('analyze-video')
+        .description('Backend VLM video semantic review → JSON findings')
+        .requiredOption('--video <path>', 'MP4/WebM/MOV path')
+        .option('--output <path>', 'Output JSON path', 'validate/vlm-video.json')
+        .option('--context-file <path>', 'DESIGN.md or similar context file')
+        .option('--context-json <json>', 'JSON string with designSummary/hook/firstAction/ctaText')
+        .option('--model <ref>', 'Model override, e.g. moonshot/kimi-k2.6 or google/gemini-2.5-flash-preview-05-20')
+        .option('--provider <name>', 'Provider override, e.g. moonshot or google')
+        .option('--tier <fast|thorough>', 'Review tier: fast=screening, thorough=deep review')
+        .option('--ring <1-4>', 'Growth-ring iteration; adapts the review rubric')
+        .option('--api-url <url>', 'Backend API URL override')
+        .option('--token <token>', 'PAT or sandbox token override')
+        .action(async (opts) => {
+        try {
+            await runVideoReview(opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+}

package/dist/commands/tools.js

@@ -1,6 +1,8 @@
 import { registerGenerationCommands } from './tools-generation.js';
 import { registerProjectCommands } from './tools-project.js';
 import { register3DCommands } from './tools-3d.js';
+import { registerDetectCommand } from './tools-detect.js';
+import { registerVideoReviewCommand } from './tools-video-review.js';
 export function registerToolsCommands(program) {
     const tools = program
         .command('tools')
@@ -8,4 +10,6 @@ export function registerToolsCommands(program) {
     registerGenerationCommands(tools);
     registerProjectCommands(tools);
     register3DCommands(tools);
+    registerDetectCommand(tools);
+    registerVideoReviewCommand(tools);
 }

package/dist/index.js

@@ -23,6 +23,7 @@ import { registerPrefabCommands } from './commands/prefab.js';
 import { registerRecommendCommands } from './commands/recommend.js';
 import { registerRemixCommands } from './commands/remix.js';
 import { registerSkillsCommands } from './commands/skills.js';
+import { registerPradCommands } from './commands/prad.js';
 import { register3DCommands } from './commands/3d.js';
 import { CLI_ROOT_DESCRIPTION, getCliTopicsHelpText, registerRootProgramHelp, } from './cli-root-help.js';
 const __filename = fileURLToPath(import.meta.url);
@@ -357,6 +358,7 @@ registerRecommendCommands(program);
 registerRemixCommands(program);
 // 开发时 Skill 发现与脚手架 (playcraft skills <command>)
 registerSkillsCommands(program);
+registerPradCommands(program);
 // 3D model utilities (playcraft 3d <command>)
 register3DCommands(program);
 program.parse(process.argv);

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;
+}

package/dist/prad/check.js

@@ -0,0 +1,377 @@
+import * as fs from 'node:fs';
+import { atomIdFromInstance, parseAtomRef } from './atom-ref.js';
+import { loadGateRequirements, loadSpineRegistry } from './load-spec.js';
+import { walkPradDocument, parentEntityPath, resolvePath } from './paths.js';
+import { effectiveAtomId, loadManifestImports, loadRegistryAtomIds, } from './skills-index.js';
+function pushIssue(list, issue) {
+    list.push(issue);
+}
+function collectAtomRefsFromDoc(doc) {
+    const map = new Map();
+    const engine = doc.engine;
+    const engineRef = typeof engine === 'string' ? parseAtomRef(engine) : parseAtomRef(engine?.atom);
+    if (engineRef)
+        map.set(engineRef.id, engineRef);
+    const remixSpec = doc.meta?.remixSpec;
+    const remixAtom = atomIdFromInstance(remixSpec);
+    if (remixAtom) {
+        const ref = parseAtomRef(remixSpec.atom);
+        if (ref)
+            map.set(ref.id, ref);
+    }
+    for (const visit of walkPradDocument(doc)) {
+        if (visit.kind === 'entity' && visit.entity) {
+            const ref = parseAtomRef(visit.entity.atom);
+            if (ref)
+                map.set(ref.id, ref);
+        }
+        if (visit.mediaInstance) {
+            const ref = parseAtomRef(visit.mediaInstance.atom);
+            if (ref)
+                map.set(ref.id, ref);
+        }
+    }
+    return map;
+}
+function parseLedger(doc) {
+    const ledger = new Map();
+    const meta = doc.meta;
+    for (const entry of meta?.atomLedger ?? []) {
+        if (entry?.id)
+            ledger.set(entry.id, entry);
+    }
+    return ledger;
+}
+export function checkPradDocument(doc, options = {}) {
+    const errors = [];
+    const warnings = [];
+    const gate = options.gate ?? doc.meta?.gate ?? 4;
+    const meta = doc.meta;
+    const pradVersion = meta?.pradVersion;
+    if (!pradVersion && !options.legacy) {
+        pushIssue(warnings, {
+            code: 'PRAD-W001',
+            severity: 'warning',
+            path: 'meta.pradVersion',
+            message: 'Missing pradVersion; treat as legacy v0.1',
+        });
+    }
+    const isV02Plus = pradVersion === '0.2' || pradVersion === '0.2.1';
+    const isV021 = pradVersion === '0.2.1';
+    const registry = loadRegistryAtomIds(options.skillsDir);
+    const spineReg = loadSpineRegistry(options.specDir);
+    const gateReq = loadGateRequirements(options.specDir);
+    const gateConfig = gateReq.gates[String(gate)];
+    const docAtoms = collectAtomRefsFromDoc(doc);
+    const ledger = parseLedger(doc);
+    // S2: atom resolve
+    for (const [atomId, ref] of docAtoms) {
+        if (ref.resolve === 'draft') {
+            const issue = {
+                code: options.strictDrafts ? 'PRAD-E020' : 'PRAD-W020',
+                severity: options.strictDrafts ? 'error' : 'warning',
+                path: atomId,
+                message: `Draft atom "${atomId}"${ref.substitute ? ` (substitute: ${ref.substitute})` : ''}`,
+            };
+            if (ref.substitute && !registry.has(ref.substitute)) {
+                pushIssue(errors, {
+                    code: 'PRAD-E023',
+                    severity: 'error',
+                    path: atomId,
+                    message: `Draft substitute "${ref.substitute}" not in Skills registry`,
+                });
+            }
+            else if (!ref.substitute) {
+                pushIssue(errors, {
+                    code: 'PRAD-E023',
+                    severity: 'error',
+                    path: atomId,
+                    message: `Draft atom "${atomId}" missing substitute`,
+                });
+            }
+            else {
+                pushIssue(options.strictDrafts ? errors : warnings, issue);
+            }
+        }
+        else if (!registry.has(atomId)) {
+            pushIssue(errors, {
+                code: 'PRAD-E020',
+                severity: 'error',
+                path: atomId,
+                message: `Unknown registry atom "${atomId}"`,
+            });
+        }
+    }
+    // S2b: atomLedger consistency
+    if (isV02Plus && gate >= 4) {
+        if (!meta?.atomLedger?.length) {
+            pushIssue(errors, {
+                code: 'PRAD-E022',
+                severity: 'error',
+                path: 'meta.atomLedger',
+                message: 'Gate 4 requires meta.atomLedger',
+            });
+        }
+    }
+    for (const [atomId, ref] of docAtoms) {
+        const ledgerEntry = ledger.get(atomId);
+        if (isV02Plus && gate >= 2 && !ledgerEntry) {
+            pushIssue(warnings, {
+                code: 'PRAD-E022',
+                severity: 'warning',
+                path: 'meta.atomLedger',
+                message: `Atom "${atomId}" used in document but missing from atomLedger`,
+            });
+        }
+        if (ledgerEntry && ledgerEntry.resolve !== ref.resolve) {
+            pushIssue(errors, {
+                code: 'PRAD-E022',
+                severity: 'error',
+                path: 'meta.atomLedger',
+                message: `Ledger resolve for "${atomId}" (${ledgerEntry.resolve}) != node (${ref.resolve})`,
+            });
+        }
+    }
+    for (const [atomId, entry] of ledger) {
+        if (entry.resolve === 'draft' && !entry.substitute) {
+            pushIssue(errors, {
+                code: 'PRAD-E023',
+                severity: 'error',
+                path: 'meta.atomLedger',
+                message: `Ledger draft "${atomId}" missing substitute`,
+            });
+        }
+        if (entry.resolve === 'draft' && entry.substitute && !registry.has(entry.substitute)) {
+            pushIssue(errors, {
+                code: 'PRAD-E023',
+                severity: 'error',
+                path: 'meta.atomLedger',
+                message: `Ledger substitute "${entry.substitute}" for "${atomId}" not in registry`,
+            });
+        }
+    }
+    if (isV02Plus && gate >= 4 && gateConfig?.requiredMeta?.includes('atomLedger')) {
+        for (const [atomId, ref] of docAtoms) {
+            if (ref.resolve === 'draft' && gate >= 4) {
+                pushIssue(warnings, {
+                    code: 'PRAD-W020',
+                    severity: 'warning',
+                    path: atomId,
+                    message: `Gate 4 document still contains draft atom "${atomId}" (compile uses substitute)`,
+                });
+            }
+        }
+    }
+    // S5: slot vs spine-registry
+    const presentSpines = new Set();
+    if (isV02Plus && gateConfig?.entitySlotRequired) {
+        for (const visit of walkPradDocument(doc)) {
+            if (visit.kind !== 'entity' || !visit.entity)
+                continue;
+            const slot = visit.entity.slot;
+            const sinceGate = visit.entity.sinceGate;
+            if (!slot?.spine) {
+                pushIssue(errors, {
+                    code: 'PRAD-E025',
+                    severity: 'error',
+                    path: visit.path,
+                    message: 'Entity missing slot.spine (required Gate 3+)',
+                });
+                continue;
+            }
+            if (!spineReg.spines[slot.spine]) {
+                pushIssue(errors, {
+                    code: 'PRAD-E025',
+                    severity: 'error',
+                    path: visit.path,
+                    message: `Unknown spine "${slot.spine}"`,
+                });
+            }
+            else {
+                presentSpines.add(slot.spine);
+            }
+            if (sinceGate != null && meta?.gate != null && sinceGate > meta.gate) {
+                pushIssue(errors, {
+                    code: 'PRAD-E027',
+                    severity: 'error',
+                    path: visit.path,
+                    message: `sinceGate ${sinceGate} > meta.gate ${meta.gate}`,
+                });
+            }
+            if (sinceGate != null && sinceGate > gate) {
+                pushIssue(errors, {
+                    code: 'PRAD-E027',
+                    severity: 'error',
+                    path: visit.path,
+                    message: `sinceGate ${sinceGate} > check gate ${gate}`,
+                });
+            }
+        }
+    }
+    for (const req of gateConfig?.requiredSpines ?? []) {
+        if (req.criticality !== 'required')
+            continue;
+        const spine = spineReg.spines[req.spine];
+        if (spine?.globalsKey) {
+            const globals = doc.globals;
+            if (!globals?.[spine.globalsKey]) {
+                pushIssue(errors, {
+                    code: 'PRAD-E040',
+                    severity: 'error',
+                    path: `globals.${spine.globalsKey}`,
+                    message: `Required spine ${req.spine} (globals.${spine.globalsKey}) missing`,
+                });
+            }
+            continue;
+        }
+        if (spine?.topLevelKey) {
+            if (!(spine.topLevelKey in doc)) {
+                pushIssue(errors, {
+                    code: 'PRAD-E040',
+                    severity: 'error',
+                    path: spine.topLevelKey,
+                    message: `Required spine ${req.spine} (${spine.topLevelKey}) missing`,
+                });
+            }
+            continue;
+        }
+        if (spine?.metaKey) {
+            const metaObj = doc.meta;
+            if (!metaObj?.[spine.metaKey]) {
+                pushIssue(errors, {
+                    code: 'PRAD-E040',
+                    severity: 'error',
+                    path: `meta.${spine.metaKey}`,
+                    message: `Required spine ${req.spine} (meta.${spine.metaKey}) missing`,
+                });
+            }
+            continue;
+        }
+        if (!presentSpines.has(req.spine)) {
+            pushIssue(errors, {
+                code: 'PRAD-E040',
+                severity: 'error',
+                path: req.spine,
+                message: `Required spine ${req.spine} not present on any entity`,
+            });
+        }
+    }
+    // S3b: bindAs on media (Gate 2+ when enabled)
+    if (isV02Plus && gate >= 2 && gateConfig?.bindAsRequiredOnMedia !== false) {
+        for (const visit of walkPradDocument(doc)) {
+            if (visit.kind === 'global') {
+                const inst = visit.mediaInstance;
+                if (!inst?.bindAs) {
+                    pushIssue(gate >= 4 ? errors : warnings, {
+                        code: 'PRAD-E026',
+                        severity: gate >= 4 ? 'error' : 'warning',
+                        path: visit.path,
+                        message: 'Global atom instance missing bindAs',
+                    });
+                }
+                continue;
+            }
+            if (visit.kind !== 'media' || !visit.mediaInstance || !visit.parentEntityAtom)
+                continue;
+            const bindAs = visit.mediaInstance.bindAs;
+            if (!bindAs) {
+                pushIssue(gate >= 4 ? errors : warnings, {
+                    code: 'PRAD-E026',
+                    severity: gate >= 4 ? 'error' : 'warning',
+                    path: visit.path,
+                    message: 'Media instance missing bindAs',
+                });
+                continue;
+            }
+            if (bindAs.startsWith('globals.'))
+                continue;
+            const bindTargetRef = visit.mediaInstance.bindTargetRef;
+            let targetEntityPath;
+            let targetEntityAtom;
+            if (bindTargetRef) {
+                if (!isV021) {
+                    pushIssue(warnings, {
+                        code: 'PRAD-W021',
+                        severity: 'warning',
+                        path: visit.path,
+                        message: 'bindTargetRef ignored on pradVersion < 0.2.1',
+                    });
+                    targetEntityPath = parentEntityPath(visit.path);
+                    targetEntityAtom = visit.parentEntityAtom;
+                }
+                else {
+                    const targetVisit = resolvePath(doc, bindTargetRef);
+                    if (!targetVisit || targetVisit.kind !== 'entity' || !targetVisit.entity) {
+                        pushIssue(errors, {
+                            code: 'PRAD-E028',
+                            severity: 'error',
+                            path: visit.path,
+                            message: `bindTargetRef "${bindTargetRef}" is not a valid entity path`,
+                        });
+                        continue;
+                    }
+                    targetEntityPath = bindTargetRef;
+                    targetEntityAtom = parseAtomRef(targetVisit.entity.atom) ?? undefined;
+                    if (!targetEntityAtom)
+                        continue;
+                }
+            }
+            else {
+                targetEntityPath = parentEntityPath(visit.path);
+                targetEntityAtom = visit.parentEntityAtom;
+            }
+            const targetEffective = effectiveAtomId(targetEntityAtom);
+            const imports = loadManifestImports(targetEffective, options.skillsDir);
+            const e026Severity = isV021 && gate >= 4 ? 'error' : 'warning';
+            const e026List = isV021 && gate >= 4 ? errors : warnings;
+            if (!imports || imports.bindAsSet.size === 0) {
+                if (isV021 && gate >= 4) {
+                    pushIssue(e026List, {
+                        code: 'PRAD-E026',
+                        severity: e026Severity,
+                        path: visit.path,
+                        message: `bindAs "${bindAs}" targets ${targetEffective} which has no manifest imports`,
+                    });
+                }
+                else if (imports && imports.bindAsSet.size > 0) {
+                    // unreachable
+                }
+                continue;
+            }
+            if (!imports.bindAsSet.has(bindAs)) {
+                pushIssue(e026List, {
+                    code: 'PRAD-E026',
+                    severity: e026Severity,
+                    path: visit.path,
+                    message: `bindAs "${bindAs}" not in ${targetEffective} manifest imports (known: ${[...imports.bindAsSet].join(', ')})`,
+                });
+            }
+        }
+    }
+    // Gate 4 review
+    if (gate >= 4) {
+        const review = doc.review;
+        if (!review) {
+            pushIssue(errors, { code: 'PRAD-E050', severity: 'error', path: 'review', message: 'Missing review block' });
+        }
+        else if (review.pass !== true) {
+            pushIssue(errors, { code: 'PRAD-E050', severity: 'error', path: 'review.pass', message: 'review.pass must be true' });
+        }
+    }
+    return { ok: errors.length === 0, errors, warnings };
+}
+export function checkPradFile(filePath, options = {}) {
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    let doc;
+    try {
+        doc = JSON.parse(raw);
+    }
+    catch {
+        return {
+            ok: false,
+            errors: [{ code: 'PRAD-E001', severity: 'error', path: filePath, message: 'Invalid JSON' }],
+            warnings: [],
+        };
+    }
+    return checkPradDocument(doc, options);
+}

package/dist/prad/check.test.js

@@ -0,0 +1,49 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { checkPradFile } from './check.js';
+import { explainPradPath, formatExplain } from './explain.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const mahjongSample = path.resolve(__dirname, '..', '..', '..', '..', 'docs', 'prad', 'samples', 'mahjong-gate4.atom-tree.json');
+describe('prad check', () => {
+    it('mahjong gate4 v0.2.1 passes with no E026 and draft warnings only', () => {
+        if (!fs.existsSync(mahjongSample))
+            return;
+        const result = checkPradFile(mahjongSample, { gate: 4 });
+        expect(result.errors).toEqual([]);
+        expect(result.warnings.some((w) => w.code === 'PRAD-W020')).toBe(true);
+        expect(result.warnings.some((w) => w.code === 'PRAD-E026')).toBe(false);
+        expect(result.errors.some((e) => e.code === 'PRAD-E026')).toBe(false);
+        expect(result.ok).toBe(true);
+    });
+    it('explain play_btn path', () => {
+        if (!fs.existsSync(mahjongSample))
+            return;
+        const doc = JSON.parse(fs.readFileSync(mahjongSample, 'utf-8'));
+        const result = explainPradPath(doc, 'scenes.entry.ui_layer.play_btn');
+        expect(result.found).toBe(true);
+        expect(result.slot?.spine).toBe('medium.hook.play');
+        expect(formatExplain(result)).toContain('medium.hook.play');
+    });
+    it('explain rule_engine itemSprites uses pick_and_match manifest', () => {
+        if (!fs.existsSync(mahjongSample))
+            return;
+        const doc = JSON.parse(fs.readFileSync(mahjongSample, 'utf-8'));
+        const result = explainPradPath(doc, 'scenes.gameplay.board_layer.rule_engine.props.itemSprites');
+        expect(result.found).toBe(true);
+        expect(result.bindAs).toBe('itemSprites');
+        expect(result.parentEffectiveAtom).toBe('pick_and_match_rules.aigameplay');
+        expect(result.manifestImportSlots).toContain('itemSprites');
+    });
+    it('explain hint_btn icon bindAs fingerTexture on tutorial_overlay', () => {
+        if (!fs.existsSync(mahjongSample))
+            return;
+        const doc = JSON.parse(fs.readFileSync(mahjongSample, 'utf-8'));
+        const result = explainPradPath(doc, 'scenes.gameplay.hud_layer.hint_btn.props.icon');
+        expect(result.found).toBe(true);
+        expect(result.bindAs).toBe('fingerTexture');
+        expect(result.parentEffectiveAtom).toBe('tutorial_overlay.aicomponent');
+        expect(result.manifestImportSlots).toContain('fingerTexture');
+    });
+});