@objectstack/service-datasource 7.6.0

package/dist/index.js

@@ -0,0 +1,995 @@
+// src/external-datasource-service.ts
+import {
+  suggestFieldType,
+  isCompatible,
+  ExternalCatalogSchema
+} from "@objectstack/spec/data";
+var BUILTIN_COLUMNS = /* @__PURE__ */ new Set(["id", "created_at", "updated_at"]);
+function parseQualified(raw) {
+  const idx = raw.indexOf(".");
+  if (idx === -1) return { name: raw };
+  return { schema: raw.slice(0, idx), name: raw.slice(idx + 1) };
+}
+function toObjectName(remoteName) {
+  const { name } = parseQualified(remoteName);
+  return name.replace(/[^a-zA-Z0-9_]/g, "_").replace(/^[^a-z_]/, (c) => `_${c.toLowerCase()}`).toLowerCase();
+}
+function toLabel(name) {
+  return name.split("_").filter(Boolean).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}
+var ExternalDatasourceService = class {
+  constructor(config) {
+    this.config = config;
+  }
+  get logger() {
+    return this.config.logger;
+  }
+  findTable(schema, remoteName) {
+    const want = parseQualified(remoteName).name;
+    for (const table of Object.values(schema.tables)) {
+      if (table.name === remoteName) return table;
+      if (parseQualified(table.name).name === want) return table;
+    }
+    return void 0;
+  }
+  async listRemoteTables(datasource, opts) {
+    const [schema, ds] = await Promise.all([
+      this.config.introspect(datasource),
+      this.config.getDatasource(datasource)
+    ]);
+    const allowed = ds?.external?.allowedSchemas;
+    const tables = [];
+    for (const table of Object.values(schema.tables)) {
+      const { schema: tableSchema, name } = parseQualified(table.name);
+      if (opts?.schema && tableSchema && tableSchema !== opts.schema) continue;
+      if (allowed && tableSchema && !allowed.includes(tableSchema)) continue;
+      tables.push({ schema: tableSchema, name, columnCount: table.columns.length });
+    }
+    return tables;
+  }
+  async generateObjectDraft(datasource, remoteName, opts = {}) {
+    const schema = await this.config.introspect(datasource);
+    const table = this.findTable(schema, remoteName);
+    if (!table) {
+      throw new Error(
+        `Remote table '${remoteName}' not found on datasource '${datasource}'.`
+      );
+    }
+    const dialect = schema.dialect;
+    const matched = parseQualified(table.name);
+    const remoteSchema = opts.remoteSchema ?? matched.schema;
+    const resolvedRemoteName = matched.name;
+    const include = opts.includeColumns ? new Set(opts.includeColumns) : void 0;
+    const exclude = opts.excludeColumns ? new Set(opts.excludeColumns) : /* @__PURE__ */ new Set();
+    const pkOverride = opts.primaryKey ? new Set(opts.primaryKey) : void 0;
+    const fields = {};
+    const review = [];
+    for (const col of table.columns) {
+      if (include && !include.has(col.name)) continue;
+      if (exclude.has(col.name)) continue;
+      const fieldName = opts.rename?.[col.name] ?? col.name;
+      const suggested = suggestFieldType(col.type, dialect);
+      const fieldType = suggested ?? "text";
+      if (!suggested) {
+        review.push({
+          column: col.name,
+          remoteType: col.type,
+          note: `unrecognised remote type \u2014 defaulted to 'text', verify`
+        });
+      } else if (isCompatible(col.type, fieldType, dialect) === "lossy") {
+        review.push({
+          column: col.name,
+          remoteType: col.type,
+          note: `mapped lossy to '${fieldType}'`
+        });
+      }
+      const isPk = pkOverride ? pkOverride.has(col.name) : col.primaryKey;
+      fields[fieldName] = isPk ? { type: fieldType, primaryKey: true } : { type: fieldType };
+    }
+    const name = toObjectName(resolvedRemoteName);
+    const definition = {
+      name,
+      label: toLabel(name),
+      datasource,
+      external: {
+        ...remoteSchema ? { remoteSchema } : {},
+        remoteName: resolvedRemoteName
+      },
+      fields
+    };
+    return {
+      name,
+      datasource,
+      definition,
+      source: renderObjectSource(definition, fields, review),
+      review
+    };
+  }
+  async importObject(datasource, remoteName, opts = {}) {
+    if (!this.config.persistObject) {
+      throw new Error(
+        `importObject requires a writable metadata store, but none is wired (datasource '${datasource}'). This deployment may be GitOps-only \u2014 use 'os datasource introspect' and commit the generated *.object.ts instead.`
+      );
+    }
+    const draft = await this.generateObjectDraft(datasource, remoteName, opts);
+    const name = opts.name ?? draft.name;
+    const external = {
+      ...draft.definition.external,
+      ...opts.writable ? { writable: true } : {}
+    };
+    const definition = {
+      ...draft.definition,
+      name,
+      label: toLabel(name),
+      external
+    };
+    await this.config.persistObject(name, definition);
+    this.logger?.info?.(`importObject: persisted '${name}' from ${datasource}.${remoteName}`, {
+      writable: opts.writable === true,
+      review: draft.review.length
+    });
+    return { name, definition, review: draft.review };
+  }
+  async refreshCatalog(datasource) {
+    const schema = await this.config.introspect(datasource);
+    const catalog = ExternalCatalogSchema.parse({
+      name: `${datasource}_catalog`,
+      datasource,
+      snapshotAt: (/* @__PURE__ */ new Date()).toISOString(),
+      dialect: schema.dialect,
+      tables: Object.values(schema.tables).map((t) => {
+        const { schema: s, name } = parseQualified(t.name);
+        return {
+          remoteSchema: s,
+          remoteName: name,
+          columns: t.columns.map((c) => ({
+            name: c.name,
+            sqlType: c.type,
+            nullable: c.nullable,
+            primaryKey: c.primaryKey,
+            suggestedFieldType: suggestFieldType(c.type, schema.dialect)
+          }))
+        };
+      })
+    });
+    if (this.config.persistCatalog) {
+      try {
+        await this.config.persistCatalog(catalog);
+      } catch (err) {
+        this.logger?.warn?.(`refreshCatalog: failed to persist '${catalog.name}'`, err);
+      }
+    }
+    return catalog;
+  }
+  async validateObject(objectName) {
+    const obj = await this.config.getObject(objectName);
+    if (!obj) {
+      throw new Error(`Object '${objectName}' not found.`);
+    }
+    const datasource = obj.datasource ?? "default";
+    const ds = await this.config.getDatasource(datasource);
+    if (!ds || !ds.schemaMode || ds.schemaMode === "managed") {
+      return { ok: true, datasource, object: objectName, diffs: [] };
+    }
+    const schema = await this.config.introspect(datasource);
+    const dialect = schema.dialect;
+    const remoteName = obj.external?.remoteName ?? obj.name;
+    const table = this.findTable(schema, remoteName);
+    const diffs = [];
+    if (!table) {
+      diffs.push({
+        kind: "missing_table",
+        remoteSchema: obj.external?.remoteSchema,
+        remoteName,
+        severity: "error"
+      });
+      return { ok: false, datasource, object: objectName, diffs };
+    }
+    const columnsByName = new Map(table.columns.map((c) => [c.name, c]));
+    const ignore = new Set(obj.external?.ignoreColumns ?? []);
+    const fieldToRemote = /* @__PURE__ */ new Map();
+    for (const [remoteCol, fieldName] of Object.entries(obj.external?.columnMap ?? {})) {
+      fieldToRemote.set(fieldName, remoteCol);
+    }
+    for (const [fieldName, field] of Object.entries(obj.fields ?? {})) {
+      if (BUILTIN_COLUMNS.has(fieldName)) continue;
+      const remoteCol = fieldToRemote.get(fieldName) ?? fieldName;
+      if (ignore.has(remoteCol)) continue;
+      const col = columnsByName.get(remoteCol);
+      if (!col) {
+        diffs.push({
+          kind: "missing_column",
+          remoteName,
+          column: remoteCol,
+          severity: "error"
+        });
+        continue;
+      }
+      const fieldType = field.type ?? "text";
+      const compat = isCompatible(col.type, fieldType, dialect);
+      if (compat === false) {
+        diffs.push({
+          kind: "type_mismatch",
+          remoteName,
+          column: remoteCol,
+          expected: fieldType,
+          actual: col.type,
+          severity: "error"
+        });
+      } else if (compat === "lossy") {
+        diffs.push({
+          kind: "type_mismatch",
+          remoteName,
+          column: remoteCol,
+          expected: fieldType,
+          actual: col.type,
+          severity: "warning"
+        });
+      }
+    }
+    const ok = !diffs.some((d) => d.severity === "error");
+    return { ok, datasource, object: objectName, diffs };
+  }
+  async validateAll() {
+    const objects = await this.config.listObjects();
+    const federated = objects.filter(
+      (o) => o.external !== void 0 || o.datasource && o.datasource !== "default"
+    );
+    const results = await Promise.all(
+      federated.map(
+        (o) => this.validateObject(o.name).catch((err) => {
+          this.logger?.warn(`validateObject('${o.name}') failed`, err);
+          return {
+            ok: false,
+            datasource: o.datasource ?? "default",
+            object: o.name,
+            diffs: [
+              {
+                kind: "missing_table",
+                remoteName: o.external?.remoteName ?? o.name,
+                actual: err instanceof Error ? err.message : String(err),
+                severity: "error"
+              }
+            ]
+          };
+        })
+      )
+    );
+    const ok = results.every((r) => r.ok);
+    return { ok, results };
+  }
+};
+function renderObjectSource(definition, fields, review) {
+  const reviewByColumn = new Map(review.map((r) => [r.column, r.note]));
+  const external = definition.external;
+  const fieldLines = Object.entries(fields).map(([fieldName, f]) => {
+    const note = reviewByColumn.get(fieldName);
+    const pk = f.primaryKey ? ", primaryKey: true" : "";
+    const comment = note ? ` // REVIEW: ${note}` : "";
+    return `    ${fieldName}: { type: '${f.type}'${pk} },${comment}`;
+  });
+  const externalLine = external.remoteSchema ? `  external: { remoteSchema: '${external.remoteSchema}', remoteName: '${external.remoteName}' },` : `  external: { remoteName: '${external.remoteName}' },`;
+  return [
+    `// Generated by \`os datasource introspect\` (ADR-0015). Review before committing.`,
+    `import type { ServiceObjectInput } from '@objectstack/spec/data';`,
+    ``,
+    `const ${definition.name}: ServiceObjectInput = {`,
+    `  name: '${definition.name}',`,
+    `  label: '${definition.label}',`,
+    `  datasource: '${definition.datasource}',`,
+    externalLine,
+    `  fields: {`,
+    ...fieldLines,
+    `  },`,
+    `};`,
+    ``,
+    `export default ${definition.name};`,
+    ``
+  ].join("\n");
+}
+
+// src/plugin.ts
+var ExternalDatasourceServicePlugin = class {
+  constructor(options = {}) {
+    this.name = "com.objectstack.service-external-datasource";
+    this.version = "1.0.0";
+    this.type = "standard";
+    this.dependencies = [];
+    this.options = options;
+  }
+  async init(ctx) {
+    const engine = safeGetService(ctx, "data");
+    const metadata = safeGetService(ctx, "metadata");
+    const introspect = this.options.introspect ?? (async (datasource) => {
+      if (engine?.introspectDatasource) return engine.introspectDatasource(datasource);
+      const driver = engine?.getDatasourceDriver?.(datasource);
+      if (driver?.introspectSchema) return driver.introspectSchema();
+      throw new Error(
+        `Cannot introspect datasource '${datasource}': no driver introspection available.`
+      );
+    });
+    const config = {
+      introspect,
+      getDatasource: async (n) => await metadata?.get("datasource", n),
+      getObject: async (n) => metadata?.getObject ? await metadata.getObject(n) : await metadata?.get("object", n),
+      listObjects: async () => (metadata?.listObjects ? await metadata.listObjects() : await metadata?.list?.("object")) ?? [],
+      // Persist the refreshed snapshot as an `external_catalog` metadata record
+      // so the boot gate + Studio's schema browser can read it without
+      // re-introspecting. No-op when the metadata service can't write.
+      ...metadata?.register ? {
+        persistCatalog: async (catalog) => {
+          await metadata.register("external_catalog", catalog.name, catalog);
+        },
+        // Runtime "Import as Object": persist a federated object so it's
+        // immediately queryable, no git commit required (ADR-0015 Addendum).
+        persistObject: async (name, definition) => {
+          await metadata.register("object", name, definition);
+        }
+      } : {},
+      logger: this.options.logger
+    };
+    this.service = new ExternalDatasourceService(config);
+    ctx.registerService("external-datasource", this.service);
+  }
+  async start(ctx) {
+    if (this.service) await ctx.trigger("external-datasource:ready", this.service);
+  }
+  async destroy() {
+    this.service = void 0;
+  }
+};
+function safeGetService(ctx, name) {
+  try {
+    return ctx.getService(name);
+  } catch {
+    return void 0;
+  }
+}
+
+// src/datasource-admin-service.ts
+var NAME_RE = /^[a-z_][a-z0-9_]*$/;
+var DatasourceAdminService = class {
+  constructor(config) {
+    this.config = config;
+  }
+  get logger() {
+    return this.config.logger;
+  }
+  async listDatasources() {
+    const records = await this.config.listDatasourceRecords();
+    const byName = /* @__PURE__ */ new Map();
+    for (const rec of records) {
+      const slot = byName.get(rec.name) ?? {};
+      if (rec.origin === "runtime") slot.runtime = rec;
+      else slot.code = rec;
+      byName.set(rec.name, slot);
+    }
+    const summaries = [];
+    for (const [name, slot] of byName) {
+      const effective = slot.code ?? slot.runtime;
+      if (!effective) continue;
+      summaries.push({
+        name,
+        label: effective.label,
+        driver: effective.driver,
+        schemaMode: effective.schemaMode ?? "managed",
+        origin: slot.code ? "code" : "runtime",
+        active: effective.active ?? true,
+        status: "unvalidated",
+        ...slot.code?.definedIn ? { definedIn: slot.code.definedIn } : {},
+        ...slot.code && slot.runtime ? { conflictsWithCode: true } : {}
+      });
+    }
+    return summaries;
+  }
+  async testConnection(input, secret) {
+    if (!input?.driver) {
+      return { ok: false, error: "A driver is required to test a connection." };
+    }
+    const queryTimeoutMs = input.external?.queryTimeoutMs;
+    try {
+      return await this.config.probe({
+        driver: input.driver,
+        config: input.config ?? {},
+        secret: secret?.value,
+        external: input.external,
+        ...typeof queryTimeoutMs === "number" ? { timeoutMs: queryTimeoutMs } : {}
+      });
+    } catch (err) {
+      return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+  async createDatasource(input, secret) {
+    this.assertValidName(input?.name);
+    if (!input.driver) throw new Error("A driver is required to create a datasource.");
+    const existing = await this.config.getDatasourceRecord(input.name);
+    if (existing) {
+      if (existing.origin === "code" || existing.origin === void 0) {
+        throw new Error(
+          `Cannot create datasource '${input.name}': a code-defined datasource owns this name (read-only).`
+        );
+      }
+      throw new Error(`Datasource '${input.name}' already exists.`);
+    }
+    const record = {
+      ...this.toRecord(input),
+      origin: "runtime"
+    };
+    if (secret) {
+      const credentialsRef = await this.config.writeSecret(secret, { name: input.name });
+      record.external = { ...record.external ?? {}, credentialsRef };
+    }
+    await this.config.putDatasourceRecord(record);
+    await this.tryRegisterPool(record);
+    return this.toSummary(record);
+  }
+  async updateDatasource(name, patch, secret) {
+    const existing = await this.config.getDatasourceRecord(name);
+    if (!existing) throw new Error(`Datasource '${name}' not found.`);
+    if (existing.origin !== "runtime") {
+      throw new Error(`Datasource '${name}' is code-defined and cannot be edited at runtime.`);
+    }
+    const merged = {
+      ...existing,
+      ...patch.label !== void 0 ? { label: patch.label } : {},
+      ...patch.driver !== void 0 ? { driver: patch.driver } : {},
+      ...patch.schemaMode !== void 0 ? { schemaMode: patch.schemaMode } : {},
+      ...patch.config !== void 0 ? { config: patch.config } : {},
+      ...patch.pool !== void 0 ? { pool: patch.pool } : {},
+      ...patch.active !== void 0 ? { active: patch.active } : {},
+      name: existing.name,
+      origin: "runtime"
+    };
+    if (patch.external !== void 0) {
+      merged.external = { ...patch.external, credentialsRef: existing.external?.credentialsRef };
+    }
+    if (secret) {
+      const prevRef = existing.external?.credentialsRef;
+      const credentialsRef = await this.config.writeSecret(secret, { name });
+      merged.external = { ...merged.external ?? {}, credentialsRef };
+      if (prevRef && prevRef !== credentialsRef) await this.tryRemoveSecret(prevRef);
+    }
+    await this.config.putDatasourceRecord(merged);
+    await this.tryRegisterPool(merged);
+    return this.toSummary(merged);
+  }
+  async removeDatasource(name) {
+    const existing = await this.config.getDatasourceRecord(name);
+    if (!existing) throw new Error(`Datasource '${name}' not found.`);
+    if (existing.origin !== "runtime") {
+      throw new Error(`Datasource '${name}' is code-defined and cannot be removed at runtime.`);
+    }
+    const bound = await this.config.countBoundObjects(name);
+    if (bound > 0) {
+      throw new Error(
+        `Cannot remove datasource '${name}': ${bound} object(s) are still bound to it.`
+      );
+    }
+    await this.config.deleteDatasourceRecord(name);
+    if (existing.external?.credentialsRef) await this.tryRemoveSecret(existing.external.credentialsRef);
+    await this.tryUnregisterPool(name);
+  }
+  // --- internals -----------------------------------------------------------
+  assertValidName(name) {
+    if (!name || !NAME_RE.test(name)) {
+      throw new Error(
+        `Invalid datasource name '${name ?? ""}': must match /^[a-z_][a-z0-9_]*$/.`
+      );
+    }
+  }
+  toRecord(input) {
+    return {
+      name: input.name,
+      ...input.label !== void 0 ? { label: input.label } : {},
+      driver: input.driver,
+      ...input.schemaMode !== void 0 ? { schemaMode: input.schemaMode } : {},
+      ...input.config !== void 0 ? { config: input.config } : {},
+      ...input.external !== void 0 ? { external: input.external } : {},
+      ...input.pool !== void 0 ? { pool: input.pool } : {},
+      ...input.active !== void 0 ? { active: input.active } : {}
+    };
+  }
+  toSummary(record) {
+    return {
+      name: record.name,
+      label: record.label,
+      driver: record.driver,
+      schemaMode: record.schemaMode ?? "managed",
+      origin: record.origin ?? "runtime",
+      active: record.active ?? true,
+      status: "unvalidated"
+    };
+  }
+  async tryRegisterPool(record) {
+    try {
+      await this.config.registerPool?.(record);
+    } catch (err) {
+      this.logger?.warn(`registerPool('${record.name}') failed`, err);
+    }
+  }
+  async tryUnregisterPool(name) {
+    try {
+      await this.config.unregisterPool?.(name);
+    } catch (err) {
+      this.logger?.warn(`unregisterPool('${name}') failed`, err);
+    }
+  }
+  async tryRemoveSecret(credentialsRef) {
+    try {
+      await this.config.removeSecret?.(credentialsRef);
+    } catch (err) {
+      this.logger?.warn(`removeSecret('${credentialsRef}') failed`, err);
+    }
+  }
+};
+
+// src/datasource-admin-plugin.ts
+import { registerMetadataTypeActions } from "@objectstack/spec/kernel";
+var DatasourceAdminServicePlugin = class {
+  constructor(options = {}) {
+    this.name = "com.objectstack.service-datasource-admin";
+    this.version = "1.0.0";
+    this.type = "standard";
+    this.dependencies = [];
+    this.options = options;
+  }
+  async init(ctx) {
+    const logger = this.options.logger;
+    registerMetadataTypeActions("datasource", [
+      {
+        name: "test_connection",
+        label: "Test connection",
+        icon: "plug-zap",
+        type: "api",
+        target: "/api/v1/datasources/${ctx.recordId}/test",
+        method: "POST",
+        variant: "secondary",
+        refreshAfter: false,
+        locations: ["record_header", "list_item"]
+      }
+    ]);
+    const metadataOf = () => safeGetService2(ctx, "metadata");
+    const engineOf = () => safeGetService2(ctx, "data");
+    const factory = () => this.options.driverFactory ?? safeGetService2(ctx, "datasource-driver-factory");
+    const config = {
+      probe: (input) => this.probe(factory(), input),
+      listDatasourceRecords: async () => {
+        const rows = await metadataOf()?.list("datasource") ?? [];
+        return rows.map((r) => ({ ...r, origin: r.origin ?? "code" }));
+      },
+      getDatasourceRecord: async (name) => {
+        const row = await metadataOf()?.get("datasource", name);
+        return row ? { ...row, origin: row.origin ?? "code" } : void 0;
+      },
+      putDatasourceRecord: async (record) => {
+        const metadata = metadataOf();
+        if (!metadata?.register) {
+          throw new Error("Metadata service is unavailable; cannot persist datasource.");
+        }
+        await metadata.register("datasource", record.name, record);
+      },
+      deleteDatasourceRecord: async (name) => {
+        const metadata = metadataOf();
+        if (!metadata?.unregister) {
+          throw new Error("Metadata service is unavailable; cannot remove datasource.");
+        }
+        await metadata.unregister("datasource", name);
+      },
+      writeSecret: async (input, hint) => {
+        const binder = this.options.secrets;
+        if (!binder?.bind) {
+          throw new Error(
+            "No secret store configured: refusing to persist a datasource credential in cleartext. Wire a SecretBinder (CryptoProvider + sys_secret) into DatasourceAdminServicePlugin."
+          );
+        }
+        return binder.bind(input, hint);
+      },
+      removeSecret: async (ref) => {
+        await this.options.secrets?.unbind?.(ref);
+      },
+      countBoundObjects: async (datasource) => {
+        const metadata = metadataOf();
+        const objects = await metadata?.listObjects?.() ?? await metadata?.list("object") ?? [];
+        return objects.filter((o) => o?.datasource === datasource).length;
+      },
+      registerPool: async (record) => {
+        const f = factory();
+        const engine = engineOf();
+        if (!f || !engine?.registerDriver || !f.supports(record.driver)) return;
+        const credentialsRef = record.external?.credentialsRef;
+        const secret = credentialsRef ? await this.options.secrets?.resolve?.(credentialsRef) : void 0;
+        const handle = await f.create({ ...this.toSpec(record), ...secret ? { secret } : {} });
+        if (typeof handle?.connect === "function") await handle.connect();
+        const engineDriver = handle.driver ?? handle;
+        try {
+          engineDriver.name = record.name;
+        } catch {
+        }
+        engine.registerDriver(engineDriver);
+        engine.registerDatasourceDef?.({
+          name: record.name,
+          schemaMode: record.schemaMode,
+          external: record.external
+        });
+      },
+      unregisterPool: async (name) => {
+        const driver = engineOf()?.getDriverByName?.(name);
+        if (typeof driver?.disconnect === "function") await driver.disconnect();
+      },
+      logger
+    };
+    this.config = config;
+    this.service = new DatasourceAdminService(config);
+    ctx.registerService("datasource-admin", this.service);
+  }
+  async start(ctx) {
+    await this.rehydratePools();
+    if (this.service) await ctx.trigger("datasource-admin:ready", this.service);
+  }
+  /**
+   * Boot-time rehydration: list persisted runtime datasources and re-register
+   * each one's connection pool (driver build → connect → registerDriver),
+   * decrypting its `sys_secret` credential on the way via the configured
+   * `registerPool` (which resolves `credentialsRef`). Code-defined datasources
+   * are owned by the host stack's own boot path and skipped here. Entirely
+   * best-effort: a missing factory/engine, an unpersisted dev store (nothing
+   * to rehydrate), or a single failing pool never blocks boot.
+   */
+  async rehydratePools() {
+    const cfg = this.config;
+    if (!cfg?.registerPool || !cfg.listDatasourceRecords) return;
+    let records;
+    try {
+      records = await cfg.listDatasourceRecords();
+    } catch (err) {
+      this.options.logger?.warn?.("datasource rehydrate: listing records failed", err);
+      return;
+    }
+    const runtime = records.filter((r) => r.origin === "runtime" && (r.active ?? true));
+    if (runtime.length === 0) return;
+    let registered = 0;
+    for (const record of runtime) {
+      try {
+        await cfg.registerPool(record);
+        registered++;
+      } catch (err) {
+        this.options.logger?.warn?.(`datasource rehydrate: pool '${record.name}' failed`, err);
+      }
+    }
+    this.options.logger?.info?.(
+      `Rehydrated ${registered}/${runtime.length} runtime datasource pool(s) on boot`
+    );
+  }
+  async destroy() {
+    this.service = void 0;
+  }
+  // --- internals -----------------------------------------------------------
+  toSpec(record) {
+    return {
+      name: record.name,
+      driver: record.driver,
+      config: record.config ?? {},
+      external: record.external,
+      pool: record.pool
+    };
+  }
+  /** Probe a connection via the driver factory: build → connect → ping → close. */
+  async probe(factory, input) {
+    if (!factory) {
+      return { ok: false, error: "No driver factory is registered to test connections." };
+    }
+    if (!factory.supports(input.driver)) {
+      return { ok: false, error: `No driver factory supports driver '${input.driver}'.` };
+    }
+    let driver;
+    try {
+      driver = await factory.create({
+        driver: input.driver,
+        config: input.config,
+        secret: input.secret,
+        external: input.external
+      });
+    } catch (err) {
+      return { ok: false, error: `Failed to build driver: ${errMsg(err)}` };
+    }
+    const startedAt = monotonicNow();
+    try {
+      if (typeof driver?.connect === "function") await driver.connect();
+      if (typeof driver?.ping === "function") await driver.ping();
+      else if (typeof driver?.checkHealth === "function") await driver.checkHealth();
+      else if (typeof driver?.introspectSchema === "function") await driver.introspectSchema();
+      const latencyMs = elapsedSince(startedAt);
+      let serverVersion;
+      try {
+        serverVersion = typeof driver?.serverVersion === "function" ? await driver.serverVersion() : void 0;
+      } catch {
+      }
+      return { ok: true, latencyMs, ...serverVersion ? { serverVersion } : {} };
+    } catch (err) {
+      return { ok: false, error: errMsg(err) };
+    } finally {
+      try {
+        if (typeof driver?.disconnect === "function") await driver.disconnect();
+      } catch {
+      }
+    }
+  }
+};
+function safeGetService2(ctx, name) {
+  try {
+    return ctx.getService(name);
+  } catch {
+    return void 0;
+  }
+}
+function errMsg(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function monotonicNow() {
+  const perf = globalThis.performance;
+  return typeof perf?.now === "function" ? perf.now() : 0;
+}
+function elapsedSince(startedAt) {
+  return Math.max(0, Math.round(monotonicNow() - startedAt));
+}
+
+// src/default-datasource-driver-factory.ts
+var DRIVER_ID_ALIASES = {
+  postgres: "postgres",
+  postgresql: "postgres",
+  pg: "postgres",
+  sqlite: "sqlite",
+  sqlite3: "sqlite",
+  "better-sqlite3": "sqlite",
+  mongodb: "mongodb",
+  mongo: "mongodb",
+  memory: "memory",
+  inmemory: "memory",
+  "in-memory": "memory"
+};
+function resolveKind(driverId) {
+  return DRIVER_ID_ALIASES[String(driverId ?? "").toLowerCase()];
+}
+function toHandle(driver, serverVersion) {
+  return {
+    connect: typeof driver?.connect === "function" ? () => driver.connect() : void 0,
+    disconnect: typeof driver?.disconnect === "function" ? () => driver.disconnect() : void 0,
+    checkHealth: typeof driver?.checkHealth === "function" ? () => driver.checkHealth() : void 0,
+    ping: typeof driver?.checkHealth === "function" ? () => driver.checkHealth() : void 0,
+    ...serverVersion ? { serverVersion } : {},
+    driver
+  };
+}
+function buildSqlConnection(spec, client) {
+  const cfg = spec.config ?? {};
+  if (client === "better-sqlite3") {
+    const filename = cfg.filename ?? cfg.file ?? cfg.database ?? ":memory:";
+    return { filename };
+  }
+  const url = cfg.url ?? cfg.connectionString;
+  if (url) {
+    return spec.secret ? { connectionString: url, password: spec.secret } : { connectionString: url };
+  }
+  return {
+    host: cfg.host,
+    port: cfg.port,
+    database: cfg.database,
+    user: cfg.user ?? cfg.username,
+    ...spec.secret ? { password: spec.secret } : cfg.password ? { password: cfg.password } : {},
+    ...cfg.ssl != null ? { ssl: cfg.ssl } : {}
+  };
+}
+function buildMongoUrl(spec) {
+  const cfg = spec.config ?? {};
+  const explicit = cfg.url ?? cfg.uri;
+  if (explicit) return explicit;
+  const host = cfg.host ?? "localhost";
+  const port = cfg.port ?? 27017;
+  const db = cfg.database ?? "";
+  const user = cfg.user ?? cfg.username;
+  const auth = user ? `${encodeURIComponent(user)}:${encodeURIComponent(spec.secret ?? "")}@` : "";
+  return `mongodb://${auth}${host}:${port}/${db}`;
+}
+function createDefaultDatasourceDriverFactory() {
+  return {
+    supports(driverId) {
+      return resolveKind(driverId) !== void 0;
+    },
+    async create(spec) {
+      const kind = resolveKind(spec.driver);
+      if (!kind) {
+        throw new Error(`Unsupported driver id '${spec.driver}'.`);
+      }
+      const schemaMode = spec.external?.schemaMode ?? spec.config?.schemaMode;
+      if (kind === "postgres") {
+        const { SqlDriver } = await import("@objectstack/driver-sql");
+        const driver = new SqlDriver({
+          client: "pg",
+          connection: buildSqlConnection(spec, "pg"),
+          pool: { min: 0, max: 5 },
+          ...schemaMode ? { schemaMode } : {}
+        });
+        return toHandle(driver, () => sqlServerVersion(driver, "pg"));
+      }
+      if (kind === "sqlite") {
+        const { SqlDriver } = await import("@objectstack/driver-sql");
+        const driver = new SqlDriver({
+          client: "better-sqlite3",
+          connection: buildSqlConnection(spec, "better-sqlite3"),
+          useNullAsDefault: true,
+          ...schemaMode ? { schemaMode } : {}
+        });
+        return toHandle(driver, () => sqlServerVersion(driver, "sqlite"));
+      }
+      if (kind === "mongodb") {
+        let MongoDBDriver;
+        try {
+          ({ MongoDBDriver } = await import("@objectstack/driver-mongodb"));
+        } catch (err) {
+          throw new Error(
+            `mongodb driver requested but @objectstack/driver-mongodb is not installed (${err?.message ?? err}).`
+          );
+        }
+        const driver = new MongoDBDriver({ url: buildMongoUrl(spec) });
+        return toHandle(driver);
+      }
+      const { InMemoryDriver } = await import("@objectstack/driver-memory");
+      return toHandle(new InMemoryDriver());
+    }
+  };
+}
+async function sqlServerVersion(driver, client) {
+  if (typeof driver?.execute !== "function") return void 0;
+  try {
+    const sql = client === "pg" ? "SELECT version() AS v" : "SELECT sqlite_version() AS v";
+    const rows = await driver.execute(sql);
+    const first = Array.isArray(rows) ? rows[0] : Array.isArray(rows?.rows) ? rows.rows[0] : rows;
+    const v = first?.v ?? first?.version ?? first?.["sqlite_version()"];
+    return typeof v === "string" ? v : void 0;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/datasource-secret-binder.ts
+var REF_PREFIX = "sys_secret:";
+function toCredentialsRef(handleId) {
+  return `${REF_PREFIX}${handleId}`;
+}
+function parseCredentialsRef(ref) {
+  return ref?.startsWith(REF_PREFIX) ? ref.slice(REF_PREFIX.length) : void 0;
+}
+function createDatasourceSecretBinder(deps) {
+  const { engine, cryptoProvider } = deps;
+  const defaultNamespace = deps.namespace ?? "datasource";
+  return {
+    async bind(input, hint) {
+      const namespace = input.namespace ?? defaultNamespace;
+      const key = input.key ?? hint.name;
+      const handle = await cryptoProvider.encrypt(input.value, { namespace, key });
+      await engine.insert("sys_secret", {
+        id: handle.id,
+        namespace,
+        key,
+        kms_key_id: handle.kmsKeyId,
+        alg: handle.alg,
+        version: handle.version,
+        ciphertext: handle.ciphertext
+      });
+      return toCredentialsRef(handle.id);
+    },
+    async unbind(credentialsRef) {
+      const id = parseCredentialsRef(credentialsRef);
+      if (!id) return;
+      await engine.delete("sys_secret", { where: { id } });
+    },
+    async resolve(credentialsRef) {
+      const id = parseCredentialsRef(credentialsRef);
+      if (!id || typeof engine.find !== "function") return void 0;
+      try {
+        const result = await engine.find("sys_secret", {
+          where: { id },
+          limit: 1,
+          // Secrets are scoped through their owning datasource artefact, so
+          // skip the tenant-audit warning (mirrors SettingsService's store).
+          bypassTenantAudit: true
+        });
+        const rows = (Array.isArray(result) ? result : result?.data) ?? [];
+        const row = rows[0];
+        if (!row?.ciphertext) return void 0;
+        return await cryptoProvider.decrypt(
+          {
+            id: row.id,
+            kmsKeyId: row.kms_key_id,
+            alg: row.alg,
+            version: row.version,
+            ciphertext: row.ciphertext
+          },
+          { namespace: row.namespace, key: row.key }
+        );
+      } catch {
+        return void 0;
+      }
+    }
+  };
+}
+
+// src/admin-routes.ts
+function registerDatasourceAdminRoutes(server, ctx, basePath = "/api/v1") {
+  const root = `${basePath}/datasources`;
+  const adminService = () => {
+    try {
+      return ctx.getService("datasource-admin");
+    } catch {
+      return void 0;
+    }
+  };
+  const unavailable = (res) => res.status(503).json({ error: "datasource_admin_unavailable" });
+  const badRequest = (res, err) => res.status(400).json({ error: "datasource_admin_error", message: err instanceof Error ? err.message : String(err) });
+  const splitSecret = (body) => {
+    const { secret, ...draft } = body ?? {};
+    const normalised = secret == null ? void 0 : typeof secret === "string" ? { value: secret } : secret;
+    return { draft, secret: normalised };
+  };
+  server.get(root, async (_req, res) => {
+    const svc = adminService();
+    if (!svc?.listDatasources) return unavailable(res);
+    const datasources = await svc.listDatasources();
+    res.json({ datasources });
+  });
+  server.post(`${root}/test`, async (req, res) => {
+    const svc = adminService();
+    if (!svc?.testConnection) return unavailable(res);
+    const { draft, secret } = splitSecret(req.body);
+    try {
+      const result = await svc.testConnection(draft, secret);
+      res.json({ result });
+    } catch (err) {
+      badRequest(res, err);
+    }
+  });
+  server.post(root, async (req, res) => {
+    const svc = adminService();
+    if (!svc?.createDatasource) return unavailable(res);
+    const { draft, secret } = splitSecret(req.body);
+    try {
+      const datasource = await svc.createDatasource(draft, secret);
+      res.status(201).json({ datasource });
+    } catch (err) {
+      badRequest(res, err);
+    }
+  });
+  server.patch(`${root}/:name`, async (req, res) => {
+    const svc = adminService();
+    if (!svc?.updateDatasource) return unavailable(res);
+    const { draft, secret } = splitSecret(req.body);
+    try {
+      const datasource = await svc.updateDatasource(req.params.name, draft, secret);
+      res.json({ datasource });
+    } catch (err) {
+      badRequest(res, err);
+    }
+  });
+  server.delete(`${root}/:name`, async (req, res) => {
+    const svc = adminService();
+    if (!svc?.removeDatasource) return unavailable(res);
+    try {
+      await svc.removeDatasource(req.params.name);
+      res.status(204).end();
+    } catch (err) {
+      badRequest(res, err);
+    }
+  });
+}
+export {
+  DatasourceAdminService,
+  DatasourceAdminServicePlugin,
+  ExternalDatasourceService,
+  ExternalDatasourceServicePlugin,
+  createDatasourceSecretBinder,
+  createDefaultDatasourceDriverFactory,
+  parseCredentialsRef,
+  registerDatasourceAdminRoutes,
+  toCredentialsRef
+};
+//# sourceMappingURL=index.js.map