ghost-qa 1.3.1 → 1.3.2

package/README.md

@@ -4,6 +4,7 @@
 
 [![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)
+[![npm downloads](https://img.shields.io/npm/dm/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)
@@ -15,11 +16,13 @@ Coding agents (Claude Code, Codex, Cursor, Windsurf) write code **blind** — th
 `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
+npx -y ghost-qa test http://localhost:3000
 ```
 
 No test scripts. No config. No mercy for "it works on my machine".
 
+> Prefer running straight from GitHub instead of npm? `npx -y github:avivgerz-hue/ghost-qa test http://localhost:3000` works identically — every command in this README accepts either package source (`ghost-qa mcp`, `ghost-qa init`, …).
+
 ---
 
 ## ⚡ Quickstart
@@ -30,10 +33,10 @@ 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
+npx -y ghost-qa test http://localhost:3000
 
 # 3. Teach your coding agent to do this automatically, forever
-npx github:avivgerz-hue/ghost-qa init
+npx -y 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.
@@ -121,7 +124,7 @@ Plus a **safety-first Interaction Runner**: it fills forms with inert data (`gho
 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
+npx -y ghost-qa mcp
 ```
 
 | MCP tool | What it does |
@@ -129,10 +132,10 @@ npx github:avivgerz-hue/ghost-qa mcp
 | `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):
+`npx -y 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"] } } }
+{ "mcpServers": { "ghost-qa": { "command": "npx", "args": ["-y", "ghost-qa", "mcp"] } } }
 ```
 
 Works with Claude Code, Claude Desktop, Cursor, Codex — any MCP host.
@@ -151,7 +154,7 @@ docker run -i ghost-qa   # MCP JSON-RPC over stdin/stdout
 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"
+npx -y 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.
@@ -224,7 +227,7 @@ Works with any stack that serves HTML on localhost — Next.js, Vite, Remix, Ast
 
 ## 🤖 The Agent Skill
 
-`SKILL.md` (repo root) is the master skill. `npx github:avivgerz-hue/ghost-qa init` installs it for:
+`SKILL.md` (repo root) is the master skill. `npx -y 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`

package/SKILL.md

@@ -26,13 +26,15 @@ Unit tests, type-checking, linting and code review do **not** satisfy this rule.
 
 | 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 |
+| Dev server already running | `npx -y ghost-qa test <url>` |
+| Server not running (most common) | `npx -y 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` |
 
+> All commands use the published npm package (`npx -y ghost-qa …`). If npm is unavailable, `npx -y github:avivgerz-hue/ghost-qa …` runs the identical CLI straight from GitHub.
+
 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
@@ -82,7 +84,7 @@ ghost-qa never clicks destructive controls (delete, checkout, pay, logout, publi
 
 | Symptom | Do this |
 | --- | --- |
-| "could not launch Chromium" | `npx playwright install chromium` (one-time), then `npx github:avivgerz-hue/ghost-qa doctor` |
+| "could not launch Chromium" | `npx playwright install chromium` (one-time), then `npx -y 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 |
@@ -93,7 +95,7 @@ ghost-qa never clicks destructive controls (delete, checkout, pay, logout, publi
 
 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**
+> ✅ Done. Verified in a real browser with ghost-qa: `npx -y 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)
 

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

@@ -1,7 +1,7 @@
 #!/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 declare const VERSION = "1.3.1";
+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 -y ghost-qa test <local-url>` (e.g. `npx -y 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;
@@ -20,7 +20,7 @@ export declare function installSkill(targetDir: string, force?: boolean): Promis
 /**
  * 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`.
+ * hosts invoke the published CLI: `npx -y ghost-qa mcp`.
  */
 export declare function installMcpConfig(mcpJsonPath: string, force?: boolean): Promise<string>;
 export declare function main(argv?: string[]): Promise<number>;

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

@@ -1 +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"}
+{"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,i+BAWX,CAAC;AA4EjB,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"}