cssprobe-cli 0.3.0 → 0.4.0

package/dist/help.json

@@ -1,13 +1,15 @@
 {
-  "global": "Usage: cssprobe-cli <command> [args] [options]\n\n\nSession Management:\n  open [url]                  open browser in session mode (non-blocking)\n  close                       close the browser session\n  status                      show current session status\n  resize <width> <height>     resize the browser viewport\n  eval <expression>           evaluate javascript expression on the page (browser context)\n  playwright <call>           execute playwright api call (node.js context)\n  state-import [file]         import cookies from netscape format file\n  state-save                  save current browser session state (cookies + localstorage)\n  mcp                         start mcp server (stdio transport) for ai clients\n  mcp-install                 install mcp server config into ai client configs\n  mcp-uninstall               remove mcp server config from ai client configs\n\nCSS Inspection:\n  inspect <selector>          inspect the runtime css of a page element\n  tree <selector>             show dom tree structure\n  layout <selector>           show ascii layout diagram\n  findings <selector>         show only issues/warnings/errors\n  inject-css <css>            inject css into the current page\n\nExport:\n  screenshot                  take a screenshot of the current page\n\nConfiguration:\n  config-show                 show current configuration\n  config-set <key> <value>    set a configuration value\n  config-list                 list all profiles\n  config-use <name>           switch active profile\n  config-new <name>           create a new profile\n  config-path                 show configuration file path\n\nAgent Skills:\n  skill-install               install agent skill for cssprobe-cli\n  skill-uninstall             remove agent skill for cssprobe-cli\n\nGlobal options:\n  --help [command]            print help\n  --json                      output response as JSON\n  --raw                       output only the result value\n  --version                   print version\n  -p, --profile <name>        use named profile (or CSSPROBE_PROFILE env)",
+  "global": "Usage: cssprobe-cli <command> [args] [options]\n\n\nSession Management:\n  open [url]                  open browser in session mode (non-blocking)\n  close                       close the browser session\n  status                      show current session status\n  frames                      list frames in the current page\n  doctor                      diagnose browser installation and playwright revision mismatch\n  scenario <action> <file>    run a json scenario suite (regression cases, artifacts, junit)\n  resize <width> <height>     resize the browser viewport\n  eval <expression>           evaluate javascript expression on the page (browser context)\n  playwright <call>           execute playwright api call (node.js context)\n  click <selector>            click an element with real mouse events (works with custom react components)\n  hover <selector>            hover an element with real mouse events\n  type <selector> <text>      type text into an element (fill by default; --sequential for real key events)\n  wait-for [selector]         wait for a condition: selector state, js predicate, or network idle\n  sample <expression>         sample a js expression over time and return a timeline with summary stats\n  wait-stable <expression>    wait until a js expression stops changing (tolerance + stable window)\n  run <file>                  run a multi-step flow script (default-exports an async function receiving the api object)\n  state-import [file]         import cookies from netscape format file\n  state-save                  save current browser session state (cookies + localstorage)\n  state-check                 validate a saved state file: cookies, expiry, and target domain coverage\n  mcp                         start mcp server (stdio transport) for ai clients\n  mcp-install                 install mcp server config into ai client configs\n  mcp-uninstall               remove mcp server config from ai client configs\n\nCSS Inspection:\n  inspect <selector>          inspect the runtime css of a page element\n  tree <selector>             show dom tree structure\n  layout <selector>           show ascii layout diagram\n  findings <selector>         show only issues/warnings/errors\n  inject-css <css>            inject css into the current page\n\nExport:\n  screenshot                  take a screenshot of the current page\n\nConfiguration:\n  config-show                 show current configuration\n  config-set <key> <value>    set a configuration value\n  config-list                 list all profiles\n  config-use <name>           switch active profile\n  config-new <name>           create a new profile\n  config-path                 show configuration file path\n\nAgent Skills:\n  skill-install               install agent skill for cssprobe-cli\n  skill-uninstall             remove agent skill for cssprobe-cli\n\nGlobal options:\n  --help [command]            print help\n  --json                      output response as JSON\n  --raw                       output only the result value\n  --version                   print version\n  -p, --profile <name>        use named profile (or CSSPROBE_PROFILE env)",
   "commands": {
     "open": {
-      "help": "cssprobe-cli open [url]\n\nOpen browser in session mode (non-blocking)\n\nArguments:\n  [url]                       url, file:// path, or local html file path\nOptions:\n  --browser                   browser engine (default chromium)\n  --headed                    show the browser window\n  --viewport                  viewport size as wxh (e.g. 1280x720)\n  --state                     path to saved state file (cookies + localstorage)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "help": "cssprobe-cli open [url]\n\nOpen browser in session mode (non-blocking)\n\nArguments:\n  [url]                       url, file:// path, or local html file path\nOptions:\n  --browser                   browser engine (default chromium)\n  --headed                    show the browser window\n  --viewport                  viewport size as wxh (e.g. 1280x720)\n  --state                     path to saved state file (cookies + localstorage)\n  --expect-url                regex the final page url must match\n  --fail-on-login             fail when the page redirects to a login url\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
       "flags": {
         "browser": "string",
         "headed": "boolean",
         "viewport": "string",
-        "state": "string"
+        "state": "string",
+        "expect-url": "string",
+        "fail-on-login": "boolean"
       },
       "args": [
         "url"
@@ -25,44 +27,80 @@
       "flags": {},
       "args": []
     },
+    "frames": {
+      "help": "cssprobe-cli frames \n\nList frames in the current page\n\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {},
+      "args": []
+    },
+    "doctor": {
+      "help": "cssprobe-cli doctor \n\nDiagnose browser installation and Playwright revision mismatch\n\nOptions:\n  --engine                    browser engine: chromium, firefox, webkit (default: chromium)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "engine": "string"
+      },
+      "args": []
+    },
+    "scenario": {
+      "help": "cssprobe-cli scenario <action> <file>\n\nRun a JSON scenario suite (regression cases, artifacts, JUnit)\n\nArguments:\n  <action>                    only \"run\" is supported\n  <file>                      scenario suite json path\nOptions:\n  --state                     fallback state file when the suite/case does not set one\n  --artifacts                 artifact directory (default: ~/.cssprobe-cli/scenario-runs/<suite>-<timestamp>)\n  --junit                     write a junit xml report to this path\n  --bail                      stop after the first failing case\n  --headed                    show the browser window\n  --browser                   browser engine (default chromium)\n  --viewport                  viewport size as wxh (default: suite defaults or 1280x720)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "state": "string",
+        "artifacts": "string",
+        "junit": "string",
+        "bail": "boolean",
+        "headed": "boolean",
+        "browser": "string",
+        "viewport": "string"
+      },
+      "args": [
+        "action",
+        "file"
+      ]
+    },
     "inspect": {
-      "help": "cssprobe-cli inspect <selector>\n\nInspect the runtime CSS of a page element\n\nArguments:\n  <selector>                  css selector for the root element\nOptions:\n  --json                      output structured json instead of markdown\n  --brief                     compact output: tree sketch + warnings/errors only\n  --layout                    ascii layout diagram showing element positions and sizes\n  --depth                     dom tree depth (default: auto, max 20)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "help": "cssprobe-cli inspect <selector>\n\nInspect the runtime CSS of a page element\n\nArguments:\n  <selector>                  css selector for the root element\nOptions:\n  --json                      output structured json instead of markdown\n  --brief                     compact output: tree sketch + warnings/errors only\n  --layout                    ascii layout diagram showing element positions and sizes\n  --depth                     dom tree depth (default: auto, max 20)\n  --frame                     target frame: index, name, or url substring (default: main frame)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
       "flags": {
         "json": "boolean",
         "brief": "boolean",
         "layout": "boolean",
-        "depth": "string"
+        "depth": "string",
+        "frame": "string"
       },
       "args": [
         "selector"
       ]
     },
     "tree": {
-      "help": "cssprobe-cli tree <selector>\n\nShow DOM tree structure\n\nArguments:\n  <selector>                  css selector for the root element\nOptions:\n  --depth                     tree depth (default: auto, max 20)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "help": "cssprobe-cli tree <selector>\n\nShow DOM tree structure\n\nArguments:\n  <selector>                  css selector for the root element\nOptions:\n  --depth                     tree depth (default: auto, max 20)\n  --frame                     target frame: index, name, or url substring (default: main frame)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
       "flags": {
-        "depth": "string"
+        "depth": "string",
+        "frame": "string"
       },
       "args": [
         "selector"
       ]
     },
     "layout": {
-      "help": "cssprobe-cli layout <selector>\n\nShow ASCII layout diagram\n\nArguments:\n  <selector>                  css selector for the root element\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
-      "flags": {},
+      "help": "cssprobe-cli layout <selector>\n\nShow ASCII layout diagram\n\nArguments:\n  <selector>                  css selector for the root element\nOptions:\n  --frame                     target frame: index, name, or url substring (default: main frame)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "frame": "string"
+      },
       "args": [
         "selector"
       ]
     },
     "findings": {
-      "help": "cssprobe-cli findings <selector>\n\nShow only issues/warnings/errors\n\nArguments:\n  <selector>                  css selector for the root element\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
-      "flags": {},
+      "help": "cssprobe-cli findings <selector>\n\nShow only issues/warnings/errors\n\nArguments:\n  <selector>                  css selector for the root element\nOptions:\n  --frame                     target frame: index, name, or url substring (default: main frame)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "frame": "string"
+      },
       "args": [
         "selector"
       ]
     },
     "inject-css": {
-      "help": "cssprobe-cli inject-css <css>\n\nInject CSS into the current page\n\nArguments:\n  <css>                       css code to inject\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
-      "flags": {},
+      "help": "cssprobe-cli inject-css <css>\n\nInject CSS into the current page\n\nArguments:\n  <css>                       css code to inject\nOptions:\n  --frame                     target frame: index, name, or url substring (default: main frame)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "frame": "string"
+      },
       "args": [
         "css"
       ]
@@ -76,14 +114,16 @@
       ]
     },
     "eval": {
-      "help": "cssprobe-cli eval <expression>\n\nEvaluate JavaScript expression on the page (browser context)\n\nArguments:\n  <expression>                javascript expression to evaluate\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
-      "flags": {},
+      "help": "cssprobe-cli eval <expression>\n\nEvaluate JavaScript expression on the page (browser context)\n\nArguments:\n  <expression>                javascript expression, or @file / - (stdin) for long scripts\nOptions:\n  --frame                     target frame: index, name, or url substring (default: main frame)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "frame": "string"
+      },
       "args": [
         "expression"
       ]
     },
     "playwright": {
-      "help": "cssprobe-cli playwright <call>\n\nExecute Playwright API call (Node.js context)\n\nArguments:\n  <call>                      playwright api call, e.g. \"page.setviewportsize({width: 1280, height: 720})\"\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "help": "cssprobe-cli playwright <call>\n\nExecute Playwright API call (Node.js context)\n\nArguments:\n  <call>                      playwright api call, or @file / - (stdin); e.g. \"page.setviewportsize({width: 1280, height: 720})\"\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
       "flags": {},
       "args": [
         "call"
@@ -97,6 +137,91 @@
       },
       "args": []
     },
+    "click": {
+      "help": "cssprobe-cli click <selector>\n\nClick an element with real mouse events (works with custom React components)\n\nArguments:\n  <selector>                  css selector\nOptions:\n  --nth                       1-based match index (default: first match)\n  --force                     skip actionability checks\n  --timeout                   action timeout in ms (default 30000)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "nth": "string",
+        "force": "boolean",
+        "timeout": "string"
+      },
+      "args": [
+        "selector"
+      ]
+    },
+    "hover": {
+      "help": "cssprobe-cli hover <selector>\n\nHover an element with real mouse events\n\nArguments:\n  <selector>                  css selector\nOptions:\n  --nth                       1-based match index (default: first match)\n  --force                     skip actionability checks\n  --timeout                   action timeout in ms (default 30000)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "nth": "string",
+        "force": "boolean",
+        "timeout": "string"
+      },
+      "args": [
+        "selector"
+      ]
+    },
+    "type": {
+      "help": "cssprobe-cli type <selector> <text>\n\nType text into an element (fill by default; --sequential for real key events)\n\nArguments:\n  <selector>                  css selector\n  <text>                      text to type\nOptions:\n  --press                     key to press after typing (e.g. enter, tab, control+a)\n  --sequential                type with real key events (for custom editors)\n  --clear                     clear existing content before sequential typing\n  --delay                     delay between keystrokes in ms (--sequential, default 0)\n  --nth                       1-based match index (default: first match)\n  --timeout                   action timeout in ms (default 30000)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "press": "string",
+        "sequential": "boolean",
+        "clear": "boolean",
+        "delay": "string",
+        "nth": "string",
+        "timeout": "string"
+      },
+      "args": [
+        "selector",
+        "text"
+      ]
+    },
+    "wait-for": {
+      "help": "cssprobe-cli wait-for [selector]\n\nWait for a condition: selector state, JS predicate, or network idle\n\nArguments:\n  [selector]                  css selector to wait for\nOptions:\n  --state                     selector state to wait for (default visible)\n  --js                        js predicate, e.g. \"() => document.queryselector('.x')?.offsetheight > 100\"\n  --network-idle              wait until the page is network-idle\n  --timeout                   timeout in ms (default 30000)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "state": "string",
+        "js": "string",
+        "network-idle": "boolean",
+        "timeout": "string"
+      },
+      "args": [
+        "selector"
+      ]
+    },
+    "sample": {
+      "help": "cssprobe-cli sample <expression>\n\nSample a JS expression over time and return a timeline with summary stats\n\nArguments:\n  <expression>                js expression sampled on an interval\nOptions:\n  --interval                  sampling interval in ms (default 250)\n  --duration                  total sampling duration in ms (default 5000)\n  --key                       dot path for numeric extraction, e.g. \"top\" or \"box.y\"\n  --tail-from                 tail starts at this elapsed ms (default: last 5000ms)\n  --ignore-errors             record evaluation errors as sample points instead of aborting\n  --frame                     target frame: index, name, or url substring (default: main frame)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "interval": "string",
+        "duration": "string",
+        "key": "string",
+        "tail-from": "string",
+        "ignore-errors": "boolean",
+        "frame": "string"
+      },
+      "args": [
+        "expression"
+      ]
+    },
+    "wait-stable": {
+      "help": "cssprobe-cli wait-stable <expression>\n\nWait until a JS expression stops changing (tolerance + stable window)\n\nArguments:\n  <expression>                js expression polled until stable\nOptions:\n  --tolerance                 absolute tolerance for numeric values (default 0)\n  --window                    stable window in ms (default 1500)\n  --timeout                   timeout in ms (default 30000)\n  --interval                  polling interval in ms (default 200)\n  --frame                     target frame: index, name, or url substring (default: main frame)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "tolerance": "string",
+        "window": "string",
+        "timeout": "string",
+        "interval": "string",
+        "frame": "string"
+      },
+      "args": [
+        "expression"
+      ]
+    },
+    "run": {
+      "help": "cssprobe-cli run <file>\n\nRun a multi-step flow script (default-exports an async function receiving the API object)\n\nArguments:\n  <file>                      flow script path (.js / .mjs / .cjs)\nOptions:\n  --timeout                   whole-script timeout in ms (default 300000, 0 = unlimited)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "timeout": "string"
+      },
+      "args": [
+        "file"
+      ]
+    },
     "state-import": {
       "help": "cssprobe-cli state-import [file]\n\nImport cookies from Netscape format file\n\nArguments:\n  [file]                      netscape cookie file path (reads from stdin if omitted)\nOptions:\n  --out                       output state file path (default: ~/.cssprobe-cli/states/imported.json)\n  --name                      custom name for the state file (e.g. mysite or mysite.json)\n  --merge                     existing state file to merge into\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
       "flags": {
@@ -115,6 +240,14 @@
       },
       "args": []
     },
+    "state-check": {
+      "help": "cssprobe-cli state-check \n\nValidate a saved state file: cookies, expiry, and target domain coverage\n\nOptions:\n  --state                     state file path (default: ~/.cssprobe-cli/states/session.json)\n  --url                       target url whose hostname must be covered by the cookies\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "state": "string",
+        "url": "string"
+      },
+      "args": []
+    },
     "config-show": {
       "help": "cssprobe-cli config-show \n\nShow current configuration\n\nOptions:\n  --profile                   profile name",
       "flags": {
@@ -198,11 +331,18 @@
   },
   "booleanOptions": [
     "headed",
+    "fail-on-login",
     "all",
+    "bail",
     "json",
     "brief",
     "layout",
     "full-page",
+    "force",
+    "sequential",
+    "clear",
+    "network-idle",
+    "ignore-errors",
     "local"
   ]
 }

package/dist/installer/skill-template.js

@@ -127,6 +127,49 @@ function buildSkillMd() {
         'cssprobe-cli close                         # stop browser + daemon',
         BT3,
         '',
+        '## Multi-step UI Flows',
+        '',
+        'Beyond inspection, cssprobe-cli drives the page: click, hover, type, wait, and',
+        'run scripted flows -- all in the same session.',
+        '',
+        BT3 + 'bash',
+        'cssprobe-cli click ".layout-switch"            # real mouse click (auto-scroll + actionability wait)',
+        'cssprobe-cli click ".item" --nth 2             # 1-based match index; multi-match without --nth fails (strict)',
+        'cssprobe-cli hover ".menu-item"',
+        'cssprobe-cli type ".block-title input" "Hi" --press Enter    # fill by default',
+        'cssprobe-cli type ".editor" "text" --sequential --clear      # real key events for custom editors',
+        'cssprobe-cli wait-for ".modal" --state visible --timeout 5000',
+        'cssprobe-cli wait-for --js "() => ready === true"',
+        'cssprobe-cli wait-for --network-idle',
+        BT3,
+        '',
+        '### Scripted flows: ' + BT + 'run <file>' + BT,
+        '',
+        'A flow script default-exports an async function receiving the API object and',
+        'runs inside the daemon session:',
+        '',
+        BT3 + 'js',
+        'export default async ({ page, click, hover, type, waitFor, inspect, screenshot, log }) => {',
+        '  await waitFor(".editor-canvas");',
+        '  await click(".layout-switch", { nth: 1 });',
+        '  await type(".block-title input", "Hello", { press: "Enter", sequential: true, clear: true });',
+        '  await waitFor({ networkIdle: true });',
+        '  const { findings } = await inspect(".block-grid", { format: "json" });',
+        '  await screenshot({ path: "./after.png" });',
+        '  return { findings: findings.length };',
+        '};',
+        BT3,
+        '',
+        BT3 + 'bash',
+        'cssprobe-cli run ./flow.js        # --timeout ms (default 300000, 0 = unlimited)',
+        BT3,
+        '',
+        'Notes:',
+        '',
+        '- Scripts run on your machine with full Node privileges -- only run trusted scripts.',
+        '- ' + BT + 'screenshot' + BT + ' relative paths resolve against the script directory.',
+        '- On failure the command exits 1, prints collected logs, and keeps the session alive.',
+        '',
         '## Output Modes',
         '',
         'Pass ' + BT + '--json' + BT + ' when consuming output programmatically:',

package/dist/scenario/assertions.d.ts

@@ -0,0 +1,13 @@
+import type { AssertStep } from './schema';
+export interface AssertionState {
+    url: string;
+    title: string;
+    frames: number;
+}
+export interface AssertionContext {
+    vars: Record<string, unknown>;
+    state: AssertionState;
+    globals: Record<string, string>;
+}
+export declare function resolvePath(value: unknown, path?: string): unknown;
+export declare function evaluateAssertion(assertion: AssertStep, context: AssertionContext): string | null;

package/dist/scenario/assertions.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePath = resolvePath;
+exports.evaluateAssertion = evaluateAssertion;
+function resolvePath(value, path) {
+    if (!path)
+        return value;
+    let current = value;
+    for (const part of path.split('.')) {
+        if (current === null || current === undefined)
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (a === null || b === null)
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((item, index) => deepEqual(item, b[index]));
+    }
+    if (typeof a === 'object' && typeof b === 'object') {
+        const aKeys = Object.keys(a).sort();
+        const bKeys = Object.keys(b).sort();
+        if (aKeys.length !== bKeys.length || aKeys.some((key, index) => key !== bKeys[index]))
+            return false;
+        return aKeys.every(key => deepEqual(a[key], b[key]));
+    }
+    return false;
+}
+function label(assertion) {
+    return assertion.label ?? 'assert';
+}
+function evaluateAssertion(assertion, context) {
+    const errors = [];
+    if (assertion.url) {
+        let regex;
+        try {
+            regex = new RegExp(assertion.url);
+        }
+        catch {
+            return `${label(assertion)}: invalid url pattern ${assertion.url}`;
+        }
+        if (!regex.test(context.state.url)) {
+            errors.push(`url ${JSON.stringify(context.state.url)} does not match ${assertion.url}`);
+        }
+    }
+    for (const [name, expected] of Object.entries(assertion.globals ?? {})) {
+        const actual = context.globals[name] ?? 'undefined';
+        if (actual !== expected) {
+            errors.push(`global ${name}: expected ${expected}, received ${actual}`);
+        }
+    }
+    for (const name of assertion.absent ?? []) {
+        const actual = context.globals[name] ?? 'undefined';
+        if (actual !== 'undefined') {
+            errors.push(`global ${name}: expected absent, received ${actual}`);
+        }
+    }
+    const hasValueCheck = ['eq', 'ne', 'match', 'within', 'min', 'max'].some(key => key in assertion);
+    if (!hasValueCheck) {
+        return errors.length ? `${label(assertion)}: ${errors.join('; ')}` : null;
+    }
+    let value;
+    if (assertion.on) {
+        if (assertion.on === 'state') {
+            value = context.state;
+        }
+        else if (assertion.on in context.vars) {
+            value = context.vars[assertion.on];
+        }
+        else {
+            return `${label(assertion)}: unknown variable "${assertion.on}"`;
+        }
+    }
+    else {
+        value = context.state;
+    }
+    value = resolvePath(value, assertion.path);
+    if ('eq' in assertion && !deepEqual(value, assertion.eq)) {
+        errors.push(`expected ${JSON.stringify(assertion.eq)}, received ${JSON.stringify(value)}`);
+    }
+    if ('ne' in assertion && deepEqual(value, assertion.ne)) {
+        errors.push(`expected value different from ${JSON.stringify(assertion.ne)}`);
+    }
+    if (assertion.match !== undefined) {
+        const actual = typeof value === 'string' ? value : JSON.stringify(value);
+        if (!new RegExp(assertion.match).test(actual)) {
+            errors.push(`expected ${JSON.stringify(actual)} to match ${assertion.match}`);
+        }
+    }
+    if (assertion.within) {
+        if (typeof value !== 'number' || Math.abs(value - assertion.within.expected) > assertion.within.tolerance) {
+            errors.push(`expected ${assertion.within.expected} ±${assertion.within.tolerance}, received ${JSON.stringify(value)}`);
+        }
+    }
+    if (assertion.min !== undefined && (typeof value !== 'number' || value < assertion.min)) {
+        errors.push(`expected >= ${assertion.min}, received ${JSON.stringify(value)}`);
+    }
+    if (assertion.max !== undefined && (typeof value !== 'number' || value > assertion.max)) {
+        errors.push(`expected <= ${assertion.max}, received ${JSON.stringify(value)}`);
+    }
+    return errors.length ? `${label(assertion)}: ${errors.join('; ')}` : null;
+}
+//# sourceMappingURL=assertions.js.map

package/dist/scenario/reporters.d.ts

@@ -0,0 +1,13 @@
+import type { CaseResult } from './schema';
+export declare function slugify(value: string): string;
+export interface ScenarioSummary {
+    total: number;
+    passed: number;
+    failed: number;
+    durationMs: number;
+    ok: boolean;
+}
+export declare function summarize(results: CaseResult[]): ScenarioSummary;
+export declare function formatConsole(suiteName: string, results: CaseResult[]): string;
+export declare function escapeXml(value: string): string;
+export declare function toJunit(suiteName: string, results: CaseResult[]): string;

package/dist/scenario/reporters.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.slugify = slugify;
+exports.summarize = summarize;
+exports.formatConsole = formatConsole;
+exports.escapeXml = escapeXml;
+exports.toJunit = toJunit;
+function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60) || 'case';
+}
+function summarize(results) {
+    const passed = results.filter(result => result.ok).length;
+    const durationMs = results.reduce((total, result) => total + result.durationMs, 0);
+    return {
+        total: results.length,
+        passed,
+        failed: results.length - passed,
+        durationMs,
+        ok: passed === results.length,
+    };
+}
+function formatConsole(suiteName, results) {
+    const summary = summarize(results);
+    const lines = [];
+    for (const result of results) {
+        const marker = result.ok ? 'PASS' : result.skipped ? 'SKIP' : 'FAIL';
+        lines.push(`${marker} ${result.name} (${result.durationMs}ms)`);
+        if (result.error)
+            lines.push(`  ${result.error}`);
+        for (const step of result.steps) {
+            if (!step.ok)
+                lines.push(`  step ${step.index + 1} (${step.action}): ${step.error}`);
+        }
+        if (result.artifactsDir)
+            lines.push(`  artifacts: ${result.artifactsDir}`);
+    }
+    lines.push('');
+    lines.push(`${suiteName}: ${summary.passed}/${summary.total} passed, ${summary.failed} failed in ${summary.durationMs}ms`);
+    return lines.join('\n');
+}
+function escapeXml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+function toJunit(suiteName, results) {
+    const summary = summarize(results);
+    const cases = results
+        .map(result => {
+        const time = (result.durationMs / 1000).toFixed(3);
+        const failureDetails = [
+            result.error,
+            ...result.steps.filter(step => !step.ok).map(step => `step ${step.index + 1} (${step.action}): ${step.error}`),
+        ]
+            .filter(Boolean)
+            .join('\n');
+        const body = result.ok
+            ? ''
+            : `<failure message="${escapeXml(result.error ?? 'scenario case failed')}">${escapeXml(failureDetails)}</failure>`;
+        return `    <testcase classname="${escapeXml(suiteName)}" name="${escapeXml(result.name)}" time="${time}">${body}</testcase>`;
+    })
+        .join('\n');
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        `<testsuites tests="${summary.total}" failures="${summary.failed}" time="${(summary.durationMs / 1000).toFixed(3)}">`,
+        `  <testsuite name="${escapeXml(suiteName)}" tests="${summary.total}" failures="${summary.failed}" time="${(summary.durationMs / 1000).toFixed(3)}">`,
+        cases,
+        '  </testsuite>',
+        '</testsuites>',
+    ].join('\n');
+}
+//# sourceMappingURL=reporters.js.map

package/dist/scenario/runner.d.ts

@@ -0,0 +1,10 @@
+import { type ScenarioSummary } from './reporters';
+import type { CaseResult, ScenarioRunOptions, Suite } from './schema';
+export interface ScenarioRunResult {
+    suite: string;
+    ok: boolean;
+    summary: ScenarioSummary;
+    results: CaseResult[];
+    artifactsDir: string;
+}
+export declare function runScenario(suite: Suite, suitePath: string, options?: ScenarioRunOptions): Promise<ScenarioRunResult>;