Merge pull request #543 from objectstack-ai/copilot/update-development-plan

Author: hotlong

packages/spec/DEVELOPMENT_PLAN.md

@@ -13,14 +13,14 @@ Based on the full audit of 139 `.zod.ts` files (43,746 LOC, 1,089 schemas), the
 
 ### Key Metrics Baseline
 
-| Metric | Current | Phase 2 Target | Phase 4 Target |
+| Metric | Original | Current | Phase 4 Target |
 |---|---|---|---|
-| `z.any()` usages | 397 | < 100 | < 30 |
-| `z.unknown()` usages | 8 | > 200 | > 350 |
-| `z.infer` coverage | 93% (1,011/1,089) | 98% | 100% |
-| `.describe()` annotations | 5,026 | 5,300 | 5,600 |
-| Schema duplications | 13+ pairs | 3 | 0 |
-| Runtime logic violations | 2 files | 0 | 0 |
+| `z.any()` usages | 397 | 8 | 8 (filter operators only) |
+| `z.unknown()` usages | 8 | 340 | > 350 |
+| `z.infer` coverage | 93% (1,011/1,089) | ~98% | 100% |
+| `.describe()` annotations | 5,026 | 5,300+ | 5,600 |
+| Schema duplications | 13+ pairs | 1 | 0 |
+| Runtime logic violations | 2 files | 2 files | 0 |
 | Naming violations | 3 | 0 | 0 |
 
 ---
@@ -120,14 +120,14 @@ error: z.object({
 
 | # | Task | File(s) | Status |
 |---|---|---|---|
-| 1.1 | Fix z.any() in handler union | `data/hook.zod.ts` | ⬜ |
-| 1.2 | Fix ValidationRuleSchema type-safety | `data/validation.zod.ts` | ⬜ |
-| 1.3 | Fix invalid computed key syntax | `system/auth-config.zod.ts` | ⬜ |
-| 1.4 | Fix Mongo capabilities key names | `data/driver/mongo.zod.ts` | ⬜ |
-| 1.5 | Fix DatasourceConfig alias | `data/datasource.zod.ts` | ⬜ |
-| 1.6 | Replace z.instanceof(Error) | `kernel/plugin-lifecycle-events.zod.ts`, `kernel/startup-orchestrator.zod.ts` | ⬜ |
-| 1.7 | Fix `$exist` → `$exists` typo | `data/filter.zod.ts` | ⬜ |
-| 1.8 | Run full test suite, verify build | — | ⬜ |
+| 1.1 | Fix z.any() in handler union | `data/hook.zod.ts` | ✅ |
+| 1.2 | Fix ValidationRuleSchema type-safety | `data/validation.zod.ts` | ✅ |
+| 1.3 | Fix invalid computed key syntax | `system/auth-config.zod.ts` | ✅ |
+| 1.4 | Fix Mongo capabilities key names | `data/driver/mongo.zod.ts` | ✅ |
+| 1.5 | Fix DatasourceConfig alias | `data/datasource.zod.ts` | ✅ |
+| 1.6 | Replace z.instanceof(Error) | `kernel/plugin-lifecycle-events.zod.ts`, `kernel/startup-orchestrator.zod.ts` | ✅ |
+| 1.7 | Fix `$exist` → `$exists` typo | `data/filter.zod.ts` | ✅ |
+| 1.8 | Run full test suite, verify build | — | ✅ |
 
 ---
 
@@ -272,17 +272,17 @@ Replace `z.date()` with `z.string().datetime()` in serializable schemas:
 
 | # | Task | File(s) | Status |
 |---|---|---|---|
-| 2.1 | Create `shared/enums.zod.ts` + update consumers | 8+ files | ⬜ |
-| 2.2 | Create `shared/metadata-types.zod.ts` | 3 files | ⬜ |
-| 2.3 | Deduplicate security schemas | 4 files | ⬜ |
-| 2.4 | Rename `MetricType` in license.zod.ts | `hub/license.zod.ts` | ⬜ |
-| 2.5 | Unify SnakeCaseIdentifierSchema usage | 4 UI files | ⬜ |
-| 2.6 | Fix snake_case property keys | `system/metadata-persistence.zod.ts` | ⬜ |
-| 2.7 | Replace z.date() with z.string().datetime() | 6 files | ⬜ |
-| 2.8 | Unify isolation level enum | `data/driver.zod.ts` | ⬜ |
-| 2.9 | Rename system/service-registry.zod.ts | 1 file + index | ⬜ |
-| 2.10 | Deduplicate Presence schemas (realtime/websocket) | 2 files | ⬜ |
-| 2.11 | Run full test suite, update index.ts re-exports | — | ⬜ |
+| 2.1 | Create `shared/enums.zod.ts` + update consumers | 8+ files | ✅ |
+| 2.2 | Create `shared/metadata-types.zod.ts` | 3 files | ✅ |
+| 2.3 | Deduplicate security schemas | 4 files | ✅ (Kernel uses Kernel-prefixed variants) |
+| 2.4 | Rename `MetricType` in license.zod.ts | `hub/license.zod.ts` | ✅ |
+| 2.5 | Unify SnakeCaseIdentifierSchema usage | 4 UI files | ✅ |
+| 2.6 | Fix snake_case property keys | `system/metadata-persistence.zod.ts` | ✅ |
+| 2.7 | Replace z.date() with z.string().datetime() | 6 files | ✅ |
+| 2.8 | Unify isolation level enum | `data/driver.zod.ts` | ✅ |
+| 2.9 | Rename system/service-registry.zod.ts | 1 file + index | ✅ |
+| 2.10 | Deduplicate Presence schemas (realtime/websocket) | 2 files | ✅ |
+| 2.11 | Run full test suite, update index.ts re-exports | — | ✅ |
 
 ---
 
@@ -387,18 +387,20 @@ Already replaced by `locations` array. Remove the deprecated field.
 
 | # | Task | Scope | z.any() Reduction | Status |
 |---|---|---|---|---|
-| 3.1 | Bulk metadata/config z.any() → z.unknown() | ~88 files | -140 | ⬜ |
-| 3.2 | Tighten id fields | 2 files | -2 | ⬜ |
-| 3.3a | Harden kernel/plugin.zod.ts | 1 file | -20 | ⬜ |
-| 3.3b | Harden data/driver.zod.ts | 1 file | -10 | ⬜ |
-| 3.3c | Harden data/data-engine.zod.ts | 1 file | -8 | ⬜ |
-| 3.3d | Harden kernel/events.zod.ts | 1 file | -8 | ⬜ |
-| 3.3e | Harden kernel/manifest.zod.ts | 1 file | -7 | ⬜ |
-| 3.4 | Fix UI z.any() with proper imports | 4 files | -6 | ⬜ |
-| 3.5 | Remove deprecated action.location | 1 file | -1 | ⬜ |
-| 3.6 | Run full test suite | — | — | ⬜ |
-
-**Expected total reduction:** 397 → ~95 (`z.any()`)
+| 3.1 | Bulk metadata/config z.any() → z.unknown() | ~88 files | -140 | ✅ |
+| 3.2 | Tighten id fields | 2 files | -2 | ✅ |
+| 3.3a | Harden kernel/plugin.zod.ts | 1 file | -23 | ✅ |
+| 3.3b | Harden data/driver.zod.ts | 1 file | -10 | ✅ |
+| 3.3c | Harden data/data-engine.zod.ts | 1 file | -8 | ✅ |
+| 3.3d | Harden kernel/events.zod.ts | 1 file | -8 | ✅ |
+| 3.3e | Harden kernel/manifest.zod.ts | 1 file | -7 | ✅ |
+| 3.4 | Fix UI z.any() with proper imports | 4 files | -6 | ✅ |
+| 3.5 | Remove deprecated action.location | 1 file | -1 | ✅ |
+| 3.6 | Replace z.any() in api/protocol.zod.ts | 1 file | -28 | ✅ |
+| 3.7 | Replace z.any() in hook, core-services, widget | 3 files | -3 | ✅ |
+| 3.8 | Run full test suite | — | — | ✅ |
+
+**Actual total reduction:** 397 → 8 (`z.any()`) — remaining 8 are legitimate filter operators ($eq/$ne/$in/$nin)
 
 ---
 
@@ -513,7 +515,7 @@ formula: z.string().optional()
 
 | # | Task | Scope | Status |
 |---|---|---|---|
-| 4.1 | Add missing z.infer exports | 14 files | ⬜ |
+| 4.1 | Add missing z.infer exports | 14 files | ✅ (1 remaining: WidgetSource added) |
 | 4.2 | Add z.input<> exports for transform schemas | ~20 files | ⬜ |
 | 4.3 | Improve .describe() coverage | 9 files | ⬜ |
 | 4.4 | Move runtime logic to core/runtime | 3 files | ⬜ |

packages/spec/src/api/protocol.zod.ts

@@ -444,92 +444,92 @@ export {
  */
 export const ObjectStackProtocolSchema = z.object({
   // Discovery & Metadata
-  getDiscovery: z.any()
+  getDiscovery: z.function()
     .describe('Get API discovery information'),
 
-  getMetaTypes: z.any()
+  getMetaTypes: z.function()
     .describe('Get available metadata types'),
 
-  getMetaItems: z.any()
+  getMetaItems: z.function()
     .describe('Get all items of a metadata type'),
 
-  getMetaItem: z.any()
+  getMetaItem: z.function()
     .describe('Get a specific metadata item'),
-  saveMetaItem: z.any()
+  saveMetaItem: z.function()
     .describe('Save metadata item'),
-  getMetaItemCached: z.any()
+  getMetaItemCached: z.function()
     .describe('Get a metadata item with cache validation'),
 
-  getUiView: z.any()
+  getUiView: z.function()
     .describe('Get UI view definition'),
 
   // Analytics Operations
-  analyticsQuery: z.any()
+  analyticsQuery: z.function()
     .describe('Execute analytics query'),
 
-  getAnalyticsMeta: z.any()
+  getAnalyticsMeta: z.function()
     .describe('Get analytics metadata (cubes)'),
 
   // Automation Operations
-  triggerAutomation: z.any()
+  triggerAutomation: z.function()
     .describe('Trigger an automation flow or script'),
 
   // Hub Operations
-  listSpaces: z.any()
+  listSpaces: z.function()
     .describe('List Hub Spaces'),
 
-  createSpace: z.any()
+  createSpace: z.function()
     .describe('Create Hub Space'),
 
-  installPlugin: z.any()
+  installPlugin: z.function()
     .describe('Install Plugin into Space'),
 
   // Package Management Operations
-  listPackages: z.any()
+  listPackages: z.function()
     .describe('List installed packages with optional filters'),
 
-  getPackage: z.any()
+  getPackage: z.function()
     .describe('Get a specific installed package by ID'),
 
-  installPackage: z.any()
+  installPackage: z.function()
     .describe('Install a new package from manifest'),
 
-  uninstallPackage: z.any()
+  uninstallPackage: z.function()
     .describe('Uninstall a package by ID'),
 
-  enablePackage: z.any()
+  enablePackage: z.function()
     .describe('Enable a disabled package'),
 
-  disablePackage: z.any()
+  disablePackage: z.function()
     .describe('Disable an installed package'),
 
   // Data Operations
-  findData: z.any()
+  findData: z.function()
     .describe('Find data records'),
 
-  getData: z.any()
+  getData: z.function()
     .describe('Get single data record'),
 
-  createData: z.any()
+  createData: z.function()
     .describe('Create a data record'),
 
-  updateData: z.any()
+  updateData: z.function()
     .describe('Update a data record'),
 
-  deleteData: z.any()
+  deleteData: z.function()
     .describe('Delete a data record'),
 
   // Batch Operations
-  batchData: z.any()
+  batchData: z.function()
     .describe('Perform batch operations'),
 
-  createManyData: z.any()
+  createManyData: z.function()
     .describe('Create multiple records'),
 
-  updateManyData: z.any()
+  updateManyData: z.function()
     .describe('Update multiple records'),
 
-  deleteManyData: z.any()
+  deleteManyData: z.function()
     .describe('Delete multiple records'),
 });
 

packages/spec/src/api/realtime.test.ts

@@ -198,10 +198,13 @@ describe('RealtimePresenceStatus', () => {
   });
 
   it('should reject invalid presence statuses', () => {
-    expect(() => RealtimePresenceStatus.parse('busy')).toThrow();
     expect(() => RealtimePresenceStatus.parse('idle')).toThrow();
     expect(() => RealtimePresenceStatus.parse('')).toThrow();
   });
+
+  it('should accept busy status', () => {
+    expect(() => RealtimePresenceStatus.parse('busy')).not.toThrow();
+  });
 });
 
 describe('RealtimePresenceSchema', () => {

packages/spec/src/api/realtime.zod.ts

@@ -55,6 +55,7 @@ export type Subscription = z.infer<typeof SubscriptionSchema>;
 export const RealtimePresenceStatus = z.enum([
   'online',
   'away',
+  'busy',
   'offline',
 ]);
 

packages/spec/src/api/websocket.zod.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { EventNameSchema } from '../shared/identifiers.zod';
+import { RealtimePresenceStatus } from './realtime.zod';
 
 /**
  * WebSocket Event Protocol
@@ -133,14 +134,9 @@ export type UnsubscribeRequest = z.infer<typeof UnsubscribeRequestSchema>;
 
 /**
  * Presence Status Enum
- * User availability status for presence tracking
+ * Re-exported from realtime.zod.ts for backward compatibility
  */
-export const WebSocketPresenceStatus = z.enum([
-  'online',      // User is actively online
-  'away',        // User is idle/away
-  'busy',        // User is busy (do not disturb)
-  'offline',     // User is offline
-]);
+export const WebSocketPresenceStatus = RealtimePresenceStatus;
 
 export type WebSocketPresenceStatus = z.infer<typeof WebSocketPresenceStatus>;
 

packages/spec/src/data/hook.zod.ts

@@ -157,7 +157,7 @@ export const HookContextSchema = z.object({
    * Engine Access
    * Reference to the ObjectQL engine for performing side effects.
    */
-  ql: z.any().describe('ObjectQL Engine Reference'),
+  ql: z.unknown().describe('ObjectQL Engine Reference'),
 });
 
 export type Hook = z.input<typeof HookSchema>;

packages/spec/src/kernel/plugin.zod.ts

@@ -1,66 +1,65 @@
 import { z } from 'zod';
 
-// We use z.any() for service methods that are interfaces with function signatures,
-// as Zod cannot easily validate function signatures at runtime.
+// Service method interfaces use z.function() instead of z.any() for type safety.
 // Generic data fields use z.unknown() for type safety.
 export const PluginContextSchema = z.object({
   ql: z.object({
-    object: z.any(), // Return any to allow method chaining
-    query: z.any(),
+    object: z.function().describe('Get object handle for method chaining'),
+    query: z.function().describe('Execute a query'),
   }).passthrough().describe('ObjectQL Engine Interface'),
 
   os: z.object({
-    getCurrentUser: z.any(),
-    getConfig: z.any(),
+    getCurrentUser: z.function().describe('Get the current authenticated user'),
+    getConfig: z.function().describe('Get platform configuration'),
   }).passthrough().describe('ObjectStack Kernel Interface'),
 
   logger: z.object({
-    debug: z.any(),
-    info: z.any(),
-    warn: z.any(),
-    error: z.any(),
+    debug: z.function().describe('Log debug message'),
+    info: z.function().describe('Log info message'),
+    warn: z.function().describe('Log warning message'),
+    error: z.function().describe('Log error message'),
   }).passthrough().describe('Logger Interface'),
 
   storage: z.object({
-    get: z.any(),
-    set: z.any(),
-    delete: z.any(),
+    get: z.function().describe('Get a value from storage'),
+    set: z.function().describe('Set a value in storage'),
+    delete: z.function().describe('Delete a value from storage'),
   }).passthrough().describe('Storage Interface'),
 
   i18n: z.object({
-    t: z.any(),
-    getLocale: z.any(),
+    t: z.function().describe('Translate a key'),
+    getLocale: z.function().describe('Get current locale'),
   }).passthrough().describe('Internationalization Interface'),
 
   metadata: z.record(z.string(), z.unknown()),
   events: z.record(z.string(), z.unknown()),
 
   app: z.object({
     router: z.object({
-      get: z.any(),
-      post: z.any(),
-      use: z.any(),
+      get: z.function().describe('Register GET route handler'),
+      post: z.function().describe('Register POST route handler'),
+      use: z.function().describe('Register middleware'),
     }).passthrough()
   }).passthrough().describe('App Framework Interface'),
 
   drivers: z.object({
-    register: z.any(),
+    register: z.function().describe('Register a driver'),
   }).passthrough().describe('Driver Registry'),
 });
 
 export type PluginContextData = z.infer<typeof PluginContextSchema>;
 export type PluginContext = PluginContextData;
 
 export const PluginLifecycleSchema = z.object({
-  onInstall: z.any().optional(),
+  onInstall: z.function().optional().describe('Called when plugin is installed'),
 
-  onEnable: z.any().optional(),
+  onEnable: z.function().optional().describe('Called when plugin is enabled'),
 
-  onDisable: z.any().optional(),
+  onDisable: z.function().optional().describe('Called when plugin is disabled'),
 
-  onUninstall: z.any().optional(),
+  onUninstall: z.function().optional().describe('Called when plugin is uninstalled'),
 
-  onUpgrade: z.any().optional(),
+  onUpgrade: z.function().optional().describe('Called when plugin is upgraded'),
 });
 
 export type PluginLifecycleHooks = z.infer<typeof PluginLifecycleSchema>;

packages/spec/src/system/core-services.zod.ts

@@ -95,7 +95,7 @@ export const ServiceStatusSchema = z.object({
  */
 export const KernelServiceMapSchema = z.record(
   CoreServiceName, 
-  z.any().describe('Service Instance implementing the protocol interface')
+  z.unknown().describe('Service Instance implementing the protocol interface')
 );
 
 // ==========================================