QA Architect

Quality automation CLI for JavaScript/TypeScript, Python, and shell script projects. One command adds ESLint, Prettier, Husky, lint-staged, and GitHub Actions. Pro tiers add security scanning (Gitleaks), Smart Test Strategy, and multi-language support.

This repo = the free CLI. For the Pro dashboard with repo analytics, CI integration, and automation workflows, see QA Architect Pro (included in VBL Starter Kit).

---

> Maintainer & Ownership
> This project is maintained by Vibe Build Lab LLC, a studio focused on AI-assisted product development, micro-SaaS, and "vibe coding" workflows for solo founders and small teams.
> Learn more at https://vibebuildlab.com.

---

Features

- Prettier Code Formatting - Consistent code style across your project
- Husky Git Hooks - Pre-commit (lint + format) and pre-push (type check + tests)
- lint-staged Processing - Only process staged files for speed
- Delta Testing - Pre-push runs tests on changed files only (fast feedback)
- GitHub Actions - Automated quality checks in CI/CD
- TypeScript Smart - Auto-detects and configures TypeScript projects
- Python Support - Complete Python toolchain with Black, Ruff, isort, mypy, pytest
- Shell Script Support - ShellCheck linting, syntax validation, permissions checks, best practices
- Security Automation - npm audit (Free), Gitleaks + ESLint security (Pro)
- Progressive Quality - Adaptive checks based on project maturity
- Smart Test Strategy - Risk-based pre-push validation (Pro feature)

$3

- Lighthouse CI - Performance, accessibility, SEO audits (Free: basic, Pro: thresholds)
- Bundle Size Limits - Enforce bundle budgets with size-limit (Pro)
- axe-core Accessibility - WCAG compliance testing scaffolding (Free)
- Conventional Commits - commitlint with commit-msg hook (Free)
- Coverage Thresholds - Enforce code coverage minimums (Pro)

$3

- SEO Validation - Sitemap, robots.txt, meta tags validation (Free)
- Link Validation - Broken link detection with linkinator (Free)
- Accessibility Audit - WCAG 2.1 AA compliance with pa11y-ci (Free)
- Documentation Check - README completeness, required sections (Free)
- Env Vars Audit - Validate .env.example against code usage (Pro)

Target Users

- Developers who want quality automation without manual setup
- Teams standardizing code quality across multiple projects
- Open source maintainers enforcing contribution standards
- Agencies shipping consistent quality across client projects

Demo / Live Links

``bash


Try it on any project


npx create-qa-architect@latest
`

Pricing

| Tier | Price | What You Get |
| -------- | ----------------- | -------------------------------------------------------------------------------------------------- |
| Free | $0 | CLI tool, basic linting/formatting, npm audit (capped: 1 private repo, 50 runs/mo) |
| Pro | $49/mo or $490/yr | Security scanning (Gitleaks + ESLint security), Smart Test Strategy, multi-language, unlimited |

> Pro included in VBL Starter Kit

$3

| Feature | Free | Pro+ |
| --------------------------- | ---- | ---- |
| npm audit (basic) | ✅ | ✅ |
| Gitleaks (secrets scanning) | ❌ | ✅ |
| ESLint security rules | ❌ | ✅ |

$3

| Feature | Free | Pro+ |
| ---------------------------- | ---- | ---- |
| Lighthouse CI (basic scores) | ✅ | ✅ |
| Lighthouse thresholds | ❌ | ✅ |
| axe-core accessibility | ✅ | ✅ |
| Conventional commits | ✅ | ✅ |
| Bundle size limits | ❌ | ✅ |
| Coverage thresholds | ❌ | ✅ |

$3

| Feature | Free | Pro+ |
| ------------------- | ---- | ---- |
| SEO validation | ✅ | ✅ |
| Link validation | ✅ | ✅ |
| Accessibility audit | ✅ | ✅ |
| Documentation check | ✅ | ✅ |
| Env vars audit | ❌ | ✅ |

$3

| Feature | Free | Pro+ |
| ---------------------------- | ---- | ---- |
| GitHub Actions cost analyzer | ❌ | ✅ |

$3

Purchase: vibebuildlab.com/qa-architect

After purchase, you'll receive a license key via email (QAA-XXXX-XXXX-XXXX-XXXX).

Activate your license:

`bash
npx create-qa-architect@latest --activate-license


Enter your license key when prompted


`

Check license status:

`bash
npx create-qa-architect@latest --license-status
`

Workflow Tiers (GitHub Actions Cost Optimization)

qa-architect follows industry best practice: "Fail fast locally, verify comprehensively remotely"

$3

| Layer | Time | What Runs | Why |
| -------------- | -------- | ---------------------------------- | -------------------------- |
| Pre-commit | < 5s | Lint + format (staged files) | Instant feedback |
| Pre-push | < 30s | Type check + tests (changed files) | Catches bugs before push |
| CI | 3-10 min | Full test suite + security | Comprehensive verification |

Note: CI does NOT re-run lint/format (pre-commit already did it). This avoids redundant work and reduces CI costs.

$3

qa-architect defaults to minimal CI to avoid unexpected GitHub Actions bills. Choose the tier that matches your needs:

$3

Best for: Solo developers, side projects, open source

- Single Node version (22) testing
- Security scans run weekly (not on every commit)
- Path filters skip CI for docs/README changes
- Runtime: ~5-10 min/commit
- Est. cost: ~$0-5/mo for typical projects (2-5 commits/day)

`bash
npx create-qa-architect@latest


or explicitly:


npx create-qa-architect@latest --workflow-minimal
`

$3

Best for: Small teams, client projects, production apps

- Matrix testing (Node 20 + 22) only on main branch
- Security scans run weekly
- Path filters enabled
- Runtime: ~15-20 min/commit
- Est. cost: ~$5-20/mo for typical projects

`bash
npx create-qa-architect@latest --workflow-standard
`

$3

Best for: High-compliance projects, large teams

- Matrix testing (Node 20 + 22) on every commit
- Security scans inline (every commit)
- No path filters (runs on all changes)
- Runtime: ~50-100 min/commit
- Est. cost: ~$100-350/mo for typical projects

`bash
npx create-qa-architect@latest --workflow-comprehensive
`

$3

Publishing an npm package or CLI tool? Use --matrix to test on multiple Node.js versions:

`bash
npx create-qa-architect@latest --matrix
`

This adds Node.js 20 + 22 matrix testing - recommended for published packages that support multiple runtime versions. Not needed for web apps you deploy (you control the Node version).

$3

Already using qa-architect? Convert to minimal to reduce costs:

`bash
npx create-qa-architect@latest --update --workflow-minimal
`

$3

qa-architect's quality.yml is designed to be your single CI workflow. Do not use it alongside a separate ci.yml - this causes:

- 2-3x CI minutes usage (both workflows run on every push)
- Duplicate checks (ESLint, tests, security scans run twice)
- Unexpected billing (easily exceeds GitHub's 2,000 min/month free tier)

If you have both ci.yml and quality.yml:

`bash


Remove the duplicate ci.yml

rm .github/workflows/ci.yml

Ensure quality.yml uses minimal mode

npx create-qa-architect@latest --update --workflow-minimal
`

The quality.yml workflow is adaptive - it runs appropriate checks based on your project's maturity level, so a separate ci.yml is unnecessary.

$3

`bash
npx create-qa-architect@latest --analyze-ci
`

Shows estimated GitHub Actions usage and provides optimization recommendations.

$3

Commercial License (freemium) — free tier covers the basic CLI; Pro features require a paid subscription. See LICENSE.

Tech Stack

| Component | Technology |
| ----------------- | -------------------------------------------------- |
| Runtime | Node.js 20+ |
| Linting | ESLint 9 (flat config) |
| Formatting | Prettier 3 |
| CSS Linting | Stylelint 16 |
| Git Hooks | Husky 9 + lint-staged 15 |
| Python | Black, Ruff, mypy, pytest |
| Shell Scripts | ShellCheck, syntax validation, permissions checks |
| Performance | Lighthouse CI |
| Security | npm audit (Free), Gitleaks + ESLint security (Pro) |

Getting Started

$3

- Node.js 20 or higher
- npm 10+ (installed automatically with Node 20)
- Git repository (required for hooks)

$3

`bash


Navigate to your project

cd your-project/

Bootstrap quality automation

npx create-qa-architect@latest

Install new dependencies

npm install

Set up pre-commit hooks

npm run prepare
`

$3

`bash
npx create-qa-architect@latest --update
npm install
npm run lint
`

$3

`bash
npx create-qa-architect@latest --deps
`

$3

`bash
npx create-qa-architect@latest --prelaunch
npm install
npm run validate:all
`

Usage Examples

$3

`bash
npx create-qa-architect@latest --check-maturity
`

Output:

`
Project Maturity Report

Maturity Level: Development
Description: Active development - has source files and tests

Quality Checks:
Required: prettier, eslint, stylelint, tests
Optional: security-audit
Disabled: coverage, documentation
`

$3

`bash


Check configuration security

npx create-qa-architect@latest --security-config

Validate documentation

npx create-qa-architect@latest --validate-docs

Comprehensive validation

npx create-qa-architect@latest --comprehensive
`

$3

`bash


Analyze GitHub Actions usage and costs


npx create-qa-architect@latest --analyze-ci
`

Output:

`
📊 GitHub Actions Usage Analysis
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Repository: my-project

Estimated usage: 4,800 min/month
Commit frequency: ~2.0 commits/day
Workflows detected: 2

Workflow breakdown:
├─ ci.yml:
• ~50 min/run
• ~60 runs/month = 3000 min/month
├─ test.yml:
• ~30 min/run
• ~60 runs/month = 1800 min/month

💰 Cost Analysis
Free tier (2,000 min): ⚠️ EXCEEDED by 2,800 min
Overage cost: $22.40/month

Alternative options:
Team plan ($4/user/month): Still exceeds (1,800 min overage)
Total cost: $18.40/month
Self-hosted runners: $0/min (but VPS costs ~$5-20/month)
`

$3

`bash


Use organization-specific standards


npx create-qa-architect@latest --template ./my-org-templates
`

What Gets Added

`
your-project/
├── .github/
│ └── workflows/
│ └── quality.yml # GitHub Actions workflow
├── .husky/ # Pre-commit hooks
├── .editorconfig # Editor defaults
├── .eslintignore # ESLint ignore patterns
├── .lighthouserc.js # Lighthouse CI config
├── .npmrc # npm configuration
├── .nvmrc # Node version pinning
├── .prettierrc # Prettier configuration
├── .stylelintrc.json # Stylelint rules
├── eslint.config.cjs # ESLint flat config
└── package.json # Updated scripts
`

Available Scripts (After Setup)

`bash
npm run format # Format all files
npm run format:check # Check formatting (CI)
npm run lint # ESLint + Stylelint
npm run lint:fix # Auto-fix linting
npm run security:audit # Vulnerability check
npm run security:secrets # Scan for secrets
npm run validate:pre-push # Pre-push validation
`

Roadmap

See ROADMAP.md for planned features and strategic direction.

Contributing

Want to improve this tool?

1. Fork the repository
2. Make your changes
3. Test with a sample project
4. Submit a pull request

See CONTRIBUTING.md for guidelines.

Pro Tier & Billing

$3

Pro tier ($49/mo or $490/yr) includes:

- Security scanning (Gitleaks + ESLint security rules)
- Smart Test Strategy (risk-based pre-push validation)
- Multi-language support (Python, Shell scripts)
- Unlimited private repos and runs

Purchase at vibebuildlab.com/qa-architect

$3

The billing system uses Stripe webhooks to manage licenses. If you're deploying your own instance:

1. Set up webhook handler (see webhook-handler.js`)
2. Configure Stripe live mode keys
3. Deploy to production server

See docs/STRIPE-LIVE-MODE-DEPLOYMENT.md for complete setup guide.

Support

1. Review GitHub Actions logs
2. Open an issue in this repository

License

Commercial freemium license — the base CLI is free to use; Pro features require a paid subscription. See LICENSE for details.

Legal

- Privacy Policy
- Terms of Service

---

> Vibe Build Lab LLC · vibebuildlab.com