@soulbatical/tetra-dev-toolkit 1.22.0 → 1.22.2

package/README.md

@@ -74,6 +74,9 @@ LAYER 8: DB HELPERS            adminDB/userDB/publicDB/systemDB enforce correct
 | `tetra-setup` | Install hooks, CI, and config |
 | `tetra-init` | Initialize project config files |
 | `tetra-dev-token` | Generate development tokens |
+| `tetra-license generate` | Generate a Tetra license key |
+| `tetra-license verify` | Verify a license key (or `TETRA_LICENSE_KEY` env) |
+| `tetra-license decode` | Decode key payload without validation |
 
 Exit codes: `0` = passed, `1` = failed (CRITICAL/HIGH), `2` = error. No middle ground.
 

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

@@ -1,14 +1,14 @@
 /**
- * Health Check: Deploy Readiness for Private Packages
+ * Health Check: Deploy Readiness for @soulbatical packages
  *
- * Verifies that a project is correctly configured to deploy with
- * @soulbatical private npm packages on Railway and Netlify.
+ * All @soulbatical packages are PUBLIC on npm since April 2026.
+ * No .npmrc, no NPM_TOKEN, no Dockerfile auth needed.
  *
  * 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
+ * 1. No file: or link: references to @soulbatical packages (breaks CI/CD)
+ * 2. No leftover .npmrc with authToken (should be removed)
+ * 3. No leftover Dockerfile ARG NPM_TOKEN (not needed for public packages)
+ * 4. Version minimums: core >= 0.4.0, ui >= 0.10.0, dev-toolkit >= 1.22.0
  *
  * Score: 0-4 (1 per aspect)
  * Skipped if project has no @soulbatical dependencies.
@@ -18,12 +18,11 @@ 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'
-]
+const MIN_VERSIONS = {
+  '@soulbatical/tetra-core': '0.4.0',
+  '@soulbatical/tetra-ui': '0.10.0',
+  '@soulbatical/tetra-dev-toolkit': '1.22.0',
+}
 
 /**
  * Collect all @soulbatical dependency references from a project's package.json files
@@ -39,6 +38,7 @@ function findSoulbaticalDeps(projectPath) {
 
   const deps = []
   const fileRefs = []
+  const outdated = []
 
   for (const { path: pkgPath, label } of pkgPaths) {
     if (!existsSync(pkgPath)) continue
@@ -53,86 +53,81 @@ function findSoulbaticalDeps(projectPath) {
         if (version.startsWith('file:') || version.startsWith('link:')) {
           fileRefs.push({ name, version, location: label })
         }
+
+        // Check version minimums
+        const minVersion = MIN_VERSIONS[name]
+        if (minVersion && version.startsWith('^')) {
+          const specified = version.slice(1) // remove ^
+          if (compareVersions(specified, minVersion) < 0) {
+            outdated.push({ name, version, minRequired: `^${minVersion}`, location: label })
+          }
+        }
       }
     } catch { /* ignore */ }
   }
 
-  return { deps, fileRefs }
+  return { deps, fileRefs, outdated }
 }
 
 /**
- * Check if .npmrc has proper config for private packages
+ * Simple semver comparison (major.minor.patch)
+ * Returns: -1 if a < b, 0 if equal, 1 if a > b
  */
-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
+function compareVersions(a, b) {
+  const pa = a.split('.').map(Number)
+  const pb = b.split('.').map(Number)
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) < (pb[i] || 0)) return -1
+    if ((pa[i] || 0) > (pb[i] || 0)) return 1
   }
+  return 0
 }
 
 /**
- * Check if Dockerfile has proper npm auth for private packages
+ * Check for leftover .npmrc files with authToken (should be removed)
  */
-function checkDockerfile(projectPath) {
-  // Check common Dockerfile locations
-  const dockerfiles = [
-    join(projectPath, 'Dockerfile'),
-    join(projectPath, 'Dockerfile.prod'),
-    join(projectPath, 'backend', 'Dockerfile')
+function checkLeftoverNpmrc(projectPath) {
+  const locations = [
+    join(projectPath, '.npmrc'),
+    join(projectPath, 'backend', '.npmrc'),
+    join(projectPath, 'frontend', '.npmrc'),
+    join(projectPath, 'backend-mcp', '.npmrc'),
   ]
 
-  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
-    }
+  const leftovers = []
+  for (const npmrcPath of locations) {
+    if (!existsSync(npmrcPath)) continue
+    try {
+      const content = readFileSync(npmrcPath, 'utf-8')
+      if (content.includes('authToken') || content.includes('_authToken')) {
+        leftovers.push(npmrcPath.replace(projectPath + '/', ''))
+      }
+    } catch { /* ignore */ }
   }
-
-  return { exists: false }
+  return leftovers
 }
 
 /**
- * Detect if project deploys to Railway (has railway config or infrastructure hints)
+ * Check for leftover Dockerfile ARG NPM_TOKEN
  */
-function isRailwayProject(projectPath) {
-  if (existsSync(join(projectPath, 'railway.json'))) return true
-  if (existsSync(join(projectPath, 'railway.toml'))) return true
+function checkLeftoverDockerfileAuth(projectPath) {
+  const dockerfiles = [
+    join(projectPath, 'Dockerfile'),
+    join(projectPath, 'Dockerfile.prod'),
+    join(projectPath, 'backend', 'Dockerfile')
+  ]
 
-  // Check INFRASTRUCTURE.yml for Railway hosting
-  const infraPath = join(projectPath, '.ralph', 'INFRASTRUCTURE.yml')
-  if (existsSync(infraPath)) {
+  const leftovers = []
+  for (const dfPath of dockerfiles) {
+    if (!existsSync(dfPath)) continue
     try {
-      const content = readFileSync(infraPath, 'utf-8')
-      if (content.toLowerCase().includes('railway')) return true
+      const content = readFileSync(dfPath, 'utf-8')
+      if (/ARG\s+NPM_TOKEN/i.test(content)) {
+        leftovers.push(dfPath.replace(projectPath + '/', ''))
+      }
     } catch { /* ignore */ }
   }
-
-  return false
+  return leftovers
 }
 
 export async function check(projectPath) {
@@ -140,66 +135,49 @@ export async function check(projectPath) {
     hasSoulbaticalDeps: false,
     soulbaticalDeps: [],
     fileRefs: [],
-    npmrc: {},
-    dockerfile: {},
-    isRailway: false,
+    outdated: [],
+    leftoverNpmrc: [],
+    leftoverDockerfileAuth: [],
     skipped: false
   })
 
   // Find @soulbatical dependencies
-  const { deps, fileRefs } = findSoulbaticalDeps(projectPath)
+  const { deps, fileRefs, outdated } = findSoulbaticalDeps(projectPath)
   result.details.soulbaticalDeps = deps
   result.details.fileRefs = fileRefs
+  result.details.outdated = outdated
 
   // 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
+    result.score = result.maxScore
     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) {
+  // --- Check 1: No file: references (+1 point) ---
+  if (fileRefs.length === 0) {
     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) {
+  // --- Check 2: No leftover .npmrc with authToken (+1 point) ---
+  const leftoverNpmrc = checkLeftoverNpmrc(projectPath)
+  result.details.leftoverNpmrc = leftoverNpmrc
+  if (leftoverNpmrc.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 3: No leftover Dockerfile ARG NPM_TOKEN (+1 point) ---
+  const leftoverDockerfile = checkLeftoverDockerfileAuth(projectPath)
+  result.details.leftoverDockerfileAuth = leftoverDockerfile
+  if (leftoverDockerfile.length === 0) {
+    result.score += 1
   }
 
-  // --- 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) {
+  // --- Check 4: Version minimums met (+1 point) ---
+  if (outdated.length === 0) {
     result.score += 1
   }
 
@@ -209,13 +187,13 @@ export async function check(projectPath) {
   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(', ')
+    if (fileRefs.length > 0) issues.push(`${fileRefs.length} file: ref(s) — will break CI/CD`)
+    if (leftoverNpmrc.length > 0) issues.push(`leftover .npmrc with authToken: ${leftoverNpmrc.join(', ')} — remove it (packages are public)`)
+    if (leftoverDockerfile.length > 0) issues.push(`leftover ARG NPM_TOKEN in: ${leftoverDockerfile.join(', ')} — remove it (packages are public)`)
+    if (outdated.length > 0) issues.push(`outdated: ${outdated.map(d => `${d.name}@${d.version} (need ${d.minRequired})`).join(', ')}`)
+    result.details.message = issues.join('; ')
+  } else {
+    result.details.message = `${deps.length} @soulbatical package(s) — all public, no auth needed, versions OK`
   }
 
   return result

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

@@ -28,7 +28,7 @@ const ALLOWED_ROOT_MD = new Set([
 
 const IGNORED_DIRS = new Set([
   'node_modules', 'dist', 'build', '.git', '.next', '.cache', '.turbo',
-  'coverage', '.nyc_output', '.playwright', 'test-results'
+  'coverage', '.nyc_output', '.playwright', 'test-results', '.netlify'
 ])
 
 const ALLOWED_SCRIPT_DIRS = new Set([
@@ -37,7 +37,7 @@ const ALLOWED_SCRIPT_DIRS = new Set([
 
 /** Directories whose .md content is always allowed (tooling config) */
 const ALLOWED_MD_DIRS = new Set([
-  'docs', '.ralph', '.claude', '.agents', 'e2e', 'tests'
+  'docs', '.ralph', '.claude', '.agents', 'e2e', 'tests', 'shell'
 ])
 
 /** Directories where .yml/.yaml config files are allowed */

package/package.json

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