spine-framework 0.2.1 → 1.0.0

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

@@ -1,184 +0,0 @@
-/**
- * @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

@@ -1,150 +0,0 @@
-/**
- * @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

@@ -1,178 +0,0 @@
-/**
- * @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'
-import WebSocket from 'ws'
-
-// WebSocket constructor for Supabase Realtime in Node.js environment
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const RealtimeWebSocket = WebSocket as any
-
-// ─── ENVIRONMENT RESOLUTION ──────────────────────────────────────────────────
-
-/**
- * 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 _env = (globalThis as any).process?.env || {}
-const supabaseUrl: string = _env.SUPABASE_URL || 'https://placeholder.supabase.co'
-const supabaseServiceKey: string = _env.SUPABASE_SERVICE_ROLE_KEY || ''
-const supabaseAnonKey: string = _env.SUPABASE_ANON_KEY || ''
-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 },
-  auth: { autoRefreshToken: false, persistSession: false },
-  realtime: { transport: RealtimeWebSocket }
-})
-
-// ─── 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 },
-    auth: { autoRefreshToken: false, persistSession: false },
-    realtime: { transport: RealtimeWebSocket },  // WebSocket for Node.js 20+
-    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)',
-}