@questpie/probe 0.1.0

package/skills/qprobe/references/recording.md

@@ -0,0 +1,194 @@
+# Recording & Replay Reference
+
+Record browser interactions → generate Playwright tests → replay without AI tokens.
+
+## Recording
+
+```bash
+qprobe record start "<n>"        # begin recording
+# ... perform browser and http actions ...
+qprobe record stop                  # save + generate Playwright test
+qprobe record cancel                # discard without saving
+```
+
+During recording, ALL `qprobe browser` and `qprobe http` commands are automatically captured. Each step records:
+
+- Action type (navigate, click, fill, etc.)
+- `@e` ref (short-term, for current session)
+- CSS selector (long-term, resolved from ref, for Playwright replay)
+- Values, URLs, expected states
+- Before/after snapshots (optional)
+
+### Example Recording Session
+
+```bash
+qprobe record start "create-user"
+
+qprobe browser open /admin/users
+qprobe browser snapshot -i
+# - link "Add User" [@e3]
+# - table (5 rows) [@e4]
+
+qprobe browser click @e3
+qprobe browser wait --url "/admin/users/new"
+qprobe browser snapshot -i
+# - textbox "Name" [@e5]
+# - textbox "Email" [@e6]
+# - select "Role" [@e7]
+# - button "Save" [@e8]
+
+qprobe browser fill @e5 "Test User"
+qprobe browser fill @e6 "test@example.com"
+qprobe browser select @e7 "editor"
+qprobe browser click @e8
+qprobe browser wait --url "/admin/users"
+qprobe browser wait --text "Test User"
+qprobe assert text "Test User"
+qprobe assert no-errors
+
+qprobe record stop
+# ✅ Recording saved: tests/qprobe/recordings/create-user.json (8 steps)
+# ✅ Playwright test: tests/qprobe/recordings/create-user.spec.ts
+```
+
+### Generated Playwright Test
+
+```typescript
+// tests/qprobe/recordings/create-user.spec.ts
+import { test, expect } from '@playwright/test'
+
+test('create-user', async ({ page }) => {
+  await page.goto('/admin/users')
+  await page.locator('a:has-text("Add User")').click()
+  await page.waitForURL('**/admin/users/new')
+  await page.locator('input[name="name"]').fill('Test User')
+  await page.locator('input[name="email"]').fill('test@example.com')
+  await page.locator('select[name="role"]').selectOption('editor')
+  await page.locator('button:has-text("Save")').click()
+  await page.waitForURL('**/admin/users')
+  await expect(page.locator('body')).toContainText('Test User')
+})
+```
+
+This test runs with **pure Playwright** — no AI, no LLM calls, no tokens.
+
+## Replay
+
+```bash
+qprobe replay "<n>"              # run single recording
+qprobe replay --all                 # run all recordings
+```
+
+| Flag | Description |
+|------|-------------|
+| `--headed` | Show visible browser |
+| `--browser <name>` | `chromium`, `firefox`, `webkit` |
+| `--parallel` | Run tests in parallel |
+| `--report` | Generate HTML report |
+| `--base <url>` | Override baseUrl |
+| `--retries <n>` | Retry count for flaky tests |
+| `--grep "<pattern>"` | Filter tests by name |
+
+### Examples
+
+```bash
+# Run single test
+qprobe replay "create-user"
+# ✅ create-user passed (2.1s)
+
+# Run all with visible browser
+qprobe replay --all --headed
+
+# Cross-browser
+qprobe replay --all --browser firefox
+
+# CI mode with report
+qprobe replay --all --report --retries 2
+# ✅ 5/5 tests passed
+# 📄 Report: tests/qprobe/report/index.html
+
+# Against staging
+qprobe replay --all --base https://staging.myapp.com
+```
+
+## Managing Recordings
+
+```bash
+qprobe recordings list                  # list all recordings
+# NAME           STEPS  CREATED
+# login-flow     5      2026-03-24
+# create-user    8      2026-03-24
+# delete-user    4      2026-03-25
+
+qprobe recordings show "create-user"    # show steps
+# 1. navigate → /admin/users
+# 2. click → a:has-text("Add User")
+# 3. waitForUrl → /admin/users/new
+# 4. fill → input[name="name"] = "Test User"
+# 5. fill → input[name="email"] = "test@example.com"
+# 6. select → select[name="role"] = "editor"
+# 7. click → button:has-text("Save")
+# 8. assert → body contains "Test User"
+
+qprobe recordings delete "old-test"     # delete recording + spec
+
+qprobe recordings export "create-user"  # export as standalone Playwright project
+# Exports to: tests/qprobe/export/create-user/
+# Includes: package.json, playwright.config.ts, test file
+# Run with: cd tests/qprobe/export/create-user && npm test
+```
+
+## Recording Format
+
+`tests/qprobe/recordings/create-user.json`:
+
+```json
+{
+  "name": "create-user",
+  "created": "2026-03-24T14:30:00Z",
+  "baseUrl": "http://localhost:3000",
+  "steps": [
+    {
+      "action": "navigate",
+      "url": "/admin/users",
+      "timestamp": "2026-03-24T14:30:01Z"
+    },
+    {
+      "action": "click",
+      "ref": "@e3",
+      "selector": "a:has-text(\"Add User\")",
+      "timestamp": "2026-03-24T14:30:03Z"
+    },
+    {
+      "action": "fill",
+      "ref": "@e5",
+      "selector": "input[name=\"name\"]",
+      "value": "Test User"
+    }
+  ]
+}
+```
+
+Key insight: `ref` is for the agent's current session. `selector` is the resolved CSS selector for Playwright. Both are captured during recording so the test works independently.
+
+## File Structure
+
+```
+tests/qprobe/
+├── recordings/
+│   ├── login-flow.json
+│   ├── login-flow.spec.ts
+│   ├── create-user.json
+│   └── create-user.spec.ts
+├── snapshots/                  # optional a11y snapshots
+└── playwright.config.ts        # auto-generated
+```
+
+## Tips
+
+- **Record important flows early** — login, CRUD, critical paths
+- **Replay is free** — zero AI tokens, runs in <5s per test
+- **Run `qprobe replay --all` after every code change** for instant regression
+- **Export recordings** to share with team or run in CI
+- **Edit generated .spec.ts** files to add custom assertions
+- **Use `--retries 2`** for network-dependent tests that may be flaky

package/skills/qprobe-browser/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: qprobe-browser
+description: "QUESTPIE Probe browser control. Accessibility tree snapshots with @e refs, click, fill, screenshot, console logs, network monitoring, JS errors, snapshot diffs. Powered by agent-browser. Use when: testing web UI, checking browser console, inspecting network requests, taking screenshots, filling forms, clicking buttons, checking for JS errors. Triggers: 'open the browser', 'check the page', 'click the button', 'fill the form', 'any console errors', 'network tab', 'screenshot', 'what does the page look like'. Use even for 'check if the UI works' or 'test the frontend'."
+---
+
+# qprobe — Browser Control
+
+Token-efficient browser automation via accessibility tree snapshots and `@e` refs.
+
+**Install:** `npm install -g @questpie/probe`
+
+## Core Workflow
+
+```bash
+qprobe browser open http://localhost:3000/login
+qprobe browser snapshot -i            # interactive elements only (~200 tokens)
+# - textbox "Email" [@e1]
+# - textbox "Password" [@e2]
+# - button "Sign In" [@e3]
+
+qprobe browser fill @e1 "admin@test.com"
+qprobe browser fill @e2 "password123"
+qprobe browser click @e3
+qprobe browser wait --url "/dashboard"
+qprobe browser snapshot --diff         # only what changed
+```
+
+## Snapshot Flags
+
+| Flag | Short | Effect |
+|------|-------|--------|
+| `--interactive` | `-i` | Only buttons, inputs, links (recommended) |
+| `--compact` | `-c` | Remove empty structural elements |
+| `--depth <n>` | `-d` | Limit tree depth |
+| `--selector <css>` | `-s` | Scope to element |
+| `--diff` | | Show changes since last snapshot |
+
+**Always use `-i` by default.** Full snapshots waste tokens on decorative elements.
+
+## Interaction (via @e refs or CSS selectors)
+
+```bash
+qprobe browser click @e3
+qprobe browser fill @e1 "text"
+qprobe browser select @e4 "value"
+qprobe browser check @e5
+qprobe browser press Enter
+qprobe browser type "hello"
+qprobe browser hover @e2
+qprobe browser scroll down 500
+```
+
+## Inspection (NO BROWSER WINDOW NEEDED)
+
+```bash
+qprobe browser console                # console messages (log, warn, error)
+qprobe browser console --level error  # only errors
+qprobe browser errors                 # uncaught JS exceptions
+qprobe browser network                # HTTP request log
+qprobe browser network --failed       # only 4xx/5xx
+qprobe browser eval "document.title"  # execute JS
+qprobe browser text "#main"           # extract text content
+```
+
+## Screenshots
+
+```bash
+qprobe browser screenshot             # basic
+qprobe browser screenshot --annotate  # with @e labels overlaid
+qprobe browser screenshot --full      # full page scroll
+```
+
+## Waiting
+
+```bash
+qprobe browser wait @e1               # element exists
+qprobe browser wait --url "/dashboard" # URL changed
+qprobe browser wait --text "Welcome"   # text appeared
+qprobe browser wait --network idle     # no pending requests
+```
+
+## Tips for Agents
+
+- `snapshot -i` saves tokens — use it always
+- `snapshot --diff` after actions — see only changes
+- Check `console --level error` and `network --failed` before visual debugging
+- `screenshot --annotate` is useful when you need visual context

package/skills/qprobe-compose/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: qprobe-compose
+description: "QUESTPIE Probe compose — multi-service orchestration with dependency graphs. Start DB, server, admin, workers in correct order with health checks. Config via qprobe.config.ts. Use when: starting a full dev stack, managing multiple services, need database + server + frontend running together. Triggers: 'start everything', 'compose up', 'start the stack', 'bring up the dev environment', 'start db and server'. Use when project has multiple services that need to start in order."
+---
+
+# qprobe — Compose
+
+Multi-service orchestration with dependency resolution and health checks.
+
+**Install:** `npm install -g @questpie/probe`
+
+## Usage
+
+```bash
+qprobe compose up          # start all services in dependency order
+qprobe compose down        # stop all in reverse order
+qprobe compose restart     # restart all
+qprobe compose status      # show service states
+```
+
+## Config (`qprobe.config.ts`)
+
+```typescript
+import { defineConfig } from '@questpie/probe'
+
+export default defineConfig({
+  services: {
+    db: {
+      cmd: 'docker compose up postgres',
+      ready: 'ready to accept connections',
+    },
+    server: {
+      cmd: 'bun dev',
+      ready: 'ready on http://localhost:3000',
+      port: 3000,
+      health: '/api/health',
+      depends: ['db'],
+    },
+    admin: {
+      cmd: 'bun run admin:dev',
+      ready: 'ready on http://localhost:3001',
+      port: 3001,
+      depends: ['server'],
+    },
+  },
+})
+```
+
+## What Happens
+
+```bash
+qprobe compose up
+# ⏳ Starting db... ready (2.3s)
+# ⏳ Starting server... ready (4.1s)    ← waited for db first
+# ⏳ Starting admin... ready (3.5s)     ← waited for server first
+# ✅ All 3 services ready (9.9s)
+```
+
+Dependency graph resolved automatically. Parallel start where possible.
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--only <names>` | Start only these (+ dependencies) |
+| `--skip <names>` | Skip these services |
+| `--no-health` | Don't wait for health checks |
+
+```bash
+qprobe compose up --only server     # starts db (dep) + server
+qprobe compose up --skip admin      # starts db + server, skips admin
+```
+
+## Inline (No Config File)
+
+```bash
+qprobe compose up \
+  --service "db: docker compose up postgres | ready to accept" \
+  --service "server: bun dev | ready on" \
+  --depends "server:db"
+```

package/skills/qprobe-http/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: qprobe-http
+description: "QUESTPIE Probe HTTP requests. Send API requests against running dev servers with auto baseUrl, Bearer auth, status assertions, JQ filtering, verbose mode. Cheaper than browser for API testing. Use when: testing API endpoints, checking server responses, CRUD operations, verifying auth, debugging 500 errors. Triggers: 'call the API', 'test the endpoint', 'POST to /api/users', 'check if the API works', 'what does the server return', 'send a request'. Prefer this over browser for any API-only testing."
+---
+
+# qprobe — HTTP Requests
+
+API testing with auto-resolved baseUrl. Cheaper than browser for backend testing.
+
+**Install:** `npm install -g @questpie/probe`
+
+## Usage
+
+```bash
+qprobe http <METHOD> <path> [flags]
+```
+
+Path is relative — baseUrl auto-resolved from config or running services.
+
+## Examples
+
+```bash
+# Basic
+qprobe http GET /api/users
+qprobe http GET /api/users/1
+
+# POST with body
+qprobe http POST /api/users -d '{"name":"New","email":"new@test.com"}'
+
+# Auth
+qprobe http GET /api/admin/stats --token "eyJhbGci..."
+qprobe http GET /api/data -H "X-API-Key: abc123"
+
+# Assert status (exit 1 if different)
+qprobe http GET /api/health --status 200
+qprobe http DELETE /api/users/1 --status 204
+
+# Filter response
+qprobe http GET /api/users --jq ".[0].name"
+qprobe http GET /api/stats --jq ".revenue.total"
+
+# Verbose (show headers)
+qprobe http POST /api/login -d '{"email":"a@b.com","pass":"123"}' -v
+
+# Raw output (for piping)
+qprobe http GET /api/users --raw | jq '.[].email'
+```
+
+## Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--data <json>` | `-d` | JSON request body |
+| `--header <k:v>` | `-H` | Header (repeatable) |
+| `--token <jwt>` | | Bearer auth shortcut |
+| `--status <code>` | | Assert expected status |
+| `--jq <expr>` | | JQ filter on response |
+| `--raw` | | No formatting (for pipes) |
+| `--verbose` | `-v` | Full request/response headers |
+| `--base <url>` | | Override baseUrl |
+
+## Tips
+
+- **Use `qprobe http` instead of browser** for API testing — much cheaper on tokens
+- **`--status` for assertions** — `qprobe http GET /api/health --status 200`
+- **`--jq` for extraction** — `qprobe http GET /api/me --jq ".user.role"`
+- **Chain with login** — extract token, use in subsequent requests

package/skills/qprobe-process/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: qprobe-process
+description: "QUESTPIE Probe process management. Start dev servers with ready-pattern detection, stop, restart, health checks, list running processes. Use when: starting a dev server, checking if server is running, waiting for service to be ready, restarting after code change. Triggers: 'start the server', 'bun dev', 'is it running', 'restart', 'health check', 'wait for ready', 'server crashed'. Use even when user just says 'run it' or 'start it up' in context of a dev project."
+---
+
+# qprobe — Process Management
+
+Start dev servers with ready-pattern detection, health checks, and lifecycle management.
+
+**Install:** `npm install -g @questpie/probe`
+
+## Commands
+
+```bash
+# Start with ready detection
+qprobe start <n> "<cmd>" --ready "<pattern>" [--port <n>] [--timeout 60s]
+
+# Examples
+qprobe start server "bun dev" --ready "ready on" --port 3000
+qprobe start db "docker compose up postgres" --ready "ready to accept"
+
+# Lifecycle
+qprobe stop <n|--all>
+qprobe restart <n>
+qprobe ps                    # list running processes
+qprobe ps --json             # machine-readable
+
+# Health check — poll URL until 200
+qprobe health http://localhost:3000/api/health --timeout 30s
+
+# Read logs
+qprobe logs <n>              # last 50 lines
+qprobe logs <n> --follow     # tail -f
+qprobe logs <n> --grep "ERROR"
+qprobe logs --all            # all processes merged
+```
+
+## How It Works
+
+- Spawns child process as daemon (survives between CLI calls)
+- Pipes stdout/stderr to `tmp/qprobe/logs/<n>.log` (timestamped)
+- Monitors output for `--ready` pattern, returns when matched
+- PID saved to `tmp/qprobe/pids/<n>.pid`
+- `qprobe stop` sends SIGTERM → SIGKILL after 5s
+
+## Common Patterns
+
+```bash
+# Start, wait, test
+qprobe start server "bun dev" --ready "ready on" --port 3000
+qprobe health http://localhost:3000/api/health
+qprobe http GET /api/users
+
+# Check what crashed
+qprobe ps
+qprobe logs server --lines 100 --grep "ERROR"
+qprobe restart server
+```

package/skills/qprobe-recording/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: qprobe-recording
+description: "QUESTPIE Probe test recording and replay. Record browser interactions, auto-generate Playwright tests, replay without AI tokens for regression testing. Use when: recording a test flow, creating regression tests, replaying tests, running test suite, checking for regressions after code changes. Triggers: 'record a test', 'save this as a test', 'replay tests', 'run regression', 'check if it still works', 'run all tests'. Use whenever user wants to capture a flow for future verification."
+---
+
+# qprobe — Recording & Replay
+
+Record browser flows → generate Playwright tests → replay with zero AI tokens.
+
+**Install:** `npm install -g @questpie/probe`
+
+## Record
+
+```bash
+qprobe record start "login-flow"
+# ... do browser actions (they're automatically captured) ...
+qprobe browser open /login
+qprobe browser fill @e1 "admin@test.com"
+qprobe browser fill @e2 "password123"
+qprobe browser click @e3
+qprobe browser wait --url "/dashboard"
+qprobe assert text "Dashboard"
+qprobe record stop
+# ✅ Recording saved: tests/qprobe/recordings/login-flow.json
+# ✅ Playwright test: tests/qprobe/recordings/login-flow.spec.ts
+```
+
+## Replay (Zero AI Tokens)
+
+```bash
+qprobe replay "login-flow"              # run one test
+qprobe replay --all                     # run all recordings
+qprobe replay --all --headed            # visible browser
+qprobe replay --all --browser firefox   # cross-browser
+qprobe replay --all --report            # HTML report
+qprobe replay --all --retries 2         # retry flaky tests
+qprobe replay --all --base https://staging.myapp.com  # against staging
+```
+
+## Manage Recordings
+
+```bash
+qprobe recordings list                  # list all
+qprobe recordings show "login-flow"     # show steps
+qprobe recordings delete "old-test"     # delete
+qprobe recordings export "login-flow"   # standalone Playwright project
+```
+
+## How It Works
+
+1. `record start` activates capture mode
+2. Every `qprobe browser` command is recorded with both `@e` ref AND CSS selector
+3. `record stop` saves JSON recording + generates `.spec.ts` Playwright test
+4. `replay` runs the Playwright test directly — no AI, no LLM, no tokens
+5. Tests are committed to repo in `tests/qprobe/recordings/`
+
+## Tips
+
+- **Record early** — capture login, CRUD, critical paths as you build them
+- **Replay after every change** — `qprobe replay --all` catches regressions instantly
+- **Replay is free** — pure Playwright, runs in <5s per test
+- **Edit `.spec.ts`** to add custom assertions beyond what was recorded
+- **Export for CI** — `qprobe recordings export` creates standalone test project