spine-framework 0.1.0

package/.framework/README.md

@@ -0,0 +1,129 @@
+# Spine v2 Frontend
+
+This is the frontend shell for Spine v2, built with React, TypeScript, and Tailwind CSS.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18+ 
+- npm or yarn
+- Supabase project
+
+### Installation
+
+1. Copy the environment file:
+```bash
+cp .env.example .env.local
+```
+
+2. Configure your Supabase credentials in `.env.local`:
+```env
+VITE_SUPABASE_URL=your_supabase_url
+VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
+```
+
+3. Install dependencies:
+```bash
+npm install
+```
+
+### Development
+
+Start the development server:
+```bash
+npm run dev
+```
+
+The application will be available at `http://localhost:3001`.
+
+### Build
+
+Build for production:
+```bash
+npm run build
+```
+
+### Functions
+
+Start the Netlify functions server:
+```bash
+npm run functions:dev
+```
+
+## Project Structure
+
+```
+src/
+├── components/
+│   ├── layout/          # Layout components (Header, Sidebar, etc.)
+│   └── ui/              # Reusable UI components
+├── contexts/            # React contexts (Auth, etc.)
+├── lib/                 # Utility functions and configurations
+├── pages/               # Page components
+│   ├── auth/           # Authentication pages
+│   └── admin/          # Admin pages
+├── types/               # TypeScript type definitions
+├── App.tsx             # Main app component
+├── main.tsx            # App entry point
+└── index.css           # Global styles
+```
+
+## Features
+
+- **Authentication**: Secure login/logout with Supabase
+- **Layout**: Responsive sidebar navigation and header
+- **Admin Interface**: Full admin pages for managing accounts, people, types, and apps
+- **Item Management**: Generic item viewing and management
+- **Dashboard**: Overview with statistics and recent activity
+- **Type Safety**: Full TypeScript support throughout
+
+## Key Components
+
+### Authentication
+- Uses Supabase Auth for secure authentication
+- JWT token management with automatic refresh
+- Role-based access control
+
+### Layout System
+- Responsive sidebar navigation
+- Mobile-friendly with collapsible menu
+- User profile and logout functionality
+
+### Admin Pages
+- **Accounts**: Multi-tenant account management
+- **People**: User management across accounts
+- **Types**: Item type schema management
+- **Apps**: Application configuration and management
+
+### Styling
+- Tailwind CSS for utility-first styling
+- Custom CSS variables for theming
+- Component-based styling approach
+
+## Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `VITE_SUPABASE_URL` | Supabase project URL | Yes |
+| `VITE_SUPABASE_ANON_KEY` | Supabase anonymous key | Yes |
+| `VITE_NETLIFY_FUNCTIONS_URL` | Netlify functions URL | No |
+
+## Scripts
+
+- `npm run dev` - Start development server
+- `npm run build` - Build for production
+- `npm run preview` - Preview production build
+- `npm run functions:dev` - Start functions server
+
+## Contributing
+
+1. Follow the existing code style
+2. Use TypeScript for all new code
+3. Add proper error handling
+4. Include loading states where appropriate
+5. Test responsive design
+
+## License
+
+This project is part of the Spine v2 framework.

package/.framework/cli/bin.cjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// Thin shebang wrapper — invokes the TypeScript CLI via tsx.
+// This file is the npm bin entry point for spine-framework.
+const { execFileSync } = require('child_process')
+const { resolve } = require('path')
+
+const tsx = resolve(__dirname, '../../node_modules/.bin/tsx')
+const entry = resolve(__dirname, 'index.ts')
+
+try {
+  execFileSync(tsx, [entry, ...process.argv.slice(2)], { stdio: 'inherit' })
+} catch (e) {
+  process.exit(e.status ?? 1)
+}

package/.framework/cli/commands/agents.ts

@@ -0,0 +1,153 @@
+/// <reference types="node" />
+/**
+ * @module cli/commands/agents
+ * @audience installer
+ * @layer cli
+ * @stability stable
+ *
+ * `spine agents` command group. Sends messages to AI agent threads and
+ * inspects thread state from the terminal or an agentic IDE. `agents run`
+ * calls `runAgent` — the same function used by API handlers — so responses
+ * are recorded in the `messages` table like any other agent turn.
+ *
+ * **Commands:**
+ * | Subcommand                                       | Description                           |
+ * |--------------------------------------------------|---------------------------------------|
+ * | `agents run <threadId> --message <text>`         | Send a message and print the response |
+ * | `agents threads list [--account <id>]`           | List agent threads                    |
+ * | `agents threads get <id> [--limit <n>]`          | Show thread + recent messages         |
+ *
+ * **Usage:**
+ * ```bash
+ * spine agents run <uuid> --message "Summarize the last 10 tickets" --json
+ * spine agents threads list --account <id> --limit 10
+ * spine agents threads get <uuid>
+ * ```
+ *
+ * @seeAlso cli/context.ts (buildCliContext)
+ * @seeAlso functions/_shared/agent-runner.ts (runAgent)
+ * @seeAlso functions/ai-agents.ts (agent configuration CRUD)
+ */
+
+import type { Command } from 'commander'
+import { buildCliContext, printResult, handleError } from '../context.ts'
+import { runAgent, adminDb } from '../../functions/_shared/index.ts'
+
+/**
+ * Registers the `agents` subcommand group on the root Commander program.
+ *
+ * @param program - The root `spine` Commander instance
+ * @sideEffects Adds `agents run`, `agents threads list/get` subcommands to `program`
+ * @calledBy cli/index.ts
+ */
+export function registerAgentCommands(program: Command) {
+  const agents = program
+    .command('agents')
+    .description('AI agent interaction')
+
+  agents
+    .command('run <threadId>')
+    .description('Send a message to an agent thread and get a response')
+    .requiredOption('--message <text>', 'The message to send')
+    .option('--account <id>', 'Account scope')
+    .option('--json', 'Output as JSON')
+    .action(async (threadId, opts) => {
+      try {
+        const ctx = await buildCliContext({ account: opts.account })
+
+        console.log(`Sending message to thread ${threadId}...`)
+        const response = await runAgent(threadId, opts.message, ctx)
+
+        if (opts.json) {
+          console.log(JSON.stringify(response, null, 2))
+        } else {
+          console.log('\n─── Agent Response ───')
+          console.log(response.content || JSON.stringify(response))
+          console.log('─────────────────────')
+          if (response.data?.confidence !== undefined) {
+            console.log(`Confidence: ${(response.data.confidence * 100).toFixed(0)}%`)
+          }
+          console.log()
+        }
+      } catch (err: any) {
+        handleError(err)
+      }
+    })
+
+  const threads = agents
+    .command('threads')
+    .description('Agent thread management')
+
+  threads
+    .command('list')
+    .description('List agent threads')
+    .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('threads')
+          .select('id, title, status, created_at')
+          .order('created_at', { ascending: false })
+          .limit(parseInt(opts.limit))
+
+        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)
+      }
+    })
+
+  threads
+    .command('get <id>')
+    .description('Get thread details and recent messages')
+    .option('--limit <n>', 'Number of messages to show', '20')
+    .option('--json', 'Output as JSON')
+    .action(async (id, opts) => {
+      try {
+        await buildCliContext()
+
+        const { data: thread, error: threadError } = await adminDb
+          .from('threads')
+          .select('*')
+          .eq('id', id)
+          .single()
+
+        if (threadError || !thread) throw new Error(`Thread not found: ${id}`)
+
+        const { data: messages, error: msgError } = await adminDb
+          .from('messages')
+          .select('id, content, data, created_at')
+          .eq('thread_id', id)
+          .order('created_at', { ascending: true })
+          .limit(parseInt(opts.limit))
+
+        if (msgError) throw new Error(msgError.message)
+
+        if (opts.json) {
+          console.log(JSON.stringify({ thread, messages }, null, 2))
+        } else {
+          console.log(`\nThread: ${thread.title || thread.id}`)
+          console.log(`Status: ${thread.status || 'open'}`)
+          console.log('─'.repeat(50))
+          for (const msg of messages || []) {
+            const msgType = msg.data?.message_type || 'message'
+            const prefix = msgType === 'human' ? 'You' : msgType === 'agent' ? 'Agent' : msgType
+            console.log(`\n[${prefix}] ${msg.created_at}`)
+            console.log(msg.content)
+          }
+          console.log()
+        }
+      } catch (err: any) {
+        handleError(err)
+      }
+    })
+}

package/.framework/cli/commands/auth.ts

@@ -0,0 +1,94 @@
+/**
+ * @module cli/commands/auth
+ * @audience installer
+ * @layer cli
+ * @stability stable
+ *
+ * `spine auth` command group. Exposes two subcommands for verifying and
+ * inspecting the currently configured CLI credentials without performing
+ * any data operations.
+ *
+ * **Commands:**
+ * | Subcommand        | Description                                           |
+ * |-------------------|-------------------------------------------------------|
+ * | `auth whoami`     | Print the resolved principal for the current env      |
+ * | `auth check`      | Validate credentials; exit 0 on success, 1 on failure |
+ *
+ * **Usage:**
+ * ```bash
+ * spine auth whoami
+ * spine auth whoami --json
+ * spine auth check
+ * ```
+ *
+ * @seeAlso cli/context.ts (buildCliContext — principal resolution)
+ * @seeAlso functions/auth.ts (API equivalent)
+ */
+
+import type { Command } from 'commander'
+import { buildCliContext, handleError } from '../context.js'
+
+/**
+ * Registers the `auth` subcommand group on the root Commander program.
+ *
+ * @param program - The root `spine` Commander instance
+ * @sideEffects Adds `auth whoami` and `auth check` subcommands to `program`
+ * @calledBy cli/index.ts
+ */
+export function registerAuthCommands(program: Command) {
+  const auth = program
+    .command('auth')
+    .description('Authentication and identity commands')
+
+  auth
+    .command('whoami')
+    .description('Show the resolved principal for the current environment config')
+    .option('--json', 'Output as JSON')
+    .action(async (opts) => {
+      try {
+        const ctx = await buildCliContext()
+        const output = {
+          principal_id: ctx.principal.id,
+          principal_type: ctx.principal.type,
+          account_id: ctx.accountId,
+          display_name: ctx.principal.displayName,
+          email: ctx.principal.email,
+          roles: ctx.principal.roles,
+          scopes: ctx.principal.scopes,
+          request_id: ctx.requestId
+        }
+
+        if (opts.json) {
+          console.log(JSON.stringify(output, null, 2))
+        } else {
+          console.log('\nSpine CLI — Current Identity')
+          console.log('─'.repeat(40))
+          console.log(`Principal ID:   ${output.principal_id}`)
+          console.log(`Type:           ${output.principal_type}`)
+          console.log(`Account:        ${output.account_id || '(none)'}`)
+          if (output.display_name) console.log(`Name:           ${output.display_name}`)
+          if (output.email) console.log(`Email:          ${output.email}`)
+          if (output.roles?.length) console.log(`Roles:          ${output.roles.join(', ')}`)
+          if (output.scopes?.length) console.log(`Scopes:         ${output.scopes.join(', ')}`)
+          console.log(`Request ID:     ${output.request_id}`)
+          console.log()
+        }
+      } catch (err: any) {
+        handleError(err)
+      }
+    })
+
+  auth
+    .command('check')
+    .description('Validate credentials — exits 0 if valid, 1 if not')
+    .action(async () => {
+      try {
+        await buildCliContext()
+        console.log('✓ Credentials valid')
+        process.exit(0)
+      } catch (err: any) {
+        console.error(`✗ ${err.message}`)
+        process.exit(1)
+      }
+    })
+}

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

@@ -0,0 +1,185 @@
+/// <reference types="node" />
+/**
+ * @module cli/commands/create-app
+ * @audience installer
+ * @layer cli
+ * @stability stable
+ *
+ * `spine-framework create-app <slug>` — scaffold a new custom app.
+ *
+ * Creates the full directory structure under `custom/apps/{slug}/`:
+ *   - manifest.json     (app metadata, roles, routes, nav_items)
+ *   - index.tsx         (React entry point)
+ *   - components/       (empty dir with .gitkeep)
+ *
+ * **Usage:**
+ * ```bash
+ * npm run spine-framework create-app my-app
+ * npm run spine-framework create-app my-app --name "My App" --role member
+ * npm run spine-framework create-app my-app --force
+ * ```
+ */
+
+import type { Command } from 'commander'
+import { existsSync, mkdirSync, 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, '../../../')
+
+function toTitleCase(slug: string): string {
+  return slug.split('-').map(s => s.charAt(0).toUpperCase() + s.slice(1)).join(' ')
+}
+
+function generateManifest(slug: string, name: string, role: string): string {
+  return JSON.stringify({
+    name,
+    slug,
+    description: `${name} app`,
+    version: "1.0.0",
+    required_roles: [role],
+    routes: [
+      `/${slug}`,
+      `/${slug}/dashboard`
+    ],
+    nav_items: [
+      {
+        title: "Dashboard",
+        path: `/${slug}/dashboard`,
+        icon: "LayoutDashboard",
+        order: 1
+      }
+    ],
+    features: [],
+    dependencies: [],
+    entry_point: "./index.tsx"
+  }, null, 2) + '\n'
+}
+
+function generateIndexTsx(slug: string, name: string): string {
+  const componentName = slug.split('-').map(s => s.charAt(0).toUpperCase() + s.slice(1)).join('')
+  return `/**
+ * @module custom/apps/${slug}
+ * @audience custom
+ * @layer frontend-app
+ * @stability experimental
+ *
+ * Entry point for the ${name} app.
+ * Generated by spine-framework CLI on ${new Date().toISOString().split('T')[0]}.
+ */
+
+import * as React from 'react'
+import { Routes, Route, Navigate } from 'react-router-dom'
+
+function ${componentName}Dashboard() {
+  return (
+    <div className="p-6">
+      <h1 className="text-2xl font-bold mb-2">${name}</h1>
+      <p className="text-slate-500">Welcome to ${name}. Edit custom/apps/${slug}/index.tsx to get started.</p>
+    </div>
+  )
+}
+
+export default function ${componentName}App() {
+  return (
+    <Routes>
+      <Route path="/" element={<Navigate to="dashboard" replace />} />
+      <Route path="dashboard" element={<${componentName}Dashboard />} />
+    </Routes>
+  )
+}
+`
+}
+
+async function createApp(slug: string, options: { name?: string; role: string; force: boolean }): Promise<void> {
+  const name = options.name || toTitleCase(slug)
+  const appDir = resolve(PROJECT_ROOT, `custom/apps/${slug}`)
+
+  console.log(`\n🔧 Creating app '${slug}'...`)
+
+  if (existsSync(appDir) && !options.force) {
+    console.error(`  ❌ App directory already exists: custom/apps/${slug}`)
+    console.error(`     Use --force to overwrite`)
+    process.exit(1)
+  }
+
+  // 1. Create directories
+  mkdirSync(resolve(appDir, 'components'), { recursive: true })
+  console.log(`  ✓ Created custom/apps/${slug}/`)
+  console.log(`  ✓ Created custom/apps/${slug}/components/`)
+
+  // 2. manifest.json
+  writeFileSync(
+    resolve(appDir, 'manifest.json'),
+    generateManifest(slug, name, options.role)
+  )
+  console.log(`  ✓ Created custom/apps/${slug}/manifest.json`)
+
+  // 3. index.tsx
+  writeFileSync(
+    resolve(appDir, 'index.tsx'),
+    generateIndexTsx(slug, name)
+  )
+  console.log(`  ✓ Created custom/apps/${slug}/index.tsx`)
+
+  // 4. components/.gitkeep
+  writeFileSync(resolve(appDir, 'components', '.gitkeep'), '')
+
+  // 5. Insert app record into database
+  console.log(`  Registering app in database...`)
+  const { data: existing } = await adminDb
+    .from('apps')
+    .select('id')
+    .eq('slug', slug)
+    .single()
+
+  if (existing) {
+    console.log(`  ⚠️  App '${slug}' already exists in database (skipping insert)`)
+  } else {
+    const { error: insertErr } = await adminDb
+      .from('apps')
+      .insert({
+        slug,
+        name,
+        route_prefix: `/${slug}`,
+        renderer: 'custom',
+        is_active: true,
+        is_system: false,
+        min_role: options.role,
+      })
+
+    if (insertErr) {
+      console.error(`  ❌ Database insert failed: ${insertErr.message}`)
+      console.error(`     Run manually: INSERT INTO apps (slug, name, route_prefix, renderer, is_active)`)
+      console.error(`     VALUES ('${slug}', '${name}', '/${slug}', 'custom', true);`)
+    } else {
+      console.log(`  ✓ App registered in database`)
+    }
+  }
+
+  console.log(`\n✅ App '${name}' ready at custom/apps/${slug}/`)
+  console.log(`\n   Next steps:`)
+  console.log(`   1. Edit custom/apps/${slug}/manifest.json to configure routes and nav`)
+  console.log(`   2. Edit custom/apps/${slug}/index.tsx to build your app`)
+  console.log(`   3. npm run assemble && netlify dev`)
+}
+
+export function registerCreateAppCommands(program: Command) {
+  program
+    .command('create-app <slug>')
+    .description('Scaffold a new custom app in custom/apps/{slug}/')
+    .option('--name <name>', 'Display name for the app (defaults to title-cased slug)')
+    .option('--role <role>', 'Required role to access this app', 'member')
+    .option('--force', 'Overwrite existing files', false)
+    .action(async (slug, opts) => {
+      try {
+        await createApp(slug, opts)
+      } catch (err: any) {
+        console.error('Error:', err.message)
+        process.exit(1)
+      }
+    })
+}