qa-toolkit-ai 1.0.0

package/README.md

@@ -0,0 +1,146 @@
+# QA Toolkit
+
+AI-powered QA toolkit that runs automated quality analysis on your codebase and produces a browsable dashboard with findings, screenshots, and videos.
+
+```
+     ___    _     _____           _ _    _ _
+    / _ \  / \   |_   _|__   ___ | | | _(_) |_
+   | | | |/ _ \    | |/ _ \ / _ \| | |/ / | __|
+   | |_| / ___ \   | | (_) | (_) | |   <| | |_
+    \__\_\_/   \_\  |_|\___/ \___/|_|_|\_\_|\__|
+```
+
+## What it does
+
+- Runs **3 parallel QA agents** (Frontend, Backend, E2E) that analyze your codebase
+- Produces a **Docsify dashboard** with all findings, organized and filterable
+- Splits findings into **Functional** (for PM/client) and **Technical** (for devs)
+- Generates fix lists, Jira-ready tickets, Confluence checklists
+- Captures **screenshots** at desktop/tablet/mobile and **E2E videos**
+- Creates a **shareable public link** via Cloudflare tunnel
+
+## Install
+
+### Option A: npm (recommended)
+
+```bash
+npx qa-toolkit-ai init
+```
+
+This copies the QA skills, rules, and Docsify template into your project's `.cursor/` directory.
+
+### Option B: Clone + install script
+
+```bash
+git clone https://github.com/L-ubu/qa-toolkit.git /tmp/qa-toolkit
+bash /tmp/qa-toolkit/install.sh /path/to/your/project
+```
+
+### Option C: GitHub template
+
+Use this repo as a template and copy the contents into your project's `.cursor/`.
+
+## Usage
+
+### Run QA (in Cursor)
+
+Open your project in Cursor and say:
+
+```
+/qa
+```
+
+Or be specific:
+
+```
+/qa-frontend
+/qa-backend
+/qa-e2e
+```
+
+The agent will:
+1. Analyze your codebase (Frontend, Backend, E2E flows)
+2. Generate reports with severity classification (P0–P3)
+3. Build a Docsify dashboard in `qa-output/`
+4. Serve it locally and create a shareable link
+
+### CLI Commands
+
+```bash
+# Install QA skills into your project
+npx qa-toolkit-ai init
+
+# Scaffold a new qa-output/ from template
+npx qa-toolkit-ai scaffold "My Project" "feature/branch"
+
+# Serve the dashboard
+npx qa-toolkit-ai serve          # default port 3333
+npx qa-toolkit-ai serve 4000     # custom port
+
+# Share via public tunnel
+npx qa-toolkit-ai share
+```
+
+## What you get
+
+### For the PM / Client
+
+- **Functional Report** — plain-language descriptions of what users see and experience
+- **Functional Checklist** — checkbox list sorted by feature area for budget decisions
+- **Severity filter** — toggle P0/P1/P2/P3 visibility in the dashboard
+- **PDF export** — one-click print to PDF
+
+### For Developers
+
+- **Full Technical Report** — code paths, file references, fix suggestions
+- **Frontend / Backend / E2E Reports** — detailed per-area analysis
+- **Fix List** — grouped by component (Frontend → JS/React → Backend)
+- **Jira Tickets** — pre-formatted, ready to create via MCP or copy-paste
+
+### Media Evidence
+
+- **Screenshots** at desktop (1280px), tablet (768px), mobile (375px)
+- **E2E videos** at all three viewports
+- **Lightbox** for screenshot zoom, inline video playback
+
+## Project structure
+
+```
+qa-toolkit/
+├── bin/cli.js                    # CLI tool (init, serve, share, scaffold)
+├── skills/
+│   ├── qa-run/SKILL.md           # Orchestrator — runs all agents
+│   ├── qa-frontend/SKILL.md      # Frontend/UI analysis
+│   ├── qa-backend/SKILL.md       # Backend/API analysis
+│   ├── qa-e2e/SKILL.md           # E2E flow analysis
+│   └── qa-merge-report/SKILL.md  # Merges findings, builds dashboard
+├── rules/
+│   └── qa-report-format.mdc      # Report format rules for Cursor
+├── docsify-template/             # Reusable Docsify dashboard template
+│   ├── index.html                # Themed dashboard with filter + PDF
+│   ├── setup-docsify.sh          # Scaffold script
+│   ├── README.md                 # Dashboard template
+│   ├── _sidebar.md               # Navigation template
+│   ├── media.md                  # Screenshots/videos template
+│   ├── qa-functional-report.md   # Functional report template
+│   └── qa-functional-checklist.md # Functional checklist template
+├── install.sh                    # Standalone install script (no npm needed)
+├── package.json
+└── README.md
+```
+
+## Customisation
+
+### Project-specific QA structure
+
+Add a `.cursor/qa-reference/` directory with a markdown file describing your project's feature areas, test scenarios, and Confluence structure. The QA agents will use it to organise findings.
+
+Example: `.cursor/qa-reference/my-project-structure.md`
+
+### Docsify theme
+
+Edit `.cursor/qa-docsify-template/index.html` to change colors, fonts, or add features. The template uses CSS custom properties for easy theming.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+
+const { execSync, spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+const PKG_ROOT = path.resolve(__dirname, '..');
+const CWD = process.cwd();
+
+const SKILLS = ['qa-run', 'qa-frontend', 'qa-backend', 'qa-e2e', 'qa-merge-report'];
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function init() {
+  const cursorDir = path.join(CWD, '.cursor');
+  fs.mkdirSync(cursorDir, { recursive: true });
+
+  console.log('\n  QA Toolkit — Installing into .cursor/\n');
+
+  // Copy skills
+  for (const skill of SKILLS) {
+    const src = path.join(PKG_ROOT, 'skills', skill);
+    const dest = path.join(cursorDir, 'skills', skill);
+    fs.mkdirSync(dest, { recursive: true });
+    fs.copyFileSync(path.join(src, 'SKILL.md'), path.join(dest, 'SKILL.md'));
+    console.log(`  + .cursor/skills/${skill}/SKILL.md`);
+  }
+
+  // Copy rules
+  const rulesDir = path.join(cursorDir, 'rules');
+  fs.mkdirSync(rulesDir, { recursive: true });
+  fs.copyFileSync(
+    path.join(PKG_ROOT, 'rules', 'qa-report-format.mdc'),
+    path.join(rulesDir, 'qa-report-format.mdc')
+  );
+  console.log('  + .cursor/rules/qa-report-format.mdc');
+
+  // Copy docsify template
+  const templateSrc = path.join(PKG_ROOT, 'docsify-template');
+  const templateDest = path.join(cursorDir, 'qa-docsify-template');
+  copyDir(templateSrc, templateDest);
+  // Make setup script executable
+  const setupScript = path.join(templateDest, 'setup-docsify.sh');
+  if (fs.existsSync(setupScript)) {
+    fs.chmodSync(setupScript, '755');
+  }
+  console.log('  + .cursor/qa-docsify-template/');
+
+  console.log('\n  Done! Your project now has QA skills and templates.');
+  console.log('  Run /qa in Cursor to start a QA analysis.\n');
+}
+
+function serve(port) {
+  const outputDir = path.join(CWD, 'qa-output');
+  if (!fs.existsSync(outputDir)) {
+    console.error('\n  No qa-output/ directory found. Run a QA analysis first.\n');
+    process.exit(1);
+  }
+
+  console.log(`\n  Serving QA dashboard at http://localhost:${port}\n`);
+  const child = spawn('npx', ['docsify-cli', 'serve', outputDir, '--port', String(port)], {
+    stdio: 'inherit',
+    shell: true
+  });
+  child.on('error', () => {
+    console.error('  Failed to start docsify. Install it: npm i -g docsify-cli');
+  });
+}
+
+function share(port) {
+  console.log(`\n  Creating public tunnel to localhost:${port}...\n`);
+  const child = spawn('npx', ['cloudflared', 'tunnel', '--url', `http://localhost:${port}`], {
+    stdio: 'inherit',
+    shell: true
+  });
+  child.on('error', () => {
+    console.error('  Failed to start cloudflared tunnel.');
+  });
+}
+
+function scaffold(projectName, branch) {
+  const slug = (projectName || 'project').toLowerCase().replace(/[^a-z0-9]+/g, '-');
+  const date = new Date().toISOString().split('T')[0];
+  const templateScript = path.join(CWD, '.cursor', 'qa-docsify-template', 'setup-docsify.sh');
+
+  if (!fs.existsSync(templateScript)) {
+    console.error('\n  No .cursor/qa-docsify-template/ found. Run `qa-toolkit init` first.\n');
+    process.exit(1);
+  }
+
+  execSync(`bash "${templateScript}" qa-output "${projectName || 'Project'}" "${slug}" "${branch || 'main'}" "${date}" "Unknown"`, {
+    stdio: 'inherit',
+    cwd: CWD
+  });
+}
+
+function help() {
+  console.log(`
+  qa-toolkit — AI-powered QA toolkit
+
+  Commands:
+    init                    Install QA skills, rules, and templates into .cursor/
+    scaffold [name] [branch] Create qa-output/ directory from template
+    serve [port]            Serve the Docsify QA dashboard (default: 3333)
+    share [port]            Create a public Cloudflare tunnel (default: 3333)
+    help                    Show this help
+
+  Examples:
+    npx qa-toolkit-ai init
+    npx qa-toolkit-ai scaffold "My Project" "feature/branch"
+    npx qa-toolkit-ai serve
+    npx qa-toolkit-ai serve 4000
+    npx qa-toolkit-ai share
+  `);
+}
+
+switch (command) {
+  case 'init':
+    init();
+    break;
+  case 'scaffold':
+    scaffold(args[1], args[2]);
+    break;
+  case 'serve':
+    serve(args[1] || 3333);
+    break;
+  case 'share':
+    share(args[1] || 3333);
+    break;
+  case 'help':
+  case '--help':
+  case '-h':
+  case undefined:
+    help();
+    break;
+  default:
+    console.error(`  Unknown command: ${command}`);
+    help();
+    process.exit(1);
+}

package/docsify-template/README.md

@@ -0,0 +1,108 @@
+# QA Dashboard — {{PROJECT_NAME}}
+
+> **Branch:** `{{BRANCH}}` · **Date:** {{DATE}} · **Stack:** {{STACK}}
+
+---
+
+## At a Glance
+
+<div class="stats-grid">
+  <div class="stat-card">
+    <div class="number">{{TOTAL}}</div>
+    <div class="label">Total Findings</div>
+  </div>
+  <div class="stat-card critical">
+    <div class="number">{{P0_COUNT}}</div>
+    <div class="label">P0 Critical</div>
+  </div>
+  <div class="stat-card high">
+    <div class="number">{{P1_COUNT}}</div>
+    <div class="label">P1 High</div>
+  </div>
+  <div class="stat-card medium">
+    <div class="number">{{P2_COUNT}}</div>
+    <div class="label">P2 Medium</div>
+  </div>
+  <div class="stat-card low">
+    <div class="number">{{P3_COUNT}}</div>
+    <div class="label">P3 Low</div>
+  </div>
+</div>
+
+---
+
+## Two Views — Pick Your Lane
+
+This QA run produces **two separate views** of the same findings:
+
+| View | For whom | What it covers |
+|------|----------|----------------|
+| [**Functional Report**](qa-functional-report.md) | PM, client, non-technical stakeholders | What a user **sees and experiences** — broken buttons, wrong text, missing features, visual bugs, confusing flows. Written in plain language. |
+| [**Technical Report**](qa-report-{{PROJECT_SLUG}}-{{DATE}}.md) | Developers | Code-level root causes, file paths, API contracts, security issues, architecture problems. |
+
+> **PM tip:** Start with the [Functional Checklist](qa-functional-checklist.md) — it's sorted by feature area so you can quickly decide what matters most for the client, even with limited budget.
+
+---
+
+## Breakdown by Area
+
+| Area | Findings | P0 | P1 | P2 | P3 |
+|------|----------|----|----|----|----|
+| **Frontend** (design/styling) | {{FE_TOTAL}} | {{FE_P0}} | {{FE_P1}} | {{FE_P2}} | {{FE_P3}} |
+| **JS/React** (logic/state) | {{JS_TOTAL}} | {{JS_P0}} | {{JS_P1}} | {{JS_P2}} | {{JS_P3}} |
+| **Backend** (API/server) | {{BE_TOTAL}} | {{BE_P0}} | {{BE_P1}} | {{BE_P2}} | {{BE_P3}} |
+
+---
+
+## Functional vs Technical Split
+
+| Category | Count | Description |
+|----------|-------|-------------|
+| **Functional** | {{FUNCTIONAL_COUNT}} | User-visible: broken interactions, wrong text, visual bugs, missing features |
+| **Technical** | {{TECHNICAL_COUNT}} | Code-level: security, architecture, performance, developer-facing issues |
+
+---
+
+## All Reports
+
+| Report | Audience | Description |
+|--------|----------|-------------|
+| [Functional Report](qa-functional-report.md) | PM / Client | Plain-language findings about what users see and experience |
+| [Functional Checklist](qa-functional-checklist.md) | PM | Checkbox list sorted by feature — tick off what to fix given budget |
+| [Full QA Report](qa-report-{{PROJECT_SLUG}}-{{DATE}}.md) | Devs | Complete technical findings with code paths and suggestions |
+| [Frontend Report](qa-frontend-report.md) | Frontend devs | React components, styling, accessibility |
+| [Backend Report](qa-backend-report.md) | Backend devs | API, security, Drupal/Symfony |
+| [E2E Flow Report](e2e-flow-report.md) | QA / Devs | End-to-end user journey analysis |
+| [Fix List](qa-fix-list-{{PROJECT_SLUG}}-{{DATE}}.md) | Devs / PM | Prioritized fix table grouped by component |
+| [Jira Tickets](qa-jira-tickets-{{PROJECT_SLUG}}-{{DATE}}.md) | PM | Pre-formatted ticket content |
+| [Confluence Checklist](qa-confluence-checklist-{{PROJECT_SLUG}}-{{DATE}}.md) | Team | Full checklist for Confluence |
+
+---
+
+## Media Evidence
+
+| Type | Status |
+|------|--------|
+| [Screenshots](media.md#screenshots) | {{SCREENSHOTS_STATUS}} |
+| [E2E Desktop Video](media.md#e2e-desktop) | {{E2E_DESKTOP_STATUS}} |
+| [Mobile Viewport Video](media.md#mobile) | {{MOBILE_STATUS}} |
+| [Tablet Viewport Video](media.md#tablet) | {{TABLET_STATUS}} |
+
+---
+
+## Top Priority Fixes (P0)
+
+{{P0_TABLE}}
+
+---
+
+## How This Was Generated
+
+This QA dashboard was generated by **AI-powered cloud agents** running automated analysis:
+
+1. **Frontend Agent** — React components, CSS, accessibility, responsive screenshots at 3 viewports
+2. **Backend Agent** — API controllers, security, DTOs, event listeners
+3. **E2E Agent** — User flows with browser automation, video recordings at desktop/mobile/tablet
+4. **Merge Agent** — Deduplicated, classified functional vs technical, assembled Docsify dashboard
+
+*Generated: {{DATE}} · Branch: {{BRANCH}}*

package/docsify-template/_coverpage.md

@@ -0,0 +1,9 @@
+# {{PROJECT_NAME}} — QA Reports
+
+> Automated quality assurance reports powered by AI agents
+
+- Full-stack analysis: Frontend · Backend · E2E flows
+- Severity classification: P0 through P3
+- Screenshots, videos, and actionable fix lists
+
+[View Dashboard](#/)

package/docsify-template/_sidebar.md

@@ -0,0 +1,20 @@
+- **Overview**
+  - [Dashboard](/)
+
+- **Functional (PM / Client)**
+  - [Functional Report](qa-functional-report.md)
+  - [Functional Checklist](qa-functional-checklist.md)
+
+- **Technical (Devs)**
+  - [Full QA Report](qa-report-{{PROJECT_SLUG}}-{{DATE}}.md)
+  - [Frontend Report](qa-frontend-report.md)
+  - [Backend Report](qa-backend-report.md)
+  - [E2E Flow Report](e2e-flow-report.md)
+
+- **Action Items**
+  - [Fix List](qa-fix-list-{{PROJECT_SLUG}}-{{DATE}}.md)
+  - [Jira Tickets](qa-jira-tickets-{{PROJECT_SLUG}}-{{DATE}}.md)
+  - [Confluence Checklist](qa-confluence-checklist-{{PROJECT_SLUG}}-{{DATE}}.md)
+
+- **Media**
+  - [Screenshots & Videos](media.md)