spine-framework 0.3.75 → 0.3.77

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

@@ -286,48 +286,66 @@ async function seedApp(appDir: string, appSlug: string) {
   const appId = appRow.id
   console.log(`  ✓ App registered (id: ${appId})`)
 
-  // Seed types
-  const typesPath = join(appDir, 'seed/types.json')
-  if (existsSync(typesPath)) {
-    const types = JSON.parse(readFileSync(typesPath, 'utf8'))
-    console.log(`  Seeding ${types.length} type(s) for ${appSlug}...`)
-    for (const type of types) {
-      const { error } = await db
-        .from('types')
-        .upsert({ ...type, app_id: appId }, { onConflict: 'app_id,kind,slug' })
-      if (error) console.warn(`    ⚠ type ${type.slug}: ${error.message}`)
-    }
-    console.log(`  ✓ Types seeded`)
+  // ── Manifest-driven seed loop ─────────────────────────────────────────────
+  // If manifest declares a `seed` array, use it. Each entry:
+  //   { file, table, conflict, inject_app_id? }
+  // inject_app_id defaults to true — set false for tables with no app_id column.
+  //
+  // Fallback: if no manifest.seed, use legacy hardcoded behavior so existing
+  // apps without a seed block continue to work.
+  // ─────────────────────────────────────────────────────────────────────────
+
+  interface SeedEntry {
+    file: string
+    table: string
+    conflict: string
+    inject_app_id?: boolean
   }
 
-  // Seed roles
-  const rolesPath = join(appDir, 'seed/roles.json')
-  if (existsSync(rolesPath)) {
-    const roles = JSON.parse(readFileSync(rolesPath, 'utf8'))
-    console.log(`  Seeding ${roles.length} role(s) for ${appSlug}...`)
-    for (const role of roles) {
-      const { error } = await db
-        .from('roles')
-        .upsert({ ...role, app_id: appId }, { onConflict: 'app_id,slug' })
-      if (error) console.warn(`    ⚠ role ${role.slug}: ${error.message}`)
+  const seedEntries: SeedEntry[] = Array.isArray(manifest.seed)
+    ? manifest.seed
+    : [
+        // Legacy fallback — matches pre-019 behavior
+        { file: 'seed/roles.json',      table: 'roles',      conflict: 'app_id,slug' },
+        { file: 'seed/types.json',       table: 'types',      conflict: 'app_id,kind,slug' },
+        { file: 'seed/link-types.json',  table: 'link_types', conflict: 'app_id,slug' },
+      ]
+
+  for (const entry of seedEntries) {
+    const filePath = join(appDir, entry.file)
+    if (!existsSync(filePath)) {
+      console.log(`  ○ ${entry.file} not found, skipping`)
+      continue
+    }
+
+    let records: Record<string, any>[]
+    try {
+      records = JSON.parse(readFileSync(filePath, 'utf8'))
+    } catch {
+      console.warn(`  ⚠ Could not parse ${entry.file}, skipping`)
+      continue
     }
-    console.log(`  ✓ Roles seeded`)
-  }
 
-  // Seed link-types
-  const linkTypesPath = join(appDir, 'seed/link-types.json')
-  if (existsSync(linkTypesPath)) {
-    const linkTypes = JSON.parse(readFileSync(linkTypesPath, 'utf8'))
-    if (linkTypes.length > 0) {
-      console.log(`  Seeding ${linkTypes.length} link type(s) for ${appSlug}...`)
-      for (const lt of linkTypes) {
-        const { error } = await db
-          .from('link_types')
-          .upsert({ ...lt, app_id: appId }, { onConflict: 'app_id,slug' })
-        if (error) console.warn(`    ⚠ link_type ${lt.slug}: ${error.message}`)
+    if (!Array.isArray(records) || records.length === 0) {
+      console.log(`  ○ ${entry.file} is empty, skipping`)
+      continue
+    }
+
+    const injectAppId = entry.inject_app_id !== false // default true
+    console.log(`  Seeding ${records.length} record(s) from ${entry.file} → ${entry.table}...`)
+
+    for (const record of records) {
+      const row = injectAppId ? { ...record, app_id: appId } : { ...record }
+      const { error } = await db
+        .from(entry.table)
+        .upsert(row, { onConflict: entry.conflict })
+      if (error) {
+        const label = record.slug ?? record.name ?? JSON.stringify(record).slice(0, 40)
+        console.warn(`    ⚠ ${entry.table} "${label}": ${error.message}`)
       }
-      console.log(`  ✓ Link types seeded`)
     }
+
+    console.log(`  ✓ ${entry.table} seeded`)
   }
 }
 

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

@@ -8,11 +8,21 @@ import { fileURLToPath } from 'url'
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
 
+interface SeedEntry {
+  file: string
+  table: string
+  conflict: string
+  inject_app_id?: boolean
+}
+
 interface Manifest {
   name: string
   slug: string
   version: string
   app_type: 'full' | 'ui' | 'backend' | 'data'
+  entry_point?: string
+  sidebar_component?: string
+  seed?: SeedEntry[]
   registration?: {
     enabled?: boolean
     default_role?: string
@@ -25,6 +35,7 @@ interface Manifest {
 interface PackageJson {
   name: string
   version: string
+  private?: boolean
   files?: string[]
   spine?: {
     type?: string
@@ -170,6 +181,68 @@ function validateDevinDirectory(appPath: string): void {
   }
 }
 
+function validateManifestComponents(appPath: string, manifest: Manifest): void {
+  // entry_point — if declared, the file must exist
+  if (manifest.entry_point) {
+    const ep = manifest.entry_point.replace(/^\.\//, '')
+    if (!existsSync(join(appPath, ep))) {
+      throw new ValidationError(`❌ manifest.json entry_point "${manifest.entry_point}" does not exist`)
+    }
+  }
+
+  // sidebar_component — if declared, the file must exist
+  if (manifest.sidebar_component) {
+    const sc = manifest.sidebar_component.replace(/^\.\//, '')
+    if (!existsSync(join(appPath, sc))) {
+      throw new ValidationError(`❌ manifest.json sidebar_component "${manifest.sidebar_component}" does not exist`)
+    }
+  }
+
+  // registration — account_strategy "existing" requires target_account
+  if (manifest.registration?.account_strategy === 'existing' && !manifest.registration?.target_account) {
+    throw new ValidationError(`❌ manifest.json registration.account_strategy is "existing" but target_account is not set`)
+  }
+}
+
+function validateSeedBlock(appPath: string, manifest: Manifest): void {
+  if (!manifest.seed) return // optional — legacy apps without seed block are fine
+
+  if (!Array.isArray(manifest.seed)) {
+    throw new ValidationError('❌ manifest.json seed must be an array')
+  }
+
+  for (const entry of manifest.seed) {
+    if (!entry.file || !entry.table || !entry.conflict) {
+      throw new ValidationError(
+        `❌ manifest.json seed entry missing required field(s) (file, table, conflict): ${JSON.stringify(entry)}`
+      )
+    }
+    const filePath = join(appPath, entry.file)
+    if (!existsSync(filePath)) {
+      throw new ValidationError(`❌ manifest.json seed entry file "${entry.file}" does not exist`)
+    }
+    // Verify the file is valid JSON and an array
+    try {
+      const contents = JSON.parse(readFileSync(filePath, 'utf8'))
+      if (!Array.isArray(contents)) {
+        throw new ValidationError(`❌ Seed file "${entry.file}" must export a JSON array`)
+      }
+    } catch (err: any) {
+      if (err instanceof ValidationError) throw err
+      throw new ValidationError(`❌ Seed file "${entry.file}" is not valid JSON: ${err.message}`)
+    }
+  }
+}
+
+function validatePackagePublishability(packageJson: PackageJson): void {
+  if (packageJson.private === true) {
+    throw new ValidationError('❌ package.json has "private": true — app cannot be published to npm')
+  }
+  if (packageJson.private === undefined) {
+    console.warn('⚠️  package.json is missing "private": false — add it to confirm the package is publishable')
+  }
+}
+
 function validatePackageFiles(appPath: string, packageJson: PackageJson): void {
   const { files = [] } = packageJson
   
@@ -202,13 +275,22 @@ function validateApp(appPath: string): void {
     
     validateRequiredFiles(appPath, manifest)
     console.log(`✅ Required files present for app_type: ${manifest.app_type}`)
-    
+
+    validateManifestComponents(appPath, manifest)
+    console.log(`✅ manifest.json entry_point, sidebar_component, and registration valid`)
+
+    validateSeedBlock(appPath, manifest)
+    console.log(`✅ manifest.json seed block valid`)
+
     validateAllowedDirectories(appPath)
     console.log(`✅ No unknown directories found`)
-    
+
     validateDevinDirectory(appPath)
     console.log(`✅ .devin/ directory valid (if present)`)
-    
+
+    validatePackagePublishability(packageJson)
+    console.log(`✅ package.json publishability valid`)
+
     validatePackageFiles(appPath, packageJson)
     console.log(`✅ package.json files array checked`)
     

package/.framework/scripts/assemble-frontend.sh

@@ -48,19 +48,29 @@ if [ -f "$PROJECT_ROOT/.framework/index.html" ]; then
   echo "  ✓ Core: index.html (paths fixed)"
 fi
 
-# 3. Copy public assets from .framework → assembled public dir (Vite serves from <root>/public)
+# 3. Copy public assets from .framework
+# Vite's publicDir is set to PROJECT_ROOT/public (i.e. ../public relative to .assembled/src)
+# so static files must go there to be served at the root URL
+VITE_PUBLIC_DIR="$PROJECT_ROOT/public"
 if [ -d "$PROJECT_ROOT/.framework/public" ]; then
-  mkdir -p "$TARGET_SRC_DIR/public"
-  cp -r "$PROJECT_ROOT/.framework/public"/* "$TARGET_SRC_DIR/public/" 2>/dev/null || true
+  mkdir -p "$VITE_PUBLIC_DIR"
+  cp -r "$PROJECT_ROOT/.framework/public"/* "$VITE_PUBLIC_DIR/" 2>/dev/null || true
   echo "  ✓ Core: $(find "$PROJECT_ROOT/.framework/public" -type f | wc -l | tr -d ' ') public files"
 fi
 
-# 3.5. Copy _redirects to Vite-served directory for Netlify dev
+# 3.5. Copy _redirects to Vite-served root for Netlify dev (served from .assembled/src root)
 if [ -f "$PROJECT_ROOT/.framework/public/_redirects" ]; then
   cp "$PROJECT_ROOT/.framework/public/_redirects" "$TARGET_SRC_DIR/_redirects"
   echo "  ✓ Core: _redirects copied to Vite-served directory for Netlify dev"
 fi
 
+# 3.6. Copy spine.config.json to Vite publicDir so it's served at /spine.config.json
+if [ -f "$PROJECT_ROOT/spine.config.json" ]; then
+  mkdir -p "$VITE_PUBLIC_DIR"
+  cp "$PROJECT_ROOT/spine.config.json" "$VITE_PUBLIC_DIR/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/custom/.devin/AGENT.md

@@ -0,0 +1,286 @@
+# Spine Framework — Custom Apps Agent Guide
+
+This document explains the structure, contract, and tooling for apps under `custom/apps/`. Read this before touching any app code.
+
+---
+
+## Directory Layout
+
+Every app lives at `custom/apps/{slug}/` and must follow this structure:
+
+```
+custom/apps/{slug}/
+├── package.json          # npm identity + spine metadata block
+├── manifest.json         # runtime contract — the source of truth
+├── index.tsx             # default export: root React component
+├── components/           # app-level shared components (sidebar, cards, etc.)
+├── pages/                # route-mapped page components
+│   └── {section}/
+│       └── SomePage.tsx
+├── functions/            # Netlify function handlers scoped to this app
+├── hooks/                # React hooks
+├── utils/                # Pure utility functions
+├── public/               # Static assets copied to PROJECT_ROOT/public/ at assemble time
+└── seed/                 # Data seeded into the DB on install
+    ├── roles.json
+    ├── types.json
+    ├── link-types.json
+    └── (any other declared seed files)
+```
+
+No other top-level directories are allowed. `validate-app` will fail on unknown directories.
+
+---
+
+## package.json — Required Shape
+
+```json
+{
+  "name": "spine-framework-{slug}",
+  "version": "X.Y.Z",
+  "private": false,
+  "description": "...",
+  "peerDependencies": {
+    "spine-framework": ">=0.1.0"
+  },
+  "files": [
+    "index.tsx",
+    "manifest.json",
+    "seed/",
+    "pages/",
+    "components/",
+    "hooks/",
+    "utils/",
+    "functions/",
+    "public/",
+    "README.md"
+  ],
+  "scripts": {
+    "validate": "npx spine-framework validate-app ."
+  },
+  "spine": {
+    "type": "app",
+    "slug": "{slug}",
+    "manifestPath": "manifest.json"
+  }
+}
+```
+
+**Rules:**
+- `"private": false` is required — apps must be publishable to npm
+- `files` must include every directory that exists in the app
+- `version` must match `manifest.json` version exactly
+- `spine.slug` must match `manifest.json` slug exactly
+- Package name convention: `spine-framework-{slug}`
+
+---
+
+## manifest.json — Full Contract
+
+```json
+{
+  "name": "My App",
+  "slug": "my-app",
+  "description": "...",
+  "version": "X.Y.Z",
+  "app_type": "full",
+  "required_roles": ["role-slug"],
+  "routes": ["/my-app", "/my-app/page"],
+  "nav_items": [
+    { "title": "Home", "path": "/my-app", "icon": "Home", "order": 1 }
+  ],
+  "features": ["feature-a", "feature-b"],
+  "dependencies": ["items", "accounts"],
+  "entry_point": "./index.tsx",
+  "sidebar_component": "./components/MyAppSidebar.tsx",
+  "seed": [
+    { "file": "seed/roles.json",     "table": "roles",      "conflict": "app_id,slug" },
+    { "file": "seed/types.json",      "table": "types",      "conflict": "app_id,kind,slug" },
+    { "file": "seed/link-types.json", "table": "link_types", "conflict": "app_id,slug" }
+  ],
+  "registration": {
+    "enabled": true,
+    "default_role": "role-slug",
+    "redirect_path": "/my-app",
+    "account_strategy": "new"
+  }
+}
+```
+
+### Field Reference
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `name` | yes | Display name — written to `apps.name` in DB |
+| `slug` | yes | Unique identifier — written to `apps.slug` |
+| `version` | yes | Must match `package.json` version |
+| `app_type` | yes | One of: `full`, `ui`, `backend`, `data` |
+| `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 |
+| `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) |
+| `registration` | if app supports self-registration | Controls `spine.config.json` registration entry |
+
+### `app_type` values
+
+- `full` — has UI (pages, components) and backend (functions). Requires `index.tsx`, `pages/`, `functions/`
+- `ui` — frontend only. Requires `index.tsx`, `pages/`
+- `backend` — functions only. Requires `functions/`
+- `data` — schema/seed only. No UI or functions required
+
+---
+
+## 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.
+
+### Seed entry format
+
+```json
+{ "file": "seed/roles.json", "table": "roles", "conflict": "app_id,slug" }
+```
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `file` | yes | Path relative to app root |
+| `table` | yes | Supabase table name |
+| `conflict` | yes | Column(s) for `onConflict` upsert (comma-separated) |
+| `inject_app_id` | no | Default `true` — set `false` for tables without `app_id` |
+
+### Common conflict keys
+
+| Table | conflict |
+|-------|----------|
+| `roles` | `app_id,slug` |
+| `types` | `app_id,kind,slug` |
+| `link_types` | `app_id,slug` |
+| `triggers` | `app_id,name` |
+
+### Seed file format
+
+Every seed file must be a JSON array. Each object maps to one DB row. Do NOT include `id` or `app_id` — these are set by the framework at install time.
+
+```json
+[
+  {
+    "slug": "my-role",
+    "name": "My Role",
+    "description": "...",
+    "permissions": ["*"],
+    "is_system": true,
+    "is_active": true,
+    "is_protected": false
+  }
+]
+```
+
+All seed files must be idempotent — safe to run against an existing DB without creating duplicates.
+
+---
+
+## registration block
+
+Controls how users self-register for this app. Written to `spine.config.json` by `install-app`.
+
+```json
+"registration": {
+  "enabled": true,
+  "default_role": "member",
+  "redirect_path": "/portal",
+  "account_strategy": "new"
+}
+```
+
+| `account_strategy` | Behavior |
+|--------------------|----------|
+| `new` | Creates a new account per registering user (customer-facing apps) |
+| `existing` | Assigns user to an existing account — requires `target_account` |
+| `choice` | User chooses at registration |
+
+If `account_strategy` is `existing`, `target_account` (account slug) is required.
+
+---
+
+## CLI Commands
+
+```bash
+# Install an app from npm
+npx spine-framework install-app spine-framework-{slug}
+npx spine-framework install-app spine-framework-{slug}@next  # pre-release
+
+# Validate an app before publishing
+npx spine-framework validate-app custom/apps/{slug}
+# or from inside the app directory:
+npm run validate
+
+# Uninstall an app
+npx spine-framework uninstall-app spine-framework-{slug}
+
+# Update an app
+npx spine-framework update-app spine-framework-{slug}
+```
+
+`validate-app` checks:
+- `manifest.json` present, valid JSON, all required fields
+- `package.json` present, versions match, `"private": false`
+- Required files exist for `app_type`
+- `entry_point` and `sidebar_component` files exist (if declared)
+- `seed` block entries are valid and all declared files exist
+- `registration.account_strategy: "existing"` has `target_account`
+- No unknown directories
+- `.devin/` present → must contain `AGENTS.md` or `AGENT.md`
+- All directories in `files` array are present
+
+---
+
+## Assemble
+
+`assemble-frontend.sh` and `assemble-functions.sh` pick up app files at build time:
+
+- `functions/` → assembled into the Netlify functions directory
+- `public/` → copied to `PROJECT_ROOT/public/` (Vite's publicDir)
+- `pages/`, `components/`, `hooks/`, `utils/` → assembled into `.assembled/src/{slug}/`
+
+**Important:** `public/` assets must go to `PROJECT_ROOT/public/`, not `.assembled/src/public/`. This was a known bug fixed in `spine-framework@0.3.76`.
+
+---
+
+## Publishing
+
+Apps are published independently to npm, separate from `spine-framework`.
+
+```bash
+# From inside custom/apps/{slug}/
+npm version patch   # bump version (must match manifest.json!)
+# Also bump version in manifest.json to match
+npm publish --tag next --access public   # pre-release
+npm publish --tag latest --access public # stable release
+```
+
+Always publish with `--tag next` for development/testing. Promote to `--tag latest` only when stable and tested E2E in a dogfood project.
+
+Version must be kept in sync between `package.json` and `manifest.json` — `validate-app` will fail if they differ.
+
+---
+
+## Current Apps
+
+| Slug | Package | Description |
+|------|---------|-------------|
+| `cortex` | `spine-framework-cortex` | Internal workspace: CRM, Support, Community, KB |
+| `portal` | `spine-framework-portal` | Customer-facing: Tickets, KB, Courses, Community |
+
+---
+
+## Adding a New App
+
+1. Create `custom/apps/{slug}/` with the directory structure above
+2. Write `package.json` and `manifest.json` following the templates above
+3. Write `index.tsx` exporting the root React component
+4. Write `components/{Slug}Sidebar.tsx` and declare it as `sidebar_component`
+5. Write seed files and declare them in the `seed` block
+6. Run `npm run validate` — fix all errors before proceeding
+7. Publish with `--tag next`
+8. Test E2E: `npx spine-framework install-app spine-framework-{slug}@next`

package/package.json

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

package/scripts/assemble-frontend.sh

@@ -48,23 +48,26 @@ if [ -f "$PROJECT_ROOT/.framework/index.html" ]; then
   echo "  ✓ Core: index.html (paths fixed)"
 fi
 
-# 3. Copy public assets from .framework → assembled public dir (Vite serves from <root>/public)
+# 3. Copy public assets from .framework
+# Vite's publicDir is set to PROJECT_ROOT/public (i.e. ../public relative to .assembled/src)
+# so static files must go there to be served at the root URL
+VITE_PUBLIC_DIR="$PROJECT_ROOT/public"
 if [ -d "$PROJECT_ROOT/.framework/public" ]; then
-  mkdir -p "$TARGET_SRC_DIR/public"
-  cp -r "$PROJECT_ROOT/.framework/public"/* "$TARGET_SRC_DIR/public/" 2>/dev/null || true
+  mkdir -p "$VITE_PUBLIC_DIR"
+  cp -r "$PROJECT_ROOT/.framework/public"/* "$VITE_PUBLIC_DIR/" 2>/dev/null || true
   echo "  ✓ Core: $(find "$PROJECT_ROOT/.framework/public" -type f | wc -l | tr -d ' ') public files"
 fi
 
-# 3.5. Copy _redirects to Vite-served directory for Netlify dev
+# 3.5. Copy _redirects to Vite-served root for Netlify dev (served from .assembled/src root)
 if [ -f "$PROJECT_ROOT/.framework/public/_redirects" ]; then
   cp "$PROJECT_ROOT/.framework/public/_redirects" "$TARGET_SRC_DIR/_redirects"
   echo "  ✓ Core: _redirects copied to Vite-served directory for Netlify dev"
 fi
 
-# 3.6. Copy spine.config.json to public directory for runtime access
+# 3.6. Copy spine.config.json to Vite publicDir so it's served at /spine.config.json
 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"
+  mkdir -p "$VITE_PUBLIC_DIR"
+  cp "$PROJECT_ROOT/spine.config.json" "$VITE_PUBLIC_DIR/spine.config.json"
   echo "  ✓ Config: spine.config.json copied to public/"
 fi