Punchlist QA

Standalone QA testing dashboard and support widget toolkit. One deployment supports multiple GitHub repos with isolated test rounds, issue filing, and tester management.

What It Does

• QA Dashboard — Run structured test rounds with pass/fail/skip/blocked tracking, tester attribution, severity levels, and automatic GitHub issue filing
• Support Widget — Drop-in <script> tag that adds a floating support button to any web app. Users submit tickets that become GitHub Issues
• Multi-Repo — Single hosted instance supports multiple projects. Add repos via the dashboard, switch between them with a dropdown
• AI Skills — Claude Code and Codex skills that auto-generate test cases from your codebase

Quick Start (Local Development)

# Clone and install
git clone https://github.com/bradtaylorsf/punchlist-qa.git
cd punchlist-qa
pnpm install

# Initialize config
pnpm cli init --local

# Start dev server
pnpm dev

# Visit http://localhost:4747 — create your admin account on first visit

Environment Variables

Create a .env file (generated by init --local):

PUNCHLIST_AUTH_SECRET=<random-64-char-hex>
PUNCHLIST_GITHUB_TOKEN=<github-pat-with-repo-scope>

Deploy to Render (Recommended)

The repo includes a render.yaml blueprint for one-click deployment.

Option 1: Blueprint (Fastest)

1. Go to Render Blueprint
2. Connect your GitHub repo
3. Render creates the web service + PostgreSQL database automatically
4. Set PUNCHLIST_GITHUB_TOKEN in environment variables (your GitHub PAT with repo scope)
5. Deploy — visit your URL and create your admin account

Option 2: Manual Setup

1. Create a PostgreSQL database on Render
2. Create a Web Service from Docker (Dockerfile.prod)
3. Set environment variables:

| Variable | Required | Description | |----------|----------|-------------| | DATABASE_URL | Yes | PostgreSQL connection string (auto-set if using Render Postgres) | | PUNCHLIST_AUTH_SECRET | Yes | Secret for session signing (Render can auto-generate) | | PUNCHLIST_GITHUB_TOKEN | Yes | GitHub PAT with repo scope | | PUNCHLIST_HOSTED | Yes | Set to true for hosted mode | | HOST | No | Defaults to 0.0.0.0 | | PORT | No | Defaults to 4747 | | CORS_DOMAINS | No | Comma-separated origins, defaults to * |

Install in a Consumer Repo

Add QA testing and the support widget to any existing project:

npx punchlist-qa init --hosted

This prompts for your hosted instance URL and AI tool choice, then:

• Copies AI skills to .claude/skills/ or .codex/skills/
• Outputs the widget <script> tag
• Creates .punchlist/hosted.json (minimal config)
• Does not install a server, database, or .env — everything runs on your hosted instance

Widget Integration

Add the script tag to your app's HTML:

<script src="https://your-instance.onrender.com/widget.js"></script>

The widget adds a floating support button. Users can submit tickets that automatically create GitHub Issues in the project's repo.

CLI Reference

punchlist-qa <command> [options]

| Command | Description | |---------|-------------| | init [--hosted\|--local] | Initialize punchlist-qa in a project | | serve [--hosted] | Start the QA dashboard server | | invite <email> --name <name> | Generate a tester invite link | | revoke <email> | Revoke a tester's access | | users | List all users | | update-skills | Update AI skills to latest version | | migrate | Run database migrations (PostgreSQL) |

Init Modes

• --hosted (default) — For consumer repos connecting to a deployed instance. Copies skills, outputs widget tag. No server installed.
• --local — Full self-hosted setup with config file, .env, and local SQLite database.

Serve Modes

• serve — Reads from punchlist.config.json + .env. Uses SQLite locally.
• serve --hosted — Reads from environment variables only. Uses PostgreSQL. No config file needed.

Authentication

Punchlist QA uses email/password authentication powered by Passport.js.

First-Time Setup

1. Visit your dashboard URL
2. The Setup Page appears automatically (no users exist yet)
3. Create your admin account with name, email, and password
4. You're logged in — start adding projects and inviting testers

Inviting Users

1. Go to Users page (admin only)
2. Click Invite — enter email, name, and role (tester or admin)
3. Copy the invite link and share it (Slack, email, etc.)
4. User clicks the link → sets their password → can log in with email/password

Password Reset

Admins can click Reset Password on any user in the Users page. This generates a new link that lets the user set a fresh password.

Architecture

Browser                          Server (Express)
  |                                 |
  |-- Dashboard (React SPA) ------->|-- /api/auth/*     (Passport.js)
  |-- Widget (vanilla JS) --------->|-- /api/projects/* (multi-tenant)
  |                                 |-- /api/rounds/*   (test rounds)
                                    |-- /api/results/*  (test results)
                                    |-- /api/issues/*   (GitHub integration)
                                    |
                              StorageAdapter
                              /            \
                    SqliteAdapter    PostgresAdapter
                    (local dev)     (production)

Key Concepts

• Projects — Each project maps to a GitHub repo. Data is isolated per project.
• Rounds — A test round is a structured QA session with a set of test cases.
• Results — Each test case in a round gets a result: pass, fail, skip, or blocked.
• Issues — Failed tests can auto-file GitHub Issues with severity labels.

Development

pnpm install          # Install dependencies
pnpm dev              # Start dev server (API + dashboard with hot reload)
pnpm build            # Build for production
pnpm test             # Run tests (Vitest)
pnpm type-check       # TypeScript strict mode check
pnpm lint             # ESLint

Project Structure

src/
  adapters/
    auth/            # Password hashing, error classes
    issues/          # GitHub issue adapter + registry
    storage/         # SQLite + PostgreSQL adapters, migrations, factory
  cli/               # CLI commands (init, serve, invite, etc.)
  dashboard/         # React SPA (Vite + Tailwind)
  server/
    auth/            # Passport config, session store, invite tokens
    middleware/      # requireAuth, requireAdmin, projectContext, CORS
    routes/          # Express route handlers
  shared/            # Zod schemas, types, config, encryption
  widget/            # Vanilla JS support widget (zero dependencies)
skills/              # AI agent skills for Claude Code and Codex

npm Package

Published as punchlist-qa on npm.

Releases are automated: create a GitHub Release with tag vX.Y.Z and the CI pipeline builds, tests, and publishes to npm.

License

MIT