spine-framework 0.4.4 → 0.5.0-rc.4

package/.framework/docs/api-governance.md

@@ -1,146 +0,0 @@
-# Spine v2 API Governance Checklist
-
-## Universal API Ground Rules
-
-### Response Format Standards
-- **Success - List**: `{ data: [...], pagination?: { page, totalPages, totalItems, itemsPerPage } }`
-- **Success - Single/Create/Update**: `{ data: {...} }`
-- **Error**: `{ error: "Human readable message", code?: "ERROR_CODE" }`
-- **Validation Error**: `{ errors: { field: "field-specific error" } }`
-
-### Authentication & Context
-- All APIs require valid session token (`Authorization: Bearer`)
-- Account context via `X-Account-Id` header
-- System admin can bypass account scoping
-- Use `requireAuth` middleware for mutations
-- Use `requireTenant` for account-scoped reads
-
-### HTTP Patterns
-- **GET /resource** - List (with query parameters)
-- **GET /resource?id=uuid** - Single
-- **POST /resource** - Create
-- **PATCH /resource?id=uuid** - Update
-- **DELETE /resource?id=uuid** - Soft delete
-
-### Query Parameter Standards
-- `page`, `itemsPerPage` - Pagination
-- `search` - Text search
-- `sort`, `direction` - Sorting
-- `field=value` - Filtering
-- `include=relation1,relation2` - Related data
-
-### Data Constraints
-- APIs return data only, never styling/UI components
-- All endpoints enforce role-based permissions
-- DELETE = soft delete (`is_active=false`), never hard deletes
-- All mutations must emit audit logs via `emitLog`
-
-## Permission Model
-
-### Single Source of Truth
-- type.schema defines what roles can do
-- v2.people_accounts + v2.people_roles define who has roles
-- No parallel permission systems
-
-### Enforcement Points
-- All first-surface APIs use shared permission resolver
-- Field filtering on reads
-- Field validation on writes
-- Multi-role merge: highest effective permission wins
-
-### System Admin Override
-- Complete bypass of runtime restrictions
-- Audit logs preserved
-- Intended for admin operations only
-
-### Error Handling
-- Use consistent error format with descriptive messages
-- Include error codes for programmatic handling
-- Log errors appropriately with context
-- Return 4xx for client errors, 5xx for server errors
-
-### Pagination
-- Default `page=1`, `itemsPerPage=20`
-- Return total count for client-side calculations
-- Support `search` and filtering in pagination queries
-- Use `range()` for efficient DB queries
-
-### Soft Delete Semantics
-- Never use `DELETE FROM` statements
-- Always set `is_active=false` with `updated_at`
-- Filter active records with `is_active=true` by default
-- Preserve audit trail before soft delete
-
-### Database Constraints
-- Use `public` schema only
-- All queries must use `db.from('public.table')`
-- Validate field names against actual schema
-- Use parameterized queries to prevent injection
-
-### Role Boundaries
-- **Config endpoints** (`admin/configs/*`): admin-only mutations
-- **Data endpoints** (`admin/data/*`): permissions by role/type schema
-- **Runtime endpoints**: account-scoped with appropriate role checks
-- **Internal endpoints**: system-only or service-to-service
-
-## Code Patterns
-
-### Handler Structure
-```typescript
-export const handler = createHandler(async (ctx, body) => {
-  const method = ctx.query?.method || 'GET'
-  switch (method) {
-    case 'GET': return await list(ctx, body)
-    case 'POST': return await create(ctx, body)
-    case 'PATCH': return await update(ctx, body)
-    case 'DELETE': return await remove(ctx, body)
-    default: throw new Error(`Unsupported method: ${method}`)
-  }
-})
-```
-
-### Auth Patterns
-```typescript
-// Public reads
-export const list = createHandler(async (ctx, body) => {
-  // Account-scoped by default
-})
-
-// Authenticated mutations
-export const create = requireAuth(createHandler(async (ctx, body) => {
-  // Requires valid session
-}))
-```
-
-### Audit Logging
-```typescript
-await emitLog(ctx, 'entity.created', 
-  { type: 'entity', id: data.id }, 
-  { after: data }
-)
-```
-
-## Documentation Requirements
-
-Each endpoint must include JSDoc comments with:
-- Purpose and domain (data/config/runtime/internal)
-- Auth requirements
-- Account scoping rules
-- Request parameters/body contract
-- Response shape
-- Soft delete behavior
-- v2 table/RPC dependencies
-
-## Review Checklist
-
-- [ ] Response format matches standard
-- [ ] Auth middleware applied appropriately
-- [ ] Account context handled correctly
-- [ ] Soft delete implemented (no hard deletes)
-- [ ] Audit logs emitted for mutations
-- [ ] Error handling consistent
-- [ ] Pagination implemented for lists
-- [ ] Query parameters validated
-- [ ] v2 schema only (no public references)
-- [ ] Role boundaries enforced
-- [ ] Inline documentation complete

package/.framework/docs/api-testing-results.md

@@ -1,212 +0,0 @@
-# API Testing Results
-
-## Test Methodology
-- **Server**: Local Netlify dev server (http://localhost:8888)
-- **Date**: April 7, 2026
-- **Test Pattern**: List, Create, Get Single, Update, Delete for each endpoint
-- **Authentication**: Tested with and without auth headers
-- **Account Context**: Tested with X-Account-Id header
-
-## Data Management APIs (admin/data/*)
-
-### accounts.ts
-- **GET List**: SUCCESS - Returns 3 accounts with type info
-- **POST Create**: SUCCESS - Creates account (no auth required)
-- **GET Single**: SUCCESS - Returns account with type info
-- **PATCH Update**: SUCCESS - Updates account
-- **DELETE Soft Delete**: SUCCESS - Sets is_active=false
-- **Status**: FULLY FUNCTIONAL
-
-### people.ts
-- **GET List**: SUCCESS - Returns 1 person with type info
-- **POST Create**: SUCCESS - Creates person with X-Account-Id header
-- **GET Single**: SUCCESS - Returns person with type info
-- **PATCH Update**: SUCCESS - Updates person
-- **DELETE Soft Delete**: SUCCESS - Sets is_active=false
-- **Status**: FULLY FUNCTIONAL (requires account context)
-
-### items.ts
-- **GET List**: FAIL - "Account context required" without X-Account-Id
-- **POST Create**: SUCCESS - Creates item with X-Account-Id header
-- **GET Single**: SUCCESS - Returns item with type info
-- **PATCH Update**: SUCCESS - Updates item
-- **DELETE Soft Delete**: SUCCESS - Sets is_active=false
-- **Status**: FUNCTIONAL (requires account context)
-
-## Configuration APIs (admin/configs/*)
-
-### types.ts
-- **GET List**: SUCCESS - Returns 6 system types (account, item, person)
-- **POST Create**: FAIL - "Invalid token specified" without proper auth
-- **GET Single**: SUCCESS - Returns type with schema
-- **PATCH Update**: FAIL - Requires admin auth
-- **DELETE Soft Delete**: FAIL - Requires admin auth
-- **Status**: READ-ONLY without auth, mutations need admin auth
-
-### apps.ts
-- **GET List**: FAIL - "Account context required" without X-Account-Id
-- **POST Create**: FAIL - Requires admin auth
-- **GET Single**: SUCCESS - Returns app with nav items
-- **PATCH Update**: FAIL - Requires admin auth
-- **DELETE Soft Delete**: FAIL - Requires admin auth
-- **Status**: READ-ONLY without account context, mutations need admin auth
-
-### pipelines.ts
-- **GET List**: FAIL - "Account context required" without X-Account-Id
-- **POST Create**: FAIL - Requires admin auth
-- **GET Single**: SUCCESS - Returns pipeline with definition
-- **PATCH Update**: FAIL - Requires admin auth
-- **DELETE Soft Delete**: FAIL - Requires admin auth
-- **Status**: READ-ONLY without account context, mutations need admin auth
-
-### triggers.ts
-- **GET List**: FAIL - "Account context required" without X-Account-Id
-- **POST Create**: FAIL - Requires admin auth
-- **GET Single**: SUCCESS - Returns trigger with config
-- **PATCH Update**: FAIL - Requires admin auth
-- **DELETE Soft Delete**: FAIL - Requires admin auth
-- **Status**: READ-ONLY without account context, mutations need admin auth
-
-### ai-agents.ts
-- **GET List**: FAIL - "Account context required" without X-Account-Id
-- **POST Create**: FAIL - Requires admin auth
-- **GET Single**: SUCCESS - Returns AI agent with config
-- **PATCH Update**: FAIL - Requires admin auth
-- **DELETE Soft Delete**: FAIL - Requires admin auth
-- **Status**: READ-ONLY without account context, mutations need admin auth
-
-### embeddings.ts
-- **GET List**: FAIL - "Account context required" without X-Account-Id
-- **POST Create**: FAIL - Requires admin auth
-- **GET Single**: SUCCESS - Returns embedding with model info
-- **PATCH Update**: FAIL - Requires admin auth
-- **DELETE Soft Delete**: FAIL - Requires admin auth
-- **Status**: READ-ONLY without account context, mutations need admin auth
-
-### timers.ts
-- **GET List**: FAIL - "Account context required" without X-Account-Id
-- **POST Create**: FAIL - Requires admin auth
-- **GET Single**: SUCCESS - Returns timer with schedule config
-- **PATCH Update**: FAIL - Requires admin auth
-- **DELETE Soft Delete**: FAIL - Requires admin auth
-- **Status**: READ-ONLY without account context, mutations need admin auth
-
-### integrations.ts
-- **GET List**: FAIL - "Account context required" without X-Account-Id
-- **POST Create**: FAIL - Requires admin auth
-- **GET Single**: SUCCESS - Returns integration with config
-- **PATCH Update**: FAIL - Requires admin auth
-- **DELETE Soft Delete**: FAIL - Requires admin auth
-- **Status**: READ-ONLY without account context, mutations need admin auth
-
-### roles.ts
-- **GET List**: SUCCESS - Returns system roles
-- **POST Create**: FAIL - Requires admin auth
-- **GET Single**: SUCCESS - Returns role with permissions
-- **PATCH Update**: FAIL - Requires admin auth
-- **DELETE Soft Delete**: FAIL - Requires admin auth
-- **Status**: READ-ONLY without auth, mutations need admin auth
-
-## Runtime APIs
-
-### threads.ts
-- **GET List**: SUCCESS - Returns threads with person info
-- **POST Create**: SUCCESS - Creates thread
-- **GET Single**: SUCCESS - Returns thread with person
-- **PATCH Update**: SUCCESS - Updates thread
-- **DELETE Soft Delete**: SUCCESS - Sets is_active=false
-- **Status**: FULLY FUNCTIONAL
-
-### messages.ts
-- **GET List**: SUCCESS - Returns messages with thread/person info
-- **POST Create**: SUCCESS - Creates message
-- **GET Single**: SUCCESS - Returns message with thread/person
-- **PATCH Update**: SUCCESS - Updates message
-- **DELETE Soft Delete**: SUCCESS - Sets is_active=false
-- **Status**: FULLY FUNCTIONAL
-
-### attachments.ts
-- **GET List**: SUCCESS - Returns attachments with person info
-- **POST Create**: SUCCESS - Creates attachment
-- **GET Single**: SUCCESS - Returns attachment with person
-- **PATCH Update**: SUCCESS - Updates attachment
-- **DELETE Soft Delete**: SUCCESS - Sets is_active=false
-- **Status**: FULLY FUNCTIONAL
-
-### watchers.ts
-- **GET List**: SUCCESS - Returns watchers with person info
-- **POST Create**: SUCCESS - Creates watcher
-- **GET Single**: SUCCESS - Returns watcher
-- **DELETE Hard Delete**: SUCCESS - Removes watcher
-- **Status**: FULLY FUNCTIONAL
-
-### links.ts
-- **GET List**: SUCCESS - Returns links with link_type/person info
-- **POST Create**: SUCCESS - Creates link
-- **GET Single**: SUCCESS - Returns link with type/person
-- **DELETE Hard Delete**: SUCCESS - Removes link
-- **Status**: FULLY FUNCTIONAL
-
-### link-types.ts
-- **GET List**: SUCCESS - Returns link types
-- **POST Create**: FAIL - Requires admin auth
-- **GET Single**: SUCCESS - Returns link type with app info
-- **PATCH Update**: FAIL - Requires admin auth
-- **DELETE Soft Delete**: FAIL - Requires admin auth
-- **Status**: READ-ONLY without auth, mutations need admin auth
-
-## Access Control APIs
-
-### people-accounts.ts
-- **GET List**: SUCCESS - Returns people-accounts relationships
-- **POST Create**: SUCCESS - Adds person to account
-- **DELETE Remove**: SUCCESS - Removes person from account
-- **Status**: FULLY FUNCTIONAL
-
-### people-roles.ts
-- **GET List**: SUCCESS - Returns people-roles relationships
-- **POST Create**: SUCCESS - Assigns role to person
-- **DELETE Remove**: SUCCESS - Removes role from person
-- **Status**: FULLY FUNCTIONAL
-
-### account-nodes.ts
-- **GET List**: SUCCESS - Returns account hierarchy via RPC
-- **Status**: FULLY FUNCTIONAL
-
-## System APIs
-
-### logs.ts
-- **GET List**: SUCCESS - Returns system logs
-- **GET Single**: SUCCESS - Returns single log entry
-- **Status**: FULLY FUNCTIONAL
-
-### pipeline-executions.ts
-- **GET List**: SUCCESS - Returns pipeline executions
-- **GET Single**: SUCCESS - Returns single execution
-- **Status**: FULLY FUNCTIONAL
-
-## Summary
-
-### Fully Functional (11 endpoints)
-- accounts, people, items (with context), threads, messages, attachments, watchers, links, people-accounts, people-roles, account-nodes, logs, pipeline-executions
-
-### Read-Only Without Auth (8 endpoints)
-- types, apps, pipelines, triggers, ai-agents, embeddings, timers, integrations, roles, link-types
-
-### Issues Identified
-1. **Authentication Required**: Config mutations need proper admin auth tokens
-2. **Account Context**: Most config endpoints require X-Account-Id header
-3. **Items Endpoint**: Requires account context for all operations
-4. **Auth Validation**: Proper token validation needed for admin operations
-
-### Recommendations
-1. Implement proper admin authentication for config mutations
-2. Add account context validation for config reads
-3. Test with valid admin session tokens
-4. Verify role-based access control enforcement
-
-## Test Data Created
-- Test account: "Test Account for API Testing"
-- Test person: "Test Person" with timestamped email
-- Test items: Created with account context
-- All test data properly soft deleted after testing

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 |