spine-framework 0.1.0

package/.framework/docs/guides/cli-guide.md

@@ -0,0 +1,224 @@
+# Spine CLI Reference
+
+The `spine` CLI is a thin adapter over Spine core functions. Every command constructs a `CoreContext` and calls the same logic used by API handlers and imports — no HTTP involved.
+
+---
+
+## Installation
+
+```bash
+# From project root
+npm run spine -- --help
+
+# Or link globally
+npm link
+spine --help
+```
+
+---
+
+## Configuration
+
+The CLI reads credentials from `v2-core/.xenv` or environment variables:
+
+| Variable | Required | Description |
+|---|---|---|
+| `SUPABASE_URL` | ✓ | Your Supabase project URL |
+| `SUPABASE_SERVICE_ROLE_KEY` | ✓ | Service role key (admin ops) |
+| `SUPABASE_ANON_KEY` | For user auth | Anon key for JWT-scoped ops |
+| `SPINE_CLI_ACCOUNT_ID` | Recommended | Default account scope |
+| `SPINE_CLI_JWT` | For human auth | User JWT token |
+| `SPINE_CLI_API_KEY` | For machine auth | Machine API key |
+| `SPINE_CLI_DEBUG` | Optional | Set to `1` for stack traces |
+
+**Authentication priority:**
+1. `SPINE_CLI_API_KEY` → machine principal
+2. `SPINE_CLI_JWT` → human principal
+3. Neither → `SYSTEM_PRINCIPAL` (admin ops only)
+
+---
+
+## Global Options
+
+```
+--account <id>   Override the account ID for this command
+--json           Output as JSON (available on most commands)
+```
+
+---
+
+## Commands
+
+### `spine auth`
+
+```bash
+# Show the resolved identity for current env
+spine auth whoami
+
+# Validate credentials — exits 0 if valid, 1 if not
+spine auth check
+```
+
+**Example: `whoami` output**
+```
+Spine CLI — Current Identity
+────────────────────────────────────────
+Principal ID:   cab578c2-c295-476a-a8c5-dca3445aa4ac
+Type:           human
+Account:        cd74879c-3bfa-4dce-9bbd-67b31eaa23e2
+Name:           K Pettit
+Email:          kpettit851@gmail.com
+Roles:          system_admin, admin
+Request ID:     f3e2a1b0-...
+```
+
+---
+
+### `spine pipelines`
+
+```bash
+# List all active pipelines
+spine pipelines list
+spine pipelines list --account <id> --all --json
+
+# Get pipeline details
+spine pipelines get <id>
+
+# Execute a pipeline
+spine pipelines run <id>
+spine pipelines run <id> --data '{"item_id":"abc123"}'
+spine pipelines run <id> --account <account-id> --json
+
+# List recent executions
+spine pipelines executions <id>
+spine pipelines executions <id> --limit 20 --json
+```
+
+**Example: `run` output**
+```
+Running pipeline e3f1a2b0-...
+
+✓ Pipeline completed
+  Execution ID: 9d8c7b6a-...
+  Duration:     342ms
+  Stages:       3
+    ✓ [0] update_item (45ms)
+    ✓ [1] send_notification (89ms)
+    ✓ [2] http_request (208ms)
+```
+
+---
+
+### `spine items`
+
+```bash
+# List items (all types or filtered)
+spine items list
+spine items list --type support_ticket --limit 50
+spine items list --account <id> --json
+
+# Get a single item
+spine items get <id>
+spine items get <id> --json
+
+# Create an item
+spine items create --type support_ticket --title "Login broken" --account <id>
+spine items create --type support_ticket --data '{"priority":"high","status":"open"}' --account <id>
+
+# Update item fields
+spine items update <id> --data '{"status":"resolved"}'
+spine items update <id> --title "New title"
+
+# Soft-delete (sets is_active = false)
+spine items delete <id>
+
+# Hard delete (permanent)
+spine items delete <id> --hard
+```
+
+---
+
+### `spine agents`
+
+```bash
+# Send a message to an agent thread
+spine agents run <thread-id> --message "How do I reset my password?"
+spine agents run <thread-id> --message "Summarize open tickets" --json
+
+# List agent threads
+spine agents threads list
+spine agents threads list --account <id> --limit 10
+
+# Get thread details + messages
+spine agents threads get <thread-id>
+spine agents threads get <thread-id> --limit 50 --json
+```
+
+**Example: `run` output**
+```
+Sending message to thread 7a6b5c4d-...
+
+─── Agent Response ───
+Based on your account settings, to reset your password: click "Forgot Password"
+on the login page and enter your email address...
+─────────────────────
+Confidence: 87%
+```
+
+---
+
+### `spine migrations`
+
+```bash
+# List all applied migrations
+spine migrations list
+spine migrations list --json
+
+# Compare local files vs applied
+spine migrations status
+spine migrations status --json
+```
+
+**Example: `status` output**
+```
+Migration Status
+────────────────────────────────────────────────────────────
+  ✓ 001_schema.sql                           applied
+  ✓ 002_accounts.sql                         applied
+  ✓ 003_people.sql                           applied
+  ...
+  ○ 065_new_feature.sql                      pending
+
+  64 applied, 1 pending
+```
+
+---
+
+## Agentic IDE Usage
+
+The CLI is designed for use in Windsurf, Cursor, and other agentic IDEs. Recommended workflow file pattern:
+
+```markdown
+---
+description: Run a Spine pipeline from the IDE
+---
+
+1. Set up credentials in v2-core/.xenv
+// turbo
+2. Run: npm run spine -- auth check
+// turbo
+3. Run: npm run spine -- pipelines run <id> --data '{"key":"value"}' --json
+```
+
+For machine-to-machine operations in IDE workflows, use `SPINE_CLI_API_KEY` with appropriate scopes rather than a human JWT.
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success |
+| `1` | Error (message printed to stderr) |
+
+Set `SPINE_CLI_DEBUG=1` to see full stack traces on errors.

package/.framework/docs/guides/getting-started.md

@@ -0,0 +1,103 @@
+# Getting Started with Spine v2
+
+Spine is a backend framework that runs on Supabase + Netlify Functions. It provides multi-tenancy, authentication, authorization, pipeline automation, and AI agent infrastructure — all accessible via three interfaces:
+
+| Interface | Use case |
+|---|---|
+| **API** | External services, frontends, webhooks |
+| **Import** | Custom functions running in the same process |
+| **CLI** | Terminal operations, agentic IDE workflows, testing |
+
+---
+
+## Prerequisites
+
+- Node.js 20+
+- A Supabase project
+- Netlify CLI (`npm install -g netlify-cli`)
+
+---
+
+## 1. Clone and configure
+
+```bash
+git clone https://github.com/your-org/spine-ia
+cd spine-ia
+npm install
+```
+
+Copy the example environment file:
+
+```bash
+cp v2-core/.xenv.example v2-core/.xenv
+```
+
+Edit `v2-core/.xenv` and fill in your Supabase credentials:
+
+```env
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_SERVICE_ROLE_KEY=eyJhbGci...
+SUPABASE_ANON_KEY=eyJhbGci...
+DB_SCHEMA=public
+```
+
+---
+
+## 2. Apply migrations
+
+```bash
+# Apply all migrations to your Supabase project
+supabase db push
+```
+
+Or via Supabase CLI against a specific project:
+
+```bash
+supabase migration up --project-id your-project-id
+```
+
+---
+
+## 3. Start the dev server
+
+```bash
+netlify dev
+```
+
+This assembles `v2-core/` + `v2-custom/` and starts the Netlify dev proxy on port 8888.
+
+---
+
+## 4. Verify the API
+
+```bash
+curl http://localhost:8888/.netlify/functions/health
+# {"data":{"status":"ok","version":"2.0.0"}, "error":null}
+```
+
+---
+
+## 5. Test the CLI
+
+```bash
+npm run spine -- auth whoami
+```
+
+Expected output:
+```
+Spine CLI — Current Identity
+────────────────────────────────────────
+Principal ID:   system
+Type:           machine
+Account:        (none)
+Request ID:     <uuid>
+```
+
+---
+
+## Next Steps
+
+- [Import Guide](./import-guide.md) — use Spine functions directly in custom code
+- [CLI Reference](./cli-guide.md) — full CLI command reference
+- [API Governance](../api-governance.md) — API versioning and contract rules
+- [Authorization Model](../authorization-model.md) — roles, scopes, and permissions

package/.framework/docs/guides/import-guide.md

@@ -0,0 +1,193 @@
+# Spine Import Guide
+
+Custom code in `v2-custom/functions/` can import Spine core functions directly, bypassing HTTP entirely. This is the **primary interface for agentic IDEs** — no HTTP calls, no auth tokens, full access to the execution engine.
+
+---
+
+## The Import Surface
+
+All stable exports are available from a single entry point:
+
+```ts
+import { ... } from '../_shared/index.ts'
+```
+
+> **Do not** import from individual `_shared/*.ts` files directly. Only `index.ts` is a committed contract.
+
+---
+
+## CoreContext
+
+Every core function accepts a `CoreContext` — the minimal execution context:
+
+```ts
+import {
+  CoreContext,
+  adminDb,
+  SYSTEM_PRINCIPAL,
+  runPipeline
+} from '../_shared/index.ts'
+
+const ctx: CoreContext = {
+  principal: SYSTEM_PRINCIPAL,     // who is performing the action
+  accountId: 'uuid-of-account',    // account scope (null for system-level)
+  db: adminDb,                     // database client
+  requestId: crypto.randomUUID()   // for audit logs
+}
+```
+
+### Constructing a human principal context
+
+When a custom function is invoked by a user:
+
+```ts
+import {
+  CoreContext,
+  getPrincipalDb,
+  resolvePrincipal
+} from '../_shared/index.ts'
+
+export const handler = async (event: any) => {
+  const principal = await resolvePrincipal(event)
+  const db = getPrincipalDb(principal)
+
+  const ctx: CoreContext = {
+    principal,
+    accountId: principal.accountId,
+    db,
+    requestId: crypto.randomUUID()
+  }
+
+  // Now call any core function
+  const result = await runPipeline(pipelineId, data, ctx)
+  return { data: result, error: null }
+}
+```
+
+---
+
+## runPipeline
+
+Execute a pipeline by ID:
+
+```ts
+import { runPipeline, CoreContext } from '../_shared/index.ts'
+
+const result = await runPipeline(
+  'pipeline-uuid',          // pipeline ID
+  { item_id: 'abc123' },    // trigger data — passed to all stages
+  ctx                       // CoreContext
+)
+
+// result: ExecutionResult
+console.log(result.status)          // 'completed' | 'failed' | 'cancelled'
+console.log(result.stages)          // StageResult[] with per-stage output
+console.log(result.durationMs)      // total execution time
+```
+
+---
+
+## checkAndFireTriggers
+
+Fire triggers after an entity event:
+
+```ts
+import { fireCreateTriggers } from '../_shared/index.ts'
+
+// After creating an item, fire all matching triggers
+await fireCreateTriggers('items', item.id, item, ctx)
+
+// Or use the full form for custom event types:
+import { checkAndFireTriggers } from '../_shared/index.ts'
+await checkAndFireTriggers('item_created', 'items', item.id, item, ctx)
+```
+
+---
+
+## runAgent
+
+Send a message to an AI agent thread:
+
+```ts
+import { runAgent } from '../_shared/index.ts'
+
+const response = await runAgent(
+  'thread-uuid',            // thread ID (must have an agent assigned)
+  'How do I reset my password?',
+  ctx
+)
+
+console.log(response.content)       // agent's reply text
+```
+
+---
+
+## PermissionEngine
+
+Check and enforce permissions in custom code:
+
+```ts
+import { PermissionEngine } from '../_shared/index.ts'
+
+// Check if the principal can read a record
+const canRead = await PermissionEngine.canAccessRecord(ctx, record, 'read')
+if (!canRead) {
+  return { data: null, error: 'Forbidden', statusCode: 403 }
+}
+
+// Sanitize a record — strips fields the principal cannot read
+const safe = await PermissionEngine.sanitizeRecordData(ctx, record, 'support_ticket')
+
+// Validate update data — rejects writes to restricted fields
+const { valid, error } = await PermissionEngine.validateUpdatePermissions(ctx, updateData, existingRecord)
+```
+
+---
+
+## emitAudit
+
+Emit structured audit log entries from custom code:
+
+```ts
+import { emitAudit } from '../_shared/index.ts'
+
+await emitAudit(ctx, 'deal.stage_changed', {
+  type: 'items',
+  id: deal.id,
+  account_id: ctx.accountId ?? undefined
+}, {
+  changes: {
+    before: { stage: 'prospect' },
+    after: { stage: 'qualified' }
+  }
+})
+```
+
+---
+
+## Available Exports Reference
+
+| Export | Type | Description |
+|---|---|---|
+| `CoreContext` | interface | Minimal context for all core functions |
+| `RequestContext` | interface | CoreContext + HTTP fields (for API handlers) |
+| `createHandler` | function | Wraps a handler with auth + audit |
+| `Principal` | interface | Unified identity for all actors |
+| `SYSTEM_PRINCIPAL` | const | Static system-level principal |
+| `ANONYMOUS_PRINCIPAL` | const | Unauthenticated principal |
+| `resolvePrincipal` | function | Resolve Principal from HTTP event |
+| `getPrincipalDb` | function | Get RLS-scoped DB client for principal |
+| `adminDb` | const | Service-role Supabase client |
+| `getUserDb` | function | JWT-scoped Supabase client |
+| `runPipeline` | function | Execute a pipeline |
+| `checkAndFireTriggers` | function | Fire matching triggers for an event |
+| `fireCreateTriggers` | function | Fire `*_created` triggers |
+| `fireUpdateTriggers` | function | Fire `*_updated` triggers |
+| `fireDeleteTriggers` | function | Fire `*_deleted` triggers |
+| `runAgent` | function | Run AI agent inference |
+| `resolveAgentConfig` | function | Resolve agent config from thread |
+| `PermissionEngine` | instance | Permission evaluation singleton |
+| `generateValidationSchema` | function | Derive validation schema from design schema |
+| `emitAudit` | function | Emit structured audit log |
+
+See [`_shared/index.ts`](../../functions/_shared/index.ts) for full TSDoc on each export.