High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
memory: document Chrome startup fixes and CLI design session
Mario402cd61e445e
diff --git a/memory/2026-03-01-pinchtab-fixes-and-cli-design.md b/memory/2026-03-01-pinchtab-fixes-and-cli-design.mdnew file mode 100644index 00000000..3301c871--- /dev/null+++ b/memory/2026-03-01-pinchtab-fixes-and-cli-design.md@@ -0,0 +1,136 @@+# PinchTab: Chrome Startup Fixes + CLI Design (2026-03-01)++## Summary+Fixed critical Chrome instance startup issues and designed comprehensive CLI command structure for scaling to complex nested resources with JSON payloads.++## Problems Fixed++### Problem 1: Chrome instances not starting (stuck in "starting" → error)+**Root cause:** Two-part issue:+1. `chromedp.Flag("headless", false)` doesn't work — can't set boolean flags this way+2. Health check failed because Chrome initialization was lazy, creating chicken-and-egg: monitor needs 200 from `/health` but `/health` fails until Chrome initializes, which doesn't happen without a request++**Fix 1:** `cmd/pinchtab/browser.go` (commit `51e3f17`)+- Removed broken `chromedp.Flag("headless", false)`+- Now: Don't add ANY headless flag in headed mode — Chrome defaults to headed when no flag present+- Headless mode: Add `chromedp.Headless` option+- Result: Exact 1-option difference between modes (25 vs 24 options)++**Fix 2:** `internal/handlers/health_tabs.go` (commit `d1d4122`)+- Made `/health` endpoint automatically call `ensureChrome()` before checking health+- Startup flow now: Request `/health` → Chrome initializes → Returns 200 → Monitor sees "running" ✅+- Tested: Both headless and headed modes now start correctly within ~8 seconds++## Testing+✅ All manual tests passed:+- Headless instance launch: Status transitions "starting" → "running"+- Headed instance launch: Status transitions "starting" → "running"+- Both instances initialize Chrome successfully+- Both respond to HTTP requests after becoming "running"++Added unit tests (commit `286f513`):+1. **Health endpoint tests** (`internal/handlers/health_tabs_test.go`)+ - `TestHandleHealth_EnsureChromeFailure` — /health returns 503 when init fails+ - `TestHandleHealth_EnsureChromeSuccess` — /health calls ensureChrome() before checks+ - MockBridge now tracks ensureChrome() calls and errors++2. **Chrome options tests** (`cmd/pinchtab/browser_test.go`)+ - `TestBuildChromeOpts_HeadlessMode` — chromedp.Headless is added+ - `TestBuildChromeOpts_HeadedMode` — NO headless flag added (Chrome defaults headed)+ - `TestBuildChromeOpts_ComparesOptions` — Headless has +1 option (the Headless flag)+ - `TestBuildChromeOpts_WithCustomBinary` — Custom binary handling works+ - Results: Headless 25 opts, Headed 24 opts ✅++## CLI Design++### Problem+Current CLI has mix of patterns:+- Single-level: `pinchtab nav https://...`+- Two-level: `pinchtab instance launch --mode headed`+- But no clear way to handle complex nested resources like `/instances/{id}/tab/{tabId}/navigate`+- And no consistent payload handling for JSON vs flags vs stdin++### Solution+Three comprehensive documents (31.6 KB total):++**1. cli-design.md** (10.8 KB)+- **Principles**: Hierarchical path mirroring, resource-oriented, consistent args+- **5 patterns**:+ 1. List resources: `pinchtab instances`+ 2. Manage resource: `pinchtab instance launch --mode headed`+ 3. Browser control (instance-scoped): `pinchtab --instance <id> snap`+ 4. Nested resources: `pinchtab --instance <id> tab <tabId> navigate <url>`+ 5. Complex payloads: Flags, stdin, file input+- **Mapping tables**: Endpoints → CLI commands+- **Examples**: Real workflows+- **Future extensibility**: REPL mode, bulk ops, streaming++**2. cli-implementation.md** (11.4 KB)+- **5 payload patterns** with Go code:+ 1. Flags → JSON body+ 2. Positional args → path params+ 3. Stdin JSON+ 4. File input (`-f`, `--json`)+ 5. Nested resources (tabs example)+- **Global flag handling**: `--instance` selection with fallback to env var+- **Error handling**: Exit codes (0=success, 1=user error, 2=server error, 4=not found)+- **Testing**: Unit and integration test examples++**3. cli-quick-reference.md** (9.4 KB)+- **Copy-paste examples** organized by feature:+ - Instance management (launch, logs, stop)+ - Browser control (navigate, snapshot, click, etc.)+ - Tab management (list, create, navigate, lock)+ - Complex actions (multi-step workflows)+- **Typical workflow** walkthrough (8 steps)+- **Scripting examples**: Batch, parallel, monitoring, cleanup+- **Troubleshooting section**+- **Common patterns**: Form fill, search, etc.++### Design Principles+1. **Hierarchical path mirroring** — CLI structure mirrors HTTP paths:+ - `/instances` → `pinchtab instances`+ - `/instances/launch` → `pinchtab instance launch`+ - `/instances/{id}/tab/{tabId}/navigate` → `pinchtab --instance <id> tab <tabId> navigate <url>`++2. **Resource-oriented** — Not verb-first, resource-first:+ - ✅ `pinchtab instance <action>`+ - ❌ `pinchtab start-instance`++3. **Consistent argument order** — `<resource> <id> <sub-resource> <sub-id> <action> [flags] [payload]`++4. **Smart payload handling**:+ - Simple: Use flags (`--port 9868`)+ - Complex: Use stdin (`cat payload.json | pinchtab ...`)+ - Inline: Use `--json` or `-f file.json`++5. **Backward compatible** — Existing commands unchanged++### Endpoint → CLI Mapping Examples+| Endpoint | CLI |+|----------|-----|+| `POST /instances/launch` | `pinchtab instance launch --mode headed --port 9869` |+| `GET /instances/{id}/logs` | `pinchtab instance <id> logs` |+| `POST /instances/{id}/navigate` | `pinchtab --instance <id> nav <url>` |+| `POST /instances/{id}/tab` | `pinchtab --instance <id> tab create <url>` |+| `POST /instances/{id}/tab/{tabId}/navigate` | `pinchtab --instance <id> tab <tabId> navigate <url>` |++## Commits on `feat/make-cli-useful`+1. `51e3f17` — Fix Chrome headless flag (omit in headed mode)+2. `d1d4122` — Make /health trigger Chrome init+3. `286f513` — Add comprehensive unit tests+4. `851ec1d` — Add CLI design + implementation + quick reference docs++## Impact+✅ **Startup fixed**: Instances go from "starting" → "running" reliably+✅ **Both modes work**: Headless and headed instances start correctly+✅ **Test coverage**: 6 new health tests, 4 new Chrome option tests+✅ **CLI roadmap**: Clear design for scaling to any endpoint complexity+✅ **Developer experience**: 31KB of examples and patterns++## Next Steps+1. Implement nested tab CLI commands using design patterns+2. Add `--instance` flag to all browser control commands+3. Add stdin/file payload support to action commands+4. Add shell completion (`_bash`, `_zsh`)+5. Update `pinchtab help` with new patterns