@soulbatical/tetra-dev-toolkit 1.20.12 → 1.20.14

package/bin/tetra-setup.js

@@ -252,6 +252,108 @@ fi
     writeFileSync(packagePath, JSON.stringify(pkg, null, 2) + '\n')
     console.log('   ✅ Added "prepare": "husky" to package.json')
   }
+
+  // Install Claude Code global hooks (worktree-guard, doppler-guard)
+  await setupClaudeHooks(options)
+}
+
+
+async function setupClaudeHooks(options) {
+  console.log('')
+  console.log('🔒 Setting up Claude Code global hooks...')
+
+  const homeDir = process.env.HOME || process.env.USERPROFILE
+  if (!homeDir) {
+    console.log('   ⚠️  Cannot detect home directory — skipping Claude hooks')
+    return
+  }
+
+  const claudeHooksDir = join(homeDir, '.claude', 'hooks')
+  if (!existsSync(join(homeDir, '.claude'))) {
+    console.log('   ⏭️  No ~/.claude directory — Claude Code not installed, skipping')
+    return
+  }
+
+  if (!existsSync(claudeHooksDir)) {
+    mkdirSync(claudeHooksDir, { recursive: true })
+  }
+
+  // Find our template hooks
+  const templatesDir = join(import.meta.dirname || __dirname, '..', 'lib', 'templates', 'hooks')
+  if (!existsSync(templatesDir)) {
+    console.log('   ⚠️  Hook templates not found — skipping')
+    return
+  }
+
+  // Copy hook scripts
+  const hooks = ['worktree-guard.sh', 'doppler-guard.sh']
+  for (const hookFile of hooks) {
+    const src = join(templatesDir, hookFile)
+    const dest = join(claudeHooksDir, hookFile)
+    if (!existsSync(src)) continue
+
+    if (!existsSync(dest) || options.force) {
+      const content = readFileSync(src, 'utf-8')
+      writeFileSync(dest, content)
+      try { execSync(`chmod +x ${dest}`) } catch {}
+      console.log(`   ✅ Installed ~/.claude/hooks/${hookFile}`)
+    } else {
+      console.log(`   ⏭️  ~/.claude/hooks/${hookFile} already exists`)
+    }
+  }
+
+  // Register hooks in ~/.claude/settings.json
+  const settingsPath = join(homeDir, '.claude', 'settings.json')
+  let settings = {}
+  if (existsSync(settingsPath)) {
+    try { settings = JSON.parse(readFileSync(settingsPath, 'utf-8')) } catch {}
+  }
+
+  settings.hooks = settings.hooks || {}
+  settings.hooks.PreToolUse = settings.hooks.PreToolUse || []
+
+  // Check if worktree-guard is already registered
+  const hasWorktreeGuard = settings.hooks.PreToolUse.some(h =>
+    JSON.stringify(h).includes('worktree-guard')
+  )
+
+  if (!hasWorktreeGuard) {
+    // Insert at the beginning so it runs first
+    settings.hooks.PreToolUse.unshift({
+      matcher: 'Edit|Write|Bash',
+      hooks: [{
+        type: 'command',
+        command: '~/.claude/hooks/worktree-guard.sh',
+        timeout: 5
+      }]
+    })
+    console.log('   ✅ Registered worktree-guard in ~/.claude/settings.json')
+  } else {
+    console.log('   ⏭️  worktree-guard already registered')
+  }
+
+  // Check if doppler-guard is already registered
+  const hasDopplerGuard = settings.hooks.PreToolUse.some(h =>
+    JSON.stringify(h).includes('doppler-guard')
+  )
+
+  if (!hasDopplerGuard) {
+    settings.hooks.PreToolUse.push({
+      matcher: 'Edit|Write',
+      hooks: [{
+        type: 'command',
+        command: '~/.claude/hooks/doppler-guard.sh',
+        timeout: 5
+      }]
+    })
+    console.log('   ✅ Registered doppler-guard in ~/.claude/settings.json')
+  } else {
+    console.log('   ⏭️  doppler-guard already registered')
+  }
+
+  if (!hasWorktreeGuard || !hasDopplerGuard) {
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n')
+  }
 }
 
 async function setupCi(options) {
@@ -1057,3 +1159,4 @@ jobs:
 }
 
 program.parse()
+

package/lib/audits/test-coverage-audit.js

@@ -107,8 +107,16 @@ export async function scanRoutes(projectRoot) {
  * Scan frontend pages by finding all page.tsx files.
  */
 export async function scanFrontendPages(projectRoot) {
-  const pattern = 'frontend/src/app/**/page.tsx'
-  const files = await glob(pattern, { cwd: projectRoot })
+  const frontendPatterns = [
+    'frontend/src/app/**/page.tsx',
+    'frontend-user/src/app/**/page.tsx',
+    'frontend-sparkbuddy/src/app/**/page.tsx',
+  ]
+  const files = []
+  for (const pattern of frontendPatterns) {
+    const found = await glob(pattern, { cwd: projectRoot })
+    files.push(...found)
+  }
 
   const pages = []
   for (const file of files) {
@@ -137,8 +145,14 @@ export async function scanFrontendPages(projectRoot) {
 export async function scanTestFiles(projectRoot) {
   const patterns = [
     'tests/e2e/**/*.test.ts',
-    'frontend/e2e/**/*.spec.ts',
     'tests/**/*.test.ts',
+    'frontend/e2e/**/*.spec.ts',
+    'frontend-user/tests/**/*.spec.ts',
+    'frontend-user/tests/**/*.test.ts',
+    'frontend-sparkbuddy/tests/**/*.spec.ts',
+    'backend/tests/**/*.test.ts',
+    'frontend-user/tests/fixtures/**/*.ts',
+    'frontend/e2e/fixtures.ts',
   ]
 
   const allFiles = []
@@ -180,6 +194,13 @@ export async function scanTestFiles(projectRoot) {
       if (basePath) pageRefs.add(basePath)
     }
 
+    // Extract path definitions from fixture files (e.g. { path: '/nl/user' })
+    const pathDefRegex2 = /path:\s*['"]([^'"]+)['"]/g
+    let pathDefMatch2
+    while ((pathDefMatch2 = pathDefRegex2.exec(content)) !== null) {
+      pageRefs.add(pathDefMatch2[1])
+    }
+
     // Detect auth wall tests
     const hasAuthTests = /(?:toBe|toEqual|status)\s*\(\s*401\s*\)/.test(content) ||
                         /expect\(.*status.*\).*401/.test(content) ||

package/lib/checks/health/index.js

@@ -1,5 +1,5 @@
 /**
- * Health Checks — All 28 project health checks
+ * Health Checks — All 29 project health checks
  *
  * Main entry: scanProjectHealth(projectPath, projectName, options?)
  * Individual checks available via named imports.
@@ -41,3 +41,4 @@ export { check as checkSecurityLayers } from './security-layers.js'
 export { check as checkSmokeReadiness } from './smoke-readiness.js'
 export { check as checkReleasePipeline } from './release-pipeline.js'
 export { check as checkTestStructure } from './test-structure.js'
+export { check as checkSentryMonitoring } from './sentry-monitoring.js'

package/lib/checks/health/scanner.js

@@ -1,7 +1,7 @@
 /**
  * Project Health Scanner
  *
- * Orchestrates all 28 health checks and produces a HealthReport.
+ * Orchestrates all 29 health checks and produces a HealthReport.
  * This is the main entry point — consumers call scanProjectHealth().
  */
 
@@ -37,6 +37,7 @@ import { check as checkSecurityLayers } from './security-layers.js'
 import { check as checkSmokeReadiness } from './smoke-readiness.js'
 import { check as checkReleasePipeline } from './release-pipeline.js'
 import { check as checkTestStructure } from './test-structure.js'
+import { check as checkSentryMonitoring } from './sentry-monitoring.js'
 import { calculateHealthStatus } from './types.js'
 
 /**
@@ -82,7 +83,8 @@ export async function scanProjectHealth(projectPath, projectName, options = {})
     checkSecurityLayers(projectPath),
     checkSmokeReadiness(projectPath),
     checkReleasePipeline(projectPath),
-    checkTestStructure(projectPath)
+    checkTestStructure(projectPath),
+    checkSentryMonitoring(projectPath)
   ])
 
   const totalScore = checks.reduce((sum, c) => sum + c.score, 0)

package/lib/checks/health/sentry-monitoring.js

@@ -0,0 +1,189 @@
+/**
+ * Health Check: Sentry Error Monitoring
+ *
+ * Checks: @sentry/node in backend, @sentry/nextjs or @sentry/react in frontend,
+ * instrument.ts exists, SENTRY_DSN referenced via env var (not hardcoded).
+ * Score: 0-3 (backend setup, frontend setup, no hardcoded DSN)
+ */
+
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { createCheck } from './types.js'
+
+export async function check(projectPath) {
+  const result = createCheck('sentry-monitoring', 3, {
+    backend: { hasSentryDep: false, hasInstrumentFile: false, importedFirst: false },
+    frontend: { hasSentryDep: false, sentryPackage: null },
+    hardcodedDsn: false,
+    dsnFiles: []
+  })
+
+  // --- Check 1: Backend Sentry setup (0-1 point) ---
+  const backendPkgPath = join(projectPath, 'backend', 'package.json')
+  if (existsSync(backendPkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(backendPkgPath, 'utf-8'))
+      const allDeps = { ...pkg.dependencies, ...pkg.devDependencies }
+      if (allDeps['@sentry/node']) {
+        result.details.backend.hasSentryDep = true
+      }
+    } catch { /* ignore */ }
+
+    // Check instrument.ts or instrument.js
+    for (const ext of ['ts', 'js']) {
+      const instrumentPath = join(projectPath, 'backend', 'src', `instrument.${ext}`)
+      if (existsSync(instrumentPath)) {
+        result.details.backend.hasInstrumentFile = true
+
+        // Check if it's imported first in index.ts/index.js/server.ts
+        for (const entryName of ['index', 'server']) {
+        for (const indexExt of ['ts', 'js']) {
+          const indexPath = join(projectPath, 'backend', 'src', `${entryName}.${indexExt}`)
+          if (existsSync(indexPath)) {
+            try {
+              const content = readFileSync(indexPath, 'utf-8')
+              const lines = content.split('\n').filter(l => l.trim() && !l.trim().startsWith('//') && !l.trim().startsWith('*') && !l.trim().startsWith('/**'))
+              const firstImport = lines.find(l => l.includes('import '))
+              if (firstImport && firstImport.includes('instrument')) {
+                result.details.backend.importedFirst = true
+              }
+            } catch { /* ignore */ }
+          }
+        }
+        }
+        break
+      }
+    }
+
+    // Check for Tetra createApp pattern — Sentry is auto-configured via SENTRY_DSN env var
+    if (!result.details.backend.hasInstrumentFile) {
+      for (const entryFile of ['index', 'server', 'app']) {
+        for (const ext of ['ts', 'js']) {
+          const filePath = join(projectPath, 'backend', 'src', `${entryFile}.${ext}`)
+          if (existsSync(filePath)) {
+            try {
+              const content = readFileSync(filePath, 'utf-8')
+              if (content.includes('createApp')) {
+                result.details.backend.usesCreateApp = true
+                result.details.backend.hasInstrumentFile = true
+                result.details.backend.importedFirst = true
+              }
+            } catch { /* ignore */ }
+          }
+        }
+        if (result.details.backend.usesCreateApp) break
+      }
+    }
+
+    if (result.details.backend.hasSentryDep && result.details.backend.hasInstrumentFile) {
+      result.score += 1
+    } else if (result.details.backend.hasSentryDep) {
+      result.score += 0.5
+    }
+  } else {
+    // No backend = skip this point, adjust maxScore
+    result.maxScore -= 1
+  }
+
+  // --- Check 2: Frontend Sentry setup (0-1 point) ---
+  let hasAnyFrontend = false
+  const frontendDirs = ['frontend']
+  // Check for multi-frontend setups
+  try {
+    const { readdirSync } = await import('fs')
+    for (const entry of readdirSync(projectPath)) {
+      if (entry.startsWith('frontend-') && existsSync(join(projectPath, entry, 'package.json'))) {
+        frontendDirs.push(entry)
+      }
+    }
+  } catch { /* ignore */ }
+
+  for (const feDir of frontendDirs) {
+    const fePkgPath = join(projectPath, feDir, 'package.json')
+    if (!existsSync(fePkgPath)) continue
+    hasAnyFrontend = true
+
+    try {
+      const pkg = JSON.parse(readFileSync(fePkgPath, 'utf-8'))
+      const allDeps = { ...pkg.dependencies, ...pkg.devDependencies }
+      if (allDeps['@sentry/nextjs']) {
+        result.details.frontend.hasSentryDep = true
+        result.details.frontend.sentryPackage = '@sentry/nextjs'
+      } else if (allDeps['@sentry/react']) {
+        result.details.frontend.hasSentryDep = true
+        result.details.frontend.sentryPackage = '@sentry/react'
+      }
+    } catch { /* ignore */ }
+  }
+
+  if (!hasAnyFrontend) {
+    result.maxScore -= 1
+  } else if (result.details.frontend.hasSentryDep) {
+    result.score += 1
+  }
+
+  // --- Check 3: No hardcoded DSN (0-1 point) ---
+  // Scan for hardcoded Sentry DSN patterns in src files
+  const DSN_PATTERN = /https:\/\/[a-f0-9]{32}@[a-z0-9.]+\.sentry\.io\/\d+/
+  const filesToCheck = []
+
+  function collectFiles(dir, depth = 0) {
+    if (depth > 3) return
+    const SKIP = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage'])
+    try {
+      const { readdirSync, statSync } = require('fs')
+      for (const entry of readdirSync(dir)) {
+        if (SKIP.has(entry)) continue
+        const full = join(dir, entry)
+        try {
+          const stat = statSync(full)
+          if (stat.isDirectory()) collectFiles(full, depth + 1)
+          else if (/\.(ts|js|tsx|jsx)$/.test(entry) && !entry.endsWith('.d.ts')) {
+            filesToCheck.push(full)
+          }
+        } catch { /* ignore */ }
+      }
+    } catch { /* ignore */ }
+  }
+
+  for (const dir of ['backend/src', 'frontend/src']) {
+    const fullDir = join(projectPath, dir)
+    if (existsSync(fullDir)) collectFiles(fullDir)
+  }
+
+  for (const file of filesToCheck) {
+    try {
+      const content = readFileSync(file, 'utf-8')
+      if (DSN_PATTERN.test(content)) {
+        result.details.hardcodedDsn = true
+        const relPath = file.replace(projectPath + '/', '')
+        result.details.dsnFiles.push(relPath)
+      }
+    } catch { /* ignore */ }
+  }
+
+  if (!result.details.hardcodedDsn) {
+    result.score += 1
+  } else {
+    result.status = 'warning'
+  }
+
+  // Finalize
+  result.score = Math.min(result.score, result.maxScore)
+
+  if (result.maxScore > 0 && result.score === 0) {
+    result.status = 'warning'
+    result.details.message = 'No Sentry error monitoring configured'
+  } else if (result.score < result.maxScore) {
+    result.status = 'warning'
+    const issues = []
+    if (!result.details.backend.hasSentryDep) issues.push('no @sentry/node in backend')
+    if (result.details.backend.hasSentryDep && !result.details.backend.hasInstrumentFile) issues.push('missing instrument.ts')
+    if (hasAnyFrontend && !result.details.frontend.hasSentryDep) issues.push('no Sentry in frontend')
+    if (result.details.hardcodedDsn) issues.push(`hardcoded DSN in ${result.details.dsnFiles.join(', ')}`)
+    if (!result.details.backend.importedFirst && result.details.backend.hasInstrumentFile) issues.push('instrument.ts not imported first')
+    result.details.message = issues.join(', ')
+  }
+
+  return result
+}

package/lib/checks/health/types.js

@@ -5,7 +5,7 @@
  */
 
 /**
- * @typedef {'plugins'|'mcps'|'git'|'tests'|'secrets'|'quality-toolkit'|'naming-conventions'|'rls-audit'|'rpc-param-mismatch'|'typescript-strict'|'prettier'|'coverage-thresholds'|'eslint-security'|'dependency-cruiser'|'conventional-commits'|'knip'|'dependency-automation'|'license-audit'|'sast'|'bundle-size'|'gitignore'|'repo-visibility'|'vincifox-widget'|'stella-integration'|'claude-md'|'doppler-compliance'|'infrastructure-yml'|'file-organization'|'security-layers'|'smoke-readiness'|'release-pipeline'} HealthCheckType
+ * @typedef {'plugins'|'mcps'|'git'|'tests'|'secrets'|'quality-toolkit'|'naming-conventions'|'rls-audit'|'rpc-param-mismatch'|'typescript-strict'|'prettier'|'coverage-thresholds'|'eslint-security'|'dependency-cruiser'|'conventional-commits'|'knip'|'dependency-automation'|'license-audit'|'sast'|'bundle-size'|'gitignore'|'repo-visibility'|'vincifox-widget'|'stella-integration'|'claude-md'|'doppler-compliance'|'infrastructure-yml'|'file-organization'|'security-layers'|'smoke-readiness'|'release-pipeline'|'sentry-monitoring'} HealthCheckType
  *
  * @typedef {'ok'|'warning'|'error'} HealthStatus
  *

package/lib/templates/hooks/doppler-guard.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+# doppler-guard.sh — PreToolUse hook
+# Blocks creating/editing .env files with secrets.
+# Installed by: tetra-setup hooks
+
+INPUT=$(cat)
+
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+if [[ "$TOOL_NAME" != "Edit" && "$TOOL_NAME" != "Write" ]]; then
+  exit 0
+fi
+
+[[ -z "$FILE_PATH" ]] && exit 0
+
+BASENAME=$(basename "$FILE_PATH")
+
+[[ "$BASENAME" != *".env"* ]] && exit 0
+
+# Allowed: .env.example, .env.local, frontend/.env
+[[ "$BASENAME" == ".env.example" ]] && exit 0
+[[ "$BASENAME" == ".env.local" ]] && exit 0
+[[ "$FILE_PATH" == *"frontend/.env" && "$BASENAME" == ".env" ]] && exit 0
+
+echo '{
+  "decision": "block",
+  "reason": "DOPPLER GUARD: .env files with secrets are NOT allowed.\n\nUse Doppler for secret management — no .env files on disk.\n\n- Add secrets: doppler secrets set KEY=value\n- Start server: doppler run -- npm run dev\n\nAllowed exceptions:\n  .env.example  (template)\n  .env.local    (machine-specific ports)\n  frontend/.env (public VITE_*/NEXT_PUBLIC_* keys)"
+}'
+exit 2

package/lib/templates/hooks/worktree-guard.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+# ╔══════════════════════════════════════════════════════════════════╗
+# ║  WORKTREE GUARD — Block concurrent edits on shared repos        ║
+# ║  Installed by: tetra-setup hooks                                ║
+# ║                                                                ║
+# ║  PreToolUse hook for Write/Edit/Bash                           ║
+# ║  Blocks file mutations when multiple Claude sessions work on   ║
+# ║  the same repo WITHOUT worktree isolation.                     ║
+# ╚══════════════════════════════════════════════════════════════════╝
+
+INPUT=$(cat)
+
+TOOL=$(echo "$INPUT" | node -e "try{const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));console.log(d.tool_name||'')}catch{}" 2>/dev/null)
+FILE_PATH=$(echo "$INPUT" | node -e "try{const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));const i=d.tool_input||{};console.log(i.file_path||i.command||'')}catch{}" 2>/dev/null)
+
+case "$TOOL" in
+  Write|Edit|MultiEdit|NotebookEdit) ;;
+  Bash)
+    case "$FILE_PATH" in
+      *git\ checkout*|*git\ restore*|*git\ reset*|*git\ stash*|*rm\ *|*mv\ *) ;;
+      *) exit 0 ;;
+    esac
+    ;;
+  *) exit 0 ;;
+esac
+
+case "$FILE_PATH" in
+  *@fix_plan.md*|*fix_plan.md*) exit 0 ;;
+esac
+
+# Temporary bypass — touch /tmp/worktree-guard-bypass-<PID>
+for bf in /tmp/worktree-guard-bypass-*; do
+  [ -f "$bf" ] && pid="${bf##*-}" && kill -0 "$pid" 2>/dev/null && exit 0
+done
+
+CWD=$(echo "$INPUT" | node -e "try{const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));console.log(d.cwd||'')}catch{}" 2>/dev/null)
+[ -z "$CWD" ] && CWD=$(pwd)
+
+GIT_DIR=$(cd "$CWD" && git rev-parse --git-dir 2>/dev/null)
+GIT_COMMON=$(cd "$CWD" && git rev-parse --git-common-dir 2>/dev/null)
+if [ -n "$GIT_DIR" ] && [ -n "$GIT_COMMON" ] && [ "$GIT_DIR" != "$GIT_COMMON" ]; then
+  exit 0
+fi
+[ -f "$CWD/.git" ] && exit 0
+
+MY_PID=$$
+REPO_PATH=$(cd "$CWD" && git rev-parse --show-toplevel 2>/dev/null)
+[ -z "$REPO_PATH" ] && exit 0
+
+CONCURRENT=0
+while IFS= read -r pid; do
+  [ -z "$pid" ] && continue
+  [ "$pid" = "$MY_PID" ] && continue
+  OTHER_CWD=$(lsof -p "$pid" 2>/dev/null | grep cwd | awk '{print $NF}')
+  [ -z "$OTHER_CWD" ] && continue
+  OTHER_REPO=$(cd "$OTHER_CWD" 2>/dev/null && git rev-parse --show-toplevel 2>/dev/null)
+  if [ "$OTHER_REPO" = "$REPO_PATH" ]; then
+    OTHER_GIT_DIR=$(cd "$OTHER_CWD" 2>/dev/null && git rev-parse --git-dir 2>/dev/null)
+    OTHER_GIT_COMMON=$(cd "$OTHER_CWD" 2>/dev/null && git rev-parse --git-common-dir 2>/dev/null)
+    [ "$OTHER_GIT_DIR" = "$OTHER_GIT_COMMON" ] && CONCURRENT=$((CONCURRENT + 1))
+  fi
+done < <(pgrep -f "claude" 2>/dev/null)
+
+if [ "$CONCURRENT" -gt 0 ]; then
+  REPO_NAME=$(basename "$REPO_PATH")
+  cat <<EOF
+{
+  "decision": "block",
+  "reason": "WORKTREE GUARD: ${CONCURRENT} other Claude session(s) working on ${REPO_NAME} without worktree isolation. Use 'claude -w <name>' or Agent tool with isolation: 'worktree' to prevent file conflicts."
+}
+EOF
+  exit 2
+fi
+
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulbatical/tetra-dev-toolkit",
-  "version": "1.20.12",
+  "version": "1.20.14",
   "publishConfig": {
     "access": "restricted"
   },