spine-framework 0.1.0

package/.framework/docs/apis/runtime.md

@@ -0,0 +1,537 @@
+# Runtime APIs
+
+## Overview
+
+Runtime APIs handle application runtime operations including threads, messages, attachments, watchers, links, and access control. These endpoints support real-time collaboration and system operations.
+
+## Threads API
+
+**Endpoint:** `/.netlify/functions/threads`
+
+**Domain:** runtime (conversation threads)
+
+**Operations:**
+- `GET /functions/threads` - List threads
+- `GET /functions/threads?id=uuid` - Get single thread
+- `POST /functions/threads` - Create thread
+- `PATCH /functions/threads?id=uuid` - Update thread
+- `DELETE /functions/threads?id=uuid` - Soft delete thread
+
+**Authentication:**
+- Reads: Account-scoped with field-level permission filtering
+- Mutations: Auth required with schema-driven permissions
+
+**Authorization:**
+- Mixed Surface Operations: User messages (first surface), AI agent messages (second surface)
+- Thread access: First surface (user permissions)
+- Field filtering applied based on type.schema
+
+**Audit Trail:**
+- System operations record ctx.triggeredBy
+- User operations record ctx.personId
+- System admin actions are logged but bypass checks
+
+**Request/Response:**
+
+### List Threads
+```typescript
+// Request
+GET /functions/threads?page=1&itemsPerPage=20&search=keyword&person_id=uuid
+
+// Response
+{
+  data: [
+    {
+      id: string,
+      person_id: string,
+      title: string,
+      description?: string,
+      thread_type: string,
+      metadata?: object,
+      is_active: true,
+      created_at: string,
+      updated_at: string,
+      created_by: string,
+      account_id: string,
+      person: {
+        id: string,
+        first_name: string,
+        last_name: string
+      }
+    }
+  ]
+}
+```
+
+### Create Thread
+```typescript
+// Request
+POST /functions/threads
+{
+  person_id: string,   // required
+  title: string,       // required
+  description?: string,
+  thread_type: string, // required
+  metadata?: object
+}
+
+// Response
+{
+  data: { /* created thread */ }
+}
+```
+
+## Messages API
+
+**Endpoint:** `/.netlify/functions/messages`
+
+**Domain:** runtime (thread messages)
+
+**Operations:**
+- `GET /functions/messages` - List messages
+- `GET /functions/messages?id=uuid` - Get single message
+- `POST /functions/messages` - Create message
+- `PATCH /functions/messages?id=uuid` - Update message
+- `DELETE /functions/messages?id=uuid` - Soft delete message
+
+**Authentication:**
+- Reads: Account-scoped
+- Mutations: Auth required
+
+**Request/Response:**
+
+### List Messages
+```typescript
+// Request
+GET /functions/messages?thread_id=uuid&page=1&itemsPerPage=50
+
+// Response
+{
+  data: [
+    {
+      id: string,
+      thread_id: string,
+      person_id: string,
+      content: string,
+      message_type: string,
+      metadata?: object,
+      is_active: true,
+      created_at: string,
+      updated_at: string,
+      created_by: string,
+      account_id: string,
+      person: {
+        id: string,
+        first_name: string,
+        last_name: string
+      },
+      thread: {
+        id: string,
+        title: string
+      }
+    }
+  ]
+}
+```
+
+### Create Message
+```typescript
+// Request
+POST /functions/messages
+{
+  thread_id: string,   // required
+  content: string,     // required
+  message_type: string, // required
+  metadata?: object
+}
+
+// Response
+{
+  data: { /* created message */ }
+}
+```
+
+## Attachments API
+
+**Endpoint:** `/.netlify/functions/attachments`
+
+**Domain:** runtime (file attachments)
+
+**Operations:**
+- `GET /functions/attachments` - List attachments
+- `GET /functions/attachments?id=uuid` - Get single attachment
+- `POST /functions/attachments` - Create attachment
+- `PATCH /functions/attachments?id=uuid` - Update attachment
+- `DELETE /functions/attachments?id=uuid` - Soft delete attachment
+
+**Authentication:**
+- Reads: Account-scoped
+- Mutations: Auth required
+
+**Request/Response:**
+
+### List Attachments
+```typescript
+// Request
+GET /functions/attachments?page=1&itemsPerPage=20&thread_id=uuid
+
+// Response
+{
+  data: [
+    {
+      id: string,
+      person_id: string,
+      thread_id?: string,
+      filename: string,
+      file_type: string,
+      file_size: number,
+      file_url: string,
+      metadata?: object,
+      is_active: true,
+      created_at: string,
+      updated_at: string,
+      created_by: string,
+      account_id: string,
+      person: {
+        id: string,
+        first_name: string,
+        last_name: string
+      }
+    }
+  ]
+}
+```
+
+### Create Attachment
+```typescript
+// Request
+POST /functions/attachments
+{
+  person_id: string,   // required
+  thread_id?: string,
+  filename: string,    // required
+  file_type: string,   // required
+  file_size: number,   // required
+  file_url: string,    // required
+  metadata?: object
+}
+
+// Response
+{
+  data: { /* created attachment */ }
+}
+```
+
+## Watchers API
+
+**Endpoint:** `/.netlify/functions/watchers`
+
+**Domain:** runtime (entity subscriptions)
+
+**Operations:**
+- `GET /functions/watchers` - List watchers
+- `GET /functions/watchers?id=uuid` - Get single watcher
+- `POST /functions/watchers` - Create watcher
+- `DELETE /functions/watchers?id=uuid` - Delete watcher (hard delete)
+
+**Authentication:**
+- Reads: Account-scoped
+- Mutations: Auth required
+
+**Request/Response:**
+
+### List Watchers
+```typescript
+// Request
+GET /functions/watchers?page=1&itemsPerPage=20&person_id=uuid&entity_type=string
+
+// Response
+{
+  data: [
+    {
+      id: string,
+      person_id: string,
+      entity_type: string,
+      entity_id: string,
+      watch_type: string,
+      created_at: string,
+      person: {
+        id: string,
+        first_name: string,
+        last_name: string
+      }
+    }
+  ]
+}
+```
+
+### Create Watcher
+```typescript
+// Request
+POST /functions/watchers
+{
+  person_id: string,    // required
+  entity_type: string,  // required
+  entity_id: string,    // required
+  watch_type: string    // required
+}
+
+// Response
+{
+  data: { /* created watcher */ }
+}
+```
+
+## Links API
+
+**Endpoint:** `/.netlify/functions/links`
+
+**Domain:** runtime (polymorphic entity relationships)
+
+**Operations:**
+- `GET /functions/links` - List links
+- `GET /functions/links?id=uuid` - Get single link
+- `POST /functions/links` - Create link
+- `DELETE /functions/links?id=uuid` - Delete link (hard delete)
+
+**Authentication:**
+- Reads: Account-scoped
+- Mutations: Auth required
+
+**Request/Response:**
+
+### List Links
+```typescript
+// Request
+GET /functions/links?page=1&itemsPerPage=20&source_type=string&source_id=uuid
+
+// Response
+{
+  data: [
+    {
+      id: string,
+      link_type_id: string,
+      person_id: string,
+      source_type: string,
+      source_id: string,
+      target_type: string,
+      target_id: string,
+      metadata?: object,
+      created_at: string,
+      created_by: string,
+      account_id: string,
+      link_type: {
+        id: string,
+        name: string,
+        forward_label: string,
+        reverse_label: string
+      },
+      person: {
+        id: string,
+        first_name: string,
+        last_name: string
+      }
+    }
+  ]
+}
+```
+
+### Create Link
+```typescript
+// Request
+POST /functions/links
+{
+  link_type_id: string, // required
+  source_type: string,  // required
+  source_id: string,    // required
+  target_type: string,  // required
+  target_id: string,    // required
+  metadata?: object
+}
+
+// Response
+{
+  data: { /* created link */ }
+}
+```
+
+## Link Types API
+
+**Endpoint:** `/.netlify/functions/link-types`
+
+**Domain:** runtime (link type definitions)
+
+**Operations:**
+- `GET /functions/link-types` - List link types
+- `GET /functions/link-types?id=uuid` - Get single link type
+- `POST /functions/link-types` - Create link type
+- `PATCH /functions/link-types?id=uuid` - Update link type
+- `DELETE /functions/link-types?id=uuid` - Soft delete link type
+
+**Authentication:**
+- Reads: Public
+- Mutations: Admin auth required
+
+**Request/Response:**
+
+### List Link Types
+```typescript
+// Request
+GET /functions/link-types?page=1&itemsPerPage=20&app_id=uuid
+
+// Response
+{
+  data: [
+    {
+      id: string,
+      app_id: string,
+      name: string,
+      description?: string,
+      forward_label: string,
+      reverse_label: string,
+      source_types: string[],
+      target_types: string[],
+      is_active: true,
+      created_at: string,
+      updated_at: string,
+      created_by: string
+    }
+  ]
+}
+```
+
+### Create Link Type
+```typescript
+// Request
+POST /functions/link-types
+{
+  app_id: string,           // required
+  name: string,             // required
+  description?: string,
+  forward_label: string,    // required
+  reverse_label: string,    // required
+  source_types: string[],   // required
+  target_types: string[]    // required
+}
+
+// Response
+{
+  data: { /* created link type */ }
+}
+```
+
+## Access Control APIs
+
+### People-Accounts API
+
+**Endpoint:** `/.netlify/functions/people-accounts`
+
+**Domain:** runtime (people-accounts junction)
+
+**Operations:**
+- `GET /functions/people-accounts` - List people-accounts relationships
+- `POST /functions/people-accounts` - Add person to account
+- `DELETE /functions/people-accounts?id=uuid` - Remove person from account
+
+**Authentication:**
+- Reads: Account-scoped
+- Mutations: Auth required
+
+### People-Roles API
+
+**Endpoint:** `/.netlify/functions/people-roles`
+
+**Domain:** runtime (people-roles junction)
+
+**Operations:**
+- `GET /functions/people-roles` - List people-roles relationships
+- `POST /functions/people-roles` - Assign role to person
+- `DELETE /functions/people-roles?id=uuid` - Remove role from person
+
+**Authentication:**
+- Reads: Account-scoped
+- Mutations: Auth required
+
+### Account Nodes API
+
+**Endpoint:** `/.netlify/functions/account-nodes`
+
+**Domain:** internal (account hierarchy traversal)
+
+**Operations:**
+- `GET /functions/account-nodes?id=uuid&include=ancestors|descendants` - Get account hierarchy
+
+**Authentication:**
+- Reads: Account-scoped
+- Uses RPC functions for hierarchy traversal
+
+## System APIs
+
+### Logs API
+
+**Endpoint:** `/.netlify/functions/logs`
+
+**Domain:** internal (system logs)
+
+**Operations:**
+- `GET /functions/logs` - List system logs
+- `GET /functions/logs?id=uuid` - Get single log entry
+
+**Authentication:**
+- Reads: Admin auth required
+
+### Pipeline Executions API
+
+**Endpoint:** `/.netlify/functions/pipeline-executions`
+
+**Domain:** runtime (pipeline execution history)
+
+**Operations:**
+- `GET /functions/pipeline-executions` - List pipeline executions
+- `GET /functions/pipeline-executions?id=uuid` - Get single execution
+
+**Authentication:**
+- Reads: Account-scoped
+
+## Common Features
+
+### Account Scoping
+- All runtime endpoints respect account boundaries
+- Account context via `X-Account-Id` header
+- System admin can bypass scoping
+
+### Real-time Operations
+- Support for WebSocket notifications
+- Event-driven updates
+- Optimistic locking for concurrent updates
+
+### Audit Trail
+- All mutations create audit logs
+- Immutable history preservation
+- Person attribution for all changes
+
+### Error Handling
+```typescript
+// Success Response
+{
+  data: T
+}
+
+// Error Response
+{
+  error: "Human readable message",
+  code?: "ERROR_CODE"
+}
+
+// Validation Error
+{
+  errors: {
+    field: "field-specific error"
+  }
+}
+```
+
+### Pagination
+- Default: `page=1`, `itemsPerPage=20`
+- Higher limits for message threads (50)
+- Supports filtering and search

package/.framework/docs/assembly-launch-guide.md

@@ -0,0 +1,138 @@
+# Spine v2 Assembly & Launch Process Guide
+
+## Source Directories vs Served Directories
+
+**Edit here (source of truth):**
+- `v2-core/src/` — core frontend (all apps, components, hooks, pages)
+- `v2-core/functions/` — core Netlify functions
+- `v2-custom/src/` — custom frontend overrides (`custom_*.tsx` files only)
+- `v2-custom/functions/` — custom function overrides (`custom_*.ts` files only)
+
+**Never edit these (generated/assembled output):**
+- `functions/` (repo root) — assembled and served by Netlify CLI
+- `src/v2-assembled/` — assembled for prod builds only (not used in dev)
+
+---
+
+## Dev vs Prod
+
+### Dev (`netlify dev`)
+
+**Frontend** — not assembled. Vite serves `v2-core/` directly as its root:
+```
+vite.config.ts → root: 'v2-core'
+```
+`v2-custom/src/` is reachable via `server.fs.allow`, so `CustomAppLoader.tsx` loads
+full custom app trees (e.g. `v2-custom/src/apps/customer-portal/`) via `import.meta.glob`
+at runtime — no file copying needed for frontend in dev.
+
+**Functions** — must be assembled. Netlify CLI serves functions from `functions/` at the
+repo root (`netlify.toml [functions] directory = "functions"`). Run `npm run assemble:v2`
+before starting dev whenever you add or change a function.
+
+### Prod (`npm run build`)
+
+`package.json` runs full assembly before the Vite build:
+```
+prebuild → npm run assemble:v2 && npm run verify
+build    → tsc -b && vite build --config vite.config.ts
+```
+
+---
+
+## Assembly: What `npm run assemble:v2` Does
+
+Calls `scripts/assemble-v2.sh`, which runs these three steps **in order**:
+
+**Step 1 — Custom overlay** (`scripts/assemble-v2-custom.sh`)
+- Finds all `custom_*.tsx` files under `v2-custom/src/` → flat-copies into `v2-core/src/`
+- Finds all `custom_*.ts` files under `v2-custom/functions/` → flat-copies into `v2-core/functions/`
+- Files NOT named `custom_*` are ignored by assembly (but full app trees in `v2-custom/src/apps/`
+  are still accessible to Vite dev server via `fs.allow`)
+
+**Step 2 — Functions** 
+- Wipes `functions/` (repo root)
+- Copies `v2-core/functions/` → `functions/` (now includes any custom_*.ts from step 1)
+
+**Step 3 — Frontend (prod only)**
+- Wipes `src/v2-assembled/`
+- Copies `v2-core/src/` → `src/v2-assembled/` (now includes any custom_*.tsx from step 1)
+- Fixes `index.html` script path: `/src/main.tsx` → `./main.tsx`
+
+The order matters: custom files must land in `v2-core/` **before** the root copy runs,
+so they are included in the output in a single pass.
+
+---
+
+## Standard Dev Launch
+
+```bash
+# First time, or after adding/modifying any function:
+npm run assemble:v2
+
+# Start the dev server:
+netlify dev
+```
+
+**What `netlify dev` does:**
+1. Runs `scripts/netlify-dev-wrapper.sh` (via `netlify.toml [dev].command`)
+2. Wrapper fires Vite directly: `exec node_modules/.bin/vite --config vite.config.ts`
+3. Vite serves `v2-core/` on port 3001 with HMR
+4. Netlify CLI proxies port 8888 → 3001 and serves `functions/` (repo root)
+
+---
+
+## Process Management
+
+```bash
+# Check ports
+lsof -i:3001   # Vite
+lsof -i:8888   # Netlify proxy
+
+# Kill both
+pkill -f vite && pkill -f netlify
+
+# Clean restart
+pkill -f vite && pkill -f netlify && sleep 1 && netlify dev
+```
+
+---
+
+## Troubleshooting
+
+### Function returning 404
+`functions/` (repo root) is stale or missing the new function. Reassemble then restart:
+```bash
+npm run assemble:v2
+# restart netlify dev
+```
+
+### `custom_*.tsx` override not taking effect
+Reassemble so the file lands in `v2-core/src/`:
+```bash
+npm run assemble:v2
+```
+Vite HMR picks it up automatically if the dev server is already running.
+
+### Vite never binds to port 3001
+`npm run dev` and `npx vite` silently hang under Netlify CLI. The wrapper must use the
+direct binary. Verify `scripts/netlify-dev-wrapper.sh` contains:
+```bash
+exec "$PROJECT_ROOT/node_modules/.bin/vite" --config "$PROJECT_ROOT/vite.config.ts"
+```
+Never change this to `npm run dev` or `npx vite`.
+
+---
+
+## Key Files
+
+| File | Role |
+|---|---|
+| `scripts/assemble-v2.sh` | Full assembly orchestrator — runs steps 1→2→3 |
+| `scripts/assemble-v2-custom.sh` | Step 1: overlays `custom_*` files into `v2-core/` |
+| `scripts/netlify-dev-wrapper.sh` | Dev entry point — fires Vite binary directly |
+| `netlify.toml` | `[dev].command` → wrapper; `[functions] directory = "functions"` |
+| `vite.config.ts` | `root: 'v2-core'`; `fs.allow` includes `v2-custom`; `@core`/`@custom` aliases |
+| `v2-core/src/components/CustomAppLoader.tsx` | Loads `v2-custom/src/apps/*/index.tsx` via `import.meta.glob` |
+| `functions/` (repo root) | Assembled output — served by Netlify CLI; never edit directly |
+| `src/v2-assembled/` | Assembled output — prod build only; never edit directly |