# runner/

The Node side of aite: reads a script, starts Chrome with the extension, talks to it over the bridge and prints what happened.

```
npm run aite -- run fixtures/hello.aite --config aite.config.json --headless --no-sandbox
```

| File | What it does |
|---|---|
| `parser.ts` | script text to a script or line-numbered errors (the subset that exists so far) |
| `engine.ts` | runs a parsed script command by command over the bridge; formats the report |
| `run.ts` | the whole `aite run`: config, profile, build the extension, bridge, Chrome, run, tidy up |
| `input.ts` | trusted click and typing over the debugging pipe, download folder, finding the run tab | 
| `lockfile.ts`, `lockRun.ts` | the lock file beside a script (`<script>.lock.json`): what each target looked like when first found; read and written by `aite run` unless `--no-lock` |
| `profile.ts` | tells whether another Chrome has a profile open |
| `launcher.ts` | starts Chrome with the extension loaded (and a private debugging pipe) and stops it, helper processes included |
| `cdp.ts` | a client for Chrome's debugging protocol over that pipe |
| `screenshot.ts` | finds the run's tab among Chrome's pages and captures a PNG of it |
| `fixtureServer.ts` | serves a folder of test pages on 127.0.0.1, read only, nothing outside the folder |
| `args.ts`, `cli.ts`, `aiteCli.ts` | the command line |

Exit codes: 0 passed, 1 the test failed, 2 the script, config or options are wrong, 3 Chrome or the extension could not be started or died.

## Negative run: `npm run mutate`

`npm run mutate -- --upstream http://127.0.0.1:PORT --replace "review=1 MALLBUCKS=>1 MUCK" --check /send` starts a proxy on 127.0.0.1 that changes the named string in the pages it relays,
proves the change on `--check PATH` (exit 2 and no proxy when the page never had the string), and prints the address of the broken build. Point a script's start URL at it; the script must fail at the step that checks that string.

## Record mode: `aite record`

`aite record https://example.com/form --out scripts/draft.aite --profile NAME` opens the page in a visible Chrome on that profile (so it can be signed in), with a recorder injected over the debugging pipe (no extension), and writes what you do when you press Enter in the terminal.

- Recorded: clicks (on the control that was meant, not on the text inside it), typing (once, when the value is committed, or at Enter), selections, ticks and radio buttons, and Enter and Escape. A password field is never recorded; the draft says `"TODO password"`.
- Targets are chosen in this order: role and name, then the element's text, then `data-testid`, then placeholder, a plain id, and last the xpath. A target is only as unique as the page makes it: run the draft and fix an ambiguous one with `index:` or a better target.
- Every step is named `TODO name`, which the parser refuses (E001) until a person names it. The draft has no `verify`: a recording says what was done, never what must be true, so add the checks yourself. Give the test a name too.
- Only the first tab is recorded, nothing inside frames, and a page that opens another tab is not followed. A file that exists is never overwritten.

## Author mode: `aite author`

`aite author journeys/send.md --out scripts/send.aite --model-command "claude -p" --attempts 5` lets a model write the script for a journey (a text file in the person's words) and loops until it is green.

- The model is **a command you give**: it reads the prompt on stdin and prints the script, in one fenced block. It gets `PATH`, `HOME`, `LANG` and the like and an API key if the environment has `ANTHROPIC_API_KEY`, and none of aite's `AITE_*` variables (no GitLab token). Give it whatever options remove its tools (for `claude -p`, see `claude --help`): the author does not rely on that, but a model that can edit files by itself is outside what it can promise.
- Each attempt is written to the one `--out` file (inside `scripts/`, never over an existing file, never through a link) and run for real, without `--freeze`, so the run captures the lock file. A red run goes back to the model with the failing step, and the text the page showed inside a block marked as untrusted page text.
- It **stops and asks a person** (exit 1, `needs-human`), and does not run or write the script, when the model's next version removes, loosens, changes or gives more time to a `verify`; expects a text that is not in the journey; or sends back something refused twice over. It sends back, without counting it as a person's problem: a script that does not parse, a step still named `TODO name`, or a `call` of a check that is not on the allowlist (the author cannot write checks).
- Green means the script passed once. **It is not approved.** A person reads the script and its lock file and commits both: that is the approval. The expectations are only as good as the journey; read every `verify` against it.
- Not tested here: a real model. The tests use a mock and a node program as the model; whether a given model writes good scripts is what manual QA M-07 is for.