ghost-qa 0.0.0-stage → 1.3.1

package/dist/src/traps/perf-trap.js

@@ -0,0 +1,196 @@
+import { makeIssue } from '../types.js';
+export const EMPTY_PERF_METRICS = {
+    domContentLoadedMs: 0,
+    loadMs: 0,
+    resourceCount: 0,
+    totalTransferBytes: 0,
+    oversizedResources: [],
+    renderBlockingCount: 0,
+    domNodeCount: 0,
+    longTaskCount: 0,
+    longTaskTotalMs: 0,
+};
+export const PERF_THRESHOLDS = {
+    domContentLoadedMs: 3_000,
+    loadMs: 5_000,
+    singleResourceBytes: 1_000_000,
+    totalTransferBytes: 3_000_000,
+    renderBlockingCount: 5,
+    domNodeCount: 1_500,
+    longTaskCount: 5,
+    longTaskTotalMs: 500,
+};
+const kb = (bytes) => `${Math.round(bytes / 1024)}KB`;
+const ms = (value) => `${Math.round(value)}ms`;
+/**
+ * Pure evaluator: Navigation/Resource Timing facts in, perf issues out.
+ * Fully unit-testable without a browser.
+ */
+export function evaluatePerfMetrics(metrics, route, viewport) {
+    const issues = [];
+    if (metrics.domContentLoadedMs > PERF_THRESHOLDS.domContentLoadedMs ||
+        metrics.loadMs > PERF_THRESHOLDS.loadMs) {
+        const critical = metrics.domContentLoadedMs > PERF_THRESHOLDS.domContentLoadedMs * 2 ||
+            metrics.loadMs > PERF_THRESHOLDS.loadMs * 2;
+        issues.push(makeIssue({
+            category: 'performance',
+            severity: critical ? 'critical' : 'major',
+            type: 'slow-page-load',
+            message: `Slow page load on ${viewport}: DOMContentLoaded ${ms(metrics.domContentLoadedMs)}, full load ${ms(metrics.loadMs)} ` +
+                `(budgets: ${ms(PERF_THRESHOLDS.domContentLoadedMs)} / ${ms(PERF_THRESHOLDS.loadMs)}). ` +
+                'Profile render-blocking scripts, server response time and hydration cost before adding more UI.',
+            route,
+            viewport,
+            details: {
+                domContentLoadedMs: Math.round(metrics.domContentLoadedMs),
+                loadMs: Math.round(metrics.loadMs),
+            },
+        }));
+    }
+    for (const resource of metrics.oversizedResources.slice(0, 5)) {
+        if (resource.transferBytes <= PERF_THRESHOLDS.singleResourceBytes)
+            continue;
+        issues.push(makeIssue({
+            category: 'performance',
+            severity: 'major',
+            type: 'oversized-resource',
+            message: `Oversized resource (${kb(resource.transferBytes)}): ${resource.url}. Compress, resize, lazy-load or code-split it — a single asset should stay under ${kb(PERF_THRESHOLDS.singleResourceBytes)}.`,
+            route,
+            viewport,
+            url: resource.url,
+            details: { transferBytes: resource.transferBytes },
+        }));
+    }
+    if (metrics.totalTransferBytes > PERF_THRESHOLDS.totalTransferBytes) {
+        issues.push(makeIssue({
+            category: 'performance',
+            severity: 'major',
+            type: 'excessive-payload',
+            message: `Excessive page payload: ${kb(metrics.totalTransferBytes)} transferred across ${metrics.resourceCount} resources (budget ${kb(PERF_THRESHOLDS.totalTransferBytes)}). Audit bundles, images and fonts; defer anything below the fold.`,
+            route,
+            viewport,
+            details: {
+                totalTransferBytes: metrics.totalTransferBytes,
+                resourceCount: metrics.resourceCount,
+            },
+        }));
+    }
+    if (metrics.renderBlockingCount > PERF_THRESHOLDS.renderBlockingCount) {
+        issues.push(makeIssue({
+            category: 'performance',
+            severity: 'minor',
+            type: 'render-blocking-resources',
+            message: `${metrics.renderBlockingCount} render-blocking scripts/stylesheets in <head> delay first paint. Add defer/async, inline critical CSS, or move non-critical tags to the end of <body>.`,
+            route,
+            viewport,
+            details: { renderBlockingCount: metrics.renderBlockingCount },
+        }));
+    }
+    if (metrics.longTaskCount > PERF_THRESHOLDS.longTaskCount || metrics.longTaskTotalMs > PERF_THRESHOLDS.longTaskTotalMs) {
+        issues.push(makeIssue({
+            category: 'performance',
+            severity: 'major',
+            type: 'layout-thrashing',
+            message: `Main-thread jank: ${metrics.longTaskCount} long tasks totalling ${ms(metrics.longTaskTotalMs)} (>50ms each) — a layout-thrashing / heavy-JS indicator. ` +
+                'Break up synchronous work, memoise renders, and avoid forced synchronous layouts (reading offsetWidth in loops after DOM writes).',
+            route,
+            viewport,
+            details: {
+                longTaskCount: metrics.longTaskCount,
+                longTaskTotalMs: Math.round(metrics.longTaskTotalMs),
+            },
+        }));
+    }
+    if (metrics.domNodeCount > PERF_THRESHOLDS.domNodeCount) {
+        issues.push(makeIssue({
+            category: 'performance',
+            severity: 'minor',
+            type: 'excessive-dom-size',
+            message: `Excessive DOM size: ${metrics.domNodeCount} nodes (budget ${PERF_THRESHOLDS.domNodeCount}). Deep/wide DOMs slow style recalculation, layout and hydration — virtualise long lists and prune wrapper divs.`,
+            route,
+            viewport,
+            details: { domNodeCount: metrics.domNodeCount },
+        }));
+    }
+    return issues;
+}
+/** In-page probe: reads Navigation Timing + Resource Timing from the live page. */
+async function probePerf() {
+    const nav = performance.getEntriesByType('navigation')[0];
+    const resources = performance.getEntriesByType('resource');
+    let totalTransferBytes = 0;
+    const oversizedResources = [];
+    for (const resource of resources) {
+        const bytes = resource.transferSize || resource.encodedBodySize || 0;
+        totalTransferBytes += bytes;
+        if (bytes > 250_000) {
+            oversizedResources.push({ url: resource.name.slice(0, 200), transferBytes: bytes });
+        }
+    }
+    oversizedResources.sort((a, b) => b.transferBytes - a.transferBytes);
+    let renderBlockingCount = 0;
+    document
+        .querySelectorAll('head script[src]:not([async]):not([defer]), head link[rel="stylesheet"]')
+        .forEach(() => {
+        renderBlockingCount += 1;
+    });
+    let longTaskCount = 0;
+    let longTaskTotalMs = 0;
+    try {
+        // PerformanceObserver with buffered entries — getEntriesByType('longtask')
+        // logs a "Deprecated API" console warning in Chromium, which ghost-qa's
+        // own Console Trap would then (correctly) flag on every page.
+        const longTasks = await new Promise((resolvePromise) => {
+            const collected = [];
+            try {
+                const observer = new PerformanceObserver((list) => {
+                    collected.push(...list.getEntries());
+                });
+                observer.observe({ type: 'longtask', buffered: true });
+                setTimeout(() => {
+                    observer.disconnect();
+                    resolvePromise(collected);
+                }, 30);
+            }
+            catch {
+                resolvePromise(collected);
+            }
+        });
+        for (const entry of longTasks) {
+            longTaskCount += 1;
+            longTaskTotalMs += entry.duration;
+        }
+    }
+    catch {
+        /* Long Tasks API unsupported in this browser */
+    }
+    return {
+        domContentLoadedMs: nav ? nav.domContentLoadedEventEnd : 0,
+        loadMs: nav ? nav.loadEventEnd || nav.responseEnd : 0,
+        resourceCount: resources.length,
+        totalTransferBytes,
+        oversizedResources: oversizedResources.slice(0, 10),
+        renderBlockingCount,
+        domNodeCount: document.querySelectorAll('*').length,
+        longTaskCount,
+        longTaskTotalMs,
+    };
+}
+/** Runs the in-page perf probe against a live page and evaluates it. */
+export class PerfTrap {
+    viewport;
+    constructor(viewport) {
+        this.viewport = viewport;
+    }
+    async collect(page, route) {
+        let metrics;
+        try {
+            metrics = await page.evaluate(probePerf);
+        }
+        catch {
+            return [];
+        }
+        return evaluatePerfMetrics(metrics, route, this.viewport);
+    }
+}
+//# sourceMappingURL=perf-trap.js.map

package/dist/src/traps/perf-trap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf-trap.js","sourceRoot":"","sources":["../../../src/traps/perf-trap.ts"],"names":[],"mappings":"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"}

package/dist/src/types.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Shared contracts for ghost-qa.
+ *
+ * Every trap, crawler and reporter speaks in these types so a run can be
+ * rendered for a human (terminal), serialised for CI (JSON), or fed back to a
+ * coding agent (Markdown diagnostic) without any translation layer.
+ */
+export type ViewportName = 'desktop' | 'mobile';
+export type IssueCategory = 'console' | 'network' | 'layout' | 'accessibility' | 'performance' | 'interaction' | 'navigation';
+export type IssueSeverity = 'critical' | 'major' | 'minor';
+export type IssueType = 'page-error' | 'unhandled-rejection' | 'hydration-mismatch' | 'console-error' | 'console-warning' | 'http-error' | 'request-failed' | 'cors-error' | 'broken-asset' | 'horizontal-overflow' | 'zero-size-interactive' | 'broken-image' | 'missing-viewport-meta' | 'interaction-failed' | 'navigation-failed' | 'missing-accessible-name' | 'img-missing-alt' | 'input-missing-label' | 'missing-document-title' | 'missing-html-lang' | 'slow-page-load' | 'oversized-resource' | 'excessive-payload' | 'render-blocking-resources' | 'layout-thrashing' | 'excessive-dom-size';
+export interface QAIssue {
+    /** Stable, de-duplication-friendly identifier (hash of the fingerprint). */
+    id: string;
+    category: IssueCategory;
+    severity: IssueSeverity;
+    type: IssueType;
+    /** Human / agent readable one-line description. */
+    message: string;
+    /** Path of the route the issue was observed on, e.g. `/pricing`. */
+    route: string;
+    viewport: ViewportName;
+    /** Optional machine-readable context (status code, selector, geometry…). */
+    details?: Record<string, string | number | boolean>;
+    stack?: string;
+    /** Fully-qualified URL related to the issue, when one exists. */
+    url?: string;
+    timestamp: string;
+}
+export interface InteractionAction {
+    kind: 'click' | 'fill' | 'tab' | 'modal-open' | 'modal-close' | 'toggle';
+    /** CSS-ish descriptor or visible label of the element exercised. */
+    target: string;
+    route: string;
+    viewport: ViewportName;
+    outcome: 'passed' | 'failed' | 'skipped';
+    reason?: string;
+}
+export interface RouteRecord {
+    url: string;
+    path: string;
+    depth: number;
+    title: string;
+    httpStatus?: number;
+    viewports: ViewportName[];
+    issueCount: number;
+}
+export interface GhostQAOptions {
+    maxDepth: number;
+    maxRoutes: number;
+    maxInteractionsPerPage: number;
+    timeoutMs: number;
+    settleMs: number;
+    headless: boolean;
+    viewports: ViewportName[];
+    interactions: boolean;
+    /** Fail (exit 1) when an issue at or above this severity is found. */
+    failOn: IssueSeverity;
+}
+export declare const DEFAULT_OPTIONS: GhostQAOptions;
+export interface GhostQAReport {
+    tool: 'ghost-qa';
+    version: string;
+    targetUrl: string;
+    startedAt: string;
+    finishedAt: string;
+    durationMs: number;
+    passed: boolean;
+    options: GhostQAOptions;
+    routes: RouteRecord[];
+    interactions: InteractionAction[];
+    issues: QAIssue[];
+    summary: {
+        routesCrawled: number;
+        interactionsTested: number;
+        interactionsSkipped: number;
+        interactionsFailed: number;
+        totalIssues: number;
+        bySeverity: Record<IssueSeverity, number>;
+        byCategory: Record<IssueCategory, number>;
+    };
+}
+export declare const SEVERITY_ORDER: Record<IssueSeverity, number>;
+export declare function severityAtOrAbove(severity: IssueSeverity, threshold: IssueSeverity): boolean;
+/** Small deterministic hash used for stable issue ids. */
+export declare function fingerprint(input: string): string;
+export declare function makeIssue(input: Omit<QAIssue, 'id' | 'timestamp'> & {
+    timestamp?: string;
+}): QAIssue;
+/** De-duplicate identical findings (the same error often fires per viewport listener). */
+export declare function dedupeIssues(issues: QAIssue[]): QAIssue[];
+export declare function summarise(routes: RouteRecord[], interactions: InteractionAction[], issues: QAIssue[], failOn: IssueSeverity): GhostQAReport['summary'] & {
+    passed: boolean;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/dist/src/types.js

@@ -0,0 +1,80 @@
+/**
+ * Shared contracts for ghost-qa.
+ *
+ * Every trap, crawler and reporter speaks in these types so a run can be
+ * rendered for a human (terminal), serialised for CI (JSON), or fed back to a
+ * coding agent (Markdown diagnostic) without any translation layer.
+ */
+export const DEFAULT_OPTIONS = {
+    maxDepth: 2,
+    maxRoutes: 25,
+    maxInteractionsPerPage: 12,
+    timeoutMs: 15_000,
+    settleMs: 600,
+    headless: true,
+    viewports: ['desktop', 'mobile'],
+    interactions: true,
+    failOn: 'major',
+};
+export const SEVERITY_ORDER = {
+    critical: 3,
+    major: 2,
+    minor: 1,
+};
+export function severityAtOrAbove(severity, threshold) {
+    return SEVERITY_ORDER[severity] >= SEVERITY_ORDER[threshold];
+}
+/** Small deterministic hash used for stable issue ids. */
+export function fingerprint(input) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < input.length; i++) {
+        hash ^= input.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, '0');
+}
+export function makeIssue(input) {
+    const detailString = input.details ? JSON.stringify(input.details) : '';
+    const id = fingerprint([input.category, input.type, input.route, input.viewport, input.message, detailString].join('|'));
+    return {
+        ...input,
+        id,
+        timestamp: input.timestamp ?? new Date().toISOString(),
+    };
+}
+/** De-duplicate identical findings (the same error often fires per viewport listener). */
+export function dedupeIssues(issues) {
+    const seen = new Map();
+    for (const issue of issues) {
+        if (!seen.has(issue.id))
+            seen.set(issue.id, issue);
+    }
+    return [...seen.values()];
+}
+export function summarise(routes, interactions, issues, failOn) {
+    const bySeverity = { critical: 0, major: 0, minor: 0 };
+    const byCategory = {
+        console: 0,
+        network: 0,
+        layout: 0,
+        accessibility: 0,
+        performance: 0,
+        interaction: 0,
+        navigation: 0,
+    };
+    for (const issue of issues) {
+        bySeverity[issue.severity] += 1;
+        byCategory[issue.category] += 1;
+    }
+    return {
+        routesCrawled: routes.length,
+        interactionsTested: interactions.filter((a) => a.outcome === 'passed').length,
+        interactionsSkipped: interactions.filter((a) => a.outcome === 'skipped').length,
+        interactionsFailed: interactions.filter((a) => a.outcome === 'failed').length,
+        totalIssues: issues.length,
+        bySeverity,
+        byCategory,
+        passed: !issues.some((i) => severityAtOrAbove(i.severity, failOn)),
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,91 @@
 {
   "name": "ghost-qa",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.3.1",
+  "description": "Autonomous headless browser QA & self-healing verification loop for coding agents. Crawls localhost, traps console/network/layout failures, and feeds structured diagnostics back to the agent.",
+  "type": "module",
+  "bin": {
+    "ghost-qa": "dist/bin/ghost-qa.js"
+  },
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "scripts/prepare-build.mjs",
+    "SKILL.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "prepare": "node scripts/prepare-build.mjs",
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "qa": "npm run build && npm test",
+    "prepublishOnly": "npm run qa"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "claude-code",
+    "claude-skills",
+    "agent-skills",
+    "ai-agents",
+    "coding-agents",
+    "playwright",
+    "headless-browser",
+    "qa-automation",
+    "e2e-testing",
+    "self-healing",
+    "codex",
+    "cursor",
+    "cursorrules",
+    "windsurf",
+    "accessibility-testing",
+    "a11y",
+    "web-vitals",
+    "performance-testing",
+    "browser-testing",
+    "test-automation",
+    "automated-testing",
+    "typescript",
+    "cli",
+    "devtools",
+    "hydration",
+    "ci-cd",
+    "browser-verification",
+    "agent-tools",
+    "llm-agents",
+    "frontend-qa",
+    "mobile-testing"
+  ],
+  "author": "VibeFoundry",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/avivgerz-hue/ghost-qa.git"
+  },
+  "homepage": "https://github.com/avivgerz-hue/ghost-qa#readme",
+  "bugs": {
+    "url": "https://github.com/avivgerz-hue/ghost-qa/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "playwright": "^1.49.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}

package/scripts/prepare-build.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+/**
+ * `prepare` lifecycle script — must be safe in EVERY install context:
+ *
+ * 1. dist/ already built (it is committed to the repo, so
+ *    `npx github:avivgerz-hue/ghost-qa` works instantly)  -> no-op.
+ * 2. TypeScript available (normal clone / npm install)    -> build.
+ * 3. TypeScript absent (production install, git dep with
+ *    devDependencies pruned)                              -> no-op, never fail.
+ *
+ * Failing here would break installs for end users, so every path exits 0
+ * except a genuine build failure when TypeScript IS present and dist/ is
+ * missing.
+ */
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+const distEntry = join(root, 'dist', 'bin', 'ghost-qa.js');
+const tscBin = join(root, 'node_modules', 'typescript', 'bin', 'tsc');
+
+if (existsSync(distEntry)) {
+  process.exit(0);
+}
+
+if (!existsSync(tscBin)) {
+  console.warn(
+    'ghost-qa: TypeScript not installed and dist/ missing — skipping build ' +
+      '(install from a full clone if you need to compile from source).',
+  );
+  process.exit(0);
+}
+
+const result = spawnSync(process.execPath, [tscBin, '-p', 'tsconfig.json'], {
+  cwd: root,
+  stdio: 'inherit',
+});
+process.exit(result.status ?? 0);