[migration-runner] Ensure the published migrate CLI installs its Postgres driver

[kang-heewon]

Priority recommendation

P1 / tech-debt. The published migrate binary imports pg directly, but the package manifest does not install pg for consumers.

Problem

@croco/migration-runner publishes a migrate CLI at dist/cli.js. That CLI imports Pool from pg at module load time and currently only supports the postgres dialect in createDbClient. However pg is listed in devDependencies, not dependencies or peerDependencies.

An isolated consumer installing @croco/migration-runner can therefore receive a CLI binary that fails before running any migration command because the Postgres driver is not resolvable.

Evidence

• packages/migration-runner/package.json:4-5 defines the local migrate bin.
• packages/migration-runner/package.json:13-30 publishes the bin and CLI export from dist/cli.js / dist/cli.mjs.
• packages/migration-runner/src/cli.ts:3-4 imports drizzle-orm/node-postgres and Pool from pg.
• packages/migration-runner/src/cli.ts:160-173 creates a pg Pool for the postgres dialect.
• packages/migration-runner/package.json:40-49 lists drizzle-orm in dependencies but puts pg in devDependencies.

Desired outcome

The published migration CLI has a correct database-driver contract:

• either pg is installed with @croco/migration-runner for the currently supported Postgres CLI path;
• or pg is an explicit peer/optional peer with a clear runtime diagnostic before attempting Postgres operations.

Implementation path

1. Decide whether Postgres is the built-in driver for this package or an externally supplied peer.
2. Move pg to the appropriate dependency section and include any required type/runtime companion packages.
3. If the driver is optional, replace top-level pg import with a lazy import inside the Postgres branch and throw a Croco Problem with installation guidance when missing.
4. Add a packed-consumer CLI smoke test that installs the package into an isolated fixture and runs migrate --help or imports the CLI without relying on monorepo hoisting.
5. If additional dialects are planned, document how each driver is declared and loaded.

Acceptance criteria

• migrate --help from a packed install does not fail due to missing pg.
• A Postgres migration command either has pg available or fails with an intentional Croco diagnostic explaining the missing peer.
• The manifest no longer relies on devDependencies for runtime CLI imports.
• Tests cover the published CLI entrypoint, not only source-level monorepo execution.

Validation

• pnpm --filter @croco/migration-runner test
• pnpm --filter @croco/migration-runner typecheck
• Packed install smoke test for the migrate binary in an isolated temp project.

Scope boundaries

• Do not change migration checkpoint semantics here.
• Do not add new dialect support unless needed to clarify the driver-loading contract.

[kang-heewon]

Starting work on this. I’ll keep the scope focused on the published migration CLI dependency contract and add a packed-consumer smoke check for the migrate binary.