spine-framework 0.1.0

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

@@ -0,0 +1,391 @@
+/// <reference types="node" />
+/**
+ * @module cli/commands/install-app
+ * @audience installer
+ * @layer cli
+ * @stability stable
+ *
+ * `spine-framework install-app <slug>` — Install an app into the current Spine instance.
+ *
+ * Reads seed/*.json files from the app package directory and upserts their
+ * contents into the database. Also registers the app in `app_installations`.
+ *
+ * **Seed file conventions:**
+ * - `types.json` → upsert into `types` table
+ * - `link-types.json` → upsert into `link_types` table
+ * - `triggers.json` → upsert into `triggers` table
+ * - `accounts.json` → upsert into `accounts` table
+ * - `pipelines.json` → upsert into `pipelines` table
+ *
+ * All upserts keyed on `(app_id, slug)` — idempotent and safe to re-run.
+ *
+ * **Usage:**
+ * ```bash
+ * spine-framework install-app cortex
+ * spine-framework install-app customer-portal
+ * spine-framework install-app cortex --account <account-id>
+ * ```
+ */
+
+import type { Command } from 'commander'
+import { existsSync, readFileSync, readdirSync } from 'fs'
+import { resolve, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import { adminDb } from '../../functions/_shared/index.ts'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const PROJECT_ROOT = resolve(__dirname, '../../../')
+
+interface InstallOptions {
+  account?: string
+  force: boolean
+  dryRun: boolean
+}
+
+interface SeedResult {
+  table: string
+  inserted: number
+  skipped: number
+  errors: string[]
+}
+
+async function resolveAppId(slug: string): Promise<string | null> {
+  const { data } = await adminDb
+    .from('apps')
+    .select('id')
+    .eq('slug', slug)
+    .single()
+
+  return data?.id || null
+}
+
+async function ensureAppRecord(slug: string, name: string): Promise<string> {
+  let appId = await resolveAppId(slug)
+
+  if (!appId) {
+    // Read manifest for display name
+    const { error: insertErr, data } = await adminDb
+      .from('apps')
+      .insert({
+        slug,
+        name,
+        route_prefix: `/${slug}`,
+        renderer: 'custom',
+        is_active: true,
+        is_system: false,
+      })
+      .select('id')
+      .single()
+
+    if (insertErr) {
+      throw new Error(`Failed to create app record: ${insertErr.message}`)
+    }
+    appId = data.id
+    console.log(`  ✓ Created app record for '${slug}'`)
+  } else {
+    console.log(`  ⏭️  App '${slug}' already in database`)
+  }
+
+  return appId
+}
+
+async function upsertTypes(appId: string, records: any[], dryRun: boolean): Promise<SeedResult> {
+  const result: SeedResult = { table: 'types', inserted: 0, skipped: 0, errors: [] }
+
+  for (const record of records) {
+    if (dryRun) {
+      console.log(`    [dry-run] Would upsert type: ${record.slug}`)
+      result.inserted++
+      continue
+    }
+
+    const { error } = await adminDb
+      .from('types')
+      .upsert({
+        ...record,
+        app_id: appId,
+      }, {
+        onConflict: 'app_id,kind,slug',
+        ignoreDuplicates: false
+      })
+
+    if (error) {
+      result.errors.push(`${record.slug}: ${error.message}`)
+    } else {
+      result.inserted++
+    }
+  }
+
+  return result
+}
+
+async function upsertLinkTypes(appId: string, records: any[], dryRun: boolean): Promise<SeedResult> {
+  const result: SeedResult = { table: 'link_types', inserted: 0, skipped: 0, errors: [] }
+
+  for (const record of records) {
+    if (dryRun) {
+      console.log(`    [dry-run] Would upsert link type: ${record.slug}`)
+      result.inserted++
+      continue
+    }
+
+    const { error } = await adminDb
+      .from('link_types')
+      .upsert({
+        ...record,
+        app_id: appId,
+      }, {
+        onConflict: 'app_id,slug',
+        ignoreDuplicates: false
+      })
+
+    if (error) {
+      result.errors.push(`${record.slug}: ${error.message}`)
+    } else {
+      result.inserted++
+    }
+  }
+
+  return result
+}
+
+async function upsertTriggers(appId: string, records: any[], dryRun: boolean): Promise<SeedResult> {
+  const result: SeedResult = { table: 'triggers', inserted: 0, skipped: 0, errors: [] }
+
+  for (const record of records) {
+    if (dryRun) {
+      console.log(`    [dry-run] Would upsert trigger: ${record.name}`)
+      result.inserted++
+      continue
+    }
+
+    const { error } = await adminDb
+      .from('triggers')
+      .upsert({
+        ...record,
+        app_id: appId,
+      }, {
+        onConflict: 'app_id,name',
+        ignoreDuplicates: false
+      })
+
+    if (error) {
+      result.errors.push(`${record.name}: ${error.message}`)
+    } else {
+      result.inserted++
+    }
+  }
+
+  return result
+}
+
+async function upsertAccounts(appId: string, records: any[], dryRun: boolean): Promise<SeedResult> {
+  const result: SeedResult = { table: 'accounts', inserted: 0, skipped: 0, errors: [] }
+
+  for (const record of records) {
+    if (dryRun) {
+      console.log(`    [dry-run] Would upsert account: ${record.slug}`)
+      result.inserted++
+      continue
+    }
+
+    // Resolve type_slug → type_id if present
+    const row = { ...record, app_id: appId }
+    if (row.type_slug && !row.type_id) {
+      const { data: typeData } = await adminDb
+        .from('types')
+        .select('id')
+        .eq('kind', 'account')
+        .eq('slug', row.type_slug)
+        .limit(1)
+        .single()
+      if (typeData) {
+        row.type_id = typeData.id
+      } else {
+        result.errors.push(`${record.slug}: type_slug '${row.type_slug}' not found`)
+        continue
+      }
+      delete row.type_slug
+    }
+
+    const { error } = await adminDb
+      .from('accounts')
+      .upsert(row, {
+        onConflict: 'slug',
+        ignoreDuplicates: false
+      })
+
+    if (error) {
+      result.errors.push(`${record.slug}: ${error.message}`)
+    } else {
+      result.inserted++
+    }
+  }
+
+  return result
+}
+
+async function upsertPipelines(appId: string, records: any[], dryRun: boolean): Promise<SeedResult> {
+  const result: SeedResult = { table: 'pipelines', inserted: 0, skipped: 0, errors: [] }
+
+  for (const record of records) {
+    if (dryRun) {
+      console.log(`    [dry-run] Would upsert pipeline: ${record.slug}`)
+      result.inserted++
+      continue
+    }
+
+    const { error } = await adminDb
+      .from('pipelines')
+      .upsert({
+        ...record,
+        app_id: appId,
+      }, {
+        onConflict: 'app_id,name',
+        ignoreDuplicates: false
+      })
+
+    if (error) {
+      result.errors.push(`${record.slug}: ${error.message}`)
+    } else {
+      result.inserted++
+    }
+  }
+
+  return result
+}
+
+const SEED_HANDLERS: Record<string, (appId: string, records: any[], dryRun: boolean) => Promise<SeedResult>> = {
+  'types.json': upsertTypes,
+  'link-types.json': upsertLinkTypes,
+  'triggers.json': upsertTriggers,
+  'accounts.json': upsertAccounts,
+  'pipelines.json': upsertPipelines,
+}
+
+async function recordInstallation(appSlug: string, accountId: string | null, dryRun: boolean): Promise<void> {
+  if (dryRun) {
+    console.log(`  [dry-run] Would record installation for '${appSlug}'`)
+    return
+  }
+
+  const { error } = await adminDb
+    .from('app_installations')
+    .upsert({
+      app_slug: appSlug,
+      account_id: accountId,
+      is_enabled: true,
+      updated_at: new Date().toISOString(),
+    }, {
+      onConflict: 'app_slug,account_id',
+    })
+
+  if (error) {
+    console.log(`  ⚠️  Failed to record installation: ${error.message}`)
+  }
+}
+
+async function installApp(slug: string, options: InstallOptions): Promise<void> {
+  console.log(`\n📦 Installing app '${slug}'...\n`)
+
+  // 1. Find the app directory
+  const appDir = resolve(PROJECT_ROOT, `custom/apps/${slug}`)
+  if (!existsSync(appDir)) {
+    console.error(`  ❌ App directory not found: custom/apps/${slug}`)
+    console.error(`     Install the npm package first or create the app with 'spine-framework create-app ${slug}'`)
+    process.exit(1)
+  }
+
+  // 2. Read manifest for display name
+  const manifestPath = resolve(appDir, 'manifest.json')
+  let appName = slug
+  if (existsSync(manifestPath)) {
+    try {
+      const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+      appName = manifest.name || slug
+      console.log(`  📋 Manifest: ${appName} v${manifest.version || '0.0.0'}`)
+    } catch {
+      console.log(`  ⚠️  Could not parse manifest.json, using slug as name`)
+    }
+  } else {
+    console.log(`  ⚠️  No manifest.json found, using slug as name`)
+  }
+
+  // 3. Ensure app record in DB
+  const appId = await ensureAppRecord(slug, appName)
+
+  // 4. Process seed files
+  const seedDir = resolve(appDir, 'seed')
+  if (!existsSync(seedDir)) {
+    console.log(`  ⏭️  No seed/ directory — skipping data seeding`)
+  } else {
+    console.log(`\n🌱 Applying seed data...`)
+    const seedFiles = readdirSync(seedDir).filter(f => f.endsWith('.json'))
+
+    let totalInserted = 0
+    let totalErrors = 0
+
+    for (const file of seedFiles) {
+      const handler = SEED_HANDLERS[file]
+      if (!handler) {
+        console.log(`  ⏭️  Skipping unknown seed file: ${file}`)
+        continue
+      }
+
+      const filePath = resolve(seedDir, file)
+      let records: any[]
+      try {
+        records = JSON.parse(readFileSync(filePath, 'utf8'))
+        if (!Array.isArray(records)) {
+          console.log(`  ⚠️  ${file}: expected array, skipping`)
+          continue
+        }
+      } catch (err: any) {
+        console.error(`  ❌ ${file}: parse error — ${err.message}`)
+        continue
+      }
+
+      console.log(`  📄 ${file} (${records.length} records)...`)
+      const result = await handler(appId, records, options.dryRun)
+
+      if (result.errors.length > 0) {
+        for (const e of result.errors) {
+          console.error(`    ❌ ${e}`)
+        }
+        totalErrors += result.errors.length
+      }
+      totalInserted += result.inserted
+      console.log(`    ✓ ${result.inserted} upserted`)
+    }
+
+    console.log(`\n  Total: ${totalInserted} records upserted, ${totalErrors} errors`)
+  }
+
+  // 5. Record installation
+  console.log(`\n📝 Recording installation...`)
+  await recordInstallation(slug, options.account || null, options.dryRun)
+
+  console.log(`\n✅ App '${appName}' installed successfully!`)
+  console.log(`\n   Next steps:`)
+  console.log(`   1. npm run assemble && netlify dev`)
+  console.log(`   2. Navigate to /${slug} in your browser`)
+}
+
+export function registerInstallAppCommands(program: Command) {
+  program
+    .command('install-app <slug>')
+    .description('Install an app by applying its seed data to the database')
+    .option('--account <id>', 'Account ID to associate the installation with')
+    .option('--force', 'Overwrite existing seed data', false)
+    .option('--dry-run', 'Show what would happen without making changes', false)
+    .action(async (slug, opts) => {
+      try {
+        await installApp(slug, 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/items.ts

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