craftdriver 1.6.0 → 1.8.0

package/dist/cli/parseArgs.js

@@ -1,3 +1,19 @@
+/**
+ * Translate raw `argv` into a `(cmd, args)` pair that the dispatcher
+ * understands. Hand-rolled because v1 has ~20 commands; pulling in
+ * `commander`/`yargs` would dwarf the library footprint.
+ *
+ * Recognised global flags (anywhere on the command line):
+ *   --timeout <ms>          per-call timeout override
+ *   --json                  force JSON output even on a TTY
+ *   --pretty                force pretty output even when piped
+ *   --headless / --headed   launch option (only honoured for ephemeral / first daemon start)
+ *   --browser <name>        chrome|chromium|firefox|safari
+ *   --ephemeral             run from stdin, don't talk to daemon
+ *
+ * Returns `null` when the user only asked for help / version.
+ */
+import { resolve } from 'node:path';
 export const HELP_TEXT = `craftdriver — agent-first WebDriver CLI
 
 USAGE
@@ -7,7 +23,14 @@ COMMON COMMANDS
   go <url>                          navigate the active page
   find <selector> [--all] [--limit N] [--offset M]
   click <selector>
-  fill <selector> <value>
+  dblclick <selector>
+  fill <selector> <value>           clear, then enter the value
+  type <text>                       type into the focused element
+  clear <selector>
+  check <selector> | uncheck <selector>
+  select <selector> <value>         pick an <option> by its value attribute
+  focus <selector>                  focus a field (caret to end), then type
+  scroll <selector>
   press <key> [selector]
   hover <selector>
   text [selector] [--limit N]
@@ -18,35 +41,81 @@ COMMON COMMANDS
   wait load [--state load|domcontentloaded|networkidle]
   exists <selector>                 0-wait probe; exit 0 if any match
   pages                             list open pages
+  page list                         open pages, marking the active one
+  page open [url]                   open a tab and select it
+  page select <index|id>            send later commands to that tab
+  page close <index|id>             close a tab
   snapshot                          sanitized DOM summary with refs
                                     (use ref=eN as a selector)
+  locators <selector>               durable selectors for an element,
+                                    each re-checked against the live page
+  logs [list] [--kind console,error,request,response] [--level error]
+       [--contains text] [--since N] [--limit N]
+                                    what the page logged and requested
+  logs wait --contains <text> [--kind k] [--timeout ms]
+  logs clear
+  mock add <url-pattern> [--status N] [--body S] [--content-type T]
+                                    reply with a fixed response
+  mock block <url-pattern>          fail matching requests
+  mock list | mock remove <id> | mock clear
+  trace start [name] [--no-screenshots]
+                                    record actions, console and network
+  trace stop [--zip]                stop and report where it landed
+  trace status
+  state save <name> [--session-storage]
+                                    save cookies + local storage for reuse
+  state load <name>                 restore saved login state (pre-navigation on BiDi)
+  state list                        saved state names
   screenshot [-o file.png] [--full-page] [--selector S]
   eval <js>                         advanced; evaluate JS on active page
   back | forward | reload | status | quit
 
+KEYBOARD / MOUSE / DIALOGS / UPLOAD
+  key press|down|up <key> [--selector S]
+  mouse move|click [selector] [--x N --y N] [--button left|middle|right]
+  mouse down|up [--button left|middle|right]
+  mouse wheel [selector] [--delta-x N] [--delta-y N]
+  dialog inspect | dialog accept [text] | dialog dismiss
+  upload <selector> <file> [file...]
+
+REFS VS. DURABLE LOCATORS
+  Refs (e1, e2, …) come from "snapshot" and are for exploration only. They
+  bind to one element in one document: if it is removed, duplicated, or the
+  page navigates, the ref fails with STALE_REF instead of quietly acting on
+  a different element. Never put a ref in a committed test — run
+  "locators <ref>" and use a candidate it reports as unique.
+
 DAEMON
   daemon start                      launch background browser (Unix socket)
   daemon status                     PID, browser, active page URL
   daemon stop                       graceful shutdown
+  Not available on Windows; use --ephemeral or MCP there.
+
+NAMED SESSIONS
+  --session <name>                  route a command to its own browser
+  session list                      open sessions and the limit
+  session close [name]              quit one session's browser, free the slot
+
+  Each session owns a browser, page selection, snapshot baseline and refs.
+  Sessions number their refs independently, so "e4" exists in more than one
+  session and always acts on the session you addressed — never carry a ref
+  between sessions. Sessions are created on first use and run independently,
+  so a slow command in one does not block another. Not available with
+  --ephemeral, which is a single browser that exits with the command.
 
-INIT (agent guide files for the current project)
-  init <flavor> [--force] [--dry-run]
-    flavors: agents | copilot | claude | cursor | gemini | all
-    writes a short rules file under the path each tool expects:
-      agents  → AGENTS.md
-      copilot → .github/copilot-instructions.md
-      claude  → CLAUDE.md
-      cursor  → .cursor/rules/craftdriver.mdc
-      gemini  → GEMINI.md
-      all     → every file above
+INIT (safe project-local skill)
+  init codex [--dry-run] [--mcp]
+    installs .agents/skills/craftdriver without reading or changing
+    AGENTS.md, CLAUDE.md, other repository instructions, or Codex config
+    --mcp prints a project-pinned config snippet for manual installation
 
 MCP SERVER (for hosted / sandboxed AI agents)
   mcp                                speak Model Context Protocol on stdio
     install snippet (Claude Code):
-      claude mcp add craftdriver -- npx -y craftdriver mcp
+      claude mcp add craftdriver -- npx --no-install craftdriver mcp
     install snippet (Cursor / Windsurf / Zed):
       { "mcpServers": { "craftdriver": {
-          "command": "npx", "args": ["-y", "craftdriver", "mcp"] } } }
+          "command": "npx", "args": ["--no-install", "craftdriver", "mcp"] } } }
 
 EPHEMERAL MODE (sandboxed agents)
   craftdriver --ephemeral < script.txt
@@ -62,15 +131,305 @@ FLAGS
   --json | --pretty                 force output format
   --headless / --headed             override headless mode (first launch only)
   --browser <chrome|chromium|firefox|safari>
+  --session <name>                  named daemon session (default: default)
   --ephemeral                       no daemon; read commands from stdin
 
 EXIT CODES
   0 success    1 assertion/timeout/no-match    2 usage error
 `;
+/**
+ * Every flag the CLI accepts. The parser branches below are the real
+ * definition; this list exists to turn a typo into a suggestion, so keep the
+ * two in step — `parse-args` covers the drift.
+ */
+const KNOWN_FLAGS = [
+    '--help', '--version', '--json', '--pretty', '--ephemeral', '--headless',
+    '--headed', '--browser', '--session', '--timeout', '--limit', '--offset',
+    '--all', '--dry-run', '--mcp', '--force', '--full-page', '--session-storage',
+    '--kind', '--level', '--contains', '--since', '--no-screenshots', '--zip',
+    '--status', '--body', '--content-type', '--state', '--selector', '--output',
+    '--name', '--text', '--button', '--files', '--delta-x', '--delta-y',
+    '--x', '--y',
+];
+/**
+ * Positional and command-specific option contracts.
+ *
+ * The dispatcher still validates untrusted socket/MCP input, but the CLI must
+ * reject its own mistakes before it starts a daemon or browser. Without this
+ * table, `click #pay -s admin` ignored two extra arguments and `click #pay
+ * --all` accepted a real-but-irrelevant flag, then reported success.
+ */
+const COMMAND_SYNTAX = {
+    go: { min: 1, max: 1, usage: 'go <url>' },
+    click: { min: 1, max: 1, usage: 'click <selector>' },
+    dblclick: { min: 1, max: 1, usage: 'dblclick <selector>' },
+    fill: { min: 2, max: Infinity, usage: 'fill <selector> <value>' },
+    type: { min: 1, max: Infinity, usage: 'type <text>' },
+    press: { min: 1, max: 2, usage: 'press <key> [selector]' },
+    hover: { min: 1, max: 1, usage: 'hover <selector>' },
+    clear: { min: 1, max: 1, usage: 'clear <selector>' },
+    check: { min: 1, max: 1, usage: 'check <selector>' },
+    uncheck: { min: 1, max: 1, usage: 'uncheck <selector>' },
+    select: { min: 2, max: Infinity, usage: 'select <selector> <value>' },
+    focus: { min: 1, max: 1, usage: 'focus <selector>' },
+    scroll: { min: 1, max: 1, usage: 'scroll <selector>' },
+    locators: { min: 1, max: 1, usage: 'locators <selector>', options: ['limit'] },
+    upload: { min: 1, max: Infinity, usage: 'upload <selector> <file> [file...]', options: ['files'] },
+    key: { min: 2, max: Infinity, usage: 'key press|down|up <key>', options: ['selector'] },
+    mouse: {
+        min: 0,
+        max: 2,
+        usage: 'mouse move|click [selector] | mouse down|up | mouse wheel [selector]',
+        options: ['selector', 'x', 'y', 'button', 'deltaX', 'deltaY'],
+    },
+    dialog: { min: 0, max: Infinity, usage: 'dialog inspect | accept [text] | dismiss', options: ['text'] },
+    find: { min: 1, max: 1, usage: 'find <selector>', options: ['all', 'limit', 'offset'] },
+    exists: { min: 1, max: 1, usage: 'exists <selector>' },
+    text: { min: 0, max: 1, usage: 'text [selector]', options: ['limit'] },
+    attr: { min: 2, max: 2, usage: 'attr <selector> <name>' },
+    value: { min: 1, max: 1, usage: 'value <selector>' },
+    is: { min: 2, max: 2, usage: 'is visible|enabled|checked <selector>' },
+    wait: { min: 1, max: 1, usage: 'wait <selector>|load', options: ['state'] },
+    pages: { min: 0, max: 0, usage: 'pages' },
+    page: { min: 0, max: 2, usage: 'page list|open|select|close [target]' },
+    logs: { min: 0, max: 1, usage: 'logs [list|wait|clear]', options: ['kind', 'level', 'contains', 'since', 'limit'] },
+    mock: { min: 0, max: 2, usage: 'mock add|block|list|remove|clear [target]', options: ['status', 'body', 'contentType'] },
+    trace: { min: 0, max: 2, usage: 'trace start|stop|status [name]', options: ['name', 'noScreenshots', 'zip'] },
+    state: { min: 0, max: 2, usage: 'state save|load|list [name]', options: ['sessionStorage'] },
+    screenshot: { min: 0, max: 0, usage: 'screenshot [-o file.png]', options: ['path', 'fullPage', 'selector'] },
+    snapshot: { min: 0, max: 0, usage: 'snapshot' },
+    eval: { min: 1, max: Infinity, usage: 'eval <javascript>' },
+    back: { min: 0, max: 0, usage: 'back' },
+    forward: { min: 0, max: 0, usage: 'forward' },
+    reload: { min: 0, max: 0, usage: 'reload' },
+    status: { min: 0, max: 0, usage: 'status' },
+    quit: { min: 0, max: 0, usage: 'quit' },
+    daemon: { min: 0, max: 1, usage: 'daemon start|status|stop' },
+    session: { min: 0, max: 2, usage: 'session list|close [name]' },
+    init: { min: 1, max: 1, usage: 'init codex', options: ['dry-run', 'mcp', 'force'] },
+    mcp: { min: 0, max: 0, usage: 'mcp' },
+};
+/**
+ * Contracts for commands whose first positional selects an action.
+ *
+ * Keeping these beside the top-level table prevents a known-but-irrelevant
+ * flag from disappearing: `trace start --zip` used to start a trace and
+ * quietly ignore the requested archive, while `page list extra` listed pages
+ * and reported success. Counts include the action token itself; the default
+ * action covers the zero-token form.
+ */
+const ACTION_COMMAND_SYNTAX = {
+    key: {
+        defaultAction: '',
+        actions: {
+            press: { min: 2, max: Infinity, usage: 'key press <key>', options: ['selector'] },
+            down: { min: 2, max: Infinity, usage: 'key down <key>', options: ['selector'] },
+            up: { min: 2, max: Infinity, usage: 'key up <key>', options: ['selector'] },
+            // Backward-compatible spelling; the dispatcher maps it to top-level type.
+            type: { min: 2, max: Infinity, usage: 'key type <text>' },
+        },
+    },
+    mouse: {
+        defaultAction: 'move',
+        actions: {
+            move: { min: 0, max: 2, usage: 'mouse move [selector]', options: ['selector', 'x', 'y'] },
+            click: { min: 1, max: 2, usage: 'mouse click [selector]', options: ['selector', 'x', 'y', 'button'] },
+            down: { min: 1, max: 1, usage: 'mouse down', options: ['button'] },
+            up: { min: 1, max: 1, usage: 'mouse up', options: ['button'] },
+            wheel: { min: 1, max: 2, usage: 'mouse wheel [selector]', options: ['selector', 'deltaX', 'deltaY'] },
+        },
+    },
+    dialog: {
+        defaultAction: 'inspect',
+        actions: {
+            inspect: { min: 0, max: 1, usage: 'dialog inspect' },
+            accept: { min: 1, max: Infinity, usage: 'dialog accept [text]', options: ['text'] },
+            dismiss: { min: 1, max: 1, usage: 'dialog dismiss' },
+        },
+    },
+    page: {
+        defaultAction: 'list',
+        actions: {
+            list: { min: 0, max: 1, usage: 'page list' },
+            open: { min: 1, max: 2, usage: 'page open [url]' },
+            select: { min: 2, max: 2, usage: 'page select <index|id>' },
+            close: { min: 2, max: 2, usage: 'page close <index|id>' },
+        },
+    },
+    logs: {
+        defaultAction: 'list',
+        actions: {
+            list: { min: 0, max: 1, usage: 'logs [list]', options: ['kind', 'level', 'contains', 'since', 'limit'] },
+            wait: { min: 1, max: 1, usage: 'logs wait', options: ['kind', 'level', 'contains', 'since', 'limit'] },
+            clear: { min: 1, max: 1, usage: 'logs clear' },
+        },
+    },
+    mock: {
+        defaultAction: 'list',
+        actions: {
+            list: { min: 0, max: 1, usage: 'mock list' },
+            add: { min: 2, max: 2, usage: 'mock add <url-pattern>', options: ['status', 'body', 'contentType'] },
+            block: { min: 2, max: 2, usage: 'mock block <url-pattern>' },
+            remove: { min: 2, max: 2, usage: 'mock remove <id>' },
+            clear: { min: 1, max: 1, usage: 'mock clear' },
+        },
+    },
+    trace: {
+        defaultAction: 'status',
+        actions: {
+            start: { min: 1, max: 2, usage: 'trace start [name]', options: ['name', 'noScreenshots'] },
+            stop: { min: 1, max: 1, usage: 'trace stop', options: ['zip'] },
+            status: { min: 0, max: 1, usage: 'trace status' },
+        },
+    },
+    state: {
+        defaultAction: 'list',
+        actions: {
+            save: { min: 2, max: 2, usage: 'state save <name>', options: ['sessionStorage'] },
+            load: { min: 2, max: 2, usage: 'state load <name>' },
+            list: { min: 0, max: 1, usage: 'state list' },
+        },
+    },
+    daemon: {
+        defaultAction: 'status',
+        actions: {
+            start: { min: 1, max: 1, usage: 'daemon start' },
+            status: { min: 0, max: 1, usage: 'daemon status' },
+            stop: { min: 1, max: 1, usage: 'daemon stop' },
+            // Private child-process entry point used by autoStartDaemon.
+            __run__: { min: 1, max: 1, usage: 'daemon __run__' },
+        },
+    },
+    session: {
+        defaultAction: 'list',
+        actions: {
+            list: { min: 0, max: 1, usage: 'session list' },
+            close: { min: 1, max: 2, usage: 'session close [name]' },
+        },
+    },
+};
+const COMMAND_ALIASES = {
+    goto: 'go',
+    navigate: 'go',
+    doubleclick: 'dblclick',
+    attribute: 'attr',
+    shot: 'screenshot',
+    log: 'logs',
+};
+const OPTION_FLAG = {
+    'dry-run': '--dry-run',
+    all: '--all',
+    body: '--body',
+    button: '--button',
+    contains: '--contains',
+    contentType: '--content-type',
+    deltaX: '--delta-x',
+    deltaY: '--delta-y',
+    files: '--files',
+    force: '--force',
+    fullPage: '--full-page',
+    kind: '--kind',
+    level: '--level',
+    limit: '--limit',
+    mcp: '--mcp',
+    name: '--name',
+    noScreenshots: '--no-screenshots',
+    offset: '--offset',
+    path: '--output',
+    selector: '--selector',
+    sessionStorage: '--session-storage',
+    since: '--since',
+    state: '--state',
+    status: '--status',
+    text: '--text',
+    x: '--x',
+    y: '--y',
+    zip: '--zip',
+};
+function usageError(flags, message, usage) {
+    return {
+        cmd: '__usage_error__',
+        args: { message, ...(usage ? { usage: `craftdriver ${usage}` } : {}) },
+        flags,
+    };
+}
+function validateActionCommand(canonical, rest, opts, flags) {
+    const command = ACTION_COMMAND_SYNTAX[canonical];
+    if (!command)
+        return null;
+    const action = (rest[0] ?? command.defaultAction).toLowerCase();
+    const syntax = command.actions[action];
+    if (!syntax) {
+        return usageError(flags, `${canonical}: unknown action ${JSON.stringify(action)}`, COMMAND_SYNTAX[canonical].usage);
+    }
+    const allowed = new Set(['timeout', ...(syntax.options ?? [])]);
+    const invalidOption = Object.keys(opts).find((key) => !allowed.has(key));
+    if (invalidOption) {
+        return usageError(flags, `${OPTION_FLAG[invalidOption] ?? `--${invalidOption}`} is not valid for ${canonical} ${action}`, syntax.usage);
+    }
+    if (rest.length < syntax.min) {
+        return usageError(flags, `${canonical} ${action}: missing required argument`, syntax.usage);
+    }
+    if (rest.length > syntax.max) {
+        return usageError(flags, `${canonical} ${action}: unexpected argument ${JSON.stringify(rest[syntax.max])}`, syntax.usage);
+    }
+    return null;
+}
+/** Levenshtein distance, capped by the shorter input — inputs are tiny. */
+function editDistance(a, b) {
+    const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    const cur = new Array(b.length + 1).fill(0);
+    for (let i = 1; i <= a.length; i++) {
+        cur[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev.splice(0, prev.length, ...cur);
+    }
+    return prev[b.length];
+}
+/** Nearest known flag, when one is close enough to be worth naming. */
+function suggestFlag(flag) {
+    let best = null;
+    let bestDistance = Infinity;
+    for (const known of KNOWN_FLAGS) {
+        const d = editDistance(flag, known);
+        if (d < bestDistance) {
+            bestDistance = d;
+            best = known;
+        }
+    }
+    // Beyond a couple of edits the "did you mean" is noise, not help.
+    return best && bestDistance <= 3 ? { suggestion: best } : {};
+}
 export function parseArgv(argv) {
     const flags = { launch: {} };
     const positional = [];
     const opts = {};
+    const takeValue = (flag, index) => {
+        const value = argv[index + 1];
+        if (value === undefined || value.startsWith('--')) {
+            return usageError(flags, `${flag} requires a value`);
+        }
+        return value;
+    };
+    const takeNumber = (flag, index, limits = {}) => {
+        const raw = takeValue(flag, index);
+        if (typeof raw !== 'string')
+            return raw;
+        const value = Number(raw);
+        const invalid = !Number.isFinite(value) ||
+            (limits.integer === true && !Number.isInteger(value)) ||
+            (limits.min !== undefined && value < limits.min) ||
+            (limits.max !== undefined && value > limits.max);
+        if (invalid) {
+            const range = limits.min !== undefined || limits.max !== undefined
+                ? ` (${limits.min ?? '-∞'}..${limits.max ?? '∞'})`
+                : '';
+            return usageError(flags, `${flag} requires ${limits.integer ? 'an integer' : 'a number'}${range}; got ${JSON.stringify(raw)}`);
+        }
+        return value;
+    };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === '--help' || a === '-h')
@@ -81,49 +440,153 @@ export function parseArgv(argv) {
             flags.json = true;
         else if (a === '--pretty')
             flags.pretty = true;
-        else if (a === '--explain')
-            flags.explain = true;
         else if (a === '--ephemeral')
             flags.ephemeral = true;
         else if (a === '--headless')
             flags.headless = true;
         else if (a === '--headed')
             flags.headless = false;
-        else if (a === '--browser')
-            flags.launch.browserName = argv[++i];
-        else if (a === '--timeout') {
-            const n = Number(argv[++i]);
-            if (Number.isFinite(n)) {
-                flags.timeout = n;
-                opts.timeout = n;
+        else if (a === '--browser') {
+            const value = takeValue(a, i);
+            if (typeof value !== 'string')
+                return value;
+            if (!['chrome', 'chromium', 'firefox', 'safari'].includes(value)) {
+                return usageError(flags, `--browser: unknown browser ${JSON.stringify(value)}`);
             }
+            flags.launch.browserName = value;
+            i += 1;
+        }
+        // A global flag, not a command arg: it addresses a session rather than
+        // parameterising a command, and the dispatcher never sees it.
+        else if (a === '--session') {
+            const value = takeValue(a, i);
+            if (typeof value !== 'string')
+                return value;
+            flags.session = value;
+            i += 1;
+        }
+        else if (a === '--timeout') {
+            const value = takeNumber(a, i, { integer: true, min: 0, max: 300_000 });
+            if (typeof value !== 'number')
+                return value;
+            flags.timeout = value;
+            opts.timeout = value;
+            i += 1;
+        }
+        else if (a === '--limit') {
+            const value = takeNumber(a, i, { integer: true });
+            if (typeof value !== 'number')
+                return value;
+            opts.limit = value;
+            i += 1;
+        }
+        else if (a === '--offset') {
+            const value = takeNumber(a, i, { integer: true, min: 0 });
+            if (typeof value !== 'number')
+                return value;
+            opts.offset = value;
+            i += 1;
         }
-        else if (a === '--limit')
-            opts.limit = Number(argv[++i]);
-        else if (a === '--offset')
-            opts.offset = Number(argv[++i]);
         else if (a === '--all')
             opts.all = true;
+        else if (a === '--dry-run')
+            opts['dry-run'] = true;
+        else if (a === '--mcp')
+            opts.mcp = true;
+        else if (a === '--force')
+            opts.force = true;
         else if (a === '--full-page' || a === '--fullPage')
             opts.fullPage = true;
-        else if (a === '--state')
-            opts.state = argv[++i];
-        else if (a === '--selector')
-            opts.selector = argv[++i];
-        else if (a === '-o' || a === '--output')
-            opts.path = argv[++i];
-        else if (a === '--name')
-            opts.name = argv[++i];
+        else if (a === '--session-storage' || a === '--sessionStorage')
+            opts.sessionStorage = true;
+        else if (a === '--kind' || a === '--level' || a === '--contains') {
+            const value = takeValue(a, i);
+            if (typeof value !== 'string')
+                return value;
+            opts[a.slice(2)] = value;
+            i += 1;
+        }
+        else if (a === '--since') {
+            const value = takeNumber(a, i, { integer: true, min: 0 });
+            if (typeof value !== 'number')
+                return value;
+            opts.since = value;
+            i += 1;
+        }
+        else if (a === '--no-screenshots' || a === '--noScreenshots')
+            opts.noScreenshots = true;
+        else if (a === '--zip')
+            opts.zip = true;
+        else if (a === '--status') {
+            const value = takeNumber(a, i, { integer: true, min: 100, max: 599 });
+            if (typeof value !== 'number')
+                return value;
+            opts.status = value;
+            i += 1;
+        }
+        else if (a === '--body' || a === '--content-type' || a === '--contentType' ||
+            a === '--state' || a === '--selector' || a === '--name' ||
+            a === '--text' || a === '--button') {
+            const value = takeValue(a, i);
+            if (typeof value !== 'string')
+                return value;
+            const key = a === '--content-type' || a === '--contentType'
+                ? 'contentType'
+                : a.slice(2);
+            opts[key] = value;
+            i += 1;
+        }
+        else if (a === '-o' || a === '--output') {
+            const value = takeValue(a, i);
+            if (typeof value !== 'string')
+                return value;
+            // Resolve in the short-lived caller process. The daemon has a different,
+            // long-lived cwd, so sending a relative output path there writes to the
+            // wrong directory.
+            opts.path = resolve(value);
+            i += 1;
+        }
+        // Resolved here, in the caller's process, for the same reason the
+        // positional form is: the daemon has its own long-lived cwd.
+        else if (a === '--files') {
+            const value = takeValue(a, i);
+            if (typeof value !== 'string')
+                return value;
+            opts.files = value
+                .split(',')
+                .map((f) => f.trim())
+                .filter((f) => f.length > 0)
+                .map((f) => resolve(f));
+            i += 1;
+        }
+        else if (a === '--delta-x' || a === '--deltaX' || a === '--delta-y' || a === '--deltaY' || a === '--x' || a === '--y') {
+            const value = takeNumber(a, i, { integer: true });
+            if (typeof value !== 'number')
+                return value;
+            const key = a === '--delta-x' || a === '--deltaX'
+                ? 'deltaX'
+                : a === '--delta-y' || a === '--deltaY'
+                    ? 'deltaY'
+                    : a.slice(2);
+            opts[key] = value;
+            i += 1;
+        }
+        // Everything after a bare `--` is data, so text that looks like a flag
+        // can still be typed: `type -- --draft`.
+        else if (a === '--') {
+            positional.push(...argv.slice(i + 1));
+            break;
+        }
+        // Unknown long flags are a usage error, never silently absorbed. Accepting
+        // them meant `--sesion admin` ran against the default session: the typo
+        // vanished and a destructive command hit the wrong browser and the wrong
+        // login. Failing closed is the only safe reading of an unrecognised flag.
+        //
+        // Single-dash tokens are left alone: `type -bob` types the text "-bob",
+        // and `--delta-y -100` passes a negative number. Only `-h`, `-V` and `-o`
+        // are short flags, so there is little to typo and much to break.
         else if (a.startsWith('--')) {
-            // Unknown long flag: take a value if next token is not another flag.
-            const key = a.slice(2);
-            const next = argv[i + 1];
-            if (next !== undefined && !next.startsWith('--')) {
-                opts[key] = next;
-                i++;
-            }
-            else
-                opts[key] = true;
+            return { cmd: '__unknown_flag__', args: { flag: a, ...suggestFlag(a) }, flags };
         }
         else
             positional.push(a);
@@ -144,6 +607,44 @@ export function parseArgv(argv) {
     }
     const [cmd0, ...rest] = positional;
     const lower = cmd0.toLowerCase();
+    const canonical = COMMAND_ALIASES[lower] ?? lower;
+    const syntax = COMMAND_SYNTAX[canonical];
+    if (syntax) {
+        const allowed = new Set(['timeout', ...(syntax.options ?? [])]);
+        const invalidOption = Object.keys(opts).find((key) => !allowed.has(key));
+        if (invalidOption) {
+            return usageError(flags, `${OPTION_FLAG[invalidOption] ?? `--${invalidOption}`} is not valid for ${cmd0}`, syntax.usage);
+        }
+        if (rest.length < syntax.min) {
+            return usageError(flags, `${cmd0}: missing required argument`, syntax.usage);
+        }
+        if (rest.length > syntax.max) {
+            return usageError(flags, `${cmd0}: unexpected argument ${JSON.stringify(rest[syntax.max])}`, syntax.usage);
+        }
+    }
+    const actionError = validateActionCommand(canonical, rest, opts, flags);
+    if (actionError)
+        return actionError;
+    if (canonical === 'upload') {
+        const optionFiles = Array.isArray(opts.files) ? opts.files : [];
+        if (rest.length < 2 && optionFiles.length === 0) {
+            return usageError(flags, 'upload: missing required argument "file"', COMMAND_SYNTAX.upload.usage);
+        }
+    }
+    if (canonical === 'is' && !['visible', 'enabled', 'checked'].includes(rest[0].toLowerCase())) {
+        return usageError(flags, `is: unknown state ${JSON.stringify(rest[0])}`, COMMAND_SYNTAX.is.usage);
+    }
+    if (canonical === 'wait' && typeof opts.state === 'string') {
+        const states = rest[0] === 'load'
+            ? ['load', 'domcontentloaded', 'networkidle']
+            : ['visible', 'hidden', 'attached', 'detached'];
+        if (!states.includes(opts.state)) {
+            return usageError(flags, `wait: unknown state ${JSON.stringify(opts.state)}`, COMMAND_SYNTAX.wait.usage);
+        }
+    }
+    if (canonical === 'init' && rest[0].toLowerCase() !== 'codex') {
+        return usageError(flags, `init: unknown target ${JSON.stringify(rest[0])}`, COMMAND_SYNTAX.init.usage);
+    }
     // Map surface command → dispatcher command + collect args.
     switch (lower) {
         case 'go':
@@ -153,13 +654,80 @@ export function parseArgv(argv) {
         case 'click':
             return { cmd: 'click', args: { selector: rest[0], ...opts }, flags };
         case 'fill':
-        case 'type':
             return { cmd: 'fill', args: { selector: rest[0], value: rest.slice(1).join(' '), ...opts }, flags };
+        case 'type':
+            // BREAKING (was an alias for `fill`): `type` now types into the
+            // focused element and takes no selector, matching `playwright-cli
+            // type <text>`. Use `fill <selector> <value>` to target a field.
+            return { cmd: 'type', args: { text: rest.join(' '), ...opts }, flags };
         case 'press':
             // craftdriver press <key> [selector]
             return { cmd: 'press', args: { key: rest[0], ...(rest[1] ? { selector: rest[1] } : {}), ...opts }, flags };
         case 'hover':
             return { cmd: 'hover', args: { selector: rest[0], ...opts }, flags };
+        case 'dblclick':
+        case 'doubleclick':
+            return { cmd: 'dblclick', args: { selector: rest[0], ...opts }, flags };
+        case 'clear':
+            return { cmd: 'clear', args: { selector: rest[0], ...opts }, flags };
+        case 'check':
+        case 'uncheck':
+            return { cmd: lower, args: { selector: rest[0], ...opts }, flags };
+        case 'select':
+            // craftdriver select <selector> <value>
+            return { cmd: 'select', args: { selector: rest[0], value: rest.slice(1).join(' '), ...opts }, flags };
+        case 'focus':
+        case 'scroll':
+            return { cmd: lower, args: { selector: rest[0], ...opts }, flags };
+        case 'locators':
+            // craftdriver locators <selector> — durable selectors for a ref
+            return { cmd: 'locators', args: { selector: rest[0], ...opts }, flags };
+        case 'upload': {
+            // craftdriver upload <selector> <file> [file...]
+            //
+            // Resolve paths here, in the caller's process. The daemon is a
+            // long-lived process with its own cwd, so a relative path sent over
+            // the socket would resolve against wherever the daemon was started.
+            const files = rest.slice(1).map((f) => resolve(f));
+            return {
+                cmd: 'upload',
+                args: {
+                    selector: rest[0],
+                    ...(files.length > 0 ? { files } : {}),
+                    ...opts,
+                },
+                flags,
+            };
+        }
+        case 'key': {
+            // craftdriver key press|down|up <key> [--selector S]
+            const action = (rest[0] ?? 'press').toLowerCase();
+            const value = rest.slice(1).join(' ');
+            // `key type` was folded into the top-level `type` command. Route it
+            // there rather than emitting args the dispatcher cannot service.
+            if (action === 'type') {
+                return { cmd: 'type', args: { text: value, ...opts }, flags };
+            }
+            return { cmd: 'key', args: { action, key: value, ...opts }, flags };
+        }
+        case 'mouse': {
+            // craftdriver mouse move|click|wheel [selector] | down|up
+            const action = (rest[0] ?? 'move').toLowerCase();
+            return {
+                cmd: 'mouse',
+                args: { action, ...(rest[1] ? { selector: rest[1] } : {}), ...opts },
+                flags,
+            };
+        }
+        case 'dialog': {
+            // craftdriver dialog inspect | accept [text] | dismiss
+            const action = (rest[0] ?? 'inspect').toLowerCase();
+            return {
+                cmd: 'dialog',
+                args: { action, ...(rest[1] ? { text: rest.slice(1).join(' ') } : {}), ...opts },
+                flags,
+            };
+        }
         case 'find':
             return { cmd: 'find', args: { selector: rest[0], ...opts }, flags };
         case 'exists':
@@ -183,6 +751,70 @@ export function parseArgv(argv) {
         }
         case 'pages':
             return { cmd: 'pages', args: { ...opts }, flags };
+        case 'page': {
+            // craftdriver page list|open [url]|select <index|id>|close <index|id>
+            const action = (rest[0] ?? 'list').toLowerCase();
+            const target = rest[1];
+            return {
+                cmd: 'page',
+                args: {
+                    action,
+                    ...(action === 'open' && target ? { url: target } : {}),
+                    ...(action !== 'open' && target ? { target } : {}),
+                    ...opts,
+                },
+                flags,
+            };
+        }
+        case 'logs':
+        case 'log': {
+            // craftdriver logs [list|wait|clear] [--kind k] [--level l]
+            //                  [--contains s] [--since N] [--limit N]
+            const action = (rest[0] ?? 'list').toLowerCase();
+            return { cmd: 'logs', args: { action, ...opts }, flags };
+        }
+        case 'mock': {
+            // craftdriver mock add <pattern> [--status N] [--body S] [--content-type T]
+            //                 | block <pattern> | list | remove <id> | clear
+            const action = (rest[0] ?? 'list').toLowerCase();
+            const target = rest[1];
+            return {
+                cmd: 'mock',
+                args: {
+                    action,
+                    ...(action === 'remove' && target ? { id: target } : {}),
+                    ...((action === 'add' || action === 'block') && target ? { pattern: target } : {}),
+                    ...opts,
+                },
+                flags,
+            };
+        }
+        case 'trace': {
+            // craftdriver trace start [name] [--no-screenshots] | stop [--zip] | status
+            const action = (rest[0] ?? 'status').toLowerCase();
+            return {
+                cmd: 'trace',
+                args: {
+                    action,
+                    ...(action === 'start' && rest[1] ? { name: rest[1] } : {}),
+                    ...opts,
+                },
+                flags,
+            };
+        }
+        case 'state': {
+            // craftdriver state save <name> [--session-storage] | load <name> | list
+            const action = (rest[0] ?? 'list').toLowerCase();
+            return {
+                cmd: 'state',
+                args: {
+                    action,
+                    ...(rest[1] ? { name: rest[1] } : {}),
+                    ...opts,
+                },
+                flags,
+            };
+        }
         case 'screenshot':
         case 'shot':
             return { cmd: 'screenshot', args: { ...opts }, flags };
@@ -201,8 +833,20 @@ export function parseArgv(argv) {
             const sub = (rest[0] ?? 'status').toLowerCase();
             return { cmd: `daemon:${sub}`, args: { ...opts }, flags };
         }
+        case 'session': {
+            // craftdriver session list | close [name]
+            //
+            // `close` takes the name positionally or from `--session`, so both
+            // `session close checkout` and `session close --session checkout` work.
+            const sub = (rest[0] ?? 'list').toLowerCase();
+            return {
+                cmd: `session:${sub}`,
+                args: { ...(rest[1] ? { target: rest[1] } : {}), ...opts },
+                flags,
+            };
+        }
         case 'init': {
-            // craftdriver init <flavor> [--force] [--dry-run]
+            // craftdriver init codex [--dry-run] [--mcp]
             const flavor = (rest[0] ?? '').toLowerCase();
             return { cmd: 'init', args: { flavor, ...opts }, flags };
         }