@pasosdejesus/m 0.15.0

package/dist/tasks/db.js

@@ -0,0 +1,791 @@
+/// <reference types="node" />
+import { spawn, spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { problem, success, info, warn } from '../util/colors.js';
+import { createTranslator } from '../i18n/createTranslator.js';
+import { detectLocale } from '../util/locale.js';
+import commonCli from '../i18n/common-cli.js';
+const dbT = createTranslator(detectLocale(), {
+    en: {
+        'db.create_success': 'Database "{{0}}" created successfully.',
+        'db.create_failed': 'Failed to create database "{{0}}": {{1}}',
+        'db.drop_success': 'Database "{{0}}" dropped successfully.',
+        'db.drop_failed': 'Failed to drop database "{{0}}": {{1}}',
+        'db.super.credentials_missing': 'PGUSER or PGPASSWORD not defined in environment (.env)',
+        'db.super.superuser_env_missing': 'PG_SUPERUSER and PG_SUPERUSER_PASSWORD must be set in .env or .env.test.\n  Without superuser credentials, db:super:createuser cannot authenticate.\n  Add to apps/.env.test:\n    PG_SUPERUSER=postgres\n    PG_SUPERUSER_PASSWORD=\n  On OpenBSD/adJ the password is typically empty and authentication is via Unix socket + doas.',
+        'db.super.invalid_username': 'Username "{{0}}" contains invalid character "-". Use only letters, numbers, and underscores.',
+        'db.super.trying_mode': '[db:super:createuser] attempting mode={{0}}',
+        'db.super.role_exists': 'PostgreSQL role \'{{0}}\' already exists (continuing).',
+        'db.super.create_failed_mode': 'Creation failed in mode {{0}}: {{1}}',
+        'db.super.create_success': 'Superuser role \'{{0}}\' created.',
+        'db.super.password_failed_mode': 'Password change failed in mode {{0}}: {{1}}',
+        'db.super.password_success': 'Password for \'{{0}}\' set.',
+        'db.super.final_failure': 'Could not create superuser: {{0}}',
+        'db.console_starting': 'Opening console for database "{{0}}"...',
+        'db.console_querying': 'Executing query on database "{{0}}"...',
+        'db.console_closed': 'Console closed.',
+        'db.console_failed': 'Console failed: {{0}}',
+        'db.test_connection.start': 'Testing database connection...',
+        'db.test_connection.success': 'Database test successful.',
+        'db.test_connection.failed': 'Database test failed: {{0}}',
+        'db.structure.dump_start': 'Dumping structure to {{0}}...',
+        'db.structure.dump_success': 'Database structure dumped to {{0}}.',
+        'db.structure.dump_failed': 'Failed to dump structure: {{0}}: {{1}}',
+        'db.structure.load_not_found': 'Structure file not found: {{0}}',
+        'db.structure.load_start': 'Loading structure from {{0}}...',
+        'db.dropping_for_load': 'Dropping database "{{0}}" before loading structure...',
+        'db.creating_for_load': 'Creating database "{{0}}" before loading structure...',
+        'db.structure.load_success': 'Database structure loaded from {{0}}.',
+        'db.structure.load_failed': 'Failed to load structure: {{0}}: {{1}}',
+        'db.mig.make_start': 'Creating migration file {{0}}...',
+        'db.mig.make_success': 'Migration file created: {{0}}',
+        'db.mig.make_failed': 'Failed to create migration: {{0}}',
+        'db.migrate.start': 'Running migrations...',
+        'db.migrate.success': 'Migrations completed successfully.',
+        'db.migrate.failed': 'Migration failed: {{0}}',
+        'db.rollback.start': 'Rolling back last migration...',
+        'db.rollback.success': 'Migration rolled back successfully.',
+        'db.rollback.failed': 'Rollback failed: {{0}}',
+        'db.rollback.step': 'Rolling back {{0}} migration(s)...',
+        'db.rollback.step_success': '{{0}} migration(s) rolled back successfully.',
+        'db.dump.start': 'Backing up database to {{0}}...',
+        'db.dump.success': 'Database backed up to {{0}}.',
+        'db.dump.failed': 'Database backup failed: {{0}}: {{1}}',
+        'db.restore.start': 'Restoring database from {{0}}...',
+        'db.restore.success': 'Database restored from {{0}}.',
+        'db.restore.failed': 'Database restoration failed: {{0}}: {{1}}',
+        'db.restore.backup_not_found': 'Backup not found: {{0}}',
+        'db.restore.no_backups': 'No backups found in {{0}}.',
+        'db.restore.available': 'Available backups:',
+        'db.restore.list_item': '  {{0}}  ({{1}})',
+        'db.types.gen_start': 'Generating types...',
+        'db.types.gen_success': 'Types generated.',
+        'db.types.gen_failed': 'Type generation failed: {{0}}',
+    },
+    es: {
+        'db.create_success': 'Base de datos "{{0}}" creada exitosamente.',
+        'db.create_failed': 'Falló la creación de la base de datos "{{0}}": {{1}}',
+        'db.drop_success': 'Base de datos "{{0}}" eliminada exitosamente.',
+        'db.drop_failed': 'Falló la eliminación de la base de datos "{{0}}": {{1}}',
+        'db.super.credentials_missing': 'PGUSER o PGPASSWORD no están definidos en el entorno (.env)',
+        'db.super.superuser_env_missing': 'PG_SUPERUSER y PG_SUPERUSER_PASSWORD deben estar definidos en .env o .env.test.\n  Sin credenciales de superusuario, db:super:createuser no puede autenticarse.\n  Agregue en apps/.env.test:\n    PG_SUPERUSER=postgres\n    PG_SUPERUSER_PASSWORD=\n  En OpenBSD/adJ la contraseña típicamente es vacía y la autenticación es vía socket Unix + doas.',
+        'db.super.invalid_username': 'El nombre de usuario "{{0}}" contiene el carácter inválido "-". Usa solo letras, números y guiones bajos.',
+        'db.super.trying_mode': '[db:super:createuser] intentando modo={{0}}',
+        'db.super.role_exists': 'El rol de PostgreSQL \'{{0}}\' ya existe (continuando).',
+        'db.super.create_failed_mode': 'Falló la creación en modo {{0}}: {{1}}',
+        'db.super.create_success': 'Rol de superusuario \'{{0}}\' creado.',
+        'db.super.password_failed_mode': 'Falló el cambio de contraseña en modo {{0}}: {{1}}',
+        'db.super.password_success': 'Contraseña para \'{{0}}\' establecida.',
+        'db.super.final_failure': 'No se pudo crear el superusuario: {{0}}',
+        'db.console_starting': 'Abriendo consola para la base de datos "{{0}}"...',
+        'db.console_querying': 'Ejecutando consulta en la base de datos "{{0}}"...',
+        'db.console_closed': 'Consola cerrada.',
+        'db.console_failed': 'Falló la consola: {{0}}',
+        'db.test_connection.start': 'Probando la conexión a la base de datos...',
+        'db.test_connection.success': 'Prueba de base de datos exitosa.',
+        'db.test_connection.failed': 'Falló la prueba de la base de datos: {{0}}',
+        'db.structure.dump_start': 'Volcando estructura a {{0}}...',
+        'db.structure.dump_success': 'Estructura de la base de datos volcada a {{0}}.',
+        'db.structure.dump_failed': 'Falló el volcado de la estructura: {{0}}: {{1}}',
+        'db.structure.load_not_found': 'Archivo de estructura no encontrado: {{0}}',
+        'db.structure.load_start': 'Cargando estructura desde {{0}}...',
+        'db.dropping_for_load': 'Eliminando la base de datos "{{0}}" antes de cargar la estructura...',
+        'db.creating_for_load': 'Creando la base de datos "{{0}}" antes de cargar la estructura...',
+        'db.structure.load_success': 'Estructura de la base de datos cargada desde {{0}}.',
+        'db.structure.load_failed': 'Falló la carga de la estructura: {{0}}: {{1}}',
+        'db.mig.make_start': 'Creando archivo de migración {{0}}...',
+        'db.mig.make_success': 'Archivo de migración creado: {{0}}',
+        'db.mig.make_failed': 'Falló la creación de la migración: {{0}}',
+        'db.migrate.start': 'Ejecutando migraciones...',
+        'db.migrate.success': 'Migraciones completadas exitosamente.',
+        'db.migrate.failed': 'Falló la migración: {{0}}',
+        'db.rollback.start': 'Revirtiendo la última migración...',
+        'db.rollback.success': 'Migraciones revertidas exitosamente.',
+        'db.rollback.failed': 'Falló la reversión: {{0}}',
+        'db.rollback.step': 'Revirtiendo {{0}} migración(es)...',
+        'db.rollback.step_success': '{{0}} migración(es) revertidas exitosamente.',
+        'db.types.gen_start': 'Generando tipos...',
+        'db.types.gen_success': 'Tipos generados.',
+        'db.types.gen_failed': 'Falló la generación de tipos: {{0}}',
+    },
+}, commonCli);
+function pgConfig(withSuperUser = false) {
+    let h = {
+        database: process.env.PGDATABASE || 'msipn_dev',
+        host: process.env.PGHOST,
+        port: process.env.PGPORT,
+        password: withSuperUser ? process.env.PG_SUPERUSER_PASSWORD : process.env.PGPASSWORD,
+        user: withSuperUser ? process.env.PG_SUPERUSER : process.env.PGUSER
+    };
+    return h;
+}
+function buildDatabaseUrl(cfg) {
+    const user = cfg.user || process.env.PGUSER || 'postgres';
+    const password = cfg.password || process.env.PGPASSWORD || '';
+    const host = cfg.host || process.env.PGHOST || 'localhost';
+    const port = cfg.port || process.env.PGPORT || '5432';
+    const database = cfg.database || process.env.PGDATABASE;
+    if (!host || host.trim() === '') {
+        throw new Error('PGHOST vacío — configure PGHOST en .env.test (ej: /var/run/postgresql para socket Unix, o localhost para TCP)');
+    }
+    let url;
+    if (host.startsWith('/') || host.startsWith('./')) {
+        // Unix socket: encode the directory path as the host component.
+        // pg (node-postgres) interprets a path starting with / in the host as a socket dir.
+        url = `postgresql://${encodeURIComponent(user)}:${encodeURIComponent(password)}@${encodeURIComponent(host)}/${database}`;
+    }
+    else if (/^[a-zA-Z0-9]([a-zA-Z0-9.-]*[a-zA-Z0-9])?$/.test(host) || /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host)) {
+        // TCP/IP hostname or IPv4
+        url = `postgresql://${encodeURIComponent(user)}:${encodeURIComponent(password)}@${host}:${port}/${database}`;
+    }
+    else {
+        throw new Error(`PGHOST="${host}" no es un formato reconocido. Use ruta de socket Unix (/var/run/postgresql), nombre de host (localhost) o dirección IP.`);
+    }
+    // Validate the URL starts correctly (catch encoding bugs early)
+    if (!url.startsWith('postgresql://')) {
+        throw new Error(`DATABASE_URL mal formada: "${url.substring(0, 60)}..." — revise PGHOST, PGUSER, PGPASSWORD.`);
+    }
+    return url;
+}
+function buildEnvArgs(cfg) {
+    const env = {
+        PATH: process.env.PATH || '',
+    };
+    if (cfg.database)
+        env.PGDATABASE = cfg.database;
+    if (cfg.host)
+        env.PGHOST = cfg.host;
+    if (cfg.port)
+        env.PGPORT = cfg.port;
+    if (cfg.user)
+        env.PGUSER = cfg.user;
+    if (cfg.password)
+        env.PGPASSWORD = cfg.password;
+    // Add DATABASE_URL which is often expected by Kysely and other tools
+    env.DATABASE_URL = buildDatabaseUrl(cfg);
+    return env;
+}
+function psqlArgs(cfg, extra = []) {
+    const args = [];
+    if (cfg.host) {
+        args.push('-h', cfg.host);
+    }
+    if (cfg.port) {
+        args.push('-p', cfg.port);
+    }
+    if (cfg.user) {
+        args.push('-U', cfg.user);
+    }
+    return [...args, ...extra];
+}
+function getSpawnTimeoutMs() {
+    // PG_TIMEOUT (seconds) → milliseconds; default 30s if not set
+    const sec = process.env.PG_TIMEOUT ? parseInt(process.env.PG_TIMEOUT) : 30;
+    if (isNaN(sec) || sec <= 0)
+        return undefined;
+    return sec * 1000;
+}
+function run(cmd, args, env, quiet = false) {
+    const res = spawnSync(cmd, args, { stdio: ['inherit', 'inherit', 'pipe'], env, timeout: getSpawnTimeoutMs() });
+    if (res.status !== 0) {
+        const errorMsg = res.stderr ?
+            res.stderr.toString().trim() : `exit code ${res.status}`;
+        throw new Error(`${cmd} failed: ${errorMsg}`);
+    }
+    return res;
+}
+export async function runDbCreate() {
+    const t = dbT;
+    const cfg = pgConfig();
+    const env = buildEnvArgs(cfg);
+    try {
+        run('createdb', [cfg.database], env);
+        success(t('db.create_success', cfg.database));
+    }
+    catch (e) {
+        problem(t('db.create_failed', cfg.database, e.message));
+    }
+}
+export async function runDbDrop() {
+    const t = dbT;
+    const cfg = pgConfig();
+    const env = buildEnvArgs(cfg);
+    try {
+        run('dropdb', ['--if-exists', cfg.database], env);
+        success(t('db.drop_success', cfg.database));
+    }
+    catch (e) {
+        problem(t('db.drop_failed', cfg.database, e.message));
+    }
+}
+export async function runDbSuperCreateUser() {
+    const t = dbT;
+    const cfg = pgConfig();
+    const defaultSystemUser = os.platform() === 'openbsd' ?
+        '_postgresql' : 'postgres';
+    const pgsystemuser = process.env.PGSYSTEMUSER || defaultSystemUser;
+    const user = cfg.user;
+    const pass = cfg.password;
+    const host = cfg.host;
+    if (!user || pass === undefined) {
+        problem(t('db.super.credentials_missing'));
+        return;
+    }
+    // On OpenBSD/adJ, PG_SUPERUSER_PASSWORD is often empty (Unix socket auth).
+    // If both PG_SUPERUSER and PG_SUPERUSER_PASSWORD are undefined, the command
+    // will hang waiting for a password prompt. Fail early with a diagnostic.
+    if (process.env.PG_SUPERUSER === undefined || process.env.PG_SUPERUSER_PASSWORD === undefined) {
+        problem(t('db.super.superuser_env_missing'));
+        return;
+    }
+    if (user.includes('-')) {
+        problem(t('db.super.invalid_username', user));
+        return;
+    }
+    const hasCmd = (c) => spawnSync('which', [c], { stdio: 'ignore' }).status === 0;
+    const psqlSuperArgs = psqlArgs(pgConfig(true), []).join(' ');
+    const psqlConnArgs = psqlArgs(cfg, []).join(' ');
+    // Use psql + SQL instead of createuser wrapper (createuser may not be in PATH
+    // when executed via sudo -u postgres due to env_reset on Linux).
+    const createCmdForOpenBSD = `psql ${psqlSuperArgs} -d postgres -c \\\"CREATE ROLE ${user} WITH LOGIN CREATEDB;\\\"`.trim();
+    const createCmdForShell = `psql ${psqlSuperArgs} -d postgres -c "CREATE ROLE \"${user}\" WITH LOGIN CREATEDB;"`;
+    // No modificar la siguiente línea fruto de larga experimentación.
+    const alterCmdForOpenBSD = `psql ${psqlSuperArgs} -d postgres -c \\\"ALTER USER ${user} WITH PASSWORD '${pass}';\\\"`.trim();
+    const alterCmdForShell = `psql ${psqlConnArgs} -d postgres -c "ALTER USER \"${user}\" WITH PASSWORD '${pass}';"`;
+    const pgSuperUser = process.env.PG_SUPERUSER;
+    const pgSuperUserPassword = process.env.PG_SUPERUSER_PASSWORD;
+    const runPriv = (mode, cmd) => {
+        const superUserEnv = {
+            ...process.env,
+            PGUSER: pgSuperUser,
+            PGPASSWORD: pgSuperUserPassword
+        };
+        switch (mode) {
+            case 'openbsd_su':
+                const finalCmd = `"${cmd}"`;
+                const spawnArgs = ['su', '-', '_postgresql', '-c', finalCmd];
+                const ret = spawnSync('/usr/bin/doas', spawnArgs, {
+                    encoding: 'utf-8',
+                    env: process.env,
+                    shell: '/bin/sh'
+                });
+                return ret;
+            case 'superuser_env':
+                return spawnSync('sh', ['-c', cmd], { encoding: 'utf-8', env: superUserEnv });
+            case 'root-su':
+                return spawnSync('su', ['-', pgsystemuser, '-c', cmd], { encoding: 'utf-8' });
+            case 'doas':
+                return spawnSync('doas', ['-u', pgsystemuser, 'sh', '-c', cmd], { encoding: 'utf-8' });
+            case 'sudo':
+                return spawnSync('sudo', ['-u', pgsystemuser, 'sh', '-c', cmd], { encoding: 'utf-8' });
+            default: // 'direct'
+                return spawnSync('sh', ['-c', cmd], { encoding: 'utf-8' });
+        }
+    };
+    const modes = [];
+    if (process.platform === 'openbsd') {
+        modes.push('openbsd_su');
+    }
+    if (pgSuperUser !== undefined && pgSuperUserPassword !== undefined) {
+        modes.push('superuser_env');
+    }
+    modes.push('direct');
+    if (!process.env.CI) {
+        if (process.getuid && process.getuid() === 0) {
+            modes.push('root-su');
+        }
+        if (hasCmd('doas')) {
+            modes.push('doas');
+        }
+        if (hasCmd('sudo')) {
+            modes.push('sudo');
+        }
+    }
+    let opSuccess = false;
+    let lastErr;
+    for (const mode of modes) {
+        info(t('db.super.trying_mode', mode));
+        const createCmd = (mode === 'openbsd_su') ? createCmdForOpenBSD : createCmdForShell;
+        let res = runPriv(mode, createCmd);
+        if (res.status !== 0) {
+            const stderr = (res.stderr || '').toString();
+            if (/already exists/i.test(stderr)) {
+                info(t('db.super.role_exists', user));
+            }
+            else {
+                lastErr = stderr || `Exit code ${res.status}`;
+                warn(t('db.super.create_failed_mode', mode, lastErr));
+                continue;
+            }
+        }
+        else {
+            success(t('db.super.create_success', user));
+        }
+        const alterCmd = (mode === 'openbsd_su') ? alterCmdForOpenBSD : alterCmdForShell;
+        res = runPriv(mode, alterCmd);
+        if (res.status !== 0) {
+            const stderr = (res.stderr || '').toString();
+            lastErr = stderr || `Exit code ${res.status}`;
+            problem(t('db.super.password_failed_mode', mode, lastErr));
+            continue;
+        }
+        else {
+            success(t('db.super.password_success', user));
+            opSuccess = true;
+            break;
+        }
+    }
+    if (!opSuccess) {
+        problem(t('db.super.final_failure', lastErr || 'unknown'));
+    }
+}
+export async function runDbConsole(query) {
+    const t = dbT;
+    const cfg = pgConfig();
+    if (query) {
+        info(t('db.console_querying', cfg.database));
+    }
+    else {
+        info(t('db.console_starting', cfg.database));
+    }
+    try {
+        const env = {
+            ...process.env,
+            ...buildEnvArgs(cfg)
+        };
+        // Configurar variables de entorno para desactivar pager y asegurar visibilidad
+        env.PAGER = '';
+        env.PSGQL_PAGER = '';
+        env.PSQL_PAGER = '';
+        // Asegurar variable TERM para terminal interactivo
+        if (!env.TERM) {
+            env.TERM = 'xterm';
+        }
+        const psqlArgs = [];
+        if (query) {
+            psqlArgs.push('-c', query);
+        }
+        // Usar spawn asíncrono para modo interactivo real
+        const child = spawn('psql', psqlArgs, {
+            stdio: query ? ['inherit', 'inherit', 'inherit'] : [0, 1, 2],
+            env: env
+        });
+        // Esperar a que psql termine
+        return new Promise((resolve) => {
+            child.on('close', (code, signal) => {
+                if (code === 0) {
+                    success(t('db.console_closed'));
+                }
+                else {
+                    problem(t('db.console_failed', signal ? `Señal: ${signal}` : `Código: ${code}`));
+                }
+                resolve();
+            });
+            child.on('error', (error) => {
+                problem(t('db.console_failed', error.message));
+                resolve();
+            });
+        });
+    }
+    catch (e) {
+        problem(t('db.console_failed', e.message));
+    }
+}
+export async function runDbTestConnection() {
+    const t = dbT;
+    info(t('db.test_connection.start'));
+    try {
+        const cfg = pgConfig();
+        const env = buildEnvArgs(cfg);
+        const res = spawnSync('psql', ['-c', 'SELECT current_database();'], { encoding: 'utf-8', env: env });
+        if (res.error) {
+            throw new Error(res.error.message);
+        }
+        if (res.status !== 0) {
+            throw new Error(res.stderr);
+        }
+        success(t('db.test_connection.success'));
+        console.log(res.stdout);
+    }
+    catch (e) {
+        problem(t('db.test_connection.failed', e.message));
+    }
+}
+async function runPostMigrationTasks() {
+    await runDbStructureDump();
+    await runDbTypesGen();
+    // Execute post-migrate hook if configured via M_POST_MIGRATE env var.
+    // Useful for syncing sibling project schemas, e.g.:
+    //   M_POST_MIGRATE="cd ../../sivel2 && bin/rails db:structure:dump"
+    const postMigrate = process.env.M_POST_MIGRATE;
+    if (postMigrate) {
+        info(`Post-migrate hook: ${postMigrate}`);
+        const res = spawnSync('sh', ['-c', postMigrate], { stdio: 'inherit', env: process.env });
+        if (res.status !== 0) {
+            problem(`Post-migrate hook failed with exit code ${res.status}`);
+        }
+    }
+}
+export async function runDbStructureDump() {
+    const t = dbT;
+    const cfg = pgConfig();
+    const env = buildEnvArgs(cfg);
+    const structureFile = path.join(process.cwd(), 'db', 'structure.sql');
+    const structureDir = path.dirname(structureFile);
+    info(t('db.structure.dump_start', structureFile));
+    try {
+        if (!fs.existsSync(structureDir)) {
+            fs.mkdirSync(structureDir, { recursive: true });
+        }
+        const args = [
+            '--schema-only',
+            '--no-owner',
+            '--no-privileges',
+            '--no-comments',
+            '-d',
+            cfg.database,
+        ];
+        const result = spawnSync('pg_dump', args, { stdio: 'pipe', env, timeout: getSpawnTimeoutMs() });
+        if (result.status !== 0) {
+            const errorMsg = result.stderr ?
+                result.stderr.toString().trim() : `exit code ${result.status}`;
+            throw new Error(`pg_dump failed: ${errorMsg}`);
+        }
+        // Normalize: remove session-specific hashes that change between dumps
+        const normalized = result.stdout?.toString()
+            .replace(/^\\restrict \S+$/gm, '\\restrict')
+            .replace(/^\\unrestrict \S+$/gm, '\\unrestrict');
+        fs.writeFileSync(structureFile, normalized);
+        success(t('db.structure.dump_success', structureFile));
+    }
+    catch (e) {
+        problem(t('db.structure.dump_failed', structureFile, e.message));
+    }
+}
+export async function runDbStructureLoad() {
+    const t = dbT;
+    const cfg = pgConfig();
+    const env = buildEnvArgs(cfg);
+    const structureFile = path.join(process.cwd(), 'db', 'structure.sql');
+    if (!fs.existsSync(structureFile)) {
+        problem(t('db.structure.load_not_found', structureFile));
+        return;
+    }
+    info(t('db.structure.load_start', structureFile));
+    try {
+        info(t('db.dropping_for_load', cfg.database));
+        run('dropdb', ['--if-exists', cfg.database], env, true /* quiet */);
+        info(t('db.creating_for_load', cfg.database));
+        run('createdb', [cfg.database], env, true /* quiet */);
+        const args = [
+            '-d',
+            cfg.database,
+            '-f',
+            structureFile,
+        ];
+        run('psql', args, env, true /* quiet */);
+        success(t('db.structure.load_success', structureFile));
+    }
+    catch (e) {
+        problem(t('db.structure.load_failed', structureFile, e.message));
+    }
+}
+export async function runDbTypesGen() {
+    const t = dbT;
+    info(t('db.types.gen_start'));
+    try {
+        const cfg = pgConfig();
+        const env = buildEnvArgs(cfg);
+        const url = buildDatabaseUrl(cfg);
+        const outFile = path.join(process.cwd(), 'db', 'db.d.ts');
+        const args = ['--url', url, '--out-file', outFile];
+        run(path.join('node_modules', '.bin', 'kysely-codegen'), args, env);
+        success(t('db.types.gen_success'));
+    }
+    catch (e) {
+        problem(t('db.types.gen_failed', e.message));
+    }
+}
+export async function runDbMigrate() {
+    const t = dbT;
+    info(t('db.migrate.start'));
+    try {
+        const cfg = pgConfig();
+        const env = buildEnvArgs(cfg);
+        const dbUrl = buildDatabaseUrl(cfg);
+        console.error('[db:migrate] PGHOST=' + (env.PGHOST || '(default)') + ' URL=' + dbUrl.substring(0, 100) + ' timeout=' + (getSpawnTimeoutMs() || 'none') + 'ms');
+        const bin = path.join('node_modules', '.bin', 'kysely');
+        // Run one migration at a time so each is in its own transaction.
+        // If one fails, previously-applied migrations stay committed.
+        let applied = 0;
+        const migrated = [];
+        while (true) {
+            const result = spawnSync(bin, ['migrate', 'up'], { stdio: 'pipe', env, timeout: getSpawnTimeoutMs() });
+            const out = (result.stdout ? result.stdout.toString() : '') + (result.stderr ? result.stderr.toString() : '');
+            // Show output to user (but skip the "no new migrations" message since we break below)
+            const isSkipped = out.includes('no pending') || out.includes('no unmigrated') || out.includes('Migration skipped');
+            if (!isSkipped && out)
+                process.stdout.write(out);
+            if (result.status !== 0) {
+                if (isSkipped)
+                    break;
+                if (out)
+                    console.error(out);
+                throw new Error('Migration failed');
+            }
+            if (isSkipped)
+                break;
+            // Extract migration name from output like "✓ Migration 20260722_name"
+            const match = out.match(/Migration\s+(\S+)/);
+            if (match)
+                migrated.push(match[1]);
+            applied++;
+        }
+        if (applied > 0) {
+            for (const name of migrated)
+                console.log('  \u2713 ' + name);
+            console.log('  ' + applied + ' migration(s) applied');
+        }
+        else
+            info(t('db.migrate.none') || 'No pending migrations');
+        success(t('db.migrate.success'));
+        await runPostMigrationTasks();
+    }
+    catch (e) {
+        problem(t('db.migrate.failed', e.message));
+    }
+}
+export async function runDbMigMake(name) {
+    const t = dbT;
+    const migrationsDir = path.join(process.cwd(), 'db', 'migrations');
+    const tstamp = new Date().toISOString().slice(0, 19).replace(/[-T:]/g, '');
+    const filename = `${tstamp}_${name}.ts`;
+    const filepath = path.join(migrationsDir, filename);
+    const template = `import { Kysely } from 'kysely';
+
+export async function up(db: Kysely<any>): Promise<void> {
+    // Migration code
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+    // Rollback code
+}
+`;
+    info(t('db.mig.make_start', filename));
+    try {
+        if (!fs.existsSync(migrationsDir)) {
+            fs.mkdirSync(migrationsDir, { recursive: true });
+        }
+        fs.writeFileSync(filepath, template);
+        success(t('db.mig.make_success', filename));
+    }
+    catch (e) {
+        problem(t('db.mig.make_failed', e.message));
+    }
+}
+export async function runDbRollback() {
+    const t = dbT;
+    // Parse --step N from CLI args (e.g., bin/m db:rollback --step 2)
+    const stepIdx = process.argv.indexOf('--step');
+    const steps = stepIdx !== -1 && stepIdx + 1 < process.argv.length ? Math.max(1, parseInt(process.argv[stepIdx + 1]) || 1) : 1;
+    info(t(steps > 1 ? 'db.rollback.step' : 'db.rollback.start', String(steps)));
+    try {
+        const cfg = pgConfig();
+        const env = buildEnvArgs(cfg);
+        const dbUrl = buildDatabaseUrl(cfg);
+        console.error('[db:rollback] PGHOST=' + (env.PGHOST || '(default)') + ' URL=' + dbUrl.substring(0, 100) + ' timeout=' + (getSpawnTimeoutMs() || 'none') + 'ms');
+        for (let i = 0; i < steps; i++) {
+            run(path.join('node_modules', '.bin', 'kysely'), ['migrate', 'down'], env);
+        }
+        if (steps === 1) {
+            success('Migration rolled back successfully');
+        }
+        else {
+            success(t('db.rollback.step_success', String(steps)));
+        }
+        await runPostMigrationTasks();
+    }
+    catch (e) {
+        problem(t('db.rollback.failed', e.message));
+    }
+}
+export async function runDbDump(name) {
+    const t = dbT;
+    const cfg = pgConfig();
+    const env = buildEnvArgs(cfg);
+    const backupsDir = path.join(process.cwd(), 'db', 'backups');
+    const dumpName = name || `${cfg.database}-${new Date().toISOString().slice(0, 19).replace(/[-T:]/g, '')}`;
+    const dumpDir = path.join(backupsDir, dumpName);
+    info(t('db.dump.start', dumpDir));
+    try {
+        if (!fs.existsSync(backupsDir)) {
+            fs.mkdirSync(backupsDir, { recursive: true });
+        }
+        if (fs.existsSync(dumpDir)) {
+            fs.rmSync(dumpDir, { recursive: true });
+        }
+        const args = [
+            '-Fd', // custom directory format
+            '--no-owner',
+            '--no-privileges',
+            '-f', dumpDir,
+            '-d', cfg.database,
+        ];
+        run('pg_dump', args, env, true /* quiet */);
+        success(t('db.dump.success', dumpDir));
+    }
+    catch (e) {
+        problem(t('db.dump.failed', dumpDir, e.message));
+    }
+}
+export async function runDbRestore(name) {
+    const t = dbT;
+    const cfg = pgConfig();
+    const env = buildEnvArgs(cfg);
+    const backupsDir = path.join(process.cwd(), 'db', 'backups');
+    if (!name) {
+        // List available backups
+        if (!fs.existsSync(backupsDir)) {
+            info(t('db.restore.no_backups', backupsDir));
+            return;
+        }
+        const entries = fs.readdirSync(backupsDir, { withFileTypes: true })
+            .filter(e => e.isDirectory())
+            .map(e => ({ name: e.name, mtime: fs.statSync(path.join(backupsDir, e.name)).mtime }))
+            .sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+        if (entries.length === 0) {
+            info(t('db.restore.no_backups', backupsDir));
+            return;
+        }
+        info(t('db.restore.available'));
+        for (const e of entries) {
+            console.log(t('db.restore.list_item', e.name, e.mtime.toISOString().slice(0, 19).replace('T', ' ')));
+        }
+        return;
+    }
+    const dumpDir = path.join(backupsDir, name);
+    if (!fs.existsSync(dumpDir)) {
+        problem(t('db.restore.backup_not_found', dumpDir));
+        return;
+    }
+    info(t('db.restore.start', dumpDir));
+    try {
+        info(t('db.dropping_for_load', cfg.database));
+        run('dropdb', ['--if-exists', cfg.database], env, true /* quiet */);
+        info(t('db.creating_for_load', cfg.database));
+        run('createdb', [cfg.database], env, true /* quiet */);
+        const args = [
+            '--no-owner',
+            '-d', cfg.database,
+            dumpDir,
+        ];
+        run('pg_restore', args, env, true /* quiet */);
+        success(t('db.restore.success', dumpDir));
+    }
+    catch (e) {
+        problem(t('db.restore.failed', dumpDir, e.message));
+    }
+}
+export async function runDbSeed() { info('Command db:seed not implemented yet.'); }
+/**
+ * db:check — verify expected DB schemas for installed modules.
+ */
+export async function runDbCheck() {
+    const { Kysely, PostgresDialect } = await import('kysely');
+    const { createRequire } = await import('node:module');
+    const { Pool } = createRequire(import.meta.url)('pg');
+    const db = new Kysely({
+        dialect: new PostgresDialect({
+            pool: new Pool({
+                host: process.env.PGHOST,
+                database: process.env.PGDATABASE,
+                user: process.env.PGUSER,
+                password: process.env.PGPASSWORD,
+            }),
+        }),
+    });
+    const modules = [
+        {
+            name: 'WBA',
+            tables: [
+                { name: 'web_event', verify: async (d) => {
+                        const { verifyWebEventSchema } = await import('../wba/routes/summary.js');
+                        return verifyWebEventSchema(d);
+                    } },
+                { name: 'transaction', verify: async (d) => {
+                        const { verifyTransactionSchema } = await import('../wba/routes/summary.js');
+                        try {
+                            await verifyTransactionSchema(d);
+                            return { ok: true };
+                        }
+                        catch (e) {
+                            return { ok: false, error: e.message };
+                        }
+                    } },
+            ],
+        },
+        {
+            name: 'Credentials',
+            tables: [
+                { name: 'credential_metadata', verify: async (_d) => {
+                        return true; // schema verification provided by @pasosdejesus/mpdj plugin
+                    } },
+                { name: 'credential_emission', verify: async (d) => {
+                        try {
+                            const { sql } = await import('kysely');
+                            await sql `SELECT 1 FROM credential_emission LIMIT 0`.execute(d);
+                            return { ok: true };
+                        }
+                        catch {
+                            return null;
+                        }
+                    } },
+            ],
+        },
+    ];
+    let errors = 0;
+    let active = 0;
+    let available = 0;
+    for (const mod of modules) {
+        console.log(`\n${mod.name}:`);
+        let modActive = false;
+        for (const t of mod.tables) {
+            try {
+                const result = await t.verify(db);
+                if (result === null) {
+                    console.log(`  ℹ️ ${t.name.padEnd(24)} — not installed (try eng:${mod.name.toLowerCase()})`);
+                }
+                else if (result.ok === false) {
+                    console.log(`  ⚠️ ${t.name.padEnd(24)} — ${result.error}`);
+                    errors++;
+                    modActive = true;
+                }
+                else if (result.missing && result.missing.length > 0) {
+                    console.log(`  ⚠️ ${t.name.padEnd(24)} — missing columns: ${result.missing.join(', ')}`);
+                    errors++;
+                    modActive = true;
+                }
+                else {
+                    const cols = result.columns || '?';
+                    console.log(`  ✅ ${t.name.padEnd(24)} — ${cols} columns`);
+                    modActive = true;
+                }
+            }
+            catch {
+                console.log(`  ℹ️ ${t.name.padEnd(24)} — not installed (try eng:${mod.name.toLowerCase()})`);
+            }
+        }
+        if (modActive)
+            active++;
+        else
+            available++;
+    }
+    console.log(`\n${active} module(s) active, ${available} available.`);
+    if (errors > 0) {
+        console.log(`${errors} error(s) found.`);
+        process.exit(1);
+    }
+    await db.destroy();
+}