@soulbatical/tetra-dev-toolkit 1.1.0

package/README.md

@@ -0,0 +1,312 @@
+# @vca/quality-toolkit
+
+Unified quality checks for all VCA projects. Consolidates security, stability, and code quality checks from sparkbuddy-live and vca-tools into a single npm package.
+
+**Status:** Installed in 13 projects | Version 1.0.0
+
+## Installation
+
+```bash
+# Local installation (recommended for VCA projects)
+npm install --save-dev /Users/albertbarth/projecten/vca-quality-toolkit
+
+# Or via file reference in package.json
+"devDependencies": {
+  "@vca/quality-toolkit": "file:../vca-quality-toolkit"
+}
+```
+
+## Quick Start
+
+```bash
+# Run all checks
+npx vca-audit
+
+# Run only security checks
+npx vca-audit security
+
+# Run only stability checks
+npx vca-audit stability
+
+# Quick check (critical issues only - fast, for pre-commit)
+npx vca-audit quick
+
+# Setup Husky hooks and CI
+npx vca-setup
+```
+
+## Example Output
+
+```
+═══════════════════════════════════════════════════════════════
+  🔍 VCA Quality Toolkit - Audit Results
+═══════════════════════════════════════════════════════════════
+
+  Project: /Users/albertbarth/projecten/ralph-manager
+  Time: 2026-02-03T15:04:03.478Z
+
+  ✅ Overall Status: PASSED
+
+  ✅ SECURITY
+  ──────────────────────────────────────────────────
+    ✅ Hardcoded Secrets Detection PASS
+    ✅ Service Role Key Exposure PASS
+    ✅ Deprecated supabaseAdmin Usage PASS
+    ✅ systemDB Context Whitelist PASS
+
+  ✅ STABILITY
+  ──────────────────────────────────────────────────
+    ✅ Pre-commit Hooks (Husky) PASS
+    ✅ CI/CD Pipeline PASS
+    ✅ NPM Vulnerability Audit PASS
+
+═══════════════════════════════════════════════════════════════
+  Checks: 7 passed, 0 failed, 0 skipped
+═══════════════════════════════════════════════════════════════
+```
+
+## What It Checks
+
+### Security (4 checks implemented)
+| Check | Severity | Description |
+|-------|----------|-------------|
+| Hardcoded Secrets | Critical | API keys, tokens, JWTs in source code |
+| Service Key Exposure | Critical | Supabase service role key in frontend |
+| Deprecated supabaseAdmin | High | Direct supabaseAdmin usage (use systemDB/userDB) |
+| systemDB Whitelist | High | Unwhitelisted systemDB contexts |
+
+### Stability (3 checks implemented)
+| Check | Severity | Description |
+|-------|----------|-------------|
+| Husky Hooks | High | Pre-commit hooks configured with useful checks |
+| CI Pipeline | High | GitHub Actions/GitLab CI with lint, test, build |
+| npm audit | High | No critical/high vulnerabilities |
+
+### Health (15 ecosystem checks) — NEW
+
+Project-level health scanner shared by ralph-manager and development-mcp.
+
+| Check | Max Score | Description |
+|-------|-----------|-------------|
+| `plugins` | 2 | Claude Code plugins installed |
+| `mcps` | 1 | MCP servers configured |
+| `git` | 3 | Branch, uncommitted, unpushed |
+| `tests` | 5 | Test pyramid (unit/integration/e2e) |
+| `secrets` | 2 | Exposed secrets in MD files |
+| `quality-toolkit` | 2 | @vca/dev-toolkit installed |
+| `naming-conventions` | 3 | DB + code naming compliance |
+| `rls-audit` | 3 | RLS policies in SQL migrations |
+| `gitignore` | 2 | Critical .gitignore entries |
+| `repo-visibility` | 2 | Public vs private repo |
+| `vincifox-widget` | 2 | VinciFox feedback widget |
+| `stella-integration` | 2 | @ralph/stella integration level |
+| `claude-md` | 3 | CLAUDE.md protocol sections |
+| `doppler-compliance` | 3 | Doppler secret management |
+| `infrastructure-yml` | 3 | .ralph/INFRASTRUCTURE.yml |
+
+**Total: 38 points.** Score thresholds: Healthy >= 70%, Warning 40-70%, Unhealthy < 40%.
+
+```javascript
+import { scanProjectHealth } from '@vca/dev-toolkit'
+
+const report = await scanProjectHealth('/path/to/project', 'my-project')
+console.log(report.healthPercent + '%')  // e.g. "58%"
+console.log(report.status)               // "healthy" | "warning" | "unhealthy"
+```
+
+### Planned Checks
+- [ ] Dead code detection (Knip integration)
+- [ ] Circular dependency detection
+- [ ] TypeScript strict mode
+- [ ] Test coverage thresholds
+
+## Integration with Ralph Manager
+
+The toolkit integrates with ralph-manager's Health dashboard:
+
+- **Health Scanner**: Shared 15-check scanner (ralph-manager imports from this package)
+- **Toolkit Check**: Shows toolkit installation status per project
+- **API Endpoint**: `/api/admin/health/quality-toolkit` returns status for all projects
+
+## Usage in package.json
+
+```json
+{
+  "scripts": {
+    "audit": "vca-audit",
+    "audit:security": "vca-audit security",
+    "audit:quick": "vca-audit quick",
+    "prepare": "husky"
+  }
+}
+```
+
+## Configuration
+
+Create `.vca-quality.json` in your project root:
+
+```json
+{
+  "suites": {
+    "security": true,
+    "stability": true,
+    "codeQuality": true,
+    "supabase": "auto"
+  },
+  "security": {
+    "checkHardcodedSecrets": true,
+    "checkServiceKeyExposure": true
+  },
+  "stability": {
+    "requireHusky": true,
+    "requireCiConfig": true,
+    "allowedVulnerabilities": {
+      "critical": 0,
+      "high": 0,
+      "moderate": 10
+    }
+  },
+  "supabase": {
+    "publicRpcFunctions": ["get_public_stats"],
+    "publicTables": ["lookup_countries"]
+  },
+  "ignore": [
+    "node_modules/**",
+    "dist/**"
+  ]
+}
+```
+
+## CI Integration
+
+### GitHub Actions
+
+```yaml
+name: Quality Checks
+
+on: [push, pull_request]
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+      - run: npx vca-audit --ci
+```
+
+The `--ci` flag outputs GitHub Actions annotations for inline PR feedback.
+
+### Pre-commit Hook
+
+Run `npx vca-setup hooks` or manually create `.husky/pre-commit`:
+
+```bash
+#!/bin/sh
+npx vca-audit quick
+if [ $? -ne 0 ]; then
+  echo "❌ Security issues found! Fix before committing."
+  exit 1
+fi
+```
+
+## Programmatic Usage
+
+```javascript
+import { runAllChecks, runSecurityChecks } from '@vca/quality-toolkit'
+
+const results = await runAllChecks()
+
+if (!results.passed) {
+  console.log('Quality checks failed!')
+  console.log(`Critical: ${results.summary.findings.critical}`)
+  console.log(`High: ${results.summary.findings.high}`)
+}
+```
+
+## Projects Using This Toolkit
+
+| Project | Status | Version |
+|---------|--------|---------|
+| ralph-manager | ✅ | 1.0.0 |
+| sparkbuddy-live | ✅ | 1.0.0 |
+| snelstart-mcp | ✅ | 1.0.0 |
+| snelstart-portal | ✅ | 1.0.0 |
+| vibecodingacademy | ✅ | 1.0.0 |
+| Plokko | ✅ | 1.0.0 |
+| ad-agent | ✅ | 1.0.0 |
+| ai-finder | ✅ | 1.0.0 |
+| airbnb | ✅ | 1.0.0 |
+| github-ai-research | ✅ | 1.0.0 |
+| groei-boom | ✅ | 1.0.0 |
+| sparkgrowth | ✅ | 1.0.0 |
+| vca-security | ✅ | 1.0.0 |
+
+## Relationship to vca-tools
+
+This package complements [vca-tools](https://github.com/mralbertzwolle/vibe-coding-academy-tools) (Claude Code plugins):
+
+| Tool | Purpose | Usage |
+|------|---------|-------|
+| **vca-tools** | Interactive Claude Code plugins | `/security-audit:run`, `/codebase-stability-audit:run` |
+| **@vca/quality-toolkit** | Automated CI/pre-commit checks | `npx vca-audit`, GitHub Actions |
+
+Both share the same check logic, but:
+- **vca-tools** = human-in-the-loop, detailed reports, fix suggestions
+- **@vca/quality-toolkit** = automated, CI-friendly, pass/fail
+
+## Architecture
+
+```
+@vca/quality-toolkit/
+├── bin/
+│   ├── vca-audit.js        # Main CLI
+│   └── vca-setup.js        # Setup hooks/CI
+├── lib/
+│   ├── index.js            # Main exports
+│   ├── config.js           # Configuration loader
+│   ├── runner.js           # Check orchestrator
+│   ├── checks/
+│   │   ├── health/         # 15 ecosystem health checks (shared with ralph-manager)
+│   │   │   ├── scanner.js  # Orchestrator — scanProjectHealth()
+│   │   │   ├── types.js    # Shared types & helpers
+│   │   │   ├── plugins.js  # Claude Code plugins
+│   │   │   ├── mcps.js     # MCP server config
+│   │   │   ├── git.js      # Git status
+│   │   │   ├── tests.js    # Test pyramid
+│   │   │   ├── secrets.js  # Exposed secrets
+│   │   │   └── ...         # 10 more checks
+│   │   ├── security/       # Security checks
+│   │   ├── stability/      # Stability checks
+│   │   ├── codeQuality/    # Code quality checks
+│   │   └── supabase/       # Supabase checks
+│   └── reporters/
+│       └── terminal.js     # Pretty output + GitHub Actions
+└── package.json
+```
+
+## Consumers
+
+| Package | Import | Usage |
+|---------|--------|-------|
+| **ralph-manager** | `scanProjectHealth` | Dashboard health scanner (background job, every 2 min) |
+| **development-mcp** | `scanProjectHealth` | `health_check` MCP tool (on-demand via Claude Code) |
+| **13 VCA projects** | `vca-audit` CLI | CI/pre-commit quality checks |
+
+## Contributing
+
+1. Add new check in `lib/checks/<category>/<name>.js`
+2. Register in `lib/runner.js`
+3. Update README
+4. Test with `npx vca-audit` in a project
+
+## License
+
+MIT
+
+---
+
+Built by [Vibe Coding Academy](https://vibecodingacademy.nl) • [Albert Barth](https://linkedin.com/in/albertbarth/)

package/bin/vca-audit.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+
+/**
+ * VCA Quality Toolkit - Main CLI
+ *
+ * Usage:
+ *   vca-audit              # Run all checks
+ *   vca-audit security     # Run security checks only
+ *   vca-audit stability    # Run stability checks only
+ *   vca-audit quick        # Run quick critical checks
+ *   vca-audit --ci         # CI mode (GitHub Actions annotations)
+ *   vca-audit --json       # JSON output
+ */
+
+import { program } from 'commander'
+import { runAllChecks, runSecurityChecks, runStabilityChecks, runCodeQualityChecks, runQuickCheck } from '../lib/runner.js'
+import { formatResults, formatGitHubActions } from '../lib/reporters/terminal.js'
+
+program
+  .name('vca-audit')
+  .description('VCA Quality Toolkit - Unified quality checks for all projects')
+  .version('1.0.0')
+  .argument('[suite]', 'Check suite to run: security, stability, quick, or all (default)')
+  .option('--ci', 'CI mode - output GitHub Actions annotations')
+  .option('--json', 'Output results as JSON')
+  .option('-v, --verbose', 'Show detailed output including fix suggestions')
+  .option('--max-findings <n>', 'Maximum findings to show per check', parseInt, 5)
+  .action(async (suite, options) => {
+    try {
+      let results
+
+      switch (suite) {
+        case 'security':
+          results = await runSecurityChecks()
+          break
+        case 'stability':
+          results = await runStabilityChecks()
+          break
+        case 'codeQuality':
+        case 'code-quality':
+          results = await runCodeQualityChecks()
+          break
+        case 'quick':
+          results = await runQuickCheck()
+          break
+        default:
+          results = await runAllChecks()
+      }
+
+      // Output based on format
+      if (options.json) {
+        console.log(JSON.stringify(results, null, 2))
+      } else if (options.ci) {
+        // GitHub Actions format
+        console.log(formatGitHubActions(results))
+
+        // Also print summary
+        console.log('')
+        console.log('## VCA Quality Audit Results')
+        console.log('')
+        console.log(`- **Status**: ${results.passed ? '✅ PASSED' : '❌ FAILED'}`)
+        console.log(`- **Checks**: ${results.summary.passed} passed, ${results.summary.failed} failed`)
+
+        if (results.summary.findings.critical > 0) {
+          console.log(`- **Critical Issues**: ${results.summary.findings.critical}`)
+        }
+        if (results.summary.findings.high > 0) {
+          console.log(`- **High Issues**: ${results.summary.findings.high}`)
+        }
+      } else {
+        // Terminal format
+        console.log(formatResults(results, {
+          verbose: options.verbose,
+          maxFindings: options.maxFindings
+        }))
+      }
+
+      // Exit with appropriate code
+      process.exit(results.passed ? 0 : 1)
+
+    } catch (error) {
+      console.error('Error running audit:', error.message)
+      if (options.verbose) {
+        console.error(error.stack)
+      }
+      process.exit(2)
+    }
+  })
+
+program.parse()

package/bin/vca-dev-token.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+/**
+ * VCA Dev Toolkit - Dev Token CLI
+ *
+ * Manage Supabase dev tokens for API testing.
+ * Auto-detects project from package.json, finds Supabase config from .env files.
+ *
+ * Usage:
+ *   vca-dev-token                    # Auto-refresh or show status
+ *   vca-dev-token --login            # Interactive login (prompts for password)
+ *   vca-dev-token --status           # Show current token status
+ *   vca-dev-token --project myapp    # Override project detection
+ */
+
+import { program } from 'commander'
+import { runDevToken } from '../lib/commands/dev-token.js'
+
+program
+  .name('vca-dev-token')
+  .description('Manage Supabase dev tokens for API testing')
+  .version('1.1.0')
+  .option('--login', 'Interactive login (prompts for email/password)')
+  .option('--status', 'Show current token status')
+  .option('--project <name>', 'Override auto-detected project slug')
+  .action(async (options) => {
+    try {
+      await runDevToken({
+        forceLogin: options.login || false,
+        showStatus: options.status || false,
+        projectOverride: options.project || null,
+      })
+    } catch (error) {
+      console.error('Error:', error.message)
+      process.exit(2)
+    }
+  })
+
+program.parse()

package/bin/vca-setup.js

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+
+/**
+ * VCA Quality Toolkit - Setup CLI
+ *
+ * Sets up quality infrastructure in a project:
+ * - Husky pre-commit hooks
+ * - GitHub Actions workflow
+ * - Configuration file
+ *
+ * Usage:
+ *   vca-setup              # Interactive setup
+ *   vca-setup hooks        # Setup Husky hooks only
+ *   vca-setup ci           # Setup GitHub Actions only
+ *   vca-setup config       # Create .vca-quality.json
+ */
+
+import { program } from 'commander'
+import { execSync } from 'child_process'
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs'
+import { join } from 'path'
+
+const projectRoot = process.cwd()
+
+program
+  .name('vca-setup')
+  .description('Setup VCA Quality Toolkit in your project')
+  .version('1.0.0')
+  .argument('[component]', 'Component to setup: hooks, ci, config, or all (default)')
+  .option('-f, --force', 'Overwrite existing files')
+  .action(async (component, options) => {
+    console.log('')
+    console.log('🔧 VCA Quality Toolkit - Setup')
+    console.log('═'.repeat(50))
+    console.log('')
+
+    const components = component === 'all' || !component
+      ? ['hooks', 'ci', 'config']
+      : [component]
+
+    for (const comp of components) {
+      switch (comp) {
+        case 'hooks':
+          await setupHooks(options)
+          break
+        case 'ci':
+          await setupCi(options)
+          break
+        case 'config':
+          await setupConfig(options)
+          break
+        default:
+          console.log(`Unknown component: ${comp}`)
+      }
+    }
+
+    console.log('')
+    console.log('✅ Setup complete!')
+    console.log('')
+    console.log('Next steps:')
+    console.log('  1. Run `vca-audit` to check your project')
+    console.log('  2. Commit the generated files')
+    console.log('  3. Push to trigger CI checks')
+    console.log('')
+  })
+
+async function setupHooks(options) {
+  console.log('📦 Setting up Husky pre-commit hooks...')
+
+  // Check if husky is installed
+  const packagePath = join(projectRoot, 'package.json')
+  if (!existsSync(packagePath)) {
+    console.log('   ❌ No package.json found')
+    return
+  }
+
+  const pkg = JSON.parse(readFileSync(packagePath, 'utf-8'))
+  const hasHusky = pkg.devDependencies?.husky || pkg.dependencies?.husky
+
+  if (!hasHusky) {
+    console.log('   Installing husky...')
+    execSync('npm install --save-dev husky', { stdio: 'inherit' })
+  }
+
+  // Initialize husky
+  const huskyDir = join(projectRoot, '.husky')
+  if (!existsSync(huskyDir)) {
+    console.log('   Initializing husky...')
+    execSync('npx husky init', { stdio: 'inherit' })
+  }
+
+  // Create pre-commit hook
+  const preCommitPath = join(huskyDir, 'pre-commit')
+  if (!existsSync(preCommitPath) || options.force) {
+    const preCommitContent = `#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+
+echo "🔍 Running VCA Quality checks..."
+
+# Run quick security checks (fast, blocks commit on critical issues)
+npx vca-audit quick
+if [ $? -ne 0 ]; then
+  echo ""
+  echo "❌ Security issues found! Fix before committing."
+  echo "   Run 'vca-audit' for detailed report."
+  exit 1
+fi
+
+# Run lint-staged if configured
+if [ -f "package.json" ] && grep -q "lint-staged" package.json; then
+  npx lint-staged
+fi
+
+echo "✅ Pre-commit checks passed"
+`
+    writeFileSync(preCommitPath, preCommitContent)
+    execSync(`chmod +x ${preCommitPath}`)
+    console.log('   ✅ Created .husky/pre-commit')
+  } else {
+    console.log('   ⏭️  .husky/pre-commit already exists (use --force to overwrite)')
+  }
+
+  // Add prepare script to package.json
+  if (!pkg.scripts?.prepare?.includes('husky')) {
+    pkg.scripts = pkg.scripts || {}
+    pkg.scripts.prepare = 'husky'
+    writeFileSync(packagePath, JSON.stringify(pkg, null, 2) + '\n')
+    console.log('   ✅ Added "prepare": "husky" to package.json')
+  }
+}
+
+async function setupCi(options) {
+  console.log('🔄 Setting up GitHub Actions workflow...')
+
+  const workflowDir = join(projectRoot, '.github/workflows')
+  if (!existsSync(workflowDir)) {
+    mkdirSync(workflowDir, { recursive: true })
+  }
+
+  const workflowPath = join(workflowDir, 'quality.yml')
+  if (!existsSync(workflowPath) || options.force) {
+    const workflowContent = `name: Quality Checks
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  quality:
+    name: 🔍 VCA Quality Audit
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run VCA Quality Audit
+        run: npx @vca/quality-toolkit --ci
+
+      - name: Upload results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: quality-report
+          path: quality-report.json
+          retention-days: 7
+`
+    writeFileSync(workflowPath, workflowContent)
+    console.log('   ✅ Created .github/workflows/quality.yml')
+  } else {
+    console.log('   ⏭️  Workflow already exists (use --force to overwrite)')
+  }
+}
+
+async function setupConfig(options) {
+  console.log('📝 Setting up configuration...')
+
+  const configPath = join(projectRoot, '.vca-quality.json')
+  if (!existsSync(configPath) || options.force) {
+    const config = {
+      "$schema": "https://vca-tools.dev/schemas/quality-toolkit.json",
+      "suites": {
+        "security": true,
+        "stability": true,
+        "codeQuality": true,
+        "supabase": "auto"
+      },
+      "security": {
+        "checkHardcodedSecrets": true,
+        "checkServiceKeyExposure": true
+      },
+      "stability": {
+        "requireHusky": true,
+        "requireCiConfig": true,
+        "allowedVulnerabilities": {
+          "critical": 0,
+          "high": 0,
+          "moderate": 10
+        }
+      },
+      "ignore": [
+        "node_modules/**",
+        "dist/**",
+        "build/**",
+        ".next/**"
+      ]
+    }
+
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n')
+    console.log('   ✅ Created .vca-quality.json')
+  } else {
+    console.log('   ⏭️  Config already exists (use --force to overwrite)')
+  }
+}
+
+program.parse()