@soulbatical/tetra-dev-toolkit 1.1.0

package/lib/config.js

@@ -0,0 +1,213 @@
+/**
+ * VCA Quality Toolkit - Configuration
+ *
+ * Default configuration that can be overridden per project via:
+ * - .vca-quality.json in project root
+ * - vca-quality key in package.json
+ */
+
+import { readFileSync, existsSync } from 'fs'
+import { join } from 'path'
+
+export const DEFAULT_CONFIG = {
+  // Which check suites to run
+  suites: {
+    security: true,
+    stability: true,
+    codeQuality: true,
+    supabase: 'auto' // true, false, or 'auto' (detect)
+  },
+
+  // Security checks
+  security: {
+    // Supabase-specific
+    checkServiceKeyExposure: true,
+    checkRlsPolicies: true,
+    checkRpcSecurity: true,
+
+    // Secrets
+    checkHardcodedSecrets: true,
+    checkEnvInGitignore: true,
+    secretPatterns: [
+      'sk-[a-zA-Z0-9]{20,}',           // OpenAI
+      'sk_live_[a-zA-Z0-9]{20,}',      // Stripe
+      'sk_test_[a-zA-Z0-9]{20,}',      // Stripe test
+      'AKIA[A-Z0-9]{16}',              // AWS
+      'ghp_[a-zA-Z0-9]{36}',           // GitHub
+      'xox[baprs]-[a-zA-Z0-9-]{10,}',  // Slack
+      'eyJ[a-zA-Z0-9_-]*\\.[a-zA-Z0-9_-]*\\.[a-zA-Z0-9_-]*' // JWT
+    ],
+
+    // Code patterns
+    checkSqlInjection: true,
+    checkEvalUsage: true,
+    checkCommandInjection: true
+  },
+
+  // Stability checks
+  stability: {
+    // Testing
+    requireTestFramework: true,
+    requireTestFiles: true,
+    minTestFiles: 1,
+    requireCoverage: false,
+    minCoverage: 0,
+
+    // Linting
+    requireEslint: true,
+    requireSecurityPlugin: true,
+
+    // Pre-commit
+    requireHusky: true,
+    requirePreCommitHook: true,
+
+    // CI/CD
+    requireCiConfig: true,
+    requireTestsInCi: true,
+    requireLintInCi: true,
+
+    // Dependencies
+    requireLockFile: true,
+    allowedVulnerabilities: {
+      critical: 0,
+      high: 0,
+      moderate: 10
+    }
+  },
+
+  // Code quality checks
+  codeQuality: {
+    // Architecture
+    maxFileLines: 500,
+    checkCircularDeps: true,
+
+    // Dead code
+    runKnip: true,
+
+    // TypeScript
+    checkAnyTypes: true,
+    maxAnyCount: 10
+  },
+
+  // Supabase-specific checks
+  supabase: {
+    checkRls: true,
+    checkSecurityDefiner: true,
+    checkViewSecurity: true,
+    checkEdgeFunctions: true,
+
+    // Whitelist for intentionally public RPC functions
+    publicRpcFunctions: [],
+
+    // Tables that intentionally have no RLS (e.g., public lookup tables)
+    publicTables: []
+  },
+
+  // Paths
+  paths: {
+    backend: ['backend/src', 'src'],
+    frontend: ['frontend/src', 'src'],
+    migrations: ['supabase/migrations', 'migrations'],
+    tests: ['**/*.test.ts', '**/*.spec.ts', '**/*.test.tsx', '**/*.spec.tsx']
+  },
+
+  // Ignore patterns
+  ignore: [
+    'node_modules/**',
+    'dist/**',
+    'build/**',
+    '.next/**',
+    'coverage/**',
+    '*.min.js'
+  ],
+
+  // Output
+  output: {
+    format: 'terminal', // 'terminal', 'json', 'github-actions'
+    verbose: false,
+    failOn: 'error' // 'error', 'warning', 'none'
+  }
+}
+
+/**
+ * Load project-specific configuration
+ */
+export function loadConfig(projectRoot = process.cwd()) {
+  let projectConfig = {}
+
+  // Check for .vca-quality.json
+  const configFile = join(projectRoot, '.vca-quality.json')
+  if (existsSync(configFile)) {
+    try {
+      projectConfig = JSON.parse(readFileSync(configFile, 'utf-8'))
+    } catch (e) {
+      console.warn(`Warning: Could not parse ${configFile}`)
+    }
+  }
+
+  // Check for vca-quality in package.json
+  const packageFile = join(projectRoot, 'package.json')
+  if (existsSync(packageFile)) {
+    try {
+      const pkg = JSON.parse(readFileSync(packageFile, 'utf-8'))
+      if (pkg['vca-quality']) {
+        projectConfig = { ...projectConfig, ...pkg['vca-quality'] }
+      }
+    } catch (e) {
+      // Ignore
+    }
+  }
+
+  // Deep merge with defaults
+  return deepMerge(DEFAULT_CONFIG, projectConfig)
+}
+
+/**
+ * Deep merge two objects
+ */
+function deepMerge(target, source) {
+  const result = { ...target }
+
+  for (const key in source) {
+    if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])) {
+      result[key] = deepMerge(target[key] || {}, source[key])
+    } else {
+      result[key] = source[key]
+    }
+  }
+
+  return result
+}
+
+/**
+ * Detect if project uses Supabase
+ */
+export function detectSupabase(projectRoot = process.cwd()) {
+  const indicators = [
+    'supabase',
+    'supabase/migrations',
+    'supabase/functions'
+  ]
+
+  for (const indicator of indicators) {
+    if (existsSync(join(projectRoot, indicator))) {
+      return true
+    }
+  }
+
+  // Check package.json for supabase dependency
+  const packageFile = join(projectRoot, 'package.json')
+  if (existsSync(packageFile)) {
+    try {
+      const pkg = JSON.parse(readFileSync(packageFile, 'utf-8'))
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies }
+      if (deps['@supabase/supabase-js']) {
+        return true
+      }
+    } catch (e) {
+      // Ignore
+    }
+  }
+
+  return false
+}

package/lib/index.js

@@ -0,0 +1,17 @@
+/**
+ * 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.
+ */
+
+export { loadConfig, detectSupabase, DEFAULT_CONFIG } from './config.js'
+export { runAllChecks, runSecurityChecks, runStabilityChecks, runQuickCheck } from './runner.js'
+export { formatResults, formatGitHubActions } from './reporters/terminal.js'
+
+// Re-export individual checks for advanced usage
+export * as checks from './checks/index.js'
+
+// Health scanner (project ecosystem checks)
+export { scanProjectHealth, calculateHealthStatus } from './checks/health/index.js'

package/lib/reporters/terminal.js

@@ -0,0 +1,134 @@
+/**
+ * Terminal Reporter - Pretty output for CLI
+ */
+
+import chalk from 'chalk'
+
+const SEVERITY_COLORS = {
+  critical: chalk.bgRed.white.bold,
+  high: chalk.red.bold,
+  medium: chalk.yellow,
+  low: chalk.blue
+}
+
+const SEVERITY_ICONS = {
+  critical: '🚨',
+  high: '❌',
+  medium: '⚠️',
+  low: 'ℹ️'
+}
+
+export function formatResults(results, options = {}) {
+  const lines = []
+
+  // Header
+  lines.push('')
+  lines.push(chalk.bold('═══════════════════════════════════════════════════════════════'))
+  lines.push(chalk.bold.cyan('  🔍 VCA Quality Toolkit - Audit Results'))
+  lines.push(chalk.bold('═══════════════════════════════════════════════════════════════'))
+  lines.push('')
+
+  // Project info
+  lines.push(chalk.gray(`  Project: ${results.projectRoot}`))
+  lines.push(chalk.gray(`  Time: ${results.timestamp}`))
+  lines.push('')
+
+  // Summary box
+  const passed = results.passed
+  const statusIcon = passed ? '✅' : '❌'
+  const statusText = passed ? chalk.green.bold('PASSED') : chalk.red.bold('FAILED')
+
+  lines.push(chalk.bold(`  ${statusIcon} Overall Status: ${statusText}`))
+  lines.push('')
+
+  // Finding counts
+  const { findings } = results.summary
+  if (findings.critical + findings.high + findings.medium + findings.low > 0) {
+    lines.push(chalk.bold('  Findings:'))
+    if (findings.critical > 0) lines.push(`    ${SEVERITY_COLORS.critical(` ${findings.critical} CRITICAL `)}`)
+    if (findings.high > 0) lines.push(`    ${SEVERITY_COLORS.high(`${findings.high} High`)}`)
+    if (findings.medium > 0) lines.push(`    ${SEVERITY_COLORS.medium(`${findings.medium} Medium`)}`)
+    if (findings.low > 0) lines.push(`    ${SEVERITY_COLORS.low(`${findings.low} Low`)}`)
+    lines.push('')
+  }
+
+  // Suite results
+  for (const [suiteName, suite] of Object.entries(results.suites || {})) {
+    const suiteIcon = suite.passed ? '✅' : '❌'
+    lines.push(chalk.bold(`  ${suiteIcon} ${suiteName.toUpperCase()}`))
+    lines.push(chalk.gray('  ' + '─'.repeat(50)))
+
+    for (const check of suite.checks || []) {
+      const checkIcon = check.skipped ? '⏭️' : (check.passed ? '✅' : '❌')
+      const checkStatus = check.skipped
+        ? chalk.gray('SKIPPED')
+        : (check.passed ? chalk.green('PASS') : chalk.red('FAIL'))
+
+      lines.push(`    ${checkIcon} ${check.name} ${checkStatus}`)
+
+      // Show findings for failed checks
+      if (!check.passed && !check.skipped && check.findings) {
+        for (const finding of check.findings.slice(0, options.maxFindings || 5)) {
+          const icon = SEVERITY_ICONS[finding.severity] || '•'
+          const color = SEVERITY_COLORS[finding.severity] || chalk.white
+
+          lines.push(color(`       ${icon} ${finding.message}`))
+
+          if (finding.file) {
+            lines.push(chalk.gray(`          ${finding.file}:${finding.line || '?'}`))
+          }
+
+          if (finding.fix && options.verbose) {
+            lines.push(chalk.cyan(`          Fix: ${finding.fix}`))
+          }
+        }
+
+        if (check.findings.length > (options.maxFindings || 5)) {
+          lines.push(chalk.gray(`       ... and ${check.findings.length - 5} more`))
+        }
+      }
+
+      // Show skip reason
+      if (check.skipped && check.skipReason) {
+        lines.push(chalk.gray(`       (${check.skipReason})`))
+      }
+    }
+
+    lines.push('')
+  }
+
+  // Footer
+  lines.push(chalk.bold('═══════════════════════════════════════════════════════════════'))
+  lines.push(`  Checks: ${results.summary.passed} passed, ${results.summary.failed} failed, ${results.summary.skipped} skipped`)
+  lines.push(chalk.bold('═══════════════════════════════════════════════════════════════'))
+  lines.push('')
+
+  return lines.join('\n')
+}
+
+/**
+ * Format for GitHub Actions annotations
+ */
+export function formatGitHubActions(results) {
+  const annotations = []
+
+  for (const [, suite] of Object.entries(results.suites || {})) {
+    for (const check of suite.checks || []) {
+      if (!check.passed && !check.skipped && check.findings) {
+        for (const finding of check.findings) {
+          const level = finding.severity === 'critical' || finding.severity === 'high'
+            ? 'error'
+            : 'warning'
+
+          if (finding.file) {
+            annotations.push(`::${level} file=${finding.file},line=${finding.line || 1}::${finding.message}`)
+          } else {
+            annotations.push(`::${level}::${finding.message}`)
+          }
+        }
+      }
+    }
+  }
+
+  return annotations.join('\n')
+}

package/lib/runner.js

@@ -0,0 +1,179 @@
+/**
+ * VCA Quality Toolkit - Check Runner
+ *
+ * Orchestrates running all checks and collecting results
+ */
+
+import { loadConfig, detectSupabase } from './config.js'
+
+// Import all checks
+import * as hardcodedSecrets from './checks/security/hardcoded-secrets.js'
+import * as serviceKeyExposure from './checks/security/service-key-exposure.js'
+import * as deprecatedSupabaseAdmin from './checks/security/deprecated-supabase-admin.js'
+import * as systemdbWhitelist from './checks/security/systemdb-whitelist.js'
+import * as huskyHooks from './checks/stability/husky-hooks.js'
+import * as ciPipeline from './checks/stability/ci-pipeline.js'
+import * as npmAudit from './checks/stability/npm-audit.js'
+import * as apiResponseFormat from './checks/codeQuality/api-response-format.js'
+import * as gitignoreValidation from './checks/security/gitignore-validation.js'
+import * as rlsPolicyAudit from './checks/supabase/rls-policy-audit.js'
+
+// Register all checks
+const ALL_CHECKS = {
+  security: [
+    hardcodedSecrets,
+    serviceKeyExposure,
+    deprecatedSupabaseAdmin,
+    systemdbWhitelist,
+    gitignoreValidation
+  ],
+  stability: [
+    huskyHooks,
+    ciPipeline,
+    npmAudit
+  ],
+  codeQuality: [
+    apiResponseFormat
+  ],
+  supabase: [
+    rlsPolicyAudit
+  ]
+}
+
+/**
+ * Run all checks for a project
+ */
+export async function runAllChecks(options = {}) {
+  const projectRoot = options.projectRoot || process.cwd()
+  const config = loadConfig(projectRoot)
+  const suites = options.suites || ['security', 'stability', 'codeQuality', 'supabase']
+
+  // Auto-detect Supabase
+  if (config.suites.supabase === 'auto') {
+    config.suites.supabase = detectSupabase(projectRoot)
+  }
+
+  const results = {
+    projectRoot,
+    timestamp: new Date().toISOString(),
+    passed: true,
+    suites: {},
+    summary: {
+      total: 0,
+      passed: 0,
+      failed: 0,
+      skipped: 0,
+      findings: { critical: 0, high: 0, medium: 0, low: 0 }
+    }
+  }
+
+  for (const suite of suites) {
+    if (!config.suites[suite]) {
+      continue
+    }
+
+    const checks = ALL_CHECKS[suite] || []
+    results.suites[suite] = {
+      passed: true,
+      checks: []
+    }
+
+    for (const check of checks) {
+      const checkResult = {
+        id: check.meta.id,
+        name: check.meta.name,
+        severity: check.meta.severity,
+        ...await check.run(config, projectRoot)
+      }
+
+      results.suites[suite].checks.push(checkResult)
+
+      // Update suite status
+      if (!checkResult.passed && !checkResult.skipped) {
+        results.suites[suite].passed = false
+        results.passed = false
+        results.summary.failed++
+      } else if (checkResult.skipped) {
+        results.summary.skipped++
+      } else {
+        results.summary.passed++
+      }
+
+      // Aggregate findings
+      results.summary.total++
+      if (checkResult.summary) {
+        results.summary.findings.critical += checkResult.summary.critical || 0
+        results.summary.findings.high += checkResult.summary.high || 0
+        results.summary.findings.medium += checkResult.summary.medium || 0
+        results.summary.findings.low += checkResult.summary.low || 0
+      }
+    }
+  }
+
+  return results
+}
+
+/**
+ * Run only security checks
+ */
+export async function runSecurityChecks(options = {}) {
+  return runAllChecks({ ...options, suites: ['security'] })
+}
+
+/**
+ * Run only stability checks
+ */
+export async function runStabilityChecks(options = {}) {
+  return runAllChecks({ ...options, suites: ['stability'] })
+}
+
+/**
+ * Run only code quality checks
+ */
+export async function runCodeQualityChecks(options = {}) {
+  return runAllChecks({ ...options, suites: ['codeQuality'] })
+}
+
+/**
+ * Quick check - only critical checks
+ */
+export async function runQuickCheck(options = {}) {
+  const projectRoot = options.projectRoot || process.cwd()
+  const config = loadConfig(projectRoot)
+
+  // Run only critical security checks
+  const criticalChecks = [
+    hardcodedSecrets,
+    serviceKeyExposure
+  ]
+
+  const results = {
+    projectRoot,
+    timestamp: new Date().toISOString(),
+    passed: true,
+    checks: [],
+    summary: { total: 0, passed: 0, failed: 0, findings: { critical: 0 } }
+  }
+
+  for (const check of criticalChecks) {
+    const checkResult = {
+      id: check.meta.id,
+      name: check.meta.name,
+      ...await check.run(config, projectRoot)
+    }
+
+    results.checks.push(checkResult)
+
+    if (!checkResult.passed) {
+      results.passed = false
+      results.summary.failed++
+    } else {
+      results.summary.passed++
+    }
+
+    results.summary.total++
+    results.summary.findings.critical += checkResult.summary?.critical || 0
+  }
+
+  return results
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@soulbatical/tetra-dev-toolkit",
+  "version": "1.1.0",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "description": "Developer toolkit for all VCA projects - audit, dev-token, quality checks",
+  "author": "Albert Barth <albertbarth@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mralbertzwolle/vca-quality-toolkit"
+  },
+  "keywords": [
+    "quality",
+    "security",
+    "audit",
+    "dev-token",
+    "eslint",
+    "supabase",
+    "rls",
+    "pre-commit",
+    "ci-cd"
+  ],
+  "type": "module",
+  "main": "lib/index.js",
+  "bin": {
+    "vca-audit": "./bin/vca-audit.js",
+    "vca-security": "./bin/vca-security.js",
+    "vca-stability": "./bin/vca-stability.js",
+    "vca-setup": "./bin/vca-setup.js",
+    "vca-dev-token": "./bin/vca-dev-token.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/"
+  ],
+  "scripts": {
+    "test": "node --test src/**/*.test.js",
+    "lint": "eslint src/ lib/ bin/",
+    "build": "echo 'No build step needed'",
+    "prepublishOnly": "npm test && npm run lint"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@supabase/supabase-js": "^2.48.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "dotenv": "^16.4.7",
+    "glob": "^10.3.10",
+    "ora": "^8.0.1",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "eslint": "^9.0.0"
+  },
+  "peerDependencies": {
+    "eslint": ">=8.0.0",
+    "typescript": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "eslint": {
+      "optional": true
+    },
+    "typescript": {
+      "optional": true
+    }
+  }
+}