@soulbatical/tetra-dev-toolkit 1.18.1 → 1.20.0

package/README.md

@@ -231,6 +231,82 @@ If any step fails, fix it before writing code. No exceptions.
 
 ---
 
+## Claude Code statusline
+
+A 3-line statusline for Claude Code that shows context usage, costs, project health, and session metadata.
+
+### Setup
+
+```bash
+# Symlink the script
+ln -sf /path/to/tetra/packages/dev-toolkit/hooks/statusline.sh ~/.claude/hooks/statusline.sh
+
+# Add to ~/.claude/settings.json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "~/.claude/hooks/statusline.sh"
+  }
+}
+```
+
+### What it shows
+
+```
+repo: vibecodingacademy  tasks: 3 open / 12 done  started by: user  cmux: workspace:308 ⠂ Claude Code
+opus  ██████░░░░░░░░░ 44%  context: 89K / 200K  99% cached  this turn: +7K
+$3.76  5m20s  (api: 3m5s)  lines: +47 -12  turn #5  main*  v2.1.73
+```
+
+**Line 1 — project dashboard**
+
+| Field | Source | Description |
+|-------|--------|-------------|
+| `repo:` | `workspace.project_dir` | Current project directory name |
+| `tasks:` | `.ralph/@fix_plan.md` | Open/done task count from Ralph fix plan |
+| `started by:` | Process tree + cmux | `user`, `monica`, `ralph`, `cursor`, `vscode` |
+| `cmux:` | `cmux identify` + `cmux list-workspaces` | Workspace ref and name (only in cmux terminal) |
+
+**Line 2 — context window**
+
+| Field | Source | Description |
+|-------|--------|-------------|
+| Model | `model.id` | Short name: `opus`, `sonnet`, `haiku` |
+| Progress bar | `context_window.used_percentage` | 15-char bar, green <50%, yellow 50-80%, red >80% |
+| `context:` | input + cache tokens | Effective tokens in window vs max |
+| `cached` | `cache_read / context` | % of context served from prompt cache (saves cost) |
+| `this turn:` | Delta from previous turn | Token growth this turn (helps spot expensive hooks) |
+
+**Line 3 — session stats**
+
+| Field | Source | Description |
+|-------|--------|-------------|
+| Cost | `cost.total_cost_usd` | Session cost so far |
+| Duration | `cost.total_duration_ms` | Wall clock time |
+| API time | `cost.total_api_duration_ms` | Time spent waiting for API responses |
+| Lines | `cost.total_lines_added/removed` | Code changes this session |
+| Turn | Delta tracker | Number of assistant responses |
+| Branch | `git branch` | Current branch, `*` if dirty |
+| Version | `version` | Claude Code version |
+
+### How "started by" detection works
+
+1. If running in cmux: checks workspace name — `monica:*` → `monica`
+2. Fallback: walks the process tree looking for `ralph`, `cursor`, `code` (VS Code)
+3. Default: `user` (manual terminal session)
+
+### Task colors
+
+| Color | Meaning |
+|-------|---------|
+| Green | 0 open tasks (all done) |
+| Yellow | 1-10 open tasks |
+| Red | 10+ open tasks |
+
+Projects without `.ralph/@fix_plan.md` don't show the tasks field.
+
+---
+
 ## Changelog
 
 ### 1.16.0

package/bin/tetra-check-peers.js

@@ -21,7 +21,28 @@ import { execSync } from 'child_process'
 
 // ─── Config ──────────────────────────────────────────────
 
-const PROJECTS_ROOT = join(process.env.HOME || '~', 'projecten')
+// Resolve paths dynamically:
+// 1. TETRA_PROJECTS_ROOT env var (explicit override)
+// 2. Detect from tetra repo: this script lives in tetra/packages/dev-toolkit/bin/
+//    so tetra root = 4 levels up, and projects root = 5 levels up (sibling dirs)
+// 3. Fallback: ~/projecten
+function resolveProjectsRoot() {
+  if (process.env.TETRA_PROJECTS_ROOT) return process.env.TETRA_PROJECTS_ROOT
+
+  // This file: <projects>/<tetra>/packages/dev-toolkit/bin/tetra-check-peers.js
+  const scriptDir = dirname(new URL(import.meta.url).pathname)
+  const tetraRoot = join(scriptDir, '..', '..', '..')  // → tetra/
+  const possibleProjectsRoot = join(tetraRoot, '..')     // → projects/
+
+  // Verify: does this directory contain a 'tetra' subdirectory?
+  if (existsSync(join(possibleProjectsRoot, 'tetra', 'packages'))) {
+    return possibleProjectsRoot
+  }
+
+  return join(process.env.HOME || '~', 'projecten')
+}
+
+const PROJECTS_ROOT = resolveProjectsRoot()
 const TETRA_ROOT = join(PROJECTS_ROOT, 'tetra', 'packages')
 
 // Tetra packages that have peerDependencies

package/bin/tetra-security-gate.js

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+
+/**
+ * Tetra Security Gate — AI-powered pre-push security review
+ *
+ * Detects security-sensitive file changes in the current git diff,
+ * submits them to ralph-manager's security gate agent for review,
+ * and blocks the push if the agent denies the changes.
+ *
+ * Usage:
+ *   tetra-security-gate                     # Auto-detect ralph-manager URL
+ *   tetra-security-gate --url <url>         # Explicit ralph-manager URL
+ *   tetra-security-gate --timeout 120       # Custom timeout (seconds)
+ *   tetra-security-gate --dry-run           # Show what would be sent, don't block
+ *
+ * Exit codes:
+ *   0 = approved (or no security files changed)
+ *   1 = denied (security violation found)
+ *   0 = ralph-manager offline (graceful fallback, doesn't block)
+ */
+
+import { program } from 'commander'
+import { execSync } from 'child_process'
+import chalk from 'chalk'
+
+// Security-sensitive file patterns
+const SECURITY_PATTERNS = [
+  /supabase\/migrations\/.*\.sql$/i,
+  /\.rls\./i,
+  /rls[-_]?policy/i,
+  /auth[-_]?config/i,
+  /middleware\/auth/i,
+  /middleware\/security/i,
+  /security\.ts$/i,
+  /security\.js$/i,
+  /\.env$/,
+  /\.env\.\w+$/,
+  /doppler\.yaml$/,
+  /auth-config/i,
+  /permissions/i,
+  /checks\/security\//i,
+]
+
+function isSecurityFile(file) {
+  return SECURITY_PATTERNS.some(p => p.test(file))
+}
+
+function getChangedFiles() {
+  try {
+    // Files changed between HEAD and upstream (what's being pushed)
+    const upstream = execSync('git rev-parse --abbrev-ref @{upstream} 2>/dev/null', { encoding: 'utf8' }).trim()
+    if (upstream) {
+      return execSync(`git diff --name-only ${upstream}...HEAD`, { encoding: 'utf8' }).trim().split('\n').filter(Boolean)
+    }
+  } catch {
+    // No upstream — compare against origin/main or origin/master
+  }
+
+  for (const base of ['origin/main', 'origin/master']) {
+    try {
+      return execSync(`git diff --name-only ${base}...HEAD`, { encoding: 'utf8' }).trim().split('\n').filter(Boolean)
+    } catch { /* try next */ }
+  }
+
+  // Fallback: last commit
+  try {
+    return execSync('git diff --name-only HEAD~1', { encoding: 'utf8' }).trim().split('\n').filter(Boolean)
+  } catch {
+    return []
+  }
+}
+
+function getDiff(files) {
+  try {
+    const upstream = execSync('git rev-parse --abbrev-ref @{upstream} 2>/dev/null', { encoding: 'utf8' }).trim()
+    if (upstream) {
+      return execSync(`git diff ${upstream}...HEAD -- ${files.join(' ')}`, { encoding: 'utf8', maxBuffer: 1024 * 1024 })
+    }
+  } catch { /* fallback */ }
+
+  for (const base of ['origin/main', 'origin/master']) {
+    try {
+      return execSync(`git diff ${base}...HEAD -- ${files.join(' ')}`, { encoding: 'utf8', maxBuffer: 1024 * 1024 })
+    } catch { /* try next */ }
+  }
+
+  try {
+    return execSync(`git diff HEAD~1 -- ${files.join(' ')}`, { encoding: 'utf8', maxBuffer: 1024 * 1024 })
+  } catch {
+    return ''
+  }
+}
+
+function getProjectName() {
+  try {
+    const remoteUrl = execSync('git remote get-url origin 2>/dev/null', { encoding: 'utf8' }).trim()
+    const match = remoteUrl.match(/\/([^/]+?)(?:\.git)?$/)
+    if (match) return match[1]
+  } catch { /* fallback */ }
+
+  try {
+    return execSync('basename "$(git rev-parse --show-toplevel)"', { encoding: 'utf8' }).trim()
+  } catch {
+    return 'unknown'
+  }
+}
+
+function getRalphManagerUrl() {
+  // Check .ralph/ports.json first
+  try {
+    const portsJson = execSync('cat .ralph/ports.json 2>/dev/null', { encoding: 'utf8' })
+    const ports = JSON.parse(portsJson)
+    if (ports.api_url) return ports.api_url
+  } catch { /* fallback */ }
+
+  // Check RALPH_MANAGER_API env
+  if (process.env.RALPH_MANAGER_API) return process.env.RALPH_MANAGER_API
+
+  // Default
+  return 'http://localhost:3005'
+}
+
+async function pollForVerdict(baseUrl, gateId, timeoutSeconds) {
+  const deadline = Date.now() + timeoutSeconds * 1000
+  const pollInterval = 3000 // 3 seconds
+
+  while (Date.now() < deadline) {
+    try {
+      const resp = await fetch(`${baseUrl}/api/internal/security-gate/${gateId}`)
+      if (!resp.ok) {
+        console.error(chalk.yellow(`  Poll failed: HTTP ${resp.status}`))
+        break
+      }
+
+      const { data } = await resp.json()
+
+      if (data.status === 'approved') {
+        return { status: 'approved', reason: data.reason, findings: data.findings }
+      }
+      if (data.status === 'denied') {
+        return { status: 'denied', reason: data.reason, findings: data.findings }
+      }
+      if (data.status === 'error') {
+        return { status: 'error', reason: data.reason }
+      }
+
+      // Still pending — wait and retry
+      await new Promise(r => setTimeout(r, pollInterval))
+    } catch {
+      // Network error — ralph-manager might be restarting
+      await new Promise(r => setTimeout(r, pollInterval))
+    }
+  }
+
+  return { status: 'timeout', reason: `No verdict within ${timeoutSeconds}s` }
+}
+
+program
+  .name('tetra-security-gate')
+  .description('AI-powered pre-push security gate — reviews RLS/auth/security changes')
+  .version('1.0.0')
+  .option('--url <url>', 'Ralph Manager URL (default: auto-detect)')
+  .option('--timeout <seconds>', 'Max wait time for agent verdict', '180')
+  .option('--dry-run', 'Show what would be submitted, do not block')
+  .action(async (options) => {
+    try {
+      console.log(chalk.blue.bold('\n  Tetra Security Gate\n'))
+
+      // Step 1: Detect changed files
+      const allFiles = getChangedFiles()
+      const securityFiles = allFiles.filter(isSecurityFile)
+
+      if (securityFiles.length === 0) {
+        console.log(chalk.green('  No security-sensitive files changed — skipping gate.'))
+        console.log(chalk.gray(`  (checked ${allFiles.length} files)\n`))
+        process.exit(0)
+      }
+
+      console.log(chalk.yellow(`  ${securityFiles.length} security-sensitive file(s) detected:`))
+      for (const f of securityFiles) {
+        console.log(chalk.gray(`    - ${f}`))
+      }
+      console.log()
+
+      // Step 2: Get the diff
+      const diff = getDiff(securityFiles)
+      if (!diff.trim()) {
+        console.log(chalk.green('  No actual diff content — skipping gate.\n'))
+        process.exit(0)
+      }
+
+      const project = getProjectName()
+
+      if (options.dryRun) {
+        console.log(chalk.cyan('  [DRY RUN] Would submit to security gate:'))
+        console.log(chalk.gray(`    Project: ${project}`))
+        console.log(chalk.gray(`    Files: ${securityFiles.length}`))
+        console.log(chalk.gray(`    Diff size: ${diff.length} chars`))
+        console.log()
+        process.exit(0)
+      }
+
+      // Step 3: Submit to ralph-manager
+      const baseUrl = options.url || getRalphManagerUrl()
+      const timeout = parseInt(options.timeout, 10)
+
+      console.log(chalk.gray(`  Submitting to ${baseUrl}...`))
+
+      let gateId
+      try {
+        const resp = await fetch(`${baseUrl}/api/internal/security-gate`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ project, files_changed: securityFiles, diff }),
+          signal: AbortSignal.timeout(10_000),
+        })
+
+        if (!resp.ok) {
+          const body = await resp.text()
+          console.error(chalk.yellow(`  Ralph Manager returned ${resp.status}: ${body}`))
+          console.log(chalk.yellow('  Falling back to PASS (ralph-manager error).\n'))
+          process.exit(0)
+        }
+
+        const { data } = await resp.json()
+        gateId = data.id
+
+        // If already resolved (e.g. fallback auto-approve)
+        if (data.status === 'approved') {
+          console.log(chalk.green(`  ${chalk.bold('APPROVED')} (immediate): ${data.reason || 'OK'}\n`))
+          process.exit(0)
+        }
+        if (data.status === 'denied') {
+          console.error(chalk.red.bold(`\n  PUSH BLOCKED — Security Gate DENIED\n`))
+          console.error(chalk.red(`  Reason: ${data.reason}\n`))
+          process.exit(1)
+        }
+      } catch (err) {
+        // Ralph-manager offline — don't block the push
+        console.log(chalk.yellow(`  Cannot reach ralph-manager at ${baseUrl}`))
+        console.log(chalk.yellow('  Falling back to PASS (offline fallback).\n'))
+        process.exit(0)
+      }
+
+      // Step 4: Poll for verdict
+      console.log(chalk.gray(`  Agent reviewing... (timeout: ${timeout}s)`))
+      const result = await pollForVerdict(baseUrl, gateId, timeout)
+
+      if (result.status === 'approved') {
+        console.log(chalk.green.bold(`\n  APPROVED: ${result.reason || 'No issues found'}`))
+        if (result.findings?.length) {
+          for (const f of result.findings) {
+            console.log(chalk.yellow(`    ⚠ ${f}`))
+          }
+        }
+        console.log()
+        process.exit(0)
+      }
+
+      if (result.status === 'denied') {
+        console.error(chalk.red.bold(`\n  ════════════════════════════════════════════════════════════`))
+        console.error(chalk.red.bold(`  PUSH BLOCKED — Security Gate DENIED`))
+        console.error(chalk.red.bold(`  ════════════════════════════════════════════════════════════`))
+        console.error(chalk.red(`\n  Reason: ${result.reason}`))
+        if (result.findings?.length) {
+          console.error(chalk.red(`\n  Findings:`))
+          for (const f of result.findings) {
+            console.error(chalk.red(`    - ${f}`))
+          }
+        }
+        console.error(chalk.yellow(`\n  Fix the issues and try again.\n`))
+        process.exit(1)
+      }
+
+      if (result.status === 'timeout') {
+        console.log(chalk.yellow(`  Agent did not respond within ${timeout}s.`))
+        console.log(chalk.yellow('  Falling back to PASS (timeout fallback).\n'))
+        process.exit(0)
+      }
+
+      // Unknown status — don't block
+      console.log(chalk.yellow(`  Unexpected verdict status: ${result.status}`))
+      console.log(chalk.yellow('  Falling back to PASS.\n'))
+      process.exit(0)
+
+    } catch (err) {
+      console.error(chalk.red(`\n  ERROR: ${err.message}\n`))
+      // Never block on internal errors
+      process.exit(0)
+    }
+  })
+
+program.parse()

package/bin/tetra-setup.js

@@ -43,7 +43,7 @@ program
     console.log('')
 
     const components = component === 'all' || !component
-      ? ['hooks', 'ci', 'config']
+      ? ['hooks', 'ci', 'config', 'smoke']
       : [component]
 
     for (const comp of components) {
@@ -81,9 +81,12 @@ program
         case 'license-audit':
           await setupLicenseAudit(options)
           break
+        case 'smoke':
+          await setupSmoke(options)
+          break
         default:
           console.log(`Unknown component: ${comp}`)
-          console.log('Available: hooks, ci, config, prettier, eslint-security, coverage, lighthouse, commitlint, depcruiser, knip, license-audit')
+          console.log('Available: hooks, ci, config, smoke, prettier, eslint-security, coverage, lighthouse, commitlint, depcruiser, knip, license-audit')
       }
     }
 
@@ -867,4 +870,171 @@ async function setupLicenseAudit(options) {
   console.log('   📦 Run: npm install --save-dev license-checker')
 }
 
+// ─── Smoke Tests ─────────────────────────────────────────────
+
+async function setupSmoke(options) {
+  console.log('🔥 Setting up smoke tests...')
+
+  // Step 1: Detect project name from git remote or package.json
+  let projectName = null
+  try {
+    const remoteUrl = execSync('git remote get-url origin 2>/dev/null', { encoding: 'utf8' }).trim()
+    const match = remoteUrl.match(/\/([^/]+?)(?:\.git)?$/)
+    if (match) projectName = match[1]
+  } catch { /* no git remote */ }
+
+  if (!projectName) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(projectRoot, 'package.json'), 'utf-8'))
+      projectName = pkg.name?.replace(/^@[^/]+\//, '') || null
+    } catch { /* no package.json */ }
+  }
+
+  if (!projectName) {
+    const { basename } = await import('path')
+    projectName = basename(projectRoot)
+  }
+
+  console.log(`   Project: ${projectName}`)
+
+  // Step 2: Get deploy config from ralph-manager
+  let backendUrl = null
+  let frontendUrl = null
+
+  const ralphUrl = process.env.RALPH_MANAGER_API || 'http://localhost:3005'
+  try {
+    const resp = await fetch(`${ralphUrl}/api/internal/projects?name=${encodeURIComponent(projectName)}`, {
+      signal: AbortSignal.timeout(5000),
+    })
+    if (resp.ok) {
+      const { data } = await resp.json()
+      if (data?.deploy_config) {
+        const dc = data.deploy_config
+        backendUrl = dc.backend?.url || (dc.domains?.api_domain ? `https://${dc.domains.api_domain}` : null)
+        frontendUrl = dc.frontend?.url || (dc.domains?.frontend_domain ? `https://${dc.domains.frontend_domain}` : null)
+      }
+    }
+  } catch {
+    console.log('   ⚠️  Could not reach ralph-manager — using manual detection')
+  }
+
+  // Fallback: detect from railway.json
+  if (!backendUrl) {
+    const railwayPath = join(projectRoot, 'railway.json')
+    if (existsSync(railwayPath)) {
+      // Railway auto-deploy URL convention: {service-name}-production.up.railway.app
+      backendUrl = `https://${projectName}-production.up.railway.app`
+      console.log(`   ℹ️  Guessed Railway URL: ${backendUrl}`)
+    }
+  }
+
+  if (!backendUrl) {
+    console.log('   ❌ Could not detect production URL.')
+    console.log('   Add deploy_config in ralph-manager or pass --url manually.')
+    console.log('   You can also add "smoke.baseUrl" to .tetra-quality.json manually.')
+    return
+  }
+
+  console.log(`   Backend: ${backendUrl}`)
+  if (frontendUrl) console.log(`   Frontend: ${frontendUrl}`)
+
+  // Step 3: Add smoke config to .tetra-quality.json
+  const configPath = join(projectRoot, '.tetra-quality.json')
+  let config = {}
+
+  if (existsSync(configPath)) {
+    try {
+      config = JSON.parse(readFileSync(configPath, 'utf-8'))
+    } catch { /* invalid JSON, start fresh */ }
+  }
+
+  if (!config.smoke || options.force) {
+    config.smoke = {
+      baseUrl: backendUrl,
+      ...(frontendUrl ? { frontendUrl } : {}),
+      timeout: 10000,
+      checks: {
+        health: true,
+        healthDeep: true,
+        authEndpoints: [
+          { path: '/api/admin/users', expect: { status: 401 }, description: 'Auth wall: admin' },
+        ],
+        ...(frontendUrl ? {
+          frontendPages: [
+            { path: '/', expect: { status: 200 }, description: 'Homepage' },
+          ]
+        } : {}),
+      },
+      notify: {
+        telegram: true,
+        onSuccess: false,
+        onFailure: true,
+      },
+    }
+
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n')
+    console.log('   ✅ Added smoke config to .tetra-quality.json')
+  } else {
+    console.log('   ⏭️  Smoke config already exists (use --force to overwrite)')
+  }
+
+  // Step 4: Create post-deploy GitHub Actions workflow
+  const workflowDir = join(projectRoot, '.github/workflows')
+  if (!existsSync(workflowDir)) {
+    mkdirSync(workflowDir, { recursive: true })
+  }
+
+  const smokeWorkflowPath = join(workflowDir, 'post-deploy-tests.yml')
+  if (!existsSync(smokeWorkflowPath) || options.force) {
+    let workflowContent = `name: Post-Deploy Smoke Tests
+
+on:
+  # Triggered after deploy via webhook
+  repository_dispatch:
+    types: [deploy-completed]
+
+  # Manual trigger
+  workflow_dispatch:
+
+  # Scheduled: every 6 hours
+  schedule:
+    - cron: '0 */6 * * *'
+
+jobs:
+  smoke:
+    uses: mralbertzwolle/tetra/.github/workflows/smoke-tests.yml@main
+    with:
+      backend-url: ${backendUrl}
+`
+    if (frontendUrl) {
+      workflowContent += `      frontend-url: ${frontendUrl}\n`
+    }
+    workflowContent += `      wait-seconds: 30
+      post-deploy: true
+`
+
+    writeFileSync(smokeWorkflowPath, workflowContent)
+    console.log('   ✅ Created .github/workflows/post-deploy-tests.yml')
+  } else {
+    console.log('   ⏭️  Post-deploy workflow already exists (use --force to overwrite)')
+  }
+
+  // Step 5: Verify smoke tests work
+  console.log('')
+  console.log('   🧪 Quick verification...')
+  try {
+    const resp = await fetch(`${backendUrl}/api/health`, { signal: AbortSignal.timeout(10000) })
+    if (resp.ok) {
+      console.log(`   ✅ ${backendUrl}/api/health → ${resp.status} OK`)
+    } else {
+      console.log(`   ⚠️  ${backendUrl}/api/health → ${resp.status}`)
+    }
+  } catch (err) {
+    console.log(`   ❌ ${backendUrl}/api/health → ${err.message}`)
+  }
+
+  console.log('')
+  console.log('   Next: run `tetra-smoke` to test all endpoints')
+}
+
 program.parse()