qai-cli 3.0.0

package/src/capture.js

@@ -0,0 +1,133 @@
+const { chromium } = require('playwright');
+const fs = require('fs').promises;
+const path = require('path');
+
+const VIEWPORTS = {
+  desktop: { width: 1920, height: 1080 },
+  tablet: { width: 768, height: 1024 },
+  mobile: { width: 375, height: 667 },
+};
+
+/**
+ * Capture page data for QA analysis
+ * @param {string} url - URL to test
+ * @param {Object} options - Capture options
+ * @returns {Promise<Object>} Capture data
+ */
+async function capturePage(url, options = {}) {
+  const {
+    viewports = ['desktop', 'mobile'],
+    timeout = 30000,
+    screenshotDir = './screenshots',
+  } = options;
+
+  // Ensure screenshot directory exists
+  await fs.mkdir(screenshotDir, { recursive: true });
+
+  const browser = await chromium.launch({
+    headless: true,
+    args: ['--no-sandbox', '--disable-setuid-sandbox'],
+  });
+
+  const captureData = {
+    pageUrl: url,
+    pageTitle: '',
+    screenshots: [],
+    consoleErrors: [],
+    consoleWarnings: [],
+    networkErrors: [],
+    networkRequests: [],
+    timestamp: new Date().toISOString(),
+  };
+
+  try {
+    const context = await browser.newContext();
+    const page = await context.newPage();
+
+    // Collect console messages
+    page.on('console', (msg) => {
+      const type = msg.type();
+      const text = msg.text();
+
+      if (type === 'error') {
+        captureData.consoleErrors.push(text);
+      } else if (type === 'warning') {
+        captureData.consoleWarnings.push(text);
+      }
+    });
+
+    // Collect network errors
+    page.on('requestfailed', (request) => {
+      captureData.networkErrors.push({
+        url: request.url(),
+        method: request.method(),
+        failure: request.failure()?.errorText || 'Unknown error',
+      });
+    });
+
+    // Collect all network requests for analysis
+    page.on('response', (response) => {
+      const status = response.status();
+      if (status >= 400) {
+        captureData.networkErrors.push({
+          url: response.url(),
+          status,
+          statusText: response.statusText(),
+          method: response.request().method(),
+        });
+      }
+    });
+
+    // Navigate to the page
+    console.log(`Navigating to ${url}...`);
+    await page.goto(url, {
+      waitUntil: 'networkidle',
+      timeout,
+    });
+
+    // Get page title
+    captureData.pageTitle = await page.title();
+    console.log(`Page title: ${captureData.pageTitle}`);
+
+    // Wait a bit for any lazy-loaded content
+    await page.waitForTimeout(1000);
+
+    // Capture screenshots at each viewport
+    for (const viewportName of viewports) {
+      const viewport = VIEWPORTS[viewportName];
+      if (!viewport) {
+        console.warn(`Unknown viewport: ${viewportName}, skipping`);
+        continue;
+      }
+
+      console.log(`Capturing ${viewportName} (${viewport.width}x${viewport.height})...`);
+
+      await page.setViewportSize(viewport);
+      await page.waitForTimeout(500); // Let layout settle
+
+      const screenshotPath = path.join(screenshotDir, `${viewportName}.png`);
+      const buffer = await page.screenshot({
+        path: screenshotPath,
+        fullPage: false,
+      });
+
+      captureData.screenshots.push({
+        viewport: viewportName,
+        width: viewport.width,
+        height: viewport.height,
+        path: screenshotPath,
+        buffer,
+      });
+    }
+
+    console.log(`Captured ${captureData.screenshots.length} screenshots`);
+    console.log(`Console errors: ${captureData.consoleErrors.length}`);
+    console.log(`Network errors: ${captureData.networkErrors.length}`);
+  } finally {
+    await browser.close();
+  }
+
+  return captureData;
+}
+
+module.exports = { capturePage, VIEWPORTS };

package/src/index.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+
+const fs = require('fs').promises;
+const { capturePage } = require('./capture');
+const { getProvider } = require('./providers');
+
+async function main() {
+  const startTime = Date.now();
+
+  // Get configuration from environment (standard format first, then INPUT_ format for GitHub Actions)
+  const url = process.env.URL || process.env.INPUT_URL;
+  const viewportsRaw = process.env.VIEWPORTS || process.env.INPUT_VIEWPORTS || 'desktop,mobile';
+  const focus = process.env.FOCUS || process.env.INPUT_FOCUS || 'all';
+  const timeout = parseInt(process.env.TIMEOUT || process.env.INPUT_TIMEOUT || '300', 10) * 1000;
+  const outputFormat = process.env.OUTPUT_FORMAT || process.env.INPUT_OUTPUT_FORMAT || 'markdown';
+
+  if (!url) {
+    console.error('Error: URL is required (set URL or INPUT_URL env var)');
+    process.exit(1);
+  }
+
+  const viewports = viewportsRaw.split(',').map((v) => v.trim().toLowerCase());
+
+  console.log('='.repeat(60));
+  console.log('qai');
+  console.log('='.repeat(60));
+  console.log(`URL: ${url}`);
+  console.log(`Viewports: ${viewports.join(', ')}`);
+  console.log(`Focus: ${focus}`);
+  console.log('='.repeat(60));
+
+  try {
+    // Get the provider (auto-detected from env vars)
+    const provider = getProvider();
+
+    // Step 1: Capture page data
+    console.log('\n[1/3] Capturing page data...');
+    const captureData = await capturePage(url, {
+      viewports,
+      timeout,
+      screenshotDir: './screenshots',
+    });
+
+    // Step 2: Analyze with LLM
+    console.log('\n[2/3] Analyzing with AI...');
+    const report = await provider.analyze(captureData, { focus });
+
+    // Step 3: Generate report
+    console.log('\n[3/3] Generating report...');
+
+    // Add metadata to report
+    report.metadata = {
+      url: captureData.pageUrl,
+      title: captureData.pageTitle,
+      timestamp: captureData.timestamp,
+      viewports,
+      focus,
+      consoleErrorCount: captureData.consoleErrors.length,
+      networkErrorCount: captureData.networkErrors.length,
+      duration: `${((Date.now() - startTime) / 1000).toFixed(1)}s`,
+    };
+
+    // Include raw errors in report
+    report.consoleErrors = captureData.consoleErrors;
+    report.networkErrors = captureData.networkErrors;
+
+    // Save report
+    if (outputFormat === 'json' || outputFormat === 'all') {
+      await fs.writeFile('qa-report.json', JSON.stringify(report, null, 2));
+      console.log('Saved: qa-report.json');
+    }
+
+    if (outputFormat === 'markdown' || outputFormat === 'all') {
+      const markdown = generateMarkdownReport(report);
+      await fs.writeFile('qa-report.md', markdown);
+      console.log('Saved: qa-report.md');
+    }
+
+    // Print summary
+    console.log('\n' + '='.repeat(60));
+    console.log('QA Report Summary');
+    console.log('='.repeat(60));
+    console.log(`Score: ${report.score !== null ? report.score + '/100' : 'N/A'}`);
+    console.log(`Bugs found: ${report.bugs?.length || 0}`);
+
+    if (report.bugs?.length > 0) {
+      const critical = report.bugs.filter((b) => b.severity === 'critical').length;
+      const high = report.bugs.filter((b) => b.severity === 'high').length;
+      const medium = report.bugs.filter((b) => b.severity === 'medium').length;
+      const low = report.bugs.filter((b) => b.severity === 'low').length;
+
+      console.log(`  - Critical: ${critical}`);
+      console.log(`  - High: ${high}`);
+      console.log(`  - Medium: ${medium}`);
+      console.log(`  - Low: ${low}`);
+    }
+
+    console.log(`Duration: ${report.metadata.duration}`);
+    console.log('='.repeat(60));
+
+    // Set outputs for GitHub Actions
+    if (process.env.GITHUB_OUTPUT) {
+      const outputs = [
+        `report=qa-report.${outputFormat === 'json' ? 'json' : 'md'}`,
+        'screenshots=./screenshots',
+        `bugs_found=${report.bugs?.length || 0}`,
+        `critical_bugs=${report.bugs?.filter((b) => ['critical', 'high'].includes(b.severity)).length || 0}`,
+      ];
+
+      await fs.appendFile(process.env.GITHUB_OUTPUT, outputs.join('\n') + '\n');
+    }
+  } catch (error) {
+    console.error('\nError:', error.message);
+    console.error(error.stack);
+    process.exit(1);
+  }
+}
+
+function generateMarkdownReport(report) {
+  const lines = [];
+
+  lines.push('# QA Report');
+  lines.push('');
+  lines.push(`**URL:** ${report.metadata.url}`);
+  lines.push(`**Title:** ${report.metadata.title}`);
+  lines.push(`**Date:** ${report.metadata.timestamp}`);
+  lines.push(`**Duration:** ${report.metadata.duration}`);
+  lines.push(`**Score:** ${report.score !== null ? report.score + '/100' : 'N/A'}`);
+  lines.push('');
+
+  lines.push('## Summary');
+  lines.push('');
+  lines.push(report.summary || 'No summary provided.');
+  lines.push('');
+
+  if (report.bugs?.length > 0) {
+    lines.push('## Bugs Found');
+    lines.push('');
+
+    for (const bug of report.bugs) {
+      const severityEmoji =
+        {
+          critical: '🔴',
+          high: '🟠',
+          medium: '🟡',
+          low: '🟢',
+        }[bug.severity] || '⚪';
+
+      lines.push(`### ${severityEmoji} ${bug.title}`);
+      lines.push('');
+      lines.push(`**Severity:** ${bug.severity}`);
+      lines.push(`**Category:** ${bug.category}`);
+      if (bug.viewport) {
+        lines.push(`**Viewport:** ${bug.viewport}`);
+      }
+      lines.push('');
+      lines.push(bug.description);
+      lines.push('');
+      if (bug.recommendation) {
+        lines.push(`**Recommendation:** ${bug.recommendation}`);
+        lines.push('');
+      }
+    }
+  } else {
+    lines.push('## Bugs Found');
+    lines.push('');
+    lines.push('No bugs found.');
+    lines.push('');
+  }
+
+  if (report.consoleErrors?.length > 0) {
+    lines.push('## Console Errors');
+    lines.push('');
+    for (const error of report.consoleErrors) {
+      lines.push(`- ${error}`);
+    }
+    lines.push('');
+  }
+
+  if (report.networkErrors?.length > 0) {
+    lines.push('## Network Errors');
+    lines.push('');
+    for (const error of report.networkErrors) {
+      lines.push(`- \`${error.method || 'GET'} ${error.url}\`: ${error.status || error.failure}`);
+    }
+    lines.push('');
+  }
+
+  if (report.recommendations?.length > 0) {
+    lines.push('## Recommendations');
+    lines.push('');
+    for (const rec of report.recommendations) {
+      lines.push(`- ${rec}`);
+    }
+    lines.push('');
+  }
+
+  lines.push('---');
+  lines.push('*Generated by [qai](https://github.com/tyler-james-bridges/qaie)*');
+
+  return lines.join('\n');
+}
+
+main();

package/src/providers/anthropic.js

@@ -0,0 +1,59 @@
+const Anthropic = require('@anthropic-ai/sdk');
+const BaseProvider = require('./base');
+
+class AnthropicProvider extends BaseProvider {
+  constructor(apiKey, options = {}) {
+    super(apiKey, options);
+    this.client = new Anthropic({ apiKey });
+    this.model = options.model || 'claude-sonnet-4-20250514';
+  }
+
+  async analyze(captureData, options = {}) {
+    const prompt = this.buildPrompt(captureData, options);
+
+    // Build content array with images
+    const content = [];
+
+    // Add screenshots as images
+    for (const screenshot of captureData.screenshots) {
+      content.push({
+        type: 'image',
+        source: {
+          type: 'base64',
+          media_type: 'image/png',
+          data: screenshot.buffer.toString('base64'),
+        },
+      });
+      content.push({
+        type: 'text',
+        text: `[Screenshot: ${screenshot.viewport} - ${screenshot.width}x${screenshot.height}]`,
+      });
+    }
+
+    // Add the analysis prompt
+    content.push({
+      type: 'text',
+      text: prompt,
+    });
+
+    const response = await this.client.messages.create({
+      model: this.model,
+      max_tokens: 4096,
+      messages: [
+        {
+          role: 'user',
+          content,
+        },
+      ],
+    });
+
+    const responseText = response.content
+      .filter((block) => block.type === 'text')
+      .map((block) => block.text)
+      .join('\n');
+
+    return this.parseResponse(responseText);
+  }
+}
+
+module.exports = AnthropicProvider;

package/src/providers/base.js

@@ -0,0 +1,164 @@
+/**
+ * Base provider class - defines the interface for all LLM providers
+ */
+class BaseProvider {
+  constructor(apiKey, options = {}) {
+    this.apiKey = apiKey;
+    this.options = options;
+  }
+
+  /**
+   * Analyze page capture data and return QA findings
+   * @param {Object} captureData - Page capture data
+   * @param {Object} options - Analysis options
+   * @returns {Promise<Object>} QA report
+   */
+  // eslint-disable-next-line no-unused-vars
+  async analyze(captureData, options = {}) {
+    throw new Error('analyze() must be implemented by subclass');
+  }
+
+  /**
+   * Build the analysis prompt with focus-specific guidance
+   */
+  buildPrompt(captureData, options) {
+    const { focus = 'all' } = options;
+
+    const focusGuidance = FOCUS_PROMPTS[focus] || FOCUS_PROMPTS.all;
+
+    const ariaSection = captureData.ariaSnapshot
+      ? `\n## ARIA / Accessibility Tree\n\`\`\`\n${captureData.ariaSnapshot}\n\`\`\``
+      : '';
+
+    const domSection = captureData.domSummary ? `\n## DOM Summary\n${captureData.domSummary}` : '';
+
+    return `You are an expert QA engineer analyzing a webpage. Be concise and actionable. Report real issues only — do not invent problems.
+
+## Page Information
+- URL: ${captureData.pageUrl}
+- Title: ${captureData.pageTitle}
+
+## Console Errors (${captureData.consoleErrors.length})
+${
+  captureData.consoleErrors.length > 0
+    ? captureData.consoleErrors.map((e) => `- ${e}`).join('\n')
+    : 'None detected'
+}
+
+## Network Errors (${captureData.networkErrors.length})
+${
+  captureData.networkErrors.length > 0
+    ? captureData.networkErrors.map((e) => `- ${e.url}: ${e.status} ${e.statusText}`).join('\n')
+    : 'None detected'
+}
+
+## Screenshots Provided
+${captureData.screenshots.map((s) => `- ${s.viewport}: ${s.width}x${s.height}`).join('\n')}
+
+## Focus Area: ${focus}
+${focusGuidance}
+
+Report issues in this JSON format:
+{
+  "summary": "Brief overall assessment",
+  "bugs": [
+    {
+      "severity": "critical|high|medium|low",
+      "category": "visual|functional|accessibility|performance|console|network|responsive",
+      "title": "Short description",
+      "description": "Detailed explanation with specific element references",
+      "viewport": "which viewport (if applicable)",
+      "recommendation": "How to fix"
+    }
+  ],
+  "score": 0-100,
+  "recommendations": ["List of general improvements"]
+}
+
+Only report actual issues. If the page looks good, say so with an empty bugs array and a high score.
+Respond with ONLY the JSON, no markdown code blocks.`;
+  }
+
+  /**
+   * Parse LLM response into structured report
+   */
+  parseResponse(response) {
+    try {
+      let jsonStr = response.trim();
+
+      // Remove markdown code blocks if present
+      if (jsonStr.startsWith('```')) {
+        jsonStr = jsonStr.replace(/```json?\n?/g, '').replace(/```\n?$/g, '');
+      }
+
+      return JSON.parse(jsonStr);
+    } catch (error) {
+      return {
+        summary: 'Failed to parse LLM response',
+        bugs: [],
+        score: null,
+        recommendations: [],
+        raw_response: response,
+        parse_error: error.message,
+      };
+    }
+  }
+}
+
+/**
+ * Focus-specific prompt guidance
+ */
+const FOCUS_PROMPTS = {
+  all:
+    'Check everything: visual consistency, responsiveness across viewports, ' +
+    'accessibility, console/network errors, interactive element states, ' +
+    'text readability, contrast, layout issues, and broken functionality.',
+
+  accessibility: `Focus on accessibility issues:
+- Missing or incorrect ARIA labels/roles
+- Color contrast failures (WCAG AA minimum 4.5:1 for text)
+- Missing alt text on images
+- Keyboard navigation issues (tab order, focus indicators)
+- Screen reader compatibility (heading hierarchy, landmark regions)
+- Form labels and error messages
+- Touch target sizes (minimum 44x44px)`,
+
+  visual: `Focus on visual and design issues:
+- Layout breaks or misalignment across viewports
+- Overlapping elements
+- Inconsistent spacing, padding, margins
+- Text truncation or overflow
+- Dark mode / light mode rendering problems
+- Font rendering issues
+- Image quality and sizing
+- Z-index stacking issues`,
+
+  responsive: `Focus on responsive design:
+- Layout differences between mobile, tablet, and desktop
+- Elements that overflow or get cut off on smaller screens
+- Touch targets too small on mobile
+- Text that's too small to read on mobile
+- Navigation usability on mobile (hamburger menu, etc.)
+- Horizontal scrolling on mobile (usually a bug)
+- Images not scaling properly`,
+
+  forms: `Focus on form usability:
+- Input field labels and placeholders
+- Validation feedback (inline errors, success states)
+- Required field indicators
+- Tab order between fields
+- Submit button states (disabled, loading, success, error)
+- Auto-fill compatibility
+- Mobile keyboard types (email, number, tel)`,
+
+  performance: `Focus on performance indicators visible in the page:
+- Lazy loading implementation
+- Image optimization (large uncompressed images)
+- Render-blocking resources
+- Layout shifts (elements moving after load)
+- Loading states and skeletons
+- Excessive DOM elements
+- Console warnings about performance`,
+};
+
+module.exports = BaseProvider;

package/src/providers/gemini.js

@@ -0,0 +1,42 @@
+const { GoogleGenerativeAI } = require('@google/generative-ai');
+const BaseProvider = require('./base');
+
+class GeminiProvider extends BaseProvider {
+  constructor(apiKey, options = {}) {
+    super(apiKey, options);
+    this.genAI = new GoogleGenerativeAI(apiKey);
+    this.model = options.model || 'gemini-1.5-flash';
+  }
+
+  async analyze(captureData, options = {}) {
+    const prompt = this.buildPrompt(captureData, options);
+    const model = this.genAI.getGenerativeModel({ model: this.model });
+
+    // Build content array with images
+    const parts = [];
+
+    // Add screenshots as images
+    for (const screenshot of captureData.screenshots) {
+      parts.push({
+        inlineData: {
+          mimeType: 'image/png',
+          data: screenshot.buffer.toString('base64'),
+        },
+      });
+      parts.push({
+        text: `[Screenshot: ${screenshot.viewport} - ${screenshot.width}x${screenshot.height}]`,
+      });
+    }
+
+    // Add the analysis prompt
+    parts.push({ text: prompt });
+
+    const result = await model.generateContent(parts);
+    const response = await result.response;
+    const responseText = response.text();
+
+    return this.parseResponse(responseText);
+  }
+}
+
+module.exports = GeminiProvider;