Skip to content

Releases

v2.1.1 — Official MCP Registry & Animated Demo

Choose a tag to compare

@avivgerz-hue avivgerz-hue released this 12 Nov 15:43
3f576e6

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 mcpName ownership marker to the npm package and a valid server.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.svg showing 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

Choose a tag to compare

@avivgerz-hue avivgerz-hue released this 09 Nov 09:23
d49147e

👻 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

Choose a tag to compare

@avivgerz-hue avivgerz-hue released this 08 Nov 20:59
4257ad4

👻 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:

  1. Console & Framework Runtime — page errors, hydration mismatches, duplicate keys, CSP violations
  2. Network & Asset Integrity — 4xx/5xx, timeouts, CORS preflights, broken images/SVGs, >500KB payloads
  3. Layout, Responsive Geometry & Collision — overflow, bounding-box collisions, <44×44px touch targets, clipped text, off-screen elements
  4. Accessibility (WCAG 2.1 AA) & Keyboard Focus — computed contrast ratios, heading hierarchy, automated Tab-order verification
  5. Performance & Core Web Vitals — TTFB, FCP, LCP, CLS, DOM bloat/depth
  6. Safe Interactive & Link Integrity — placeholder/dead links, in-form buttons without type, stuck disabled controls
  7. SEO, Metadata & Social Graph — title/meta/canonical/OpenGraph, duplicate ids
  8. 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-dir bundle: report.json (selectors + bounding boxes), GHOST-QA-REPORT.md, PATCH-PROMPT.md, interactive self-contained report.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.yaml included

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

Choose a tag to compare

@avivgerz-hue avivgerz-hue released this 07 Nov 22:45
813d97d

👻 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:3000

dist/ 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 definitions
  • server.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.js verified 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

Choose a tag to compare

@avivgerz-hue avivgerz-hue released this 07 Nov 21:36
fdaf0a3

👻 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-cmd vs MCP tool), per-trap root-cause fix guidance, anti-cheating rules, troubleshooting table, and a completion-report template for agents.
  • prepublishOnly guard; copy-paste launch posts in docs/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

Choose a tag to compare

@avivgerz-hue avivgerz-hue released this 07 Nov 21:00

👻 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 mcp command: 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 test
  • ghost-qa init now also writes/merges the ready-to-use .mcp.json entry (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 missing alt, 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.json merge 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

Choose a tag to compare

@avivgerz-hue avivgerz-hue released this 07 Nov 20:13
5e34d06

👻 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 automatically

Highlights

  • 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 pageerror exceptions, 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 init installs .claude/skills/ghost-qa/SKILL.md and the Verify in Browser Before Done protocol into CLAUDE.md, AGENTS.md and .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