fix(cli): port db diff --use-pgadmin to a native differ-container invocation (CLI-1968)

apps/cli/docs/binary-distribution.md

@@ -101,7 +101,7 @@ This:
 
 ### Removed commands
 
-`apps/cli-go/internal/start` (Go's `supabase start` implementation) was deleted outright (CLI-1966), not just excluded from the shipped binary. Native TS `start` talks to Docker directly and never proxies to Go for it, and no other still-live TS→Go delegation seam (`db test`, `db branch`/`db remote`, `db diff --use-pgadmin`/`--use-pg-schema`, `db pull --experimental`, the hidden `db __catalog` seam (baseline/declarative modes only — the migrations mode was removed by CLI-1959, and the sibling hidden `db __shadow` seam was removed outright by CLI-1956) — the sibling hidden `db __db-bootstrap` seam was removed outright by CLI-1955, once native `db reset --local` became its last remaining caller — etc.) ever called into `internal/start` either — a repo-wide `grep` for the import confirmed the only reference anywhere in `apps/cli-go` was `start`'s own cobra registration. `internal/start` alone previously accounted for roughly half the shipped Go binary's size via its exclusive dependency tree (docker-compose/v2, buildx, buildkit, k8s client-go, aws-sdk-go-v2, notary, secret-detector), which `go mod tidy` dropped entirely once the package was deleted. `cmd/start.go` keeps `start`'s cobra registration and flag surface (needed by the `__complete` passthrough) but its `RunE` is a permanent stub returning a "not available in supabase-go" error — see `apps/cli-go/cmd/start_test.go` for the pinned error text. There is no longer a `bundled` build tag: with no second implementation to select between, the Go CLI's `cmd` package has only one `start`.
+`apps/cli-go/internal/start` (Go's `supabase start` implementation) was deleted outright (CLI-1966), not just excluded from the shipped binary. Native TS `start` talks to Docker directly and never proxies to Go for it, and no other still-live TS→Go delegation seam (`db test`, `db branch`/`db remote`, `db diff --use-pg-schema`, `db pull --experimental`, the hidden `db __catalog` seam (baseline/declarative modes only — the migrations mode was removed by CLI-1959, and the sibling hidden `db __shadow` seam was removed outright by CLI-1956) — the sibling hidden `db __db-bootstrap` seam was removed outright by CLI-1955, once native `db reset --local` became its last remaining caller — etc.) ever called into `internal/start` either — a repo-wide `grep` for the import confirmed the only reference anywhere in `apps/cli-go` was `start`'s own cobra registration. `internal/start` alone previously accounted for roughly half the shipped Go binary's size via its exclusive dependency tree (docker-compose/v2, buildx, buildkit, k8s client-go, aws-sdk-go-v2, notary, secret-detector), which `go mod tidy` dropped entirely once the package was deleted. `cmd/start.go` keeps `start`'s cobra registration and flag surface (needed by the `__complete` passthrough) but its `RunE` is a permanent stub returning a "not available in supabase-go" error — see `apps/cli-go/cmd/start_test.go` for the pinned error text. There is no longer a `bundled` build tag: with no second implementation to select between, the Go CLI's `cmd` package has only one `start`.
 
 ## See Also
 

apps/cli/src/legacy/commands/db/diff/diff.errors.ts

@@ -75,3 +75,83 @@ export class LegacyDbDiffWriteError extends Data.TaggedError("LegacyDbDiffWriteE
     return actionability.permission;
   }
 }
+
+/**
+ * The local database container is not running, or inspecting it failed —
+ * Go's `utils.ErrNotRunning` / `"failed to inspect service: %w"` via
+ * `AssertSupabaseDbIsRunning` (`apps/cli-go/internal/db/diff/pgadmin.go:51`,
+ * `internal/utils/misc.go:151-166`). Unlike every other engine on this command,
+ * `--use-pgadmin` runs this check even for `--linked`/`--db-url` — see
+ * `diff.handler.ts`'s pgadmin branch.
+ */
+export class LegacyDbDiffDbNotRunningError extends Data.TaggedError(
+  "LegacyDbDiffDbNotRunningError",
+)<{
+  readonly message: string;
+  readonly daemonDown?: boolean;
+  readonly suggestion?: string;
+}> {
+  // Must stay character-identical to `LegacyLocalDbRunningError`'s classification
+  // (`legacy-db-bootstrap`'s equivalent local-db-not-running check) — the two are
+  // deliberately duplicated for this command's own `AssertSupabaseDbIsRunning`
+  // parity target, not shared, so keep them in sync by hand.
+  get [ErrorActionabilityId](): CliErrorActionabilityDeclaration {
+    return this.daemonDown === true
+      ? { ...actionability.dockerNotRunning, fingerprint_suffix: "docker_not_running" }
+      : actionability.startStack; // same preset `reset-local-database.ts` uses
+  }
+}
+
+/**
+ * Classic "assertNever" exhaustiveness helper: with every literal of
+ * `LegacyDbDiffPgAdminError["reason"]` handled by its own `case` below, `reason`
+ * narrows to `never` by the time it reaches this call — so a FUTURE reason added
+ * to the union without a matching `case` is a compile error here (its residual
+ * type inside `default:` would no longer be `never`), not a silently-absorbed
+ * classification. The parameter is intentionally unused at runtime: the drift
+ * guard (`error-actionability-coverage.unit.test.ts`) evaluates every getter
+ * against a field-less probe (`Object.create(prototype)`, no constructor args),
+ * so `this.reason` is genuinely runtime-`undefined` there, bypassing the type
+ * system entirely — this must still degrade to a valid declaration rather than
+ * `undefined`/a crash, so it returns the SAME fallback as the "differ" case.
+ */
+function legacyPgAdminUnreachableReason(_reason: never): CliErrorActionabilityDeclaration {
+  return actionability.dbFinding;
+}
+
+/**
+ * The pgAdmin differ container failed to run, or its `--json-diff` output could
+ * not be parsed. `reason` is a closed union set at the docker/parse boundary —
+ * never inferred from `message` text.
+ */
+export class LegacyDbDiffPgAdminError extends Data.TaggedError("LegacyDbDiffPgAdminError")<{
+  readonly message: string;
+  readonly reason:
+    | "differ"
+    | "invalid_output"
+    | "docker_daemon"
+    | "registry_pull"
+    | "image_inspect";
+}> {
+  get [ErrorActionabilityId](): CliErrorActionabilityDeclaration {
+    switch (this.reason) {
+      case "docker_daemon":
+        return { ...actionability.dockerNotRunning, fingerprint_suffix: "docker_not_running" };
+      case "registry_pull":
+        return { ...actionability.externalNetwork, fingerprint_suffix: "registry_pull" };
+      // Malformed pinned-differ wire output is an internal contract violation, not a
+      // user input mistake — same precedent as pg-delta's own malformed-subprocess-
+      // output branch (`legacy-pgdelta.apply.ts`'s `"output_parse"` case).
+      case "invalid_output":
+        return { ...actionability.impossibleState, fingerprint_suffix: "invalid_content" };
+      case "image_inspect":
+        return { ...actionability.invalidConfig, fingerprint_suffix: "image_inspect" };
+      // "differ": a failing container is the user's own schema/connection, matching
+      // `LegacyMigraDiffError`'s default classification for the equivalent engine failure.
+      case "differ":
+        return actionability.dbFinding;
+      default:
+        return legacyPgAdminUnreachableReason(this.reason);
+    }
+  }
+}