@objectstack/metadata 17.0.0-rc.0 → 17.0.0-rc.1

package/dist/index.cjs

@@ -383,6 +383,8 @@ export default metadata;
 
 // src/loaders/database-loader.ts
 var import_metadata_core = require("@objectstack/metadata-core");
+var import_spec = require("@objectstack/spec");
+var import_shared = require("@objectstack/spec/shared");
 
 // src/utils/metadata-history-utils.ts
 async function calculateChecksum(metadata) {
@@ -658,6 +660,12 @@ var DatabaseLoader = class {
     };
     this.schemaReady = false;
     this.historySchemaReady = false;
+    /**
+     * Once-per-process dedupe for stored-row conversion notices — `load` /
+     * `loadMany` are hot read paths (cached, but re-hit on every TTL expiry),
+     * so a legacy row must warn once, not once per cache miss.
+     */
+    this.storedConversionWarned = /* @__PURE__ */ new Set();
     if (!options.driver && !options.engine) {
       throw new Error("DatabaseLoader requires either a driver or engine");
     }
@@ -918,13 +926,33 @@ var DatabaseLoader = class {
     }
   }
   /**
-   * Convert a database row to a metadata payload.
-   * Parses the JSON `metadata` column back into an object.
+   * Convert a LIVE database row to a metadata payload.
+   *
+   * Parses the JSON `metadata` column back into an object, then replays the
+   * full ADR-0087 conversion chain over it (#3903): rows written under a past
+   * protocol are served canonical, exactly like the metadata-protocol's
+   * `sys_metadata` seams. History rows do NOT pass through here — history
+   * readers parse inline and stay verbatim, as a record of what was written.
+   *
+   * `flow` is skipped for the same reason the protocol skips it: flow-node
+   * conversions need the automation engine's live executor registry for their
+   * open-namespace conflict guard; flows canonicalize at `registerFlow`.
    */
   rowToData(row) {
     if (!row || !row.metadata) return null;
     const payload = typeof row.metadata === "string" ? JSON.parse(row.metadata) : row.metadata;
-    return payload;
+    const singular = import_shared.PLURAL_TO_SINGULAR[row.type] ?? row.type;
+    if (singular === "flow") return payload;
+    return (0, import_spec.applyConversionsToStoredItem)(singular, payload, {
+      onNotice: (n) => {
+        const key = `${n.conversionId}|${singular}|${String(row.name ?? "")}`;
+        if (this.storedConversionWarned.has(key)) return;
+        this.storedConversionWarned.add(key);
+        console.warn(
+          `[DatabaseLoader] stored ${singular}/${String(row.name ?? "<unnamed>")} carries a pre-protocol shape; ${n.message}`
+        );
+      }
+    });
   }
   /**
    * Convert a database row to a MetadataRecord-like object.
@@ -2339,19 +2367,44 @@ var _MetadataManager = class _MetadataManager {
   /**
    * Load a single metadata item from loaders.
    * Iterates through registered loaders until found.
+   *
+   * Returns `null` both when no loader HAS the item and when every loader
+   * FAILED — see {@link loadDiagnosed} when the caller must tell those apart.
    */
   async load(type, name, options) {
+    return (await this.loadDiagnosed(type, name, options)).data;
+  }
+  /**
+   * `load`, plus whether the answer can be trusted as complete.
+   *
+   * [ADR-0110 D3] A miss and an outage are different facts with opposite
+   * security meanings, and plain `load` cannot express the difference: a
+   * loader that throws is warn-logged and skipped, so a database the metadata
+   * plane cannot reach returns the same `null` as a name that was never
+   * declared. Callers that gate on a declaration MUST NOT read that `null` as
+   * "the author declared no gate" — an availability failure would silently
+   * widen access (the REST `/actions` route's fail-open branch, #3935).
+   *
+   * `degraded` is true when at least one loader threw AND no loader answered
+   * with the item. The posture is deliberately conservative: with a loader
+   * down we cannot prove the item is absent, so we decline to claim it is.
+   * A clean miss (every loader answered, none had it) is NOT degraded.
+   */
+  async loadDiagnosed(type, name, options) {
+    const errors = [];
     for (const loader of this.loaders.values()) {
       try {
         const result = await loader.load(type, name, options);
         if (result.data) {
-          return result.data;
+          return { data: result.data, degraded: false, errors };
         }
       } catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        errors.push(`${loader.contract.name}: ${message}`);
         this.logger.warn(`Loader ${loader.contract.name} failed to load ${type}:${name}`, { error: e });
       }
     }
-    return null;
+    return { data: null, degraded: errors.length > 0, errors };
   }
   /**
    * Load multiple metadata items from loaders.
@@ -3238,10 +3291,10 @@ var MemoryLoader = class {
 
 // src/plugin.ts
 var import_kernel2 = require("@objectstack/spec/kernel");
-var import_shared = require("@objectstack/spec/shared");
+var import_shared2 = require("@objectstack/spec/shared");
 var import_metadata_core2 = require("@objectstack/metadata-core");
-var import_spec = require("@objectstack/spec");
 var import_spec2 = require("@objectstack/spec");
+var import_spec3 = require("@objectstack/spec");
 var queryableMetadataObjects = [
   import_metadata_core2.SysMetadataObject,
   import_metadata_core2.SysMetadataHistoryObject,
@@ -3293,6 +3346,12 @@ var MetadataPlugin = class {
     this.name = "com.objectstack.metadata";
     this.type = "standard";
     this.version = "1.0.0";
+    /**
+     * Services init() UNCONDITIONALLY registers (ADR-0116, #4131) — lets the
+     * kernel name this plugin when a consumer requires `metadata` before it
+     * initializes.
+     */
+    this.providesServices = ["metadata"];
     this.init = async (ctx) => {
       ctx.logger.info("Initializing Metadata Manager", {
         root: this.options.rootDir || process.cwd(),
@@ -3332,27 +3391,27 @@ var MetadataPlugin = class {
         bootstrap: mode,
         artifactSource: src?.mode ?? "none"
       });
+      if (src && src.mode !== "local-file") {
+        const bad = src.mode;
+        throw new Error(
+          `[MetadataPlugin] artifactSource.mode '${bad}' is not supported` + (bad === "artifact-api" ? " \u2014 the 'artifact-api' source was removed (#4246). Load the same artifact with { mode: 'local-file', path: '<http(s) URL>' } (e.g. the control plane's /pub/v1/environments/:id/artifact route), or install packages into a running runtime via @objectstack/cloud-connection." : ". The only artifact source is { mode: 'local-file', path }.")
+        );
+      }
       if (mode === "artifact-only") {
-        if (src?.mode === "local-file") {
+        if (src) {
           await this._loadFromLocalFile(ctx, src.path, src.fetchTimeoutMs);
-        } else if (src?.mode === "artifact-api") {
-          await this._loadFromArtifactApi(ctx, src);
         } else {
           throw new Error("[MetadataPlugin] bootstrap=artifact-only requires options.artifactSource to be set");
         }
       } else if (mode === "lazy") {
-        if (src?.mode === "local-file") {
-          await this._loadFromLocalFile(ctx, src.path, src.fetchTimeoutMs);
-        } else if (src?.mode === "artifact-api") {
-          await this._loadFromArtifactApi(ctx, src);
+        if (src) {
+          await this._loadFromLocalFile(ctx, src.path, src.fetchTimeoutMs, { optional: true });
         } else {
           ctx.logger.info("[MetadataPlugin] lazy bootstrap \u2014 skipping filesystem priming; metadata loads on demand");
         }
       } else {
-        if (src?.mode === "local-file") {
-          await this._loadFromLocalFile(ctx, src.path, src.fetchTimeoutMs);
-        } else if (src?.mode === "artifact-api") {
-          await this._loadFromArtifactApi(ctx, src);
+        if (src) {
+          await this._loadFromLocalFile(ctx, src.path, src.fetchTimeoutMs, { optional: true });
         } else {
           await this._loadFromFileSystem(ctx);
         }
@@ -3394,7 +3453,14 @@ var MetadataPlugin = class {
         });
       }
       try {
-        const httpServer = ctx.getService("http-server") ?? ctx.getService("http.server");
+        const readServer = (name) => {
+          try {
+            return ctx.getService(name);
+          } catch {
+            return void 0;
+          }
+        };
+        const httpServer = readServer("http.server") ?? readServer("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);
@@ -3507,14 +3573,13 @@ var MetadataPlugin = class {
   /**
    * Fetch JSON content from a URL with configurable timeout.
    */
-  async _fetchJson(url, fetchTimeoutMs, token) {
+  async _fetchJson(url, fetchTimeoutMs) {
     const envTimeout = Number(process.env.OS_ARTIFACT_FETCH_TIMEOUT_MS);
     const timeoutMs = fetchTimeoutMs ?? (Number.isFinite(envTimeout) && envTimeout > 0 ? envTimeout : void 0) ?? 6e4;
     const controller = new AbortController();
     const timer = timeoutMs > 0 ? setTimeout(() => controller.abort(), timeoutMs) : void 0;
     try {
       const headers = { Accept: "application/json, */*;q=0.5" };
-      if (token) headers.Authorization = `Bearer ${token}`;
       const res = await fetch(url, { redirect: "follow", signal: controller.signal, headers });
       if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`);
       const content = await res.text();
@@ -3576,21 +3641,21 @@ var MetadataPlugin = class {
       const items = metadata[field];
       if (!Array.isArray(items) || items.length === 0) continue;
       for (const item of items) {
-        if (metaType === "view" && (0, import_spec2.isAggregatedViewContainer)(item)) {
+        if (metaType === "view" && (0, import_spec3.isAggregatedViewContainer)(item)) {
           const viewObject = item?.list?.data?.object ?? item?.form?.data?.object;
           if (!viewObject) continue;
-          (0, import_shared.applyProtection)(item, {
+          (0, import_shared2.applyProtection)(item, {
             packageId: manifestPackageId,
             packageVersion: manifestVersion
           });
           await memLoader.save("view", viewObject, item);
           await this.manager.register("view", viewObject, item, { notify: false });
           totalRegistered++;
-          for (const vi of (0, import_spec2.expandViewContainer)(viewObject, item)) {
+          for (const vi of (0, import_spec3.expandViewContainer)(viewObject, item)) {
             for (const w of vi._diagnostics?.warnings ?? []) {
               ctx.logger.warn(`[MetadataPlugin] View expansion warning for '${vi.name}': ${w.message}`);
             }
-            (0, import_shared.applyProtection)(vi, {
+            (0, import_shared2.applyProtection)(vi, {
               packageId: manifestPackageId,
               packageVersion: manifestVersion
             });
@@ -3607,7 +3672,7 @@ var MetadataPlugin = class {
           }
         }
         if (!name) continue;
-        (0, import_shared.applyProtection)(item, {
+        (0, import_shared2.applyProtection)(item, {
           packageId: manifestPackageId,
           packageVersion: manifestVersion
         });
@@ -3634,14 +3699,26 @@ var MetadataPlugin = class {
    * logged but never blocks the reload.
    */
   async _reloadAndAnnounce(ctx, src, changed) {
-    await this._loadFromLocalFile(ctx, src.path, src.fetchTimeoutMs);
+    await this._loadFromLocalFile(ctx, src.path, src.fetchTimeoutMs, { optional: true });
     try {
       await ctx.trigger("metadata:reloaded", { changed, metadata: this.lastParsedMetadata });
     } catch (e) {
       ctx.logger.warn("[MetadataPlugin] metadata:reloaded subscriber failed", { error: e?.message });
     }
   }
-  async _loadFromLocalFile(ctx, filePath, fetchTimeoutMs) {
+  /**
+   * @param opts.optional When true, a LOCAL artifact file that does not exist
+   *   is "nothing compiled yet" rather than a fault: log and return, leaving
+   *   the manager empty and the artifact watcher armed so the first
+   *   `os compile` hydrates the running server (#4085). Callers pass it for
+   *   the `eager` / `lazy` bootstrap modes — the development-platform paths,
+   *   where an app is optional. `artifact-only` (sealed runtime) does NOT:
+   *   there the artifact IS the deployment, so its absence must fail loudly
+   *   instead of silently serving an empty runtime. Only ENOENT is tolerated;
+   *   a present-but-unreadable artifact (malformed JSON, bad permissions) and
+   *   every remote-URL failure stay fatal.
+   */
+  async _loadFromLocalFile(ctx, filePath, fetchTimeoutMs, opts = {}) {
     const isUrl = /^https?:\/\//i.test(filePath);
     ctx.logger.info(
       `[MetadataPlugin] Loading metadata from ${isUrl ? "remote URL" : "local artifact file"}`,
@@ -3656,34 +3733,17 @@ var MetadataPlugin = class {
         raw = JSON.parse(content);
       }
     } catch (e) {
+      if (opts.optional && !isUrl && e?.code === "ENOENT") {
+        ctx.logger.info(
+          "[MetadataPlugin] no compiled artifact yet \u2014 starting with no artifact metadata",
+          { path: filePath }
+        );
+        return;
+      }
       throw new Error(`[MetadataPlugin] Cannot read artifact ${isUrl ? "URL" : "file"} at "${filePath}": ${e.message}`);
     }
     await this._parseAndRegisterArtifact(ctx, raw, filePath);
   }
-  /**
-   * P2: Load metadata from the cloud artifact API endpoint.
-   */
-  async _loadFromArtifactApi(ctx, src) {
-    const environmentId = this.options.environmentId;
-    if (!environmentId) {
-      throw new Error("[MetadataPlugin] artifact-api source requires options.environmentId to be set");
-    }
-    let artifactUrl = src.url.replace(/\/+$/, "");
-    if (!/\/api\/v\d+\/cloud\/projects\//i.test(artifactUrl)) {
-      artifactUrl = `${artifactUrl}/api/v1/cloud/environments/${environmentId}/artifact`;
-    }
-    if (src.commitId) {
-      artifactUrl += `${artifactUrl.includes("?") ? "&" : "?"}commit=${encodeURIComponent(src.commitId)}`;
-    }
-    ctx.logger.info("[MetadataPlugin] Loading metadata from artifact API", { url: artifactUrl });
-    let raw;
-    try {
-      raw = await this._fetchJson(artifactUrl, src.fetchTimeoutMs, src.token);
-    } catch (e) {
-      throw new Error(`[MetadataPlugin] Cannot load artifact from API "${artifactUrl}": ${e.message}`);
-    }
-    await this._parseAndRegisterArtifact(ctx, raw, artifactUrl);
-  }
   async _loadFromFileSystem(ctx) {
     ctx.logger.info("Loading metadata from file system...");
     const sortedTypes = [...import_kernel2.DEFAULT_METADATA_TYPE_REGISTRY].sort((a, b) => a.loadOrder - b.loadOrder);
@@ -3698,7 +3758,7 @@ var MetadataPlugin = class {
           for (const item of items) {
             const meta = item;
             if (meta?.name) {
-              (0, import_shared.applyProtection)(meta, {
+              (0, import_shared2.applyProtection)(meta, {
                 packageId: this.options.packageId
               });
               await this.manager.register(entry.type, meta.name, item, { notify: false });