@soulbatical/tetra-dev-toolkit 1.20.21 → 1.20.22

package/bin/tetra-init.js

@@ -442,8 +442,8 @@ async function initCi(config, options) {
   // Detect project structure
   const hasBackend = existsSync(join(projectRoot, 'backend/package.json'))
   const hasFrontend = existsSync(join(projectRoot, 'frontend/package.json'))
-  const hasMigrations = existsSync(join(projectRoot, 'backend/supabase/migrations')) ||
-    existsSync(join(projectRoot, 'supabase/migrations'))
+  const hasMigrations = existsSync(join(projectRoot, 'supabase/migrations')) ||
+    existsSync(join(projectRoot, 'backend/supabase/migrations'))
 
   let workspaces
   if (hasBackend && hasFrontend) {
@@ -488,6 +488,31 @@ ${withLines.join('\n')}
 `
 
   writeIfMissing(join(workflowDir, 'quality.yml'), workflowContent, options)
+
+  // Deploy Migrations workflow (only if supabase migrations exist)
+  if (hasMigrations) {
+    const deployContent = `name: Deploy Migrations
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'supabase/migrations/**'
+
+jobs:
+  deploy:
+    uses: mralbertzwolle/tetra/.github/workflows/deploy-migrations.yml@main
+    secrets: inherit
+`
+    writeIfMissing(join(workflowDir, 'deploy-migrations.yml'), deployContent, options)
+  }
+
+  // Ensure supabase/migrations/ directory exists at root
+  const migrationsDir = join(projectRoot, 'supabase/migrations')
+  if (!existsSync(migrationsDir)) {
+    mkdirSync(migrationsDir, { recursive: true })
+    console.log(`  📁 Created supabase/migrations/`)
+  }
 }
 
 function checkCompleteness() {
@@ -529,8 +554,9 @@ function checkCompleteness() {
     { path: 'frontend/next.config.ts', category: 'frontend', required: true },
     { path: 'frontend/src/app/layout.tsx', category: 'frontend', required: true },
 
-    // Database
-    { path: 'supabase/migrations', category: 'database', required: false },
+    // Database & CI
+    { path: 'supabase/migrations', category: 'database', required: true },
+    { path: '.github/workflows/deploy-migrations.yml', category: 'database', required: false },
   ]
 
   let currentCategory = ''

package/lib/checks/codeQuality/appshell-compliance.js

@@ -0,0 +1,573 @@
+/**
+ * Code Quality Check: AppShell Compliance
+ *
+ * Verifies that consumer projects correctly integrate with the Tetra UI
+ * AppShell and design token system. Catches issues that were found in
+ * CoachHub and would affect any consumer:
+ *
+ * 1. globals.css pattern: Has @theme inline block, :root with --tetra-* tokens,
+ *    and body styled with var(--tetra-*)
+ * 2. AppShell usage: Uses AppShell from @soulbatical/tetra-ui (not custom sidebar)
+ * 3. Config consistency: No items duplicated across navigation and userMenu
+ * 4. TetraAppConfig completeness: Has branding, navigation, layout, theme, features
+ * 5. Version check: Installed tetra-ui version meets minimum
+ *
+ * Severity: high — these issues break theming, layout, and UX consistency
+ */
+
+import { readFileSync, existsSync } from 'fs'
+import { execFileSync } from 'child_process'
+import { join } from 'path'
+import { glob } from 'glob'
+
+// ============================================================================
+// META
+// ============================================================================
+
+export const meta = {
+  id: 'appshell-compliance',
+  name: 'AppShell Compliance',
+  category: 'codeQuality',
+  severity: 'high',
+  description: 'Verifies consumer projects correctly use Tetra AppShell, design tokens, and config patterns'
+}
+
+// ============================================================================
+// HELPERS
+// ============================================================================
+
+function readFileSafe(filePath) {
+  try {
+    return readFileSync(filePath, 'utf-8')
+  } catch {
+    return null
+  }
+}
+
+function findFrontendDir(projectRoot) {
+  const candidates = [
+    join(projectRoot, 'frontend', 'src'),
+    join(projectRoot, 'src'),
+  ]
+  for (const dir of candidates) {
+    if (existsSync(dir)) return dir
+  }
+  return null
+}
+
+function findGlobalsCss(frontendDir) {
+  const candidates = [
+    join(frontendDir, 'app', 'globals.css'),
+    join(frontendDir, 'styles', 'globals.css'),
+    join(frontendDir, 'globals.css'),
+  ]
+  for (const p of candidates) {
+    if (existsSync(p)) return p
+  }
+  const found = glob.sync('**/globals.css', { cwd: frontendDir, absolute: true, ignore: ['**/node_modules/**'] })
+  return found[0] || null
+}
+
+// ============================================================================
+// CHECK 1: globals.css pattern
+// ============================================================================
+
+function checkGlobalsCss(frontendDir) {
+  const findings = []
+  const cssPath = findGlobalsCss(frontendDir)
+
+  if (!cssPath) {
+    findings.push({
+      severity: 'high',
+      message: 'No globals.css found — required for Tetra design token integration',
+      rule: 'globals-css-missing',
+    })
+    return findings
+  }
+
+  const content = readFileSafe(cssPath)
+  if (!content) return findings
+
+  // 1a. Must have @theme inline block (not just @import tokens.css)
+  if (!content.includes('@theme inline')) {
+    findings.push({
+      severity: 'critical',
+      message: 'globals.css missing `@theme inline` block — Tailwind v4 requires @theme inline to map utility classes to Tetra tokens',
+      rule: 'missing-theme-inline',
+      fix: 'Add @theme inline { --color-background: var(--tetra-bg); ... } block',
+    })
+  }
+
+  // Check for old @import pattern (warn but don't fail if @theme inline exists)
+  if (content.includes('@import') && content.includes('tokens.css')) {
+    findings.push({
+      severity: content.includes('@theme inline') ? 'medium' : 'critical',
+      message: 'globals.css uses old @import tokens.css pattern — migrate to @theme inline with --tetra-* tokens',
+      rule: 'old-import-pattern',
+    })
+  }
+
+  // 1b. Must have :root with --tetra-* tokens
+  const hasRootBlock = /:root\s*\{/.test(content)
+  const hasTetraTokens = /--tetra-\w+/.test(content)
+  if (!hasRootBlock || !hasTetraTokens) {
+    findings.push({
+      severity: 'critical',
+      message: 'globals.css missing :root block with --tetra-* token definitions',
+      rule: 'missing-root-tokens',
+      fix: 'Add :root { --tetra-bg: #ffffff; --tetra-text: #0f172a; ... } block',
+    })
+  }
+
+  // 1c. Must have body styling with var(--tetra-*)
+  const bodyMatch = content.match(/body\s*\{([^}]+)\}/s)
+  if (!bodyMatch) {
+    findings.push({
+      severity: 'high',
+      message: 'globals.css missing body { } block with Tetra token references',
+      rule: 'missing-body-styling',
+      fix: 'Add body { background: var(--tetra-bg); color: var(--tetra-text); font-family: var(--tetra-font); }',
+    })
+  } else {
+    const bodyBlock = bodyMatch[1]
+    if (!bodyBlock.includes('var(--tetra-')) {
+      findings.push({
+        severity: 'high',
+        message: 'body block does not use var(--tetra-*) tokens — hardcoded values will break theming',
+        rule: 'body-no-tetra-vars',
+        fix: 'Use var(--tetra-bg), var(--tetra-text), var(--tetra-font) in body styles',
+      })
+    }
+  }
+
+  // 1d. Check that @theme inline maps to var(--tetra-*), not hardcoded values
+  const themeInlineMatch = content.match(/@theme inline\s*\{([^}]+)\}/s)
+  if (themeInlineMatch) {
+    const themeBlock = themeInlineMatch[1]
+    const lines = themeBlock.split('\n').filter(l => l.trim() && !l.trim().startsWith('/*') && !l.trim().startsWith('//'))
+    const hardcodedInTheme = lines.filter(l => {
+      const valueMatch = l.match(/:\s*([^;]+);/)
+      if (!valueMatch) return false
+      const value = valueMatch[1].trim()
+      return value.startsWith('#') || value.startsWith('rgb') || value.startsWith('hsl')
+    })
+
+    if (hardcodedInTheme.length > 0) {
+      findings.push({
+        severity: 'high',
+        message: `@theme inline has ${hardcodedInTheme.length} hardcoded value(s) — should reference var(--tetra-*) tokens`,
+        rule: 'theme-inline-hardcoded',
+        details: hardcodedInTheme.map(l => l.trim()).slice(0, 5),
+      })
+    }
+  }
+
+  // 1e. Dark mode block should exist
+  const hasDarkBlock = /(?:html\.dark|\.dark|\[data-theme="dark"\])\s*(?:,\s*(?:html\.dark|\.dark|\[data-theme="dark"\])\s*)*\{/.test(content)
+  if (!hasDarkBlock) {
+    findings.push({
+      severity: 'medium',
+      message: 'globals.css missing dark mode override block (html.dark or [data-theme="dark"])',
+      rule: 'missing-dark-mode',
+      fix: 'Add html.dark, [data-theme="dark"] { --tetra-bg: ...; --tetra-text: ...; } block',
+    })
+  }
+
+  return findings
+}
+
+// ============================================================================
+// CHECK 2: AppShell usage
+// ============================================================================
+
+function checkAppShellUsage(frontendDir) {
+  const findings = []
+
+  const files = glob.sync('**/*.{tsx,ts,jsx}', {
+    cwd: frontendDir,
+    ignore: ['**/node_modules/**', '**/.next/**', '**/dist/**'],
+    absolute: false,
+  })
+
+  let usesTetraAppShell = false
+  let hasCustomSidebar = false
+  const customSidebarFiles = []
+
+  for (const file of files) {
+    const content = readFileSafe(join(frontendDir, file))
+    if (!content) continue
+
+    // Check for tetra-ui AppShell import
+    if (content.includes('@soulbatical/tetra-ui') && /\bAppShell\b/.test(content)) {
+      usesTetraAppShell = true
+    }
+
+    // Detect custom sidebar implementations (not from tetra-ui)
+    if (
+      (/\bSidebar\b/.test(content) || /\bAppSidebar\b/.test(content)) &&
+      !content.includes('@soulbatical/tetra-ui') &&
+      (file.toLowerCase().includes('sidebar') || file.toLowerCase().includes('layout'))
+    ) {
+      if (content.includes('export') && (/function\s+\w*[Ss]idebar/.test(content) || /const\s+\w*[Ss]idebar/.test(content))) {
+        hasCustomSidebar = true
+        customSidebarFiles.push(file)
+      }
+    }
+  }
+
+  if (!usesTetraAppShell) {
+    findings.push({
+      severity: 'high',
+      message: 'Project does not use AppShell from @soulbatical/tetra-ui — should use the standard shell for consistent UX',
+      rule: 'no-tetra-appshell',
+      fix: 'Import and use AppShell from @soulbatical/tetra-ui in your root layout',
+    })
+  }
+
+  if (hasCustomSidebar && usesTetraAppShell) {
+    findings.push({
+      severity: 'medium',
+      message: `Custom sidebar component(s) found alongside Tetra AppShell: ${customSidebarFiles.join(', ')} — remove custom implementations`,
+      rule: 'custom-sidebar-with-appshell',
+    })
+  }
+
+  return findings
+}
+
+// ============================================================================
+// CHECK 3: Config consistency (no duplicate nav/userMenu items)
+// ============================================================================
+
+function checkConfigConsistency(frontendDir) {
+  const findings = []
+
+  const files = glob.sync('**/*.{ts,tsx}', {
+    cwd: frontendDir,
+    ignore: ['**/node_modules/**', '**/.next/**', '**/dist/**'],
+    absolute: false,
+  })
+
+  for (const file of files) {
+    const content = readFileSafe(join(frontendDir, file))
+    if (!content) continue
+
+    // Look for files defining TetraAppConfig or app config objects
+    if (!content.includes('navigation') || !content.includes('userMenu')) continue
+
+    // Extract navigation item labels/titles
+    const navLabels = extractLabels(content, 'navigation')
+    const userMenuLabels = extractLabels(content, 'userMenu')
+
+    if (navLabels.length === 0 || userMenuLabels.length === 0) continue
+
+    // Find duplicates between navigation and userMenu
+    const duplicates = navLabels.filter(label => userMenuLabels.includes(label))
+    if (duplicates.length > 0) {
+      findings.push({
+        file,
+        severity: 'medium',
+        message: `Config has items in BOTH navigation and userMenu: ${duplicates.join(', ')} — each item should appear in only one location`,
+        rule: 'duplicate-nav-usermenu',
+        fix: `Move "${duplicates.join('", "')}" to either navigation OR userMenu, not both`,
+      })
+    }
+
+    // Check for duplicate items within navigation itself
+    const navDuplicates = findDuplicates(navLabels)
+    if (navDuplicates.length > 0) {
+      findings.push({
+        file,
+        severity: 'medium',
+        message: `Duplicate items within navigation: ${navDuplicates.join(', ')}`,
+        rule: 'duplicate-nav-items',
+      })
+    }
+
+    // Check for duplicate items within userMenu itself
+    const menuDuplicates = findDuplicates(userMenuLabels)
+    if (menuDuplicates.length > 0) {
+      findings.push({
+        file,
+        severity: 'medium',
+        message: `Duplicate items within userMenu: ${menuDuplicates.join(', ')}`,
+        rule: 'duplicate-usermenu-items',
+      })
+    }
+  }
+
+  return findings
+}
+
+function extractLabels(content, sectionName) {
+  const labels = []
+  const sectionRegex = new RegExp(`${sectionName}\\s*[:\\[]`, 'g')
+  let match
+  while ((match = sectionRegex.exec(content)) !== null) {
+    const remaining = content.slice(match.index, match.index + 2000)
+    const labelMatches = remaining.matchAll(/(?:label|title)\s*:\s*['"]([^'"]+)['"]/g)
+    for (const m of labelMatches) {
+      labels.push(m[1])
+    }
+  }
+  return labels
+}
+
+function findDuplicates(arr) {
+  const seen = new Set()
+  const dupes = new Set()
+  for (const item of arr) {
+    if (seen.has(item)) dupes.add(item)
+    seen.add(item)
+  }
+  return [...dupes]
+}
+
+// ============================================================================
+// CHECK 4: TetraAppConfig completeness
+// ============================================================================
+
+function checkConfigCompleteness(frontendDir) {
+  const findings = []
+
+  const files = glob.sync('**/*.{ts,tsx}', {
+    cwd: frontendDir,
+    ignore: ['**/node_modules/**', '**/.next/**', '**/dist/**'],
+    absolute: false,
+  })
+
+  let foundConfig = false
+  const requiredSections = ['branding', 'navigation', 'layout', 'theme', 'features']
+
+  for (const file of files) {
+    const content = readFileSafe(join(frontendDir, file))
+    if (!content) continue
+
+    if (!content.includes('TetraAppConfig')) continue
+    foundConfig = true
+
+    const missingSections = []
+    for (const section of requiredSections) {
+      const sectionRegex = new RegExp(`\\b${section}\\s*[:\\?]`)
+      if (!sectionRegex.test(content)) {
+        missingSections.push(section)
+      }
+    }
+
+    if (missingSections.length > 0) {
+      findings.push({
+        file,
+        severity: 'medium',
+        message: `TetraAppConfig missing section(s): ${missingSections.join(', ')}`,
+        rule: 'incomplete-config',
+        fix: `Add ${missingSections.map(s => `${s}: { ... }`).join(', ')} to your TetraAppConfig`,
+      })
+    }
+  }
+
+  if (!foundConfig) {
+    findings.push({
+      severity: 'high',
+      message: 'No TetraAppConfig found — project should define a typed config for AppShell integration',
+      rule: 'no-tetra-config',
+      fix: 'Create a config file with `const config: TetraAppConfig = { branding, navigation, layout, theme, features }`',
+    })
+  }
+
+  return findings
+}
+
+// ============================================================================
+// CHECK 5: Version check
+// ============================================================================
+
+function checkTetraUiVersion(projectRoot) {
+  const findings = []
+
+  const pkgJsonPath = join(projectRoot, 'frontend', 'package.json')
+  const altPkgJsonPath = join(projectRoot, 'package.json')
+
+  const pkgContent = readFileSafe(pkgJsonPath) || readFileSafe(altPkgJsonPath)
+  if (!pkgContent) {
+    findings.push({
+      severity: 'low',
+      message: 'Could not read package.json to check tetra-ui version',
+      rule: 'version-check-skipped',
+    })
+    return findings
+  }
+
+  let pkg
+  try {
+    pkg = JSON.parse(pkgContent)
+  } catch {
+    return findings
+  }
+
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies }
+  const tetraSpec = deps['@soulbatical/tetra-ui']
+
+  if (!tetraSpec) {
+    findings.push({
+      severity: 'high',
+      message: '@soulbatical/tetra-ui is not listed as a dependency',
+      rule: 'tetra-ui-not-installed',
+      fix: 'Run npm install @soulbatical/tetra-ui',
+    })
+    return findings
+  }
+
+  // Check installed version from node_modules
+  const installedPkgPath = join(projectRoot, 'frontend', 'node_modules', '@soulbatical', 'tetra-ui', 'package.json')
+  const altInstalledPkgPath = join(projectRoot, 'node_modules', '@soulbatical', 'tetra-ui', 'package.json')
+  const installedPkg = readFileSafe(installedPkgPath) || readFileSafe(altInstalledPkgPath)
+
+  let installedVersion = null
+  if (installedPkg) {
+    try {
+      installedVersion = JSON.parse(installedPkg).version
+    } catch { /* ignore */ }
+  }
+
+  // Try to get latest published version (best effort, using execFileSync to avoid shell injection)
+  let latestVersion = null
+  try {
+    latestVersion = execFileSync('npm', ['view', '@soulbatical/tetra-ui', 'version'], {
+      timeout: 10000,
+      encoding: 'utf-8',
+    }).trim()
+  } catch {
+    // Network or registry not available — skip
+  }
+
+  if (installedVersion && latestVersion && installedVersion !== latestVersion) {
+    const installed = installedVersion.split('.').map(Number)
+    const latest = latestVersion.split('.').map(Number)
+    const isOutdated =
+      installed[0] < latest[0] ||
+      (installed[0] === latest[0] && installed[1] < latest[1]) ||
+      (installed[0] === latest[0] && installed[1] === latest[1] && installed[2] < latest[2])
+
+    if (isOutdated) {
+      findings.push({
+        severity: installed[0] < latest[0] ? 'high' : 'medium',
+        message: `@soulbatical/tetra-ui is outdated: installed ${installedVersion}, latest ${latestVersion}`,
+        rule: 'tetra-ui-outdated',
+        fix: `Run npm install @soulbatical/tetra-ui@${latestVersion}`,
+      })
+    }
+  } else if (installedVersion) {
+    findings.push({
+      severity: 'low',
+      message: `@soulbatical/tetra-ui version ${installedVersion} installed (could not verify latest)`,
+      rule: 'version-info',
+    })
+  }
+
+  return findings
+}
+
+// ============================================================================
+// MAIN CHECK
+// ============================================================================
+
+export async function run(config, projectRoot) {
+  const result = {
+    passed: true,
+    findings: [],
+    summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 },
+    details: {
+      globalsCss: { checked: false, issues: 0 },
+      appShell: { checked: false, issues: 0 },
+      configConsistency: { checked: false, issues: 0 },
+      configCompleteness: { checked: false, issues: 0 },
+      versionCheck: { checked: false, issues: 0 },
+    }
+  }
+
+  const frontendDir = findFrontendDir(projectRoot)
+  if (!frontendDir) {
+    result.findings.push({
+      file: 'project',
+      line: 0,
+      severity: 'low',
+      message: 'No frontend source directory found — skipping AppShell compliance check',
+    })
+    return result
+  }
+
+  // ── 1. globals.css ──
+  const cssFindings = checkGlobalsCss(frontendDir)
+  result.details.globalsCss.checked = true
+  result.details.globalsCss.issues = cssFindings.length
+  for (const f of cssFindings) {
+    result.summary[f.severity] = (result.summary[f.severity] || 0) + 1
+    result.summary.total++
+    result.findings.push({ file: 'globals.css', line: 0, ...f })
+  }
+
+  // ── 2. AppShell usage ──
+  const shellFindings = checkAppShellUsage(frontendDir)
+  result.details.appShell.checked = true
+  result.details.appShell.issues = shellFindings.length
+  for (const f of shellFindings) {
+    result.summary[f.severity] = (result.summary[f.severity] || 0) + 1
+    result.summary.total++
+    result.findings.push({ file: 'project', line: 0, ...f })
+  }
+
+  // ── 3. Config consistency ──
+  const consistencyFindings = checkConfigConsistency(frontendDir)
+  result.details.configConsistency.checked = true
+  result.details.configConsistency.issues = consistencyFindings.length
+  for (const f of consistencyFindings) {
+    result.summary[f.severity] = (result.summary[f.severity] || 0) + 1
+    result.summary.total++
+    result.findings.push({ line: 0, ...f })
+  }
+
+  // ── 4. Config completeness ──
+  const completenessFindings = checkConfigCompleteness(frontendDir)
+  result.details.configCompleteness.checked = true
+  result.details.configCompleteness.issues = completenessFindings.length
+  for (const f of completenessFindings) {
+    result.summary[f.severity] = (result.summary[f.severity] || 0) + 1
+    result.summary.total++
+    result.findings.push({ file: 'project', line: 0, ...f })
+  }
+
+  // ── 5. Version check ──
+  const versionFindings = checkTetraUiVersion(projectRoot)
+  result.details.versionCheck.checked = true
+  result.details.versionCheck.issues = versionFindings.length
+  for (const f of versionFindings) {
+    result.summary[f.severity] = (result.summary[f.severity] || 0) + 1
+    result.summary.total++
+    result.findings.push({ file: 'package.json', line: 0, ...f })
+  }
+
+  // ── Determine pass/fail ──
+  result.passed = result.summary.critical === 0 && result.summary.high === 0
+
+  // ── Summary finding ──
+  if (!result.passed) {
+    const d = result.details
+    result.findings.unshift({
+      file: 'project',
+      line: 0,
+      severity: 'high',
+      message: [
+        `AppShell compliance FAILED:`,
+        `globals.css: ${d.globalsCss.issues} issue(s),`,
+        `AppShell: ${d.appShell.issues} issue(s),`,
+        `Config consistency: ${d.configConsistency.issues} issue(s),`,
+        `Config completeness: ${d.configCompleteness.issues} issue(s),`,
+        `Version: ${d.versionCheck.issues} issue(s).`,
+        `Fix: ensure globals.css has @theme inline + :root --tetra-* tokens,`,
+        `use AppShell from @soulbatical/tetra-ui, and define a complete TetraAppConfig.`,
+      ].join(' '),
+    })
+  }
+
+  return result
+}

package/lib/checks/health/deploy-readiness.js

@@ -0,0 +1,222 @@
+/**
+ * Health Check: Deploy Readiness for Private Packages
+ *
+ * Verifies that a project is correctly configured to deploy with
+ * @soulbatical private npm packages on Railway and Netlify.
+ *
+ * Checks:
+ * 1. .npmrc exists with @soulbatical scope + ${NPM_TOKEN} auth
+ * 2. No file: references to @soulbatical packages (breaks CI/CD)
+ * 3. Railway projects have a Dockerfile with npm auth step
+ * 4. Dockerfile ARG NPM_TOKEN + .npmrc creation happens BEFORE npm install
+ *
+ * Score: 0-4 (1 per aspect)
+ * Skipped if project has no @soulbatical dependencies.
+ */
+
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { createCheck } from './types.js'
+
+const SOULBATICAL_PACKAGES = [
+  '@soulbatical/tetra-core',
+  '@soulbatical/tetra-ui',
+  '@soulbatical/tetra-dev-toolkit',
+  '@soulbatical/stella'
+]
+
+/**
+ * Collect all @soulbatical dependency references from a project's package.json files
+ */
+function findSoulbaticalDeps(projectPath) {
+  const pkgPaths = [
+    { path: join(projectPath, 'package.json'), label: 'root' },
+    { path: join(projectPath, 'backend', 'package.json'), label: 'backend' },
+    { path: join(projectPath, 'frontend', 'package.json'), label: 'frontend' },
+    { path: join(projectPath, 'backend-mcp', 'package.json'), label: 'backend-mcp' },
+    { path: join(projectPath, 'bot', 'package.json'), label: 'bot' }
+  ]
+
+  const deps = []
+  const fileRefs = []
+
+  for (const { path: pkgPath, label } of pkgPaths) {
+    if (!existsSync(pkgPath)) continue
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+      const allDeps = { ...pkg.dependencies, ...pkg.devDependencies }
+
+      for (const [name, version] of Object.entries(allDeps)) {
+        if (!name.startsWith('@soulbatical/')) continue
+        deps.push({ name, version, location: label })
+
+        if (version.startsWith('file:') || version.startsWith('link:')) {
+          fileRefs.push({ name, version, location: label })
+        }
+      }
+    } catch { /* ignore */ }
+  }
+
+  return { deps, fileRefs }
+}
+
+/**
+ * Check if .npmrc has proper config for private packages
+ */
+function checkNpmrc(projectPath) {
+  const npmrcPath = join(projectPath, '.npmrc')
+  if (!existsSync(npmrcPath)) return { exists: false, hasAuth: false, hasScope: false, content: '' }
+
+  const content = readFileSync(npmrcPath, 'utf-8')
+  return {
+    exists: true,
+    hasAuth: content.includes('_authToken=${NPM_TOKEN}') || content.includes('_authToken=$NPM_TOKEN'),
+    hasScope: content.includes('@soulbatical:registry='),
+    content
+  }
+}
+
+/**
+ * Check if Dockerfile has proper npm auth for private packages
+ */
+function checkDockerfile(projectPath) {
+  // Check common Dockerfile locations
+  const dockerfiles = [
+    join(projectPath, 'Dockerfile'),
+    join(projectPath, 'Dockerfile.prod'),
+    join(projectPath, 'backend', 'Dockerfile')
+  ]
+
+  for (const dfPath of dockerfiles) {
+    if (!existsSync(dfPath)) continue
+    const content = readFileSync(dfPath, 'utf-8')
+
+    const hasArgNpmToken = /ARG\s+NPM_TOKEN/i.test(content)
+    const hasNpmrcCreation = content.includes('.npmrc') && content.includes('authToken')
+    const hasNpmInstall = /npm\s+(ci|install)/i.test(content)
+
+    // Check ordering: .npmrc creation should be BEFORE npm install
+    let orderCorrect = false
+    if (hasNpmrcCreation && hasNpmInstall) {
+      const npmrcPos = content.indexOf('.npmrc')
+      const installPos = content.search(/npm\s+(ci|install)/i)
+      orderCorrect = npmrcPos < installPos
+    }
+
+    return {
+      exists: true,
+      path: dfPath,
+      hasArgNpmToken,
+      hasNpmrcCreation,
+      hasNpmInstall,
+      orderCorrect
+    }
+  }
+
+  return { exists: false }
+}
+
+/**
+ * Detect if project deploys to Railway (has railway config or infrastructure hints)
+ */
+function isRailwayProject(projectPath) {
+  if (existsSync(join(projectPath, 'railway.json'))) return true
+  if (existsSync(join(projectPath, 'railway.toml'))) return true
+
+  // Check INFRASTRUCTURE.yml for Railway hosting
+  const infraPath = join(projectPath, '.ralph', 'INFRASTRUCTURE.yml')
+  if (existsSync(infraPath)) {
+    try {
+      const content = readFileSync(infraPath, 'utf-8')
+      if (content.toLowerCase().includes('railway')) return true
+    } catch { /* ignore */ }
+  }
+
+  return false
+}
+
+export async function check(projectPath) {
+  const result = createCheck('deploy-readiness', 4, {
+    hasSoulbaticalDeps: false,
+    soulbaticalDeps: [],
+    fileRefs: [],
+    npmrc: {},
+    dockerfile: {},
+    isRailway: false,
+    skipped: false
+  })
+
+  // Find @soulbatical dependencies
+  const { deps, fileRefs } = findSoulbaticalDeps(projectPath)
+  result.details.soulbaticalDeps = deps
+  result.details.fileRefs = fileRefs
+
+  // Skip if no @soulbatical dependencies
+  if (deps.length === 0) {
+    result.details.skipped = true
+    result.details.message = 'No @soulbatical dependencies — check skipped'
+    result.score = result.maxScore // Full score if not applicable
+    return result
+  }
+
+  result.details.hasSoulbaticalDeps = true
+  const isRailway = isRailwayProject(projectPath)
+  result.details.isRailway = isRailway
+
+  // --- Check 1: .npmrc exists with auth + scope (+1 point) ---
+  const npmrc = checkNpmrc(projectPath)
+  result.details.npmrc = npmrc
+
+  if (npmrc.exists && npmrc.hasAuth && npmrc.hasScope) {
+    result.score += 1
+  } else if (npmrc.exists && npmrc.hasAuth) {
+    result.score += 0.5 // Auth OK but missing scope
+  }
+
+  // --- Check 2: No file: references (+1 point) ---
+  if (fileRefs.length === 0) {
+    result.score += 1
+  }
+
+  // --- Check 3: Railway projects need Dockerfile (+1 point) ---
+  if (isRailway) {
+    const df = checkDockerfile(projectPath)
+    result.details.dockerfile = df
+
+    if (df.exists && df.hasArgNpmToken && df.hasNpmrcCreation && df.orderCorrect) {
+      result.score += 1
+    } else if (df.exists && df.hasNpmInstall) {
+      result.score += 0.5 // Dockerfile exists but missing npm auth
+    }
+  } else {
+    result.score += 1 // Not Railway — full score for this check
+  }
+
+  // --- Check 4: Overall deploy confidence (+1 point) ---
+  // All non-dev @soulbatical deps use semver (not file:, not link:)
+  const nonDevFileRefs = fileRefs.filter(r => r.location !== 'root') // root devDeps are OK locally
+  const allSemver = nonDevFileRefs.length === 0
+  const npmrcReady = npmrc.exists && npmrc.hasAuth
+  const dockerReady = !isRailway || (result.details.dockerfile.exists && result.details.dockerfile.hasArgNpmToken)
+
+  if (allSemver && npmrcReady && dockerReady) {
+    result.score += 1
+  }
+
+  result.score = Math.min(result.score, result.maxScore)
+
+  // Summary message
+  if (result.score < result.maxScore) {
+    result.status = 'warning'
+    const issues = []
+    if (!npmrc.exists) issues.push('missing .npmrc')
+    else if (!npmrc.hasAuth) issues.push('.npmrc missing ${NPM_TOKEN} auth')
+    else if (!npmrc.hasScope) issues.push('.npmrc missing @soulbatical:registry scope')
+    if (fileRefs.length > 0) issues.push(`${fileRefs.length} file: ref(s) to @soulbatical packages — will break CI/CD`)
+    if (isRailway && !result.details.dockerfile.exists) issues.push('Railway project without Dockerfile �� private packages will fail')
+    else if (isRailway && !result.details.dockerfile.hasArgNpmToken) issues.push('Dockerfile missing ARG NPM_TOKEN')
+    result.details.message = issues.join(', ')
+  }
+
+  return result
+}

package/lib/checks/health/file-organization.js

@@ -102,9 +102,15 @@ const ROOT_CLUTTER_DIRS = new Set([
 ])
 
 /**
- * Recursively find files matching a predicate, respecting ignored dirs
+ * Recursively find files matching a predicate, respecting ignored dirs.
+ * @param {string} dir - Directory to scan
+ * @param {Function} predicate - (name, fullPath) => boolean
+ * @param {number} maxDepth - Max recursion depth
+ * @param {number} currentDepth - Current depth
+ * @param {string} rootPath - Project root (for relative path matching against gitignore)
+ * @param {Set<string>} gitignored - Gitignored path patterns from .gitignore
  */
-function findFiles(dir, predicate, maxDepth = 5, currentDepth = 0) {
+function findFiles(dir, predicate, maxDepth = 5, currentDepth = 0, rootPath = dir, gitignored = new Set()) {
   const results = []
   if (currentDepth >= maxDepth) return results
 
@@ -117,7 +123,10 @@ function findFiles(dir, predicate, maxDepth = 5, currentDepth = 0) {
 
     const fullPath = join(dir, name)
     if (entry.isDirectory()) {
-      results.push(...findFiles(fullPath, predicate, maxDepth, currentDepth + 1))
+      // Skip directories matched by .gitignore entries
+      const relPath = relative(rootPath, fullPath)
+      if (gitignored.has(name) || gitignored.has(relPath)) continue
+      results.push(...findFiles(fullPath, predicate, maxDepth, currentDepth + 1, rootPath, gitignored))
     } else if (entry.isFile() && predicate(name, fullPath)) {
       results.push(fullPath)
     }
@@ -132,7 +141,7 @@ const ALLOWED_NESTED_DOCS_PARENTS = new Set(['.ralph'])
  * Find directories named "docs" that are not at the repo root,
  * excluding allowed parents like .ralph/docs
  */
-function findNestedDocsDirs(rootPath, currentDir, maxDepth = 4, currentDepth = 0) {
+function findNestedDocsDirs(rootPath, currentDir, maxDepth = 4, currentDepth = 0, gitignored = new Set()) {
   const results = []
   if (currentDepth >= maxDepth) return results
 
@@ -146,6 +155,9 @@ function findNestedDocsDirs(rootPath, currentDir, maxDepth = 4, currentDepth = 0
 
     const fullPath = join(currentDir, name)
     const relFromRoot = relative(rootPath, fullPath)
+
+    // Skip gitignored directories
+    if (gitignored.has(name) || gitignored.has(relFromRoot)) continue
     const topDir = relFromRoot.split('/')[0]
 
     if (name === 'docs' && currentDepth > 0) {
@@ -154,7 +166,7 @@ function findNestedDocsDirs(rootPath, currentDir, maxDepth = 4, currentDepth = 0
         results.push(fullPath)
       }
     } else {
-      results.push(...findNestedDocsDirs(rootPath, fullPath, maxDepth, currentDepth + 1))
+      results.push(...findNestedDocsDirs(rootPath, fullPath, maxDepth, currentDepth + 1, gitignored))
     }
   }
   return results
@@ -192,7 +204,7 @@ export async function check(projectPath) {
   }
 
   // --- Check 1: Stray .md files ---
-  const allMdFiles = findFiles(projectPath, (name) => name.endsWith('.md'))
+  const allMdFiles = findFiles(projectPath, (name) => name.endsWith('.md'), 5, 0, projectPath, gitignoredDirs)
   const strayMd = []
 
   for (const file of allMdFiles) {
@@ -224,7 +236,7 @@ export async function check(projectPath) {
   result.details.totalStrayMd = strayMd.length
 
   // --- Check 2: Stray scripts ---
-  const allScripts = findFiles(projectPath, (name) => name.endsWith('.sh'))
+  const allScripts = findFiles(projectPath, (name) => name.endsWith('.sh'), 5, 0, projectPath, gitignoredDirs)
   const strayScripts = []
 
   for (const file of allScripts) {
@@ -246,7 +258,7 @@ export async function check(projectPath) {
   result.details.totalStrayScripts = strayScripts.length
 
   // --- Check 3: Stray config files (.yml/.yaml) ---
-  const allConfigs = findFiles(projectPath, (name) => name.endsWith('.yml') || name.endsWith('.yaml'))
+  const allConfigs = findFiles(projectPath, (name) => name.endsWith('.yml') || name.endsWith('.yaml'), 5, 0, projectPath, gitignoredDirs)
   const strayConfigs = []
 
   for (const file of allConfigs) {
@@ -352,7 +364,7 @@ export async function check(projectPath) {
   result.details.totalRootClutter = rootClutter.length
 
   // --- Check 6: Nested docs/ directories ---
-  const nestedDocs = findNestedDocsDirs(projectPath, projectPath)
+  const nestedDocs = findNestedDocsDirs(projectPath, projectPath, 4, 0, gitignoredDirs)
   const nestedDocsRel = nestedDocs.map(d => relative(projectPath, d))
 
   result.details.nestedDocsDirs = nestedDocsRel

package/lib/checks/health/gitignore.js

@@ -18,7 +18,8 @@ const CRITICAL = [
 const RECOMMENDED = [
   { name: 'credential files (*.pem, *.key)', patterns: ['*.pem', '*.key'] },
   { name: 'Supabase temp', patterns: ['.supabase', 'supabase/.temp'] },
-  { name: '.DS_Store', patterns: ['.DS_Store'] }
+  { name: '.DS_Store', patterns: ['.DS_Store'] },
+  { name: 'Ralph runtime state (.ralph/)', patterns: ['.ralph'] }
 ]
 
 function isCovered(lines, pattern) {

package/lib/checks/health/index.js

@@ -43,3 +43,4 @@ 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'
+export { check as checkDeployReadiness } from './deploy-readiness.js'

package/lib/checks/health/scanner.js

@@ -39,6 +39,7 @@ 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 { check as checkDeployReadiness } from './deploy-readiness.js'
 import { calculateHealthStatus } from './types.js'
 
 /**
@@ -86,7 +87,8 @@ export async function scanProjectHealth(projectPath, projectName, options = {})
     checkReleasePipeline(projectPath),
     checkTestStructure(projectPath),
     checkSentryMonitoring(projectPath),
-    checkShadcnUiTokens(projectPath)
+    checkShadcnUiTokens(projectPath),
+    checkDeployReadiness(projectPath)
   ])
 
   const totalScore = checks.reduce((sum, c) => sum + c.score, 0)

package/lib/checks/index.js

@@ -19,6 +19,7 @@ export * as rpcParamMismatch from './supabase/rpc-param-mismatch.js'
 export * as rpcGeneratorOrigin from './supabase/rpc-generator-origin.js'
 
 // Code quality checks
+export * as appshellCompliance from './codeQuality/appshell-compliance.js'
 export * as uiTheming from './codeQuality/ui-theming.js'
 export * as barrelImportDetector from './codeQuality/barrel-import-detector.js'
 export * as typescriptStrictness from './codeQuality/typescript-strictness.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulbatical/tetra-dev-toolkit",
-  "version": "1.20.21",
+  "version": "1.20.22",
   "publishConfig": {
     "access": "restricted"
   },