spine-framework 0.2.1 → 0.2.3

package/.framework/cli/commands/claim.ts

@@ -0,0 +1,447 @@
+/// <reference types="node" />
+/**
+ * @module cli/commands/claim
+ * @audience installer
+ * @layer cli
+ * @stability stable
+ *
+ * `spine-framework claim` — Claim framework installation via Spine Portal.
+ *
+ * Engagement-based claim system that offers contextual prompts based on
+ * user activity. Tracks engagement signals and triggers claim prompts
+ * at value-realization moments.
+ *
+ * **Usage:**
+ * ```bash
+ * spine-framework claim              # Interactive claim flow
+ * spine-framework claim --status     # Show claim status only
+ * spine-framework claim --token <t>  # Headless claim with token
+ * ```
+ */
+
+import type { Command } from 'commander'
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs'
+import { resolve } from 'path'
+import { createHash, randomBytes } from 'crypto'
+import * as readline from 'readline'
+import { signalConfig, claimTriggers, engagementSignals, type EngagementData, type ClaimPrompt, type EngagementSignalType } from '../../config/signals.ts'
+
+const PROJECT_ROOT = process.cwd()
+const SPINE_DIR = resolve(PROJECT_ROOT, '.spine')
+const SERIAL_FILE = resolve(SPINE_DIR, 'serial.json')
+const ENGAGEMENT_FILE = resolve(SPINE_DIR, 'engagement.json')
+
+// ─── SERIAL NUMBER MANAGEMENT ────────────────────────────────────────────────
+
+export interface SerialData {
+  serial_number: string
+  salt: string
+  created_at: string
+  framework_version: string
+  account_id: string | null
+  machine_fingerprint: string
+}
+
+function generateMachineFingerprint(): string {
+  const hostname = process.env.HOSTNAME || process.env.COMPUTERNAME || 'unknown'
+  const platform = process.platform
+  const arch = process.arch
+  const data = `${hostname}-${platform}-${arch}-${process.env.USER || 'unknown'}`
+  return createHash('sha256').update(data).digest('hex').substring(0, 16)
+}
+
+function generateSerialNumber(version: string, machineId: string, salt: string): string {
+  const timestamp = Date.now().toString()
+  const data = `spine-framework-${version}-${machineId}-${timestamp}-${salt}`
+  const hash = createHash('sha256').update(data).digest('hex')
+  return `spn_fw_${hash.substring(0, 16).toUpperCase()}`
+}
+
+export function ensureSerialData(): SerialData {
+  if (existsSync(SERIAL_FILE)) {
+    try {
+      return JSON.parse(readFileSync(SERIAL_FILE, 'utf8')) as SerialData
+    } catch { /* fall through to create new */ }
+  }
+
+  // Create .spine directory if needed
+  if (!existsSync(SPINE_DIR)) {
+    mkdirSync(SPINE_DIR, { recursive: true })
+  }
+
+  // Generate new serial
+  const salt = randomBytes(32).toString('hex')
+  const machineFingerprint = generateMachineFingerprint()
+  const frameworkVersion = getFrameworkVersion()
+  const serialNumber = generateSerialNumber(frameworkVersion, machineFingerprint, salt)
+
+  const serialData: SerialData = {
+    serial_number: serialNumber,
+    salt,
+    created_at: new Date().toISOString(),
+    framework_version: frameworkVersion,
+    account_id: null,
+    machine_fingerprint: machineFingerprint,
+  }
+
+  writeFileSync(SERIAL_FILE, JSON.stringify(serialData, null, 2) + '\n', 'utf8')
+  return serialData
+}
+
+function getFrameworkVersion(): string {
+  const pkgJsonPath = resolve(PROJECT_ROOT, 'package.json')
+  if (existsSync(pkgJsonPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8'))
+      return pkg.version || '0.0.0'
+    } catch { /* fall through */ }
+  }
+  return '0.0.0'
+}
+
+// ─── ENGAGEMENT TRACKING ─────────────────────────────────────────────────────
+
+export function readEngagementData(): EngagementData | null {
+  if (!existsSync(ENGAGEMENT_FILE)) return null
+  try {
+    return JSON.parse(readFileSync(ENGAGEMENT_FILE, 'utf8')) as EngagementData
+  } catch {
+    return null
+  }
+}
+
+export function writeEngagementData(data: EngagementData): void {
+  if (!existsSync(SPINE_DIR)) {
+    mkdirSync(SPINE_DIR, { recursive: true })
+  }
+  writeFileSync(ENGAGEMENT_FILE, JSON.stringify(data, null, 2) + '\n', 'utf8')
+}
+
+export function recordEngagementSignal(signalType: EngagementSignalType): void {
+  const serialData = ensureSerialData()
+  let engagement = readEngagementData()
+
+  if (!engagement) {
+    engagement = {
+      framework_install_serial: serialData.serial_number,
+      engagement_score: 0,
+      signals: [],
+      claim_status: 'anonymous',
+    }
+  }
+
+  const signalDef = engagementSignals[signalType]
+  const entry = {
+    type: signalType,
+    timestamp: new Date().toISOString(),
+    score: signalDef.score,
+  }
+
+  // Avoid duplicate signals of the same type within 1 hour
+  const oneHourAgo = Date.now() - 3600000
+  const recentSignal = engagement.signals.find(
+    s => s.type === signalType && new Date(s.timestamp).getTime() > oneHourAgo
+  )
+  if (recentSignal) {
+    return // Skip duplicate
+  }
+
+  engagement.signals.push(entry)
+  engagement.engagement_score += signalDef.score
+  writeEngagementData(engagement)
+}
+
+export function shouldOfferClaim(): ClaimPrompt | null {
+  const engagement = readEngagementData()
+  if (!engagement) return null
+  if (engagement.claim_status !== 'anonymous') return null
+
+  const score = engagement.engagement_score
+
+  if (score >= claimTriggers.power_user) {
+    return {
+      timing: 'power_user',
+      message: "You're a power user! Unlock advanced features and priority support by claiming your installation.",
+    }
+  } else if (score >= claimTriggers.ecosystem_engaged) {
+    return {
+      timing: 'ecosystem_engaged',
+      message: "You're expanding your toolkit! Claim your install for app-specific guides and community access.",
+    }
+  } else if (score >= claimTriggers.value_realized) {
+    return {
+      timing: 'value_realized',
+      message: 'Database connected! Claim your install to unlock production deployment guides and audit tools.',
+    }
+  } else if (score >= claimTriggers.gentle_nudge) {
+    return {
+      timing: 'gentle_nudge',
+      message: 'Framework started! Ready to explore the full ecosystem? Claim your install for docs and support.',
+    }
+  }
+
+  return null
+}
+
+// ─── SIGNAL SENDING ───────────────────────────────────────────────────────────
+
+export interface FrameworkInstallSignal {
+  signal_type: 'framework_install'
+  install_serial: string
+  package: string
+  version: string
+  anonymous_id: string
+  machine_fingerprint: string
+  platform: string
+  timestamp: string
+}
+
+export interface AppInstallSignal {
+  signal_type: 'app_install'
+  package: string
+  version: string
+  framework_install_serial: string
+  app_serial: string
+  timestamp: string
+}
+
+export async function sendFrameworkInstallSignal(): Promise<void> {
+  const serialData = ensureSerialData()
+
+  const signal: FrameworkInstallSignal = {
+    signal_type: 'framework_install',
+    install_serial: serialData.serial_number,
+    package: 'spine-framework',
+    version: serialData.framework_version,
+    anonymous_id: `anon_${randomBytes(8).toString('hex')}`,
+    machine_fingerprint: serialData.machine_fingerprint,
+    platform: `${process.platform}-${process.arch}`,
+    timestamp: new Date().toISOString(),
+  }
+
+  try {
+    await fetch(`${signalConfig.endpoint}/api/integrations/webhook/funnel-signal`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(signal),
+    })
+  } catch {
+    // Silent fail - signal endpoint is best-effort
+  }
+}
+
+export async function sendAppInstallSignal(packageName: string, version: string): Promise<void> {
+  const serialData = ensureSerialData()
+
+  const signal: AppInstallSignal = {
+    signal_type: 'app_install',
+    package: packageName,
+    version,
+    framework_install_serial: serialData.serial_number,
+    app_serial: `${packageName}_${randomBytes(8).toString('hex')}`,
+    timestamp: new Date().toISOString(),
+  }
+
+  try {
+    await fetch(`${signalConfig.endpoint}/api/integrations/webhook/funnel-signal`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(signal),
+    })
+  } catch {
+    // Silent fail
+  }
+}
+
+// ─── CLAIM FLOW ───────────────────────────────────────────────────────────────
+
+function promptQuestion(question: string): Promise<string> {
+  return new Promise(resolve => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+    rl.question(question, answer => {
+      rl.close()
+      resolve(answer.trim())
+    })
+  })
+}
+
+async function openPortalClaim(serialNumber: string): Promise<void> {
+  const claimUrl = `https://portal.spine-framework.com/claim?serial=${serialNumber}`
+
+  // Try to open browser
+  const platform = process.platform
+  const cmd = platform === 'darwin' ? 'open' : platform === 'win32' ? 'start' : 'xdg-open'
+
+  console.log(`\n🌐 Opening ${claimUrl}`)
+  console.log('   Create your account or log in to claim this installation.\n')
+
+  try {
+    const { execSync } = await import('child_process')
+    execSync(`${cmd} "${claimUrl}"`, { stdio: 'ignore' })
+  } catch {
+    console.log(`   Could not open browser automatically.`)
+    console.log(`   Please visit the URL manually.\n`)
+  }
+}
+
+async function tokenClaimFlow(serialNumber: string): Promise<void> {
+  console.log('\n🔑 Token-Based Claim')
+  console.log('   1. Visit https://portal.spine-framework.com/settings/claim')
+  console.log('   2. Copy your claim token\n')
+
+  const token = await promptQuestion('   Enter your claim token: ')
+
+  if (!token) {
+    console.log('\n   ❌ No token provided. Claim cancelled.')
+    return
+  }
+
+  // Validate token with portal API
+  try {
+    const response = await fetch(`${signalConfig.endpoint}/api/claim`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        install_serial: serialNumber,
+        user_token: token,
+      }),
+    })
+
+    if (!response.ok) {
+      console.log('\n   ❌ Invalid token or claim failed. Please try again.')
+      return
+    }
+
+    const result = await response.json() as { success: boolean; account_id?: string }
+
+    if (result.success) {
+      // Update local files
+      const serialData = ensureSerialData()
+      serialData.account_id = result.account_id || null
+      writeFileSync(SERIAL_FILE, JSON.stringify(serialData, null, 2) + '\n', 'utf8')
+
+      const engagement = readEngagementData()
+      if (engagement) {
+        engagement.claim_status = 'claimed'
+        engagement.account_id = result.account_id
+        writeEngagementData(engagement)
+      }
+
+      console.log('\n   ✅ Installation claimed successfully!')
+      console.log('   Welcome to the Spine ecosystem. 🎉\n')
+    } else {
+      console.log('\n   ❌ Claim failed. Please check your token and try again.')
+    }
+  } catch {
+    console.log('\n   ⚠️  Could not connect to portal. Please try again later.')
+  }
+}
+
+async function showClaimStatus(): Promise<void> {
+  const serialData = existsSync(SERIAL_FILE) ? JSON.parse(readFileSync(SERIAL_FILE, 'utf8')) as SerialData : null
+  const engagement = readEngagementData()
+
+  console.log('\n📊 Claim Status\n')
+
+  if (!serialData) {
+    console.log('   No installation serial found.')
+    console.log('   Run any spine-framework command to initialize.\n')
+    return
+  }
+
+  console.log(`   Serial Number: ${serialData.serial_number}`)
+  console.log(`   Framework Version: ${serialData.framework_version}`)
+  console.log(`   Created: ${new Date(serialData.created_at).toLocaleDateString()}`)
+
+  if (engagement) {
+    console.log(`\n   Engagement Score: ${engagement.engagement_score}`)
+    console.log(`   Signals Recorded: ${engagement.signals.length}`)
+    console.log(`   Claim Status: ${engagement.claim_status}`)
+
+    if (engagement.claim_status === 'anonymous') {
+      const prompt = shouldOfferClaim()
+      if (prompt) {
+        console.log(`\n   💡 ${prompt.message}`)
+      }
+    } else if (engagement.account_id) {
+      console.log(`   Account ID: ${engagement.account_id}`)
+    }
+  }
+
+  console.log('')
+}
+
+async function runClaimFlow(options: { status: boolean; token?: string }): Promise<void> {
+  // Ensure serial exists
+  const serialData = ensureSerialData()
+
+  // Send framework install signal on first claim check
+  recordEngagementSignal('framework_initialized')
+  await sendFrameworkInstallSignal()
+
+  if (options.status) {
+    await showClaimStatus()
+    return
+  }
+
+  // Check if already claimed
+  const engagement = readEngagementData()
+  if (engagement?.claim_status === 'claimed') {
+    console.log('\n✅ This installation is already claimed.')
+    console.log(`   Account: ${engagement.account_id}\n`)
+    return
+  }
+
+  console.log('\n🔐 Claim Your Spine Installation\n')
+  console.log(`   Serial: ${serialData.serial_number}`)
+  console.log('\n   Claiming unlocks:')
+  console.log('   • Documentation and playbooks')
+  console.log('   • App packs and marketplace')
+  console.log('   • Support and community access')
+  console.log('   • Audit and compliance tools\n')
+
+  if (options.token) {
+    await tokenClaimFlow(serialData.serial_number)
+    return
+  }
+
+  console.log('   Choose a claim method:')
+  console.log('   1. Portal flow (opens browser) - RECOMMENDED')
+  console.log('   2. Token flow (paste token from portal)')
+  console.log('   3. Check status only\n')
+
+  const choice = await promptQuestion('   Select (1-3): ')
+
+  switch (choice) {
+    case '1':
+      await openPortalClaim(serialData.serial_number)
+      break
+    case '2':
+      await tokenClaimFlow(serialData.serial_number)
+      break
+    case '3':
+      await showClaimStatus()
+      break
+    default:
+      console.log('\n   Invalid choice. Run `spine-framework claim` to try again.\n')
+  }
+}
+
+// ─── COMMAND REGISTRATION ───────────────────────────────────────────────────
+
+export function registerClaimCommands(program: Command): void {
+  program
+    .command('claim')
+    .description('Claim framework installation via Spine Portal')
+    .option('--status', 'Show claim status only', false)
+    .option('--token <token>', 'Headless claim with token')
+    .action(async (opts) => {
+      try {
+        await runClaimFlow(opts)
+      } catch (err: any) {
+        console.error('Error:', err.message)
+        if (process.env.SPINE_CLI_DEBUG) console.error(err.stack)
+        process.exit(1)
+      }
+    })
+}

package/.framework/cli/commands/install-app.ts

@@ -28,11 +28,12 @@
  */
 
 import type { Command } from 'commander'
-import { existsSync, readFileSync, readdirSync, cpSync, mkdirSync } from 'fs'
+import { existsSync, readFileSync, readdirSync, cpSync, mkdirSync, statSync } from 'fs'
 import { resolve, dirname } from 'path'
 import { fileURLToPath } from 'url'
 import { execSync } from 'child_process'
 import { adminDb } from '../../functions/_shared/index.ts'
+import { recordEngagementSignal, sendAppInstallSignal, ensureSerialData } from './claim.ts'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
@@ -42,6 +43,7 @@ interface InstallOptions {
   account?: string
   force: boolean
   dryRun: boolean
+  packageName?: string
 }
 
 interface SeedResult {
@@ -332,9 +334,15 @@ const SEED_HANDLERS: Record<string, (appId: string, records: any[], dryRun: bool
   'roles.json': upsertRoles,
 }
 
-async function recordInstallation(appSlug: string, accountId: string | null, dryRun: boolean): Promise<void> {
+async function recordInstallation(
+  appSlug: string,
+  accountId: string | null,
+  dryRun: boolean,
+  installedVersion?: string,
+  packageName?: string,
+): Promise<void> {
   if (dryRun) {
-    console.log(`  [dry-run] Would record installation for '${appSlug}'`)
+    console.log(`  [dry-run] Would record installation for '${appSlug}' (version: ${installedVersion || 'unknown'})`)
     return
   }
 
@@ -344,6 +352,8 @@ async function recordInstallation(appSlug: string, accountId: string | null, dry
       app_slug: appSlug,
       account_id: accountId,
       is_enabled: true,
+      installed_version: installedVersion || null,
+      package_name: packageName || null,
       updated_at: new Date().toISOString(),
     }, {
       onConflict: 'app_slug,account_id',
@@ -380,10 +390,23 @@ async function checkPrerequisites(_slug: string): Promise<void> {
   // Future: read prereqs from the app's manifest.json if needed.
 }
 
-function copyAppFiles(pkg: string, slug: string): void {
+function copyAppFiles(pkg: string, slug: string, force: boolean): void {
   const pkgDir = resolve(PROJECT_ROOT, `node_modules/${pkg}`)
   const targetAppDir = resolve(PROJECT_ROOT, `custom/apps/${slug}`)
 
+  // Guard: abort if already installed and --force not passed
+  if (existsSync(targetAppDir) && statSync(targetAppDir).isDirectory()) {
+    const hasFiles = readdirSync(targetAppDir).length > 0
+    if (hasFiles && !force) {
+      console.error(`  ❌ App '${slug}' is already installed at custom/apps/${slug}/`)
+      console.error(`     Use 'update-app ${slug}' to upgrade, or 'install-app --force' to overwrite.`)
+      process.exit(1)
+    }
+    if (hasFiles && force) {
+      console.log(`  ⚠️  --force: overwriting existing custom/apps/${slug}/`)
+    }
+  }
+
   mkdirSync(targetAppDir, { recursive: true })
 
   // Always copy core app files
@@ -437,7 +460,11 @@ async function installApp(slug: string, options: InstallOptions): Promise<void>
     packageName = barePackageName
     console.log(`📥 Step 1: Installing npm package...`)
     const pkgDir = resolve(PROJECT_ROOT, `node_modules/${barePackageName}`)
-    if (!existsSync(pkgDir)) {
+    // Always run npm install when a version specifier is given (e.g. @1.2.3 or @latest)
+    // so the correct version is fetched even if an older one is already in node_modules.
+    const hasVersionSpec = slug.includes('@') && !slug.startsWith('@') || (slug.startsWith('@') && slug.split('@').length > 2)
+    const shouldInstall = !existsSync(pkgDir) || hasVersionSpec
+    if (shouldInstall) {
       try {
         console.log(`  Running: npm install ${slug}`)
         execSync(`npm install ${slug}`, { cwd: PROJECT_ROOT, stdio: 'inherit' })
@@ -453,7 +480,7 @@ async function installApp(slug: string, options: InstallOptions): Promise<void>
     console.log(`  ✓ App slug: ${resolvedSlug}`)
 
     console.log(`\n📁 Step 2: Ejecting app files...`)
-    copyAppFiles(barePackageName, resolvedSlug)
+    copyAppFiles(barePackageName, resolvedSlug, options.force)
   }
 
   // Check prerequisites (e.g. portal requires cortex)
@@ -538,7 +565,40 @@ async function installApp(slug: string, options: InstallOptions): Promise<void>
 
   // 5. Record installation
   console.log(`\n📝 Recording installation...`)
-  await recordInstallation(resolvedSlug, options.account || null, options.dryRun)
+  let installedVersion: string | undefined
+  const manifestForVersion = resolve(appDir, 'manifest.json')
+  if (existsSync(manifestForVersion)) {
+    try {
+      installedVersion = JSON.parse(readFileSync(manifestForVersion, 'utf8')).version
+    } catch { /* ignore */ }
+  }
+  await recordInstallation(resolvedSlug, options.account || null, options.dryRun, installedVersion, packageName || undefined)
+
+  // 6. Signal integration (only on new installs, not --force overwrites)
+  if (!options.force && !options.dryRun) {
+    console.log(`\n📡 Sending install signal...`)
+    try {
+      // Ensure framework serial exists
+      ensureSerialData()
+      // Record engagement
+      recordEngagementSignal('app_install')
+      // Send app install signal
+      if (packageName) {
+        await sendAppInstallSignal(packageName, installedVersion || '0.0.0')
+      }
+      console.log(`  ✓ Install signal sent`)
+
+      // Check for claim prompt
+      const { shouldOfferClaim } = await import('./claim.ts')
+      const prompt = shouldOfferClaim()
+      if (prompt) {
+        console.log(`\n💡 ${prompt.message}`)
+        console.log(`   Run: spine-framework claim`)
+      }
+    } catch {
+      // Silent fail - signal tracking is best-effort
+    }
+  }
 
   console.log(`\n✅ App '${appName}' installed successfully!`)
   console.log(`\n   Next steps:`)

package/.framework/cli/commands/migrate.ts

@@ -94,8 +94,20 @@ async function migrateCommand(options: MigrateOptions): Promise<void> {
   for (const file of files) {
     const sql = readFileSync(resolve(MIGRATIONS_DIR, file), 'utf8')
     process.stdout.write(`  Applying ${file}... `)
+
+    // Split into individual statements so each executes in its own round-trip.
+    // Running the whole file as one query string causes pg to abort the entire
+    // batch on the first error, preventing PL/pgSQL EXCEPTION handlers from
+    // catching expected errors like "relation already exists".
+    const statements = sql
+      .split(/;\s*$/m)
+      .map(s => s.trim())
+      .filter(s => s.length > 0 && !s.startsWith('--'))
+
     try {
-      await client.query(sql)
+      for (const stmt of statements) {
+        await client.query(stmt + ';')
+      }
       console.log('✓')
       applied++
     } catch (err: any) {