@soulbatical/tetra-dev-toolkit 1.20.21 → 1.20.23

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.23",
   "publishConfig": {
     "access": "restricted"
   },
@@ -43,7 +43,8 @@
     "tetra-test-audit": "./bin/tetra-test-audit.js",
     "tetra-check-pages": "./bin/tetra-check-pages.js",
     "tetra-check-views": "./bin/tetra-check-views.js",
-    "tetra-doctor": "./bin/tetra-doctor.js"
+    "tetra-doctor": "./bin/tetra-doctor.js",
+    "tetra-style-audit": "./bin/tetra-style-audit.js"
   },
   "files": [
     "bin/",