[brynary]

Stacked on #46.

This is phase 2 of the Whirl–BrowserSim delivery sequence: the CLI and settings rules. It does not integrate BrowserSim. It gives ordinary runs the agreed command line, and it gives later commands one shared way to resolve options.

This changes existing scripts. Whirl has no users to migrate yet, so there are no aliases except --artifacts.

Explicit run and renamed flags

Before	After
whirl checkout.whirl	whirl run checkout.whirl
whirl --artifacts DIR ...	whirl run --out DIR ...
whirl --storage app.json ...	whirl run --load-state app.json ...
whirl --save-storage app.json ...	whirl run --save-state app.json ...
whirl --base URL --step-timeout 15s ...	whirl run -O base=URL -O step-timeout=15s ...

• whirl checkout.whirl and whirl --headed checkout.whirl fail with a hint to use whirl run. whirl alone prints help and exits 4.
• --out defaults to whirl-artifacts/, as before. --artifacts still works and prints a deprecation warning. Supplying both is an error.
• --storage and --save-storage fail with a message that names the new flag. The state file format does not change; SPEC section 13 documents it.
• --load-state cannot be combined with a file's storage or setup option. The old --storage silently replaced the file's storage option.

-O key=value

whirl run and whirl check take repeatable -O arguments that set an [Options] key for every file, setup flows included:

whirl run checkout.whirl -O browser=firefox -O step-timeout=15s
whirl run flows/ -O block-hosts=analytics.example.com -O block-hosts=*.analytics.example.com
whirl run flows/ -O allow-hosts=
whirl check checkout.whirl -O model=anthropic/claude-sonnet-5

• Settings resolve from the built-in default, then the file, then the command line.
• Each value is one literal item, with the file option's validation. A snapshot-mask value is the exception: it is a locator, written as in a file.
• The last value wins for a single-value key. For a list key, the -O items replace the file's list, and an empty value clears it.
• An unknown key, an invalid value, and -O setup= are usage errors, found before any browser starts.
• --browser is the one flag left that sets an option. It goes through the same resolver, and --browser together with -O browser= is an error, even when the values agree. --base, --step-timeout, --entry-timeout, and --user-agent are removed; each fails with a message that names its -O form.
• whirl check lints with the overrides in place, and still launches no browser. A lint about a -O value has no line.

One module, lang::cli_options, owns this, so later commands can reuse it. It puts the command line's option lines in place of the file's, marked with their source.

block-hosts, browsersim-origin, and settings in reports

• [Options] block-hosts blocks the hosts its globs match, with the glob rules of allow-hosts. A block wins over an allowance, including the base host's implicit allowance. It applies to page requests, redirect hops, WebSockets, and HTTP entries.
• Each blocked host now shows its rule, as in blocked host: localhost (not in allow-hosts). The JSON report adds blockedHostRules; blockedHosts is unchanged.
• browsersim-origin: build | recorded is checked but not used by ordinary runs. When a file or -O sets it, the console and reports list it as inactive. Other browsersim- keys stay unknown.
• The JSON and HTML reports list each file's settings: the value it ran with, masked like other output, and whether it came from the default, the file, or the command line.
• The shim moves to protocol 9, because endFlow now returns a rule with each blocked host. Installed bundles need whirl install.

Recording contract

The accepted ADR recording-settings-and-bundles fixes what later recording work must follow. whirl record is the only recording command. --engine and --browser stay separate. A *.sim.json recording stores every effective setting, and replay uses only those. Each written flow records to a sibling bundle named after its stem. It adds no commands.

Commits

1. Run files with whirl run, and rename the output and state flags.
2. Set options from the command line with -O key=value.
3. Add block-hosts, an inactive browsersim-origin, and settings in reports.
4. Draft the recording settings and bundle contract as an ADR, then accept it.
5. Take each -O value as one literal item.
6. Remove --base, --step-timeout, --entry-timeout, and --user-agent.

Validation

• mise run check passes after each commit.
• CLI cases cover the removed forms and each -O error.
• Browser tests use the local test site, whose page fetches the same server under a second host name. They cover:
  • -O across two flows: the last value wins, and list items replace or clear the file's list.
  • block-hosts alone, block-hosts with allow-hosts, and blocking the base host, for page requests and an HTTP entry.
  • An inactive browsersim-origin, and effective settings that keep an env.* user agent out of the console, JSON, and HTML output.
  • The default output directory, --out, and the --artifacts alias.
• CI below.

🤖 Generated with Claude Code