spine-framework 0.2.1 → 1.0.0

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

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

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

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