@nmakarov/cli-toolkit 0.33.0 → 0.37.0

package/dist/index.js

@@ -1799,6 +1799,49 @@ var Params = class _Params {
       module: moduleName ?? this._currentModule
     });
   }
+  /**
+   * Report a param value that a component RESOLVED ON ITS OWN — outside
+   * Params.get() — e.g. discovered by combining its config files (the way
+   * blueprints merge defaults/aggregator/feed data). Without this, every
+   * key such a component probed for an override shows up in the
+   * --showUsedParams dump as "undefined (default)"; reporting upgrades the
+   * entry to the value the component actually works with.
+   *
+   * Attribution rules:
+   *   - entries figured from an explicit input (cli/env/options/…) are left
+   *     untouched — the component merely confirmed them, the origin stands;
+   *   - "default" entries (Params had nothing) and earlier reports are
+   *     replaced by the report;
+   *   - keys never seen by Params are appended as new entries.
+   * The LATEST report wins — a component may resolve the same key several
+   * times with increasing specificity (e.g. a blueprint re-merged for a
+   * concrete resource) and the dump should show what it settled on.
+   * Later params.get() probes that find nothing ("default") never shadow a
+   * reported value — see {@link getFiguredByModule}.
+   *
+   * @param {string} key
+   * @param {*} value - the value the component actually uses
+   * @param {string} [source="discovered"] - short origin label, e.g. "blueprint"
+   * @param {string} [moduleName] - dump section; defaults to the current module
+   */
+  reportResolved(key, value, source = "discovered", moduleName) {
+    const mod = moduleName ?? this._currentModule;
+    const mine = this.trackedParams.filter((e) => e.key === key && e.module === mod);
+    if (mine.some((e) => e.source !== "default" && !e.reported)) {
+      return;
+    }
+    this.trackedParams = this.trackedParams.filter(
+      (e) => !(e.key === key && e.module === mod)
+    );
+    this.trackedParams.push({
+      key,
+      definition: "reported",
+      value,
+      source,
+      module: mod,
+      reported: true
+    });
+  }
   /**
    * Get all tracked parameters (for --stopAfter=init)
    */
@@ -1823,12 +1866,24 @@ var Params = class _Params {
   /**
    * Get figured parameters grouped by module name.
    * Same param can appear in multiple modules (e.g. source, resource).
+   * Last occurrence per key wins, EXCEPT that an empty probe — a
+   * params.get() that found nothing ("default", undefined) — never shadows
+   * a value reported via {@link reportResolved}: components probe for
+   * overrides on every resolution cycle, and those misses say nothing about
+   * the value the component actually uses.
    */
   getFiguredByModule() {
+    const reported = /* @__PURE__ */ new Set();
+    for (const param of this.trackedParams) {
+      if (param.reported) reported.add(`${param.module}\0${param.key}`);
+    }
     const byModule = {};
     for (const param of this.trackedParams) {
       const mod = param.module;
       if (!byModule[mod]) byModule[mod] = {};
+      if (!param.reported && param.source === "default" && reported.has(`${mod}\0${param.key}`)) {
+        continue;
+      }
       byModule[mod][param.key] = { value: param.value, source: param.source };
     }
     return byModule;
@@ -3304,13 +3359,113 @@ function listSources(basePath) {
 
 // src/db/index.js
 import knex from "knex";
+
+// src/db/ensure.js
+var dbLabel = (db) => db?.config?.name ?? "db";
+async function ensureExtension(db, name, options = {}) {
+  const action = `CREATE EXTENSION IF NOT EXISTS "${name}"`;
+  if (!options.dryRun) {
+    await db.raw(action);
+  }
+  options.logger?.silly?.(`[ensure] ${dbLabel(db)}: ${action}${options.dryRun ? " (dryRun)" : ""}`);
+  return { action };
+}
+async function ensureTable(db, tableName, spec, options = {}) {
+  const { dryRun = false, logger } = options;
+  const actions = [];
+  const exists = await db.tableExists(tableName);
+  if (!exists) {
+    actions.push(`CREATE TABLE ${tableName} (${Object.keys(spec.columns).length} columns)`);
+    if (!dryRun) {
+      await db.schema.createTable(tableName, (t) => {
+        for (const define of Object.values(spec.columns)) {
+          define(t, db);
+        }
+      });
+    }
+  } else {
+    const missing = [];
+    for (const column of Object.keys(spec.columns)) {
+      if (!await db.schema.hasColumn(tableName, column)) {
+        missing.push(column);
+      }
+    }
+    if (missing.length > 0) {
+      actions.push(`ALTER TABLE ${tableName} ADD COLUMN ${missing.join(", ")}`);
+      if (!dryRun) {
+        await db.schema.alterTable(tableName, (t) => {
+          for (const column of missing) {
+            spec.columns[column](t, db);
+          }
+        });
+      }
+    }
+  }
+  for (const index of spec.indexes ?? []) {
+    const indexActions = await ensureIndex(db, tableName, index, options);
+    actions.push(...indexActions);
+  }
+  for (const action of actions) {
+    logger?.silly?.(`[ensure] ${dbLabel(db)}: ${action}${dryRun ? " (dryRun)" : ""}`);
+  }
+  return actions;
+}
+async function ensureIndex(db, tableName, index, options = {}) {
+  const { dryRun = false } = options;
+  const kind = index.unique ? "UNIQUE INDEX" : "INDEX";
+  const cols = index.columns.map((c) => `"${c}"`).join(", ");
+  const isPg = String(db?.config?.connectionString ?? "").startsWith("postgresql");
+  if (isPg) {
+    const sql2 = `CREATE ${kind} IF NOT EXISTS "${index.name}" ON "${tableName}" (${cols})`;
+    const { rows } = await db.raw(`SELECT 1 FROM pg_indexes WHERE indexname = ?`, [index.name]);
+    if (rows.length > 0) return [];
+    if (!dryRun) await db.raw(sql2);
+    return [sql2];
+  }
+  const sql = `CREATE ${kind} ${index.name} ON ${tableName} (${cols})`;
+  if (!dryRun) {
+    try {
+      await db.raw(sql);
+    } catch (error) {
+      if (!/already exists|duplicate/i.test(error?.message ?? "")) throw error;
+      return [];
+    }
+  }
+  return [sql];
+}
+async function ensureSchema(db, spec, options = {}) {
+  const actions = [];
+  for (const extension of spec.extensions ?? []) {
+    const { action } = await ensureExtension(db, extension, options);
+    if (options.dryRun) actions.push(action);
+  }
+  for (const [tableName, tableSpec] of Object.entries(spec.tables ?? {})) {
+    actions.push(...await ensureTable(db, tableName, tableSpec, options));
+  }
+  return { database: dbLabel(db), actions };
+}
+async function ensureSchemaEverywhere(dbs, spec, options = {}) {
+  const reports = [];
+  for (const db of dbs) {
+    const report = await ensureSchema(db, spec, options);
+    if (report.actions.length > 0) {
+      options.logger?.info?.(
+        `[ensure] ${report.database}: ${options.dryRun ? "would apply" : "applied"} ${report.actions.length} DDL statement(s)`
+      );
+    }
+    reports.push(report);
+  }
+  return reports;
+}
+
+// src/db/index.js
 var KNEX_DEFAULTS = {
   testConnection: true,
   pool: { min: 2, max: 10 },
   acquireConnectionTimeout: 1e4,
   ssl: { rejectUnauthorized: false }
 };
-var Db = class {
+var Db = class _Db {
   static async init(context, options = {}) {
     const buildConfig = async () => {
       const defs = {
@@ -3379,6 +3534,177 @@ var Db = class {
     const config2 = context?.params?.runWithModuleAsync ? await context.params.runWithModuleAsync("db", buildConfig) : await buildConfig();
     return dbConnect(context, config2);
   }
+  /**
+   * Initialize a SIBLING database handler: a database that lives on the same
+   * server with the same credentials/options as an existing ("base") one, and
+   * differs only by its database name. Typical use: a per-tenant / per-subject
+   * database alongside a main database that keeps the shared tables.
+   *
+   *   context.db = await Db.init(context);                       // main
+   *   const sub  = await Db.initSibling(context, "src_bright");  // sibling
+   *
+   * LOCATION-AGNOSTIC BY DESIGN — the call gracefully falls back to the main
+   * database, so callers can use it for all subject data without knowing what
+   * has been migrated where:
+   *   - empty `siblingName`            → the main handler (same as Db.init)
+   *   - sibling DB does not exist yet  → the main handler (data not migrated;
+   *     it still lives in the main database)
+   * Callers that must not fall back can check `handler === context.db`.
+   *
+   * Connection string resolution for an actual sibling, in order:
+   *   1. Explicit override — param `dbConnectionStringSib<SiblingName>` (env
+   *      `DB_CONNECTION_STRING_SIB_<SIBLING_NAME>`, e.g. `src_bright` →
+   *      `DB_CONNECTION_STRING_SIB_SRC_BRIGHT`). Nobody needs this on day
+   *      one; it is the escape hatch for when a sibling later moves to its
+   *      own server — one env var, no code changes (the `SIB_` namespace
+   *      both overrides the connection and declares that the sibling
+   *      exists, so it never falls back to main).
+   *   2. Derived — take the base connection string and swap the database
+   *      name (after confirming the database exists on that server). The
+   *      base is `options.baseDb` (a Db handler), then
+   *      `options.baseConnectionString`, then `context.db`.
+   *
+   * Handlers are cached per name on the context (`context.siblingDbs`), so
+   * any number of components asking for the same sibling share one pool —
+   * including the "falls back to main" answer, which is remembered for the
+   * lifetime of the process (a mid-run migration is picked up on restart).
+   * Disconnect is registered via `context.registerCleanup`, same as the
+   * main handler.
+   *
+   * @param {object} context - context with params/logger (and usually .db)
+   * @param {string} [siblingName] - the sibling's database name (e.g. "src_bright")
+   * @param {object} [options] - { baseDb, baseConnectionString, dbProfile }
+   * @returns {Promise<Db>} connected handler (same proxy shape as Db.init)
+   */
+  static async initSibling(context, siblingName, options = {}) {
+    if (!siblingName) {
+      return resolveMainHandler(context, options);
+    }
+    if (!/^[a-zA-Z0-9_]+$/.test(siblingName)) {
+      throw new ParamError(
+        `Db.initSibling: invalid sibling database name "${siblingName}" (letters, digits and _ only)`
+      );
+    }
+    if (!context.siblingDbs) {
+      context.siblingDbs = /* @__PURE__ */ new Map();
+    }
+    const cached = context.siblingDbs.get(siblingName);
+    if (cached) {
+      return cached;
+    }
+    const overrideParam = `dbConnectionStringSib${camelizeDbName(siblingName)}`;
+    let connectionString = await context?.params?.get?.(overrideParam, "string");
+    if (connectionString) {
+      context.logger?.debug?.(
+        `[Db] sibling "${siblingName}": using override param "${overrideParam}"`
+      );
+    } else {
+      const baseHandle = options.baseDb ?? context.db;
+      const base = baseHandle?.config?.connectionString ?? options.baseConnectionString;
+      if (!base) {
+        throw new ParamError(
+          `Db.initSibling: no base connection to derive "${siblingName}" from \u2014 init the main Db first (context.db = await Db.init(context)), or pass options.baseDb / options.baseConnectionString, or set the ${overrideParam} param (env ${toEnvKey(overrideParam)})`
+        );
+      }
+      const exists = await databaseExistsOnServer(baseHandle, base, siblingName);
+      if (!exists) {
+        context.logger?.debug?.(
+          `[Db] sibling "${siblingName}" does not exist \u2014 falling back to the main database`
+        );
+        const main = await resolveMainHandler(context, options);
+        context.siblingDbs.set(siblingName, main);
+        return main;
+      }
+      connectionString = replaceDatabaseName(base, siblingName);
+      context.logger?.debug?.(
+        `[Db] sibling "${siblingName}": derived from base (${formatConnectionEndpoint(base) ?? "?"})`
+      );
+    }
+    const config2 = {
+      ...KNEX_DEFAULTS,
+      connectionString,
+      name: siblingName,
+      profile: !!options.dbProfile,
+      logger: context.logger
+    };
+    const handler = await dbConnect(context, config2);
+    context.siblingDbs.set(siblingName, handler);
+    return handler;
+  }
+  /**
+   * Discover the sibling databases that are "currently in use", by name.
+   * Two sources, merged (env wins on duplicates):
+   *
+   *   1. ENV-DECLARED — every `DB_CONNECTION_STRING_SIB_<NAME>` env var
+   *      (the dedicated `SIB_` namespace) whose decoded name matches. This
+   *      covers siblings that moved to their own server: the same var that
+   *      overrides the connection also *registers* the database, so `.env`
+   *      stays the single convenient list.
+   *   2. SAME-SERVER SCAN — `SELECT datname FROM pg_database` on the base
+   *      server (PostgreSQL only), filtered the same way.
+   *
+   * The caller says what "matches": `{ prefix: "src_" }` or
+   * `{ match: /^src_/ }` — the toolkit does not guess a naming convention.
+   *
+   * @param {object} context - needs context.db (or options.baseDb) for the server scan
+   * @param {{ prefix?: string, match?: RegExp, baseDb?: object, env?: object }} options
+   * @returns {Promise<Array<{ name: string, origin: "env"|"server" }>>} sorted by name
+   */
+  static async discoverSiblings(context, options = {}) {
+    const { prefix, match, env = process.env } = options;
+    if (!prefix && !match) {
+      throw new ParamError(`Db.discoverSiblings: pass { prefix: "..." } or { match: /.../ }`);
+    }
+    const matches = match instanceof RegExp ? (n) => match.test(n) : (n) => n.startsWith(prefix);
+    const found = /* @__PURE__ */ new Map();
+    for (const key of Object.keys(env)) {
+      const m = /^DB_CONNECTION_STRING_SIB_(.+)$/.exec(key);
+      if (!m || !env[key]) continue;
+      const name = m[1].toLowerCase();
+      if (matches(name)) {
+        found.set(name, "env");
+      }
+    }
+    const base = options.baseDb ?? context?.db;
+    if (base) {
+      const connectionString = String(base.config?.connectionString ?? "");
+      if (connectionString.startsWith("postgresql")) {
+        const { rows } = await base.raw(
+          "SELECT datname FROM pg_database WHERE datistemplate = false"
+        );
+        for (const { datname } of rows) {
+          if (matches(datname) && !found.has(datname)) {
+            found.set(datname, "server");
+          }
+        }
+      } else {
+        context?.logger?.warn?.(
+          "[Db] discoverSiblings: server scan supported for PostgreSQL only; using env-declared siblings"
+        );
+      }
+    }
+    return [...found].map(([name, origin]) => ({ name, origin })).sort((a, b) => a.name.localeCompare(b.name));
+  }
+  /**
+   * Discover + connect: one handler per active sibling (cached, pooled —
+   * see initSibling). Pass `includeMain: true` to get `[context.db, ...]`,
+   * which is the usual shape for "apply this DDL everywhere" loops:
+   *
+   *   const dbs = await Db.initAllSiblings(context, { prefix: "src_", includeMain: true });
+   *   await ensureSchemaEverywhere(dbs, spec, { logger: context.logger });
+   *
+   * @param {object} context
+   * @param {{ prefix?: string, match?: RegExp, includeMain?: boolean, baseDb?: object, env?: object }} options
+   * @returns {Promise<Function[]>} connected handlers
+   */
+  static async initAllSiblings(context, options = {}) {
+    const discovered = await _Db.discoverSiblings(context, options);
+    const handlers = [];
+    for (const { name } of discovered) {
+      handlers.push(await _Db.initSibling(context, name, options));
+    }
+    return options.includeMain && context.db ? [context.db, ...handlers] : handlers;
+  }
   constructor(config2) {
     if (!config2 || !config2.connectionString) {
       throw new ParamError("Db: connectionString is required");
@@ -3639,6 +3965,54 @@ var Db = class {
 function capitalizeFirstLetter(str) {
   return str.charAt(0).toUpperCase() + str.slice(1);
 }
+async function resolveMainHandler(context, options = {}) {
+  if (options.baseDb) {
+    return options.baseDb;
+  }
+  if (!context.db) {
+    context.db = await Db.init(context);
+  }
+  return context.db;
+}
+async function databaseExistsOnServer(baseHandle, baseConnectionString, databaseName) {
+  if (!String(baseConnectionString).startsWith("postgresql")) {
+    return true;
+  }
+  const query = "SELECT 1 FROM pg_database WHERE datname = ?";
+  if (baseHandle) {
+    const { rows } = await baseHandle.raw(query, [databaseName]);
+    return rows.length > 0;
+  }
+  const shortLived = knex({
+    client: "pg",
+    connection: { connectionString: baseConnectionString },
+    pool: { min: 0, max: 1 }
+  });
+  try {
+    const { rows } = await shortLived.raw(query, [databaseName]);
+    return rows.length > 0;
+  } finally {
+    await shortLived.destroy();
+  }
+}
+function camelizeDbName(name) {
+  return name.split(/[_-]+/).filter(Boolean).map(capitalizeFirstLetter).join("");
+}
+function toEnvKey(key) {
+  return key.replace(/([A-Z])/g, "_$1").toUpperCase();
+}
+function replaceDatabaseName(connectionString, databaseName) {
+  let url;
+  try {
+    url = new URL(connectionString);
+  } catch {
+    throw new ParamError(
+      `Db: cannot parse connection string to derive a sibling database from it`
+    );
+  }
+  url.pathname = `/${databaseName}`;
+  return url.toString();
+}
 function resolveDbDisplayName(dbName, connectionParam, argsEnv, mergedName) {
   if (dbName) {
     return dbName;
@@ -5754,29 +6128,90 @@ function queueToTableNames(queueName) {
     registryTable: `${queueName}_services_registry`
   };
 }
-function defineTasksTable(t, db, tableNameForIndex) {
-  t.uuid("id").primary().defaultTo(db.raw("uuid_generate_v4()"));
-  t.timestamp("created_at").notNullable().defaultTo(db.fn.now());
-  t.timestamp("started_at");
-  t.timestamp("completed_at");
-  t.integer("priority").notNullable().defaultTo(50);
-  t.text("schedule");
-  t.timestamp("next_run_at").defaultTo(null);
-  t.timestamp("past_due").defaultTo(null);
-  t.text("name").notNullable();
-  t.text("opid");
-  t.jsonb("params");
-  t.text("service_group");
-  t.integer("instance_number");
-  t.text("service_name");
-  t.text("server_name");
-  t.text("status").notNullable().defaultTo("idle");
-  t.timestamp("status_changed_at").defaultTo(null);
-  t.text("progress");
-  t.boolean("success");
-  t.jsonb("results");
-  t.index(["service_group", "status", "priority", "created_at"], `${tableNameForIndex}_claim_idx`);
-  t.index(["service_group", "name"], `${tableNameForIndex}_group_name_idx`);
+function tasksTableSpec(tableNameForIndex) {
+  return {
+    columns: {
+      id: (t, db) => t.uuid("id").primary().defaultTo(db.raw("uuid_generate_v4()")),
+      created_at: (t, db) => t.timestamp("created_at").notNullable().defaultTo(db.fn.now()),
+      started_at: (t) => t.timestamp("started_at"),
+      completed_at: (t) => t.timestamp("completed_at"),
+      /*
+       * Priority: lower number = claimed first (see claimNextRunnableTask: ORDER BY priority ASC).
+       * Suggested range 0–100: 0 = most urgent, 100 = least; default 50 for normal work.
+       */
+      priority: (t) => t.integer("priority").notNullable().defaultTo(50),
+      schedule: (t) => t.text("schedule"),
+      next_run_at: (t) => t.timestamp("next_run_at").defaultTo(null),
+      past_due: (t) => t.timestamp("past_due").defaultTo(null),
+      name: (t) => t.text("name").notNullable(),
+      opid: (t) => t.text("opid"),
+      params: (t) => t.jsonb("params"),
+      // those are target identifiers, kind of who is going to run a task.
+      service_group: (t) => t.text("service_group"),
+      // harvester, loader, photos, ...
+      instance_number: (t) => t.integer("instance_number"),
+      service_name: (t) => t.text("service_name"),
+      // that's a "<server_name>_<service_group>_<instance_number>"
+      server_name: (t) => t.text("server_name"),
+      // filled by runner when registering, auto.
+      status: (t) => t.text("status").notNullable().defaultTo("idle"),
+      // idle, running, completed, failed, paused
+      status_changed_at: (t) => t.timestamp("status_changed_at").defaultTo(null),
+      progress: (t) => t.text("progress"),
+      success: (t) => t.boolean("success"),
+      results: (t) => t.jsonb("results")
+    },
+    indexes: [
+      {
+        columns: ["service_group", "status", "priority", "created_at"],
+        name: `${tableNameForIndex}_claim_idx`
+      },
+      { columns: ["service_group", "name"], name: `${tableNameForIndex}_group_name_idx` }
+    ]
+  };
+}
+function registryTableSpec(registryTable) {
+  return {
+    columns: {
+      id: (t, db) => t.uuid("id").primary().defaultTo(db.raw("uuid_generate_v4()")),
+      queue_name: (t) => t.text("queue_name").notNullable(),
+      service_group: (t) => t.text("service_group").notNullable(),
+      // harvester, loader, photos, ...
+      instance_number: (t) => t.integer("instance_number").notNullable().defaultTo(1),
+      service_name: (t) => t.text("service_name").notNullable(),
+      // that's a "<server_name>_<service_group>_<instance_number>"
+      server_name: (t) => t.text("server_name").notNullable(),
+      // filled by runner when registering, auto.
+      pid: (t) => t.integer("pid"),
+      metadata: (t) => t.json("metadata"),
+      created_at: (t, db) => t.timestamp("created_at").notNullable().defaultTo(db.fn.now()),
+      last_seen_at: (t, db) => t.timestamp("last_seen_at").notNullable().defaultTo(db.fn.now())
+    },
+    indexes: [
+      {
+        columns: ["queue_name", "service_name"],
+        name: `${registryTable}_queue_name_service_name_uniq`,
+        unique: true
+      },
+      {
+        columns: ["queue_name", "service_group", "last_seen_at"],
+        name: `${registryTable}_queue_group_seen_idx`
+      },
+      { columns: ["queue_name", "last_seen_at"], name: `${registryTable}_queue_seen_idx` }
+    ]
+    // TODO: a reference is needed - task_history entry should reference the registry entry, so that we can easily find all executed tasks for a given service and calculate the average workload or identify if there's a bottleneck. Also may be used for the load balancing.
+  };
+}
+function tasksSchemaSpec(queueName = "tasks") {
+  const { tasksTable, historyTable, registryTable } = queueToTableNames(queueName);
+  return {
+    extensions: ["uuid-ossp"],
+    tables: {
+      [tasksTable]: tasksTableSpec(tasksTable),
+      [historyTable]: tasksTableSpec(historyTable),
+      [registryTable]: registryTableSpec(registryTable)
+    }
+  };
 }
 function taskHistoryInsertFromQueueRow(row, overrides) {
   const { id, ...snapshot } = row;
@@ -5790,60 +6225,38 @@ async function ensureTaskTables(context, options = {}) {
   const queueName = options.queueName ?? "tasks";
   const recreate = options.recreate ?? false;
   const dryRun = options.dryRun ?? false;
-  const db = getDb(context);
+  const databases = options.databases ?? [getDb(context)];
   const log = context.logger ?? console;
   const { tasksTable, historyTable, registryTable } = queueToTableNames(queueName);
-  const needsTasks = recreate ? true : !await db.tableExists(tasksTable);
-  const needsHistory = recreate ? true : !await db.tableExists(historyTable);
-  const needsRegistry = recreate ? true : !await db.tableExists(registryTable);
-  if (dryRun) {
-    const plan = [];
+  const spec = tasksSchemaSpec(queueName);
+  for (const db of databases) {
+    const label = db?.config?.name ?? "db";
     if (recreate) {
-      plan.push(`DROP TABLE IF EXISTS ${historyTable}, ${tasksTable}, ${registryTable}`);
+      if (dryRun) {
+        log.info?.(
+          `[tasks-schema] dryRun \u2014 ${label}: DROP TABLE IF EXISTS ${historyTable}, ${tasksTable}, ${registryTable}`
+        );
+      } else {
+        await db.schema.dropTableIfExists(historyTable);
+        await db.schema.dropTableIfExists(tasksTable);
+        await db.schema.dropTableIfExists(registryTable);
+      }
     }
-    if (needsTasks) plan.push(`CREATE TABLE ${tasksTable} (tasks queue)`);
-    if (needsHistory) plan.push(`CREATE TABLE ${historyTable} (history mirror)`);
-    if (needsRegistry) plan.push(`CREATE TABLE ${registryTable} (services registry)`);
-    if (plan.length === 0) {
-      log.info?.(`[tasks-schema] dryRun \u2014 queue "${queueName}" already up to date; no DDL`);
-    } else {
-      log.info?.(`[tasks-schema] dryRun \u2014 would run ${plan.length} statement(s) for queue "${queueName}":`);
-      for (const s of plan) log.info?.(`  - ${s}`);
+    const { actions } = await ensureSchema(db, spec, { dryRun, logger: context.logger });
+    if (dryRun) {
+      if (actions.length === 0) {
+        log.info?.(`[tasks-schema] dryRun \u2014 ${label}: queue "${queueName}" already up to date; no DDL`);
+      } else {
+        log.info?.(
+          `[tasks-schema] dryRun \u2014 ${label}: would run ${actions.length} statement(s) for queue "${queueName}":`
+        );
+        for (const s of actions) log.info?.(`  - ${s}`);
+      }
+    } else if (actions.length > 0) {
+      log.info?.(
+        `[tasks-schema] ${label}: applied ${actions.length} DDL statement(s) for queue "${queueName}"`
+      );
     }
-    return;
-  }
-  if (recreate) {
-    await db.schema.dropTableIfExists(historyTable);
-    await db.schema.dropTableIfExists(tasksTable);
-    await db.schema.dropTableIfExists(registryTable);
-  }
-  if (needsTasks) {
-    await db.raw(`CREATE EXTENSION IF NOT EXISTS "uuid-ossp"`);
-    await db.schema.createTable(tasksTable, (t) => {
-      defineTasksTable(t, db, tasksTable);
-    });
-  }
-  if (needsHistory) {
-    await db.schema.createTable(historyTable, (t) => {
-      defineTasksTable(t, db, historyTable);
-    });
-  }
-  if (needsRegistry) {
-    await db.schema.createTable(registryTable, (t) => {
-      t.uuid("id").primary().defaultTo(db.raw("uuid_generate_v4()"));
-      t.text("queue_name").notNullable();
-      t.text("service_group").notNullable();
-      t.integer("instance_number").notNullable().defaultTo(1);
-      t.text("service_name").notNullable();
-      t.text("server_name").notNullable();
-      t.integer("pid");
-      t.json("metadata");
-      t.timestamp("created_at").notNullable().defaultTo(db.fn.now());
-      t.timestamp("last_seen_at").notNullable().defaultTo(db.fn.now());
-      t.unique(["queue_name", "service_name"], `${registryTable}_queue_name_service_name_uniq`);
-      t.index(["queue_name", "service_group", "last_seen_at"], `${registryTable}_queue_group_seen_idx`);
-      t.index(["queue_name", "last_seen_at"], `${registryTable}_queue_seen_idx`);
-    });
   }
 }
 async function enqueueTask(context, options) {
@@ -8002,8 +8415,13 @@ export {
   enqueueTask,
   ensureDeployKeyOnRemote,
   ensureEnvOnRemote,
+  ensureExtension,
+  ensureIndex,
   ensureRemoteRepo,
   ensureRepoDependencies,
+  ensureSchema,
+  ensureSchemaEverywhere,
+  ensureTable,
   ensureTaskTables,
   flushTaskIpcLogs,
   getArgsInstance,
@@ -8042,6 +8460,7 @@ export {
   releaseDir,
   releaseStamp,
   reloadPm2,
+  replaceDatabaseName,
   resolveAsterisks,
   resolveIpcFileLogsDir,
   resolveNextVersion,