@questpie/probe 0.1.0

package/skills/qprobe/references/browser.md

@@ -0,0 +1,201 @@
+# Browser Control Reference
+
+Powered by `agent-browser` (default) or `playwright-cli` (optional). Uses accessibility tree snapshots with compact `@e` refs.
+
+## Navigation
+
+```bash
+qprobe browser open <url>         # navigate (absolute or relative to baseUrl)
+qprobe browser open /login        # relative
+qprobe browser back               # browser back
+qprobe browser forward            # browser forward
+qprobe browser reload             # reload current page
+qprobe browser url                # print current URL
+qprobe browser title              # print page title
+qprobe browser close              # close browser
+```
+
+## Snapshot — How the Agent Sees the Page
+
+```bash
+qprobe browser snapshot [flags]
+```
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--interactive` | `-i` | Only interactive elements (buttons, inputs, links) |
+| `--compact` | `-c` | Remove empty structural elements |
+| `--depth <n>` | `-d` | Limit tree depth |
+| `--selector <css>` | `-s` | Scope to CSS selector |
+| `--diff` | | Show only changes since last snapshot |
+
+### Output Example (-i -c)
+```
+- heading "Login" [@e1]
+- textbox "Email" [@e2]
+- textbox "Password" [@e3]
+- button "Sign In" [@e4]
+- link "Forgot password?" [@e5]
+```
+
+~200-400 tokens for a typical page. Each element gets a stable ref like `@e1`.
+
+### Diff Output (--diff)
+```
+URL: /login → /dashboard
+REMOVED: textbox "Email" [@e2]
+REMOVED: textbox "Password" [@e3]
+REMOVED: button "Sign In" [@e4]
+ADDED:   heading "Dashboard" [@e6]
+ADDED:   button "Logout" [@e7]
+ADDED:   table (12 rows) [@e8]
+```
+
+**Use `-i` by default.** Full snapshots include decorative elements that waste tokens. Add `-c` for even more compression. Use `--diff` after actions to see only what changed.
+
+## Interaction
+
+All interaction commands accept `@e` refs (from snapshot) or CSS selectors.
+
+```bash
+qprobe browser click @e4                    # click
+qprobe browser dblclick @e4                 # double-click
+qprobe browser fill @e2 "admin@test.com"    # clear + fill
+qprobe browser type "hello"                 # type at current focus
+qprobe browser select @e3 "option-value"    # select dropdown
+qprobe browser check @e5                    # check checkbox
+qprobe browser uncheck @e5                  # uncheck
+qprobe browser press Enter                  # keyboard key
+qprobe browser press Tab
+qprobe browser press Control+a
+qprobe browser hover @e1                    # hover
+qprobe browser scroll down 500              # scroll pixels
+qprobe browser scroll up
+qprobe browser focus @e2                    # focus element
+qprobe browser upload @e6 ./file.pdf        # file upload
+```
+
+## Console & Errors
+
+```bash
+qprobe browser console                      # all console messages
+qprobe browser console --level error         # only errors
+qprobe browser console --level warn          # warnings and above
+qprobe browser console --clear               # clear buffer
+qprobe browser console --json                # machine-readable
+
+qprobe browser errors                        # uncaught JS exceptions only
+qprobe browser errors --clear
+```
+
+Output:
+```
+[error] TypeError: Cannot read property 'map' of undefined
+    at UserList (src/components/UserList.tsx:23:15)
+[warn]  Each child in a list should have a unique "key" prop
+[log]   API response: 200 OK
+```
+
+## Network
+
+```bash
+qprobe browser network                       # all HTTP requests
+qprobe browser network --failed              # only 4xx/5xx
+qprobe browser network --method POST         # filter by method
+qprobe browser network --grep "api/"         # filter by URL pattern
+qprobe browser network --json                # machine-readable
+```
+
+Output:
+```
+200 GET  /api/health         12ms
+200 GET  /api/users          89ms
+201 POST /api/users          123ms
+500 POST /api/orders         234ms  ← FAILED
+404 GET  /api/nonexistent    8ms    ← FAILED
+```
+
+## Screenshots
+
+```bash
+qprobe browser screenshot                    # save to tmp/qprobe/shots/
+qprobe browser screenshot ./my-shot.png      # custom path
+qprobe browser screenshot --annotate         # overlay @e ref labels
+qprobe browser screenshot --full             # full page scroll capture
+qprobe browser screenshot --selector "#main" # capture specific element
+```
+
+Annotated screenshots overlay numbered labels `[1] @e1`, `[2] @e2` on interactive elements — useful for multimodal AI models that can reason about visual layout.
+
+## Waiting
+
+```bash
+qprobe browser wait @e1                      # wait for element to exist
+qprobe browser wait "#loading" --hidden      # wait for element to disappear
+qprobe browser wait --url "/dashboard"       # wait for URL change
+qprobe browser wait --text "Welcome"         # wait for text to appear
+qprobe browser wait --network idle           # wait for no pending requests
+qprobe browser wait --timeout 10s            # custom timeout (default 30s)
+```
+
+## JavaScript Execution
+
+```bash
+qprobe browser eval "document.title"
+# "My App - Dashboard"
+
+qprobe browser eval "document.querySelectorAll('tr').length"
+# 12
+
+qprobe browser eval "localStorage.getItem('token')"
+# "eyJhbG..."
+
+qprobe browser text                          # extract all text content
+qprobe browser text "#main"                  # text from specific element
+```
+
+## Common Patterns
+
+### Login Flow
+```bash
+qprobe browser open /login
+qprobe browser snapshot -i
+qprobe browser fill @e1 "admin@test.com"
+qprobe browser fill @e2 "password"
+qprobe browser click @e3
+qprobe browser wait --url "/dashboard"
+qprobe browser snapshot --diff
+```
+
+### Check for Errors After Action
+```bash
+qprobe browser click @e5                    # submit form
+qprobe browser wait --network idle
+qprobe browser console --level error         # any JS errors?
+qprobe browser network --failed              # any failed requests?
+qprobe browser snapshot --diff               # what changed?
+```
+
+### Debug Why Page Looks Wrong
+```bash
+qprobe browser screenshot --annotate         # see the visual state
+qprobe browser console --level error         # JS errors?
+qprobe browser network --failed              # failed API calls?
+qprobe browser eval "document.querySelector('.error')?.textContent"
+```
+
+## Driver Selection
+
+```bash
+# Default: agent-browser (token-efficient, Rust CLI, persistent daemon)
+qprobe browser open /login
+
+# Playwright: cross-browser, network interception, test codegen
+qprobe browser open /login --driver playwright
+qprobe browser open /login --driver playwright --browser firefox
+```
+
+Set default in `qprobe.config.ts`:
+```typescript
+browser: { driver: 'agent-browser' }  // or 'playwright'
+```

package/skills/qprobe/references/compose.md

@@ -0,0 +1,128 @@
+# Compose Reference
+
+## Commands
+
+```bash
+qprobe compose up [flags]     # start all services in dependency order
+qprobe compose down           # stop all in reverse order
+qprobe compose restart [name] # restart one or all
+qprobe compose status         # show all service states
+```
+
+| Flag | Description |
+|------|-------------|
+| `--only <name,...>` | Start only these services (+ their dependencies) |
+| `--skip <name,...>` | Skip these services |
+| `--no-health` | Don't wait for health checks |
+| `--config <path>` | Custom config file path |
+
+## Config File
+
+`qprobe.config.ts` in project root:
+
+```typescript
+import { defineConfig } from '@questpie/probe'
+
+export default defineConfig({
+  services: {
+    db: {
+      cmd: 'docker compose up postgres',
+      ready: 'ready to accept connections',
+      health: 'http://localhost:5432',
+      stop: 'docker compose down postgres',  // custom stop command
+    },
+    server: {
+      cmd: 'bun dev',
+      ready: 'ready on http://localhost:3000',
+      port: 3000,
+      health: '/api/health',    // relative to http://localhost:<port>
+      depends: ['db'],
+      env: {
+        DATABASE_URL: 'postgresql://postgres:postgres@localhost:5432/dev',
+      },
+    },
+    admin: {
+      cmd: 'bun run admin:dev',
+      ready: 'ready on http://localhost:3001',
+      port: 3001,
+      depends: ['server'],
+    },
+    worker: {
+      cmd: 'bun run jobs',
+      ready: 'worker started',
+      depends: ['db'],
+    },
+  },
+  browser: {
+    driver: 'agent-browser',
+    baseUrl: 'http://localhost:3000',
+  },
+  http: {
+    baseUrl: 'http://localhost:3000',
+  },
+})
+```
+
+## Dependency Resolution
+
+`qprobe compose up` resolves the dependency graph and starts in order:
+
+```
+Given: server depends on db, admin depends on server, worker depends on db
+
+Start order:
+1. db (no dependencies)
+2. server + worker (both depend on db, start in parallel)
+3. admin (depends on server)
+
+Stop order (reverse):
+1. admin
+2. server + worker
+3. db
+```
+
+## Examples
+
+```bash
+# Start everything
+qprobe compose up
+# ⏳ Starting db... ready (2.3s)
+# ⏳ Starting server... ready (4.1s)
+# ⏳ Starting worker... ready (1.2s)
+# ⏳ Starting admin... ready (3.5s)
+# ✅ All 4 services ready (11.1s)
+
+# Start only server (auto-starts db dependency)
+qprobe compose up --only server
+# ⏳ Starting db... ready (2.3s)
+# ⏳ Starting server... ready (4.1s)
+# ✅ 2 services ready (6.4s)
+
+# Skip admin
+qprobe compose up --skip admin
+
+# Stop everything
+qprobe compose down
+# ⏳ Stopping admin... stopped
+# ⏳ Stopping server... stopped
+# ⏳ Stopping worker... stopped
+# ⏳ Stopping db... stopped
+# ✅ All services stopped
+
+# Restart just the server
+qprobe compose restart server
+
+# Check status
+qprobe compose status
+```
+
+## Inline Compose (No Config File)
+
+```bash
+qprobe compose up \
+  --service "db: docker compose up postgres | ready to accept" \
+  --service "server: bun dev | ready on http://localhost:3000" \
+  --depends "server:db"
+```
+
+Format: `--service "name: command | ready-pattern"`

package/skills/qprobe/references/http.md

@@ -0,0 +1,151 @@
+# HTTP Requests Reference
+
+## Basic Usage
+
+```bash
+qprobe http <METHOD> <path> [flags]
+```
+
+Path is relative to baseUrl (from config, `--base`, or auto-detected from running services).
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--base <url>` | | Override base URL |
+| `--data <json>` | `-d` | Request body (JSON string) |
+| `--header <k:v>` | `-H` | Header (repeatable) |
+| `--token <jwt>` | | Bearer token shortcut |
+| `--status <code>` | | Assert expected status (exit 1 if different) |
+| `--jq <expr>` | | JQ-style filter on response body |
+| `--raw` | | Raw output (no pretty-print, no status line) |
+| `--timing` | | Show request timing breakdown |
+| `--verbose` | `-v` | Show full request + response headers |
+| `--form` | | Send as form-urlencoded instead of JSON |
+| `--file <path>` | | Upload file as multipart |
+
+## BaseUrl Resolution
+
+Order of precedence:
+1. `--base` flag
+2. `QPROBE_BASE_URL` env variable
+3. `http.baseUrl` in `qprobe.config.ts`
+4. `browser.baseUrl` in config
+5. First running service with a port → `http://localhost:<port>`
+6. `http://localhost:3000` (fallback)
+
+## Examples
+
+### GET
+```bash
+qprobe http GET /api/users
+# 200 OK (45ms)
+# [
+#   { "id": 1, "name": "Admin", "email": "admin@test.com" },
+#   { "id": 2, "name": "User", "email": "user@test.com" }
+# ]
+```
+
+### POST with Body
+```bash
+qprobe http POST /api/users -d '{"name":"New User","email":"new@test.com"}'
+# 201 Created (123ms)
+# { "id": 3, "name": "New User", "email": "new@test.com" }
+```
+
+### Auth
+```bash
+# Bearer token
+qprobe http GET /api/admin/stats --token "eyJhbGci..."
+
+# Custom header
+qprobe http GET /api/data -H "X-API-Key: abc123"
+
+# Cookie
+qprobe http GET /api/me -H "Cookie: session=abc123"
+```
+
+### Assert Status
+```bash
+qprobe http GET /api/health --status 200
+# ✅ 200 OK (12ms)
+
+qprobe http DELETE /api/users/1 --status 204
+# ✅ 204 No Content (89ms)
+
+qprobe http GET /api/nonexistent --status 404
+# ✅ 404 Not Found (8ms)
+
+qprobe http GET /api/broken --status 200
+# ❌ Expected 200, got 500 Internal Server Error (234ms)
+# { "error": "Database connection failed" }
+# Exit code: 1
+```
+
+### JQ Filter
+```bash
+qprobe http GET /api/users --jq ".[0].name"
+# "Admin"
+
+qprobe http GET /api/users --jq "length"
+# 5
+
+qprobe http GET /api/stats --jq ".revenue.total"
+# 125000
+```
+
+### Verbose
+```bash
+qprobe http POST /api/login -d '{"email":"a@b.com","password":"123"}' -v
+# → POST http://localhost:3000/api/login
+# → Content-Type: application/json
+# → Body: {"email":"a@b.com","password":"123"}
+# ← 200 OK (89ms)
+# ← Set-Cookie: session=abc123; HttpOnly; Path=/
+# ← Content-Type: application/json
+# { "token": "eyJ...", "user": { "id": 1, "name": "Admin" } }
+```
+
+### File Upload
+```bash
+qprobe http POST /api/upload --file ./avatar.png -H "Authorization: Bearer eyJ..."
+```
+
+### Raw Output (for piping)
+```bash
+# Pipe JSON to jq
+qprobe http GET /api/users --raw | jq '.[].email'
+
+# Save response to file
+qprobe http GET /api/export --raw > export.json
+```
+
+## Common Patterns
+
+### Login → Use Token
+```bash
+# Login and extract token
+TOKEN=$(qprobe http POST /api/login -d '{"email":"admin@test.com","password":"pass"}' --raw | jq -r '.token')
+
+# Use token in subsequent requests
+qprobe http GET /api/admin/users --token "$TOKEN"
+```
+
+### Test CRUD Sequence
+```bash
+# Create
+qprobe http POST /api/users -d '{"name":"Test"}' --status 201
+# Read
+qprobe http GET /api/users/3 --status 200
+# Update
+qprobe http PUT /api/users/3 -d '{"name":"Updated"}' --status 200
+# Delete
+qprobe http DELETE /api/users/3 --status 204
+# Verify deleted
+qprobe http GET /api/users/3 --status 404
+```
+
+### Health Check with Retry
+```bash
+# Wait for server, then test
+qprobe health http://localhost:3000/api/health
+qprobe http GET /api/users --status 200
+```

package/skills/qprobe/references/process.md

@@ -0,0 +1,114 @@
+# Process Management Reference
+
+## Start a Process
+
+```bash
+qprobe start <name> "<command>" [flags]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--ready "<pattern>"` | — | String/regex in stdout that signals ready |
+| `--timeout <dur>` | `60s` | Max wait for ready pattern |
+| `--port <n>` | — | Port for health checks and baseUrl |
+| `--env KEY=VAL` | — | Environment variables (repeatable) |
+| `--cwd <path>` | `.` | Working directory |
+
+### Examples
+
+```bash
+# Database
+qprobe start db "docker compose up postgres" --ready "ready to accept" --timeout 30s
+
+# Dev server
+qprobe start server "bun dev" --ready "ready on" --port 3000
+
+# Worker with env
+qprobe start worker "bun run jobs" --ready "worker started" --env QUEUE=default
+
+# No ready pattern — just start and return immediately
+qprobe start redis "redis-server"
+```
+
+### What Happens
+
+1. Spawns child process (detached, survives between CLI calls)
+2. Pipes stdout/stderr → `tmp/qprobe/logs/<name>.log` (timestamped)
+3. Monitors stdout for `--ready` pattern
+4. Returns when ready OR exits with code 2 on timeout
+5. Saves PID to `tmp/qprobe/pids/<name>.pid`
+6. Saves config to `tmp/qprobe/state/<name>.json` (for restart)
+
+## Stop
+
+```bash
+qprobe stop <name>      # stop one service
+qprobe stop --all        # stop everything
+```
+
+Sends SIGTERM → waits 5s → SIGKILL if still alive.
+
+## Restart
+
+```bash
+qprobe restart <name>    # stop + start with original config
+```
+
+## Process Status
+
+```bash
+qprobe ps                # table view
+qprobe ps --json         # machine-readable
+```
+
+Output:
+```
+NAME     PID    PORT   STATUS   UPTIME    MEM
+db       12345  5432   ready    5m 23s    128MB
+server   12346  3000   ready    5m 20s    256MB
+```
+
+## Health Check
+
+```bash
+qprobe health <url> [flags]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--interval <dur>` | `1s` | Polling interval |
+| `--timeout <dur>` | `30s` | Max total wait |
+| `--status <code>` | `200` | Expected HTTP status |
+
+```bash
+qprobe health http://localhost:3000/api/health
+# ✅ Responding (200 OK, 45ms) after 3.2s
+
+qprobe health http://localhost:5432 --timeout 60s
+# ✅ Responding after 8.1s
+```
+
+## Common Patterns
+
+### Start server, wait, then test
+```bash
+qprobe start server "bun dev" --ready "ready on" --port 3000
+qprobe health http://localhost:3000/api/health
+qprobe http GET /api/users
+```
+
+### Restart after code change
+```bash
+qprobe restart server
+qprobe health http://localhost:3000/api/health
+qprobe check
+```
+
+### Check if something crashed
+```bash
+qprobe ps
+# If server shows "stopped" or is missing:
+qprobe logs server --lines 50
+# Look for the crash reason, then:
+qprobe restart server
+```