@questpie/probe 0.1.0

package/dist/replay-Dg9PHNrg.js

@@ -0,0 +1,171 @@
+import "./duration-DUrbfMLK.js";
+import { loadProbeConfig } from "./config-BUEMgFYN.js";
+import { error, log } from "./output-CHUjdVDf.js";
+import { formatReplayResult } from "./reporter-CqWc26OP.js";
+import { defineCommand } from "citty";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { x } from "tinyexec";
+
+//#region src/testing/replayer.ts
+async function replayRecording(opts) {
+	const config = await loadProbeConfig();
+	const testsDir = config.tests?.dir ?? "tests/qprobe";
+	const specPath = join(testsDir, "recordings", `${opts.name}.spec.ts`);
+	await ensurePlaywrightConfig(testsDir, opts);
+	const args = [
+		"playwright",
+		"test",
+		specPath
+	];
+	if (opts.headed) args.push("--headed");
+	if (opts.browser) args.push("--project", opts.browser);
+	if (opts.parallel) args.push("--workers", "4");
+	if (opts.retries) args.push("--retries", String(opts.retries));
+	if (opts.report) args.push("--reporter", "html");
+	const result = await x("npx", args, {
+		timeout: (config.tests?.timeout ?? 3e4) * 10,
+		throwOnError: false
+	});
+	const output = result.stdout + result.stderr;
+	const passMatch = output.match(/(\d+) passed/);
+	const failMatch = output.match(/(\d+) failed/);
+	return {
+		exitCode: result.exitCode ?? 0,
+		passed: passMatch ? Number(passMatch[1]) : 0,
+		failed: failMatch ? Number(failMatch[1]) : 0,
+		output
+	};
+}
+async function replayAll(opts) {
+	const config = await loadProbeConfig();
+	const testsDir = config.tests?.dir ?? "tests/qprobe";
+	const recordingsDir = join(testsDir, "recordings");
+	await ensurePlaywrightConfig(testsDir, opts);
+	const args = [
+		"playwright",
+		"test",
+		recordingsDir,
+		"--grep",
+		"\\.spec\\.ts$"
+	];
+	if (opts.headed) args.push("--headed");
+	if (opts.browser) args.push("--project", opts.browser);
+	if (opts.parallel) args.push("--workers", "4");
+	if (opts.retries) args.push("--retries", String(opts.retries));
+	if (opts.report) args.push("--reporter", "html");
+	const result = await x("npx", args, {
+		timeout: (config.tests?.timeout ?? 3e4) * 20,
+		throwOnError: false
+	});
+	const output = result.stdout + result.stderr;
+	const passMatch = output.match(/(\d+) passed/);
+	const failMatch = output.match(/(\d+) failed/);
+	return {
+		exitCode: result.exitCode ?? 0,
+		passed: passMatch ? Number(passMatch[1]) : 0,
+		failed: failMatch ? Number(failMatch[1]) : 0,
+		output
+	};
+}
+async function ensurePlaywrightConfig(testsDir, opts) {
+	const config = await loadProbeConfig();
+	const baseUrl = opts.base ?? config.browser?.baseUrl ?? config.http?.baseUrl ?? "http://localhost:3000";
+	const content = `import { defineConfig } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './recordings',
+  timeout: ${config.tests?.timeout ?? 3e4},
+  use: {
+    baseURL: '${baseUrl}',
+    trace: 'on-first-retry',
+  },
+  projects: [
+    { name: 'chromium', use: { browserName: 'chromium' } },
+    { name: 'firefox', use: { browserName: 'firefox' } },
+    { name: 'webkit', use: { browserName: 'webkit' } },
+  ],
+})
+`;
+	await mkdir(testsDir, { recursive: true });
+	await writeFile(join(testsDir, "playwright.config.ts"), content, "utf-8");
+}
+
+//#endregion
+//#region src/commands/replay.ts
+const command = defineCommand({
+	meta: {
+		name: "replay",
+		description: "Run recorded Playwright tests"
+	},
+	args: {
+		name: {
+			type: "positional",
+			description: "Recording name to replay",
+			required: false
+		},
+		all: {
+			type: "boolean",
+			description: "Replay all recordings",
+			default: false
+		},
+		headed: {
+			type: "boolean",
+			description: "Show browser window",
+			default: false
+		},
+		browser: {
+			type: "string",
+			description: "Browser to use (chromium, firefox, webkit)"
+		},
+		parallel: {
+			type: "boolean",
+			description: "Run tests in parallel",
+			default: false
+		},
+		report: {
+			type: "boolean",
+			description: "Generate HTML report",
+			default: false
+		},
+		retries: {
+			type: "string",
+			description: "Number of retries for flaky tests"
+		},
+		base: {
+			type: "string",
+			description: "Override base URL"
+		}
+	},
+	async run({ args }) {
+		try {
+			const opts = {
+				headed: args.headed,
+				browser: args.browser,
+				parallel: args.parallel,
+				report: args.report,
+				retries: args.retries ? Number(args.retries) : void 0,
+				base: args.base
+			};
+			let result;
+			if (args.all) result = await replayAll(opts);
+			else if (args.name) result = await replayRecording({
+				name: args.name,
+				...opts
+			});
+			else {
+				error("Provide a recording name or use --all");
+				process.exit(1);
+			}
+			log(formatReplayResult(result));
+			if (result.exitCode !== 0) process.exit(6);
+		} catch (err) {
+			error(err instanceof Error ? err.message : String(err));
+			process.exit(1);
+		}
+	}
+});
+var replay_default = command;
+
+//#endregion
+export { replay_default as default };

package/dist/reporter-CqWc26OP.js

@@ -0,0 +1,25 @@
+//#region src/testing/reporter.ts
+function formatReplayResult(result) {
+	const lines = [];
+	if (result.exitCode === 0) lines.push(`\u2705 All tests passed (${result.passed} passed)`);
+	else lines.push(`\u274c Tests failed (${result.passed} passed, ${result.failed} failed)`);
+	if (result.output.trim()) {
+		lines.push("");
+		lines.push(result.output.trim());
+	}
+	return lines.join("\n");
+}
+function formatRecordingsList(recordings) {
+	if (recordings.length === 0) return "No recordings found";
+	const lines = [];
+	lines.push("NAME                    ACTIONS  DATE");
+	for (const r of recordings) {
+		const name = r.name.padEnd(24);
+		const actions = String(r.actions).padEnd(9);
+		lines.push(`${name}${actions}${r.date}`);
+	}
+	return lines.join("\n");
+}
+
+//#endregion
+export { formatRecordingsList, formatReplayResult };

package/dist/restart-By3Edj5X.js

@@ -0,0 +1,44 @@
+import { error, success } from "./output-CHUjdVDf.js";
+import "./state-DRTSIt_r.js";
+import { getProcessState, startProcess, stopProcess } from "./process-manager-CzexpFO4.js";
+import { defineCommand } from "citty";
+
+//#region src/commands/restart.ts
+const command = defineCommand({
+	meta: {
+		name: "restart",
+		description: "Restart a process with its original config"
+	},
+	args: { name: {
+		type: "positional",
+		description: "Process name to restart",
+		required: true
+	} },
+	async run({ args }) {
+		try {
+			const state = await getProcessState(args.name);
+			if (!state) {
+				error(`No saved state for "${args.name}"`);
+				process.exit(1);
+			}
+			await stopProcess(args.name);
+			const { pid } = await startProcess({
+				name: state.name,
+				cmd: state.cmd,
+				ready: state.ready,
+				timeout: state.timeout,
+				port: state.port,
+				env: state.env,
+				cwd: state.cwd
+			});
+			success(`Restarted "${args.name}" (PID ${pid})`);
+		} catch (err) {
+			error(err instanceof Error ? err.message : String(err));
+			process.exit(1);
+		}
+	}
+});
+var restart_default = command;
+
+//#endregion
+export { restart_default as default };

package/dist/snapshot-diff-CqXEVTAZ.js

@@ -0,0 +1,51 @@
+//#region src/browser/snapshot-diff.ts
+function parseSnapshot(text) {
+	const elements = [];
+	const lines = text.split("\n");
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith("URL:")) continue;
+		const match = trimmed.match(/^-\s+(\w+)\s+"([^"]*)"\s+\[ref=(@e\d+)\]/);
+		if (match) {
+			elements.push({
+				role: match[1],
+				name: match[2],
+				ref: match[3]
+			});
+			continue;
+		}
+		const matchNoQuote = trimmed.match(/^-\s+(\w+)\s+(.+?)\s+\[ref=(@e\d+)\]/);
+		if (matchNoQuote) elements.push({
+			role: matchNoQuote[1],
+			name: matchNoQuote[2],
+			ref: matchNoQuote[3]
+		});
+	}
+	return elements;
+}
+function extractUrl(text) {
+	const match = text.match(/^URL:\s*(.+)$/m);
+	return match ? match[1].trim() : null;
+}
+function elementKey(el) {
+	return `${el.role}:${el.name}`;
+}
+function diffSnapshots(previous, current) {
+	const prevElements = parseSnapshot(previous);
+	const currElements = parseSnapshot(current);
+	const prevUrl = extractUrl(previous);
+	const currUrl = extractUrl(current);
+	const prevKeys = new Map();
+	for (const el of prevElements) prevKeys.set(elementKey(el), el);
+	const currKeys = new Map();
+	for (const el of currElements) currKeys.set(elementKey(el), el);
+	const lines = [];
+	if (prevUrl && currUrl && prevUrl !== currUrl) lines.push(`URL: ${prevUrl} \u2192 ${currUrl}`);
+	for (const [key, el] of prevKeys) if (!currKeys.has(key)) lines.push(`REMOVED: ${el.role} "${el.name}" [${el.ref}]`);
+	for (const [key, el] of currKeys) if (!prevKeys.has(key)) lines.push(`ADDED:   ${el.role} "${el.name}" [${el.ref}]`);
+	if (lines.length === 0) return "No changes detected";
+	return lines.join("\n");
+}
+
+//#endregion
+export { diffSnapshots };

package/dist/start-BClY6oJq.js

@@ -0,0 +1,79 @@
+import { parseDuration } from "./duration-DUrbfMLK.js";
+import { error, success } from "./output-CHUjdVDf.js";
+import "./state-DRTSIt_r.js";
+import { startProcess } from "./process-manager-CzexpFO4.js";
+import { defineCommand } from "citty";
+
+//#region src/commands/start.ts
+const command = defineCommand({
+	meta: {
+		name: "start",
+		description: "Start a background process with ready detection"
+	},
+	args: {
+		name: {
+			type: "positional",
+			description: "Process name",
+			required: true
+		},
+		cmd: {
+			type: "positional",
+			description: "Command to run",
+			required: true
+		},
+		ready: {
+			type: "string",
+			description: "Ready pattern (regex/string in stdout)"
+		},
+		timeout: {
+			type: "string",
+			description: "Max wait for ready (e.g. 60s, 5m)",
+			default: "60s"
+		},
+		port: {
+			type: "string",
+			description: "Port for health checks"
+		},
+		env: {
+			type: "string",
+			description: "Environment variables as comma-separated KEY=VAL pairs (e.g. \"PORT=3000,DB_URL=postgres://...\")"
+		},
+		cwd: {
+			type: "string",
+			description: "Working directory"
+		}
+	},
+	async run({ args }) {
+		const envVars = {};
+		if (args.env) {
+			const pairs = args.env.split(/,(?=[A-Za-z_][A-Za-z0-9_]*=)/);
+			for (const pair of pairs) {
+				const eqIndex = pair.indexOf("=");
+				if (eqIndex > 0) {
+					const key = pair.slice(0, eqIndex);
+					const value = pair.slice(eqIndex + 1);
+					envVars[key] = value;
+				}
+			}
+		}
+		try {
+			const { pid } = await startProcess({
+				name: args.name,
+				cmd: args.cmd,
+				ready: args.ready,
+				timeout: parseDuration(args.timeout),
+				port: args.port ? Number(args.port) : void 0,
+				env: Object.keys(envVars).length > 0 ? envVars : void 0,
+				cwd: args.cwd
+			});
+			success(`Started "${args.name}" (PID ${pid})`);
+		} catch (err) {
+			error(err instanceof Error ? err.message : String(err));
+			process.exit(err instanceof Error && err.message.includes("Timeout") ? 2 : 1);
+		}
+	}
+});
+var start_default = command;
+
+//#endregion
+export { start_default as default };

package/dist/state-DRTSIt_r.js

@@ -0,0 +1,62 @@
+import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+//#region src/core/state.ts
+const BASE_DIR = "tmp/qprobe";
+const PIDS_DIR = join(BASE_DIR, "pids");
+const STATE_DIR = join(BASE_DIR, "state");
+const LOGS_DIR = join(BASE_DIR, "logs");
+async function ensureDir(dir) {
+	await mkdir(dir, { recursive: true });
+}
+function getLogPath(name) {
+	return join(LOGS_DIR, `${name}.log`);
+}
+async function savePid(name, pid) {
+	await ensureDir(PIDS_DIR);
+	await writeFile(join(PIDS_DIR, `${name}.pid`), String(pid), "utf-8");
+}
+async function readPid(name) {
+	try {
+		const content = await readFile(join(PIDS_DIR, `${name}.pid`), "utf-8");
+		return Number.parseInt(content.trim(), 10);
+	} catch {
+		return null;
+	}
+}
+async function removePid(name) {
+	try {
+		await rm(join(PIDS_DIR, `${name}.pid`));
+	} catch {}
+}
+async function saveState(name, state) {
+	await ensureDir(STATE_DIR);
+	await writeFile(join(STATE_DIR, `${name}.json`), JSON.stringify(state, null, 2), "utf-8");
+}
+async function readState(name) {
+	try {
+		const content = await readFile(join(STATE_DIR, `${name}.json`), "utf-8");
+		return JSON.parse(content);
+	} catch {
+		return null;
+	}
+}
+async function removeState(name) {
+	try {
+		await rm(join(STATE_DIR, `${name}.json`));
+	} catch {}
+}
+async function listProcessNames() {
+	try {
+		const files = await readdir(PIDS_DIR);
+		return files.filter((f) => f.endsWith(".pid")).map((f) => f.replace(".pid", ""));
+	} catch {
+		return [];
+	}
+}
+async function ensureLogsDir() {
+	await ensureDir(LOGS_DIR);
+}
+
+//#endregion
+export { ensureLogsDir, getLogPath, listProcessNames, readPid, readState, removePid, removeState, savePid, saveState };

package/dist/stop-QAP6gbDe.js

@@ -0,0 +1,47 @@
+import { error, success } from "./output-CHUjdVDf.js";
+import "./state-DRTSIt_r.js";
+import { stopAll, stopProcess } from "./process-manager-CzexpFO4.js";
+import { defineCommand } from "citty";
+
+//#region src/commands/stop.ts
+const command = defineCommand({
+	meta: {
+		name: "stop",
+		description: "Stop a running process (SIGTERM → SIGKILL)"
+	},
+	args: {
+		name: {
+			type: "positional",
+			description: "Process name to stop",
+			required: false
+		},
+		all: {
+			type: "boolean",
+			description: "Stop all processes",
+			default: false
+		}
+	},
+	async run({ args }) {
+		try {
+			if (args.all) {
+				const stopped = await stopAll();
+				if (stopped.length === 0) success("No processes running");
+				else success(`Stopped ${stopped.length} process(es): ${stopped.join(", ")}`);
+				return;
+			}
+			if (!args.name) {
+				error("Provide a process name or use --all");
+				process.exit(1);
+			}
+			await stopProcess(args.name);
+			success(`Stopped "${args.name}"`);
+		} catch (err) {
+			error(err instanceof Error ? err.message : String(err));
+			process.exit(1);
+		}
+	}
+});
+var stop_default = command;
+
+//#endregion
+export { stop_default as default };

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@questpie/probe",
+  "version": "0.1.0",
+  "description": "Dev testing CLI for AI coding agents",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "qprobe": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "skills",
+    "templates"
+  ],
+  "scripts": {
+    "dev": "tsdown --watch",
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "lint": "biome check .",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "c12": "^2.0.0",
+    "chokidar": "^4.0.0",
+    "citty": "^0.1.0",
+    "consola": "^3.0.0",
+    "defu": "^6.0.0",
+    "ofetch": "^1.0.0",
+    "tinyexec": "^0.3.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "@types/bun": "latest",
+    "tsdown": "^0.9.0",
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {
+    "agent-browser": ">=0.1.0",
+    "@playwright/test": ">=1.45.0"
+  },
+  "peerDependenciesMeta": {
+    "agent-browser": {
+      "optional": false
+    },
+    "@playwright/test": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "testing",
+    "ai",
+    "agent",
+    "browser-automation",
+    "cli",
+    "dev-tools",
+    "playwright",
+    "questpie"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/questpie/probe"
+  },
+  "author": "QUESTPIE <hello@questpie.com>",
+  "homepage": "https://probe.questpie.com"
+}

package/skills/qprobe/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: qprobe
+description: "QUESTPIE Probe — dev testing CLI for AI coding agents. Orchestrates dev servers, aggregates logs, controls browsers, sends HTTP requests, records and replays tests. Use when: testing web apps, starting dev servers, checking logs, debugging runtime errors, recording test flows, making API calls against running servers, checking browser console or network tab, composing multi-service stacks. Triggers: 'test this app', 'start the server', 'check if it works', 'what are the logs', 'any errors?', 'record a test', 'run the tests', 'call the API', 'check the network tab', 'start the database', 'compose up', 'is the server running', 'replay tests', 'check for regressions'. Even if the user doesn't mention qprobe by name, use this skill when they want to test, debug, or verify a running web application."
+---
+
+# QUESTPIE Probe
+
+Dev testing CLI. Manages dev servers, reads logs, controls browsers, sends HTTP requests, records and replays tests.
+
+**Install:** `npm install -g @questpie/probe`
+
+## Core Principle
+
+> Read logs before opening a browser. 90% of debugging needs zero visual context.
+
+## Quick Start
+
+```bash
+qprobe compose up                           # start all services from config
+qprobe check http://localhost:3000           # health + console + network summary
+qprobe logs server --grep "ERROR"            # check process logs
+qprobe http GET /api/health                  # test API endpoint
+qprobe browser open http://localhost:3000    # open browser (only if needed)
+qprobe browser snapshot -i                   # see interactive elements
+```
+
+## Command Groups
+
+| Command | What it does | When to use |
+|---------|-------------|-------------|
+| `qprobe start` | Start a process with ready detection | Need to run dev server, DB, worker |
+| `qprobe stop` | Stop a running process | Cleanup, restart |
+| `qprobe ps` | List running processes | Check what's running |
+| `qprobe health` | Poll URL until healthy | Wait for server to be ready |
+| `qprobe compose` | Multi-service orchestration | Start full stack (DB+server+admin) |
+| `qprobe logs` | Read/filter/follow process logs | Debug server errors |
+| `qprobe http` | Send HTTP requests | Test API endpoints |
+| `qprobe check` | All-in-one health summary | Quick status overview |
+| `qprobe browser` | Browser automation | Visual testing, form filling |
+| `qprobe record` | Record a test session | Capture a flow for regression |
+| `qprobe replay` | Replay recorded tests | Run regression (zero AI tokens) |
+| `qprobe assert` | Assert conditions | Verify state in CI or scripts |
+
+## Recommended Workflow
+
+1. **Start stack** → `qprobe compose up`
+2. **Read logs** → `qprobe logs --all --grep ERROR` (no browser yet!)
+3. **Test API** → `qprobe http GET /api/health` (still no browser!)
+4. **Quick check** → `qprobe check` (summarizes everything)
+5. **Open browser** → `qprobe browser open /login` (only if needed)
+6. **Record test** → `qprobe record start "login-flow"`
+7. **Replay free** → `qprobe replay --all` (pure Playwright, zero tokens)
+
+## Sub-Skills
+
+For detailed reference on each command group, read the corresponding reference file:
+
+- **Process management** (start, stop, ps, health, restart) → read `references/process.md`
+- **Compose** (multi-service orchestration, config file) → read `references/compose.md`
+- **HTTP requests** (API testing, auth, assertions) → read `references/http.md`
+- **Browser control** (snapshot, click, fill, console, network) → read `references/browser.md`
+- **Recording & replay** (test capture, Playwright codegen) → read `references/recording.md`
+
+## Config File
+
+Create `qprobe.config.ts` in project root (optional — CLI works without it):
+
+```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'],
+    },
+  },
+  browser: {
+    driver: 'agent-browser',
+    baseUrl: 'http://localhost:3000',
+  },
+  http: {
+    baseUrl: 'http://localhost:3000',
+  },
+})
+```
+
+## Tips for Agents
+
+- **Always check logs before opening browser** — most bugs are visible in `qprobe logs`
+- **Use `qprobe check`** for a one-command overview of server health
+- **Use `qprobe http`** instead of browser for API testing — much cheaper on tokens
+- **Snapshot with `-i`** (interactive only) to save tokens — skip structural/decorative elements
+- **Snapshot with `--diff`** after actions to see only what changed
+- **Record flows you want to verify later** — replay costs zero AI tokens
+- **Grep is your friend** — `qprobe logs server --grep "ERROR"` is faster than reading everything