spine-framework 0.1.61 → 1.0.0

package/.framework/cli/commands/items.ts

@@ -1,253 +0,0 @@
-/// <reference types="node" />
-/**
- * @module cli/commands/items
- * @audience installer
- * @layer cli
- * @stability stable
- *
- * `spine items` command group. Direct CRUD access to the `items` table via
- * `adminDb` (service-role, bypasses RLS). Use only in controlled environments;
- * does NOT enforce field-level permissions or RLS for the principal.
- *
- * **Commands:**
- * | Subcommand                                     | Description                    |
- * |------------------------------------------------|--------------------------------|
- * | `items list [--type <slug>] [--account <id>]`  | List items, filtered by type   |
- * | `items get <id>`                               | Fetch a single item by UUID    |
- * | `items create --type <slug> --data <json>`     | Insert a new item              |
- * | `items update <id> --data <json>`              | Patch item data fields         |
- * | `items delete <id> [--hard]`                   | Soft-delete or hard-delete     |
- *
- * **Authorization note:** All commands use `adminDb` — no RLS enforcement.
- * Account scoping is applied as a filter only; it does not restrict access.
- *
- * **Usage:**
- * ```bash
- * spine items list --type support_ticket --account <id> --limit 50
- * spine items get <uuid>
- * spine items create --type support_ticket --title "Bug report" --data '{"priority":"high"}'
- * spine items update <uuid> --data '{"status":"resolved"}'
- * spine items delete <uuid>
- * spine items delete <uuid> --hard
- * ```
- *
- * @seeAlso cli/context.ts (buildCliContext)
- * @seeAlso functions/admin-data.ts (API equivalent with RLS)
- */
-
-import type { Command } from 'commander'
-import { buildCliContext, printResult, handleError } from '../context.ts'
-import { adminDb } from '../../functions/_shared/index.ts'
-
-/**
- * Registers the `items` subcommand group on the root Commander program.
- *
- * @param program - The root `spine` Commander instance
- * @sideEffects Adds `items list/get/create/update/delete` subcommands to `program`
- * @calledBy cli/index.ts
- */
-export function registerItemCommands(program: Command) {
-  const items = program
-    .command('items')
-    .description('Item record management')
-
-  items
-    .command('list')
-    .description('List items, optionally filtered by type')
-    .option('--type <slug>', 'Filter by item type slug')
-    .option('--account <id>', 'Account scope')
-    .option('--limit <n>', 'Max results', '20')
-    .option('--json', 'Output as JSON')
-    .action(async (opts) => {
-      try {
-        const ctx = await buildCliContext({ account: opts.account })
-
-        let query = adminDb
-          .from('items')
-          .select('id, type_id, title, status, is_active, created_at')
-          .order('created_at', { ascending: false })
-          .limit(parseInt(opts.limit))
-
-        if (ctx.accountId) {
-          query = query.eq('account_id', ctx.accountId)
-        }
-
-        if (opts.type) {
-          const { data: typeRecord } = await adminDb
-            .from('types')
-            .select('id')
-            .eq('slug', opts.type)
-            .single()
-
-          if (!typeRecord) throw new Error(`Item type not found: ${opts.type}`)
-          query = query.eq('type_id', typeRecord.id)
-        }
-
-        const { data, error } = await query
-        if (error) throw new Error(error.message)
-        printResult(data || [], { json: opts.json })
-      } catch (err: any) {
-        handleError(err)
-      }
-    })
-
-  items
-    .command('get <id>')
-    .description('Get a single item by ID')
-    .option('--json', 'Output as JSON')
-    .action(async (id, opts) => {
-      try {
-        await buildCliContext()
-
-        const { data, error } = await adminDb
-          .from('items')
-          .select('*')
-          .eq('id', id)
-          .single()
-
-        if (error || !data) throw new Error(error?.message || `Item not found: ${id}`)
-        printResult(data, { json: opts.json })
-      } catch (err: any) {
-        handleError(err)
-      }
-    })
-
-  items
-    .command('create')
-    .description('Create a new item')
-    .requiredOption('--type <slug>', 'Item type slug')
-    .option('--data <json>', 'Item data as JSON', '{}')
-    .option('--title <title>', 'Item title')
-    .option('--account <id>', 'Account scope')
-    .option('--json', 'Output as JSON')
-    .action(async (opts) => {
-      try {
-        const ctx = await buildCliContext({ account: opts.account })
-
-        if (!ctx.accountId) {
-          throw new Error('--account or SPINE_CLI_ACCOUNT_ID required to create items')
-        }
-
-        const { data: typeRecord, error: typeError } = await adminDb
-          .from('types')
-          .select('id')
-          .eq('slug', opts.type)
-          .single()
-
-        if (typeError || !typeRecord) throw new Error(`Item type not found: ${opts.type}`)
-
-        let itemData: any = {}
-        try {
-          itemData = JSON.parse(opts.data)
-        } catch {
-          throw new Error(`--data must be valid JSON. Got: ${opts.data}`)
-        }
-
-        const { data, error } = await adminDb
-          .from('items')
-          .insert({
-            type_id: typeRecord.id,
-            account_id: ctx.accountId,
-            title: opts.title || itemData.title || null,
-            data: itemData,
-            is_active: true,
-            created_by: ctx.principal.id,
-            created_at: new Date().toISOString(),
-            updated_at: new Date().toISOString()
-          })
-          .select()
-          .single()
-
-        if (error) throw new Error(error.message)
-        if (opts.json) {
-          console.log(JSON.stringify(data, null, 2))
-        } else {
-          console.log(`✓ Created item ${data.id}`)
-          printResult(data, { json: false })
-        }
-      } catch (err: any) {
-        handleError(err)
-      }
-    })
-
-  items
-    .command('update <id>')
-    .description('Update item data fields')
-    .option('--data <json>', 'Partial item data as JSON', '{}')
-    .option('--title <title>', 'Update item title')
-    .option('--json', 'Output as JSON')
-    .action(async (id, opts) => {
-      try {
-        const ctx = await buildCliContext()
-
-        let patchData: any = {}
-        try {
-          patchData = JSON.parse(opts.data)
-        } catch {
-          throw new Error(`--data must be valid JSON`)
-        }
-
-        const updates: any = {
-          updated_at: new Date().toISOString(),
-          updated_by: ctx.principal.id
-        }
-        if (opts.title) updates.title = opts.title
-        if (Object.keys(patchData).length > 0) updates.data = patchData
-
-        const { data, error } = await adminDb
-          .from('items')
-          .update(updates)
-          .eq('id', id)
-          .select()
-          .single()
-
-        if (error) throw new Error(error.message)
-        if (opts.json) {
-          console.log(JSON.stringify(data, null, 2))
-        } else {
-          console.log(`✓ Updated item ${id}`)
-          printResult(data, { json: false })
-        }
-      } catch (err: any) {
-        handleError(err)
-      }
-    })
-
-  items
-    .command('delete <id>')
-    .description('Soft-delete an item (sets is_active = false)')
-    .option('--hard', 'Hard delete — permanently removes the record')
-    .option('--json', 'Output as JSON')
-    .action(async (id, opts) => {
-      try {
-        const ctx = await buildCliContext()
-
-        if (opts.hard) {
-          const { error } = await adminDb
-            .from('items')
-            .delete()
-            .eq('id', id)
-
-          if (error) throw new Error(error.message)
-          console.log(`✓ Hard-deleted item ${id}`)
-        } else {
-          const { data, error } = await adminDb
-            .from('items')
-            .update({
-              is_active: false,
-              updated_at: new Date().toISOString(),
-              updated_by: ctx.principal.id
-            })
-            .eq('id', id)
-            .select('id, is_active')
-            .single()
-
-          if (error) throw new Error(error.message)
-          const out = opts.json ? JSON.stringify(data) : `✓ Soft-deleted item ${id}`
-          console.log(out)
-        }
-      } catch (err: any) {
-        handleError(err)
-      }
-    })
-}

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

@@ -1,139 +0,0 @@
-/// <reference types="node" />
-/**
- * @module cli/commands/migrate
- * @audience installer
- * @layer cli
- * @stability stable
- *
- * `spine-framework migrate` — Apply SQL migrations to a Supabase project
- * via a direct Postgres connection.
- *
- * Requires --db-password (the Supabase database password).
- * Get it from: https://supabase.com/dashboard/project/_/settings/database
- *
- * **Usage:**
- * ```bash
- * spine-framework migrate --db-password <password>
- * spine-framework migrate --db-password <password> --dry-run
- * ```
- */
-
-import type { Command } from 'commander'
-import { existsSync, readdirSync, readFileSync } from 'fs'
-import { resolve, dirname } from 'path'
-import { fileURLToPath } from 'url'
-
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = dirname(__filename)
-const MIGRATIONS_DIR = resolve(__dirname, '../../migrations')
-
-interface MigrateOptions {
-  dbPassword?: string
-  dryRun: boolean
-}
-
-async function migrateCommand(options: MigrateOptions): Promise<void> {
-  console.log('\n🗄️  Spine Framework — Migrate\n')
-
-  const supabaseUrl = process.env.SUPABASE_URL
-  if (!supabaseUrl || supabaseUrl === 'https://your-project.supabase.co') {
-    console.error('❌ SUPABASE_URL not set. Fill in your .env file first.')
-    process.exit(1)
-  }
-
-  const dbPassword = options.dbPassword || process.env.SUPABASE_DB_PASSWORD
-  if (!dbPassword || dbPassword === 'your-db-password') {
-    console.error('❌ SUPABASE_DB_PASSWORD not set.')
-    console.error('   Add it to .env or pass --db-password <password>')
-    console.error('   Get it from: https://supabase.com/dashboard/project/_/settings/database')
-    process.exit(1)
-  }
-
-  const projectRef = supabaseUrl.replace('https://', '').split('.')[0]
-  const connectionString = `postgresql://postgres:${dbPassword}@db.${projectRef}.supabase.co:5432/postgres`
-
-  if (!existsSync(MIGRATIONS_DIR)) {
-    console.error(`❌ Migrations directory not found: ${MIGRATIONS_DIR}`)
-    process.exit(1)
-  }
-
-  const files = readdirSync(MIGRATIONS_DIR)
-    .filter(f => f.endsWith('.sql'))
-    .sort()
-
-  if (files.length === 0) {
-    console.log('  No migration files found.')
-    return
-  }
-
-  console.log(`  Found ${files.length} migration file(s)\n`)
-
-  if (options.dryRun) {
-    for (const file of files) {
-      console.log(`  [dry-run] Would apply: ${file}`)
-    }
-    return
-  }
-
-  // Dynamically import pg to avoid loading it at module init time
-  const { default: pg } = await import('pg')
-  const client = new pg.Client({ connectionString })
-
-  try {
-    await client.connect()
-    console.log('  ✓ Connected to database\n')
-  } catch (err: any) {
-    console.error(`❌ Could not connect to database: ${err.message}`)
-    console.error('   Check your --db-password and that the project is active.')
-    process.exit(1)
-  }
-
-  let applied = 0
-  let failed = 0
-
-  for (const file of files) {
-    const sql = readFileSync(resolve(MIGRATIONS_DIR, file), 'utf8')
-    process.stdout.write(`  Applying ${file}... `)
-    try {
-      await client.query(sql)
-      console.log('✓')
-      applied++
-    } catch (err: any) {
-      console.log('❌')
-      console.error(`     ${err.message}`)
-      failed++
-      // Continue applying remaining migrations
-    }
-  }
-
-  await client.end()
-
-  console.log(`\n  ${applied} applied, ${failed} failed`)
-
-  if (failed > 0) {
-    console.error('\n❌ Some migrations failed. Check errors above.')
-    process.exit(1)
-  }
-
-  console.log('\n✅ All migrations applied successfully!')
-  console.log('\n   Next steps:')
-  console.log('   1. spine-framework install-app <app-slug>')
-  console.log('   2. npm run assemble && netlify dev')
-}
-
-export function registerMigrateCommands(program: Command) {
-  program
-    .command('migrate')
-    .description('Apply SQL migrations via direct Postgres connection')
-    .option('--db-password <password>', 'DB password override (default: reads SUPABASE_DB_PASSWORD from .env)')
-    .option('--dry-run', 'Show what would happen without making changes', false)
-    .action(async (opts) => {
-      try {
-        await migrateCommand(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/migrations.ts

@@ -1,141 +0,0 @@
-/// <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

@@ -1,166 +0,0 @@
-/// <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)
-      }
-    })
-}