@mindscraft/branch-video-agent-cli 0.4.1 → 0.4.3

package/README.md

@@ -31,9 +31,9 @@ branch-video-agent --version
 - `AIHUB_AGENT_TOKEN`
 - `BRANCH_VIDEO_AGENT_BASE_URL`
 
-AI Gateway 调用同样只传 `AIHUB_AGENT_TOKEN`；CLI 不读取、不传递 `AiGatewayKey` 或 AIHub `projectKey`，上游鉴权由服务端处理。
-
-AI Gateway 生产媒体验收使用 `ai-gateway media-understand --raw`。P0 模型固定为 `doubao-seed-2-0-mini-260215`，输入为带 SHA-256 的公共 HTTPS 图片/视频 URL、一个 candidate、可选 reference、prompt 与 criteria；输出为 `media_acceptance_review.v1`。该能力只判断可见画面，不声称分析视频音轨。`kimi-k3` 和 `MiniMax-M3` 在真实 payload Canary 通过前不可调用。
+AI Gateway 调用同样只传 `AIHUB_AGENT_TOKEN`；CLI 不读取、不传递 `AiGatewayKey` 或 AIHub `projectKey`，上游鉴权由服务端处理。
+
+AI Gateway 生产媒体验收使用 `ai-gateway media-understand --raw`。P0 模型固定为 `doubao-seed-2-0-mini-260215`，输入为带 SHA-256 的公共 HTTPS 图片/视频 URL、一个 candidate、可选 reference、prompt 与 criteria；输出为 `media_acceptance_review.v1`。该能力只判断可见画面，不声称分析视频音轨。`kimi-k3` 和 `MiniMax-M3` 在真实 payload Canary 通过前不可调用。
 
 最小调用示例：
 
@@ -47,6 +47,57 @@ AI Gateway 生产媒体验收使用 `ai-gateway media-understand --raw`。P0 模
 '@ | npm exec --yes --package=@mindscraft/branch-video-agent-cli branch-video-agent -- project list
 ```
 
+## BV V3 全分支可播放性测试
+
+`playtest run` 从 `0.4.0` 起提供，使用 Playwright Chromium 驱动真实播放器。命令只读草稿或已发布版本，不会保存测试副本或自动发布；运行前仍应先通过 V3 静态 self-test。
+
+场景规划保留较长路线，删除其完整前缀场景；沿途动作、条件、状态效果和检查仍随长路线执行。`maxScenarios` 限制去重后的场景数；无法在步骤、访问次数或搜索预算内到达的边仍会使规划失败。
+
+搜索展开上限的数值不变；可安全去重的相同状态不重复计入，其他状态沿原搜索计数。
+
+```powershell
+@'
+{
+  "source": { "kind": "draft", "projectId": "project-id" },
+  "contractPath": "project.playtest.json",
+  "reportDir": "playtest-results",
+  "concurrency": 2,
+  "limits": {
+    "scenarioTimeoutMs": 60000,
+    "maxStepsPerScenario": 100,
+    "maxScenarios": 500,
+    "maxNodeVisits": 3
+  }
+}
+'@ | branch-video-agent playtest run
+```
+
+发布版把 `source` 改为 `{ "kind": "published", "projectId": "...", "version": 3, "playUrl": "<发布接口返回值>" }`。CLI 会先读回精确版本并比较规范化内容摘要，再直接使用 `playUrl`；漂移返回 `PUBLISHED_SCRIPT_MISMATCH`。该 SHA-256 摘要只由 sidecar 绑定、发布读回比较和报告追踪消费，不是身份认证、数字签名或 HMAC。
+
+sidecar 使用 `branch-video-playtest/1`，Web 结果必须提供 iframe 内的真实操作，不接受测试侧消息注入：
+
+```json
+{
+  "schemaVersion": "branch-video-playtest/1",
+  "scriptFingerprint": "sha256:...",
+  "webResults": [{
+    "nodeId": "web_quiz",
+    "routeValue": "success",
+    "rawMessage": { "eventName": "ActivityData", "value": "1" },
+    "steps": [{
+      "action": "click",
+      "locator": { "by": "role", "role": "button", "name": "正确答案" }
+    }]
+  }]
+}
+```
+
+支持 `click`、`fill`、`selectOption`、`check`、`press`、`dragTo`、`setInputFiles` 和 `waitFor`。只要输入中有合法 `reportDir`，静态门禁、契约、版本漂移和浏览器启动等前置失败也会输出 `branch-video-playtest-report.json`、`junit.xml`；失败场景另存截图、trace、视频和浏览器日志。若 Chromium 缺失，执行 `npx playwright install chromium`。
+
+CI 顺序为：V3 静态 self-test → 草稿 `playtest run` → 外部发布步骤 → `version get` 精确内容读回。发布内容与已测草稿一致时无需再跑发布版全量测试；内容变化后应重新测试。`playtest run` 自身始终只读，不承担发布。
+
+从 `0.4.3` 起，规划器删除被更长场景完整包含的有序前缀场景，保留条件、状态效果与全部目标边；场景数由实际图决定，不固定为 96。重复搜索状态也会合并以减少规划开销。覆盖或路径预算失败仍返回失败，不通过删边取得通过。复测时记录实际可执行文件路径；升级全局 npm 包不会更新任务内复制的旧 CLI。
+
 AIHub 导入公共库示例：
 
 ```powershell

package/dist/commands/playtest.d.ts

@@ -0,0 +1,2 @@
+import type { CommandHandler } from '../lib/types.js';
+export declare const playtestCommands: Record<string, CommandHandler>;

package/dist/commands/playtest.js

@@ -0,0 +1,200 @@
+import { CliCommandError } from '../lib/errors.js';
+import { validatePlaytestContract } from '../playtest/contract.js';
+import { PlaytestError } from '../playtest/errors.js';
+import { createScriptFingerprint } from '../playtest/fingerprint.js';
+import { getReachablePlaytestGraph } from '../playtest/graph.js';
+import { writePlaytestReport } from '../playtest/report.js';
+import { createDraftPlayerUrl, createPublishedPlayerUrl, runPlaytestScenarios } from '../playtest/runner.js';
+import { buildPlaytestScenarios } from '../playtest/scenarios.js';
+import { assertPlaytestStaticPreflight } from '../playtest/staticPreflight.js';
+const DEFAULT_LIMITS = {
+    scenarioTimeoutMs: 60000,
+    maxStepsPerScenario: 100,
+    maxScenarios: 500,
+    maxNodeVisits: 3,
+};
+function isObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function parseInput(payload) {
+    const source = payload.source;
+    if (!isObject(source) || (source.kind !== 'draft' && source.kind !== 'published') || typeof source.projectId !== 'string') {
+        throw new PlaytestError('VALIDATION_ERROR', 'source.kind and source.projectId are required');
+    }
+    if (source.kind === 'published' && (!Number.isInteger(source.version) || source.version <= 0 || typeof source.playUrl !== 'string')) {
+        throw new PlaytestError('VALIDATION_ERROR', 'published source requires positive version and server-returned playUrl');
+    }
+    if (typeof payload.contractPath !== 'string' || typeof payload.reportDir !== 'string') {
+        throw new PlaytestError('VALIDATION_ERROR', 'contractPath and reportDir are required');
+    }
+    return payload;
+}
+function extractScript(response) {
+    const candidate = response;
+    const script = candidate?.script ?? candidate?.data?.script ?? candidate?.draft?.script ?? candidate?.project?.script;
+    if (!isObject(script))
+        throw new PlaytestError('SCRIPT_READ_FAILED', 'server response does not contain a V3 script');
+    return script;
+}
+async function readSourceScript(source, client) {
+    const projectId = encodeURIComponent(source.projectId);
+    if (source.kind === 'draft') {
+        return client.request(`/api/branch-video/${projectId}`, { method: 'GET' });
+    }
+    return client.request(`/api/branch-video/${projectId}/versions/${source.version}`, { method: 'GET' });
+}
+function normalizePositiveInt(value, fallback, name) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isInteger(value) || Number(value) <= 0)
+        throw new PlaytestError('VALIDATION_ERROR', `${name} must be a positive integer`);
+    return Number(value);
+}
+async function runPlaytest({ client, payload, runtime }) {
+    const startedAt = new Date().toISOString();
+    let input = null;
+    let source = null;
+    let fingerprint = null;
+    let requestId = null;
+    let reachableNodeIds = [];
+    let reachableEdgeIds = [];
+    let scenarioResults = [];
+    let phase = 'input';
+    try {
+        input = parseInput(payload);
+        source = input.source;
+        phase = 'source-read';
+        const sourceResult = await readSourceScript(input.source, client);
+        requestId = sourceResult.requestId;
+        const script = extractScript(sourceResult.data);
+        fingerprint = createScriptFingerprint(script);
+        phase = 'static-preflight';
+        assertPlaytestStaticPreflight(script);
+        phase = 'contract';
+        let rawContract;
+        try {
+            rawContract = JSON.parse(await runtime.readTextFile(input.contractPath));
+        }
+        catch (error) {
+            throw new PlaytestError('PLAYTEST_CONTRACT_INVALID', `Cannot read playtest contract: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (input.source.kind === 'published' && (!isObject(rawContract) || rawContract.scriptFingerprint !== fingerprint)) {
+            throw new PlaytestError('PUBLISHED_SCRIPT_MISMATCH', 'published version readback does not match the playtest contract fingerprint', {
+                expected: isObject(rawContract) ? rawContract.scriptFingerprint : null,
+                actual: fingerprint,
+                projectId: input.source.projectId,
+                version: input.source.version,
+            });
+        }
+        const contract = validatePlaytestContract(script, rawContract);
+        const limits = {
+            scenarioTimeoutMs: normalizePositiveInt(input.limits?.scenarioTimeoutMs, DEFAULT_LIMITS.scenarioTimeoutMs, 'limits.scenarioTimeoutMs'),
+            maxStepsPerScenario: normalizePositiveInt(input.limits?.maxStepsPerScenario, DEFAULT_LIMITS.maxStepsPerScenario, 'limits.maxStepsPerScenario'),
+            maxScenarios: normalizePositiveInt(input.limits?.maxScenarios, DEFAULT_LIMITS.maxScenarios, 'limits.maxScenarios'),
+            maxNodeVisits: normalizePositiveInt(input.limits?.maxNodeVisits, DEFAULT_LIMITS.maxNodeVisits, 'limits.maxNodeVisits'),
+        };
+        const concurrency = Math.min(8, normalizePositiveInt(input.concurrency, 2, 'concurrency'));
+        const viewport = input.viewport || { width: 1280, height: 720 };
+        phase = 'scenario-generation';
+        const scenarios = buildPlaytestScenarios(script, limits, contract.nodeVisitLimits);
+        const graph = getReachablePlaytestGraph(script);
+        reachableNodeIds = graph.reachableNodeIds;
+        reachableEdgeIds = graph.reachableEdges.map((edge) => edge.id);
+        const draftPlayer = input.source.kind === 'draft' ? createDraftPlayerUrl(client.resolveUrl('/')) : null;
+        const playerUrl = input.source.kind === 'draft'
+            ? draftPlayer.playerUrl
+            : createPublishedPlayerUrl(input.source.playUrl);
+        phase = 'browser';
+        scenarioResults = await runPlaytestScenarios({
+            script,
+            contract,
+            scenarios,
+            playerUrl,
+            draftScriptUrl: draftPlayer?.scriptUrl,
+            reportDir: input.reportDir,
+            concurrency,
+            limits,
+            viewport,
+        });
+        const coveredNodeIds = [...new Set(scenarioResults.flatMap((result) => result.visitedNodes))];
+        const coveredEdgeIds = [...new Set(scenarioResults.flatMap((result) => result.coveredEdges))];
+        const findings = scenarioResults.flatMap((result) => result.findings);
+        const warnings = [...new Map(scenarioResults
+                .flatMap((result) => result.warnings)
+                .map((warning) => [`${warning.code}:${warning.message}`, warning])).values()];
+        phase = 'coverage';
+        for (const nodeId of graph.reachableNodeIds) {
+            if (!coveredNodeIds.includes(nodeId))
+                findings.push({ code: 'NODE_UNCOVERED', message: `Reachable node ${nodeId} was not rendered`, nodeId, phase });
+        }
+        for (const edge of graph.reachableEdges) {
+            if (!coveredEdgeIds.includes(edge.id))
+                findings.push({ code: 'EDGE_UNCOVERED', message: `Reachable edge ${edge.id} was not covered`, edgeId: edge.id, phase });
+        }
+        const report = {
+            schemaVersion: 'branch-video-playtest-report/1',
+            source: input.source,
+            scriptFingerprint: fingerprint,
+            startedAt,
+            finishedAt: new Date().toISOString(),
+            status: findings.length ? 'failed' : 'passed',
+            reachableNodeIds,
+            reachableEdgeIds,
+            coveredNodeIds,
+            coveredEdgeIds,
+            scenarios: scenarioResults,
+            findings,
+            warnings,
+        };
+        const reportPaths = await writePlaytestReport(input.reportDir, report);
+        if (report.status === 'failed') {
+            const first = report.findings[0];
+            throw new PlaytestError(first?.code || 'PLAYTEST_FAILED', first?.message || 'BV V3 playtest failed', { reportPaths, report });
+        }
+        return { data: { report, reportPaths }, requestId };
+    }
+    catch (error) {
+        if (error instanceof PlaytestError && isObject(error.details) && error.details.reportPaths)
+            throw error;
+        const failure = error instanceof PlaytestError
+            ? error
+            : error instanceof CliCommandError
+                ? new PlaytestError(error.code, error.message, { data: error.data, requestId: error.requestId, status: error.status })
+                : new PlaytestError('PLAYTEST_FAILED', error instanceof Error ? error.message : String(error));
+        const reportDir = input?.reportDir ?? (typeof payload.reportDir === 'string' ? payload.reportDir : null);
+        if (!reportDir)
+            throw failure;
+        const finding = { code: failure.code, message: failure.message, phase, details: failure.details };
+        const report = {
+            schemaVersion: 'branch-video-playtest-report/1',
+            source,
+            scriptFingerprint: fingerprint,
+            startedAt,
+            finishedAt: new Date().toISOString(),
+            status: 'failed',
+            reachableNodeIds,
+            reachableEdgeIds,
+            coveredNodeIds: [...new Set(scenarioResults.flatMap((result) => result.visitedNodes))],
+            coveredEdgeIds: [...new Set(scenarioResults.flatMap((result) => result.coveredEdges))],
+            scenarios: scenarioResults,
+            findings: [finding],
+            warnings: [],
+        };
+        const reportPaths = await writePlaytestReport(reportDir, report);
+        throw new PlaytestError(failure.code, failure.message, { reportPaths, report });
+    }
+}
+export const playtestCommands = {
+    run: async (context) => {
+        try {
+            return await runPlaytest(context);
+        }
+        catch (error) {
+            if (error instanceof CliCommandError)
+                throw error;
+            if (error instanceof PlaytestError)
+                throw new CliCommandError(error.message, error.code, error.details);
+            throw error;
+        }
+    },
+};

package/dist/index.js

@@ -6,6 +6,7 @@ import { versionCommands } from './commands/version.js';
 import { workflowCommands } from './commands/workflow.js';
 import { characterCommands } from './commands/character.js';
 import { aiGatewayCommands } from './commands/aiGateway.js';
+import { playtestCommands } from './commands/playtest.js';
 import { CliCommandError } from './lib/errors.js';
 import { getCliHelpText, parseCliArgs, resolveCliConfig } from './lib/flags.js';
 import { CliHttpClient } from './lib/http.js';
@@ -20,6 +21,7 @@ const commandRegistry = {
     'aihub-production': productionCommands,
     character: characterCommands,
     'ai-gateway': aiGatewayCommands,
+    playtest: playtestCommands,
 };
 function normalizeError(error) {
     if (error instanceof CliCommandError) {
@@ -44,7 +46,7 @@ function writeError(runtime, command, raw, error) {
     }
     writeJson(runtime, {
         ok: false,
-        data: null,
+        data: error.data ?? null,
         error: error.message,
         code: error.code,
         requestId: error.requestId || null,

package/dist/lib/flags.js

@@ -101,6 +101,7 @@ export function getCliHelpText() {
         '  aihub-production schema | start | status | retry',
         '  character  search | create | get',
         '  ai-gateway capabilities | request | media-understand | image-generate | image-edit | video-create | video-get | seed-audio-create | seed-audio-get | music-submit | music-get | tts-create | tts-get',
+        '  playtest   run',
         '',
         'Config precedence:',
         '  AIHUB_AGENT_TOKEN / BRANCH_VIDEO_AGENT_BASE_URL > stdin JSON or --token-file > command flags',

package/dist/lib/http.d.ts

@@ -13,6 +13,7 @@ export declare class CliHttpClient {
     private readonly token;
     private readonly fetchImpl;
     constructor(baseUrl: string, token: string, fetchImpl: typeof fetch);
+    resolveUrl(path: string): string;
     request<T>(path: string, options: RequestOptions): Promise<RequestResult<T>>;
 }
 export {};

package/dist/lib/http.js

@@ -26,6 +26,9 @@ export class CliHttpClient {
         this.token = token;
         this.fetchImpl = fetchImpl;
     }
+    resolveUrl(path) {
+        return buildUrl(this.baseUrl, path);
+    }
     async request(path, options) {
         const headers = {
             Authorization: `Bearer ${this.token}`,

package/dist/playtest/contract.d.ts

@@ -0,0 +1,2 @@
+import type { PlaytestContract } from './types.js';
+export declare function validatePlaytestContract(script: unknown, rawContract: unknown): PlaytestContract;

package/dist/playtest/contract.js

@@ -0,0 +1,119 @@
+import { createScriptFingerprint } from './fingerprint.js';
+import { getReachablePlaytestGraph } from './graph.js';
+import { PlaytestError } from './errors.js';
+const ACTIONS = new Set(['click', 'fill', 'selectOption', 'check', 'press', 'dragTo', 'setInputFiles', 'waitFor']);
+const LOCATORS = new Set(['role', 'label', 'testId', 'css']);
+function isObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function assertLocator(locator, path) {
+    if (!isObject(locator) || !LOCATORS.has(locator.by)) {
+        throw new PlaytestError('PLAYTEST_CONTRACT_INVALID', `${path} must use role, label, testId, or css locator`);
+    }
+    if (locator.by === 'role' && typeof locator.role !== 'string') {
+        throw new PlaytestError('PLAYTEST_CONTRACT_INVALID', `${path}.role is required`);
+    }
+    if (locator.by === 'label' && typeof locator.label !== 'string') {
+        throw new PlaytestError('PLAYTEST_CONTRACT_INVALID', `${path}.label is required`);
+    }
+    if (locator.by === 'testId' && typeof locator.testId !== 'string') {
+        throw new PlaytestError('PLAYTEST_CONTRACT_INVALID', `${path}.testId is required`);
+    }
+    if (locator.by === 'css' && typeof locator.selector !== 'string') {
+        throw new PlaytestError('PLAYTEST_CONTRACT_INVALID', `${path}.selector is required`);
+    }
+}
+function assertStep(step, path) {
+    if (!isObject(step) || !ACTIONS.has(step.action)) {
+        throw new PlaytestError('PLAYTEST_CONTRACT_INVALID', `${path}.action is unsupported`);
+    }
+    assertLocator(step.locator, `${path}.locator`);
+    if (step.action === 'dragTo')
+        assertLocator(step.target, `${path}.target`);
+}
+function rawMappingValue(rawMessage) {
+    if (rawMessage.eventName === 'PageEnd')
+        return '*';
+    const value = rawMessage.value ?? (isObject(rawMessage.data) ? rawMessage.data.value ?? rawMessage.data.result : rawMessage.data);
+    if (typeof value === 'string')
+        return value;
+    return value === undefined ? '' : JSON.stringify(value);
+}
+export function validatePlaytestContract(script, rawContract) {
+    if (!isObject(rawContract) || rawContract.schemaVersion !== 'branch-video-playtest/1') {
+        throw new PlaytestError('PLAYTEST_CONTRACT_INVALID', 'contract schemaVersion must be branch-video-playtest/1');
+    }
+    const scriptFingerprint = createScriptFingerprint(script);
+    if (rawContract.scriptFingerprint !== scriptFingerprint) {
+        throw new PlaytestError('SCRIPT_FINGERPRINT_MISMATCH', 'playtest contract does not match the normalized script fingerprint', {
+            expected: rawContract.scriptFingerprint,
+            actual: scriptFingerprint,
+        });
+    }
+    if (!Array.isArray(rawContract.webResults)) {
+        throw new PlaytestError('PLAYTEST_CONTRACT_INVALID', 'contract.webResults must be an array');
+    }
+    for (const [resultIndex, result] of rawContract.webResults.entries()) {
+        if (!isObject(result) || typeof result.nodeId !== 'string' || typeof result.routeValue !== 'string') {
+            throw new PlaytestError('PLAYTEST_CONTRACT_INVALID', `webResults[${resultIndex}] must declare nodeId and routeValue`);
+        }
+        if (!isObject(result.rawMessage) || typeof result.rawMessage.eventName !== 'string') {
+            throw new PlaytestError('PLAYTEST_CONTRACT_INVALID', `webResults[${resultIndex}].rawMessage.eventName is required`);
+        }
+        if (!Array.isArray(result.steps) || result.steps.length === 0) {
+            throw new PlaytestError('WEB_PLAYTEST_RECIPE_MISSING', `Web result ${result.nodeId}:${result.routeValue} has no real-action steps`);
+        }
+        result.steps.forEach((step, stepIndex) => assertStep(step, `webResults[${resultIndex}].steps[${stepIndex}]`));
+    }
+    const nodes = script?.graph?.nodes || {};
+    const { reachableEdges, reachableNodeIds } = getReachablePlaytestGraph(script);
+    for (const nodeId of reachableNodeIds) {
+        const node = nodes[nodeId];
+        if (node?.type !== 'web')
+            continue;
+        const mapping = node.config?.messageMapping || {};
+        for (const routeValue of new Set(Object.values(mapping).filter((value) => typeof value === 'string'))) {
+            const recipe = rawContract.webResults.find((candidate) => candidate.nodeId === nodeId && candidate.routeValue === routeValue);
+            if (!recipe) {
+                throw new PlaytestError('WEB_PLAYTEST_RECIPE_MISSING', `Reachable Web result ${nodeId}:${routeValue} has no real-action recipe`, {
+                    nodeId,
+                    routeValue,
+                });
+            }
+        }
+    }
+    for (const recipe of rawContract.webResults) {
+        const node = nodes[recipe.nodeId];
+        if (node?.type !== 'web') {
+            throw new PlaytestError('PLAYTEST_CONTRACT_INVALID', `Web recipe ${recipe.nodeId}:${recipe.routeValue} does not reference a Web node`);
+        }
+        const mapping = node.config?.messageMapping || {};
+        const rawValue = rawMappingValue(recipe.rawMessage);
+        const mappedValue = typeof mapping[rawValue] === 'string' && mapping[rawValue] ? mapping[rawValue] : rawValue;
+        if (mappedValue !== recipe.routeValue) {
+            throw new PlaytestError('WEB_MESSAGE_MAPPING_MISMATCH', `Web recipe ${recipe.nodeId}:${recipe.routeValue} does not match messageMapping`, {
+                rawValue,
+                mappedValue,
+            });
+        }
+    }
+    for (const edge of reachableEdges) {
+        if (nodes[edge.from]?.type !== 'web' || edge.owner !== 'node')
+            continue;
+        const explicitRoutes = new Set(reachableEdges
+            .filter((candidate) => candidate.from === edge.from && candidate.trigger.type === 'message')
+            .map((candidate) => String(candidate.trigger.value)));
+        const recipe = edge.trigger.type === 'message'
+            ? rawContract.webResults.find((candidate) => candidate.nodeId === edge.from && candidate.routeValue === String(edge.trigger.value))
+            : edge.default
+                ? rawContract.webResults.find((candidate) => candidate.nodeId === edge.from && !explicitRoutes.has(candidate.routeValue))
+                : null;
+        if (!recipe) {
+            throw new PlaytestError('WEB_PLAYTEST_RECIPE_MISSING', `Reachable Web edge ${edge.id} has no real-action recipe`, {
+                nodeId: edge.from,
+                edgeId: edge.id,
+            });
+        }
+    }
+    return rawContract;
+}

package/dist/playtest/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class PlaytestError extends Error {
+    code: string;
+    details?: unknown;
+    constructor(code: string, message: string, details?: unknown);
+}

package/dist/playtest/errors.js

@@ -0,0 +1,10 @@
+export class PlaytestError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = 'PlaytestError';
+        this.code = code;
+        this.details = details;
+    }
+}

package/dist/playtest/fingerprint.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizeScriptForFingerprint(script: unknown): unknown;
+export declare function createScriptFingerprint(script: unknown): string;

package/dist/playtest/fingerprint.js

@@ -0,0 +1,46 @@
+import { createHash } from 'node:crypto';
+const EMPTY_ASSETS = {
+    videos: {},
+    images: {},
+    audios: {},
+    speeches: {},
+};
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function canonicalize(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => canonicalize(item));
+    }
+    if (!isRecord(value))
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .filter(([, item]) => item !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, item]) => [key, canonicalize(item)]));
+}
+export function normalizeScriptForFingerprint(script) {
+    if (!isRecord(script))
+        return canonicalize(script);
+    const normalized = { ...script };
+    delete normalized.editorData;
+    normalized.assets = {
+        ...EMPTY_ASSETS,
+        ...(isRecord(script.assets) ? script.assets : {}),
+    };
+    normalized.resources = {
+        variables: [],
+        ...(isRecord(script.resources) ? script.resources : {}),
+    };
+    if (isRecord(script.metadata)) {
+        const metadata = { ...script.metadata };
+        delete metadata.createdAt;
+        delete metadata.updatedAt;
+        normalized.metadata = metadata;
+    }
+    return canonicalize(normalized);
+}
+export function createScriptFingerprint(script) {
+    const canonicalJson = JSON.stringify(normalizeScriptForFingerprint(script));
+    return `sha256:${createHash('sha256').update(canonicalJson).digest('hex')}`;
+}

package/dist/playtest/graph.d.ts

@@ -0,0 +1,7 @@
+import type { PlaytestEdge } from './types.js';
+export declare function extractPlaytestEdges(script: unknown): PlaytestEdge[];
+export declare function getReachablePlaytestGraph(script: unknown): {
+    entryNodeId: string;
+    reachableNodeIds: string[];
+    reachableEdges: PlaytestEdge[];
+};

package/dist/playtest/graph.js

@@ -0,0 +1,115 @@
+function actionTarget(action, from) {
+    const candidate = action;
+    if (candidate?.type === 'goto' && typeof candidate.target === 'string')
+        return candidate.target;
+    if (candidate?.type === 'end')
+        return '@ended';
+    if (candidate?.type === 'restart' || candidate?.type === 'loop' || candidate?.type === 'seek' || candidate?.type === 'segment')
+        return from;
+    return null;
+}
+function addEdge(edges, from, owner, ownerId, trigger, action, isDefault = false, effects = {}) {
+    const actionRecord = action;
+    const to = actionTarget(action, from);
+    if (!to)
+        return;
+    const valuePart = trigger.value === undefined ? '' : `:${JSON.stringify(trigger.value)}`;
+    const defaultPart = isDefault ? ':default' : '';
+    edges.push({
+        id: `${from}:${owner}:${ownerId}:${trigger.type}${valuePart}${defaultPart}->${to}`,
+        from,
+        to,
+        owner,
+        ownerId,
+        trigger,
+        condition: effects.condition,
+        variableActions: effects.variableActions,
+        inventoryActions: effects.inventoryActions,
+        actionType: String(actionRecord?.type || ''),
+        action: { ...(actionRecord || {}) },
+        default: isDefault || undefined,
+    });
+}
+function addBranchConfigEdges(edges, from, owner, ownerId, config) {
+    for (const rule of config?.rules || []) {
+        const rawTrigger = rule.trigger || { type: 'unknown' };
+        const trigger = {
+            type: rawTrigger.type,
+            value: rawTrigger.value ?? rawTrigger.optionId ?? rawTrigger.optionIds,
+        };
+        addEdge(edges, from, owner, ownerId, trigger, rule.action, false, {
+            condition: rule.condition,
+            variableActions: rule.variableActions,
+            inventoryActions: rule.inventoryActions,
+        });
+    }
+    addEdge(edges, from, owner, ownerId, { type: 'default' }, config?.defaultAction, true);
+}
+export function extractPlaytestEdges(script) {
+    const graph = script?.graph;
+    const nodes = graph?.nodes || {};
+    const edges = [];
+    for (const [nodeId, rawNode] of Object.entries(nodes)) {
+        const node = rawNode || {};
+        if (node.type === 'start')
+            addEdge(edges, nodeId, 'node', nodeId, { type: 'enter' }, node.config?.next);
+        if (node.type === 'video' || node.type === 'image') {
+            addEdge(edges, nodeId, 'node', nodeId, { type: 'complete' }, node.config?.onComplete);
+        }
+        addBranchConfigEdges(edges, nodeId, 'node', nodeId, node.branchConfig);
+        for (const handler of node.config?.messageHandlers || []) {
+            addEdge(edges, nodeId, 'node', nodeId, handler.when || { type: 'message' }, handler.then, false, {
+                variableActions: handler.variableActions,
+                inventoryActions: handler.inventoryActions,
+            });
+        }
+        for (const legacy of node.branches || []) {
+            addEdge(edges, nodeId, 'node', nodeId, { type: 'legacy', value: legacy.when }, legacy.then, false, {
+                condition: typeof legacy.when === 'object' ? legacy.when : undefined,
+                variableActions: legacy.variableActions,
+                inventoryActions: legacy.inventoryActions,
+            });
+        }
+        for (const interaction of node.interactions || []) {
+            addBranchConfigEdges(edges, nodeId, 'interaction', interaction.id, interaction.branchConfig);
+            for (const legacy of interaction.branches || []) {
+                addEdge(edges, nodeId, 'interaction', interaction.id, { type: 'legacy', value: legacy.when }, legacy.then, false, {
+                    condition: typeof legacy.when === 'object' ? legacy.when : undefined,
+                    variableActions: legacy.variableActions,
+                    inventoryActions: legacy.inventoryActions,
+                });
+            }
+            addEdge(edges, nodeId, 'interaction', interaction.id, { type: 'timeout' }, interaction.fallback?.onTimeout);
+            addEdge(edges, nodeId, 'interaction', interaction.id, { type: 'default' }, interaction.fallback?.onDefault, true);
+        }
+    }
+    for (const edge of edges) {
+        if (edge.actionType !== 'restart')
+            continue;
+        const oldTarget = edge.to;
+        edge.to = String(graph?.entryNodeId || edge.from);
+        edge.id = edge.id.replace(`->${oldTarget}`, `->${edge.to}`);
+    }
+    return [...new Map(edges.map((edge) => [edge.id, edge])).values()];
+}
+export function getReachablePlaytestGraph(script) {
+    const graph = script?.graph;
+    const nodes = graph?.nodes || {};
+    const entryNodeId = String(graph?.entryNodeId || '');
+    const allEdges = extractPlaytestEdges(script);
+    const reachableNodeIds = new Set();
+    const reachableEdges = [];
+    const queue = entryNodeId ? [entryNodeId] : [];
+    while (queue.length) {
+        const nodeId = queue.shift();
+        if (reachableNodeIds.has(nodeId))
+            continue;
+        reachableNodeIds.add(nodeId);
+        for (const edge of allEdges.filter((candidate) => candidate.from === nodeId)) {
+            reachableEdges.push(edge);
+            if (nodes[edge.to] && !reachableNodeIds.has(edge.to))
+                queue.push(edge.to);
+        }
+    }
+    return { entryNodeId, reachableNodeIds: [...reachableNodeIds], reachableEdges };
+}

package/dist/playtest/report.d.ts

@@ -0,0 +1,6 @@
+import type { PlaytestReport } from './types.js';
+export declare function createJUnitXml(report: PlaytestReport): string;
+export declare function writePlaytestReport(reportDir: string, report: PlaytestReport): Promise<{
+    jsonPath: string;
+    junitPath: string;
+}>;