@soulbatical/tetra-dev-toolkit 1.20.16 → 1.20.18

package/bin/tetra-doctor.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+
+/**
+ * Tetra Doctor — checks a project for common Tetra integration issues.
+ *
+ * Scans layout.tsx, providers.tsx, globals.css, package.json, app-config.tsx
+ * to find missing or outdated Tetra setup before they become runtime bugs.
+ *
+ * Usage:
+ *   tetra-doctor                    # Check current project
+ *   tetra-doctor --path /path       # Check specific project
+ *   tetra-doctor --json             # JSON output for CI
+ *   tetra-doctor --fix              # Auto-fix safe issues
+ *   tetra-doctor --ci               # GitHub Actions annotations
+ *
+ * Exit codes:
+ *   0 = all critical checks pass
+ *   1 = one or more critical checks fail
+ */
+
+import { program } from 'commander'
+import chalk from 'chalk'
+import { readFileSync, existsSync } from 'fs'
+import { join } from 'path'
+import {
+  runDoctorAudit,
+  applyFixes,
+  formatDoctorReport,
+  formatDoctorReportJSON,
+  formatDoctorCIAnnotations,
+} from '../lib/audits/doctor-audit.js'
+
+/**
+ * Re-read the files that are subject to auto-fix, so applyFixes has
+ * fresh content after a potential prior fix in the same session.
+ */
+function readFixableFiles(projectRoot, report) {
+  function tryRead(relativePath) {
+    if (!relativePath) return null
+    const fullPath = join(projectRoot, relativePath)
+    if (!existsSync(fullPath)) return null
+    return { path: relativePath, content: readFileSync(fullPath, 'utf-8') }
+  }
+
+  return {
+    layout: tryRead(report.files.layout),
+    globalsCss: tryRead(report.files.globalsCss),
+  }
+}
+
+program
+  .name('tetra-doctor')
+  .description('Check a Tetra project for integration issues (versions, layout, CSS tokens, etc.)')
+  .version('1.0.0')
+  .option('--path <dir>', 'Project root directory (default: cwd)')
+  .option('--json', 'JSON output')
+  .option('--fix', 'Auto-fix safe issues (suppressHydrationWarning, dark-mode.css)')
+  .option('--ci', 'GitHub Actions annotations for failures')
+  .action(async (options) => {
+    try {
+      const projectRoot = options.path || process.cwd()
+
+      if (!options.json) {
+        console.log(chalk.gray('\n  Running checks...'))
+      }
+
+      let report = await runDoctorAudit(projectRoot)
+
+      // Apply fixes if requested
+      if (options.fix && !options.json) {
+        const fixableChecks = report.checks.filter(c => !c.pass && c.fixable)
+        if (fixableChecks.length === 0) {
+          console.log(chalk.gray('  Nothing to auto-fix.\n'))
+        } else {
+          const fixableFiles = readFixableFiles(projectRoot, report)
+          const fixes = applyFixes(projectRoot, report.checks, fixableFiles)
+
+          for (const fix of fixes) {
+            if (fix.success) {
+              console.log(chalk.green(`  Fixed: ${fix.fix} in ${fix.file}`))
+            } else {
+              console.log(chalk.red(`  Failed to fix ${fix.fix}: ${fix.error}`))
+            }
+          }
+          console.log('')
+
+          // Re-run after fixes to show updated state
+          report = await runDoctorAudit(projectRoot)
+        }
+      }
+
+      // Output
+      if (options.json) {
+        console.log(formatDoctorReportJSON(report))
+      } else {
+        console.log(formatDoctorReport(report, chalk, projectRoot))
+
+        if (options.ci) {
+          const annotations = formatDoctorCIAnnotations(report)
+          if (annotations) {
+            console.log(annotations)
+          }
+        }
+      }
+
+      // Exit code: fail only on critical checks
+      process.exit(report.summary.criticalFailed > 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()

package/lib/audits/doctor-audit.js

@@ -0,0 +1,905 @@
+/**
+ * Tetra Doctor Audit — checks a project for common Tetra integration issues.
+ *
+ * Scans layout.tsx, providers.tsx, globals.css, package.json, app-config.tsx
+ * to find missing or outdated Tetra setup.
+ *
+ * Checks are grouped by severity:
+ *   CRITICAL — blocks CI (exit 1)
+ *   HIGH     — warnings
+ *   INFO     — suggestions
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs'
+import { join } from 'path'
+import { execSync } from 'child_process'
+import { glob } from 'glob'
+
+// ============================================================================
+// FILE RESOLUTION
+// ============================================================================
+
+/**
+ * Find a file by trying multiple candidate paths.
+ * Returns { path, content } or null if not found.
+ */
+function findFile(projectRoot, candidates) {
+  for (const candidate of candidates) {
+    const fullPath = join(projectRoot, candidate)
+    if (existsSync(fullPath)) {
+      return { path: candidate, content: readFileSync(fullPath, 'utf-8') }
+    }
+  }
+  return null
+}
+
+function resolveFiles(projectRoot) {
+  return {
+    layout: findFile(projectRoot, [
+      'frontend/src/app/layout.tsx',
+      'src/app/layout.tsx',
+      'app/layout.tsx',
+    ]),
+    providers: findFile(projectRoot, [
+      'frontend/src/app/providers.tsx',
+      'src/app/providers.tsx',
+      'app/providers.tsx',
+    ]),
+    globalsCss: findFile(projectRoot, [
+      'frontend/src/app/globals.css',
+      'src/app/globals.css',
+      'app/globals.css',
+    ]),
+    appConfig: findFile(projectRoot, [
+      'frontend/src/lib/app-config.tsx',
+      'src/lib/app-config.tsx',
+      'lib/app-config.tsx',
+      'frontend/src/lib/app-config.ts',
+      'src/lib/app-config.ts',
+    ]),
+    frontendPackageJson: findFile(projectRoot, [
+      'frontend/package.json',
+      'package.json',
+    ]),
+    backendPackageJson: findFile(projectRoot, [
+      'backend/package.json',
+    ]),
+  }
+}
+
+// ============================================================================
+// NPM VERSION CACHE
+// ============================================================================
+
+const VERSION_CACHE_FILE = '/tmp/tetra-doctor-version-cache.json'
+const CACHE_TTL_MS = 60 * 60 * 1000 // 1 hour
+
+function readVersionCache() {
+  try {
+    if (existsSync(VERSION_CACHE_FILE)) {
+      const raw = readFileSync(VERSION_CACHE_FILE, 'utf-8')
+      const cache = JSON.parse(raw)
+      if (Date.now() - cache.timestamp < CACHE_TTL_MS) {
+        return cache.versions || {}
+      }
+    }
+  } catch {
+    // ignore
+  }
+  return null
+}
+
+function writeVersionCache(versions) {
+  try {
+    writeFileSync(VERSION_CACHE_FILE, JSON.stringify({ timestamp: Date.now(), versions }))
+  } catch {
+    // ignore cache write failures
+  }
+}
+
+function getNpmLatestVersion(packageName) {
+  const cached = readVersionCache()
+  if (cached && cached[packageName]) {
+    return cached[packageName]
+  }
+
+  try {
+    const version = execSync(`npm view ${packageName} version 2>/dev/null`, {
+      timeout: 10000,
+      encoding: 'utf-8',
+    }).trim()
+
+    if (version) {
+      const newCache = { ...(cached || {}), [packageName]: version }
+      writeVersionCache(newCache)
+    }
+
+    return version || null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Parse semver string into [major, minor, patch].
+ */
+function parseSemver(version) {
+  if (!version) return [0, 0, 0]
+  const clean = version.replace(/^[^0-9]*/, '')
+  const parts = clean.split('.').map(p => parseInt(p, 10) || 0)
+  return [parts[0] || 0, parts[1] || 0, parts[2] || 0]
+}
+
+/**
+ * Returns true if installed is at least the same major+minor as latest.
+ */
+function isVersionRecent(installed, latest) {
+  const [iMaj, iMin] = parseSemver(installed)
+  const [lMaj, lMin] = parseSemver(latest)
+  if (iMaj !== lMaj) return iMaj > lMaj
+  return iMin >= lMin
+}
+
+/**
+ * Extract installed version of a package from a package.json content string.
+ */
+function getInstalledVersion(packageJsonContent, packageName) {
+  if (!packageJsonContent) return null
+  try {
+    const pkg = JSON.parse(packageJsonContent)
+    const deps = {
+      ...(pkg.dependencies || {}),
+      ...(pkg.devDependencies || {}),
+    }
+    const raw = deps[packageName]
+    if (!raw) return null
+    return raw.replace(/^[^0-9]*/, '')
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Check if a package exists in node_modules.
+ */
+function isInNodeModules(projectRoot, packageName) {
+  const candidates = [
+    join(projectRoot, 'frontend/node_modules', packageName, 'package.json'),
+    join(projectRoot, 'node_modules', packageName, 'package.json'),
+  ]
+  return candidates.some(p => existsSync(p))
+}
+
+function getNodeModulesVersion(projectRoot, packageName) {
+  const candidates = [
+    join(projectRoot, 'frontend/node_modules', packageName, 'package.json'),
+    join(projectRoot, 'node_modules', packageName, 'package.json'),
+  ]
+  for (const p of candidates) {
+    if (existsSync(p)) {
+      try {
+        return JSON.parse(readFileSync(p, 'utf-8')).version || null
+      } catch { /* ignore */ }
+    }
+  }
+  return null
+}
+
+// ============================================================================
+// INDIVIDUAL CHECKS
+// ============================================================================
+
+/**
+ * CRITICAL 1: layout.tsx <html> must have suppressHydrationWarning.
+ */
+function checkSuppressHydrationWarning(files) {
+  if (!files.layout) {
+    return {
+      id: 'suppressHydrationWarning',
+      severity: 'critical',
+      label: 'suppressHydrationWarning',
+      pass: false,
+      detail: 'layout.tsx not found',
+      fixable: false,
+    }
+  }
+
+  // If TetraRootLayout is used, it provides suppressHydrationWarning implicitly
+  if (/TetraRootLayout/.test(files.layout.content)) {
+    return {
+      id: 'suppressHydrationWarning',
+      severity: 'critical',
+      label: 'suppressHydrationWarning',
+      pass: true,
+      detail: `provided by TetraRootLayout in ${files.layout.path}`,
+      fixable: false,
+    }
+  }
+
+  const hasHtmlTag = /<html[\s>]/.test(files.layout.content)
+  if (!hasHtmlTag) {
+    return {
+      id: 'suppressHydrationWarning',
+      severity: 'critical',
+      label: 'suppressHydrationWarning',
+      pass: false,
+      detail: `no <html> tag found in ${files.layout.path}`,
+      fixable: false,
+    }
+  }
+
+  const hasSuppressWarning = /<html[^>]*suppressHydrationWarning/.test(files.layout.content)
+  return {
+    id: 'suppressHydrationWarning',
+    severity: 'critical',
+    label: 'suppressHydrationWarning',
+    pass: hasSuppressWarning,
+    detail: hasSuppressWarning
+      ? `present in ${files.layout.path}`
+      : `missing on <html> tag in ${files.layout.path}`,
+    fixable: !hasSuppressWarning,
+    fixFile: files.layout.path,
+  }
+}
+
+/**
+ * CRITICAL 2: ThemeProvider must be imported from tetra-ui in providers.tsx or layout.tsx.
+ */
+function checkThemeProvider(files) {
+  const searchFiles = [files.providers, files.layout].filter(Boolean)
+
+  for (const file of searchFiles) {
+    // TetraRootLayout includes ThemeProvider
+    if (/TetraRootLayout/.test(file.content)) {
+      return {
+        id: 'themeProvider',
+        severity: 'critical',
+        label: 'ThemeProvider',
+        pass: true,
+        detail: `provided by TetraRootLayout in ${file.path}`,
+        fixable: false,
+      }
+    }
+
+    const importsFromTetraUi = /from ['"]@soulbatical\/tetra-ui['"]/.test(file.content) ||
+      /from ['"]@soulbatical\/tetra-ui\//.test(file.content)
+    const mentionsThemeProvider = /ThemeProvider/.test(file.content)
+
+    if (importsFromTetraUi && mentionsThemeProvider) {
+      return {
+        id: 'themeProvider',
+        severity: 'critical',
+        label: 'ThemeProvider',
+        pass: true,
+        detail: `imported in ${file.path}`,
+        fixable: false,
+      }
+    }
+  }
+
+  return {
+    id: 'themeProvider',
+    severity: 'critical',
+    label: 'ThemeProvider',
+    pass: false,
+    detail: 'not found in providers.tsx or layout.tsx',
+    fixable: false,
+  }
+}
+
+/**
+ * CRITICAL 3: tetra-ui version must be >= latest minor.
+ */
+function checkTetraUiVersion(files) {
+  const pkgContent = files.frontendPackageJson?.content
+  const installed = getInstalledVersion(pkgContent, '@soulbatical/tetra-ui')
+
+  if (!installed) {
+    return {
+      id: 'tetraUiVersion',
+      severity: 'critical',
+      label: 'tetra-ui version',
+      pass: false,
+      detail: '@soulbatical/tetra-ui not found in package.json',
+      fixable: false,
+    }
+  }
+
+  const latest = getNpmLatestVersion('@soulbatical/tetra-ui')
+  if (!latest) {
+    return {
+      id: 'tetraUiVersion',
+      severity: 'critical',
+      label: 'tetra-ui version',
+      pass: true,
+      detail: `${installed} installed (npm registry unreachable)`,
+      fixable: false,
+    }
+  }
+
+  const isRecent = isVersionRecent(installed, latest)
+  return {
+    id: 'tetraUiVersion',
+    severity: 'critical',
+    label: 'tetra-ui version',
+    pass: isRecent,
+    detail: isRecent
+      ? `${installed} installed (latest: ${latest})`
+      : `${installed} installed, ${latest} available`,
+    fixable: false,
+    installed,
+    latest,
+  }
+}
+
+/**
+ * CRITICAL 4: next-themes must be in node_modules.
+ */
+function checkNextThemes(projectRoot) {
+  const installed = isInNodeModules(projectRoot, 'next-themes')
+  const version = installed ? getNodeModulesVersion(projectRoot, 'next-themes') : null
+
+  return {
+    id: 'nextThemes',
+    severity: 'critical',
+    label: 'next-themes',
+    pass: installed,
+    detail: installed
+      ? `${version || 'unknown version'} installed`
+      : 'not found in node_modules (required peerDep of tetra-ui)',
+    fixable: false,
+  }
+}
+
+/**
+ * CRITICAL 5: globals.css must import tokens.css.
+ */
+function checkCssTokens(files) {
+  if (!files.globalsCss) {
+    return {
+      id: 'cssTokens',
+      severity: 'critical',
+      label: 'CSS tokens',
+      pass: false,
+      detail: 'globals.css not found',
+      fixable: false,
+    }
+  }
+
+  const hasTokens =
+    /tetra-ui.*tokens\.css/.test(files.globalsCss.content) ||
+    /@import.*tokens\.css/.test(files.globalsCss.content)
+
+  return {
+    id: 'cssTokens',
+    severity: 'critical',
+    label: 'CSS tokens',
+    pass: hasTokens,
+    detail: hasTokens
+      ? `tokens.css imported in ${files.globalsCss.path}`
+      : `tokens.css not imported in ${files.globalsCss.path}`,
+    fixable: false,
+  }
+}
+
+/**
+ * CRITICAL 6: globals.css must import dark-mode.css OR define @custom-variant dark.
+ */
+function checkDarkMode(files) {
+  if (!files.globalsCss) {
+    return {
+      id: 'darkMode',
+      severity: 'critical',
+      label: 'Dark mode',
+      pass: false,
+      detail: 'globals.css not found',
+      fixable: false,
+    }
+  }
+
+  const hasDarkModeCss =
+    /tetra-ui.*dark-mode\.css/.test(files.globalsCss.content) ||
+    /@import.*dark-mode\.css/.test(files.globalsCss.content)
+  const hasCustomVariant = /@custom-variant\s+dark/.test(files.globalsCss.content)
+  const pass = hasDarkModeCss || hasCustomVariant
+
+  return {
+    id: 'darkMode',
+    severity: 'critical',
+    label: 'Dark mode',
+    pass,
+    detail: pass
+      ? hasDarkModeCss
+        ? `dark-mode.css imported in ${files.globalsCss.path}`
+        : `@custom-variant dark found in ${files.globalsCss.path}`
+      : `dark-mode.css not imported and no @custom-variant dark in ${files.globalsCss.path}`,
+    fixable: !pass,
+    fixFile: files.globalsCss?.path,
+  }
+}
+
+/**
+ * HIGH 7: tetra-core version should be recent.
+ */
+function checkTetraCoreVersion(files) {
+  const pkgContent = files.backendPackageJson?.content
+  const installed = getInstalledVersion(pkgContent, '@soulbatical/tetra-core')
+
+  if (!installed) {
+    return {
+      id: 'tetraCoreVersion',
+      severity: 'high',
+      label: 'tetra-core version',
+      pass: true,
+      detail: 'backend/package.json not found or tetra-core not used',
+      fixable: false,
+    }
+  }
+
+  const latest = getNpmLatestVersion('@soulbatical/tetra-core')
+  if (!latest) {
+    return {
+      id: 'tetraCoreVersion',
+      severity: 'high',
+      label: 'tetra-core version',
+      pass: true,
+      detail: `${installed} installed (npm registry unreachable)`,
+      fixable: false,
+    }
+  }
+
+  const isRecent = isVersionRecent(installed, latest)
+  return {
+    id: 'tetraCoreVersion',
+    severity: 'high',
+    label: 'tetra-core version',
+    pass: isRecent,
+    detail: isRecent
+      ? `${installed} (latest: ${latest})`
+      : `${installed} installed, ${latest} available`,
+    fixable: false,
+    installed,
+    latest,
+  }
+}
+
+/**
+ * HIGH 8: dashboard layout should use AppShell from tetra-ui.
+ */
+async function checkAppShellUsage(projectRoot) {
+  const knownCandidates = [
+    'frontend/src/app/(dashboard)/layout.tsx',
+    'src/app/(dashboard)/layout.tsx',
+    'frontend/src/app/(admin)/layout.tsx',
+    'src/app/(admin)/layout.tsx',
+  ]
+
+  for (const candidate of knownCandidates) {
+    const fullPath = join(projectRoot, candidate)
+    if (existsSync(fullPath)) {
+      const content = readFileSync(fullPath, 'utf-8')
+      const usesAppShell = /AppShell/.test(content)
+      return {
+        id: 'appShellUsage',
+        severity: 'high',
+        label: 'AppShell usage',
+        pass: usesAppShell,
+        detail: usesAppShell
+          ? `found in ${candidate}`
+          : `${candidate} exists but does not use AppShell`,
+        fixable: false,
+      }
+    }
+  }
+
+  // Fallback: scan all layout files for one that looks like a dashboard layout
+  try {
+    const layoutFiles = await glob('**/layout.tsx', {
+      cwd: projectRoot,
+      ignore: ['**/node_modules/**'],
+    })
+    const dashboardLayout = layoutFiles.find(f =>
+      f.includes('dashboard') || f.includes('admin')
+    )
+    if (dashboardLayout) {
+      const content = readFileSync(join(projectRoot, dashboardLayout), 'utf-8')
+      const usesAppShell = /AppShell/.test(content)
+      return {
+        id: 'appShellUsage',
+        severity: 'high',
+        label: 'AppShell usage',
+        pass: usesAppShell,
+        detail: usesAppShell
+          ? `found in ${dashboardLayout}`
+          : `${dashboardLayout} does not use AppShell`,
+        fixable: false,
+      }
+    }
+  } catch { /* ignore glob failures */ }
+
+  return {
+    id: 'appShellUsage',
+    severity: 'high',
+    label: 'AppShell usage',
+    pass: true,
+    detail: 'no dashboard/admin layout found',
+    fixable: false,
+  }
+}
+
+/**
+ * HIGH 9: app-config.tsx must exist with TetraAppConfig.
+ */
+function checkAppConfig(files) {
+  if (!files.appConfig) {
+    return {
+      id: 'appConfig',
+      severity: 'high',
+      label: 'app-config.tsx',
+      pass: false,
+      detail: 'app-config.tsx not found in frontend/src/lib/',
+      fixable: false,
+    }
+  }
+
+  const hasTetraAppConfig = /TetraAppConfig/.test(files.appConfig.content)
+  return {
+    id: 'appConfig',
+    severity: 'high',
+    label: 'app-config.tsx',
+    pass: hasTetraAppConfig,
+    detail: hasTetraAppConfig
+      ? `TetraAppConfig found in ${files.appConfig.path}`
+      : `${files.appConfig.path} exists but does not use TetraAppConfig`,
+    fixable: false,
+  }
+}
+
+/**
+ * HIGH 10: nav items should have shortcuts property.
+ */
+function checkKeyboardShortcuts(files) {
+  if (!files.appConfig) {
+    return {
+      id: 'keyboardShortcuts',
+      severity: 'high',
+      label: 'Keyboard shortcuts',
+      pass: true,
+      detail: 'app-config.tsx not found, skipping',
+      fixable: false,
+    }
+  }
+
+  const content = files.appConfig.content
+  const navItemMatches = content.match(/href\s*:/g) || []
+  const shortcutMatches = content.match(/shortcut\s*:/g) || []
+
+  const total = navItemMatches.length
+  const withShortcuts = shortcutMatches.length
+  const missing = total - withShortcuts
+
+  if (total === 0) {
+    return {
+      id: 'keyboardShortcuts',
+      severity: 'high',
+      label: 'Keyboard shortcuts',
+      pass: true,
+      detail: 'no nav items found in app-config.tsx',
+      fixable: false,
+    }
+  }
+
+  const pass = missing === 0
+  return {
+    id: 'keyboardShortcuts',
+    severity: 'high',
+    label: 'Keyboard shortcuts',
+    pass,
+    detail: pass
+      ? `all ${total} nav items have shortcuts`
+      : `${withShortcuts}/${total} nav items have shortcuts (${missing} missing)`,
+    fixable: false,
+    navTotal: total,
+    navWithShortcuts: withShortcuts,
+  }
+}
+
+/**
+ * INFO 11: Suggest TetraRootLayout if layout.tsx is manually built.
+ */
+function checkTetraRootLayoutAdoption(files) {
+  if (!files.layout) {
+    return {
+      id: 'tetraRootLayout',
+      severity: 'info',
+      label: 'TetraRootLayout',
+      pass: true,
+      detail: 'layout.tsx not found',
+      suggestion: null,
+    }
+  }
+
+  const usesTetraRootLayout = /TetraRootLayout/.test(files.layout.content)
+  const hasManualHtml = /<html[\s>]/.test(files.layout.content)
+
+  return {
+    id: 'tetraRootLayout',
+    severity: 'info',
+    label: 'TetraRootLayout',
+    pass: usesTetraRootLayout,
+    detail: usesTetraRootLayout
+      ? `TetraRootLayout used in ${files.layout.path}`
+      : null,
+    suggestion: !usesTetraRootLayout && hasManualHtml
+      ? 'Consider using TetraRootLayout instead of manual layout.tsx (guarantees suppressHydrationWarning + ThemeProvider)'
+      : null,
+  }
+}
+
+/**
+ * INFO 12: Count pages using FeaturePage vs ad-hoc.
+ */
+async function checkFeaturePageAdoption(projectRoot) {
+  let pageFiles = []
+  try {
+    pageFiles = await glob('**/page.tsx', {
+      cwd: projectRoot,
+      ignore: ['**/node_modules/**'],
+    })
+  } catch {
+    return {
+      id: 'featurePageAdoption',
+      severity: 'info',
+      label: 'FeaturePage adoption',
+      pass: true,
+      detail: null,
+      suggestion: null,
+    }
+  }
+
+  let total = 0
+  let usingFeaturePage = 0
+
+  for (const file of pageFiles) {
+    const fullPath = join(projectRoot, file)
+    try {
+      const content = readFileSync(fullPath, 'utf-8')
+      total++
+      if (/FeaturePage/.test(content)) {
+        usingFeaturePage++
+      }
+    } catch { /* ignore */ }
+  }
+
+  const remaining = total - usingFeaturePage
+  return {
+    id: 'featurePageAdoption',
+    severity: 'info',
+    label: 'FeaturePage adoption',
+    pass: remaining === 0,
+    detail: `${usingFeaturePage}/${total} pages use FeaturePage`,
+    suggestion: remaining > 0 && usingFeaturePage > 0
+      ? `${usingFeaturePage}/${total} pages use FeaturePage (${remaining} remaining)`
+      : null,
+    total,
+    usingFeaturePage,
+  }
+}
+
+// ============================================================================
+// AUTO-FIX
+// ============================================================================
+
+/**
+ * Apply safe auto-fixes to the project.
+ * Returns list of { fix, file, success, error? } applied.
+ */
+export function applyFixes(projectRoot, checks, files) {
+  const applied = []
+
+  // Fix 1: Add suppressHydrationWarning to <html> tag
+  const suppressCheck = checks.find(c => c.id === 'suppressHydrationWarning')
+  if (suppressCheck && !suppressCheck.pass && suppressCheck.fixable && files.layout) {
+    const fullPath = join(projectRoot, files.layout.path)
+    try {
+      const original = readFileSync(fullPath, 'utf-8')
+      // Replace <html> or <html prop with <html suppressHydrationWarning prop / <html suppressHydrationWarning>
+      const fixed = original
+        .replace(/<html\s+([^>]*)>/, '<html suppressHydrationWarning $1>')
+        .replace(/<html>/, '<html suppressHydrationWarning>')
+      if (fixed !== original) {
+        writeFileSync(fullPath, fixed)
+        applied.push({ fix: 'suppressHydrationWarning', file: files.layout.path, success: true })
+      }
+    } catch (err) {
+      applied.push({ fix: 'suppressHydrationWarning', file: files.layout.path, success: false, error: err.message })
+    }
+  }
+
+  // Fix 2: Add dark-mode.css import to globals.css
+  const darkModeCheck = checks.find(c => c.id === 'darkMode')
+  if (darkModeCheck && !darkModeCheck.pass && darkModeCheck.fixable && files.globalsCss) {
+    const fullPath = join(projectRoot, files.globalsCss.path)
+    try {
+      const original = readFileSync(fullPath, 'utf-8')
+      const darkModeImport = '@import "@soulbatical/tetra-ui/styles/dark-mode.css";'
+
+      // Insert after tokens.css import if it exists, otherwise prepend
+      const tokensImportMatch = original.match(/(@import[^\n]*tokens\.css[^\n]*\n?)/)
+      let fixed
+      if (tokensImportMatch) {
+        fixed = original.replace(
+          tokensImportMatch[0],
+          tokensImportMatch[0] + darkModeImport + '\n'
+        )
+      } else {
+        fixed = darkModeImport + '\n' + original
+      }
+
+      if (fixed !== original) {
+        writeFileSync(fullPath, fixed)
+        applied.push({ fix: 'darkMode', file: files.globalsCss.path, success: true })
+      }
+    } catch (err) {
+      applied.push({ fix: 'darkMode', file: files.globalsCss.path, success: false, error: err.message })
+    }
+  }
+
+  return applied
+}
+
+// ============================================================================
+// MAIN AUDIT
+// ============================================================================
+
+/**
+ * Run the full doctor audit.
+ */
+export async function runDoctorAudit(projectRoot) {
+  const files = resolveFiles(projectRoot)
+
+  const [appShellCheck, featurePageCheck] = await Promise.all([
+    checkAppShellUsage(projectRoot),
+    checkFeaturePageAdoption(projectRoot),
+  ])
+
+  const checks = [
+    // CRITICAL
+    checkSuppressHydrationWarning(files),
+    checkThemeProvider(files),
+    checkTetraUiVersion(files),
+    checkNextThemes(projectRoot),
+    checkCssTokens(files),
+    checkDarkMode(files),
+    // HIGH
+    checkTetraCoreVersion(files),
+    appShellCheck,
+    checkAppConfig(files),
+    checkKeyboardShortcuts(files),
+    // INFO
+    checkTetraRootLayoutAdoption(files),
+    featurePageCheck,
+  ]
+
+  const criticalChecks = checks.filter(c => c.severity === 'critical')
+  const highChecks = checks.filter(c => c.severity === 'high')
+  const infoChecks = checks.filter(c => c.severity === 'info')
+
+  const criticalFailed = criticalChecks.filter(c => !c.pass).length
+  const highFailed = highChecks.filter(c => !c.pass).length
+  const totalChecks = criticalChecks.length + highChecks.length
+  const totalPassed = totalChecks - criticalFailed - highFailed
+  const score = totalChecks > 0 ? Math.round((totalPassed / totalChecks) * 100) : 100
+
+  return {
+    checks,
+    criticalChecks,
+    highChecks,
+    infoChecks,
+    files: {
+      layout: files.layout?.path || null,
+      providers: files.providers?.path || null,
+      globalsCss: files.globalsCss?.path || null,
+      appConfig: files.appConfig?.path || null,
+    },
+    summary: {
+      score,
+      criticalFailed,
+      highFailed,
+      totalChecks,
+      totalPassed,
+    },
+  }
+}
+
+// ============================================================================
+// FORMATTERS
+// ============================================================================
+
+/**
+ * Format report as pretty terminal output.
+ */
+export function formatDoctorReport(report, chalk, projectRoot) {
+  const lines = []
+  const { criticalChecks, highChecks, infoChecks, summary } = report
+
+  const projectName = projectRoot.split('/').pop()
+
+  lines.push('')
+  lines.push(chalk.cyan.bold('  Tetra Doctor'))
+  lines.push(chalk.cyan('  ' + '='.repeat(15)))
+  lines.push('')
+  lines.push(chalk.gray(`  Checking ${projectName}...`))
+  lines.push('')
+
+  // CRITICAL
+  lines.push(chalk.white.bold('  CRITICAL'))
+  for (const check of criticalChecks) {
+    const icon = check.pass ? chalk.green('  ✅') : chalk.red('  ❌')
+    const label = check.label.padEnd(30)
+    lines.push(`${icon} ${chalk.white(label)} ${chalk.gray(check.detail || '')}`)
+  }
+  lines.push('')
+
+  // HIGH
+  lines.push(chalk.white.bold('  HIGH'))
+  for (const check of highChecks) {
+    const icon = check.pass ? chalk.green('  ✅') : chalk.yellow('  ⚠️ ')
+    const label = check.label.padEnd(30)
+    lines.push(`${icon} ${chalk.white(label)} ${chalk.gray(check.detail || '')}`)
+  }
+  lines.push('')
+
+  // INFO — only show if there are suggestions
+  const infoWithSuggestions = infoChecks.filter(c => c.suggestion || c.detail)
+  if (infoWithSuggestions.length > 0) {
+    lines.push(chalk.white.bold('  INFO'))
+    for (const check of infoChecks) {
+      const message = check.suggestion || check.detail
+      if (message) {
+        lines.push(`  ${chalk.blue('💡')} ${chalk.gray(message)}`)
+      }
+    }
+    lines.push('')
+  }
+
+  // Summary
+  lines.push(chalk.gray('  ' + '─'.repeat(39)))
+  const scoreColor = summary.score >= 90
+    ? chalk.green
+    : summary.score >= 70
+    ? chalk.yellow
+    : chalk.red
+  lines.push(
+    scoreColor.bold(`  Score: ${summary.score}%`) +
+    chalk.gray(` — ${summary.criticalFailed} critical, ${summary.highFailed} warning`)
+  )
+  lines.push('')
+
+  return lines.join('\n')
+}
+
+/**
+ * Format report as JSON.
+ */
+export function formatDoctorReportJSON(report) {
+  return JSON.stringify(report, null, 2)
+}
+
+/**
+ * Format GitHub Actions annotations for failures.
+ */
+export function formatDoctorCIAnnotations(report) {
+  const annotations = []
+  for (const check of report.criticalChecks) {
+    if (!check.pass) {
+      annotations.push(`::error title=Tetra Doctor — ${check.label}::${check.detail}`)
+    }
+  }
+  for (const check of report.highChecks) {
+    if (!check.pass) {
+      annotations.push(`::warning title=Tetra Doctor — ${check.label}::${check.detail}`)
+    }
+  }
+  return annotations.join('\n')
+}

package/lib/checks/security/route-config-alignment.js

@@ -103,26 +103,38 @@ function hasOrgAdminMiddleware(content) {
 }
 
 /**
- * Check if admin routes are protected by a RouteManager group-level middleware.
- * Many projects apply auth middleware at the route group level (e.g., all /api/admin/* routes)
- * rather than in individual route files.
+ * Check if admin routes are protected by group-level middleware.
+ *
+ * Supports two patterns:
+ * 1. RouteManager: explicit authenticateToken in routes/index.ts or RouteManager.ts
+ * 2. createApp declarative routes: `access: 'admin'` in index.ts/app.ts
+ *    → createApp auto-injects authenticateToken + requireOrgAdmin for access='admin'
  */
 function hasRouteManagerGroupAuth(projectRoot) {
   const candidates = [
     join(projectRoot, 'backend/src/core/RouteManager.ts'),
     join(projectRoot, 'src/core/RouteManager.ts'),
     join(projectRoot, 'backend/src/routes/index.ts'),
-    join(projectRoot, 'src/routes/index.ts')
+    join(projectRoot, 'src/routes/index.ts'),
+    join(projectRoot, 'backend/src/index.ts'),
+    join(projectRoot, 'src/index.ts'),
+    join(projectRoot, 'backend/src/app.ts'),
+    join(projectRoot, 'src/app.ts')
   ]
 
   for (const file of candidates) {
     if (!existsSync(file)) continue
     try {
       const content = readFileSync(file, 'utf-8')
-      // Check for group middleware pattern: prefix '/api/admin' with authenticateToken
+      // Pattern 1: RouteManager with explicit authenticateToken for /api/admin
       if (/\/api\/admin/.test(content) && /authenticateToken/.test(content)) {
         return true
       }
+      // Pattern 2: createApp declarative routes — access: 'admin' auto-injects auth
+      // createApp guarantees authenticateToken + requireOrgAdmin for access='admin'
+      if (/createApp/.test(content) && /access:\s*['"]admin['"]/.test(content)) {
+        return true
+      }
     } catch { /* skip */ }
   }
   return false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulbatical/tetra-dev-toolkit",
-  "version": "1.20.16",
+  "version": "1.20.18",
   "publishConfig": {
     "access": "restricted"
   },
@@ -42,7 +42,8 @@
     "tetra-init-tests": "./bin/tetra-init-tests.js",
     "tetra-test-audit": "./bin/tetra-test-audit.js",
     "tetra-check-pages": "./bin/tetra-check-pages.js",
-    "tetra-check-views": "./bin/tetra-check-views.js"
+    "tetra-check-views": "./bin/tetra-check-views.js",
+    "tetra-doctor": "./bin/tetra-doctor.js"
   },
   "files": [
     "bin/",