@objectstack/metadata 5.2.0 → 6.0.0

package/dist/index.d.cts

@@ -179,9 +179,9 @@ declare class MetadataManager implements IMetadataService {
      *
      * @param driver - An IDataDriver instance for database operations
      * @param organizationId - Organization ID for multi-tenant isolation
-     * @param projectId - Project ID (undefined = platform-global)
+     * @param environmentId - Project ID (undefined = platform-global)
      */
-    setDatabaseDriver(driver: IDataDriver, organizationId?: string, projectId?: string): void;
+    setDatabaseDriver(driver: IDataDriver, organizationId?: string, environmentId?: string): void;
     /**
      * Configure and register a DatabaseLoader backed by an IDataEngine (ObjectQL).
      * The engine handles datasource routing automatically — sys_metadata will
@@ -190,9 +190,9 @@ declare class MetadataManager implements IMetadataService {
      *
      * @param engine - An IDataEngine instance (typically the ObjectQL service)
      * @param organizationId - Organization ID for multi-tenant isolation
-     * @param projectId - Project ID (undefined = platform-global)
+     * @param environmentId - Project ID (undefined = platform-global)
      */
-    setDataEngine(engine: IDataEngine, organizationId?: string, projectId?: string): void;
+    setDataEngine(engine: IDataEngine, organizationId?: string, environmentId?: string): void;
     /**
      * Set the realtime service for publishing metadata change events.
      * Should be called after kernel resolves the realtime service.
@@ -511,7 +511,7 @@ interface MetadataPluginOptions {
     /** Organization ID for metadata-scoped consumers; MetadataPlugin itself does not persist runtime metadata. */
     organizationId?: string;
     /** Project ID used by local artifact envelopes and metadata-scoped consumers. */
-    projectId?: string;
+    environmentId?: string;
     /**
      * When set, MetadataPlugin loads metadata from an artifact instead of scanning
      * the filesystem. Only `local-file` is implemented now; `artifact-api` is
@@ -712,10 +712,10 @@ interface DatabaseLoaderOptions {
      * @deprecated since ADR-0008 §0 amendment (branch/project removal).
      * The metadata layer is keyed by organization only. This option is
      * accepted for back-compat but ignored — writes do not set
-     * `project_id` and filters do not constrain on it. Will be removed
+     * `environment_id` and filters do not constrain on it. Will be removed
      * in the next major release.
      */
-    projectId?: string;
+    environmentId?: string;
     /** Enable history tracking (default: true) */
     trackHistory?: boolean;
     /**
@@ -794,7 +794,7 @@ declare class DatabaseLoader implements MetadataLoader {
     private ensureHistorySchema;
     /**
      * Build base filter conditions for queries.
-     * Filters by organizationId when configured. `projectId` is accepted
+     * Filters by organizationId when configured. `environmentId` is accepted
      * for back-compat but no longer constrains the query — see
      * ADR-0008 §0 (branch/project removal).
      */

package/dist/index.d.ts

@@ -179,9 +179,9 @@ declare class MetadataManager implements IMetadataService {
      *
      * @param driver - An IDataDriver instance for database operations
      * @param organizationId - Organization ID for multi-tenant isolation
-     * @param projectId - Project ID (undefined = platform-global)
+     * @param environmentId - Project ID (undefined = platform-global)
      */
-    setDatabaseDriver(driver: IDataDriver, organizationId?: string, projectId?: string): void;
+    setDatabaseDriver(driver: IDataDriver, organizationId?: string, environmentId?: string): void;
     /**
      * Configure and register a DatabaseLoader backed by an IDataEngine (ObjectQL).
      * The engine handles datasource routing automatically — sys_metadata will
@@ -190,9 +190,9 @@ declare class MetadataManager implements IMetadataService {
      *
      * @param engine - An IDataEngine instance (typically the ObjectQL service)
      * @param organizationId - Organization ID for multi-tenant isolation
-     * @param projectId - Project ID (undefined = platform-global)
+     * @param environmentId - Project ID (undefined = platform-global)
      */
-    setDataEngine(engine: IDataEngine, organizationId?: string, projectId?: string): void;
+    setDataEngine(engine: IDataEngine, organizationId?: string, environmentId?: string): void;
     /**
      * Set the realtime service for publishing metadata change events.
      * Should be called after kernel resolves the realtime service.
@@ -511,7 +511,7 @@ interface MetadataPluginOptions {
     /** Organization ID for metadata-scoped consumers; MetadataPlugin itself does not persist runtime metadata. */
     organizationId?: string;
     /** Project ID used by local artifact envelopes and metadata-scoped consumers. */
-    projectId?: string;
+    environmentId?: string;
     /**
      * When set, MetadataPlugin loads metadata from an artifact instead of scanning
      * the filesystem. Only `local-file` is implemented now; `artifact-api` is
@@ -712,10 +712,10 @@ interface DatabaseLoaderOptions {
      * @deprecated since ADR-0008 §0 amendment (branch/project removal).
      * The metadata layer is keyed by organization only. This option is
      * accepted for back-compat but ignored — writes do not set
-     * `project_id` and filters do not constrain on it. Will be removed
+     * `environment_id` and filters do not constrain on it. Will be removed
      * in the next major release.
      */
-    projectId?: string;
+    environmentId?: string;
     /** Enable history tracking (default: true) */
     trackHistory?: boolean;
     /**
@@ -794,7 +794,7 @@ declare class DatabaseLoader implements MetadataLoader {
     private ensureHistorySchema;
     /**
      * Build base filter conditions for queries.
-     * Filters by organizationId when configured. `projectId` is accepted
+     * Filters by organizationId when configured. `environmentId` is accepted
      * for back-compat but no longer constrains the query — see
      * ADR-0008 §0 (branch/project removal).
      */

package/dist/index.js

@@ -502,7 +502,7 @@ var LRUCache = class {
 // src/migrations/add-sys-metadata-overlay-index.ts
 var INDEX_NAME = "idx_sys_metadata_overlay_active";
 var TABLE = "sys_metadata";
-var COLUMNS = "(type, name, organization_id, project_id, scope)";
+var COLUMNS = "(type, name, organization_id, environment_id, scope)";
 var WHERE = "state = 'active'";
 async function addSysMetadataOverlayIndex(driver) {
   const driverAny = driver;
@@ -541,6 +541,59 @@ async function addSysMetadataOverlayIndex(driver) {
   }
 }
 
+// src/migrations/migrate-project-id-to-environment-id.ts
+var AFFECTED_TABLES = [
+  "sys_metadata",
+  "sys_metadata_history"
+];
+async function migrateProjectIdToEnvironmentId(driver) {
+  const driverAny = driver;
+  if (typeof driverAny.raw !== "function") {
+    throw new Error(
+      "migrateProjectIdToEnvironmentId: driver must expose a .raw(sql, bindings?) method. SqlDriver (better-sqlite3/knex) and TursoDriver both support this."
+    );
+  }
+  const results = [];
+  for (const table of AFFECTED_TABLES) {
+    try {
+      const hasColumn = await _columnExists(driverAny, table, "project_id");
+      const alreadyMigrated = await _columnExists(driverAny, table, "environment_id");
+      if (alreadyMigrated && !hasColumn) {
+        results.push({ table, status: "already_done" });
+        continue;
+      }
+      if (!hasColumn) {
+        results.push({ table, status: "table_missing" });
+        continue;
+      }
+      await driverAny.raw(
+        `ALTER TABLE "${table}" RENAME COLUMN project_id TO environment_id`
+      );
+      results.push({ table, status: "renamed" });
+    } catch (err) {
+      results.push({ table, status: "error", error: err?.message ?? String(err) });
+    }
+  }
+  return results;
+}
+async function _columnExists(driver, table, column) {
+  try {
+    const rows = await driver.raw(`PRAGMA table_info("${table}")`);
+    if (Array.isArray(rows) && rows.length > 0) {
+      const list2 = Array.isArray(rows[0]) ? rows[0] : rows;
+      return list2.some((r) => r?.name === column);
+    }
+    const result = await driver.raw(
+      `SELECT column_name FROM information_schema.columns WHERE table_name = ? AND column_name = ?`,
+      [table, column]
+    );
+    const list = Array.isArray(result[0]) ? result[0] : result;
+    return list.length > 0;
+  } catch {
+    return false;
+  }
+}
+
 // src/loaders/database-loader.ts
 var DatabaseLoader = class {
   constructor(options) {
@@ -564,7 +617,7 @@ var DatabaseLoader = class {
     this.tableName = options.tableName ?? "sys_metadata";
     this.historyTableName = options.historyTableName ?? "sys_metadata_history";
     this.organizationId = options.organizationId;
-    void options.projectId;
+    void options.environmentId;
     this.trackHistory = options.trackHistory !== false;
     const cacheOpts = options.cache;
     const cacheEnabled = cacheOpts?.enabled !== false;
@@ -696,6 +749,7 @@ var DatabaseLoader = class {
           }
         }
         if (driver) {
+          await migrateProjectIdToEnvironmentId(driver).catch(() => void 0);
           await addSysMetadataOverlayIndex(driver);
         }
       } catch {
@@ -708,6 +762,10 @@ var DatabaseLoader = class {
         name: this.tableName
       });
       this.schemaReady = true;
+      try {
+        await migrateProjectIdToEnvironmentId(this.driver);
+      } catch {
+      }
       try {
         await addSysMetadataOverlayIndex(this.driver);
       } catch {
@@ -738,7 +796,7 @@ var DatabaseLoader = class {
   }
   /**
    * Build base filter conditions for queries.
-   * Filters by organizationId when configured. `projectId` is accepted
+   * Filters by organizationId when configured. `environmentId` is accepted
    * for back-compat but no longer constrains the query — see
    * ADR-0008 §0 (branch/project removal).
    */
@@ -837,7 +895,7 @@ var DatabaseLoader = class {
       owner: row.owner,
       state: row.state ?? "active",
       organizationId: row.organization_id,
-      projectId: row.project_id,
+      environmentId: row.environment_id,
       version: row.version ?? 1,
       checksum: row.checksum,
       source: row.source,
@@ -1271,13 +1329,13 @@ var _MetadataManager = class _MetadataManager {
    *
    * @param driver - An IDataDriver instance for database operations
    * @param organizationId - Organization ID for multi-tenant isolation
-   * @param projectId - Project ID (undefined = platform-global)
+   * @param environmentId - Project ID (undefined = platform-global)
    */
-  setDatabaseDriver(driver, organizationId, projectId) {
-    if (projectId !== void 0) {
+  setDatabaseDriver(driver, organizationId, environmentId) {
+    if (environmentId !== void 0) {
       this.logger.info("Project kernel \u2014 skipping DatabaseLoader for sys_metadata (control-plane only)", {
         organizationId,
-        projectId
+        environmentId
       });
       return;
     }
@@ -1286,7 +1344,7 @@ var _MetadataManager = class _MetadataManager {
       driver,
       tableName,
       organizationId,
-      projectId,
+      environmentId,
       cache: this.config.cache?.databaseLoader
     });
     this.registerLoader(dbLoader);
@@ -1300,13 +1358,13 @@ var _MetadataManager = class _MetadataManager {
    *
    * @param engine - An IDataEngine instance (typically the ObjectQL service)
    * @param organizationId - Organization ID for multi-tenant isolation
-   * @param projectId - Project ID (undefined = platform-global)
+   * @param environmentId - Project ID (undefined = platform-global)
    */
-  setDataEngine(engine, organizationId, projectId) {
-    if (projectId !== void 0) {
+  setDataEngine(engine, organizationId, environmentId) {
+    if (environmentId !== void 0) {
       this.logger.info("Project kernel \u2014 skipping DatabaseLoader for sys_metadata (control-plane only)", {
         organizationId,
-        projectId
+        environmentId
       });
       return;
     }
@@ -1315,7 +1373,7 @@ var _MetadataManager = class _MetadataManager {
       engine,
       tableName,
       organizationId,
-      projectId,
+      environmentId,
       cache: this.config.cache?.databaseLoader
     });
     this.registerLoader(dbLoader);
@@ -3317,24 +3375,24 @@ var MetadataPlugin = class {
    * metadata items into the MetadataManager.
    */
   async _parseAndRegisterArtifact(ctx, raw, label) {
-    const { ProjectArtifactSchema } = await import("@objectstack/spec/cloud");
+    const { EnvironmentArtifactSchema } = await import("@objectstack/spec/cloud");
     const { ObjectStackDefinitionSchema } = await import("@objectstack/spec");
     let metadata;
     const obj = raw;
     if (obj?.schemaVersion && obj?.commitId && obj?.metadata !== void 0) {
-      const artifact = ProjectArtifactSchema.parse(obj);
+      const artifact = EnvironmentArtifactSchema.parse(obj);
       metadata = artifact.metadata;
     } else if (obj?.success && obj?.data?.metadata) {
-      const artifact = ProjectArtifactSchema.parse(obj.data);
+      const artifact = EnvironmentArtifactSchema.parse(obj.data);
       metadata = artifact.metadata;
     } else {
       const def = ObjectStackDefinitionSchema.parse(obj);
       const canonical = JSON.stringify(def, Object.keys(def).sort());
       const checksum = createHash2("sha256").update(canonical).digest("hex");
-      const projectId = this.options.projectId ?? "proj_local";
-      ProjectArtifactSchema.parse({
+      const environmentId = this.options.environmentId ?? "proj_local";
+      EnvironmentArtifactSchema.parse({
         schemaVersion: "0.1",
-        projectId,
+        environmentId,
         commitId: "local-dev",
         checksum,
         metadata: def
@@ -3390,13 +3448,13 @@ var MetadataPlugin = class {
    * P2: Load metadata from the cloud artifact API endpoint.
    */
   async _loadFromArtifactApi(ctx, src) {
-    const projectId = this.options.projectId;
-    if (!projectId) {
-      throw new Error("[MetadataPlugin] artifact-api source requires options.projectId to be set");
+    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/projects/${projectId}/artifact`;
+      artifactUrl = `${artifactUrl}/api/v1/cloud/environments/${environmentId}/artifact`;
     }
     if (src.commitId) {
       artifactUrl += `${artifactUrl.includes("?") ? "&" : "?"}commit=${encodeURIComponent(src.commitId)}`;