@soulbatical/tetra-dev-toolkit 1.20.11 → 1.20.13

package/lib/checks/health/scanner.js

@@ -1,7 +1,7 @@
 /**
  * Project Health Scanner
  *
- * Orchestrates all 28 health checks and produces a HealthReport.
+ * Orchestrates all 29 health checks and produces a HealthReport.
  * This is the main entry point — consumers call scanProjectHealth().
  */
 
@@ -37,6 +37,7 @@ import { check as checkSecurityLayers } from './security-layers.js'
 import { check as checkSmokeReadiness } from './smoke-readiness.js'
 import { check as checkReleasePipeline } from './release-pipeline.js'
 import { check as checkTestStructure } from './test-structure.js'
+import { check as checkSentryMonitoring } from './sentry-monitoring.js'
 import { calculateHealthStatus } from './types.js'
 
 /**
@@ -82,7 +83,8 @@ export async function scanProjectHealth(projectPath, projectName, options = {})
     checkSecurityLayers(projectPath),
     checkSmokeReadiness(projectPath),
     checkReleasePipeline(projectPath),
-    checkTestStructure(projectPath)
+    checkTestStructure(projectPath),
+    checkSentryMonitoring(projectPath)
   ])
 
   const totalScore = checks.reduce((sum, c) => sum + c.score, 0)

package/lib/checks/health/sentry-monitoring.js

@@ -0,0 +1,167 @@
+/**
+ * Health Check: Sentry Error Monitoring
+ *
+ * Checks: @sentry/node in backend, @sentry/nextjs or @sentry/react in frontend,
+ * instrument.ts exists, SENTRY_DSN referenced via env var (not hardcoded).
+ * Score: 0-3 (backend setup, frontend setup, no hardcoded DSN)
+ */
+
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { createCheck } from './types.js'
+
+export async function check(projectPath) {
+  const result = createCheck('sentry-monitoring', 3, {
+    backend: { hasSentryDep: false, hasInstrumentFile: false, importedFirst: false },
+    frontend: { hasSentryDep: false, sentryPackage: null },
+    hardcodedDsn: false,
+    dsnFiles: []
+  })
+
+  // --- Check 1: Backend Sentry setup (0-1 point) ---
+  const backendPkgPath = join(projectPath, 'backend', 'package.json')
+  if (existsSync(backendPkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(backendPkgPath, 'utf-8'))
+      const allDeps = { ...pkg.dependencies, ...pkg.devDependencies }
+      if (allDeps['@sentry/node']) {
+        result.details.backend.hasSentryDep = true
+      }
+    } catch { /* ignore */ }
+
+    // Check instrument.ts or instrument.js
+    for (const ext of ['ts', 'js']) {
+      const instrumentPath = join(projectPath, 'backend', 'src', `instrument.${ext}`)
+      if (existsSync(instrumentPath)) {
+        result.details.backend.hasInstrumentFile = true
+
+        // Check if it's imported first in index.ts/index.js
+        for (const indexExt of ['ts', 'js']) {
+          const indexPath = join(projectPath, 'backend', 'src', `index.${indexExt}`)
+          if (existsSync(indexPath)) {
+            try {
+              const content = readFileSync(indexPath, 'utf-8')
+              const lines = content.split('\n').filter(l => l.trim() && !l.trim().startsWith('//') && !l.trim().startsWith('*') && !l.trim().startsWith('/**'))
+              const firstImport = lines.find(l => l.includes('import '))
+              if (firstImport && firstImport.includes('instrument')) {
+                result.details.backend.importedFirst = true
+              }
+            } catch { /* ignore */ }
+          }
+        }
+        break
+      }
+    }
+
+    if (result.details.backend.hasSentryDep && result.details.backend.hasInstrumentFile) {
+      result.score += 1
+    } else if (result.details.backend.hasSentryDep) {
+      result.score += 0.5
+    }
+  } else {
+    // No backend = skip this point, adjust maxScore
+    result.maxScore -= 1
+  }
+
+  // --- Check 2: Frontend Sentry setup (0-1 point) ---
+  let hasAnyFrontend = false
+  const frontendDirs = ['frontend']
+  // Check for multi-frontend setups
+  try {
+    const { readdirSync } = await import('fs')
+    for (const entry of readdirSync(projectPath)) {
+      if (entry.startsWith('frontend-') && existsSync(join(projectPath, entry, 'package.json'))) {
+        frontendDirs.push(entry)
+      }
+    }
+  } catch { /* ignore */ }
+
+  for (const feDir of frontendDirs) {
+    const fePkgPath = join(projectPath, feDir, 'package.json')
+    if (!existsSync(fePkgPath)) continue
+    hasAnyFrontend = true
+
+    try {
+      const pkg = JSON.parse(readFileSync(fePkgPath, 'utf-8'))
+      const allDeps = { ...pkg.dependencies, ...pkg.devDependencies }
+      if (allDeps['@sentry/nextjs']) {
+        result.details.frontend.hasSentryDep = true
+        result.details.frontend.sentryPackage = '@sentry/nextjs'
+      } else if (allDeps['@sentry/react']) {
+        result.details.frontend.hasSentryDep = true
+        result.details.frontend.sentryPackage = '@sentry/react'
+      }
+    } catch { /* ignore */ }
+  }
+
+  if (!hasAnyFrontend) {
+    result.maxScore -= 1
+  } else if (result.details.frontend.hasSentryDep) {
+    result.score += 1
+  }
+
+  // --- Check 3: No hardcoded DSN (0-1 point) ---
+  // Scan for hardcoded Sentry DSN patterns in src files
+  const DSN_PATTERN = /https:\/\/[a-f0-9]{32}@[a-z0-9.]+\.sentry\.io\/\d+/
+  const filesToCheck = []
+
+  function collectFiles(dir, depth = 0) {
+    if (depth > 3) return
+    const SKIP = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage'])
+    try {
+      const { readdirSync, statSync } = require('fs')
+      for (const entry of readdirSync(dir)) {
+        if (SKIP.has(entry)) continue
+        const full = join(dir, entry)
+        try {
+          const stat = statSync(full)
+          if (stat.isDirectory()) collectFiles(full, depth + 1)
+          else if (/\.(ts|js|tsx|jsx)$/.test(entry) && !entry.endsWith('.d.ts')) {
+            filesToCheck.push(full)
+          }
+        } catch { /* ignore */ }
+      }
+    } catch { /* ignore */ }
+  }
+
+  for (const dir of ['backend/src', 'frontend/src']) {
+    const fullDir = join(projectPath, dir)
+    if (existsSync(fullDir)) collectFiles(fullDir)
+  }
+
+  for (const file of filesToCheck) {
+    try {
+      const content = readFileSync(file, 'utf-8')
+      if (DSN_PATTERN.test(content)) {
+        result.details.hardcodedDsn = true
+        const relPath = file.replace(projectPath + '/', '')
+        result.details.dsnFiles.push(relPath)
+      }
+    } catch { /* ignore */ }
+  }
+
+  if (!result.details.hardcodedDsn) {
+    result.score += 1
+  } else {
+    result.status = 'warning'
+  }
+
+  // Finalize
+  result.score = Math.min(result.score, result.maxScore)
+
+  if (result.maxScore > 0 && result.score === 0) {
+    result.status = 'warning'
+    result.details.message = 'No Sentry error monitoring configured'
+  } else if (result.score < result.maxScore) {
+    result.status = 'warning'
+    const issues = []
+    if (!result.details.backend.hasSentryDep) issues.push('no @sentry/node in backend')
+    if (result.details.backend.hasSentryDep && !result.details.backend.hasInstrumentFile) issues.push('missing instrument.ts')
+    if (hasAnyFrontend && !result.details.frontend.hasSentryDep) issues.push('no Sentry in frontend')
+    if (result.details.hardcodedDsn) issues.push(`hardcoded DSN in ${result.details.dsnFiles.join(', ')}`)
+    if (!result.details.backend.importedFirst && result.details.backend.hasInstrumentFile) issues.push('instrument.ts not imported first')
+    result.details.message = issues.join(', ')
+  }
+
+  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'|'smoke-readiness'|'release-pipeline'} 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'|'release-pipeline'|'sentry-monitoring'} HealthCheckType
  *
  * @typedef {'ok'|'warning'|'error'} HealthStatus
  *

package/lib/checks/stability/ci-pipeline.js

@@ -53,16 +53,31 @@ export async function run(config, projectRoot) {
     results.passed = false
     results.findings.push({
       type: 'ci-missing',
-      severity: 'high',
-      message: 'No CI/CD configuration found',
-      fix: 'Add .github/workflows/ with CI configuration'
+      severity: 'critical',
+      message: 'No CI/CD configuration found — PRs have no quality gate',
+      fix: 'Run: tetra-setup ci'
     })
-    results.summary.high++
+    results.summary.critical++
     results.summary.total++
     return results
   }
 
-  // Check for essential CI steps
+  // Check if using Tetra reusable PR Quality Gate workflow
+  // If so, all essential checks are covered — skip individual pattern checks
+  const usesTetraQualityGate = ciContent.includes('pr-quality.yml')
+
+  if (usesTetraQualityGate) {
+    results.info = {
+      ciProvider: foundCi,
+      tetraQualityGate: true,
+      workflowCount: foundCi === 'GitHub Actions'
+        ? readdirSync(join(projectRoot, '.github/workflows')).filter(f => f.endsWith('.yml')).length
+        : 1
+    }
+    return results
+  }
+
+  // Check for essential CI steps (only when NOT using reusable workflow)
   const essentialChecks = [
     {
       name: 'install-dependencies',
@@ -109,7 +124,7 @@ export async function run(config, projectRoot) {
         type: `ci-missing-${name}`,
         severity,
         message: `CI pipeline missing: ${name}`,
-        fix: `Add ${name} step to your CI workflow`
+        fix: `Add ${name} step to your CI workflow, or use the Tetra reusable workflow: tetra-setup ci --force`
       })
       results.summary[severity]++
       results.summary.total++

package/lib/templates/hooks/doppler-guard.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+# doppler-guard.sh — PreToolUse hook
+# Blocks creating/editing .env files with secrets.
+# Installed by: tetra-setup hooks
+
+INPUT=$(cat)
+
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+if [[ "$TOOL_NAME" != "Edit" && "$TOOL_NAME" != "Write" ]]; then
+  exit 0
+fi
+
+[[ -z "$FILE_PATH" ]] && exit 0
+
+BASENAME=$(basename "$FILE_PATH")
+
+[[ "$BASENAME" != *".env"* ]] && exit 0
+
+# Allowed: .env.example, .env.local, frontend/.env
+[[ "$BASENAME" == ".env.example" ]] && exit 0
+[[ "$BASENAME" == ".env.local" ]] && exit 0
+[[ "$FILE_PATH" == *"frontend/.env" && "$BASENAME" == ".env" ]] && exit 0
+
+echo '{
+  "decision": "block",
+  "reason": "DOPPLER GUARD: .env files with secrets are NOT allowed.\n\nUse Doppler for secret management — no .env files on disk.\n\n- Add secrets: doppler secrets set KEY=value\n- Start server: doppler run -- npm run dev\n\nAllowed exceptions:\n  .env.example  (template)\n  .env.local    (machine-specific ports)\n  frontend/.env (public VITE_*/NEXT_PUBLIC_* keys)"
+}'
+exit 2

package/lib/templates/hooks/worktree-guard.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+# ╔══════════════════════════════════════════════════════════════════╗
+# ║  WORKTREE GUARD — Block concurrent edits on shared repos        ║
+# ║  Installed by: tetra-setup hooks                                ║
+# ║                                                                ║
+# ║  PreToolUse hook for Write/Edit/Bash                           ║
+# ║  Blocks file mutations when multiple Claude sessions work on   ║
+# ║  the same repo WITHOUT worktree isolation.                     ║
+# ╚══════════════════════════════════════════════════════════════════╝
+
+INPUT=$(cat)
+
+TOOL=$(echo "$INPUT" | node -e "try{const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));console.log(d.tool_name||'')}catch{}" 2>/dev/null)
+FILE_PATH=$(echo "$INPUT" | node -e "try{const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));const i=d.tool_input||{};console.log(i.file_path||i.command||'')}catch{}" 2>/dev/null)
+
+case "$TOOL" in
+  Write|Edit|MultiEdit|NotebookEdit) ;;
+  Bash)
+    case "$FILE_PATH" in
+      *git\ checkout*|*git\ restore*|*git\ reset*|*git\ stash*|*rm\ *|*mv\ *) ;;
+      *) exit 0 ;;
+    esac
+    ;;
+  *) exit 0 ;;
+esac
+
+case "$FILE_PATH" in
+  *@fix_plan.md*|*fix_plan.md*) exit 0 ;;
+esac
+
+# Temporary bypass — touch /tmp/worktree-guard-bypass-<PID>
+for bf in /tmp/worktree-guard-bypass-*; do
+  [ -f "$bf" ] && pid="${bf##*-}" && kill -0 "$pid" 2>/dev/null && exit 0
+done
+
+CWD=$(echo "$INPUT" | node -e "try{const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));console.log(d.cwd||'')}catch{}" 2>/dev/null)
+[ -z "$CWD" ] && CWD=$(pwd)
+
+GIT_DIR=$(cd "$CWD" && git rev-parse --git-dir 2>/dev/null)
+GIT_COMMON=$(cd "$CWD" && git rev-parse --git-common-dir 2>/dev/null)
+if [ -n "$GIT_DIR" ] && [ -n "$GIT_COMMON" ] && [ "$GIT_DIR" != "$GIT_COMMON" ]; then
+  exit 0
+fi
+[ -f "$CWD/.git" ] && exit 0
+
+MY_PID=$$
+REPO_PATH=$(cd "$CWD" && git rev-parse --show-toplevel 2>/dev/null)
+[ -z "$REPO_PATH" ] && exit 0
+
+CONCURRENT=0
+while IFS= read -r pid; do
+  [ -z "$pid" ] && continue
+  [ "$pid" = "$MY_PID" ] && continue
+  OTHER_CWD=$(lsof -p "$pid" 2>/dev/null | grep cwd | awk '{print $NF}')
+  [ -z "$OTHER_CWD" ] && continue
+  OTHER_REPO=$(cd "$OTHER_CWD" 2>/dev/null && git rev-parse --show-toplevel 2>/dev/null)
+  if [ "$OTHER_REPO" = "$REPO_PATH" ]; then
+    OTHER_GIT_DIR=$(cd "$OTHER_CWD" 2>/dev/null && git rev-parse --git-dir 2>/dev/null)
+    OTHER_GIT_COMMON=$(cd "$OTHER_CWD" 2>/dev/null && git rev-parse --git-common-dir 2>/dev/null)
+    [ "$OTHER_GIT_DIR" = "$OTHER_GIT_COMMON" ] && CONCURRENT=$((CONCURRENT + 1))
+  fi
+done < <(pgrep -f "claude" 2>/dev/null)
+
+if [ "$CONCURRENT" -gt 0 ]; then
+  REPO_NAME=$(basename "$REPO_PATH")
+  cat <<EOF
+{
+  "decision": "block",
+  "reason": "WORKTREE GUARD: ${CONCURRENT} other Claude session(s) working on ${REPO_NAME} without worktree isolation. Use 'claude -w <name>' or Agent tool with isolation: 'worktree' to prevent file conflicts."
+}
+EOF
+  exit 2
+fi
+
+exit 0

package/lib/templates/tests/02-crud-resources.test.ts.tmpl

@@ -0,0 +1,135 @@
+/**
+ * CRUD E2E tests — auto-generated from FeatureConfigs.
+ * Tetra golden standard — tests list, create, read, update, delete for each resource.
+ *
+ * CUSTOMIZE: Add your project's resources to allConfigs below.
+ * Use the testing section from each FeatureConfig as a guide.
+ */
+import { describe, it, expect, beforeAll } from 'vitest';
+import { get, post, put, patch, del } from './helpers/api-client';
+import { getTestContext, type TestContext } from './helpers/test-users';
+
+let ctx: TestContext;
+
+beforeAll(async () => {
+  ctx = await getTestContext();
+}, 60000);
+
+/* ---------- helpers ---------- */
+
+function resolveBody(body: Record<string, unknown>): Record<string, unknown> {
+  const ts = Date.now();
+  const resolved: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(body)) {
+    resolved[k] = typeof v === 'string' ? v.replace('$timestamp', String(ts)) : v;
+  }
+  return resolved;
+}
+
+/* ---------- resource configs ---------- */
+// CUSTOMIZE: Add entries for each FeatureConfig in your project.
+// Set skip* flags for resources that don't support direct CRUD (system-created, etc.)
+
+interface CrudConfig {
+  name: string;
+  restBasePath: string;
+  createBody: Record<string, unknown>;
+  updateBody?: Record<string, unknown>;
+  updateMethod?: 'PATCH' | 'PUT';
+  requiredFields?: string[];
+  skipCreate?: boolean;
+  skipUpdate?: boolean;
+  skipDelete?: boolean;
+  skipList?: boolean;
+  skipSingle?: boolean;
+}
+
+const allConfigs: CrudConfig[] = [
+  // TODO: Add your project's resources here
+  // Example:
+  // {
+  //   name: 'projects',
+  //   restBasePath: '/api/projects',
+  //   createBody: { name: 'E2E Project $timestamp' },
+  //   updateBody: { name: 'E2E Project Updated $timestamp' },
+  //   updateMethod: 'PATCH',
+  //   requiredFields: ['name'],
+  // },
+];
+
+/* ---------- tests ---------- */
+
+for (const cfg of allConfigs) {
+  describe(`CRUD: ${cfg.name}`, () => {
+    let createdId: string | undefined;
+
+    // LIST
+    if (!cfg.skipList) {
+      it(`GET ${cfg.restBasePath} returns data`, async () => {
+        const res = await get<any>(cfg.restBasePath, ctx.admin.token);
+        expect(res.status).toBe(200);
+        const body = res.data;
+        const items = Array.isArray(body) ? body
+          : body?.data && Array.isArray(body.data) ? body.data
+          : typeof body === 'object' ? body : null;
+        expect(items !== null).toBe(true);
+      });
+    }
+
+    // CREATE
+    if (!cfg.skipCreate) {
+      it(`POST ${cfg.restBasePath} creates resource`, async () => {
+        const body = resolveBody(cfg.createBody);
+        const res = await post<any>(cfg.restBasePath, body, ctx.admin.token);
+        expect([200, 201]).toContain(res.status);
+        createdId = res.data?.data?.id || res.data?.id;
+        expect(createdId).toBeTruthy();
+      });
+
+      // READ single
+      if (!cfg.skipSingle) {
+        it(`GET ${cfg.restBasePath}/:id reads resource`, async () => {
+          if (!createdId) return;
+          const res = await get<any>(`${cfg.restBasePath}/${createdId}`, ctx.admin.token);
+          expect(res.status).toBe(200);
+        });
+      }
+    }
+
+    // UPDATE
+    if (!cfg.skipCreate && !cfg.skipUpdate && cfg.updateBody) {
+      it(`${cfg.updateMethod || 'PATCH'} ${cfg.restBasePath}/:id updates`, async () => {
+        if (!createdId) return;
+        const body = resolveBody(cfg.updateBody!);
+        const method = cfg.updateMethod || 'PATCH';
+        const res = method === 'PUT'
+          ? await put<any>(`${cfg.restBasePath}/${createdId}`, body, ctx.admin.token)
+          : await patch<any>(`${cfg.restBasePath}/${createdId}`, body, ctx.admin.token);
+        expect(res.status).toBe(200);
+      });
+    }
+
+    // DELETE
+    if (!cfg.skipCreate && !cfg.skipDelete) {
+      it(`DELETE ${cfg.restBasePath}/:id removes resource`, async () => {
+        if (!createdId) return;
+        const res = await del<any>(`${cfg.restBasePath}/${createdId}`, ctx.admin.token);
+        expect([200, 204]).toContain(res.status);
+      });
+
+      it(`GET ${cfg.restBasePath}/:id returns 404 or empty after delete`, async () => {
+        if (!createdId) return;
+        const res = await get<any>(`${cfg.restBasePath}/${createdId}`, ctx.admin.token);
+        expect([200, 404]).toContain(res.status);
+      });
+    }
+
+    // REQUIRED FIELDS
+    if (!cfg.skipCreate && cfg.requiredFields?.length) {
+      it(`POST ${cfg.restBasePath} rejects empty body`, async () => {
+        const res = await post<any>(cfg.restBasePath, {}, ctx.admin.token);
+        expect([400, 422]).toContain(res.status);
+      });
+    }
+  });
+}

package/lib/templates/tests/03-permissions.test.ts.tmpl

@@ -0,0 +1,110 @@
+/**
+ * Permissions E2E tests — auth walls, role access, public routes.
+ * Tetra golden standard — verifies every protected route requires auth.
+ *
+ * CUSTOMIZE: Update protectedRoutes with ALL your admin/user API endpoints.
+ * Use tetra-test-audit to find routes missing from this list.
+ */
+import { describe, it, expect, beforeAll } from 'vitest';
+import { get, post, api } from './helpers/api-client';
+import { getTestContext, type TestContext } from './helpers/test-users';
+
+let ctx: TestContext;
+
+beforeAll(async () => {
+  ctx = await getTestContext();
+}, 60000);
+
+/* ---------- Protected routes require auth ---------- */
+// CUSTOMIZE: Add ALL protected API routes here.
+// Run tetra-test-audit to find any you missed.
+
+const protectedRoutes: string[] = [
+  // TODO: Add your project's protected routes
+  // '/api/admin/users',
+  // '/api/admin/projects',
+];
+
+describe('Permissions: Protected routes require auth', () => {
+  for (const route of protectedRoutes) {
+    it(`GET ${route} returns 401 without token`, async () => {
+      const res = await get(route);
+      expect(res.status).toBe(401);
+    });
+  }
+});
+
+/* ---------- Admin can access protected routes ---------- */
+
+describe('Permissions: Admin can access protected routes', () => {
+  for (const route of protectedRoutes) {
+    it(`GET ${route} returns 200 for admin`, async () => {
+      const res = await get(route, ctx.admin.token);
+      expect(res.status).toBe(200);
+    });
+  }
+});
+
+/* ---------- Superadmin routes forbidden for regular admin ---------- */
+// CUSTOMIZE: Add superadmin-only routes
+
+const superadminRoutes: string[] = [
+  // '/api/superadmin/organizations',
+];
+
+describe('Permissions: Admin cannot access superadmin routes', () => {
+  for (const route of superadminRoutes) {
+    it(`GET ${route} returns 401 or 403 for admin`, async () => {
+      const res = await get(route, ctx.admin.token);
+      expect([401, 403]).toContain(res.status);
+    });
+  }
+});
+
+/* ---------- Public routes accessible without auth ---------- */
+
+describe('Permissions: Public routes accessible without auth', () => {
+  it('GET /api/health is public', async () => {
+    const res = await get('/api/health');
+    expect(res.status).toBe(200);
+  });
+
+  it('POST /api/public/auth/login is public (rejects missing fields)', async () => {
+    const res = await post('/api/public/auth/login', {});
+    expect([400, 401, 422]).toContain(res.status);
+  });
+});
+
+/* ---------- Invalid tokens ---------- */
+
+describe('Permissions: Invalid tokens rejected', () => {
+  it('rejects malformed JWT', async () => {
+    const firstRoute = protectedRoutes[0] || '/api/health';
+    const res = await get(firstRoute, 'eyJhbGciOiJIUzI1NiJ9.fake.fake');
+    expect(res.status).toBe(401);
+  });
+
+  it('rejects empty Authorization header', async () => {
+    const firstRoute = protectedRoutes[0] || '/api/health';
+    const res = await api(firstRoute, { headers: { 'Authorization': '' } });
+    expect(res.status).toBe(401);
+  });
+
+  it('rejects Bearer with no token', async () => {
+    const firstRoute = protectedRoutes[0] || '/api/health';
+    const res = await api(firstRoute, { headers: { 'Authorization': 'Bearer ' } });
+    expect(res.status).toBe(401);
+  });
+});
+
+/* ---------- RFC 7807 error format ---------- */
+
+describe('Permissions: RFC 7807 error format', () => {
+  it('401 returns structured error', async () => {
+    const firstRoute = protectedRoutes[0] || '/api/health';
+    const res = await get<any>(firstRoute);
+    if (res.status === 401) {
+      expect(res.data.type || res.data.error || res.data.message).toBeTruthy();
+    }
+  });
+});

package/lib/templates/tests/04-business-flows.test.ts.tmpl

@@ -0,0 +1,64 @@
+/**
+ * Business flows E2E tests — end-to-end user journeys.
+ * Tetra golden standard — tests complete workflows, not just CRUD.
+ *
+ * CUSTOMIZE: Replace with your project's actual business flows.
+ * Each describe block should test a complete user journey.
+ */
+import { describe, it, expect, beforeAll } from 'vitest';
+import { get, post, put, patch, del } from './helpers/api-client';
+import { getTestContext, type TestContext } from './helpers/test-users';
+
+let ctx: TestContext;
+
+beforeAll(async () => {
+  ctx = await getTestContext();
+}, 60000);
+
+/* ---------- Flow 1: Main resource lifecycle ---------- */
+// CUSTOMIZE: Replace with your primary resource flow
+
+describe('Flow: Resource lifecycle (create → update → delete)', () => {
+  let resourceId: string;
+
+  it('creates a resource', async () => {
+    // TODO: POST to your main resource endpoint
+    // const res = await post<any>('/api/resources', { name: `E2E ${Date.now()}` }, ctx.admin.token);
+    // expect([200, 201]).toContain(res.status);
+    // resourceId = res.data?.data?.id || res.data?.id;
+    // expect(resourceId).toBeTruthy();
+  });
+
+  it('reads the resource', async () => {
+    if (!resourceId) return;
+    // const res = await get<any>(`/api/resources/${resourceId}`, ctx.admin.token);
+    // expect(res.status).toBe(200);
+  });
+
+  it('updates the resource', async () => {
+    if (!resourceId) return;
+    // const res = await patch<any>(`/api/resources/${resourceId}`, { name: 'Updated' }, ctx.admin.token);
+    // expect(res.status).toBe(200);
+  });
+
+  it('deletes the resource', async () => {
+    if (!resourceId) return;
+    // const res = await del<any>(`/api/resources/${resourceId}`, ctx.admin.token);
+    // expect([200, 204]).toContain(res.status);
+  });
+
+  it('confirms resource is gone', async () => {
+    if (!resourceId) return;
+    // const res = await get<any>(`/api/resources/${resourceId}`, ctx.admin.token);
+    // expect([200, 404]).toContain(res.status);
+  });
+});
+
+/* ---------- Edge cases ---------- */
+
+describe('Flow: Edge cases', () => {
+  it('nonexistent resource returns 404 or empty', async () => {
+    // const res = await get<any>('/api/resources/00000000-0000-0000-0000-000000000000', ctx.admin.token);
+    // expect([200, 404]).toContain(res.status);
+  });
+});