spine-framework 0.1.0

package/.framework/cli/commands/migrations.ts

@@ -0,0 +1,141 @@
+/// <reference types="node" />
+/**
+ * @module cli/commands/migrations
+ * @audience installer
+ * @layer cli
+ * @stability stable
+ *
+ * `spine migrations` command group. Read-only inspection of the migration
+ * state. Does NOT apply or roll back migrations — use the Supabase CLI for
+ * that. These commands are intended for verifying the state of a deployed
+ * instance during setup or debugging.
+ *
+ * **Commands:**
+ * | Subcommand            | Description                                         |
+ * |-----------------------|-----------------------------------------------------|
+ * | `migrations list`     | Show all applied migrations from `schema_migrations`|
+ * | `migrations status`   | Diff local `.sql` files against applied migrations  |
+ *
+ * **Authorization:** Uses `adminDb` (service-role) with an explicit
+ * `.schema('public')` override to reach `schema_migrations`. Requires
+ * `SUPABASE_SERVICE_ROLE_KEY` with public schema access.
+ *
+ * **Usage:**
+ * ```bash
+ * spine migrations list
+ * spine migrations status
+ * spine migrations status --json
+ * ```
+ *
+ * @seeAlso v2-core/migrations/ (local .sql migration files)
+ * @seeAlso cli/context.ts (buildCliContext)
+ */
+
+import type { Command } from 'commander'
+import { readdirSync, existsSync } from 'fs'
+import { resolve, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import { buildCliContext, printResult, handleError } from '../context.ts'
+import { adminDb } from '../../functions/_shared/index.ts'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+/**
+ * Registers the `migrations` subcommand group on the root Commander program.
+ *
+ * @param program - The root `spine` Commander instance
+ * @sideEffects Adds `migrations list` and `migrations status` subcommands to `program`
+ * @calledBy cli/index.ts
+ */
+export function registerMigrationCommands(program: Command) {
+  const migrations = program
+    .command('migrations')
+    .description('Database migration inspection')
+
+  migrations
+    .command('list')
+    .description('List applied migrations from supabase schema_migrations')
+    .option('--json', 'Output as JSON')
+    .action(async (opts) => {
+      try {
+        await buildCliContext()
+
+        const { data, error } = await adminDb
+          .schema('supabase_migrations' as any)
+          .from('schema_migrations' as any)
+          .select('version, name, executed_at')
+          .order('version', { ascending: true })
+
+        if (error) {
+          throw new Error(
+            `Could not query migrations: ${error.message}\n` +
+            'Ensure SUPABASE_SERVICE_ROLE_KEY has access to the public schema.'
+          )
+        }
+
+        printResult(data || [], { json: opts.json })
+      } catch (err: any) {
+        handleError(err)
+      }
+    })
+
+  migrations
+    .command('status')
+    .description('Compare local migration files against applied migrations')
+    .option('--json', 'Output as JSON')
+    .action(async (opts) => {
+      try {
+        await buildCliContext()
+
+        const migrationsDir = resolve(__dirname, '../../migrations')
+
+        if (!existsSync(migrationsDir)) {
+          throw new Error(`Migrations directory not found: ${migrationsDir}`)
+        }
+
+        const localFiles = readdirSync(migrationsDir)
+          .filter((f: string) => f.endsWith('.sql'))
+          .sort()
+
+        const { data: applied, error } = await adminDb
+          .schema('supabase_migrations' as any)
+          .from('schema_migrations' as any)
+          .select('version')
+
+        if (error) {
+          throw new Error(`Could not query migrations: ${error.message}`)
+        }
+
+        const appliedVersions = new Set(
+          (applied || []).map((r: any) => r.version)
+        )
+
+        const status = localFiles.map((file: string) => {
+          const version = file.replace('.sql', '')
+          const isApplied = appliedVersions.has(version)
+          return {
+            file,
+            version,
+            status: isApplied ? 'applied' : 'pending'
+          }
+        })
+
+        if (opts.json) {
+          console.log(JSON.stringify(status, null, 2))
+        } else {
+          console.log('\nMigration Status')
+          console.log('─'.repeat(60))
+          for (const m of status as Array<{file: string; status: string}>) {
+            const icon = m.status === 'applied' ? '✓' : '○'
+            console.log(`  ${icon} ${m.file.padEnd(40)} ${m.status}`)
+          }
+          const pending = status.filter(m => m.status === 'pending').length
+          console.log(`\n  ${status.length - pending} applied, ${pending} pending`)
+          console.log()
+        }
+      } catch (err: any) {
+        handleError(err)
+      }
+    })
+}

package/.framework/cli/commands/pipelines.ts

@@ -0,0 +1,166 @@
+/// <reference types="node" />
+/**
+ * @module cli/commands/pipelines
+ * @audience installer
+ * @layer cli
+ * @stability stable
+ *
+ * `spine pipelines` command group. Lists, inspects, and triggers pipeline
+ * execution directly from the terminal or an agentic IDE. `pipelines run`
+ * calls `runPipeline` — the same function used by API handlers and timers —
+ * so CLI executions are fully recorded in `pipeline_executions`.
+ *
+ * **Commands:**
+ * | Subcommand                            | Description                              |
+ * |---------------------------------------|------------------------------------------|
+ * | `pipelines list [--account] [--all]`  | List active (or all) pipelines           |
+ * | `pipelines get <id>`                  | Show pipeline details                    |
+ * | `pipelines run <id> [--data <json>]`  | Execute a pipeline and show stage output |
+ * | `pipelines executions <id>`           | List recent executions for a pipeline    |
+ *
+ * **Usage:**
+ * ```bash
+ * spine pipelines list --account <id>
+ * spine pipelines run <uuid> --data '{"key":"value"}' --json
+ * spine pipelines executions <uuid> --limit 20
+ * ```
+ *
+ * @seeAlso cli/context.ts (buildCliContext)
+ * @seeAlso functions/_shared/pipeline-runner.ts (runPipeline)
+ * @seeAlso functions/pipeline-executions.ts (API query endpoint)
+ */
+
+import type { Command } from 'commander'
+import { buildCliContext, printResult, handleError } from '../context.ts'
+import { runPipeline, adminDb } from '../../functions/_shared/index.ts'
+
+/**
+ * Registers the `pipelines` subcommand group on the root Commander program.
+ *
+ * @param program - The root `spine` Commander instance
+ * @sideEffects Adds `pipelines list/get/run/executions` subcommands to `program`
+ * @calledBy cli/index.ts
+ */
+export function registerPipelineCommands(program: Command) {
+  const pipelines = program
+    .command('pipelines')
+    .description('Pipeline management and execution')
+
+  pipelines
+    .command('list')
+    .description('List all active pipelines')
+    .option('--account <id>', 'Filter by account ID')
+    .option('--json', 'Output as JSON')
+    .option('--all', 'Include inactive pipelines')
+    .action(async (opts) => {
+      try {
+        const ctx = await buildCliContext({ account: opts.account })
+
+        let query = adminDb
+          .from('pipelines')
+          .select('id, name, description, is_active, created_at')
+          .order('name')
+
+        if (!opts.all) {
+          query = query.eq('is_active', true)
+        }
+
+        if (ctx.accountId) {
+          query = query.eq('account_id', ctx.accountId)
+        }
+
+        const { data, error } = await query
+
+        if (error) throw new Error(error.message)
+        printResult(data || [], { json: opts.json })
+      } catch (err: any) {
+        handleError(err)
+      }
+    })
+
+  pipelines
+    .command('get <id>')
+    .description('Show pipeline details')
+    .option('--json', 'Output as JSON')
+    .action(async (id, opts) => {
+      try {
+        await buildCliContext()
+
+        const { data, error } = await adminDb
+          .from('pipelines')
+          .select('*')
+          .eq('id', id)
+          .single()
+
+        if (error || !data) throw new Error(error?.message || `Pipeline not found: ${id}`)
+        printResult(data, { json: opts.json })
+      } catch (err: any) {
+        handleError(err)
+      }
+    })
+
+  pipelines
+    .command('run <id>')
+    .description('Execute a pipeline')
+    .option('--data <json>', 'Trigger data as JSON string', '{}')
+    .option('--account <id>', 'Account scope for the execution')
+    .option('--json', 'Output result as JSON')
+    .action(async (id, opts) => {
+      try {
+        const ctx = await buildCliContext({ account: opts.account })
+
+        let triggerData: any = {}
+        try {
+          triggerData = JSON.parse(opts.data)
+        } catch {
+          throw new Error(`--data must be valid JSON. Got: ${opts.data}`)
+        }
+
+        console.log(`Running pipeline ${id}...`)
+        const result = await runPipeline(id, triggerData, ctx)
+
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2))
+        } else {
+          const icon = result.status === 'completed' ? '✓' : '✗'
+          console.log(`\n${icon} Pipeline ${result.status}`)
+          console.log(`  Execution ID: ${result.executionId}`)
+          console.log(`  Duration:     ${result.durationMs}ms`)
+          console.log(`  Stages:       ${result.stages.length}`)
+          result.stages.forEach((s: any, i: number) => {
+            const stageIcon = s.status === 'success' ? '✓' : s.status === 'skipped' ? '○' : '✗'
+            console.log(`    ${stageIcon} [${i}] ${s.stageType} (${s.durationMs}ms)${s.error ? ` — ${s.error}` : ''}`)
+          })
+          if (result.error) {
+            console.log(`\n  Error: ${result.error}`)
+          }
+          console.log()
+        }
+      } catch (err: any) {
+        handleError(err)
+      }
+    })
+
+  pipelines
+    .command('executions <id>')
+    .description('List recent executions for a pipeline')
+    .option('--limit <n>', 'Number of executions to show', '10')
+    .option('--json', 'Output as JSON')
+    .action(async (id, opts) => {
+      try {
+        await buildCliContext()
+
+        const { data, error } = await adminDb
+          .from('pipeline_executions')
+          .select('id, status, started_at, completed_at, duration_ms, error_message')
+          .eq('pipeline_id', id)
+          .order('started_at', { ascending: false })
+          .limit(parseInt(opts.limit))
+
+        if (error) throw new Error(error.message)
+        printResult(data || [], { json: opts.json })
+      } catch (err: any) {
+        handleError(err)
+      }
+    })
+}

package/.framework/cli/commands/status.ts

@@ -0,0 +1,197 @@
+/// <reference types="node" />
+/**
+ * @module cli/commands/status
+ * @audience installer
+ * @layer cli
+ * @stability stable
+ *
+ * `spine-framework status` — Show the current state of the Spine installation.
+ *
+ * Displays:
+ * - Database connection status
+ * - Installed apps and their seed state
+ * - Migration history
+ * - Webhook handler registrations
+ *
+ * **Usage:**
+ * ```bash
+ * spine-framework status
+ * spine-framework status --json
+ * ```
+ */
+
+import type { Command } from 'commander'
+import { existsSync, readdirSync } from 'fs'
+import { resolve, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import { adminDb } from '../../functions/_shared/index.ts'
+import { discoverManifests } from '../../functions/_shared/app-manifest.ts'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const PROJECT_ROOT = resolve(__dirname, '../../../')
+
+interface StatusOptions {
+  json: boolean
+}
+
+interface StatusReport {
+  database: { connected: boolean; error?: string }
+  apps: Array<{ slug: string; name: string; hasManifest: boolean; hasSeed: boolean; installed: boolean }>
+  webhookHandlers: Array<{ name: string; functionName: string; isActive: boolean }>
+  typeCounts: { total: number; byApp: Record<string, number> }
+}
+
+async function gatherStatus(): Promise<StatusReport> {
+  const report: StatusReport = {
+    database: { connected: false },
+    apps: [],
+    webhookHandlers: [],
+    typeCounts: { total: 0, byApp: {} },
+  }
+
+  // 1. Database connection
+  try {
+    const { data, error } = await adminDb
+      .from('apps')
+      .select('slug')
+      .limit(1)
+
+    if (error) {
+      report.database = { connected: false, error: error.message }
+    } else {
+      report.database = { connected: true }
+    }
+  } catch (err: any) {
+    report.database = { connected: false, error: err.message }
+    return report
+  }
+
+  // 2. Apps — merge filesystem + database
+  const manifests = discoverManifests()
+  const { data: dbApps } = await adminDb
+    .from('apps')
+    .select('slug, name, is_active')
+    .eq('is_active', true)
+    .order('slug')
+
+  const { data: installations } = await adminDb
+    .from('app_installations')
+    .select('app_slug, is_enabled')
+
+  const installedSlugs = new Set(
+    (installations || []).filter(i => i.is_enabled).map(i => i.app_slug)
+  )
+
+  const allSlugs = new Set([
+    ...manifests.map(m => m.slug),
+    ...(dbApps || []).map(a => a.slug).filter(s => s !== 'spine-core'),
+  ])
+
+  for (const slug of allSlugs) {
+    const manifest = manifests.find(m => m.slug === slug)
+    const dbApp = dbApps?.find(a => a.slug === slug)
+    const seedDir = resolve(PROJECT_ROOT, `custom/apps/${slug}/seed`)
+
+    report.apps.push({
+      slug,
+      name: dbApp?.name || slug,
+      hasManifest: !!manifest,
+      hasSeed: existsSync(seedDir) && readdirSync(seedDir).some(f => f.endsWith('.json')),
+      installed: installedSlugs.has(slug),
+    })
+  }
+
+  // 3. Webhook handlers
+  const { data: handlers } = await adminDb
+    .from('webhook_handlers')
+    .select('name, function_name, is_active')
+    .order('name')
+
+  report.webhookHandlers = (handlers || []).map(h => ({
+    name: h.name,
+    functionName: h.function_name,
+    isActive: h.is_active,
+  }))
+
+  // 4. Type counts by app
+  const { data: types } = await adminDb
+    .from('types')
+    .select('slug, app_id, apps!inner(slug)')
+    .eq('is_active', true)
+
+  report.typeCounts.total = types?.length || 0
+  for (const t of types || []) {
+    const appSlug = (t as any).apps?.slug || 'unassigned'
+    report.typeCounts.byApp[appSlug] = (report.typeCounts.byApp[appSlug] || 0) + 1
+  }
+
+  return report
+}
+
+function printStatus(report: StatusReport): void {
+  console.log('\n🔍 Spine Framework Status\n')
+
+  // Database
+  if (report.database.connected) {
+    console.log('  📡 Database: ✅ Connected')
+  } else {
+    console.log(`  📡 Database: ❌ ${report.database.error || 'Not connected'}`)
+    return
+  }
+
+  // Apps
+  console.log(`\n  📱 Apps (${report.apps.length}):`)
+  if (report.apps.length === 0) {
+    console.log('     (none)')
+  } else {
+    for (const app of report.apps) {
+      const status = [
+        app.hasManifest ? '📋 manifest' : '',
+        app.hasSeed ? '🌱 seed' : '',
+        app.installed ? '✅ installed' : '⬜ not installed',
+      ].filter(Boolean).join('  ')
+      console.log(`     ${app.slug.padEnd(24)} ${status}`)
+    }
+  }
+
+  // Webhook handlers
+  console.log(`\n  🔗 Webhook Handlers (${report.webhookHandlers.length}):`)
+  if (report.webhookHandlers.length === 0) {
+    console.log('     (none)')
+  } else {
+    for (const h of report.webhookHandlers) {
+      const status = h.isActive ? '✅' : '❌'
+      console.log(`     ${status} ${h.name.padEnd(24)} → ${h.functionName}`)
+    }
+  }
+
+  // Types
+  console.log(`\n  📊 Types (${report.typeCounts.total} total):`)
+  for (const [app, count] of Object.entries(report.typeCounts.byApp).sort()) {
+    console.log(`     ${app.padEnd(24)} ${count} types`)
+  }
+
+  console.log('')
+}
+
+export function registerStatusCommands(program: Command) {
+  program
+    .command('status')
+    .description('Show the current state of the Spine installation')
+    .option('--json', 'Output as JSON', false)
+    .action(async (opts: StatusOptions) => {
+      try {
+        const report = await gatherStatus()
+        if (opts.json) {
+          console.log(JSON.stringify(report, null, 2))
+        } else {
+          printStatus(report)
+        }
+      } 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/system.ts

@@ -0,0 +1,184 @@
+/// <reference types="node" />
+/**
+ * @module cli/commands/system
+ * @audience installer
+ * @layer cli
+ * @stability stable
+ *
+ * `spine system` command — CLI interface to system discovery endpoints.
+ * Queries the running Spine instance for manifest, health, and OpenAPI spec.
+ *
+ * **Commands:**
+ * | Subcommand              | Description                                           |
+ * |-------------------------|-------------------------------------------------------|
+ * | `system manifest`       | Fetch and display system manifest                     |
+ * | `system health`         | Fetch and display health check results                |
+ * | `system openapi`        | Fetch OpenAPI spec (outputs JSON)                     |
+ * | `system --json`         | Output as JSON for all subcommands                    |
+ *
+ * **Usage:**
+ * ```bash
+ * spine system manifest
+ * spine system health --json
+ * spine system openapi > openapi.json
+ * ```
+ *
+ * @seeAlso functions/system.ts (HTTP endpoints this CLI consumes)
+ */
+
+import type { Command } from 'commander'
+import { buildCliContext, printResult, handleError } from '../context.ts'
+
+// ─── API CLIENT ────────────────────────────────────────────────────────────
+
+async function fetchSystemEndpoint(ctx: any, action: string): Promise<any> {
+  const supabaseUrl = process.env.SUPABASE_URL
+  if (!supabaseUrl) {
+    throw new Error('SUPABASE_URL not configured')
+  }
+
+  // Construct the Netlify function URL
+  // When running locally, this is http://localhost:8888/.netlify/functions/system
+  // We'll try localhost:8888 first, then fall back to production URL if configured
+  const localUrl = 'http://localhost:8888/.netlify/functions/system'
+  const url = `${localUrl}?action=${action}`
+
+  try {
+    const response = await fetch(url, {
+      method: 'GET',
+      headers: {
+        'Accept': 'application/json',
+        'x-app-id': 'cli-system'
+      }
+    })
+
+    if (!response.ok) {
+      const text = await response.text()
+      throw new Error(`HTTP ${response.status}: ${text}`)
+    }
+
+    return await response.json()
+  } catch (err: any) {
+    // If local fails, try direct Supabase function invoke (for production)
+    if (err.message.includes('fetch failed') || err.message.includes('ECONNREFUSED')) {
+      throw new Error(
+        'Cannot connect to local dev server. ' +
+        'Ensure `spine dev` or `netlify dev` is running on port 8888.'
+      )
+    }
+    throw err
+  }
+}
+
+// ─── COMMAND REGISTRATION ────────────────────────────────────────────────
+
+export function registerSystemCommands(program: Command) {
+  const system = program
+    .command('system')
+    .description('System discovery and health commands')
+
+  system
+    .command('manifest')
+    .description('Fetch system manifest (version, functions, migrations)')
+    .option('--json', 'Output as JSON')
+    .action(async (opts) => {
+      try {
+        const ctx = await buildCliContext()
+        const result = await fetchSystemEndpoint(ctx, 'manifest')
+
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2))
+        } else {
+          console.log('\n📋 Spine System Manifest')
+          console.log('─'.repeat(50))
+
+          if (result.data) {
+            const m = result.data
+            console.log(`Version:     ${m.version}`)
+            console.log(`Schema:      ${m.schema}`)
+            console.log(`Migrations:  ${m.migrations?.applied || 0} applied` +
+              (m.migrations?.pending ? `, ${m.migrations.pending} pending` : ''))
+            console.log(`Functions:   ${m.functions?.length || 0} endpoints`)
+            console.log(`Integrity:   ${m.integrity?.verified ? '✓ verified' : '⚠ not verified'}`)
+
+            if (m.functions?.length > 0) {
+              console.log('\nAvailable Functions:')
+              for (const fn of m.functions.slice(0, 10)) {
+                console.log(`  • ${fn.name} (${fn.methods.join(',')})`)
+              }
+              if (m.functions.length > 10) {
+                console.log(`  ... and ${m.functions.length - 10} more`)
+              }
+            }
+          } else {
+            console.log('No manifest data returned')
+          }
+          console.log()
+        }
+      } catch (err: any) {
+        handleError(err)
+      }
+    })
+
+  system
+    .command('health')
+    .description('Fetch health check status')
+    .option('--json', 'Output as JSON')
+    .action(async (opts) => {
+      try {
+        const ctx = await buildCliContext()
+        const result = await fetchSystemEndpoint(ctx, 'health')
+
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2))
+        } else {
+          console.log('\n🏥 Spine Health Check')
+          console.log('─'.repeat(50))
+
+          if (result.data) {
+            const h = result.data
+            const statusIcon = h.status === 'healthy' ? '✓' :
+                              h.status === 'degraded' ? '⚠' : '✗'
+            console.log(`Status: ${statusIcon} ${h.status.toUpperCase()}`)
+            console.log()
+
+            if (h.checks) {
+              for (const [name, check] of Object.entries(h.checks)) {
+                const c = check as any
+                const icon = c.connected || c.current || c.verified ? '✓' :
+                            c.status === 'passed' ? '✓' : '⚠'
+                console.log(`${icon} ${name}:`)
+                if (c.latency_ms !== undefined) {
+                  console.log(`    latency: ${c.latency_ms}ms`)
+                }
+                if (c.applied !== undefined) {
+                  console.log(`    applied: ${c.applied}, pending: ${c.pending}`)
+                }
+                if (c.last_suite) {
+                  console.log(`    last run: ${c.last_suite} (${c.last_status})`)
+                }
+              }
+            }
+          } else {
+            console.log('No health data returned')
+          }
+          console.log()
+        }
+      } catch (err: any) {
+        handleError(err)
+      }
+    })
+
+  system
+    .command('openapi')
+    .description('Fetch OpenAPI specification')
+    .action(async () => {
+      try {
+        const ctx = await buildCliContext()
+        const result = await fetchSystemEndpoint(ctx, 'openapi')
+        console.log(JSON.stringify(result.data || result, null, 2))
+      } catch (err: any) {
+        handleError(err)
+      }
+    })
+}