spine-framework 0.3.17 → 0.3.19

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

@@ -1,430 +0,0 @@
-/// <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 async function sendFrameworkInstallSignal(): Promise<void> {
-  const serialData = ensureSerialData()
-
-  const signal = {
-    stage: 'installed' as const,
-    source: 'use' as const,
-    action_type: 'framework_install',
-    action_value: 2 as const,
-    instance_id: serialData.serial_number,
-    anonymous_id: `anon_${randomBytes(8).toString('hex')}`,
-    environment: (process.env.NODE_ENV === 'production' ? 'production' : 'dev') as 'dev' | 'production',
-    occurred_at: new Date().toISOString(),
-  }
-
-  try {
-    await fetch(`${signalConfig.endpoint}/api/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 = {
-    stage: 'installed' as const,
-    source: 'use' as const,
-    action_type: 'app_install',
-    action_value: 2 as const,
-    instance_id: serialData.serial_number,
-    anonymous_id: `anon_${randomBytes(8).toString('hex')}`,
-    action_description: packageName,
-    environment: (process.env.NODE_ENV === 'production' ? 'production' : 'dev') as 'dev' | 'production',
-    occurred_at: new Date().toISOString(),
-  }
-
-  try {
-    await fetch(`${signalConfig.endpoint}/api/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/init.ts

@@ -1,219 +0,0 @@
-/// <reference types="node" />
-/**
- * @module cli/commands/init
- * @audience installer
- * @layer cli
- * @stability stable
- *
- * `spine-framework init` — Write .env and scaffold the custom/ workspace.
- *
- * Intentionally does NOT touch the database — run `spine-framework migrate`
- * after init to apply SQL migrations via a direct Postgres connection.
- *
- * **Usage:**
- * ```bash
- * spine-framework init --url https://xyz.supabase.co --anon-key eyJ... --service-role-key eyJ...
- * spine-framework migrate --db-password <password>
- * ```
- */
-
-import type { Command } from 'commander'
-import { existsSync, mkdirSync, writeFileSync, cpSync, readFileSync } from 'fs'
-import { resolve, dirname } from 'path'
-import { fileURLToPath } from 'url'
-import { execSync } from 'child_process'
-
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = dirname(__filename)
-const PROJECT_ROOT = process.cwd()
-// Package root: node_modules/spine-framework/ — 3 levels up from .framework/cli/commands/
-const PACKAGE_ROOT = resolve(__dirname, '../../..')
-
-interface InitOptions {
-  dryRun: boolean
-}
-
-function scaffoldCustomWorkspace(dryRun: boolean): void {
-  const dirs = [
-    'custom/apps',
-    'custom/functions',
-    'custom/components',
-    'custom/migrations',
-    'custom/tests',
-  ]
-
-  for (const dir of dirs) {
-    const fullPath = resolve(PROJECT_ROOT, dir)
-    if (existsSync(fullPath)) {
-      console.log(`  ⏭️  ${dir}/ already exists`)
-    } else if (dryRun) {
-      console.log(`  [dry-run] Would create: ${dir}/`)
-    } else {
-      mkdirSync(fullPath, { recursive: true })
-      writeFileSync(resolve(fullPath, '.gitkeep'), '')
-      console.log(`  ✓ Created ${dir}/`)
-    }
-  }
-}
-
-function writeEnvFile(dryRun: boolean): void {
-  const envPath = resolve(PROJECT_ROOT, '.env')
-
-  if (existsSync(envPath)) {
-    console.log('  ⏭️  .env already exists, skipping')
-    return
-  }
-
-  const envContent = [
-    '# ─── Supabase ────────────────────────────────────────────────────────────────',
-    '# Get these from: https://supabase.com/dashboard/project/_/settings/api',
-    'SUPABASE_URL=https://your-project.supabase.co',
-    'SUPABASE_ANON_KEY=your-anon-key',
-    'SUPABASE_SERVICE_ROLE_KEY=your-service-role-key',
-    '',
-    '# DB password for running migrations (direct Postgres connection)',
-    '# Get from: https://supabase.com/dashboard/project/_/settings/database',
-    'SUPABASE_DB_PASSWORD=your-db-password',
-    '',
-    '# ─── Vite / Frontend ─────────────────────────────────────────────────────────',
-    'VITE_SUPABASE_URL=https://your-project.supabase.co',
-    'VITE_SUPABASE_ANON_KEY=your-anon-key',
-    'VITE_APP_NAME=Spine',
-    '',
-    '# ─── OpenAI ──────────────────────────────────────────────────────────────────',
-    'OPENAI_API_KEY=your-openai-api-key',
-    '',
-    '# ─── App config ──────────────────────────────────────────────────────────────',
-    'DB_SCHEMA=public',
-  ].join('\n') + '\n'
-
-  if (dryRun) {
-    console.log('  [dry-run] Would write .env with placeholder values')
-    return
-  }
-
-  writeFileSync(envPath, envContent, 'utf8')
-  console.log('  ✓ Created .env')
-}
-
-function copyFrameworkFiles(dryRun: boolean): void {
-  // Directories and files to copy from the package root into the consumer project root
-  const items = [
-    { src: '.framework',     dest: '.framework'     },
-    { src: 'bin',            dest: 'bin'            },
-    { src: 'config',         dest: 'config'         },
-    { src: 'scripts',        dest: 'scripts'        },
-    { src: 'netlify.toml',   dest: 'netlify.toml'   },
-    { src: 'vitest.config.ts', dest: 'vitest.config.ts' },
-    { src: 'index.html',     dest: 'index.html'     },
-    { src: 'package-project.json', dest: 'package.json', template: true },
-    { src: 'STRUCTURE.md',   dest: 'STRUCTURE.md'   },
-    { src: 'README.md',      dest: 'README.md'      },
-    { src: 'LICENSE.md',     dest: 'LICENSE.md'     },
-    { src: 'CHANGELOG.md',   dest: 'CHANGELOG.md'   },
-  ]
-
-  // Resolve current framework version from the installed package
-  let frameworkVersion = '0.1.0'
-  try {
-    const fwPkg = JSON.parse(readFileSync(resolve(PACKAGE_ROOT, 'package.json'), 'utf8'))
-    frameworkVersion = fwPkg.version || frameworkVersion
-  } catch { /* fall through */ }
-
-  for (const item of items as Array<{ src: string; dest: string; template?: boolean }>) {
-    const src  = resolve(PACKAGE_ROOT, item.src)
-    const dest = resolve(PROJECT_ROOT, item.dest)
-
-    if (!existsSync(src)) {
-      console.log(`  ⏭️  ${item.src} not found in package, skipping`)
-      continue
-    }
-
-    if (existsSync(dest)) {
-      // For package.json: only skip if it already has scripts (i.e. it's a real project package.json)
-      // A bare stub created by `npm install` has no scripts and should be overwritten
-      if (item.template) {
-        try {
-          const existing = JSON.parse(readFileSync(dest, 'utf8'))
-          if (existing.scripts && Object.keys(existing.scripts).length > 0) {
-            console.log(`  ⏭️  ${item.dest} already exists, skipping`)
-            continue
-          }
-          // Fall through — bare stub, overwrite it
-        } catch {
-          // Unparseable — overwrite it
-        }
-      } else {
-        console.log(`  ⏭️  ${item.dest} already exists, skipping`)
-        continue
-      }
-    }
-
-    if (dryRun) {
-      console.log(`  [dry-run] Would copy: ${item.src} → ./${item.dest}`)
-      continue
-    }
-
-    if (item.template) {
-      // Stamp the current framework version into the project package.json
-      const templateContent = JSON.parse(readFileSync(src, 'utf8'))
-      if (templateContent.dependencies?.['spine-framework']) {
-        templateContent.dependencies['spine-framework'] = `^${frameworkVersion}`
-      }
-      writeFileSync(dest, JSON.stringify(templateContent, null, 2) + '\n', 'utf8')
-    } else {
-      cpSync(src, dest, { recursive: true })
-    }
-    console.log(`  ✓ Copied ${item.dest}`)
-  }
-}
-
-async function initCommand(options: InitOptions): Promise<void> {
-  console.log('\n🚀 Spine Framework — Init\n')
-
-  // Step 1: Copy framework files to project root
-  console.log('📦 Step 1: Installing framework files...')
-  copyFrameworkFiles(options.dryRun)
-
-  // Step 2: Install dev dependencies (vite, netlify-cli)
-  if (!options.dryRun) {
-    console.log('\n📦 Step 2: Installing dev dependencies...')
-    try {
-      execSync('npm install', { stdio: 'inherit', cwd: PROJECT_ROOT })
-      console.log('  ✓ Dev dependencies installed')
-    } catch (err) {
-      console.log('  ⚠️  npm install failed — run manually: npm install')
-    }
-  }
-
-  // Step 3: Scaffold custom workspace
-  console.log('\n📁 Step 3: Scaffolding custom workspace...')
-  scaffoldCustomWorkspace(options.dryRun)
-
-  // Step 4: Write .env with placeholders
-  console.log('\n🔑 Step 4: Writing environment configuration...')
-  writeEnvFile(options.dryRun)
-
-  console.log('\n✅ Project initialized!')
-  console.log('\n   Next steps:')
-  console.log('   1. Fill in your Supabase credentials in .env')
-  console.log('      (get them from https://supabase.com/dashboard/project/_/settings/api)')
-  console.log('   2. Run: npx spine-framework migrate')
-  console.log('      (ensure SUPABASE_DB_PASSWORD is set in .env)')
-}
-
-export function registerInitCommands(program: Command) {
-  program
-    .command('init')
-    .description('Install framework files, scaffold custom/ workspace, and write .env template')
-    .option('--dry-run', 'Show what would happen without making changes', false)
-    .action(async (opts) => {
-      try {
-        await initCommand(opts)
-      } catch (err: any) {
-        console.error('Error:', err.message)
-        if (process.env.SPINE_CLI_DEBUG) console.error(err.stack)
-        process.exit(1)
-      }
-    })
-}