@soulbatical/tetra-dev-toolkit 1.20.14 → 1.20.16

package/bin/tetra-check-pages.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+/**
+ * Tetra Page Compliance — enforce FeaturePage usage across frontend pages.
+ *
+ * Scans all Next.js / Vite page files and checks whether they use
+ * the FeaturePage component from tetra-ui, or contain ad-hoc patterns
+ * that violate the Tetra page standard.
+ *
+ * Usage:
+ *   tetra-check-pages                          # Audit current project
+ *   tetra-check-pages --path /path/to/project  # Audit specific project
+ *   tetra-check-pages --json                   # JSON output for CI
+ *   tetra-check-pages --ci                     # GitHub Actions annotations
+ *   tetra-check-pages --strict                 # Fail on any violation (incl. warnings)
+ *   tetra-check-pages --fix-hint               # Show suggested fix for each violation
+ *
+ * Exit codes:
+ *   0 = all critical checks pass
+ *   1 = violations found
+ */
+
+import { program } from 'commander'
+import chalk from 'chalk'
+import {
+  runPageComplianceAudit,
+  formatReport,
+  formatReportJSON,
+  formatCIAnnotations,
+} from '../lib/audits/page-compliance-audit.js'
+
+program
+  .name('tetra-check-pages')
+  .description('Enforce FeaturePage usage across frontend pages')
+  .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 violation including warnings (default: only critical violations)')
+  .option('--fix-hint', 'Show suggested fix for each violation')
+  .action(async (options) => {
+    try {
+      const projectRoot = options.path || process.cwd()
+
+      if (!options.json) {
+        console.log(chalk.gray('\n  Scanning pages...'))
+      }
+
+      const report = await runPageComplianceAudit(projectRoot)
+
+      // Output
+      if (options.json) {
+        console.log(formatReportJSON(report))
+      } else {
+        console.log(formatReport(report, chalk, { fixHint: options.fixHint }))
+
+        if (options.ci) {
+          const annotations = formatCIAnnotations(report)
+          if (annotations) {
+            console.log(annotations)
+          }
+        }
+      }
+
+      // Exit code
+      const { summary } = report
+      if (options.strict) {
+        // Strict: fail on any violation or warning
+        process.exit(summary.violations > 0 || summary.warningOnly > 0 ? 1 : 0)
+      } else {
+        // Default: only fail on critical violations
+        process.exit(summary.criticalViolations > 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/bin/tetra-check-views.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+
+/**
+ * Tetra View Config — enforce view configuration in FeatureConfig files.
+ *
+ * Scans all backend FeatureConfig files and verifies they have the properties
+ * required for FeaturePage to work: views, restBasePath, and columns.
+ *
+ * Usage:
+ *   tetra-check-views                          # Audit current project
+ *   tetra-check-views --path /path/to/project  # Audit specific project
+ *   tetra-check-views --json                   # JSON output for CI
+ *   tetra-check-views --ci                     # GitHub Actions annotations
+ *   tetra-check-views --strict                 # Fail on any violation (incl. warnings)
+ *
+ * Exit codes:
+ *   0 = all critical checks pass
+ *   1 = violations found
+ */
+
+import { program } from 'commander'
+import chalk from 'chalk'
+import {
+  runViewConfigAudit,
+  formatReport,
+  formatReportJSON,
+  formatCIAnnotations,
+} from '../lib/audits/view-config-audit.js'
+
+program
+  .name('tetra-check-views')
+  .description('Enforce view configuration in FeatureConfig files')
+  .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 violation including warnings (default: only critical violations)')
+  .action(async (options) => {
+    try {
+      const projectRoot = options.path || process.cwd()
+
+      if (!options.json) {
+        console.log(chalk.gray('\n  Scanning feature configs...'))
+      }
+
+      const report = await runViewConfigAudit(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 violation or warning
+        process.exit(summary.violations > 0 || summary.warningOnly > 0 ? 1 : 0)
+      } else {
+        // Default: only fail on critical violations
+        process.exit(summary.criticalViolations > 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/page-compliance-audit.js

@@ -0,0 +1,406 @@
+/**
+ * Page Compliance Audit — scans a Tetra project to enforce FeaturePage usage.
+ *
+ * Finds all Next.js / Vite frontend page files and checks whether they use
+ * the FeaturePage component from tetra-ui, or have ad-hoc patterns that
+ * should be replaced.
+ */
+
+import { readFileSync, existsSync } from 'fs'
+import { join, relative } from 'path'
+import { glob } from 'glob'
+
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+
+/** Pages that are always whitelisted — they legitimately don't use FeaturePage. */
+const ALWAYS_WHITELISTED = [
+  { pattern: /^frontend\/src\/app\/.*\(auth\)/, reason: 'auth flow' },
+  { pattern: /^frontend\/src\/app\/.*auth\//, reason: 'auth flow' },
+  { pattern: /^frontend\/src\/app\/.*invite\//, reason: 'invite flow' },
+  { pattern: /^frontend\/src\/app\/.*onboarding\//, reason: 'onboarding flow' },
+  // The root dashboard page is a summary/overview — not a list page
+  { pattern: /^frontend\/src\/app\/(?:\([^)]+\/\))?page\.tsx$/, reason: 'main dashboard' },
+  { pattern: /^frontend\/src\/app\/\([^)]+\)\/page\.tsx$/, reason: 'main dashboard' },
+]
+
+/** CRITICAL violations block CI. */
+const CRITICAL_PATTERNS = [
+  {
+    id: 'useState-filter',
+    label: 'ad-hoc filter/search state (useState)',
+    regex: /useState[^(]*\([^)]*\)\s*(?:\/\/[^\n]*)?\n[^;]*(?:[Ff]ilter|[Ss]earch|[Ss]ort|[Qq]uery)/,
+    // Simpler alternative: catch useState calls where the state name contains filter/search/sort
+    regexAlt: /const\s*\[\s*\w*(?:[Ff]ilter|[Ss]earch|[Ss]ort)\w*\s*,/,
+  },
+  {
+    id: 'manual-fetch',
+    label: 'manual API fetching',
+    regex: /apiFetch\s*\(|apiClient\s*\.\s*get\s*\(|fetch\s*\(\s*['"`][^'"`]*\/api\//,
+  },
+  {
+    id: 'list-detail-layout',
+    label: 'direct ListDetailLayout import (use FeaturePage instead)',
+    regex: /import[^;]*ListDetailLayout[^;]*from/,
+  },
+  {
+    id: 'hardcoded-layout',
+    label: 'hardcoded page shell (min-h-screen + p-8/p-6 wrapper)',
+    // Only flag when min-h-screen AND p-8/p-6 appear on the same className attribute —
+    // the classic hand-rolled page wrapper pattern.
+    regex: /className=["'][^"']*\bmin-h-screen\b[^"']*\bp-[68]\b[^"']*["']|className=["'][^"']*\bp-[68]\b[^"']*\bmin-h-screen\b[^"']*["']/,
+  },
+]
+
+/** WARNING violations are reported but don't block CI by default. */
+const WARNING_PATTERNS = [
+  {
+    id: 'long-page',
+    label: 'page file > 50 lines',
+    check: (content) => content.split('\n').length > 50,
+  },
+  {
+    id: 'missing-feature-page',
+    label: 'looks like a list page but missing FeaturePage import',
+    check: (content) => {
+      // Heuristic: file renders a list-like structure (map, table, grid) but no FeaturePage
+      const looksLikeList = /\.map\s*\(/.test(content) || /<table/i.test(content) || /grid-cols/i.test(content)
+      const hasFeaturePage = /FeaturePage|GeneratedPage/.test(content)
+      return looksLikeList && !hasFeaturePage
+    },
+  },
+]
+
+// ============================================================================
+// WHITELIST LOADER
+// ============================================================================
+
+/**
+ * Load extra whitelist entries from .tetra-whitelist.json in project root.
+ */
+function loadProjectWhitelist(projectRoot) {
+  const whitelistPath = join(projectRoot, '.tetra-whitelist.json')
+  if (!existsSync(whitelistPath)) return []
+
+  try {
+    const raw = readFileSync(whitelistPath, 'utf-8')
+    const parsed = JSON.parse(raw)
+    const entries = parsed.pageWhitelist || []
+    return entries.map((e) => ({
+      // Convert glob-style path to a simple string prefix check
+      pattern: e.path,
+      reason: e.reason || 'whitelisted',
+    }))
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Check whether a file path matches any whitelist entry.
+ * Returns the matching entry or null.
+ */
+function matchWhitelist(filePath, always, project) {
+  for (const entry of always) {
+    if (entry.pattern instanceof RegExp && entry.pattern.test(filePath)) {
+      return entry
+    }
+  }
+  for (const entry of project) {
+    // Simple glob: convert "video-studio/**" → prefix match
+    const prefix = entry.pattern.replace(/\/\*\*$/, '').replace(/\/\*$/, '')
+    if (filePath.includes(prefix)) {
+      return entry
+    }
+  }
+  return null
+}
+
+// ============================================================================
+// PAGE SCANNER
+// ============================================================================
+
+/**
+ * Find all page files in the project.
+ */
+async function scanPageFiles(projectRoot) {
+  const patterns = [
+    'frontend/src/app/**/page.tsx',
+    'frontend/src/pages/**/*.tsx',
+  ]
+
+  const files = []
+  for (const pattern of patterns) {
+    const found = await glob(pattern, { cwd: projectRoot })
+    files.push(...found)
+  }
+
+  return [...new Set(files)]
+}
+
+/**
+ * Derive a human-readable page label from the file path.
+ * e.g. "frontend/src/app/(dashboard)/campaigns/page.tsx" → "campaigns/page.tsx"
+ */
+function pageLabel(filePath) {
+  // Strip common prefix
+  return filePath
+    .replace(/^frontend\/src\/app\//, '')
+    .replace(/^frontend\/src\/pages\//, '')
+    // Remove route groups like (dashboard)
+    .replace(/\([^)]+\)\//g, '')
+}
+
+// ============================================================================
+// VIOLATION CHECKER
+// ============================================================================
+
+/**
+ * Scan a single page file for violations.
+ * Returns { violations: [], warnings: [], isCompliant: bool }
+ */
+function auditPageContent(content) {
+  const violations = []
+  const warnings = []
+
+  // Check CRITICAL patterns
+  for (const p of CRITICAL_PATTERNS) {
+    let matched = false
+    if (p.regex && p.regex.test(content)) {
+      matched = true
+    } else if (p.regexAlt && p.regexAlt.test(content)) {
+      matched = true
+    }
+    if (matched) {
+      violations.push({ id: p.id, label: p.label, severity: 'critical' })
+    }
+  }
+
+  // Check WARNING patterns
+  for (const p of WARNING_PATTERNS) {
+    if (p.check(content)) {
+      warnings.push({ id: p.id, label: p.label, severity: 'warning' })
+    }
+  }
+
+  // Check for good patterns
+  const hasFeaturePage = /import[^;]*FeaturePage[^;]*from[^;]*tetra-ui/.test(content) ||
+    /import[^;]*GeneratedPage/.test(content)
+
+  return { violations, warnings, hasFeaturePage }
+}
+
+/**
+ * Build a fix hint for a page with violations.
+ */
+function buildFixHint(label, violations) {
+  // Strip route suffix to get the feature name
+  const featureName = label
+    .replace(/\/page\.tsx$/, '')
+    .replace(/\.tsx$/, '')
+    .split('/')
+    .pop()
+
+  const ids = violations.map((v) => v.id)
+
+  if (ids.includes('list-detail-layout')) {
+    return `Replace with <FeaturePage featureName="${featureName}" views={[{type:'list-detail'}]} />`
+  }
+  return `Replace with <FeaturePage featureName="${featureName}" />`
+}
+
+// ============================================================================
+// MAIN AUDIT
+// ============================================================================
+
+/**
+ * Run the full page compliance audit.
+ */
+export async function runPageComplianceAudit(projectRoot) {
+  const projectWhitelist = loadProjectWhitelist(projectRoot)
+  const pageFiles = await scanPageFiles(projectRoot)
+
+  const results = []
+
+  for (const filePath of pageFiles) {
+    const label = pageLabel(filePath)
+    const whitelistMatch = matchWhitelist(filePath, ALWAYS_WHITELISTED, projectWhitelist)
+
+    if (whitelistMatch) {
+      results.push({
+        file: filePath,
+        label,
+        status: 'whitelisted',
+        reason: whitelistMatch.reason,
+        violations: [],
+        warnings: [],
+        hasFeaturePage: false,
+        fixHint: null,
+      })
+      continue
+    }
+
+    const fullPath = join(projectRoot, filePath)
+    let content = ''
+    try {
+      content = readFileSync(fullPath, 'utf-8')
+    } catch {
+      results.push({
+        file: filePath,
+        label,
+        status: 'error',
+        reason: 'could not read file',
+        violations: [],
+        warnings: [],
+        hasFeaturePage: false,
+        fixHint: null,
+      })
+      continue
+    }
+
+    const { violations, warnings, hasFeaturePage } = auditPageContent(content)
+
+    let status
+    if (violations.length > 0) {
+      status = 'violation'
+    } else if (hasFeaturePage) {
+      status = 'compliant'
+    } else if (warnings.length > 0) {
+      status = 'warning'
+    } else {
+      // No violations, no FeaturePage, no warnings — treat as OK (may be a simple page)
+      status = 'compliant'
+    }
+
+    const fixHint = violations.length > 0 ? buildFixHint(label, violations) : null
+
+    results.push({
+      file: filePath,
+      label,
+      status,
+      reason: null,
+      violations,
+      warnings,
+      hasFeaturePage,
+      fixHint,
+    })
+  }
+
+  // Summary
+  const total = results.length
+  const whitelisted = results.filter((r) => r.status === 'whitelisted').length
+  const compliant = results.filter((r) => r.status === 'compliant').length
+  const warningOnly = results.filter((r) => r.status === 'warning').length
+  const violations = results.filter((r) => r.status === 'violation').length
+  const audited = total - whitelisted
+  const score = audited > 0 ? Math.round((compliant / audited) * 100) : 100
+  const criticalViolations = violations
+
+  return {
+    results,
+    summary: {
+      total,
+      audited,
+      compliant,
+      warningOnly,
+      violations,
+      whitelisted,
+      score,
+      criticalViolations,
+    },
+  }
+}
+
+// ============================================================================
+// FORMATTERS
+// ============================================================================
+
+/**
+ * Format the report as pretty terminal output.
+ */
+export function formatReport(report, chalk, options = {}) {
+  const lines = []
+  const { results, summary } = report
+
+  lines.push('')
+  lines.push(chalk.blue.bold('  Tetra Page Compliance Audit'))
+  lines.push(chalk.blue('  ' + '═'.repeat(27)))
+  lines.push('')
+
+  for (const r of results) {
+    if (r.status === 'whitelisted') {
+      lines.push(chalk.gray(`  ⚠️   ${r.label.padEnd(40)} (whitelisted: ${r.reason})`))
+    } else if (r.status === 'compliant') {
+      lines.push(chalk.green(`  ✅  ${r.label.padEnd(40)} FeaturePage ✓`))
+    } else if (r.status === 'warning') {
+      const warnLabels = r.warnings.map((w) => w.label).join('; ')
+      lines.push(chalk.yellow(`  ⚠️   ${r.label.padEnd(40)} WARNING: ${warnLabels}`))
+      if (options.fixHint && r.fixHint) {
+        lines.push(chalk.yellow(`       → Fix: ${r.fixHint}`))
+      }
+    } else if (r.status === 'violation') {
+      const violLabels = r.violations.map((v) => v.label).join('; ')
+      lines.push(chalk.red(`  ❌  ${r.label.padEnd(40)} VIOLATION: ${violLabels}`))
+      if (options.fixHint && r.fixHint) {
+        lines.push(chalk.red(`       → Fix: ${r.fixHint}`))
+      }
+    } else {
+      lines.push(chalk.gray(`  ?   ${r.label.padEnd(40)} (${r.reason || 'unknown'})`))
+    }
+  }
+
+  lines.push('')
+  lines.push(chalk.gray('  ' + '─'.repeat(39)))
+
+  const scoreColor =
+    summary.score >= 80 ? chalk.green : summary.score >= 50 ? chalk.yellow : chalk.red
+  lines.push(scoreColor.bold(`  Score: ${summary.score}% (${summary.compliant}/${summary.audited} compliant)`))
+  lines.push(
+    chalk.white(
+      `  Pages: ${summary.total} total, ${summary.compliant} compliant, ${summary.violations} violations, ${summary.whitelisted} whitelisted`
+    )
+  )
+  lines.push('')
+
+  if (summary.criticalViolations > 0) {
+    lines.push(
+      chalk.red.bold(`  ❌ ${summary.criticalViolations} critical violation${summary.criticalViolations > 1 ? 's' : ''} found. Fix before merging.`)
+    )
+    lines.push('')
+  } else if (summary.violations === 0) {
+    lines.push(chalk.green.bold('  All pages compliant.'))
+    lines.push('')
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Format the report as JSON.
+ */
+export function formatReportJSON(report) {
+  return JSON.stringify(report, null, 2)
+}
+
+/**
+ * Output GitHub Actions annotations for violations.
+ */
+export function formatCIAnnotations(report) {
+  const annotations = []
+
+  for (const r of report.results) {
+    for (const v of r.violations) {
+      annotations.push(
+        `::error file=${r.file},title=Page Compliance Violation::${r.label}: ${v.label}`
+      )
+    }
+    for (const w of r.warnings) {
+      annotations.push(
+        `::warning file=${r.file},title=Page Compliance Warning::${r.label}: ${w.label}`
+      )
+    }
+  }
+
+  return annotations.join('\n')
+}

package/lib/audits/view-config-audit.js

@@ -0,0 +1,289 @@
+/**
+ * View Config Audit — scans FeatureConfig files to enforce view configuration.
+ *
+ * Finds all backend FeatureConfig files and verifies they have the properties
+ * required for FeaturePage to work correctly.
+ */
+
+import { readFileSync } from 'fs'
+import { join } from 'path'
+import { glob } from 'glob'
+
+// ============================================================================
+// SCANNERS
+// ============================================================================
+
+/**
+ * Scan all FeatureConfig files and extract relevant properties.
+ */
+async function scanFeatureConfigs(projectRoot) {
+  const pattern = 'backend/src/features/**/config/*.config.ts'
+  const files = await glob(pattern, { cwd: projectRoot })
+
+  const configs = []
+  for (const file of files) {
+    const fullPath = join(projectRoot, file)
+    let content = ''
+    try {
+      content = readFileSync(fullPath, 'utf-8')
+    } catch {
+      configs.push({
+        file,
+        featureName: deriveFeatureName(file),
+        readError: true,
+        hasViews: false,
+        hasRestBasePath: false,
+        hasColumns: false,
+        views: [],
+      })
+      continue
+    }
+
+    const featureName = deriveFeatureName(file)
+
+    // Detect presence of views property
+    const hasViews = /\bviews\s*:/.test(content)
+
+    // Detect restBasePath
+    const hasRestBasePath = /\brestBasePath\s*:/.test(content)
+
+    // Detect columns
+    const hasColumns = /\bcolumns\s*:/.test(content)
+
+    // Extract view types listed
+    const views = extractViewTypes(content)
+
+    configs.push({
+      file,
+      featureName,
+      readError: false,
+      hasViews,
+      hasRestBasePath,
+      hasColumns,
+      views,
+    })
+  }
+
+  return configs
+}
+
+/**
+ * Derive a short feature name from the file path.
+ * e.g. "backend/src/features/adcampaigns/config/adcampaigns.config.ts" → "adcampaigns"
+ */
+function deriveFeatureName(filePath) {
+  const parts = filePath.split('/')
+  // features/<featureName>/config/...
+  const featIdx = parts.indexOf('features')
+  if (featIdx !== -1 && parts[featIdx + 1]) {
+    return parts[featIdx + 1]
+  }
+  return parts[parts.length - 1].replace(/\.config\.ts$/, '')
+}
+
+/**
+ * Extract view type strings from a config file content.
+ * Looks for patterns like type: 'list-detail' or type: "cards".
+ */
+function extractViewTypes(content) {
+  const types = []
+  const typeRegex = /type\s*:\s*['"]([^'"]+)['"]/g
+  let match
+  while ((match = typeRegex.exec(content)) !== null) {
+    // Only include known view types
+    const knownViewTypes = ['list-detail', 'cards', 'table', 'kanban', 'calendar', 'timeline']
+    if (knownViewTypes.includes(match[1])) {
+      types.push(match[1])
+    }
+  }
+  return [...new Set(types)]
+}
+
+// ============================================================================
+// VIOLATION CHECKER
+// ============================================================================
+
+/**
+ * Determine violations for a single config.
+ */
+function auditConfig(config) {
+  const violations = []
+  const warnings = []
+
+  if (config.readError) {
+    violations.push({ id: 'read-error', label: 'could not read config file', severity: 'critical' })
+    return { violations, warnings }
+  }
+
+  // CRITICAL: missing views
+  if (!config.hasViews) {
+    violations.push({ id: 'missing-views', label: 'MISSING: views property', severity: 'critical' })
+  }
+
+  // CRITICAL: missing restBasePath
+  if (!config.hasRestBasePath) {
+    violations.push({ id: 'missing-rest-base-path', label: 'MISSING: restBasePath', severity: 'critical' })
+  }
+
+  // WARNING: missing columns
+  if (!config.hasColumns) {
+    warnings.push({ id: 'missing-columns', label: 'no columns (table view and AutoDetail disabled)', severity: 'warning' })
+  }
+
+  // WARNING: list-detail or table view without columns
+  if (config.hasViews && !config.hasColumns) {
+    const needsColumns = config.views.some((v) => v === 'list-detail' || v === 'table')
+    if (needsColumns) {
+      warnings.push({
+        id: 'view-needs-columns',
+        label: `views include ${config.views.filter((v) => v === 'list-detail' || v === 'table').join('/')} but no columns defined`,
+        severity: 'warning',
+      })
+    }
+  }
+
+  return { violations, warnings }
+}
+
+// ============================================================================
+// MAIN AUDIT
+// ============================================================================
+
+/**
+ * Run the full view config audit.
+ */
+export async function runViewConfigAudit(projectRoot) {
+  const configs = await scanFeatureConfigs(projectRoot)
+
+  const results = []
+
+  for (const config of configs) {
+    const { violations, warnings } = auditConfig(config)
+
+    let status
+    if (violations.length > 0) {
+      status = 'violation'
+    } else if (warnings.length > 0) {
+      status = 'warning'
+    } else {
+      status = 'ok'
+    }
+
+    results.push({
+      file: config.file,
+      featureName: config.featureName,
+      status,
+      violations,
+      warnings,
+      views: config.views,
+      hasColumns: config.hasColumns,
+    })
+  }
+
+  // Summary
+  const total = results.length
+  const ok = results.filter((r) => r.status === 'ok').length
+  const warningOnly = results.filter((r) => r.status === 'warning').length
+  const violations = results.filter((r) => r.status === 'violation').length
+  const configured = ok + warningOnly
+  const score = total > 0 ? Math.round((configured / total) * 100) : 100
+  const criticalViolations = violations
+
+  return {
+    results,
+    summary: {
+      total,
+      ok,
+      warningOnly,
+      violations,
+      configured,
+      score,
+      criticalViolations,
+    },
+  }
+}
+
+// ============================================================================
+// FORMATTERS
+// ============================================================================
+
+/**
+ * Format the report as pretty terminal output.
+ */
+export function formatReport(report, chalk) {
+  const lines = []
+  const { results, summary } = report
+
+  lines.push('')
+  lines.push(chalk.blue.bold('  Tetra View Config Audit'))
+  lines.push(chalk.blue('  ' + '═'.repeat(23)))
+  lines.push('')
+
+  for (const r of results) {
+    const name = r.featureName.padEnd(24)
+
+    if (r.status === 'ok') {
+      const viewList = r.views.length > 0 ? `views: [${r.views.join(', ')}]` : 'views: configured'
+      const colNote = r.hasColumns ? ' ✓' : ''
+      lines.push(chalk.green(`  ✅  ${name} ${viewList}${colNote}`))
+    } else if (r.status === 'warning') {
+      const viewList = r.views.length > 0 ? `views: [${r.views.join(', ')}]` : 'views: configured'
+      const warnLabels = r.warnings.map((w) => w.label).join('; ')
+      lines.push(chalk.yellow(`  ⚠️   ${name} ${viewList} — WARNING: ${warnLabels}`))
+    } else {
+      const violLabels = r.violations.map((v) => v.label).join(' + ')
+      lines.push(chalk.red(`  ❌  ${name} ${violLabels}`))
+    }
+  }
+
+  lines.push('')
+  lines.push(chalk.gray('  ' + '─'.repeat(39)))
+
+  const scoreColor =
+    summary.score >= 80 ? chalk.green : summary.score >= 50 ? chalk.yellow : chalk.red
+  lines.push(scoreColor.bold(`  Score: ${summary.score}% (${summary.configured}/${summary.total} configured)`))
+  lines.push('')
+
+  if (summary.criticalViolations > 0) {
+    lines.push(
+      chalk.red.bold(
+        `  ❌ ${summary.criticalViolations} feature${summary.criticalViolations > 1 ? 's' : ''} missing required config. Fix before merging.`
+      )
+    )
+    lines.push('')
+  } else if (summary.violations === 0) {
+    lines.push(chalk.green.bold('  All feature configs valid.'))
+    lines.push('')
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Format the report as JSON.
+ */
+export function formatReportJSON(report) {
+  return JSON.stringify(report, null, 2)
+}
+
+/**
+ * Output GitHub Actions annotations for violations.
+ */
+export function formatCIAnnotations(report) {
+  const annotations = []
+
+  for (const r of report.results) {
+    for (const v of r.violations) {
+      annotations.push(
+        `::error file=${r.file},title=View Config Violation::${r.featureName}: ${v.label}`
+      )
+    }
+    for (const w of r.warnings) {
+      annotations.push(
+        `::warning file=${r.file},title=View Config Warning::${r.featureName}: ${w.label}`
+      )
+    }
+  }
+
+  return annotations.join('\n')
+}

package/lib/checks/health/index.js

@@ -42,3 +42,4 @@ export { check as checkSmokeReadiness } from './smoke-readiness.js'
 export { check as checkReleasePipeline } from './release-pipeline.js'
 export { check as checkTestStructure } from './test-structure.js'
 export { check as checkSentryMonitoring } from './sentry-monitoring.js'
+export { check as checkShadcnUiTokens } from './shadcn-ui-tokens.js'

package/lib/checks/health/scanner.js

@@ -38,6 +38,7 @@ 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 { check as checkShadcnUiTokens } from './shadcn-ui-tokens.js'
 import { calculateHealthStatus } from './types.js'
 
 /**
@@ -84,7 +85,8 @@ export async function scanProjectHealth(projectPath, projectName, options = {})
     checkSmokeReadiness(projectPath),
     checkReleasePipeline(projectPath),
     checkTestStructure(projectPath),
-    checkSentryMonitoring(projectPath)
+    checkSentryMonitoring(projectPath),
+    checkShadcnUiTokens(projectPath)
   ])
 
   const totalScore = checks.reduce((sum, c) => sum + c.score, 0)

package/lib/checks/health/shadcn-ui-tokens.js

@@ -0,0 +1,240 @@
+/**
+ * Health Check: shadcn/ui Token Completeness
+ *
+ * Verifies that a frontend project defines all required shadcn/ui CSS custom properties.
+ * These are needed by tetra-ui components and any shadcn/ui primitives.
+ *
+ * Score: 5 (full) = all tokens defined, 3 = partial, 0 = missing critical tokens
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'fs'
+import { join, resolve } from 'path'
+import { createCheck } from './types.js'
+
+// shadcn/ui required CSS tokens (Tailwind v4 @theme format: --color-*)
+// These map to utility classes like bg-background, text-foreground, border-border, etc.
+const CRITICAL_TOKENS = [
+  { name: 'background', css: '--color-background', usage: 'bg-background' },
+  { name: 'foreground', css: '--color-foreground', usage: 'text-foreground' },
+  { name: 'border', css: '--color-border', usage: 'border-border' },
+  { name: 'primary', css: '--color-primary', usage: 'bg-primary' },
+  { name: 'primary-foreground', css: '--color-primary-foreground', usage: 'text-primary-foreground' },
+  { name: 'accent', css: '--color-accent', usage: 'bg-accent' },
+  { name: 'accent-foreground', css: '--color-accent-foreground', usage: 'text-accent-foreground' },
+  { name: 'muted', css: '--color-muted', usage: 'bg-muted' },
+  { name: 'muted-foreground', css: '--color-muted-foreground', usage: 'text-muted-foreground' },
+  { name: 'destructive', css: '--color-destructive', usage: 'text-destructive, hover:text-destructive' },
+]
+
+const RECOMMENDED_TOKENS = [
+  { name: 'card', css: '--color-card', usage: 'bg-card' },
+  { name: 'card-foreground', css: '--color-card-foreground', usage: 'text-card-foreground' },
+  { name: 'popover', css: '--color-popover', usage: 'bg-popover' },
+  { name: 'popover-foreground', css: '--color-popover-foreground', usage: 'text-popover-foreground' },
+  { name: 'secondary', css: '--color-secondary', usage: 'bg-secondary' },
+  { name: 'secondary-foreground', css: '--color-secondary-foreground', usage: 'text-secondary-foreground' },
+  { name: 'input', css: '--color-input', usage: 'border-input' },
+  { name: 'ring', css: '--color-ring', usage: 'ring-ring' },
+]
+
+const DARK_MODE_INDICATORS = [
+  '.dark',
+  'dark:',
+  '@custom-variant dark',
+  'prefers-color-scheme: dark',
+  'data-theme="dark"',
+]
+
+/**
+ * Find all CSS files in frontend/src
+ */
+function findCssFiles(projectPath) {
+  const frontendSrc = join(projectPath, 'frontend', 'src')
+  if (!existsSync(frontendSrc)) return []
+
+  const files = []
+  function walk(dir) {
+    try {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name === 'node_modules') continue
+        const full = join(dir, entry.name)
+        if (entry.isDirectory()) walk(full)
+        else if (entry.name.endsWith('.css')) files.push(full)
+      }
+    } catch { /* ignore permission errors */ }
+  }
+  walk(frontendSrc)
+  return files
+}
+
+/**
+ * Check if a CSS var is defined in content (either directly or via @theme)
+ */
+function isTokenDefined(allCss, token) {
+  // Direct: --color-background: ...
+  if (allCss.includes(token.css + ':')) return true
+  if (allCss.includes(token.css + ' :')) return true
+
+  // @theme block: --color-background: ...
+  // Already covered by above
+
+  // Check for shadcn HSL format: --background: ...  (without --color- prefix)
+  const hslVar = token.css.replace('--color-', '--')
+  if (allCss.includes(hslVar + ':')) return true
+
+  return false
+}
+
+/**
+ * Check if shadcn/ui is initialized (has the standard globals.css structure)
+ */
+function hasShadcnInit(allCss) {
+  // shadcn init creates a globals.css with @layer base { :root { --background: ... } }
+  // or Tailwind v4 style @theme { --color-background: ... }
+  return (
+    allCss.includes('--background:') ||
+    allCss.includes('--color-background:') ||
+    allCss.includes('@layer base')
+  )
+}
+
+/**
+ * Check tetra-ui version
+ */
+function getTetraUiVersion(projectPath) {
+  const paths = [
+    join(projectPath, 'frontend', 'package.json'),
+    join(projectPath, 'package.json'),
+  ]
+  for (const p of paths) {
+    try {
+      const pkg = JSON.parse(readFileSync(p, 'utf-8'))
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies }
+      return deps['@soulbatical/tetra-ui'] || deps['@vca/tetra-ui'] || null
+    } catch { /* skip */ }
+  }
+  return null
+}
+
+/**
+ * Count shadcn token usage in TSX files
+ */
+function countTokenUsage(projectPath) {
+  const frontendSrc = join(projectPath, 'frontend', 'src')
+  if (!existsSync(frontendSrc)) return {}
+
+  const usageCounts = {}
+  const allTokens = [...CRITICAL_TOKENS, ...RECOMMENDED_TOKENS]
+
+  function walk(dir) {
+    try {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name === 'node_modules') continue
+        const full = join(dir, entry.name)
+        if (entry.isDirectory()) walk(full)
+        else if (entry.name.endsWith('.tsx') || entry.name.endsWith('.ts')) {
+          try {
+            const content = readFileSync(full, 'utf-8')
+            for (const token of allTokens) {
+              if (content.includes(token.usage.split(',')[0])) {
+                usageCounts[token.name] = (usageCounts[token.name] || 0) + 1
+              }
+            }
+          } catch { /* skip */ }
+        }
+      }
+    } catch { /* ignore */ }
+  }
+  walk(frontendSrc)
+  return usageCounts
+}
+
+export async function check(projectPath) {
+  const result = createCheck('shadcn-ui-tokens', 5, {
+    hasFrontend: false,
+    tetraUiVersion: null,
+    shadcnInitialized: false,
+    hasDarkMode: false,
+    missingCritical: [],
+    missingRecommended: [],
+    definedTokens: [],
+    tokenUsage: {},
+  })
+  result.score = 5
+
+  // Check if project has a frontend
+  const frontendPath = join(projectPath, 'frontend')
+  if (!existsSync(frontendPath)) {
+    result.score = 5  // N/A — no frontend
+    result.details.message = 'No frontend directory — check skipped'
+    return result
+  }
+  result.details.hasFrontend = true
+  result.details.tetraUiVersion = getTetraUiVersion(projectPath)
+
+  // Gather all CSS content (project + imported tetra-ui tokens)
+  const cssFiles = findCssFiles(projectPath)
+  if (cssFiles.length === 0) {
+    result.score = 0
+    result.status = 'error'
+    result.details.message = 'No CSS files found in frontend/src'
+    return result
+  }
+
+  // Also include tetra-ui tokens.css if imported
+  const tetraTokensPaths = [
+    join(projectPath, 'frontend', 'node_modules', '@soulbatical', 'tetra-ui', 'src', 'styles', 'tokens.css'),
+    join(projectPath, 'node_modules', '@soulbatical', 'tetra-ui', 'src', 'styles', 'tokens.css'),
+  ]
+  for (const p of tetraTokensPaths) {
+    if (existsSync(p) && !cssFiles.includes(p)) cssFiles.push(p)
+  }
+
+  const allCss = cssFiles.map(f => {
+    try { return readFileSync(f, 'utf-8') } catch { return '' }
+  }).join('\n')
+
+  result.details.shadcnInitialized = hasShadcnInit(allCss)
+  result.details.hasDarkMode = DARK_MODE_INDICATORS.some(i => allCss.includes(i))
+
+  // Check token definitions
+  for (const token of CRITICAL_TOKENS) {
+    if (isTokenDefined(allCss, token)) {
+      result.details.definedTokens.push(token.name)
+    } else {
+      result.details.missingCritical.push(token.name)
+    }
+  }
+  for (const token of RECOMMENDED_TOKENS) {
+    if (isTokenDefined(allCss, token)) {
+      result.details.definedTokens.push(token.name)
+    } else {
+      result.details.missingRecommended.push(token.name)
+    }
+  }
+
+  // Check actual usage
+  result.details.tokenUsage = countTokenUsage(projectPath)
+
+  // Score
+  if (result.details.missingCritical.length > 5) {
+    result.score = 0
+    result.status = 'error'
+    result.details.message = `shadcn/ui not initialized — ${result.details.missingCritical.length}/10 critical tokens missing: ${result.details.missingCritical.join(', ')}`
+  } else if (result.details.missingCritical.length > 0) {
+    result.score = 2
+    result.status = 'warning'
+    result.details.message = `Missing ${result.details.missingCritical.length} critical tokens: ${result.details.missingCritical.join(', ')}`
+  } else if (result.details.missingRecommended.length > 0) {
+    result.score = 4
+    result.status = 'warning'
+    result.details.message = `All critical tokens OK. Missing ${result.details.missingRecommended.length} recommended: ${result.details.missingRecommended.join(', ')}`
+  }
+
+  if (!result.details.hasDarkMode) {
+    result.score = Math.max(0, result.score - 1)
+    result.details.message = (result.details.message || '') + ' | No dark mode setup detected'
+  }
+
+  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'|'sentry-monitoring'} 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'|'shadcn-ui-tokens'} HealthCheckType
  *
  * @typedef {'ok'|'warning'|'error'} HealthStatus
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulbatical/tetra-dev-toolkit",
-  "version": "1.20.14",
+  "version": "1.20.16",
   "publishConfig": {
     "access": "restricted"
   },
@@ -40,7 +40,9 @@
     "tetra-security-gate": "./bin/tetra-security-gate.js",
     "tetra-smoke": "./bin/tetra-smoke.js",
     "tetra-init-tests": "./bin/tetra-init-tests.js",
-    "tetra-test-audit": "./bin/tetra-test-audit.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"
   },
   "files": [
     "bin/",