spine-framework 0.2.1 → 1.0.0

package/.framework/functions/types.ts

@@ -1,604 +0,0 @@
-/**
- * @module types
- * @audience core-contributor
- * @layer api-handler
- * @stability stable
- *
- * CRUD API for the `types` table. Types are the schema configuration objects
- * that define `design_schema`, `validation_schema`, field definitions, and
- * view configurations for runtime entities (`items`, `people`, `accounts`).
- *
- * **Routed by:** `GET/POST/PATCH/DELETE /.netlify/functions/types`
- *
- * **Authorization model:**
- * - All reads use `ctx.db` (RLS-scoped) and are sanitized via `sanitizeRecordData`.
- * - All writes (`create`, `update`, `remove`) require `isSystemAdmin` AND the
- *   caller's account must be a master tenant (`accounts.parent_id IS NULL`).
- * - Unauthenticated `list` calls receive minimal fields only (id, slug, name, kind).
- *
- * **Design schema auto-sync:** `update` regenerates `validation_schema` automatically
- * via `generateValidationSchema` whenever `design_schema` changes.
- *
- * INVARIANT: type slugs must be unique per (kind, app_id) combination.
- * INVARIANT: `ownership` of system types cannot be changed (to prevent constraint violations).
- * INVARIANT: `app_id = null` for system types; must be provided for app/tenant types.
- *
- * @seeAlso middleware.ts (createHandler, CoreContext)
- * @seeAlso permissions.ts (PermissionEngine, sanitizeRecordData, validateUpdatePermissions)
- * @seeAlso schema-utils.ts (generateValidationSchema — auto-called on design_schema updates)
- * @seeAlso audit.ts (emitLog for type.created / type.updated / type.deleted)
- */
-
-import { createHandler } from './_shared/middleware'
-import { adminDb, joins } from './_shared/db'
-import { emitLog } from './_shared/audit'
-import { PermissionEngine, sanitizeRecordData } from './_shared/permissions'
-import { generateValidationSchema } from './_shared/schema-utils'
-
-const permissions = PermissionEngine as any
-
-// ─── HANDLERS ─────────────────────────────────────────────────────────────────
-
-// ─── CHUNK_START: TYPES_LIST ──────────────────────────────────────────────
-/**
- * @chunk-id    TYPES_LIST_1_0_0
- * @version     1.0.0
- * @hash        0cfcf45a5a70d17002599b77e1c45bf7d3de456bc474e68a89ff44069d711b91
- * @macro       Types List Handler
- * @micro       Lists types with filtering, authentication-based response, and sanitization
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: any — Request body (unused for GET)
- * @outputs     Array of type records with app join, sanitized and schema-aware
- * @depends-on  [createHandler, joins, sanitizeRecordData]
- * @depended-by [Netlify function routing]
- * @side-effects [DB queries, permission sanitization, schema preservation]
- * @tags        types, list, crud, filtering, authentication
- */
-export const list = createHandler(async (ctx, body) => {
-  const { kind, app_id, ownership, limit = '50', offset = '0', include_schema } = ctx.query || {}
-
-  // RLS automatically filters to accessible accounts
-  let query = ctx.db
-    .from('types')
-    .select(`*, ${joins.app}`)
-    .eq('is_active', true)
-    .order('kind')
-    .order('name')
-
-  if (kind) {
-    query = query.eq('kind', kind)
-  }
-
-  if (app_id) {
-    query = query.eq('app_id', app_id)
-  } else if (app_id === 'null') {
-    query = query.is('app_id', null)
-  }
-
-  if (ownership) {
-    query = query.eq('ownership', ownership)
-  }
-
-  const { data, error: err } = await query
-    .range(parseInt(offset), parseInt(offset) + parseInt(limit) - 1)
-
-  if (err) throw err
-
-  // For authenticated users, always include design_schema for schema-driven UI
-  // System admin sees everything, others get sanitized data with design_schema preserved
-  // When include_schema=true, preserve full design_schema for all accessible types
-  const sanitized = []
-  for (const type of data || []) {
-    if (ctx.principal) {
-      // Authenticated user - get sanitized data but preserve design_schema
-      const sanitizedType = await sanitizeRecordData(ctx, type, 'type')
-      // Ensure design_schema is preserved for schema-driven UI
-      if (type.design_schema && !sanitizedType.design_schema) {
-        sanitizedType.design_schema = type.design_schema
-      }
-      // When include_schema=true, also preserve validation_schema
-      if (include_schema === 'true' && type.validation_schema) {
-        sanitizedType.validation_schema = type.validation_schema
-      }
-      sanitized.push(sanitizedType)
-    } else {
-      // Unauthenticated user - return minimal data
-      const minimal: any = {
-        id: type.id,
-        slug: type.slug,
-        name: type.name,
-        kind: type.kind
-      }
-      // When include_schema=true, unauthenticated users also get schema
-      if (include_schema === 'true' && type.design_schema) {
-        minimal.design_schema = type.design_schema
-      }
-      sanitized.push(minimal)
-    }
-  }
-
-  return sanitized
-})
-// ─── CHUNK_END: TYPES_LIST ────────────────────────────────────────────────
-
-// ─── CHUNK_START: TYPES_GET ──────────────────────────────────────────────
-/**
- * @chunk-id    TYPES_GET_1_0_0
- * @version     1.0.0
- * @hash        435ff5a93d05f74e0299b515d32f50ceb5c526b517a6972ef65c3bdaa75c218f
- * @macro       Type Get Handler
- * @micro       Returns single type record with joins and sanitization
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: any — Request body (unused for GET)
- * @outputs     Sanitized type record with app join
- * @depends-on  [createHandler, joins, sanitizeRecordData]
- * @depended-by [Netlify function routing]
- * @side-effects [DB single row query, permission sanitization]
- * @tags        types, get, crud, single-record
- */
-export const get = createHandler(async (ctx, body) => {
-  const { id } = ctx.query || {}
-  
-  if (!id) {
-    throw new Error('Type ID is required')
-  }
-
-  const { data, error: err } = await ctx.db
-    .from('types')
-    .select(`*, ${joins.app}`)
-    .eq('id', id)
-    .eq('is_active', true)
-    .single()
-
-  if (err) throw err
-
-  // Sanitize based on role permissions
-  return await sanitizeRecordData(ctx, data, 'type')
-})
-// ─── CHUNK_END: TYPES_GET ────────────────────────────────────────────────
-
-// ─── CHUNK_START: TYPES_GET_BY_SLUG ──────────────────────────────────────────────
-/**
- * @chunk-id    TYPES_GET_BY_SLUG_1_0_0
- * @version     1.0.0
- * @hash        6585200f3ecdef92e2912849afd5d72a3968fe13b464cdf43f33a888edda4163
- * @macro       Type Get By Slug Handler
- * @micro       Returns single type record by slug with joins and sanitization
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: any — Request body (unused for GET)
- * @outputs     Sanitized type record with app join
- * @depends-on  [createHandler, joins, sanitizeRecordData]
- * @depended-by [Netlify function routing]
- * @side-effects [DB single row query, permission sanitization]
- * @tags        types, get, crud, single-record, slug
- */
-export const getBySlug = createHandler(async (ctx, body) => {
-  const { slug } = ctx.query || {}
-  
-  if (!slug) {
-    throw new Error('Type slug is required')
-  }
-
-  const { data, error: err } = await ctx.db
-    .from('types')
-    .select(`*, ${joins.app}`)
-    .eq('slug', slug)
-    .eq('is_active', true)
-    .single()
-
-  if (err) throw err
-
-  // Sanitize based on role permissions
-  return await sanitizeRecordData(ctx, data, 'type')
-})
-// ─── CHUNK_END: TYPES_GET_BY_SLUG ────────────────────────────────────────────────
-
-// ─── CHUNK_START: TYPES_GET_SCHEMA ──────────────────────────────────────────────
-/**
- * @chunk-id    TYPES_GET_SCHEMA_1_0_0
- * @version     1.0.0
- * @hash        2cff73f363bb53c145d64b5b2fc788de592a94321000425f6b2ab82489c9a1e4
- * @macro       Type Schema Handler
- * @micro       Returns design_schema for a type via RPC
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: any — Request body (unused for GET)
- * @outputs     {design_schema: object} — Type design schema
- * @depends-on  [createHandler]
- * @depended-by [Netlify function routing]
- * @side-effects [DB RPC call, RLS enforcement]
- * @tags        types, schema, rpc, design-schema
- */
-export const getSchema = createHandler(async (ctx, body) => {
-  const { kind, slug, app_id } = ctx.query || {}
-
-  if (!kind || !slug) {
-    throw new Error('kind and slug are required')
-  }
-
-  const { data, error: err } = await ctx.db
-    .rpc('get_type_schema', {
-      kind,
-      slug,
-      app_id: app_id || null
-    })
-
-  if (err) throw err
-
-  return { design_schema: data }
-})
-// ─── CHUNK_END: TYPES_GET_SCHEMA ────────────────────────────────────────────────
-
-// ─── CHUNK_START: TYPES_CREATE ──────────────────────────────────────────────
-/**
- * @chunk-id    TYPES_CREATE_1_0_0
- * @version     1.0.0
- * @hash        c226d40910e332c0c89bfbb0d09f2b6a04b45a0a104c70d485ebd08c2c07cbe0
- * @macro       Type Create Handler
- * @micro       Creates type with system admin validation, schema generation, and audit logging
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — Type data including kind, slug, name, and optional fields
- * @outputs     Inserted type record
- * @depends-on  [createHandler, adminDb, permissions, generateValidationSchema, emitLog]
- * @depended-by [Netlify function routing]
- * @side-effects [DB insert, master tenant validation, schema generation, audit logging]
- * @tags        types, create, crud, system-admin, schema-generation, audit
- */
-export const create = createHandler(async (ctx, body) => {
-  const { app_id, kind, slug, name, description, icon, color, design_schema: bodySchema = {}, ownership } = body
-
-  if (!kind || !slug || !name) {
-    throw new Error('kind, slug, and name are required')
-  }
-
-  if (!ctx.principal || ctx.principal.id === 'anonymous' || !ctx.accountId) {
-    throw new Error('User context (person and account) required')
-  }
-
-  // Config mutations (types) are only allowed in master tenant by system admins
-  if (!permissions.isSystemAdmin(ctx)) {
-    throw new Error('Only system administrators can create type configurations')
-  }
-
-  // Verify the current account is a master tenant (parent_id IS NULL)
-  // Use adminDb for this check since we're verifying account structure
-  const { data: accountData } = await adminDb
-    .from('accounts')
-    .select('parent_id')
-    .eq('id', ctx.accountId!)
-    .single()
-
-  if (!accountData || accountData.parent_id !== null) {
-    throw new Error('Type configurations can only be created in master tenant accounts')
-  }
-
-  // Check if slug is unique within app/kind
-  let query = adminDb
-    .from('types')
-    .select('id')
-    .eq('kind', kind)
-    .eq('slug', slug)
-
-  if (app_id) {
-    query = query.eq('app_id', app_id)
-  } else {
-    query = query.is('app_id', null)
-  }
-
-  const { data: existing } = await query.single()
-
-  if (existing) {
-    throw new Error('Type slug already exists for this kind and app')
-  }
-
-  // Basic schema validation
-  if (bodySchema && typeof bodySchema === 'object') {
-    if (bodySchema.fields && (typeof bodySchema.fields !== 'object' || bodySchema.fields === null)) {
-      throw new Error('Schema fields must be an object')
-    }
-  }
-
-  // For non-system ownership, we need an app_id to satisfy the constraint
-  let finalAppId = app_id
-  let finalOwnership = ownership
-  
-  if (!app_id && ownership !== 'system') {
-    // Get the first available app for tenant/custom types
-    const { data: apps } = await adminDb
-      .from('apps')
-      .select('id')
-      .limit(1)
-      .single()
-    
-    if (apps?.id) {
-      finalAppId = apps.id
-      finalOwnership = 'app' // Use 'app' ownership when associated with an app
-    } else {
-      throw new Error('Cannot create type without app_id for non-system ownership')
-    }
-  }
-
-  // Generate validation schema from design schema
-  const validationSchema = generateValidationSchema(bodySchema || {})
-
-  const { data, error: err } = await adminDb
-    .from('types')
-    .insert({
-      app_id: finalAppId,
-      kind,
-      slug,
-      name,
-      description,
-      icon,
-      color,
-      design_schema: bodySchema || {},
-      validation_schema: validationSchema,
-      ownership: finalOwnership || 'system',
-      is_active: true
-    })
-    .select()
-    .single()
-
-  if (err) throw err
-
-  await emitLog(ctx, 'type.created', { type: 'type', id: data.id }, { after: data })
-
-  return data
-})
-// ─── CHUNK_END: TYPES_CREATE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: TYPES_UPDATE ──────────────────────────────────────────────
-/**
- * @chunk-id    TYPES_UPDATE_1_0_0
- * @version     1.0.0
- * @hash        7778ce63ecc3dd50fe50680c4f1199a59db4c4dae734cf7a2d58cc2de76b9a6a
- * @macro       Type Update Handler
- * @micro       Updates type with validation, schema regeneration, and audit logging
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — Type updates including id and updatable fields
- * @outputs     Updated type record
- * @depends-on  [createHandler, adminDb, permissions, generateValidationSchema, emitLog]
- * @depended-by [Netlify function routing]
- * @side-effects [DB update, field validation, schema regeneration, audit logging]
- * @tags        types, update, crud, system-admin, schema-generation, audit
- */
-export const update = createHandler(async (ctx, body) => {
-  const id = body?.id || ctx.query?.id
-  const { id: _bodyId, ...updates } = body || {}
-
-  if (!id) {
-    throw new Error('Type ID is required')
-  }
-
-  if (!ctx.principal || ctx.principal.id === 'anonymous' || !ctx.accountId) {
-    throw new Error('User context (person and account) required')
-  }
-
-  // Get current state for audit - RLS will filter to accessible types
-  const { data: current } = await adminDb
-    .from('types')
-    .select('*')
-    .eq('id', id)
-    .single()
-
-  if (!current) {
-    throw new Error('Type not found')
-  }
-
-  // Config mutations (types) are only allowed in master tenant by system admins
-  if (!permissions.isSystemAdmin(ctx)) {
-    throw new Error('Only system administrators can update type configurations')
-  }
-
-  // System types can only be updated by system admins (already checked above)
-  // App types require app ownership verification
-  if (current.ownership === 'app' && current.app_id) {
-    // Verify user has access to this app
-    const { data: appAccess } = await adminDb
-      .from('apps')
-      .select('id')
-      .eq('id', current.app_id)
-      .eq('is_active', true)
-      .single()
-    
-    if (!appAccess) {
-      throw new Error('App not found or inactive')
-    }
-  }
-
-  // Verify the current account is a master tenant (parent_id IS NULL)
-  // Use adminDb for this check since we're verifying account structure
-  const { data: accountData } = await adminDb
-    .from('accounts')
-    .select('parent_id')
-    .eq('id', ctx.accountId!)
-    .single()
-
-  if (!accountData || accountData.parent_id !== null) {
-    throw new Error('Type configurations can only be updated in master tenant accounts')
-  }
-
-  // Validate field-level permissions
-  const fieldValidation = await permissions.validateUpdatePermissions(
-    ctx,
-    updates,
-    current,
-    'type'
-  )
-  
-  if (!fieldValidation.valid) {
-    throw new Error(fieldValidation.error)
-  }
-
-  // Prevent ownership changes for system types to avoid constraint violations
-  if (current.ownership === 'system' && updates.ownership && updates.ownership !== 'system') {
-    // Remove ownership from updates to preserve system ownership
-    delete updates.ownership
-  }
-
-  // Handle app_id null conversion for system types
-  if (updates.app_id === '') {
-    updates.app_id = null
-  }
-
-  // Validate design_schema if being updated
-  if (updates.design_schema) {
-    if (typeof updates.design_schema !== 'object' || updates.design_schema === null) {
-      throw new Error('Design schema must be an object')
-    }
-    if (updates.design_schema.fields && (typeof updates.design_schema.fields !== 'object' || updates.design_schema.fields === null)) {
-      throw new Error('Design schema fields must be an object')
-    }
-    
-    // Auto-generate validation_schema when design_schema changes
-    updates.validation_schema = generateValidationSchema(updates.design_schema)
-  }
-
-  const { data, error: err } = await ctx.db
-    .from('types')
-    .update({
-      ...updates,
-      updated_at: new Date().toISOString()
-    })
-    .eq('id', id)
-    .select()
-    .single()
-
-  if (err) throw err
-
-  await emitLog(ctx, 'type.updated', { type: 'type', id }, { before: current, after: data })
-
-  return data
-})
-// ─── CHUNK_END: TYPES_UPDATE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: TYPES_REMOVE ──────────────────────────────────────────────
-/**
- * @chunk-id    TYPES_REMOVE_1_0_0
- * @version     1.0.0
- * @hash        eef22a9e3f661c71c65ba5d69ce7e60c2c2bfccec986ad2309290217f5332455
- * @macro       Type Remove Handler
- * @micro       Soft-deletes type with system admin validation and audit logging
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — Type id for deletion
- * @outputs     Updated type record with is_active: false
- * @depends-on  [createHandler, adminDb, permissions, emitLog]
- * @depended-by [Netlify function routing]
- * @side-effects [DB soft delete, master tenant validation, audit logging]
- * @tags        types, remove, soft-delete, system-admin, audit
- */
-export const remove = createHandler(async (ctx, body) => {
-  const id = body?.id || ctx.query?.id
-
-  if (!id) {
-    throw new Error('Type ID is required')
-  }
-
-  if (!ctx.principal || ctx.principal.id === 'anonymous' || !ctx.accountId) {
-    throw new Error('User context (person and account) required')
-  }
-
-  // Get current state for audit - RLS will filter to accessible types
-  const { data: current } = await ctx.db
-    .from('types')
-    .select('*')
-    .eq('id', id)
-    .single()
-
-  if (!current) {
-    throw new Error('Type not found')
-  }
-
-  // Config mutations (types) are only allowed in master tenant by system admins
-  if (!permissions.isSystemAdmin(ctx)) {
-    throw new Error('Only system administrators can delete type configurations')
-  }
-
-  // System types can only be deleted by system admins (already checked above)
-  // App types require app ownership verification
-  if (current.ownership === 'app' && current.app_id) {
-    // Verify user has access to this app
-    const { data: appAccess } = await ctx.db
-      .from('apps')
-      .select('id')
-      .eq('id', current.app_id)
-      .eq('is_active', true)
-      .single()
-    
-    if (!appAccess) {
-      throw new Error('App not found or inactive')
-    }
-  }
-
-  // Verify the current account is a master tenant (parent_id IS NULL)
-  // Use adminDb for this check since we're verifying account structure
-  const { data: accountData } = await adminDb
-    .from('accounts')
-    .select('parent_id')
-    .eq('id', ctx.accountId!)
-    .single()
-
-  if (!accountData || accountData.parent_id !== null) {
-    throw new Error('Type configurations can only be deleted in master tenant accounts')
-  }
-
-  const { data, error: err } = await ctx.db
-    .from('types')
-    .update({
-      is_active: false,
-      updated_at: new Date().toISOString()
-    })
-    .eq('id', id)
-    .select()
-    .single()
-
-  if (err) throw err
-
-  await emitLog(ctx, 'type.deleted', { type: 'type', id }, { before: current })
-
-  return data
-})
-// ─── CHUNK_END: TYPES_REMOVE ────────────────────────────────────────────────
-
-// ─── MAIN HANDLER ────────────────────────────────────────────────────────────
-
-// ─── CHUNK_START: TYPES_HANDLER ──────────────────────────────────────────────
-/**
- * @chunk-id    TYPES_HANDLER_1_0_0
- * @version     1.0.0
- * @hash        70e9e120f669468bd7aa45d7a2b8b4cf9a13a2323f897a6fc2bd389d960f8adc
- * @macro       Types Router
- * @micro       Routes HTTP methods and actions to appropriate type handlers
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: any — Request body for POST/PATCH/DELETE operations
- * @outputs     Varies — Depends on routed handler (list/get/getBySlug/getSchema/create/update/remove)
- * @depends-on  [createHandler, list, get, getBySlug, getSchema, create, update, remove]
- * @depended-by [Netlify function routing]
- * @side-effects [Delegates to appropriate handler]
- * @tags        types, router, crud, netlify-function
- */
-export const handler = createHandler(async (ctx, body) => {
-  const method = ctx.query?.method || 'GET'
-  const action = ctx.query?.action
-
-  switch (method) {
-    case 'GET':
-      if (action === 'get' && ctx.query?.slug) {
-        return await getBySlug(ctx, body)
-      } else if (ctx.query?.id) {
-        return await get(ctx, body)
-      } else if (action === 'schema') {
-        return await getSchema(ctx, body)
-      } else {
-        return await list(ctx, body)
-      }
-    case 'POST':
-      return await create(ctx, body)
-    case 'PATCH':
-      return await update(ctx, body)
-    case 'DELETE':
-      return await remove(ctx, body)
-    default:
-      throw new Error(`Unsupported method: ${method}`)
-  }
-})
-// ─── CHUNK_END: TYPES_HANDLER ────────────────────────────────────────────────

package/.framework/index.html

@@ -1,16 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <link rel="icon" type="image/svg+xml" href="/spine-logo.svg" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <link rel="preconnect" href="https://fonts.googleapis.com">
-    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
-    <title>Spine Framework</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/src/main.tsx"></script>
-  </body>
-</html>