@soulbatical/tetra-dev-toolkit 1.20.25 → 1.21.0

package/bin/tetra-init-smoke.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+
+/**
+ * tetra-init-smoke
+ *
+ * Scaffolds a Playwright smoke test suite into e2e/smoke.spec.ts.
+ *
+ * What it does:
+ *   1. Reads frontend/src/app/app/app-config.tsx (if present) and extracts
+ *      all href values from the navigation config.
+ *   2. Reads doppler.yaml to discover the Doppler project name.
+ *   3. Reads .ralph/ports.json (or package.json scripts) to find the frontend port.
+ *   4. Copies the template from ../templates/playwright-smoke.spec.ts.template
+ *      into e2e/smoke.spec.ts, substituting:
+ *        {{NAV_ROUTES}}      -> extracted route array
+ *        {{FRONTEND_PORT}}   -> detected frontend port
+ *        {{DOPPLER_PROJECT}} -> doppler project name
+ *   5. Prints next steps: run with --update-snapshots, commit the file + baseline.
+ *
+ * Usage:
+ *   npx tetra-init-smoke
+ *   npx tetra-init-smoke --force   (overwrite existing e2e/smoke.spec.ts)
+ *   npx tetra-init-smoke --dry-run (preview without writing)
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const projectRoot = process.cwd()
+const args = process.argv.slice(2)
+const force = args.includes('--force') || args.includes('-f')
+const dryRun = args.includes('--dry-run')
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+// -- Helpers ------------------------------------------------------------------
+
+function readFileSafe(absPath) {
+  try { return readFileSync(absPath, 'utf-8') } catch { return null }
+}
+
+function log(msg) { console.log(msg) }
+function warn(msg) { console.warn('  WARNING: ' + msg) }
+function ok(msg) { console.log('  OK: ' + msg) }
+
+// -- Step 1: discover navigation routes ---------------------------------------
+
+function extractNavRoutes(projectRoot) {
+  const candidates = [
+    join(projectRoot, 'frontend', 'src', 'app', 'app', 'app-config.tsx'),
+    join(projectRoot, 'frontend', 'src', 'app', 'app', 'app-config.ts'),
+    join(projectRoot, 'src', 'app', 'app', 'app-config.tsx'),
+    join(projectRoot, 'src', 'app', 'app', 'app-config.ts'),
+    join(projectRoot, 'app', 'app', 'app-config.tsx'),
+  ]
+
+  for (const candidate of candidates) {
+    const content = readFileSafe(candidate)
+    if (!content) continue
+
+    const routes = []
+    const hrefRe = /href\s*:\s*['"]([^'"]+)['"]/g
+    let m
+    while ((m = hrefRe.exec(content)) !== null) {
+      const href = m[1]
+      if (href.startsWith('/') && !href.includes('://')) {
+        routes.push(href)
+      }
+    }
+
+    if (routes.length > 0) {
+      ok('Found ' + routes.length + ' navigation routes in ' + candidate.replace(projectRoot + '/', ''))
+      return routes
+    }
+  }
+
+  warn('Could not find app-config.tsx -- NAV_ROUTES will be empty. Add routes manually.')
+  return []
+}
+
+// -- Step 2: discover Doppler project -----------------------------------------
+
+function readDopplerProject(projectRoot) {
+  const dopplerPath = join(projectRoot, 'doppler.yaml')
+  const content = readFileSafe(dopplerPath)
+  if (!content) return null
+  const m = content.match(/project:\s*(\S+)/)
+  return m ? m[1] : null
+}
+
+// -- Step 3: discover frontend port -------------------------------------------
+
+function detectFrontendPort(projectRoot) {
+  const portsPath = join(projectRoot, '.ralph', 'ports.json')
+  const portsContent = readFileSafe(portsPath)
+  if (portsContent) {
+    try {
+      const ports = JSON.parse(portsContent)
+      if (ports.frontend_port) return String(ports.frontend_port)
+    } catch { /* ignore */ }
+  }
+
+  const envLocal = readFileSafe(join(projectRoot, '.env.local'))
+  if (envLocal) {
+    const m = envLocal.match(/VITE_PORT\s*=\s*(\d+)/)
+    if (m) return m[1]
+  }
+
+  const pkgPath = join(projectRoot, 'frontend', 'package.json')
+  const pkg = readFileSafe(pkgPath)
+  if (pkg) {
+    try {
+      const parsed = JSON.parse(pkg)
+      const scripts = Object.values(parsed.scripts || {}).join(' ')
+      const m = scripts.match(/-p\s+(\d+)/)
+      if (m) return m[1]
+    } catch { /* ignore */ }
+  }
+
+  return '3001'
+}
+
+// -- Step 4: load and fill template -------------------------------------------
+
+function findTemplate() {
+  const templatePath = join(__dirname, '..', 'templates', 'playwright-smoke.spec.ts.template')
+  if (existsSync(templatePath)) return templatePath
+
+  const nmPath = join(projectRoot, 'node_modules', '@soulbatical', 'tetra-dev-toolkit', 'templates', 'playwright-smoke.spec.ts.template')
+  if (existsSync(nmPath)) return nmPath
+
+  return null
+}
+
+function buildOutput(template, opts) {
+  const navRoutes = opts.navRoutes
+  const frontendPort = opts.frontendPort
+  const dopplerProject = opts.dopplerProject
+
+  const routesArray = navRoutes.length > 0
+    ? navRoutes.map(function(r) { return "  '" + r + "'," }).join('\n')
+    : "  // No routes detected -- add them manually, e.g. '/app/dashboard',"
+
+  return template
+    .replace('  // {{NAV_ROUTES}}', routesArray)
+    .split('{{NAV_ROUTES}}').join(routesArray)
+    .split('{{FRONTEND_PORT}}').join(frontendPort)
+    .split('{{DOPPLER_PROJECT}}').join(dopplerProject || '<your-doppler-project>')
+}
+
+// -- Main ---------------------------------------------------------------------
+
+log('')
+log('Tetra Smoke Test Scaffolder')
+log('='.repeat(50))
+log('')
+
+const navRoutes = extractNavRoutes(projectRoot)
+const frontendPort = detectFrontendPort(projectRoot)
+const dopplerProject = readDopplerProject(projectRoot)
+
+log('  Routes:   ' + navRoutes.length + ' detected')
+log('  Port:     ' + frontendPort)
+log('  Doppler:  ' + (dopplerProject || '(not found -- doppler.yaml missing)'))
+log('')
+
+const templatePath = findTemplate()
+if (!templatePath) {
+  console.error('  ERROR: Template not found. Is @soulbatical/tetra-dev-toolkit installed?')
+  process.exit(1)
+}
+
+const template = readFileSafe(templatePath)
+if (!template) {
+  console.error('  ERROR: Could not read template: ' + templatePath)
+  process.exit(1)
+}
+
+const output = buildOutput(template, { navRoutes, frontendPort, dopplerProject })
+const outputPath = join(projectRoot, 'e2e', 'smoke.spec.ts')
+
+if (dryRun) {
+  log('DRY RUN -- would write:')
+  log('  ' + outputPath)
+  log('')
+  log('Preview (first 40 lines):')
+  log('-'.repeat(50))
+  output.split('\n').slice(0, 40).forEach(function(l) { log('  ' + l) })
+  log('  ...')
+  log('')
+  process.exit(0)
+}
+
+if (existsSync(outputPath) && !force) {
+  console.error('  ERROR: ' + outputPath + ' already exists.')
+  console.error('         Use --force to overwrite, or --dry-run to preview.')
+  process.exit(1)
+}
+
+const e2eDir = join(projectRoot, 'e2e')
+if (!existsSync(e2eDir)) {
+  mkdirSync(e2eDir, { recursive: true })
+  ok('Created e2e/')
+}
+
+writeFileSync(outputPath, output, 'utf-8')
+ok('Written ' + outputPath.replace(projectRoot + '/', ''))
+
+log('')
+log('Next steps:')
+log('='.repeat(50))
+log('')
+log('  1. Install Playwright if not already:')
+log('     npm install --save-dev @playwright/test')
+log('     npx playwright install chromium')
+log('')
+log('  2. Make sure DEV_TEST_EMAIL and DEV_TEST_PASSWORD exist in Doppler:')
+if (dopplerProject) {
+  log('     doppler secrets set DEV_TEST_EMAIL=... --project ' + dopplerProject + ' --config dev_backend')
+  log('     doppler secrets set DEV_TEST_PASSWORD=... --project ' + dopplerProject + ' --config dev_backend')
+} else {
+  log('     doppler secrets set DEV_TEST_EMAIL=... --project <p> --config dev_backend')
+  log('     doppler secrets set DEV_TEST_PASSWORD=... --project <p> --config dev_backend')
+}
+log('')
+log('  3. Start the dev server, then generate baseline screenshots:')
+log('     doppler run -- npx playwright test e2e/smoke.spec.ts --update-snapshots')
+log('')
+log('  4. Commit the spec and baseline:')
+log('     git add e2e/smoke.spec.ts e2e/smoke.spec.ts-snapshots/')
+log('     git commit -m "test: add Playwright smoke tests"')
+log('')
+log('  5. Subsequent runs (CI):')
+log('     doppler run -- npx playwright test e2e/smoke.spec.ts')
+log('')

package/lib/checks/codeQuality/api-response-format.js

@@ -33,46 +33,46 @@ export async function run(config, projectRoot) {
     }
   }
 
-  // Find all route and controller files
-  const patterns = [
-    '**/routes/**/*.ts',
-    '**/routes/**/*.js',
-    '**/controllers/**/*.ts',
-    '**/controllers/**/*.js',
-    '**/features/**/controllers/**/*.ts',
-    '**/features/**/*.controller.ts'
-  ]
-
-  let files = []
-  for (const pattern of patterns) {
-    const found = await glob(pattern, {
-      cwd: projectRoot,
-      ignore: [
-        ...(config.ignore || []),
-        'node_modules/**',
-        '**/node_modules/**',
-        'dist/**',
-        '**/dist/**',
-        'build/**',
-        '**/build/**',
-        '**/*.test.*',
-        '**/*.spec.*',
-        '**/*.d.ts',
-        '**/*.js.map'
-      ]
-    })
-    files.push(...found)
-  }
-
-  // Deduplicate
-  files = [...new Set(files)]
+  // Discover ALL backend source files (no path conventions assumed).
+  // Strategy: scan every .ts/.js file and detect Express route handlers by content.
+  // This catches feature folders, custom layouts, monorepo backends, etc.
+  const candidates = await glob('**/*.{ts,js,mts,cts,mjs,cjs}', {
+    cwd: projectRoot,
+    ignore: [
+      ...(config.ignore || []),
+      'node_modules/**',
+      '**/node_modules/**',
+      'dist/**',
+      '**/dist/**',
+      'build/**',
+      '**/build/**',
+      '.next/**',
+      '**/.next/**',
+      'coverage/**',
+      '**/coverage/**',
+      '**/*.test.*',
+      '**/*.spec.*',
+      '**/*.d.ts',
+      '**/*.js.map',
+      // Frontend folders – these are not Express backends
+      'frontend/**',
+      'web/**',
+      'app/**',
+      'pages/**',
+      'src/app/**',
+      'src/pages/**'
+    ]
+  })
+
+  const files = [...new Set(candidates)]
 
   if (files.length === 0) {
     results.skipped = true
-    results.skipReason = 'No route or controller files found'
+    results.skipReason = 'No source files found to scan'
     return results
   }
 
+  let backendFilesScanned = 0
   for (const file of files) {
     const filePath = `${projectRoot}/${file}`
     let content
@@ -82,10 +82,21 @@ export async function run(config, projectRoot) {
       continue
     }
 
+    if (!isExpressRouteFile(content)) continue
+
+    backendFilesScanned++
     const lines = content.split('\n')
     analyzeFile(file, lines, results)
   }
 
+  results.info.backendFilesScanned = backendFilesScanned
+
+  if (backendFilesScanned === 0) {
+    results.skipped = true
+    results.skipReason = 'No Express route handlers detected in scanned files'
+    return results
+  }
+
   results.passed = results.findings.filter(f => f.severity === 'critical' || f.severity === 'high').length === 0
   results.info.violations = results.findings.length
   results.info.compliant = results.info.totalEndpoints - results.info.violations
@@ -93,6 +104,30 @@ export async function run(config, projectRoot) {
   return results
 }
 
+/**
+ * Heuristic: does this file contain Express-style route handlers that
+ * eventually call res.json() or res.status().json()?
+ *
+ * We require BOTH:
+ *   1. An indicator that this is server code (express import / Request type / router/app verb)
+ *   2. At least one res.json() / res.status(...).json() call
+ *
+ * This avoids scanning frontend files that happen to use the variable name `res`.
+ */
+function isExpressRouteFile(content) {
+  const hasResJsonCall = /\bres\s*(?:\.\s*status\s*\([^)]*\)\s*)?\.\s*json\s*\(/.test(content)
+  if (!hasResJsonCall) return false
+
+  const looksLikeExpress =
+    /from\s+['"]express['"]/.test(content) ||
+    /require\s*\(\s*['"]express['"]\s*\)/.test(content) ||
+    /\b(?:Request|Response|NextFunction|Router)\b/.test(content) ||
+    /\b(?:router|app)\s*\.\s*(?:get|post|put|patch|delete|all|use)\s*\(/.test(content) ||
+    /\bexpress\s*\(\s*\)/.test(content)
+
+  return looksLikeExpress
+}
+
 function analyzeFile(file, lines, results) {
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i]