spine-framework 0.4.4 → 0.5.0-rc.5

package/.framework/cli/commands/migrations.ts

@@ -12,11 +12,9 @@
 
 
 import type { Command } from 'commander'
-import { readdirSync, existsSync } from 'fs'
-import { resolve, dirname } from 'path'
-import { fileURLToPath } from 'url'
 import { buildCliContext, printResult, handleError } from '../context.ts'
 import { adminDb } from '../../functions/_shared/index.ts'
+import { collectMigrations } from './migrate.ts'
 // CIL[DOC-VECTOR type="context" content="purpose='CLI migration inspection commands for listing applied migrations and comparing local SQL files'; No verified external callers; imports: .framework/cli/context.ts,.framework/functions/_shared/index.ts"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
@@ -25,42 +23,10 @@ import { adminDb } from '../../functions/_shared/index.ts'
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 // CIL[END stable_id="~/.framework/cli/commands/migrations.ts:module_header:module_header"]
 
-// CIL[BEGIN stable_id="~/.framework/cli/commands/migrations.ts:__filename:constant" type="constant" identity="__filename" parent="~/.framework/cli/commands/migrations.ts"]
-// CIL[DOC-MACRO purpose="Resolve the current module filename from import.meta.url"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide a CommonJS-style __filename value in ESM"]
-// CIL[DOC-CONTEXT module="cli/commands/migrations" layer="utility" related_files=".framework/cli/commands/migrations.ts,.framework/cli/context.ts,.framework/functions/_shared/index.ts"]
-// CIL[DOC-CONTRACT inputs="import.meta.url" outputs="absolute __filename" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="call fileURLToPath on import.meta.url" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-const __filename = fileURLToPath(import.meta.url)
-// CIL[DOC-VECTOR type="context" content="purpose='Resolve the current module filename from import.meta.url'; No verified external callers; imports: .framework/cli/context.ts,.framework/functions/_shared/index.ts"]
-// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
-// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
-// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/cli/commands/migrations.ts:__filename:constant"]
-// CIL[BEGIN stable_id="~/.framework/cli/commands/migrations.ts:__dirname:constant" type="constant" identity="__dirname" parent="~/.framework/cli/commands/migrations.ts"]
-// CIL[DOC-MACRO purpose="Resolve the current module directory name"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide a CommonJS-style __dirname value in ESM"]
-// CIL[DOC-CONTEXT module="cli/commands/migrations" layer="utility" related_files=".framework/cli/commands/migrations.ts,.framework/cli/context.ts,.framework/functions/_shared/index.ts"]
-// CIL[DOC-CONTRACT inputs="__filename" outputs="absolute __dirname" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="call dirname on the resolved __filename" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-const __dirname = dirname(__filename)
-// CIL[DOC-VECTOR type="context" content="purpose='Resolve the current module directory name'; No verified external callers; imports: .framework/cli/context.ts,.framework/functions/_shared/index.ts"]
-// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
-// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
-// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/cli/commands/migrations.ts:__dirname:constant"]
 
 // CIL[BEGIN stable_id="~/.framework/cli/commands/migrations.ts:registerMigrationCommands:function" type="function" identity="registerMigrationCommands" parent="~/.framework/cli/commands/migrations.ts"]
 // CIL[DOC-MACRO purpose="Register migration list and status CLI subcommands"]
-// CIL[DOC-RESPONSIBILITY responsibility="Expose commands that query supabase_migrations and compare local SQL files"]
+// CIL[DOC-RESPONSIBILITY responsibility="Expose commands that query _spine_migrations and compare local SQL files"]
 // CIL[DOC-CONTEXT module="cli/commands/migrations" layer="cli" related_files=".framework/cli/commands/migrations.ts,.framework/cli/context.ts,.framework/functions/_shared/index.ts"]
 // CIL[DOC-CONTRACT inputs="program: Command" outputs="void" errors="Throws on missing migrations directory or failed DB queries" side_effects="Adds commands and options to the Commander program"]
 // CIL[DOC-MICRO logic_summary="Define migrations command, add list and status subcommands with options, perform DB calls and console output" notable_decisions="[]"]
@@ -73,17 +39,16 @@ export function registerMigrationCommands(program: Command) {
 
   migrations
     .command('list')
-    .description('List applied migrations from supabase schema_migrations')
+    .description('List applied migrations from _spine_migrations')
     .option('--json', 'Output as JSON')
     .action(async (opts) => {
       try {
         await buildCliContext()
 
         const { data, error } = await adminDb
-          .schema('supabase_migrations' as any)
-          .from('schema_migrations' as any)
-          .select('version, name, executed_at')
-          .order('version', { ascending: true })
+          .from('_spine_migrations' as any)
+          .select('filename, applied_at')
+          .order('filename', { ascending: true })
 
         if (error) {
           throw new Error(
@@ -106,34 +71,29 @@ export function registerMigrationCommands(program: Command) {
       try {
         await buildCliContext()
 
-        const migrationsDir = resolve(__dirname, '../../migrations')
+        const migrationFiles = collectMigrations(false)
 
-        if (!existsSync(migrationsDir)) {
-          throw new Error(`Migrations directory not found: ${migrationsDir}`)
+        if (migrationFiles.length === 0) {
+          throw new Error('Migrations directory not found (.framework/migrations)')
         }
 
-        const localFiles = readdirSync(migrationsDir)
-          .filter((f: string) => f.endsWith('.sql'))
-          .sort()
-
         const { data: applied, error } = await adminDb
-          .schema('supabase_migrations' as any)
-          .from('schema_migrations' as any)
-          .select('version')
+          .from('_spine_migrations' as any)
+          .select('filename')
 
         if (error) {
           throw new Error(`Could not query migrations: ${error.message}`)
         }
 
         const appliedVersions = new Set(
-          (applied || []).map((r: any) => r.version)
+          (applied || []).map((r: any) => r.filename)
         )
 
-        const status = localFiles.map((file: string) => {
-          const version = file.replace('.sql', '')
-          const isApplied = appliedVersions.has(version)
+        const status = migrationFiles.map(({ name }) => {
+          const version = name.replace('.sql', '')
+          const isApplied = appliedVersions.has(name)
           return {
-            file,
+            file: name,
             version,
             status: isApplied ? 'applied' : 'pending'
           }

package/.framework/cli/commands/upgrade.ts

@@ -22,6 +22,8 @@ import {
   mergePackageJson,
   writeFrozenManifest,
   cmpSemver,
+  syncAgentFiles,
+  collectAgentFileHashes,
 } from '../lib/project-files.ts'
 // CIL[END stable_id="~/.framework/cli/commands/upgrade.ts:module_header:module_header"]
 
@@ -167,11 +169,27 @@ function runUpgrade(opts: { dryRun: boolean; force: boolean }): void {
     .filter((rel) => rel.startsWith('.framework/migrations/') && rel.endsWith('.sql') && !(rel in oldFiles))
 
   console.log(`\n  ${added.length} added · ${changed.length} changed · ${removed.length} removed · ${kept} unchanged`)
+
+  // Agent assets are computed before the dry-run exit so the report is complete:
+  // AGENTS.md gets its marker-delimited framework block refreshed in place
+  // (customer content outside the markers is preserved); .devin/skills/spine-*
+  // dirs are replaced wholesale (customer-owned sibling dirs untouched).
+  const agentActions = syncAgentFiles({
+    pkgRoot: PACKAGE_ROOT,
+    projectRoot: PROJECT_ROOT,
+    entries: profile.agent_files ?? [],
+    version: newVersion,
+    dryRun: true,
+  })
+
   if (opts.dryRun) {
     for (const f of added) console.log(`     + ${f}`)
     for (const f of changed) console.log(`     ~ ${f}`)
     for (const f of removed) console.log(`     - ${f}`)
     for (const f of staleOutside) console.log(`     ? ${f} (dropped upstream, left in place)`)
+    for (const a of agentActions) {
+      if (a.action !== 'unchanged') console.log(`     ~ ${a.rel} (agent asset: ${a.action})`)
+    }
     if (newMigrations.length > 0) {
       console.log(`\n  New migrations in this version (${newMigrations.length}):`)
       for (const rel of newMigrations) console.log(`     ${rel.split('/').pop()}`)
@@ -186,6 +204,22 @@ function runUpgrade(opts: { dryRun: boolean; force: boolean }): void {
   for (const rel of staleOutside) console.log(`  ⚠ ${rel} is no longer shipped upstream — left in place`)
   console.log(`  ✓ framework files synced (${files.length})`)
 
+  // 4b. Apply agent assets (the dry-run pass above reported; this one writes)
+  const applied = syncAgentFiles({
+    pkgRoot: PACKAGE_ROOT,
+    projectRoot: PROJECT_ROOT,
+    entries: profile.agent_files ?? [],
+    version: newVersion,
+  })
+  for (const a of applied) {
+    if (a.action === 'prepended') {
+      console.log(`  ⚠ ${a.rel} had no spine-framework markers — fresh framework block prepended`)
+    } else if (a.action !== 'unchanged') {
+      console.log(`  ✓ ${a.rel} (${a.action})`)
+    }
+  }
+  console.log('  ✓ agent assets synced (AGENTS.md + .devin/skills/spine-*)')
+
   // 5. package.json — framework scripts/deps, exact pin
   const pkgPath = join(PROJECT_ROOT, 'package.json')
   const existingPkg = existsSync(pkgPath) ? JSON.parse(readFileSync(pkgPath, 'utf8')) : {}
@@ -222,6 +256,7 @@ function runUpgrade(opts: { dryRun: boolean; force: boolean }): void {
     projectRoot: PROJECT_ROOT,
     frameworkVersion: newVersion,
     frameworkDeps: merged.frameworkDeps,
+    agentFiles: collectAgentFileHashes(PROJECT_ROOT, profile.agent_files ?? []),
   })
   console.log(`  ✓ .spine-manifest.json regenerated (${manifest.fileCount} files)`)
 

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

@@ -20,6 +20,7 @@
 
 import { Command } from 'commander'
 import { readFileSync, existsSync, readdirSync, statSync, realpathSync } from 'fs'
+import { createHash } from 'crypto'
 import { join, dirname, resolve, isAbsolute, sep } from 'path'
 import { fileURLToPath } from 'url'
 // CIL[DOC-VECTOR type="context" content="purpose='Provide module-level imports for the validate-app CLI command'; No verified external callers; imports: none"]
@@ -127,6 +128,14 @@ interface Manifest {
     parent_account?: string
     default_workspace_name?: boolean
   }
+  route_prefix?: string
+  preview_domain?: string
+  prod_domain?: string
+  preview_route_prefix?: string
+  prod_route_prefix?: string
+  agent?: {
+    skill_prefix?: string
+  }
 }
 // CIL[DOC-VECTOR type="context" content="purpose='Define the shape of an app manifest'; No verified external callers; imports: none"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
@@ -337,7 +346,8 @@ function validateAllowedDirectories(appPath: string): void {
   const allowedDirs = [
     'pages', 'components', 'hooks', 'utils', 'functions',
     'seed', 'public', 'lib', 'views', 'docs', 'mcp',
-    'migrations', 'migrations-archive', 'tests'
+    'migrations', 'migrations-archive', 'tests', 'installer',
+    'agent', 'src'
   ]
   
   const entries = readdirSync(appPath, { withFileTypes: true })
@@ -414,6 +424,23 @@ function validateDevinDirectory(appPath: string): void {
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stable]
 function validateRoutes(appPath: string, manifest: Manifest): void {
+  // Host-keyed mount overrides: an override prefix only makes sense with its
+  // domain trigger, and both must be root-relative.
+  const pairs: [keyof Manifest, keyof Manifest][] = [
+    ['prod_route_prefix', 'prod_domain'],
+    ['preview_route_prefix', 'preview_domain'],
+  ]
+  for (const [prefixKey, domainKey] of pairs) {
+    const prefix = manifest[prefixKey] as string | undefined
+    if (prefix === undefined) continue
+    if (typeof prefix !== 'string' || !prefix.startsWith('/')) {
+      throw new ValidationError(`❌ manifest.json ${prefixKey} "${prefix}" must start with /`)
+    }
+    if (!manifest[domainKey]) {
+      throw new ValidationError(`❌ manifest.json ${prefixKey} requires ${domainKey} — the override has no trigger host without it`)
+    }
+  }
+
   if (!manifest.route_prefix) {
     console.warn('⚠️  manifest.json is missing route_prefix — install-app will default to /{slug}')
     return
@@ -642,6 +669,7 @@ function validateOwnedTypes(appPath: string, manifest: Manifest): void {
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 // CIL[END stable_id="~/.framework/cli/commands/validate-app.ts:validateownedtypes:function"]
+// CIL[BEGIN stable_id="~/.framework/cli/commands/validate-app.ts:validateknowledgeenvelope:function" type="function" identity="validateKnowledgeEnvelope" parent="~/.framework/cli/commands/validate-app.ts"]
 // CIL[DOC-MACRO purpose="Validate the manifest knowledge envelope and seed prompt-config picks"]
 // CIL[DOC-RESPONSIBILITY responsibility="Check config.knowledge shape and verify seeded prompt_configs' retrieval_policy picks stay inside the envelope — an agent may narrow the app envelope but never widen it"]
 // CIL[DOC-CONTEXT module="validate-app" layer="cli" related_files=".framework/functions/_shared/kb.ts"]
@@ -740,6 +768,103 @@ function validateKnowledgeEnvelope(appPath: string, manifest: Manifest): void {
 }
 // CIL[END stable_id="~/.framework/cli/commands/validate-app.ts:validateknowledgeenvelope:function"]
 
+// CIL[BEGIN stable_id="~/.framework/cli/commands/validate-app.ts:validateagentdirectory:function" type="function" identity="validateAgentDirectory" parent="~/.framework/cli/commands/validate-app.ts"]
+// CIL[DOC-AUDIENCE audience="CLI engineers and framework maintainers"]
+// CIL[DOC-MACRO purpose="Validate the app's staged agent/ directory (skills and instructions)"]
+// CIL[DOC-RESPONSIBILITY responsibility="Enforce skill prefix naming and SKILL.md name/dir equality, markdown-only instructions, and warn when staged assets drift from their live copies"]
+// CIL[DOC-CONTEXT module="validate-app" layer="cli" related_files=".framework/cli/commands/install-app.ts"]
+// CIL[DOC-CONTRACT inputs="appPath: string, manifest: Manifest" outputs="void" errors="ValidationError on missing skill_prefix, prefix mismatch, missing SKILL.md, or non-markdown instructions" side_effects="logs warnings to stdout on staged-vs-live drift"]
+// CIL[DOC-MICRO logic_summary="agent/skills requires manifest.agent.skill_prefix; every staged dir must start <prefix>_ and its SKILL.md name must equal the dir name; agent/instructions may only contain .md; sha1 snapshots of staged trees are compared to live custom/.devin/skills and src/instructions" notable_decisions="['drift_is_a_warning_not_an_error','skill_prefix_fail_closed']"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+function validateAgentDirectory(appPath: string, manifest: Manifest): void {
+  const agentPath = join(appPath, 'agent')
+  if (!existsSync(agentPath)) return
+
+  const skillsPath = join(agentPath, 'skills')
+  const instructionsPath = join(agentPath, 'instructions')
+
+  if (existsSync(skillsPath)) {
+    const prefix = manifest.agent?.skill_prefix
+    if (typeof prefix !== 'string' || !/^[a-z][a-z0-9]{0,7}$/.test(prefix)) {
+      throw new ValidationError(
+        `❌ agent/skills/ requires manifest.json agent.skill_prefix matching /^[a-z][a-z0-9]{0,7}$/`
+      )
+    }
+    for (const dir of readdirSync(skillsPath, { withFileTypes: true })) {
+      if (!dir.isDirectory()) continue
+      if (!dir.name.startsWith(`${prefix}_`)) {
+        throw new ValidationError(
+          `❌ agent/skills/${dir.name} must start with the declared prefix "${prefix}_"`
+        )
+      }
+      const skillFile = join(skillsPath, dir.name, 'SKILL.md')
+      if (!existsSync(skillFile)) {
+        throw new ValidationError(`❌ agent/skills/${dir.name}/ is missing SKILL.md`)
+      }
+      const nameMatch = /^name:\s*(.+)$/m.exec(readFileSync(skillFile, 'utf8'))
+      if (!nameMatch || nameMatch[1].trim() !== dir.name) {
+        throw new ValidationError(
+          `❌ agent/skills/${dir.name}/SKILL.md name must equal its directory name "${dir.name}"`
+        )
+      }
+    }
+  }
+
+  if (existsSync(instructionsPath)) {
+    const checkMarkdownOnly = (dirPath: string): void => {
+      for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
+        const full = join(dirPath, entry.name)
+        if (entry.isDirectory()) checkMarkdownOnly(full)
+        else if (!entry.name.endsWith('.md')) {
+          throw new ValidationError(
+            `❌ agent/instructions may only contain .md files — found ${entry.name}`
+          )
+        }
+      }
+    }
+    checkMarkdownOnly(instructionsPath)
+  }
+
+  // Staged copies should match their live counterparts — drift means one
+  // side was edited without re-staging (or the live install is stale).
+  const snapshot = (root: string): Map<string, string> => {
+    const out = new Map<string, string>()
+    const walk = (dir: string): void => {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name)
+        if (entry.isDirectory()) walk(full)
+        else out.set(full.slice(root.length + 1), createHash('sha1').update(readFileSync(full)).digest('hex'))
+      }
+    }
+    if (existsSync(root)) walk(root)
+    return out
+  }
+  const sameTree = (a: Map<string, string>, b: Map<string, string>): boolean =>
+    a.size === b.size && [...a].every(([k, v]) => b.get(k) === v)
+
+  if (existsSync(skillsPath)) {
+    const liveSkillsRoot = join(appPath, '..', '..', '.devin', 'skills')
+    for (const dir of readdirSync(skillsPath, { withFileTypes: true })) {
+      if (!dir.isDirectory()) continue
+      if (!sameTree(snapshot(join(skillsPath, dir.name)), snapshot(join(liveSkillsRoot, dir.name)))) {
+        console.warn(`⚠️  agent/skills/${dir.name} differs from live custom/.devin/skills/${dir.name} — re-stage or reinstall`)
+      }
+    }
+  }
+
+  if (existsSync(instructionsPath)) {
+    if (!sameTree(snapshot(instructionsPath), snapshot(join(appPath, 'src', 'instructions')))) {
+      console.warn(`⚠️  agent/instructions differs from src/instructions — re-stage before packaging`)
+    }
+  }
+
+  if (existsSync(skillsPath) || existsSync(instructionsPath)) {
+    console.log(`✅ agent/ staged assets valid`)
+  }
+}
+// CIL[END stable_id="~/.framework/cli/commands/validate-app.ts:validateagentdirectory:function"]
+
 // CIL[BEGIN stable_id="~/.framework/cli/commands/validate-app.ts:validateAppStructure:function" type="function" identity="validateAppStructure" parent="~/.framework/cli/commands/validate-app.ts"]
 // CIL[DOC-AUDIENCE audience="CLI engineers and framework maintainers"]
 // CIL[DOC-MACRO purpose="Run the full app structure validation pipeline"]
@@ -755,6 +880,7 @@ export function validateAppStructure(appPath: string): void {
   validateRequiredFiles(appPath, manifest)
   validateAllowedDirectories(appPath)
   validateDevinDirectory(appPath)
+  validateAgentDirectory(appPath, manifest)
   validateRoutes(appPath, manifest)
   validateManifestComponents(appPath, manifest)
   validateSeedBlock(appPath, manifest)

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

@@ -0,0 +1,147 @@
+// validate-schema — standalone design_schema validator.
+//
+// Ported from .framework/mcp/tools/architect.ts (the retired Spine MCP
+// architect tools) so `spine-schema` and CI have a runnable validator without
+// the MCP server. `validate-app` covers app packages (manifest/package.json/
+// structure) — this command covers a single design_schema JSON file.
+
+import type { Command } from 'commander'
+import { readFileSync, existsSync } from 'fs'
+import { resolve } from 'path'
+
+const DATA_TYPES = new Set([
+  'text', 'textarea', 'rich_text', 'email', 'phone', 'url', 'number', 'currency', 'range',
+  'date', 'datetime', 'boolean', 'checkbox', 'select', 'multiselect', 'radio', 'color',
+  'file', 'image', 'json', 'reference', 'address',
+])
+
+const DISPLAY_TYPES = new Set([
+  'text', 'input', 'textarea', 'rich_text', 'select', 'multiselect', 'radio', 'checkbox',
+  'switch', 'date_picker', 'datetime_picker', 'color_picker', 'file_upload', 'image_upload',
+  'range_slider', 'badge', 'timestamp', 'currency', 'number',
+])
+
+/**
+ * Validate a design_schema object. `checkViews` additionally requires
+ * views.default_list / views.default_detail and scans every declared
+ * display_type — the generic runtime UI breaks without them.
+ */
+export function validateDesignSchema(
+  schema: any,
+  opts: { checkViews?: boolean } = {},
+): { ok: boolean; errors: string[] } {
+  const checkViews = opts.checkViews ?? true
+  const errors: string[] = []
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+    errors.push('design_schema must be an object')
+    return { ok: false, errors }
+  }
+
+  const scope = schema.scope ?? 'account'
+  if (scope !== 'account' && scope !== 'platform') {
+    errors.push('scope must be "account" or "platform"')
+  }
+
+  if (!schema.fields || typeof schema.fields !== 'object' || Object.keys(schema.fields).length === 0) {
+    errors.push('fields is required and must contain at least one field definition')
+  }
+
+  for (const [key, field] of Object.entries(schema.fields || {})) {
+    if (!field || typeof field !== 'object') {
+      errors.push(`fields.${key} must be an object`)
+      continue
+    }
+    const f = field as any
+    if (!f.data_type) errors.push(`fields.${key} is missing data_type`)
+    else if (!DATA_TYPES.has(f.data_type)) errors.push(`fields.${key} has unknown data_type: ${f.data_type}`)
+    if (!f.label) errors.push(`fields.${key} is missing label`)
+    if (f.required === undefined) errors.push(`fields.${key} is missing required`)
+    if (['select', 'multiselect', 'radio'].includes(f.data_type) && (!f.options || !Array.isArray(f.options) || f.options.length === 0)) {
+      errors.push(`fields.${key} (${f.data_type}) requires options`)
+    }
+  }
+
+  if (!schema.record_permissions || typeof schema.record_permissions !== 'object') {
+    errors.push('record_permissions is required')
+  } else if (!Object.keys(schema.record_permissions).includes('system-admin') && !Object.keys(schema.record_permissions).includes('system_admin')) {
+    errors.push('record_permissions must grant at least system-admin or system_admin')
+  }
+
+  if (schema.views) {
+    if (schema.views.default_list) {
+      const list = schema.views.default_list
+      if (list.type !== 'list') errors.push('views.default_list.type must be "list"')
+      if (!list.fields || typeof list.fields !== 'object') errors.push('views.default_list.fields is required')
+      if (!list.default_sort) errors.push('views.default_list.default_sort is required')
+    }
+    if (schema.views.default_detail) {
+      const detail = schema.views.default_detail
+      if (detail.type !== 'detail') errors.push('views.default_detail.type must be "detail"')
+    }
+  }
+
+  if (checkViews && !schema.views) {
+    errors.push('views is required when check_views is true')
+  }
+  if (schema.views) {
+    if (checkViews && !schema.views.default_list) errors.push('views.default_list is required')
+    if (checkViews && !schema.views.default_detail) errors.push('views.default_detail is required')
+    for (const [viewName, view] of Object.entries(schema.views || {})) {
+      const v = view as any
+      if (!v || typeof v !== 'object') continue
+      for (const [fieldName, field] of Object.entries(v.fields || {})) {
+        const f = field as any
+        if (f && f.display_type && !DISPLAY_TYPES.has(f.display_type)) {
+          errors.push(`views.${viewName}.fields.${fieldName} has unknown display_type: ${f.display_type}`)
+        }
+      }
+      if (v.sections) {
+        for (const section of v.sections) {
+          for (const [fieldName, field] of Object.entries(section.fields || {})) {
+            const f = field as any
+            if (f && f.display_type && !DISPLAY_TYPES.has(f.display_type)) {
+              errors.push(`views.${viewName}.sections.*.fields.${fieldName} has unknown display_type: ${f.display_type}`)
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors }
+}
+
+export function registerValidateSchemaCommands(program: Command) {
+  program
+    .command('validate-schema')
+    .description('Validate a design_schema JSON file against the Spine design-schema rules')
+    .argument('<file>', 'Path to a design_schema JSON file')
+    .option('--no-views', 'Skip the default_list/default_detail view requirements (custom apps)')
+    .option('--json', 'Output the result as JSON')
+    .action(async (file: string, opts: { views: boolean; json: boolean }) => {
+      const abs = resolve(file)
+      if (!existsSync(abs)) {
+        console.error(`❌ file not found: ${file}`)
+        process.exit(1)
+      }
+      let schema: any
+      try {
+        schema = JSON.parse(readFileSync(abs, 'utf8'))
+      } catch (err: any) {
+        console.error(`❌ ${file} is not valid JSON: ${err.message}`)
+        process.exit(1)
+      }
+
+      const result = validateDesignSchema(schema, { checkViews: opts.views })
+
+      if (opts.json) {
+        console.log(JSON.stringify({ ok: result.ok, error_count: result.errors.length, errors: result.errors }, null, 2))
+      } else if (result.ok) {
+        console.log(`✅ ${file}: design_schema is valid`)
+      } else {
+        console.error(`❌ ${file}: ${result.errors.length} design_schema error(s)`)
+        for (const e of result.errors) console.error(`   - ${e}`)
+      }
+      if (!result.ok) process.exit(1)
+    })
+}