Skip to content

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.md
new file mode 100644
index 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