Normalize metadata types to singular forms

hotlong · hotlong · commit 6409037ce485 · 2026-04-13T11:41:07.000+08:00
Unify metadata type naming to singular forms across the codebase. Add PLURAL_TO_SINGULAR / SINGULAR_TO_PLURAL maps and helper functions (pluralToSingular, singularToPlural) in spec shared, and use them in ObjectQL engine, protocol, runtime HTTP dispatcher and UI hooks to normalize incoming plural/singular type names. Update SchemaRegistry to register/list apps as 'app' (and related callers), adjust studio sidebar and discovery hooks to use singular type keys and fix system-object filtering/expansion logic, and update related tests. Also add .agents to .gitignore.
diff --git a/apps/studio/src/components/DeveloperOverview.tsx b/apps/studio/src/components/DeveloperOverview.tsx
@@ -77,7 +77,7 @@ export function DeveloperOverview({ packages, selectedPackage, onNavigate }: Dev
 
   useEffect(() => { loadStats(); }, [loadStats]);
 
-  const objectCount = stats.metadata.counts['object'] || stats.metadata.counts['objects'] || 0;
+  const objectCount = stats.metadata.counts['object'] || 0;
   const totalMetaItems = Object.values(stats.metadata.counts).reduce((a, b) => a + b, 0);
 
   return (
diff --git a/apps/studio/src/components/app-sidebar.tsx b/apps/studio/src/components/app-sidebar.tsx
@@ -118,16 +118,16 @@ interface ProtocolGroup {
 }
 
 const PROTOCOL_GROUPS: ProtocolGroup[] = [
-  { key: 'data',       label: 'Data',       icon: Database,  types: ['object', 'objects', 'hooks', 'mappings', 'analyticsCubes', 'data'] },
-  { key: 'ui',         label: 'UI',         icon: AppWindow,  types: ['app', 'apps', 'actions', 'views', 'pages', 'dashboards', 'reports', 'themes'] },
-  { key: 'automation', label: 'Automation', icon: Workflow,   types: ['flows', 'workflows', 'approvals', 'webhooks'] },
-  { key: 'security',   label: 'Security',   icon: Shield,     types: ['roles', 'permissions', 'profiles', 'sharingRules', 'policies'] },
-  { key: 'ai',         label: 'AI',         icon: Bot,        types: ['agent', 'agents', 'tool', 'tools', 'ragPipeline', 'ragPipelines'] },
-  { key: 'api',        label: 'API',        icon: Globe,      types: ['apis', 'connectors'] },
+  { key: 'data',       label: 'Data',       icon: Database,  types: ['object', 'hook', 'mapping', 'analyticsCube', 'data'] },
+  { key: 'ui',         label: 'UI',         icon: AppWindow,  types: ['app', 'action', 'view', 'page', 'dashboard', 'report', 'theme'] },
+  { key: 'automation', label: 'Automation', icon: Workflow,   types: ['flow', 'workflow', 'approval', 'webhook'] },
+  { key: 'security',   label: 'Security',   icon: Shield,     types: ['role', 'permission', 'profile', 'sharingRule', 'policy'] },
+  { key: 'ai',         label: 'AI',         icon: Bot,        types: ['agent', 'tool', 'ragPipeline'] },
+  { key: 'api',        label: 'API',        icon: Globe,      types: ['api', 'connector'] },
 ];
 
 /** Types that are internal / should be hidden from the sidebar */
-const HIDDEN_TYPES = new Set(['plugin', 'plugins', 'kind']);
+const HIDDEN_TYPES = new Set(['plugin', 'kind']);
 
 /** System namespace used for FQN-based names (e.g., sys__user) */
 const SYSTEM_NAMESPACE = 'sys';
@@ -186,7 +186,7 @@ export function AppSidebar({
   const [metaItems, setMetaItems] = useState<Record<string, any[]>>({});
 
   // Track which metadata *types* are expanded (show individual items)
-  const [expandedTypes, setExpandedTypes] = useState<Set<string>>(new Set(['object', 'objects']));
+  const [expandedTypes, setExpandedTypes] = useState<Set<string>>(new Set(['object']));
 
   // Toggle to show/hide system objects in the Data protocol group
   const [showSystemInData, setShowSystemInData] = useState(true);
@@ -277,25 +277,18 @@ export function AppSidebar({
     label.toLowerCase().includes(searchQuery.toLowerCase()) ||
     name.toLowerCase().includes(searchQuery.toLowerCase());
 
-  // Extract system objects from loaded metadata (object/objects types)
+  // Extract system objects from loaded metadata
   const systemObjects = useMemo(() => {
-    const objectTypes = ['object', 'objects'];
-    const sysItems: any[] = [];
-    for (const type of objectTypes) {
-      const items = metaItems[type] || [];
-      sysItems.push(...items.filter(isSystemObject));
-    }
-    return sysItems;
+    const items = metaItems['object'] || [];
+    return items.filter(isSystemObject);
   }, [metaItems]);
 
   // Filter system objects out of the Data protocol group when toggled off
   const filteredMetaItems = useMemo(() => {
     if (showSystemInData) return metaItems;
     const result = { ...metaItems };
-    for (const type of ['object', 'objects']) {
-      if (result[type]) {
-        result[type] = result[type].filter((item: any) => !isSystemObject(item));
-      }
+    if (result['object']) {
+      result['object'] = result['object'].filter((item: any) => !isSystemObject(item));
     }
     return result;
   }, [metaItems, showSystemInData]);
@@ -433,7 +426,7 @@ export function AppSidebar({
                     const items = filteredMetaItems[type] || [];
                     const TypeIcon = getTypeIcon(type);
                     const typeLabel = getTypeLabel(type);
-                    const isObjectType = type === 'object' || type === 'objects';
+                    const isObjectType = type === 'object';
                     const isExpanded = expandedTypes.has(type) || !!searchQuery;
 
                     const filtered = items.filter((item: any) =>
diff --git a/apps/studio/src/hooks/use-api-discovery.ts b/apps/studio/src/hooks/use-api-discovery.ts
@@ -264,7 +264,7 @@ export function useApiDiscovery() {
       // 4. Fetch object names from metadata
       let objectNames: string[] = [];
       try {
-        const objectType = metaTypes.includes('objects') ? 'objects' : metaTypes.includes('object') ? 'object' : null;
+        const objectType = metaTypes.includes('object') ? 'object' : null;
         if (objectType) {
           const objectResult = await client.meta.getItems(objectType);
           let items: any[] = [];
diff --git a/packages/objectql/src/engine.ts b/packages/objectql/src/engine.ts
@@ -13,6 +13,7 @@ import { ExecutionContext, ExecutionContextSchema } from '@objectstack/spec/kern
 import { DriverInterface, IDataEngine, Logger, createLogger } from '@objectstack/core';
 import { CoreServiceName } from '@objectstack/spec/system';
 import { IRealtimeService, RealtimeEventPayload } from '@objectstack/spec/contracts';
+import { pluralToSingular } from '@objectstack/spec/shared';
 import { SchemaRegistry } from './registry.js';
 
 export type HookHandler = (context: HookContext) => Promise<void> | void;
@@ -395,7 +396,7 @@ export class ObjectQL implements IDataEngine {
               for (const item of items) {
                   const itemName = item.name || item.id;
                   if (itemName) {
-                      SchemaRegistry.registerItem(key, item, 'name' as any, id);
+                      SchemaRegistry.registerItem(pluralToSingular(key), item, 'name' as any, id);
                   }
               }
           }
@@ -501,7 +502,7 @@ export class ObjectQL implements IDataEngine {
               for (const item of items) {
                   const itemName = item.name || item.id;
                   if (itemName) {
-                      SchemaRegistry.registerItem(key, item, 'name' as any, ownerId);
+                      SchemaRegistry.registerItem(pluralToSingular(key), item, 'name' as any, ownerId);
                   }
               }
           }
diff --git a/packages/objectql/src/protocol.ts b/packages/objectql/src/protocol.ts
@@ -2,15 +2,16 @@
 
 import { ObjectStackProtocol } from '@objectstack/spec/api';
 import { IDataEngine } from '@objectstack/core';
-import type { 
-    BatchUpdateRequest, 
-    BatchUpdateResponse, 
+import type {
+    BatchUpdateRequest,
+    BatchUpdateResponse,
     UpdateManyDataRequest,
     DeleteManyDataRequest
 } from '@objectstack/spec/api';
 import type { MetadataCacheRequest, MetadataCacheResponse, ServiceInfo, ApiRoutes, WellKnownCapabilities } from '@objectstack/spec/api';
 import type { IFeedService } from '@objectstack/spec/contracts';
 import { parseFilterAST, isFilterAST } from '@objectstack/spec/data';
+import { PLURAL_TO_SINGULAR, SINGULAR_TO_PLURAL } from '@objectstack/spec/shared';
 
 // We import SchemaRegistry directly since this class lives in the same package
 import { SchemaRegistry } from './registry.js';
@@ -201,10 +202,10 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     async getMetaItems(request: { type: string; packageId?: string }) {
         const { packageId } = request;
         let items = SchemaRegistry.listItems(request.type, packageId);
-        // Normalize singular/plural: REST uses singular ('app') but registry may store as plural ('apps')
+        // Normalize singular/plural using explicit mapping
         if (items.length === 0) {
-            const alt = request.type.endsWith('s') ? request.type.slice(0, -1) : request.type + 's';
-            items = SchemaRegistry.listItems(alt, packageId);
+            const alt = PLURAL_TO_SINGULAR[request.type] ?? SINGULAR_TO_PLURAL[request.type];
+            if (alt) items = SchemaRegistry.listItems(alt, packageId);
         }
 
         // Fallback to database if registry is empty for this type
@@ -225,8 +226,9 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                         return data;
                     });
                 } else {
-                    // Try alternate type name in DB
-                    const alt = request.type.endsWith('s') ? request.type.slice(0, -1) : request.type + 's';
+                    // Try alternate type name in DB using explicit mapping
+                    const alt = PLURAL_TO_SINGULAR[request.type] ?? SINGULAR_TO_PLURAL[request.type];
+                    if (alt) {
                     const altRecords = await this.engine.find('sys_metadata', {
                         where: { type: alt, state: 'active' }
                     });
@@ -239,6 +241,7 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                             return data;
                         });
                     }
+                    }
                 }
             } catch {
                 // DB not available, return registry results (empty)
@@ -281,10 +284,10 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
 
     async getMetaItem(request: { type: string, name: string, packageId?: string }) {
         let item = SchemaRegistry.getItem(request.type, request.name);
-        // Normalize singular/plural
+        // Normalize singular/plural using explicit mapping
         if (item === undefined) {
-            const alt = request.type.endsWith('s') ? request.type.slice(0, -1) : request.type + 's';
-            item = SchemaRegistry.getItem(alt, request.name);
+            const alt = PLURAL_TO_SINGULAR[request.type] ?? SINGULAR_TO_PLURAL[request.type];
+            if (alt) item = SchemaRegistry.getItem(alt, request.name);
         }
 
         // Fallback to database if not in registry
@@ -300,8 +303,9 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                     // Hydrate back into registry for next time
                     SchemaRegistry.registerItem(request.type, item, 'name' as any);
                 } else {
-                    // Try alternate type name
-                    const alt = request.type.endsWith('s') ? request.type.slice(0, -1) : request.type + 's';
+                    // Try alternate type name using explicit mapping
+                    const alt = PLURAL_TO_SINGULAR[request.type] ?? SINGULAR_TO_PLURAL[request.type];
+                    if (alt) {
                     const altRecord = await this.engine.findOne('sys_metadata', {
                         where: { type: alt, name: request.name, state: 'active' }
                     });
@@ -312,6 +316,7 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                         // Hydrate back into registry for next time
                         SchemaRegistry.registerItem(request.type, item, 'name' as any);
                     }
+                    }
                 }
             } catch {
                 // DB not available, return undefined
@@ -617,7 +622,27 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
 
     async getMetaItemCached(request: { type: string, name: string, cacheRequest?: MetadataCacheRequest }): Promise<MetadataCacheResponse> {
         try {
-            const item = SchemaRegistry.getItem(request.type, request.name);
+            let item = SchemaRegistry.getItem(request.type, request.name);
+
+            // Normalize singular/plural using explicit mapping
+            if (!item) {
+                const alt = PLURAL_TO_SINGULAR[request.type] ?? SINGULAR_TO_PLURAL[request.type];
+                if (alt) item = SchemaRegistry.getItem(alt, request.name);
+            }
+
+            // Fallback to MetadataService (e.g. agents, tools registered in MetadataManager)
+            if (!item) {
+                try {
+                    const services = this.getServicesRegistry?.();
+                    const metadataService = services?.get('metadata');
+                    if (metadataService && typeof metadataService.get === 'function') {
+                        item = await metadataService.get(request.type, request.name);
+                    }
+                } catch {
+                    // MetadataService not available
+                }
+            }
+
             if (!item) {
                 throw new Error(`Metadata item ${request.type}/${request.name} not found`);
             }
@@ -1038,10 +1063,12 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                     const data = typeof record.metadata === 'string'
                         ? JSON.parse(record.metadata)
                         : record.metadata;
-                    if (record.type === 'object') {
+                    // Normalize DB type to singular (DB may store legacy plural forms)
+                    const normalizedType = PLURAL_TO_SINGULAR[record.type] ?? record.type;
+                    if (normalizedType === 'object') {
                         SchemaRegistry.registerObject(data as any, record.packageId || 'sys_metadata');
                     } else {
-                        SchemaRegistry.registerItem(record.type, data, 'name' as any);
+                        SchemaRegistry.registerItem(normalizedType, data, 'name' as any);
                     }
                     loaded++;
                 } catch (e) {
diff --git a/packages/objectql/src/registry.test.ts b/packages/objectql/src/registry.test.ts
@@ -353,17 +353,17 @@ describe('SchemaRegistry', () => {
     describe('Generic Metadata', () => {
         it('should register and retrieve generic items', () => {
             const item = { name: 'test_action', type: 'custom' };
-            SchemaRegistry.registerItem('actions', item, 'name', 'com.pkg');
-            
-            const retrieved = SchemaRegistry.getItem('actions', 'test_action');
+            SchemaRegistry.registerItem('action', item, 'name', 'com.pkg');
+
+            const retrieved = SchemaRegistry.getItem('action', 'test_action');
             expect(retrieved).toEqual(item);
         });
 
         it('should list items by type with package filter', () => {
-            SchemaRegistry.registerItem('actions', { name: 'a1' }, 'name', 'com.pkg1');
-            SchemaRegistry.registerItem('actions', { name: 'a2' }, 'name', 'com.pkg2');
-            
-            const filtered = SchemaRegistry.listItems('actions', 'com.pkg1');
+            SchemaRegistry.registerItem('action', { name: 'a1' }, 'name', 'com.pkg1');
+            SchemaRegistry.registerItem('action', { name: 'a2' }, 'name', 'com.pkg2');
+
+            const filtered = SchemaRegistry.listItems('action', 'com.pkg1');
             expect(filtered).toHaveLength(1);
         });
     });
@@ -396,12 +396,12 @@ describe('SchemaRegistry', () => {
     describe('Reset', () => {
         it('should clear all state', () => {
             SchemaRegistry.registerObject({ name: 'obj', fields: {} } as any, 'com.pkg', 'pkg', 'own');
-            SchemaRegistry.registerItem('actions', { name: 'act' }, 'name');
-            
+            SchemaRegistry.registerItem('action', { name: 'act' }, 'name');
+
             SchemaRegistry.reset();
-            
+
             expect(SchemaRegistry.getAllObjects()).toHaveLength(0);
-            expect(SchemaRegistry.listItems('actions')).toHaveLength(0);
+            expect(SchemaRegistry.listItems('action')).toHaveLength(0);
         });
     });
 
diff --git a/packages/objectql/src/registry.ts b/packages/objectql/src/registry.ts
@@ -485,7 +485,7 @@ export class SchemaRegistry {
     if (type === 'object') {
       return ObjectSchema.parse(item);
     }
-    if (type === 'apps') {
+    if (type === 'app') {
       return AppSchema.parse(item);
     }
     if (type === 'package') {
@@ -664,15 +664,15 @@ export class SchemaRegistry {
   // ==========================================
 
   static registerApp(app: any, packageId?: string) {
-    this.registerItem('apps', app, 'name', packageId);
+    this.registerItem('app', app, 'name', packageId);
   }
 
   static getApp(name: string): any {
-    return this.getItem('apps', name);
+    return this.getItem('app', name);
   }
 
   static getAllApps(): any[] {
-    return this.listItems('apps');
+    return this.listItems('app');
   }
 
   // ==========================================
diff --git a/packages/runtime/src/http-dispatcher.ts b/packages/runtime/src/http-dispatcher.ts
@@ -2,6 +2,7 @@
 
 import { ObjectKernel, getEnv, resolveLocale } from '@objectstack/core';
 import { CoreServiceName } from '@objectstack/spec/system';
+import { pluralToSingular } from '@objectstack/spec/shared';
 
 /** Browser-safe UUID generator — prefers Web Crypto, falls back to RFC 4122 v4 */
 function randomUUID(): string {
@@ -489,9 +490,8 @@ export class HttpDispatcher {
                     return { handled: true, response: this.error('Not found', 404) };
                 }
 
-                // If type is singular (e.g. 'app'), use it directly
-                // If plural (e.g. 'apps'), slice it
-                const singularType = type.endsWith('s') ? type.slice(0, -1) : type;
+                // Normalize plural URL paths to singular registry type names
+                const singularType = pluralToSingular(type);
 
                 // Try Protocol Service First (Preferred)
                 const protocol = await this.resolveService('protocol');
diff --git a/packages/runtime/vitest.config.ts b/packages/runtime/vitest.config.ts
@@ -12,6 +12,7 @@ export default defineConfig({
       '@objectstack/spec/contracts': path.resolve(__dirname, '../spec/src/contracts/index.ts'),
       '@objectstack/spec/data': path.resolve(__dirname, '../spec/src/data/index.ts'),
       '@objectstack/spec/kernel': path.resolve(__dirname, '../spec/src/kernel/index.ts'),
+      '@objectstack/spec/shared': path.resolve(__dirname, '../spec/src/shared/index.ts'),
       '@objectstack/spec/system': path.resolve(__dirname, '../spec/src/system/index.ts'),
       '@objectstack/spec': path.resolve(__dirname, '../spec/src/index.ts'),
       '@objectstack/types': path.resolve(__dirname, '../types/src/index.ts'),
diff --git a/packages/spec/src/shared/metadata-collection.test.ts b/packages/spec/src/shared/metadata-collection.test.ts
diff --git a/packages/spec/src/shared/metadata-collection.zod.ts b/packages/spec/src/shared/metadata-collection.zod.ts

Original file line number	Diff line number	Diff line change
`@@ -13,6 +13,7 @@ import { ExecutionContext, ExecutionContextSchema } from '@objectstack/spec/kern`
`13`	`13`	`import { DriverInterface, IDataEngine, Logger, createLogger } from '@objectstack/core';`
`14`	`14`	`import { CoreServiceName } from '@objectstack/spec/system';`
`15`	`15`	`import { IRealtimeService, RealtimeEventPayload } from '@objectstack/spec/contracts';`
	`16`	`+import { pluralToSingular } from '@objectstack/spec/shared';`
`16`	`17`	`import { SchemaRegistry } from './registry.js';`
`17`	`18`
`18`	`19`	`export type HookHandler = (context: HookContext) => Promise<void> \| void;`
`@@ -395,7 +396,7 @@ export class ObjectQL implements IDataEngine {`
`395`	`396`	`for (const item of items) {`
`396`	`397`	`const itemName = item.name \|\| item.id;`
`397`	`398`	`if (itemName) {`
`398`		`- SchemaRegistry.registerItem(key, item, 'name' as any, id);`
	`399`	`+ SchemaRegistry.registerItem(pluralToSingular(key), item, 'name' as any, id);`
`399`	`400`	`}`
`400`	`401`	`}`
`401`	`402`	`}`
`@@ -501,7 +502,7 @@ export class ObjectQL implements IDataEngine {`
`501`	`502`	`for (const item of items) {`
`502`	`503`	`const itemName = item.name \|\| item.id;`
`503`	`504`	`if (itemName) {`
`504`		`- SchemaRegistry.registerItem(key, item, 'name' as any, ownerId);`
	`505`	`+ SchemaRegistry.registerItem(pluralToSingular(key), item, 'name' as any, ownerId);`
`505`	`506`	`}`
`506`	`507`	`}`
`507`	`508`	`}`
Original file line number	Diff line number	Diff line change
`@@ -485,7 +485,7 @@ export class SchemaRegistry {`
`485`	`485`	`if (type === 'object') {`
`486`	`486`	`return ObjectSchema.parse(item);`
`487`	`487`	`}`
`488`		`- if (type === 'apps') {`
	`488`	`+ if (type === 'app') {`
`489`	`489`	`return AppSchema.parse(item);`
`490`	`490`	`}`
`491`	`491`	`if (type === 'package') {`
`@@ -664,15 +664,15 @@ export class SchemaRegistry {`
`664`	`664`	`// ==========================================`
`665`	`665`
`666`	`666`	`static registerApp(app: any, packageId?: string) {`
`667`		`- this.registerItem('apps', app, 'name', packageId);`
	`667`	`+ this.registerItem('app', app, 'name', packageId);`
`668`	`668`	`}`
`669`	`669`
`670`	`670`	`static getApp(name: string): any {`
`671`		`- return this.getItem('apps', name);`
	`671`	`+ return this.getItem('app', name);`
`672`	`672`	`}`
`673`	`673`
`674`	`674`	`static getAllApps(): any[] {`
`675`		`- return this.listItems('apps');`
	`675`	`+ return this.listItems('app');`
`676`	`676`	`}`
`677`	`677`
`678`	`678`	`// ==========================================`