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

package/dist/playtest/scenarios.js

@@ -0,0 +1,179 @@
+import { isDeepStrictEqual } from 'node:util';
+import { PlaytestError } from './errors.js';
+import { getReachablePlaytestGraph } from './graph.js';
+function compare(actual, op, expected) {
+    if (op === 'eq')
+        return actual === expected;
+    if (op === 'ne')
+        return actual !== expected;
+    if (op === 'gt')
+        return Number(actual) > Number(expected);
+    if (op === 'gte')
+        return Number(actual) >= Number(expected);
+    if (op === 'lt')
+        return Number(actual) < Number(expected);
+    if (op === 'lte')
+        return Number(actual) <= Number(expected);
+    return false;
+}
+function conditionMatches(condition, variables, inventory) {
+    if (!condition)
+        return true;
+    if (condition.type === 'variable' || condition.variable)
+        return compare(variables[condition.variable], condition.op, condition.value);
+    if (condition.type === 'inventory') {
+        const source = inventory.items[condition.item] ?? inventory.cards[condition.item] ?? 0;
+        return compare(source, condition.op, condition.value);
+    }
+    if (condition.type === 'not')
+        return !conditionMatches(condition.condition, variables, inventory);
+    if (condition.type === 'and')
+        return (condition.conditions || []).every((item) => conditionMatches(item, variables, inventory));
+    if (condition.type === 'or')
+        return (condition.conditions || []).some((item) => conditionMatches(item, variables, inventory));
+    if (Array.isArray(condition.and))
+        return condition.and.every((item) => conditionMatches(item, variables, inventory));
+    if (Array.isArray(condition.or))
+        return condition.or.some((item) => conditionMatches(item, variables, inventory));
+    if (condition.not)
+        return !conditionMatches(condition.not, variables, inventory);
+    return true;
+}
+function applyEffects(state, edge, targetNode) {
+    const variables = { ...state.variables };
+    const inventory = { items: { ...state.inventory.items }, cards: { ...state.inventory.cards } };
+    const variableActions = [...(edge.variableActions || []), ...(targetNode?.variableActions || [])];
+    for (const action of variableActions) {
+        const current = variables[action.variable];
+        if (action.operator === 'set')
+            variables[action.variable] = action.value;
+        else if (action.operator === 'add')
+            variables[action.variable] = Number(current || 0) + Number(action.value || 0);
+        else if (action.operator === 'subtract')
+            variables[action.variable] = Number(current || 0) - Number(action.value || 0);
+    }
+    const inventoryActions = [...(edge.inventoryActions || []), ...(targetNode?.inventoryActions || [])];
+    for (const action of inventoryActions) {
+        const bucket = action.kind === 'card' ? inventory.cards : inventory.items;
+        const count = Number(action.count ?? 1);
+        if (action.op === 'set')
+            bucket[action.id] = count;
+        else if (action.op === 'add')
+            bucket[action.id] = (bucket[action.id] || 0) + count;
+        else if (action.op === 'remove')
+            bucket[action.id] = Math.max(0, (bucket[action.id] || 0) - count);
+    }
+    return { variables, inventory };
+}
+function findPathToEdge(entryNodeId, edges, targetEdgeId, limits, nodeVisitLimits, script, future) {
+    const definitions = script?.resources?.variables || {};
+    const variables = Object.fromEntries(Object.entries(definitions).map(([name, definition]) => [name, definition?.default ?? 0]));
+    const initial = {
+        nodeId: entryNodeId,
+        edges: [],
+        visits: { [entryNodeId]: 1 },
+        variables,
+        inventory: { items: {}, cards: {} },
+    };
+    const entryEffects = applyEffects(initial, { variableActions: [], inventoryActions: [] }, script?.graph?.nodes?.[entryNodeId]);
+    const queue = [{ ...initial, ...entryEffects }];
+    const seen = new Set();
+    let head = 0;
+    let examined = 0;
+    while (head < queue.length) {
+        const state = queue[head];
+        queue[head++] = undefined;
+        if (state.edges.length >= limits.maxStepsPerScenario)
+            continue;
+        const records = [state.visits, state.variables, state.inventory.items, state.inventory.cards];
+        // Non-finite or non-scalar values keep the original search; JSON keys would conflate them.
+        const canDeduplicate = records.every((record) => Object.values(record).every((value) => (typeof value === 'string' || typeof value === 'boolean'
+            || (typeof value === 'number' && Number.isFinite(value) && !Object.is(value, -0)))));
+        if (canDeduplicate) {
+            const relevant = future.get(state.nodeId);
+            // Past-only visits and unread variables cannot change any continuation.
+            const projected = [
+                Object.fromEntries(Object.entries(state.visits).filter(([name]) => relevant.nodes.has(name))),
+                Object.fromEntries(Object.entries(state.variables).filter(([name]) => relevant.variables.has(name))),
+                state.inventory.items, state.inventory.cards,
+            ];
+            const key = JSON.stringify([state.nodeId, state.edges.length, ...projected.map((record) => (Object.keys(record).sort().map((name) => [name, record[name]])))]);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+        }
+        examined += 1;
+        if (examined > Math.max(10000, limits.maxScenarios * limits.maxStepsPerScenario * 20))
+            break;
+        for (const edge of edges.filter((candidate) => candidate.from === state.nodeId)) {
+            if (!conditionMatches(edge.condition, state.variables, state.inventory))
+                continue;
+            const nextVisits = { ...state.visits, [edge.to]: (state.visits[edge.to] || 0) + 1 };
+            const visitLimit = nodeVisitLimits[edge.to] ?? limits.maxNodeVisits;
+            if (nextVisits[edge.to] > visitLimit)
+                continue;
+            const nextEdges = [...state.edges, edge];
+            if (edge.id === targetEdgeId)
+                return nextEdges;
+            const effects = applyEffects(state, edge, script?.graph?.nodes?.[edge.to]);
+            queue.push({ nodeId: edge.to, edges: nextEdges, visits: nextVisits, ...effects });
+        }
+    }
+    return null;
+}
+export function removePrefixScenarios(scenarios) {
+    // ponytail: pairwise scan; index prefixes if scenario planning becomes a bottleneck.
+    return scenarios.filter((scenario) => !scenarios.some((longer) => (longer.edges.length > scenario.edges.length
+        && scenario.edges.every((edge, index) => isDeepStrictEqual(edge, longer.edges[index])))));
+}
+export function buildPlaytestScenarios(script, limits, nodeVisitLimits = {}) {
+    const { entryNodeId, reachableEdges } = getReachablePlaytestGraph(script);
+    if (!entryNodeId)
+        throw new PlaytestError('PLAYTEST_GRAPH_INVALID', 'script graph has no entryNodeId');
+    const future = new Map();
+    const collectVariables = (condition, names) => {
+        if (!condition || typeof condition !== 'object')
+            return;
+        if (condition.type === 'variable' || condition.variable)
+            names.add(String(condition.variable));
+        for (const child of Object.values(condition))
+            collectVariables(child, names);
+    };
+    for (const nodeId of new Set([entryNodeId, ...reachableEdges.map((edge) => edge.to)])) {
+        const nodes = new Set([nodeId]);
+        const variables = new Set();
+        // Include all structural continuations, even currently false conditions and loops.
+        for (const from of nodes) {
+            for (const edge of reachableEdges.filter((candidate) => candidate.from === from)) {
+                nodes.add(edge.to);
+                collectVariables(edge.condition, variables);
+            }
+        }
+        future.set(nodeId, { nodes, variables });
+    }
+    const edgeScenarios = reachableEdges.map((targetEdge, index) => {
+        const edges = findPathToEdge(entryNodeId, reachableEdges, targetEdge.id, limits, nodeVisitLimits, script, future);
+        if (!edges) {
+            throw new PlaytestError('PATH_BUDGET_EXCEEDED', `No path to edge ${targetEdge.id} fits the configured step/node-visit budget`, {
+                edgeId: targetEdge.id,
+                maxStepsPerScenario: limits.maxStepsPerScenario,
+                maxNodeVisits: limits.maxNodeVisits,
+                nodeVisitLimits,
+            });
+        }
+        return {
+            id: `scenario-${String(index + 2).padStart(3, '0')}`,
+            targetEdgeId: targetEdge.id,
+            edges,
+        };
+    });
+    const scenarios = removePrefixScenarios([{ id: 'scenario-001', targetEdgeId: `@entry:${entryNodeId}`, edges: [] }, ...edgeScenarios]);
+    if (scenarios.length > limits.maxScenarios) {
+        throw new PlaytestError('PATH_BUDGET_EXCEEDED', `Required scenario count ${scenarios.length} exceeds maxScenarios ${limits.maxScenarios}`, {
+            reachableEdges: reachableEdges.length,
+            requiredScenarios: scenarios.length,
+            maxScenarios: limits.maxScenarios,
+        });
+    }
+    return scenarios;
+}

package/dist/playtest/staticPreflight.d.ts

@@ -0,0 +1 @@
+export declare function assertPlaytestStaticPreflight(script: unknown): void;

package/dist/playtest/staticPreflight.js

@@ -0,0 +1,30 @@
+import { PlaytestError } from './errors.js';
+import { extractPlaytestEdges } from './graph.js';
+const NODE_TYPES = new Set(['start', 'video', 'image', 'web', 'end', 'avg']);
+export function assertPlaytestStaticPreflight(script) {
+    const candidate = script;
+    if (candidate?.version !== '3.0.0') {
+        throw new PlaytestError('STATIC_PREFLIGHT_FAILED', 'script version must be 3.0.0');
+    }
+    const entryNodeId = candidate.graph?.entryNodeId;
+    const nodes = candidate.graph?.nodes;
+    if (typeof entryNodeId !== 'string' || !nodes || typeof nodes !== 'object' || !nodes[entryNodeId]) {
+        throw new PlaytestError('STATIC_PREFLIGHT_FAILED', 'script graph entryNodeId/nodes are invalid');
+    }
+    for (const [nodeId, node] of Object.entries(nodes)) {
+        if (!NODE_TYPES.has(node?.type)) {
+            throw new PlaytestError('STATIC_PREFLIGHT_FAILED', `Unsupported V3 node type ${node?.type || 'missing'} at ${nodeId}`);
+        }
+        if (node?.id !== nodeId) {
+            throw new PlaytestError('STATIC_PREFLIGHT_FAILED', `Node key/id mismatch at ${nodeId}`);
+        }
+        if (node?.type === 'web' && (node.config?.params !== undefined || node.config?.events !== undefined)) {
+            throw new PlaytestError('STATIC_PREFLIGHT_FAILED', `Web node ${nodeId} contains legacy params/events fields`);
+        }
+    }
+    for (const edge of extractPlaytestEdges(script)) {
+        if (!nodes[edge.to]) {
+            throw new PlaytestError('STATIC_PREFLIGHT_FAILED', `Edge ${edge.id} targets missing node ${edge.to}`);
+        }
+    }
+}

package/dist/playtest/types.d.ts

@@ -0,0 +1,152 @@
+export type PlaytestLocator = {
+    by: 'role';
+    role: string;
+    name?: string;
+    exact?: boolean;
+} | {
+    by: 'label';
+    label: string;
+    exact?: boolean;
+} | {
+    by: 'testId';
+    testId: string;
+} | {
+    by: 'css';
+    selector: string;
+};
+export type PlaytestStep = {
+    action: 'click';
+    locator: PlaytestLocator;
+} | {
+    action: 'fill';
+    locator: PlaytestLocator;
+    value: string;
+} | {
+    action: 'selectOption';
+    locator: PlaytestLocator;
+    value: string | string[];
+} | {
+    action: 'check';
+    locator: PlaytestLocator;
+    checked?: boolean;
+} | {
+    action: 'press';
+    locator: PlaytestLocator;
+    key: string;
+} | {
+    action: 'dragTo';
+    locator: PlaytestLocator;
+    target: PlaytestLocator;
+} | {
+    action: 'setInputFiles';
+    locator: PlaytestLocator;
+    files: string[];
+} | {
+    action: 'waitFor';
+    locator: PlaytestLocator;
+    state?: 'attached' | 'detached' | 'visible' | 'hidden';
+    timeoutMs?: number;
+};
+export interface PlaytestWebResult {
+    nodeId: string;
+    routeValue: string;
+    rawMessage: {
+        eventName: string;
+        value?: unknown;
+        data?: unknown;
+    };
+    steps: PlaytestStep[];
+}
+export interface PlaytestContract {
+    schemaVersion: 'branch-video-playtest/1';
+    scriptFingerprint: string;
+    webResults: PlaytestWebResult[];
+    storageStatePath?: string;
+    microphoneWavPath?: string;
+    nodeVisitLimits?: Record<string, number>;
+}
+export interface PlaytestEdge {
+    id: string;
+    from: string;
+    to: string;
+    owner: 'node' | 'interaction';
+    ownerId: string;
+    trigger: {
+        type: string;
+        value?: unknown;
+    };
+    condition?: unknown;
+    variableActions?: unknown[];
+    inventoryActions?: unknown[];
+    actionType: string;
+    action: Record<string, unknown>;
+    default?: boolean;
+}
+export interface PlaytestScenario {
+    id: string;
+    targetEdgeId: string;
+    edges: PlaytestEdge[];
+}
+export interface PlaytestLimits {
+    scenarioTimeoutMs: number;
+    maxStepsPerScenario: number;
+    maxScenarios: number;
+    maxNodeVisits: number;
+}
+export interface PlaytestSourceDraft {
+    kind: 'draft';
+    projectId: string;
+}
+export interface PlaytestSourcePublished {
+    kind: 'published';
+    projectId: string;
+    version: number;
+    playUrl: string;
+}
+export type PlaytestSource = PlaytestSourceDraft | PlaytestSourcePublished;
+export interface PlaytestRunInput {
+    source: PlaytestSource;
+    contractPath: string;
+    reportDir: string;
+    concurrency?: number;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    limits?: Partial<PlaytestLimits>;
+}
+export interface PlaytestFinding {
+    code: string;
+    message: string;
+    phase?: 'input' | 'source-read' | 'static-preflight' | 'contract' | 'scenario-generation' | 'browser' | 'coverage';
+    scenarioId?: string;
+    nodeId?: string;
+    edgeId?: string;
+    details?: unknown;
+}
+export interface PlaytestScenarioResult {
+    id: string;
+    targetEdgeId: string;
+    status: 'passed' | 'failed';
+    durationMs: number;
+    visitedNodes: string[];
+    coveredEdges: string[];
+    findings: PlaytestFinding[];
+    warnings: PlaytestFinding[];
+    artifacts: Record<string, string>;
+}
+export interface PlaytestReport {
+    schemaVersion: 'branch-video-playtest-report/1';
+    source: PlaytestSource | null;
+    scriptFingerprint: string | null;
+    startedAt: string;
+    finishedAt: string;
+    status: 'passed' | 'failed';
+    reachableNodeIds: string[];
+    reachableEdgeIds: string[];
+    coveredNodeIds: string[];
+    coveredEdgeIds: string[];
+    scenarios: PlaytestScenarioResult[];
+    findings: PlaytestFinding[];
+    warnings: PlaytestFinding[];
+}

package/dist/playtest/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindscraft/branch-video-agent-cli",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Published CLI for branch-video and AIHub agent APIs.",
   "type": "module",
   "bin": {
@@ -18,6 +18,9 @@
   "engines": {
     "node": ">=18"
   },
+  "dependencies": {
+    "playwright": "^1.57.0"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"