Merge branch 'main' into copilot/update-fumadocs-to-latest

Author: hotlong

apps/docs/package.json

@@ -6,7 +6,7 @@
   "license": "Apache-2.0",
   "scripts": {
     "dev": "next dev",
-    "build": "pnpm --filter @objectstack/spec gen:docs && next build",
+    "build": "pnpm --filter @objectstack/spec gen:schema && pnpm --filter @objectstack/spec gen:docs && next build",
     "site:start": "next start",
     "site:lint": "next lint",
     "types:check": "fumadocs-mdx && next typegen && tsc --noEmit",

packages/cli/src/commands/serve.ts

@@ -207,6 +207,17 @@ export const serveCommand = new Command('serve')
               }
             }
 
+            // Wrap raw config objects (no init/start) into AppPlugin
+            // This handles plugins defined as plain { name, objects, ... } bundles
+            if (pluginToLoad && typeof pluginToLoad === 'object' && !pluginToLoad.init) {
+              try {
+                const { AppPlugin } = await import('@objectstack/runtime');
+                pluginToLoad = new AppPlugin(pluginToLoad);
+              } catch (e: any) {
+                // Fall through to kernel.use which will report the error
+              }
+            }
+
             await kernel.use(pluginToLoad);
             const pluginName = plugin.name || plugin.constructor?.name || 'unnamed';
             trackPlugin(pluginName);

packages/objectql/src/engine.ts

@@ -268,6 +268,92 @@ export class ObjectQL implements IDataEngine {
             this.logger.debug('Registered Kind', { kind: kind.name || kind.type, from: id });
           }
        }
+
+      // 7. Recursively register nested plugins
+      if (Array.isArray(manifest.plugins) && manifest.plugins.length > 0) {
+          this.logger.debug('Processing nested plugins', { id, count: manifest.plugins.length });
+          for (const plugin of manifest.plugins) {
+              if (plugin && typeof plugin === 'object') {
+                  const pluginName = plugin.name || plugin.id || 'unnamed-plugin';
+                  this.logger.debug('Registering nested plugin', { pluginName, parentId: id });
+                  this.registerPlugin(plugin, id, namespace);
+              }
+          }
+      }
+  }
+
+  /**
+   * Register a nested plugin's metadata (objects, actions, views, etc.)
+   *
+   * Unlike registerApp(), this does NOT call SchemaRegistry.installPackage()
+   * because plugins are not formal manifests — they are lightweight config
+   * bundles with objects, actions, triggers, and navigation.
+   *
+   * @param plugin - The plugin config object
+   * @param parentId - The parent package ID (for ownership tracking)
+   * @param parentNamespace - The parent package's namespace (for FQN resolution)
+   */
+  private registerPlugin(plugin: any, parentId: string, parentNamespace?: string) {
+      const pluginName = plugin.name || plugin.id || 'unnamed';
+      const pluginNamespace = plugin.namespace || parentNamespace;
+
+      // Use parentId as the owning package for namespace consistency.
+      // The parent package already claimed the namespace — nested plugins
+      // contribute objects UNDER the parent's ownership.
+      const ownerId = parentId;
+
+      // Register objects (supports both Array and Map formats)
+      if (plugin.objects) {
+          try {
+              if (Array.isArray(plugin.objects)) {
+                  this.logger.debug('Registering plugin objects (Array)', { pluginName, count: plugin.objects.length });
+                  for (const objDef of plugin.objects) {
+                      const fqn = SchemaRegistry.registerObject(objDef, ownerId, pluginNamespace, 'own');
+                      this.logger.debug('Registered Object', { fqn, from: pluginName });
+                  }
+              } else {
+                  const entries = Object.entries(plugin.objects);
+                  this.logger.debug('Registering plugin objects (Map)', { pluginName, count: entries.length });
+                  for (const [name, objDef] of entries) {
+                      (objDef as any).name = name;
+                      const fqn = SchemaRegistry.registerObject(objDef as any, ownerId, pluginNamespace, 'own');
+                      this.logger.debug('Registered Object', { fqn, from: pluginName });
+                  }
+              }
+          } catch (err: any) {
+              this.logger.warn('Failed to register plugin objects', { pluginName, error: err.message });
+          }
+      }
+
+      // Register plugin as app if it has navigation (for sidebar display)
+      if (plugin.name && plugin.navigation) {
+          try {
+              SchemaRegistry.registerApp(plugin, ownerId);
+              this.logger.debug('Registered plugin-as-app', { app: plugin.name, from: pluginName });
+          } catch (err: any) {
+              this.logger.warn('Failed to register plugin as app', { pluginName, error: err.message });
+          }
+      }
+
+      // Register metadata arrays (actions, views, triggers, etc.)
+      const metadataArrayKeys = [
+          'actions', 'views', 'pages', 'dashboards', 'reports', 'themes',
+          'flows', 'workflows', 'approvals', 'webhooks',
+          'roles', 'permissions', 'profiles', 'sharingRules', 'policies',
+          'agents', 'ragPipelines', 'apis',
+          'hooks', 'mappings', 'analyticsCubes', 'connectors',
+      ];
+      for (const key of metadataArrayKeys) {
+          const items = (plugin as any)[key];
+          if (Array.isArray(items) && items.length > 0) {
+              for (const item of items) {
+                  const itemName = item.name || item.id;
+                  if (itemName) {
+                      SchemaRegistry.registerItem(key, item, 'name' as any, ownerId);
+                  }
+              }
+          }
+      }
   }
 
   /**

packages/spec/package.json

@@ -112,8 +112,7 @@
     "@vitest/coverage-v8": "^4.0.18",
     "tsx": "^4.21.0",
     "typescript": "^5.3.0",
-    "vitest": "^4.0.18",
-    "zod-to-json-schema": "^3.25.1"
+    "vitest": "^4.0.18"
   },
   "dependencies": {
     "zod": "^4.3.6"

packages/spec/scripts/build-docs.ts

@@ -329,7 +329,11 @@ Object.entries(CATEGORIES).forEach(([category, title]) => {
   // BUT 'index' must be in 'meta.json' pages? No, index is implicit usually.
 
   // However, Fumadocs often treats folder/index.mdx as the page for the folder.
-  fs.writeFileSync(path.join(DOCS_ROOT, category, 'index.mdx'), mdx);
+  // Ensure directory exists before writing
+  const categoryDir = path.join(DOCS_ROOT, category);
+  if (!fs.existsSync(categoryDir)) fs.mkdirSync(categoryDir, { recursive: true });
+  
+  fs.writeFileSync(path.join(categoryDir, 'index.mdx'), mdx);
   console.log(`✓ Generated ${category}/index.mdx`);
 });
 

packages/spec/scripts/build-schemas.ts

@@ -3,7 +3,6 @@
 import fs from 'fs';
 import path from 'path';
 import { z } from 'zod';
-import { zodToJsonSchema } from 'zod-to-json-schema';
 import * as Protocol from '../src/index';
 
 const OUT_DIR = path.resolve(__dirname, '../json-schema');
@@ -92,8 +91,20 @@ ensureDir(OUT_DIR);
 console.log(`Generating JSON Schemas to ${OUT_DIR}...`);
 
 let count = 0;
+let skippedCount = 0;
 let errorCount = 0;
 
+// Error messages for schema types that inherently cannot be represented in JSON Schema.
+// These are expected warnings, not build-breaking errors.
+const KNOWN_UNSUPPORTED_PATTERNS = [
+  'cannot be represented in JSON Schema',
+];
+
+function isKnownUnsupported(error: unknown): boolean {
+  const msg = error instanceof Error ? error.message : String(error);
+  return KNOWN_UNSUPPORTED_PATTERNS.some((p) => msg.includes(p));
+}
+
 // Protocol now exports namespaces (Data, UI, System, AI, API)
 // We need to iterate through each namespace
 for (const [namespaceName, namespaceExports] of Object.entries(Protocol)) {
@@ -118,31 +129,42 @@ for (const [namespaceName, namespaceExports] of Object.entries(Protocol)) {
         const schemaName = key.endsWith('Schema') ? key.replace('Schema', '') : key;
 
         try {
-          // Convert to JSON Schema
-          const jsonSchema = zodToJsonSchema(value, {
-            name: schemaName,
-            $refStrategy: "none" // We want self-contained schemas for now
+          // Convert to JSON Schema using Zod v4's built-in toJSONSchema()
+          const jsonSchema = z.toJSONSchema(value, {
+            target: 'draft-2020-12',
           });
 
           const fileName = `${schemaName}.json`;
           const filePath = path.join(categoryDir, fileName);
 
           writeFileWithRetry(filePath, JSON.stringify(jsonSchema, null, 2));
-          console.log(`✓ ${namespaceName.toLowerCase()}/${fileName}`);
+          console.log(`  ✓ ${namespaceName.toLowerCase()}/${fileName}`);
           count++;
         } catch (error) {
-          console.error(`Failed to generate schema for ${namespaceName}.${key}:`, error);
-          errorCount++;
+          if (isKnownUnsupported(error)) {
+            // Functions, transforms, Date types etc. have no JSON Schema representation — skip gracefully
+            const msg = error instanceof Error ? error.message : String(error);
+            console.warn(`  ⊘ ${namespaceName}.${key}: ${msg} (skipped)`);
+            skippedCount++;
+          } else {
+            console.error(`  ✗ Failed to generate schema for ${namespaceName}.${key}:`, error);
+            errorCount++;
+          }
         }
       }
     }
   }
 }
 
+console.log(`\n─── Summary ───`);
+console.log(`  Generated: ${count}`);
+if (skippedCount > 0) {
+  console.log(`  Skipped:   ${skippedCount} (unsupported types: function, transform, date)`);
+}
+
 if (errorCount > 0) {
-  console.error(`\n❌ Completed with ${errorCount} error(s). ${count} schemas generated successfully.`);
-  console.error(`\nNote: Partial schema generation occurred. Some schemas may be missing.`);
-  console.error(`This typically indicates a Zod schema definition error or file system issue.`);
+  console.error(`  Errors:    ${errorCount}`);
+  console.error(`\n❌ Build failed with ${errorCount} unexpected error(s).`);
   process.exit(1);
 }