spine-framework 0.3.124 → 0.3.126

package/docs/dev-guides/05-testing.md

@@ -1,168 +0,0 @@
-# Guide 05: Testing Custom Code
-
-## What this guide covers
-
-How to test custom functions, components, and apps using the Spine test harness.
-
----
-
-## Test commands
-
-```bash
-npm run test               # All tests
-npm run test:unit          # Unit tests only (.framework/tests/unit/)
-npm run test:core          # Core isolation test (no custom code required)
-npm run test:integration   # Integration tests (requires running Supabase)
-npm run test:boundary      # Architectural boundary check
-```
-
----
-
-## Testing a custom function
-
-Use `makeTestContext` from the core testing utilities to create a mock `CoreContext`:
-
-```typescript
-// custom/tests/my-feature.test.ts
-import { describe, it, expect } from 'vitest'
-import { makeTestContext, mockPrincipal } from '@core/_shared/testing'
-
-// Import your handler's logic (not the Netlify wrapper)
-import { handler } from '../functions/custom_my-feature'
-
-describe('custom_my-feature', () => {
-  it('returns items for list action', async () => {
-    const ctx = makeTestContext({
-      principal: mockPrincipal({ roles: ['member'] }),
-      query: { action: 'list' },
-    })
-
-    const result = await handler({} as any, ctx)
-    expect(result.data).toBeDefined()
-    expect(Array.isArray(result.data)).toBe(true)
-  })
-
-  it('rejects unauthenticated requests', async () => {
-    const ctx = makeTestContext({ principal: null })
-
-    await expect(handler({} as any, ctx)).rejects.toThrow()
-  })
-})
-```
-
----
-
-## makeTestContext options
-
-```typescript
-makeTestContext({
-  principal?: Principal | null,  // defaults to a mock member principal
-  query?: Record<string, string>, // URL query params
-  body?: any,                     // parsed request body
-  db?: SupabaseClient,            // override with a real or mock DB client
-})
-```
-
----
-
-## mockPrincipal options
-
-```typescript
-mockPrincipal({
-  id?: string           // UUID, defaults to a stable test UUID
-  account_id?: string   // UUID, defaults to a stable test UUID
-  roles?: string[]      // defaults to ['member']
-  permissions?: string[]
-})
-```
-
----
-
-## Testing role-based access
-
-```typescript
-it('allows support role to access restricted data', async () => {
-  const ctx = makeTestContext({
-    principal: mockPrincipal({ roles: ['support'] }),
-    query: { action: 'list' },
-  })
-  const result = await handler({} as any, ctx)
-  expect(result.data).toBeDefined()
-})
-
-it('denies member role from restricted endpoint', async () => {
-  const ctx = makeTestContext({
-    principal: mockPrincipal({ roles: ['member'] }),
-    query: { action: 'admin_list' },
-  })
-  await expect(handler({} as any, ctx)).rejects.toThrow('required')
-})
-```
-
----
-
-## Boundary check
-
-The boundary check verifies that core never imports from custom, and that custom apps use `@core` aliases (not relative paths to `.framework/`):
-
-```bash
-npm run test:boundary
-# or
-bash scripts/boundary-check.sh
-```
-
-Run this before any PR. The GitHub Actions CI also runs it automatically.
-
-**What it checks:**
-1. No `from 'custom/'` or `import @custom` in `.framework/`
-2. No `from 'custom_'` module imports in `.framework/`
-3. No relative paths to `.framework/` from `custom/` (must use `@core`)
-4. No app-specific slugs hardcoded in `.framework/src/`
-
----
-
-## Running core tests in isolation
-
-Core tests must pass without any custom code present:
-
-```bash
-npm run test:core
-```
-
-This verifies the architectural boundary holds — if core tests fail, it means core has leaked a dependency on custom code.
-
----
-
-## Integration tests
-
-Integration tests require a running Supabase instance. Set your `.env` before running:
-
-```bash
-# .env
-SUPABASE_URL=http://localhost:54321
-SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
-
-npm run test:integration
-```
-
----
-
-## File locations
-
-```
-.framework/tests/
-  unit/
-    core-isolation.test.ts    ← core tests with no custom deps
-    permissions.test.ts
-    pipeline-runner.test.ts
-  integration/
-    admin-data-accounts.test.ts
-    isolation.test.ts
-    ...
-  fixtures/
-    seed.ts                   ← test data seeding
-    teardown.ts
-
-custom/tests/                 ← your custom tests go here (create this dir)
-  my-feature.test.ts
-```

package/docs/dev-guides/README.md

@@ -1,40 +0,0 @@
-# Spine Developer Guides
-
-Guides for building custom apps, functions, and components on Spine Core.
-
-## Guides
-
-| Guide | What it covers |
-|-------|---------------|
-| [01-create-an-app.md](./01-create-an-app.md) | Scaffold, configure, and register a new custom app |
-| [02-create-a-function.md](./02-create-a-function.md) | Write a custom Netlify function using core utilities |
-| [03-create-a-component.md](./03-create-a-component.md) | Build a React component inside a custom app |
-| [04-webhook-handlers.md](./04-webhook-handlers.md) | Register a webhook handler without touching core |
-| [05-testing.md](./05-testing.md) | Test custom code using the core test harness |
-
-## Architecture in One Sentence
-
-> **Core provides mechanism. Custom provides data.**
-
-Core never imports from `custom/`. Custom code imports from core using the `@core` alias.
-
-## Key Paths
-
-| Path | Purpose |
-|------|---------|
-| `custom/apps/{slug}/` | Your app lives here |
-| `custom/apps/{slug}/manifest.json` | App metadata, routes, roles |
-| `custom/apps/{slug}/index.tsx` | React entry point |
-| `custom/apps/{slug}/components/` | App-specific components |
-| `custom/functions/` | Custom Netlify functions |
-| `.framework/functions/_shared/` | Core utilities (import via `@core/_shared`) |
-
-## Quick Start
-
-```bash
-# 1. Scaffold a new app (creates files + registers in DB)
-npm run spine-framework create-app my-app -- --name "My App" --role member
-
-# 2. Assemble and run
-npm run assemble && netlify dev
-```

package/docs/npm-packages-plan.md

@@ -1,288 +0,0 @@
-# Spine npm Packages Plan
-
-**Created:** May 28, 2026  
-**Version target:** 0.x (breaking change freedom until stable)  
-**CLI standard:** All commands via `spine-framework` — no shorthand aliases  
-**Status:** Planning  
-
----
-
-## Goal
-
-Publish Spine Core and its apps as independent npm packages that any developer or agentic IDE can install and run from scratch.
-
-```bash
-npm install spine-framework
-spine-framework init                              # stand up DB schema + seed
-spine-framework install-app spine-framework-cortex
-spine-framework install-app spine-framework-portal
-npm run assemble && netlify dev
-```
-
----
-
-## Package Model
-
-### Three packages, one dependency direction
-
-```
-spine-framework                    ← core platform, no spine dependencies
-spine-framework-cortex             → peerDep: spine-framework
-spine-framework-portal             → peerDep: spine-framework
-```
-
-No cross-dependency between `spine-framework-cortex` and `spine-framework-portal`. Each is wholly self-sufficient.
-
-### What each package contains
-
-**spine-framework**
-- Core DB schema (`000_foundation.sql`) and seed data (`001_seed.sql`)
-- Core Netlify functions (auth, items, pipelines, accounts, people, webhooks, etc.)
-- Core frontend shell (routing, auth context, AppShell, UI primitives, hooks)
-- CLI (`spine-framework init`, `spine-framework create-app`, `spine-framework migrate`, etc.)
-- Assembly scripts
-- Public API surface (`_shared/index.ts`)
-
-**spine-framework-cortex**
-- Frontend: all Cortex pages, components, sidebar
-- `manifest.json` — routes, roles, nav
-- `seed/types.json` — type definitions Cortex needs upserted on install
-- No DB migrations, no owned tables
-
-**spine-framework-portal**
-- Frontend: all Portal pages, components, sidebar
-- `manifest.json` — routes, roles, nav
-- `seed/types.json` — type definitions Portal needs upserted on install
-- No DB migrations, no owned tables
-
-### App data model principle
-
-> Apps never touch DB structure. Apps upsert type records into core's `types` table using `design_schema` to define their data shape.
-
-Cortex and Portal share the same core tables (`items`, `types`, `accounts`, `people`). They are independent — no imports between them.
-
----
-
-## Phases
-
-### Phase 1: Merge + Production Validation
-**Goal:** Ship current state to prod, verify nothing is broken before forking.
-
-**Checklist:**
-- [ ] Migrations 014 (webhook registry) and 015 (apps table simplify) applied in prod
-- [ ] All apps load correctly (manifest-driven routing works)
-- [ ] Webhook registry doesn't break existing integrations
-- [ ] Boundary check passes (`npm run test:boundary`)
-- [ ] Demo site functional
-
-**Branch:** `main`  
-**Timeline:** Before demo (2 weeks)
-
----
-
-### Phase 2: Fork for npm Work
-**Goal:** Protect the stable demo branch while doing structural npm work.
-
-**Actions:**
-- Create branch `v0-npm-packages` from `main` after Phase 1 merges
-- All Phases 3–6 happen on `v0-npm-packages`
-- `main` remains the demo-stable branch
-- Merge back only when end-to-end install story is verified
-
-**Branch:** `v0-npm-packages`
-
----
-
-### Phase 3: Migrations Audit + Foundation SQL
-**Goal:** Single authoritative schema for a fresh install. The critical path item — nothing else in this plan works without it.
-
-**Decisions to make before writing SQL:**
-- [x] ~~Include `links` table in core?~~ **Resolved: yes.** `links` and `link_types` already exist in production with 21 rows. Goes in `000_foundation.sql`.
-- [ ] Which types are core seed data vs app seed data? System roles yes. Default item types — draw the line.
-- [ ] RLS policy audit — capture all policies explicitly (easily missed in schema dumps)
-- [ ] ⚠️ `account_paths`, `test_runs`, `test_results` have RLS disabled — decide on policies before including in foundation SQL
-
-**Deliverables:**
-- [ ] Audit document: current live DB schema vs migration files — flag all drift
-- [ ] `000_foundation.sql` — creates all core tables, indexes, constraints, RLS policies, functions, triggers in correct dependency order. **Confirmed tables (34 total):** `accounts`, `people`, `types`, `apps`, `roles`, `items`, `threads`, `messages`, `links`, `link_types`, `attachments`, `watchers`, `pipelines`, `pipeline_executions`, `triggers`, `trigger_executions`, `timers`, `ai_agents`, `embeddings`, `integrations`, `prompt_configs`, `api_keys`, `api_key_usage_logs`, `logs`, `actions`, `schedules`, `schedule_executions`, `account_paths`, `test_runs`, `test_results`, `item_progress`, `webhook_handlers`, `app_installations`, `embeddings`
-- [ ] `001_seed.sql` — inserts: system roles, core link types (`account_signals`, `account_opportunities`), bootstrap data core needs to boot. **App-owned link types (`tagged_with`, `analyzed_by`) go in app seed, not here.**
-- [ ] Old migrations moved to `archive/migrations/` with a `README` marking them historical
-
-**Verification:**
-```bash
-# Must pass: blank Supabase project + run 000 + 001 = working app
-spine-framework init   # runs 000_foundation.sql then 001_seed.sql
-```
-
----
-
-### Phase 4: Separate Core, Cortex, Portal
-**Goal:** Each is an independently packageable unit with no cross-contamination.
-
-**Core separation:**
-- [ ] Verify `.framework/` has zero imports from `custom/`
-- [ ] Verify `.framework/` has zero Cortex/Portal-specific references
-- [ ] Boundary check extended to catch Cortex↔Portal cross-imports
-
-**Cortex separation:**
-- [ ] All Cortex frontend confirmed in `custom/apps/cortex/`
-- [ ] Extract Cortex type definitions from live DB → `custom/apps/cortex/seed/types.json`
-- [ ] Extract Cortex link types (`tagged_with`, `analyzed_by`) → `custom/apps/cortex/seed/link-types.json`
-- [x] ~~Verify no Portal imports in Cortex~~ **Confirmed clean** (validated May 28, 2026)
-- [x] ~~Verify Cortex imports only from `@core` and its own files~~ **Confirmed clean**
-
-**Portal separation:**
-- [ ] All Portal frontend confirmed in `custom/apps/customer-portal/`
-- [ ] Extract Portal type definitions from live DB → `custom/apps/customer-portal/seed/types.json`
-- [ ] Extract any Portal-owned link types → `custom/apps/customer-portal/seed/link-types.json`
-- [x] ~~Verify no Cortex imports in Portal~~ **Confirmed clean** (validated May 28, 2026)
-- [x] ~~Verify Portal imports only from `@core` and its own files~~ **Confirmed clean**
-
-**End state directory map:**
-```
-spine-framework/          ← becomes the spine-framework npm package
-  .framework/
-    functions/
-    src/
-    migrations/
-      000_foundation.sql
-      001_seed.sql
-    cli/
-
-spine-framework-cortex/   ← becomes the spine-framework-cortex npm package
-  manifest.json
-  index.tsx
-  components/
-  pages/
-  seed/
-    types.json
-
-spine-framework-portal/   ← becomes the spine-framework-portal npm package
-  manifest.json
-  index.tsx
-  components/
-  pages/
-  seed/
-    types.json
-```
-
----
-
-### Phase 5: npm Packages
-**Goal:** Three publishable packages with working install flows.
-
-**spine-framework package.json additions:**
-```json
-{
-  "name": "spine-framework",
-  "version": "0.1.0",
-  "private": false,
-  "bin": {
-    "spine-framework": "./dist/cli/index.js"
-  },
-  "exports": {
-    "./_shared": "./dist/functions/_shared/index.js",
-    "./src/*": "./dist/src/*"
-  }
-}
-```
-
-**spine-framework-cortex / spine-framework-portal package.json:**
-```json
-{
-  "name": "spine-framework-cortex",
-  "version": "0.1.0",
-  "private": false,
-  "peerDependencies": {
-    "spine-framework": ">=0.1.0"
-  }
-}
-```
-
-**CLI commands to build/verify:**
-
-| Command | Description |
-|---------|-------------|
-| `spine-framework init` | Run 000 + 001 migrations against configured Supabase project |
-| `spine-framework migrate` | Run pending migrations |
-| `spine-framework install-app spine-framework-cortex` | Copy app files + upsert type seed records |
-| `spine-framework uninstall-app spine-framework-cortex` | Remove app record + type seed records |
-| `spine-framework create-app <slug>` | Scaffold a new custom app |
-| `spine-framework status` | Show installed apps and migration state |
-
-**Build pipeline:**
-- [ ] Add `tsc` build step for functions and CLI → `dist/`
-- [ ] Add Vite library mode build for frontend components → `dist/src/`
-- [ ] Generate `.d.ts` type declarations
-- [ ] `prepublishOnly` script runs build + boundary check + tests
-
-**Registry:** GitHub Packages (private) first. Public npm only after end-to-end install verified.
-
----
-
-### Phase 6: End-to-End Install Verification
-**Goal:** Prove the install story works from a completely blank starting point. Must pass before any publish.
-
-**Fresh install checklist:**
-- [ ] Blank Supabase project (no existing schema)
-- [ ] `npm install spine-framework`
-- [ ] `spine-framework init` → DB schema created, seed data present, app boots
-- [ ] Admin panel functional
-- [ ] `spine-framework install-app spine-framework-cortex` → Cortex loads, type records seeded
-- [ ] `spine-framework install-app spine-framework-portal` → Portal loads, type records seeded
-- [ ] Both apps functional and independent
-- [ ] `spine-framework create-app my-test` → scaffolds correctly
-- [ ] `npm run assemble && netlify dev` → dev server runs cleanly
-
-**This checklist is the publish gate. All items must pass.**
-
----
-
-### Phase 7: Documentation
-**Goal:** A developer or agentic IDE can go from zero to running in one session.
-
-**Docs needed:**
-
-| Document | Audience |
-|----------|---------|
-| Getting Started (from zero) | New developer / agentic IDE |
-| `spine-framework init` walkthrough | Developer |
-| Installing apps | Developer |
-| Building a custom app | Developer (dev-guides already exist) |
-| Core API reference | Developer (API.md exists, extend) |
-| Upgrade guide | Existing Spine developer |
-| Contributing to core | Core contributor |
-
----
-
-## Decisions Log
-
-| Decision | Choice | Rationale |
-|----------|--------|-----------|
-| Version target | `0.x` | Breaking change freedom until stable |
-| CLI namespace | `spine-framework` only | No shorthand aliases |
-| App DB model | Type records only, no app-owned tables | Clean install, clean uninstall, no schema drift |
-| Cortex ↔ Portal | Fully independent, no cross-imports | Each is self-sufficient |
-| Shared type records | Both apps use same core tables | Core owns schema, apps own their type definitions |
-| Registry | GitHub Packages (private) → npm (public) | Validate before exposing |
-| Links table | **In core** — `links` + `link_types` in `000_foundation.sql` | Already live in production with 21 rows. `app_id` column on `link_types` distinguishes core vs app-owned relationship types. |
-| App-owned link types | Seeded by app (`seed/link-types.json`), not by core | `tagged_with`, `analyzed_by` are Cortex-owned; `account_signals`, `account_opportunities` are core-owned |
-
----
-
-## Open Questions
-
-1. **Supabase project config** — How does `spine-framework init` know which Supabase project to target? `.env` file, interactive prompt, or CLI flag?
-2. **Assembly in package model** — Does `assemble.sh` read from `node_modules/spine-framework-cortex/` after install, or does `install-app` copy files into `custom/apps/`? Copy is simpler and matches current model.
-3. **Frontend build** — Does `spine-framework` ship pre-built frontend components (library mode) or source that gets assembled into the host project? Source + assemble matches current model and avoids Vite/React version conflicts.
-4. **RLS on `account_paths`, `test_runs`, `test_results`** — These 3 tables have RLS disabled in production. Decide on policies before writing `000_foundation.sql`. Without policies, enabling RLS will block all access.
-
----
-
-## Related Documents
-
-- `docs/enterprise-framework-implementation-summary.md` — current state of enterprise framework work
-- `docs/dev-guides/` — developer guides for building on Spine (Phases 3–7 prerequisite)
-- `.framework/API.md` — public API surface
-- `.framework/migrations/` — current migration files (to be audited in Phase 3)
-- `scripts/boundary-check.sh` — architectural boundary enforcement