create-qa-architect 5.0.7 → 5.4.3

package/config/shell-quality.yml

@@ -0,0 +1,148 @@
+name: Shell Script Quality Checks
+
+on:
+  push:
+    branches: [main, master, develop]
+  pull_request:
+    branches: [main, master, develop]
+
+jobs:
+  documentation:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Check README exists
+        run: |
+          if [ ! -f "README.md" ]; then
+            echo "❌ README.md is missing"
+            exit 1
+          fi
+          echo "✅ README.md exists"
+
+      - name: Validate README content
+        run: |
+          readme_lines=$(wc -l < README.md)
+          if [ "$readme_lines" -lt 10 ]; then
+            echo "⚠️  README.md is very short (< 10 lines)"
+            echo "   Consider adding: description, usage examples, installation"
+          else
+            echo "✅ README.md has adequate content ($readme_lines lines)"
+          fi
+
+      - name: Check for usage documentation
+        run: |
+          if grep -q -i "usage\|example\|how to" README.md; then
+            echo "✅ README includes usage documentation"
+          else
+            echo "⚠️  README should include usage examples"
+          fi
+
+  script-analysis:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Count shell scripts
+        id: count
+        run: |
+          script_count=$(find . -type f -name "*.sh" ! -path "*/node_modules/*" ! -path "*/.git/*" | wc -l)
+          echo "count=$script_count" >> $GITHUB_OUTPUT
+          echo "Found $script_count shell script(s)"
+
+      - name: Analyze script complexity
+        if: steps.count.outputs.count > 0
+        run: |
+          echo "Analyzing shell script complexity..."
+          find . -type f -name "*.sh" ! -path "*/node_modules/*" ! -path "*/.git/*" | while read -r script; do
+            lines=$(wc -l < "$script")
+            functions=$(grep -c "^[[:space:]]*function\|^[[:space:]]*[a-zA-Z_][a-zA-Z0-9_]*[[:space:]]*()[[:space:]]*{" "$script" || echo 0)
+            echo "  $script: $lines lines, $functions functions"
+
+            if [ "$lines" -gt 500 ]; then
+              echo "    ⚠️  Large script (>500 lines) - consider splitting"
+            fi
+          done
+
+  best-practices:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Check for shebang
+        run: |
+          echo "Checking for proper shebang in shell scripts..."
+          missing_shebang=0
+          find . -type f -name "*.sh" ! -path "*/node_modules/*" ! -path "*/.git/*" | while read -r script; do
+            if ! head -n 1 "$script" | grep -q "^#!/"; then
+              echo "⚠️  Missing shebang: $script"
+              missing_shebang=$((missing_shebang + 1))
+            fi
+          done
+
+          if [ "$missing_shebang" -eq 0 ]; then
+            echo "✅ All scripts have proper shebang"
+          fi
+
+      - name: Check for set -e or set -euo pipefail
+        run: |
+          echo "Checking for error handling (set -e / set -euo pipefail)..."
+          missing_set_e=0
+          find . -type f -name "*.sh" ! -path "*/node_modules/*" ! -path "*/.git/*" | while read -r script; do
+            if ! grep -q "set -e\|set -euo pipefail" "$script"; then
+              echo "⚠️  Missing error handling: $script"
+              echo "   Recommendation: Add 'set -euo pipefail' after shebang"
+              missing_set_e=$((missing_set_e + 1))
+            fi
+          done
+
+          if [ "$missing_set_e" -eq 0 ]; then
+            echo "✅ All scripts use error handling"
+          fi
+
+  security:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Check for hardcoded secrets
+        run: |
+          echo "Scanning for potential hardcoded secrets..."
+          found_issues=0
+
+          # Check for common secret patterns
+          if grep -r -i "password\s*=\|api_key\s*=\|secret\s*=" --include="*.sh" .; then
+            echo "⚠️  Found potential hardcoded secrets"
+            echo "   Use environment variables instead: \${VARIABLE_NAME}"
+            found_issues=1
+          fi
+
+          # Check for AWS keys
+          if grep -r "AKIA[0-9A-Z]{16}" --include="*.sh" .; then
+            echo "❌ Found AWS access key pattern"
+            found_issues=1
+          fi
+
+          if [ "$found_issues" -eq 0 ]; then
+            echo "✅ No obvious hardcoded secrets found"
+          fi
+
+      - name: Check for unsafe practices
+        run: |
+          echo "Checking for unsafe shell practices..."
+
+          # Check for eval usage
+          if grep -r "eval " --include="*.sh" . | grep -v "^#"; then
+            echo "⚠️  Found 'eval' usage - potential security risk"
+          fi
+
+          # Check for unquoted variables
+          echo "  (ShellCheck will provide detailed analysis)"

package/docs/ADOPTION-SUMMARY.md

@@ -0,0 +1,41 @@
+# qa-architect - Adoption Summary
+
+**Adopted:** 2025-12-29
+**Value Score:** 95/100
+
+## Metrics
+
+| Metric                | Count |
+| --------------------- | ----- |
+| Total Requirements    | 104   |
+| API Endpoints         | 0     |
+| UI Pages              | 0     |
+| Test Coverage Items   | 104   |
+| Integrations Detected | 0     |
+
+## Value Breakdown
+
+| Component      | Score      | Description                           |
+| -------------- | ---------- | ------------------------------------- |
+| Documentation  | 20/25      | Requirements extracted and documented |
+| Traceability   | 25/25      | Test-to-requirement mappings          |
+| Architecture   | 25/25      | Architecture documentation            |
+| Quality Config | 25/25      | Quality thresholds configured         |
+| **Total**      | **95/100** | -                                     |
+
+## Files Adopted
+
+- ✅ docs/ARCHITECTURE-REVIEW.md
+- ✅ docs/CODE-REVIEW.md
+- ✅ docs/SECURITY-AUDIT.md
+
+## Files Skipped (already existed)
+
+- ⏭️ .qualityrc.json
+- ⏭️ docs/REQUIREMENTS.md
+- ⏭️ docs/test-trace-matrix.md
+- ⏭️ docs/ARCHITECTURE.md
+
+---
+
+_Generated by VBL Adopt_

package/docs/ARCHITECTURE-REVIEW.md

@@ -0,0 +1,67 @@
+Based on the limited documentation provided, I'll conduct an architecture review with the available information. However, I must note that this review is constrained by insufficient architectural details in the documentation.
+
+## Architecture Review: qa-architect
+
+**Verdict: NEEDS REVISION**
+**Overall Score: 45/100**
+
+### Dimension Scores
+
+| Dimension             | Score  | Assessment                                                |
+| --------------------- | ------ | --------------------------------------------------------- |
+| Pattern Selection     | 40/100 | CLI pattern unclear, no architectural patterns documented |
+| Scalability           | 30/100 | No scalability considerations documented                  |
+| Security Architecture | 60/100 | Security features mentioned but implementation unclear    |
+| Simplicity            | 50/100 | Dependencies suggest complexity but design not documented |
+| API Design            | 35/100 | CLI interface not documented, no API specifications       |
+
+### Strengths
+
+1. **Clear Product Vision** - Well-defined target users and pricing tiers
+2. **Multi-language Support** - Supports both JavaScript/TypeScript and Python ecosystems
+3. **Progressive Enhancement** - Free tier with Pro upgrades shows thoughtful monetization
+4. **Quality Focus** - Integrates multiple quality tools (ESLint, Prettier, Husky, etc.)
+
+### Concerns
+
+1. **Insufficient Documentation** → Complete architectural documentation showing components, data flow, and patterns
+2. **Missing Security Architecture** → Document how Gitleaks, ESLint security, and other security features are architected
+3. **No API Design** → Document CLI interface, command structure, configuration schemas
+4. **Unclear Scalability** → Document how the system handles different project sizes and team requirements
+5. **Missing Data Architecture** → Document configuration management, state handling, and data persistence
+6. **No Error Handling Strategy** → Document error handling, recovery, and user feedback patterns
+7. **Dependency Justification Missing** → Explain rationale for 13 production dependencies
+
+### Required Changes (NEEDS REVISION)
+
+- [ ] **Document Core Architecture** - Create detailed architecture diagrams showing components, modules, and data flow
+- [ ] **Define CLI API Design** - Document command structure, options, configuration schemas, and interfaces
+- [ ] **Security Architecture Documentation** - Detail how security scanning, audit features, and Pro tier security work
+- [ ] **Scalability Design** - Document performance considerations, memory usage, and scaling patterns
+- [ ] **Error Handling Strategy** - Define error handling patterns, user feedback, and recovery mechanisms
+- [ ] **Configuration Management** - Document how different project types are detected and configured
+- [ ] **Testing Architecture** - With 104 tests, document testing strategy and patterns
+
+### Alternative Approaches Considered
+
+The documentation doesn't indicate consideration of alternatives. Should have evaluated:
+
+- **CLI Frameworks**: Why not use Commander.js, Yargs, or Oclif for CLI structure?
+- **Configuration Management**: JSON vs YAML vs TypeScript configs
+- **Plugin Architecture**: Extensible vs monolithic design for different languages/tools
+- **Distribution Strategy**: npm package vs standalone binary vs Docker
+
+### Approval
+
+**NEEDS REVISION**: The architecture documentation is insufficient for proper review. While the product concept is solid and the README shows clear market positioning, the actual architectural design is not documented. The auto-generated architecture document provides no meaningful architectural insight.
+
+**Critical Missing Elements:**
+
+1. Component architecture and module organization
+2. CLI command structure and API design
+3. Configuration and state management patterns
+4. Security implementation architecture
+5. Multi-language support architecture
+6. Testing and quality assurance patterns
+
+**Recommendation**: Before implementation proceeds, create comprehensive architecture documentation showing how the system is designed to handle its stated requirements. The gap between the feature-rich product description and the minimal architecture documentation suggests the architecture design phase was incomplete.

package/docs/ARCHITECTURE.md

@@ -1,57 +1,41 @@
-# Architecture
+# qa-architect - Architecture
 
-## Overview
+**Generated:** 2025-12-27
+**Framework:** Node.js
+**Maturity:** minimal
 
-QA Architect is a CLI tool that bootstraps quality automation in JavaScript/TypeScript and Python projects.
+## Overview
 
-## Core Components
+This is a Node.js application.
 
-```
-create-qa-architect/
-├── setup.js              # Main CLI entry point
-├── lib/                  # Core logic (validation, licensing, maturity, telemetry, dependency monitoring)
-├── templates/            # Project templates
-│   ├── ci/               # GitHub Actions + CircleCI/GitLab samples
-│   ├── scripts/          # Helper scripts (smart test strategy, etc.)
-│   ├── integration-tests/# Starter integration tests
-│   ├── test-stubs/       # Unit/E2E placeholders
-│   ├── python/           # Python quality config
-│   └── QUALITY_TROUBLESHOOTING.md
-├── config/               # Defaults and language-specific configs
-│   ├── pyproject.toml
-│   └── quality-python.yml
-└── docs/                 # Architecture/testing/SLA/security docs
-```
+## Tech Stack
 
-## Data Flow
+| Layer           | Technology       |
+| --------------- | ---------------- |
+| Framework       | Node.js          |
+| Language        | TypeScript       |
+| Package Manager | npm              |
+| Testing         | Jest/Node assert |
 
-1. **Detection Phase**: Detect project type (JS/TS/Python/mixed)
-2. **Configuration Phase**: Generate appropriate configs
-3. **Installation Phase**: Copy templates, update package.json
-4. **Validation Phase**: Verify setup is complete
+## Project Structure
 
-## Extension Points
-
-- Custom templates via `--template` flag
-- Language detection can be extended in `setup.js`
-- New quality checks via template files
+```
+├── src/                 # Source code
+├── lib/                 # Libraries
+├── tests/               # Test files (104 test items)
+└── docs/                # Documentation
+```
 
-## Smart Test Strategy (Pro)
+## Key Components
 
-Risk-based pre-push validation that adapts to change context:
+## Quality Standards
 
-1. Calculate risk score (0-10) based on files changed
-2. Select appropriate test tier (minimal → comprehensive)
-3. Run tests with appropriate depth
+| Metric         | Target  |
+| -------------- | ------- |
+| Test Coverage  | 50%     |
+| Maturity Level | minimal |
 
-## CLI Flags
+---
 
-- `--update` - Update existing setup
-- `--deps` - Dependency monitoring only
-- `--security-config` - Security validation
-- `--check-maturity` - Project maturity report
-- `--validate` / `--comprehensive` - Full validation suite
-- `--validate-docs` - Documentation validation only
-- `--validate-config` - Validate `.qualityrc.json`
-- `--alerts-slack` / `--pr-comments` - Collaboration hooks
-- `--license-status` - Show current tier/features
+_Auto-generated by VBL Adopt - 2025-12-27_
+_Run `vbl docs` for detailed architecture documentation_

package/docs/CI-COST-ANALYSIS.md

@@ -0,0 +1,323 @@
+# GitHub Actions Cost Analysis: Is qa-architect Over-Engineering CI/CD?
+
+**Date**: 2026-01-06
+**Finding**: YES - qa-architect's default setup is 3-5x more expensive than industry standards for solo/small projects.
+
+---
+
+## The Problem
+
+Your projects are costing **$469/month** in GitHub Actions CI when they should cost **$0-50/month**.
+
+| Project                    | Commits/Day | Minutes/Month | Cost/Month | Status      |
+| -------------------------- | ----------- | ------------- | ---------- | ----------- |
+| vibebuildlab               | 7.4         | 46,852 min    | $358       | 🔴 CRITICAL |
+| qa-architect               | 1.7         | 15,810 min    | $110       | 🔴 HIGH     |
+| stark-program-intelligence | 1.6         | 2,160 min     | $1.28      | 🟢 OK       |
+| vibelab-claude-setup       | 2.0         | 531 min       | $0         | ✅ OPTIMAL  |
+
+---
+
+## Root Cause Analysis
+
+### What qa-architect Is Doing (vibebuildlab example)
+
+**Current quality.yml**: 161 minutes per commit, runs 221 times/month
+
+```yaml
+Jobs running on EVERY push:
+1. detect-maturity (1 job) ~ 2 min
+2. core-checks (2 jobs) ~ 10 min  # Node 20 + 22 matrix
+3. linting (1 job) ~ 8 min
+4. security (1 job) ~ 25 min       # Gitleaks + Semgrep + 3× npm audit
+5. tests (2 jobs) ~ 30 min         # Node 20 + 22 matrix
+6. documentation (1 job) ~ 15 min  # Only if production-ready
+7. summary (1 job) ~ 1 min
+
+TOTAL: ~90-100 minutes per push (when all jobs run)
+```
+
+**Problems identified**:
+
+1. ❌ **No path filters** - Runs full CI on docs/README commits
+2. ❌ **Duplicate matrix testing** - Both core-checks AND tests run Node 20/22
+3. ❌ **Security overkill** - Gitleaks + Semgrep + npm audit (3 variants) on EVERY push
+4. ❌ **No job concurrency limits** - Rapid commits queue up expensive builds
+5. ❌ **Production checks on every commit** - Documentation validation should be release-only
+
+---
+
+## Industry Standards (Successful Projects)
+
+### Vite (Major Framework, 1000+ contributors)
+
+- **Runtime**: 50-60 min/commit
+- **Path filters**: ✅ Skips tests on docs-only changes
+- **Matrix**: Node 20, 22, 24 (3 versions)
+- **Cross-platform**: Only on latest Node, not all versions
+- **Security**: Runs on schedule, not every commit
+
+### Ky (Popular Library, Sindre Sorhus)
+
+- **Runtime**: 10-15 min/commit
+- **Matrix**: Node 20, 22, 24, latest (4 versions)
+- **Platform**: macOS only (assumes Linux/Windows compatibility)
+- **Security**: Separate workflow
+
+### Common Patterns
+
+1. **Minimal on push** - Lint + test current Node only
+2. **Matrix testing** - Only on main branch or scheduled
+3. **Security scans** - Weekly/nightly, not per commit
+4. **Documentation** - Only on release branches
+5. **Path filters** - Skip CI for docs/README/LICENSE changes
+
+**Sources**:
+
+- [GitHub Actions alternatives for modern CI/CD](https://northflank.com/blog/github-actions-alternatives)
+- [Ultimate free CI/CD for open-source projects](https://dev.to/itnext/the-ultimate-free-ci-cd-for-your-open-source-projects-3bkd)
+
+---
+
+## Recommended Changes
+
+### Phase 1: Quick Wins (Reduce by 60-70%)
+
+#### 1. Add Path Filters
+
+```yaml
+on:
+  push:
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - 'LICENSE'
+      - '.gitignore'
+      - '.editorconfig'
+```
+
+**Savings**: ~20% of commits are docs-only
+**vibebuildlab**: 7,117 min/month saved ($57/mo)
+
+#### 2. Reduce Matrix Redundancy
+
+```yaml
+# BEFORE: 2 matrix jobs (core-checks + tests)
+core-checks:
+  matrix:
+    node-version: [20, 22]  # Runs twice
+
+tests:
+  matrix:
+    node-version: [20, 22]  # Runs twice again!
+
+# AFTER: 1 matrix job only
+tests:
+  matrix:
+    node-version: [20, 22]  # Runs once
+```
+
+**Savings**: 50% reduction in matrix jobs
+**vibebuildlab**: ~18,000 min/month saved ($144/mo)
+
+#### 3. Move Security to Scheduled Workflow
+
+```yaml
+# New file: .github/workflows/security-weekly.yml
+on:
+  schedule:
+    - cron: '0 0 * * 0' # Weekly on Sunday
+  workflow_dispatch: # Manual trigger
+
+jobs:
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Gitleaks
+      - name: Semgrep
+      - name: npm audit
+```
+
+**Savings**: From 221 runs/month → 4 runs/month
+**vibebuildlab**: ~5,400 min/month saved ($43/mo)
+
+### Phase 2: Industry-Standard Setup (Get under $50/mo total)
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - 'LICENSE'
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true # Cancel old runs
+
+jobs:
+  # Quick checks on every commit (current Node only)
+  quick-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run format:check
+      - run: npm test
+
+  # Matrix testing only on main branch
+  cross-version:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20, 22]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+      - run: npm ci
+      - run: npm test
+```
+
+**Estimated runtime**:
+
+- Pull requests: 5-10 min (quick-check only)
+- Main branch: 15-20 min (quick-check + cross-version)
+
+**Estimated cost for vibebuildlab**:
+
+- Current: 46,852 min/month ($358/mo)
+- After changes: ~3,500 min/month ($12/mo)
+- **Savings: $346/month (97% reduction)**
+
+---
+
+## Strategic Recommendations
+
+### For Solo Developers / Small Teams
+
+**Make all repos public** → GitHub Actions is FREE
+
+- If code can be public, this is the best option
+- vibebuildlab, qa-architect could potentially be public
+
+### For Private Repos
+
+**Option A: Minimal CI** (Recommended)
+
+```
+✅ Lint + format on every commit (5 min)
+✅ Test on current Node only (10 min)
+✅ Matrix testing on main branch only
+✅ Security scans weekly, not per commit
+✅ Documentation checks on releases only
+
+Total: ~500-1,000 min/month ($0-8/mo)
+```
+
+**Option B: Self-Hosted Runner**
+
+- Rent $10-20/mo VPS (Hetzner, DigitalOcean)
+- Install GitHub self-hosted runner
+- Total cost: $20/mo for UNLIMITED minutes
+- **Best if you have 5+ active private repos**
+
+**Option C: Strategic Testing**
+
+```yaml
+# Only test what matters
+on:
+  pull_request: # Test on PRs
+  push:
+    branches: [main] # Test on main
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+
+# Skip matrix on draft PRs
+if: github.event.pull_request.draft == false
+```
+
+### For qa-architect Product
+
+**Current Default** (what qa-architect creates):
+
+- ❌ Enterprise-grade CI for solo devs
+- ❌ Costs $100-350/mo for typical projects
+- ❌ Over-engineering: Gitleaks + Semgrep on every commit
+
+**Recommended Default**:
+
+```yaml
+Basic (Free tier friendly):
+✅ Lint + format + test (current Node only)
+✅ Security scans weekly
+✅ Matrix testing opt-in only
+✅ Path filters enabled by default
+
+Pro tier enhancements:
+✅ Add matrix testing (if needed)
+✅ Add cross-platform testing (if needed)
+✅ Add comprehensive security (scheduled)
+```
+
+---
+
+## Action Items
+
+### Immediate (This Week)
+
+1. Add path filters to all repos → Save 20% instantly
+2. Move security scans to weekly schedule → Save 95% of security costs
+3. Remove duplicate matrix jobs → Save 50% of test costs
+
+### Short Term (This Month)
+
+1. Redesign qa-architect default template (minimal-first approach)
+2. Create three tiers:
+   - `--minimal`: Lint + test (current Node), FREE tier friendly
+   - `--standard`: + matrix testing (main branch only)
+   - `--comprehensive`: Current setup (for large teams)
+3. Add `--public` flag that optimizes for unlimited minutes
+
+### Long Term (Q1 2026)
+
+1. Add cost analyzer to `npx create-qa-architect` (show estimated costs)
+2. Default to minimal setup, prompt for upgrades
+3. Document self-hosted runner setup guide
+4. Create cost monitoring dashboard (track actual usage)
+
+---
+
+## Conclusion
+
+**YES, you're right to question this.**
+
+qa-architect is creating **enterprise-grade CI for solo developers**, resulting in:
+
+- 3-5x longer CI times than industry standards
+- 10-20x higher costs than necessary
+- Excessive testing that doesn't add proportional value
+
+**The fix**: Shift to "minimal by default, comprehensive on demand."
+
+For your specific projects:
+
+- **vibebuildlab**: $358/mo → $12/mo (implement Phase 1 + 2)
+- **qa-architect**: $110/mo → $5/mo (same changes)
+- **Total savings**: $451/month ($5,412/year)
+
+Or just make repos public → **$0/month**.