feat(appkit): add appkit db verify

[ditadi]

Stacked on #672.

Summary

Adds appkit db verify, a read-only check that answers "will my app work with its database?".

• appkit db verify checks the branch .env points at, which is normally your dev or session branch:

  • every table and column config/database/schema.ts declares exists (the same check the plugin runs on start);
  • every committed migration has been applied;
  • no committed migration is one the migrator will never run there. That covers a migration merged out of order (older than one the branch already ran) and one edited after it ran.

• appkit db verify --prod checks that the deployed app is set up to use the branch databricks.yml deploys to, through the Databricks API only:

  • the app exists;
  • its postgres resource names that branch and database, with CAN_CONNECT_AND_CREATE;
  • its service principal has a role on the branch;
  • the app is running.

  A running app has applied its migrations and checked its schema on start (feat(appkit): apply committed database migrations on deploy start #654). --prod reads no database, so it needs no Postgres role on the deploy branch.

Both exit 1 on any finding, and each finding names its fix.

Details

• The local check runs in one READ ONLY transaction that is rolled back, then closes the connection.
• Stranded migrations come from comparing the journal table's (created_at, hash) rows with the committed journal and files. The migrator itself is unchanged: it still runs only entries newer than the last recorded one.
• With --prod, a crashed, stopped, failed or in-progress app is reported with the app's own status message and the command to run next (databricks apps logs, start or deploy).
• The app name comes from the default target's resources.apps override, else the top-level app. A name with ${…} is reported as unresolvable rather than looked up.
• findSchemaProblems is split out of the plugin's startup check, so verify reports the same problems the app would fail on.

Tests

• The local tests cover:

  • a matching branch;
  • missing columns and pending migrations;
  • no journal table;
  • out-of-order and edited migrations;
  • the read-only transaction, including rollback and connection cleanup on failure.

• The --prod tests use a faked Apps and Lakebase API where the developer has no role on the deploy branch. They cover:

  • each binding mismatch;
  • each app state;
  • a missing app, branch or database;
  • an undeclared or interpolated app name.

  They also assert that no database connection and no write happens.

• Checked live, read-only, against a workspace:

  • the apps API's postgres resource format and a deleted app's 404;
  • a stopped app's response (it has no active deployment);
  • the service principal's role lookup.

• Checked against a local Postgres 14 with the real migrator: no false positives, and both stranded cases detected.