feat: recipes — saved, shareable session scripts

[sanketsudake]

Implements RFC-0009 (recipes). Stacked on #13 → #12 → #11 → #10.

RFC-0011 (session recording) is being added to this same branch and will appear here shortly.

What this is for

session already does the hard part — many commands over one held connection, with refs that stay valid across the batch. What it lacked was a way to keep a batch.

Today, a user who works out the exact eleven commands that submit their timesheet has that knowledge in shell history, or a bespoke wrapper, or an agent's context that's gone tomorrow. There's no artifact — so nothing accumulates, nothing is reviewable, and nothing is shareable. The most valuable thing a user of this tool produces is a working automation for a specific internal app, and there was no unit in which to hand that to a colleague.

name: submit-timesheet
description: Fill and submit the weekly timesheet.
inputs:
  week:  { required: true, description: "Monday of the week, YYYY-MM-DD" }
  hours: { default: "8" }
target: url:workday
steps:
  - label: open the timesheet
    run: ["nav", "https://workday.internal/time/{{week}}"]
  - run: ["wait", "--idle"]
  - label: save
    run: ["click", "--by", "name", "Save and Close", "--role", "button", "--wait-text", "saved"]

chrome-cdp recipe run submit-timesheet --set week=2026-07-20

It is deliberately not a language

The design constraint is that a recipe is session with a header. run is an argv array — identical to a session stdin line, so anything valid in one is valid in the other. on_error is abort or continue and nothing else: no retries, no conditionals, no loops. If a recipe needs control flow it should be a program that calls session, and the docs say so.

VS-10 is the structural guard for that claim, and it's implemented: dry-run output piped into session executes identically to recipe run, asserted by reflect.DeepEqual on the recorded browser call sequences. It holds because the runner's only execution primitive is the same Execute(argv...) that session uses per line.

For the pipe to be real, human-mode --dry-run puts only argv lines on stdout (the note goes to stderr).

There is no shell, and there must never be one

A recipe is a file that gets shared and run against your authenticated browser. A shell: step type would make every shared recipe a code-execution vector, so substitution goes into an argv element and the schema is decoded with KnownFields(true) — an unknown key, including shell:, is exit 2.

VS-15 pins it with 11 hostile values (; rm -rf /, backticks, $(...), newlines, quotes), asserted byte-for-byte at the browser boundary.

Validation is a separate pass from execution

Parse → validate → resolve inputs → check every placeholder → then connect. Everything a recipe can get wrong statically is exit 2 with Chrome never contacted, proven with the noCall(t) helper across 12 cases.

An unknown --set key is rejected, not ignored — silently dropping a typo would let a run proceed with a default the user didn't intend.

Rules added beyond the RFC text, each closing a hole

• name must equal the filename stem — otherwise recipe list advertises one name and recipe run uses another.
• session is a reserved step verb — a step invoking it would read the process's stdin.
• argv[0] must be a literal — without this, run: ["{{cmd}}"] plus --set cmd=recipe smuggles recursion past the static recursion check.
• run elements must carry the !!str tag, so ["--nth", 2] says "quote it" rather than silently coercing.

Policy interaction (from #12)

recipe run is classified Exempt for the same reason session is: it touches no tab itself and re-enters the command tree per step, so each step is classified and checked on its own. Classifying the wrapper Mutating would refuse a read-only recipe on a read_only origin; Reading would be a lie.

That's a security claim, so it has a test: TestRecipeStepsAreCheckedIndividually runs a recipe whose steps target a refused origin against a browser double that fails the test if any action method is reached. If per-step enforcement regressed, a shared recipe would become a way to drive exactly the origins the policy was configured to refuse.

Testing

All 15 verification scenarios. The bulk is pure internal/recipe tests over t.TempDir() fixtures — no browser, -short clean. gofmt, go vet, go test -race ./... all green.

Ships a worked example and guide in docs/scenarios/.