@soulbatical/tetra-dev-toolkit 1.1.0

package/lib/checks/codeQuality/api-response-format.js

@@ -0,0 +1,268 @@
+/**
+ * Check API response format consistency
+ *
+ * Validates that all res.json() calls follow the standard format:
+ * - Success: { success: true, data: ... }
+ * - Error:   { success: false, error: "..." }
+ * - List:    { success: true, data: [...], meta: { total, limit, offset, hasMore } }
+ *
+ * Based on SparkBuddy-Live response format standard.
+ * Works with both feature-based (controllers) and route-based (routes) architectures.
+ */
+
+import { glob } from 'glob'
+import { readFileSync } from 'fs'
+
+export const meta = {
+  id: 'api-response-format',
+  name: 'API Response Format Consistency',
+  category: 'codeQuality',
+  severity: 'high',
+  description: 'Validates all API responses follow { success, data/error } standard format'
+}
+
+export async function run(config, projectRoot) {
+  const results = {
+    passed: true,
+    findings: [],
+    summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 },
+    info: {
+      totalEndpoints: 0,
+      compliant: 0,
+      violations: 0
+    }
+  }
+
+  // Find all route and controller files
+  const patterns = [
+    '**/routes/**/*.ts',
+    '**/routes/**/*.js',
+    '**/controllers/**/*.ts',
+    '**/controllers/**/*.js',
+    '**/features/**/controllers/**/*.ts',
+    '**/features/**/*.controller.ts'
+  ]
+
+  let files = []
+  for (const pattern of patterns) {
+    const found = await glob(pattern, {
+      cwd: projectRoot,
+      ignore: [
+        ...(config.ignore || []),
+        'node_modules/**',
+        '**/node_modules/**',
+        'dist/**',
+        '**/dist/**',
+        'build/**',
+        '**/build/**',
+        '**/*.test.*',
+        '**/*.spec.*',
+        '**/*.d.ts',
+        '**/*.js.map'
+      ]
+    })
+    files.push(...found)
+  }
+
+  // Deduplicate
+  files = [...new Set(files)]
+
+  if (files.length === 0) {
+    results.skipped = true
+    results.skipReason = 'No route or controller files found'
+    return results
+  }
+
+  for (const file of files) {
+    const filePath = `${projectRoot}/${file}`
+    let content
+    try {
+      content = readFileSync(filePath, 'utf-8')
+    } catch {
+      continue
+    }
+
+    const lines = content.split('\n')
+    analyzeFile(file, lines, results)
+  }
+
+  results.passed = results.findings.filter(f => f.severity === 'critical' || f.severity === 'high').length === 0
+  results.info.violations = results.findings.length
+  results.info.compliant = results.info.totalEndpoints - results.info.violations
+
+  return results
+}
+
+function analyzeFile(file, lines, results) {
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+
+    // Skip comments, imports, type definitions
+    const trimmed = line.trim()
+    if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*') ||
+        trimmed.startsWith('import') || trimmed.startsWith('export type') ||
+        trimmed.startsWith('export interface')) {
+      continue
+    }
+
+    // Skip SSE responses (res.write)
+    if (trimmed.includes('res.write(') || trimmed.includes('res.end(')) {
+      continue
+    }
+
+    // Find res.json() or res.status().json() calls
+    if (!line.match(/res\.(json|status\s*\([^)]+\)\s*\.\s*json)\s*\(/)) {
+      continue
+    }
+
+    // Check for 204 No Content (valid without body)
+    if (line.match(/status\s*\(\s*204\s*\)/)) {
+      continue
+    }
+
+    results.info.totalEndpoints++
+
+    // Extract the complete response object using brace counting
+    const responseCode = extractResponseObject(lines, i)
+    if (!responseCode) continue
+
+    // Get function context for better error messages
+    const functionName = extractFunctionContext(lines, i)
+
+    // Validate the response
+    validateResponse(file, i + 1, responseCode, functionName, results)
+  }
+}
+
+function extractResponseObject(lines, startLine) {
+  let braceCount = 0
+  let content = ''
+  let foundOpenBrace = false
+
+  for (let j = startLine; j < Math.min(startLine + 30, lines.length); j++) {
+    const currentLine = lines[j]
+    content += currentLine + '\n'
+
+    for (const char of currentLine) {
+      if (char === '{') {
+        braceCount++
+        foundOpenBrace = true
+      }
+      if (char === '}') braceCount--
+    }
+
+    // Found complete object
+    if (foundOpenBrace && braceCount <= 0) {
+      return content
+    }
+  }
+
+  // Handle single-line responses like res.json(data) or res.json([...])
+  if (!foundOpenBrace) {
+    return content
+  }
+
+  return content
+}
+
+function extractFunctionContext(lines, lineNum) {
+  for (let i = lineNum - 1; i >= Math.max(0, lineNum - 30); i--) {
+    const line = lines[i]
+
+    // router.get/post/put/patch/delete
+    const routeMatch = line.match(/router\.(get|post|put|patch|delete)\s*\(\s*['"`]([^'"`]+)['"`]/)
+    if (routeMatch) return `${routeMatch[1].toUpperCase()} ${routeMatch[2]}`
+
+    // app.get/post etc
+    const appMatch = line.match(/app\.(get|post|put|patch|delete)\s*\(\s*['"`]([^'"`]+)['"`]/)
+    if (appMatch) return `${appMatch[1].toUpperCase()} ${appMatch[2]}`
+
+    // async function name
+    const asyncMatch = line.match(/async\s+(\w+)\s*\(/)
+    if (asyncMatch) return asyncMatch[1]
+
+    // const name = async
+    const arrowMatch = line.match(/const\s+(\w+)\s*=\s*async/)
+    if (arrowMatch) return arrowMatch[1]
+  }
+
+  return 'unknown'
+}
+
+function validateResponse(file, lineNum, responseCode, functionName, results) {
+  const isErrorResponse = responseCode.includes('success: false') ||
+    responseCode.includes('success:false') ||
+    /res\.status\s*\(\s*(4\d{2}|5\d{2})\s*\)/.test(responseCode)
+
+  const hasSuccess = /success\s*:/.test(responseCode)
+  const hasData = /\bdata\s*[:}]|\bdata\s*,/.test(responseCode) || /,\s*data\s*[,}]|{\s*data\s*[,}]/.test(responseCode)
+  const hasError = /\berror\s*:/.test(responseCode)
+  const hasResults = /\bresults\s*:/.test(responseCode)
+
+  // Check for raw array response: res.json(someArray) or res.json([...])
+  const isRawResponse = /res\.(json|status\s*\([^)]+\)\s*\.\s*json)\s*\(\s*[a-zA-Z_]/.test(responseCode) &&
+    !responseCode.includes('{')
+
+  if (isRawResponse) {
+    addFinding(results, {
+      file,
+      line: lineNum,
+      type: 'RAW_RESPONSE',
+      severity: 'critical',
+      message: `Raw response without wrapper in ${functionName}`,
+      fix: 'Wrap in { success: true, data: <value> }'
+    })
+    return
+  }
+
+  if (isErrorResponse) {
+    // Error response validation
+    if (!hasSuccess || !hasError) {
+      const missing = []
+      if (!hasSuccess) missing.push('success: false')
+      if (!hasError) missing.push('error')
+
+      addFinding(results, {
+        file,
+        line: lineNum,
+        type: 'INVALID_ERROR_RESPONSE',
+        severity: 'high',
+        message: `Error response missing ${missing.join(', ')} in ${functionName}`,
+        fix: 'Use { success: false, error: "message" }'
+      })
+    }
+  } else {
+    // Success response validation
+    const isBatch = /refresh|batch|bulk/i.test(functionName)
+    const hasValidData = hasData || (isBatch && hasResults)
+
+    if (!hasSuccess) {
+      addFinding(results, {
+        file,
+        line: lineNum,
+        type: 'MISSING_SUCCESS_WRAPPER',
+        severity: 'critical',
+        message: `Success response missing 'success: true' in ${functionName}`,
+        snippet: responseCode.substring(0, 120).replace(/\s+/g, ' ').trim(),
+        fix: 'Add success: true to response object'
+      })
+    } else if (!hasValidData && !hasError) {
+      addFinding(results, {
+        file,
+        line: lineNum,
+        type: 'SUCCESS_WITHOUT_DATA',
+        severity: 'high',
+        message: `Response has success but no data field in ${functionName}`,
+        fix: 'Add data field: { success: true, data: ... }'
+      })
+    }
+  }
+}
+
+function addFinding(results, finding) {
+  results.findings.push(finding)
+
+  const severity = finding.severity || 'medium'
+  results.summary.total++
+  results.summary[severity] = (results.summary[severity] || 0) + 1
+}

package/lib/checks/health/claude-md.js

@@ -0,0 +1,114 @@
+/**
+ * Health Check: CLAUDE.md Protocol Sections
+ *
+ * Verifies CLAUDE.md has the full Stella protocol (v2):
+ *   1. Session check-in (akkoord + identity)
+ *   2. 6-step howto process (search, make, load, plan, execute, evaluate)
+ *   3. Howto-maken (step 1b — never freestyle)
+ *   4. Ralph workflow
+ *   5. MCP fallback
+ *
+ * Score: 0-5 (1 per section present)
+ */
+
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { createCheck } from './types.js'
+
+export async function check(projectPath) {
+  const result = createCheck('claude-md', 5, {
+    exists: false,
+    hasSessionCheckin: false,
+    hasHowtoProtocol: false,
+    hasHowtoMaken: false,
+    hasRalphWorkflow: false,
+    hasMcpFallback: false,
+    missing: []
+  })
+
+  const claudeMdPath = join(projectPath, 'CLAUDE.md')
+  if (!existsSync(claudeMdPath)) {
+    result.status = 'error'
+    result.details.message = 'CLAUDE.md not found'
+    result.details.missing.push('CLAUDE.md file')
+    return result
+  }
+
+  result.details.exists = true
+  let content
+  try { content = readFileSync(claudeMdPath, 'utf-8') } catch {
+    result.status = 'error'; result.details.message = 'Could not read CLAUDE.md'; return result
+  }
+
+  // Check 1: Session check-in (stella_howto_akkoord + stella_confirm_identity)
+  const hasAkkoord = content.includes('howto_akkoord')
+  const hasIdentity = content.includes('confirm_identity')
+  if (hasAkkoord && hasIdentity) {
+    result.details.hasSessionCheckin = true
+    result.score += 1
+  } else {
+    const missing = []
+    if (!hasAkkoord) missing.push('stella_howto_akkoord')
+    if (!hasIdentity) missing.push('stella_confirm_identity')
+    result.details.missing.push(`Sessie inchecken: ${missing.join(', ')}`)
+  }
+
+  // Check 2: 6-step howto protocol (search + rate + plan + summarize)
+  const hasHowtoSearch = content.includes('howto_search')
+  const hasHowtoRate = content.includes('howto_rate')
+  const hasPlanCreate = content.includes('plan_create')
+  const hasSummarize = content.includes('summarize')
+
+  if (hasHowtoSearch && hasHowtoRate && hasPlanCreate && hasSummarize) {
+    result.details.hasHowtoProtocol = true
+    result.score += 1
+  } else {
+    const missing = []
+    if (!hasHowtoSearch) missing.push('howto_search')
+    if (!hasHowtoRate) missing.push('howto_rate')
+    if (!hasPlanCreate) missing.push('plan_create')
+    if (!hasSummarize) missing.push('summarize')
+    result.details.missing.push(`Howto protocol stappen: ${missing.join(', ')}`)
+  }
+
+  // Check 3: Howto-maken (step 1b — never freestyle, always create howto)
+  const hasHowtoUpsert = content.includes('howto_upsert')
+  const hasHowtoMaken = content.includes('HOW-TO MAKEN') || content.includes('howto maken')
+  const hasNeverFreestyle = content.includes('altijd eerst howto maken') || content.includes('NOOIT')
+
+  if (hasHowtoUpsert && (hasHowtoMaken || hasNeverFreestyle)) {
+    result.details.hasHowtoMaken = true
+    result.score += 1
+  } else {
+    const missing = []
+    if (!hasHowtoUpsert) missing.push('howto_upsert')
+    if (!hasHowtoMaken && !hasNeverFreestyle) missing.push('HOW-TO MAKEN stap / "altijd eerst howto maken"')
+    result.details.missing.push(`Howto-maken (stap 1b): ${missing.join(', ')}`)
+  }
+
+  // Check 4: Ralph workflow
+  if (/Ralph workflow/i.test(content) || (/@fix_plan/.test(content) && /\.ralph\/specs/.test(content))) {
+    result.details.hasRalphWorkflow = true
+    result.score += 1
+  } else {
+    result.details.missing.push('Ralph workflow sectie')
+  }
+
+  // Check 5: MCP fallback
+  if (/MCP niet bereikbaar|\/mcp/.test(content)) {
+    result.details.hasMcpFallback = true
+    result.score += 1
+  } else {
+    result.details.missing.push('MCP niet bereikbaar instructie')
+  }
+
+  if (result.score === 0) {
+    result.status = 'error'
+    result.details.message = 'CLAUDE.md exists but missing all required sections'
+  } else if (result.score < result.maxScore) {
+    result.status = 'warning'
+    result.details.message = `Missing: ${result.details.missing.join(', ')}`
+  }
+
+  return result
+}

package/lib/checks/health/doppler-compliance.js

@@ -0,0 +1,174 @@
+/**
+ * Health Check: Doppler Secret Management Compliance
+ *
+ * Checks: doppler.yaml exists, npm scripts use `doppler run`, no .env files with secrets.
+ * Recursively scans for ANY file containing secrets (not just .env in root dirs).
+ * Score: 0-3 (1 per aspect)
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs'
+import { join, relative } from 'path'
+import { createCheck } from './types.js'
+
+export async function check(projectPath) {
+  const result = createCheck('doppler-compliance', 3, {
+    hasDopplerYaml: false,
+    dopplerConfigs: [],
+    scriptsWithDoppler: [],
+    scriptsWithoutDoppler: [],
+    envFilesFound: [],
+    hasDotenvDep: false
+  })
+
+  // --- Check 1: doppler.yaml ---
+  const dopplerYamlPath = join(projectPath, 'doppler.yaml')
+  if (existsSync(dopplerYamlPath)) {
+    try {
+      const content = readFileSync(dopplerYamlPath, 'utf-8')
+      const configs = []
+      let currentEntry = {}
+
+      for (const line of content.split('\n')) {
+        const trimmed = line.trim()
+        if (trimmed.startsWith('- project:')) {
+          if (currentEntry.project) configs.push(currentEntry)
+          currentEntry = { project: trimmed.replace('- project:', '').trim() }
+        } else if (trimmed.startsWith('config:') && currentEntry.project) {
+          currentEntry.config = trimmed.replace('config:', '').trim()
+        } else if (trimmed.startsWith('path:') && currentEntry.project) {
+          currentEntry.path = trimmed.replace('path:', '').trim()
+        }
+      }
+      if (currentEntry.project) configs.push(currentEntry)
+
+      result.details.dopplerConfigs = configs
+      if (configs.some(c => c.project && c.config && c.path)) {
+        result.details.hasDopplerYaml = true
+        result.score += 1
+      } else {
+        result.details.dopplerYamlIssue = 'doppler.yaml exists but has no valid setup entries'
+      }
+    } catch {
+      result.details.dopplerYamlIssue = 'Could not parse doppler.yaml'
+    }
+  }
+
+  // --- Check 2: npm scripts use `doppler run` ---
+  const packageJsonPaths = [
+    { path: join(projectPath, 'package.json'), label: 'root' },
+    { path: join(projectPath, 'backend', 'package.json'), label: 'backend' },
+    { path: join(projectPath, 'bot', 'package.json'), label: 'bot' }
+  ]
+
+  const secretScriptPatterns = /^(dev|dev:backend|dev:bot|dev:all|dev:full)$/
+
+  for (const { path: pkgPath, label } of packageJsonPaths) {
+    if (!existsSync(pkgPath)) continue
+    try {
+      const scripts = JSON.parse(readFileSync(pkgPath, 'utf-8')).scripts || {}
+      for (const [name, cmd] of Object.entries(scripts)) {
+        if (!secretScriptPatterns.test(name)) continue
+        if (cmd.includes('doppler run')) result.details.scriptsWithDoppler.push(`${label}:${name}`)
+        else if (!cmd.includes('npm run dev --workspace') && !cmd.includes('npm:dev:')) {
+          result.details.scriptsWithoutDoppler.push(`${label}:${name}`)
+        }
+      }
+    } catch { /* ignore */ }
+  }
+
+  if (result.details.scriptsWithDoppler.length > 0 && result.details.scriptsWithoutDoppler.length === 0) {
+    result.score += 1
+  } else if (result.details.scriptsWithDoppler.length > 0) {
+    result.score += 0.5
+  }
+
+  // --- Check 3: No files with secrets on disk ---
+  // Recursively scan the project for any file that looks like it contains secrets.
+  // Matches: .env, .env.local, .env.production, episode-config.env, etc.
+  const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.turbo', '.cache', 'coverage', '__pycache__'])
+  const ALLOWED_FILES = new Set(['.env.example', 'frontend/.env', 'bot/.env.example'])
+  const SECRET_PATTERNS = [
+    /^(sk-|sk_live_|sk_test_)/,           // OpenAI / Stripe keys
+    /^(sb_secret_|sbp_)/,                  // Supabase service role
+    /^eyJ[A-Za-z0-9_-]{20,}/,             // JWT tokens
+    /^gh[pousr]_[A-Za-z0-9]{20,}/,        // GitHub tokens
+    /^AKIA[A-Z0-9]{12,}/,                 // AWS access keys
+    /^xox[bpsa]-[A-Za-z0-9-]{20,}/,       // Slack tokens
+    /^[A-Za-z0-9+/]{40,}={0,2}$/,         // Base64 encoded secrets (40+ chars)
+  ]
+  const PLACEHOLDER_VALUES = new Set(['your_value_here', 'xxx', 'TODO', 'CHANGE_ME', 'replace_me', ''])
+
+  function isSecretValue(value) {
+    const v = value.trim().replace(/^["']|["']$/g, '')
+    if (!v || PLACEHOLDER_VALUES.has(v)) return false
+    if (v.startsWith('http://localhost') || v.startsWith('https://localhost')) return false
+    if (SECRET_PATTERNS.some(p => p.test(v))) return true
+    // Generic: long alphanumeric values (20+ chars, not a URL)
+    if (v.length >= 20 && /^[A-Za-z0-9_+/=-]+$/.test(v) && !v.startsWith('http')) return true
+    return false
+  }
+
+  function scanDir(dir, depth = 0) {
+    if (depth > 5) return // prevent runaway recursion
+    try {
+      for (const entry of readdirSync(dir)) {
+        if (SKIP_DIRS.has(entry)) continue
+        const fullPath = join(dir, entry)
+        try {
+          const stat = statSync(fullPath)
+          if (stat.isDirectory()) {
+            scanDir(fullPath, depth + 1)
+          } else if (stat.isFile() && entry.includes('.env') && !entry.endsWith('.example')) {
+            const relPath = relative(projectPath, fullPath)
+            if (ALLOWED_FILES.has(relPath)) continue
+            try {
+              const content = readFileSync(fullPath, 'utf-8')
+              const hasSecrets = content.split('\n').some(line => {
+                const trimmed = line.trim()
+                if (!trimmed || trimmed.startsWith('#')) return false
+                const m = trimmed.match(/^([A-Z_][A-Z_0-9]*)\s*=\s*(.+)/)
+                if (!m) return false
+                return isSecretValue(m[2])
+              })
+              if (hasSecrets) result.details.envFilesFound.push(relPath)
+            } catch { /* ignore unreadable files */ }
+          }
+        } catch { /* ignore stat errors */ }
+      }
+    } catch { /* ignore unreadable dirs */ }
+  }
+
+  scanDir(projectPath)
+
+  // Check for dotenv dependency
+  for (const pkgPath of [join(projectPath, 'package.json'), join(projectPath, 'backend', 'package.json')]) {
+    if (!existsSync(pkgPath)) continue
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+      if ({ ...pkg.dependencies, ...pkg.devDependencies }['dotenv']) {
+        result.details.hasDotenvDep = true
+        break
+      }
+    } catch { /* ignore */ }
+  }
+
+  if (result.details.envFilesFound.length === 0 && !result.details.hasDotenvDep) result.score += 1
+  else if (result.details.envFilesFound.length === 0) result.score += 0.5
+
+  result.score = Math.min(result.score, result.maxScore)
+
+  if (result.score === 0) {
+    result.status = 'warning'
+    result.details.message = 'Not using Doppler — secrets may be in .env files'
+  } else if (result.score < result.maxScore) {
+    result.status = 'warning'
+    const issues = []
+    if (!result.details.hasDopplerYaml) issues.push('no doppler.yaml')
+    if (result.details.scriptsWithoutDoppler.length > 0) issues.push(`${result.details.scriptsWithoutDoppler.length} scripts without doppler run`)
+    if (result.details.envFilesFound.length > 0) issues.push(`${result.details.envFilesFound.length} .env files with secrets`)
+    if (result.details.hasDotenvDep) issues.push('dotenv dependency still present')
+    result.details.message = issues.join(', ')
+  }
+
+  return result
+}

package/lib/checks/health/git.js

@@ -0,0 +1,61 @@
+/**
+ * Health Check: Git Status
+ *
+ * Checks branch, uncommitted changes, and unpushed commits.
+ * Score: 3 (full) - deductions for uncommitted/unpushed changes
+ */
+
+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('git', 3)
+
+  if (!existsSync(join(projectPath, '.git'))) {
+    result.status = 'warning'
+    result.details.message = 'Not a git repository'
+    return result
+  }
+
+  try {
+    const branch = execSync('git rev-parse --abbrev-ref HEAD', {
+      cwd: projectPath, encoding: 'utf-8'
+    }).trim()
+    result.details.branch = branch
+
+    const status = execSync('git status --porcelain', {
+      cwd: projectPath, encoding: 'utf-8'
+    }).trim()
+    const uncommittedChanges = status.split('\n').filter(l => l.trim()).length
+    result.details.uncommittedChanges = uncommittedChanges
+
+    try {
+      const unpushed = execSync(`git log origin/${branch}..HEAD --oneline 2>/dev/null || echo ""`, {
+        cwd: projectPath, encoding: 'utf-8'
+      }).trim()
+      result.details.unpushedCommits = unpushed.split('\n').filter(l => l.trim()).length
+    } catch {
+      result.details.unpushedCommits = 0
+    }
+
+    result.score = 3
+    if (uncommittedChanges > 10) {
+      result.score -= 2
+      result.status = 'warning'
+    } else if (uncommittedChanges > 0) {
+      result.score -= 1
+    }
+    if (result.details.unpushedCommits > 5) {
+      result.score -= 1
+      result.status = 'warning'
+    }
+    result.score = Math.max(0, result.score)
+  } catch {
+    result.status = 'error'
+    result.details.error = 'Failed to check git status'
+  }
+
+  return result
+}