@soulbatical/tetra-dev-toolkit 1.19.0 → 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-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()

package/bin/tetra-smoke.js

@@ -0,0 +1,532 @@
+#!/usr/bin/env node
+
+/**
+ * Tetra Smoke — Config-driven + auto-discover post-deploy smoke tester
+ *
+ * Runs HTTP-based smoke tests against live endpoints.
+ * Two modes:
+ *   1. Config-driven: tests from .tetra-quality.json smoke section
+ *   2. Auto-discover: fetches /api/health/routes and tests ALL endpoints
+ *
+ * Usage:
+ *   tetra-smoke                          # Config + auto-discover
+ *   tetra-smoke --url <backend-url>      # Override backend URL
+ *   tetra-smoke --discover-only          # Only auto-discover (skip config checks)
+ *   tetra-smoke --no-discover            # Only config checks (skip auto-discover)
+ *   tetra-smoke --json                   # JSON output for CI
+ *   tetra-smoke --ci                     # GitHub Actions annotations
+ *   tetra-smoke --notify                 # Telegram notification on failure
+ *   tetra-smoke --post-deploy            # Wait + retry mode for post-deploy
+ *
+ * Exit codes:
+ *   0 = all checks passed
+ *   1 = one or more checks failed
+ */
+
+import { program } from 'commander'
+import chalk from 'chalk'
+import { readFileSync, existsSync } from 'fs'
+import { join } from 'path'
+
+function mergeHeaders(globalHeaders, endpointHeaders) {
+  return { ...(globalHeaders || {}), ...(endpointHeaders || {}) }
+}
+
+function loadSmokeConfig(projectRoot) {
+  const configFile = join(projectRoot, '.tetra-quality.json')
+  if (!existsSync(configFile)) return null
+
+  try {
+    const config = JSON.parse(readFileSync(configFile, 'utf-8'))
+    return config.smoke || null
+  } catch {
+    return null
+  }
+}
+
+async function httpCheck(url, options = {}) {
+  const timeout = options.timeout || 10000
+  const start = Date.now()
+
+  try {
+    const fetchOptions = {
+      method: options.method || 'GET',
+      signal: AbortSignal.timeout(timeout),
+      headers: options.headers || {},
+      redirect: 'follow',
+    }
+
+    const resp = await fetch(url, fetchOptions)
+
+    const duration = Date.now() - start
+    const body = await resp.text().catch(() => '')
+
+    return {
+      url,
+      status: resp.status,
+      duration,
+      bodyLength: body.length,
+      passed: options.expectStatus ? resp.status === options.expectStatus : resp.ok,
+      body: body.substring(0, 500),
+    }
+  } catch (err) {
+    return {
+      url,
+      status: 0,
+      duration: Date.now() - start,
+      bodyLength: 0,
+      passed: false,
+      error: err.message,
+    }
+  }
+}
+
+// ============================================================================
+// AUTO-DISCOVER: Fetch /api/health/routes and test all endpoints
+// ============================================================================
+
+async function discoverAndTestRoutes(baseUrl, options = {}) {
+  const timeout = options.timeout || 10000
+  const results = []
+
+  // Fetch route manifest
+  let routes
+  try {
+    const resp = await fetch(`${baseUrl}/api/health/routes`, {
+      signal: AbortSignal.timeout(timeout),
+    })
+    if (!resp.ok) {
+      return {
+        passed: true,
+        results: [{
+          name: 'Route Discovery',
+          url: `${baseUrl}/api/health/routes`,
+          status: resp.status,
+          duration: 0,
+          passed: true, // Don't fail if endpoint doesn't exist yet
+          skipped: true,
+          error: `Route discovery not available (HTTP ${resp.status}) — deploy tetra-core update first`,
+        }],
+        discoveredCount: 0,
+      }
+    }
+
+    const data = await resp.json()
+    routes = data.routes || []
+  } catch (err) {
+    return {
+      passed: true,
+      results: [{
+        name: 'Route Discovery',
+        url: `${baseUrl}/api/health/routes`,
+        status: 0,
+        duration: 0,
+        passed: true,
+        skipped: true,
+        error: `Route discovery failed: ${err.message}`,
+      }],
+      discoveredCount: 0,
+    }
+  }
+
+  // Filter: only test GET routes (POST/PUT/DELETE would mutate data)
+  const getRoutes = routes.filter(r => r.method === 'GET')
+
+  // Skip routes with :params (we don't have valid IDs to test with)
+  // But we CAN test list endpoints, counts, filters, etc.
+  const testableRoutes = getRoutes.filter(r => !r.path.includes(':'))
+
+  // Skip certain paths that need special handling
+  const skipPaths = [
+    '/api/health',           // Already tested
+    '/api/health/routes',    // This endpoint itself
+  ]
+
+  const routesToTest = testableRoutes.filter(r => !skipPaths.includes(r.path))
+
+  // Expected status per auth level (without providing auth token)
+  const expectedStatus = {
+    public: null,    // Could be 200, 400 (missing params), or 422 — just not 500
+    admin: 401,      // Must require auth
+    user: 401,       // Must require auth
+    superadmin: 401, // Must require auth
+  }
+
+  // Test routes in parallel batches of 10
+  const BATCH_SIZE = 10
+  for (let i = 0; i < routesToTest.length; i += BATCH_SIZE) {
+    const batch = routesToTest.slice(i, i + BATCH_SIZE)
+
+    const batchResults = await Promise.all(
+      batch.map(async (route) => {
+        const expected = expectedStatus[route.auth]
+        const r = await httpCheck(`${baseUrl}${route.path}`, {
+          timeout,
+          expectStatus: expected || undefined,
+        })
+
+        // For public routes: accept anything except 500 (server error)
+        if (route.auth === 'public') {
+          r.passed = r.status > 0 && r.status < 500
+        }
+
+        return {
+          name: `${route.auth.toUpperCase()} ${route.path}`,
+          auth: route.auth,
+          ...r,
+        }
+      })
+    )
+
+    results.push(...batchResults)
+  }
+
+  const allPassed = results.every(r => r.passed)
+  return {
+    passed: allPassed,
+    results,
+    discoveredCount: routesToTest.length,
+    totalRoutes: routes.length,
+    skippedParamRoutes: getRoutes.length - testableRoutes.length,
+    skippedNonGet: routes.length - getRoutes.length,
+  }
+}
+
+// ============================================================================
+// CONFIG-DRIVEN SMOKE TESTS
+// ============================================================================
+
+async function runConfigTests(config, options) {
+  const baseUrl = options.url || config.baseUrl
+  const frontendUrl = config.frontendUrl
+  const timeout = config.timeout || 10000
+  const results = []
+
+  if (!baseUrl) {
+    return { passed: false, results: [], error: 'No baseUrl configured' }
+  }
+
+  const checks = config.checks || {}
+
+  // 1. Health check
+  if (checks.health !== false) {
+    const r = await httpCheck(`${baseUrl}/api/health`, { timeout })
+    results.push({ name: 'Health', ...r })
+  }
+
+  // 2. Deep health check
+  if (checks.healthDeep) {
+    const r = await httpCheck(`${baseUrl}/api/health?deep=true`, { timeout })
+    if (r.passed) {
+      try {
+        const data = JSON.parse(r.body)
+        if (data.status === 'degraded') {
+          r.passed = false
+          r.error = `Degraded: ${JSON.stringify(data.checks)}`
+        }
+      } catch { /* non-JSON is fine for basic health */ }
+    }
+    results.push({ name: 'Deep Health', ...r })
+  }
+
+  // 3. Public endpoints
+  if (checks.publicEndpoints) {
+    for (const ep of checks.publicEndpoints) {
+      const expectedStatus = ep.expect?.status || 200
+      const r = await httpCheck(`${baseUrl}${ep.path}`, {
+        timeout,
+        expectStatus: expectedStatus,
+        headers: mergeHeaders(config.headers, ep.headers),
+      })
+      results.push({
+        name: ep.description || `Public: ${ep.path}`,
+        ...r,
+      })
+    }
+  }
+
+  // 4. Auth endpoints (should return 401 without token)
+  if (checks.authEndpoints) {
+    for (const ep of checks.authEndpoints) {
+      const expectedStatus = ep.expect?.status || 401
+      const r = await httpCheck(`${baseUrl}${ep.path}`, {
+        timeout,
+        expectStatus: expectedStatus,
+        headers: mergeHeaders(config.headers, ep.headers),
+      })
+      results.push({
+        name: ep.description || `Auth wall: ${ep.path}`,
+        ...r,
+      })
+    }
+  }
+
+  // 5. Frontend pages
+  if (checks.frontendPages && frontendUrl) {
+    for (const ep of checks.frontendPages) {
+      const expectedStatus = ep.expect?.status || 200
+      const r = await httpCheck(`${frontendUrl}${ep.path}`, {
+        timeout,
+        expectStatus: expectedStatus,
+      })
+      if (r.passed && r.bodyLength < 100) {
+        r.passed = false
+        r.error = `Body too small (${r.bodyLength} bytes) — possibly empty page`
+      }
+      results.push({
+        name: ep.description || `Frontend: ${ep.path}`,
+        ...r,
+      })
+    }
+  }
+
+  const allPassed = results.every(r => r.passed)
+  return { passed: allPassed, results }
+}
+
+// ============================================================================
+// OUTPUT
+// ============================================================================
+
+function printResults(configResults, discoverResults, options) {
+  if (options.json) {
+    console.log(JSON.stringify({ config: configResults, discover: discoverResults }, null, 2))
+    return
+  }
+
+  // Config results
+  if (configResults && configResults.results.length > 0) {
+    console.log(chalk.blue.bold('\n  Config Smoke Tests\n'))
+    printCheckResults(configResults.results, options)
+  }
+
+  // Discover results
+  if (discoverResults && discoverResults.results.length > 0) {
+    const stats = []
+    if (discoverResults.totalRoutes) stats.push(`${discoverResults.totalRoutes} total routes`)
+    if (discoverResults.discoveredCount) stats.push(`${discoverResults.discoveredCount} testable`)
+    if (discoverResults.skippedParamRoutes) stats.push(`${discoverResults.skippedParamRoutes} skipped (need :id)`)
+    if (discoverResults.skippedNonGet) stats.push(`${discoverResults.skippedNonGet} skipped (POST/PUT/DELETE)`)
+
+    console.log(chalk.blue.bold('\n  Auto-Discovered Route Tests'))
+    if (stats.length > 0) {
+      console.log(chalk.gray(`  ${stats.join(' | ')}`))
+    }
+    console.log()
+
+    // Group by auth level
+    const byAuth = {}
+    for (const r of discoverResults.results) {
+      const auth = r.auth || 'other'
+      if (!byAuth[auth]) byAuth[auth] = []
+      byAuth[auth].push(r)
+    }
+
+    for (const [auth, results] of Object.entries(byAuth)) {
+      const passed = results.filter(r => r.passed).length
+      const failed = results.filter(r => !r.passed).length
+      const authLabel = auth.toUpperCase()
+
+      if (failed === 0) {
+        console.log(chalk.green(`  ✓ ${authLabel}: ${passed}/${results.length} passed`))
+      } else {
+        console.log(chalk.red(`  ✗ ${authLabel}: ${failed}/${results.length} failed`))
+        // Show only failed ones
+        for (const r of results.filter(r => !r.passed)) {
+          console.log(chalk.red(`    ✗ ${r.name} [${r.status}] ${r.error || ''}`))
+          if (options.ci) {
+            console.log(`::error title=Smoke Test Failed::${r.name}: ${r.error || `HTTP ${r.status}`}`)
+          }
+        }
+      }
+    }
+  }
+
+  // Summary
+  const allResults = [
+    ...(configResults?.results || []),
+    ...(discoverResults?.results || []),
+  ]
+  const totalPassed = allResults.filter(r => r.passed).length
+  const totalFailed = allResults.filter(r => !r.passed).length
+  const total = allResults.length
+
+  console.log()
+  if (totalFailed === 0) {
+    console.log(chalk.green.bold(`  All ${total} checks passed\n`))
+  } else {
+    console.log(chalk.red.bold(`  ${totalFailed}/${total} checks failed\n`))
+  }
+}
+
+function printCheckResults(results, options) {
+  for (const r of results) {
+    const icon = r.passed ? chalk.green('✓') : chalk.red('✗')
+    const duration = chalk.gray(`${r.duration}ms`)
+    const status = r.status ? chalk.gray(`[${r.status}]`) : ''
+
+    console.log(`  ${icon} ${r.name} ${status} ${duration}`)
+
+    if (!r.passed && r.error) {
+      console.log(chalk.red(`    ${r.error}`))
+    }
+
+    if (r.skipped) {
+      console.log(chalk.yellow(`    ${r.error}`))
+    }
+
+    if (options.ci && !r.passed && !r.skipped) {
+      console.log(`::error title=Smoke Test Failed::${r.name}: ${r.error || `HTTP ${r.status}`}`)
+    }
+
+    if (r.passed && r.duration > 3000) {
+      console.log(chalk.yellow(`    ⚠ Slow response (${r.duration}ms)`))
+    }
+  }
+}
+
+async function sendTelegramNotification(allResults, config) {
+  const ralphUrl = process.env.RALPH_MANAGER_API || 'http://localhost:3005'
+
+  const failedChecks = allResults.filter(r => !r.passed)
+  const lines = [
+    `🔥 *Smoke Test FAILED*`,
+    '',
+    `Project: ${config.baseUrl}`,
+    `Failed: ${failedChecks.length}/${allResults.length}`,
+    '',
+    ...failedChecks.slice(0, 10).map(r => `❌ ${r.name}: ${r.error || `HTTP ${r.status}`}`),
+    ...(failedChecks.length > 10 ? [`... and ${failedChecks.length - 10} more`] : []),
+  ]
+
+  try {
+    await fetch(`${ralphUrl}/api/internal/telegram/send`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ message: lines.join('\n') }),
+      signal: AbortSignal.timeout(5000),
+    })
+  } catch {
+    console.log(chalk.yellow('  Could not send Telegram notification'))
+  }
+}
+
+// ============================================================================
+// MAIN
+// ============================================================================
+
+program
+  .name('tetra-smoke')
+  .description('Config-driven + auto-discover post-deploy smoke tester')
+  .version('1.0.0')
+  .option('--url <url>', 'Override backend URL')
+  .option('--frontend-url <url>', 'Override frontend URL')
+  .option('--discover-only', 'Only run auto-discovered route tests')
+  .option('--no-discover', 'Skip auto-discover, only run config tests')
+  .option('--json', 'JSON output')
+  .option('--ci', 'GitHub Actions annotations')
+  .option('--notify', 'Send Telegram notification on failure')
+  .option('--post-deploy', 'Wait + retry mode (waits 30s, retries 3x)')
+  .option('--timeout <ms>', 'Request timeout in ms', '10000')
+  .action(async (options) => {
+    try {
+      const projectRoot = process.cwd()
+      const smokeConfig = loadSmokeConfig(projectRoot)
+
+      if (!smokeConfig && !options.url) {
+        console.error(chalk.red('\n  No smoke config found in .tetra-quality.json and no --url provided.\n'))
+        console.log(chalk.gray('  Add a "smoke" section to .tetra-quality.json:'))
+        console.log(chalk.gray('  {'))
+        console.log(chalk.gray('    "smoke": {'))
+        console.log(chalk.gray('      "baseUrl": "https://your-app.railway.app",'))
+        console.log(chalk.gray('      "checks": { "health": true, "healthDeep": true }'))
+        console.log(chalk.gray('    }'))
+        console.log(chalk.gray('  }\n'))
+        process.exit(1)
+      }
+
+      const config = {
+        baseUrl: options.url || smokeConfig?.baseUrl,
+        frontendUrl: options.frontendUrl || smokeConfig?.frontendUrl,
+        timeout: parseInt(options.timeout, 10) || smokeConfig?.timeout || 10000,
+        checks: smokeConfig?.checks || { health: true },
+        headers: smokeConfig?.headers || {},
+        notify: smokeConfig?.notify || {},
+      }
+
+      const runTests = async () => {
+        let configResults = null
+        let discoverResults = null
+
+        // Run config tests (unless --discover-only)
+        if (!options.discoverOnly) {
+          configResults = await runConfigTests(config, options)
+        }
+
+        // Run auto-discover tests (unless --no-discover or explicitly disabled)
+        if (options.discover !== false) {
+          discoverResults = await discoverAndTestRoutes(config.baseUrl, {
+            timeout: config.timeout,
+          })
+        }
+
+        return { configResults, discoverResults }
+      }
+
+      // Post-deploy mode: wait then retry
+      if (options.postDeploy) {
+        console.log(chalk.gray('  Post-deploy mode: waiting 30s for deploy to stabilize...\n'))
+        await new Promise(r => setTimeout(r, 30000))
+
+        let lastResult = null
+        for (let attempt = 1; attempt <= 3; attempt++) {
+          console.log(chalk.gray(`  Attempt ${attempt}/3...`))
+          lastResult = await runTests()
+
+          const allPassed = (lastResult.configResults?.passed !== false) &&
+                           (lastResult.discoverResults?.passed !== false)
+          if (allPassed) break
+
+          if (attempt < 3) {
+            console.log(chalk.yellow(`  Attempt ${attempt} failed, retrying in 15s...`))
+            await new Promise(r => setTimeout(r, 15000))
+          }
+        }
+
+        printResults(lastResult.configResults, lastResult.discoverResults, options)
+
+        const allResults = [
+          ...(lastResult.configResults?.results || []),
+          ...(lastResult.discoverResults?.results || []),
+        ]
+        const allPassed = allResults.every(r => r.passed || r.skipped)
+
+        if (!allPassed && (options.notify || config.notify?.onFailure)) {
+          await sendTelegramNotification(allResults, config)
+        }
+
+        process.exit(allPassed ? 0 : 1)
+      }
+
+      // Normal mode
+      const { configResults, discoverResults } = await runTests()
+      printResults(configResults, discoverResults, options)
+
+      const allResults = [
+        ...(configResults?.results || []),
+        ...(discoverResults?.results || []),
+      ]
+      const allPassed = allResults.every(r => r.passed || r.skipped)
+
+      if (!allPassed && (options.notify || config.notify?.onFailure)) {
+        await sendTelegramNotification(allResults, config)
+      }
+
+      process.exit(allPassed ? 0 : 1)
+    } catch (err) {
+      console.error(chalk.red(`\n  ERROR: ${err.message}\n`))
+      process.exit(1)
+    }
+  })
+
+program.parse()

package/lib/checks/health/index.js

@@ -38,3 +38,4 @@ export { check as checkLicenseAudit } from './license-audit.js'
 export { check as checkSast } from './sast.js'
 export { check as checkBundleSize } from './bundle-size.js'
 export { check as checkSecurityLayers } from './security-layers.js'
+export { check as checkSmokeReadiness } from './smoke-readiness.js'

package/lib/checks/health/scanner.js

@@ -34,6 +34,7 @@ import { check as checkLicenseAudit } from './license-audit.js'
 import { check as checkSast } from './sast.js'
 import { check as checkBundleSize } from './bundle-size.js'
 import { check as checkSecurityLayers } from './security-layers.js'
+import { check as checkSmokeReadiness } from './smoke-readiness.js'
 import { calculateHealthStatus } from './types.js'
 
 /**
@@ -76,7 +77,8 @@ export async function scanProjectHealth(projectPath, projectName, options = {})
     checkLicenseAudit(projectPath),
     checkSast(projectPath),
     checkBundleSize(projectPath),
-    checkSecurityLayers(projectPath)
+    checkSecurityLayers(projectPath),
+    checkSmokeReadiness(projectPath)
   ])
 
   const totalScore = checks.reduce((sum, c) => sum + c.score, 0)

package/lib/checks/health/smoke-readiness.js

@@ -0,0 +1,150 @@
+/**
+ * Health Check: Smoke Test Readiness
+ *
+ * Checks if a project has proper smoke test and E2E infrastructure:
+ * - Smoke config in .tetra-quality.json
+ * - Health endpoint configured
+ * - E2E test files exist and are runnable
+ * - Post-deploy workflow exists
+ *
+ * Score: up to 5 points
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'fs'
+import { join } from 'path'
+import { createCheck } from './types.js'
+
+export async function check(projectPath) {
+  const result = createCheck('smoke-readiness', 5, {
+    hasSmokeConfig: false,
+    hasHealthEndpoint: false,
+    hasE2ETests: false,
+    hasPostDeployWorkflow: false,
+    hasSmokeEndpoints: false,
+    smokeEndpointCount: 0,
+    e2eTestCount: 0,
+  })
+
+  // 1. Check for smoke config in .tetra-quality.json (+1 point)
+  const configFile = join(projectPath, '.tetra-quality.json')
+  if (existsSync(configFile)) {
+    try {
+      const config = JSON.parse(readFileSync(configFile, 'utf-8'))
+      if (config.smoke) {
+        result.details.hasSmokeConfig = true
+        result.score += 1
+
+        // Check if smoke endpoints are configured
+        const checks = config.smoke.checks || {}
+        const endpointCount =
+          (checks.publicEndpoints?.length || 0) +
+          (checks.authEndpoints?.length || 0) +
+          (checks.frontendPages?.length || 0)
+
+        if (endpointCount > 0) {
+          result.details.hasSmokeEndpoints = true
+          result.details.smokeEndpointCount = endpointCount
+          result.score += 1
+        }
+      }
+    } catch { /* invalid JSON */ }
+  }
+
+  // 2. Check for health endpoint in createApp config (+1 point)
+  // Look for createApp usage or /api/health route
+  const healthIndicators = [
+    'createApp',           // tetra-core createApp includes /api/health
+    '/api/health',         // explicit health endpoint
+    'healthcheck',         // Railway/Docker healthcheck
+  ]
+
+  let hasHealthEndpoint = false
+  const srcDirs = ['src', 'backend/src']
+  for (const srcDir of srcDirs) {
+    const srcPath = join(projectPath, srcDir)
+    if (!existsSync(srcPath)) continue
+
+    try {
+      const scanForHealth = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+          if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue
+          const fullPath = join(dir, entry.name)
+          if (entry.isDirectory()) {
+            scanForHealth(fullPath)
+          } else if (entry.isFile() && /\.(ts|js)$/.test(entry.name)) {
+            try {
+              const content = readFileSync(fullPath, 'utf-8')
+              if (healthIndicators.some(h => content.includes(h))) {
+                hasHealthEndpoint = true
+              }
+            } catch { /* skip */ }
+          }
+        }
+      }
+      scanForHealth(srcPath)
+    } catch { /* skip */ }
+  }
+
+  if (hasHealthEndpoint) {
+    result.details.hasHealthEndpoint = true
+    result.score += 1
+  }
+
+  // 3. Check for E2E test files (+1 point)
+  const e2eDirs = ['e2e', 'tests/e2e', 'test/e2e', 'cypress/e2e', 'playwright']
+  let e2eCount = 0
+
+  for (const dir of e2eDirs) {
+    const dirPath = join(projectPath, dir)
+    if (!existsSync(dirPath)) continue
+
+    try {
+      const countE2E = (path) => {
+        for (const entry of readdirSync(path, { withFileTypes: true })) {
+          if (entry.isDirectory() && !entry.name.startsWith('.')) {
+            countE2E(join(path, entry.name))
+          } else if (entry.isFile() && /\.(test|spec)\.(ts|tsx|js|jsx)$/.test(entry.name)) {
+            e2eCount++
+          }
+        }
+      }
+      countE2E(dirPath)
+    } catch { /* skip */ }
+  }
+
+  if (e2eCount > 0) {
+    result.details.hasE2ETests = true
+    result.details.e2eTestCount = e2eCount
+    result.score += 1
+  }
+
+  // 4. Check for post-deploy or smoke workflow (+1 point)
+  const workflowDir = join(projectPath, '.github/workflows')
+  if (existsSync(workflowDir)) {
+    try {
+      const workflows = readdirSync(workflowDir).filter(f => f.endsWith('.yml') || f.endsWith('.yaml'))
+      for (const wf of workflows) {
+        const content = readFileSync(join(workflowDir, wf), 'utf-8').toLowerCase()
+        if (content.includes('tetra-smoke') || content.includes('smoke-tests') || content.includes('post-deploy')) {
+          result.details.hasPostDeployWorkflow = true
+          result.details.workflowFile = wf
+          result.score += 1
+          break
+        }
+      }
+    } catch { /* skip */ }
+  }
+
+  // Status
+  result.score = Math.min(result.score, result.maxScore)
+
+  if (result.score === 0) {
+    result.status = 'error'
+    result.details.message = 'No smoke test infrastructure — add smoke config to .tetra-quality.json'
+  } else if (result.score < 3) {
+    result.status = 'warning'
+    result.details.message = 'Incomplete smoke test coverage'
+  }
+
+  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'} 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'} HealthCheckType
  *
  * @typedef {'ok'|'warning'|'error'} HealthStatus
  *

package/lib/checks/hygiene/stella-compliance.js

@@ -29,7 +29,7 @@ const DUPLICATE_PATTERNS = [
   {
     pattern: /const QUESTIONS_DIR\s*=\s*join\(tmpdir\(\)/,
     label: 'Local QUESTIONS_DIR (telegram question store)',
-    allowedIn: ['stella/src/telegram.ts']
+    allowedIn: ['stella/src/telegram.ts', 'backend/src/features/telegram/']
   },
   {
     pattern: /function detectWorkspaceRef\(\)/,
@@ -49,7 +49,7 @@ const DUPLICATE_PATTERNS = [
   {
     pattern: /function splitMessage\(text:\s*string/,
     label: 'Local splitMessage helper (for telegram)',
-    allowedIn: ['stella/src/telegram.ts', 'tools/helpers.ts']
+    allowedIn: ['stella/src/telegram.ts', 'tools/helpers.ts', 'backend/src/features/telegram/']
   },
   {
     pattern: /function playMacAlert\(\)/,

package/lib/checks/security/direct-supabase-client.js

@@ -63,6 +63,15 @@ const ALLOWED_FILES = [
   // Domain middleware (sets RLS session vars — needs direct client)
   /middleware\/domainOrganizationMiddleware\.ts$/,
 
+  // Auth routes that only use Supabase Auth API (not DB queries)
+  /routes\/auth\.ts$/,
+
+  // WebSocket auth verification (only uses auth.getUser for token validation)
+  /services\/terminalWebSocket\.ts$/,
+
+  // Frontend Supabase client (Vite apps — client-side auth only, no Tetra backend)
+  /frontend\/src\/lib\/supabase\.ts$/,
+
   // Scripts (not production code)
   /scripts\//,
 ]

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

@@ -34,10 +34,13 @@ export async function run(config, projectRoot) {
     summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 }
   }
 
-  // Get all source files
+  // Get all source files (always exclude node_modules, even nested ones)
   const files = await glob('**/*.{ts,tsx,js,jsx,json}', {
     cwd: projectRoot,
-    ignore: config.ignore
+    ignore: [
+      '**/node_modules/**',
+      ...config.ignore
+    ]
   })
 
   for (const file of files) {

package/lib/runner.js

@@ -47,6 +47,7 @@ import { check as checkBundleSize } from './checks/health/bundle-size.js'
 import { check as checkSast } from './checks/health/sast.js'
 import { check as checkLicenseAudit } from './checks/health/license-audit.js'
 import { check as checkSecurityLayers } from './checks/health/security-layers.js'
+import { check as checkSmokeReadiness } from './checks/health/smoke-readiness.js'
 
 /**
  * Adapt a health check (score-based) to the runner format (meta + run).
@@ -116,7 +117,8 @@ const ALL_CHECKS = {
     adaptHealthCheck('bundle-size', 'Bundle Size Monitoring', 'low', checkBundleSize),
     adaptHealthCheck('sast', 'Static Application Security Testing', 'medium', checkSast),
     adaptHealthCheck('license-audit', 'License Compliance', 'low', checkLicenseAudit),
-    adaptHealthCheck('security-layers', 'Security Layer Coverage', 'high', checkSecurityLayers)
+    adaptHealthCheck('security-layers', 'Security Layer Coverage', 'high', checkSecurityLayers),
+    adaptHealthCheck('smoke-readiness', 'Smoke Test Readiness', 'medium', checkSmokeReadiness)
   ],
   codeQuality: [
     apiResponseFormat,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulbatical/tetra-dev-toolkit",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "publishConfig": {
     "access": "restricted"
   },
@@ -33,7 +33,8 @@
     "tetra-migration-lint": "./bin/tetra-migration-lint.js",
     "tetra-db-push": "./bin/tetra-db-push.js",
     "tetra-check-peers": "./bin/tetra-check-peers.js",
-    "tetra-security-gate": "./bin/tetra-security-gate.js"
+    "tetra-security-gate": "./bin/tetra-security-gate.js",
+    "tetra-smoke": "./bin/tetra-smoke.js"
   },
   "files": [
     "bin/",