@soulbatical/tetra-dev-toolkit 1.1.0

package/lib/checks/health/quality-toolkit.js

@@ -0,0 +1,97 @@
+/**
+ * Health Check: @vca/dev-toolkit Installation
+ *
+ * Checks if the quality toolkit is installed and CLI commands available.
+ * Score: 0 = not installed, 1 = installed, 2 = all commands available
+ *
+ * @param {Function} [getCachedCodeQuality] - Optional callback to get cached audit results
+ */
+
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { createCheck } from './types.js'
+
+export async function check(projectPath, { getCachedCodeQuality } = {}) {
+  const result = createCheck('quality-toolkit', 2, {
+    installed: false,
+    version: null,
+    commands: { 'vca-audit': false, 'vca-setup': false, 'vca-dev-token': false }
+  })
+
+  const packageJsonPath = join(projectPath, 'package.json')
+  if (!existsSync(packageJsonPath)) {
+    result.status = 'warning'
+    result.details.message = 'No package.json found'
+    return result
+  }
+
+  try {
+    const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'))
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies }
+    const toolkitDep = allDeps['@vca/dev-toolkit'] || allDeps['@vca/quality-toolkit']
+
+    if (!toolkitDep) {
+      result.status = 'warning'
+      result.details.message = 'Not installed'
+      result.details.installCommand = 'npm install --save-dev /Users/albertbarth/projecten/vca-quality-toolkit'
+      return result
+    }
+
+    result.details.installed = true
+    result.details.dependencyVersion = toolkitDep
+    result.score = 1
+
+    // Get installed version from node_modules
+    for (const pkgName of ['dev-toolkit', 'quality-toolkit']) {
+      const toolkitPackagePath = join(projectPath, 'node_modules', '@vca', pkgName, 'package.json')
+      if (existsSync(toolkitPackagePath)) {
+        try {
+          result.details.version = JSON.parse(readFileSync(toolkitPackagePath, 'utf-8')).version
+        } catch {
+          result.details.version = 'unknown'
+        }
+        break
+      }
+    }
+
+    // Check CLI commands
+    const binPath = join(projectPath, 'node_modules', '.bin')
+    const commands = ['vca-audit', 'vca-setup', 'vca-dev-token']
+    for (const cmd of commands) {
+      result.details.commands[cmd] = existsSync(join(binPath, cmd))
+    }
+
+    if (commands.every(cmd => result.details.commands[cmd])) {
+      result.score = 2
+    } else {
+      result.status = 'warning'
+      result.details.message = 'Some CLI commands missing - try npm install'
+    }
+  } catch {
+    result.status = 'error'
+    result.details.error = 'Failed to check package.json'
+  }
+
+  // Merge cached audit results (informational, doesn't affect score)
+  if (getCachedCodeQuality) {
+    const projectName = projectPath.split('/').pop() || ''
+    const auditResult = getCachedCodeQuality(projectName)
+    if (auditResult) {
+      result.details.audit = {
+        passed: auditResult.passed,
+        summary: auditResult.summary,
+        apiCompliance: auditResult.apiCompliance,
+        suites: {
+          security: auditResult.suites.security?.passed ?? null,
+          stability: auditResult.suites.stability?.passed ?? null,
+          codeQuality: auditResult.suites.codeQuality?.passed ?? null
+        },
+        scannedAt: auditResult.scannedAt
+      }
+    } else {
+      result.details.audit = null
+    }
+  }
+
+  return result
+}

package/lib/checks/health/repo-visibility.js

@@ -0,0 +1,70 @@
+/**
+ * Health Check: Repository Visibility
+ *
+ * Checks if GitHub repo is public (security risk) or private.
+ * Score: 2 = private, 0 = public (critical)
+ */
+
+import { existsSync } from 'fs'
+import { execSync } from 'child_process'
+import { join } from 'path'
+import { createCheck } from './types.js'
+
+export async function check(projectPath) {
+  const result = createCheck('repo-visibility', 2, {
+    visibility: 'unknown', remoteUrl: null, owner: null, repo: null
+  })
+  result.score = 2
+
+  if (!existsSync(join(projectPath, '.git'))) {
+    result.status = 'warning'; result.score = 0
+    result.details.visibility = 'no-repo'; result.details.message = 'Not a git repository'
+    return result
+  }
+
+  let remoteUrl
+  try {
+    remoteUrl = execSync('git remote get-url origin', { cwd: projectPath, encoding: 'utf-8', timeout: 5000 }).trim()
+  } catch {
+    result.details.visibility = 'no-remote'; result.details.message = 'No remote origin configured'
+    return result
+  }
+  result.details.remoteUrl = remoteUrl
+
+  const match = remoteUrl.match(/github\.com[\/:]+([^/]+)\/([^/.]+)/)
+  if (!match) {
+    result.details.visibility = 'non-github'; result.details.message = 'Not a GitHub repo (visibility check skipped)'
+    return result
+  }
+
+  const [, owner, repo] = match
+  result.details.owner = owner
+  result.details.repo = repo
+
+  try {
+    const response = await fetch(`https://api.github.com/repos/${owner}/${repo}`, {
+      headers: { 'User-Agent': 'vca-health-check' },
+      signal: AbortSignal.timeout(5000)
+    })
+
+    if (response.status === 200) {
+      const data = await response.json()
+      result.details.visibility = data.private ? 'private' : 'public'
+      if (!data.private) {
+        result.status = 'error'; result.score = 0
+        result.details.message = 'REPOSITORY IS PUBLIC — anyone can see your code!'
+        result.details.htmlUrl = data.html_url
+      }
+    } else if (response.status === 404) {
+      result.details.visibility = 'private' // 404 = private or doesn't exist
+    } else {
+      result.details.visibility = 'unknown'; result.score = 1; result.status = 'warning'
+      result.details.message = `GitHub API returned ${response.status}`
+    }
+  } catch {
+    result.details.visibility = 'unknown'; result.score = 1; result.status = 'warning'
+    result.details.message = 'Could not reach GitHub API'
+  }
+
+  return result
+}

package/lib/checks/health/rls-audit.js

@@ -0,0 +1,130 @@
+/**
+ * Health Check: RLS Policies in SQL Migrations
+ *
+ * Builds table state from migrations, checks RLS enabled + policies exist.
+ * Score: 3 (full) with deductions for missing RLS, missing policies, permissive policies
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'fs'
+import { join } from 'path'
+import { createCheck } from './types.js'
+
+export async function check(projectPath) {
+  const result = createCheck('rls-audit', 3, {
+    tablesFound: 0,
+    tablesWithRls: 0,
+    tablesWithoutRls: [],
+    tablesWithoutPolicies: [],
+    permissivePolicies: [],
+    securityDefinerFunctions: []
+  })
+  result.score = 3 // Start full, deduct for issues
+
+  const migrationDirs = [
+    join(projectPath, 'supabase', 'migrations'),
+    join(projectPath, 'backend', 'supabase', 'migrations')
+  ]
+
+  const sqlFiles = []
+  for (const dir of migrationDirs) {
+    if (!existsSync(dir)) continue
+    try {
+      for (const f of readdirSync(dir).filter(f => f.endsWith('.sql')).sort()) {
+        sqlFiles.push(join(dir, f))
+      }
+    } catch { /* ignore */ }
+  }
+
+  if (sqlFiles.length === 0) {
+    result.details.message = 'No SQL migrations found'
+    return result
+  }
+
+  // Build table state from migrations
+  const tables = new Map()
+
+  for (const filePath of sqlFiles) {
+    let content
+    try { content = readFileSync(filePath, 'utf-8') } catch { continue }
+    const fileName = filePath.split('/').pop() || ''
+    let m
+
+    // CREATE TABLE
+    const createRe = /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?(?:public\.)?["']?(\w+)["']?/gi
+    while ((m = createRe.exec(content)) !== null) {
+      const name = m[1].toLowerCase()
+      if (!tables.has(name)) tables.set(name, { rlsEnabled: false, policies: [], file: fileName })
+    }
+
+    // DROP TABLE
+    const dropRe = /DROP\s+TABLE\s+(?:IF\s+EXISTS\s+)?(?:public\.)?["']?(\w+)["']?/gi
+    while ((m = dropRe.exec(content)) !== null) tables.delete(m[1].toLowerCase())
+
+    // RENAME TABLE
+    const renameRe = /ALTER\s+TABLE\s+(?:IF\s+EXISTS\s+)?(?:public\.)?["']?(\w+)["']?\s+RENAME\s+TO\s+["']?(\w+)["']?/gi
+    while ((m = renameRe.exec(content)) !== null) {
+      const data = tables.get(m[1].toLowerCase())
+      if (data) { tables.delete(m[1].toLowerCase()); tables.set(m[2].toLowerCase(), data) }
+    }
+
+    // ENABLE/DISABLE RLS
+    const enableRe = /ALTER\s+TABLE\s+(?:public\.)?["']?(\w+)["']?\s+ENABLE\s+ROW\s+LEVEL\s+SECURITY/gi
+    while ((m = enableRe.exec(content)) !== null) {
+      const name = m[1].toLowerCase()
+      if (tables.has(name)) tables.get(name).rlsEnabled = true
+      else tables.set(name, { rlsEnabled: true, policies: [], file: fileName })
+    }
+    const disableRe = /ALTER\s+TABLE\s+(?:public\.)?["']?(\w+)["']?\s+DISABLE\s+ROW\s+LEVEL\s+SECURITY/gi
+    while ((m = disableRe.exec(content)) !== null) {
+      if (tables.has(m[1].toLowerCase())) tables.get(m[1].toLowerCase()).rlsEnabled = false
+    }
+
+    // CREATE POLICY
+    const policyRe = /CREATE\s+POLICY\s+"([^"]+)"\s+ON\s+(?:public\.)?["']?(\w+)["']?\s+([\s\S]*?)(?:;|CREATE\s|ALTER\s|DROP\s|GRANT\s)/gi
+    while ((m = policyRe.exec(content)) !== null) {
+      const tableName = m[2].toLowerCase()
+      if (!tables.has(tableName)) tables.set(tableName, { rlsEnabled: false, policies: [], file: fileName })
+      tables.get(tableName).policies.push(m[1])
+      if (/USING\s*\(\s*true\s*\)/i.test(m[3]) || /WITH\s+CHECK\s*\(\s*true\s*\)/i.test(m[3])) {
+        result.details.permissivePolicies.push(`${m[1]} on ${tableName}`)
+      }
+    }
+
+    // DROP POLICY
+    const dropPolicyRe = /DROP\s+POLICY\s+(?:IF\s+EXISTS\s+)?"([^"]+)"\s+ON\s+(?:public\.)?["']?(\w+)["']?/gi
+    while ((m = dropPolicyRe.exec(content)) !== null) {
+      const t = tables.get(m[2].toLowerCase())
+      if (t) t.policies = t.policies.filter(p => p !== m[1])
+    }
+
+    // SECURITY DEFINER
+    const secDefRe = /CREATE\s+(?:OR\s+REPLACE\s+)?FUNCTION\s+(?:public\.)?["']?(\w+)["']?[\s\S]*?SECURITY\s+DEFINER/gi
+    while ((m = secDefRe.exec(content)) !== null) {
+      result.details.securityDefinerFunctions.push(m[1])
+    }
+  }
+
+  // Analyze
+  result.details.tablesFound = tables.size
+  let tablesWithRls = 0
+
+  for (const [name, info] of tables) {
+    if (name.startsWith('_') || name.startsWith('pg_') || name.startsWith('auth_')) continue
+    if (!info.rlsEnabled) {
+      result.details.tablesWithoutRls.push(name)
+    } else {
+      tablesWithRls++
+      if (info.policies.length === 0) result.details.tablesWithoutPolicies.push(name)
+    }
+  }
+
+  result.details.tablesWithRls = tablesWithRls
+
+  if (result.details.tablesWithoutRls.length > 0) { result.score -= 1.5; result.status = 'error'; result.details.message = `${result.details.tablesWithoutRls.length} table(s) without RLS` }
+  if (result.details.tablesWithoutPolicies.length > 0) { result.score -= 0.5; if (result.status === 'ok') result.status = 'warning' }
+  if (result.details.permissivePolicies.length > 0) { result.score -= 0.5; if (result.status === 'ok') result.status = 'warning' }
+  if (result.details.securityDefinerFunctions.length > 0) { result.score -= 0.5; if (result.status === 'ok') result.status = 'warning' }
+
+  result.score = Math.max(0, result.score)
+  return result
+}

package/lib/checks/health/scanner.js

@@ -0,0 +1,68 @@
+/**
+ * Project Health Scanner
+ *
+ * Orchestrates all 15 health checks and produces a HealthReport.
+ * This is the main entry point — consumers call scanProjectHealth().
+ */
+
+import { check as checkPlugins } from './plugins.js'
+import { check as checkMcps } from './mcps.js'
+import { check as checkGit } from './git.js'
+import { check as checkTests } from './tests.js'
+import { check as checkSecrets } from './secrets.js'
+import { check as checkQualityToolkit } from './quality-toolkit.js'
+import { check as checkNamingConventions } from './naming-conventions.js'
+import { check as checkRlsPolicies } from './rls-audit.js'
+import { check as checkGitignore } from './gitignore.js'
+import { check as checkRepoVisibility } from './repo-visibility.js'
+import { check as checkVinciFoxWidget } from './vincifox-widget.js'
+import { check as checkStellaIntegration } from './stella-integration.js'
+import { check as checkClaudeMd } from './claude-md.js'
+import { check as checkDopplerCompliance } from './doppler-compliance.js'
+import { check as checkInfrastructureYml } from './infrastructure-yml.js'
+import { calculateHealthStatus } from './types.js'
+
+/**
+ * Run full health check on a project
+ *
+ * @param {string} projectPath - Absolute path to project root
+ * @param {string} projectName - Display name for the project
+ * @param {Object} [options]
+ * @param {Function} [options.getCachedCodeQuality] - Callback for cached audit results (ralph-manager specific)
+ * @returns {Promise<import('./types.js').HealthReport>}
+ */
+export async function scanProjectHealth(projectPath, projectName, options = {}) {
+  // Run all checks in parallel
+  const checks = await Promise.all([
+    checkPlugins(projectPath),
+    checkMcps(projectPath),
+    checkGit(projectPath),
+    checkTests(projectPath),
+    checkSecrets(projectPath),
+    checkQualityToolkit(projectPath, { getCachedCodeQuality: options.getCachedCodeQuality }),
+    checkNamingConventions(projectPath),
+    checkRlsPolicies(projectPath),
+    checkGitignore(projectPath),
+    checkRepoVisibility(projectPath),
+    checkVinciFoxWidget(projectPath),
+    checkStellaIntegration(projectPath),
+    checkClaudeMd(projectPath),
+    checkDopplerCompliance(projectPath),
+    checkInfrastructureYml(projectPath)
+  ])
+
+  const totalScore = checks.reduce((sum, c) => sum + c.score, 0)
+  const maxScore = checks.reduce((sum, c) => sum + c.maxScore, 0)
+  const healthPercent = maxScore > 0 ? Math.round((totalScore / maxScore) * 100) : 0
+
+  return {
+    projectName,
+    projectPath,
+    overallScore: totalScore,
+    maxScore,
+    healthPercent,
+    status: calculateHealthStatus(checks),
+    checks,
+    scannedAt: new Date().toISOString()
+  }
+}

package/lib/checks/health/secrets.js

@@ -0,0 +1,80 @@
+/**
+ * Health Check: Exposed Secrets in Markdown/Config Files
+ *
+ * Scans .ralph/, README.md, and specs for hardcoded secrets.
+ * Score: 2 (full) if no secrets, 0 if any found
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'fs'
+import { join } from 'path'
+import { createCheck, maskSecret } from './types.js'
+
+const SECRET_PATTERNS = [
+  { name: 'API Key', pattern: /(?:api[_-]?key|apikey)\s*[=:]\s*["']?([a-zA-Z0-9_\-]{20,})["']?/gi },
+  { name: 'Secret Key', pattern: /(?:secret[_-]?key|secretkey)\s*[=:]\s*["']?([a-zA-Z0-9_\-]{20,})["']?/gi },
+  { name: 'Access Token', pattern: /(?:access[_-]?token|accesstoken)\s*[=:]\s*["']?([a-zA-Z0-9_\-]{20,})["']?/gi },
+  { name: 'AWS Key', pattern: /AKIA[A-Z0-9]{16}/g },
+  { name: 'GitHub Token', pattern: /gh[pousr]_[A-Za-z0-9_]{36,}/g },
+  { name: 'Supabase JWT', pattern: /eyJ[A-Za-z0-9_-]{50,}\.[A-Za-z0-9_-]{50,}\.[A-Za-z0-9_-]{50,}/g },
+  { name: 'Bearer Token', pattern: /Bearer\s+[A-Za-z0-9_\-\.]{20,}/gi },
+  { name: 'Password', pattern: /(?:password|passwd|pwd)\s*[=:]\s*["']([^"'\s]{8,})["']/gi }
+]
+
+export async function check(projectPath) {
+  const result = createCheck('secrets', 2, { exposedSecrets: [], scannedFiles: 0 })
+  result.score = 2 // Full score unless we find something
+
+  const filesToScan = [
+    '.ralph/PROMPT.md',
+    '.ralph/@fix_plan.md',
+    'README.md',
+    'docs/README.md'
+  ]
+
+  // Also scan .ralph/specs/
+  const specsPath = join(projectPath, '.ralph', 'specs')
+  if (existsSync(specsPath)) {
+    try {
+      for (const spec of readdirSync(specsPath)) {
+        if (spec.endsWith('.md')) filesToScan.push(`.ralph/specs/${spec}`)
+      }
+    } catch { /* ignore */ }
+  }
+
+  const exposedSecrets = []
+
+  for (const file of filesToScan) {
+    const filePath = join(projectPath, file)
+    if (!existsSync(filePath)) continue
+    result.details.scannedFiles++
+
+    try {
+      const content = readFileSync(filePath, 'utf-8')
+      const lines = content.split('\n')
+
+      for (let i = 0; i < lines.length; i++) {
+        for (const { name, pattern } of SECRET_PATTERNS) {
+          pattern.lastIndex = 0
+          for (const match of lines[i].matchAll(pattern)) {
+            const value = match[1] || match[0]
+            const masked = maskSecret(value)
+            const exists = exposedSecrets.some(s => s.file === file && s.line === i + 1 && s.masked === masked)
+            if (!exists) {
+              exposedSecrets.push({ type: name, file, line: i + 1, masked })
+            }
+          }
+        }
+      }
+    } catch { /* ignore */ }
+  }
+
+  result.details.exposedSecrets = exposedSecrets
+
+  if (exposedSecrets.length > 0) {
+    result.status = 'error'
+    result.score = 0
+    result.details.message = `Found ${exposedSecrets.length} potential exposed secrets`
+  }
+
+  return result
+}

package/lib/checks/health/stella-integration.js

@@ -0,0 +1,124 @@
+/**
+ * Health Check: @ralph/stella Integration
+ *
+ * Checks for @ralph/stella dependency and integration level in MCP server.
+ * Score: 0 = not installed, 1 = basic, 2 = full integration
+ */
+
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { createCheck } from './types.js'
+
+export async function check(projectPath) {
+  const result = createCheck('stella-integration', 2, {
+    installed: false, version: null, integrationLevel: 'none', features: [], packageLocation: null
+  })
+
+  // Search for @ralph/stella in package.json files
+  const packageLocations = [
+    { path: join(projectPath, 'package.json'), label: 'root' },
+    { path: join(projectPath, 'mcp', 'package.json'), label: 'mcp/' },
+    { path: join(projectPath, 'backend-mcp', 'package.json'), label: 'backend-mcp/' },
+  ]
+
+  let stellaDep = null
+  let stellaLocation = null
+
+  for (const loc of packageLocations) {
+    if (!existsSync(loc.path)) continue
+    try {
+      const pkg = JSON.parse(readFileSync(loc.path, 'utf-8'))
+      const allDeps = { ...pkg.dependencies, ...pkg.devDependencies }
+      if (allDeps['@ralph/stella']) {
+        stellaDep = allDeps['@ralph/stella']
+        stellaLocation = loc.label
+        break
+      }
+    } catch { /* ignore */ }
+  }
+
+  if (!stellaDep) {
+    result.status = 'warning'
+    result.details.message = 'Not installed'
+    return result
+  }
+
+  result.details.installed = true
+  result.details.dependencyRef = stellaDep
+  result.details.packageLocation = stellaLocation
+  result.score = 1
+
+  // Get installed version
+  const nmPaths = [
+    join(projectPath, 'node_modules', '@ralph', 'stella', 'package.json'),
+    join(projectPath, stellaLocation || '', 'node_modules', '@ralph', 'stella', 'package.json'),
+  ]
+  for (const nmPath of nmPaths) {
+    if (!existsSync(nmPath)) continue
+    try {
+      result.details.version = JSON.parse(readFileSync(nmPath, 'utf-8')).version || null
+      break
+    } catch { /* ignore */ }
+  }
+
+  // Detect integration level from MCP server source
+  const mcpIndexPaths = [
+    join(projectPath, 'mcp', 'src', 'index.ts'),
+    join(projectPath, 'backend-mcp', 'src', 'index.ts'),
+    join(projectPath, 'src', 'index.ts'),
+  ]
+
+  let mcpSource = null
+  for (const p of mcpIndexPaths) {
+    if (!existsSync(p)) continue
+    try { mcpSource = readFileSync(p, 'utf-8'); break } catch { /* ignore */ }
+  }
+
+  if (mcpSource) {
+    const features = []
+    const featureChecks = [
+      ['isAkkoordGiven', 'akkoord-gate'],
+      ['checkIdentityGate', 'identity-gate'],
+      ['checkEvaluationGate', 'evaluation-gate'],
+      ['checkReflectionGate', 'reflection-gate'],
+      ['processInlineStatus', 'inline-params'],
+      ['processInlineReview', 'inline-params'],
+      ['processInlineReflection', 'inline-params'],
+      ['afterToolCall', 'reflection-counting'],
+      ['getLargeResponseTip', 'large-response-gate'],
+      ['getContextualTip', 'contextual-tips'],
+      ['getEvaluationCountdown', 'eval-countdown'],
+      ['getContextWarning', 'token-tracking'],
+      ['token-tracker', 'token-tracking'],
+      ['apiMonitor', 'api-monitoring'],
+      ['api-monitor', 'api-monitoring'],
+      ['batch_tools', 'batch-tools'],
+      ['batchTools', 'batch-tools'],
+    ]
+
+    for (const [pattern, feature] of featureChecks) {
+      if (mcpSource.includes(pattern) && !features.includes(feature)) features.push(feature)
+    }
+
+    if (mcpSource.includes('withGates') && !mcpSource.includes('isAkkoordGiven')) features.push('withGates-wrapper')
+
+    result.details.features = features
+
+    const hasExplicitGates = features.includes('akkoord-gate') && features.includes('identity-gate')
+    const hasMonitoring = features.includes('token-tracking') || features.includes('api-monitoring')
+
+    if (hasExplicitGates && hasMonitoring && features.length >= 8) {
+      result.details.integrationLevel = 'full'
+      result.score = 2
+    } else if (features.length >= 1) {
+      result.details.integrationLevel = 'basic'
+      result.status = 'warning'
+      result.details.message = `Basic integration (${features.length} features) — upgrade to full gate orchestration`
+    }
+  } else {
+    result.status = 'warning'
+    result.details.message = 'Installed but no MCP server source found'
+  }
+
+  return result
+}