@objectstack/metadata 4.1.1 → 5.0.0

package/dist/index.cjs

@@ -5,6 +5,9 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -27,6 +30,160 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// src/routes/hmr-routes.ts
+var hmr_routes_exports = {};
+__export(hmr_routes_exports, {
+  registerMetadataHmrRoutes: () => registerMetadataHmrRoutes
+});
+function registerMetadataHmrRoutes(app, manager, options = {}) {
+  const routePath = options.path ?? "/api/v1/dev/metadata-events";
+  const listeners = /* @__PURE__ */ new Set();
+  const broadcast = (evt) => {
+    for (const l of listeners) {
+      try {
+        l(evt);
+      } catch {
+      }
+    }
+  };
+  let fsHookInstalled = false;
+  const installFsHooks = async () => {
+    if (fsHookInstalled) return;
+    const mgr = manager;
+    if (typeof mgr.subscribe !== "function") {
+      fsHookInstalled = true;
+      return;
+    }
+    const types = await manager.getRegisteredTypes();
+    for (const type of types) {
+      mgr.subscribe(type, (evt) => {
+        const ts = typeof evt.timestamp === "string" ? Date.parse(evt.timestamp) : evt.timestamp ?? Date.now();
+        broadcast({
+          kind: "metadata-change",
+          type: evt.type ?? "changed",
+          metadataType: evt.metadataType ?? type,
+          name: evt.name ?? "",
+          path: evt.path,
+          timestamp: Number.isFinite(ts) ? ts : Date.now(),
+          // Forward the canonical server-side sequence number when the
+          // event originated from a MetadataRepository (ADR-0008). Legacy
+          // chokidar-driven events have no seq — clients fall back to
+          // their local counter in that case.
+          ...typeof evt.seq === "number" ? { seq: evt.seq } : {}
+        });
+      });
+    }
+    fsHookInstalled = true;
+  };
+  installFsHooks().catch(() => {
+  });
+  let onPostReload = null;
+  app.get(routePath, async (c) => {
+    await installFsHooks().catch(() => {
+    });
+    const types = await manager.getRegisteredTypes().catch(() => []);
+    const stream = new ReadableStream({
+      async start(controller) {
+        const enc = new TextEncoder();
+        let closed = false;
+        const safeEnqueue = (chunk) => {
+          if (closed) return;
+          try {
+            controller.enqueue(enc.encode(chunk));
+          } catch {
+            closed = true;
+          }
+        };
+        const listener = (evt) => {
+          if (closed) return;
+          const eventName = evt.kind === "reload" ? "reload" : "metadata-change";
+          safeEnqueue(`event: ${eventName}
+data: ${JSON.stringify(evt)}
+
+`);
+        };
+        listeners.add(listener);
+        safeEnqueue(`event: ready
+data: ${JSON.stringify({ types, timestamp: Date.now() })}
+
+`);
+        const heartbeat = setInterval(() => {
+          safeEnqueue(`: ping ${Date.now()}
+
+`);
+        }, 15e3);
+        const cleanup = () => {
+          if (closed) return;
+          closed = true;
+          clearInterval(heartbeat);
+          listeners.delete(listener);
+          try {
+            controller.close();
+          } catch {
+          }
+        };
+        const signal = c.req?.raw?.signal;
+        if (signal) {
+          if (signal.aborted) cleanup();
+          else signal.addEventListener("abort", cleanup, { once: true });
+        }
+      }
+    });
+    return new Response(stream, {
+      status: 200,
+      headers: {
+        "Content-Type": "text/event-stream; charset=utf-8",
+        "Cache-Control": "no-cache, no-transform",
+        "Connection": "keep-alive",
+        "X-Accel-Buffering": "no"
+      }
+    });
+  });
+  app.post(routePath, async (c) => {
+    let body = {};
+    try {
+      const ct = c.req?.header?.("content-type") ?? "";
+      if (typeof c.req?.json === "function" && ct.includes("json")) {
+        body = await c.req.json();
+      }
+    } catch {
+    }
+    try {
+      if (onPostReload) await onPostReload(body);
+    } catch (e) {
+      return new Response(
+        JSON.stringify({ ok: false, error: e?.message ?? "reload handler failed" }),
+        { status: 500, headers: { "Content-Type": "application/json" } }
+      );
+    }
+    const reason = body.reason ?? "manual-trigger";
+    broadcast({
+      kind: "reload",
+      reason,
+      changed: body.changed,
+      timestamp: Date.now()
+    });
+    return new Response(
+      JSON.stringify({ ok: true, listeners: listeners.size, reason }),
+      { status: 200, headers: { "Content-Type": "application/json" } }
+    );
+  });
+  return {
+    broadcastReload(reason, changed) {
+      broadcast({ kind: "reload", reason, changed, timestamp: Date.now() });
+    },
+    setOnPostReload(fn) {
+      onPostReload = fn;
+    },
+    listenerCount: () => listeners.size
+  };
+}
+var init_hmr_routes = __esm({
+  "src/routes/hmr-routes.ts"() {
+    "use strict";
+  }
+});
+
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
@@ -451,7 +608,7 @@ var DatabaseLoader = class {
     this.tableName = options.tableName ?? "sys_metadata";
     this.historyTableName = options.historyTableName ?? "sys_metadata_history";
     this.organizationId = options.organizationId;
-    this.projectId = options.projectId;
+    void options.projectId;
     this.trackHistory = options.trackHistory !== false;
     const cacheOpts = options.cache;
     const cacheEnabled = cacheOpts?.enabled !== false;
@@ -541,6 +698,26 @@ var DatabaseLoader = class {
     }
     return this.driver.delete(table, id);
   }
+  /**
+   * Compute the next per-org `event_seq` for `sys_metadata_history`.
+   * Reads `MAX(event_seq) + 1` for the configured `organization_id`.
+   * Legacy path — not transactional, so concurrent writes can collide.
+   * The canonical (transactional) producer is `SysMetadataRepository`.
+   */
+  async nextEventSeq() {
+    const where = this.organizationId ? { organization_id: this.organizationId } : {};
+    try {
+      const rows = await this._find(this.historyTableName, { where });
+      let max = 0;
+      for (const row of rows) {
+        const v = typeof row.event_seq === "number" ? row.event_seq : 0;
+        if (v > max) max = v;
+      }
+      return max + 1;
+    } catch {
+      return 1;
+    }
+  }
   /**
    * Ensure the metadata table exists.
    * Uses IDataDriver.syncSchema with the SysMetadataObject definition
@@ -605,8 +782,9 @@ var DatabaseLoader = class {
   }
   /**
    * Build base filter conditions for queries.
-   * Filters by organizationId when configured; project_id when projectId is set,
-   * or null (platform-global) when not set.
+   * Filters by organizationId when configured. `projectId` is accepted
+   * for back-compat but no longer constrains the query — see
+   * ADR-0008 §0 (branch/project removal).
    */
   baseFilter(type, name) {
     const filter = { type };
@@ -616,7 +794,6 @@ var DatabaseLoader = class {
     if (this.organizationId) {
       filter.organization_id = this.organizationId;
     }
-    filter.project_id = this.projectId ?? null;
     return filter;
   }
   /**
@@ -642,6 +819,7 @@ var DatabaseLoader = class {
     }
     const historyId = generateId();
     const metadataJson = JSON.stringify(metadata);
+    const eventSeq = await this.nextEventSeq();
     const historyRecord = {
       id: historyId,
       metadataId,
@@ -655,12 +833,12 @@ var DatabaseLoader = class {
       changeNote,
       recordedBy,
       recordedAt: now,
-      ...this.organizationId ? { organizationId: this.organizationId } : {},
-      ...this.projectId !== void 0 ? { projectId: this.projectId } : {}
+      ...this.organizationId ? { organizationId: this.organizationId } : {}
     };
     try {
       await this._create(this.historyTableName, {
         id: historyRecord.id,
+        event_seq: eventSeq,
         metadata_id: historyRecord.metadataId,
         name: historyRecord.name,
         type: historyRecord.type,
@@ -672,8 +850,8 @@ var DatabaseLoader = class {
         change_note: historyRecord.changeNote,
         recorded_by: historyRecord.recordedBy,
         recorded_at: historyRecord.recordedAt,
-        ...this.organizationId ? { organization_id: this.organizationId } : {},
-        ...this.projectId !== void 0 ? { project_id: this.projectId } : {}
+        source: "database-loader",
+        ...this.organizationId ? { organization_id: this.organizationId } : {}
       });
     } catch (error) {
       console.error(`Failed to create history record for ${type}/${name}:`, error);
@@ -860,7 +1038,6 @@ var DatabaseLoader = class {
     if (this.organizationId) {
       filter.organization_id = this.organizationId;
     }
-    filter.project_id = this.projectId ?? null;
     const row = await this._findOne(this.historyTableName, {
       where: filter
     });
@@ -877,7 +1054,6 @@ var DatabaseLoader = class {
       previousChecksum: row.previous_checksum,
       changeNote: row.change_note,
       organizationId: row.organization_id,
-      projectId: row.project_id,
       recordedBy: row.recorded_by,
       recordedAt: row.recorded_at
     };
@@ -895,7 +1071,6 @@ var DatabaseLoader = class {
     await this.ensureHistorySchema();
     const filter = { type, name };
     if (this.organizationId) filter.organization_id = this.organizationId;
-    filter.project_id = this.projectId ?? null;
     const metadataRecord = await this._findOne(this.tableName, { where: filter });
     if (!metadataRecord) {
       return { records: [], total: 0, hasMore: false };
@@ -904,7 +1079,6 @@ var DatabaseLoader = class {
       metadata_id: metadataRecord.id
     };
     if (this.organizationId) historyFilter.organization_id = this.organizationId;
-    historyFilter.project_id = this.projectId ?? null;
     if (options?.operationType) historyFilter.operation_type = options.operationType;
     if (options?.since) historyFilter.recorded_at = { $gte: options.since };
     if (options?.until) {
@@ -943,7 +1117,6 @@ var DatabaseLoader = class {
         previousChecksum: row.previous_checksum,
         changeNote: row.change_note,
         organizationId: row.organization_id,
-        projectId: row.project_id,
         recordedBy: row.recorded_by,
         recordedAt: row.recorded_at
       };
@@ -1050,7 +1223,6 @@ var DatabaseLoader = class {
           version: 1,
           source: "database",
           ...this.organizationId ? { organization_id: this.organizationId } : {},
-          ...this.projectId !== void 0 ? { project_id: this.projectId } : { project_id: null },
           created_at: now,
           updated_at: now
         });
@@ -1123,6 +1295,7 @@ var _MetadataManager = class _MetadataManager {
     // Invalidated on every `register()` / `unregister()` to keep CRUD writes
     // visible to subsequent reads.
     this.listCache = /* @__PURE__ */ new Map();
+    this.repoWatchClosed = false;
     this.config = config;
     this.logger = (0, import_core.createLogger)({ level: "info", format: "pretty" });
     this.serializers = /* @__PURE__ */ new Map();
@@ -1818,6 +1991,21 @@ var _MetadataManager = class _MetadataManager {
       unsubscribe: () => this.removeWatchCallback(type, wrappedCallback)
     };
   }
+  /**
+   * Subscribe to raw metadata watch events for a given type.
+   *
+   * Unlike `watchService` (which maps to the IMetadataService contract and
+   * drops fields like `path`/`timestamp`), this returns the raw
+   * `MetadataWatchEvent` produced by the underlying watcher — useful for
+   * developer-facing tooling such as the HMR SSE endpoint that wants the
+   * source file path and original timestamp.
+   *
+   * @returns An unsubscribe function.
+   */
+  subscribe(type, callback) {
+    this.addWatchCallback(type, callback);
+    return () => this.removeWatchCallback(type, callback);
+  }
   // ==========================================
   // Import / Export
   // ==========================================
@@ -2115,6 +2303,110 @@ var _MetadataManager = class _MetadataManager {
    */
   async stopWatching() {
   }
+  // ─── ADR-0008 PR-6: Repository wiring ───────────────────────────────
+  /**
+   * Attach a {@link MetadataRepository} as a supplementary event source.
+   *
+   * The manager subscribes to `repo.watch({})` and re-emits each event
+   * through {@link notifyWatchers} as a legacy `MetadataWatchEvent`.
+   * Each event also invalidates the in-memory registry entry and the
+   * `list()` cache for the affected type so subsequent reads see fresh
+   * data.
+   *
+   * No write-through. `register()` / `unregister()` / `save()` are
+   * untouched in this PR (deferred to ADR-0008 M0 PR-10).
+   *
+   * Call {@link dispose} (or {@link stopRepositoryWatch}) to detach.
+   */
+  setRepository(repo) {
+    if (this.repository === repo) return;
+    if (this.repository) {
+      void this.stopRepositoryWatch();
+    }
+    this.repository = repo;
+    this.repoWatchClosed = false;
+    void this.startRepositoryWatch();
+  }
+  /** Return the attached repository, if any. */
+  getRepository() {
+    return this.repository;
+  }
+  /** Stop the active repo.watch() loop (best-effort). */
+  async stopRepositoryWatch() {
+    this.repoWatchClosed = true;
+    const iter = this.repoWatchIter;
+    this.repoWatchIter = void 0;
+    if (iter && typeof iter.return === "function") {
+      try {
+        await iter.return(void 0);
+      } catch {
+      }
+    }
+  }
+  /**
+   * Best-effort cleanup. Stops the FS watcher (if any), drains the
+   * repository watch loop, and clears registry caches. Safe to call
+   * multiple times.
+   */
+  async dispose() {
+    await this.stopWatching().catch(() => void 0);
+    await this.stopRepositoryWatch().catch(() => void 0);
+    this.listCache.clear();
+  }
+  async startRepositoryWatch() {
+    const repo = this.repository;
+    if (!repo) return;
+    const iterable = repo.watch({});
+    const iter = iterable[Symbol.asyncIterator]();
+    this.repoWatchIter = iter;
+    try {
+      while (!this.repoWatchClosed) {
+        const { value, done } = await iter.next();
+        if (done) break;
+        try {
+          this.applyRepoEvent(value);
+        } catch (err) {
+          this.logger.warn("[MetadataManager] repo event handler failed", {
+            error: err instanceof Error ? err.message : String(err)
+          });
+        }
+      }
+    } catch (err) {
+      if (!this.repoWatchClosed) {
+        this.logger.warn("[MetadataManager] repository watch loop exited unexpectedly", {
+          error: err instanceof Error ? err.message : String(err)
+        });
+      }
+    } finally {
+      if (this.repoWatchIter === iter) this.repoWatchIter = void 0;
+    }
+  }
+  /** Translate a repo event to the legacy MetadataWatchEvent + invalidate caches. */
+  applyRepoEvent(evt) {
+    const ref = evt.ref;
+    const type = ref.type;
+    const name = ref.name;
+    const typeStore = this.registry.get(type);
+    if (typeStore) {
+      typeStore.delete(name);
+      if (typeStore.size === 0) this.registry.delete(type);
+    }
+    this.listCache.delete(type);
+    const legacyType = evt.op === "create" ? "added" : evt.op === "delete" ? "deleted" : "changed";
+    const legacyEvent = {
+      type: legacyType,
+      metadataType: type,
+      name,
+      path: "",
+      // Repo events carry the hash only; the body is fetched on demand
+      // via manager.get(type, name). HMR consumers don't read `data` so
+      // this is fine for M0. (See ADR-0008 §12 open question 1.)
+      data: void 0,
+      timestamp: evt.ts
+    };
+    legacyEvent.seq = evt.seq;
+    this.notifyWatchers(type, legacyEvent);
+  }
   notifyWatchers(type, event) {
     const callbacks = this.watchCallbacks.get(type);
     if (!callbacks) return;
@@ -2590,7 +2882,13 @@ var NodeMetadataManager = class extends MetadataManager {
     this.watcher = (0, import_chokidar.watch)(rootDir, {
       ignored,
       persistent,
-      ignoreInitial: true
+      ignoreInitial: true,
+      // Use polling to avoid `fs.watch` EMFILE on macOS / busy dev hosts.
+      // Recursive watch over a project root would otherwise wire native
+      // watches across the entire tree, easily exhausting the FD pool.
+      usePolling: true,
+      interval: 1e3,
+      binaryInterval: 2e3
     });
     this.watcher.on("add", async (filePath) => {
       await this.handleFileEvent("added", filePath);
@@ -2725,6 +3023,7 @@ var queryableMetadataObjects = [
   import_metadata2.SysMetadataObject,
   import_metadata2.SysMetadataHistoryObject
 ];
+var REPO_SUBDIR = ".objectstack/metadata";
 var ARTIFACT_FIELD_TO_TYPE = {
   objects: "object",
   objectExtensions: "object_extension",
@@ -2822,6 +3121,31 @@ var MetadataPlugin = class {
           await this._loadFromFileSystem(ctx);
         }
       }
+      const bootstrapMode = this.options.config?.bootstrap ?? "eager";
+      if (bootstrapMode !== "artifact-only") {
+        try {
+          const path3 = await import("path");
+          const { FileSystemRepository } = await import("@objectstack/metadata-fs");
+          const rootDir = this.options.rootDir || process.cwd();
+          const repoRoot = path3.join(rootDir, REPO_SUBDIR);
+          const repo = new FileSystemRepository({
+            root: repoRoot,
+            org: this.options.organizationId ?? "system",
+            disableWatch: this.options.watch === false
+          });
+          await repo.start();
+          this.repository = repo;
+          this.manager.setRepository(repo);
+          ctx.logger.info("[MetadataPlugin] FileSystemRepository attached", {
+            repoRoot,
+            watch: this.options.watch !== false
+          });
+        } catch (e) {
+          ctx.logger.warn("[MetadataPlugin] Failed to attach FileSystemRepository", {
+            error: e?.message
+          });
+        }
+      }
       try {
         const realtimeService = ctx.getService("realtime");
         if (realtimeService && typeof realtimeService === "object" && "publish" in realtimeService) {
@@ -2833,6 +3157,102 @@ var MetadataPlugin = class {
           error: e.message
         });
       }
+      try {
+        const httpServer = ctx.getService("http-server") ?? ctx.getService("http.server");
+        if (httpServer && typeof httpServer.getRawApp === "function") {
+          const { registerMetadataHmrRoutes: registerMetadataHmrRoutes2 } = await Promise.resolve().then(() => (init_hmr_routes(), hmr_routes_exports));
+          const hub = registerMetadataHmrRoutes2(httpServer.getRawApp(), this.manager);
+          hub.setOnPostReload(async (body = {}) => {
+            const src3 = this.options.artifactSource;
+            if (src3?.mode === "local-file") {
+              try {
+                await this._loadFromLocalFile(ctx, src3.path, src3.fetchTimeoutMs);
+                ctx.logger.info("[MetadataPlugin] artifact reloaded via HMR POST", {
+                  path: src3.path,
+                  reason: body?.reason
+                });
+              } catch (e) {
+                ctx.logger.warn("[MetadataPlugin] artifact reload failed", { error: e?.message });
+                throw e;
+              }
+            }
+          });
+          const src2 = this.options.artifactSource;
+          const wantArtifactWatch = this.options.artifactWatch ?? src2?.mode === "local-file";
+          if (src2?.mode === "local-file" && wantArtifactWatch && !/^https?:\/\//i.test(src2.path)) {
+            try {
+              const { watch: chokidarWatch2 } = await import("chokidar");
+              const w = chokidarWatch2(src2.path, {
+                ignoreInitial: true,
+                awaitWriteFinish: { stabilityThreshold: 50, pollInterval: 20 },
+                persistent: true,
+                // Use polling to avoid `fs.watch` exhausting the
+                // process file-descriptor limit on macOS (chokidar
+                // recursively wires watches on the parent
+                // directory tree which can trip EMFILE on busy
+                // dev hosts). 500ms polling is fast enough for
+                // HMR (a recompile takes ~400ms anyway).
+                usePolling: true,
+                interval: 500,
+                binaryInterval: 1e3
+              });
+              let pending = false;
+              const reload = async () => {
+                if (pending) return;
+                pending = true;
+                try {
+                  await this._loadFromLocalFile(ctx, src2.path, src2.fetchTimeoutMs);
+                  hub.broadcastReload("artifact-file-changed", [src2.path]);
+                  ctx.logger.info("[MetadataPlugin] artifact auto-reloaded (file watcher)", {
+                    path: src2.path
+                  });
+                } catch (e) {
+                  ctx.logger.warn("[MetadataPlugin] artifact auto-reload failed", { error: e?.message });
+                } finally {
+                  pending = false;
+                }
+              };
+              w.on("change", () => {
+                void reload();
+              });
+              w.on("add", () => {
+                void reload();
+              });
+              this.artifactWatcher = { close: () => w.close() };
+              console.log("[MetadataPlugin] artifact file watcher attached", src2.path);
+            } catch (e) {
+              ctx.logger.warn("[MetadataPlugin] artifact watcher failed to start", { error: e?.message });
+            }
+          }
+          console.log("[MetadataPlugin] HMR endpoint registered at /api/v1/dev/metadata-events");
+        } else {
+          console.log("[MetadataPlugin] HTTP server with getRawApp() not available \u2014 skipping HMR endpoint");
+        }
+      } catch (e) {
+        console.warn("[MetadataPlugin] Failed to register HMR endpoint", e?.message);
+      }
+    };
+    this.stop = async (ctx) => {
+      if (this.artifactWatcher) {
+        try {
+          await this.artifactWatcher.close();
+        } catch {
+        }
+        this.artifactWatcher = void 0;
+      }
+      try {
+        await this.manager.dispose();
+      } catch (e) {
+        ctx.logger.warn("[MetadataPlugin] manager.dispose() failed", { error: e?.message });
+      }
+      const repo = this.repository;
+      if (repo && typeof repo.close === "function") {
+        try {
+          await repo.close();
+        } catch {
+        }
+      }
+      this.repository = void 0;
     };
     this.options = {
       watch: true,
@@ -2910,7 +3330,12 @@ var MetadataPlugin = class {
       const items = metadata[field];
       if (!Array.isArray(items) || items.length === 0) continue;
       for (const item of items) {
-        const name = item?.name;
+        let name = item?.name;
+        if (!name) {
+          if (metaType === "view") {
+            name = item?.list?.data?.object ?? item?.form?.data?.object;
+          }
+        }
         if (!name) continue;
         if (manifestPackageId && item._packageId === void 0) {
           item._packageId = manifestPackageId;
@@ -3254,7 +3679,6 @@ var HistoryCleanupManager = class {
     const driver = this.dbLoader.driver;
     const historyTableName = this.dbLoader.historyTableName;
     const organizationId = this.dbLoader.organizationId;
-    const projectId = this.dbLoader.projectId;
     let deleted = 0;
     let errors = 0;
     try {
@@ -3268,9 +3692,6 @@ var HistoryCleanupManager = class {
         if (organizationId) {
           filter.organization_id = organizationId;
         }
-        if (projectId !== void 0) {
-          filter.project_id = projectId;
-        }
         try {
           const result = await this.bulkDeleteByFilter(driver, historyTableName, filter);
           deleted += result.deleted;
@@ -3283,7 +3704,6 @@ var HistoryCleanupManager = class {
         try {
           const baseWhere = {};
           if (organizationId) baseWhere.organization_id = organizationId;
-          if (projectId !== void 0) baseWhere.project_id = projectId;
           const metadataIds = await driver.find(historyTableName, {
             object: historyTableName,
             where: baseWhere,
@@ -3371,13 +3791,11 @@ var HistoryCleanupManager = class {
     const driver = this.dbLoader.driver;
     const historyTableName = this.dbLoader.historyTableName;
     const organizationId = this.dbLoader.organizationId;
-    const projectId = this.dbLoader.projectId;
     let recordsByAge = 0;
     let recordsByCount = 0;
     try {
       const baseWhere = {};
       if (organizationId) baseWhere.organization_id = organizationId;
-      if (projectId !== void 0) baseWhere.project_id = projectId;
       if (this.policy.maxAgeDays) {
         const cutoffDate = /* @__PURE__ */ new Date();
         cutoffDate.setDate(cutoffDate.getDate() - this.policy.maxAgeDays);