Repository navigation
Releases
v2.1.1 — Official MCP Registry & Animated Demo
ghost-qa v2.1.1
Published on npm as ghost-qa@2.1.1 (@latest) and listed on the Official MCP Registry as io.github.avivgerz-hue/ghost-qa.
npx -y ghost-qa@latest test http://localhost:3000
What changed
Official MCP Registry readiness (#16)
- Added the
mcpNameownership marker to the npm package and a validserver.json, and bumped the version to 2.1.1.
README and demo (#15)
- Reworked the top of the README so the one-line quickstart and the star callout come first.
- Added an animated
demo.svgshowing a run of the CLI.
Notes
- ghost-qa is a local development verification tool, built for localhost dev servers. It is not a full WCAG audit and does not replace your own test suite. Do not point it at production systems or sites you do not own.
Ghost-QA v2.1.0 — Star CTA, QA Verified Badge & Interactive Live Demo
👻 Ghost-QA v2.1.0
★ Terminal Star CTA & QA Verified Badge
Every human-readable surface — terminal summary, compare, doctor, init, and the generated report.html header/footer — now closes with a star call-to-action and a copy-pasteable Ghost-QA Verified README badge encoding the run's actual QA Health Grade:
★ Caught a bug before deploy? Star Ghost-QA on GitHub:
https://github.com/avivgerz-hue/ghost-qa
Instant terminal star: gh repo star avivgerz-hue/ghost-qa
Machine output stays clean: --json and MCP stdio output contain zero CTA bytes (covered by hygiene tests).
🎮 Interactive 8-Trap Live Demo (GitHub Pages)
docs/index.html — a self-contained, zero-backend showcase: flip between the broken Vibe-Coded App (Score 38, Grade F) and the Self-Healed App (Score 100, Grade A+) across Desktop 1440×900, Tablet 768×1024 and Mobile 375×812 in Light & Dark, explore trap scores, findings and the route×viewport matrix, generate npx / GitHub Action / 8-agent init configs with 1-tap copy, and mint your own Copy QA Badge.
Also
- GitHub Action now pins
ghost-qa@2.1.0 - 117 tests passing (Node 20/22 CI), dynamic version loading:
--version→ghost-qa 2.1.0
Install
- npm:
npx -y ghost-qa test http://localhost:3000 - GitHub:
npx -y github:avivgerz-hue/ghost-qa test http://localhost:3000 - CI:
uses: avivgerz-hue/ghost-qa@v2 - Agents:
npx -y ghost-qa init(Claude Code, OpenCode, Codex, Cursor, Windsurf, Copilot, Cline, Zed)
Ghost-QA v2.0.0 — 8-Trap Browser QA Engine, HTML Dashboard & Universal Agent Integration
👻 Ghost-QA v2.0.0
The 8-Trap Deep Browser Inspection Engine for coding agents — now natively connected to every major agent and CI.
🪤 8-Trap Engine · 3 Viewports · Light + Dark
Desktop 1440×900, Tablet 768×1024 and Mobile 375×812, each under light + dark emulation:
- Console & Framework Runtime — page errors, hydration mismatches, duplicate keys, CSP violations
- Network & Asset Integrity — 4xx/5xx, timeouts, CORS preflights, broken images/SVGs, >500KB payloads
- Layout, Responsive Geometry & Collision — overflow, bounding-box collisions, <44×44px touch targets, clipped text, off-screen elements
- Accessibility (WCAG 2.1 AA) & Keyboard Focus — computed contrast ratios, heading hierarchy, automated Tab-order verification
- Performance & Core Web Vitals — TTFB, FCP, LCP, CLS, DOM bloat/depth
- Safe Interactive & Link Integrity — placeholder/dead links, in-form buttons without type, stuck disabled controls
- SEO, Metadata & Social Graph — title/meta/canonical/OpenGraph, duplicate ids
- Dark / Light Theme Emulation — per-scheme contrast parity (catches invisible dark-mode text)
📊 QA Health Score, Dashboard & Regression Diffing
- Deterministic QA Health Score (0–100, Grade A+…F) with per-trap sub-scores
--out-dirbundle:report.json(selectors + bounding boxes),GHOST-QA-REPORT.md,PATCH-PROMPT.md, interactive self-containedreport.html(grade hero, 8-trap scorecard, route×viewport matrix, filters, embedded screenshots)ghost-qa compare/ghost_qa_compare— Regression & Verification Delta Report (scoreDelta,fixedFindings,newRegressions,remainingFindings) so agents prove fixes
🔌 Universal Agent Integration (new in this release)
npx -y ghost-qa init connects Claude Code, OpenCode, Codex, Cursor, Windsurf, VS Code/Copilot, Cline/Roo and Zed in their native dialects — idempotently, preserving existing config. SKILL.md is the 5-phase Staff QA Engineer Protocol (doctor → baseline → root-cause mapping → remediation → delta verification to 95–100/A+).
⚙️ GitHub Actions
- uses: avivgerz-hue/ghost-qa@v2
with:
url: "http://localhost:3000"
cmd: "npm run dev"
fail-on: "high"📦 Install
- npm:
npx -y ghost-qa test http://localhost:3000 - GitHub:
npx -y github:avivgerz-hue/ghost-qa test http://localhost:3000 - Docker/MCP registries:
Dockerfile,server.json,glama.json,smithery.yamlincluded
Version is loaded dynamically from package.json, so ghost-qa --version can never lag a release again. Full details: CHANGELOG.md.
v1.3.0 — 👻 MCP Registry Indexing, Citation Metadata, Instant Zero-Build npx
👻 ghost-qa v1.3.0
The discoverability release: ghost-qa is now auto-indexable by the MCP ecosystem, citable in academic/grant contexts, and runs instantly from GitHub with zero build step.
⚡ Zero-build execution
npx github:avivgerz-hue/ghost-qa test http://localhost:3000dist/ is now committed to the repository (bin ships executable), so the command above runs immediately — no TypeScript toolchain, no compile wait on the user's machine. The prepare lifecycle is handled by scripts/prepare-build.mjs: it no-ops instantly when dist/ exists, no-ops safely when TypeScript is absent (production/git installs), and only compiles from a full source checkout.
🔌 MCP registry auto-indexing
Three manifests in the repo root, all describing exactly the tools the live server exposes (ghost_qa_audit_url, ghost_qa_doctor), kept honest by drift tests:
smithery.yaml— Smithery stdio configuration (node dist/bin/ghost-qa.js mcp)glama.json— Glama metadata, maintainer and tool definitionsserver.json— official Model Context Protocol Registry format (io.github.avivgerz-hue/ghost-qa, npm/stdio transport)
🎓 Academic & grant citation
CITATION.cff (Citation File Format 1.2.0) enables GitHub's Cite this repository widget — BibTeX/APA export for papers, grants and reports that build on ghost-qa.
🔍 Discovery
npm keywords expanded to 34 high-intent terms: mcp, mcp-server, model-context-protocol, claude-code, claude-skills, agent-skills, playwright, self-healing, accessibility-testing, web-vitals, and more.
Verified
- 69 tests passing (incl. 7 new registry-manifest drift guards) · CI green on Node 20 / 22
- Manifests validated as parseable JSON/YAML with correct CFF and Smithery semantics
- Committed
dist/bin/ghost-qa.jsverified executing through a package-manager bin symlink
Full changelog: https://github.com/avivgerz-hue/ghost-qa/blob/main/CHANGELOG.md
Part of the VibeFoundry Agent Suite — 🎨 unslop · 🛡️ vibe-shield · 👻 ghost-qa
MIT © VibeFoundry
v1.2.0 — 👻 Public-launch hardening: Node 20, current Playwright, browser E2E in CI
👻 ghost-qa v1.2.0 — public-launch hardening
Changed
- Node.js >= 20 is now required (Node 18 reached end-of-life; current Playwright requires Node 20+). Node 18 users should stay on ghost-qa 1.1.x.
- Playwright unpinned to
^1.49.1(installs current 1.x) now that the Node floor allows it — retiring the project's biggest piece of tech debt.
Added
- Real-browser end-to-end test in CI (
tests/browser-e2e.test.ts): serves a fixture app with planted console/accessibility bugs and asserts the full audit catches them on desktop + mobile while a clean route passes with zero issues. Chromium now installs before the test step so the audit loop itself can never silently regress. - SECURITY.md, CODE_OF_CONDUCT.md, CHANGELOG.md, GitHub issue templates, and an honest Scope & limitations README section (not a WCAG audit, heuristic interaction safety, auth-gated route limits, local perf heuristics).
- Greatly expanded SKILL.md: path-selection table (CLI vs
--server-cmdvs MCP tool), per-trap root-cause fix guidance, anti-cheating rules, troubleshooting table, and a completion-report template for agents. prepublishOnlyguard; copy-paste launch posts indocs/launch-post.md.
Verified
- 62 tests passing (60 unit + 2 real-browser E2E), CI green on Node 20 / 22
- Full history attribution cleanup: every commit authored & committed solely by the maintainer, zero co-author trailers
Full changelog: https://github.com/avivgerz-hue/ghost-qa/blob/main/CHANGELOG.md
Part of the VibeFoundry Agent Suite — 🎨 unslop · 🛡️ vibe-shield · 👻 ghost-qa
MIT © VibeFoundry
v1.1.0 — 👻 Native MCP Server, 5-Trap Engine, --server-cmd & HTML Evidence
👻 ghost-qa v1.1.0
The "agent-native" release: ghost-qa is now a first-class tool inside MCP hosts, sees two entirely new classes of bugs, manages your dev server for you, and produces visual evidence you can attach to a PR.
⚡ Quickstart
npx ghost-qa test http://localhost:3000 --server-cmd "npm run dev"
npx ghost-qa init # skill + protocol + .mcp.json
npx ghost-qa mcp # native MCP server🔌 Native MCP Server Mode
- New
ghost-qa mcpcommand: a zero-dependency JSON-RPC 2.0 over stdio Model Context Protocol server (src/mcp/server.ts) — no MCP SDK required ghost_qa_audit_url— runs the full crawl + trap suite against a running URL and returns the Self-Healing Bug Report (text + structured content with per-issue ids, severities, routes and viewports)ghost_qa_doctor— verifies Node, Chromium availability, and runs a live browser smoke testghost-qa initnow also writes/merges the ready-to-use.mcp.jsonentry (npx -y ghost-qa mcp), preserving any MCP servers already configured — works with Claude Code, Claude Desktop, Cursor, Codex and any MCP host
🪤 The 5-Trap Engine
Console, Network and Layout are joined by two new traps:
- Accessibility Trap (
a11y-trap.ts) — buttons/links with no accessible name, images missingalt, form inputs with no associated label (a placeholder is not a label), missing document<title>, missing<html lang> - Performance & Asset Trap (
perf-trap.ts) — Navigation/Resource Timing budgets for DOMContentLoaded and load, oversized resources (>1MB) and excessive payloads (>3MB), Long-Tasks layout-thrashing indicators, render-blocking resources, excessive DOM size
All five traps share the same architecture: a pure, unit-tested evaluator behind a thin in-page probe, feeding the terminal summary, the agent diagnostic, and the new HTML report.
🖥️ Dev-Server Lifecycle (--server-cmd)
npx ghost-qa test http://localhost:3000 --server-cmd "npm run dev"Spawns the dev server in its own process group, polls the target URL until it responds (configurable via --server-timeout), runs the complete audit, then terminates the entire server process tree — even when the audit fails. Server output is captured and included in startup-failure errors.
📊 HTML Visual Evidence Report (--html)
--html ghost-qa-report.html writes a sleek, self-contained, zero-dependency dark-mode dashboard: run verdict and coverage cards, every route crawled across desktop/mobile, issue counts by trap category, all failures with severity/viewport/issue id, and the full interaction log. Fully HTML-escaped, safe to attach to CI artifacts and pull requests.
🧰 Under the hood
- Audit engine extracted to
src/engine/audit-runner.ts— CLI, MCP server and library consumers run byte-identical audits - 60 Vitest tests (26 new): a11y/perf evaluators, the MCP JSON-RPC handler including a full stdio session, HTML escaping, a real spawned dev-server lifecycle, and
.mcp.jsonmerge behaviour - Verified end-to-end in a real Chromium via
--server-cmd: a fixture with planted a11y violations and a 1.3MB asset produced exactly the 12 expected issues across both viewports; the clean route passed with zero issues and generated the HTML evidence report - CI green on Node 18 / 20 / 22 (build → test → Chromium install → browser smoke test)
Requirements
Node.js >= 18.17 · Playwright (Chromium) · any app serving HTML on localhost.
Part of the VibeFoundry Agent Suite — alongside 🎨 unslop and 🛡️ vibe-shield.
MIT © VibeFoundry
v1.0.0 — 👻 ghost-qa initial launch
👻 ghost-qa v1.0.0 — Initial Launch
Autonomous headless browser QA & self-healing verification loop for AI coding agents. Coding agents write code blind and declare victory while the browser has hydration errors, dead buttons, 500ing APIs, or mobile layout overflow — ghost-qa launches a real browser, crawls the live DOM, traps what actually breaks, and hands the agent a structured bug report to fix before it reports done.
⚡ Quickstart
npm run dev # your app on localhost
npx playwright install chromium # one-time
npx ghost-qa test http://localhost:3000 # verify it in a real browser
npx ghost-qa init # teach your agent to do this automaticallyHighlights
- Zero-config autonomous crawl —
ghost-qa test <url>discovers internal routes (BFS, configurable--max-depth/--max-routes) and tests Desktop 1440×900 + Mobile 390×844 in one command, no test scripts needed - Console Trap — uncaught
pageerrorexceptions, unhandled promise rejections, React hydration mismatches,console.error(dev-server noise filtered out) - Network Trap — HTTP 5xx API crashes, 4xx responses, failed fetch/XHR, CORS failures, broken static assets
- Layout Trap — horizontal scroll overflow with offending elements named, zero-size interactive elements, broken images (
naturalWidth === 0), missing viewport meta - Safety-first Interaction Runner — clicks buttons, opens tabs/modals, fills forms with inert data — but never destructive controls (delete, checkout, pay, logout, publish…)
- Agent Skill installer —
ghost-qa initinstalls.claude/skills/ghost-qa/SKILL.mdand the Verify in Browser Before Done protocol intoCLAUDE.md,AGENTS.mdand.cursorrules(idempotent) - Self-Healing Bug Report — token-efficient Markdown/JSON diagnostic grouped by route, with stable issue
#ids and a per-category fix playbook (--report,--json) ghost-qa doctor— Node / Playwright / Chromium diagnostics with a live browser smoke test
Verification
- 34 Vitest tests covering trap evaluators, crawler policy, the interaction safety gate, and both reporters
- CI on Node 18 / 20 / 22: build → test → Chromium install → browser smoke test
- Validated end-to-end against a deliberately buggy fixture app: hydration error, uncaught exception, 500 API, broken image, and mobile overflow all trapped; clean routes pass
Requirements
Node.js >= 18.17 · Playwright (Chromium) · any app serving HTML on localhost — Next.js, Vite, Remix, Astro, CRA, static servers and more.
Part of the VibeFoundry Agent Suite — alongside 🎨 unslop and 🛡️ vibe-shield.
MIT © VibeFoundry