spine-framework 0.3.19 → 0.3.21

package/.framework/cli/commands/init.ts

@@ -0,0 +1,202 @@
+/// <reference types="node" />
+/**
+ * @module cli/commands/init
+ * @audience installer
+ * @layer cli
+ * @stability stable
+ *
+ * `spine-framework init` — scaffolds a new Spine Framework project in the
+ * current directory. Copies framework files, creates the custom/ workspace,
+ * writes package.json and .env template.
+ *
+ * **Usage:**
+ * ```bash
+ * npx spine-framework init
+ * ```
+ */
+
+import type { Command } from 'commander'
+import { existsSync, mkdirSync, writeFileSync, copyFileSync, readdirSync, statSync, cpSync } from 'fs'
+import { resolve, dirname, join } from 'path'
+import { fileURLToPath } from 'url'
+import { execSync } from 'child_process'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+// Root of the spine-framework package (node_modules/spine-framework/)
+const PACKAGE_ROOT = resolve(__dirname, '../../../')
+// Root of the user's project (cwd)
+const PROJECT_ROOT = process.cwd()
+
+export function registerInitCommands(program: Command) {
+  program
+    .command('init')
+    .description('Scaffold a new Spine Framework project in the current directory')
+    .option('--force', 'Overwrite existing files', false)
+    .action(async (opts) => {
+      console.log('\nInitializing Spine Framework project...\n')
+
+      // Guard: don't overwrite an existing project unless --force
+      if (existsSync(join(PROJECT_ROOT, 'package.json')) && !opts.force) {
+        console.error('Error: package.json already exists. Use --force to overwrite.')
+        process.exit(1)
+      }
+
+      try {
+        // 1. Copy .framework/ into the project
+        console.log('  Copying .framework/...')
+        const fwSrc = join(PACKAGE_ROOT, '.framework')
+        const fwDest = join(PROJECT_ROOT, '.framework')
+        if (!existsSync(fwDest)) {
+          cpSync(fwSrc, fwDest, { recursive: true })
+          console.log('  ✓ .framework/ copied')
+        } else {
+          console.log('  ○ .framework/ already exists, skipping')
+        }
+
+        // 2. Create custom/ workspace directories
+        console.log('  Creating custom/ workspace...')
+        const customDirs = [
+          'custom/apps',
+          'custom/functions',
+          'custom/components',
+          'custom/migrations',
+          'custom/tests',
+        ]
+        for (const dir of customDirs) {
+          const full = join(PROJECT_ROOT, dir)
+          if (!existsSync(full)) {
+            mkdirSync(full, { recursive: true })
+          }
+        }
+        // Copy custom/.devin if present in package
+        const devinSrc = join(PACKAGE_ROOT, 'custom/.devin')
+        const devinDest = join(PROJECT_ROOT, 'custom/.devin')
+        if (existsSync(devinSrc) && !existsSync(devinDest)) {
+          cpSync(devinSrc, devinDest, { recursive: true })
+        }
+        console.log('  ✓ custom/ workspace created')
+
+        // 3. Copy config files (vite, tailwind, tsconfig, postcss)
+        console.log('  Copying config files...')
+        const configSrc = join(PACKAGE_ROOT, 'config')
+        const configDest = join(PROJECT_ROOT, 'config')
+        if (existsSync(configSrc) && !existsSync(configDest)) {
+          cpSync(configSrc, configDest, { recursive: true })
+          console.log('  ✓ config/ copied')
+        }
+
+        // 4. Copy scripts/
+        console.log('  Copying scripts/...')
+        const scriptsSrc = join(PACKAGE_ROOT, 'scripts')
+        const scriptsDest = join(PROJECT_ROOT, 'scripts')
+        if (existsSync(scriptsSrc) && !existsSync(scriptsDest)) {
+          cpSync(scriptsSrc, scriptsDest, { recursive: true })
+          console.log('  ✓ scripts/ copied')
+        }
+
+        // 5. Copy netlify.toml
+        const netlifyTomlSrc = join(PACKAGE_ROOT, 'netlify.toml')
+        if (existsSync(netlifyTomlSrc) && !existsSync(join(PROJECT_ROOT, 'netlify.toml'))) {
+          copyFileSync(netlifyTomlSrc, join(PROJECT_ROOT, 'netlify.toml'))
+          console.log('  ✓ netlify.toml copied')
+        }
+
+        // 6. Write package.json
+        console.log('  Writing package.json...')
+        const projectName = PROJECT_ROOT.split('/').pop() || 'my-spine-project'
+        const pkgJson = {
+          name: projectName,
+          version: '0.1.0',
+          private: true,
+          type: 'module',
+          scripts: {
+            dev: 'netlify dev',
+            assemble: 'bash scripts/assemble.sh',
+            'assemble:frontend': 'bash scripts/assemble-frontend.sh',
+            'assemble:functions': 'bash scripts/assemble-functions.sh',
+            build: 'npm run assemble && vite build --config config/vite.config.ts',
+            verify: 'bash scripts/verify-integrity.sh',
+            test: 'vitest run',
+          },
+          dependencies: {
+            'spine-framework': `^${getPackageVersion()}`,
+          },
+        }
+        if (!existsSync(join(PROJECT_ROOT, 'package.json')) || opts.force) {
+          writeFileSync(
+            join(PROJECT_ROOT, 'package.json'),
+            JSON.stringify(pkgJson, null, 2) + '\n'
+          )
+          console.log('  ✓ package.json written')
+        }
+
+        // 7. Write .env template
+        console.log('  Writing .env template...')
+        if (!existsSync(join(PROJECT_ROOT, '.env'))) {
+          const envTemplate = [
+            '# Supabase credentials',
+            '# Get these from: Supabase Dashboard → Your Project → Settings → API',
+            'SUPABASE_URL=https://<project-ref>.supabase.co',
+            'SUPABASE_ANON_KEY=',
+            'SUPABASE_SERVICE_ROLE_KEY=',
+            'SUPABASE_DB_PASSWORD=',
+            '',
+            '# Vite (browser-safe)',
+            'VITE_SUPABASE_URL=https://<project-ref>.supabase.co',
+            'VITE_SUPABASE_ANON_KEY=',
+            'VITE_DB_SCHEMA=public',
+            'VITE_APP_NAME=Spine',
+            '',
+          ].join('\n')
+          writeFileSync(join(PROJECT_ROOT, '.env'), envTemplate)
+          console.log('  ✓ .env template written')
+        } else {
+          console.log('  ○ .env already exists, skipping')
+        }
+
+        // 8. Write .gitignore
+        if (!existsSync(join(PROJECT_ROOT, '.gitignore'))) {
+          const gitignore = [
+            'node_modules',
+            'dist',
+            '.assembled/',
+            '.netlify',
+            '.env',
+            '.env.local',
+            '.env.production',
+            '*.log',
+            '.DS_Store',
+            '*.tsbuildinfo',
+            '.vite',
+          ].join('\n') + '\n'
+          writeFileSync(join(PROJECT_ROOT, '.gitignore'), gitignore)
+          console.log('  ✓ .gitignore written')
+        }
+
+        console.log('\n✅ Project initialized!\n')
+        console.log('Next steps:')
+        console.log('  1. Edit .env with your Supabase credentials')
+        console.log('  2. Run: npx spine-framework migrate')
+        console.log('  3. Run: npm install && npm run assemble && netlify dev')
+        console.log()
+
+      } catch (err: any) {
+        console.error('\n❌ Init failed:', err.message)
+        if (process.env.SPINE_CLI_DEBUG) console.error(err.stack)
+        process.exit(1)
+      }
+    })
+}
+
+function getPackageVersion(): string {
+  try {
+    const pkg = JSON.parse(
+      require('fs').readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8')
+    )
+    return pkg.version || '0.3.0'
+  } catch {
+    return '0.3.0'
+  }
+}

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

@@ -0,0 +1,255 @@
+/// <reference types="node" />
+/**
+ * @module cli/commands/install-app
+ * @audience installer
+ * @layer cli
+ * @stability stable
+ *
+ * `spine-framework install-app` — installs a Spine Framework app from npm.
+ * Copies app files into custom/apps/, seeds types/roles/link-types into the DB.
+ *
+ * **Usage:**
+ * ```bash
+ * npx spine-framework install-app spine-framework-portal@latest
+ * npx spine-framework install-app spine-framework-cortex
+ * npx spine-framework uninstall-app spine-framework-portal
+ * npx spine-framework update-app spine-framework-portal
+ * ```
+ */
+
+import type { Command } from 'commander'
+import { existsSync, readFileSync, mkdirSync, cpSync } from 'fs'
+import { resolve, dirname, join, basename } from 'path'
+import { fileURLToPath } from 'url'
+import { execSync } from 'child_process'
+import { createClient } from '@supabase/supabase-js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const PROJECT_ROOT = process.cwd()
+
+export function registerInstallAppCommands(program: Command) {
+  // install-app
+  program
+    .command('install-app <package>')
+    .description('Install a Spine Framework app from npm')
+    .option('--no-seed', 'Skip seeding types and roles into the database', false)
+    .action(async (packageName: string, opts) => {
+      console.log(`\nInstalling app: ${packageName}\n`)
+
+      loadEnv()
+
+      try {
+        // 1. npm install the package
+        console.log(`  Installing ${packageName} via npm...`)
+        execSync(`npm install ${packageName} --save`, {
+          cwd: PROJECT_ROOT,
+          stdio: 'inherit',
+        })
+        console.log('  ✓ npm install complete')
+
+        // 2. Resolve package location in node_modules
+        const pkgSlug = packageName.split('@')[0] // strip version
+        const pkgPath = join(PROJECT_ROOT, 'node_modules', pkgSlug)
+
+        if (!existsSync(pkgPath)) {
+          throw new Error(`Package not found at ${pkgPath}`)
+        }
+
+        // 3. Determine app slug from package manifest or name
+        const appSlug = resolveAppSlug(pkgPath, pkgSlug)
+        console.log(`  App slug: ${appSlug}`)
+
+        // 4. Copy app files to custom/apps/<slug>/
+        const appDest = join(PROJECT_ROOT, 'custom/apps', appSlug)
+        if (!existsSync(appDest)) {
+          mkdirSync(appDest, { recursive: true })
+        }
+
+        // Copy everything except node_modules and package.json internals
+        const skipDirs = new Set(['node_modules', '.git'])
+        for (const entry of ['index.tsx', 'manifest.json', 'pages', 'components', 'hooks', 'api', 'seed']) {
+          const src = join(pkgPath, entry)
+          if (existsSync(src)) {
+            cpSync(src, join(appDest, entry), { recursive: true })
+          }
+        }
+        console.log(`  ✓ App files copied to custom/apps/${appSlug}/`)
+
+        // 5. Seed types, roles, link-types into database
+        if (!opts.seed === false) {
+          await seedApp(appDest, appSlug)
+        }
+
+        console.log(`\n✅ ${appSlug} installed successfully!\n`)
+        console.log('Next: npm run assemble && netlify dev\n')
+
+      } catch (err: any) {
+        console.error(`\n❌ Install failed: ${err.message}`)
+        if (process.env.SPINE_CLI_DEBUG) console.error(err.stack)
+        process.exit(1)
+      }
+    })
+
+  // uninstall-app
+  program
+    .command('uninstall-app <package>')
+    .description('Remove an installed Spine Framework app')
+    .option('--keep-data', 'Keep seeded types and roles in the database', false)
+    .action(async (packageName: string, opts) => {
+      console.log(`\nUninstalling app: ${packageName}\n`)
+      loadEnv()
+
+      const pkgSlug = packageName.split('@')[0]
+      const appSlug = pkgSlug.replace('spine-framework-', '')
+      const appDir = join(PROJECT_ROOT, 'custom/apps', appSlug)
+
+      try {
+        if (existsSync(appDir)) {
+          const { rmSync } = await import('fs')
+          rmSync(appDir, { recursive: true, force: true })
+          console.log(`  ✓ Removed custom/apps/${appSlug}/`)
+        } else {
+          console.log(`  ○ custom/apps/${appSlug}/ not found, nothing to remove`)
+        }
+
+        execSync(`npm uninstall ${pkgSlug}`, { cwd: PROJECT_ROOT, stdio: 'inherit' })
+        console.log(`  ✓ npm uninstall complete`)
+
+        console.log(`\n✅ ${appSlug} uninstalled.\n`)
+      } catch (err: any) {
+        console.error(`\n❌ Uninstall failed: ${err.message}`)
+        process.exit(1)
+      }
+    })
+
+  // update-app
+  program
+    .command('update-app <package>')
+    .description('Update an installed Spine Framework app to a newer version')
+    .action(async (packageName: string) => {
+      console.log(`\nUpdating app: ${packageName}\n`)
+      loadEnv()
+
+      try {
+        execSync(`npm install ${packageName}@latest --save`, {
+          cwd: PROJECT_ROOT,
+          stdio: 'inherit',
+        })
+
+        const pkgSlug = packageName.split('@')[0]
+        const pkgPath = join(PROJECT_ROOT, 'node_modules', pkgSlug)
+        const appSlug = resolveAppSlug(pkgPath, pkgSlug)
+        const appDest = join(PROJECT_ROOT, 'custom/apps', appSlug)
+
+        if (!existsSync(appDest)) {
+          mkdirSync(appDest, { recursive: true })
+        }
+
+        for (const entry of ['index.tsx', 'manifest.json', 'pages', 'components', 'hooks', 'api', 'seed']) {
+          const src = join(pkgPath, entry)
+          if (existsSync(src)) {
+            cpSync(src, join(appDest, entry), { recursive: true })
+          }
+        }
+
+        console.log(`\n✅ ${appSlug} updated.\n`)
+      } catch (err: any) {
+        console.error(`\n❌ Update failed: ${err.message}`)
+        process.exit(1)
+      }
+    })
+}
+
+// ─── HELPERS ────────────────────────────────────────────────────────────────
+
+function resolveAppSlug(pkgPath: string, pkgName: string): string {
+  try {
+    const manifest = JSON.parse(readFileSync(join(pkgPath, 'manifest.json'), 'utf8'))
+    if (manifest.slug) return manifest.slug
+  } catch {}
+  // Derive from package name: spine-framework-portal → portal
+  return pkgName.replace(/^spine-framework-/, '')
+}
+
+function loadEnv() {
+  const envPath = join(PROJECT_ROOT, '.env')
+  if (!existsSync(envPath)) return
+  const lines = readFileSync(envPath, 'utf8').split('\n')
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+    const eqIdx = trimmed.indexOf('=')
+    if (eqIdx === -1) continue
+    const key = trimmed.slice(0, eqIdx).trim()
+    const val = trimmed.slice(eqIdx + 1).trim()
+    if (key && !(key in process.env)) process.env[key] = val
+  }
+}
+
+async function seedApp(appDir: string, appSlug: string) {
+  const supabaseUrl = process.env.SUPABASE_URL
+  const serviceRoleKey = process.env.SUPABASE_SERVICE_ROLE_KEY
+
+  if (!supabaseUrl || !serviceRoleKey) {
+    console.log('  ○ Skipping DB seed (SUPABASE_URL / SUPABASE_SERVICE_ROLE_KEY not set)')
+    return
+  }
+
+  const db = createClient(supabaseUrl, serviceRoleKey, {
+    auth: { persistSession: false },
+  })
+
+  // Get spine-core app id for foreign key
+  const { data: coreApp } = await db
+    .from('apps')
+    .select('id')
+    .eq('slug', appSlug)
+    .single()
+
+  const appId = coreApp?.id
+
+  // Seed types
+  const typesPath = join(appDir, 'seed/types.json')
+  if (existsSync(typesPath)) {
+    const types = JSON.parse(readFileSync(typesPath, 'utf8'))
+    console.log(`  Seeding ${types.length} type(s) for ${appSlug}...`)
+    for (const type of types) {
+      const { error } = await db
+        .from('types')
+        .upsert({ ...type, app_id: appId }, { onConflict: 'slug' })
+      if (error) console.warn(`    ⚠ type ${type.slug}: ${error.message}`)
+    }
+    console.log(`  ✓ Types seeded`)
+  }
+
+  // Seed roles
+  const rolesPath = join(appDir, 'seed/roles.json')
+  if (existsSync(rolesPath)) {
+    const roles = JSON.parse(readFileSync(rolesPath, 'utf8'))
+    console.log(`  Seeding ${roles.length} role(s) for ${appSlug}...`)
+    for (const role of roles) {
+      const { error } = await db
+        .from('roles')
+        .upsert({ ...role, app_id: appId }, { onConflict: 'slug' })
+      if (error) console.warn(`    ⚠ role ${role.slug}: ${error.message}`)
+    }
+    console.log(`  ✓ Roles seeded`)
+  }
+
+  // Seed link-types
+  const linkTypesPath = join(appDir, 'seed/link-types.json')
+  if (existsSync(linkTypesPath)) {
+    const linkTypes = JSON.parse(readFileSync(linkTypesPath, 'utf8'))
+    if (linkTypes.length > 0) {
+      console.log(`  Seeding ${linkTypes.length} link type(s) for ${appSlug}...`)
+      for (const lt of linkTypes) {
+        const { error } = await db
+          .from('link_types')
+          .upsert({ ...lt, app_id: appId }, { onConflict: 'slug' })
+        if (error) console.warn(`    ⚠ link_type ${lt.slug}: ${error.message}`)
+      }
+      console.log(`  ✓ Link types seeded`)
+    }
+  }
+}

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

@@ -0,0 +1,241 @@
+/// <reference types="node" />
+/**
+ * @module cli/commands/migrate
+ * @audience installer
+ * @layer cli
+ * @stability stable
+ *
+ * `spine-framework migrate` — applies pending SQL migrations to the configured
+ * Supabase project using the Supabase Management API and direct DB connection.
+ *
+ * Reads migration files from `.framework/migrations/` and `custom/migrations/`
+ * in order, skipping any already tracked in `spine_migrations` table.
+ *
+ * **Usage:**
+ * ```bash
+ * npx spine-framework migrate
+ * npx spine-framework migrate --dry-run
+ * ```
+ */
+
+import type { Command } from 'commander'
+import { readFileSync, readdirSync, existsSync } from 'fs'
+import { resolve, dirname, join, basename } from 'path'
+import { fileURLToPath } from 'url'
+import { createClient } from '@supabase/supabase-js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const PACKAGE_ROOT = resolve(__dirname, '../../../')
+const PROJECT_ROOT = process.cwd()
+
+export function registerMigrateCommands(program: Command) {
+  program
+    .command('migrate')
+    .description('Apply pending database migrations to your Supabase project')
+    .option('--dry-run', 'Show pending migrations without applying them', false)
+    .option('--framework-only', 'Only apply .framework/migrations/, skip custom/', false)
+    .action(async (opts) => {
+      console.log('\nRunning Spine Framework migrations...\n')
+
+      // Load env
+      loadEnv()
+
+      const supabaseUrl = process.env.SUPABASE_URL
+      const serviceRoleKey = process.env.SUPABASE_SERVICE_ROLE_KEY
+
+      if (!supabaseUrl || !serviceRoleKey) {
+        console.error('Error: SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY must be set in .env')
+        console.error('Run: npx spine-framework init  to create a .env template')
+        process.exit(1)
+      }
+
+      const db = createClient(supabaseUrl, serviceRoleKey, {
+        auth: { persistSession: false },
+        db: { schema: 'public' },
+      })
+
+      try {
+        // Ensure tracking table exists
+        await ensureMigrationsTable(db)
+
+        // Collect migration files in order
+        const migrationFiles = collectMigrations(opts.frameworkOnly)
+
+        if (migrationFiles.length === 0) {
+          console.log('No migration files found.')
+          process.exit(0)
+        }
+
+        // Get already-applied migrations
+        const { data: applied, error: fetchErr } = await db
+          .from('spine_migrations')
+          .select('filename')
+          .order('applied_at', { ascending: true })
+
+        if (fetchErr) throw new Error(`Could not read migration state: ${fetchErr.message}`)
+
+        const appliedSet = new Set((applied || []).map((r: any) => r.filename))
+
+        const pending = migrationFiles.filter(f => !appliedSet.has(basename(f)))
+
+        if (pending.length === 0) {
+          console.log('✓ All migrations already applied. Nothing to do.\n')
+          process.exit(0)
+        }
+
+        console.log(`Found ${pending.length} pending migration(s):\n`)
+        for (const f of pending) {
+          console.log(`  ○ ${basename(f)}`)
+        }
+        console.log()
+
+        if (opts.dryRun) {
+          console.log('Dry run — no changes made.\n')
+          process.exit(0)
+        }
+
+        // Apply each pending migration
+        let applied_count = 0
+        for (const filepath of pending) {
+          const filename = basename(filepath)
+          process.stdout.write(`  Applying ${filename}...`)
+
+          const sql = readFileSync(filepath, 'utf8')
+
+          // Execute via rpc exec_sql or direct query
+          const { error } = await db.rpc('exec_sql' as any, { sql }).single()
+
+          if (error) {
+            // exec_sql may not exist — fall back to running via REST
+            const fallbackResult = await applyViaMigrationEndpoint(supabaseUrl, serviceRoleKey, sql)
+            if (!fallbackResult.ok) {
+              console.log(' ✗')
+              console.error(`\nFailed to apply ${filename}: ${fallbackResult.error}`)
+              console.error('\nFallback: Apply this migration manually in the Supabase SQL editor:')
+              console.error(`  ${filepath}`)
+              process.exit(1)
+            }
+          }
+
+          // Track as applied
+          await db.from('spine_migrations').insert({
+            filename,
+            applied_at: new Date().toISOString(),
+          })
+
+          console.log(' ✓')
+          applied_count++
+        }
+
+        console.log(`\n✅ Applied ${applied_count} migration(s) successfully.\n`)
+
+        if (applied_count > 0) {
+          console.log('Next: npx spine-framework status  — to verify the installation\n')
+        }
+
+      } catch (err: any) {
+        console.error('\n❌ Migration failed:', err.message)
+        if (process.env.SPINE_CLI_DEBUG) console.error(err.stack)
+        process.exit(1)
+      }
+    })
+}
+
+// ─── HELPERS ────────────────────────────────────────────────────────────────
+
+function loadEnv() {
+  const envPath = join(PROJECT_ROOT, '.env')
+  if (!existsSync(envPath)) return
+  const lines = readFileSync(envPath, 'utf8').split('\n')
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+    const eqIdx = trimmed.indexOf('=')
+    if (eqIdx === -1) continue
+    const key = trimmed.slice(0, eqIdx).trim()
+    const val = trimmed.slice(eqIdx + 1).trim()
+    if (key && !(key in process.env)) {
+      process.env[key] = val
+    }
+  }
+}
+
+async function ensureMigrationsTable(db: any) {
+  // Create tracking table if it doesn't exist
+  await db.rpc('exec_sql' as any, {
+    sql: `
+      CREATE TABLE IF NOT EXISTS public.spine_migrations (
+        id SERIAL PRIMARY KEY,
+        filename TEXT NOT NULL UNIQUE,
+        applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
+      );
+    `
+  })
+  // Ignore errors — table may already exist or exec_sql may not exist yet
+  // We'll handle this via the fallback path
+}
+
+function collectMigrations(frameworkOnly: boolean): string[] {
+  const files: string[] = []
+
+  // Framework migrations (from installed package or local .framework/)
+  const fwMigrationsDir = existsSync(join(PROJECT_ROOT, '.framework/migrations'))
+    ? join(PROJECT_ROOT, '.framework/migrations')
+    : join(PACKAGE_ROOT, '.framework/migrations')
+
+  if (existsSync(fwMigrationsDir)) {
+    const fwFiles = readdirSync(fwMigrationsDir)
+      .filter(f => f.endsWith('.sql') && !f.startsWith('.'))
+      .sort()
+      .map(f => join(fwMigrationsDir, f))
+    files.push(...fwFiles)
+  }
+
+  // Custom migrations (from project's custom/migrations/)
+  if (!frameworkOnly) {
+    const customMigrationsDir = join(PROJECT_ROOT, 'custom/migrations')
+    if (existsSync(customMigrationsDir)) {
+      const customFiles = readdirSync(customMigrationsDir)
+        .filter(f => f.endsWith('.sql') && !f.startsWith('.'))
+        .sort()
+        .map(f => join(customMigrationsDir, f))
+      files.push(...customFiles)
+    }
+  }
+
+  return files
+}
+
+async function applyViaMigrationEndpoint(
+  supabaseUrl: string,
+  serviceRoleKey: string,
+  sql: string
+): Promise<{ ok: boolean; error?: string }> {
+  try {
+    // Use Supabase's REST SQL endpoint
+    const projectRef = supabaseUrl.match(/https:\/\/([^.]+)\.supabase\.co/)?.[1]
+    if (!projectRef) return { ok: false, error: 'Could not parse project ref from SUPABASE_URL' }
+
+    const res = await fetch(
+      `https://api.supabase.com/v1/projects/${projectRef}/database/query`,
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${serviceRoleKey}`,
+        },
+        body: JSON.stringify({ query: sql }),
+      }
+    )
+
+    if (!res.ok) {
+      const body = await res.text()
+      return { ok: false, error: `API error ${res.status}: ${body}` }
+    }
+
+    return { ok: true }
+  } catch (err: any) {
+    return { ok: false, error: err.message }
+  }
+}

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

@@ -0,0 +1,153 @@
+/// <reference types="node" />
+/**
+ * @module cli/commands/status
+ * @audience installer
+ * @layer cli
+ * @stability stable
+ *
+ * `spine-framework status` — shows installed apps, migration state, and
+ * framework version.
+ *
+ * **Usage:**
+ * ```bash
+ * npx spine-framework status
+ * npx spine-framework status --json
+ * ```
+ */
+
+import type { Command } from 'commander'
+import { existsSync, readFileSync, readdirSync } from 'fs'
+import { resolve, dirname, join, basename } from 'path'
+import { fileURLToPath } from 'url'
+import { createClient } from '@supabase/supabase-js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const PACKAGE_ROOT = resolve(__dirname, '../../../')
+const PROJECT_ROOT = process.cwd()
+
+export function registerStatusCommands(program: Command) {
+  program
+    .command('status')
+    .description('Show installed apps and framework version')
+    .option('--json', 'Output as JSON')
+    .action(async (opts) => {
+      loadEnv()
+
+      const supabaseUrl = process.env.SUPABASE_URL
+      const serviceRoleKey = process.env.SUPABASE_SERVICE_ROLE_KEY
+
+      // Framework version
+      let frameworkVersion = 'unknown'
+      try {
+        const pkg = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8'))
+        frameworkVersion = pkg.version
+      } catch {}
+
+      // Installed apps (from custom/apps/)
+      const appsDir = join(PROJECT_ROOT, 'custom/apps')
+      const installedApps: { slug: string; version?: string; hasManifest: boolean }[] = []
+
+      if (existsSync(appsDir)) {
+        for (const slug of readdirSync(appsDir)) {
+          const appDir = join(appsDir, slug)
+          const manifestPath = join(appDir, 'manifest.json')
+          let version: string | undefined
+          let hasManifest = false
+          if (existsSync(manifestPath)) {
+            hasManifest = true
+            try {
+              const m = JSON.parse(readFileSync(manifestPath, 'utf8'))
+              version = m.version
+            } catch {}
+          }
+          installedApps.push({ slug, version, hasManifest })
+        }
+      }
+
+      // Migration state
+      let migrations: { applied: number; pending: number; files: string[] } = {
+        applied: 0,
+        pending: 0,
+        files: [],
+      }
+
+      const fwMigrationsDir = existsSync(join(PROJECT_ROOT, '.framework/migrations'))
+        ? join(PROJECT_ROOT, '.framework/migrations')
+        : join(PACKAGE_ROOT, '.framework/migrations')
+
+      if (existsSync(fwMigrationsDir)) {
+        migrations.files = readdirSync(fwMigrationsDir)
+          .filter(f => f.endsWith('.sql'))
+          .sort()
+      }
+
+      if (supabaseUrl && serviceRoleKey) {
+        try {
+          const db = createClient(supabaseUrl, serviceRoleKey, {
+            auth: { persistSession: false },
+          })
+          const { data } = await db
+            .from('spine_migrations')
+            .select('filename')
+          const appliedSet = new Set((data || []).map((r: any) => r.filename))
+          migrations.applied = migrations.files.filter(f => appliedSet.has(f)).length
+          migrations.pending = migrations.files.length - migrations.applied
+        } catch {
+          // DB not accessible — just show file count
+          migrations.pending = migrations.files.length
+        }
+      }
+
+      if (opts.json) {
+        console.log(JSON.stringify({ frameworkVersion, installedApps, migrations }, null, 2))
+        return
+      }
+
+      // Human-readable output
+      console.log('\n── Spine Framework Status ─────────────────────────────')
+      console.log(`   Version:      spine-framework@${frameworkVersion}`)
+      console.log(`   Project:      ${PROJECT_ROOT}`)
+      console.log()
+
+      console.log('── Installed Apps ─────────────────────────────────────')
+      if (installedApps.length === 0) {
+        console.log('   No apps installed.')
+        console.log('   Run: npx spine-framework install-app spine-framework-portal@latest')
+      } else {
+        for (const app of installedApps) {
+          const ver = app.version ? `@${app.version}` : ''
+          const manifest = app.hasManifest ? '' : ' (no manifest)'
+          console.log(`   ✓ ${app.slug}${ver}${manifest}`)
+        }
+      }
+      console.log()
+
+      console.log('── Migrations ─────────────────────────────────────────')
+      if (!supabaseUrl) {
+        console.log('   (Set SUPABASE_URL in .env to check migration state)')
+      } else {
+        console.log(`   Applied:  ${migrations.applied}`)
+        console.log(`   Pending:  ${migrations.pending}`)
+        if (migrations.pending > 0) {
+          console.log('   Run: npx spine-framework migrate')
+        }
+      }
+      console.log()
+    })
+}
+
+function loadEnv() {
+  const envPath = join(PROJECT_ROOT, '.env')
+  if (!existsSync(envPath)) return
+  const lines = readFileSync(envPath, 'utf8').split('\n')
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+    const eqIdx = trimmed.indexOf('=')
+    if (eqIdx === -1) continue
+    const key = trimmed.slice(0, eqIdx).trim()
+    const val = trimmed.slice(eqIdx + 1).trim()
+    if (key && !(key in process.env)) process.env[key] = val
+  }
+}

package/.framework/cli/index.ts

@@ -42,11 +42,15 @@ const program = new Command()
 
 program
   .name('spine-framework')
-  .description('Spine v2 CLI — interact with your Spine instance from the terminal or agentic IDE')
+  .description('Spine Framework CLI — install, migrate, and manage your Spine instance')
   .version('2.0.0')
   .option('--account <id>', 'Override the account ID for this command')
 
 const [
+  { registerInitCommands },
+  { registerMigrateCommands },
+  { registerInstallAppCommands },
+  { registerStatusCommands },
   { registerAuthCommands },
   { registerPipelineCommands },
   { registerItemCommands },
@@ -59,6 +63,10 @@ const [
   { registerGenerateCommands },
   { registerCreateAppCommands },
 ] = await Promise.all([
+  import('./commands/init.ts'),
+  import('./commands/migrate.ts'),
+  import('./commands/install-app.ts'),
+  import('./commands/status.ts'),
   import('./commands/auth.ts'),
   import('./commands/pipelines.ts'),
   import('./commands/items.ts'),
@@ -72,6 +80,10 @@ const [
   import('./commands/create-app.ts'),
 ])
 
+registerInitCommands(program)
+registerMigrateCommands(program)
+registerInstallAppCommands(program)
+registerStatusCommands(program)
 registerAuthCommands(program)
 registerPipelineCommands(program)
 registerItemCommands(program)

package/package.json

@@ -1,11 +1,9 @@
 {
   "name": "spine-framework",
-  "version": "0.3.19",
+  "version": "0.3.21",
   "description": "Multi-tenant, modular application platform for modern SaaS systems",
   "type": "module",
-  "bin": {
-    "spine-framework": "./.framework/cli/bin.mjs"
-  },
+  "bin": "./.framework/cli/bin.mjs",
   "files": [
     ".framework/cli/bin.mjs",
     ".framework/cli/",
@@ -46,7 +44,7 @@
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
     "type": "git",
-    "url": "https://github.com/spine-framework/spine-framework.git"
+    "url": "git+https://github.com/spine-framework/spine-framework.git"
   },
   "homepage": "https://spine-framework.com",
   "bugs": {