@objectstack/metadata 2.0.6 → 3.0.0

package/dist/index.mjs

@@ -179,6 +179,14 @@ var MetadataManager = class {
   constructor(config) {
     this.loaders = /* @__PURE__ */ new Map();
     this.watchCallbacks = /* @__PURE__ */ new Map();
+    // In-memory metadata registry: type -> name -> data
+    this.registry = /* @__PURE__ */ new Map();
+    // Overlay storage: "type:name:scope" -> MetadataOverlay
+    this.overlays = /* @__PURE__ */ new Map();
+    // Type registry for metadata type info
+    this.typeRegistry = [];
+    // Dependency tracking: "type:name" -> dependencies
+    this.dependencies = /* @__PURE__ */ new Map();
     this.config = config;
     this.logger = createLogger({ level: "info", format: "pretty" });
     this.serializers = /* @__PURE__ */ new Map();
@@ -199,6 +207,12 @@ var MetadataManager = class {
       config.loaders.forEach((loader) => this.registerLoader(loader));
     }
   }
+  /**
+   * Set the type registry for metadata type discovery.
+   */
+  setTypeRegistry(entries) {
+    this.typeRegistry = entries;
+  }
   /**
    * Register a new metadata loader (data source)
    */
@@ -206,9 +220,513 @@ var MetadataManager = class {
     this.loaders.set(loader.contract.name, loader);
     this.logger.info(`Registered metadata loader: ${loader.contract.name} (${loader.contract.protocol})`);
   }
+  // ==========================================
+  // IMetadataService — Core CRUD Operations
+  // ==========================================
+  /**
+   * Register/save a metadata item by type
+   */
+  async register(type, name, data) {
+    if (!this.registry.has(type)) {
+      this.registry.set(type, /* @__PURE__ */ new Map());
+    }
+    this.registry.get(type).set(name, data);
+  }
+  /**
+   * Get a metadata item by type and name.
+   * Checks in-memory registry first, then falls back to loaders.
+   */
+  async get(type, name) {
+    const typeStore = this.registry.get(type);
+    if (typeStore?.has(name)) {
+      return typeStore.get(name);
+    }
+    const result = await this.load(type, name);
+    return result ?? void 0;
+  }
+  /**
+   * List all metadata items of a given type
+   */
+  async list(type) {
+    const items = /* @__PURE__ */ new Map();
+    const typeStore = this.registry.get(type);
+    if (typeStore) {
+      for (const [name, data] of typeStore) {
+        items.set(name, data);
+      }
+    }
+    for (const loader of this.loaders.values()) {
+      try {
+        const loaderItems = await loader.loadMany(type);
+        for (const item of loaderItems) {
+          const itemAny = item;
+          if (itemAny && typeof itemAny.name === "string" && !items.has(itemAny.name)) {
+            items.set(itemAny.name, item);
+          }
+        }
+      } catch (e) {
+        this.logger.warn(`Loader ${loader.contract.name} failed to loadMany ${type}`, { error: e });
+      }
+    }
+    return Array.from(items.values());
+  }
+  /**
+   * Unregister/remove a metadata item by type and name
+   */
+  async unregister(type, name) {
+    const typeStore = this.registry.get(type);
+    if (typeStore) {
+      typeStore.delete(name);
+      if (typeStore.size === 0) {
+        this.registry.delete(type);
+      }
+    }
+  }
+  /**
+   * Check if a metadata item exists
+   */
+  async exists(type, name) {
+    if (this.registry.get(type)?.has(name)) {
+      return true;
+    }
+    for (const loader of this.loaders.values()) {
+      if (await loader.exists(type, name)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * List all names of metadata items of a given type
+   */
+  async listNames(type) {
+    const names = /* @__PURE__ */ new Set();
+    const typeStore = this.registry.get(type);
+    if (typeStore) {
+      for (const name of typeStore.keys()) {
+        names.add(name);
+      }
+    }
+    for (const loader of this.loaders.values()) {
+      const result = await loader.list(type);
+      result.forEach((item) => names.add(item));
+    }
+    return Array.from(names);
+  }
+  /**
+   * Convenience: get an object definition by name
+   */
+  async getObject(name) {
+    return this.get("object", name);
+  }
+  /**
+   * Convenience: list all object definitions
+   */
+  async listObjects() {
+    return this.list("object");
+  }
+  // ==========================================
+  // Package Management
+  // ==========================================
+  /**
+   * Unregister all metadata items from a specific package
+   */
+  async unregisterPackage(packageName) {
+    for (const [type, typeStore] of this.registry) {
+      const toDelete = [];
+      for (const [name, data] of typeStore) {
+        const meta = data;
+        if (meta?.packageId === packageName || meta?.package === packageName) {
+          toDelete.push(name);
+        }
+      }
+      for (const name of toDelete) {
+        typeStore.delete(name);
+      }
+      if (typeStore.size === 0) {
+        this.registry.delete(type);
+      }
+    }
+  }
+  // ==========================================
+  // Query / Search
+  // ==========================================
+  /**
+   * Query metadata items with filtering, sorting, and pagination
+   */
+  async query(query) {
+    const { types, search, page = 1, pageSize = 50, sortBy = "name", sortOrder = "asc" } = query;
+    const allItems = [];
+    const targetTypes = types && types.length > 0 ? types : Array.from(this.registry.keys());
+    for (const type of targetTypes) {
+      const items = await this.list(type);
+      for (const item of items) {
+        const meta = item;
+        allItems.push({
+          type,
+          name: meta?.name ?? "",
+          namespace: meta?.namespace,
+          label: meta?.label,
+          scope: meta?.scope,
+          state: meta?.state,
+          packageId: meta?.packageId,
+          updatedAt: meta?.updatedAt
+        });
+      }
+    }
+    let filtered = allItems;
+    if (search) {
+      const searchLower = search.toLowerCase();
+      filtered = filtered.filter(
+        (item) => item.name.toLowerCase().includes(searchLower) || item.label && item.label.toLowerCase().includes(searchLower)
+      );
+    }
+    if (query.scope) {
+      filtered = filtered.filter((item) => item.scope === query.scope);
+    }
+    if (query.state) {
+      filtered = filtered.filter((item) => item.state === query.state);
+    }
+    if (query.namespaces && query.namespaces.length > 0) {
+      filtered = filtered.filter((item) => item.namespace && query.namespaces.includes(item.namespace));
+    }
+    if (query.packageId) {
+      filtered = filtered.filter((item) => item.packageId === query.packageId);
+    }
+    if (query.tags && query.tags.length > 0) {
+      filtered = filtered.filter((item) => {
+        const meta = item;
+        return meta?.tags && query.tags.some((t) => meta.tags.includes(t));
+      });
+    }
+    filtered.sort((a, b) => {
+      const aVal = a[sortBy] ?? "";
+      const bVal = b[sortBy] ?? "";
+      const cmp = String(aVal).localeCompare(String(bVal));
+      return sortOrder === "desc" ? -cmp : cmp;
+    });
+    const total = filtered.length;
+    const start = (page - 1) * pageSize;
+    const paged = filtered.slice(start, start + pageSize);
+    return {
+      items: paged,
+      total,
+      page,
+      pageSize
+    };
+  }
+  // ==========================================
+  // Bulk Operations
+  // ==========================================
+  /**
+   * Register multiple metadata items in a single batch
+   */
+  async bulkRegister(items, options) {
+    const { continueOnError = false } = options ?? {};
+    let succeeded = 0;
+    let failed = 0;
+    const errors = [];
+    for (const item of items) {
+      try {
+        await this.register(item.type, item.name, item.data);
+        succeeded++;
+      } catch (e) {
+        failed++;
+        errors.push({
+          type: item.type,
+          name: item.name,
+          error: e instanceof Error ? e.message : String(e)
+        });
+        if (!continueOnError) break;
+      }
+    }
+    return {
+      total: items.length,
+      succeeded,
+      failed,
+      errors: errors.length > 0 ? errors : void 0
+    };
+  }
+  /**
+   * Unregister multiple metadata items in a single batch
+   */
+  async bulkUnregister(items) {
+    let succeeded = 0;
+    let failed = 0;
+    const errors = [];
+    for (const item of items) {
+      try {
+        await this.unregister(item.type, item.name);
+        succeeded++;
+      } catch (e) {
+        failed++;
+        errors.push({
+          type: item.type,
+          name: item.name,
+          error: e instanceof Error ? e.message : String(e)
+        });
+      }
+    }
+    return {
+      total: items.length,
+      succeeded,
+      failed,
+      errors: errors.length > 0 ? errors : void 0
+    };
+  }
+  // ==========================================
+  // Overlay / Customization Management
+  // ==========================================
+  overlayKey(type, name, scope = "platform") {
+    return `${encodeURIComponent(type)}:${encodeURIComponent(name)}:${scope}`;
+  }
+  /**
+   * Get the active overlay for a metadata item
+   */
+  async getOverlay(type, name, scope) {
+    return this.overlays.get(this.overlayKey(type, name, scope ?? "platform"));
+  }
+  /**
+   * Save/update an overlay for a metadata item
+   */
+  async saveOverlay(overlay) {
+    const key = this.overlayKey(overlay.baseType, overlay.baseName, overlay.scope);
+    this.overlays.set(key, overlay);
+  }
+  /**
+   * Remove an overlay, reverting to the base definition
+   */
+  async removeOverlay(type, name, scope) {
+    this.overlays.delete(this.overlayKey(type, name, scope ?? "platform"));
+  }
+  /**
+   * Get the effective (merged) metadata after applying all overlays.
+   * Resolution order: system ← merge(platform) ← merge(user)
+   */
+  async getEffective(type, name) {
+    const base = await this.get(type, name);
+    if (!base) return void 0;
+    let effective = { ...base };
+    const platformOverlay = await this.getOverlay(type, name, "platform");
+    if (platformOverlay?.active && platformOverlay.patch) {
+      effective = { ...effective, ...platformOverlay.patch };
+    }
+    const userOverlay = await this.getOverlay(type, name, "user");
+    if (userOverlay?.active && userOverlay.patch) {
+      effective = { ...effective, ...userOverlay.patch };
+    }
+    return effective;
+  }
+  // ==========================================
+  // Watch / Subscribe (IMetadataService)
+  // ==========================================
   /**
-   * Load a single metadata item
-   * Iterates through registered loaders until found
+   * Watch for metadata changes (IMetadataService contract).
+   * Returns a handle for unsubscribing.
+   */
+  watchService(type, callback) {
+    const wrappedCallback = (event) => {
+      const mappedType = event.type === "added" ? "registered" : event.type === "deleted" ? "unregistered" : "updated";
+      callback({
+        type: mappedType,
+        metadataType: event.metadataType ?? type,
+        name: event.name ?? "",
+        data: event.data
+      });
+    };
+    this.addWatchCallback(type, wrappedCallback);
+    return {
+      unsubscribe: () => this.removeWatchCallback(type, wrappedCallback)
+    };
+  }
+  // ==========================================
+  // Import / Export
+  // ==========================================
+  /**
+   * Export metadata as a portable bundle
+   */
+  async exportMetadata(options) {
+    const bundle = {};
+    const targetTypes = options?.types ?? Array.from(this.registry.keys());
+    for (const type of targetTypes) {
+      const items = await this.list(type);
+      if (items.length > 0) {
+        bundle[type] = items;
+      }
+    }
+    return bundle;
+  }
+  /**
+   * Import metadata from a portable bundle
+   */
+  async importMetadata(data, options) {
+    const {
+      conflictResolution = "skip",
+      validate: _validate = true,
+      dryRun = false
+    } = options ?? {};
+    const bundle = data;
+    let total = 0;
+    let imported = 0;
+    let skipped = 0;
+    let failed = 0;
+    const errors = [];
+    for (const [type, items] of Object.entries(bundle)) {
+      if (!Array.isArray(items)) continue;
+      for (const item of items) {
+        total++;
+        const meta = item;
+        const name = meta?.name;
+        if (!name) {
+          failed++;
+          errors.push({ type, name: "(unknown)", error: "Item missing name field" });
+          continue;
+        }
+        try {
+          const itemExists = await this.exists(type, name);
+          if (itemExists && conflictResolution === "skip") {
+            skipped++;
+            continue;
+          }
+          if (!dryRun) {
+            if (itemExists && conflictResolution === "merge") {
+              const existing = await this.get(type, name);
+              const merged = { ...existing, ...item };
+              await this.register(type, name, merged);
+            } else {
+              await this.register(type, name, item);
+            }
+          }
+          imported++;
+        } catch (e) {
+          failed++;
+          errors.push({
+            type,
+            name,
+            error: e instanceof Error ? e.message : String(e)
+          });
+        }
+      }
+    }
+    return {
+      total,
+      imported,
+      skipped,
+      failed,
+      errors: errors.length > 0 ? errors : void 0
+    };
+  }
+  // ==========================================
+  // Validation
+  // ==========================================
+  /**
+   * Validate a metadata item against its type schema.
+   * Returns validation result with errors and warnings.
+   */
+  async validate(_type, data) {
+    if (data === null || data === void 0) {
+      return {
+        valid: false,
+        errors: [{ path: "", message: "Metadata data cannot be null or undefined" }]
+      };
+    }
+    if (typeof data !== "object") {
+      return {
+        valid: false,
+        errors: [{ path: "", message: "Metadata data must be an object" }]
+      };
+    }
+    const meta = data;
+    const warnings = [];
+    if (!meta.name) {
+      return {
+        valid: false,
+        errors: [{ path: "name", message: "Metadata item must have a name field" }]
+      };
+    }
+    if (!meta.label) {
+      warnings.push({ path: "label", message: "Missing label field (recommended)" });
+    }
+    return { valid: true, warnings: warnings.length > 0 ? warnings : void 0 };
+  }
+  // ==========================================
+  // Type Registry
+  // ==========================================
+  /**
+   * Get all registered metadata types
+   */
+  async getRegisteredTypes() {
+    const types = /* @__PURE__ */ new Set();
+    for (const entry of this.typeRegistry) {
+      types.add(entry.type);
+    }
+    for (const type of this.registry.keys()) {
+      types.add(type);
+    }
+    return Array.from(types);
+  }
+  /**
+   * Get detailed information about a metadata type
+   */
+  async getTypeInfo(type) {
+    const entry = this.typeRegistry.find((e) => e.type === type);
+    if (!entry) return void 0;
+    return {
+      type: entry.type,
+      label: entry.label,
+      description: entry.description,
+      filePatterns: entry.filePatterns,
+      supportsOverlay: entry.supportsOverlay,
+      domain: entry.domain
+    };
+  }
+  // ==========================================
+  // Dependency Tracking
+  // ==========================================
+  /**
+   * Get metadata items that this item depends on
+   */
+  async getDependencies(type, name) {
+    return this.dependencies.get(`${encodeURIComponent(type)}:${encodeURIComponent(name)}`) ?? [];
+  }
+  /**
+   * Get metadata items that depend on this item
+   */
+  async getDependents(type, name) {
+    const dependents = [];
+    for (const deps of this.dependencies.values()) {
+      for (const dep of deps) {
+        if (dep.targetType === type && dep.targetName === name) {
+          dependents.push(dep);
+        }
+      }
+    }
+    return dependents;
+  }
+  /**
+   * Register a dependency between two metadata items.
+   * Used internally to track cross-references.
+   * Duplicate dependencies (same source, target, and kind) are ignored.
+   */
+  addDependency(dep) {
+    const key = `${encodeURIComponent(dep.sourceType)}:${encodeURIComponent(dep.sourceName)}`;
+    if (!this.dependencies.has(key)) {
+      this.dependencies.set(key, []);
+    }
+    const existing = this.dependencies.get(key);
+    const isDuplicate = existing.some(
+      (d) => d.targetType === dep.targetType && d.targetName === dep.targetName && d.kind === dep.kind
+    );
+    if (!isDuplicate) {
+      existing.push(dep);
+    }
+  }
+  // ==========================================
+  // Legacy Loader API (backward compatible)
+  // ==========================================
+  /**
+   * Load a single metadata item from loaders.
+   * Iterates through registered loaders until found.
    */
   async load(type, name, options) {
     for (const loader of this.loaders.values()) {
@@ -224,8 +742,8 @@ var MetadataManager = class {
     return null;
   }
   /**
-   * Load multiple metadata items
-   * Aggregates results from all loaders
+   * Load multiple metadata items from loaders.
+   * Aggregates results from all loaders.
    */
   async loadMany(type, options) {
     const results = [];
@@ -247,10 +765,7 @@ var MetadataManager = class {
     return results;
   }
   /**
-   * Save metadata to disk
-   */
-  /**
-   * Save metadata item
+   * Save metadata item to a loader
    */
   async save(type, name, data, options) {
     const targetLoader = options?.loader;
@@ -296,40 +811,18 @@ var MetadataManager = class {
     return loader.save(type, name, data, options);
   }
   /**
-   * Check if metadata item exists
+   * Register a watch callback for metadata changes
    */
-  async exists(type, name) {
-    for (const loader of this.loaders.values()) {
-      if (await loader.exists(type, name)) {
-        return true;
-      }
-    }
-    return false;
-  }
-  /**
-   * List all items of a type
-   */
-  async list(type) {
-    const items = /* @__PURE__ */ new Set();
-    for (const loader of this.loaders.values()) {
-      const result = await loader.list(type);
-      result.forEach((item) => items.add(item));
-    }
-    return Array.from(items);
-  }
-  /**
-   * Watch for metadata changes
-   */
-  watch(type, callback) {
+  addWatchCallback(type, callback) {
     if (!this.watchCallbacks.has(type)) {
       this.watchCallbacks.set(type, /* @__PURE__ */ new Set());
     }
     this.watchCallbacks.get(type).add(callback);
   }
   /**
-   * Unwatch metadata changes
+   * Remove a watch callback for metadata changes
    */
-  unwatch(type, callback) {
+  removeWatchCallback(type, callback) {
     const callbacks = this.watchCallbacks.get(type);
     if (callbacks) {
       callbacks.delete(callback);
@@ -375,7 +868,7 @@ var FilesystemLoader = class {
     this.logger = logger;
     this.contract = {
       name: "filesystem",
-      protocol: "file",
+      protocol: "file:",
       capabilities: {
         read: true,
         write: true,
@@ -527,7 +1020,7 @@ var FilesystemLoader = class {
       const format = this.detectFormat(filePath);
       return {
         size: stats.size,
-        modifiedAt: stats.mtime,
+        modifiedAt: stats.mtime.toISOString(),
         etag,
         format,
         path: filePath
@@ -758,14 +1251,14 @@ var NodeMetadataManager = class extends MetadataManager {
       name,
       path: filePath,
       data,
-      timestamp: /* @__PURE__ */ new Date()
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
     };
     this.notifyWatchers(type, event);
   }
 };
 
 // src/plugin.ts
-import { ObjectStackDefinitionSchema } from "@objectstack/spec";
+import { DEFAULT_METADATA_TYPE_REGISTRY } from "@objectstack/spec/kernel";
 var MetadataPlugin = class {
   constructor(options = {}) {
     this.name = "com.objectstack.metadata";
@@ -779,29 +1272,35 @@ var MetadataPlugin = class {
       ctx.registerService("metadata", this.manager);
       ctx.logger.info("MetadataPlugin providing metadata service (primary mode)", {
         mode: "file-system",
-        features: ["watch", "persistence", "multi-format"]
+        features: ["watch", "persistence", "multi-format", "query", "overlay", "type-registry"]
       });
     };
     this.start = async (ctx) => {
       ctx.logger.info("Loading metadata from file system...");
-      const metadataTypes = Object.keys(ObjectStackDefinitionSchema.shape).filter((key) => key !== "manifest");
+      const sortedTypes = [...DEFAULT_METADATA_TYPE_REGISTRY].sort((a, b) => a.loadOrder - b.loadOrder);
       let totalLoaded = 0;
-      for (const type of metadataTypes) {
+      for (const entry of sortedTypes) {
         try {
-          const items = await this.manager.loadMany(type, {
+          const items = await this.manager.loadMany(entry.type, {
             recursive: true
           });
           if (items.length > 0) {
-            ctx.logger.info(`Loaded ${items.length} ${type} from file system`);
+            for (const item of items) {
+              const meta = item;
+              if (meta?.name) {
+                await this.manager.register(entry.type, meta.name, item);
+              }
+            }
+            ctx.logger.info(`Loaded ${items.length} ${entry.type} from file system`);
             totalLoaded += items.length;
           }
         } catch (e) {
-          ctx.logger.debug(`No ${type} metadata found`, { error: e.message });
+          ctx.logger.debug(`No ${entry.type} metadata found`, { error: e.message });
         }
       }
       ctx.logger.info("Metadata loading complete", {
         totalItems: totalLoaded,
-        note: "ObjectQL will sync these into its registry during its start phase"
+        registeredTypes: sortedTypes.length
       });
     };
     this.options = {
@@ -814,6 +1313,7 @@ var MetadataPlugin = class {
       watch: this.options.watch ?? true,
       formats: ["yaml", "json", "typescript", "javascript"]
     });
+    this.manager.setTypeRegistry(DEFAULT_METADATA_TYPE_REGISTRY);
   }
 };
 
@@ -822,7 +1322,7 @@ var MemoryLoader = class {
   constructor() {
     this.contract = {
       name: "memory",
-      protocol: "memory",
+      protocol: "memory:",
       capabilities: {
         read: true,
         write: true,
@@ -890,7 +1390,7 @@ var RemoteLoader = class {
     this.authToken = authToken;
     this.contract = {
       name: "remote",
-      protocol: "http",
+      protocol: "http:",
       capabilities: {
         read: true,
         write: true,