spine-framework 0.2.1 → 1.0.0

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

@@ -1,537 +0,0 @@
-# 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

@@ -1,138 +0,0 @@
-# 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 |