commit 1dac5c15f114eb763e06f61b8660974100618cf2 Author: Rogee Date: Thu Aug 20 20:59:50 2026 +0800 Initialize Lume Ctrl repository diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..19ec799 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,31 @@ +# Repository Guidelines + +## Scope + +- Build a CDP-only network observability and debugging control plane for clark-browser/Chromium. +- Collect and correlate CDP `Network`/`Fetch` HTTP(S), failure, cache, and WebSocket events. +- Keep the MVP read-only. Any future request or response mutation must be explicit opt-in and default off. +- Prefer the smallest correct change and reuse existing patterns before adding dependencies or abstractions. + +## Non-goals + +- Do not add VNC/noVNC, desktop streaming, or GUI browser control. +- Do not add MITM, proxy certificates, CA injection, TLS interception, packet capture, or `SSLKEYLOGFILE` flows. +- Do not add proxy pools, IP rotation, fingerprint generation, account operations, DOM scraping, or media decoding. + +## Security and reliability + +- Never commit or log CDP tokens, cookies, `Authorization`, `Set-Cookie`, credentials, full sensitive bodies, or production data. +- Use short-lived CDP credentials over a protected internal or TLS connection, with session isolation and auditable access. +- Redact sensitive headers and bodies before persistence or export; enforce body, event, frame, and retention limits. +- Treat response bodies as optional: cache, target closure, protocol behavior, or lifecycle timing may make them unavailable. +- Report disconnects, target closure, dropped events, and body-read failures without stopping the browser workload. +- Validate all external input and preserve compatibility of persisted schemas and exported data. + +## Development and tests + +- Keep commits focused; do not add speculative scaffolding, dependencies, CI, or an unconfirmed application stack. +- Use local fixtures only. Never use production credentials, send real external messages, deploy, publish, or perform destructive data operations. +- Add the smallest relevant test for non-trivial behavior. +- Cover request-to-response completion/failure correlation, WebSocket frames, redaction, truncation, session isolation, pagination, disconnect recovery, and unavailable response bodies where applicable. +- Run relevant tests and formatting checks before pushing. diff --git a/README.md b/README.md new file mode 100644 index 0000000..061e8b5 --- /dev/null +++ b/README.md @@ -0,0 +1,7 @@ +# Lume Ctrl + +Lume Ctrl is a CDP-only network observability and debugging control plane for clark-browser/Chromium automation instances. + +It observes browser-internal HTTP(S), failure, cache, and WebSocket events without changing the TLS path. The MVP focuses on safe collection, correlation, redaction, bounded body handling, session-isolated query, and JSONL export. + +VNC/noVNC, GUI control, MITM, proxy certificates, CA injection, packet capture, proxy pools, fingerprinting, account operations, DOM scraping, and media decoding are out of scope.