ghost-qa 0.0.0-stage → 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VibeFoundry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,273 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# 👻 ghost-qa
+
+**Autonomous headless browser QA & self-healing verification loop for coding agents.**
+
+[![CI](https://github.com/avivgerz-hue/ghost-qa/actions/workflows/ci.yml/badge.svg)](https://github.com/avivgerz-hue/ghost-qa/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/ghost-qa.svg)](https://www.npmjs.com/package/ghost-qa)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Node >= 20](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
+[![Powered by Playwright](https://img.shields.io/badge/powered%20by-Playwright-45ba4b.svg)](https://playwright.dev)
+
+![ghost-qa terminal preview](./assets/hero-terminal.svg)
+
+Coding agents (Claude Code, Codex, Cursor, Windsurf) write code **blind** — then declare victory while the actual browser has React hydration errors, broken buttons, 500ing APIs, or mobile layout overflow.
+
+`ghost-qa` fixes that. One command launches a headless browser against your running app, crawls the live DOM, safely pokes every button, traps runtime/network/layout failures, and hands the agent a structured **Self-Healing Bug Report** so it fixes its own bugs *before* telling you it's done.
+
+```bash
+npx github:avivgerz-hue/ghost-qa test http://localhost:3000
+```
+
+No test scripts. No config. No mercy for "it works on my machine".
+
+---
+
+## ⚡ Quickstart
+
+```bash
+# 1. Start your app as usual
+npm run dev            # → http://localhost:3000
+
+# 2. Verify it in a real browser (one-time: downloads Chromium)
+npx playwright install chromium
+npx github:avivgerz-hue/ghost-qa test http://localhost:3000
+
+# 3. Teach your coding agent to do this automatically, forever
+npx github:avivgerz-hue/ghost-qa init
+```
+
+`ghost-qa init` installs `.claude/skills/ghost-qa/SKILL.md` and appends the strict **"Verify in Browser Before Done"** protocol to `CLAUDE.md`, `AGENTS.md`, and `.cursorrules`. From then on, your agent runs ghost-qa itself, fixes what it finds, and only reports completion on a PASS.
+
+---
+
+## 🔁 The Autonomous Self-Healing QA Loop
+
+```
+                        ┌──────────────────────────────────────────┐
+                        │            CODING AGENT                   │
+                        │  Claude Code · Codex · Cursor · Windsurf  │
+                        └───┬──────────────────────────────▲───────┘
+              writes code   │                                │  Self-Healing
+                            ▼                                │  Bug Report
+                    ┌───────────────┐              ┌─────────┴──────────┐
+                    │   DEV SERVER   │              │  AGENT DIAGNOSTIC   │
+                    │ localhost:3000 │              │  verdict · #ids ·   │
+                    └───────┬───────┘              │  fix playbook       │
+                            │ serves live DOM      └─────────▲──────────┘
+                            ▼                                │ Markdown / JSON
+                    ┌────────────────────────────────────────┴──────────┐
+                    │                   👻 ghost-qa                      │
+                    │                                                    │
+                    │   Route Crawler ──► Interaction Runner             │
+                    │        │                    │                      │
+                    │        ▼                    ▼                      │
+                    │   ┌─────────┐  ┌──────────┐  ┌─────────┐          │
+                    │   │ CONSOLE │  │ NETWORK  │  │ LAYOUT  │          │
+                    │   │  A11Y   │  │  PERF    │  │ 5 TRAPS │          │
+                    │   │  TRAP   │  │  TRAP    │  │  TRAP   │          │
+                    │   └─────────┘  └──────────┘  └─────────┘          │
+                    │   Desktop 1440×900  +  Mobile 390×844 (iPhone)     │
+                    └────────────────────────────────────────────────────┘
+                                          │
+                          fix bugs ───────┘  re-run until ✔ PASS
+```
+
+1. The agent writes code and starts the dev server.
+2. `ghost-qa test` crawls every internal route on **desktop + mobile**, exercising interactive controls.
+3. Five traps capture everything the browser actually experienced.
+4. Failures return as a token-efficient diagnostic; the agent fixes the root causes and re-runs.
+5. The loop ends only at **PASS** — that's when the agent may tell you it's done.
+
+---
+
+## 🪤 The 5-Trap Engine
+
+### 1. Console Trap — `src/traps/console-trap.ts`
+- Uncaught `pageerror` exceptions with stack traces
+- Unhandled promise rejections
+- **React hydration mismatches** ("Text content did not match", "A tree hydrated but…")
+- `console.error` (major) and `console.warning` (minor) — with dev-server noise (`[vite]`, HMR, React DevTools banners) filtered out
+
+### 2. Network Trap — `src/traps/network-trap.ts`
+- HTTP `5xx` API crashes (critical) and `4xx` responses (major)
+- Failed `fetch`/`XHR` requests and connection failures
+- **CORS-blocked requests** with remediation guidance
+- Broken static assets (JS/CSS/images/fonts) and missing favicons (minor)
+
+### 3. Layout Trap — `src/traps/layout-trap.ts`
+- **Horizontal overflow**: `scrollWidth > innerWidth`, with the offending elements named (critical on mobile)
+- Zero-dimension interactive elements — buttons rendered at 0×0 that no human could tap
+- Broken images (`naturalWidth === 0`)
+- Missing `<meta name="viewport">` on mobile
+
+### 4. Accessibility Trap — `src/traps/a11y-trap.ts` *(new in v1.1.0)*
+- Buttons and links with **no accessible name** (icon-only controls screen readers can't identify)
+- Images **missing `alt`** attributes (descriptive alt, or `alt=""` for decorative)
+- Form inputs with **no associated label** — a placeholder is not a label
+- Missing document `<title>` and missing `<html lang>`
+
+### 5. Performance & Asset Trap — `src/traps/perf-trap.ts` *(new in v1.1.0)*
+- Slow page loads via Navigation Timing (DOMContentLoaded / load budgets, 2× = critical)
+- **Oversized resources** (> 1MB single asset) and excessive total payload (> 3MB)
+- Main-thread jank / layout-thrashing indicators from the Long Tasks API
+- Render-blocking `<head>` resources and excessive DOM size
+
+Plus a **safety-first Interaction Runner**: it fills forms with inert data (`ghost-qa@example.com`), opens tabs/modals/menus, and clicks ordinary buttons — but *never* destructive ones (`delete`, `checkout`, `pay`, `logout`, `publish`… are blocked by a tested safety gate).
+
+---
+
+## 🔌 Native MCP Server *(new in v1.1.0)*
+
+ghost-qa ships a zero-dependency **Model Context Protocol** server (JSON-RPC 2.0 over stdio), so MCP hosts can invoke browser verification as a native tool instead of shelling out:
+
+```bash
+npx github:avivgerz-hue/ghost-qa mcp
+```
+
+| MCP tool | What it does |
+| --- | --- |
+| `ghost_qa_audit_url` | Runs the full crawl + 5-trap suite against a running URL and returns the Self-Healing Bug Report (text + structured content) |
+| `ghost_qa_doctor` | Verifies Node, Chromium availability, and runs a live browser smoke test |
+
+`npx github:avivgerz-hue/ghost-qa init` writes the ready-to-use `.mcp.json` entry for you (merging with any servers you already have):
+
+```json
+{ "mcpServers": { "ghost-qa": { "command": "npx", "args": ["-y", "github:avivgerz-hue/ghost-qa", "mcp"] } } }
+```
+
+Works with Claude Code, Claude Desktop, Cursor, Codex — any MCP host.
+
+**Docker / Glama:** the repo ships a production `Dockerfile` whose entrypoint is the MCP server (`node dist/bin/ghost-qa.js mcp`). Registry introspection (`initialize` + `tools/list` over stdio) answers instantly with no Chromium present — a browser is only launched when a tool is actually called:
+
+```bash
+docker build -t ghost-qa .
+docker run -i ghost-qa   # MCP JSON-RPC over stdin/stdout
+```
+
+---
+
+## 🖥️ Zero-lifecycle testing with `--server-cmd` *(new in v1.1.0)*
+
+Don't even start the dev server yourself — ghost-qa will spawn it, wait for the URL to respond, audit, and terminate the whole process tree afterward:
+
+```bash
+npx github:avivgerz-hue/ghost-qa test http://localhost:3000 --server-cmd "npm run dev"
+```
+
+Pair it with `--html ghost-qa-report.html` for a self-contained, dark-mode **visual evidence dashboard** (routes, interactions, every trap finding per viewport) you can attach to CI artifacts or PRs.
+
+---
+
+## 📟 Example output
+
+```
+👻 ghost-qa — autonomous browser verification
+Target: http://localhost:3000/
+Duration: 8.4s · Viewports: desktop + mobile · Depth: 2
+
+Routes crawled
+  /                            Home                 [200] 3 issues
+  /pricing                     Pricing              [200] ✓
+  /dashboard                   Dashboard            [200] 2 issues
+
+Coverage
+  Routes visited:       3
+  Interactions tested:  21 passed · 1 failed · 4 skipped (safety)
+  Issues:               5 total — 2 critical, 3 major, 0 minor
+
+Failures caught
+  ✖ CRITICAL [console] React hydration mismatch: Text content did not match…
+      ↳ / · desktop · #a91f03cc
+  ✖ CRITICAL [network] Server error HTTP 500 for /api/users — backend/API is crashing on this route.
+      ↳ /dashboard · mobile · #51bd77e0
+  ▲ MAJOR [layout] Horizontal overflow on mobile: page scrolls sideways by 130px…
+      ↳ / · mobile · #c04d19aa
+
+✖ GHOST-QA FAIL — blocking browser failures found. Fix them and re-run before reporting done.
+```
+
+The agent-facing report (`--report ghost-qa-report.md`) groups the same bugs by route with a per-category fix playbook and the exact re-run command.
+
+---
+
+## 🚀 CLI reference
+
+| Command | Description |
+| --- | --- |
+| `ghost-qa test <url>` | Crawl a running app and trap browser failures. Exit `0` = PASS, `1` = blocking issues, `2` = runner error |
+| `ghost-qa init [--force]` | Install `.claude/skills/ghost-qa/SKILL.md`, verification protocol (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`) + MCP config (`.mcp.json`) — all idempotent |
+| `ghost-qa mcp` | Run the native MCP server (JSON-RPC 2.0 over stdio) exposing `ghost_qa_audit_url` and `ghost_qa_doctor` |
+| `ghost-qa doctor` | Diagnose Node ≥ 20, Playwright and Chromium setup, with a live browser smoke test |
+| `ghost-qa --version` / `--help` | Version / usage |
+
+### `test` flags
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `--max-depth <n>` | `2` | Link-following depth from the start URL |
+| `--max-routes <n>` | `25` | Maximum routes to visit |
+| `--timeout <ms>` | `15000` | Per-navigation timeout |
+| `--viewport <name>` | `both` | `both` \| `desktop` \| `mobile` |
+| `--no-interactions` | off | Load pages only; don't click or fill anything |
+| `--headed` | off | Show the browser window (debugging) |
+| `--fail-on <severity>` | `major` | Exit 1 on `critical` \| `major` \| `minor` issues |
+| `--json` | off | Print the full machine-readable JSON report to stdout |
+| `--report <file>` | — | Write diagnostic to a file (Markdown, or JSON if the name ends `.json`) |
+| `--html <file>` | — | Write the self-contained dark-mode HTML visual evidence dashboard |
+| `--server-cmd <cmd>` | — | Spawn a dev server, wait for the URL, audit, then terminate the server tree |
+| `--server-timeout <ms>` | `30000` | How long to wait for `--server-cmd` to start responding |
+| `--quiet` | off | Suppress the terminal summary (report file + exit code only) |
+
+Works with any stack that serves HTML on localhost — Next.js, Vite, Remix, Astro, Create React App, plain static servers, Rails, Django… if a browser can open it, ghost-qa can judge it.
+
+---
+
+## 🤖 The Agent Skill
+
+`SKILL.md` (repo root) is the master skill. `npx github:avivgerz-hue/ghost-qa init` installs it for:
+
+- **Claude Code** → `.claude/skills/ghost-qa/SKILL.md` + protocol in `CLAUDE.md`
+- **Codex / generic agents** → protocol in `AGENTS.md`
+- **Cursor / Windsurf** → protocol in `.cursorrules`
+
+The protocol is wrapped in `<!-- ghost-qa:start/end -->` markers, so re-running `init` updates it in place without duplicating or clobbering your other instructions.
+
+## ⚖️ Scope & limitations (read this — we mean it)
+
+ghost-qa is a **local development verification tool**, and we'd rather be honest than viral:
+
+- **Not a WCAG audit.** The Accessibility Trap catches common machine-checkable failures (names, alt, labels, title, lang). Full WCAG conformance still needs assistive-technology testing.
+- **Not a replacement for your test suite.** It complements unit/E2E tests by checking the *live* app the way a browser experiences it — it writes no persistent tests for you.
+- **Heuristic safety.** The Interaction Runner refuses destructive-looking controls (delete, checkout, pay, logout…) and fills only inert data, but "destructive" is ultimately a word list. It is designed for localhost dev servers.
+- **Auth-gated apps.** Without credentials, ghost-qa audits what an anonymous visitor sees (often the login page). Authenticated crawling is on the roadmap, not in the box today.
+- **Performance numbers are local-machine heuristics.** Borderline perf findings on a loaded CI box deserve a re-run, not a panic.
+- **Never point it at production systems or sites you don't own** or have explicit permission to test. It clicks real buttons.
+- The MCP server is **stdio-only** (no network ports). Only wire it into MCP hosts you trust.
+
+Found a trap flagging a healthy page? That's our most valuable issue type — [file it with the report attached](https://github.com/avivgerz-hue/ghost-qa/issues/new/choose). Security reports: see [SECURITY.md](./SECURITY.md). Release history: [CHANGELOG.md](./CHANGELOG.md).
+
+## 🧑‍💻 Development
+
+```bash
+npm install
+npx playwright install chromium
+npm run build     # tsc → dist/
+npm test          # Vitest: trap evaluators, crawler policy, safety gate, reporters
+node dist/bin/ghost-qa.js doctor
+```
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the "pure evaluator first" architecture rules.
+
+## 📄 License
+
+MIT © VibeFoundry — see [LICENSE](./LICENSE).
+
+---
+
+## Part of the VibeFoundry Agent Suite
+
+| Tool | Description |
+| --- | --- |
+| 🎨 [unslop](https://github.com/avivgerz-hue/unslop) | Studio-grade UI design systems & Anti-Slop engine for coding agents. |
+| 🛡️ [vibe-shield](https://github.com/avivgerz-hue/vibe-shield) | Automated security scanner & MCP guard for AI-generated codebases. |
+| 👻 [ghost-qa](https://github.com/avivgerz-hue/ghost-qa) | Autonomous headless browser QA & self-healing verification loop. |

package/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: ghost-qa
+description: Verify frontend work in a real headless browser before reporting a task complete. Use after building or changing any UI, route, form, API integration, or client-side logic — crawls the running app on desktop and mobile, runs a 5-trap engine (console/hydration, network, layout, accessibility, performance), exercises interactive controls, and returns a self-healing bug report to fix from. Also usable via the ghost_qa_audit_url MCP tool.
+license: MIT
+---
+
+# 👻 ghost-qa — Verify in Browser Before Done
+
+Coding agents write code blind. Code that type-checks can still ship with React hydration mismatches, uncaught exceptions, 500ing APIs, dead buttons, icon-only controls no screen reader can name, and mobile layouts that scroll sideways. **The browser is the source of truth — never your mental model of the DOM.**
+
+## The Rule
+
+> Before reporting ANY task that touches frontend code as complete, you MUST run the app in a real browser with ghost-qa, fix everything blocking it catches, and re-run until it passes.
+
+Unit tests, type-checking, linting and code review do **not** satisfy this rule. They cannot see hydration, layout, network or accessibility failures.
+
+## When to use this skill
+
+- ✅ You created or changed pages, components, routes, forms, styles, or client-side data fetching
+- ✅ You fixed a bug that manifested in the browser
+- ✅ You are about to tell the user a UI task is "done"
+
+**Not a substitute for:** your unit/E2E test suites, a full WCAG accessibility audit (ghost-qa's a11y trap covers common machine-checkable failures, not full WCAG conformance), load testing, or manual exploratory QA.
+
+## Choose your path
+
+| Situation | Command |
+| --- | --- |
+| Dev server already running | `npx github:avivgerz-hue/ghost-qa test <url>` |
+| Server not running (most common) | `npx github:avivgerz-hue/ghost-qa test <url> --server-cmd "npm run dev"` — ghost-qa spawns it, waits for it, audits, and kills the process tree afterward |
+| Your host exposes MCP tools | Call **`ghost_qa_audit_url`** with the URL (call `ghost_qa_doctor` first if it errors) — identical engine, identical report |
+| Mobile-only bug hunt | add `--viewport mobile` |
+| Large app | add `--max-depth 3 --max-routes 50` |
+| Evidence for a PR/CI | add `--report ghost-qa-report.md --html ghost-qa-report.html` |
+
+Common local URLs: Next.js / CRA `http://localhost:3000`, Vite `http://localhost:5173`, Astro `http://localhost:4321`, Angular `http://localhost:4200`. If unsure, check the dev server output or `package.json` scripts — never guess silently; state the URL you verified in your completion message.
+
+## The Self-Healing Loop
+
+1. **Run the audit** (path table above). The 5-Trap Engine checks, on Desktop 1440×900 *and* Mobile 390×844:
+   - **Console** — uncaught errors, unhandled promise rejections, React hydration mismatches, `console.error`
+   - **Network** — HTTP 4xx/5xx, failed fetch/XHR, CORS failures, broken assets
+   - **Layout** — horizontal overflow, zero-size interactive elements, broken images, missing viewport meta
+   - **Accessibility** — buttons/links with no accessible name, images missing `alt`, inputs with no label, missing `<title>` / `<html lang>`
+   - **Performance** — slow loads, oversized assets/payloads, main-thread long-task jank, render-blocking resources, excessive DOM
+2. **Read the Self-Healing Bug Report.** Every issue has a stable `#id`, a severity (`critical` / `major` / `minor`), the route, and the viewport. Fix **critical and major** issues. Note minors; fix them when cheap.
+3. **Fix root causes in source** (fix guidance below). Reference issues by `#id` in your own narration so the user can follow along.
+4. **Re-run the identical command.** A fix that breaks a different route or viewport only shows up on re-run.
+5. **Repeat until `GHOST-QA PASS`.** If you have looped 5 times on the same `#id`, stop and report to the user what is stuck and why — do not silently give up or declare success.
+6. **Only then** report completion, using the completion template below.
+
+## Fix guidance per trap
+
+| Trap | Typical root causes | Fix like this |
+| --- | --- | --- |
+| Hydration mismatch | `Date.now()`/`Math.random()`/`window` during render, server/client branching, invalid HTML nesting (`<p>` in `<p>`, `<div>` in `<p>`) | Make server and client render identical markup; move time/random/client-only values into `useEffect` + state; fix the nesting |
+| Uncaught page error | undefined data, missing null checks on async data, bad imports | Reproduce via the stack trace in the report; guard the actual data path |
+| Console error | failed state updates, rejected promises, React warnings treated seriously by the app | Trace the first error, not the cascade after it |
+| HTTP 5xx | API route crash, bad env var, DB down | Read the server logs for that endpoint; the browser found it, the fix is server-side |
+| HTTP 404 / broken asset | wrong path, case-sensitivity, asset not emitted by the build | Compare the URL in the report with the actual build output / public dir |
+| CORS failure | API missing `Access-Control-Allow-Origin` for the page origin | Fix the API's CORS config (or the dev proxy), not the fetch call |
+| Horizontal overflow | `100vw` + scrollbar, fixed-width children, flex/grid children without `min-width: 0` | Constrain widths (`max-width: 100%`, `min-width: 0`, `overflow-wrap`); the report names the offending elements |
+| Zero-size interactive | collapsed CSS, `display: contents` misuse, content that never rendered | Restore a real, tappable size (≥ 24px, ideally ≥ 40px on mobile) |
+| No accessible name | icon-only `<button>`/`<a>` | Add visible text or `aria-label` describing the action/destination |
+| Missing `alt` | forgotten attribute | Descriptive alt; `alt=""` only if purely decorative |
+| Input without label | placeholder used as label | Real `<label for>`, wrapping `<label>`, or `aria-label` |
+| Slow load / oversized asset | unoptimized images, giant bundles, blocking scripts | Compress/lazy-load, `defer`/`async`, code-split; check the named resource first |
+| Long-task jank | heavy sync JS, layout reads in loops after writes | Break up work, memoize, batch DOM reads before writes |
+
+## Anti-cheating rules (this is the point of the skill)
+
+- ❌ Never silence the checker: no deleting the failing UI, no blanket `try/catch`, no `suppressHydrationWarning`, no removing the code path "so the error goes away"
+- ❌ Never use `--no-interactions` or narrow `--viewport`/`--max-depth` to hide failures (legitimate only when a page has side-effectful controls, and you must say so)
+- ❌ Never edit ghost-qa's report, thresholds, or your project's ghost-qa invocation to manufacture a PASS
+- ✅ If a finding is a genuine false positive, say so explicitly in your completion message with the `#id` and why — a human can overrule the tool; you may not quietly ignore it
+
+## Safety guarantees you can rely on
+
+ghost-qa never clicks destructive controls (delete, checkout, pay, logout, publish, sign-in…), never submits real orders/payments, fills forms only with inert data (`ghost-qa@example.com`, `ghost-qa test`), stays on same-origin links, and is designed for localhost/dev servers. **Do not point it at production systems you do not own or have permission to test.** Pages behind authentication will typically redirect to a login page — ghost-qa will audit what an anonymous visitor sees; say so if that's what happened.
+
+## Troubleshooting
+
+| Symptom | Do this |
+| --- | --- |
+| "could not launch Chromium" | `npx playwright install chromium` (one-time), then `npx github:avivgerz-hue/ghost-qa doctor` |
+| `navigation-failed` on every route | Server isn't on that URL/port — start it, or re-run with `--server-cmd "npm run dev"` |
+| Everything 404s | Wrong port or base path — confirm the URL in a browser/`curl` yourself first |
+| Audit seems to test a login page | The app requires auth for those routes; report that limitation instead of claiming full verification |
+| Perf findings vary between runs | Machine load affects timings; re-run once before treating a borderline perf major as real |
+| MCP tool unavailable | Fall back to the CLI — the audit engine and report are identical |
+
+## Completion template
+
+When the final run passes, report completion like this:
+
+> ✅ Done. Verified in a real browser with ghost-qa: `npx github:avivgerz-hue/ghost-qa test <url>` → **GHOST-QA PASS**
+> Routes crawled: N · Interactions tested: N · Issues fixed this session: (list `#id`s, or "none found")
+> Stack: desktop 1440×900 + mobile 390×844, 5 traps (console, network, layout, accessibility, performance)
+
+## Completion checklist
+
+- [ ] Final code state audited (not an earlier draft of the change)
+- [ ] All critical/major issues fixed at the root cause, or explicitly reported as false positives with reasoning
+- [ ] Final run prints `GHOST-QA PASS`
+- [ ] Completion message uses the template above and names the URL verified

package/dist/bin/ghost-qa.d.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { type GhostQAOptions } from '../src/types.js';
+export declare const VERSION = "1.3.0";
+export declare const AGENT_PROTOCOL = "<!-- ghost-qa:start -->\n## \uD83D\uDC7B ghost-qa \u2014 Browser Verification Protocol (MANDATORY)\n\nBefore reporting any task that touches frontend code as complete, you MUST verify it in a real browser:\n\n1. Ensure the app is running locally (e.g. `npm run dev`).\n2. Run: `npx github:avivgerz-hue/ghost-qa test <local-url>` (e.g. `npx github:avivgerz-hue/ghost-qa test http://localhost:3000`) \u2014 or call the `ghost_qa_audit_url` MCP tool if your host exposes it. Add `--server-cmd \"npm run dev\"` to let ghost-qa manage the dev server itself.\n3. If ghost-qa reports ANY critical or major issue (hydration errors, console errors, 4xx/5xx responses, mobile overflow, accessibility or performance failures, broken interactions), fix the root cause in source and re-run.\n4. Repeat until ghost-qa prints **PASS**. Only then may you tell the user the task is done.\n\nNever declare a UI task finished based only on code review, type-checking, or unit tests. The browser is the source of truth.\n<!-- ghost-qa:end -->";
+export interface ParsedTestArgs {
+    target: string;
+    options: GhostQAOptions;
+    json: boolean;
+    quiet: boolean;
+    reportFile?: string;
+    htmlFile?: string;
+    serverCmd?: string;
+    serverTimeoutMs: number;
+}
+export declare function parseTestArgs(args: string[]): ParsedTestArgs;
+export declare function installSkill(targetDir: string, force?: boolean): Promise<Array<{
+    file: string;
+    action: string;
+}>>;
+/**
+ * Writes (or merges into) `.mcp.json`, preserving any MCP servers the
+ * project already configured. The ghost-qa entry is always refreshed so
+ * hosts invoke the published CLI: `npx -y github:avivgerz-hue/ghost-qa mcp`.
+ */
+export declare function installMcpConfig(mcpJsonPath: string, force?: boolean): Promise<string>;
+export declare function main(argv?: string[]): Promise<number>;
+/**
+ * True when this module is the process entry point. The entry path MUST be
+ * realpath-resolved first: package managers invoke bins through a
+ * `node_modules/.bin/ghost-qa` symlink, while `import.meta.url` always
+ * points at the real file — comparing unresolved paths would make the CLI
+ * silently no-op (exit 0, no output) under `npx`.
+ */
+export declare function isMainEntry(argvEntry: string | undefined, moduleUrl?: string): boolean;
+//# sourceMappingURL=ghost-qa.d.ts.map

package/dist/bin/ghost-qa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ghost-qa.d.ts","sourceRoot":"","sources":["../../bin/ghost-qa.ts"],"names":[],"mappings":";AAWA,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEvE,eAAO,MAAM,OAAO,UAAmB,CAAC;AAKxC,eAAO,MAAM,cAAc,mgCAWX,CAAC;AAyEjB,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,cAAc,CAAC;IACxB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,cAAc,CA+E5D;AAyDD,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,KAAK,UAAQ,GACZ,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAqBlD;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,KAAK,UAAQ,GACZ,OAAO,CAAC,MAAM,CAAC,CAuBjB;AAuCD,wBAAsB,IAAI,CAAC,IAAI,WAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CAoDxE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,SAAS,GAAE,MAAwB,GAClC,OAAO,CAOT"}