spine-framework 0.1.0

package/.framework/cli/commands/generate.ts

@@ -0,0 +1,332 @@
+/// <reference types="node" />
+/**
+ * @module cli/commands/generate
+ * @audience installer
+ * @layer cli
+ * @stability stable
+ *
+ * `spine generate` command — code scaffolding for extending Spine safely.
+ * Generates type definitions, handlers, and UI pages in v2-custom/ only.
+ *
+ * **Commands:**
+ * | Subcommand              | Description                                           |
+ * |-------------------------|-------------------------------------------------------|
+ * | `generate type <slug>`  | Create new type with handler and UI stubs             |
+ * | `generate function <name>` | Create new Netlify function stub                   |
+ *
+ * **What gets generated for `type`:**
+ * 1. Type record in database (item type by default)
+ * 2. Handler stub: `v2-custom/functions/{slug}.ts`
+ * 3. UI page stub: `v2-custom/src/pages/{slug}/index.tsx`
+ *
+ * **What gets generated for `function`:**
+ * 1. Netlify function stub: `v2-custom/functions/{name}.ts`
+ * 2. Basic handler structure with middleware imports
+ *
+ * **Usage:**
+ * ```bash
+ * spine generate type ticket-v2
+ * spine generate function webhook-handler
+ * ```
+ *
+ * @seeAlso functions/types.ts (type CRUD API)
+ * @seeAlso functions/_shared/middleware.ts (handler structure)
+ */
+
+import type { Command } from 'commander'
+import { buildCliContext, handleError } from '../context.ts'
+import { adminDb } from '../../functions/_shared/index.ts'
+import { existsSync, mkdirSync, writeFileSync } from 'fs'
+import { resolve, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const PROJECT_ROOT = resolve(__dirname, '../../../')
+
+// ─── TYPE GENERATION ─────────────────────────────────────────────────────────
+
+async function generateType(ctx: any, slug: string, options: any): Promise<void> {
+  const name = options.name || slug.split('-').map(s => s.charAt(0).toUpperCase() + s.slice(1)).join(' ')
+  const kind = options.kind || 'item'
+  const description = options.description || `${name} type generated by spine CLI`
+
+  console.log(`\n🔧 Generating type '${slug}'...`)
+
+  // Step 1: Create type record in database
+  console.log('  Step 1: Creating type record in database...')
+
+  const { data: existing, error: checkErr } = await adminDb
+    .from('types')
+    .select('id')
+    .eq('slug', slug)
+    .eq('kind', kind)
+    .single()
+
+  if (checkErr && checkErr.code !== 'PGRST116') { // PGRST116 = not found
+    throw new Error(`Failed to check existing type: ${checkErr.message}`)
+  }
+
+  if (existing) {
+    console.log(`  ⚠️  Type '${slug}' already exists (skipping DB creation)`)
+  } else {
+    const designSchema = {
+      fields: {
+        title: {
+          type: 'string',
+          required: true,
+          label: 'Title',
+          description: `Title for this ${name}`
+        },
+        status: {
+          type: 'select',
+          options: ['open', 'in_progress', 'closed'],
+          default: 'open',
+          label: 'Status'
+        }
+      },
+      layout: {
+        detail: ['title', 'status'],
+        list: ['title', 'status']
+      }
+    }
+
+    const { error: insertErr } = await adminDb
+      .from('types')
+      .insert({
+        kind,
+        slug,
+        name,
+        description,
+        design_schema: designSchema,
+        validation_schema: {},
+        ownership: 'system',
+        is_active: true
+      })
+
+    if (insertErr) {
+      throw new Error(`Failed to create type: ${insertErr.message}`)
+    }
+
+    console.log('  ✓ Type record created')
+  }
+
+  // Step 2: Generate handler stub
+  console.log('  Step 2: Generating handler stub...')
+  const handlerPath = resolve(PROJECT_ROOT, `v2-custom/functions/${slug}.ts`)
+
+  if (existsSync(handlerPath) && !options.force) {
+    console.log(`  ⚠️  Handler stub already exists: ${handlerPath}`)
+  } else {
+    const handlerCode = generateHandlerStub(slug, kind, name)
+    writeFileSync(handlerPath, handlerCode)
+    console.log(`  ✓ Handler stub created: v2-custom/functions/${slug}.ts`)
+  }
+
+  // Step 3: Generate UI page stub
+  console.log('  Step 3: Generating UI page stub...')
+  const pageDir = resolve(PROJECT_ROOT, `v2-custom/src/pages/${slug}`)
+  const pagePath = resolve(pageDir, 'index.tsx')
+
+  if (existsSync(pagePath) && !options.force) {
+    console.log(`  ⚠️  UI page stub already exists: ${pagePath}`)
+  } else {
+    mkdirSync(pageDir, { recursive: true })
+    const pageCode = generatePageStub(slug, name, kind)
+    writeFileSync(pagePath, pageCode)
+    console.log(`  ✓ UI page stub created: v2-custom/src/pages/${slug}/index.tsx`)
+  }
+
+  console.log(`\n✅ Type '${slug}' generation complete!`)
+  console.log(`   Next steps:`)
+  console.log(`   1. Edit v2-custom/functions/${slug}.ts to implement custom logic`)
+  console.log(`   2. Edit v2-custom/src/pages/${slug}/index.tsx to customize the UI`)
+  console.log(`   3. Run 'spine dev' to see your changes`)
+}
+
+function generateHandlerStub(slug: string, kind: string, name: string): string {
+  return `/**
+ * @module ${slug}
+ * @audience custom
+ * @layer api-handler
+ * @stability experimental
+ *
+ * Custom handler for ${name} (${kind} type).
+ * Generated by spine CLI on ${new Date().toISOString()}.
+ *
+ * Extend this handler to add custom logic for your type.
+ */
+
+import { createHandler } from '../v2-core/functions/_shared/middleware'
+
+export const handler = createHandler(async (ctx) => {
+  const method = ctx.query?.method || 'GET'
+
+  switch (method) {
+    case 'GET':
+      // TODO: Implement GET logic
+      return { message: '${name} handler - GET not implemented' }
+
+    case 'POST':
+      // TODO: Implement POST logic
+      return { message: '${name} handler - POST not implemented' }
+
+    case 'PATCH':
+      // TODO: Implement PATCH logic
+      return { message: '${name} handler - PATCH not implemented' }
+
+    case 'DELETE':
+      // TODO: Implement DELETE logic
+      return { message: '${name} handler - DELETE not implemented' }
+
+    default:
+      throw new Error('Unsupported method: ' + method)
+  }
+})
+`
+}
+
+function generatePageStub(slug: string, name: string, kind: string): string {
+  return `/**
+ * @page ${slug}/index
+ * @audience custom
+ * @layer page
+ * @stability experimental
+ *
+ * UI page for ${name} (${kind} type).
+ * Generated by spine CLI on ${new Date().toISOString()}.
+ */
+
+import React from 'react'
+import { useParams } from 'react-router-dom'
+import { useApi } from '../../v2-core/src/hooks/useApi'
+import { apiFetch } from '../../v2-core/src/lib/api'
+
+export default function ${name.replace(/\s+/g, '')}Page() {
+  const { id } = useParams()
+
+  const { data, loading, error } = useApi(
+    () => apiFetch('/.netlify/functions/${slug}' + (id ? '?id=' + id : '')),
+    { immediate: true }
+  )
+
+  if (loading) return <div>Loading...</div>
+  if (error) return <div>Error: {error.message}</div>
+
+  return (
+    <div className="p-6">
+      <h1 className="text-2xl font-bold mb-4">${name}</h1>
+      <pre className="bg-gray-100 p-4 rounded">
+        {JSON.stringify(data, null, 2)}
+      </pre>
+      <p className="mt-4 text-gray-600">
+        Edit v2-custom/src/pages/${slug}/index.tsx to customize this page.
+      </p>
+    </div>
+  )
+}
+`
+}
+
+// ─── FUNCTION GENERATION ─────────────────────────────────────────────────────
+
+async function generateFunction(name: string, options: any): Promise<void> {
+  console.log(`\n🔧 Generating function '${name}'...`)
+
+  const handlerPath = resolve(PROJECT_ROOT, `v2-custom/functions/${name}.ts`)
+
+  if (existsSync(handlerPath) && !options.force) {
+    console.log(`  ⚠️  Function already exists: ${handlerPath}`)
+    console.log(`  Use --force to overwrite`)
+    return
+  }
+
+  const handlerCode = generateFunctionStub(name, options.description)
+  writeFileSync(handlerPath, handlerCode)
+
+  console.log(`✅ Function '${name}' created!`)
+  console.log(`   Location: v2-custom/functions/${name}.ts`)
+  console.log(`   Next steps:`)
+  console.log(`   1. Edit the handler to implement your logic`)
+  console.log(`   2. Run 'spine dev' to see your changes`)
+}
+
+function generateFunctionStub(name: string, description?: string): string {
+  return `/**
+ * @module ${name}
+ * @audience custom
+ * @layer api-handler
+ * @stability experimental
+ *
+ * ${description || `Custom Netlify function: ${name}`}
+ * Generated by spine CLI on ${new Date().toISOString()}.
+ */
+
+import { createHandler } from '../v2-core/functions/_shared/middleware'
+
+export const handler = createHandler(async (ctx) => {
+  // Access principal: ctx.principal (human, machine, or system)
+  // Access database: ctx.db (RLS-scoped) or import { adminDb } for admin access
+  // Access query params: ctx.query
+
+  const q = ctx.query || {}
+  const action = q.action || 'default'
+
+  switch (action) {
+    case 'default':
+      return {
+        message: 'Hello from ${name}',
+        principal: ctx.principal?.id,
+        timestamp: new Date().toISOString()
+      }
+
+    // TODO: Add more actions here
+    // case 'custom':
+    //   return { data: await yourCustomLogic(ctx) }
+
+    default:
+      return {
+        error: 'Unknown action: ' + action,
+        available_actions: ['default']
+      }
+  }
+})
+`
+}
+
+// ─── COMMAND REGISTRATION ────────────────────────────────────────────────────
+
+export function registerGenerateCommands(program: Command) {
+  const generate = program
+    .command('generate')
+    .description('Generate code stubs for extending Spine')
+
+  generate
+    .command('type <slug>')
+    .description('Generate a new type with handler and UI stubs')
+    .option('--name <name>', 'Display name for the type')
+    .option('--kind <kind>', 'Type kind (item, account, person)', 'item')
+    .option('--description <desc>', 'Type description')
+    .option('--force', 'Overwrite existing files', false)
+    .action(async (slug, opts) => {
+      try {
+        const ctx = await buildCliContext()
+        await generateType(ctx, slug, opts)
+      } catch (err: any) {
+        handleError(err)
+      }
+    })
+
+  generate
+    .command('function <name>')
+    .description('Generate a new Netlify function stub')
+    .option('--description <desc>', 'Function description')
+    .option('--force', 'Overwrite existing file', false)
+    .action(async (name, opts) => {
+      try {
+        await generateFunction(name, opts)
+      } catch (err: any) {
+        handleError(err)
+      }
+    })
+}

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

@@ -0,0 +1,272 @@
+/// <reference types="node" />
+/**
+ * @module cli/commands/init
+ * @audience installer
+ * @layer cli
+ * @stability stable
+ *
+ * `spine-framework init` — Bootstrap a fresh Spine installation.
+ *
+ * Runs the foundation schema (000_foundation.sql) and seed data (001_seed.sql)
+ * against the configured Supabase project, then scaffolds the custom/ workspace
+ * if it doesn't already exist.
+ *
+ * **Usage:**
+ * ```bash
+ * # Fresh install (agent provides credentials from Supabase dashboard)
+ * spine-framework init --url https://xyz.supabase.co --anon-key eyJ... --service-role-key eyJ...
+ *
+ * # Already have .env configured
+ * spine-framework init
+ *
+ * # DB only, no filesystem changes
+ * spine-framework init --skip-scaffold
+ * ```
+ *
+ * When --url/--anon-key/--service-role-key are provided, init writes .env before
+ * running migrations — so it works on a completely fresh checkout with no prior config.
+ */
+
+import type { Command } from 'commander'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } 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, '../../../')
+const MIGRATIONS_DIR = resolve(__dirname, '../../migrations')
+
+interface InitOptions {
+  skipScaffold: boolean
+  dryRun: boolean
+  url?: string
+  anonKey?: string
+  serviceRoleKey?: string
+}
+
+async function runMigration(filename: string, dryRun: boolean): Promise<boolean> {
+  const filePath = resolve(MIGRATIONS_DIR, filename)
+  if (!existsSync(filePath)) {
+    console.error(`  ❌ Migration file not found: ${filename}`)
+    return false
+  }
+
+  const sql = readFileSync(filePath, 'utf8')
+
+  if (dryRun) {
+    console.log(`  [dry-run] Would execute: ${filename} (${sql.length} chars)`)
+    return true
+  }
+
+  // Use the Supabase SQL endpoint to execute raw DDL.
+  // This works on blank projects (no exec_sql RPC needed).
+  const supabaseUrl = process.env.SUPABASE_URL
+  const serviceKey = process.env.SUPABASE_SERVICE_ROLE_KEY
+
+  if (!supabaseUrl || !serviceKey) {
+    console.error(`  ❌ Missing SUPABASE_URL or SUPABASE_SERVICE_ROLE_KEY`)
+    return false
+  }
+
+  // Try exec_sql RPC first (works if schema already has it)
+  const { error } = await adminDb.rpc('exec_sql', { query: sql }).single()
+  if (!error) return true
+
+  // Fallback: use the Supabase /pg/query endpoint for raw SQL execution
+  console.log(`  ⚠️  exec_sql not available, using direct SQL endpoint...`)
+
+  const pgResponse = await fetch(`${supabaseUrl}/pg/query`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'apikey': serviceKey,
+      'Authorization': `Bearer ${serviceKey}`,
+    },
+    body: JSON.stringify({ query: sql })
+  })
+
+  if (pgResponse.ok) return true
+
+  // Second fallback: use the Supabase Management API SQL endpoint
+  // Extract project ref from URL (e.g. https://abcdef.supabase.co → abcdef)
+  const projectRef = supabaseUrl.replace('https://', '').split('.')[0]
+
+  const mgmtResponse = await fetch(
+    `https://api.supabase.com/v1/projects/${projectRef}/database/query`,
+    {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${serviceKey}`,
+      },
+      body: JSON.stringify({ query: sql })
+    }
+  )
+
+  if (mgmtResponse.ok) return true
+
+  const text = await mgmtResponse.text()
+  console.error(`  ❌ Migration ${filename} failed: ${text}`)
+  return false
+}
+
+function scaffoldCustomWorkspace(dryRun: boolean): void {
+  const dirs = [
+    'custom/apps',
+    'custom/functions',
+    'custom/components',
+    'custom/migrations',
+    'custom/tests',
+  ]
+
+  for (const dir of dirs) {
+    const fullPath = resolve(PROJECT_ROOT, dir)
+    if (existsSync(fullPath)) {
+      console.log(`  ⏭️  ${dir}/ already exists`)
+    } else if (dryRun) {
+      console.log(`  [dry-run] Would create: ${dir}/`)
+    } else {
+      mkdirSync(fullPath, { recursive: true })
+      writeFileSync(resolve(fullPath, '.gitkeep'), '')
+      console.log(`  ✓ Created ${dir}/`)
+    }
+  }
+}
+
+async function checkAlreadyInitialized(): Promise<boolean> {
+  try {
+    const { data, error } = await adminDb
+      .from('apps')
+      .select('slug')
+      .eq('slug', 'spine-core')
+      .single()
+
+    return !error && !!data
+  } catch {
+    return false
+  }
+}
+
+function writeEnvFile(url: string, anonKey: string, serviceRoleKey: string, dryRun: boolean): void {
+  const envPath = resolve(PROJECT_ROOT, '.env')
+  const envContent = [
+    `VITE_SUPABASE_URL=${url}`,
+    `VITE_SUPABASE_ANON_KEY=${anonKey}`,
+    `SUPABASE_URL=${url}`,
+    `SUPABASE_ANON_KEY=${anonKey}`,
+    `SUPABASE_SERVICE_ROLE_KEY=${serviceRoleKey}`,
+    `VITE_APP_NAME=Spine`,
+    `DB_SCHEMA=public`,
+  ].join('\n') + '\n'
+
+  if (dryRun) {
+    console.log(`  [dry-run] Would write .env with SUPABASE_URL=${url}`)
+    return
+  }
+
+  const existed = existsSync(envPath)
+  writeFileSync(envPath, envContent, 'utf8')
+  console.log(`  ✓ ${existed ? 'Updated' : 'Created'} .env`)
+
+  // Also inject into process.env for the rest of this run
+  process.env.SUPABASE_URL = url
+  process.env.SUPABASE_ANON_KEY = anonKey
+  process.env.SUPABASE_SERVICE_ROLE_KEY = serviceRoleKey
+  process.env.VITE_SUPABASE_URL = url
+  process.env.VITE_SUPABASE_ANON_KEY = anonKey
+}
+
+async function initCommand(options: InitOptions): Promise<void> {
+  console.log('\n🚀 Spine Framework — Init\n')
+
+  // Step 0: Write .env if credentials were provided via flags
+  if (options.url && options.anonKey && options.serviceRoleKey) {
+    console.log('🔑 Step 0: Writing environment configuration...')
+    writeEnvFile(options.url, options.anonKey, options.serviceRoleKey, options.dryRun)
+  } else if (!process.env.SUPABASE_URL || !process.env.SUPABASE_SERVICE_ROLE_KEY) {
+    console.error('❌ No Supabase credentials found.')
+    console.error('   Provide them via flags:')
+    console.error('   spine-framework init --url <url> --anon-key <key> --service-role-key <key>')
+    console.error('   Or set SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY in .env')
+    process.exit(1)
+  }
+
+  // Check if already initialized
+  const alreadyInit = await checkAlreadyInitialized()
+  if (alreadyInit) {
+    console.log('  ⚠️  Database already initialized (spine-core app exists)')
+    console.log('  Skipping schema migration. Use "spine-framework migrations" to manage updates.\n')
+
+    if (!options.skipScaffold) {
+      console.log('📁 Checking workspace scaffold...')
+      scaffoldCustomWorkspace(options.dryRun)
+    }
+
+    console.log('\n✅ Init complete (already initialized)')
+    return
+  }
+
+  // Step 1: Foundation schema
+  console.log('📦 Step 1: Applying foundation schema (000_foundation.sql)...')
+  const foundationOk = await runMigration('000_foundation.sql', options.dryRun)
+  if (!foundationOk && !options.dryRun) {
+    console.error('\n❌ Init failed at foundation schema. Check your Supabase connection.')
+    process.exit(1)
+  }
+  console.log('  ✓ Foundation schema applied')
+
+  // Step 2: Seed data
+  console.log('\n🌱 Step 2: Applying seed data (001_seed.sql)...')
+  const seedOk = await runMigration('001_seed.sql', options.dryRun)
+  if (!seedOk && !options.dryRun) {
+    console.error('\n❌ Init failed at seed data.')
+    process.exit(1)
+  }
+  console.log('  ✓ Seed data applied')
+
+  // Step 3: Record migration versions
+  if (!options.dryRun) {
+    console.log('\n📝 Step 3: Recording migration versions...')
+    await adminDb
+      .from('schema_migrations')
+      .upsert([
+        { version: '000_foundation', applied_at: new Date().toISOString() },
+        { version: '001_seed', applied_at: new Date().toISOString() },
+      ], { onConflict: 'version' })
+    console.log('  ✓ Migration versions recorded')
+  }
+
+  // Step 4: Scaffold custom workspace
+  if (!options.skipScaffold) {
+    console.log('\n📁 Step 4: Scaffolding custom workspace...')
+    scaffoldCustomWorkspace(options.dryRun)
+  }
+
+  console.log('\n✅ Spine initialized successfully!')
+  console.log('\n   Next steps:')
+  console.log('   1. spine-framework install-app <app-slug>   # Install an app')
+  console.log('   2. spine-framework create-app my-app        # Or scaffold a new one')
+  console.log('   3. npm run assemble && netlify dev          # Start developing')
+}
+
+export function registerInitCommands(program: Command) {
+  program
+    .command('init')
+    .description('Initialize a fresh Spine installation (schema + seed + scaffold)')
+    .option('--url <url>', 'Supabase project URL (writes .env if provided)')
+    .option('--anon-key <key>', 'Supabase anon key')
+    .option('--service-role-key <key>', 'Supabase service role key')
+    .option('--skip-scaffold', 'Skip creating custom/ workspace directories', false)
+    .option('--dry-run', 'Show what would happen without making changes', false)
+    .action(async (opts) => {
+      try {
+        await initCommand(opts)
+      } catch (err: any) {
+        console.error('Error:', err.message)
+        if (process.env.SPINE_CLI_DEBUG) console.error(err.stack)
+        process.exit(1)
+      }
+    })
+}