spine-framework 0.1.0

package/.framework/cli/index.ts

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/// <reference types="node" />
+/**
+ * @module cli/index
+ * @audience installer
+ * @layer cli
+ * @stability stable
+ *
+ * Spine CLI entry point (`npx spine-framework`). Registers all command groups via
+ * Commander and delegates each subcommand to the same core logic used by
+ * API handlers and direct imports. No business logic lives here — only
+ * command registration and top-level error handling.
+ *
+ * **Command groups registered:**
+ * | Group       | File                       |
+ * |-------------|----------------------------|
+ * | auth        | commands/auth.ts           |
+ * | pipelines   | commands/pipelines.ts      |
+ * | items       | commands/items.ts          |
+ * | agents      | commands/agents.ts         |
+ * | migrations  | commands/migrations.ts     |
+ * | init        | commands/init.ts           |
+ * | install-app | commands/install-app.ts    |
+ * | status      | commands/status.ts         |
+ * | uninstall   | commands/uninstall-app.ts  |
+ *
+ * **Usage:**
+ * ```bash
+ * npx spine-framework --help
+ * npx spine-framework auth whoami
+ * npx spine-framework pipelines run <id> --data '{"key":"value"}'
+ * npx spine-framework items list --type support_ticket
+ * npx spine-framework items get <id>
+ * npx spine-framework agents run <thread-id> --message "Hello"
+ * npx spine-framework migrations list
+ * ```
+ *
+ * @seeAlso cli/context.ts (buildCliContext — constructs CoreContext for every command)
+ * @seeAlso functions/_shared/index.ts (core functions exposed to CLI)
+ */
+
+import './env-loader.ts'
+import { Command } from 'commander'
+
+const program = new Command()
+
+program
+  .name('spine-framework')
+  .description('Spine v2 CLI — interact with your Spine instance from the terminal or agentic IDE')
+  .version('2.0.0')
+  .option('--account <id>', 'Override the account ID for this command')
+
+const [
+  { registerAuthCommands },
+  { registerPipelineCommands },
+  { registerItemCommands },
+  { registerAgentCommands },
+  { registerMigrationCommands },
+  { registerDoctorCommands },
+  { registerDevCommands },
+  { registerTestCommands },
+  { registerSystemCommands },
+  { registerGenerateCommands },
+  { registerCreateAppCommands },
+  { registerInitCommands },
+  { registerInstallAppCommands },
+  { registerStatusCommands },
+  { registerUninstallAppCommands },
+] = await Promise.all([
+  import('./commands/auth.ts'),
+  import('./commands/pipelines.ts'),
+  import('./commands/items.ts'),
+  import('./commands/agents.ts'),
+  import('./commands/migrations.ts'),
+  import('./commands/doctor.ts'),
+  import('./commands/dev.ts'),
+  import('./commands/test.ts'),
+  import('./commands/system.ts'),
+  import('./commands/generate.ts'),
+  import('./commands/create-app.ts'),
+  import('./commands/init.ts'),
+  import('./commands/install-app.ts'),
+  import('./commands/status.ts'),
+  import('./commands/uninstall-app.ts'),
+])
+
+registerAuthCommands(program)
+registerPipelineCommands(program)
+registerItemCommands(program)
+registerAgentCommands(program)
+registerMigrationCommands(program)
+registerDoctorCommands(program)
+registerDevCommands(program)
+registerTestCommands(program)
+registerSystemCommands(program)
+registerGenerateCommands(program)
+registerCreateAppCommands(program)
+registerInitCommands(program)
+registerInstallAppCommands(program)
+registerStatusCommands(program)
+registerUninstallAppCommands(program)
+
+program.parseAsync(process.argv).catch((err) => {
+  console.error('Error:', err.message)
+  process.exit(1)
+})

package/.framework/cli/welcome.cjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// Postinstall welcome message — runs automatically after npm install spine-framework.
+// Tells the agent (or developer) exactly what to do next.
+// Uses only Node built-ins — no dependencies.
+
+const lines = [
+  '',
+  '╭──────────────────────────────────────────────────────────────╮',
+  '│                                                              │',
+  '│   ███████╗██████╗ ██╗███╗   ██╗███████╗                    │',
+  '│   ██╔════╝██╔══██╗██║████╗  ██║██╔════╝                    │',
+  '│   ███████╗██████╔╝██║██╔██╗ ██║█████╗                      │',
+  '│   ╚════██║██╔═══╝ ██║██║╚██╗██║██╔══╝                      │',
+  '│   ███████║██║     ██║██║ ╚████║███████╗                    │',
+  '│   ╚══════╝╚═╝     ╚═╝╚═╝  ╚═══╝╚══════╝  Framework v0.1   │',
+  '│                                                              │',
+  '╰──────────────────────────────────────────────────────────────╯',
+  '',
+  '  Spine Framework installed successfully!',
+  '',
+  '  To complete setup you need a Supabase project.',
+  '  ─────────────────────────────────────────────',
+  '  If you have one already, run:',
+  '',
+  '    spine-framework init \\',
+  '      --url       https://<project>.supabase.co \\',
+  '      --anon-key  <anon-key> \\',
+  '      --service-role-key <service-role-key>',
+  '',
+  '  Your credentials are at:',
+  '  Supabase Dashboard → Your Project → Settings → API',
+  '',
+  '  ─────────────────────────────────────────────',
+  '  If you need a Supabase project, create one at:',
+  '  https://supabase.com/dashboard → New project',
+  '',
+  '  After init:',
+  '    spine-framework install-app <app-slug>   # optional apps',
+  '    npm run assemble && netlify dev           # start dev server',
+  '',
+  '  Docs: https://github.com/art-mojo-admin/spine',
+  '',
+]
+
+console.log(lines.join('\n'))

package/.framework/docs/API.md

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

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

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

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