@mindscraft/branch-video-agent-cli 0.3.5 → 0.4.0

package/README.md

@@ -10,12 +10,6 @@
 npm exec --yes --package=@mindscraft/branch-video-agent-cli branch-video-agent -- --help
 ```
 
-中国大陆用户如果希望更稳定、更快地安装，可以走 npm 的公开镜像：
-
-```powershell
-npm exec --yes --registry=https://registry.npmmirror.com --package=@mindscraft/branch-video-agent-cli branch-video-agent -- --help
-```
-
 如果你更喜欢简写，从 `0.1.2` 开始也支持：
 
 ```powershell
@@ -25,10 +19,13 @@ npx -y @mindscraft/branch-video-agent-cli --help
 也可以全局安装：
 
 ```powershell
-npm install -g @mindscraft/branch-video-agent-cli
+npm install -g @mindscraft/branch-video-agent-cli@latest --registry=https://registry.npmjs.org/
 branch-video-agent --help
+branch-video-agent --version
 ```
 
+从 `0.3.6` 开始，发布版 CLI 在每次执行命令前查询 npm 官方 registry 的 `latest`，发现新版本时先全局安装该精确版本，再用原参数重新执行命令。registry 查询或安装失败时命令会 fail closed，不会继续提交业务请求。仅在明确接受旧版风险的紧急诊断中设置 `BRANCH_VIDEO_AGENT_DISABLE_AUTO_UPDATE=1` 跳过检查。
+
 环境变量：
 
 - `AIHUB_AGENT_TOKEN`
@@ -48,6 +45,51 @@ AI Gateway 调用同样只传 `AIHUB_AGENT_TOKEN`；CLI 不读取、不传递 `A
 '@ | 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。
+
+```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`。`playtest run` 自身始终只读，不承担发布。
+
 AIHub 导入公共库示例：
 
 ```powershell
@@ -116,7 +158,7 @@ AIHub 导入公共库示例：
 
 `character search` 只返回已经人工添加 `accepted_for_reuse` 标签的角色资产；新入库资产默认未验收，需要在角色资产库页面验收后才会被 Agent 二次复用。
 
-AI Gateway 图片生成示例：
+AI Gateway 图片生成示例：
 
 ```powershell
 @'
@@ -124,24 +166,24 @@ AI Gateway 图片生成示例：
   "model": "doubao-seedream-5-0-260128",
   "prompt": "3D 卡通风格，穿白大褂的喵星人科学老师在实验室讲解电路"
 }
-'@ | npm exec --yes --package=@mindscraft/branch-video-agent-cli branch-video-agent -- ai-gateway image-generate -- --raw
-```
-
-AI Gateway Banana Pro 同步生成示例（实际模型值为 `gemini-3-pro-image-preview`）：
-
-```powershell
-@'
-{
-  "model": "gemini-3-pro-image-preview",
-  "prompt": "一幅写实风格的山水画，远处有云雾缭绕的山峰",
-  "size": "16:9",
-  "image_size_ratios": "2K",
-  "output_format": "image/png"
-}
-'@ | npm exec --yes --package=@mindscraft/branch-video-agent-cli branch-video-agent -- ai-gateway image-generate -- --raw
-```
-
-Banana Pro 图片编辑继续使用 `ai-gateway image-edit`，请求体为 JSON，`image` 是 HTTP(S) URL 字符串数组；GPT Image 2 编辑仍使用 multipart 文件描述。Banana Pro 当前只支持同步调用，不使用 `--wait`。响应通常包含 `data[].b64_json`，不要把完整 base64 写进 Agent 回复或持久化日志。
+'@ | npm exec --yes --package=@mindscraft/branch-video-agent-cli branch-video-agent -- ai-gateway image-generate -- --raw
+```
+
+AI Gateway Banana Pro 同步生成示例（实际模型值为 `gemini-3-pro-image-preview`）：
+
+```powershell
+@'
+{
+  "model": "gemini-3-pro-image-preview",
+  "prompt": "一幅写实风格的山水画，远处有云雾缭绕的山峰",
+  "size": "16:9",
+  "image_size_ratios": "2K",
+  "output_format": "image/png"
+}
+'@ | npm exec --yes --package=@mindscraft/branch-video-agent-cli branch-video-agent -- ai-gateway image-generate -- --raw
+```
+
+Banana Pro 图片编辑继续使用 `ai-gateway image-edit`，请求体为 JSON，`image` 是 HTTP(S) URL 字符串数组；GPT Image 2 编辑仍使用 multipart 文件描述。Banana Pro 当前只支持同步调用，不使用 `--wait`。响应通常包含 `data[].b64_json`，不要把完整 base64 写进 Agent 回复或持久化日志。
 
 AI Gateway 视频生成并等待示例：
 

package/dist/bin.js

@@ -1,3 +1,23 @@
 #!/usr/bin/env node
+import { readFileSync } from 'node:fs';
 import { main } from './index.js';
-process.exitCode = await main(process.argv.slice(2));
+import { autoUpdateAndReexec } from './lib/autoUpdate.js';
+const packageJson = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const argv = process.argv.slice(2);
+const update = await autoUpdateAndReexec({
+    currentVersion: packageJson.version,
+    argv,
+    executablePath: process.argv[1],
+    env: process.env,
+    platform: process.platform,
+    writeStderr: (text) => process.stderr.write(text),
+});
+if (update.handled) {
+    process.exitCode = update.exitCode;
+}
+else if (argv.length === 1 && ['--version', '-v'].includes(argv[0])) {
+    process.stdout.write(`${packageJson.version}\n`);
+}
+else {
+    process.exitCode = await main(argv);
+}

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/autoUpdate.d.ts

@@ -0,0 +1,26 @@
+export interface AutoUpdateRunResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+}
+export interface AutoUpdateRunOptions {
+    env?: Record<string, string | undefined>;
+    inheritStdio?: boolean;
+    timeoutMs?: number;
+}
+export type AutoUpdateRunner = (command: string, args: string[], options?: AutoUpdateRunOptions) => Promise<AutoUpdateRunResult>;
+export interface AutoUpdateOptions {
+    currentVersion: string;
+    argv: string[];
+    executablePath: string;
+    env: Record<string, string | undefined>;
+    platform: NodeJS.Platform;
+    run?: AutoUpdateRunner;
+    writeStderr: (text: string) => void;
+}
+export interface AutoUpdateResult {
+    handled: boolean;
+    exitCode: number;
+    latestVersion: string;
+}
+export declare function autoUpdateAndReexec(options: AutoUpdateOptions): Promise<AutoUpdateResult>;

package/dist/lib/autoUpdate.js

@@ -0,0 +1,90 @@
+import { spawnSync } from 'node:child_process';
+const PACKAGE_NAME = '@mindscraft/branch-video-agent-cli';
+const OFFICIAL_REGISTRY = 'https://registry.npmjs.org/';
+const REEXEC_ENV = 'BRANCH_VIDEO_AGENT_AUTO_UPDATE_REEXEC';
+const DISABLE_ENV = 'BRANCH_VIDEO_AGENT_DISABLE_AUTO_UPDATE';
+function runProcess(command, args, options) {
+    const result = spawnSync(command, args, {
+        encoding: 'utf8',
+        env: options?.env,
+        stdio: options?.inheritStdio ? 'inherit' : 'pipe',
+        timeout: options?.timeoutMs,
+    });
+    return Promise.resolve({
+        status: result.status,
+        stdout: result.stdout || '',
+        stderr: result.stderr || '',
+    });
+}
+function failedResult(options, message, latestVersion) {
+    options.writeStderr(`[branch-video-agent] ${message}\n`);
+    return { handled: true, exitCode: 1, latestVersion };
+}
+function compareVersions(left, right) {
+    const [leftCore, leftPrerelease] = left.split('-', 2);
+    const [rightCore, rightPrerelease] = right.split('-', 2);
+    const leftParts = leftCore.split('.').map(Number);
+    const rightParts = rightCore.split('.').map(Number);
+    for (let index = 0; index < 3; index += 1) {
+        const difference = leftParts[index] - rightParts[index];
+        if (difference !== 0)
+            return difference;
+    }
+    if (leftPrerelease === rightPrerelease)
+        return 0;
+    if (!leftPrerelease)
+        return 1;
+    if (!rightPrerelease)
+        return -1;
+    return leftPrerelease.localeCompare(rightPrerelease);
+}
+export async function autoUpdateAndReexec(options) {
+    if (options.env[DISABLE_ENV] === '1' || options.env[REEXEC_ENV] === '1') {
+        return { handled: false, exitCode: 0, latestVersion: options.currentVersion };
+    }
+    const run = options.run || runProcess;
+    const npmCommand = options.platform === 'win32'
+        ? options.env.ComSpec || options.env.COMSPEC || 'cmd.exe'
+        : 'npm';
+    const npmArgsPrefix = options.platform === 'win32' ? ['/d', '/s', '/c', 'npm'] : [];
+    const viewResult = await run(npmCommand, [
+        ...npmArgsPrefix,
+        'view',
+        `${PACKAGE_NAME}@latest`,
+        'version',
+        '--registry',
+        OFFICIAL_REGISTRY,
+    ], { timeoutMs: 15_000 });
+    const latestVersion = viewResult.stdout.trim();
+    if (viewResult.status !== 0 || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(latestVersion)) {
+        return failedResult(options, `cannot verify ${PACKAGE_NAME}@latest from ${OFFICIAL_REGISTRY}; refusing to run an unverified CLI`, latestVersion || options.currentVersion);
+    }
+    if (compareVersions(latestVersion, options.currentVersion) <= 0) {
+        return { handled: false, exitCode: 0, latestVersion };
+    }
+    options.writeStderr(`[branch-video-agent] upgrading ${PACKAGE_NAME} ${options.currentVersion} -> ${latestVersion}\n`);
+    const installResult = await run(npmCommand, [
+        ...npmArgsPrefix,
+        'install',
+        '-g',
+        `${PACKAGE_NAME}@${latestVersion}`,
+        '--registry',
+        OFFICIAL_REGISTRY,
+    ], { inheritStdio: true, env: options.env, timeoutMs: 120_000 });
+    if (installResult.status !== 0) {
+        return failedResult(options, `automatic upgrade to ${latestVersion} failed; command was not executed`, latestVersion);
+    }
+    const childEnv = {
+        ...options.env,
+        [REEXEC_ENV]: '1',
+    };
+    const reexecResult = await run(process.execPath, [options.executablePath, ...options.argv], {
+        inheritStdio: true,
+        env: childEnv,
+    });
+    return {
+        handled: true,
+        exitCode: reexecResult.status ?? 1,
+        latestVersion,
+    };
+}

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