spine-framework 0.1.0

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

@@ -0,0 +1,229 @@
+# Testing Guide
+
+Spine's test suite covers four surfaces: **unit**, **integration**, **API**, and **UI (Playwright)**.
+All tests target the **public schema** (`DB_SCHEMA=public`). Results are persisted to
+`public.test_runs` / `public.test_results` and surfaced in the admin UI at `/admin/testing`.
+
+The primary purpose of running tests against the public schema is to discover **day-zero gaps** —
+missing seed data, structural issues, or RLS mismatches that must be resolved before production.
+
+---
+
+## Running Tests
+
+```bash
+# All tests (unit + integration + api)
+npm test
+
+# Unit tests only (fast, no network)
+npm run test:unit
+
+# Integration tests (requires SUPABASE_URL + SUPABASE_SERVICE_ROLE_KEY + SPINE_TEST_ACCOUNT_ID)
+npm run test:integration
+
+# API tests (requires dev server running + SPINE_DEV_JWT)
+SPINE_DEV_JWT=<jwt> vitest run v2-core/tests/api
+
+# UI sweep (requires dev server + playwright)
+tsx v2-core/tests/ui/ui-sweep.ts
+```
+
+See `.windsurf/workflows/run-tests.md` for the full step-by-step workflow.
+
+---
+
+## Environment Setup
+
+Integration, API, and UI tests need credentials in `v2-core/.xenv` or `v2-core/.xenv.test`:
+
+```env
+SUPABASE_URL=https://uyokuiibztwfasdprsov.supabase.co
+SUPABASE_SERVICE_ROLE_KEY=<service-role-key>
+SPINE_TEST_ACCOUNT_ID=<uuid>
+DB_SCHEMA=public
+# For API tests:
+SPINE_DEV_JWT=<user-jwt>
+SPINE_DEV_URL=http://localhost:8888
+```
+
+---
+
+## Test Suites
+
+### Unit Tests (`v2-core/tests/unit/`)
+
+Pure function tests — no network, no DB. Mock `db.ts` with `vi.mock`.
+
+```ts
+// v2-core/tests/unit/pipeline-runner.test.ts
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { runPipeline } from '../../functions/_shared/pipeline-runner.ts'
+import { SYSTEM_PRINCIPAL } from '../../functions/_shared/principal.ts'
+import type { CoreContext } from '../../functions/_shared/middleware.ts'
+
+// Mock adminDb
+vi.mock('../../functions/_shared/db.ts', () => ({
+  adminDb: {
+    from: vi.fn().mockReturnThis(),
+    select: vi.fn().mockReturnThis(),
+    insert: vi.fn().mockReturnThis(),
+    update: vi.fn().mockReturnThis(),
+    eq: vi.fn().mockReturnThis(),
+    single: vi.fn()
+  }
+}))
+
+function makeCtx(overrides: Partial<CoreContext> = {}): CoreContext {
+  return {
+    principal: SYSTEM_PRINCIPAL,
+    accountId: 'test-account-id',
+    db: {},  // mocked via vi.mock above
+    requestId: 'test-request-id',
+    ...overrides
+  }
+}
+```
+
+### Example unit test
+
+```ts
+describe('runPipeline', () => {
+  it('throws when pipeline not found', async () => {
+    const { adminDb } = await import('../../functions/_shared/db.ts')
+    vi.mocked(adminDb.from('pipelines').select('*').eq('id', 'x').eq('is_active', true).single)
+      .mockResolvedValue({ data: null, error: { message: 'Not found' } })
+
+    await expect(
+      runPipeline('nonexistent-id', {}, makeCtx())
+    ).rejects.toThrow('Pipeline not found or inactive')
+  })
+})
+```
+
+---
+
+## Integration Tests (`v2-core/tests/integration/`)
+
+Run against the live Supabase public schema via `adminDb`. Failures are **day-zero gaps**.
+
+Key files:
+- `helpers.ts` — `adminDb`, `makeTestCtx()`, `TEST_ACCOUNT_ID`
+- `admin-data-accounts.test.ts` — accounts table shape + HTTP endpoint
+- `admin-data-people.test.ts` — people table shape + HTTP endpoint
+- `schema-validation.test.ts` — `design_schema` completeness across all types
+- `custom-integrity.test.ts` — public schema connectivity, RLS isolation, export surface
+
+Tests use `describe.skipIf(!TEST_ACCOUNT_ID)` to skip gracefully when env is not configured.
+
+```ts
+describe.skipIf(!TEST_ACCOUNT_ID)('my integration test', () => {
+  it('checks something in public schema', async () => {
+    const { data, error } = await adminDb.from('types').select('*').limit(1)
+    expect(error).toBeNull()
+    // Gap warning pattern:
+    if (!data?.length) console.warn('[gap] public.types is empty')
+  })
+})
+```
+
+---
+
+## API Tests (`v2-core/tests/api/`)
+
+HTTP fetch tests against the local dev server. Requires `SPINE_DEV_JWT`.
+
+- `api-surface.test.ts` — auth matrix, CRUD lifecycle, error handling across all entities
+
+```bash
+SPINE_DEV_JWT=<jwt> vitest run v2-core/tests/api
+```
+
+---
+
+## UI Tests (`v2-core/tests/ui/`)
+
+Playwright sweep over all admin routes. Checks for zero console errors per page.
+
+```bash
+tsx v2-core/tests/ui/ui-sweep.ts
+```
+
+Results written to `public.test_runs` with `suite='ui'`.
+
+---
+
+## Result Reporter
+
+`tests/reporter.ts` is a Vitest custom reporter that persists results to `public.test_runs`
+and `public.test_results` after every test run. Also exports `writeRunResults()` for use
+by non-Vitest runners (UI sweep, API tests).
+
+It is registered in `vitest.config.ts`:
+```ts
+reporters: ['default', './v2-core/tests/reporter.ts']
+```
+
+View results in the admin UI at `/admin/testing`.
+
+---
+
+## Fixtures
+
+```bash
+# Seed test data into public schema (idempotent)
+tsx v2-core/tests/fixtures/seed.ts
+
+# Remove test-* rows from public schema
+tsx v2-core/tests/fixtures/teardown.ts
+```
+
+---
+
+## Gap Report
+
+After running integration + API + UI tests, document every failure in
+`v2-core/docs/dayzero-gap-report.md`:
+
+```markdown
+## Gap: public.types is empty
+- **Test**: schema-validation.test.ts — "all active types have a non-empty design_schema"
+- **Root cause**: `migrations_dayzero/007_seeds.sql` not yet applied to public schema
+- **Fix**: Apply seeds or add missing type rows
+```
+
+---
+
+## Testing Custom Code
+
+Import from the stable `_shared` index:
+
+```ts
+import { runPipeline, adminDb, SYSTEM_PRINCIPAL, CoreContext } from '../../_shared/index.ts'
+```
+
+---
+
+## Test File Structure
+
+```
+v2-core/tests/
+  unit/
+    pipeline-runner.test.ts
+    permissions.test.ts
+    schema-utils.test.ts
+    principal.test.ts
+  integration/
+    auth.test.ts
+    isolation.test.ts
+    permissions.test.ts
+    pipeline.test.ts
+    machine-principal.test.ts
+    cli-smoke.test.ts
+    helpers.ts
+```
+
+---
+
+## CI Integration
+
+Tests run automatically in GitHub Actions via `.github/workflows/smoke-test.yml`. Unit tests run on every push; integration tests run on PRs against `main` using the Supabase staging branch credentials stored in GitHub Secrets.

package/.framework/docs/permission-examples.md

@@ -0,0 +1,326 @@
+# Permission Examples
+
+## Support Ticket Use Case
+
+### Customer (user role)
+- Can create tickets in their own account
+- Can only see/update their own tickets
+- Cannot see ARR field
+
+### Master Support Agent (master-support role)
+- Assigned to client accounts via v2.people_roles
+- Can read all client tickets
+- Can update most ticket fields
+- Cannot see ARR field (field override)
+
+### Master CSM (master-csm role)  
+- Assigned to client accounts via v2.people_roles
+- Can read all client tickets
+- Can update ARR field (field override)
+- Cannot delete tickets
+
+## Schema Example
+
+```json
+{
+  "record_permissions": {
+    "user": {
+      "create": true,
+      "read": "own",
+      "update": "own",
+      "delete": false
+    },
+    "master-support": {
+      "create": false,
+      "read": "all", 
+      "update": "all",
+      "delete": false
+    },
+    "master-csm": {
+      "create": false,
+      "read": "all",
+      "update": false,
+      "delete": false
+    }
+  },
+  "fields": {
+    "arr": {
+      "type": "number",
+      "permissions": {
+        "master-support": {
+          "read": false,
+          "write": false
+        },
+        "master-csm": {
+          "read": true,
+          "write": true
+        }
+      }
+    }
+  }
+}
+```
+
+## API Behavior Examples
+
+### Creating a Ticket
+
+**Customer Request:**
+```typescript
+POST /functions/items
+{
+  "item_type": "support_ticket",
+  "title": "Login issue",
+  "data": {
+    "description": "Cannot login to account",
+    "priority": "high"
+  }
+}
+```
+
+**Permission Check:**
+- User has `user` role
+- `record_permissions.user.create` is `true`
+- **Result:** Ticket created successfully
+
+**Master Support Request:**
+```typescript
+POST /functions/items
+{
+  "item_type": "support_ticket", 
+  "title": "System maintenance",
+  "data": {
+    "description": "Scheduled maintenance",
+    "priority": "low"
+  }
+}
+```
+
+**Permission Check:**
+- User has `master-support` role
+- `record_permissions.master-support.create` is `false`
+- **Result:** Permission denied
+
+### Reading Tickets
+
+**Customer Reading Their Own Ticket:**
+```typescript
+GET /functions/items?id=customer-ticket-123
+```
+
+**Permission Check:**
+- User has `user` role
+- `record_permissions.user.read` is `"own"`
+- Ticket was created by this user
+- **Result:** Returns ticket with all fields visible to user
+
+**Customer Reading Another Customer's Ticket:**
+```typescript
+GET /functions/items?id=other-customer-ticket-456
+```
+
+**Permission Check:**
+- User has `user` role
+- `record_permissions.user.read` is `"own"`
+- Ticket was NOT created by this user
+- **Result:** Permission denied
+
+**Master Support Reading Any Client Ticket:**
+```typescript
+GET /functions/items?id=client-ticket-789
+```
+
+**Permission Check:**
+- User has `master-support` role
+- `record_permissions.master-support.read` is `"all"`
+- **Result:** Returns ticket, but ARR field is filtered out due to field override
+
+### Updating Tickets
+
+**Customer Updating Their Own Ticket:**
+```typescript
+PATCH /functions/items?id=customer-ticket-123
+{
+  "data": {
+    "description": "Updated description"
+  }
+}
+```
+
+**Permission Check:**
+- User has `user` role
+- `record_permissions.user.update` is `"own"`
+- Ticket was created by this user
+- Field has no specific override for `user` role
+- **Result:** Update successful
+
+**Customer Trying to Update ARR Field:**
+```typescript
+PATCH /functions/items?id=customer-ticket-123
+{
+  "data": {
+    "arr": 50000
+  }
+}
+```
+
+**Permission Check:**
+- User has `user` role
+- `record_permissions.user.update` is `"own"`
+- Ticket was created by this user
+- Field `arr` has no permission override for `user` role
+- Falls back to record-level permission: `"own"` allows update
+- **Result:** Update successful (if this is desired behavior, add field override to prevent)
+
+**Master CSM Updating ARR Field:**
+```typescript
+PATCH /functions/items?id=client-ticket-789
+{
+  "data": {
+    "arr": 75000
+  }
+}
+```
+
+**Permission Check:**
+- User has `master-csm` role
+- `record_permissions.master-csm.update` is `false`
+- Field `arr` has override: `permissions.master-csm.write` is `true`
+- **Result:** Update successful due to field override
+
+**Master Support Trying to Update ARR Field:**
+```typescript
+PATCH /functions/items?id=client-ticket-789
+{
+  "data": {
+    "arr": 75000
+  }
+}
+```
+
+**Permission Check:**
+- User has `master-support` role
+- `record_permissions.master-support.update` is `"all"`
+- Field `arr` has override: `permissions.master-support.write` is `false`
+- **Result:** Permission denied due to field override
+
+## List Endpoint Behavior
+
+**Customer Listing Tickets:**
+```typescript
+GET /functions/items?item_type=support_ticket
+```
+
+**Permission Check:**
+- Returns only tickets user can read
+- Filters out fields user cannot see
+- **Result:** List of user's own tickets with appropriate field filtering
+
+**Master Support Listing Tickets:**
+```typescript
+GET /functions/items?item_type=support_ticket
+```
+
+**Permission Check:**
+- Returns all tickets in account
+- Filters out ARR field for all tickets
+- **Result:** All client tickets with ARR field removed
+
+## System Admin Behavior
+
+**System Admin Any Operation:**
+```typescript
+// Any operation as system admin
+GET /functions/items?id=any-ticket
+PATCH /functions/items?id=any-ticket
+DELETE /functions/items?id=any-ticket
+```
+
+**Permission Check:**
+- `systemRole === 'system_admin'`
+- **Result:** All operations succeed, no field filtering, full audit trail maintained
+
+## Multi-Role User Behavior
+
+**User with Both user and master-support Roles:**
+```typescript
+GET /functions/items?id=other-user-ticket
+```
+
+**Permission Check:**
+- User has `user` role: `record_permissions.user.read` is `"own"` - denied
+- User has `master-support` role: `record_permissions.master-support.read` is `"all"` - allowed
+- **Result:** Access granted (highest effective permission wins)
+
+## Error Messages
+
+### Permission Denied Errors
+- `"Insufficient permissions to create this type of item"`
+- `"Insufficient permissions to update this item"`
+- `"Insufficient permissions to delete this item"`
+- `"Insufficient permissions to view this item"`
+- `"Insufficient permissions to update field 'field_name'"`
+
+### Context Errors
+- `"Authentication required"`
+- `"Account context required"`
+- `"Item not found"`
+
+## Debugging Permission Issues
+
+### Step 1: Check Authentication
+```sql
+-- Verify user is authenticated
+SELECT person_id, system_role FROM v2.people WHERE auth_uid = 'user_auth_uid';
+```
+
+### Step 2: Check Account Membership
+```sql
+-- Verify user is member of account
+SELECT * FROM v2.people_accounts 
+WHERE person_id = 'user_person_id' AND account_id = 'target_account_id' AND is_active = true;
+```
+
+### Step 3: Check Role Assignments
+```sql
+-- Verify user has required roles
+SELECT pr.role_slug, r.name 
+FROM v2.people_roles pr
+JOIN v2.roles r ON pr.role_id = r.id
+WHERE pr.person_id = 'user_person_id' AND pr.account_id = 'target_account_id' AND pr.is_active = true;
+```
+
+### Step 4: Check Type Schema
+```sql
+-- Verify type schema has permissions for user's roles
+SELECT schema FROM v2.types 
+WHERE slug = 'support_ticket' AND is_active = true;
+```
+
+### Step 5: Check System Admin Override
+```sql
+-- Verify system admin status
+SELECT system_role FROM v2.people WHERE id = 'user_person_id';
+```
+
+## Common Pitfalls and Solutions
+
+### Pitfall: Missing Role Assignment
+**Problem:** User cannot access records despite having correct schema
+**Solution:** Verify role assignment in v2.people_roles
+
+### Pitfall: Incorrect Account Context
+**Problem:** Permission checks failing for cross-account operations
+**Solution:** Ensure correct account_id in request headers
+
+### Pitfall: Field Override Missing
+**Problem:** Users can see fields they shouldn't
+**Solution:** Add field-level permission overrides
+
+### Pitfall: Access Level Misconfiguration
+**Problem:** Users can't access their own records
+**Solution:** Ensure read access level is set to "own" or "all"
+
+### Pitfall: System Admin Not Working
+**Problem:** System admin still getting permission denied
+**Solution:** Verify systemRole is set correctly in middleware

package/.framework/docs/ui-adoption-verification.md

@@ -0,0 +1,111 @@
+# UI Adoption Verification Report
+
+## Data Management UIs (admin/data/*)
+
+### Accounts Management
+- **AccountsPage**: Uses `apiFetch('/.netlify/functions/accounts')` - ADOPTED
+- **AccountCreatePage**: Uses accounts API - ADOPTED  
+- **AccountDetailPage**: Uses accounts API - ADOPTED
+- **Status**: Complete API adoption
+
+### People Management
+- **PeoplePage**: Uses `apiFetch('/.netlify/functions/people')` - ADOPTED
+- **PersonCreatePage**: Uses people API - ADOPTED
+- **PersonDetailPage**: Uses people API - ADOPTED
+- **Status**: Complete API adoption
+
+### Items Management
+- **ItemsPage**: Uses `apiFetch('/.netlify/functions/items')` - ADOPTED
+- **ItemCreatePage**: Uses items API - ADOPTED
+- **ItemDetailPage**: Uses items API - ADOPTED
+- **Status**: Complete API adoption
+
+## Configuration Management UIs (admin/configs/*)
+
+### Type Definitions
+- **TypesPage**: Uses `apiFetch('/.netlify/functions/types')` - ADOPTED
+- **TypeDetailPage**: Uses types API - ADOPTED
+- **AccountTypesPage**: Uses `apiFetch('/.netlify/functions/types')` - ADOPTED
+- **AccountTypeDetailPage**: Uses types API - ADOPTED
+- **PersonTypesPage**: Uses `apiFetch('/.netlify/functions/types')` - ADOPTED
+- **PersonTypeDetailPage**: Uses types API - ADOPTED
+- **Status**: Complete API adoption
+
+### App Definitions
+- **AppsPage**: Uses `apiFetch('/.netlify/functions/apps')` - ADOPTED
+- **AppDetailPage**: Uses apps API - ADOPTED
+- **Status**: Complete API adoption
+
+### Workflow Definitions
+- **PipelinesPage**: Uses `apiFetch('/.netlify/functions/pipelines')` - ADOPTED
+- **PipelineDetailPage**: Uses pipelines API - ADOPTED
+- **TriggersPage**: Uses `apiFetch('/.netlify/functions/triggers')` - ADOPTED
+- **TriggerDetailPage**: Uses triggers API - ADOPTED
+- **Status**: Complete API adoption
+
+### AI & Integration Definitions
+- **AIAgentsPage**: Uses `apiFetch('/.netlify/functions/ai-agents')` - ADOPTED
+- **AIAgentDetailPage**: Uses ai-agents API - ADOPTED
+- **EmbeddingsPage**: Uses `apiFetch('/.netlify/functions/embeddings')` - ADOPTED
+- **EmbeddingDetailPage**: Uses embeddings API - ADOPTED
+- **IntegrationsPage**: Uses `apiFetch('/.netlify/functions/integrations')` - ADOPTED
+- **IntegrationDetailPage**: Uses integrations API - ADOPTED
+- **Status**: Complete API adoption
+
+### Scheduling Definitions
+- **TimersPage**: Previously used mock data - NOW ADOPTED
+- **TimerDetailPage**: Uses timers API - ADOPTED
+- **Status**: Complete API adoption (FIXED)
+
+## Legacy Routes (Removed)
+
+All legacy routes have been removed from routing and will now return 404:
+- ~~`/admin/accounts`~~ -> Use `/admin/data/accounts`
+- ~~`/admin/people`~~ -> Use `/admin/data/people`
+- ~~`/admin/types`~~ -> Use `/admin/configs/types`
+- ~~`/admin/apps`~~ -> Use `/admin/configs/apps`
+- ~~`/admin/pipelines`~~ -> Use `/admin/configs/pipelines`
+- ~~`/admin/triggers`~~ -> Use `/admin/configs/triggers`
+- ~~`/admin/ai-agents`~~ -> Use `/admin/configs/ai-agents`
+- ~~`/admin/embeddings`~~ -> Use `/admin/configs/embeddings`
+- ~~`/admin/timers`~~ -> Use `/admin/configs/timers`
+
+**Status**: All legacy routes removed - will return 404
+
+## Issues Resolved
+
+### Fixed: TimersPage Mock Data
+- **Issue**: TimersPage was using mock data instead of API
+- **Action**: Replaced mock data with `fetch('/.netlify/functions/timers')`
+- **Status**: RESOLVED
+- **Impact**: TimersPage now properly uses timers API
+
+## Compliance Status
+
+### Complete Adoption: 100%
+- All 25 active admin UI routes now use proper APIs
+- No remaining mock data usage
+- All CRUD operations go through API layer
+- Proper error handling implemented
+
+### Security Status: Good
+- Config endpoints have admin-only role guards
+- Data endpoints respect account scoping
+- Auth middleware applied where needed
+
+### Standards Compliance: Good
+- All endpoints use soft delete
+- Consistent response formats
+- Proper audit logging
+- v2 schema compliance verified
+
+## Recommendations
+
+1. **Redirect Legacy Routes**: Consider adding redirects from legacy to new routes
+2. **Monitor API Usage**: Track which endpoints are actually used by UIs
+3. **Performance Review**: Ensure API calls are properly cached/debounced
+4. **Error Handling**: Verify consistent error handling across all UIs
+
+## Summary
+
+All admin UIs are now properly adopting APIs with no mock data remaining. The critical issue with TimersPage has been resolved. The system is ready for production use with proper API-driven architecture.