@soulbatical/tetra-dev-toolkit 1.1.0

package/lib/checks/health/tests.js

@@ -0,0 +1,140 @@
+/**
+ * Health Check: Test Pyramid
+ *
+ * Counts test files by level (unit/integration/e2e), detects frameworks.
+ * Score: up to 5 points for framework + pyramid coverage
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'fs'
+import { join } from 'path'
+import { createCheck } from './types.js'
+
+export async function check(projectPath) {
+  const result = createCheck('tests', 5, {
+    framework: null,
+    hasTestDir: false,
+    pyramid: { unit: 0, integration: 0, e2e: 0, total: 0 },
+    testFiles: { unit: [], integration: [], e2e: [] }
+  })
+
+  // Check for test directories
+  for (const dir of ['__tests__', 'tests', 'test', 'spec', 'e2e']) {
+    if (existsSync(join(projectPath, dir))) {
+      result.details.hasTestDir = true
+      result.details.testDir = dir
+      break
+    }
+  }
+
+  // Scan test files by level
+  const scanDir = (dir, level) => {
+    const dirPath = join(projectPath, dir)
+    if (!existsSync(dirPath)) return
+    try {
+      const walk = (path) => {
+        for (const entry of readdirSync(path, { withFileTypes: true })) {
+          const fullPath = join(path, entry.name)
+          if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules') {
+            walk(fullPath)
+          } else if (entry.isFile() && /\.(test|spec)\.(ts|tsx|js|jsx)$/.test(entry.name)) {
+            result.details.testFiles[level].push(fullPath.replace(projectPath + '/', ''))
+          }
+        }
+      }
+      walk(dirPath)
+    } catch { /* ignore */ }
+  }
+
+  // Unit: src dirs
+  for (const dir of ['src', 'backend/src', 'frontend/src', 'lib', 'mcp/src']) scanDir(dir, 'unit')
+  // Integration
+  for (const dir of ['tests/integration', 'backend/tests/integration', 'test/integration', '__tests__/integration']) scanDir(dir, 'integration')
+  // E2E
+  for (const dir of ['e2e', 'tests/e2e', 'test/e2e', 'cypress/e2e', 'playwright']) scanDir(dir, 'e2e')
+
+  // Also check top-level test dirs for non-categorized tests
+  for (const dir of ['tests', 'test', '__tests__', 'mcp/tests']) {
+    const dirPath = join(projectPath, dir)
+    if (!existsSync(dirPath)) continue
+    try {
+      for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
+        if (entry.isFile() && /\.(test|spec)\.(ts|tsx|js|jsx)$/.test(entry.name)) {
+          const relPath = `${dir}/${entry.name}`
+          if (!result.details.testFiles.unit.includes(relPath) &&
+              !result.details.testFiles.integration.includes(relPath)) {
+            result.details.testFiles.unit.push(relPath)
+          }
+        }
+      }
+    } catch { /* ignore */ }
+  }
+
+  // Playwright spec files in e2e/
+  const playwrightPath = join(projectPath, 'e2e')
+  if (existsSync(playwrightPath)) {
+    try {
+      for (const file of readdirSync(playwrightPath)) {
+        if (file.endsWith('.spec.ts') || file.endsWith('.spec.js')) {
+          const fullPath = `e2e/${file}`
+          if (!result.details.testFiles.e2e.includes(fullPath)) {
+            result.details.testFiles.e2e.push(fullPath)
+          }
+        }
+      }
+    } catch { /* ignore */ }
+  }
+
+  // Update pyramid counts
+  const p = result.details.pyramid
+  p.unit = result.details.testFiles.unit.length
+  p.integration = result.details.testFiles.integration.length
+  p.e2e = result.details.testFiles.e2e.length
+  p.total = p.unit + p.integration + p.e2e
+
+  // Detect test frameworks (check root + sub-packages)
+  const packageJsonPaths = [
+    join(projectPath, 'package.json'),
+    join(projectPath, 'backend', 'package.json'),
+    join(projectPath, 'frontend', 'package.json'),
+    join(projectPath, 'mcp', 'package.json'),
+  ]
+  const frameworks = []
+  for (const packageJsonPath of packageJsonPaths) {
+    if (!existsSync(packageJsonPath)) continue
+    try {
+      const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'))
+      const allDeps = { ...pkg.dependencies, ...pkg.devDependencies }
+      for (const fw of ['jest', 'vitest', 'mocha', 'ava', 'playwright', 'cypress', '@playwright/test']) {
+        if (allDeps[fw] || allDeps[`@types/${fw}`]) {
+          frameworks.push(fw.replace('@playwright/test', 'playwright'))
+        }
+      }
+      if (pkg.scripts?.test && !pkg.scripts.test.includes('no test')) result.details.hasTestScript = true
+      if (pkg.scripts?.['test:e2e']) result.details.hasE2EScript = true
+    } catch { /* ignore */ }
+  }
+  result.details.frameworks = [...new Set(frameworks)]
+  result.details.framework = result.details.frameworks[0] || null
+
+  // Scoring
+  if (result.details.framework) result.score += 1
+  if (p.unit >= 10) result.score += 1
+  else if (p.unit >= 1) result.score += 0.5
+  if (p.integration >= 5) result.score += 1
+  else if (p.integration >= 1) result.score += 0.5
+  if (p.e2e >= 3) result.score += 1
+  else if (p.e2e >= 1) result.score += 0.5
+  if (p.unit > 0 && p.integration > 0 && p.e2e > 0) result.score += 1
+
+  result.score = Math.min(result.score, result.maxScore)
+
+  if (result.score === 0) {
+    result.status = 'error'
+    result.details.message = 'No tests detected'
+  } else if (result.score < 3) {
+    result.status = 'warning'
+    result.details.message = 'Incomplete test coverage'
+  }
+
+  return result
+}

package/lib/checks/health/types.js

@@ -0,0 +1,77 @@
+/**
+ * Health Check Types & Helpers
+ *
+ * Shared types and utility functions for all health checks.
+ */
+
+/**
+ * @typedef {'plugins'|'mcps'|'git'|'tests'|'secrets'|'quality-toolkit'|'naming-conventions'|'rls-audit'|'gitignore'|'repo-visibility'|'vincifox-widget'|'stella-integration'|'claude-md'|'doppler-compliance'|'infrastructure-yml'} HealthCheckType
+ *
+ * @typedef {'ok'|'warning'|'error'} HealthStatus
+ *
+ * @typedef {Object} HealthCheck
+ * @property {HealthCheckType} type
+ * @property {HealthStatus} status
+ * @property {number} score
+ * @property {number} maxScore
+ * @property {Record<string, any>} details
+ *
+ * @typedef {Object} HealthReport
+ * @property {string} projectName
+ * @property {string} projectPath
+ * @property {number} overallScore
+ * @property {number} maxScore
+ * @property {number} healthPercent
+ * @property {'healthy'|'warning'|'unhealthy'} status
+ * @property {HealthCheck[]} checks
+ * @property {string} scannedAt
+ */
+
+/**
+ * Create a blank HealthCheck with defaults
+ * @param {HealthCheckType} type
+ * @param {number} maxScore
+ * @param {Record<string, any>} [details]
+ * @returns {HealthCheck}
+ */
+export function createCheck(type, maxScore, details = {}) {
+  return {
+    type,
+    status: 'ok',
+    score: 0,
+    maxScore,
+    details
+  }
+}
+
+/**
+ * Mask a secret value (show first 4 and last 4 chars)
+ * @param {string} value
+ * @returns {string}
+ */
+export function maskSecret(value) {
+  if (value.length <= 12) return '****'
+  return `${value.substring(0, 4)}...${value.substring(value.length - 4)}`
+}
+
+/**
+ * Calculate overall health status from checks
+ * @param {HealthCheck[]} checks
+ * @returns {'healthy'|'warning'|'unhealthy'}
+ */
+export function calculateHealthStatus(checks) {
+  const totalScore = checks.reduce((sum, c) => sum + c.score, 0)
+  const maxScore = checks.reduce((sum, c) => sum + c.maxScore, 0)
+  const percent = maxScore > 0 ? (totalScore / maxScore) * 100 : 0
+
+  // Critical checks override percentage
+  if (checks.some(c =>
+    (c.type === 'secrets' || c.type === 'rls-audit' || c.type === 'repo-visibility') && c.status === 'error'
+  )) {
+    return 'unhealthy'
+  }
+
+  if (percent >= 70) return 'healthy'
+  if (percent >= 40) return 'warning'
+  return 'unhealthy'
+}

package/lib/checks/health/vincifox-widget.js

@@ -0,0 +1,47 @@
+/**
+ * Health Check: VinciFox Feedback Widget
+ *
+ * Scans HTML/layout files for feedback-widget.js integration.
+ * Score: 0 = not found, 2 = installed
+ */
+
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { createCheck } from './types.js'
+
+const CANDIDATE_FILES = [
+  'index.html', 'frontend/index.html', 'src/index.html', 'public/index.html',
+  'src/app/layout.tsx', 'frontend/src/app/layout.tsx',
+  'frontend-user/src/app/layout.tsx', 'app/layout.tsx'
+]
+
+export async function check(projectPath) {
+  const result = createCheck('vincifox-widget', 2, { found: false, file: null, apiKey: null })
+
+  for (const file of CANDIDATE_FILES) {
+    const filePath = join(projectPath, file)
+    if (!existsSync(filePath)) continue
+
+    try {
+      const content = readFileSync(filePath, 'utf-8')
+      if (/feedback-widget\.js/.test(content)) {
+        result.details.found = true
+        result.details.file = file
+        result.score = 2
+
+        const keyMatch = content.match(/data-api-key="([a-f0-9]+)"/)
+        if (keyMatch) result.details.apiKey = keyMatch[1].substring(0, 8) + '...'
+
+        if (content.includes('api.vincifox.com')) result.details.environment = 'production'
+        else if (content.includes('localhost')) result.details.environment = 'development'
+
+        return result
+      }
+    } catch { /* ignore */ }
+  }
+
+  result.status = 'warning'
+  result.details.message = 'Widget not installed'
+  result.details.installUrl = 'https://www.vincifox.com/projects'
+  return result
+}

package/lib/checks/index.js

@@ -0,0 +1,17 @@
+/**
+ * All available checks
+ */
+
+// Security checks
+export * as hardcodedSecrets from './security/hardcoded-secrets.js'
+export * as serviceKeyExposure from './security/service-key-exposure.js'
+export * as deprecatedSupabaseAdmin from './security/deprecated-supabase-admin.js'
+export * as systemdbWhitelist from './security/systemdb-whitelist.js'
+
+// Stability checks
+export * as huskyHooks from './stability/husky-hooks.js'
+export * as ciPipeline from './stability/ci-pipeline.js'
+export * as npmAudit from './stability/npm-audit.js'
+
+// Health checks (project ecosystem)
+export * as health from './health/index.js'

package/lib/checks/security/deprecated-supabase-admin.js

@@ -0,0 +1,96 @@
+/**
+ * Check for deprecated supabaseAdmin usage (ralph-manager pattern)
+ *
+ * Projects should use:
+ * - systemDB('context') for system operations
+ * - userDB(req) for user-scoped operations
+ */
+
+import { glob } from 'glob'
+import { readFileSync, existsSync } from 'fs'
+
+export const meta = {
+  id: 'deprecated-supabase-admin',
+  name: 'Deprecated supabaseAdmin Usage',
+  category: 'security',
+  severity: 'high',
+  description: 'Detects direct supabaseAdmin usage - use systemDB(context) or userDB(req) instead'
+}
+
+export async function run(config, projectRoot) {
+  const results = {
+    passed: true,
+    findings: [],
+    summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 }
+  }
+
+  // Check if project uses the systemDB/userDB pattern
+  const hasSystemDb = existsSync(`${projectRoot}/backend/src/core/systemDb.ts`) ||
+                      existsSync(`${projectRoot}/src/core/systemDb.ts`)
+
+  if (!hasSystemDb) {
+    // Project doesn't use this pattern, skip check
+    results.skipped = true
+    results.skipReason = 'Project does not use systemDB/userDB pattern'
+    return results
+  }
+
+  // Get all backend TypeScript files
+  const files = await glob('**/*.ts', {
+    cwd: projectRoot,
+    ignore: [
+      ...config.ignore,
+      '**/supabase.ts', // The deprecated file itself
+      '**/*.test.ts',
+      '**/*.spec.ts'
+    ]
+  })
+
+  for (const file of files) {
+    try {
+      const content = readFileSync(`${projectRoot}/${file}`, 'utf-8')
+      const lines = content.split('\n')
+
+      // Check for direct supabaseAdmin imports/usage
+      const patterns = [
+        { pattern: /import.*supabaseAdmin.*from/g, name: 'supabaseAdmin import' },
+        { pattern: /supabaseAdmin\./g, name: 'supabaseAdmin usage' },
+        { pattern: /supabaseAdmin\s*\(/g, name: 'supabaseAdmin call' }
+      ]
+
+      for (const { pattern, name } of patterns) {
+        pattern.lastIndex = 0
+
+        let match
+        while ((match = pattern.exec(content)) !== null) {
+          // Find line number
+          let lineNumber = 1
+          let pos = 0
+          for (const line of lines) {
+            if (pos + line.length >= match.index) {
+              break
+            }
+            pos += line.length + 1
+            lineNumber++
+          }
+
+          results.passed = false
+          results.findings.push({
+            file,
+            line: lineNumber,
+            type: name,
+            severity: 'high',
+            message: `Deprecated ${name} - use systemDB('context') or userDB(req) instead`,
+            snippet: lines[lineNumber - 1]?.trim().substring(0, 100)
+          })
+          results.summary.high++
+          results.summary.total++
+        }
+      }
+    } catch (e) {
+      // Skip unreadable files
+    }
+  }
+
+  return results
+}

package/lib/checks/security/gitignore-validation.js

@@ -0,0 +1,211 @@
+/**
+ * .gitignore Validation
+ *
+ * Verifies that .gitignore contains critical entries to prevent
+ * accidental commits of secrets, dependencies, and build artifacts.
+ */
+
+import { readFileSync, existsSync } from 'fs'
+import { join } from 'path'
+
+export const meta = {
+  id: 'gitignore-validation',
+  name: 'Gitignore Validation',
+  category: 'security',
+  severity: 'high',
+  description: 'Checks .gitignore for critical entries that prevent secret/credential leaks'
+}
+
+// Required entries grouped by category
+const REQUIRED_ENTRIES = [
+  {
+    category: 'Environment files',
+    severity: 'critical',
+    patterns: ['.env', '.env.*', '.env.local'],
+    description: 'Environment files often contain API keys and secrets'
+  },
+  {
+    category: 'Dependencies',
+    severity: 'high',
+    patterns: ['node_modules', 'node_modules/'],
+    description: 'Dependencies should never be committed'
+  },
+  {
+    category: 'Build artifacts',
+    severity: 'medium',
+    patterns: ['dist', 'build', '.next'],
+    description: 'Build output should not be in version control'
+  }
+]
+
+const RECOMMENDED_ENTRIES = [
+  {
+    category: 'Credential files',
+    severity: 'high',
+    patterns: ['*.pem', '*.key', '*.p12', '*.pfx', 'credentials.json', 'service-account*.json'],
+    description: 'Certificate/key files can contain private keys'
+  },
+  {
+    category: 'Supabase temp files',
+    severity: 'medium',
+    patterns: ['.supabase', 'supabase/.temp'],
+    description: 'Supabase CLI temp files may contain tokens'
+  },
+  {
+    category: 'IDE & OS files',
+    severity: 'low',
+    patterns: ['.DS_Store', '.idea', '.vscode/settings.json'],
+    description: 'IDE settings may leak local paths or preferences'
+  },
+  {
+    category: 'Ralph working files',
+    severity: 'medium',
+    patterns: ['.ralph'],
+    description: 'Ralph session files may contain sensitive project data'
+  }
+]
+
+export async function run(config, projectRoot) {
+  const results = {
+    passed: true,
+    findings: [],
+    summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 },
+    details: {
+      gitignoreExists: false,
+      entryCount: 0,
+      missingRequired: [],
+      missingRecommended: []
+    }
+  }
+
+  const gitignorePath = join(projectRoot, '.gitignore')
+
+  // Check if .gitignore exists
+  if (!existsSync(gitignorePath)) {
+    results.passed = false
+    results.findings.push({
+      file: '.gitignore',
+      type: 'Missing .gitignore',
+      severity: 'critical',
+      message: 'No .gitignore file found — secrets and dependencies could be committed'
+    })
+    results.summary.critical++
+    results.summary.total++
+    return results
+  }
+
+  results.details.gitignoreExists = true
+
+  let content
+  try {
+    content = readFileSync(gitignorePath, 'utf-8')
+  } catch {
+    results.passed = false
+    results.findings.push({
+      file: '.gitignore',
+      type: 'Unreadable .gitignore',
+      severity: 'critical',
+      message: 'Could not read .gitignore file'
+    })
+    results.summary.critical++
+    results.summary.total++
+    return results
+  }
+
+  // Parse gitignore lines (strip comments and whitespace)
+  const lines = content
+    .split('\n')
+    .map(l => l.trim())
+    .filter(l => l && !l.startsWith('#'))
+
+  results.details.entryCount = lines.length
+
+  // Helper: check if a pattern is covered by any gitignore line
+  const isCovered = (pattern) => {
+    const normalizedPattern = pattern.replace(/\/$/, '')
+    return lines.some(line => {
+      const normalizedLine = line.replace(/\/$/, '')
+      // Exact match
+      if (normalizedLine === normalizedPattern) return true
+      // Wildcard match: .env.* covers .env.local, .env.production etc.
+      if (normalizedLine === '.env.*' && pattern.startsWith('.env.')) return true
+      if (normalizedLine === '.env*' && pattern.startsWith('.env')) return true
+      // Glob match: *.pem covers any .pem file
+      if (normalizedLine.startsWith('*') && pattern.endsWith(normalizedLine.slice(1))) return true
+      // Pattern with leading slash
+      if (normalizedLine === '/' + normalizedPattern) return true
+      // Directory glob
+      if (normalizedLine === normalizedPattern + '/') return true
+      if (normalizedLine === normalizedPattern + '/**') return true
+      // Path-prefixed match: /frontend/dist or /backend/dist covers "dist"
+      if (normalizedLine.endsWith('/' + normalizedPattern)) return true
+      return false
+    })
+  }
+
+  // Check required entries
+  for (const entry of REQUIRED_ENTRIES) {
+    const covered = entry.patterns.some(p => isCovered(p))
+    if (!covered) {
+      results.passed = false
+      results.details.missingRequired.push(entry.category)
+      results.findings.push({
+        file: '.gitignore',
+        type: `Missing: ${entry.category}`,
+        severity: entry.severity,
+        message: `${entry.category}: none of [${entry.patterns.join(', ')}] found in .gitignore — ${entry.description}`,
+        missingPatterns: entry.patterns
+      })
+      results.summary[entry.severity]++
+      results.summary.total++
+    }
+  }
+
+  // Check recommended entries
+  for (const entry of RECOMMENDED_ENTRIES) {
+    const covered = entry.patterns.some(p => isCovered(p))
+    if (!covered) {
+      results.details.missingRecommended.push(entry.category)
+      results.findings.push({
+        file: '.gitignore',
+        type: `Recommended: ${entry.category}`,
+        severity: entry.severity,
+        message: `${entry.category}: consider adding [${entry.patterns.join(', ')}] — ${entry.description}`,
+        missingPatterns: entry.patterns
+      })
+      results.summary[entry.severity]++
+      results.summary.total++
+    }
+  }
+
+  // Check for accidentally tracked .env files (git ls-files)
+  // This is informational — the gitignore may be fine but files were added before
+  try {
+    const { execSync } = await import('child_process')
+    const tracked = execSync('git ls-files -- .env .env.* .env.local 2>/dev/null || true', {
+      cwd: projectRoot,
+      encoding: 'utf-8'
+    }).trim()
+
+    if (tracked) {
+      // Exclude .env.example and .env.sample — these are meant to be committed
+      const trackedFiles = tracked.split('\n').filter(f => f.trim() && !f.includes('.example') && !f.includes('.sample'))
+      if (trackedFiles.length > 0) {
+        results.passed = false
+        results.findings.push({
+          file: '.gitignore',
+          type: 'Tracked env files',
+          severity: 'critical',
+          message: `${trackedFiles.length} .env file(s) are tracked by git despite .gitignore: ${trackedFiles.join(', ')} — run: git rm --cached ${trackedFiles.join(' ')}`,
+          trackedFiles
+        })
+        results.summary.critical++
+        results.summary.total++
+      }
+    }
+  } catch {
+    // Not a git repo or git not available — skip this check
+  }
+
+  return results
+}

package/lib/checks/security/hardcoded-secrets.js

@@ -0,0 +1,95 @@
+/**
+ * Check for hardcoded secrets in source code
+ */
+
+import { glob } from 'glob'
+import { readFileSync } from 'fs'
+
+export const meta = {
+  id: 'hardcoded-secrets',
+  name: 'Hardcoded Secrets Detection',
+  category: 'security',
+  severity: 'critical',
+  description: 'Detects API keys, tokens, and other secrets hardcoded in source files'
+}
+
+const DEFAULT_PATTERNS = [
+  { name: 'OpenAI API Key', pattern: /sk-[a-zA-Z0-9]{20,}/g },
+  { name: 'Stripe Live Key', pattern: /sk_live_[a-zA-Z0-9]{20,}/g },
+  { name: 'Stripe Test Key', pattern: /sk_test_[a-zA-Z0-9]{20,}/g },
+  { name: 'AWS Access Key', pattern: /AKIA[A-Z0-9]{16}/g },
+  { name: 'GitHub Token', pattern: /ghp_[a-zA-Z0-9]{36}/g },
+  { name: 'GitHub OAuth', pattern: /gho_[a-zA-Z0-9]{36}/g },
+  { name: 'Slack Token', pattern: /xox[baprs]-[a-zA-Z0-9-]{10,}/g },
+  { name: 'Supabase Service Key', pattern: /eyJ[a-zA-Z0-9_-]{100,}\.[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+/g },
+  { name: 'Generic API Key', pattern: /['"]api[_-]?key['"]\s*[:=]\s*['"][a-zA-Z0-9]{20,}['"]/gi },
+  { name: 'Generic Secret', pattern: /['"]secret['"]\s*[:=]\s*['"][a-zA-Z0-9]{20,}['"]/gi },
+  { name: 'Private Key Header', pattern: /-----BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----/g }
+]
+
+export async function run(config, projectRoot) {
+  const results = {
+    passed: true,
+    findings: [],
+    summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 }
+  }
+
+  // Get all source files
+  const files = await glob('**/*.{ts,tsx,js,jsx,json}', {
+    cwd: projectRoot,
+    ignore: config.ignore
+  })
+
+  for (const file of files) {
+    // Skip test files and examples
+    if (file.includes('.test.') || file.includes('.spec.') || file.includes('example')) {
+      continue
+    }
+
+    try {
+      const content = readFileSync(`${projectRoot}/${file}`, 'utf-8')
+      const lines = content.split('\n')
+
+      for (const { name, pattern } of DEFAULT_PATTERNS) {
+        // Reset regex state
+        pattern.lastIndex = 0
+
+        let match
+        while ((match = pattern.exec(content)) !== null) {
+          // Find line number
+          let lineNumber = 1
+          let pos = 0
+          for (const line of lines) {
+            if (pos + line.length >= match.index) {
+              break
+            }
+            pos += line.length + 1
+            lineNumber++
+          }
+
+          // Check if it's in a comment or placeholder
+          const line = lines[lineNumber - 1] || ''
+          if (line.includes('// ') || line.includes('example') || line.includes('placeholder')) {
+            continue
+          }
+
+          results.passed = false
+          results.findings.push({
+            file,
+            line: lineNumber,
+            type: name,
+            severity: 'critical',
+            message: `Potential ${name} found`,
+            snippet: match[0].substring(0, 20) + '...'
+          })
+          results.summary.critical++
+          results.summary.total++
+        }
+      }
+    } catch (e) {
+      // Skip unreadable files
+    }
+  }
+
+  return results
+}