@zintrust/core 0.1.26 → 0.1.28

package/src/cli/commands/MigrateCommand.ts

@@ -0,0 +1,435 @@
+/**
+ * Migrate Command
+ * Run database migrations
+ */
+
+import type { CommandOptions, IBaseCommand } from '@cli/BaseCommand';
+import { BaseCommand } from '@cli/BaseCommand';
+import { D1SqlMigrations } from '@cli/d1/D1SqlMigrations';
+import { WranglerConfig } from '@cli/d1/WranglerConfig';
+import { WranglerD1 } from '@cli/d1/WranglerD1';
+import { PromptHelper } from '@cli/PromptHelper';
+import {
+  confirmProductionRun,
+  mapConnectionToOrmConfig,
+  parseRollbackSteps,
+} from '@cli/utils/DatabaseCliUtils';
+import { readEnvString } from '@common/ExternalServiceUtils';
+import { databaseConfig } from '@config/database';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { Migrator } from '@migrations/Migrator';
+import * as path from '@node-singletons/path';
+import { Database } from '@orm/Database';
+import { DatabaseAdapterRegistry } from '@orm/DatabaseAdapterRegistry';
+import type { Command } from 'commander';
+
+const addMigrateOptions = (command: Command): void => {
+  command
+    .option('--status', 'Display migration status (applied, pending, failed)')
+    .option('--fresh', 'Reset database: drop all tables and re-run all migrations')
+    .option('--reset', 'Rollback all migrations to initial state')
+    .option('--rollback', 'Rollback last migration batch')
+    .option('--step <number>', 'Number of batches to rollback (use with --rollback)', '1')
+    .option('--force', 'Skip production confirmation (allow unsafe operations in production)')
+    .option('--service <domain/name>', 'Run global + service-specific migrations for microservices')
+    .option('--only-service <domain/name>', 'Run only service-specific migrations (exclude global)')
+    .option('--local', 'D1 only: run against local D1 database')
+    .option('--remote', 'D1 only: run against remote D1 database')
+    .option(
+      '--database <name>',
+      'D1 only: Wrangler D1 database binding name (not DB_DATABASE env var)'
+    )
+    .option('--all', 'Run migrations for all configured database connections')
+    .option('--no-interactive', 'Disable interactive prompts (useful for CI/CD)');
+};
+
+const getInteractive = (options: CommandOptions): boolean => options['interactive'] !== false;
+
+const getMigrationDirs = (): {
+  globalDir: string;
+  extension: string;
+  separateTracking: boolean;
+} => {
+  const globalDir = readEnvString('MIGRATIONS_GLOBAL_DIR', databaseConfig.migrations.directory);
+  const extension = databaseConfig.migrations.extension;
+  const separateTrackingRaw = readEnvString('MIGRATIONS_SEPARATE_TRACKING', '').trim();
+  const separateTracking =
+    separateTrackingRaw === '1' || separateTrackingRaw.toLowerCase() === 'true';
+  return { globalDir, extension, separateTracking };
+};
+
+const getServiceArgs = (
+  options: CommandOptions
+): { service: string | undefined; includeGlobal: boolean } => {
+  let serviceArg: string | undefined;
+
+  if (typeof options['onlyService'] === 'string') {
+    serviceArg = String(options['onlyService']);
+  } else if (typeof options['service'] === 'string') {
+    serviceArg = String(options['service']);
+  }
+
+  const includeGlobal = typeof options['onlyService'] !== 'string';
+  return { service: serviceArg, includeGlobal };
+};
+
+const isDestructiveAction = (options: CommandOptions): boolean =>
+  options['fresh'] === true || options['reset'] === true || options['rollback'] === true;
+
+const isD1Driver = (driver: string): boolean => driver === 'd1' || driver === 'd1-remote';
+
+const describeTargetDatabase = (conn: ReturnType<typeof databaseConfig.getConnection>): string => {
+  switch (conn.driver) {
+    case 'sqlite':
+      return `sqlite:${conn.database}`;
+    case 'postgresql':
+      return `postgresql:${conn.host}:${conn.port}/${conn.database}`;
+    case 'mysql':
+      return `mysql:${conn.host}:${conn.port}/${conn.database}`;
+    case 'sqlserver':
+      return `sqlserver:${conn.host}:${conn.port}/${conn.database}`;
+    default:
+      return `${conn.driver}`;
+  }
+};
+
+const printStatus = (
+  cmd: IBaseCommand,
+  rows: Array<{
+    name: string;
+    applied: boolean;
+    batch?: number | null;
+    status?: string | null;
+    appliedAt?: string | null;
+  }>
+): void => {
+  if (rows.length === 0) {
+    cmd.info('No migrations found.');
+    return;
+  }
+
+  for (const row of rows) {
+    const normalizedStatus = typeof row.status === 'string' ? row.status : null;
+    const tag = normalizedStatus ?? (row.applied ? 'applied' : 'pending');
+
+    const hasMeta =
+      normalizedStatus === 'completed' ||
+      normalizedStatus === 'failed' ||
+      normalizedStatus === 'running' ||
+      row.applied;
+    const extra = hasMeta ? ` (batch=${row.batch ?? '?'}, at=${row.appliedAt ?? '?'})` : '';
+
+    cmd.info(`${tag}: ${row.name}${extra}`);
+  }
+};
+
+const logAppliedMigrations = (cmd: IBaseCommand, appliedNames: ReadonlyArray<string>): void => {
+  cmd.info('Applied migrations:');
+  for (const name of appliedNames) {
+    cmd.info(`✓ ${name}`);
+  }
+};
+
+const handleStatusAction = async (
+  migrator: ReturnType<typeof Migrator.create>,
+  cmd: IBaseCommand,
+  driver: string
+): Promise<void> => {
+  cmd.info(`Adapter: ${driver}`);
+  const rows = await migrator.status();
+  printStatus(cmd, rows);
+};
+
+const handleFreshAction = async (
+  migrator: ReturnType<typeof Migrator.create>,
+  cmd: IBaseCommand,
+  interactive: boolean
+): Promise<void> => {
+  cmd.warn('This will drop all tables and re-run migrations.');
+  if (interactive) {
+    const confirmed = await PromptHelper.confirm('Continue?', false, interactive);
+    if (!confirmed) {
+      cmd.warn('Cancelled.');
+      return;
+    }
+  }
+
+  const result = await migrator.fresh();
+  cmd.success(`Fresh migration completed (applied=${result.applied})`);
+};
+
+const handleResetAction = async (
+  migrator: ReturnType<typeof Migrator.create>,
+  cmd: IBaseCommand,
+  interactive: boolean
+): Promise<void> => {
+  cmd.warn('This will rollback ALL migrations.');
+  if (interactive) {
+    const confirmed = await PromptHelper.confirm('Continue?', false, interactive);
+    if (!confirmed) {
+      cmd.warn('Cancelled.');
+      return;
+    }
+  }
+
+  const result = await migrator.resetAll();
+  cmd.success(`All migrations reset (rolledBack=${result.rolledBack})`);
+};
+
+const handleRollbackAction = async (
+  migrator: ReturnType<typeof Migrator.create>,
+  cmd: IBaseCommand,
+  options: CommandOptions
+): Promise<void> => {
+  const steps = parseRollbackSteps(options);
+  const result = await migrator.rollbackLastBatch(steps);
+  cmd.success(`Migrations rolled back (rolledBack=${result.rolledBack})`);
+};
+
+const handleMigrateAction = async (
+  migrator: ReturnType<typeof Migrator.create>,
+  cmd: IBaseCommand
+): Promise<void> => {
+  const result = await migrator.migrate();
+  if (result.applied === 0) {
+    cmd.success(`Migrations completed successfully (applied=${result.applied})`);
+    return;
+  }
+
+  const appliedNames = Array.isArray((result as { appliedNames?: unknown }).appliedNames)
+    ? ((result as { appliedNames?: unknown }).appliedNames as string[])
+    : [];
+
+  if (appliedNames.length > 0) {
+    logAppliedMigrations(cmd, appliedNames);
+  }
+  cmd.success(`Migrations completed successfully (applied=${result.applied})`);
+};
+
+const runMigratorActions = async (
+  migrator: ReturnType<typeof Migrator.create>,
+  options: CommandOptions,
+  cmd: IBaseCommand,
+  interactive: boolean,
+  driver: string
+): Promise<void> => {
+  if (options['status'] === true) {
+    await handleStatusAction(migrator, cmd, driver);
+    return;
+  }
+
+  if (options['fresh'] === true) {
+    await handleFreshAction(migrator, cmd, interactive);
+    return;
+  }
+
+  if (options['reset'] === true) {
+    await handleResetAction(migrator, cmd, interactive);
+    return;
+  }
+
+  if (options['rollback'] === true) {
+    await handleRollbackAction(migrator, cmd, options);
+    return;
+  }
+
+  await handleMigrateAction(migrator, cmd);
+};
+
+const runD1Actions = async (params: {
+  options: CommandOptions;
+  cmd: IBaseCommand;
+  projectRoot: string;
+  globalDir: string;
+  extension: string;
+  separateTracking: boolean;
+  service: string | undefined;
+  includeGlobal: boolean;
+}): Promise<void> => {
+  const {
+    options,
+    cmd,
+    projectRoot,
+    globalDir,
+    extension,
+    separateTracking,
+    service,
+    includeGlobal,
+  } = params;
+
+  if (
+    options['status'] === true ||
+    options['fresh'] === true ||
+    options['reset'] === true ||
+    options['rollback'] === true
+  ) {
+    throw ErrorFactory.createCliError(
+      'This project is configured for D1. Only applying migrations is supported here. Use `zin d1:migrate --local|--remote` (and Wrangler subcommands) for status/rollback/reset.'
+    );
+  }
+
+  if (separateTracking) {
+    cmd.warn('Note: MIGRATIONS_SEPARATE_TRACKING is ignored for D1 (Wrangler owns tracking).');
+  }
+
+  const isLocal = options['local'] === true || options['remote'] !== true;
+  const dbName =
+    typeof options['database'] === 'string' && options['database'].trim() !== ''
+      ? options['database']
+      : 'zintrust_db';
+
+  const migrationsRelDir = WranglerConfig.getD1MigrationsDir(projectRoot, dbName);
+  const outputDir = path.join(projectRoot, migrationsRelDir);
+
+  cmd.info(`Generating D1 SQL migrations into ${migrationsRelDir}...`);
+  const generated = await D1SqlMigrations.compileAndWrite({
+    projectRoot,
+    globalDir,
+    extension,
+    service,
+    includeGlobal,
+    outputDir,
+  });
+  cmd.info(`Generated ${generated.length} SQL migration file(s).`);
+
+  cmd.info(`Running D1 migrations for ${dbName} (${isLocal ? 'local' : 'remote'})...`);
+  const output = WranglerD1.applyMigrations({ cmd, dbName, isLocal });
+  if (output !== '') cmd.info(output);
+  cmd.success('D1 migrations completed successfully');
+};
+
+const processConnection = async (
+  conn: ReturnType<typeof databaseConfig.getConnection>,
+  options: CommandOptions,
+  cmd: IBaseCommand,
+  interactive: boolean
+): Promise<void> => {
+  // Avoid confusion: `--database` is a D1-only option (Wrangler binding name), not DB_DATABASE.
+  if (isD1Driver(conn.driver)) {
+    cmd.debug(`Migrate command executed with options: ${JSON.stringify(options)}`);
+  } else {
+    const optionsForLog: CommandOptions = { ...options };
+    delete optionsForLog['database'];
+    delete optionsForLog['local'];
+    delete optionsForLog['remote'];
+    cmd.debug(`Migrate command executed with options: ${JSON.stringify(optionsForLog)}`);
+  }
+
+  const { globalDir, extension, separateTracking } = getMigrationDirs();
+  const { service, includeGlobal } = getServiceArgs(options);
+
+  if (isD1Driver(conn.driver)) {
+    await runD1Actions({
+      options,
+      cmd,
+      projectRoot: process.cwd(),
+      globalDir,
+      extension,
+      separateTracking,
+      service,
+      includeGlobal,
+    });
+    return;
+  }
+
+  const ormConfig = mapConnectionToOrmConfig(conn);
+  const destructive = isDestructiveAction(options);
+  const force = options['force'] === true;
+
+  const okToProceed = await confirmProductionRun({
+    cmd,
+    interactive,
+    destructive,
+    force,
+    message: 'NODE_ENV=production. Continue running migrations?',
+  });
+  if (!okToProceed) return;
+
+  cmd.info(`[i] Target database: ${describeTargetDatabase(conn)}`);
+  cmd.info('[i] Migration tracking table: migrations');
+
+  cmd.debug(`[debug] Registered database adapters: ${DatabaseAdapterRegistry.list().join(', ')}`);
+
+  // Warn only when the adapter truly isn't registered.
+  // Adapters are registered via side-effect imports in src/zintrust.plugins.ts
+  // (generated by `zin plugin install`) and are loaded at CLI startup.
+  if (conn.driver === 'mysql' && DatabaseAdapterRegistry.get('mysql') === undefined) {
+    cmd.warn('MySQL adapter is not installed/registered; migrations may not hit a real MySQL DB.');
+    cmd.warn('Install via `zin plugin install adapter:mysql` (or `zin add db:mysql`).');
+    cmd.debug(
+      '[debug] Expected a side-effect import in src/zintrust.plugins.ts like: import "@zintrust/db-mysql/register";'
+    );
+  }
+  if (conn.driver === 'postgresql' && DatabaseAdapterRegistry.get('postgresql') === undefined) {
+    cmd.warn(
+      'PostgreSQL adapter is not installed/registered; migrations may not hit a real PostgreSQL DB.'
+    );
+    cmd.warn('Install via `zin plugin install adapter:postgres` (or `zin add db:postgres`).');
+  }
+
+  const db = Database.create(ormConfig);
+  await db.connect();
+  try {
+    const migrator = Migrator.create({
+      db,
+      projectRoot: process.cwd(),
+      globalDir,
+      extension,
+      separateTracking,
+      service,
+      includeGlobal,
+    });
+
+    await runMigratorActions(migrator, options, cmd, interactive, conn.driver);
+  } finally {
+    await db.disconnect();
+  }
+};
+
+const executeMigrate = async (options: CommandOptions, cmd: IBaseCommand): Promise<void> => {
+  const interactive = getInteractive(options);
+
+  const targets: Array<{ name: string; config: ReturnType<typeof databaseConfig.getConnection> }> =
+    [];
+
+  if (options['all'] === true) {
+    for (const [name, config] of Object.entries(databaseConfig.connections)) {
+      targets.push({ name, config });
+    }
+  } else {
+    targets.push({ name: 'default', config: databaseConfig.getConnection() });
+  }
+
+  // Run sequentially (to preserve ordering and interactive prompts), but avoid `await` inside a loop.
+  let sequence: Promise<void> = Promise.resolve();
+
+  for (const { name, config } of targets) {
+    sequence = sequence.then(async () => {
+      if (targets.length > 1) {
+        cmd.info(`\n--- Connection: ${name} (${config.driver}) ---`);
+      }
+      await processConnection(config, options, cmd, interactive);
+    });
+  }
+
+  await sequence;
+};
+
+/**
+ * Migrate Command Factory
+ */
+export const MigrateCommand = Object.freeze({
+  /**
+   * Create a new migrate command instance
+   */
+  create(): IBaseCommand {
+    const cmd: IBaseCommand = BaseCommand.create({
+      name: 'migrate',
+      description: 'Run database migrations',
+      addOptions: addMigrateOptions,
+      execute: async (options: CommandOptions): Promise<void> => executeMigrate(options, cmd),
+    });
+
+    return cmd;
+  },
+});

package/src/cli/commands/MigrateWorkerCommand.ts

@@ -0,0 +1,180 @@
+/**
+ * Migrate Worker Command
+ * Run worker package migrations
+ */
+
+import type { CommandOptions, IBaseCommand } from '@cli/BaseCommand';
+import { BaseCommand } from '@cli/BaseCommand';
+import {
+  confirmProductionRun,
+  mapConnectionToOrmConfig,
+  parseRollbackSteps,
+} from '@cli/utils/DatabaseCliUtils';
+import { databaseConfig } from '@config/database';
+import { Migrator } from '@migrations/Migrator';
+import * as path from '@node-singletons/path';
+import { Database } from '@orm/Database';
+import { DatabaseAdapterRegistry } from '@orm/DatabaseAdapterRegistry';
+import type { Command } from 'commander';
+
+const addOptions = (command: Command): void => {
+  command
+    .option('--status', 'Display migration status (applied, pending, failed)')
+    .option('--fresh', 'Reset database: drop all tables and re-run all migrations')
+    .option('--reset', 'Rollback all migrations to initial state')
+    .option('--rollback', 'Rollback last migration batch')
+    .option('--step <number>', 'Number of batches to rollback (use with --rollback)', '1')
+    .option('--force', 'Skip production confirmation (allow unsafe operations in production)')
+    .option('--all', 'Run migrations for all configured database connections')
+    .option('--no-interactive', 'Disable interactive prompts (useful for CI/CD)');
+};
+
+const getInteractive = (options: CommandOptions): boolean => options['interactive'] !== false;
+
+const isDestructiveAction = (options: CommandOptions): boolean =>
+  options['fresh'] === true || options['reset'] === true || options['rollback'] === true;
+
+const printStatus = async (
+  migrator: ReturnType<typeof Migrator.create>,
+  cmd: IBaseCommand
+): Promise<void> => {
+  const rows = await migrator.status();
+  if (rows.length === 0) {
+    cmd.info('No migrations found.');
+    return;
+  }
+  for (const row of rows) {
+    const tag = row.status ?? (row.applied ? 'applied' : 'pending');
+    const extra = row.applied ? ` (batch=${row.batch ?? '?'}, at=${row.appliedAt ?? '?'})` : '';
+    cmd.info(`${tag}: ${row.name}${extra}`);
+  }
+};
+
+const applyMigrations = async (
+  migrator: ReturnType<typeof Migrator.create>,
+  cmd: IBaseCommand
+): Promise<void> => {
+  const result = await migrator.migrate();
+  if (result.appliedNames.length === 0) {
+    cmd.info('No pending worker migrations.');
+    return;
+  }
+  cmd.success('Worker migrations applied.');
+  for (const name of result.appliedNames) {
+    cmd.info(`✓ ${name}`);
+  }
+};
+
+const runActions = async (
+  migrator: ReturnType<typeof Migrator.create>,
+  options: CommandOptions,
+  cmd: IBaseCommand,
+  driver: string
+): Promise<void> => {
+  if (options['status'] === true) {
+    cmd.info(`Adapter: ${driver}`);
+    await printStatus(migrator, cmd);
+    return;
+  }
+
+  if (options['fresh'] === true) {
+    await migrator.fresh();
+    cmd.success('Worker migrations applied (fresh).');
+    return;
+  }
+
+  if (options['reset'] === true) {
+    await migrator.resetAll();
+    cmd.success('Worker migrations reset.');
+    return;
+  }
+
+  if (options['rollback'] === true) {
+    const steps = parseRollbackSteps(options);
+    const result = await migrator.rollbackLastBatch(steps);
+    cmd.success(`Worker migrations rolled back (${result.rolledBack}).`);
+    return;
+  }
+
+  await applyMigrations(migrator, cmd);
+};
+
+const runForConnection = async (
+  conn: ReturnType<typeof databaseConfig.getConnection>,
+  options: CommandOptions,
+  cmd: IBaseCommand,
+  interactive: boolean
+): Promise<void> => {
+  const destructive = isDestructiveAction(options);
+  const proceed = await confirmProductionRun({
+    cmd,
+    interactive,
+    destructive,
+    force: options['force'] === true,
+    message: 'NODE_ENV=production. Continue running worker migrations?',
+  });
+  if (!proceed) return;
+
+  if (!DatabaseAdapterRegistry.has(conn.driver)) {
+    cmd.warn(`Missing adapter for driver: ${conn.driver}`);
+    cmd.warn('Install via `zin plugin install adapter:postgres` (or `zin add db:postgres`).');
+  }
+
+  const ormConfig = mapConnectionToOrmConfig(conn);
+  const db = Database.create(ormConfig);
+  await db.connect();
+
+  try {
+    const migrator = Migrator.create({
+      db,
+      projectRoot: process.cwd(),
+      globalDir: path.join(process.cwd(), 'packages', 'workers', 'migrations'),
+      extension: databaseConfig.migrations.extension,
+      separateTracking: true,
+    });
+
+    await runActions(migrator, options, cmd, conn.driver);
+  } finally {
+    await db.disconnect();
+  }
+};
+
+const executeMigrateWorker = async (options: CommandOptions, cmd: IBaseCommand): Promise<void> => {
+  const interactive = getInteractive(options);
+
+  const targets: Array<{ name: string; config: ReturnType<typeof databaseConfig.getConnection> }> =
+    [];
+
+  if (options['all'] === true) {
+    for (const [name, config] of Object.entries(databaseConfig.connections)) {
+      targets.push({ name, config });
+    }
+  } else {
+    targets.push({ name: 'default', config: databaseConfig.getConnection() });
+  }
+
+  let sequence: Promise<void> = Promise.resolve();
+  for (const { name, config } of targets) {
+    sequence = sequence.then(async () => {
+      if (targets.length > 1) {
+        cmd.info(`\n--- Connection: ${name} (${config.driver}) ---`);
+      }
+      await runForConnection(config, options, cmd, interactive);
+    });
+  }
+
+  await sequence;
+};
+
+export const MigrateWorkerCommand = Object.freeze({
+  create(): IBaseCommand {
+    const cmd: IBaseCommand = BaseCommand.create({
+      name: 'migrate:worker',
+      description: 'Run worker package migrations',
+      addOptions,
+      execute: async (options: CommandOptions): Promise<void> => executeMigrateWorker(options, cmd),
+    });
+
+    return cmd;
+  },
+});