afterburn-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Afterburn Contributors
+
+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

@@ -0,0 +1,281 @@
+# Afterburn
+
+[![npm version](https://img.shields.io/npm/v/afterburn-cli)](https://www.npmjs.com/package/afterburn-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)
+[![Tests](https://img.shields.io/badge/tests-193%20passing-brightgreen)]()
+[![Built at BridgeMind Vibeathon 2026](https://img.shields.io/badge/Built%20at-BridgeMind%20Vibeathon%202026-blueviolet)]()
+
+**One command finds every bug on your website.** Zero config. Generates a report your AI coding tool can use to fix them automatically.
+
+```bash
+npx afterburn-cli https://your-site.com
+```
+
+```
+Afterburn v1.0.0
+
+✔ Checking browser...
+✔ Crawling site...
+✔ Testing workflows...
+✔ Analyzing results...
+✔ Generating reports...
+
+Health: 62/100 — 20 issues found (0 high, 17 medium, 3 low)
+
+Reports saved:
+  HTML:     afterburn-reports/1770564079516/report.html
+  Markdown: afterburn-reports/1770564079516/report.md
+```
+
+Afterburn crawls your site, fills out forms, clicks every button, and tells you what's broken -- in plain English for you, in structured Markdown for Claude, Cursor, or ChatGPT to auto-fix.
+
+> **The AI workflow:** Afterburn finds the bugs. You paste the Markdown report into Claude, Cursor, or ChatGPT. It reads the reproduction steps and fixes them. You re-scan. Done.
+
+## The AI-readable report (the killer feature)
+
+Every scan generates **two reports**:
+
+1. **HTML Report** -- A health score and prioritized bug list in plain English. For you to read.
+2. **Markdown Report** -- Structured with reproduction steps and fix suggestions. Feed it directly to Claude, ChatGPT, or Cursor and your AI coding tool can **fix the bugs automatically**.
+
+```
+You: "Here's my Afterburn report. Fix these bugs."
+AI:  *reads structured report, fixes 12 issues across 4 files*
+```
+
+This is the workflow: Afterburn finds the bugs, your AI fixes them. Zero manual debugging.
+
+### What the AI report looks like
+
+The Markdown report is structured so AI tools can parse and act on it:
+
+```markdown
+## Issues (Prioritized)
+
+| # | Priority | Category | Summary | Location |
+|---|----------|----------|---------|----------|
+| 1 | HIGH | Workflow Error | Form "form#contact-form" submission isn't working | /contact |
+| 2 | MEDIUM | Dead Button | Button "Get Started Free" doesn't do anything when clicked | / |
+| 3 | MEDIUM | Console Error | An image failed to load | /images/icon-deploy.png |
+```
+
+Each issue includes a category, priority, plain-English summary, and location. Paste this into Claude or Cursor and it knows exactly what to fix.
+
+### Sample reports
+
+See what Afterburn produces when scanning a real app with 20+ intentional defects:
+
+![Afterburn HTML Report](assets/report-preview.png)
+
+- [Sample HTML report](demo-cache/report.html) -- Health score, prioritized issues, fix suggestions
+- [Sample Markdown report](demo-cache/report.md) -- Structured for AI coding tools
+- [Terminal output](demo-cache/terminal-output.txt) -- What you see in the CLI
+
+## What it catches
+
+- Broken forms that don't submit
+- Dead buttons that do nothing when clicked
+- JavaScript errors and console crashes
+- HTTP errors (404s, 500s, failed API calls)
+- Broken images and missing assets
+- Accessibility violations (WCAG 2.1 AA via axe-core)
+- Slow page loads and poor performance scores
+
+## Quick start
+
+```bash
+# No install needed -- run directly
+npx afterburn-cli https://your-site.com
+
+# Or install globally
+npm install -g afterburn-cli
+```
+
+Afterburn downloads a browser automatically on first run (~200MB, one-time).
+
+## Try it now
+
+Scan any public website -- no signup, no API key, no config:
+
+```bash
+npx afterburn-cli https://en.wikipedia.org/wiki/Main_Page
+```
+
+Or point it at your own site to see what's broken.
+
+### Common options
+
+```bash
+# Test login flows
+npx afterburn-cli https://your-site.com --email test@example.com --password mypass123
+
+# Hint at specific workflows
+npx afterburn-cli https://your-site.com --flows "signup, checkout, profile edit"
+
+# Map bugs to your source code (file:line)
+npx afterburn-cli https://your-site.com --source ./src
+
+# Watch the browser do its thing
+npx afterburn-cli https://your-site.com --no-headless
+```
+
+Reports are saved to `./afterburn-reports/{timestamp}/`.
+
+## How it works
+
+```
+Your URL --> Crawl all pages --> Plan test workflows --> Execute tests --> Analyze failures --> Generate reports
+```
+
+1. **Crawl** -- Discovers all pages, forms, buttons, and links. Handles SPAs (React, Next.js, Vue, Angular, Svelte).
+2. **Plan** -- AI generates smart test workflows (or heuristic fallback with no API key).
+3. **Execute** -- Runs each workflow in a real browser: fills forms, clicks buttons, captures screenshots.
+4. **Analyze** -- Diagnoses root causes. AI vision analysis with Gemini, or pattern matching without.
+5. **Report** -- Health score (0-100) and prioritized fix list in HTML + Markdown.
+
+### AI is optional
+
+Afterburn works **without any API keys**. Set `GEMINI_API_KEY` for smarter test planning and AI-powered diagnosis, but the core tool runs a full test suite either way.
+
+```bash
+# Optional: enable AI-powered planning and diagnosis
+export GEMINI_API_KEY=your-key-here
+```
+
+## How is this different?
+
+| Feature | Afterburn | Lighthouse | axe-core | Manual testing |
+|---------|-----------|------------|----------|----------------|
+| Zero config (no test writing) | Yes | Yes | Needs integration | Yes |
+| Crawls entire site | Yes | Single page | No | Tedious |
+| Form filling and submission | Yes | No | No | Manual |
+| Dead button detection | Yes | No | No | If you notice |
+| Plain English reports | Yes | Partial | No | N/A |
+| AI-ready report for auto-fix | Yes | No | No | No |
+| Free and open source | Yes | Yes | Yes | Free (your time) |
+| CI/CD integration | GitHub Action | CI plugin | CI plugin | No |
+
+## Health score
+
+The health score (0-100) is weighted:
+
+| Category | Weight | What it measures |
+|----------|--------|------------------|
+| Workflows | 40% | Did test workflows complete without errors? |
+| Errors | 30% | HTTP errors, console crashes, broken resources |
+| Accessibility | 20% | WCAG 2.1 AA violations |
+| Performance | 10% | Page load times, LCP scores |
+
+## Pre-flight check
+
+```bash
+npx afterburn-cli doctor
+```
+
+Checks Node.js version, browser installation, API key, and network connectivity.
+
+## Testing
+
+```bash
+# Build CLI + bundled GitHub Action artifacts
+npm run build:release
+
+# Fast default lane (unit tests)
+npm test
+
+# Deterministic end-to-end lane (local fixture server)
+npm run test:e2e
+
+# Unit coverage gate with thresholds
+npm run test:coverage
+
+# Optional real-internet smoke test (only runs when URL is provided)
+AFTERBURN_EXTERNAL_SMOKE_URL=https://example.com npm run test:smoke:external
+```
+
+## CLI reference
+
+```
+Usage: afterburn [options] [command] <url>
+
+Automated testing for vibe-coded websites
+
+Arguments:
+  url                    URL to test
+
+Options:
+  -V, --version          output the version number
+  --source <path>        Source code directory for pinpointing bugs
+  --email <email>        Login email (or set AFTERBURN_EMAIL env var)
+  --password <password>  Login password (tip: use AFTERBURN_PASSWORD env var
+                         to avoid shell history exposure)
+  --output-dir <path>    Custom output directory
+                         (default: ./afterburn-reports/{timestamp})
+  --flows <hints>        Comma-separated workflow hints (e.g., "signup, checkout")
+  --max-pages <n>        Max pages to crawl (default: 50, max: 500)
+  --no-headless          Show browser window (useful for debugging)
+  --verbose              Show detailed progress output
+  -h, --help             display help for command
+
+Commands:
+  doctor                 Check if your environment is ready to run Afterburn
+```
+
+## Known limitations
+
+- **Visual analysis requires GEMINI_API_KEY**. Without it, UI analysis relies on axe-core plus pattern matching.
+- **SPA support is experimental**. Complex client-side routing may not be fully exercised.
+- **Desktop viewport only**. Tests run at 1920x1080. Mobile testing planned for v2.
+
+## Three interfaces
+
+### CLI
+
+```bash
+npx afterburn-cli https://your-site.com
+```
+
+### GitHub Action
+
+```yaml
+name: Afterburn
+on: [pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: gods-strongest-vibecoder/afterburn@main
+        with:
+          url: https://your-staging-site.com
+          fail-on: high
+```
+
+Posts a summary comment on your PR and uploads reports as artifacts.
+
+### MCP Server (for AI coding assistants)
+
+```json
+{
+  "mcpServers": {
+    "afterburn": {
+      "command": "npx",
+      "args": ["afterburn-mcp"]
+    }
+  }
+}
+```
+
+Exposes a `scan_website` tool that returns structured results your AI assistant can act on.
+
+## Tech stack
+
+[Playwright](https://playwright.dev/) (browser automation) | [Gemini 2.5 Flash](https://ai.google.dev/) (AI vision, optional) | [axe-core](https://github.com/dequelabs/axe-core) (accessibility) | [Commander.js](https://github.com/tj/commander.js) (CLI) | [Handlebars](https://handlebarsjs.com/) (HTML reports) | [ts-morph](https://github.com/dsherret/ts-morph) (source mapping) | [sharp](https://sharp.pixelplumbing.com/) (screenshot compression)
+
+## License
+
+MIT
+
+Built for the [BridgeMind Vibeathon 2026](https://bridgemind.dev).

package/dist/ai/gemini-client.d.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+/**
+ * Reusable Gemini 2.5 Flash client for structured and unstructured generation.
+ * Used for workflow planning (Phase 2), error diagnosis (Phase 4), and report generation (Phase 5).
+ */
+export declare class GeminiClient {
+    private model;
+    constructor(apiKey?: string);
+    /**
+     * Generate structured JSON output validated against a Zod schema
+     */
+    generateStructured<T>(prompt: string, schema: z.ZodType<T>): Promise<T>;
+    /**
+     * Generate plain text response (no schema constraints)
+     */
+    generateText(prompt: string): Promise<string>;
+    /**
+     * Generate structured JSON output with image input (multimodal)
+     */
+    generateStructuredWithImage<T>(prompt: string, schema: z.ZodType<T>, imagePath: string): Promise<T>;
+}

package/dist/ai/gemini-client.js

@@ -0,0 +1,105 @@
+// Gemini 2.5 Flash API client with structured JSON output support
+import { GoogleGenerativeAI } from '@google/generative-ai';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import fs from 'node:fs';
+/**
+ * Reusable Gemini 2.5 Flash client for structured and unstructured generation.
+ * Used for workflow planning (Phase 2), error diagnosis (Phase 4), and report generation (Phase 5).
+ */
+export class GeminiClient {
+    model;
+    constructor(apiKey) {
+        const key = apiKey || process.env.GEMINI_API_KEY;
+        if (!key) {
+            throw new Error('GEMINI_API_KEY not set. Get one at https://aistudio.google.com/apikey');
+        }
+        const genAI = new GoogleGenerativeAI(key);
+        this.model = genAI.getGenerativeModel({ model: 'gemini-2.5-flash' });
+    }
+    /**
+     * Generate structured JSON output validated against a Zod schema
+     */
+    async generateStructured(prompt, schema) {
+        try {
+            // Convert Zod schema to JSON Schema for Gemini
+            const jsonSchema = zodToJsonSchema(schema, { name: 'ResponseSchema' });
+            // Configure model for structured JSON output
+            const result = await this.model.generateContent({
+                contents: [{ role: 'user', parts: [{ text: prompt }] }],
+                generationConfig: {
+                    responseMimeType: 'application/json',
+                    responseSchema: jsonSchema,
+                },
+            });
+            // Extract text response
+            const responseText = result.response.text();
+            // Parse JSON
+            const jsonData = JSON.parse(responseText);
+            // Validate against Zod schema
+            const validated = schema.parse(jsonData);
+            return validated;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Gemini API error: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Generate plain text response (no schema constraints)
+     */
+    async generateText(prompt) {
+        try {
+            const result = await this.model.generateContent(prompt);
+            return result.response.text();
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Gemini API error: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Generate structured JSON output with image input (multimodal)
+     */
+    async generateStructuredWithImage(prompt, schema, imagePath) {
+        try {
+            // Read image file as base64
+            const base64Data = fs.readFileSync(imagePath, { encoding: 'base64' });
+            // Convert Zod schema to JSON Schema for Gemini
+            const jsonSchema = zodToJsonSchema(schema, { name: 'ResponseSchema' });
+            // Configure model for structured JSON output with image
+            const result = await this.model.generateContent({
+                contents: [
+                    {
+                        role: 'user',
+                        parts: [
+                            { text: prompt },
+                            { inlineData: { mimeType: 'image/png', data: base64Data } },
+                        ],
+                    },
+                ],
+                generationConfig: {
+                    responseMimeType: 'application/json',
+                    responseSchema: jsonSchema,
+                },
+            });
+            // Extract text response
+            const responseText = result.response.text();
+            // Parse JSON
+            const jsonData = JSON.parse(responseText);
+            // Validate against Zod schema
+            const validated = schema.parse(jsonData);
+            return validated;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Gemini API error: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=gemini-client.js.map

package/dist/ai/gemini-client.js.map

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

package/dist/ai/index.d.ts

@@ -0,0 +1 @@
+export { GeminiClient } from './gemini-client.js';

package/dist/ai/index.js

@@ -0,0 +1,3 @@
+// AI module barrel exports
+export { GeminiClient } from './gemini-client.js';
+//# sourceMappingURL=index.js.map

package/dist/ai/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ai/index.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAE3B,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/analysis/diagnosis-schema.d.ts

@@ -0,0 +1,106 @@
+import { z } from 'zod';
+import { ArtifactMetadata } from '../types/artifacts.js';
+/**
+ * Individual error diagnosis from LLM or fallback pattern matching
+ */
+export declare const ErrorDiagnosisSchema: z.ZodObject<{
+    summary: z.ZodString;
+    rootCause: z.ZodString;
+    errorType: z.ZodEnum<{
+        form: "form";
+        navigation: "navigation";
+        unknown: "unknown";
+        authentication: "authentication";
+        network: "network";
+        javascript: "javascript";
+        dom: "dom";
+    }>;
+    confidence: z.ZodEnum<{
+        high: "high";
+        medium: "medium";
+        low: "low";
+    }>;
+    suggestedFix: z.ZodString;
+    technicalDetails: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ErrorDiagnosis = z.infer<typeof ErrorDiagnosisSchema>;
+/**
+ * Batch response schema for diagnosing multiple errors in a single LLM call
+ */
+export declare const ErrorDiagnosisBatchSchema: z.ZodObject<{
+    diagnoses: z.ZodArray<z.ZodObject<{
+        rootCause: z.ZodString;
+        plainEnglish: z.ZodString;
+        suggestedFix: z.ZodString;
+        severity: z.ZodEnum<{
+            high: "high";
+            medium: "medium";
+            low: "low";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ErrorDiagnosisBatch = z.infer<typeof ErrorDiagnosisBatchSchema>;
+/**
+ * UI audit findings from vision LLM analysis
+ */
+export declare const UIAuditSchema: z.ZodObject<{
+    layoutIssues: z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+        severity: z.ZodEnum<{
+            high: "high";
+            medium: "medium";
+            low: "low";
+        }>;
+        location: z.ZodString;
+    }, z.core.$strip>>;
+    contrastIssues: z.ZodArray<z.ZodObject<{
+        element: z.ZodString;
+        issue: z.ZodString;
+        suggestion: z.ZodString;
+    }, z.core.$strip>>;
+    formattingIssues: z.ZodArray<z.ZodObject<{
+        problem: z.ZodString;
+        suggestion: z.ZodString;
+    }, z.core.$strip>>;
+    improvements: z.ZodArray<z.ZodString>;
+    overallScore: z.ZodEnum<{
+        good: "good";
+        "needs-work": "needs-work";
+        poor: "poor";
+    }>;
+}, z.core.$strip>;
+export type UIAudit = z.infer<typeof UIAuditSchema>;
+/**
+ * Source code location for an error (populated by source mapper in Plan 04-03)
+ */
+export declare const SourceLocationSchema: z.ZodObject<{
+    file: z.ZodString;
+    line: z.ZodNumber;
+    context: z.ZodString;
+}, z.core.$strip>;
+export type SourceLocation = z.infer<typeof SourceLocationSchema>;
+/**
+ * Diagnosed error with original message for source mapping
+ */
+export interface DiagnosedError extends ErrorDiagnosis {
+    originalError: string;
+    sourceLocation?: SourceLocation;
+    screenshotRef?: string;
+    pageUrl?: string;
+}
+/**
+ * UI audit result for a specific page
+ */
+export interface UIAuditResult extends UIAudit {
+    pageUrl: string;
+    screenshotRef?: string;
+}
+/**
+ * Complete analysis artifact (output of Phase 4)
+ */
+export interface AnalysisArtifact extends ArtifactMetadata {
+    diagnosedErrors: DiagnosedError[];
+    uiAudits: UIAuditResult[];
+    sourceAnalysisAvailable: boolean;
+    aiPowered: boolean;
+}

package/dist/analysis/diagnosis-schema.js

@@ -0,0 +1,54 @@
+// Zod schemas for Phase 4 error diagnosis, UI auditing, and analysis artifacts
+import { z } from 'zod';
+/**
+ * Individual error diagnosis from LLM or fallback pattern matching
+ */
+export const ErrorDiagnosisSchema = z.object({
+    summary: z.string().describe('One-sentence plain English summary of what went wrong'),
+    rootCause: z.string().describe('Plain English explanation of the root cause'),
+    errorType: z.enum(['network', 'javascript', 'dom', 'form', 'navigation', 'authentication', 'unknown']),
+    confidence: z.enum(['high', 'medium', 'low']),
+    suggestedFix: z.string().describe('Actionable next step in plain English'),
+    technicalDetails: z.string().optional().describe('Technical details for developers'),
+});
+/**
+ * Batch response schema for diagnosing multiple errors in a single LLM call
+ */
+export const ErrorDiagnosisBatchSchema = z.object({
+    diagnoses: z.array(z.object({
+        rootCause: z.string().describe('Plain English explanation of the root cause'),
+        plainEnglish: z.string().describe('One-sentence plain English summary of what went wrong'),
+        suggestedFix: z.string().describe('Actionable next step in plain English'),
+        severity: z.enum(['high', 'medium', 'low']).describe('Severity of the error'),
+    })).describe('One diagnosis per error, in the same order as the input errors'),
+});
+/**
+ * UI audit findings from vision LLM analysis
+ */
+export const UIAuditSchema = z.object({
+    layoutIssues: z.array(z.object({
+        description: z.string(),
+        severity: z.enum(['high', 'medium', 'low']),
+        location: z.string(),
+    })),
+    contrastIssues: z.array(z.object({
+        element: z.string(),
+        issue: z.string(),
+        suggestion: z.string(),
+    })),
+    formattingIssues: z.array(z.object({
+        problem: z.string(),
+        suggestion: z.string(),
+    })),
+    improvements: z.array(z.string()).describe('Plain English improvement suggestions'),
+    overallScore: z.enum(['good', 'needs-work', 'poor']),
+});
+/**
+ * Source code location for an error (populated by source mapper in Plan 04-03)
+ */
+export const SourceLocationSchema = z.object({
+    file: z.string(),
+    line: z.number(),
+    context: z.string().describe('First ~200 chars of relevant code'),
+});
+//# sourceMappingURL=diagnosis-schema.js.map

package/dist/analysis/diagnosis-schema.js.map

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

package/dist/analysis/error-analyzer.d.ts

@@ -0,0 +1,9 @@
+import { ExecutionArtifact } from '../types/execution.js';
+import { DiagnosedError } from './diagnosis-schema.js';
+/**
+ * Main export: Analyze all errors from ExecutionArtifact and produce plain English diagnoses
+ */
+export declare function analyzeErrors(artifact: ExecutionArtifact, options?: {
+    apiKey?: string;
+    aiEnabled?: boolean;
+}): Promise<DiagnosedError[]>;