spine-framework 0.2.1 → 1.0.0

package/.framework/docs/API.md

@@ -1,384 +0,0 @@
-# Spine Core Public API
-
-**Stability:** Evolving (pre-1.0)  
-**Version:** 0.1.0  
-
-This document describes the stable API surface for building on Spine Core. These exports from `@core/_shared` are intended for use by custom code.
-
----
-
-## Stability Levels
-
-- **Stable** — Safe to use, won't change in minor versions
-- **Evolving** — May change, backward compatibility maintained when possible
-- **Internal** — Not for external use, subject to breaking changes
-
----
-
-## Core Context & Authentication
-
-### `createHandler`
-**Stability:** Stable
-
-Creates a type-safe API handler with built-in authentication, authorization, and logging.
-
-```typescript
-import { createHandler } from '@core/_shared'
-
-export const handler = createHandler(async (event, ctx) => {
-  // ctx.db is RLS-scoped to the authenticated user
-  // ctx.principal contains user identity, roles, permissions
-  return { data: await ctx.db.from('items').select('*') }
-})
-```
-
-**Context Object:**
-```typescript
-interface CoreContext {
-  db: SupabaseClient        // RLS-scoped database client
-  principal: Principal     // Authenticated user info
-  logger: Logger           // Structured logging
-}
-```
-
----
-
-### `resolvePrincipal`
-**Stability:** Stable
-
-Resolves an API key or JWT to a principal with permissions.
-
-```typescript
-import { resolvePrincipal } from '@core/_shared'
-
-const principal = await resolvePrincipal(apiKey, adminDb)
-// Returns: { id, account_id, roles, permissions, ... }
-```
-
----
-
-## Webhook Registry
-
-### `resolveHandler`
-**Stability:** Evolving
-
-Dynamically loads a webhook handler by name from the registry.
-
-```typescript
-import { resolveHandler } from '@core/_shared'
-
-const handler = await resolveHandler('cortex-webhook')
-if (handler) {
-  await handler(event, context)
-}
-```
-
-**Usage in custom code:** See `registerWebhookHandler` below.
-
----
-
-### `registerWebhookHandler`
-**Stability:** Evolving
-
-Self-register a custom webhook handler at runtime.
-
-```typescript
-import { registerWebhookHandler } from '@core/_shared'
-
-await registerWebhookHandler({
-  name: 'my-handler',           // Unique identifier
-  functionName: 'custom_my-handler',  // Netlify function name
-  description: 'Handles X events',
-  events: ['item.created', 'user.updated']
-})
-```
-
-**Benefits:**
-- No core code changes to add handlers
-- Self-contained registration
-- Runtime discovery
-
----
-
-## Pipeline Engine
-
-### `runPipeline`
-**Stability:** Evolving
-
-Execute a pipeline with the given input and context.
-
-```typescript
-import { runPipeline } from '@core/_shared'
-
-const result = await runPipeline(pipelineId, {
-  item_id: itemId,
-  account_id: accountId,
-  user_id: userId
-}, context)
-```
-
----
-
-## Database
-
-### `adminDb`
-**Stability:** Stable
-
-Service-role database client (bypasses RLS). Use with caution.
-
-```typescript
-import { adminDb } from '@core/_shared'
-
-// For operations requiring elevated privileges
-const { data } = await adminDb.from('system_config').select('*')
-```
-
-**⚠️ Warning:** Only use for cross-tenant operations or when RLS would block legitimate system actions.
-
----
-
-### `joins`
-**Stability:** Stable
-
-Database query builders for common patterns.
-
-```typescript
-import { joins } from '@core/_shared'
-
-// Joins with common filters applied
-const query = joins.itemsWithAccounts(ctx.db)
-```
-
----
-
-## Permissions
-
-### `checkPermission`
-**Stability:** Evolving
-
-Check if principal has permission for an action.
-
-```typescript
-import { checkPermission } from '@core/_shared'
-
-const allowed = await checkPermission(ctx.principal, 'item', 'update', itemId)
-```
-
----
-
-### `sanitizeRecordData`
-**Stability:** Evolving
-
-Removes fields user cannot see based on permissions.
-
-```typescript
-import { sanitizeRecordData } from '@core/_shared'
-
-const safeData = sanitizeRecordData(record, ctx.principal, 'read')
-```
-
----
-
-## App Manifest Utilities
-
-### `loadManifest`
-**Stability:** Evolving
-
-Load and parse an app manifest.json file.
-
-```typescript
-import { loadManifest } from '@core/_shared'
-
-const manifest = loadManifest('custom/apps/my-app/manifest.json')
-// Returns: { name, slug, required_roles, routes, nav_items, ... }
-```
-
----
-
-### `mergeWithManifest`
-**Stability:** Evolving
-
-Merge database app record with manifest data.
-
-```typescript
-import { mergeWithManifest } from '@core/_shared'
-
-const app = mergeWithManifest(dbRecord)
-// Returns merged data with manifest taking precedence for metadata
-```
-
----
-
-## Audit & Logging
-
-### `emitAudit`
-**Stability:** Stable
-
-Emit structured audit log entry.
-
-```typescript
-import { emitAudit } from '@core/_shared'
-
-emitAudit({
-  action: 'item.updated',
-  target: { type: 'item', id: itemId },
-  actor: ctx.principal.id,
-  metadata: { fields_changed: ['status', 'assignee'] }
-})
-```
-
----
-
-## Schema Utilities
-
-### `validateSchema`
-**Stability:** Evolving
-
-Validate data against JSON schema.
-
-```typescript
-import { validateSchema } from '@core/_shared'
-
-const { valid, errors } = validateSchema(data, schema)
-```
-
----
-
-## Agent Runner
-
-### `runAgent`
-**Stability:** Evolving
-
-Execute an AI agent with context.
-
-```typescript
-import { runAgent } from '@core/_shared'
-
-const result = await runAgent(agentId, {
-  input: userMessage,
-  context: { account_id, user_id }
-})
-```
-
----
-
-## Trigger Engine
-
-### `registerTrigger`
-**Stability:** Evolving
-
-Register a trigger handler.
-
-```typescript
-import { registerTrigger } from '@core/_shared'
-
-registerTrigger({
-  event: 'item.created',
-  condition: { item_type: 'ticket' },
-  action: { pipeline_id: 'notify-slack' }
-})
-```
-
----
-
-## Type Exports
-
-### `CoreContext`
-**Stability:** Stable
-
-```typescript
-import type { CoreContext } from '@core/_shared'
-```
-
-### `Principal`
-**Stability:** Stable
-
-```typescript
-import type { Principal } from '@core/_shared'
-```
-
-### `AppManifest`
-**Stability:** Evolving
-
-```typescript
-import type { AppManifest, NavItem } from '@core/_shared'
-```
-
-### `WebhookHandlerRegistration`
-**Stability:** Evolving
-
-```typescript
-import type { WebhookHandlerRegistration } from '@core/_shared'
-```
-
----
-
-## Usage Examples
-
-### Custom API Endpoint
-
-```typescript
-// custom/functions/custom_my-endpoint.ts
-import { createHandler, adminDb } from '@core/_shared'
-
-export const handler = createHandler(async (event, ctx) => {
-  const { data } = await ctx.db.from('my_items').select('*')
-  return { data }
-})
-```
-
-### Custom Webhook Handler
-
-```typescript
-// custom/functions/custom_slack-webhook.ts
-import { createHandler, registerWebhookHandler, adminDb } from '@core/_shared'
-
-export const handler = createHandler(async (event, ctx) => {
-  // Handle webhook
-  return { status: 'processed' }
-})
-
-// Self-register
-registerWebhookHandler({
-  name: 'slack-webhook',
-  functionName: 'custom_slack-webhook',
-  description: 'Posts to Slack',
-  events: ['item.created']
-}, adminDb)
-```
-
-### Using Manifest
-
-```typescript
-// In a custom app component
-import { loadManifest } from '@core/_shared'
-
-const manifest = loadManifest('custom/apps/my-app/manifest.json')
-console.log(manifest.required_roles) // ['member', 'operator']
-```
-
----
-
-## Breaking Changes Policy
-
-- **Stable APIs:** No breaking changes within major version
-- **Evolving APIs:** Breaking changes announced in release notes, 1 version deprecation
-- **Internal APIs:** No guarantees, may break anytime
-
----
-
-## Version History
-
-### 0.1.0 (Current)
-- Initial public API surface
-- Webhook registry pattern (evolving)
-- App manifest utilities (evolving)
-- Pipeline engine access (evolving)
-
----
-
-## See Also
-
-- `docs/enterprise-framework-implementation-summary.md` — Architecture overview
-- `.framework/functions/_shared/index.ts` — Source of truth for exports
-- `docs/framework-developer-guide.md` — Developer guide (coming soon)

package/.framework/docs/STABILITY.md

@@ -1,52 +0,0 @@
-# Stability Policy
-
-> Version target: **0.x** — breaking changes are allowed until 1.0.
-
-## Stability Levels
-
-Every exported symbol in `_shared/index.ts` is annotated with one of these levels:
-
-| Level | Meaning | Breaking change policy |
-|-------|---------|----------------------|
-| **stable** | Safe for custom code to depend on | Minimum 1 minor version deprecation notice before removal |
-| **evolving** | API may change between minor versions | No deprecation period required, but changelog entry mandatory |
-| **internal** | Not exported; core-contributor only | May change without notice |
-
-## Versioning
-
-Spine follows [semver](https://semver.org/) with these conventions:
-
-- **0.x.y** — Pre-stable. Breaking changes increment the minor version.
-- **1.0.0+** — Stable. Breaking changes increment the major version.
-
-## Deprecation Process
-
-1. Mark the symbol with `@deprecated` JSDoc tag and a migration hint
-2. Add a console warning on first use (once per process)
-3. Remove after the next minor version bump
-
-## What Counts as Breaking
-
-- Removing or renaming an exported function/type from `_shared/index.ts`
-- Changing function signatures (required params added, return type changed)
-- Removing a CLI command or changing its required arguments
-- Changing database table/column names in migration files
-- Removing seed data keys from `seed/*.json` schemas
-
-## What Does NOT Count as Breaking
-
-- Adding new optional parameters to existing functions
-- Adding new exports to `_shared/index.ts`
-- Adding new CLI commands
-- Adding new database tables or columns
-- Performance improvements to existing functions
-- Bug fixes (even if they change observable behavior that was clearly wrong)
-
-## Release Checklist
-
-1. `npm run test:boundary` — architectural boundaries intact
-2. `npm run test:unit` — unit tests pass
-3. Update `CHANGELOG.md` with breaking changes highlighted
-4. Bump version in `package.json`
-5. `npm run prepublishOnly` — build + test gate
-6. `npm publish`

package/.framework/docs/admin-routes.md

@@ -1,76 +0,0 @@
-# Admin Route Inventory (v2-core)
-
-## Data Management Routes (admin/data/*)
-
-| Route | Purpose | Page Component | Entity | Notes |
-|-------|---------|----------------|--------|-------|
-| `/admin/data/accounts` | List accounts | AccountsPage | Account records | Runtime account management |
-| `/admin/data/accounts/new` | Create account | AccountCreatePage | Account records | |
-| `/admin/data/accounts/:id` | Account detail/edit | AccountDetailPage | Account records | |
-| `/admin/data/people` | List people | PeoplePage | Person records | |
-| `/admin/data/people/new` | Create person | PersonCreatePage | Person records | |
-| `/admin/data/people/:id` | Person detail/edit | PersonDetailPage | Person records | |
-| `/admin/data/items` | List items | ItemsPage | Item records | |
-| `/admin/data/items/new` | Create item | ItemCreatePage | Item records | |
-| `/admin/data/items/:id` | Item detail/edit | ItemDetailPage | Item records | |
-
-## Configuration Management Routes (admin/configs/*)
-
-| Route | Purpose | Page Component | Entity | Notes |
-|-------|---------|----------------|--------|-------|
-| `/admin/configs/types` | List item types | TypesPage | Type definitions | kind='item' |
-| `/admin/configs/types/new` | Create item type | TypeDetailPage | Type definitions | |
-| `/admin/configs/types/:id` | Item type detail/edit | TypeDetailPage | Type definitions | |
-| `/admin/configs/accounts` | List account types | AccountTypesPage | Type definitions | kind='account' |
-| `/admin/configs/accounts/new` | Create account type | AccountTypeDetailPage | Type definitions | |
-| `/admin/configs/accounts/:id` | Account type detail/edit | AccountTypeDetailPage | Type definitions | |
-| `/admin/configs/people` | List person types | PersonTypesPage | Type definitions | kind='person' |
-| `/admin/configs/people/new` | Create person type | PersonTypeDetailPage | Type definitions | |
-| `/admin/configs/people/:id` | Person type detail/edit | PersonTypeDetailPage | Type definitions | |
-| `/admin/configs/apps` | List apps | AppsPage | App definitions | |
-| `/admin/configs/apps/new` | Create app | AppDetailPage | App definitions | |
-| `/admin/configs/apps/:id` | App detail/edit | AppDetailPage | App definitions | |
-| `/admin/configs/pipelines` | List pipelines | PipelinesPage | Pipeline definitions | |
-| `/admin/configs/pipelines/new` | Create pipeline | PipelineDetailPage | Pipeline definitions | |
-| `/admin/configs/pipelines/:id` | Pipeline detail/edit | PipelineDetailPage | Pipeline definitions | |
-| `/admin/configs/triggers` | List triggers | TriggersPage | Trigger definitions | |
-| `/admin/configs/triggers/new` | Create trigger | TriggerDetailPage | Trigger definitions | |
-| `/admin/configs/triggers/:id` | Trigger detail/edit | TriggerDetailPage | Trigger definitions | |
-| `/admin/configs/ai-agents` | List AI agents | AIAgentsPage | AI agent definitions | |
-| `/admin/configs/ai-agents/new` | Create AI agent | AIAgentDetailPage | AI agent definitions | |
-| `/admin/configs/ai-agents/:id` | AI agent detail/edit | AIAgentDetailPage | AI agent definitions | |
-| `/admin/configs/embeddings` | List embeddings | EmbeddingsPage | Embedding definitions | |
-| `/admin/configs/embeddings/new` | Create embedding | EmbeddingDetailPage | Embedding definitions | |
-| `/admin/configs/embeddings/:id` | Embedding detail/edit | EmbeddingDetailPage | Embedding definitions | |
-| `/admin/configs/timers` | List timers | TimersPage | Timer definitions | |
-| `/admin/configs/timers/new` | Create timer | TimerDetailPage | Timer definitions | |
-| `/admin/configs/timers/:id` | Timer detail/edit | TimerDetailPage | Timer definitions | |
-| `/admin/configs/integrations` | List integrations | IntegrationsPage | Integration definitions | |
-| `/admin/configs/integrations/new` | Create integration | IntegrationDetailPage | Integration definitions | |
-| `/admin/configs/integrations/:id` | Integration detail/edit | IntegrationDetailPage | Integration definitions | |
-
-## Legacy Routes (Deprecated)
-
-| Route | Purpose | Page Component | Entity | Notes |
-|-------|---------|----------------|--------|-------|
-| `/admin/accounts` | Accounts (legacy) | AccountsPage | Account records | Use /admin/data/accounts |
-| `/admin/accounts/:id` | Account detail (legacy) | AccountDetailPage | Account records | Use /admin/data/accounts/:id |
-| `/admin/people` | People (legacy) | PeoplePage | Person records | Use /admin/data/people |
-| `/admin/people/:id` | Person detail (legacy) | PersonDetailPage | Person records | Use /admin/data/people/:id |
-| `/admin/types` | Types (legacy) | TypesPage | Type definitions | Use /admin/configs/types |
-| `/admin/types/:id` | Type detail (legacy) | TypeDetailPage | Type definitions | Use /admin/configs/types/:id |
-| `/admin/apps` | Apps (legacy) | AppsPage | App definitions | Use /admin/configs/apps |
-| `/admin/pipelines` | Pipelines (legacy) | PipelinesPage | Pipeline definitions | Use /admin/configs/pipelines |
-| `/admin/triggers` | Triggers (legacy) | TriggersPage | Trigger definitions | Use /admin/configs/triggers |
-| `/admin/ai-agents` | AI agents (legacy) | AIAgentsPage | AI agent definitions | Use /admin/configs/ai-agents |
-| `/admin/embeddings` | Embeddings (legacy) | EmbeddingsPage | Embedding definitions | Use /admin/configs/embeddings |
-| `/admin/timers` | Timers (legacy) | TimersPage | Timer definitions | Use /admin/configs/timers |
-
-## Summary
-
-- **Total routes**: 43 active routes (25 data/config + 10 legacy)
-- **Data routes**: 9 (accounts, people, items)
-- **Config routes**: 34 (types, apps, pipelines, triggers, ai-agents, embeddings, timers, integrations)
-- **Legacy routes**: 10 (deprecated but still active)
-
-All routes are defined in `v2-core/src/App.tsx` and use lazy-loaded components from `v2-core/src/pages/`.

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

@@ -1,38 +0,0 @@
-# API Documentation Progress
-
-## Completed Inline Documentation
-
-### accounts.ts
-- Added comprehensive header documentation
-- Documented all CRUD operations
-- Fixed lint warnings (unused imports/parameters)
-- Status: COMPLETE
-
-### Next Files to Document
-1. people.ts
-2. items.ts
-3. types.ts
-4. apps.ts
-5. pipelines.ts
-6. triggers.ts
-7. ai-agents.ts
-8. embeddings.ts
-9. timers.ts
-10. integrations.ts
-11. All remaining runtime endpoints
-
-## Documentation Template Applied
-
-Each endpoint file now includes:
-- Domain classification (admin-data/admin-configs/runtime/internal)
-- Auth requirements
-- Account scoping rules
-- v2 schema dependencies
-- Soft delete behavior
-- Audit logging requirements
-- Request/response contracts
-- Error handling
-
-## Progress: 1/18 endpoints documented
-
-Continuing with remaining endpoints...

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