spine-framework 0.3.55 → 0.3.56

package/.framework/cli/commands/dev.ts

@@ -255,6 +255,25 @@ async function fastReassemble(projectRoot: string): Promise<void> {
       copyChangedFiles(customFuncsDir, funcsDest)
     }
   }
+
+  // Reassemble spine.config.json to public directory
+  const spineConfigSrc = resolve(projectRoot, 'spine.config.json')
+  const publicDest = resolve(srcDest, 'public')
+  if (existsSync(spineConfigSrc)) {
+    if (!existsSync(publicDest)) {
+      mkdirSync(publicDest, { recursive: true })
+    }
+    const spineConfigDest = resolve(publicDest, 'spine.config.json')
+    const srcStat = statSync(spineConfigSrc)
+    let needsCopy = true
+    if (existsSync(spineConfigDest)) {
+      const destStat = statSync(spineConfigDest)
+      needsCopy = srcStat.mtimeMs > destStat.mtimeMs
+    }
+    if (needsCopy) {
+      copyFileSync(spineConfigSrc, spineConfigDest)
+    }
+  }
 }
 
 /**

package/.framework/cli/commands/install-app.ts

@@ -18,7 +18,7 @@
  */
 
 import type { Command } from 'commander'
-import { existsSync, readFileSync, mkdirSync, cpSync } from 'fs'
+import { existsSync, readFileSync, mkdirSync, cpSync, writeFileSync } from 'fs'
 import { resolve, dirname, join, basename } from 'path'
 import { fileURLToPath } from 'url'
 import { execSync } from 'child_process'
@@ -81,6 +81,14 @@ export function registerInstallAppCommands(program: Command) {
           await seedApp(appDest, appSlug)
         }
 
+        // 6. Aggregate registration config from manifest into spine.config.json
+        const manifestPath = join(appDest, 'manifest.json')
+        let manifest: Record<string, any> = {}
+        try { manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) } catch {}
+        if (manifest.registration?.enabled) {
+          updateRegistrationConfig(appSlug, manifest.registration)
+        }
+
         console.log(`\n✅ ${appSlug} installed successfully!\n`)
         console.log('Next: npm run assemble && netlify dev\n')
 
@@ -153,6 +161,14 @@ export function registerInstallAppCommands(program: Command) {
           }
         }
 
+        // Update registration config from manifest
+        const manifestPath = join(appDest, 'manifest.json')
+        let manifest: Record<string, any> = {}
+        try { manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) } catch {}
+        if (manifest.registration?.enabled) {
+          updateRegistrationConfig(appSlug, manifest.registration)
+        }
+
         console.log(`\n✅ ${appSlug} updated.\n`)
       } catch (err: any) {
         console.error(`\n❌ Update failed: ${err.message}`)
@@ -278,3 +294,75 @@ async function seedApp(appDir: string, appSlug: string) {
     }
   }
 }
+
+// ─── SPINE CONFIG HELPERS ───────────────────────────────────────────────────
+
+interface RegistrationConfig {
+  enabled: boolean
+  default_role: string
+  redirect_path: string
+}
+
+interface SpineConfig {
+  registration?: {
+    default_app?: string
+    default_role?: string
+    allow_url_override?: boolean
+    apps?: Record<string, {
+      role: string
+      path: string
+      enabled: boolean
+    }>
+  }
+}
+
+const SPINE_CONFIG_PATH = join(PROJECT_ROOT, 'spine.config.json')
+
+function loadSpineConfig(): SpineConfig {
+  if (!existsSync(SPINE_CONFIG_PATH)) {
+    return { registration: { apps: {} } }
+  }
+  try {
+    return JSON.parse(readFileSync(SPINE_CONFIG_PATH, 'utf8'))
+  } catch {
+    return { registration: { apps: {} } }
+  }
+}
+
+function saveSpineConfig(config: SpineConfig): void {
+  writeFileSync(SPINE_CONFIG_PATH, JSON.stringify(config, null, 2) + '\n')
+}
+
+function updateRegistrationConfig(appSlug: string, regConfig: RegistrationConfig): void {
+  const config = loadSpineConfig()
+
+  // Ensure registration section exists
+  if (!config.registration) {
+    config.registration = { apps: {} }
+  }
+  if (!config.registration.apps) {
+    config.registration.apps = {}
+  }
+
+  // Add/update this app's registration entry
+  config.registration.apps[appSlug] = {
+    role: regConfig.default_role,
+    path: regConfig.redirect_path,
+    enabled: regConfig.enabled,
+  }
+
+  // If this is the first registration-enabled app, make it the default
+  const enabledApps = Object.entries(config.registration.apps).filter(([, cfg]) => cfg.enabled)
+  if (enabledApps.length === 1 || !config.registration.default_app) {
+    config.registration.default_app = appSlug
+    config.registration.default_role = regConfig.default_role
+  }
+
+  // Default allow_url_override to true if not set
+  if (config.registration.allow_url_override === undefined) {
+    config.registration.allow_url_override = true
+  }
+
+  saveSpineConfig(config)
+  console.log(`  ✓ Updated spine.config.json registration for ${appSlug}`)
+}

package/.framework/functions/invites.ts

@@ -13,6 +13,7 @@
  * **Public actions (no auth required):**
  * | action            | method | description |
  * |-------------------|--------|-------------|
+ * | check-first-user  | GET    | Boolean: is this the first user registration? |
  * | check-domain      | GET    | Boolean: does this email domain have existing accounts? |
  * | validate-token    | GET    | Validate invite token, return preview |
  * | complete-registration | POST | Finalise walk-up registration after Supabase auth |
@@ -93,6 +94,22 @@ function isAdminRole(roleSlug: string | undefined): boolean {
   )
 }
 
+// ─── PUBLIC: check-first-user ─────────────────────────────────────────────────
+
+/**
+ * Returns { is_first_user: boolean } — true if there are zero people in the system.
+ * Used by RegisterPage to show simplified first-user flow.
+ */
+export const checkFirstUser = createHandler(async (_ctx, _body) => {
+  const { count, error } = await adminDb
+    .from('people')
+    .select('*', { count: 'exact', head: true })
+
+  if (error) throw new Error('Failed to check first user: ' + error.message)
+
+  return { is_first_user: (count ?? 0) === 0 }
+})
+
 // ─── PUBLIC: check-domain ─────────────────────────────────────────────────────
 
 /**
@@ -621,6 +638,7 @@ export const handler = createHandler(async (ctx, body) => {
 
   switch (action) {
     // Public
+    case 'check-first-user':    return await checkFirstUser(ctx, body)
     case 'check-domain':        return await checkDomain(ctx, body)
     case 'validate-token':      return await validateToken(ctx, body)
     case 'complete-registration': return await completeRegistration(ctx, body)

package/.framework/migrations/016_invites.sql

@@ -0,0 +1,27 @@
+-- Migration 016: Invite system indexes
+-- Invite and access_request stubs are stored as people rows with status
+-- 'invited' or 'pending' and invite metadata in the data jsonb column.
+--
+-- people.status values:
+--   active    — normal active person
+--   inactive  — deactivated
+--   invited   — admin-generated invite stub, unclaimed (pre-approval by definition)
+--   pending   — walk-up access request stub, awaiting member_admin approval
+--
+-- Invite metadata stored in people.data:
+--   invite_token       text     — 16-char random lookup key (URL: /register?t=TOKEN)
+--   invite_kind        text     — 'invite' | 'access_request'
+--   invite_expires_at  text     — ISO timestamp
+--   invite_attempts    integer  — failed validation attempts
+--   invite_blocked_at  text     — ISO timestamp, set after too many attempts
+--   invite_invited_by  uuid     — person UUID of the inviter
+
+-- Fast token lookup
+CREATE INDEX IF NOT EXISTS people_invite_token_idx
+  ON public.people ((data->>'invite_token'))
+  WHERE data->>'invite_token' IS NOT NULL;
+
+-- Efficient scoped invite list queries
+CREATE INDEX IF NOT EXISTS people_invite_kind_account_idx
+  ON public.people (account_id, status)
+  WHERE data->>'invite_kind' IS NOT NULL;

package/.framework/src/pages/auth/RegisterPage.tsx

@@ -4,21 +4,28 @@
  * @layer frontend-page
  * @stability stable
  *
- * Registration page. Handles four paths:
+ * Registration page. Handles multiple paths:
  *
- *   1. Invite link (?t=TOKEN) — email + account pre-filled and locked.
+ *   1. First user (no people in system) — simplified form, becomes system_admin.
+ *      No personal/company toggle shown.
+ *
+ *   2. Invite link (?t=TOKEN) — email + account pre-filled and locked.
  *      On submit: Supabase signUp → auth trigger resolves stub → active.
  *
- *   2. Walk-up personal — new account named after the person.
+ *   3. Walk-up personal — new account named after the person.
  *      On submit: Supabase signUp → complete-registration(new_account).
  *
- *   3. Walk-up company, no domain match — new account with company name.
+ *   4. Walk-up company, no domain match — new account with company name.
  *      On submit: Supabase signUp → complete-registration(new_account).
  *
- *   4. Walk-up company, domain match — user chooses join or create new.
+ *   5. Walk-up company, domain match — user chooses join or create new.
  *      Join: Supabase signUp → complete-registration(join_request) → pending.
  *      Create new: same as path 3.
  *
+ * URL params:
+ *   ?app=portal|cortex — override default registration app
+ *   ?role=member|support — override default role
+ *
  * @seeAlso functions/invites.ts   (check-domain, validate-token, complete-registration)
  * @seeAlso migrations/005_auth_user_trigger.sql  (invite stub resolution)
  * @seeAlso src/pages/auth/PendingApprovalPage.tsx
@@ -41,6 +48,17 @@ interface InvitePreview {
   kind: string
 }
 
+interface RegistrationConfig {
+  default_app: string
+  default_role: string
+  allow_url_override: boolean
+  apps: Record<string, {
+    role: string
+    path: string
+    enabled: boolean
+  }>
+}
+
 // ─── HELPERS ──────────────────────────────────────────────────────────────────
 
 async function callInvitesApi(action: string, params: Record<string, any> = {}, method: 'GET' | 'POST' = 'GET') {
@@ -58,6 +76,54 @@ async function callInvitesApi(action: string, params: Record<string, any> = {},
   return res.json()
 }
 
+async function loadRegistrationConfig(): Promise<RegistrationConfig | null> {
+  try {
+    const res = await fetch('/spine.config.json')
+    if (!res.ok) return null
+    const config = await res.json()
+    return config.registration ?? null
+  } catch {
+    return null
+  }
+}
+
+async function checkFirstUser(): Promise<boolean> {
+  try {
+    const result = await callInvitesApi('check-first-user')
+    return result.data?.is_first_user ?? false
+  } catch {
+    return false
+  }
+}
+
+function getPostRegistrationRedirect(
+  config: RegistrationConfig | null,
+  searchParams: URLSearchParams,
+  isInvite: boolean,
+  inviteAccountId?: string
+): string {
+  // Invites: redirect to the account's primary app or default
+  if (isInvite) {
+    return '/'
+  }
+
+  // Check for URL override if allowed
+  if (config?.allow_url_override) {
+    const appOverride = searchParams.get('app')
+    if (appOverride && config.apps[appOverride]?.enabled) {
+      return config.apps[appOverride].path
+    }
+  }
+
+  // Default app from config
+  if (config?.default_app && config.apps[config.default_app]?.enabled) {
+    return config.apps[config.default_app].path
+  }
+
+  // Fallback
+  return '/'
+}
+
 // ─── COMPONENT ────────────────────────────────────────────────────────────────
 
 export function RegisterPage() {
@@ -65,6 +131,10 @@ export function RegisterPage() {
   const navigate = useNavigate()
   const inviteToken = searchParams.get('t')
 
+  // Registration config
+  const [regConfig, setRegConfig] = useState<RegistrationConfig | null>(null)
+  const [isFirstUser, setIsFirstUser] = useState<boolean | null>(null)
+
   // Invite preview (when token present)
   const [invitePreview, setInvitePreview] = useState<InvitePreview | null>(null)
   const [tokenError, setTokenError] = useState('')
@@ -85,7 +155,19 @@ export function RegisterPage() {
   const [error, setError] = useState('')
   const [isLoading, setIsLoading] = useState(false)
 
-  // ── Resolve invite token on mount ──────────────────────────────────────────
+  // ── Load config and check first user on mount ──────────────────────────────
+  useEffect(() => {
+    ;(async () => {
+      const [config, firstUserCheck] = await Promise.all([
+        loadRegistrationConfig(),
+        checkFirstUser(),
+      ])
+      setRegConfig(config)
+      setIsFirstUser(firstUserCheck)
+    })()
+  }, [])
+
+  // ── Resolve invite token ───────────────────────────────────────────────────
   useEffect(() => {
     if (!inviteToken) return
     ;(async () => {
@@ -103,7 +185,7 @@ export function RegisterPage() {
 
   // ── Domain check on email blur ─────────────────────────────────────────────
   const handleEmailBlur = useCallback(async () => {
-    if (!email || !email.includes('@') || inviteToken || useType === 'personal') return
+    if (!email || !email.includes('@') || inviteToken || useType === 'personal' || isFirstUser) return
 
     setDomainCheckLoading(true)
     setDomainMatchAccountId(null)
@@ -113,10 +195,9 @@ export function RegisterPage() {
     setDomainCheckLoading(false)
 
     if (result.data?.match) {
-      // We signal a match but don't expose the account id here (fetched server-side on join)
       setDomainMatchAccountId('__matched__')
     }
-  }, [email, inviteToken, useType])
+  }, [email, inviteToken, useType, isFirstUser])
 
   // ── Submit ─────────────────────────────────────────────────────────────────
   const handleSubmit = async (e: React.FormEvent) => {
@@ -126,7 +207,7 @@ export function RegisterPage() {
 
     try {
       // 1. Supabase auth signup
-      const { error: signUpError } = await supabase.auth.signUp({
+      const { data: signUpData, error: signUpError } = await supabase.auth.signUp({
         email: invitePreview?.email ?? email,
         password,
         options: { data: { full_name: fullName } },
@@ -137,13 +218,20 @@ export function RegisterPage() {
         return
       }
 
-      // 2. Invite path — trigger handles everything, navigate to login
+      // 2. First user path — trigger handles everything, navigate to root
+      if (isFirstUser) {
+        // First user becomes system_admin immediately, go to admin
+        navigate('/spine-framework/admin', { replace: true })
+        return
+      }
+
+      // 3. Invite path — trigger handles everything, navigate to account
       if (inviteToken) {
-        navigate('/login?registered=1')
+        navigate('/', { replace: true })
         return
       }
 
-      // 3. Walk-up paths — call complete-registration
+      // 4. Walk-up paths — call complete-registration
       const resolvedEmail = email
 
       if (domainMatchChoice === 'join') {
@@ -157,7 +245,7 @@ export function RegisterPage() {
           setError(joinResult.error)
           return
         }
-        navigate('/pending-approval')
+        navigate('/pending-approval', { replace: true })
         return
       }
 
@@ -174,7 +262,9 @@ export function RegisterPage() {
         return
       }
 
-      navigate('/login?registered=1')
+      // Navigate to configured post-registration destination
+      const redirectPath = getPostRegistrationRedirect(regConfig, searchParams, false)
+      navigate(redirectPath, { replace: true })
     } catch (err: any) {
       setError(err.message || 'Registration failed')
     } finally {
@@ -182,8 +272,8 @@ export function RegisterPage() {
     }
   }
 
-  // ── Token loading / error states ───────────────────────────────────────────
-  if (tokenLoading) {
+  // ── Loading states ───────────────────────────────────────────────────────────
+  if (tokenLoading || isFirstUser === null) {
     return (
       <div className="min-h-screen flex items-center justify-center bg-slate-50">
         <LoadingSpinner className="w-8 h-8" />
@@ -208,8 +298,31 @@ export function RegisterPage() {
   }
 
   const isInvite = !!inviteToken && !!invitePreview
-  const showDomainMatchPrompt = domainMatchAccountId && domainMatchChoice === null && useType === 'company'
+  const showDomainMatchPrompt = domainMatchAccountId && domainMatchChoice === null && useType === 'company' && !isFirstUser
   const effectiveEmail = isInvite ? invitePreview.email : email
+  const showUseTypeToggle = !isInvite && !isFirstUser
+
+  // Header text based on scenario
+  let headerTitle = 'Create your account'
+  let headerSubtitle: React.ReactNode = null
+
+  if (isFirstUser) {
+    headerTitle = 'Create system administrator account'
+    headerSubtitle = (
+      <p className="mt-2 text-center text-sm text-slate-500">
+        You're the first user. This account will have full system access.
+      </p>
+    )
+  } else if (isInvite) {
+    headerTitle = `Join ${invitePreview.account_name ?? 'the team'}`
+    if (invitePreview.role_name) {
+      headerSubtitle = (
+        <p className="mt-2 text-center text-sm text-slate-500">
+          You've been invited as <span className="font-medium">{invitePreview.role_name}</span>
+        </p>
+      )
+    }
+  }
 
   return (
     <div className="min-h-screen flex items-center justify-center bg-slate-50 py-12 px-4 sm:px-6 lg:px-8">
@@ -221,19 +334,17 @@ export function RegisterPage() {
             <span className="text-white font-bold text-xl">S</span>
           </div>
           <h2 className="mt-6 text-center text-3xl font-extrabold text-slate-900">
-            {isInvite ? `Join ${invitePreview.account_name ?? 'the team'}` : 'Create your account'}
+            {headerTitle}
           </h2>
-          {isInvite && invitePreview.role_name && (
-            <p className="mt-2 text-center text-sm text-slate-500">
-              You've been invited as <span className="font-medium">{invitePreview.role_name}</span>
+          {headerSubtitle}
+          {!isFirstUser && (
+            <p className="mt-2 text-center text-sm text-slate-600">
+              Already have an account?{' '}
+              <Link to="/login" className="font-medium text-blue-600 hover:text-blue-500">
+                Sign in
+              </Link>
             </p>
           )}
-          <p className="mt-2 text-center text-sm text-slate-600">
-            Already have an account?{' '}
-            <Link to="/login" className="font-medium text-blue-600 hover:text-blue-500">
-              Sign in
-            </Link>
-          </p>
         </div>
 
         <form className="mt-8 space-y-6" onSubmit={handleSubmit}>
@@ -244,8 +355,8 @@ export function RegisterPage() {
           )}
 
           <div className="space-y-4">
-            {/* Personal / Company toggle — only for walk-up */}
-            {!isInvite && (
+            {/* Personal / Company toggle — only for walk-up, not first user */}
+            {showUseTypeToggle && (
               <div>
                 <label className="block text-sm font-medium text-slate-700 mb-2">
                   Account type
@@ -343,7 +454,7 @@ export function RegisterPage() {
             )}
 
             {/* Company name — shown for company type when not joining existing */}
-            {!isInvite && useType === 'company' && domainMatchChoice !== 'join' && (
+            {!isInvite && useType === 'company' && domainMatchChoice !== 'join' && !isFirstUser && (
               <div>
                 <label htmlFor="companyName" className="block text-sm font-medium text-slate-700">
                   Company name
@@ -402,18 +513,19 @@ export function RegisterPage() {
 
           <button
             type="submit"
-            disabled={isLoading || (showDomainMatchPrompt ? false : false)}
+            disabled={isLoading}
             className="group relative w-full flex justify-center py-2 px-4 border border-transparent rounded-[5px] shadow-sm text-sm font-medium text-white bg-slate-900 hover:bg-slate-800 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500 disabled:opacity-50 disabled:cursor-not-allowed"
           >
             {isLoading ? (
-              <>
-                <LoadingSpinner size="sm" />
-                <span className="ml-2">Creating account...</span>
-              </>
+              <LoadingSpinner className="w-5 h-5" />
+            ) : isFirstUser ? (
+              'Create System Admin Account'
+            ) : isInvite ? (
+              'Accept Invite'
             ) : domainMatchChoice === 'join' ? (
-              'Request access'
+              'Request to Join'
             ) : (
-              'Create account'
+              'Create Account'
             )}
           </button>
         </form>

package/config/vite.config.ts

@@ -10,6 +10,10 @@ export default defineConfig({
 
   // Root directory for the assembled app
   root: path.resolve(__dirname, '../.assembled/src'),
+
+  // Public directory for static files copied to dist
+  // Only spine.config.json is exposed publicly from project root
+  publicDir: path.resolve(__dirname, '../public'),
   
   // Build configuration
   build: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-framework",
-  "version": "0.3.55",
+  "version": "0.3.56",
   "description": "Multi-tenant, modular application platform for modern SaaS systems",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
     "scripts/",
     "config/",
     "netlify.toml",
+    "spine.config.json",
     ".framework/cli/bin.js",
     ".framework/cli/",
     ".framework/docs/",
@@ -21,6 +22,7 @@
     ".framework/migrations/004_enhancements.sql",
     ".framework/migrations/005_auth_user_trigger.sql",
     ".framework/migrations/006_fix_current_actor_id.sql",
+    ".framework/migrations/016_invites.sql",
     ".framework/public/",
     ".framework/scripts/",
     ".framework/seeds/",

package/scripts/assemble-frontend.sh

@@ -61,6 +61,13 @@ if [ -f "$PROJECT_ROOT/.framework/public/_redirects" ]; then
   echo "  ✓ Core: _redirects copied to Vite-served directory for Netlify dev"
 fi
 
+# 3.6. Copy spine.config.json to public directory for runtime access
+if [ -f "$PROJECT_ROOT/spine.config.json" ]; then
+  mkdir -p "$TARGET_SRC_DIR/public"
+  cp "$PROJECT_ROOT/spine.config.json" "$TARGET_SRC_DIR/public/spine.config.json"
+  echo "  ✓ Config: spine.config.json copied to public/"
+fi
+
 # 6. Overlay custom src (overrides + additions)
 if [ -d "$CUSTOM_SRC_DIR" ]; then
   # Copy files and subdirectories

package/spine.config.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "./.framework/schemas/spine.config.schema.json",
+  "registration": {
+    "default_app": "portal",
+    "default_role": "member",
+    "allow_url_override": true,
+    "apps": {
+      "portal": {
+        "role": "member",
+        "path": "/portal",
+        "enabled": true
+      },
+      "cortex": {
+        "role": "support",
+        "path": "/cortex",
+        "enabled": true
+      }
+    }
+  }
+}