spine-framework 0.2.1 → 1.0.0

package/.framework/src/types/auth.ts

@@ -1,125 +0,0 @@
-/**
- * @module src/types/auth
- * @audience installer
- * @layer frontend-hook
- * @stability stable
- *
- * Authentication and principal type definitions for the Spine frontend.
- * These shapes mirror the response from `GET /api/auth?action=context` and
- * are used throughout `AuthContext`, hooks, and any component that needs
- * to reason about the current user's identity, account, or permissions.
- *
- * **Server source:** `functions/auth.ts` → `get_account_hierarchy` RPC resolves
- * `User.account`, `User.roles`, `User.permissions`, and `User.accessible_accounts`.
- *
- * @seeAlso src/contexts/AuthContext.tsx (stores and exposes User)
- * @seeAlso src/types/types.ts (design-schema types; separate concern)
- * @seeAlso functions/auth.ts (API endpoint that returns User shape)
- */
-
-// ─── PRINCIPAL ─────────────────────────────────────────────────────────────────
-
-/**
- * The resolved user/principal context returned by the auth API and stored
- * in `AuthContext`. Populated from the `people`, `accounts`, and `roles`
- * tables via the `get_account_hierarchy` RPC.
- *
- * @prop id - UUID of the `people` row (matches `auth.users.id`)
- * @prop email - Primary email address
- * @prop full_name - Display name
- * @prop account_id - UUID of the user's primary account
- * @prop account - Hydrated primary `Account` object (optional join)
- * @prop roles - Flat list of role slugs (e.g. `['admin', 'member']`)
- * @prop permissions - Flat list of permission slugs
- * @prop is_system_admin - Convenience flag set when `system_admin` is in roles
- * @prop accessible_accounts - All accounts the user can act on (multi-tenancy)
- */
-export interface User {
-  id: string
-  email: string
-  full_name: string
-  account_id: string
-  account?: Account
-  roles: string[] // Simplified for now
-  permissions: string[] // Simplified for now
-  is_system_admin?: boolean
-  accessible_accounts?: Account[]
-}
-
-/**
- * A Spine account record. Used as the primary organisational scope for all
- * data access.
- *
- * @prop slug - URL-safe unique identifier
- * @prop display_name - Human-readable name shown in UI
- * @prop account_type - `'tenant'` | `'organization'` | `'individual'`
- * @prop owner_account_id - Parent account UUID for tenant hierarchy
- * @prop metadata - Arbitrary extra fields set by the application layer
- */
-export interface Account {
-  id: string
-  slug: string
-  display_name: string
-  name?: string
-  account_type?: string
-  owner_account_id?: string
-  metadata?: Record<string, any>
-}
-
-// ─── ROLES & PERMISSIONS ──────────────────────────────────────────────────────────
-
-/**
- * A role record from the `v2.roles` table.
- *
- * @prop slug - Unique role identifier used in permission checks
- * @prop permissions - Granular permission list attached to this role
- */
-export interface Role {
-  id: string
-  slug: string
-  name: string
-  description?: string
-  permissions: Permission[]
-}
-
-/**
- * A single permission grant.
- *
- * @prop resource - The entity or system resource being guarded
- * @prop action - The allowed action (`'read'`, `'write'`, `'delete'`, etc.)
- * @prop scope - Optional scope qualifier (e.g. `'own'` vs `'any'`)
- */
-export interface Permission {
-  id: string
-  resource: string
-  action: string
-  scope?: string
-}
-
-// ─── AUTH FLOW ─────────────────────────────────────────────────────────────────
-
-/**
- * Shape of a successful auth response (Supabase sign-in).
- * Not used directly by Spine — the frontend uses `supabase.auth.signInWithPassword`
- * and then calls `fetchUserContext`; this type documents the underlying contract.
- */
-export interface AuthResponse {
-  user: User
-  access_token: string
-  refresh_token: string
-  expires_in: number
-}
-
-/** Credentials for `supabase.auth.signInWithPassword` via `AuthContext.login`. */
-export interface LoginCredentials {
-  email: string
-  password: string
-}
-
-/** Registration data for new user sign-up flows. */
-export interface RegisterData {
-  email: string
-  password: string
-  full_name: string
-  account_name?: string
-}

package/.framework/src/types/types.ts

@@ -1,407 +0,0 @@
-/**
- * @module src/types/types
- * @audience installer
- * @layer frontend-hook
- * @stability stable
- *
- * Core TypeScript type definitions for the Spine frontend. These types
- * mirror the `design_schema` and API response shapes used across hooks,
- * components, and pages.
- *
- * **Type hierarchy:**
- * ```
- * DesignSchema
- *   ├── fields: Record<string, FieldDefinition>
- *   ├── views: Record<string, View>   ← ListView | DetailView
- *   ├── record_permissions
- *   └── functionality?: FunctionalityBindings
- * ItemType  ← row in v2.types table
- * Item       ← row in v2.items table
- * ```
- *
- * **`system` flag on `FieldDefinition`:** When `system: true`, the field
- * maps to a real DB column (e.g. `title`, `status`). When absent or false,
- * the field value lives in the `data` JSONB column.
- *
- * @seeAlso src/hooks/useSchemaRecord.ts (consumes FieldDefinition[])
- * @seeAlso src/hooks/useForm.ts (consumes FieldDefinition[] for validation)
- * @seeAlso src/hooks/useListSchema.ts (consumes DesignSchema + View)
- * @seeAlso functions/_shared/schema-utils.ts (server-side schema generation)
- */
-
-// ─── FIELD DEFINITIONS ───────────────────────────────────────────────────────────
-
-/**
- * Definition of a single field in a `design_schema`. Drives both UI rendering
- * and client-side validation in `useForm`.
- *
- * @prop data_type - Controls rendering widget and validation rules
- * @prop label - Human-readable display label
- * @prop required - Whether the field must be non-empty on save
- * @prop system - If true, maps to a top-level DB column; false/absent → `data` JSONB
- * @prop name - Injected at runtime by hooks; not stored in the schema itself
- * @prop validation - Type-specific constraint overrides
- * @prop options - Choice list for select/multiselect/radio fields
- * @prop permissions - Role-based read/write access map; absent = all roles allowed
- */
-export interface FieldDefinition {
-  data_type: 'text' | 'textarea' | 'rich_text' | 'email' | 'phone' | 'url' | 
-             'number' | 'currency' | 'range' | 'date' | 'datetime' | 'boolean' | 
-             'checkbox' | 'select' | 'multiselect' | 'radio' | 'color' | 
-             'file' | 'image' | 'json' | 'reference' | 'address'
-  label: string
-  required: boolean
-  system?: boolean // true = DB column, false/absent = custom field in .data
-  // Runtime identity — populated by SchemaFields when building field arrays from schema
-  name?: string
-  // UI hints — informational only, do not affect data contract or permissions
-  placeholder?: string
-  description?: string
-  rows?: number
-  min?: number
-  max?: number
-  step?: number
-  readonly?: boolean
-  disabled?: boolean
-  validation?: {
-    pattern?: string
-    minLength?: number
-    maxLength?: number
-    min?: number
-    max?: number
-    step?: number
-    integer?: boolean
-    precision?: number
-    maxSize?: number
-    allowedTypes?: string[]
-    maxWidth?: number
-    maxHeight?: number
-    currency_code?: string
-    reference_kind?: string
-    reference_type?: string
-  }
-  // Type-specific constraint properties (move out of validation for clarity)
-  options?: (string | { value: string; label: string })[] // For select/multiselect/radio
-  permissions?: {
-    [role: string]: string[] // Array of actions: ["read", "write"]
-  }
-}
-
-// ─── VIEW TYPES ─────────────────────────────────────────────────────────────────
-
-/**
- * Per-field display/behaviour config within a view. Stored as
- * `design_schema.views[viewSlug].fields[fieldName]`.
- *
- * @prop display_type - Override the default widget for this field in this view
- * @prop sortable - Whether the column header shows a sort toggle in list views
- * @prop searchable - Whether the field is included in free-text search
- */
-export interface ViewFieldConfig {
-  display_type: 'input' | 'textarea' | 'rich_text' | 'select' | 'multiselect' | 
-                 'radio' | 'checkbox' | 'switch' | 'date_picker' | 'datetime_picker' | 
-                 'color_picker' | 'file_upload' | 'image_upload' | 'range_slider' | 
-                 'rating' | 'autocomplete' | 'address_form' | 'reference_picker' |
-                 'text' | 'badge' | 'timestamp' | 'currency' | 'number'
-  sortable?: boolean
-  searchable?: boolean
-}
-
-/**
- * A list view definition. Rendered by `DataListPage` as a table, card grid,
- * or Kanban board depending on `display`.
- *
- * @prop fields - Ordered map of field name → `ViewFieldConfig`
- * @prop default_sort - Initial sort applied before user interaction
- * @prop filters - Field names to expose as filter controls
- * @prop stats - Summary stat cards shown above the list
- * @prop group_by - Field to use as board column grouping (`display: 'board'` only)
- */
-export interface ListView {
-  type: 'list'
-  display: 'table' | 'card' | 'board'
-  label: string
-  fields: Record<string, ViewFieldConfig>
-  default_sort?: {
-    field: string
-    direction: 'asc' | 'desc'
-  }
-  filters?: string[]
-  stats?: Array<{
-    title: string
-    type: 'count' | 'filter_count'
-    icon?: string
-    color?: string
-    filter?: Record<string, any>
-  }>
-  group_by?: string // For board display
-}
-
-/**
- * A single section within a `DetailView`. Groups related fields under
- * an optional title. Field permissions from the schema still apply —
- * there are no section-level permission overrides.
- */
-export interface DetailViewSection {
-  title: string
-  fields: Record<string, ViewFieldConfig>
-  // Note: No view-level permissions - field permissions from schema apply
-}
-
-/**
- * A detail view definition. Rendered by `DataDetailPage` as a sectioned
- * record form.
- */
-export interface DetailView {
-  type: 'detail'
-  label: string
-  sections: DetailViewSection[]
-}
-
-/** Discriminated union of all supported view types. */
-export type View = ListView | DetailView
-
-// ─── FUNCTIONALITY BINDINGS ──────────────────────────────────────────────────────────
-
-/**
- * Optional automation and integration bindings attached to a `DesignSchema`.
- * Each array entry describes a trigger condition and the target pipeline,
- * agent, embedding, integration, or constraint.
- *
- * These bindings are evaluated by API handlers and the system cron — not
- * by the frontend. They are included here as a type contract so the frontend
- * can read and display binding metadata without making blind `any` casts.
- */
-export interface FunctionalityBindings {
-  pipelines?: Array<{
-    pipeline_id: string
-    trigger: 'manual' | 'on_create' | 'on_update' | 'on_field_change' | 'on_delete' | 'scheduled'
-    field?: string // For on_field_change
-    condition?: string // Expression string
-    roles: string[]
-  }>
-  ai_agents?: Array<{
-    agent_id: string
-    capabilities: ('read' | 'summarize' | 'suggest' | 'update')[]
-    trigger: 'manual' | 'on_create' | 'on_update' | 'on_field_change'
-    roles: string[]
-  }>
-  embeddings?: Array<{
-    slug: string
-    fields: string[]
-    model: string
-    vector_column: string
-    trigger: 'on_create' | 'on_update' | 'on_create_or_update'
-  }>
-  integrations?: Array<{
-    integration_id: string
-    sync: 'bidirectional' | 'inbound' | 'outbound'
-    field_map: Record<string, {
-      external_field: string
-      direction: 'both' | 'inbound' | 'outbound' | 'none'
-      transform?: string
-    }>
-    trigger: 'on_create' | 'on_update' | 'on_create_or_update'
-  }>
-  constraints?: Array<{
-    type: 'unique' | 'conditional_required' | 'immutable'
-    fields?: string[] // For unique
-    field?: string // For conditional_required and immutable
-    condition?: string // For conditional_required
-    message: string
-    after?: 'create' | 'update' // For immutable
-  }>
-}
-
-// ─── DESIGN SCHEMA ────────────────────────────────────────────────────────────────
-
-/**
- * The complete design schema for a `types` record. Stored as a JSONB column
- * (`design_schema`) and stamp-copied onto records at create time.
- *
- * @prop record_permissions - Role → allowed CRUD actions map for the entire record
- * @prop fields - All field definitions keyed by field name
- * @prop views - Named view definitions (`list`, `detail`, etc.)
- * @prop functionality - Optional automation bindings (pipelines, agents, etc.)
- */
-export interface DesignSchema {
-  record_permissions: {
-    [role: string]: string[] // Array of actions: ["create", "read", "update", "delete"]
-  }
-  fields: Record<string, FieldDefinition>
-  views: Record<string, View>
-  functionality?: FunctionalityBindings
-}
-
-// ─── RECORD SHAPES ─────────────────────────────────────────────────────────────────
-
-/**
- * A row from the `v2.types` table. Represents a type definition (item type,
- * account type, person type, etc.) including its full `design_schema`.
- *
- * @prop kind - Discriminator: `'item'` | `'account'` | `'person'` | etc.
- * @prop design_schema - Full schema defining fields, views, and functionality
- * @prop validation_schema - Auto-generated JSON Schema used for server-side validation
- * @prop ownership - `'pack'` | `'tenant'` (pack-ownership tracking)
- */
-export interface ItemType {
-  id: string
-  name: string
-  slug: string
-  kind: string
-  description?: string
-  icon?: string
-  color?: string
-  design_schema: DesignSchema
-  validation_schema: {
-    fields: Record<string, {
-      data_type: string
-      required?: boolean
-      [key: string]: any // Type-specific validation properties
-    }>
-  }
-  ownership: string
-  is_active: boolean
-  app_id?: string
-  app?: any
-  created_at: string
-  updated_at: string
-}
-
-/**
- * A row from the `v2.items` table. The `data` JSONB column holds all
- * custom field values; system fields (`title`, `status`, etc.) are top-level.
- *
- * @prop design_schema - Stamp of the type's schema at create time (for resilience
- *   to schema changes; may be stale relative to `types` table)
- * @prop validation_schema - Stamp of the validation schema at create time
- */
-export interface Item {
-  id: string
-  item_type_id: string
-  item_type_slug?: string
-  title: string
-  description?: string
-  status: string
-  is_active: boolean
-  data: Record<string, any>
-  created_at: string
-  updated_at: string
-  created_by?: string
-  account_id: string
-  app_id?: string
-  design_schema?: Record<string, any> // Schema snapshot at creation time
-  validation_schema?: Record<string, any> // Validation schema snapshot at creation time
-}
-
-// ─── FORM & QUERY TYPES ───────────────────────────────────────────────────────────
-
-/** A field-level validation failure from `useForm` or server-side validation. */
-export interface ValidationError {
-  field: string
-  message: string
-}
-
-/** Snapshot of form state — used as a shared type between `useForm` and form components. */
-export interface FormState {
-  data: Record<string, any>
-  errors: Record<string, string>
-  touched: Record<string, boolean>
-  isSubmitting: boolean
-  isValid: boolean
-}
-
-/** Pagination query parameters for list endpoints. */
-export interface PaginationParams {
-  limit?: number
-  offset?: number
-  page?: number
-}
-
-/** Sort order specification for list endpoints. */
-export interface SortParams {
-  field: string
-  direction: 'asc' | 'desc'
-}
-
-/** Arbitrary key→value filter map for list endpoints. */
-export interface FilterParams {
-  [key: string]: any
-}
-
-/** Combined search, sort, filter, and pagination params for list queries. */
-export interface SearchParams extends PaginationParams {
-  search?: string
-  sort?: SortParams
-  filters?: FilterParams
-}
-
-// ─── UI DISPLAY TYPES ────────────────────────────────────────────────────────────────
-
-/** A rendered column descriptor for list/table UI components. */
-export interface EntityColumn {
-  key: string
-  label: string
-  sortable?: boolean
-  type?: string
-  display_type?: string
-  badgeColors?: Record<string, string>
-  maxLength?: number
-}
-
-/** A stat card shown above entity list pages (count or filtered count). */
-export interface EntityStat {
-  title: string
-  type: 'count' | 'filter_count'
-  icon: string
-  color: string
-  filter?: Record<string, any>
-}
-
-/** A filter control definition for entity list pages. */
-export interface EntityFilter {
-  key: string
-  label: string
-  type: 'search' | 'enum' | 'boolean'
-  options?: string[]
-}
-
-// ─── ITEM PROGRESS ───────────────────────────────────────────────────────────
-
-/**
- * A per-person, per-item progress record. Tracks pipeline status, score, and
- * arbitrary interaction data for courses, onboarding, tasks, and quizzes.
- *
- * `title` is auto-composed as "<item title> — <person name>".
- * `description` is auto-composed as "Completed · score 85 · 2 attempts".
- * `data` holds extensible fields: attempts, time_spent, last_position, etc.
- *
- * INVARIANT: (person_id, item_id) is unique — state, not a log.
- */
-export interface ItemProgress {
-  id: string
-  type_id: string
-  account_id: string
-  app_id: string | null
-  person_id: string
-  item_id: string
-  title: string | null
-  description: string | null
-  status: 'not_started' | 'in_progress' | 'completed' | string
-  score: number | null
-  data: {
-    attempts?: number
-    time_spent?: number
-    last_position?: number
-    started_at?: string
-    completed_at?: string
-    [key: string]: any
-  }
-  is_active: boolean
-  design_schema: Record<string, any>
-  validation_schema: Record<string, any>
-  created_by: string | null
-  updated_by: string | null
-  created_at: string
-  updated_at: string
-}

package/STRUCTURE.md

@@ -1,150 +0,0 @@
-# Spine Enterprise Directory Structure
-
-This document explains the directory layout for the Spine framework.
-
-## Overview
-
-```
-my-app/
-├── .framework/          # 🔒 CLI-managed framework code (read-only)
-├── custom/              # ✏️ Developer workspace (your code)
-├── .assembled/          # 🏗️ Build output (gitignored)
-├── config/              # ⚙️ Build tool configuration
-├── scripts/             # 🔧 Build automation
-├── archive/             # 📦 Historical artifacts
-├── docs/                # 📚 Documentation
-├── netlify.toml         # 🌐 Netlify configuration (must be at root)
-├── package.json         # Root package manifest
-└── STRUCTURE.md         # This file
-```
-
-## Directory Details
-
-### `.framework/` — Framework Core (Hidden)
-**Managed by:** Spine CLI (read-only)
-**Contains:**
-- `functions/` — Core Netlify function handlers
-- `src/` — Core React components (Admin shell, app router)
-- `migrations/` — Base database schema
-- `cli/` — Framework CLI tools
-- `tests/` — Core test suites
-
-**You should not edit files here.** The CLI manages updates to this directory.
-
-### `custom/` — Developer Workspace
-**Managed by:** You
-**Contains:**
-- `functions/` — Your custom Netlify function handlers
-- `apps/` — Your applications (one folder per app)
-- `components/` — Shared UI components across your apps
-- `migrations/` — Your database schema changes
-- `tests/` — Your test suites
-
-**This is where you build your product.** Everything here is yours.
-
-### `.assembled/` — Build Output (Hidden, Gitignored)
-**Generated by:** Assembly scripts
-**Contains:**
-- `netlify/functions/` — Merged: `.framework/functions` + `custom/functions`
-- `src/` — Merged: `.framework/src` + `custom/apps/*`
-
-**Never edit files here.** This is rebuilt on every `netlify dev` or deployment.
-
-### `config/` — Build Tool Configuration
-**Contains:**
-- `vite.config.ts` — Vite build configuration
-- `tsconfig.json` — TypeScript configuration
-- `tailwind.config.ts` — Styling configuration
-- `postcss.config.js` — CSS processing
-
-### `netlify.toml` — Netlify Configuration (Root)
-**Must be at project root** (Netlify CLI requirement)
-- Functions path: `.assembled/netlify/functions/`
-- Dev server settings: port 3001 (Vite) → 8888 (Netlify proxy)
-
-### `scripts/` — Build Automation
-**Contains:**
-- Assembly scripts that merge `.framework/` + `custom/` → `.assembled/`
-- Verification scripts for integrity checking
-
-### `archive/` — Historical Artifacts
-**Contains:**
-- Old audit documents
-- Completed project reports
-- Test artifacts
-
-## Assembly Flow
-
-```bash
-Development:
-  .framework/ + custom/  ──►  scripts/assemble.sh  ──►  .assembled/
-                                                      ──►  netlify dev
-
-Production:
-  .framework/ + custom/  ──►  scripts/assemble.sh  ──►  .assembled/
-                                                      ──►  Netlify deploy
-```
-
-## Path Aliases
-
-After assembly, code uses these aliases:
-- `@core` → `.framework/src/`
-- `@custom` → `custom/apps/`
-
-## Adding New Code
-
-### New App
-```bash
-mkdir custom/apps/my-app
-cd custom/apps/my-app
-# Create src/, components/, pages/
-```
-
-### New Function
-```bash
-touch custom/functions/my-handler.ts
-# Edit with your logic
-```
-
-### New Migration
-```bash
-touch custom/migrations/101_my_change.sql
-# Write ALTER TABLE statements
-```
-
-## Updating Framework
-
-```bash
-spine-framework update
-# CLI updates .framework/ to latest version
-# Your custom/ code is untouched
-```
-
-## Important Rules
-
-1. **Never edit `.framework/`** — use `custom/` instead
-2. **Never commit `.assembled/`** — it's in `.gitignore`
-3. **Always use assembly** — don't manually copy to `.assembled/`
-4. **Test after update** — run `netlify dev` after `spine-framework update`
-
-## Troubleshooting
-
-### "Where do I put X?"
-- Framework extension → `.framework/` (via CLI or PR)
-- Custom business logic → `custom/`
-- App-specific code → `custom/apps/{app-name}/`
-
-### "Assembly failed"
-1. Check both `.framework/` and `custom/` exist
-2. Verify no duplicate function names
-3. Run `scripts/assemble.sh` manually for error details
-
-### "Functions not found"
-1. Check `.assembled/netlify/functions/` exists
-2. Verify `netlify.toml` (in project root) points to correct path
-3. Ensure assembly ran without errors
-
-### "Netlify dev can't connect"
-1. Check Vite is running on port 3001
-2. Verify `netlify.toml` is in project root (not config/)
-3. Check `targetPort = 3001` in netlify.toml [dev] section