docs: add CLAUDE.md guidance + apply test-writing guidelines to the suite (#4)

* docs: add CLAUDE.md + AGENTS.md and .claude/resources guidance

Add repo guidance for Claude Code / AI agents:

- CLAUDE.md: slim index calling out the two load-bearing invariants
  (the result envelope is public API; the CLI never connects to Chrome
  directly — capabilities go through the chrome.Browser seam).
- AGENTS.md: symlink to CLAUDE.md.
- .claude/resources/architecture.md: envelope/exit-code contract, the
  internal/ package map, DI seams, and the daemon/connection model.
- .claude/resources/development.md: build/test/lint commands, what CI
  runs, live-Chrome test behavior, and the release flow.
- .claude/resources/test-writing-guidelines.md: adapted from the Fission
  conventions, keeping only what applies and noting where this repo
  deviates (stdlib not testify; testing.Short() not build tags).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* test: parallelize independent tests and name table subtests

Apply the test-writing guidelines to the existing suite:

- Add t.Parallel() to every independent unit test and subtest across the
  result, target, config, browser, daemon/lifecycle, and cli packages.
- Convert loop-based table tests (cookie/attr/emulate/extract/grid verbs
  and result.TestExitCodeFor) to named t.Run subtests.

Left sequential on purpose: the live-Chrome tests (shared browser),
profile_test.go (t.Setenv), and daemon_test.go (real socket listeners).

Verified: gofmt clean, go vet clean, and the full `go test -race ./...`
(live Chrome included) passes — proving the added parallelism is safe.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: sanketsudake

.claude/resources/architecture.md

@@ -0,0 +1,53 @@
+# Architecture
+
+`chrome-cdp` attaches to the user's **already-running** Chrome over the DevTools Protocol (CDP) and drives it from the command line.
+It never launches a headless browser for real work — the whole point is to reuse the live session's cookies, logins, and extensions.
+
+## The one-envelope, one-exit-code contract
+
+Every command emits a single `result.Envelope` (`internal/result/result.go`) and exits with a code derived from it.
+This contract is the load-bearing interface: both humans and the Claude skill parse against it, so treat it as public API.
+
+- `error.code` strings (fine-grained, e.g. `target_not_found`) map to process exit codes via `result.codeToExit` / `ExitCodeFor`.
+- Exit codes are the coarse, stable contract: `0` ok, `2` usage, `3` connection, `4` target/timeout, `5` cdp, `6` daemon.
+- Adding a new failure mode means adding a `Code*` constant **and** its `codeToExit` entry — an unmapped code silently degrades to `ExitGeneric`.
+- Usage/validation errors (exit `2`) are checked **before** touching Chrome, so a bad flag never launches or connects.
+
+## Package map (`internal/`)
+
+Data flows outermost → innermost: `cli` parses → resolves a `target` → gets a `chrome.Browser` (via `daemon` or direct) → emits a `result`.
+
+- `result` — the envelope, `Err`, and the exit-code table. No dependencies; the root of the contract.
+- `target` — the target grammar (`idprefix | url:<s> | title:<s> | @N`) and `Resolve` against a tab list.
+- `config` — layered defaults: built-in < config file (`~/.config/chrome-cdp/config.toml`) < `CHROME_CDP_*` env < flag. `Builtin()`, `Resolve()`, `FromEnv()`.
+- `browser` — endpoint discovery: finds Chrome's `DevToolsActivePort` file and computes the per-endpoint key (see connection model below).
+- `chrome` — the `Browser` interface and its chromedp-backed implementation: snapshot, click/type/fill/select, grid, wait, raw CDP. The real driver logic lives here.
+- `chrometest` — `StubBrowser`, a permissive `chrome.Browser` double embedded by the `cli` and `daemon` tests.
+- `state` — the sticky current-target store, keyed per endpoint so distinct `--port`s don't share a "current tab".
+- `daemon` — the held-connection RPC: a background process holds the CDP attach so Chrome's consent prompt appears once per session, not per command.
+- `cli` — the cobra command tree (`app.go` = wiring + envelope emission, `commands.go` = the verbs). Knows nothing about how the browser connects; `main` injects that.
+
+## Dependency injection at the seams (`cmd/chrome-cdp/main.go`)
+
+`cli.App` is deliberately ignorant of daemons, sockets, and process spawning — it holds function seams that `main` wires up:
+
+- `WithConnector` — how to get a `chrome.Browser` (daemon client vs. `--no-daemon` direct connect), invoked lazily only when a command needs Chrome.
+- `WithStickyTarget` — get/set the current target; keyed by `ConnOpts` so each endpoint has its own.
+- `WithDaemonCtl` — start/stop/status for the per-endpoint daemon.
+- `WithDefaults` — inject config+env defaults (tests keep `config.Builtin()`).
+
+This is why tests can inject a `chrometest.StubBrowser` directly and never spawn a process.
+When adding a command that needs a new capability, add the method to the `chrome.Browser` interface, give it a default in `chrometest.StubBrowser` (one place), then implement it in `internal/chrome`.
+
+## Connection & daemon model
+
+- The **endpoint key** derives from the port file + effective `--port`; it names both the daemon socket and the sticky-state file.
+  It cannot be computed once at startup — `--port` isn't known until cobra parses flags — so `main` computes it per command from `ConnOpts`.
+- The **daemon** (`chrome-cdp __daemon <socket>`, a hidden mode) holds one CDP connection for ~30 min and serves commands over a Unix socket, so the "Allow debugging?" consent fires once.
+  `--no-daemon` bypasses it and connects directly (used by tests and one-shot scripts).
+- Chrome M136+ dropped the classic `--remote-debugging-port` for the default profile; `browser` reads `DevToolsActivePort` and connects directly, which is why it keeps working where older tools broke.
+
+## Human vs. JSON rendering
+
+`--json` emits the raw envelope; otherwise `renderHuman` prints a terse line (`✓ …` / `✗ …` to stderr), honoring `NO_COLOR` and `--quiet`.
+The human path is a courtesy; the JSON envelope is the contract. Never let a human-formatting change alter the envelope shape.

.claude/resources/development.md

@@ -0,0 +1,36 @@
+# Development
+
+## Build, test, lint
+
+```sh
+go build -o chrome-cdp ./cmd/chrome-cdp   # build the binary (the checked-in ./chrome-cdp is gitignored)
+go test ./...                             # full suite — spawns a headless Chrome for the live-driver tests
+go test -short ./...                      # skip every live-Chrome test (no Chrome needed; what to run without a browser)
+go test -race ./...                       # what CI runs
+go test -run TestExitCodeFor ./internal/result   # a single test
+go test ./internal/chrome/ -run TestFill  # a single package + test
+gofmt -l .                                # CI fails if this lists any file
+go vet ./...
+```
+
+There is no Makefile and no golangci config — CI is exactly the four steps in `.github/workflows/ci.yml`: `gofmt -l`, `go vet`, `go test -race ./...`, `go build ./...`, on ubuntu + macOS.
+Before pushing, run `gofmt -l .` (must be empty), `go vet ./...`, and `go test -race ./...` locally to match it.
+
+## The live-Chrome tests
+
+Tests in `internal/chrome/*_test.go` drive a **real** Chrome the test spawns.
+They guard themselves with `if testing.Short() { t.Skip(...) }` and also skip gracefully when no Chrome binary is present (so `macos-latest` in CI, which has no Chrome, is green without running them).
+CI runs the live path on `ubuntu-latest` (it ships `google-chrome-stable`).
+When iterating on non-driver code, prefer `go test -short ./...` — it's fast and needs no browser.
+
+## Release
+
+Tag-driven via GoReleaser (`.goreleaser.yaml`): pushing a `vX.Y.Z` tag runs `goreleaser release` (see `.github/workflows/release.yml`).
+`Version` in `internal/cli/commands.go` is set at build time via `-ldflags`; leave it `"dev"` in source.
+Validate config changes with `goreleaser check`.
+
+## Conventions
+
+- Follow the repo's markdown style for docs: **one sentence per line** (keeps `git diff` surgical; renders identically).
+- The user opens PRs — push the branch, don't open the PR, unless asked.
+- Never commit the built `./chrome-cdp` binary, `*.png`/`*.pdf` screenshots, or `.scratch/` (all gitignored).

.claude/resources/test-writing-guidelines.md

@@ -0,0 +1,43 @@
+# Test-writing guidelines
+
+Adapted from the [Fission test-writing conventions](https://github.com/fission/fission/blob/main/.claude/resources/test-writing-guidelines.md), keeping only what applies to this Go CLI and reconciling with the conventions already in the tree.
+When a rule below disagrees with an existing test, follow the existing pattern in that package — consistency wins — and raise the discrepancy rather than silently rewriting.
+
+## Structure (adopted)
+
+- **Table-driven** with a `map[...]` or `[]struct` of cases; use `t.Run(name, …)` with descriptive case names for anything with more than a couple of cases (see `internal/result/result_test.go`).
+- **`t.Parallel()`** on independent tests and non-state-sharing subtests. Do **not** parallelize the live-Chrome tests — they share a spawned browser.
+- **`t.TempDir()`** for any filesystem fixture; never write into the repo or a hardcoded path.
+- **`t.Cleanup()`** for teardown instead of bare `defer` when the resource is set up mid-test.
+- Name tests `TestXxx` and test through the **exported API** of the package (the envelope, the `chrome.Browser` interface, `target.Resolve`) — not unexported internals, unless the internal is the unit.
+
+## The `chrome.Browser` seam (project-specific)
+
+- Unit-test CLI and daemon behavior against **`chrometest.StubBrowser`**, not a real browser. Embed it and override only the methods the test asserts on.
+- When you add a method to the `chrome.Browser` interface, give it a permissive default in `chrometest.StubBrowser` — that's the single place a new method gets its test default.
+- Assert on the **envelope and exit code** (the contract), not on incidental human-rendered text. A test that pins `error.code` → exit code is more valuable than one that pins a `✗ …` string.
+
+## Live-Chrome tests (project-specific)
+
+- Guard every test that drives a real Chrome with `if testing.Short() { t.Skip(...) }`, and skip gracefully when no Chrome binary is found. This project uses `testing.Short()` for this, **not** `//go:build integration` tags.
+- These tests legitimately use `context.Background()` (the driver context is tied to the browser lifecycle, not the test's). Elsewhere, prefer a scoped context.
+- Keep them hermetic: spawn the browser the test needs, drive a `data:`/local fixture page where possible, and tear it down in `t.Cleanup`.
+
+## HTTP handlers (adopted, where relevant)
+
+Use `net/http/httptest` (`NewRecorder` / `NewServer`) for any HTTP-facing code rather than a real network listener.
+
+## Property-based tests & fuzzing (adopted, where valuable)
+
+- The parser-shaped surfaces — the `target` grammar and the `--by` selector syntax — are good fuzz/property targets: round-trip stability, and "only exactly-valid input parses". Prefer `pgregory.net/rapid` over the frozen `testing/quick` if you add property tests; direct `go test -fuzz` at the parser boundary and check the corpus into `testdata/`.
+- Good properties here: `Resolve` is deterministic for a fixed tab list; a selector that round-trips through parse→format is unchanged; unknown `error.code` always maps to `ExitGeneric`.
+
+## Assertions (project deviation — note before changing)
+
+The existing suite uses the **standard library** (`t.Errorf` / `t.Fatalf`), not `testify`.
+Fission mandates `testify require`/`assert`; this repo does not depend on it.
+Match the standard-library style in existing files; do not introduce `testify` as a new dependency for a single test without agreement.
+
+## Not applicable
+
+These Fission rules target infrastructure this project doesn't have — ignore them: Kubernetes fake clientsets / `envtest`, `go-snaps` snapshots, `porcupine`/TLA+ linearizability, `framework.Connect(t)` integration harness, SPDX-header `make license`, and the Fission-specific builders.

AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

CLAUDE.md

@@ -0,0 +1,25 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+`chrome-cdp` is a Go CLI that drives the user's **already-running** local Chrome over the DevTools Protocol (via chromedp).
+It reuses the live session's logins and cookies, and speaks one JSON envelope + one stable exit-code contract to both humans and AI agents.
+
+## Detailed guidance
+
+Read the resource file that matches your task before making changes:
+
+- **[Architecture](.claude/resources/architecture.md)** — the envelope/exit-code contract, the `internal/` package map, the `chrome.Browser` seam, and the connection/daemon model. Read this before touching anything cross-cutting.
+- **[Development](.claude/resources/development.md)** — build, test (`go test -short` to skip live Chrome), lint, what CI runs, and release.
+- **[Test-writing guidelines](.claude/resources/test-writing-guidelines.md)** — how tests are structured here (stub-driven unit tests, `testing.Short()`-guarded live-Chrome tests) and which conventions are adopted vs. deviated from.
+
+## The two things most likely to trip you up
+
+- **The result envelope is public API.** Every command emits one `result.Envelope`; both humans and the Claude skill parse it. A new failure mode needs a `Code*` constant *and* a `codeToExit` entry, or it silently degrades to `ExitGeneric`. Never let human-formatting changes alter the JSON shape. Validate usage/args *before* connecting to Chrome.
+- **The CLI never connects to Chrome directly.** `cli.App` holds function seams (`WithConnector`, `WithStickyTarget`, `WithDaemonCtl`) that `cmd/chrome-cdp/main.go` wires to the daemon. To add a browser capability: extend the `chrome.Browser` interface → add a default in `chrometest.StubBrowser` (one place) → implement in `internal/chrome`.
+
+## Docs & style
+
+User-facing docs live in `docs/` and `README.md`; the Agent Skill lives in `skills/drive-chrome-cdp/`.
+When editing any markdown, follow the repo style: **one sentence per line**.
+Push branches and let the user open PRs unless asked otherwise.

internal/browser/browser_test.go

@@ -7,6 +7,7 @@ import (
 )
 
 func TestParseDevToolsActivePort(t *testing.T) {
+	t.Parallel()
 	port, wsPath, err := ParseDevToolsActivePort([]byte("9222\n/devtools/browser/2d642c44\n"))
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -20,6 +21,7 @@ func TestParseDevToolsActivePort(t *testing.T) {
 }
 
 func TestParseDevToolsActivePortErrors(t *testing.T) {
+	t.Parallel()
 	for _, in := range []string{"", "9222", "notaport\n/devtools/browser/x"} {
 		if _, _, err := ParseDevToolsActivePort([]byte(in)); err == nil {
 			t.Errorf("ParseDevToolsActivePort(%q) = nil error, want error", in)
@@ -28,6 +30,7 @@ func TestParseDevToolsActivePortErrors(t *testing.T) {
 }
 
 func TestWSURLFromPortFile(t *testing.T) {
+	t.Parallel()
 	dir := t.TempDir()
 	f := filepath.Join(dir, "DevToolsActivePort")
 	if err := os.WriteFile(f, []byte("9222\n/devtools/browser/abc\n"), 0o600); err != nil {
@@ -43,12 +46,14 @@ func TestWSURLFromPortFile(t *testing.T) {
 }
 
 func TestWSURLFromPortFileMissing(t *testing.T) {
+	t.Parallel()
 	if _, err := WSURLFromPortFile(filepath.Join(t.TempDir(), "nope")); err == nil {
 		t.Error("expected error for missing port file")
 	}
 }
 
 func TestDecideConnection(t *testing.T) {
+	t.Parallel()
 	cases := []struct {
 		name string
 		p    Probe
@@ -67,6 +72,7 @@ func TestDecideConnection(t *testing.T) {
 	}
 	for _, c := range cases {
 		t.Run(c.name, func(t *testing.T) {
+			t.Parallel()
 			if got := DecideConnection(c.p); got != c.want {
 				t.Errorf("DecideConnection(%+v) = %v, want %v", c.p, got, c.want)
 			}
@@ -75,6 +81,7 @@ func TestDecideConnection(t *testing.T) {
 }
 
 func TestEndpointKey(t *testing.T) {
+	t.Parallel()
 	// An explicit port yields a distinct, port-specific key (no collisions).
 	if k := EndpointKey("", 9333); k != "127.0.0.1:9333" {
 		t.Errorf("explicit port key = %q, want 127.0.0.1:9333", k)

internal/cli/app_test.go

@@ -40,6 +40,7 @@ func run(t *testing.T, b chrome.Browser, args ...string) (env map[string]any, st
 }
 
 func TestListJSONEnvelope(t *testing.T) {
+	t.Parallel()
 	b := &fakeBrowser{tabs: []target.Info{
 		{ID: "aa11", Title: "GitHub", URL: "https://github.com/"},
 		{ID: "bb22", Title: "Inbox", URL: "https://mail.google.com/"},
@@ -58,6 +59,7 @@ func TestListJSONEnvelope(t *testing.T) {
 }
 
 func TestEvalWithoutTargetIsTargetError(t *testing.T) {
+	t.Parallel()
 	b := &fakeBrowser{tabs: []target.Info{{ID: "aa11", Title: "X", URL: "u"}, {ID: "bb22", Title: "Y", URL: "v"}}}
 	env, _, code := run(t, b, "eval", "1+1", "--json")
 	if code != 4 {
@@ -72,6 +74,7 @@ func TestEvalWithoutTargetIsTargetError(t *testing.T) {
 }
 
 func TestRawBadParamsIsUsageError(t *testing.T) {
+	t.Parallel()
 	b := &fakeBrowser{tabs: []target.Info{{ID: "aa11", Title: "X", URL: "u"}}}
 	env, _, code := run(t, b, "raw", "Foo.bar", "not-json", "--target", "aa11", "--json")
 	if code != 2 {
@@ -83,6 +86,7 @@ func TestRawBadParamsIsUsageError(t *testing.T) {
 }
 
 func TestEvalResolvedTargetSucceeds(t *testing.T) {
+	t.Parallel()
 	b := &fakeBrowser{tabs: []target.Info{{ID: "aa11", Title: "X", URL: "u"}, {ID: "bb22", Title: "Y", URL: "v"}}}
 	env, _, code := run(t, b, "eval", "1+1", "--target", "aa11", "--json")
 	if code != 0 {
@@ -94,6 +98,7 @@ func TestEvalResolvedTargetSucceeds(t *testing.T) {
 }
 
 func TestExitCodesCommand(t *testing.T) {
+	t.Parallel()
 	var out, errb bytes.Buffer
 	app := New(&fakeBrowser{}, &out, &errb)
 	code := app.Execute("exit-codes")

internal/cli/config_wire_test.go

@@ -24,6 +24,7 @@ func clickCapture(t *testing.T, defs config.Defaults, args ...string) *queryCapt
 }
 
 func TestConfigDefaultsFeedFlagDefaults(t *testing.T) {
+	t.Parallel()
 	defs := config.Defaults{By: "search", Wait: "ready", Timeout: 5 * time.Second}
 	// No --by/--wait on the command line, so the config defaults take effect.
 	b := clickCapture(t, defs, "click", "#x", "--target", "aa11", "--json")
@@ -33,6 +34,7 @@ func TestConfigDefaultsFeedFlagDefaults(t *testing.T) {
 }
 
 func TestExplicitFlagOverridesConfigDefault(t *testing.T) {
+	t.Parallel()
 	defs := config.Defaults{By: "search", Wait: "ready", Timeout: 5 * time.Second}
 	// An explicit --by must win over the config default.
 	b := clickCapture(t, defs, "click", "#x", "--target", "aa11", "--by", "id", "--json")
@@ -45,6 +47,7 @@ func TestExplicitFlagOverridesConfigDefault(t *testing.T) {
 }
 
 func TestConfigTargetIsFallback(t *testing.T) {
+	t.Parallel()
 	// With no --target and no sticky target, the config default target resolves.
 	defs := config.Defaults{By: "css", Wait: "visible", Timeout: 5 * time.Second, Target: "@1"}
 	b := &fakeBrowser{tabs: []target.Info{{ID: "aa11", Title: "A", URL: "u"}}}

internal/cli/fill_test.go

@@ -26,6 +26,7 @@ func (f *fillCapture) Wait(_ context.Context, _ string, c chrome.WaitCond) (map[
 }
 
 func TestFillAndWaitTextCommand(t *testing.T) {
+	t.Parallel()
 	b := &fillCapture{fakeBrowser: fakeBrowser{tabs: []target.Info{{ID: "aa11", Title: "A", URL: "u"}}}}
 	env, _, code := run(t, b,
 		"fill", "#h", "8", "--wait-text", "Saved", "--target", "aa11", "--json")