spine-framework 0.1.0

package/.framework/functions/_shared/app-manifest.ts

@@ -0,0 +1,184 @@
+/**
+ * @module app-manifest
+ * @audience core-contributor
+ * @layer shared-util
+ * @stability evolving
+ *
+ * Utility for loading and merging app manifests with database records.
+ * Enables file-first app configuration with database tracking installations.
+ *
+ * **Pattern:**
+ * 1. Manifest files in custom/apps/{slug}/manifest.json are source of truth
+ * 2. Database tracks which tenant has which app installed/enabled
+ * 3. This utility merges both sources for the API response
+ *
+ * @seeAlso apps.ts (uses this for manifest-driven responses)
+ * @seeAlso 015_simplify_apps_table.sql (database structure)
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'fs'
+import { resolve, join } from 'path'
+
+export interface AppManifest {
+  name: string
+  slug: string
+  description?: string
+  version?: string
+  required_roles: string[]  // Migrated from min_role (string) to array
+  routes: string[]
+  nav_items: NavItem[]
+  features?: string[]
+  dependencies?: string[]
+  entry_point: string
+  is_public?: boolean
+  auth_required?: boolean
+}
+
+export interface NavItem {
+  title: string
+  path: string
+  icon?: string
+  order?: number
+  children?: NavItem[]
+}
+
+// Cache for manifest content (development mode - no caching in production)
+const manifestCache = new Map<string, AppManifest>()
+
+/**
+ * Loads a manifest.json file from the filesystem.
+ * 
+ * @param manifestPath - Relative path to manifest (e.g., 'custom/apps/cortex/manifest.json')
+ * @returns Parsed manifest or null if not found
+ */
+export function loadManifest(manifestPath: string): AppManifest | null {
+  // Check cache first (dev only)
+  if (manifestCache.has(manifestPath)) {
+    return manifestCache.get(manifestPath)!
+  }
+
+  try {
+    // Resolve from project root (functions are at .assembled/netlify/functions/)
+    const projectRoot = resolve(__dirname, '../../../..')
+    const fullPath = resolve(projectRoot, manifestPath)
+    
+    const content = readFileSync(fullPath, 'utf-8')
+    const manifest: AppManifest = JSON.parse(content)
+    
+    // Validate required fields
+    if (!manifest.slug || !manifest.name) {
+      console.error(`[app-manifest] Invalid manifest at ${manifestPath}: missing slug or name`)
+      return null
+    }
+    
+    // Ensure required_roles is array (backward compat)
+    if (!manifest.required_roles) {
+      manifest.required_roles = []
+    }
+    
+    // Cache for development (dev server restarts clear cache)
+    manifestCache.set(manifestPath, manifest)
+    
+    return manifest
+  } catch (err) {
+    console.error(`[app-manifest] Failed to load ${manifestPath}:`, err)
+    return null
+  }
+}
+
+/**
+ * Clears the manifest cache. Useful for testing.
+ */
+export function clearManifestCache(): void {
+  manifestCache.clear()
+}
+
+/**
+ * Merges database app record with manifest data.
+ * Manifest takes precedence for metadata fields.
+ * 
+ * @param dbRecord - App record from app_definitions table
+ * @returns Merged app data for API response
+ */
+export function mergeWithManifest(dbRecord: any): any {
+  if (!dbRecord) return null
+  
+  // If no manifest path, return DB record as-is (legacy mode)
+  if (!dbRecord.manifest_path || dbRecord.config_source !== 'manifest') {
+    // Convert legacy min_role to required_roles for frontend compatibility
+    return {
+      ...dbRecord,
+      required_roles: dbRecord.min_role ? [dbRecord.min_role] : [],
+      _source: 'database'
+    }
+  }
+  
+  // Load manifest and merge
+  const manifest = loadManifest(dbRecord.manifest_path)
+  if (!manifest) {
+    console.warn(`[app-manifest] Could not load manifest for ${dbRecord.slug}, falling back to DB`)
+    return {
+      ...dbRecord,
+      required_roles: dbRecord.min_role ? [dbRecord.min_role] : [],
+      _source: 'database (manifest missing)'
+    }
+  }
+  
+  // Merge: Manifest metadata + DB state fields
+  return {
+    id: dbRecord.id,
+    slug: manifest.slug,
+    name: manifest.name,
+    description: manifest.description || dbRecord.description,
+    
+    // Role-based access (new array format)
+    required_roles: manifest.required_roles,
+    min_role: manifest.required_roles[0] || null, // Backward compat
+    
+    // Navigation and routing
+    routes: manifest.routes,
+    nav_items: manifest.nav_items,
+    
+    // Features and metadata
+    features: manifest.features || [],
+    dependencies: manifest.dependencies || [],
+    version: manifest.version,
+    
+    // Database state fields
+    is_active: dbRecord.is_active,
+    is_system: dbRecord.is_system,
+    is_public: manifest.is_public ?? false,
+    auth_required: manifest.auth_required ?? true,
+    
+    // Installation tracking
+    account_id: dbRecord.account_id,
+    pack_id: dbRecord.pack_id,
+    ownership: dbRecord.ownership,
+    
+    // Internal
+    _source: 'manifest',
+    _manifest_path: dbRecord.manifest_path
+  }
+}
+
+/**
+ * Lists all available manifests from filesystem.
+ * Used for initial discovery before database tracking.
+ * 
+ * @returns Array of discovered app slugs and their paths
+ */
+export function discoverManifests(): Array<{slug: string, path: string}> {
+  const appsDir = resolve(process.cwd(), 'custom/apps')
+  if (!existsSync(appsDir)) return []
+
+  const results: Array<{slug: string, path: string}> = []
+  for (const entry of readdirSync(appsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue
+    if (entry.name === 'lib' || entry.name.startsWith('.')) continue
+    const manifestPath = join('custom/apps', entry.name, 'manifest.json')
+    if (existsSync(resolve(process.cwd(), manifestPath))) {
+      results.push({ slug: entry.name, path: manifestPath })
+    }
+  }
+  return results
+}

package/.framework/functions/_shared/audit.ts

@@ -0,0 +1,150 @@
+/**
+ * @module audit
+ * @audience both
+ * @layer shared-core
+ * @stability stable
+ *
+ * Unified audit logging for all operations in Spine. Every state-changing
+ * operation should call `emitAudit` to write a structured row to the `logs`
+ * table with full principal provenance. Audit failures never throw — a failed
+ * log write must never break the operation that triggered it.
+ *
+ * INVARIANT: always call `emitAudit` after a successful write, not before.
+ *   Pass `result: 'failure'` only when the operation itself failed.
+ * INVARIANT: never pass sensitive secrets (API keys, tokens) in metadata.
+ *
+ * @seeAlso principal.ts (formatPrincipalForAudit — shapes the principal field)
+ * @seeAlso middleware.ts (CoreContext — ctx.requestId ties logs to HTTP requests)
+ * @seeAlso logs.ts (API handler that queries the logs table)
+ * @seeAlso permissions.ts (getPrincipalPermissionSummary — used in metadata)
+ */
+
+import { CoreContext } from './middleware'
+import { adminDb } from './db'
+import { Principal, formatPrincipalForAudit } from './principal'
+
+// ─── PRIMARY AUDIT FUNCTION ───────────────────────────────────────────────────
+
+// ─── CHUNK_START: SHARED_AUDIT_EMIT ──────────────────────────────────────────────
+/**
+ * @chunk-id    SHARED_AUDIT_EMIT_1_0_0
+ * @version     1.0.0
+ * @hash        d9c3dbc103f5f2f0543dc4c154bbad256e59c885643a20bc20ca07198eabd67c
+ * @macro       Audit Log Emitter
+ * @micro       Writes structured audit logs to logs table with principal provenance
+ * @inputs      ctx: CoreContext — Request context with principal and database
+ * @inputs      action: string — Dot-namespaced action (e.g. 'items.create')
+ * @inputs      target: {type, id?, account_id?} — Resource being acted upon
+ * @inputs      metadata: {changes?, result?, error?, ...} — Optional context
+ * @outputs     void — Always resolves, never rejects
+ * @depends-on  [adminDb, formatPrincipalForAudit]
+ * @depended-by [All state-changing API functions, pipeline-runner, trigger-engine]
+ * @side-effects [DB insert to logs table, console.error on failure]
+ * @tags        audit, logging, security, compliance
+ */
+export async function emitAudit(
+  ctx: CoreContext,
+  action: string,
+  target: { type: string; id?: string; account_id?: string },
+  metadata?: {
+    changes?: { before?: any; after?: any }
+    result?: 'success' | 'failure' | 'denied'
+    error?: string
+    [key: string]: any
+  }
+): Promise<void> {
+  try {
+    // Use the RLS-scoped db from context, or fallback to adminDb
+    const logDb = ctx.db || adminDb
+    
+    await logDb.from('logs').insert({
+      level: metadata?.result === 'failure' || metadata?.result === 'denied' ? 'warning' : 'info',
+      source: 'audit',
+      message: `${action} by ${ctx.principal?.type || 'unknown'}:${ctx.principal?.id || 'anonymous'}`,
+      metadata: {
+        principal: ctx.principal ? formatPrincipalForAudit(ctx.principal) : null,
+        action,
+        target: {
+          type: target.type,
+          id: target.id,
+          account_id: target.account_id || ctx.accountId
+        },
+        request_id: ctx.requestId,
+        ...metadata
+      },
+      account_id: target.account_id || ctx.accountId || ctx.principal?.accountId || null
+    })
+  } catch (err) {
+    console.error('Failed to emit audit log:', err)
+    // Don't throw - audit failures shouldn't break operations
+  }
+}
+// ─── CHUNK_END: SHARED_AUDIT_EMIT ────────────────────────────────────────────────
+
+// ─── LEGACY EXPORTS ───────────────────────────────────────────────────────────
+
+// ─── CHUNK_START: SHARED_AUDIT_EMIT_LOG ──────────────────────────────────────────────
+/**
+ * @chunk-id    SHARED_AUDIT_EMIT_LOG_1_0_0
+ * @version     1.0.0
+ * @hash        148fb1ce7badf1d3df08e2daa38bac4c084c94ba2f262c782c9df092a22890dd
+ * @macro       Legacy Audit Log Wrapper
+ * @micro       Backward compatibility wrapper around emitAudit
+ * @inputs      ctx: CoreContext — Request context
+ * @inputs      eventType: string — Action string (maps to emitAudit's action)
+ * @inputs      target: {type, id} | undefined — Resource target
+ * @inputs      changes: {before?, after?} | undefined — Change data
+ * @inputs      metadata: Record<string, any> — Additional context
+ * @outputs     void — Always resolves
+ * @depends-on  [emitAudit]
+ * @depended-by [Legacy code, should not be used in new code]
+ * @side-effects [DB insert via emitAudit, console.error on failure]
+ * @tags        audit, logging, legacy, wrapper, deprecated
+ */
+export async function emitLog(
+  ctx: CoreContext,
+  eventType: string,
+  target?: { type: string; id: string },
+  changes?: { before?: any; after?: any },
+  metadata: Record<string, any> = {}
+): Promise<void> {
+  try {
+    await emitAudit(ctx, eventType, {
+      type: target?.type || 'unknown',
+      id: target?.id,
+      account_id: ctx.accountId || undefined
+    }, {
+      changes,
+      ...metadata
+    })
+  } catch (error) {
+    console.error('Failed to emit log:', error)
+    // Don't throw - logging failures shouldn't break operations
+  }
+}
+// ─── CHUNK_END: SHARED_AUDIT_EMIT_LOG ────────────────────────────────────────────────
+
+// ─── CHUNK_START: SHARED_AUDIT_EMIT_ACTIVITY ──────────────────────────────────────────────
+/**
+ * @chunk-id    SHARED_AUDIT_EMIT_ACTIVITY_1_0_0
+ * @version     1.0.0
+ * @hash        58e532a743fdae480ca24d311be66e82612477309270ec7462fd7dfd695d5282
+ * @macro       Legacy Activity Logger
+ * @micro       Wraps emitLog with activity. prefix for backward compatibility
+ * @inputs      ctx: CoreContext — Request context
+ * @inputs      type: string — Activity type (prefixed with 'activity.')
+ * @inputs      details: Record<string, any> — Metadata context
+ * @outputs     void — Always resolves
+ * @depends-on  [emitLog]
+ * @depended-by [Legacy code, should not be used in new code]
+ * @side-effects [DB insert via emitLog → emitAudit, console.error on failure]
+ * @tags        audit, logging, legacy, activity, deprecated
+ */
+export async function emitActivity(
+  ctx: CoreContext,
+  type: string,
+  details: Record<string, any> = {}
+): Promise<void> {
+  await emitLog(ctx, `activity.${type}`, undefined, undefined, details)
+}
+// ─── CHUNK_END: SHARED_AUDIT_EMIT_ACTIVITY ────────────────────────────────────────────────

package/.framework/functions/_shared/db.ts

@@ -0,0 +1,174 @@
+/**
+ * @module db
+ * @audience both
+ * @layer shared-core
+ * @stability stable
+ *
+ * Supabase client factory and PostgREST join helpers. This module owns the
+ * two-client pattern that is central to Spine's security model: `adminDb`
+ * bypasses RLS for system operations; `getUserDb` enforces RLS for all
+ * human-principal requests. Never use `adminDb` for user-scoped queries —
+ * doing so silently bypasses account isolation.
+ *
+ * @seeAlso principal.ts (getPrincipalDb selects between these two clients)
+ * @seeAlso middleware.ts (ctx.db is set from getPrincipalDb at request time)
+ */
+
+import { createClient } from '@supabase/supabase-js'
+
+// ─── ENVIRONMENT RESOLUTION ──────────────────────────────────────────────────
+
+const _env = (globalThis as any).process?.env || {}
+const supabaseUrl: string = _env.SUPABASE_URL!
+const supabaseServiceKey: string = _env.SUPABASE_SERVICE_ROLE_KEY!
+const supabaseAnonKey: string = _env.SUPABASE_ANON_KEY!
+
+/**
+ * Active database schema name, read from `DB_SCHEMA` env var.
+ *
+ * Defaults to `'public'` (production schema). Set to `'v2'` only in legacy
+ * environments. All new migrations target `public`.
+ *
+ * @inputSpec DB_SCHEMA: string — one of 'public' | 'v2'. Any other value is
+ *   passed through as-is and will cause runtime query errors.
+ * @outputSpec string — schema name applied to both Supabase clients.
+ * @sideEffects none
+ * @calledBy adminDb, getUserDb (applied at client construction time)
+ */
+const dbSchema: string = _env.DB_SCHEMA || 'public'
+
+// ─── CLIENTS ─────────────────────────────────────────────────────────────────
+
+/**
+ * Service-role Supabase client. Bypasses Row Level Security.
+ *
+ * Use this ONLY for:
+ * - System/cron operations that must cross account boundaries (`system-cron.ts`)
+ * - Principal resolution lookups (`principal.ts` — resolving auth_uid to person)
+ * - Machine principal validation RPCs
+ * - Test helpers that need to seed/clean data across accounts
+ *
+ * Do NOT use this in request handlers for user-scoped data reads or writes.
+ * Always prefer `ctx.db` (set by `getPrincipalDb` in middleware) for those.
+ *
+ * @inputSpec SUPABASE_URL: string — valid Supabase project URL, required
+ * @inputSpec SUPABASE_SERVICE_ROLE_KEY: string — service role JWT, required
+ * @outputSpec SupabaseClient — PostgREST client scoped to `dbSchema`, RLS disabled
+ * @sideEffects none (client construction only)
+ * @calledBy principal.ts, middleware.ts, system-cron.ts, permissions.ts,
+ *   tests/integration/helpers.ts
+ * @calls createClient (supabase-js)
+ * @testUnit tests/unit/pipeline-runner.test.ts — mocked via vi.mock
+ * @testIntegration tests/integration/helpers.ts — used directly as adminDb
+ *
+ * @example API handler (system operation)
+ * ```ts
+ * import { adminDb } from './_shared/db'
+ * const { data } = await adminDb.from('types').select('*').eq('slug', 'item')
+ * ```
+ *
+ * @example Import usage (v2-custom/ — system-level only)
+ * ```ts
+ * import { adminDb } from '../_shared/index'
+ * // Only use adminDb if your custom code runs as a system/cron principal
+ * ```
+ */
+export const adminDb = createClient(supabaseUrl, supabaseServiceKey, {
+  db: {
+    schema: dbSchema
+  }
+})
+
+// ─── CHUNK_START: SHARED_DB_GET_USER_DB ──────────────────────────────────────────────
+/**
+ * @chunk-id    SHARED_DB_GET_USER_DB_1_0_0
+ * @version     1.0.0
+ * @hash        af3c792634c60ced1c1c4184cfc6c20add90ab97eb62f7e46bdf40ae2899a0f8
+ * @macro       User Database Client Factory
+ * @micro       Creates RLS-enforced Supabase client for specific user JWT
+ * @inputs      jwt: string — Valid Supabase JWT from Authorization header
+ * @outputs     SupabaseClient — PostgREST client with RLS enforced
+ * @depends-on  [createClient, supabaseUrl, supabaseAnonKey, dbSchema]
+ * @depended-by [principal.ts, middleware.ts]
+ * @side-effects [Client construction with Authorization header]
+ * @tags        database, supabase, rls, authentication, user-scoped
+ */
+export function getUserDb(jwt: string) {
+  return createClient(supabaseUrl, supabaseAnonKey, {
+    db: {
+      schema: dbSchema
+    },
+    global: {
+      headers: {
+        Authorization: `Bearer ${jwt}`
+      }
+    }
+  })
+}
+// ─── CHUNK_END: SHARED_DB_GET_USER_DB ────────────────────────────────────────────────
+
+// ─── TYPES ───────────────────────────────────────────────────────────────────
+
+/**
+ * Standard shape returned by all Supabase PostgREST queries.
+ *
+ * Both `data` and `error` follow the Supabase JS client convention: on success,
+ * `error` is null; on failure, `data` is null and `error` contains the Postgres
+ * error details. Always check `error` before using `data`.
+ *
+ * @inputSpec T — the expected shape of a successful result row
+ * @outputSpec data: T | null — the query result, null on error
+ * @outputSpec error: any — null on success, Postgres/PostgREST error object on failure
+ * @calledBy used as return type annotation across all functions/*.ts handlers
+ *
+ * @example
+ * ```ts
+ * const result: DbResult<Item> = await adminDb.from('items').select('*').single()
+ * if (result.error) throw result.error
+ * return result.data!
+ * ```
+ */
+export type DbResult<T> = {
+  data: T | null
+  error: any
+}
+
+// ─── JOIN HELPERS ─────────────────────────────────────────────────────────────
+
+/**
+ * PostgREST relationship hint strings for all foreign keys in the public schema.
+ *
+ * These strings are interpolated into `.select()` calls to eager-load related
+ * records in a single query. They use explicit `!fk_column` hints to resolve
+ * ambiguous relationships — required when a table has multiple FKs to the same
+ * target table, or when the FK column name doesn't follow PostgREST's default
+ * `tablename_id` inference convention (e.g. `created_by` → `people.id`).
+ *
+ * Only add a join here when it is used in two or more handlers. One-off joins
+ * should be written inline.
+ *
+ * @inputSpec none — these are static string constants
+ * @outputSpec string — valid PostgREST embed expression for use in .select()
+ * @sideEffects none
+ * @calledBy types.ts, apps.ts, pipelines.ts, triggers.ts, admin-data.ts, and others
+ * @testUnit none — these are string constants; incorrect joins fail at runtime
+ * @testIntegration tests/integration/admin-data-accounts.test.ts — exercises joins.type
+ *
+ * @example
+ * ```ts
+ * import { joins } from './_shared/db'
+ * const { data } = await ctx.db
+ *   .from('items')
+ *   .select(`*, ${joins.type}, ${joins.app}`)
+ * // Returns items with nested type and app objects
+ * ```
+ */
+export const joins = {
+  type:         'type:types!type_id(id, slug, name, icon, color, design_schema)',
+  app:          'app:apps!app_id(id, slug, name)',
+  ownerAccount: 'owner_account:accounts!owner_account_id(id, slug, display_name)',
+  createdBy:    'created_by_person:people!created_by(id, full_name, email)',
+  parentAccount:'parent:accounts!parent_id(id, slug, display_name)',
+  role:         'role:roles!role_id(id, slug, name)',
+  pipeline:     'pipeline:pipelines!pipeline_id(id, name)',
+}