spine-framework 0.3.17 → 0.3.19

package/docs/APPS.md

@@ -0,0 +1,232 @@
+# Spine Framework App Development
+
+Apps are the primary way to extend Spine Framework functionality. This guide covers creating, installing, and managing apps.
+
+## What is an App?
+
+An app in Spine Framework is:
+- A self-contained feature module
+- Has its own types, roles, and permissions
+- Can define pages, components, and API endpoints
+- Installs into `custom/apps/<app-slug>/`
+
+## App Structure
+
+```
+custom/apps/my-app/
+├── index.tsx           # Entry point & routes
+├── manifest.json       # App configuration
+├── seed/
+│   ├── types.json     # Custom types
+│   ├── roles.json     # Custom roles
+│   └── link-types.json # Link definitions
+├── pages/
+│   ├── Dashboard.tsx
+│   └── Settings.tsx
+├── components/
+│   └── MyComponent.tsx
+├── api/
+│   └── handlers.ts
+├── hooks/
+│   └── useMyData.ts
+└── README.md
+```
+
+## manifest.json
+
+The manifest defines your app's metadata and configuration:
+
+```json
+{
+  "slug": "my-app",
+  "name": "My App",
+  "description": "What this app does",
+  "version": "1.0.0",
+  "icon": "app-icon",
+  "color": "#3B82F6",
+  "route_prefix": "/my-app",
+  "renderer": "generic",
+  "min_role": "member",
+  "nav_items": [
+    {
+      "label": "Dashboard",
+      "path": "/my-app",
+      "icon": "layout-dashboard"
+    }
+  ]
+}
+```
+
+### Renderer Types
+
+- `generic` - Uses framework's generic app shell
+- `custom` - Full custom rendering (you control everything)
+- `none` - No UI (backend-only app)
+
+## Creating an App
+
+### 1. Scaffold the App
+
+```bash
+npx spine-cli app:create my-app
+```
+
+### 2. Define Types
+
+Edit `seed/types.json`:
+
+```json
+[
+  {
+    "kind": "item",
+    "slug": "my_entity",
+    "name": "My Entity",
+    "description": "Custom entity for my app",
+    "icon": "box",
+    "color": "#3B82F6",
+    "ownership": "tenant",
+    "is_active": true,
+    "design_schema": {
+      "scope": "account",
+      "fields": {
+        "title": {
+          "label": "Title",
+          "required": true,
+          "data_type": "text",
+          "permissions": {
+            "system_admin": ["read", "write"],
+            "member": ["read"]
+          }
+        }
+      },
+      "record_permissions": {
+        "member": ["read"],
+        "system_admin": ["create", "read", "update", "delete"]
+      }
+    }
+  }
+]
+```
+
+### 3. Create Pages
+
+```tsx
+// pages/Dashboard.tsx
+import { useItems } from '../../../.framework/src/hooks/useItems'
+
+export function Dashboard() {
+  const { items, loading } = useItems('my_entity')
+
+  if (loading) return <div>Loading...</div>
+
+  return (
+    <div>
+      <h1>My Entities</h1>
+      {items.map(item => (
+        <div key={item.id}>{item.data.title}</div>
+      ))}
+    </div>
+  )
+}
+```
+
+### 4. Wire Up Routes
+
+```tsx
+// index.tsx
+import { Routes, Route } from 'react-router-dom'
+import { Dashboard } from './pages/Dashboard'
+
+export default function MyApp() {
+  return (
+    <Routes>
+      <Route path="/" element={<Dashboard />} />
+    </Routes>
+  )
+}
+```
+
+### 5. Install & Test
+
+```bash
+# The CLI automatically installs to custom/apps/
+npx spine-cli app:install ./my-app
+
+# Apply seed data
+npx spine-cli seed --app=my-app
+
+# Restart dev server
+npm run dev
+```
+
+## Publishing Apps
+
+### Prepare for npm
+
+1. Update `package.json`:
+
+```json
+{
+  "name": "spine-framework-my-app",
+  "version": "1.0.0",
+  "files": [
+    "index.tsx",
+    "manifest.json",
+    "seed/",
+    "pages/",
+    "components/"
+  ],
+  "peerDependencies": {
+    "spine-framework": ">=0.1.0"
+  }
+}
+```
+
+2. Build and test:
+
+```bash
+npm run build
+npm run test
+```
+
+3. Publish:
+
+```bash
+npm publish --tag next
+```
+
+## App Installation API
+
+Programmatically install apps:
+
+```typescript
+import { installApp } from 'spine-framework/cli'
+
+await installApp({
+  source: 'npm',  // or 'local', 'git'
+  name: 'spine-framework-portal',
+  targetDir: './custom/apps/portal'
+})
+```
+
+## Best Practices
+
+### Do:
+- Keep apps self-contained
+- Use semantic versioning
+- Document your types and roles
+- Provide sensible defaults
+
+### Don't:
+- Modify framework core tables
+- Hardcode IDs or slugs that might conflict
+- Skip the manifest.json
+- Forget to handle errors gracefully
+
+## Example Apps
+
+- **portal** - Customer portal with courses, community, support
+- **cortex** - AI-powered CRM, support, knowledge base
+- **marketplace** - Extension marketplace for apps
+
+See `custom/apps/` for reference implementations.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,246 @@
+# Spine Framework Architecture
+
+## Overview
+
+Spine Framework is a modular, multi-tenant application platform built on:
+- **Frontend**: React + TypeScript + Tailwind CSS
+- **Backend**: Supabase (PostgreSQL + Auth + Realtime)
+- **Edge**: Netlify/Vercel Edge Functions
+- **Extension**: Custom workspace pattern
+
+## Core Principles
+
+1. **Framework-Agnostic Core** - Base platform knows nothing of specific apps
+2. **App-Defined Data** - Types, roles, and schemas are defined by apps
+3. **Custom Workspace** - Extensions live in `custom/` without modifying core
+4. **RLS-First Security** - Row Level Security enforces all permissions
+
+## System Layers
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      CUSTOM WORKSPACE                        │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐      │
+│  │   Apps   │ │Components│ │Functions │ │Migrations│      │
+│  └──────────┘ └──────────┘ └──────────┘ └──────────┘      │
+│  (Your code - safe to modify)                               │
+├─────────────────────────────────────────────────────────────┤
+│                    SPINE FRAMEWORK                          │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │              React + React Router                    │   │
+│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐     │   │
+│  │  │ App Router │  │   Auth     │  │    API     │     │   │
+│  │  └────────────┘  └────────────┘  └────────────┘     │   │
+│  └─────────────────────────────────────────────────────┘   │
+│  (Read-only - never modify)                                │
+├─────────────────────────────────────────────────────────────┤
+│                     SUPABASE PLATFORM                         │
+│  ┌────────────┐  ┌────────────┐  ┌────────────┐            │
+│  │ PostgreSQL │  │    Auth    │  │  Realtime  │            │
+│  └────────────┘  └────────────┘  └────────────┘            │
+│  (RLS policies enforce security)                            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Database Schema
+
+### Core Entities (spine-core)
+
+| Entity | Purpose | Scope |
+|--------|---------|-------|
+| `accounts` | Multi-tenant organizations | platform |
+| `people` | Users across accounts | platform |
+| `items` | Typed records (deals, tickets, posts) | account |
+| `threads` | Conversation threads | account |
+| `messages` | Individual messages | account |
+| `links` | Relationships between items | account |
+| `attachments` | File attachments | account |
+| `watchers` | Subscription/notification | account |
+
+### Metadata Entities
+
+| Entity | Purpose |
+|--------|---------|
+| `types` | Type definitions (item, account, link) |
+| `apps` | Installed apps registry |
+| `roles` | Role definitions and permissions |
+| `app_installations` | Per-account app instances |
+
+## Runtime Type System
+
+Types are stored in `types` table with JSON design schemas:
+
+```typescript
+interface Type {
+  slug: string           // Unique identifier
+  kind: 'item' | 'account' | 'link'
+  ownership: 'system' | 'tenant' | 'platform'
+  design_schema: {
+    scope: 'account' | 'platform' | 'system'
+    fields: Record<string, FieldDef>
+    record_permissions: Record<Role, Permission[]>
+    views: Record<string, ViewConfig>
+  }
+}
+```
+
+Fields are defined with:
+- Data type (text, number, boolean, select, date, datetime, json, textarea)
+- Validation rules
+- Permissions per role
+- UI configuration
+
+## App System
+
+Apps are runtime-loaded modules:
+
+### Registration
+1. App manifest stored in `apps` table
+2. Seed data in `custom/apps/<slug>/seed/`
+3. Code in `custom/apps/<slug>/` (pages, components, hooks)
+
+### Loading
+1. Framework queries `apps` table on boot
+2. Dynamic imports for `renderer='custom'` apps
+3. Generic shell for `renderer='generic'` apps
+
+### Routing
+- Apps define `route_prefix` in manifest
+- Framework's AppRouter generates routes dynamically
+- First app becomes default redirect (`/` → first app)
+
+## Security Model
+
+### RLS (Row Level Security)
+
+Every table has RLS policies checking:
+
+```sql
+-- Example: items table
+CREATE POLICY item_access ON items
+  FOR ALL USING (
+    -- System admin: full access
+    auth.role() = 'system_admin'
+    OR
+    -- Account member: account-scoped access
+    (account_id IN (
+      SELECT account_id FROM public.memberships
+      WHERE person_id = auth.uid()
+    ))
+  );
+```
+
+### Permission Hierarchy
+
+```
+system_admin → Full system access
+     ↓
+support → Cross-account support role
+     ↓
+member → Standard user (account-scoped)
+```
+
+### Field-Level Permissions
+
+```json
+{
+  "sensitive_field": {
+    "permissions": {
+      "system_admin": ["read", "write"],
+      "support": ["read"],
+      "member": []
+    }
+  }
+}
+```
+
+## Extension Points
+
+### Custom Apps
+Add to `custom/apps/<name>/`:
+- `index.tsx` - Entry point
+- `manifest.json` - Configuration
+- `seed/` - Types, roles, link-types
+- `pages/`, `components/`, `hooks/`
+
+### Custom Functions
+Add to `custom/functions/`:
+- Edge functions for API endpoints
+- Webhook handlers
+- Background jobs
+
+### Custom Migrations
+Add to `custom/migrations/`:
+- Database schema changes
+- Migration numbers continue from framework
+
+## Data Flow
+
+### Write Path
+1. UI calls `apiFetch()` with item data
+2. Edge function validates against type schema
+3. Supabase inserts with RLS check
+4. Realtime broadcasts change
+5. UI updates via subscription
+
+### Read Path
+1. UI calls `useItems(type)` hook
+2. Hook subscribes to realtime changes
+3. Initial fetch with account_id filter
+4. RLS ensures only accessible items returned
+
+## Build System
+
+### Assembly Process
+```
+1. Copy .framework/ → build/
+2. Copy custom/ → build/
+3. Merge app routes
+4. Generate type definitions
+5. Bundle with Vite
+```
+
+### Why Two-Level .devin?
+
+- **Root `.devin/`** - Framework usage (CLI, setup, troubleshooting)
+- **Custom `.devin/`** - Extension workflows (app install, custom functions)
+
+This separation keeps framework concerns distinct from extension concerns.
+
+## Deployment
+
+### Framework Package (npm)
+- `.framework/` - Core code
+- `docs/` - Documentation
+- `README.md` - Getting started
+
+### App Packages (npm)
+- `seed/` - Configuration data
+- `index.tsx` - Entry point
+- `manifest.json` - Metadata
+
+### Custom Workspace (project)
+- `custom/` - Project-specific code
+- `.env` - Environment config
+- `supabase/` - Database config
+
+## Performance
+
+### Optimizations
+- Lazy-loaded app bundles
+- Realtime subscriptions (no polling)
+- Pre-computed aggregations in `item_aggregations`
+- Funnel intelligence with materialized views
+
+### Scaling Considerations
+- Tenant-scoped queries use account_id indexes
+- RLS policies add ~5% query overhead
+- Edge functions cache auth tokens
+- Connection pooling via Supabase
+
+## Further Reading
+
+- [Installation Guide](INSTALL.md)
+- [App Development](APPS.md)
+- [API Reference](spine-core--api-reference.md)
+- [Developer Guides](dev-guides/)

package/docs/INSTALL.md

@@ -0,0 +1,155 @@
+# Spine Framework Installation Guide
+
+## Quick Start
+
+```bash
+# 1. Create a new project directory
+mkdir my-spine-app && cd my-spine-app
+
+# 2. Install the framework
+npm install spine-framework@next
+
+# 3. Initialize the project
+npx spine-cli init
+
+# 4. Start development
+npm run dev
+```
+
+## Prerequisites
+
+- Node.js 18+ and npm
+- PostgreSQL 14+ (local or hosted)
+- Supabase account (for hosted database/auth)
+
+## Installation Methods
+
+### Method 1: npm init (Recommended)
+
+```bash
+npm init spine-framework@next
+```
+
+This interactive wizard will:
+- Set up the project structure
+- Configure environment variables
+- Install default apps (optional)
+
+### Method 2: Manual Setup
+
+1. **Install the framework package:**
+   ```bash
+   npm install spine-framework@next
+   ```
+
+2. **Copy framework files:**
+   ```bash
+   cp -r node_modules/spine-framework/.framework ./.framework
+   cp -r node_modules/spine-framework/custom ./custom
+   ```
+
+3. **Configure environment:**
+   ```bash
+   cp .framework/.env.example .env
+   # Edit .env with your Supabase credentials
+   ```
+
+4. **Apply database migrations:**
+   ```bash
+   npx spine-cli db:migrate
+   ```
+
+5. **Start development:**
+   ```bash
+   npm run dev
+   ```
+
+## Installing Apps
+
+### Install from npm
+
+```bash
+npm install spine-framework-portal@next
+npx spine-cli app:install portal
+```
+
+### Install from local package
+
+```bash
+npx spine-cli app:install ./custom/npm/my-app
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `VITE_SUPABASE_URL` | Supabase project URL | Yes |
+| `VITE_SUPABASE_ANON_KEY` | Supabase anon key | Yes |
+| `VITE_SUPABASE_SERVICE_ROLE_KEY` | Service role key | For admin ops |
+| `VITE_API_BASE_URL` | Edge functions URL | Yes |
+
+### Database Setup
+
+1. Create a Supabase project
+2. Run migrations: `npx spine-cli db:migrate`
+3. Apply seed data: `npx spine-cli db:seed`
+
+## Project Structure
+
+```
+my-spine-app/
+├── .framework/          # Framework code (read-only)
+│   ├── src/
+│   ├── migrations/
+│   └── scripts/
+├── custom/             # Your custom code
+│   ├── apps/
+│   ├── components/
+│   ├── functions/
+│   └── migrations/
+├── docs/               # Documentation
+├── supabase/           # Supabase config
+├── .env               # Environment variables
+└── package.json
+```
+
+## Verification
+
+After installation, verify everything works:
+
+```bash
+# Check CLI
+npx spine-cli --version
+
+# Check database connection
+npx spine-cli db:status
+
+# Run health check
+npm run health-check
+```
+
+## Troubleshooting
+
+### Database Connection Issues
+
+- Verify `VITE_SUPABASE_URL` is correct
+- Check that migrations have been applied
+- Ensure RLS policies are enabled
+
+### Build Errors
+
+- Clear `node_modules` and reinstall
+- Run `npm run build:clean` to reset build cache
+
+### App Installation Failures
+
+- Check that the app package is compatible
+- Verify no conflicting route prefixes exist
+
+## Next Steps
+
+- [Create your first app](dev-guides/01-create-an-app.md)
+- [Read the architecture overview](ARCHITECTURE.md)
+- [Explore the API reference](spine-core--api-reference.md)