create-qa-architect 5.3.1 → 5.4.3

package/.github/workflows/quality.yml

@@ -12,8 +12,10 @@ name: Quality Checks
 on:
   push:
     branches: [main, master, develop]
+    # PATH_FILTERS_PLACEHOLDER
   pull_request:
     branches: [main, master, develop]
+  # SECURITY_SCHEDULE_PLACEHOLDER
 
 jobs:
   # Step 1: Detect project maturity level and package manager
@@ -148,6 +150,7 @@ jobs:
   security:
     runs-on: ubuntu-latest
     needs: detect-maturity
+    # SECURITY_CONDITION_PLACEHOLDER
     if: needs.detect-maturity.outputs.has-deps == 'true'
 
     steps:
@@ -236,14 +239,11 @@ jobs:
           esac
 
       - name: Check for hardcoded secrets
-        uses: gitleaks/gitleaks-action@ff98106e4c7b2bc287b24eaf42907196329070c7 # v2.3.9
-        env:
-          # Use enhanced token if available, fallback to default GitHub token
-          # GITLEAKS_LICENSE can be set for commercial features
-          GITHUB_TOKEN: ${{ secrets.GITLEAKS_TOKEN || secrets.GITHUB_TOKEN }}
-          GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}
-        with:
-          args: --redact --verbose
+        run: |
+          echo "🔍 Running gitleaks secret scanning..."
+          # Use setup.js security scan which manages gitleaks binary internally
+          # This avoids the commercial license requirement of the gitleaks-action
+          node setup.js --security-config
 
       - name: Security pattern detection
         uses: semgrep/semgrep-action@713efdd345f3035192eaa63f56867b88e63e4e5d # v1
@@ -266,9 +266,9 @@ jobs:
     runs-on: ubuntu-latest
     needs: detect-maturity
     if: fromJSON(needs.detect-maturity.outputs.test-count) > 0
+    # TESTS_CONDITION_PLACEHOLDER
+    # MATRIX_PLACEHOLDER
     strategy:
-      matrix:
-        node-version: [20, 22]
       fail-fast: false
 
     steps:
@@ -320,7 +320,7 @@ jobs:
         if: runner.os == 'Linux'
         run: |
           echo "🔐 Running real gitleaks binary verification test..."
-          RUN_REAL_BINARY_TEST=1 node tests/gitleaks-real-binary-test.js
+          QAA_DEVELOPER=true RUN_REAL_BINARY_TEST=1 node tests/gitleaks-real-binary-test.js
 
   # Step 6: Documentation - run for production-ready projects
   documentation:

package/.github/workflows/shell-ci.yml.example

@@ -0,0 +1,82 @@
+name: Shell Script CI
+
+on:
+  push:
+    branches: [main, master, develop]
+  pull_request:
+    branches: [main, master, develop]
+
+jobs:
+  shellcheck:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Run ShellCheck
+        uses: ludeeus/action-shellcheck@master
+        with:
+          scandir: '.'
+          severity: warning
+          format: gcc
+        env:
+          SHELLCHECK_OPTS: -x -s bash
+
+  syntax-check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Bash syntax validation
+        run: |
+          echo "Validating bash syntax for all .sh files..."
+          find . -type f -name "*.sh" ! -path "*/node_modules/*" ! -path "*/.git/*" | while read -r script; do
+            echo "Checking: $script"
+            bash -n "$script" || exit 1
+          done
+
+  permissions-check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Check script permissions
+        run: |
+          echo "Checking that shell scripts are executable..."
+          non_executable=$(find . -type f -name "*.sh" ! -path "*/node_modules/*" ! -path "*/.git/*" ! -perm -u+x)
+          if [ -n "$non_executable" ]; then
+            echo "⚠️  Warning: The following scripts are not executable:"
+            echo "$non_executable"
+            echo ""
+            echo "To fix, run: chmod +x <script-name>"
+          else
+            echo "✅ All shell scripts are executable"
+          fi
+
+  bats-tests:
+    runs-on: ubuntu-latest
+    if: hashFiles('**/*.bats') != ''
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup BATS
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y bats
+
+      - name: Run BATS tests
+        run: |
+          if [ -d "tests" ] && [ -n "$(find tests -name '*.bats' 2>/dev/null)" ]; then
+            bats tests/*.bats
+          elif [ -n "$(find . -maxdepth 1 -name '*.bats' 2>/dev/null)" ]; then
+            bats *.bats
+          else
+            echo "No BATS test files found"
+          fi

package/.github/workflows/shell-quality.yml.example

@@ -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/README.md

@@ -1,6 +1,6 @@
 # QA Architect
 
-Quality automation CLI for JavaScript/TypeScript and Python 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.
+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](https://vibebuildlab.com/qa-architect) (included in VBL Starter Kit).
 
@@ -21,6 +21,7 @@ Quality automation CLI for JavaScript/TypeScript and Python projects. One comman
 - **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)
@@ -95,22 +96,93 @@ npx create-qa-architect@latest
 | Documentation check | ✅   | ✅   |
 | Env vars audit      | ❌   | ✅   |
 
+### CI/CD Optimization by Tier
+
+| Feature                      | Free | Pro+ |
+| ---------------------------- | ---- | ---- |
+| GitHub Actions cost analyzer | ❌   | ✅   |
+
+## Workflow Tiers (GitHub Actions Cost Optimization)
+
+qa-architect now defaults to **minimal CI** to avoid unexpected GitHub Actions bills. Choose the tier that matches your needs:
+
+### Minimal (Default) - $0-5/month
+
+**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
+```
+
+### Standard - $5-20/month
+
+**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
+```
+
+### Comprehensive - $100-350/month
+
+**Best for:** Enterprise teams, 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
+```
+
+### Switching Between Tiers
+
+Already using qa-architect? Convert to minimal to reduce costs:
+
+```bash
+npx create-qa-architect@latest --update --workflow-minimal
+```
+
+### Analyzing Your Costs (Pro Feature)
+
+```bash
+npx create-qa-architect@latest --analyze-ci
+```
+
+Shows estimated GitHub Actions usage and provides optimization recommendations.
+
 ### License
 
 **Commercial License (freemium)** — free tier covers the basic CLI; Pro/Team/Enterprise features require a paid subscription. See [LICENSE](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                          |
-| **Performance** | Lighthouse CI                                      |
-| **Security**    | npm audit (Free), Gitleaks + ESLint security (Pro) |
+| 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
 
@@ -155,7 +227,7 @@ npx create-qa-architect@latest --deps
 ```bash
 npx create-qa-architect@latest --prelaunch
 npm install
-npm run validate:prelaunch
+npm run validate:all
 ```
 
 ## Usage Examples
@@ -193,6 +265,42 @@ npx create-qa-architect@latest --validate-docs
 npx create-qa-architect@latest --comprehensive
 ```
 
+### GitHub Actions Cost Analysis (Pro)
+
+```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)
+```
+
 ### Custom Templates
 
 ```bash

package/config/shell-ci.yml

@@ -0,0 +1,82 @@
+name: Shell Script CI
+
+on:
+  push:
+    branches: [main, master, develop]
+  pull_request:
+    branches: [main, master, develop]
+
+jobs:
+  shellcheck:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Run ShellCheck
+        uses: ludeeus/action-shellcheck@master
+        with:
+          scandir: '.'
+          severity: warning
+          format: gcc
+        env:
+          SHELLCHECK_OPTS: -x -s bash
+
+  syntax-check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Bash syntax validation
+        run: |
+          echo "Validating bash syntax for all .sh files..."
+          find . -type f -name "*.sh" ! -path "*/node_modules/*" ! -path "*/.git/*" | while read -r script; do
+            echo "Checking: $script"
+            bash -n "$script" || exit 1
+          done
+
+  permissions-check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Check script permissions
+        run: |
+          echo "Checking that shell scripts are executable..."
+          non_executable=$(find . -type f -name "*.sh" ! -path "*/node_modules/*" ! -path "*/.git/*" ! -perm -u+x)
+          if [ -n "$non_executable" ]; then
+            echo "⚠️  Warning: The following scripts are not executable:"
+            echo "$non_executable"
+            echo ""
+            echo "To fix, run: chmod +x <script-name>"
+          else
+            echo "✅ All shell scripts are executable"
+          fi
+
+  bats-tests:
+    runs-on: ubuntu-latest
+    if: hashFiles('**/*.bats') != ''
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup BATS
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y bats
+
+      - name: Run BATS tests
+        run: |
+          if [ -d "tests" ] && [ -n "$(find tests -name '*.bats' 2>/dev/null)" ]; then
+            bats tests/*.bats
+          elif [ -n "$(find . -maxdepth 1 -name '*.bats' 2>/dev/null)" ]; then
+            bats *.bats
+          else
+            echo "No BATS test files found"
+          fi

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)"