craftdriver 1.7.0 → 1.9.0

package/skills/craftdriver/cli.md

@@ -1,104 +1,230 @@
-# craftdriver CLI
+# CraftDriver CLI for agent exploration
 
-The `craftdriver` binary is what you reach for from a **shell**, not from
-TypeScript. Use it for probing, debugging, and agent-driven exploration.
+Use the CLI to learn the live page and exercise a flow. Use the TypeScript
+library for committed tests.
 
-## Install once
+## Safe setup
 
 ```bash
-npm install craftdriver
+npm install --save-dev craftdriver
+npx craftdriver init codex
 npx craftdriver --help
 ```
 
-## Daemon model (preferred)
+The init command installs `.agents/skills/craftdriver/`. It never reads or
+changes `AGENTS.md`, `CLAUDE.md`, other assistant instructions, or
+`.codex/config.toml`. `--dry-run` previews the installation. `--mcp` only prints
+an optional project-pinned MCP snippet.
 
-Long-lived browser; each command is a one-shot RPC. State (page,
-cookies, storage) survives between calls.
+## Persistent browser
 
 ```bash
 npx craftdriver daemon start
 npx craftdriver go http://127.0.0.1:8080/login.html
-npx craftdriver click 'button[type=submit]'
+npx craftdriver snapshot
 npx craftdriver daemon stop
 ```
 
-If no daemon is running, the first command auto-starts one. Use
-`daemon start` explicitly when you want a non-default browser
-(`--browser firefox`) or a specific timing.
+The first ordinary command auto-starts the daemon when needed. State, cookies,
+and the active page survive between commands.
+
+The daemon uses a Unix socket and is not available on Windows. On Windows, use
+the configured MCP server for a persistent agent session, or send the whole
+flow in one `--ephemeral` script.
+
+## Current commands
+
+```text
+go <url>
+find <selector> [--all] [--limit N] [--offset N]
+exists <selector>
+click <selector>
+dblclick <selector>
+fill <selector> <value>
+type <text>
+clear <selector>
+check <selector> | uncheck <selector>
+select <selector> <value>
+focus <selector> | scroll <selector>
+press <key> [selector]
+hover <selector>
+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...]
+text [selector] [--limit N]
+attr <selector> <name>
+value <selector>
+is visible|enabled|checked <selector>
+wait <selector> [--state visible|hidden|attached|detached] [--timeout ms]
+wait load [--state load|domcontentloaded|networkidle]
+pages
+page list | open [url] | select <index|id> | close <index|id>
+snapshot
+locators <selector>
+screenshot [-o out.png] [--full-page] [--selector selector]
+eval <javascript>
+back | forward | reload | status | quit
+daemon start | status | stop
+session list | close [name]
+state save <name> [--session-storage] | load <name> | list
+logs [list] [--kind console,error,request,response] [--level l]
+     [--contains s] [--since N] [--limit N] | wait ... | clear
+mock add <pattern> [--status N] [--body S] | block <pattern>
+     | list | remove <id> | clear
+trace start [name] [--no-screenshots] | stop [--zip] | status
+```
+
+## Named sessions
 
-## Ephemeral mode (sandboxed agents)
+Add `--session <name>` to any command to run it against its own browser,
+cookies, page selection, snapshot baseline and refs. Omitting the flag means
+the session named `default`.
 
 ```bash
-printf 'go http://127.0.0.1:8080/login.html
-fill "#user" alice
-click "button[type=submit]"
-text "#result"
-' | npx craftdriver --ephemeral
+npx craftdriver go http://127.0.0.1:8080/login.html --session shopper
+npx craftdriver go http://127.0.0.1:8080/admin.html  --session admin
+npx craftdriver session list
+npx craftdriver session close admin
 ```
 
-One short-lived browser for the whole script. No daemon, no socket.
+Use this when one workflow needs two logged-in identities at once, not as a
+default habit — each session is a real browser process and only 8 may be open
+at a time. Sessions start on first use and run independently, so a slow
+command in one does not block another.
 
-## Commands you actually use
+**Refs are per-session.** `e4` in one session and `e4` in another are
+different elements, and nothing will warn you if you mix them up. Run
+`snapshot` and the commands that use its refs with the same `--session`.
 
-```
-go <url>                navigate active page
-find <sel> [--all]      first match (or all); pretty-prints index + tag + text
-exists <sel>            0-wait probe; exit 0 = match, exit 1 = none
-click <sel>
-fill <sel> <value>
-press <key> [sel]
-hover <sel>
-text [sel]              page text or element text
-attr <sel> <name>
-value <sel>
-is visible|enabled|checked <sel>
-wait <sel> [--state visible|hidden|attached|detached] [--timeout ms]
-wait load [--state load|domcontentloaded|networkidle]
-pages
-screenshot [-o out.png] [--full-page] [--selector sel]
-eval <js>               last resort
-back | forward | reload | status | quit
-daemon start|status|stop
-```
+`--session` is not available with `--ephemeral`, which is a single browser
+that exits with the command.
+
+`select` matches an `<option>` by its `value` attribute, not its label.
+
+Use `fill <selector> <value>` to put a value in a field — it clears first and
+delivers real key events, so fields with key handlers work. `type <text>` takes
+no selector and types into whatever holds focus, mapping onto
+`browser.keyboard.type()`; reach for `focus <selector>` then `type` only when
+you need to append to existing text. `focus` leaves the caret at the end.
+
+`eval` is a last resort for inspection, not a replacement for public test APIs.
 
 ## Selector syntax
 
-CSS by default. Switch kind with `prefix=value`:
+CSS is the default. Prefix semantic selectors:
 
+```text
+role=button[name=Submit]   label=Email          testid=login-btn
+text=Sign In              text*=Sign           placeholder=Search…
+alt=Logo                  title=Help           xpath=//div[1]
+id=submit                 name=email           tag=h1
 ```
-role=button[name=Submit]   text=Sign In            text*=Sign
-label=Email                placeholder=Search…     testid=login-btn
-alt=Logo                   title=Help              xpath=//div[1]
-id=submit                  name=email              tag=h1
-```
 
-Anything else (including CSS attribute selectors like
-`button[type=submit]`) is parsed as CSS.
+Use `exists` as a zero-wait uniqueness probe and `find --all` to inspect
+ambiguous matches.
+
+## Tabs
+
+Commands act on the active tab. A tab the application opens by itself is
+listed by `page list` but is not selected, so nothing switches under you —
+use `page select <index|id>` first. An unknown target is an error rather than
+a fallback to the active tab. Switching, opening, or closing a tab clears
+refs, so take a fresh `snapshot` afterwards.
+
+## Console and network evidence
 
-## Output
+`logs` answers what the page logged and requested, after the fact — capture is
+already running before your first command, so you never arrange it in advance
+or re-run a flow to observe it.
 
-- TTY → human-readable text.
-- Piped or redirected → `{"ok":true,"result":…}` per line.
-- Force with `--json` or `--pretty`.
-- Errors include a stable `code:` line (same codes as the library
-  — see `docs/error-codes.md`). Use the code, not the prose.
+Use it to check your work: after a click, `logs --kind error` tells you whether
+the app threw, and `logs --kind request,response --contains /api/` shows what it
+called. This is the evidence to cite when explaining a failure.
 
-## Exit codes
+Ask for deltas, not dumps: every result carries a `cursor`; pass it back as
+`--since` to get only what happened since. `logs wait --contains <text>` scans
+what already arrived before waiting, so it resolves immediately when the event
+has already happened.
 
-- `0` success (or `exists` matched ≥ 1)
-- `1` assertion / timeout / `NO_MATCH` / `exists` matched zero
-- `2` usage error
+History is bounded (500 entries / 512 KB, oldest evicted). Check `dropped` and
+`droppedBeforeCursor` before concluding that nothing happened — a non-zero
+`droppedBeforeCursor` means the page you asked for has a hole in it.
+
+Network rows carry URL, method, status, MIME type and time only. No bodies,
+cookies or headers — do not report them as if they were a full capture. URLs
+include query strings, so avoid echoing sensitive query tokens into a report.
+
+## Traces and mocking
+
+`trace start <name>` … `trace stop --zip` records actions, console, network and
+screenshots under `.craftdriver/traces/`. Reach for it when a failure is not
+explicable from a snapshot — not by default, since it costs size and time.
+One trace at a time; a second `start` is an error.
+
+`mock add <pattern> --status N --body S` serves a fixed response and
+`mock block <pattern>` fails matching requests, so you can drive error paths
+without touching the application. `mock list` and `mock clear` manage them;
+clear them when done, since they outlive the command that added them.
+
+Only these flat shapes exist. The library's `network.intercept()` takes a
+handler function that no command line can express — if you need dynamic
+behaviour, write it in a test with the library API instead of asking for a
+CLI flag that does not exist.
+
+## Saved login state
+
+`state save <name>` captures the current browser's cookies and local storage;
+`state load <name>` puts them back. Use it so you log in once instead of
+replaying the form for every exploration.
+
+On Chrome/Chromium and Firefox BiDi, load before the first real navigation:
+`state load <name>` → `go <url>`. Cookies plus all captured localStorage origins
+are ready for the page's first script. If a page is already open, reload it
+after the overlay.
+
+Classic browsers (including Safari) require `go <url>` → `state load <name>` →
+`reload`, and only a single matching origin is supported. State saved with
+`--session-storage` also requires that active-page order because sessionStorage
+is tab-scoped. Unsupported combinations fail before mutation rather than
+silently restoring only cookies.
+
+State files are credentials — cookies included. They live under
+`.craftdriver/state/`, owner-only. Never print one, commit one, or paste its
+contents into a test; pass a bare name (`alice`), never a path. `state save`
+reports counts and origins only, and that is all you should report onward.
+
+`state load` clears refs, so take a fresh `snapshot` after it.
+
+## Refs vs. durable locators
+
+A `ref=eN` from `snapshot` names one element for as long as it lives. It cannot
+drift onto a different element: if the element is removed or duplicated, or the
+page navigates or reloads, the command fails with `STALE_REF` and you take a
+fresh snapshot. Refs are never reused, so an old ref never matches a new page.
+
+Refs are still exploration state and never belong in test code. To write a test,
+turn the element into a durable selector and let CraftDriver check it against
+the live page first:
+
+```bash
+npx craftdriver locators ref=e7
+```
 
-## Defaults
+Each candidate is reported `unique`, `ambiguous`, or `missing`, ordered by
+durability (role + name, label, test id, unique text, minimal CSS). Use one
+reported `unique`. If none is, add a `data-testid` to the application rather
+than committing a positional selector.
 
-- 5 s per-call timeout (override with `--timeout ms` or
-  `CRAFTDRIVER_AGENT_TIMEOUT`).
-- Probe with `exists` before `click`/`wait` when you're guessing.
-- Don't `sleep`. `wait <sel>` is auto-waiting; `wait load` waits on
-  document state.
+## Output and failures
 
-## When NOT to use the CLI
+- TTY output is concise text; piped output is JSON per line.
+- `--json` and `--pretty` force the output format.
+- Exit `0` is success, `1` is action/assertion/no-match failure, and `2` is
+  invalid CLI usage.
+- Errors carry the same stable codes as the public library.
 
-Writing a test suite. Use the library (`import { Browser } from
-'craftdriver'`) — it has 30 s default timeouts, full TS types, and
-chainable `Locator` ergonomics.
+Do not add sleeps. CLI actions already auto-wait, and `wait` expresses explicit
+page conditions.

package/skills/craftdriver/patterns.md

@@ -1,10 +1,12 @@
-# craftdriver — patterns
+# CraftDriver — patterns
 
-Worked recipes. Each is ≤ ~200 tokens; load on demand from
-[SKILL.md](SKILL.md).
+Worked recipes, each kept compact. Load on demand from [SKILL.md](SKILL.md).
 
 ## 1. Login, save storage state for reuse
 
+Add `.auth/` to the consuming project's `.gitignore`; these files contain live
+session cookies even though CraftDriver writes them with restricted permissions.
+
 ```ts
 const browser = await Browser.launch();
 await browser.navigateTo('https://app.example.com/login');
@@ -13,21 +15,28 @@ await browser.locator(By.labelText('Password')).fill(process.env.PW!);
 await browser.locator(By.role('button', { name: 'Sign in' })).click();
 await browser.locator(By.testId('dashboard')).expect().toBeVisible();
 
-// Persist for fast subsequent runs.
-const state = await browser.defaultContext.storageState();
-await fs.writeFile('.auth/state.json', JSON.stringify(state));
+// Persist atomically with owner-only permissions where supported.
+await browser.saveState('.auth/state.json');
 await browser.quit();
 ```
 
 ## 2. Re-use saved login
 
+On a BiDi session, launch restores cookies and every captured localStorage
+origin before the first real navigation. Application changes then survive
+reload because the state is seeded once, not replayed on every document.
+
 ```ts
-const state = JSON.parse(await fs.readFile('.auth/state.json', 'utf8'));
-const browser = await Browser.launch({ storageState: state });
+const browser = await Browser.launch({ storageState: '.auth/state.json' });
 await browser.navigateTo('https://app.example.com/dashboard');
 await browser.locator(By.testId('dashboard')).expect().toBeVisible();
 ```
 
+Classic WebDriver cannot seed arbitrary origins before navigation: launch
+rejects non-empty state. Launch first, navigate to the sole captured origin,
+then call `browser.loadState('.auth/state.json')`. Snapshots containing
+sessionStorage also require that active-origin flow, including on BiDi.
+
 ## 3. Wait for a network response after a click
 
 ```ts

package/skills/craftdriver/workflow.md

@@ -0,0 +1,149 @@
+# Explore an application and write a CraftDriver test
+
+This workflow turns live browser evidence into an ordinary, reviewable test.
+
+## 1. Learn the project
+
+Before editing, inspect `package.json`, existing test files, fixtures, and the
+commands the repository already uses. Reuse its test runner, naming, setup, URL,
+and browser lifecycle. Do not create a second test framework or edit repository
+assistant instructions.
+
+## 2. Start the application and browser
+
+Run the project's existing app command in its own process. Then:
+
+```bash
+npx craftdriver daemon start
+npx craftdriver go http://127.0.0.1:3000
+npx craftdriver snapshot
+```
+
+Use the actual project URL and wait for a clear page condition when necessary.
+On Windows the daemon is unavailable; use the configured MCP server, or put
+the complete exploration flow into one `--ephemeral` script.
+
+## 3. Inspect before acting
+
+Read role/name, labels, test IDs, visible text, and nearby DOM structure from the
+snapshot. Prefer a semantic selector and prove it:
+
+```bash
+npx craftdriver exists 'role=button[name=Sign in]'
+npx craftdriver find 'label=Email' --all
+```
+
+Refs from the snapshot are safe to act on: a ref binds to one element, and if
+that element is gone or the page navigated, the command fails with `STALE_REF`
+instead of hitting something else. Take a fresh snapshot when that happens.
+
+Never copy `ref=eN` into test code. When you have the right element, ask for a
+durable selector and let CraftDriver validate it against the live page:
+
+```bash
+npx craftdriver locators ref=e7
+```
+
+Use a candidate it reports as `unique`. If none is unique, add a `data-testid`
+to the application rather than committing a positional selector.
+
+## 4. Exercise the user flow
+
+```bash
+npx craftdriver fill 'label=Email' alice@example.test
+npx craftdriver fill 'label=Password' secret
+npx craftdriver click 'role=button[name=Sign in]'
+npx craftdriver text 'testid=welcome'
+```
+
+After each meaningful mutation, inspect fresh output or snapshot state. If a
+selector is ambiguous, refine it from observed structure and validate again.
+
+**The DOM is not the whole story.** An application can fail while showing a
+generic message, or succeed while logging an error you should not ship. Check
+what the page actually did:
+
+```bash
+npx craftdriver logs --kind error                    # exceptions + console.error
+npx craftdriver logs --kind request,response --contains /api/
+```
+
+Capture is already running before your first command, so this works after the
+fact — you never re-run a flow to observe it. Assert on what you find, not on
+what the page happens to render.
+
+## 5. Write the smallest durable test
+
+Follow the repository's style. A direct test may look like:
+
+```ts
+import { Browser, By, expect } from 'craftdriver';
+
+const browser = await Browser.launch({ browserName: 'chrome' });
+try {
+  await browser.navigateTo('http://127.0.0.1:3000');
+  await browser.locator(By.labelText('Email')).fill('alice@example.test');
+  await browser.locator(By.labelText('Password')).fill('secret');
+  await browser.locator(By.role('button', { name: 'Sign in' })).click();
+  await expect(browser.locator(By.testId('welcome'))).toHaveText(/welcome/i);
+} finally {
+  await browser.quit();
+}
+```
+
+Use the exact public API patterns already present in the repository when they
+differ from this standalone example.
+
+## 6. Run and debug
+
+Run the narrowest existing test command. On failure:
+
+1. read the stable CraftDriver error code;
+2. reproduce against the current app;
+3. take a fresh snapshot and re-check the locator with `locators`;
+4. inspect only the relevant page value/text/attribute;
+5. **read the evidence before theorising** — see below;
+6. change application or test source through an explicit diff;
+7. rerun the focused test, then the repository's required checks.
+
+### Read the evidence
+
+Most failures that look mysterious in the DOM are explicit in the console or
+the network journal:
+
+```bash
+npx craftdriver logs --kind error                 # exceptions and console.error
+npx craftdriver logs --kind response --contains /api/   # status codes
+```
+
+A page that renders "Something went wrong" tells you nothing; a 4xx on
+`/api/checkout` and a matching `console.error` tell you exactly where to look.
+`--kind error` covers both uncaught exceptions and `console.error`, since a
+caller asking for errors means both.
+Quote that evidence when you explain the failure, rather than guessing from the
+rendered text.
+
+For a failure that a snapshot cannot explain — a race, or something that only
+happens mid-flow — record the whole run and inspect it afterwards:
+
+```bash
+npx craftdriver trace start bug
+# …reproduce…
+npx craftdriver trace stop --zip
+```
+
+To confirm a diagnosis, drive the branch directly instead of waiting for the
+real backend to misbehave:
+
+```bash
+npx craftdriver mock add '**/api/checkout*' --status 500
+npx craftdriver mock clear     # always clean up; mocks outlive the command
+```
+
+### Never heal a test at runtime
+
+Do not make a failing test green through sleeps, broad catch blocks, weaker
+assertions, or silent runtime selector substitution. If the application
+changed, change the test in an explicit source diff and say what changed and
+why. A test that hides a real application change is worse than a failing one,
+because it removes the signal without fixing the cause.