feat(pgpm): pgpm diff --append-module — append the delta into an existing module

[pyramation]

Summary

pgpm diff could only emit its delta as a fresh package. This adds an append mode: emit the semantic delta into an existing pgpm module's plan, so you can grow one module version-over-version instead of accumulating separate migration packages.

The core is a new appendModule in @pgpmjs/transform — a non-destructive sibling of writeModule (which rmSyncs the deploy/revert/verify tree and rewrites everything). appendModule touches nothing that already exists:

appendModule(moduleDir, rows) -> { dir, added[], skipped[], warnings[] }
// parse existing pgpm.plan
// for each incoming row:
//   name already in plan?           -> skip (never overwrite), warn
//   dep not resolvable in plan?     -> drop it from the bracket, warn
//                                      (plan order still sequences the change last)
//   else                            -> push Change onto plan.changes
// writePgpmFiles(newRowsOnly)   // no rmSync — only new change scripts written
// writePlanFile(plan)           // existing lines regenerated from parsed values, new ones appended

CLI: pgpm diff <A> <B> --append-module <dir>. It's standalone — rejected together with --emit-migration/--emit-module/--emit-sql/--emit-bundle/--verify, since those all target the fresh-delta module model (e.g. --verify's oracle deploys the migration dir as just the delta on top of A).

Tests

diff-e2e gains an append case: build a standalone module holding v1's schema, pgpm diff … --append-module the v1→v2 delta into it, then assert (a) an existing change's deploy script is byte-for-byte unchanged, (b) the plan grew, and (c) the appended module (v1 + delta) fresh-deploys to a catalog equivalent to v2 (order-insensitive, since drop+add can't reproduce physical column ordinals). Full local run: diff-e2e 9/9, @pgpmjs/transform 85/85.

Roadmap: the append-to-existing-module follow-up discussed for pgpm diff (Part C of #1340).

Link to Devin session: https://app.devin.ai/sessions/798445577ac8487abf80e28f9ff7a916
Requested by: @pyramation

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring