spine-framework 0.1.61 → 1.0.0

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/context.ts

@@ -1,268 +0,0 @@
-/// <reference types="node" />
-/**
- * @module cli/context
- * @audience installer
- * @layer cli
- * @stability stable
- *
- * CLI context builder and output utilities. This is the CLI equivalent of
- * `createHandler()` in `middleware.ts` — it resolves the principal, picks the
- * correct Supabase client, and returns a `CoreContext` that every CLI command
- * passes directly to core functions.
- *
- * **Environment variables read from `.xenv` or `process.env`:**
- * | Variable                  | Required | Purpose                            |
- * |---------------------------|----------|------------------------------------|
- * | `SUPABASE_URL`            | yes      | Project API URL                    |
- * | `SUPABASE_SERVICE_ROLE_KEY` | yes    | Service-role client (admin ops)    |
- * | `SUPABASE_ANON_KEY`       | yes      | User-scoped client (JWT mode)      |
- * | `SPINE_CLI_ACCOUNT_ID`    | no       | Default account scope              |
- * | `SPINE_CLI_JWT`           | no       | Human principal (Supabase JWT)     |
- * | `SPINE_CLI_API_KEY`       | no       | Machine principal (hashed key)     |
- * | `SPINE_CLI_DEBUG`         | no       | Print stack traces on error        |
- *
- * **Principal resolution priority** (first match wins):
- * 1. `SPINE_CLI_JWT` → human principal (RLS-scoped `getUserDb`)
- * 2. `SPINE_CLI_API_KEY` → machine principal (`adminDb`)
- * 3. Fallback → `SYSTEM_PRINCIPAL` (`adminDb` — admin ops only)
- *
- * @seeAlso functions/_shared/middleware.ts (createHandler — server-side equivalent)
- * @seeAlso functions/_shared/principal.ts (Principal type and SYSTEM_PRINCIPAL)
- * @seeAlso cli/index.ts (entry point that imports all commands)
- */
-
-import { readFileSync, existsSync } from 'fs'
-import { resolve, dirname } from 'path'
-import { fileURLToPath } from 'url'
-import { CoreContext, adminDb, SYSTEM_PRINCIPAL, Principal, getUserDb } from '../functions/_shared/index.ts'
-
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = dirname(__filename)
-
-// ─── ENV LOADING ────────────────────────────────────────────────────────────
-
-// ─── CHUNK_START: CLI_CONTEXT_LOAD_ENV ──────────────────────────────────────────────
-/**
- * @chunk-id    CLI_CONTEXT_LOAD_ENV_1_0_0
- * @version     1.0.0
- * @hash        0adefa52a0c93821ee538ffe32a4069061bd75e7cada7175b11be3e11027e369
- * @macro       Environment Variable Loader
- * @micro       Reads .xenv file and populates process.env with missing vars
- * @inputs      none — reads from .xenv file path
- * @outputs     void — mutates process.env
- * @depends-on  [fs, path]
- * @depended-by [buildCliContext]
- * @side-effects [mutates process.env, file system reads]
- * @tags        environment, configuration, cli, dotenv
- */
-function loadEnv() {
-  const envPath = resolve(__dirname, '../.xenv')
-  if (existsSync(envPath)) {
-    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 value = trimmed.slice(eqIdx + 1).trim().replace(/^["']|["']$/g, '')
-      if (!process.env[key]) {
-        process.env[key] = value
-      }
-    }
-  }
-}
-// ─── CHUNK_END: CLI_CONTEXT_LOAD_ENV ────────────────────────────────────────────────
-
-// ─── TYPES ──────────────────────────────────────────────────────────────────
-
-/**
- * Options passed from CLI command `.action()` callbacks to `buildCliContext`.
- *
- * @inputSpec account: string | undefined — UUID of the target account; overrides
- *   `SPINE_CLI_ACCOUNT_ID` if both are present.
- * @calledBy All `registerXxxCommands` functions before calling core functions
- */
-export interface CliOptions {
-  account?: string
-}
-
-// ─── CONTEXT BUILDER ─────────────────────────────────────────────────────────
-
-// ─── CHUNK_START: CLI_CONTEXT_BUILD ──────────────────────────────────────────────
-/**
- * @chunk-id    CLI_CONTEXT_BUILD_1_0_0
- * @version     1.0.0
- * @hash        501162983b1b24e9a15267ca7b8398b3733f540b2a65a96d8277ec3d780f2003
- * @macro       CLI Context Builder
- * @micro       Constructs CoreContext with principal resolution and Supabase client
- * @inputs      opts: CliOptions — Optional overrides including account ID
- * @outputs     CoreContext — Fully resolved context with principal, DB client, and request ID
- * @depends-on  [loadEnv, adminDb, getUserDb, SYSTEM_PRINCIPAL]
- * @depended-by [All CLI command handlers]
- * @side-effects [DB queries, environment reads, crypto.randomUUID]
- * @tags        cli, authentication, principal-resolution, context
- */
-export async function buildCliContext(opts: CliOptions = {}): Promise<CoreContext> {
-  loadEnv()
-
-  if (!process.env.SUPABASE_URL || !process.env.SUPABASE_SERVICE_ROLE_KEY) {
-    throw new Error(
-      'Missing required env vars: SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY.\n' +
-      'Set them in v2-core/.xenv or export them before running spine commands.'
-    )
-  }
-
-  const accountId = opts.account || process.env.SPINE_CLI_ACCOUNT_ID || null
-  const requestId = crypto.randomUUID()
-
-  // Machine API key auth
-  const apiKey = process.env.SPINE_CLI_API_KEY
-  if (apiKey) {
-    const { data: keyRecord } = await adminDb
-      .from('api_keys')
-      .select('id, account_id, scopes, principal_id')
-      .eq('key_hash', apiKey)
-      .eq('is_active', true)
-      .single()
-
-    if (!keyRecord) {
-      throw new Error('Invalid or inactive SPINE_CLI_API_KEY')
-    }
-
-    const principal: Principal = {
-      id: keyRecord.principal_id || keyRecord.id,
-      type: 'machine',
-      accountId: keyRecord.account_id,
-      scopes: keyRecord.scopes || [],
-      provenance: {
-        sourceType: 'api_key',
-        createdBy: null,
-        apiKeyId: keyRecord.id,
-        invokedAt: new Date().toISOString()
-      }
-    }
-
-    return {
-      principal,
-      accountId: accountId || keyRecord.account_id,
-      db: adminDb,
-      requestId
-    }
-  }
-
-  // JWT auth (human principal)
-  const jwt = process.env.SPINE_CLI_JWT
-  if (jwt) {
-    const userDb = getUserDb(jwt)
-    const { data: { user } } = await userDb.auth.getUser()
-
-    if (!user) {
-      throw new Error('Invalid or expired SPINE_CLI_JWT')
-    }
-
-    const { data: person } = await adminDb
-      .from('people')
-      .select('id, full_name, email, roles:people_roles(role:roles(slug))')
-      .eq('auth_user_id', user.id)
-      .single()
-
-    const roles = (person?.roles as any[])?.map((r: any) => r.role?.slug).filter(Boolean) || []
-
-    const principal: Principal = {
-      id: person?.id || user.id,
-      type: 'human',
-      accountId: accountId,
-      displayName: person?.full_name || user.email,
-      email: person?.email || user.email,
-      roles,
-      provenance: {
-        sourceType: 'jwt',
-        createdBy: person?.id || user.id,
-        invokedAt: new Date().toISOString()
-      },
-      authContext: { jwt }
-    }
-
-    return {
-      principal,
-      accountId,
-      db: userDb,
-      requestId
-    }
-  }
-
-  // Fallback: system principal (admin ops)
-  return {
-    principal: SYSTEM_PRINCIPAL,
-    accountId,
-    db: adminDb,
-    requestId
-  }
-}
-// ─── CHUNK_END: CLI_CONTEXT_BUILD ────────────────────────────────────────────────
-
-// ─── OUTPUT UTILITIES ─────────────────────────────────────────────────────────
-
-// ─── CHUNK_START: CLI_CONTEXT_PRINT_RESULT ──────────────────────────────────────────────
-/**
- * @chunk-id    CLI_CONTEXT_PRINT_RESULT_1_0_0
- * @version     1.0.0
- * @hash        06e492defa9012290a5c8b2d4fca27f01df11bdc194ffbdf4f4b4518aa683c2b
- * @macro       CLI Output Formatter
- * @micro       Pretty-prints query results as JSON or ASCII tables
- * @inputs      data: any — Result data to display (array or single value)
- * @inputs      opts: { json?: boolean } — Output format options
- * @outputs     void — Console output only
- * @depends-on  [console, JSON]
- * @depended-by [All CLI command list/get handlers]
- * @side-effects [console.log output]
- * @tags        cli, output, formatting, tables, json
- */
-export function printResult(data: any, opts: { json?: boolean } = {}) {
-  if (opts.json) {
-    console.log(JSON.stringify(data, null, 2))
-    return
-  }
-
-  if (Array.isArray(data)) {
-    if (data.length === 0) {
-      console.log('(no results)')
-      return
-    }
-    const keys = Object.keys(data[0])
-    const rows = data.map(row => keys.map(k => String(row[k] ?? '')))
-    const widths = keys.map((k, i) => Math.max(k.length, ...rows.map(r => r[i].length)))
-    const hr = widths.map(w => '-'.repeat(w)).join('  ')
-    console.log(keys.map((k, i) => k.padEnd(widths[i])).join('  '))
-    console.log(hr)
-    rows.forEach(row => console.log(row.map((v, i) => v.padEnd(widths[i])).join('  ')))
-    console.log(`\n(${data.length} row${data.length !== 1 ? 's' : ''})`)
-  } else {
-    console.log(JSON.stringify(data, null, 2))
-  }
-}
-// ─── CHUNK_END: CLI_CONTEXT_PRINT_RESULT ────────────────────────────────────────────────
-
-// ─── CHUNK_START: CLI_CONTEXT_HANDLE_ERROR ──────────────────────────────────────────────
-/**
- * @chunk-id    CLI_CONTEXT_HANDLE_ERROR_1_0_0
- * @version     1.0.0
- * @hash        61aca7e4bce61b5b790e8f27ef3f505a6a6fe9a8cd6643e577f610d9dd15b1cd
- * @macro       CLI Error Handler
- * @micro       Prints formatted error and exits with proper debug information
- * @inputs      err: any — Error object or string message
- * @outputs     void — Process termination (exit code 1)
- * @depends-on  [console, process]
- * @depended-by [All CLI command action handlers]
- * @side-effects [console.error output, process.exit]
- * @tags        cli, error-handling, debug, process-exit
- */
-export function handleError(err: any) {
-  console.error(`\nError: ${err.message || err}`)
-  if (process.env.SPINE_CLI_DEBUG) {
-    console.error(err.stack)
-  }
-  process.exit(1)
-}
-// ─── CHUNK_END: CLI_CONTEXT_HANDLE_ERROR ────────────────────────────────────────────────

package/.framework/cli/env-loader.ts

@@ -1,36 +0,0 @@
-/// <reference types="node" />
-/**
- * @module cli/env-loader
- * @audience installer
- * @layer cli
- * @stability stable
- *
- * Side-effect module: loads `v2-core/.xenv` into `process.env` before any
- * other CLI module is imported. Must be the first import in `cli/index.ts`
- * so that `db.ts` (which reads env vars at module-load time) sees the values.
- *
- * @sideEffects Mutates process.env — only sets keys not already present
- */
-
-import { readFileSync, existsSync } from 'fs'
-import { resolve, dirname } from 'path'
-import { fileURLToPath } from 'url'
-
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = dirname(__filename)
-
-const envPath = resolve(__dirname, '../.xenv')
-if (existsSync(envPath)) {
-  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 value = trimmed.slice(eqIdx + 1).trim().replace(/^["']|["']$/g, '')
-    if (!process.env[key]) {
-      process.env[key] = value
-    }
-  }
-}

package/.framework/cli/index.ts

@@ -1,116 +0,0 @@
-#!/usr/bin/env node
-/// <reference types="node" />
-/**
- * @module cli/index
- * @audience installer
- * @layer cli
- * @stability stable
- *
- * Spine CLI entry point (`npx spine-framework`). Registers all command groups via
- * Commander and delegates each subcommand to the same core logic used by
- * API handlers and direct imports. No business logic lives here — only
- * command registration and top-level error handling.
- *
- * **Command groups registered:**
- * | Group       | File                       |
- * |-------------|----------------------------|
- * | auth        | commands/auth.ts           |
- * | pipelines   | commands/pipelines.ts      |
- * | items       | commands/items.ts          |
- * | agents      | commands/agents.ts         |
- * | migrations  | commands/migrations.ts     |
- * | init        | commands/init.ts           |
- * | install-app | commands/install-app.ts    |
- * | status      | commands/status.ts         |
- * | uninstall   | commands/uninstall-app.ts  |
- *
- * **Usage:**
- * ```bash
- * npx spine-framework --help
- * npx spine-framework auth whoami
- * npx spine-framework pipelines run <id> --data '{"key":"value"}'
- * npx spine-framework items list --type support_ticket
- * npx spine-framework items get <id>
- * npx spine-framework agents run <thread-id> --message "Hello"
- * npx spine-framework migrations list
- * ```
- *
- * @seeAlso cli/context.ts (buildCliContext — constructs CoreContext for every command)
- * @seeAlso functions/_shared/index.ts (core functions exposed to CLI)
- */
-
-import { Command } from 'commander'
-
-const program = new Command()
-
-program
-  .name('spine-framework')
-  .description('Spine v2 CLI — interact with your Spine instance from the terminal or agentic IDE')
-  .version('2.0.0')
-  .option('--account <id>', 'Override the account ID for this command')
-
-// Commands that do NOT need DB/env — safe to run on a fresh install
-const { registerInitCommands }    = await import('./commands/init.ts')
-const { registerMigrateCommands } = await import('./commands/migrate.ts')
-registerInitCommands(program)
-registerMigrateCommands(program)
-
-// All other commands require SUPABASE_URL to be set — only load if not init/migrate
-const subcommand = process.argv[2]
-const noDbCommands = ['init', 'migrate', '--help', '-h', '--version', '-V', undefined]
-
-if (!noDbCommands.includes(subcommand)) {
-  await import('./env-loader.ts')
-
-  const [
-    { registerAuthCommands },
-    { registerPipelineCommands },
-    { registerItemCommands },
-    { registerAgentCommands },
-    { registerMigrationCommands },
-    { registerDoctorCommands },
-    { registerDevCommands },
-    { registerTestCommands },
-    { registerSystemCommands },
-    { registerGenerateCommands },
-    { registerCreateAppCommands },
-    { registerInstallAppCommands },
-    { registerStatusCommands },
-    { registerUninstallAppCommands },
-  ] = await Promise.all([
-    import('./commands/auth.ts'),
-    import('./commands/pipelines.ts'),
-    import('./commands/items.ts'),
-    import('./commands/agents.ts'),
-    import('./commands/migrations.ts'),
-    import('./commands/doctor.ts'),
-    import('./commands/dev.ts'),
-    import('./commands/test.ts'),
-    import('./commands/system.ts'),
-    import('./commands/generate.ts'),
-    import('./commands/create-app.ts'),
-    import('./commands/install-app.ts'),
-    import('./commands/status.ts'),
-    import('./commands/uninstall-app.ts'),
-  ])
-
-  registerAuthCommands(program)
-  registerPipelineCommands(program)
-  registerItemCommands(program)
-  registerAgentCommands(program)
-  registerMigrationCommands(program)
-  registerDoctorCommands(program)
-  registerDevCommands(program)
-  registerTestCommands(program)
-  registerSystemCommands(program)
-  registerGenerateCommands(program)
-  registerCreateAppCommands(program)
-  registerInstallAppCommands(program)
-  registerStatusCommands(program)
-  registerUninstallAppCommands(program)
-}
-
-program.parseAsync(process.argv).catch((err) => {
-  console.error('Error:', err.message)
-  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'))