@zincapp/znvault-migrate 1.0.0

package/dist/lease/run-migrations.d.ts

@@ -0,0 +1,169 @@
+/**
+ * run-migrations.ts — the deploy migration phase.
+ *
+ * Mints a dynamic-secrets lease (4h TTL), opens a connection via the selected
+ * engine adapter with the ephemeral credentials, runs the migration engine,
+ * and revokes the lease in the finally block and on SIGINT/SIGTERM.
+ *
+ * Design decisions (spec §run-migrations.ts + Codex):
+ *  - 4h TTL (not 600s): Vault's cleanup job KILLs active DB sessions when a
+ *    lease expires mid-DDL. A generous TTL + explicit revoke-on-exit is safer.
+ *  - Migration-helper scaffolding (if `opts.scaffoldingFile` configured) is
+ *    applied by the runner at the start of the phase, against the just-minted
+ *    lease's own ephemeral user, and cleaned up (definer objects dropped)
+ *    after reconcile — so the ephemeral migrate user never owns a routine
+ *    past the phase and revokes cleanly.
+ *  - ALWAYS call runner.run() — never short-circuit on status (CRITICAL F4.1):
+ *    run() unconditionally executes pending migrations on every invocation; a
+ *    status check short-circuit would leave pending migrations unapplied while
+ *    reporting "up to date".
+ *  - revokeOnce: single guarded revoke with 3× retry + backoff; 404/non-ACTIVE
+ *    treated as success (Codex F6.1). Signal handlers await the revoke (5s cap)
+ *    before exiting (Codex F6.4) so the in-flight HTTP request isn't aborted.
+ *  - Lease mint failure aborts the deploy before any DB/host change.
+ *  - Migration failure propagates; revokeOnce still runs in finally.
+ *  - Credentials held only in memory; never logged (Codex F6.3).
+ *
+ * PACKAGE SEAM (znvault-migrate): the source (znvault-plugin-payara's
+ * src/run-migrations.ts) hard-imports a MySQL-only `openDb` + `MigrationRunner`.
+ * Here the DB-open + runner-construction are parameterized by an `EngineAdapter`
+ * selected from `opts.engine` (mysql only — postgres is a deferred adapter; see
+ * `selectAdapter` below). Everything else — lease mint, settle, revoke-retry,
+ * signal handlers, password redaction — is byte-identical to the source.
+ */
+import type { Lease } from './dynamic-secrets-client.js';
+import type { EngineAdapter, Conn } from '../adapters/engine-adapter.js';
+export interface RunMigrationsOpts {
+    /**
+     * The engine adapter selector. Only 'mysql' is implemented — 'postgres' is a
+     * valid literal (future-ready) but rejected at runtime by `selectAdapter`
+     * (defense-in-depth; mirrors the deferred-adapter guard in `config.ts`'s
+     * `validateMigrationConfig`).
+     */
+    engine: 'mysql' | 'postgres';
+    env: string;
+    roleId: string;
+    /**
+     * Optional database name override.
+     *
+     * host/port/database are provided by the Vault dynamic-secrets connection
+     * (referenced by roleId) and returned with the lease — the deploy config
+     * only names the role + the migrations dir. This field lets the caller
+     * override the database name when the lease does not pin one.
+     */
+    database?: string;
+    migrationsDir: string;
+    /**
+     * Additional migration directories that share this deploy's schema_migrations
+     * history table (the OTHER phase's dir — e.g. the pre-deploy dir when running the
+     * post-deploy phase). Used ONLY to widen the planner's orphan/checksum integrity
+     * lookup so a migration applied by a sibling phase is not mistaken for a
+     * renamed/deleted file. Absent/empty = single-directory behavior (unchanged).
+     */
+    integrityDirs?: string[];
+    /**
+     * Optional migration-helper scaffolding SQL file, applied at the start of the
+     * migration phase and cleaned up (definer objects dropped) after reconcile.
+     * The cleanup target is the lease's own minted username — see where this is
+     * consumed below for the {filename, leaseUser} construction. Absent = no
+     * scaffolding (today's behavior, byte-identical).
+     */
+    scaffoldingFile?: string;
+}
+/** Shape of a minimal dynamic-secrets client (for injection / testing). */
+export interface DynamicSecretsClient {
+    issueCredential(roleId: string, opts: {
+        ttlSeconds: number;
+    }): Promise<Lease>;
+    revokeCredential(leaseId: string, opts: {
+        reason: string;
+    }): Promise<void>;
+}
+/** Injectable dependencies (real in production; mocked in tests). */
+export interface RunMigrationsDeps {
+    client: DynamicSecretsClient;
+    openConnection(cfg: {
+        host: string;
+        port: number;
+        database: string;
+        user: string;
+        password: string;
+        ssl: boolean;
+    }): Promise<Conn>;
+    makeRunner(conn: Conn, dir: string, appliedBy: string, integrityDirs?: string[], scaffolding?: {
+        filename: string;
+        leaseUser: string;
+    }): {
+        run(): Promise<unknown>;
+    };
+    /**
+     * Override the settle delay applied after conn.end() and before revokeOnce().
+     * Set to 0 in tests to avoid real waiting.  Production always uses REVOKE_SETTLE_MS.
+     */
+    settleMs?: number;
+}
+/**
+ * Adapt a CLIPluginContext-style client (returns T directly) to the VaultHttp
+ * shape expected by makeDynamicSecretsClient ({ status, body }).
+ *
+ * The CLI client throws on non-2xx (see agentPost); on success it returns the
+ * parsed body directly. We wrap it so revokeCredential's isAlreadyGone() logic
+ * can inspect the status on thrown errors.
+ *
+ * The adapter is intentionally narrow — only `post` is needed.
+ */
+export declare function makeVaultHttpAdapter(client: {
+    post<T>(path: string, body: unknown): Promise<T>;
+}): {
+    post(path: string, body: unknown): Promise<{
+        status: number;
+        body: unknown;
+    }>;
+};
+/**
+ * Build the real production deps.
+ *
+ * @param client  - the vault CLI client (CLIPluginContext.client), used to mint/revoke leases.
+ * @param adapter - the selected EngineAdapter (see `selectAdapter` / `runMigrations`).
+ */
+export declare function defaultDeps(client: {
+    post<T>(path: string, body: unknown): Promise<T>;
+}, adapter: EngineAdapter): RunMigrationsDeps;
+/**
+ * How long to wait after conn.end() before calling revokeOnce() in the normal
+ * teardown path.
+ *
+ * WHY: conn.end() sends COM_QUIT to MySQL, but the server-side session lingers
+ * for a short window.  The vault revoke path does:
+ *   SELECT ID FROM processlist WHERE user=<ephemeral> → KILL sessions → DROP USER
+ * If the KILL races a just-closed session, the DROP USER fails transiently and
+ * vault marks the lease FAILED — subsequent retry attempts then hit
+ * "Cannot revoke failed lease" (vault's failed-lease guard), making all 3
+ * attempts fail.  Waiting ~1.5s gives the server time to tear down the session
+ * so the revoke's KILL/DROP runs against a clean slate.
+ *
+ * This delay is ONLY in the normal finally teardown.  The signal handler path
+ * calls revokeOnce() directly (inside withTimeout) and must stay fast.
+ */
+export declare const REVOKE_SETTLE_MS = 1500;
+/**
+ * Run schema migrations as a deploy phase.
+ *
+ * 1. Mint a dynamic-secrets lease (TTL 4h).
+ * 2. Install signal handlers that await revoke (5s cap) before exiting.
+ * 3. Open a connection (via the engine adapter) with the ephemeral credentials.
+ * 4. ALWAYS call runner.run() — never skip (CRITICAL F4.1).
+ * 5. In finally: close the connection + revokeOnce + remove signal handlers.
+ *
+ * @param ctx    - CLI plugin context (used for logging; pass {} as `any` in tests).
+ * @param opts   - engine, env, roleId, migrationsDir, and an optional database override.
+ *                 host/port/database come from the Vault dynamic-secrets lease.
+ * @param deps   - Injectable deps (real = defaultDeps(ctx.client, adapter); tests pass mocks).
+ */
+export declare function runMigrations(ctx: {
+    output?: {
+        info(msg: string): void;
+        warn(msg: string): void;
+    };
+}, opts: RunMigrationsOpts, deps: RunMigrationsDeps): Promise<void>;
+//# sourceMappingURL=run-migrations.d.ts.map

package/dist/lease/run-migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-migrations.d.ts","sourceRoot":"","sources":["../../src/lease/run-migrations.ts"],"names":[],"mappings":"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"}

package/dist/lease/run-migrations.js

@@ -0,0 +1,302 @@
+/**
+ * run-migrations.ts — the deploy migration phase.
+ *
+ * Mints a dynamic-secrets lease (4h TTL), opens a connection via the selected
+ * engine adapter with the ephemeral credentials, runs the migration engine,
+ * and revokes the lease in the finally block and on SIGINT/SIGTERM.
+ *
+ * Design decisions (spec §run-migrations.ts + Codex):
+ *  - 4h TTL (not 600s): Vault's cleanup job KILLs active DB sessions when a
+ *    lease expires mid-DDL. A generous TTL + explicit revoke-on-exit is safer.
+ *  - Migration-helper scaffolding (if `opts.scaffoldingFile` configured) is
+ *    applied by the runner at the start of the phase, against the just-minted
+ *    lease's own ephemeral user, and cleaned up (definer objects dropped)
+ *    after reconcile — so the ephemeral migrate user never owns a routine
+ *    past the phase and revokes cleanly.
+ *  - ALWAYS call runner.run() — never short-circuit on status (CRITICAL F4.1):
+ *    run() unconditionally executes pending migrations on every invocation; a
+ *    status check short-circuit would leave pending migrations unapplied while
+ *    reporting "up to date".
+ *  - revokeOnce: single guarded revoke with 3× retry + backoff; 404/non-ACTIVE
+ *    treated as success (Codex F6.1). Signal handlers await the revoke (5s cap)
+ *    before exiting (Codex F6.4) so the in-flight HTTP request isn't aborted.
+ *  - Lease mint failure aborts the deploy before any DB/host change.
+ *  - Migration failure propagates; revokeOnce still runs in finally.
+ *  - Credentials held only in memory; never logged (Codex F6.3).
+ *
+ * PACKAGE SEAM (znvault-migrate): the source (znvault-plugin-payara's
+ * src/run-migrations.ts) hard-imports a MySQL-only `openDb` + `MigrationRunner`.
+ * Here the DB-open + runner-construction are parameterized by an `EngineAdapter`
+ * selected from `opts.engine` (mysql only — postgres is a deferred adapter; see
+ * `selectAdapter` below). Everything else — lease mint, settle, revoke-retry,
+ * signal handlers, password redaction — is byte-identical to the source.
+ */
+import os from 'node:os';
+import { makeDynamicSecretsClient } from './dynamic-secrets-client.js';
+import { mysqlAdapter } from '../adapters/mysql/mysql-adapter.js';
+import { MigrationRunner } from '../core/runner.js';
+// ─── VaultHttp adapter ────────────────────────────────────────────────────────
+/**
+ * Adapt a CLIPluginContext-style client (returns T directly) to the VaultHttp
+ * shape expected by makeDynamicSecretsClient ({ status, body }).
+ *
+ * The CLI client throws on non-2xx (see agentPost); on success it returns the
+ * parsed body directly. We wrap it so revokeCredential's isAlreadyGone() logic
+ * can inspect the status on thrown errors.
+ *
+ * The adapter is intentionally narrow — only `post` is needed.
+ */
+export function makeVaultHttpAdapter(client) {
+    return {
+        async post(path, body) {
+            // ctx.client.post<T> returns T on success, throws on non-2xx.
+            const result = await client.post(path, body);
+            return { status: 200, body: result };
+        },
+    };
+}
+// ─── Engine adapter selection ─────────────────────────────────────────────────
+/**
+ * Select the concrete EngineAdapter for `opts.engine`. Only 'mysql' is
+ * implemented; 'postgres' throws the SAME deferred-error string used by
+ * `config.ts`'s `validateMigrationConfig` (em-dash U+2014 included), so a
+ * postgres engine is rejected consistently whether caught at config-validation
+ * time or here (defense-in-depth — see the doc comment on `RunMigrationsOpts.engine`).
+ */
+function selectAdapter(engine) {
+    if (engine === 'mysql')
+        return mysqlAdapter;
+    // postgres is a valid type literal but not implemented — mirror the config-validation deferral.
+    throw new Error('postgres migrations are not yet supported (the PostgreSQL adapter is a deferred project — see the znvault-migrate PostgreSQL design)');
+}
+// ─── Default production deps factory ─────────────────────────────────────────
+/**
+ * Build the real production deps.
+ *
+ * @param client  - the vault CLI client (CLIPluginContext.client), used to mint/revoke leases.
+ * @param adapter - the selected EngineAdapter (see `selectAdapter` / `runMigrations`).
+ */
+export function defaultDeps(client, adapter) {
+    const http = makeVaultHttpAdapter(client);
+    const dynamicClient = makeDynamicSecretsClient(http);
+    return {
+        client: dynamicClient,
+        openConnection: (cfg) => adapter.openConnection(cfg),
+        makeRunner(conn, dir, appliedBy, integrityDirs, scaffolding) {
+            return new MigrationRunner(adapter, conn, dir, appliedBy, integrityDirs ?? [], scaffolding);
+        },
+    };
+}
+// ─── revokeOnce with retry helper ────────────────────────────────────────────
+const REVOKE_RETRY_DELAYS_MS = [200, 600]; // 3 attempts: immediate + 2 retries
+/**
+ * Return true when the caught error indicates the lease is permanently in a
+ * non-revocable state (e.g. vault already marked it FAILED after a previous
+ * failed attempt).  Retrying these is futile — bail out immediately.
+ *
+ * Examples from the vault server:
+ *   "Cannot revoke failed lease"
+ *   "Cannot revoke a FAILED lease"
+ */
+function isNonRevocable(e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return /cannot revoke .* lease|failed lease/i.test(msg);
+}
+/**
+ * Build a guarded single-shot revoke function with 3× retry + backoff.
+ *
+ * Idempotent: subsequent calls after the first are no-ops (the `revoked` flag
+ * is captured in closure so parallel signal + finally can't double-revoke).
+ *
+ * 404/410/non-ACTIVE response → already gone → resolved as success (F6.1 — handled
+ * inside revokeCredential, never reaches the catch here).
+ *
+ * Non-revocable lease (vault marked FAILED) → log WARN with real error, stop
+ * immediately without retrying — retrying cannot fix a FAILED-lease state.
+ *
+ * Other transient failures → log DEBUG + retry up to 3 times; on final failure
+ * log WARN with the real error and give up without throwing (cleanup job + 4h
+ * TTL will drop the user eventually).
+ */
+function makeRevokeOnce(client, lease, log) {
+    let revoked = false;
+    return async function revokeOnce() {
+        if (revoked)
+            return;
+        revoked = true;
+        const attempts = 1 + REVOKE_RETRY_DELAYS_MS.length; // 3 total
+        for (let attempt = 1; attempt <= attempts; attempt++) {
+            try {
+                await client.revokeCredential(lease.leaseId, { reason: 'migration complete' });
+                return; // success
+            }
+            catch (e) {
+                const errMsg = e instanceof Error ? e.message : String(e);
+                // Part C: if the lease is permanently non-revocable (vault already
+                // marked it FAILED), retrying is futile — stop immediately.
+                if (isNonRevocable(e)) {
+                    log(`[run-migrations] WARN: revoke failed after ${attempt} attempt(s): ${errMsg}; ` +
+                        `lease is in a non-revocable state — cleanup job + 4h TTL will drop the user. leaseId=${lease.leaseId}`);
+                    return;
+                }
+                const isLast = attempt === attempts;
+                if (isLast) {
+                    // All retries exhausted — log real error and give up; do NOT throw.
+                    log(`[run-migrations] WARN: revoke failed after ${attempts} attempt(s): ${errMsg}; ` +
+                        `cleanup job + 4h TTL will drop the user. leaseId=${lease.leaseId}`);
+                    return;
+                }
+                // Non-last transient failure: log attempt details then wait before retry.
+                const delayMs = REVOKE_RETRY_DELAYS_MS[attempt - 1] ?? 200;
+                log(`[run-migrations] revoke attempt ${attempt} failed: ${errMsg}; retrying in ${delayMs}ms`);
+                await new Promise((resolve) => setTimeout(resolve, delayMs));
+            }
+        }
+    };
+}
+// ─── Settle delay constant ────────────────────────────────────────────────────
+/**
+ * How long to wait after conn.end() before calling revokeOnce() in the normal
+ * teardown path.
+ *
+ * WHY: conn.end() sends COM_QUIT to MySQL, but the server-side session lingers
+ * for a short window.  The vault revoke path does:
+ *   SELECT ID FROM processlist WHERE user=<ephemeral> → KILL sessions → DROP USER
+ * If the KILL races a just-closed session, the DROP USER fails transiently and
+ * vault marks the lease FAILED — subsequent retry attempts then hit
+ * "Cannot revoke failed lease" (vault's failed-lease guard), making all 3
+ * attempts fail.  Waiting ~1.5s gives the server time to tear down the session
+ * so the revoke's KILL/DROP runs against a clean slate.
+ *
+ * This delay is ONLY in the normal finally teardown.  The signal handler path
+ * calls revokeOnce() directly (inside withTimeout) and must stay fast.
+ */
+export const REVOKE_SETTLE_MS = 1500;
+// ─── withTimeout helper ───────────────────────────────────────────────────────
+/**
+ * Race a promise against a timeout. Resolves (possibly undefined) on timeout
+ * so that a stuck revoke doesn't block process.exit indefinitely.
+ */
+function withTimeout(p, ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        p.then(() => { clearTimeout(timer); resolve(); }, () => { clearTimeout(timer); resolve(); });
+    });
+}
+// ─── Core function ────────────────────────────────────────────────────────────
+/**
+ * Run schema migrations as a deploy phase.
+ *
+ * 1. Mint a dynamic-secrets lease (TTL 4h).
+ * 2. Install signal handlers that await revoke (5s cap) before exiting.
+ * 3. Open a connection (via the engine adapter) with the ephemeral credentials.
+ * 4. ALWAYS call runner.run() — never skip (CRITICAL F4.1).
+ * 5. In finally: close the connection + revokeOnce + remove signal handlers.
+ *
+ * @param ctx    - CLI plugin context (used for logging; pass {} as `any` in tests).
+ * @param opts   - engine, env, roleId, migrationsDir, and an optional database override.
+ *                 host/port/database come from the Vault dynamic-secrets lease.
+ * @param deps   - Injectable deps (real = defaultDeps(ctx.client, adapter); tests pass mocks).
+ */
+export async function runMigrations(ctx, opts, deps) {
+    // Validate the engine selector up front (defense-in-depth — see selectAdapter's
+    // doc comment). The real adapter used for the DB open + runner construction is
+    // the one already baked into `deps` by `defaultDeps`; this call exists solely
+    // so a postgres `opts.engine` is rejected even if deps were somehow built for
+    // an unsupported engine, mirroring config.ts's validation-time deferral.
+    selectAdapter(opts.engine);
+    const log = (msg) => {
+        if (ctx.output?.warn) {
+            ctx.output.warn(msg);
+        }
+        else {
+            // eslint-disable-next-line no-console
+            console.warn(msg);
+        }
+    };
+    const info = (msg) => {
+        if (ctx.output?.info) {
+            ctx.output.info(msg);
+        }
+        else {
+            // eslint-disable-next-line no-console
+            console.info(msg);
+        }
+    };
+    // ── Step 1: Mint lease (4h TTL). Failure aborts deploy before any host change. ──
+    const LEASE_TTL_SECONDS = 4 * 3600; // 14400 — NOT 600; see spec §run-migrations.ts
+    const lease = await deps.client.issueCredential(opts.roleId, { ttlSeconds: LEASE_TTL_SECONDS });
+    info(`[run-migrations] Lease minted: ${lease.leaseId} (TTL ${LEASE_TTL_SECONDS}s)`);
+    // ── Step 2: Build the guarded revoke function ──────────────────────────────
+    const revokeOnce = makeRevokeOnce(deps.client, lease, log);
+    // ── Step 3: Signal handlers — await revoke before exit (Codex F6.4) ───────
+    const onSignal = async () => {
+        log('[run-migrations] Signal received — revoking lease before exit...');
+        await withTimeout(revokeOnce(), 5000);
+        process.exit(1);
+    };
+    const sigintHandler = () => { void onSignal(); };
+    const sigtermHandler = () => { void onSignal(); };
+    process.on('SIGINT', sigintHandler);
+    process.on('SIGTERM', sigtermHandler);
+    // ── Step 4: Open connection + run engine ──────────────────────────────────
+    let conn;
+    try {
+        // Resolve the database name: prefer the lease's value (from the Vault connection),
+        // fall back to the opts override, and error if neither is available.
+        // This check is INSIDE the try so that revokeOnce fires in finally even on validation failure.
+        const database = lease.database ?? opts.database;
+        if (!database) {
+            throw new Error('[run-migrations] No database name: the Vault dynamic-secrets connection did not return a ' +
+                'database name and no database override was provided in the migration config.');
+        }
+        conn = await deps.openConnection({
+            host: lease.host,
+            port: lease.port,
+            database,
+            user: lease.username,
+            password: lease.password,
+            ssl: true,
+        });
+        const appliedBy = `${os.userInfo().username}@${os.hostname()}`;
+        // Scaffolding cleanup must target the lease's OWN minted username — that is
+        // the ephemeral identity that will own any definer objects created while the
+        // scaffolding file is applied, and the one whose leftover objects need
+        // dropping after reconcile. Absent opts.scaffoldingFile = no scaffolding
+        // (byte-identical to pre-scaffolding behavior).
+        const scaffolding = opts.scaffoldingFile
+            ? { filename: opts.scaffoldingFile, leaseUser: lease.username }
+            : undefined;
+        // ALWAYS run() — NEVER short-circuit on status (CRITICAL F4.1).
+        // run() applies the scaffolding (if configured) and pending migrations;
+        // a status-check short-circuit would leave pending migrations unapplied
+        // while reporting "up to date".
+        const result = await deps
+            .makeRunner(conn, opts.migrationsDir, appliedBy, opts.integrityDirs, scaffolding)
+            .run();
+        info(`[run-migrations] Migrations complete: ${JSON.stringify(result)}`);
+    }
+    finally {
+        // ── Step 5: Teardown — close connection (best-effort) then revoke ────────
+        if (conn) {
+            await conn.end().catch(() => {
+                // best-effort; never mask the primary error
+            });
+            // Settle delay: give the server time to tear down the just-closed
+            // ephemeral session before the vault revoke's KILL/DROP runs.
+            // Without this, conn.end() (COM_QUIT) may still linger server-side,
+            // causing the revoke's KILL to race it → vault marks the lease FAILED
+            // → subsequent retry attempts hit "Cannot revoke failed lease".
+            // The signal handler path does NOT include this delay (stays fast).
+            // deps.settleMs overrides REVOKE_SETTLE_MS (set to 0 in tests to skip).
+            const settleMs = deps.settleMs ?? REVOKE_SETTLE_MS;
+            if (settleMs > 0) {
+                await new Promise((resolve) => setTimeout(resolve, settleMs));
+            }
+        }
+        await revokeOnce();
+        // Remove signal handlers to avoid memory leaks and double-handling.
+        process.removeListener('SIGINT', sigintHandler);
+        process.removeListener('SIGTERM', sigtermHandler);
+    }
+}

package/dist/lease/run-migrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-migrations.js","sourceRoot":"","sources":["../../src/lease/run-migrations.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@zincapp/znvault-migrate",
+  "version": "1.0.0",
+  "description": "Shared MySQL schema-migration library for ZnVault deployer tooling",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "build:prod": "tsc --sourceMap false",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "ESLINT_USE_FLAT_CONFIG=false eslint 'src/**/*.ts' 'test/**/*.ts'",
+    "lint:fix": "ESLINT_USE_FLAT_CONFIG=false eslint 'src/**/*.ts' 'test/**/*.ts' --fix",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build:prod"
+  },
+  "keywords": [
+    "znvault",
+    "mysql",
+    "migration",
+    "schema",
+    "database"
+  ],
+  "author": "ZincApp",
+  "license": "MIT",
+  "homepage": "https://github.com/vidaldiego/znvault-migrate#readme",
+  "bugs": {
+    "url": "https://github.com/vidaldiego/znvault-migrate/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vidaldiego/znvault-migrate.git"
+  },
+  "dependencies": {
+    "mysql2": "^3.16.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.10",
+    "@typescript-eslint/eslint-plugin": "^8.53.1",
+    "@typescript-eslint/parser": "^8.53.1",
+    "@vitest/coverage-v8": "^4.0.17",
+    "eslint": "^9.39.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.17"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}