@celilo/cli 0.5.0-alpha.1 → 0.5.0-alpha.11

package/src/cli/index.ts

@@ -10,6 +10,7 @@ import { COMMANDS, type CommandDef } from './command-registry';
 import { handleCapabilityInfo } from './commands/capability-info';
 import { handleCapabilityList } from './commands/capability-list';
 import { handleCompletion } from './commands/completion';
+import { handleDnsRegistrations } from './commands/dns';
 import {
   handleEventsAck,
   handleEventsDrain,
@@ -21,6 +22,7 @@ import {
   handleEventsRepair,
   handleEventsReply,
   handleEventsRespond,
+  handleEventsResyncSubscriptions,
   handleEventsRun,
   handleEventsRunHook,
   handleEventsShowDaemon,
@@ -64,6 +66,7 @@ import { handleModuleTypesCheck, handleModuleTypesGenerate } from './commands/mo
 import { handleModuleUpgrade } from './commands/module-upgrade';
 import { moduleVerify } from './commands/module-verify';
 import { handlePackage } from './commands/package';
+import { handleProxmoxNodeList } from './commands/proxmox-node-list';
 import { main as runPublish } from './commands/publish';
 import { handleSecretList } from './commands/secret-list';
 import { handleSecretSet } from './commands/secret-set';
@@ -87,6 +90,7 @@ import { handleSystemAudit } from './commands/system-audit';
 import { handleSystemConfigGet, handleSystemConfigSet } from './commands/system-config';
 import { handleSystemDoctor } from './commands/system-doctor';
 import { handleSystemInit } from './commands/system-init';
+import { handleSystemMigrate } from './commands/system-migrate';
 import { handleSystemSecretGet } from './commands/system-secret-get';
 import { handleSystemSecretSet } from './commands/system-secret-set';
 import { handleSystemUpdate } from './commands/system-update';
@@ -162,6 +166,7 @@ Commands:
   audit                    Top-level alias for 'system audit'
   events                   SQLite event-bus operations (status, tail, run dispatcher, etc.)
   capability               View registered module capabilities
+  dns                      View DNS bookkeeping (registrations ledger)
   package                  Create distributable .netapp packages from module source
   module                   Manage modules (import, list, configure, build, generate)
   service                  Manage container services (Proxmox, Digital Ocean)
@@ -171,6 +176,7 @@ Commands:
   machine                  Manage machine pool (bring-your-own-hardware)
   system                   Manage system configuration
   ipam                     Manage IP address and VMID allocations and reservations
+  proxmox                  Proxmox cluster introspection (proxmox node list)
   publish                  Publish workspace packages to npm and modules to celilo.computer
   subscribers              Manage build-bus subscribers (cross-machine publish-event delivery)
   completion               Generate shell completion scripts (bash/zsh)
@@ -255,6 +261,7 @@ Subcommands:
   status                       Print bus health as JSON
   tail [--type T] [--limit N]  Recent events as JSON
   list-subscribers             List persistent bus subscribers
+  resync-subscriptions         Rebuild subscribers from deployed modules' manifests (after a restore/migration)
   list-pending [--subscriber]  List pending deliveries
   drain [--concurrency N]      Process pending deliveries once and return
   run [--poll-ms N]            Run the long-running dispatcher (foreground)
@@ -265,9 +272,9 @@ Subcommands:
   repair                       Crash-recovery sweep without starting the dispatcher
   resume                       Alias for repair (acknowledges halt-on-recovery)
   respond                      Run the terminal responder; answer deploy prompts from another shell
-  install-daemon               Write a systemd/launchd user unit for the dispatcher
-  uninstall-daemon             Remove the installed supervisor unit
-  show-daemon                  Print the currently installed unit file
+  install-daemon [--system]    Write a systemd/launchd unit for the dispatcher (--system: management-plane scope)
+  uninstall-daemon [--system]  Remove the installed supervisor unit
+  show-daemon [--system]       Print the currently installed unit file
 
 Description:
   The event bus is a SQLite-backed pub/sub layer for celilo modules.
@@ -282,7 +289,7 @@ Examples:
   celilo events tail --type deploy.completed.lunacycle   # filter by type
   celilo events emit deploy.completed.lunacycle '{}'     # operator-fired event
   celilo events tail --type 'config.required.*'          # see pending deploy questions
-  celilo events reply 42 '"lunacycle.net"'               # answer query #42 (config)
+  celilo events reply 42 '"example.net"'               # answer query #42 (config)
 `;
   return { success: true, message: helpText.trim() };
 }
@@ -380,6 +387,32 @@ Related Commands:
   };
 }
 
+function displayDnsHelp(): CommandResult {
+  const helpText = `
+Celilo - DNS Bookkeeping
+
+Usage:
+  celilo dns <subcommand> [options]
+
+Subcommands:
+  registrations           List the DNS registration ledger
+
+Description:
+  Every successful dns_registrar.registerHost (e.g. a deploy registering
+  its public hostname with namecheap) is recorded in the registration
+  ledger. The provider's refresh_registrations hook re-asserts these on
+  a timer; REFRESHED shows when that last succeeded.
+
+Options:
+  --provider <module-id>  Only show registrations owned by one provider
+
+Examples:
+  celilo dns registrations
+  celilo dns registrations --provider namecheap
+`;
+  return { success: true, message: helpText };
+}
+
 function displayCapabilityHelp(): CommandResult {
   const helpText = `
 Celilo - Capability Management
@@ -1060,7 +1093,7 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
           '',
           'Examples:',
           '  celilo hook run namecheap validate_config --debug',
-          '  celilo hook run namecheap container_created vps_ip=138.68.140.177',
+          '  celilo hook run namecheap container_created vps_ip=192.0.2.30',
         ].join('\n'),
       };
     }
@@ -1075,6 +1108,28 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
     };
   }
 
+  if (parsed.command === 'dns') {
+    if (parsed.flags.help || parsed.flags.h) {
+      return displayDnsHelp();
+    }
+
+    if (!parsed.subcommand) {
+      return {
+        success: false,
+        error: 'DNS subcommand required\n\nRun "celilo dns --help" for usage',
+      };
+    }
+
+    if (parsed.subcommand === 'registrations') {
+      return handleDnsRegistrations(parsed.args, parsed.flags);
+    }
+
+    return {
+      success: false,
+      error: `Unknown dns subcommand: ${parsed.subcommand}\n\nRun "celilo dns --help" for usage`,
+    };
+  }
+
   if (parsed.command === 'capability') {
     if (parsed.flags.help || parsed.flags.h) {
       return displayCapabilityHelp();
@@ -1144,6 +1199,8 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
         return handleEventsTail(parsed.args, parsed.flags);
       case 'list-subscribers':
         return handleEventsListSubscribers();
+      case 'resync-subscriptions':
+        return handleEventsResyncSubscriptions();
       case 'list-pending':
         return handleEventsListPending(parsed.args, parsed.flags);
       case 'drain':
@@ -1168,9 +1225,9 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
       case 'install-daemon':
         return handleEventsInstallDaemon(parsed.args, parsed.flags);
       case 'uninstall-daemon':
-        return handleEventsUninstallDaemon();
+        return handleEventsUninstallDaemon(parsed.args, parsed.flags);
       case 'show-daemon':
-        return handleEventsShowDaemon();
+        return handleEventsShowDaemon(parsed.args, parsed.flags);
       default:
         return {
           success: false,
@@ -1729,12 +1786,39 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
       return handleSystemDoctor(parsed.args, parsed.flags);
     }
 
+    if (parsed.subcommand === 'migrate') {
+      return handleSystemMigrate();
+    }
+
     return {
       success: false,
       error: `Unknown system subcommand: ${parsed.subcommand}\n\nRun "celilo system --help" for usage`,
     };
   }
 
+  if (parsed.command === 'proxmox') {
+    if (!parsed.subcommand) {
+      return {
+        success: false,
+        error: 'Proxmox subcommand required (node)\n\nRun "celilo proxmox --help" for usage',
+      };
+    }
+    if (parsed.subcommand === 'node') {
+      const nodeSubcommand = parsed.args[0];
+      if (nodeSubcommand === 'list') {
+        return handleProxmoxNodeList(parsed.args.slice(1), parsed.flags);
+      }
+      return {
+        success: false,
+        error: 'Proxmox node action required (list)\n\nRun "celilo proxmox --help" for usage',
+      };
+    }
+    return {
+      success: false,
+      error: `Unknown proxmox subcommand: ${parsed.subcommand}\n\nRun "celilo proxmox --help" for usage`,
+    };
+  }
+
   if (parsed.command === 'ipam') {
     // Handle ipam --help
     if (parsed.flags.help || parsed.flags.h) {

package/src/cli/service-credential.ts

@@ -0,0 +1,54 @@
+/**
+ * Service-credential secret resolution (ISS-0127, D7).
+ *
+ * Service credentials (a Proxmox API token, a DigitalOcean API token, an SSH
+ * password) are a special kind of secret: at `service add` time the service
+ * does not exist yet, so there is no encrypted store to write the value to
+ * out-of-band and no safe sink for a bus reply. Per design decision D7 these
+ * secrets therefore travel by **flag or env var**, never over the event bus.
+ *
+ * The resolution order is: explicit `--<flag>` → `$ENV` → (only when stdin is
+ * a TTY) a local clack `password` prompt → otherwise a fail-fast error naming
+ * the flag and env var. This keeps a zero-TTY `service add` possible while the
+ * credential never lands on the bus, and the local password prompt is the one
+ * clack input the recurrence gate (D6) allow-lists — precisely because a
+ * flag/env path always exists alongside it.
+ */
+
+import { promptPassword } from './prompts';
+
+export interface ServiceCredentialSpec {
+  /** Human-readable field name used in the prompt + error, e.g. "API token secret". */
+  field: string;
+  /** The flag value (already resolved from `flags[<flag>]`), if the operator passed `--<flag>`. */
+  flagValue: string | boolean | undefined;
+  /** The CLI flag the operator would pass, e.g. `api-token-secret`. */
+  flag: string;
+  /** The environment variable that supplies the value headlessly, e.g. `PROXMOX_API_TOKEN_SECRET`. */
+  envVar: string;
+}
+
+/**
+ * Resolve a service-credential secret from flag → env → (TTY) clack password →
+ * error. Returns the secret value as a string. Throws an actionable error when
+ * no value is available on a non-TTY run.
+ */
+export async function resolveServiceCredential(spec: ServiceCredentialSpec): Promise<string> {
+  if (typeof spec.flagValue === 'string' && spec.flagValue.trim() !== '') {
+    return spec.flagValue.trim();
+  }
+
+  const fromEnv = process.env[spec.envVar];
+  if (fromEnv && fromEnv.trim() !== '') {
+    return fromEnv.trim();
+  }
+
+  if (process.stdin.isTTY) {
+    return promptPassword({
+      message: `${spec.field}:`,
+      validate: (val) => (!val || val.trim() === '' ? `${spec.field} is required` : undefined),
+    });
+  }
+
+  throw new Error(`${spec.field} required: pass --${spec.flag} or set $${spec.envVar} (no TTY)`);
+}

package/src/config/paths.test.ts

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { skipIntegration } from '../test-utils/integration-guard';
 import { getDataDir, getDbPath, getMasterKeyPath, getModuleStoragePath } from './paths';
 
 describe('paths configuration', () => {
@@ -34,18 +35,21 @@ describe('paths configuration', () => {
       expect(path).toMatch(/celilo-data\/modules$/);
     });
 
-    it('returns platform-specific path by default', () => {
-      process.env.CELILO_DATA_DIR = undefined;
-      process.env.ENVIRONMENT = undefined;
+    it.skipIf(skipIntegration({ platform: 'darwin' }))(
+      'returns platform-specific path by default',
+      () => {
+        process.env.CELILO_DATA_DIR = undefined;
+        process.env.ENVIRONMENT = undefined;
 
-      const path = getModuleStoragePath();
+        const path = getModuleStoragePath();
 
-      if (process.platform === 'darwin') {
-        expect(path).toMatch(/Library\/Application Support\/celilo\/modules$/);
-      } else {
-        expect(path).toBe('/var/lib/celilo/modules');
-      }
-    });
+        if (process.platform === 'darwin') {
+          expect(path).toMatch(/Library\/Application Support\/celilo\/modules$/);
+        } else {
+          expect(path).toBe('/var/lib/celilo/modules');
+        }
+      },
+    );
 
     it('prioritizes CELILO_DATA_DIR over ENVIRONMENT=dev', () => {
       process.env.CELILO_DATA_DIR = '/custom/data';
@@ -73,18 +77,21 @@ describe('paths configuration', () => {
       expect(path).toMatch(/celilo-data$/);
     });
 
-    it('returns platform-specific path by default', () => {
-      process.env.CELILO_DATA_DIR = undefined;
-      process.env.ENVIRONMENT = undefined;
-
-      const path = getDataDir();
-
-      if (process.platform === 'darwin') {
-        expect(path).toMatch(/Library\/Application Support\/celilo$/);
-      } else {
-        expect(path).toBe('/var/lib/celilo');
-      }
-    });
+    it.skipIf(skipIntegration({ platform: 'darwin' }))(
+      'returns platform-specific path by default',
+      () => {
+        process.env.CELILO_DATA_DIR = undefined;
+        process.env.ENVIRONMENT = undefined;
+
+        const path = getDataDir();
+
+        if (process.platform === 'darwin') {
+          expect(path).toMatch(/Library\/Application Support\/celilo$/);
+        } else {
+          expect(path).toBe('/var/lib/celilo');
+        }
+      },
+    );
   });
 
   describe('getMasterKeyPath', () => {
@@ -103,19 +110,22 @@ describe('paths configuration', () => {
       expect(path).toBe('/custom/data/master.key');
     });
 
-    it('uses platform-specific data dir by default', () => {
-      process.env.CELILO_MASTER_KEY_PATH = undefined;
-      process.env.CELILO_DATA_DIR = undefined;
-      process.env.ENVIRONMENT = undefined;
-
-      const path = getMasterKeyPath();
-
-      if (process.platform === 'darwin') {
-        expect(path).toMatch(/Library\/Application Support\/celilo\/master\.key$/);
-      } else {
-        expect(path).toBe('/var/lib/celilo/master.key');
-      }
-    });
+    it.skipIf(skipIntegration({ platform: 'darwin' }))(
+      'uses platform-specific data dir by default',
+      () => {
+        process.env.CELILO_MASTER_KEY_PATH = undefined;
+        process.env.CELILO_DATA_DIR = undefined;
+        process.env.ENVIRONMENT = undefined;
+
+        const path = getMasterKeyPath();
+
+        if (process.platform === 'darwin') {
+          expect(path).toMatch(/Library\/Application Support\/celilo\/master\.key$/);
+        } else {
+          expect(path).toBe('/var/lib/celilo/master.key');
+        }
+      },
+    );
   });
 
   describe('getDbPath', () => {
@@ -128,19 +138,22 @@ describe('paths configuration', () => {
       expect(path).toBe('/custom/path/celilo.db');
     });
 
-    it('returns data dir + celilo.db on macOS in production', () => {
-      process.env.CELILO_DB_PATH = undefined;
-      process.env.CELILO_DATA_DIR = undefined;
-      process.env.ENVIRONMENT = undefined;
-
-      const path = getDbPath();
-
-      if (process.platform === 'darwin') {
-        expect(path).toMatch(/Library\/Application Support\/celilo\/celilo.db$/);
-      } else {
-        expect(path).toBe('/var/lib/celilo/celilo.db');
-      }
-    });
+    it.skipIf(skipIntegration({ platform: 'darwin' }))(
+      'returns data dir + celilo.db on macOS in production',
+      () => {
+        process.env.CELILO_DB_PATH = undefined;
+        process.env.CELILO_DATA_DIR = undefined;
+        process.env.ENVIRONMENT = undefined;
+
+        const path = getDbPath();
+
+        if (process.platform === 'darwin') {
+          expect(path).toMatch(/Library\/Application Support\/celilo\/celilo.db$/);
+        } else {
+          expect(path).toBe('/var/lib/celilo/celilo.db');
+        }
+      },
+    );
 
     it('returns celilo-data/celilo.db in development mode', () => {
       process.env.CELILO_DB_PATH = undefined;

package/src/db/client.ts

@@ -41,145 +41,6 @@ export function findMigrationsFolder(): string {
   throw new Error(`Could not find drizzle migrations folder. Tried: ${candidates.join(', ')}`);
 }
 
-/**
- * Check if database needs initialization (tables don't exist)
- */
-function needsMigration(sqlite: Database): boolean {
-  try {
-    // Check if the modules table exists at all (new database)
-    const result = sqlite
-      .query("SELECT name FROM sqlite_master WHERE type='table' AND name='modules'")
-      .get();
-    if (!result) return true; // New database — run full migrations
-
-    // Existing database — apply incremental schema updates
-    // Each statement is wrapped in try/catch (no-op if already applied)
-    const alterStatements = [
-      'ALTER TABLE capabilities ADD zones text',
-      'ALTER TABLE machines ADD earmarked_module text',
-      // web_routes' subdomain/custom_domain columns were folded into a
-      // single `hostname` field by migration 0004. Don't re-add them
-      // here — the migration drops and recreates the table.
-      // Backup system tables (Phase 1)
-      `CREATE TABLE IF NOT EXISTS backup_storages (
-        id text PRIMARY KEY NOT NULL,
-        storage_id text NOT NULL UNIQUE,
-        name text NOT NULL,
-        provider_name text NOT NULL,
-        credentials_encrypted text NOT NULL,
-        provider_config text NOT NULL,
-        verified integer DEFAULT 0 NOT NULL,
-        verified_at integer,
-        verification_error text,
-        is_default integer DEFAULT 0 NOT NULL,
-        created_at integer DEFAULT (unixepoch()) NOT NULL,
-        updated_at integer DEFAULT (unixepoch()) NOT NULL
-      )`,
-      `CREATE TABLE IF NOT EXISTS backups (
-        id text PRIMARY KEY NOT NULL,
-        module_id text REFERENCES modules(id) ON DELETE SET NULL,
-        storage_id text NOT NULL REFERENCES backup_storages(id),
-        storage_path text NOT NULL,
-        backup_type text NOT NULL,
-        module_version text,
-        schema_version text,
-        size_bytes integer,
-        metadata text DEFAULT '{}' NOT NULL,
-        status text DEFAULT 'in_progress' NOT NULL,
-        error_message text,
-        started_at integer DEFAULT (unixepoch()) NOT NULL,
-        completed_at integer
-      )`,
-      // Backup naming support
-      'ALTER TABLE backups ADD name text',
-      // Module systems (v2/MODULE_SYSTEMS_ADDRESSING.md) — a module's 0..N
-      // deployed hosts. Fresh DBs get this via migration 0007; existing installs
-      // get it here. Replaces the scalar target_ip/vmid rows in module_configs.
-      `CREATE TABLE IF NOT EXISTS module_systems (
-        module_id text NOT NULL REFERENCES modules(id) ON DELETE cascade,
-        name text NOT NULL,
-        hostname text NOT NULL,
-        ipv4_address text NOT NULL,
-        zone text NOT NULL,
-        infra_type text NOT NULL,
-        machine_id text REFERENCES machines(id),
-        service_id text REFERENCES container_services(id),
-        vmid integer,
-        created_at integer DEFAULT (unixepoch()) NOT NULL,
-        updated_at integer DEFAULT (unixepoch()) NOT NULL,
-        PRIMARY KEY (module_id, name)
-      )`,
-      // Aspect consent decision (ISS-0027). Fresh DBs get this via migration
-      // 0008; existing installs get it here. Defaults to true so pre-existing
-      // rows (all approvals) keep running; false = a durable refusal.
-      'ALTER TABLE aspect_approvals ADD consented integer DEFAULT true NOT NULL',
-    ];
-
-    for (const stmt of alterStatements) {
-      try {
-        sqlite.exec(stmt);
-      } catch {
-        // Column already exists — fine
-      }
-    }
-
-    // web_routes hostname migration (CADDY_HOSTNAME_LIST design).
-    // Drizzle's auto-migrate path (`migrate()`) only runs for fresh
-    // databases — for existing celilo installs we apply the schema
-    // change here. Phase 0 + no production users = destructive
-    // rebuild; modules repopulate routes on their next deploy.
-    try {
-      const cols = sqlite.query("SELECT name FROM pragma_table_info('web_routes')").all() as Array<{
-        name: string;
-      }>;
-      const hasHostname = cols.some((c) => c.name === 'hostname');
-      const hasOldColumns = cols.some((c) => c.name === 'subdomain' || c.name === 'custom_domain');
-      if (!hasHostname && cols.length > 0) {
-        // Old shape detected (or missing hostname) — drop and recreate.
-        // Wrap in a transaction so the table is never half-migrated.
-        sqlite.exec('BEGIN');
-        try {
-          sqlite.exec('DROP TABLE web_routes');
-          sqlite.exec(`CREATE TABLE web_routes (
-            id integer PRIMARY KEY AUTOINCREMENT NOT NULL,
-            slug text NOT NULL,
-            module_id text NOT NULL,
-            type text NOT NULL,
-            path text NOT NULL,
-            hostname text NOT NULL,
-            target_host text,
-            target_port integer,
-            websocket integer DEFAULT false NOT NULL,
-            content_hash text,
-            created_at integer DEFAULT (unixepoch()) NOT NULL,
-            updated_at integer DEFAULT (unixepoch()) NOT NULL,
-            FOREIGN KEY (module_id) REFERENCES modules(id) ON UPDATE no action ON DELETE cascade
-          )`);
-          sqlite.exec(
-            'CREATE UNIQUE INDEX web_routes_hostname_path_idx ON web_routes (hostname, path)',
-          );
-          sqlite.exec('COMMIT');
-          if (hasOldColumns) {
-            console.log(
-              'web_routes migrated to hostname-based schema. Modules will repopulate their routes on next deploy.',
-            );
-          }
-        } catch (err) {
-          sqlite.exec('ROLLBACK');
-          throw err;
-        }
-      }
-    } catch (err) {
-      console.error('Failed to migrate web_routes schema:', err);
-      throw err;
-    }
-
-    return false; // Schema is up to date
-  } catch {
-    return true;
-  }
-}
-
 /**
  * Create database client and run migrations if needed
  */
@@ -209,12 +70,21 @@ export function createDbClient(config?: Partial<DatabaseConfig>) {
 
   const db = drizzle(sqlite, { schema });
 
-  // Auto-run migrations if database is new
-  if (!readonly && needsMigration(sqlite)) {
+  // Apply migrations on open (ISS-0100). Drizzle's migrator is the single
+  // migration mechanism for ALL DBs — fresh and existing — and the only place
+  // schema changes live (the old imperative hand-list is gone). migrate() is
+  // idempotent: it applies every migration newer than the latest recorded in
+  // `__drizzle_migrations` and no-ops once current.
+  //
+  // One-time caveat (ISS-0100): an existing DB from the hand-list era has a
+  // frozen `__drizzle_migrations` watermark; it must be remediated by hand
+  // (stamp the watermark to the latest migration + create any missing table)
+  // BEFORE this code opens it, or migrate() re-runs already-applied migrations
+  // and throws. `celilo system doctor` (checkSchemaDrift) detects the drift.
+  if (!readonly) {
     try {
       const migrationsFolder = findMigrationsFolder();
       migrate(db, { migrationsFolder });
-      console.log('Database initialized with migrations');
     } catch (error) {
       console.error('Failed to run migrations:', error);
       throw error;
@@ -222,10 +92,9 @@ export function createDbClient(config?: Partial<DatabaseConfig>) {
   }
 
   // One-time upgrade backfill for the target_ip → module_systems refactor
-  // (v2/MODULE_SYSTEMS_ADDRESSING.md). Runs for both paths above: needsMigration
-  // has already ensured the module_systems table exists (via migration 0007 for
-  // a fresh DB, or the imperative CREATE for an existing install). A deployment
-  // created before the refactor has its host data only in module_configs /
+  // (v2/MODULE_SYSTEMS_ADDRESSING.md). migrate() above has ensured the
+  // module_systems table exists (migration 0007). A deployment created before
+  // the refactor has its host data only in module_configs /
   // ip_allocations / module_infrastructure and an EMPTY module_systems, so its
   // modules resolve to no system and the migrated hooks throw "No deployed
   // system found". This lifts that state across. Idempotent (skips modules

package/src/db/migrate.ts

@@ -1,17 +1,25 @@
 import { migrate } from 'drizzle-orm/bun-sqlite/migrator';
-import { closeDb, createDbClient, findMigrationsFolder } from './client';
+import { type DbClient, closeDb, createDbClient, findMigrationsFolder } from './client';
 
 /**
- * Run database migrations
+ * Apply pending drizzle migrations to an open DB. Idempotent — drizzle applies
+ * only migrations newer than the latest recorded in `__drizzle_migrations`.
+ * The single migration mechanism (ISS-0100); createDbClient also calls this
+ * shape on open (auto-migrate).
+ */
+export function runMigrationsOn(db: DbClient): void {
+  migrate(db, { migrationsFolder: findMigrationsFolder() });
+}
+
+/**
+ * Run database migrations (standalone entrypoint — `bun run src/db/migrate.ts`).
+ * createDbClient already migrates on open; this re-asserts for explicit use.
  */
 export async function runMigrations(dbPath?: string) {
   console.log('Running database migrations...');
-
   const db = createDbClient(dbPath ? { path: dbPath } : undefined);
-
   try {
-    const migrationsFolder = findMigrationsFolder();
-    await migrate(db, { migrationsFolder });
+    runMigrationsOn(db);
     console.log('Migrations completed successfully');
   } catch (error) {
     console.error('Migration failed:', error);