@soulbatical/tetra-dev-toolkit 1.20.17 → 1.20.19

package/bin/tetra-dark-mode-fix.js

@@ -0,0 +1,355 @@
+#!/usr/bin/env node
+
+/**
+ * Tetra Dark Mode Autofix
+ *
+ * Mechanically replaces hardcoded Tailwind colors with Tetra design tokens.
+ * Run on a clean git branch so you can easily revert.
+ *
+ * Usage:
+ *   node tetra-dark-mode-fix.js                  # Dry run (shows what would change)
+ *   node tetra-dark-mode-fix.js --apply           # Apply changes
+ *   node tetra-dark-mode-fix.js --apply --verbose  # Apply + show each replacement
+ *
+ * Strategy:
+ *   1. PAIRED replacements first (bg-white dark:bg-gray-900 → bg-background)
+ *   2. NEUTRAL unpaired (bg-white → bg-background, text-gray-500 → text-muted-foreground)
+ *   3. SEMANTIC unpaired (bg-green-50 → bg-success-subtle, text-red-600 → text-danger-foreground)
+ *   4. HOVER/FOCUS modifiers (hover:bg-gray-100 → hover:bg-accent)
+ *   5. Remove orphaned dark: classes that no longer have a light counterpart
+ */
+
+import { readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { glob } from 'glob'
+
+const args = process.argv.slice(2)
+const APPLY = args.includes('--apply')
+const VERBOSE = args.includes('--verbose')
+const projectRoot = process.cwd()
+
+// ============================================================================
+// REPLACEMENT RULES — ordered from most specific to least specific
+// ============================================================================
+
+/**
+ * PAIRED rules: match "light-class dark:dark-class" and replace both with a single token.
+ * These run FIRST to avoid partial matches.
+ */
+const PAIRED_RULES = [
+  // ── Backgrounds ──
+  [/\bbg-white\s+dark:bg-(?:gray|slate|zinc|neutral)-(?:900|950)\b/g, 'bg-background'],
+  [/\bdark:bg-(?:gray|slate|zinc|neutral)-(?:900|950)\s+bg-white\b/g, 'bg-background'],
+  [/\bbg-(?:gray|slate|zinc|neutral)-50\s+dark:bg-(?:gray|slate|zinc|neutral)-(?:900|950)\b/g, 'bg-background'],
+  [/\bdark:bg-(?:gray|slate|zinc|neutral)-(?:900|950)\s+bg-(?:gray|slate|zinc|neutral)-50\b/g, 'bg-background'],
+  [/\bbg-(?:gray|slate|zinc|neutral)-100\s+dark:bg-(?:gray|slate|zinc|neutral)-(?:800|900)\b/g, 'bg-secondary'],
+  [/\bdark:bg-(?:gray|slate|zinc|neutral)-(?:800|900)\s+bg-(?:gray|slate|zinc|neutral)-100\b/g, 'bg-secondary'],
+  [/\bbg-(?:gray|slate|zinc|neutral)-200\s+dark:bg-(?:gray|slate|zinc|neutral)-(?:700|800)\b/g, 'bg-muted'],
+  [/\bdark:bg-(?:gray|slate|zinc|neutral)-(?:700|800)\s+bg-(?:gray|slate|zinc|neutral)-200\b/g, 'bg-muted'],
+  // ── Text ──
+  [/\btext-(?:gray|slate|zinc|neutral)-900\s+dark:text-(?:gray|slate|zinc|neutral)-(?:50|100)\b/g, 'text-foreground'],
+  [/\bdark:text-(?:gray|slate|zinc|neutral)-(?:50|100)\s+text-(?:gray|slate|zinc|neutral)-900\b/g, 'text-foreground'],
+  [/\btext-(?:gray|slate|zinc|neutral)-(?:700|800)\s+dark:text-(?:gray|slate|zinc|neutral)-(?:200|300)\b/g, 'text-foreground'],
+  [/\bdark:text-(?:gray|slate|zinc|neutral)-(?:200|300)\s+text-(?:gray|slate|zinc|neutral)-(?:700|800)\b/g, 'text-foreground'],
+  [/\btext-(?:gray|slate|zinc|neutral)-(?:500|600)\s+dark:text-(?:gray|slate|zinc|neutral)-(?:300|400)\b/g, 'text-muted-foreground'],
+  [/\bdark:text-(?:gray|slate|zinc|neutral)-(?:300|400)\s+text-(?:gray|slate|zinc|neutral)-(?:500|600)\b/g, 'text-muted-foreground'],
+  // ── Borders ──
+  [/\bborder-(?:gray|slate|zinc|neutral)-(?:200|300)\s+dark:border-(?:gray|slate|zinc|neutral)-(?:600|700|800)\b/g, 'border-border'],
+  [/\bdark:border-(?:gray|slate|zinc|neutral)-(?:600|700|800)\s+border-(?:gray|slate|zinc|neutral)-(?:200|300)\b/g, 'border-border'],
+  // ── Divide ──
+  [/\bdivide-(?:gray|slate|zinc|neutral)-(?:200|300)\s+dark:divide-(?:gray|slate|zinc|neutral)-(?:600|700|800)\b/g, 'divide-border'],
+  // ── Ring ──
+  [/\bring-(?:gray|slate|zinc|neutral)-(?:200|300)\s+dark:ring-(?:gray|slate|zinc|neutral)-(?:600|700|800)\b/g, 'ring-ring'],
+  // ── Hover backgrounds ──
+  [/\bhover:bg-(?:gray|slate|zinc|neutral)-(?:50|100)\s+dark:hover:bg-(?:gray|slate|zinc|neutral)-(?:800|900)\b/g, 'hover:bg-accent'],
+  [/\bdark:hover:bg-(?:gray|slate|zinc|neutral)-(?:800|900)\s+hover:bg-(?:gray|slate|zinc|neutral)-(?:50|100)\b/g, 'hover:bg-accent'],
+  // ── Hover text ──
+  [/\bhover:text-(?:gray|slate|zinc|neutral)-900\s+dark:hover:text-(?:gray|slate|zinc|neutral)-(?:50|100)\b/g, 'hover:text-foreground'],
+  // ── Hover borders ──
+  [/\bhover:border-(?:gray|slate|zinc|neutral)-(?:300|400)\s+dark:hover:border-(?:gray|slate|zinc|neutral)-(?:500|600)\b/g, 'hover:border-border'],
+]
+
+/**
+ * UNPAIRED neutral rules: single class → token.
+ * Run AFTER paired rules so we don't break paired sets.
+ */
+const UNPAIRED_NEUTRAL_RULES = [
+  // Backgrounds (including opacity suffixes like bg-black/50)
+  [/\bbg-white\b/g, 'bg-background'],
+  [/\bbg-(?:gray|slate|zinc|neutral)-50\b/g, 'bg-background'],
+  [/\bbg-(?:gray|slate|zinc|neutral)-100\b/g, 'bg-secondary'],
+  [/\bbg-(?:gray|slate|zinc|neutral)-200\b/g, 'bg-muted'],
+  [/\bbg-(?:gray|slate|zinc|neutral)-(?:300|400|500|600|700)\b/g, 'bg-muted'],
+  [/\bbg-(?:gray|slate|zinc|neutral)-(?:800|900|950)\b/g, 'bg-foreground'],
+  [/\bbg-black(?:\/\d+)?\b/g, 'bg-foreground/50'],
+  // Text (including white on dark surfaces)
+  [/\btext-(?:gray|slate|zinc|neutral)-(?:900|950)\b/g, 'text-foreground'],
+  [/\btext-(?:gray|slate|zinc|neutral)-(?:700|800)\b/g, 'text-foreground'],
+  [/\btext-(?:gray|slate|zinc|neutral)-(?:500|600)\b/g, 'text-muted-foreground'],
+  [/\btext-(?:gray|slate|zinc|neutral)-(?:100|200|300|400)\b/g, 'text-muted-foreground'],
+  [/\btext-black\b/g, 'text-foreground'],
+  [/\btext-white\b/g, 'text-primary-foreground'],
+  // Borders
+  [/\bborder-(?:gray|slate|zinc|neutral)-\d+\b/g, 'border-border'],
+  // Divide (all shades)
+  [/\bdivide-(?:gray|slate|zinc|neutral)-\d+\b/g, 'divide-border'],
+  // Ring
+  [/\bring-(?:gray|slate|zinc|neutral)-\d+\b/g, 'ring-ring'],
+  // Placeholder
+  [/\bplaceholder-(?:gray|slate|zinc|neutral)-\d+\b/g, 'placeholder:text-muted-foreground'],
+  // Fill / Stroke
+  [/\bfill-(?:gray|slate|zinc|neutral)-\d+\b/g, 'fill-muted-foreground'],
+  [/\bstroke-(?:gray|slate|zinc|neutral)-\d+\b/g, 'stroke-border'],
+  // Hover
+  [/\bhover:bg-(?:gray|slate|zinc|neutral)-(?:50|100)\b/g, 'hover:bg-accent'],
+  [/\bhover:bg-(?:gray|slate|zinc|neutral)-(?:200|300)\b/g, 'hover:bg-accent'],
+  [/\bhover:text-(?:gray|slate|zinc|neutral)-(?:700|800|900)\b/g, 'hover:text-foreground'],
+  [/\bhover:text-(?:gray|slate|zinc|neutral)-(?:500|600)\b/g, 'hover:text-muted-foreground'],
+  [/\bhover:border-(?:gray|slate|zinc|neutral)-(?:300|400|500)\b/g, 'hover:border-border'],
+  // Focus
+  [/\bfocus:ring-(?:gray|slate|zinc|neutral)-(?:300|400|500)\b/g, 'focus:ring-ring'],
+  [/\bfocus:border-(?:gray|slate|zinc|neutral)-(?:300|400|500)\b/g, 'focus:border-ring'],
+]
+
+/**
+ * SEMANTIC color rules: map colored classes to semantic tokens.
+ */
+const SEMANTIC_RULES = [
+  // ── Success (green/emerald) ──
+  [/\bbg-(?:green|emerald)-(?:50|100)\b/g, 'bg-success-subtle'],
+  [/\bbg-(?:green|emerald)-(?:500|600)\b/g, 'bg-success'],
+  [/\btext-(?:green|emerald)-(?:400|500|600|700|800|900)\b/g, 'text-success-foreground'],
+  [/\bborder-(?:green|emerald)-(?:200|300|400)\b/g, 'border-success'],
+  // ── Danger (red/rose) ──
+  [/\bbg-(?:red|rose)-(?:50|100)\b/g, 'bg-danger-subtle'],
+  [/\bbg-(?:red|rose)-(?:500|600)\b/g, 'bg-destructive'],
+  [/\btext-(?:red|rose)-(?:400|500|600|700|800|900)\b/g, 'text-danger-foreground'],
+  [/\bborder-(?:red|rose)-(?:200|300|400)\b/g, 'border-destructive'],
+  // ── Warning (amber/yellow/orange) ──
+  [/\bbg-(?:amber|yellow|orange)-(?:50|100)\b/g, 'bg-warning-subtle'],
+  [/\bbg-(?:amber|yellow|orange)-(?:500|600)\b/g, 'bg-warning'],
+  [/\btext-(?:amber|yellow|orange)-(?:400|500|600|700|800|900)\b/g, 'text-warning-foreground'],
+  [/\bborder-(?:amber|yellow|orange)-(?:200|300|400)\b/g, 'border-warning'],
+  // ── Info (blue/sky/cyan) ──
+  [/\bbg-(?:blue|sky|cyan)-(?:50|100)\b/g, 'bg-info-subtle'],
+  [/\bbg-(?:blue|sky|cyan)-(?:500|600)\b/g, 'bg-info'],
+  [/\btext-(?:blue|sky|cyan)-(?:400|500|600|700|800|900)\b/g, 'text-info-foreground'],
+  [/\bborder-(?:blue|sky|cyan)-(?:200|300|400)\b/g, 'border-info'],
+]
+
+/**
+ * BRAND color rules: map indigo/violet/purple to brand tokens.
+ * Projects override --tetra-brand-* in their globals.css.
+ */
+const BRAND_RULES = [
+  // ── Primary brand (indigo/violet → brand) ──
+  [/\bbg-(?:indigo|violet)-(?:50|100)\b/g, 'bg-brand-subtle'],
+  [/\bbg-(?:indigo|violet)-(?:500|600)\b/g, 'bg-brand'],
+  [/\bbg-(?:indigo|violet)-(?:700|800)\b/g, 'bg-brand-hover'],
+  [/\bbg-(?:indigo|violet)-(?:900|950)(?:\/\d+)?\b/g, 'bg-brand/10'],
+  [/\btext-(?:indigo|violet)-(?:400|500)\b/g, 'text-brand-text'],
+  [/\btext-(?:indigo|violet)-(?:600|700)\b/g, 'text-brand-text'],
+  [/\btext-(?:indigo|violet)-(?:800|900)\b/g, 'text-brand-text'],
+  [/\bborder-(?:indigo|violet)-(?:200|300)\b/g, 'border-brand/30'],
+  [/\bborder-(?:indigo|violet)-(?:400|500)\b/g, 'border-brand'],
+  [/\bborder-(?:indigo|violet)-(?:600)\b/g, 'border-brand'],
+  [/\bring-(?:indigo|violet)-(?:100|200)\b/g, 'ring-brand/20'],
+  [/\bring-(?:indigo|violet)-(?:500|600)\b/g, 'ring-brand-ring'],
+  [/\bhover:bg-(?:indigo|violet)-(?:500|600|700)\b/g, 'hover:bg-brand-hover'],
+  [/\bhover:text-(?:indigo|violet)-(?:300|400)\b/g, 'hover:text-brand-text'],
+  [/\bfocus:ring-(?:indigo|violet)-(?:500|600)\b/g, 'focus:ring-brand-ring'],
+  [/\bfocus:border-(?:indigo|violet)-(?:500|600)\b/g, 'focus:border-brand'],
+  // ── Alt brand (purple/fuchsia → brand-alt) ──
+  [/\bbg-(?:purple|fuchsia)-(?:50|100)\b/g, 'bg-brand-alt-subtle'],
+  [/\bbg-(?:purple|fuchsia)-(?:500|600)\b/g, 'bg-brand-alt'],
+  [/\bbg-(?:purple|fuchsia)-(?:700|800)\b/g, 'bg-brand-alt-hover'],
+  [/\bbg-(?:purple|fuchsia)-(?:900)(?:\/\d+)?\b/g, 'bg-brand-alt/10'],
+  [/\btext-(?:purple|fuchsia)-(?:400|500)\b/g, 'text-brand-alt-text'],
+  [/\btext-(?:purple|fuchsia)-(?:600|700)\b/g, 'text-brand-alt-text'],
+  [/\btext-(?:purple|fuchsia)-(?:800|900)\b/g, 'text-brand-alt-text'],
+  [/\bborder-(?:purple|fuchsia)-(?:200|300)\b/g, 'border-brand-alt/30'],
+  [/\bborder-(?:purple|fuchsia)-(?:500)\b/g, 'border-brand-alt'],
+  [/\bring-(?:purple|fuchsia)-(?:500|600)\b/g, 'ring-brand-alt'],
+  [/\bhover:bg-(?:purple|fuchsia)-(?:500|600|700)\b/g, 'hover:bg-brand-alt-hover'],
+  [/\bfocus:ring-(?:purple|fuchsia)-(?:500|600)\b/g, 'focus:ring-brand-alt'],
+  // ── Platform A: pink (Instagram, etc.) ──
+  [/\bbg-pink-(?:50|100)\b/g, 'bg-platform-a-subtle'],
+  [/\bbg-pink-(?:400|500|600)\b/g, 'bg-platform-a'],
+  [/\bbg-pink-(?:900)(?:\/\d+)?\b/g, 'bg-platform-a/10'],
+  [/\btext-pink-(?:400|500)\b/g, 'text-platform-a-text'],
+  [/\btext-pink-(?:600|700|800)\b/g, 'text-platform-a-text'],
+  [/\bborder-pink-(?:200|300)\b/g, 'border-platform-a/30'],
+  [/\bborder-pink-(?:500)\b/g, 'border-platform-a'],
+  // ── Platform B: teal (TikTok, etc.) ──
+  [/\bbg-teal-(?:50|100)\b/g, 'bg-platform-b-subtle'],
+  [/\bbg-teal-(?:400|500|600)\b/g, 'bg-platform-b'],
+  [/\bbg-teal-(?:900)(?:\/\d+)?\b/g, 'bg-platform-b/10'],
+  [/\btext-teal-(?:400|500)\b/g, 'text-platform-b-text'],
+  [/\btext-teal-(?:600|700|800)\b/g, 'text-platform-b-text'],
+  [/\bborder-teal-(?:200|300)\b/g, 'border-platform-b/30'],
+  [/\bborder-teal-(?:500)\b/g, 'border-platform-b'],
+  // ── Platform C: orange/amber (Reddit, warnings, etc.) ──
+  [/\bbg-(?:orange|amber)-(?:50|100)\b/g, 'bg-platform-c-subtle'],
+  [/\bbg-(?:orange|amber)-(?:400|500|600)\b/g, 'bg-platform-c'],
+  [/\bbg-(?:orange|amber)-(?:700|800|900)(?:\/\d+)?\b/g, 'bg-platform-c/10'],
+  [/\bbg-(?:orange|amber)-(?:950)(?:\/\d+)?\b/g, 'bg-platform-c/10'],
+  [/\btext-(?:orange|amber)-(?:400|500|600)\b/g, 'text-platform-c-text'],
+  [/\btext-(?:orange|amber)-(?:700|800)\b/g, 'text-platform-c-text'],
+  [/\bborder-(?:orange|amber)-(?:200|300|500)\b/g, 'border-platform-c/30'],
+  [/\bborder-(?:orange|amber)-(?:800)\b/g, 'border-platform-c'],
+  [/\bring-(?:orange|amber)-(?:300|400|500)(?:\/\d+)?\b/g, 'ring-platform-c/40'],
+  [/\bhover:bg-(?:orange|amber)-(?:200|700)\b/g, 'hover:bg-platform-c-subtle'],
+  [/\bhover:border-(?:orange|amber)-(?:500)(?:\/\d+)?\b/g, 'hover:border-platform-c'],
+  // ── Platform D: purple (decorative, Twitch, etc.) ──
+  [/\bborder-purple-(?:400|600)\b/g, 'border-platform-d'],
+  [/\bbg-purple-(?:200|400)\b/g, 'bg-platform-d-subtle'],
+  [/\bhover:bg-purple-(?:200)\b/g, 'hover:bg-platform-d-subtle'],
+  [/\bhover:text-purple-(?:200|300)\b/g, 'hover:text-platform-d-text'],
+  [/\bhover:border-purple-(?:400)\b/g, 'hover:border-platform-d'],
+  // ── Remaining: emerald borders/hovers ──
+  [/\bborder-emerald-(?:500)\b/g, 'border-success'],
+  [/\bhover:border-emerald-(?:500)(?:\/\d+)?\b/g, 'hover:border-success'],
+  [/\bhover:bg-emerald-(?:900)(?:\/\d+)?\b/g, 'hover:bg-success/10'],
+]
+
+/**
+ * ORPHAN dark: cleanup — remove dark: classes whose light counterpart was already replaced.
+ * These are now redundant because tokens handle dark mode automatically.
+ */
+const ORPHAN_DARK_RULES = [
+  // Backgrounds
+  [/\s*\bdark:bg-(?:gray|slate|zinc|neutral)-(?:50|100|200|300|400|500|600|700|800|900|950)\b/g, ''],
+  [/\s*\bdark:bg-(?:gray|slate|zinc|neutral)-(?:900|950)\/\d+\b/g, ''],
+  // Text
+  [/\s*\bdark:text-(?:gray|slate|zinc|neutral)-(?:50|100|200|300|400|500|600|700|800|900|950)\b/g, ''],
+  // Borders
+  [/\s*\bdark:border-(?:gray|slate|zinc|neutral)-(?:50|100|200|300|400|500|600|700|800|900|950)\b/g, ''],
+  // Divide
+  [/\s*\bdark:divide-(?:gray|slate|zinc|neutral)-\d+\b/g, ''],
+  // Ring
+  [/\s*\bdark:ring-(?:gray|slate|zinc|neutral)-\d+\b/g, ''],
+  // Hover
+  [/\s*\bdark:hover:bg-(?:gray|slate|zinc|neutral)-\d+\b/g, ''],
+  [/\s*\bdark:hover:text-(?:gray|slate|zinc|neutral)-\d+\b/g, ''],
+  [/\s*\bdark:hover:border-(?:gray|slate|zinc|neutral)-\d+\b/g, ''],
+  // Focus
+  [/\s*\bdark:focus:ring-(?:gray|slate|zinc|neutral)-\d+\b/g, ''],
+  [/\s*\bdark:focus:border-(?:gray|slate|zinc|neutral)-\d+\b/g, ''],
+  // Semantic dark overrides
+  [/\s*\bdark:bg-(?:green|emerald|red|rose|amber|yellow|orange|blue|sky|cyan)-\d+(?:\/\d+)?\b/g, ''],
+  [/\s*\bdark:text-(?:green|emerald|red|rose|amber|yellow|orange|blue|sky|cyan)-\d+\b/g, ''],
+  [/\s*\bdark:border-(?:green|emerald|red|rose|amber|yellow|orange|blue|sky|cyan)-\d+\b/g, ''],
+  // Brand dark overrides
+  [/\s*\bdark:bg-(?:indigo|violet|purple|fuchsia)-\d+(?:\/\d+)?\b/g, ''],
+  [/\s*\bdark:text-(?:indigo|violet|purple|fuchsia)-\d+\b/g, ''],
+  [/\s*\bdark:border-(?:indigo|violet|purple|fuchsia)-\d+\b/g, ''],
+  [/\s*\bdark:ring-(?:indigo|violet|purple|fuchsia)-\d+(?:\/\d+)?\b/g, ''],
+  [/\s*\bdark:hover:bg-(?:indigo|violet|purple|fuchsia)-\d+(?:\/\d+)?\b/g, ''],
+  // Platform dark overrides
+  [/\s*\bdark:(?:bg|text|border|ring)-(?:pink|teal|orange|amber)-\d+(?:\/\d+)?\b/g, ''],
+  [/\s*\bdark:hover:(?:bg|text|border)-(?:pink|teal|orange|amber)-\d+(?:\/\d+)?\b/g, ''],
+]
+
+// ============================================================================
+// APPLY
+// ============================================================================
+
+const frontendDir = join(projectRoot, 'frontend', 'src')
+const files = [
+  ...glob.sync('**/*.tsx', { cwd: frontendDir, ignore: ['**/node_modules/**', '**/.next/**'] }),
+  ...glob.sync('**/*.jsx', { cwd: frontendDir, ignore: ['**/node_modules/**', '**/.next/**'] }),
+]
+
+let totalReplacements = 0
+let totalFiles = 0
+const stats = { paired: 0, neutral: 0, semantic: 0, brand: 0, orphanDark: 0 }
+
+for (const file of files) {
+  const fullPath = join(frontendDir, file)
+  const original = readFileSync(fullPath, 'utf-8')
+  let content = original
+
+  // Phase 1: Paired replacements
+  for (const [re, token] of PAIRED_RULES) {
+    re.lastIndex = 0
+    content = content.replace(re, (match) => {
+      stats.paired++
+      if (VERBOSE) console.log(`  [paired] ${file}: ${match} → ${token}`)
+      return token
+    })
+  }
+
+  // Phase 2: Unpaired neutrals
+  for (const [re, token] of UNPAIRED_NEUTRAL_RULES) {
+    re.lastIndex = 0
+    content = content.replace(re, (match) => {
+      stats.neutral++
+      if (VERBOSE) console.log(`  [neutral] ${file}: ${match} → ${token}`)
+      return token
+    })
+  }
+
+  // Phase 3: Semantics
+  for (const [re, token] of SEMANTIC_RULES) {
+    re.lastIndex = 0
+    content = content.replace(re, (match) => {
+      stats.semantic++
+      if (VERBOSE) console.log(`  [semantic] ${file}: ${match} → ${token}`)
+      return token
+    })
+  }
+
+  // Phase 3b: Brand colors
+  for (const [re, token] of BRAND_RULES) {
+    re.lastIndex = 0
+    content = content.replace(re, (match) => {
+      stats.brand++
+      if (VERBOSE) console.log(`  [brand] ${file}: ${match} → ${token}`)
+      return token
+    })
+  }
+
+  // Phase 4: Orphan dark: cleanup
+  for (const [re, replacement] of ORPHAN_DARK_RULES) {
+    re.lastIndex = 0
+    content = content.replace(re, (match) => {
+      stats.orphanDark++
+      if (VERBOSE) console.log(`  [orphan-dark] ${file}: removed ${match.trim()}`)
+      return replacement
+    })
+  }
+
+  // Clean up double/triple spaces left by removals
+  content = content.replace(/  +/g, ' ')
+  // Clean up space before closing quote
+  content = content.replace(/ "/g, '"').replace(/ '/g, "'")
+  // But restore intentional space-before-quote in template literals etc.
+  // Actually, be conservative — only clean within className attributes
+  // This simple approach works for most cases
+
+  if (content !== original) {
+    totalFiles++
+    const currentTotal = stats.paired + stats.neutral + stats.semantic + stats.brand + stats.orphanDark
+    const replacements = currentTotal - totalReplacements
+    totalReplacements = currentTotal
+    console.log(`${APPLY ? '✅' : '📋'} ${file} (${replacements} changes)`)
+
+    if (APPLY) {
+      writeFileSync(fullPath, content, 'utf-8')
+    }
+  }
+}
+
+console.log('')
+console.log(`${'='.repeat(60)}`)
+const total = stats.paired + stats.neutral + stats.semantic + stats.brand + stats.orphanDark
+console.log(`${APPLY ? 'APPLIED' : 'DRY RUN'} — ${totalFiles} files, ${total} total replacements`)
+console.log(`  Paired (light+dark → token):  ${stats.paired}`)
+console.log(`  Neutral (single → token):     ${stats.neutral}`)
+console.log(`  Semantic (color → token):      ${stats.semantic}`)
+console.log(`  Brand (indigo/purple → token): ${stats.brand}`)
+console.log(`  Orphan dark: removed:          ${stats.orphanDark}`)
+console.log('')
+if (!APPLY) {
+  console.log('Run with --apply to write changes. Make sure you are on a clean branch!')
+}

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()