spine-framework 0.1.61 → 0.2.0

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

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

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

@@ -1,166 +0,0 @@
-/// <reference types="node" />
-/**
- * @module cli/commands/uninstall-app
- * @audience installer
- * @layer cli
- * @stability stable
- *
- * `spine-framework uninstall-app <slug>` — Soft-uninstall an app.
- *
- * Deactivates the app's types, link types, and triggers in the database.
- * Does NOT delete data (items, threads, etc.) — those remain for audit.
- * Does NOT remove filesystem files — the app code stays in custom/apps/.
- *
- * To fully remove: manually delete the app directory after uninstall.
- *
- * **Usage:**
- * ```bash
- * spine-framework uninstall-app cortex
- * spine-framework uninstall-app cortex --hard   # Also deactivate items
- * ```
- */
-
-import type { Command } from 'commander'
-import { adminDb } from '../../functions/_shared/index.ts'
-
-interface UninstallOptions {
-  hard: boolean
-  dryRun: boolean
-}
-
-async function uninstallApp(slug: string, options: UninstallOptions): Promise<void> {
-  console.log(`\n🗑️  Uninstalling app '${slug}'...\n`)
-
-  // 1. Find the app
-  const { data: app, error: appErr } = await adminDb
-    .from('apps')
-    .select('id, name')
-    .eq('slug', slug)
-    .single()
-
-  if (appErr || !app) {
-    console.error(`  ❌ App '${slug}' not found in database`)
-    process.exit(1)
-  }
-
-  const appId = app.id
-
-  // 2. Deactivate types
-  if (options.dryRun) {
-    const { data: types } = await adminDb
-      .from('types').select('slug').eq('app_id', appId).eq('is_active', true)
-    console.log(`  [dry-run] Would deactivate ${types?.length || 0} types`)
-  } else {
-    const { data: updated } = await adminDb
-      .from('types')
-      .update({ is_active: false })
-      .eq('app_id', appId)
-      .eq('is_active', true)
-      .select('id')
-
-    console.log(`  ✓ Deactivated ${updated?.length || 0} types`)
-  }
-
-  // 3. Deactivate link types
-  if (options.dryRun) {
-    const { data: lt } = await adminDb
-      .from('link_types').select('slug').eq('app_id', appId).eq('is_active', true)
-    console.log(`  [dry-run] Would deactivate ${lt?.length || 0} link types`)
-  } else {
-    const { data: updated } = await adminDb
-      .from('link_types')
-      .update({ is_active: false })
-      .eq('app_id', appId)
-      .eq('is_active', true)
-      .select('id')
-
-    console.log(`  ✓ Deactivated ${updated?.length || 0} link types`)
-  }
-
-  // 4. Deactivate triggers
-  if (options.dryRun) {
-    const { data: triggers } = await adminDb
-      .from('triggers').select('name').eq('app_id', appId).eq('is_active', true)
-    console.log(`  [dry-run] Would deactivate ${triggers?.length || 0} triggers`)
-  } else {
-    const { data: updated } = await adminDb
-      .from('triggers')
-      .update({ is_active: false })
-      .eq('app_id', appId)
-      .eq('is_active', true)
-      .select('id')
-
-    console.log(`  ✓ Deactivated ${updated?.length || 0} triggers`)
-  }
-
-  // 5. Hard mode: deactivate items of this app's types
-  if (options.hard) {
-    if (options.dryRun) {
-      const { data: types } = await adminDb
-        .from('types').select('id').eq('app_id', appId)
-      const typeIds = types?.map(t => t.id) || []
-      if (typeIds.length > 0) {
-        const { data: items } = await adminDb
-          .from('items').select('id').in('type_id', typeIds).eq('is_active', true)
-        console.log(`  [dry-run] Would deactivate ${items?.length || 0} items (--hard)`)
-      }
-    } else {
-      const { data: types } = await adminDb
-        .from('types').select('id').eq('app_id', appId)
-      const typeIds = types?.map(t => t.id) || []
-
-      if (typeIds.length > 0) {
-        const { data: updated } = await adminDb
-          .from('items')
-          .update({ is_active: false })
-          .in('type_id', typeIds)
-          .eq('is_active', true)
-          .select('id')
-
-        console.log(`  ✓ Deactivated ${updated?.length || 0} items (--hard)`)
-      }
-    }
-  }
-
-  // 6. Mark installation as disabled
-  if (!options.dryRun) {
-    await adminDb
-      .from('app_installations')
-      .update({ is_enabled: false, updated_at: new Date().toISOString() })
-      .eq('app_slug', slug)
-  }
-
-  // 7. Deactivate app record
-  if (!options.dryRun) {
-    await adminDb
-      .from('apps')
-      .update({ is_active: false })
-      .eq('id', appId)
-
-    console.log(`  ✓ App '${slug}' deactivated`)
-  }
-
-  console.log(`\n✅ App '${app.name}' uninstalled (soft-delete)`)
-  if (!options.hard) {
-    console.log(`   Items created by this app are preserved.`)
-    console.log(`   Use --hard to also deactivate items.`)
-  }
-  console.log(`   App files remain in custom/apps/${slug}/ — delete manually if desired.`)
-}
-
-export function registerUninstallAppCommands(program: Command) {
-  program
-    .command('uninstall-app <slug>')
-    .description('Soft-uninstall an app (deactivate types, triggers, link types)')
-    .option('--hard', 'Also deactivate items created by this app', false)
-    .option('--dry-run', 'Show what would happen without making changes', false)
-    .action(async (slug, opts) => {
-      try {
-        await uninstallApp(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/welcome.cjs

@@ -1,45 +0,0 @@
-#!/usr/bin/env node
-// Postinstall welcome message — runs automatically after npm install spine-framework.
-// Tells the agent (or developer) exactly what to do next.
-// Uses only Node built-ins — no dependencies.
-
-const lines = [
-  '',
-  '╭──────────────────────────────────────────────────────────────╮',
-  '│                                                              │',
-  '│   ███████╗██████╗ ██╗███╗   ██╗███████╗                    │',
-  '│   ██╔════╝██╔══██╗██║████╗  ██║██╔════╝                    │',
-  '│   ███████╗██████╔╝██║██╔██╗ ██║█████╗                      │',
-  '│   ╚════██║██╔═══╝ ██║██║╚██╗██║██╔══╝                      │',
-  '│   ███████║██║     ██║██║ ╚████║███████╗                    │',
-  '│   ╚══════╝╚═╝     ╚═╝╚═╝  ╚═══╝╚══════╝  Framework v0.1   │',
-  '│                                                              │',
-  '╰──────────────────────────────────────────────────────────────╯',
-  '',
-  '  Spine Framework installed successfully!',
-  '',
-  '  To complete setup you need a Supabase project.',
-  '  ─────────────────────────────────────────────',
-  '  If you have one already, run:',
-  '',
-  '    spine-framework init \\',
-  '      --url       https://<project>.supabase.co \\',
-  '      --anon-key  <anon-key> \\',
-  '      --service-role-key <service-role-key>',
-  '',
-  '  Your credentials are at:',
-  '  Supabase Dashboard → Your Project → Settings → API',
-  '',
-  '  ─────────────────────────────────────────────',
-  '  If you need a Supabase project, create one at:',
-  '  https://supabase.com/dashboard → New project',
-  '',
-  '  After init:',
-  '    spine-framework install-app <app-slug>   # optional apps',
-  '    npm run assemble && netlify dev           # start dev server',
-  '',
-  '  Docs: https://github.com/art-mojo-admin/spine',
-  '',
-]
-
-console.log(lines.join('\n'))

package/.framework/docs/STABILITY.md

@@ -1,52 +0,0 @@
-# Stability Policy
-
-> Version target: **0.x** — breaking changes are allowed until 1.0.
-
-## Stability Levels
-
-Every exported symbol in `_shared/index.ts` is annotated with one of these levels:
-
-| Level | Meaning | Breaking change policy |
-|-------|---------|----------------------|
-| **stable** | Safe for custom code to depend on | Minimum 1 minor version deprecation notice before removal |
-| **evolving** | API may change between minor versions | No deprecation period required, but changelog entry mandatory |
-| **internal** | Not exported; core-contributor only | May change without notice |
-
-## Versioning
-
-Spine follows [semver](https://semver.org/) with these conventions:
-
-- **0.x.y** — Pre-stable. Breaking changes increment the minor version.
-- **1.0.0+** — Stable. Breaking changes increment the major version.
-
-## Deprecation Process
-
-1. Mark the symbol with `@deprecated` JSDoc tag and a migration hint
-2. Add a console warning on first use (once per process)
-3. Remove after the next minor version bump
-
-## What Counts as Breaking
-
-- Removing or renaming an exported function/type from `_shared/index.ts`
-- Changing function signatures (required params added, return type changed)
-- Removing a CLI command or changing its required arguments
-- Changing database table/column names in migration files
-- Removing seed data keys from `seed/*.json` schemas
-
-## What Does NOT Count as Breaking
-
-- Adding new optional parameters to existing functions
-- Adding new exports to `_shared/index.ts`
-- Adding new CLI commands
-- Adding new database tables or columns
-- Performance improvements to existing functions
-- Bug fixes (even if they change observable behavior that was clearly wrong)
-
-## Release Checklist
-
-1. `npm run test:boundary` — architectural boundaries intact
-2. `npm run test:unit` — unit tests pass
-3. Update `CHANGELOG.md` with breaking changes highlighted
-4. Bump version in `package.json`
-5. `npm run prepublishOnly` — build + test gate
-6. `npm publish`

package/.framework/docs/examples/custom-app/README.md

@@ -1,77 +0,0 @@
-# Example: Custom App
-
-A minimal React app with manifest and routing, installable via `spine-framework install-app`.
-
-## Directory Structure
-
-```
-custom/apps/my-app/
-├── manifest.json       # App metadata, routes, nav items
-├── index.tsx           # React entry point (default export)
-├── seed/
-│   ├── types.json      # Item types this app provides
-│   └── triggers.json   # Automation triggers
-├── components/
-│   └── Dashboard.tsx   # App-specific components
-└── package.json        # npm package metadata (optional)
-```
-
-## manifest.json
-
-```json
-{
-  "name": "My App",
-  "slug": "my-app",
-  "version": "0.1.0",
-  "description": "A custom app for demonstration",
-  "routes": [
-    { "path": "/", "redirect": "/dashboard" },
-    { "path": "/dashboard", "component": "Dashboard" }
-  ],
-  "nav_items": [
-    { "label": "Dashboard", "path": "/dashboard", "icon": "LayoutDashboard" }
-  ],
-  "required_roles": ["member"]
-}
-```
-
-## index.tsx
-
-```tsx
-import * as React from 'react'
-import { Routes, Route, Navigate } from 'react-router-dom'
-
-function Dashboard() {
-  return (
-    <div className="p-6">
-      <h1 className="text-2xl font-bold">My App</h1>
-    </div>
-  )
-}
-
-export default function MyApp() {
-  return (
-    <Routes>
-      <Route path="/" element={<Navigate to="dashboard" replace />} />
-      <Route path="dashboard" element={<Dashboard />} />
-    </Routes>
-  )
-}
-```
-
-## Installation
-
-```bash
-# Create the app scaffold
-spine-framework create-app my-app
-
-# Or install an existing app package
-spine-framework install-app my-app
-```
-
-## How It Works
-
-1. `CustomAppLoader` discovers apps via `import.meta.glob('custom/apps/*/index.tsx')`
-2. The app's `manifest.json` provides routing and navigation metadata
-3. Seed data is applied via `spine-framework install-app` (idempotent upserts)
-4. The app is isolated — it cannot import from other apps or core internals

package/.framework/docs/examples/custom-function/README.md

@@ -1,27 +0,0 @@
-# Example: Custom Function
-
-A minimal Netlify Function using Spine's core context system.
-
-## Setup
-
-1. Create `custom/functions/custom_my-handler.ts`
-2. Import `createHandler` and `CoreContext` from `spine-framework/_shared`
-3. Your handler receives a fully-resolved `CoreContext` with:
-   - `ctx.principal` — authenticated user/machine identity
-   - `ctx.db` — Supabase client (scoped to principal's permissions)
-   - `ctx.accountId` — resolved account UUID
-   - `ctx.requestId` — unique request trace ID
-
-## Key Points
-
-- **Naming convention:** Custom functions MUST be prefixed with `custom_`
-- **No static imports from core:** Use the `spine-framework` package exports
-- **Authentication is automatic:** `createHandler` validates the JWT/API key before your code runs
-- **Database access:** Use `ctx.db` for RLS-scoped queries, or import `adminDb` for service-role operations
-
-## API
-
-```
-GET/POST /.netlify/functions/custom_my-handler?action=list
-Authorization: Bearer <jwt>
-```

package/.framework/docs/examples/custom-function/handler.ts

@@ -1,48 +0,0 @@
-/**
- * Example: Custom Netlify Function using Spine core context
- *
- * This demonstrates the minimal pattern for creating a custom function
- * that leverages Spine's authentication, database, and principal system.
- *
- * File: custom/functions/custom_my-handler.ts
- */
-
-import { createHandler, adminDb } from 'spine-framework/_shared'
-import type { CoreContext } from 'spine-framework/_shared'
-
-/**
- * A simple handler that lists items for the current account.
- */
-async function listAccountItems(ctx: CoreContext) {
-  const { data, error } = await ctx.db
-    .from('items')
-    .select('id, title, type_id, created_at')
-    .eq('account_id', ctx.accountId)
-    .eq('is_active', true)
-    .order('created_at', { ascending: false })
-    .limit(50)
-
-  if (error) {
-    return { statusCode: 500, body: JSON.stringify({ error: error.message }) }
-  }
-
-  return {
-    statusCode: 200,
-    body: JSON.stringify({ items: data }),
-  }
-}
-
-/**
- * Netlify Function entry point.
- * `createHandler` resolves the principal, validates auth, and provides CoreContext.
- */
-export const handler = createHandler(async (ctx) => {
-  const { action } = ctx.params
-
-  switch (action) {
-    case 'list':
-      return listAccountItems(ctx)
-    default:
-      return { statusCode: 400, body: JSON.stringify({ error: 'Unknown action' }) }
-  }
-})

package/.framework/docs/examples/custom-webhook/README.md

@@ -1,68 +0,0 @@
-# Example: Custom Webhook Handler
-
-Demonstrates the self-registration pattern for webhook handlers.
-
-## How It Works
-
-1. Create a handler function in `custom/functions/custom_my-webhook.ts`
-2. Register it by calling `registerWebhookHandler()` in `custom/functions/custom_webhook-handlers.ts`
-3. Core resolves handlers at runtime via the `webhook_handlers` DB table — no static imports needed
-
-## Handler Function
-
-```ts
-// custom/functions/custom_my-webhook.ts
-
-import { createHandler } from 'spine-framework/_shared'
-import type { CoreContext } from 'spine-framework/_shared'
-
-export const handler = createHandler(async (ctx: CoreContext) => {
-  const payload = ctx.body
-
-  // Process the webhook payload
-  console.log('Received webhook:', payload.event_type)
-
-  // Do something with the data
-  const { error } = await ctx.db
-    .from('items')
-    .insert({
-      title: `Webhook: ${payload.event_type}`,
-      type_id: await resolveTypeId('webhook_event'),
-      account_id: ctx.accountId,
-      data: payload,
-    })
-
-  if (error) {
-    return { statusCode: 500, body: JSON.stringify({ error: error.message }) }
-  }
-
-  return { statusCode: 200, body: JSON.stringify({ ok: true }) }
-})
-```
-
-## Registration
-
-```ts
-// In custom/functions/custom_webhook-handlers.ts
-
-import { registerWebhookHandler } from 'spine-framework/_shared/webhook-registration'
-
-registerWebhookHandler({
-  name: 'my-webhook',
-  functionName: 'custom_my-webhook',
-  description: 'Handles incoming webhooks from MyService',
-  events: ['integration.webhook'],
-}).catch(console.error)
-```
-
-## Integration Config
-
-When configuring an integration in the admin panel, set:
-- `handler.path` = `my-webhook` (matches the `name` in registration)
-
-## Key Points
-
-- **Self-registration is idempotent** — safe to call on every module load
-- **No core changes needed** — just add your handler and register it
-- **Runtime resolution** — core looks up handlers from `webhook_handlers` table via `resolveHandler()`
-- **Events array** — currently `['integration.webhook']` is the standard event type