Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/rfc/0001-keyboard-key-verb.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# RFC-0001: Keyboard input — the `key` verb

- **Status:** Draft
- **Status:** Accepted — implemented in [#10](https://github.com/sanketsudake/chrome-cdp-cli/pull/10)
- **Priority:** P0
- **Area:** input
- **Depends on:** —
Expand Down
2 changes: 1 addition & 1 deletion docs/rfc/0002-console-messages.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# RFC-0002: Console messages — the `console` verb

- **Status:** Draft
- **Status:** Accepted — implemented in [#13](https://github.com/sanketsudake/chrome-cdp-cli/pull/13), with follow-up fixes in [#16](https://github.com/sanketsudake/chrome-cdp-cli/pull/16)
- **Priority:** P0
- **Area:** observability
- **Depends on:** —
Expand Down
2 changes: 1 addition & 1 deletion docs/rfc/0003-network-requests.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# RFC-0003: Network requests — the `net` verb

- **Status:** Draft
- **Status:** Accepted — implemented in [#13](https://github.com/sanketsudake/chrome-cdp-cli/pull/13), with follow-up fixes in [#16](https://github.com/sanketsudake/chrome-cdp-cli/pull/16)
- **Priority:** P0
- **Area:** observability
- **Depends on:** RFC-0002 (reuses the daemon-side CDP event buffer)
Expand Down
2 changes: 1 addition & 1 deletion docs/rfc/0004-mcp-server-mode.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# RFC-0004: MCP server mode — `chrome-cdp mcp`

- **Status:** Draft
- **Status:** Accepted — implemented in [#15](https://github.com/sanketsudake/chrome-cdp-cli/pull/15), with follow-up fixes in [#18](https://github.com/sanketsudake/chrome-cdp-cli/pull/18)
- **Priority:** P0
- **Area:** distribution
- **Depends on:** RFC-0012 (should land with or before this)
Expand Down
2 changes: 1 addition & 1 deletion docs/rfc/0005-pointer-verbs.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# RFC-0005: Pointer verbs — `hover`, `dblclick`, `rclick`, `drag`

- **Status:** Draft
- **Status:** Accepted — implemented in [#10](https://github.com/sanketsudake/chrome-cdp-cli/pull/10)
- **Priority:** P1
- **Area:** input
- **Depends on:** —
Expand Down
2 changes: 1 addition & 1 deletion docs/rfc/0006-file-upload.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# RFC-0006: File upload — the `upload` verb

- **Status:** Draft
- **Status:** Accepted — implemented in [#12](https://github.com/sanketsudake/chrome-cdp-cli/pull/12)
- **Priority:** P1
- **Area:** input
- **Depends on:** —
Expand Down
2 changes: 1 addition & 1 deletion docs/rfc/0007-tab-lifecycle.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# RFC-0007: Tab lifecycle — `close`, `activate`, and history navigation

- **Status:** Draft
- **Status:** Accepted — implemented in [#10](https://github.com/sanketsudake/chrome-cdp-cli/pull/10)
- **Priority:** P1
- **Area:** tabs
- **Depends on:** —
Expand Down
2 changes: 1 addition & 1 deletion docs/rfc/0008-screenshot-options.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# RFC-0008: Screenshot options — element, full-page, region, format

- **Status:** Draft
- **Status:** Accepted — implemented in [#11](https://github.com/sanketsudake/chrome-cdp-cli/pull/11)
- **Priority:** P1
- **Area:** capture
- **Depends on:** —
Expand Down
2 changes: 1 addition & 1 deletion docs/rfc/0009-recipes.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# RFC-0009: Recipes — saved, shareable `session` scripts

- **Status:** Draft
- **Status:** Accepted — implemented in [#14](https://github.com/sanketsudake/chrome-cdp-cli/pull/14)
- **Priority:** P2
- **Area:** workflow
- **Depends on:** `session` (exists); benefits from RFC-0001, RFC-0005, RFC-0006
Expand Down
2 changes: 1 addition & 1 deletion docs/rfc/0010-page-reading-ergonomics.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# RFC-0010: Page-reading ergonomics — `text --article` and `eval --await`

- **Status:** Draft
- **Status:** Accepted — implemented in [#11](https://github.com/sanketsudake/chrome-cdp-cli/pull/11)
- **Priority:** P2
- **Area:** reading
- **Depends on:** —
Expand Down
2 changes: 1 addition & 1 deletion docs/rfc/0011-session-recording.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# RFC-0011: Session recording — `record` and GIF export

- **Status:** Draft
- **Status:** Accepted — implemented in [#14](https://github.com/sanketsudake/chrome-cdp-cli/pull/14), with follow-up fixes in [#18](https://github.com/sanketsudake/chrome-cdp-cli/pull/18)
- **Priority:** P2
- **Area:** capture
- **Depends on:** RFC-0008 (shares capture options), RFC-0002 (daemon-side buffering pattern)
Expand Down
2 changes: 1 addition & 1 deletion docs/rfc/0012-domain-allowlist.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# RFC-0012: Domain allow-list — bounding what the CLI may drive

- **Status:** Draft
- **Status:** Accepted — implemented in [#12](https://github.com/sanketsudake/chrome-cdp-cli/pull/12)
- **Priority:** P2 *(raise to P0 if RFC-0004 is scheduled — MCP should not ship without it)*
- **Area:** safety
- **Depends on:** —
Expand Down
10 changes: 5 additions & 5 deletions docs/rfc/0013-consent-prompt-lifecycle.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# RFC-0013: Surviving Chrome's consent prompt

- **Status:** Draft
- **Status:** Accepted — implemented in [#18](https://github.com/sanketsudake/chrome-cdp-cli/pull/18)
- **Priority:** P0
- **Area:** connection
- **Depends on:** the spawn serialisation in #17 (necessary, not sufficient)
- **Depends on:** the spawn serialisation, which shipped alongside this in [#18](https://github.com/sanketsudake/chrome-cdp-cli/pull/18) — necessary, not sufficient

## Summary

Expand All @@ -16,7 +16,7 @@ A user's Chrome froze with the consent dialog on screen and no button responding
It was reproduced deliberately afterwards, and the reproduction contradicted the first diagnosis.

The initial theory was **stacked prompts**: several `chrome-cdp` processes had started at once, each found no daemon, each spawned one, and each spawned daemon attached to Chrome and raised its own prompt.
That much is real, and #17 fixes it — eight concurrent callers produced eight daemons before the fix and one after.
That much is real, and the spawn serialisation fixes it — eight concurrent callers produced eight daemons before the fix and one after.

But the controlled reproduction showed a **single** prompt wedges Chrome just as thoroughly.
Serialising the spawn is necessary and not sufficient.
Expand Down Expand Up @@ -74,7 +74,7 @@ As a user whose browser is already wedged, I want to be told the actual remedy,

**US-5 — One prompt, not many.**
As a user running several commands at once, I want at most one consent request.
*Acceptance:* covered by #17 for concurrent spawns; this RFC keeps it true across the wait as well.
*Acceptance:* covered by the spawn serialisation for concurrent spawns; this RFC keeps it true across the wait as well.
Serialising the spawn only guarantees one prompt *at a time*: without more, each queued caller in turn cleared the previous verdict and raised its own, so eight commands became eight sequential prompts.
A `consent_pending` verdict is inherited by callers released within a few seconds of it, so a queue drains on one answer.

Expand Down Expand Up @@ -147,7 +147,7 @@ Chrome's debug port is a loopback port any local process can bind, and the budge
Given a listener answering `101` without a valid `Sec-WebSocket-Accept` for the key we sent, the endpoint is classified refused.

**VS-7 — Concurrency stays at one prompt.**
The guard from #17, restated here so this RFC's changes cannot regress it.
The spawn-serialisation guard, restated here so this RFC's changes cannot regress it.

## Test plan

Expand Down
37 changes: 24 additions & 13 deletions docs/rfc/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,15 @@ Design proposals for `chrome-cdp`, written before the code so the CLI surface, t
Each RFC is self-contained: motivation, user stories with acceptance criteria, the proposed command surface, the envelope shape, and a verification plan that maps to real tests.
An RFC is `Draft` until someone implements it; the implementing PR flips it to `Accepted` and links itself.

**All thirteen are now implemented and merged.**
They are kept as the design record — what was proposed, why, and what the verification plan was — not as a to-do list.
Where the implementation departed from the proposal, the RFC's own Open Questions section records the decision, and the PR records the reason.

## Why these, and why in this order

Written when none of it existed.
Kept in the present tense of the time, because the reasoning is the point: this is what the tool could not do, and why that ordering.

`chrome-cdp` is already strong where browser automation is usually weak: a stable JSON envelope, a stable exit-code contract, batched execution over one connection (`session`), settle-aware waiting (`wait --idle` / `--stable`), and element addressing that survives dynamic-id apps (`--by name` / `cell` / `label` / `in-row`).

The gaps are concentrated in three places:
Expand All @@ -24,23 +31,27 @@ The gaps are concentrated in three places:

The ordering below follows that: make the interaction surface complete, then make the browser observable, then make the tool easy to adopt and safe to hand to an agent.

RFC-0013 was not part of that plan.
It came out of a failure the work itself caused — several processes attaching at once, each raising Chrome's consent prompt, and the browser wedging with no button that responded.
The reproduction then contradicted the first diagnosis, which is why it is written up rather than just fixed.

## Index

| RFC | Title | Priority | Area | Status |
|-----|-------|----------|------|--------|
| [0001](0001-keyboard-key-verb.md) | Keyboard input: the `key` verb | P0 | input | Draft |
| [0002](0002-console-messages.md) | Console messages: the `console` verb | P0 | observability | Draft |
| [0003](0003-network-requests.md) | Network requests: the `net` verb | P0 | observability | Draft |
| [0004](0004-mcp-server-mode.md) | MCP server mode: `chrome-cdp mcp` | P0 | distribution | Draft |
| [0005](0005-pointer-verbs.md) | Pointer verbs: `hover`, `dblclick`, `rclick`, `drag` | P1 | input | Draft |
| [0006](0006-file-upload.md) | File upload: the `upload` verb | P1 | input | Draft |
| [0007](0007-tab-lifecycle.md) | Tab lifecycle: `close`, `activate`, history navigation | P1 | tabs | Draft |
| [0008](0008-screenshot-options.md) | Screenshot options: element, full-page, region, format | P1 | capture | Draft |
| [0009](0009-recipes.md) | Recipes: saved, shareable `session` scripts | P2 | workflow | Draft |
| [0010](0010-page-reading-ergonomics.md) | Page-reading ergonomics: `text --article`, `eval --await` | P2 | reading | Draft |
| [0011](0011-session-recording.md) | Session recording: `record` and GIF export | P2 | capture | Draft |
| [0012](0012-domain-allowlist.md) | Domain allow-list: bounding what the CLI may drive | P2 | safety | Draft |
| [0013](0013-consent-prompt-lifecycle.md) | Surviving Chrome's consent prompt | P0 | connection | Draft |
| [0001](0001-keyboard-key-verb.md) | Keyboard input: the `key` verb | P0 | input | Accepted — [#10](https://github.com/sanketsudake/chrome-cdp-cli/pull/10) |
| [0002](0002-console-messages.md) | Console messages: the `console` verb | P0 | observability | Accepted — [#13](https://github.com/sanketsudake/chrome-cdp-cli/pull/13) |
| [0003](0003-network-requests.md) | Network requests: the `net` verb | P0 | observability | Accepted — [#13](https://github.com/sanketsudake/chrome-cdp-cli/pull/13) |
| [0004](0004-mcp-server-mode.md) | MCP server mode: `chrome-cdp mcp` | P0 | distribution | Accepted — [#15](https://github.com/sanketsudake/chrome-cdp-cli/pull/15) |
| [0005](0005-pointer-verbs.md) | Pointer verbs: `hover`, `dblclick`, `rclick`, `drag` | P1 | input | Accepted — [#10](https://github.com/sanketsudake/chrome-cdp-cli/pull/10) |
| [0006](0006-file-upload.md) | File upload: the `upload` verb | P1 | input | Accepted — [#12](https://github.com/sanketsudake/chrome-cdp-cli/pull/12) |
| [0007](0007-tab-lifecycle.md) | Tab lifecycle: `close`, `activate`, history navigation | P1 | tabs | Accepted — [#10](https://github.com/sanketsudake/chrome-cdp-cli/pull/10) |
| [0008](0008-screenshot-options.md) | Screenshot options: element, full-page, region, format | P1 | capture | Accepted — [#11](https://github.com/sanketsudake/chrome-cdp-cli/pull/11) |
| [0009](0009-recipes.md) | Recipes: saved, shareable `session` scripts | P2 | workflow | Accepted — [#14](https://github.com/sanketsudake/chrome-cdp-cli/pull/14) |
| [0010](0010-page-reading-ergonomics.md) | Page-reading ergonomics: `text --article`, `eval --await` | P2 | reading | Accepted — [#11](https://github.com/sanketsudake/chrome-cdp-cli/pull/11) |
| [0011](0011-session-recording.md) | Session recording: `record` and GIF export | P2 | capture | Accepted — [#14](https://github.com/sanketsudake/chrome-cdp-cli/pull/14) |
| [0012](0012-domain-allowlist.md) | Domain allow-list: bounding what the CLI may drive | P2 | safety | Accepted — [#12](https://github.com/sanketsudake/chrome-cdp-cli/pull/12) |
| [0013](0013-consent-prompt-lifecycle.md) | Surviving Chrome's consent prompt | P0 | connection | Accepted — [#18](https://github.com/sanketsudake/chrome-cdp-cli/pull/18) |

## Dependency graph

Expand Down
Loading