@soulbatical/tetra-dev-toolkit 1.20.0 → 2.0.0

package/bin/tetra-smoke.js

@@ -1,532 +0,0 @@
-#!/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/smoke-readiness.js

@@ -1,150 +0,0 @@
-/**
- * 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
-}