@soulbatical/tetra-dev-toolkit 1.21.0 → 1.22.0

package/bin/tetra-license.js

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+
+/**
+ * Tetra Dev Toolkit - License Key CLI
+ *
+ * Generate and verify Tetra license keys.
+ *
+ * Usage:
+ *   tetra-license generate --customer "Acme BV" --order ORD-2026-001 --plan pro --expiry 2027-04-09
+ *   tetra-license verify <key>
+ *   tetra-license verify              # reads TETRA_LICENSE_KEY env var
+ *   tetra-license decode <key>        # show payload without HMAC validation
+ */
+
+import { program } from 'commander'
+import chalk from 'chalk'
+import crypto from 'node:crypto'
+
+// ─── Inline license logic (dev-toolkit has no tetra-core dependency) ───
+
+const KEY_VERSION = 1
+const KEY_SEPARATOR = '.'
+const HMAC_ALGORITHM = 'sha256'
+const SIGNING_SECRET = 'tetra-license-v1-soulbatical-bv-2026'
+
+const PLAN_HIERARCHY = { starter: 0, pro: 1, enterprise: 2 }
+
+function generateKey({ orderId, customer, plan, scope, model, expiryDate }) {
+  const payload = {
+    orderId,
+    customer,
+    plan,
+    scope: scope || ['core', 'ui'],
+    model: model || 'perpetual',
+    expiry: new Date(expiryDate).getTime(),
+    keyVersion: KEY_VERSION,
+  }
+  if (isNaN(payload.expiry)) throw new Error(`Invalid expiry date: ${expiryDate}`)
+  const payloadBase64 = Buffer.from(JSON.stringify(payload)).toString('base64url')
+  const hmac = crypto.createHmac(HMAC_ALGORITHM, SIGNING_SECRET).update(payloadBase64).digest('hex')
+  return `${hmac}${KEY_SEPARATOR}${payloadBase64}`
+}
+
+function decodeKey(key) {
+  try {
+    const sep = key.indexOf(KEY_SEPARATOR)
+    if (sep === -1) return null
+    const json = Buffer.from(key.slice(sep + 1), 'base64url').toString('utf8')
+    return JSON.parse(json)
+  } catch { return null }
+}
+
+function verifyKey(key) {
+  const sep = key.indexOf(KEY_SEPARATOR)
+  if (sep === -1) return { valid: false, reason: 'Invalid format' }
+  const hmacProvided = key.slice(0, sep)
+  const payloadBase64 = key.slice(sep + 1)
+  const hmacComputed = crypto.createHmac(HMAC_ALGORITHM, SIGNING_SECRET).update(payloadBase64).digest('hex')
+  try {
+    if (!crypto.timingSafeEqual(Buffer.from(hmacProvided, 'hex'), Buffer.from(hmacComputed, 'hex'))) {
+      return { valid: false, reason: 'HMAC mismatch — key has been tampered with' }
+    }
+  } catch {
+    return { valid: false, reason: 'HMAC mismatch — invalid key' }
+  }
+  const payload = decodeKey(key)
+  if (!payload) return { valid: false, reason: 'Payload decode failed' }
+  return { valid: true, payload }
+}
+
+// ─── Commands ────────────────────────────────────────────────
+
+program
+  .name('tetra-license')
+  .description('Generate and verify Tetra license keys')
+  .version('1.0.0')
+
+program
+  .command('generate')
+  .description('Generate a new license key')
+  .requiredOption('--customer <name>', 'Customer name')
+  .requiredOption('--order <id>', 'Order ID (e.g., ORD-2026-001)')
+  .requiredOption('--plan <plan>', 'Plan tier: starter, pro, enterprise')
+  .requiredOption('--expiry <date>', 'Expiry date (ISO format, e.g., 2027-04-09)')
+  .option('--scope <scopes>', 'Comma-separated scopes (default: core,ui)', 'core,ui')
+  .option('--model <model>', 'Licensing model: perpetual or subscription (default: perpetual)', 'perpetual')
+  .action((options) => {
+    try {
+      if (!['starter', 'pro', 'enterprise'].includes(options.plan)) {
+        console.error(chalk.red(`Invalid plan: ${options.plan}. Must be starter, pro, or enterprise.`))
+        process.exit(1)
+      }
+      if (!['perpetual', 'subscription'].includes(options.model)) {
+        console.error(chalk.red(`Invalid model: ${options.model}. Must be perpetual or subscription.`))
+        process.exit(1)
+      }
+
+      const key = generateKey({
+        orderId: options.order,
+        customer: options.customer,
+        plan: options.plan,
+        scope: options.scope.split(','),
+        model: options.model,
+        expiryDate: options.expiry,
+      })
+
+      const payload = decodeKey(key)
+      const expiryDate = new Date(payload.expiry).toISOString().split('T')[0]
+
+      console.log()
+      console.log(chalk.green.bold('✓ License key generated'))
+      console.log()
+      console.log(chalk.dim('─'.repeat(60)))
+      console.log(chalk.bold('Key:       '), key)
+      console.log(chalk.dim('─'.repeat(60)))
+      console.log(chalk.bold('Customer:  '), payload.customer)
+      console.log(chalk.bold('Order:     '), payload.orderId)
+      console.log(chalk.bold('Plan:      '), chalk.cyan(payload.plan))
+      console.log(chalk.bold('Scope:     '), payload.scope.join(', '))
+      console.log(chalk.bold('Model:     '), payload.model)
+      console.log(chalk.bold('Expiry:    '), expiryDate)
+      console.log(chalk.bold('Version:   '), `v${payload.keyVersion}`)
+      console.log()
+      console.log(chalk.dim('Set this in the customer\'s environment:'))
+      console.log(chalk.yellow(`  TETRA_LICENSE_KEY=${key}`))
+      console.log(chalk.dim('For frontend (Next.js):'))
+      console.log(chalk.yellow(`  NEXT_PUBLIC_TETRA_LICENSE_KEY=${key}`))
+      console.log()
+    } catch (err) {
+      console.error(chalk.red(`Error: ${err.message}`))
+      process.exit(1)
+    }
+  })
+
+program
+  .command('verify [key]')
+  .description('Verify a license key (reads TETRA_LICENSE_KEY if no key given)')
+  .action((keyArg) => {
+    const key = keyArg || process.env.TETRA_LICENSE_KEY
+    if (!key) {
+      console.error(chalk.red('No key provided. Pass as argument or set TETRA_LICENSE_KEY.'))
+      process.exit(1)
+    }
+
+    const result = verifyKey(key)
+    console.log()
+
+    if (!result.valid) {
+      console.log(chalk.red.bold('✗ Invalid license key'))
+      console.log(chalk.red(`  Reason: ${result.reason}`))
+      console.log()
+      process.exit(1)
+    }
+
+    const { payload } = result
+    const now = Date.now()
+    const daysRemaining = Math.floor((payload.expiry - now) / (1000 * 60 * 60 * 24))
+    const expired = payload.model === 'subscription' ? now > payload.expiry : false
+    const expiryDate = new Date(payload.expiry).toISOString().split('T')[0]
+
+    console.log(expired ? chalk.red.bold('✗ License EXPIRED') : chalk.green.bold('✓ License valid'))
+    console.log()
+    console.log(chalk.bold('Customer:  '), payload.customer)
+    console.log(chalk.bold('Order:     '), payload.orderId)
+    console.log(chalk.bold('Plan:      '), chalk.cyan(payload.plan))
+    console.log(chalk.bold('Scope:     '), payload.scope.join(', '))
+    console.log(chalk.bold('Model:     '), payload.model)
+    console.log(chalk.bold('Expiry:    '), expired ? chalk.red(expiryDate) : expiryDate)
+    console.log(chalk.bold('Remaining: '), daysRemaining > 0
+      ? (daysRemaining <= 30 ? chalk.yellow(`${daysRemaining} days`) : chalk.green(`${daysRemaining} days`))
+      : chalk.red(`expired ${Math.abs(daysRemaining)} days ago`))
+    console.log(chalk.bold('Version:   '), `v${payload.keyVersion}`)
+    console.log()
+  })
+
+program
+  .command('decode [key]')
+  .description('Decode a license key payload (no HMAC validation)')
+  .action((keyArg) => {
+    const key = keyArg || process.env.TETRA_LICENSE_KEY
+    if (!key) {
+      console.error(chalk.red('No key provided.'))
+      process.exit(1)
+    }
+
+    const payload = decodeKey(key)
+    if (!payload) {
+      console.error(chalk.red('Could not decode key payload.'))
+      process.exit(1)
+    }
+
+    console.log()
+    console.log(chalk.bold('Decoded payload:'))
+    console.log(JSON.stringify(payload, null, 2))
+    console.log()
+  })
+
+program.parse()

package/lib/audits/doctor-audit.js

@@ -11,7 +11,7 @@
  */
 
 import { readFileSync, writeFileSync, existsSync } from 'fs'
-import { join } from 'path'
+import { join, resolve, dirname } from 'path'
 import { execSync } from 'child_process'
 import { glob } from 'glob'
 
@@ -419,7 +419,107 @@ function checkDarkMode(files) {
 }
 
 /**
- * HIGH 7: tetra-core version should be recent.
+ * CRITICAL 7: All @source directives in globals.css must resolve to existing paths,
+ * and at least one must point to @soulbatical/tetra-ui/dist so Tailwind v4 generates
+ * AppShell layout utility classes (ml-64, ml-16, etc.).
+ *
+ * Root cause this prevents: a path with one too few `../` segments silently scans
+ * nothing, causing AppShell margins to never be generated and pages to render
+ * underneath the fixed sidebar.
+ */
+function checkTetraUiSourcePath(files, projectRoot) {
+  if (!files.globalsCss) {
+    return {
+      id: 'tetraUiSourcePath',
+      severity: 'critical',
+      label: 'tetra-ui @source path',
+      pass: false,
+      detail: 'globals.css not found',
+      fixable: false,
+    }
+  }
+
+  const globalsCssFullPath = join(projectRoot, files.globalsCss.path)
+  const globalsCssDir = dirname(globalsCssFullPath)
+  const content = files.globalsCss.content
+
+  // Collect all @source directives
+  const sourceRegex = /@source\s+["']([^"']+)["']/g
+  const sourcePaths = []
+  let match
+  while ((match = sourceRegex.exec(content)) !== null) {
+    sourcePaths.push(match[1])
+  }
+
+  if (sourcePaths.length === 0) {
+    // No @source directives — skip to avoid false positives on minimal setups
+    return {
+      id: 'tetraUiSourcePath',
+      severity: 'critical',
+      label: 'tetra-ui @source path',
+      pass: true,
+      detail: `no @source directives in ${files.globalsCss.path} (skipped)`,
+      fixable: false,
+    }
+  }
+
+  // Check every @source path resolves to an existing directory/file
+  const broken = []
+  for (const sourcePath of sourcePaths) {
+    const resolvedPath = resolve(globalsCssDir, sourcePath)
+    if (!existsSync(resolvedPath)) {
+      broken.push({ raw: sourcePath, resolved: resolvedPath })
+    }
+  }
+
+  if (broken.length > 0) {
+    const first = broken[0]
+    const extra = broken.length > 1 ? ` (and ${broken.length - 1} more)` : ''
+    return {
+      id: 'tetraUiSourcePath',
+      severity: 'critical',
+      label: 'tetra-ui @source path',
+      pass: false,
+      detail: `@source "${first.raw}" resolves to non-existent path: ${first.resolved}${extra}` +
+        ` — fix: @source "../../../node_modules/@soulbatical/tetra-ui/dist"` +
+        ` (adjust depth to reach node_modules from ${files.globalsCss.path})`,
+      fixable: false,
+    }
+  }
+
+  // Check at least one @source entry covers tetra-ui/dist so AppShell
+  // margin classes (ml-64, ml-16, etc.) are generated by Tailwind v4
+  const tetraUiDistPaths = sourcePaths.filter(sourcePath => {
+    const resolvedPath = resolve(globalsCssDir, sourcePath)
+    return resolvedPath.includes('@soulbatical/tetra-ui') && resolvedPath.includes('dist')
+  })
+
+  if (tetraUiDistPaths.length === 0) {
+    return {
+      id: 'tetraUiSourcePath',
+      severity: 'critical',
+      label: 'tetra-ui @source path',
+      pass: false,
+      detail: `no @source entry pointing to @soulbatical/tetra-ui/dist found in ${files.globalsCss.path}` +
+        ` — AppShell layout classes (ml-64, ml-16, etc.) will not be generated by Tailwind v4.` +
+        ` Add: @source "../../../node_modules/@soulbatical/tetra-ui/dist"` +
+        ` (adjust relative depth as needed)`,
+      fixable: false,
+    }
+  }
+
+  return {
+    id: 'tetraUiSourcePath',
+    severity: 'critical',
+    label: 'tetra-ui @source path',
+    pass: true,
+    detail: `@source "${tetraUiDistPaths[0]}" exists in ${files.globalsCss.path}`,
+    fixable: false,
+  }
+}
+
+/**
+ * HIGH 8: tetra-core version should be recent.
  */
 function checkTetraCoreVersion(files) {
   const pkgContent = files.backendPackageJson?.content
@@ -771,6 +871,7 @@ export async function runDoctorAudit(projectRoot) {
     checkNextThemes(projectRoot),
     checkCssTokens(files),
     checkDarkMode(files),
+    checkTetraUiSourcePath(files, projectRoot),
     // HIGH
     checkTetraCoreVersion(files),
     appShellCheck,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulbatical/tetra-dev-toolkit",
-  "version": "1.21.0",
+  "version": "1.22.0",
   "publishConfig": {
     "access": "restricted"
   },
@@ -45,7 +45,8 @@
     "tetra-check-views": "./bin/tetra-check-views.js",
     "tetra-doctor": "./bin/tetra-doctor.js",
     "tetra-style-audit": "./bin/tetra-style-audit.js",
-    "tetra-init-smoke": "./bin/tetra-init-smoke.js"
+    "tetra-init-smoke": "./bin/tetra-init-smoke.js",
+    "tetra-license": "./bin/tetra-license.js"
   },
   "files": [
     "bin/",