feat: implement SaveMetaItem request and response schemas; add RemoteLoader for metadata fetching; enhance MetadataManager with Node-specific capabilities

Author: hotlong

content/docs/references/api/protocol.mdx

@@ -34,8 +34,8 @@ Architecture Alignment:
 ## TypeScript Usage
 
 ```typescript
-import { AutomationTriggerRequest, AutomationTriggerResponse, BatchDataRequest, BatchDataResponse, CreateDataRequest, CreateDataResponse, CreateManyDataRequest, CreateManyDataResponse, DeleteDataRequest, DeleteDataResponse, DeleteManyDataRequest, DeleteManyDataResponse, FindDataRequest, FindDataResponse, GetDataRequest, GetDataResponse, GetDiscoveryRequest, GetDiscoveryResponse, GetMetaItemCachedRequest, GetMetaItemCachedResponse, GetMetaItemRequest, GetMetaItemResponse, GetMetaItemsRequest, GetMetaItemsResponse, GetMetaTypesRequest, GetMetaTypesResponse, GetUiViewRequest, GetUiViewResponse, ObjectStackProtocol, UpdateDataRequest, UpdateDataResponse, UpdateManyDataRequest, UpdateManyDataResponse } from '@objectstack/spec/api';
-import type { AutomationTriggerRequest, AutomationTriggerResponse, BatchDataRequest, BatchDataResponse, CreateDataRequest, CreateDataResponse, CreateManyDataRequest, CreateManyDataResponse, DeleteDataRequest, DeleteDataResponse, DeleteManyDataRequest, DeleteManyDataResponse, FindDataRequest, FindDataResponse, GetDataRequest, GetDataResponse, GetDiscoveryRequest, GetDiscoveryResponse, GetMetaItemCachedRequest, GetMetaItemCachedResponse, GetMetaItemRequest, GetMetaItemResponse, GetMetaItemsRequest, GetMetaItemsResponse, GetMetaTypesRequest, GetMetaTypesResponse, GetUiViewRequest, GetUiViewResponse, ObjectStackProtocol, UpdateDataRequest, UpdateDataResponse, UpdateManyDataRequest, UpdateManyDataResponse } from '@objectstack/spec/api';
+import { AutomationTriggerRequest, AutomationTriggerResponse, BatchDataRequest, BatchDataResponse, CreateDataRequest, CreateDataResponse, CreateManyDataRequest, CreateManyDataResponse, DeleteDataRequest, DeleteDataResponse, DeleteManyDataRequest, DeleteManyDataResponse, FindDataRequest, FindDataResponse, GetDataRequest, GetDataResponse, GetDiscoveryRequest, GetDiscoveryResponse, GetMetaItemCachedRequest, GetMetaItemCachedResponse, GetMetaItemRequest, GetMetaItemResponse, GetMetaItemsRequest, GetMetaItemsResponse, GetMetaTypesRequest, GetMetaTypesResponse, GetUiViewRequest, GetUiViewResponse, ObjectStackProtocol, SaveMetaItemRequest, SaveMetaItemResponse, UpdateDataRequest, UpdateDataResponse, UpdateManyDataRequest, UpdateManyDataResponse } from '@objectstack/spec/api';
+import type { AutomationTriggerRequest, AutomationTriggerResponse, BatchDataRequest, BatchDataResponse, CreateDataRequest, CreateDataResponse, CreateManyDataRequest, CreateManyDataResponse, DeleteDataRequest, DeleteDataResponse, DeleteManyDataRequest, DeleteManyDataResponse, FindDataRequest, FindDataResponse, GetDataRequest, GetDataResponse, GetDiscoveryRequest, GetDiscoveryResponse, GetMetaItemCachedRequest, GetMetaItemCachedResponse, GetMetaItemRequest, GetMetaItemResponse, GetMetaItemsRequest, GetMetaItemsResponse, GetMetaTypesRequest, GetMetaTypesResponse, GetUiViewRequest, GetUiViewResponse, ObjectStackProtocol, SaveMetaItemRequest, SaveMetaItemResponse, UpdateDataRequest, UpdateDataResponse, UpdateManyDataRequest, UpdateManyDataResponse } from '@objectstack/spec/api';
 
 // Validate data
 const result = AutomationTriggerRequest.parse(data);
@@ -411,6 +411,31 @@ const result = AutomationTriggerRequest.parse(data);
 | :--- | :--- | :--- | :--- |
 
 
+---
+
+## SaveMetaItemRequest
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **type** | `string` | ✅ | Metadata type name |
+| **name** | `string` | ✅ | Item name |
+| **item** | `any` | optional | Metadata item definition |
+
+
+---
+
+## SaveMetaItemResponse
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **success** | `boolean` | ✅ |  |
+| **message** | `string` | optional |  |
+
+
 ---
 
 ## UpdateDataRequest

examples/app-react-crud/package.json

@@ -17,6 +17,7 @@
     "@objectstack/client-react": "workspace:*",
     "@objectstack/driver-memory": "workspace:*",
     "@example/app-todo": "workspace:*",
+    "@objectstack/metadata": "workspace:*",
     "@objectstack/plugin-msw": "workspace:*",
     "@objectstack/runtime": "workspace:*",
     "@objectstack/objectql": "workspace:*",

examples/app-react-crud/src/App.tsx

@@ -10,6 +10,7 @@ import { ObjectStackClient } from '@objectstack/client';
 import type { Task } from './types';
 import { TaskForm } from './components/TaskForm';
 import { TaskList } from './components/TaskList';
+import { MetadataDemo } from './components/MetadataDemo';
 import './App.css';
 
 export function App() {
@@ -130,6 +131,10 @@ export function App() {
         </section>
       </main>
 
+      <div className="mt-8">
+        <MetadataDemo />
+      </div>
+
       <footer className="mt-16 pt-8 border-t border-accents-2 text-center text-sm text-accents-4 space-y-2">
         <p>
           This example demonstrates MSW integration with React components.

examples/app-react-crud/src/components/MetadataDemo.tsx

@@ -0,0 +1,77 @@
+import { useState, useEffect } from 'react';
+import { MetadataManager, RemoteLoader } from '@objectstack/metadata';
+
+export function MetadataDemo() {
+  const [manager, setManager] = useState<MetadataManager | null>(null);
+  const [data, setData] = useState<any>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    // Initialize Metadata Manager with Remote Loader pointing to MSW
+    // MSW is configured at /api/v1
+    // MSW Plugin exposes metadata at /meta/:type/:name
+    // So RemoteLoader should target /api/v1/meta
+    const mgr = new MetadataManager({
+      loaders: [
+        new RemoteLoader('/api/v1/meta')
+      ]
+    });
+    setManager(mgr);
+  }, []);
+
+  const loadMetadata = async () => {
+    if (!manager) return;
+    setLoading(true);
+    setError(null);
+    setData(null);
+
+    try {
+      console.log('Fetching metadata for object: todo_task...');
+      const result = await manager.load('objects', 'todo_task');
+      console.log('Result:', result);
+      
+      if (result) {
+        setData(result);
+      } else {
+        setError('Metadata not found');
+      }
+    } catch (err) {
+      console.error('Metadata load error:', err);
+      setError(err instanceof Error ? err.message : 'Unknown error');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div className="p-4 border rounded bg-gray-50 mt-4">
+      <h3 className="text-lg font-bold mb-2">Remote Loader Demo (Browser)</h3>
+      <p className="text-sm text-gray-600 mb-4">
+        Fetches metadata via <code>RemoteLoader</code> → <code>fetch</code> → <code>MSW Interceptor</code> → <code>ObjectStack Kernel</code>
+      </p>
+
+      <div className="flex gap-2 mb-4">
+        <button 
+          onClick={loadMetadata} 
+          disabled={loading || !manager}
+          className="px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700 disabled:opacity-50"
+        >
+          {loading ? 'Loading...' : 'Load TodoTask Metadata'}
+        </button>
+      </div>
+
+      {error && (
+        <div className="p-3 bg-red-100 text-red-700 rounded mb-2">
+          {error}
+        </div>
+      )}
+
+      {data && (
+        <div className="bg-white p-3 rounded border overflow-auto max-h-60">
+          <pre className="text-xs">{JSON.stringify(data, null, 2)}</pre>
+        </div>
+      )}
+    </div>
+  );
+}

examples/metadata-demo/src/local-fs-workflow.ts

@@ -1,4 +1,4 @@
-import { MetadataManager } from '@objectstack/metadata';
+import { NodeMetadataManager } from '@objectstack/metadata/node';
 import * as path from 'node:path';
 import * as fs from 'node:fs/promises';
 
@@ -10,8 +10,8 @@ async function main() {
   console.log(`📂 项目目录: ${PROJECT_ROOT}`);
 
   // 1. 初始化管理器，指向项目根目录
-  // MetadataManager 会自动在这个目录下寻找 `objects`, `views`, `apps` 等子目录
-  const manager = new MetadataManager({
+  // NodeMetadataManager 会自动在这个目录下寻找 `objects`, `views`, `apps` 等子目录
+  const manager = new NodeMetadataManager({
     rootDir: path.join(PROJECT_ROOT, 'src'), // 假设元数据在 src 下
     formats: ['yaml', 'json'],               // 优先使用 YAML
     watch: true                              // 开启监听

examples/metadata-demo/src/remote-mode.ts

@@ -0,0 +1,74 @@
+
+import { MetadataManager } from '@objectstack/metadata';
+import { RemoteLoader } from '@objectstack/metadata';
+
+// Mock global fetch to simulate MSW (Mock Service Worker)
+// In a real app, MSW would intercept the requests network-level.
+const mockDatabase: Record<string, any> = {
+  'objects/customer': {
+    name: 'customer',
+    label: 'Customer',
+    fields: {
+      name: { type: 'text' }
+    }
+  },
+  'views/all_customers': {
+    name: 'all_customers',
+    object: 'customer',
+    type: 'grid'
+  }
+};
+
+global.fetch = async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+  const url = input.toString();
+  console.log(`[MockNetwork] ${init?.method || 'GET'} ${url}`);
+
+  if (init?.method === 'GET') {
+    // URL format: http://api.example.com/metadata/{type}/{name}
+    const parts = url.split('/');
+    const name = parts.pop();
+    const type = parts.pop();
+    const key = `${type}/${name}`;
+    
+    if (mockDatabase[key]) {
+      return new Response(JSON.stringify(mockDatabase[key]), { status: 200 });
+    }
+    return new Response(null, { status: 404 });
+  }
+
+  // Handle loadMany (list)
+  // URL format: http://api.example.com/metadata/{type}
+  // This is a naive check, improvements needed for robust routing
+  if (init?.method === 'GET' && !url.split('/').pop()?.includes('_')) {
+     // Simplifying for demo: returns empty list for directory listing if not specific match above
+     return new Response(JSON.stringify([]), { status: 200 });
+  }
+
+  return new Response(null, { status: 404 });
+};
+
+
+async function runRemoteDemo() {
+  console.log('--- Starting Remote Loader Demo (Simulating MSW) ---');
+
+  // 1. Initialize Manager with RemoteLoader
+  const manager = new MetadataManager({
+    loaders: [
+      new RemoteLoader('http://api.example.com/metadata')
+    ]
+  });
+
+  // 2. Load Item (Network Request -> Mocked Response)
+  console.log('\nLoading Customer Object...');
+  const customer = await manager.load('objects', 'customer');
+  console.log('Result:', customer ? customer.label : 'Not Found');
+
+  // 3. Load Missing Item
+  console.log('\nLoading Missing Object...');
+  const missing = await manager.load('objects', 'ghost');
+  console.log('Result:', missing ? 'Found' : 'Correctly returned null');
+
+  console.log('\n--- Demo Complete ---');
+}
+
+runRemoteDemo().catch(console.error);

packages/client/src/index.ts

@@ -161,6 +161,21 @@ export class ObjectStackClient {
         const res = await this.fetch(`${this.baseUrl}${route}/${type}/${name}`);
         return res.json();
     },
+
+    /**
+     * Save a metadata item
+     * @param type - Metadata type (e.g., 'object', 'plugin')
+     * @param name - Item name
+     * @param item - The metadata content to save
+     */
+    saveItem: async (type: string, name: string, item: any) => {
+        const route = this.getRoute('metadata');
+        const res = await this.fetch(`${this.baseUrl}${route}/${type}/${name}`, {
+            method: 'PUT',
+            body: JSON.stringify(item)
+        });
+        return res.json();
+    },
 
     /**
      * Get object metadata with cache support

packages/metadata/package.json

@@ -5,6 +5,18 @@
   "description": "Metadata loading, saving, and persistence for ObjectStack",
   "main": "src/index.ts",
   "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./node": {
+      "types": "./src/node.ts",
+      "import": "./src/node.ts",
+      "default": "./src/node.ts"
+    }
+  },
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",

packages/metadata/src/index.ts

@@ -5,15 +5,12 @@
  */
 
 // Main Manager
-export { MetadataManager, type WatchCallback } from './metadata-manager.js';
-
-// Plugin
-export { MetadataPlugin } from './plugin.js';
+export { MetadataManager, type WatchCallback, type MetadataManagerOptions } from './metadata-manager.js';
 
 // Loaders
 export { type MetadataLoader } from './loaders/loader-interface.js';
-export { FilesystemLoader } from './loaders/filesystem-loader.js';
 export { MemoryLoader } from './loaders/memory-loader.js';
+export { RemoteLoader } from './loaders/remote-loader.js';
 
 // Serializers
 export { type MetadataSerializer, type SerializeOptions } from './serializers/serializer-interface.js';