spine-framework 0.3.77 → 0.3.78

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

@@ -65,24 +65,33 @@ export function registerInstallAppCommands(program: Command) {
 
         // 4. Copy app files to custom/apps/<slug>/
         const appDest = join(PROJECT_ROOT, 'custom/apps', appSlug)
-        if (!existsSync(appDest)) {
+        const isReinstall = existsSync(appDest)
+        if (!isReinstall) {
           mkdirSync(appDest, { recursive: true })
         }
 
-        // Copy all allowed directories and files
+        // On reinstall, preserve the developer's local manifest.json — it is
+        // the source of truth for route_prefix and other project-level config.
+        // All other files are updated from npm as normal.
         const allowedEntries = [
           'index.tsx', 'manifest.json', 'package.json',
           'pages', 'components', 'hooks', 'utils', 'functions', 'seed', 'public'
         ]
-        
+
         console.log(`  Copying files from ${pkgPath} to ${appDest}`)
-        
+
         for (const entry of allowedEntries) {
           const src = join(pkgPath, entry)
-          if (existsSync(src)) {
-            console.log(`    Copying ${entry}`)
-            cpSync(src, join(appDest, entry), { recursive: true })
+          if (!existsSync(src)) continue
+
+          // Preserve local manifest on reinstall — developer owns it after first install
+          if (entry === 'manifest.json' && isReinstall) {
+            console.log(`    Preserving local manifest.json (use update-db-app to sync changes)`)
+            continue
           }
+
+          console.log(`    Copying ${entry}`)
+          cpSync(src, join(appDest, entry), { recursive: true })
         }
         console.log(`  ✓ App files copied to custom/apps/${appSlug}/`)
 
@@ -206,6 +215,80 @@ export function registerInstallAppCommands(program: Command) {
     })
 }
 
+  // update-db-app
+  program
+    .command('update-db-app <slug>')
+    .description('Sync local manifest.json changes to the database (no npm, no file changes)')
+    .action(async (slug: string) => {
+      console.log(`\nSyncing manifest to DB for: ${slug}\n`)
+      loadEnv()
+
+      const appDir = join(PROJECT_ROOT, 'custom/apps', slug)
+      const manifestPath = join(appDir, 'manifest.json')
+
+      if (!existsSync(manifestPath)) {
+        console.error(`❌ No app found at custom/apps/${slug}/manifest.json`)
+        console.error(`   Run install-app first: npx spine-framework install-app spine-framework-${slug}`)
+        process.exit(1)
+      }
+
+      const supabaseUrl = process.env.SUPABASE_URL
+      const serviceRoleKey = process.env.SUPABASE_SERVICE_ROLE_KEY
+
+      if (!supabaseUrl || !serviceRoleKey) {
+        console.error('❌ SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY must be set')
+        process.exit(1)
+      }
+
+      let manifest: Record<string, any> = {}
+      try {
+        manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+      } catch {
+        console.error(`❌ Could not parse manifest.json`)
+        process.exit(1)
+      }
+
+      const db = createClient(supabaseUrl, serviceRoleKey, { auth: { persistSession: false } })
+
+      const { data: appRow, error: appErr } = await db
+        .from('apps')
+        .upsert(
+          {
+            slug,
+            name: manifest.name ?? slug,
+            description: manifest.description ?? '',
+            version: manifest.version ?? '1.0.0',
+            nav_items: manifest.nav_items ?? [],
+            app_type: 'custom',
+            source: 'npm',
+            is_active: true,
+            route_prefix: manifest.route_prefix ?? ('/' + slug),
+            renderer: manifest.renderer ?? 'custom',
+            required_roles: manifest.required_roles ?? (manifest.min_role ? [manifest.min_role] : []),
+            min_role: manifest.required_roles?.[0] ?? manifest.min_role ?? null,
+          },
+          { onConflict: 'slug' }
+        )
+        .select('id')
+        .single()
+
+      if (appErr || !appRow?.id) {
+        console.error(`❌ Failed to update app row: ${appErr?.message ?? 'no id returned'}`)
+        process.exit(1)
+      }
+
+      console.log(`  ✓ apps row updated (route_prefix: ${manifest.route_prefix ?? '/' + slug})`)
+
+      // Update registration config in spine.config.json if declared
+      if (manifest.registration?.enabled) {
+        updateRegistrationConfig(slug, manifest.registration)
+      }
+
+      console.log(`\n✅ ${slug} DB synced from local manifest.\n`)
+      console.log(`Next: npm run assemble && netlify dev\n`)
+    })
+}
+
 // ─── HELPERS ────────────────────────────────────────────────────────────────
 
 function resolveAppSlug(pkgPath: string, pkgName: string): string {

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

@@ -181,6 +181,45 @@ function validateDevinDirectory(appPath: string): void {
   }
 }
 
+function validateRoutes(appPath: string, manifest: Manifest): void {
+  if (!manifest.route_prefix) {
+    console.warn('⚠️  manifest.json is missing route_prefix — install-app will default to /{slug}')
+    return
+  }
+
+  const prefix = manifest.route_prefix === '/' ? null : manifest.route_prefix
+
+  if (!Array.isArray((manifest as any).routes)) return
+
+  for (const route of (manifest as any).routes as string[]) {
+    if (prefix && route.startsWith(prefix)) {
+      throw new ValidationError(
+        `❌ manifest.json route "${route}" must be root-relative (should not include route_prefix "${prefix}"). Use "${route.replace(prefix, '') || '/'}" instead.`
+      )
+    }
+    if (!route.startsWith('/')) {
+      throw new ValidationError(
+        `❌ manifest.json route "${route}" must start with /`
+      )
+    }
+  }
+
+  // nav_items paths must also be root-relative
+  if (Array.isArray((manifest as any).nav_items)) {
+    const checkNavItem = (item: any) => {
+      if (item.path && prefix && item.path.startsWith(prefix)) {
+        throw new ValidationError(
+          `❌ manifest.json nav_items path "${item.path}" must be root-relative (should not include route_prefix "${prefix}"). Use "${item.path.replace(prefix, '') || '/'}" instead.`
+        )
+      }
+      if (Array.isArray(item.children)) {
+        for (const child of item.children) checkNavItem(child)
+      }
+    }
+    for (const item of (manifest as any).nav_items) checkNavItem(item)
+  }
+}
+
 function validateManifestComponents(appPath: string, manifest: Manifest): void {
   // entry_point — if declared, the file must exist
   if (manifest.entry_point) {
@@ -276,6 +315,9 @@ function validateApp(appPath: string): void {
     validateRequiredFiles(appPath, manifest)
     console.log(`✅ Required files present for app_type: ${manifest.app_type}`)
 
+    validateRoutes(appPath, manifest)
+    console.log(`✅ manifest.json routes and nav_items are root-relative`)
+
     validateManifestComponents(appPath, manifest)
     console.log(`✅ manifest.json entry_point, sidebar_component, and registration valid`)
 

package/.framework/src/App.tsx

@@ -64,18 +64,23 @@ function AuthenticatedRouter() {
     )
   }
 
-  // Sort: explicit prefixes first, root (/) last
+  // Sort: longer explicit prefixes first (most specific), root (/) last so it
+  // doesn't swallow other routes. spine-framework reserved namespace excluded.
   const sorted = [...apps]
     .filter(app => app.slug !== 'spine-framework' && !app.route_prefix?.startsWith('/spine-framework'))
     .sort((a, b) => {
-      if (a.route_prefix === '/') return 1
+      if (a.route_prefix === '/') return 1   // root always last
       if (b.route_prefix === '/') return -1
       return (b.route_prefix?.length || 0) - (a.route_prefix?.length || 0)
     })
 
-  // Determine default redirect: first app with a route_prefix, or fall back to dashboard
+  // Determine default redirect:
+  //   - If an app owns root ('/'), redirect there directly
+  //   - Otherwise use the first non-root app's prefix
+  //   - Fall back to /dashboard if no apps installed
+  const rootApp = sorted.find(app => app.route_prefix === '/')
   const defaultApp = sorted.find(app => app.route_prefix && app.route_prefix !== '/')
-  const defaultRedirect = defaultApp?.route_prefix || '/dashboard'
+  const defaultRedirect = rootApp ? '/' : (defaultApp?.route_prefix || '/dashboard')
 
   return (
     <Suspense fallback={<div className="min-h-screen flex items-center justify-center"><LoadingSpinner /></div>}>

package/.framework/src/hooks/useAppPath.ts

@@ -0,0 +1,38 @@
+import { useCurrentApp } from '../contexts/AppContext'
+
+/**
+ * Returns a helper function that prepends the current app's route_prefix
+ * to a root-relative path.
+ *
+ * Use this instead of hardcoding absolute paths in app components so that
+ * changing `route_prefix` in manifest.json (and running update-db-app) is
+ * the only change needed to move an app to a new URL location.
+ *
+ * @example
+ * const appPath = useAppPath()
+ * appPath('/dashboard')      // → '/cortex/dashboard'  (if prefix is /cortex)
+ * appPath('/crm/accounts')   // → '/cortex/crm/accounts'
+ * appPath('/')               // → '/cortex'
+ *
+ * // With route_prefix = '/'
+ * appPath('/dashboard')      // → '/dashboard'
+ * appPath('/crm/accounts')   // → '/crm/accounts'
+ */
+export function useAppPath(): (path: string) => string {
+  const app = useCurrentApp()
+
+  // Normalize: '/' prefix means the app owns root — no prefix to prepend.
+  // Any other prefix is prepended as-is (trailing slash stripped).
+  const prefix =
+    !app.route_prefix || app.route_prefix === '/'
+      ? ''
+      : app.route_prefix.replace(/\/$/, '')
+
+  return (path: string): string => {
+    // path should be root-relative (start with /)
+    // If the caller passes '/' return just the prefix (or '/' if no prefix)
+    if (path === '/') return prefix || '/'
+    const normalized = path.startsWith('/') ? path : `/${path}`
+    return `${prefix}${normalized}`
+  }
+}

package/custom/.devin/AGENT.md

@@ -84,10 +84,11 @@ No other top-level directories are allowed. `validate-app` will fail on unknown
   "description": "...",
   "version": "X.Y.Z",
   "app_type": "full",
+  "route_prefix": "/my-app",
   "required_roles": ["role-slug"],
-  "routes": ["/my-app", "/my-app/page"],
+  "routes": ["/", "/page"],
   "nav_items": [
-    { "title": "Home", "path": "/my-app", "icon": "Home", "order": 1 }
+    { "title": "Home", "path": "/", "icon": "Home", "order": 1 }
   ],
   "features": ["feature-a", "feature-b"],
   "dependencies": ["items", "accounts"],
@@ -115,9 +116,10 @@ No other top-level directories are allowed. `validate-app` will fail on unknown
 | `slug` | yes | Unique identifier — written to `apps.slug` |
 | `version` | yes | Must match `package.json` version |
 | `app_type` | yes | One of: `full`, `ui`, `backend`, `data` |
+| `route_prefix` | yes | Where the app is mounted (e.g. `/cortex`, `/`, `/workspace`). Single source of truth for routing. |
 | `required_roles` | yes | Array of role slugs required to access the app |
-| `routes` | recommended | All route paths the app handles |
-| `nav_items` | recommended | Sidebar nav — written to `apps.nav_items` in DB |
+| `routes` | recommended | Root-relative paths the app handles — **must NOT include route_prefix** |
+| `nav_items` | recommended | Root-relative sidebar nav paths — **must NOT include route_prefix** |
 | `entry_point` | yes (full/ui) | Path to root React component (relative to app root) |
 | `sidebar_component` | yes (full/ui) | Path to sidebar component — used by AppWrapper |
 | `seed` | yes | Declares all seed files (see below) |
@@ -132,6 +134,67 @@ No other top-level directories are allowed. `validate-app` will fail on unknown
 
 ---
 
+## Dynamic route_prefix
+
+`route_prefix` in `manifest.json` is the **single source of truth** for where an app is served. Changing it and running `update-db-app` is the only step needed to move an app to a different URL.
+
+### How it flows
+
+1. `manifest.json` declares `"route_prefix": "/cortex"` (or `/`, or anything)
+2. `install-app` / `update-db-app` writes it to `apps.route_prefix` in the DB
+3. `App.tsx` reads all app records and mounts each at `{route_prefix}/*`
+4. Inside the app, `useAppPath()` prepends the prefix to all links — no hardcoded paths
+
+### Rules for routes and nav_items
+
+Routes and nav_items must be **root-relative** — declared from the app's own root, not the full URL:
+
+```json
+// CORRECT
+"route_prefix": "/cortex",
+"routes": ["/", "/dashboard", "/crm/accounts"],
+"nav_items": [{ "title": "Dashboard", "path": "/dashboard" }]
+
+// WRONG — validate-app will reject these
+"routes": ["/cortex", "/cortex/dashboard", "/cortex/crm/accounts"],
+"nav_items": [{ "title": "Dashboard", "path": "/cortex/dashboard" }]
+```
+
+### useAppPath() hook
+
+All absolute links inside an app must use `useAppPath()` instead of hardcoded strings:
+
+```tsx
+import { useAppPath } from '@core/hooks/useAppPath'
+
+function MyComponent() {
+  const appPath = useAppPath()
+
+  return <a href={appPath('/dashboard')}>Dashboard</a>
+  // → '/cortex/dashboard' if route_prefix is /cortex
+  // → '/dashboard'        if route_prefix is /
+}
+```
+
+Use `useAppPath()` in: sidebar nav arrays, breadcrumbs, `navigate()` calls, any `<Link>` with an absolute path.
+
+### Changing an app's location
+
+```bash
+# 1. Edit manifest.json
+"route_prefix": "/"   # was "/cortex"
+
+# 2. Sync to DB (no npm, no file changes)
+npx spine-framework update-db-app cortex
+
+# 3. Rebuild and serve
+npm run assemble && netlify dev
+```
+
+That's the entire workflow. No code changes needed.
+
+---
+
 ## Seed Block
 
 The `seed` array in `manifest.json` declares every file to be seeded into the DB at install time. `install-app` reads this array and runs a generic upsert loop — no hardcoded file names.
@@ -206,10 +269,14 @@ If `account_strategy` is `existing`, `target_account` (account slug) is required
 ## CLI Commands
 
 ```bash
-# Install an app from npm
+# Install an app from npm (first time)
 npx spine-framework install-app spine-framework-{slug}
 npx spine-framework install-app spine-framework-{slug}@next  # pre-release
 
+# Sync local manifest.json changes to the DB (no npm, no file changes)
+# Use this after changing route_prefix, nav_items, registration, etc.
+npx spine-framework update-db-app {slug}
+
 # Validate an app before publishing
 npx spine-framework validate-app custom/apps/{slug}
 # or from inside the app directory:
@@ -218,10 +285,14 @@ npm run validate
 # Uninstall an app
 npx spine-framework uninstall-app spine-framework-{slug}
 
-# Update an app
+# Update app code from npm (preserves local manifest.json)
 npx spine-framework update-app spine-framework-{slug}
 ```
 
+**Key distinction:**
+- `install-app` = get/update code from npm. After first install, `manifest.json` is preserved — the developer owns it.
+- `update-db-app` = push local manifest changes to DB. No npm involved.
+
 `validate-app` checks:
 - `manifest.json` present, valid JSON, all required fields
 - `package.json` present, versions match, `"private": false`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-framework",
-  "version": "0.3.77",
+  "version": "0.3.78",
   "description": "Multi-tenant, modular application platform for modern SaaS systems",
   "type": "module",
   "bin": {