@soulbatical/tetra-dev-toolkit 1.20.10 → 1.20.12

package/bin/tetra-init-tests.js

@@ -3,16 +3,24 @@
 /**
  * Tetra Init Tests — Scaffold golden standard E2E test structure.
  *
- * Creates:
- *   tests/e2e/helpers/api-client.ts    (HTTP client with X-Test-Key bypass)
- *   tests/e2e/helpers/test-users.ts    (Login + token caching)
- *   tests/e2e/01-auth.test.ts          (Auth: login, session, refresh, logout)
- *   tests/e2e/07-security.test.ts      (Auth walls + role access)
- *   vitest.config.e2e.ts               (Vitest config for E2E)
+ * Creates the complete test infrastructure:
+ *   tests/e2e/helpers/api-client.ts       HTTP client with X-Test-Key bypass
+ *   tests/e2e/helpers/test-users.ts       Login + token caching
+ *   tests/e2e/global-setup.ts             Login once, share tokens
+ *   tests/e2e/.gitignore                  Exclude token files
+ *   tests/e2e/01-auth.test.ts             Auth: login, session, refresh, logout
+ *   tests/e2e/02-crud-resources.test.ts   CRUD for all resources (customize)
+ *   tests/e2e/03-permissions.test.ts      Auth walls for all routes (customize)
+ *   tests/e2e/04-business-flows.test.ts   End-to-end user journeys (customize)
+ *   tests/e2e/05-security.test.ts         Input validation, injection, CORS
+ *   vitest.config.e2e.ts                  Vitest config for E2E
+ *   .github/workflows/ci.yml             CI with API tests (if missing)
+ *   package.json                          test:e2e script (if missing)
  *
  * Usage:
- *   tetra-init-tests                   # Interactive
+ *   tetra-init-tests                   # Scaffold all
  *   tetra-init-tests --force           # Overwrite existing files
+ *   tetra-init-tests --ci-only         # Only add CI workflow
  */
 
 import { program } from 'commander'
@@ -24,9 +32,13 @@ const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
 const TEMPLATES_DIR = join(__dirname, '..', 'lib', 'templates', 'tests')
 
+let filesCreated = 0
+let filesSkipped = 0
+
 function copyTemplate(templateName, destPath, force = false) {
   if (existsSync(destPath) && !force) {
-    console.log(`  ⏩ ${destPath} (exists, use --force to overwrite)`)
+    console.log(`  ⏩ ${destPath} (exists)`)
+    filesSkipped++
     return false
   }
 
@@ -40,17 +52,38 @@ function copyTemplate(templateName, destPath, force = false) {
   mkdirSync(dirname(destPath), { recursive: true })
   writeFileSync(destPath, content)
   console.log(`  ✅ ${destPath}`)
+  filesCreated++
   return true
 }
 
 function writeFile(destPath, content, force = false) {
   if (existsSync(destPath) && !force) {
     console.log(`  ⏩ ${destPath} (exists)`)
+    filesSkipped++
     return false
   }
   mkdirSync(dirname(destPath), { recursive: true })
   writeFileSync(destPath, content)
   console.log(`  ✅ ${destPath}`)
+  filesCreated++
+  return true
+}
+
+function addNpmScript(root, scriptName, scriptCmd) {
+  const pkgPath = join(root, 'package.json')
+  if (!existsSync(pkgPath)) return false
+
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+  if (pkg.scripts?.[scriptName]) {
+    console.log(`  ⏩ package.json script "${scriptName}" (exists)`)
+    return false
+  }
+
+  pkg.scripts = pkg.scripts || {}
+  pkg.scripts[scriptName] = scriptCmd
+  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
+  console.log(`  ✅ package.json script "${scriptName}" added`)
+  filesCreated++
   return true
 }
 
@@ -59,27 +92,39 @@ program
   .description('Scaffold Tetra golden standard E2E test structure')
   .option('--force', 'Overwrite existing files')
   .option('--dir <path>', 'Test directory (default: tests/e2e)', 'tests/e2e')
+  .option('--ci-only', 'Only add CI workflow, skip test files')
+  .option('--port <port>', 'Backend port (default: 3003)', '3003')
   .action((options) => {
     const root = process.cwd()
     const testDir = join(root, options.dir)
     const helpersDir = join(testDir, 'helpers')
     const force = !!options.force
+    const port = options.port
 
-    console.log('\n  Tetra Init Tests — Golden Standard E2E\n')
+    console.log('\n  Tetra Init Tests — Golden Standard E2E v2\n')
 
-    // 1. Helpers
-    console.log('  Helpers:')
-    copyTemplate('api-client.ts.tmpl', join(helpersDir, 'api-client.ts'), force)
-    copyTemplate('test-users.ts.tmpl', join(helpersDir, 'test-users.ts'), force)
+    if (!options.ciOnly) {
+      // ── 1. Helpers ──
+      console.log('  Helpers:')
+      copyTemplate('api-client.ts.tmpl', join(helpersDir, 'api-client.ts'), force)
+      copyTemplate('test-users.ts.tmpl', join(helpersDir, 'test-users.ts'), force)
 
-    // 2. Test files
-    console.log('\n  Test files:')
-    copyTemplate('01-auth.test.ts.tmpl', join(testDir, '01-auth.test.ts'), force)
-    copyTemplate('07-security.test.ts.tmpl', join(testDir, '07-security.test.ts'), force)
+      // ── 2. Global setup ──
+      console.log('\n  Setup:')
+      copyTemplate('global-setup.ts.tmpl', join(testDir, 'global-setup.ts'), force)
+      writeFile(join(testDir, '.gitignore'), '.e2e-tokens.json\n', force)
 
-    // 3. Vitest config
-    console.log('\n  Config:')
-    writeFile(join(root, 'vitest.config.e2e.ts'), `import { defineConfig } from 'vitest/config';
+      // ── 3. Test files (complete suite) ──
+      console.log('\n  Test files:')
+      copyTemplate('01-auth.test.ts.tmpl', join(testDir, '01-auth.test.ts'), force)
+      copyTemplate('02-crud-resources.test.ts.tmpl', join(testDir, '02-crud-resources.test.ts'), force)
+      copyTemplate('03-permissions.test.ts.tmpl', join(testDir, '03-permissions.test.ts'), force)
+      copyTemplate('04-business-flows.test.ts.tmpl', join(testDir, '04-business-flows.test.ts'), force)
+      copyTemplate('05-security.test.ts.tmpl', join(testDir, '05-security.test.ts'), force)
+
+      // ── 4. Vitest config ──
+      console.log('\n  Config:')
+      writeFile(join(root, 'vitest.config.e2e.ts'), `import { defineConfig } from 'vitest/config';
 
 export default defineConfig({
   test: {
@@ -88,62 +133,136 @@ export default defineConfig({
     testTimeout: 30000,
     hookTimeout: 60000,
     sequence: { concurrent: false },
+    env: {
+      E2E_BASE_URL: process.env.E2E_BASE_URL || 'http://localhost:${port}',
+      E2E_ADMIN_EMAIL: process.env.E2E_ADMIN_EMAIL || 'e2e-admin@example.com',
+      E2E_PASSWORD: process.env.E2E_PASSWORD || 'TestPass1234',
+      RATE_LIMIT_BYPASS_KEY: process.env.RATE_LIMIT_BYPASS_KEY || '',
+    },
   },
 });
 `, force)
 
-    // 4. Global setup stub
-    writeFile(join(testDir, 'global-setup.ts'), `/**
- * Global setup — creates test users via API before all tests.
- * CUSTOMIZE: implement signup + invite flow for your project.
- *
- * Required env vars (set these in your test runner or CI):
- *   E2E_BASE_URL          — Backend URL (e.g. http://localhost:3026)
- *   RATE_LIMIT_BYPASS_KEY — X-Test-Key value (from .ralph/test-config.yml)
- *
- * This setup should:
- * 1. Create an admin via signup
- * 2. Create a shared resource (track/project/workspace)
- * 3. Invite an elevated user (coach/manager)
- * 4. Invite a basic user (client/member)
- * 5. Store IDs/emails in process.env for test-users.ts
- */
+      // ── 5. npm scripts ──
+      console.log('\n  Scripts:')
+      addNpmScript(root, 'test:e2e', `E2E_BASE_URL=http://localhost:${port} vitest run --config vitest.config.e2e.ts`)
+      addNpmScript(root, 'test:e2e:watch', `E2E_BASE_URL=http://localhost:${port} vitest --config vitest.config.e2e.ts`)
+    }
 
-const BASE_URL = process.env.E2E_BASE_URL!;
-const PASSWORD = 'TestPass1234';
+    // ── 6. CI workflow ──
+    console.log('\n  CI:')
+    const ciPath = join(root, '.github', 'workflows', 'ci.yml')
+    if (existsSync(ciPath)) {
+      // Check if api-tests job already exists
+      const ciContent = readFileSync(ciPath, 'utf-8')
+      if (ciContent.includes('api-tests')) {
+        console.log('  ⏩ .github/workflows/ci.yml (api-tests job exists)')
+      } else {
+        console.log('  ⚠️  .github/workflows/ci.yml exists but has NO api-tests job')
+        console.log('     Add an api-tests job that runs: npx vitest run --config vitest.config.e2e.ts')
+        console.log('     See: tetra-init-tests --ci-only --force')
+      }
+    } else {
+      writeFile(ciPath, `name: CI
 
-export async function setup() {
-  // TODO: Implement for your project
-  // See CoachHub's global-setup.ts as reference
-  console.log('\\n  ⚠️  global-setup.ts is a stub — implement for your project\\n');
-}
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
 
-export async function teardown() {
-  // Best-effort cleanup
-}
+jobs:
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: cd backend && npx tsc --noEmit
+
+  frontend-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: cd frontend && npx next build
+        env:
+          NEXT_PUBLIC_API_URL: http://localhost:${port}
+          NEXT_PUBLIC_SUPABASE_URL: https://placeholder.supabase.co
+          NEXT_PUBLIC_SUPABASE_ANON_KEY: placeholder
+
+  api-tests:
+    runs-on: ubuntu-latest
+    needs: typecheck
+    env:
+      SUPABASE_URL: \${{ secrets.E2E_SUPABASE_URL }}
+      SUPABASE_ANON_KEY: \${{ secrets.E2E_SUPABASE_ANON_KEY }}
+      SUPABASE_SERVICE_ROLE_KEY: \${{ secrets.E2E_SUPABASE_SERVICE_ROLE_KEY }}
+      SUPABASE_JWT_SECRET: \${{ secrets.E2E_SUPABASE_JWT_SECRET }}
+      E2E_ADMIN_EMAIL: \${{ secrets.E2E_ADMIN_EMAIL }}
+      E2E_PASSWORD: \${{ secrets.E2E_PASSWORD }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - name: Start backend
+        run: |
+          cd backend && npx tsx src/index.ts &
+          for i in $(seq 1 30); do
+            curl -sf http://localhost:${port}/api/health > /dev/null 2>&1 && break
+            sleep 2
+          done
+          curl -sf http://localhost:${port}/api/health || exit 1
+        env:
+          NODE_ENV: test
+          PORT: ${port}
+      - name: Run API e2e tests
+        run: npx vitest run --config vitest.config.e2e.ts
+        env:
+          E2E_BASE_URL: http://localhost:${port}
 `, force)
+    }
 
-    // Summary
+    // ── 7. Post-deploy workflow ──
+    const postDeployPath = join(root, '.github', 'workflows', 'post-deploy-tests.yml')
+    if (!existsSync(postDeployPath)) {
+      console.log('  💡 No post-deploy-tests.yml found')
+      console.log('     Create one with: tetra-smoke --url https://your-app.railway.app')
+    }
+
+    // ── Summary ──
     console.log(`
-  Done! Next steps:
-
-  1. Implement global-setup.ts (create test users via your API)
-  2. Set E2E_BASE_URL and RATE_LIMIT_BYPASS_KEY in your env
-  3. Customize 07-security.test.ts with your protected routes
-  4. Add project-specific test files (02-*.test.ts, 03-*.test.ts, etc.)
-  5. Run: npx vitest run --config vitest.config.e2e.ts
-
-  Golden standard pattern:
-    01-auth         — login, session, refresh, logout (universal)
-    02-[resource]   — main resource CRUD + permissions
-    03-[nested]     — nested resources (messages, notes, etc.)
-    04-admin        — admin-only features
-    05-[feature]    — feature-specific tests
-    06-planner      — scheduling (if using Tetra Planner)
-    07-security     — auth walls + role access (universal)
-    08-permissions   — permission matrix (generatable)
-    09-isolation    — cross-role data isolation
-    10+             — additional features
+  ─────────────────────────────────────────
+  Created: ${filesCreated} files | Skipped: ${filesSkipped} (already exist)
+  ─────────────────────────────────────────
+
+  Next steps:
+
+  1. Edit global-setup.ts — set your test user email/password
+  2. Edit 02-crud-resources.test.ts — add your FeatureConfig resources
+  3. Edit 03-permissions.test.ts — add all protected routes
+  4. Edit 04-business-flows.test.ts — add your business flows
+  5. Run: npm run test:e2e
+
+  Then run tetra-test-audit to see what's NOT covered yet.
+
+  Golden standard layers:
+    01-auth              Auth: login, session, refresh (universal)
+    02-crud-resources    CRUD for every resource (from FeatureConfig)
+    03-permissions       Auth walls for every route (auto-auditable)
+    04-business-flows    End-to-end user journeys
+    05-security          Input validation, injection, error format
+    06+                  Project-specific features
 `)
   })
 

package/bin/tetra-init.js

@@ -430,6 +430,66 @@ async function initQuality(config, options) {
   )
 }
 
+async function initCi(config, options) {
+  console.log('')
+  console.log('🔄 Initializing CI workflow...')
+
+  const workflowDir = join(projectRoot, '.github/workflows')
+  if (!existsSync(workflowDir)) {
+    mkdirSync(workflowDir, { recursive: true })
+  }
+
+  // Detect project structure
+  const hasBackend = existsSync(join(projectRoot, 'backend/package.json'))
+  const hasFrontend = existsSync(join(projectRoot, 'frontend/package.json'))
+  const hasMigrations = existsSync(join(projectRoot, 'backend/supabase/migrations')) ||
+    existsSync(join(projectRoot, 'supabase/migrations'))
+
+  let workspaces
+  if (hasBackend && hasFrontend) {
+    workspaces = 'backend,frontend'
+  } else if (hasBackend) {
+    workspaces = 'backend'
+  } else {
+    workspaces = '.'
+  }
+
+  let withLines = [`      workspaces: "${workspaces}"`]
+  if (!hasFrontend) withLines.push('      skip-frontend: true')
+  if (!hasMigrations) withLines.push('      skip-migration-lint: true')
+
+  const workflowContent = `name: PR Quality Gate
+
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - '*.md'
+      - 'docs/**'
+      - '.ralph/**'
+      - 'LICENSE'
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - '*.md'
+      - 'docs/**'
+      - '.ralph/**'
+      - 'LICENSE'
+
+concurrency:
+  group: quality-\${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    uses: mralbertzwolle/tetra/.github/workflows/pr-quality.yml@main
+    with:
+${withLines.join('\n')}
+`
+
+  writeIfMissing(join(workflowDir, 'quality.yml'), workflowContent, options)
+}
+
 function checkCompleteness() {
   console.log('')
   console.log('🔎 Checking project completeness...')
@@ -441,6 +501,7 @@ function checkCompleteness() {
     { path: 'doppler.yaml', category: 'root', required: true },
     { path: 'CLAUDE.md', category: 'root', required: true },
     { path: '.tetra-quality.json', category: 'root', required: false },
+    { path: '.github/workflows/quality.yml', category: 'root', required: true },
     { path: '.gitignore', category: 'root', required: true },
 
     // .ralph/ files
@@ -524,7 +585,7 @@ program
   .name('tetra-init')
   .description('Initialize a Tetra project with all required config files')
   .version('1.0.0')
-  .argument('[component]', 'Component to init: ralph, quality, check, or all (default)')
+  .argument('[component]', 'Component to init: ralph, quality, ci, check, or all (default)')
   .option('-n, --name <name>', 'Project name (skips interactive prompt)')
   .option('-d, --description <desc>', 'Project description')
   .option('--backend-port <port>', 'Backend port number', parseInt)
@@ -573,7 +634,7 @@ program
     console.log(`  Frontend: localhost:${config.frontendPort}`)
 
     const components = component === 'all' || !component
-      ? ['ralph', 'quality']
+      ? ['ralph', 'quality', 'ci']
       : [component]
 
     for (const comp of components) {
@@ -584,9 +645,12 @@ program
         case 'quality':
           await initQuality(config, options)
           break
+        case 'ci':
+          await initCi(config, options)
+          break
         default:
           console.log(`Unknown component: ${comp}`)
-          console.log('Available: ralph, quality, check, or all (default)')
+          console.log('Available: ralph, quality, ci, check, or all (default)')
       }
     }
 

package/bin/tetra-setup.js

@@ -262,47 +262,66 @@ async function setupCi(options) {
     mkdirSync(workflowDir, { recursive: true })
   }
 
+  // Detect project structure
+  const hasBackend = existsSync(join(projectRoot, 'backend/package.json'))
+  const hasFrontend = existsSync(join(projectRoot, 'frontend/package.json'))
+  const hasMigrations = existsSync(join(projectRoot, 'backend/supabase/migrations')) ||
+    existsSync(join(projectRoot, 'supabase/migrations'))
+
+  // Determine workspaces
+  let workspaces
+  if (hasBackend && hasFrontend) {
+    workspaces = 'backend,frontend'
+  } else if (hasBackend) {
+    workspaces = 'backend'
+  } else {
+    workspaces = '.'
+  }
+
+  const skipFrontend = !hasFrontend
+  const skipMigrationLint = !hasMigrations
+
+  // Build with block for inputs
+  let withBlock = `      workspaces: "${workspaces}"`
+  if (skipFrontend) {
+    withBlock += `\n      skip-frontend: true`
+  }
+  if (skipMigrationLint) {
+    withBlock += `\n      skip-migration-lint: true`
+  }
+
   const workflowPath = join(workflowDir, 'quality.yml')
   if (!existsSync(workflowPath) || options.force) {
-    const workflowContent = `name: Quality Checks
+    const workflowContent = `name: PR Quality Gate
 
 on:
   push:
-    branches: [main, master]
+    branches: [main]
+    paths-ignore:
+      - '*.md'
+      - 'docs/**'
+      - '.ralph/**'
+      - 'LICENSE'
   pull_request:
-    branches: [main, master]
+    branches: [main]
+    paths-ignore:
+      - '*.md'
+      - 'docs/**'
+      - '.ralph/**'
+      - 'LICENSE'
+
+concurrency:
+  group: quality-\${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
   quality:
-    name: 🔍 Tetra Quality Audit
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          cache: 'npm'
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Run Tetra Quality Audit
-        run: npx tetra-audit --ci
-
-      - name: Upload results
-        if: always()
-        uses: actions/upload-artifact@v4
-        with:
-          name: quality-report
-          path: quality-report.json
-          retention-days: 7
+    uses: mralbertzwolle/tetra/.github/workflows/pr-quality.yml@main
+    with:
+${withBlock}
 `
     writeFileSync(workflowPath, workflowContent)
-    console.log('   ✅ Created .github/workflows/quality.yml')
+    console.log(`   ✅ Created .github/workflows/quality.yml (${workspaces}, frontend=${!skipFrontend}, migrations=${!skipMigrationLint})`)
   } else {
     console.log('   ⏭️  Workflow already exists (use --force to overwrite)')
   }

package/bin/tetra-test-audit.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+/**
+ * Tetra Test Audit — Discover test coverage gaps across a Tetra project.
+ *
+ * Scans FeatureConfigs, routes, frontend pages, and test files to find:
+ *   - Features without CRUD tests
+ *   - API endpoints without auth wall tests
+ *   - Frontend pages without e2e specs
+ *   - CI pipeline gaps
+ *
+ * Usage:
+ *   tetra-test-audit                          # Audit current project
+ *   tetra-test-audit --path /path/to/project  # Audit specific project
+ *   tetra-test-audit --json                   # JSON output for CI
+ *   tetra-test-audit --ci                     # GitHub Actions annotations
+ *   tetra-test-audit --strict                 # Fail on any gap
+ *
+ * Exit codes:
+ *   0 = all critical checks pass (or no gaps in --strict mode)
+ *   1 = gaps found
+ */
+
+import { program } from 'commander'
+import chalk from 'chalk'
+import {
+  runTestCoverageAudit,
+  formatReport,
+  formatReportJSON,
+  formatCIAnnotations,
+} from '../lib/audits/test-coverage-audit.js'
+
+program
+  .name('tetra-test-audit')
+  .description('Audit test coverage gaps across a Tetra project')
+  .version('1.0.0')
+  .option('--path <dir>', 'Project root directory (default: cwd)')
+  .option('--json', 'JSON output for CI')
+  .option('--ci', 'GitHub Actions annotations for failures')
+  .option('--strict', 'Fail on any gap (default: only fail on critical gaps like missing auth tests)')
+  .action(async (options) => {
+    try {
+      const projectRoot = options.path || process.cwd()
+
+      if (!options.json) {
+        console.log(chalk.gray('\n  Scanning project...'))
+      }
+
+      const report = await runTestCoverageAudit(projectRoot)
+
+      // Output
+      if (options.json) {
+        console.log(formatReportJSON(report))
+      } else {
+        console.log(formatReport(report, chalk))
+
+        if (options.ci) {
+          const annotations = formatCIAnnotations(report)
+          if (annotations) {
+            console.log(annotations)
+          }
+        }
+      }
+
+      // Exit code
+      const { summary } = report
+      if (options.strict) {
+        // Strict: fail on any gap
+        process.exit(summary.totalGaps > 0 ? 1 : 0)
+      } else {
+        // Default: only fail on critical gaps (missing auth wall tests)
+        process.exit(summary.criticalGaps > 0 ? 1 : 0)
+      }
+    } catch (err) {
+      console.error(chalk.red(`\n  ERROR: ${err.message}\n`))
+      if (!options.json) {
+        console.error(chalk.gray(`  ${err.stack}`))
+      }
+      process.exit(1)
+    }
+  })
+
+program.parse()