TML-2801: bring the six migration read commands into consistency (#726)

Brings the `migration` read-verb family — `status`, `list`, `graph`,
`log`, `show`, `check` — into line on the axes a prior audit flagged
(`projects/migration-graph-rendering/read-command-consistency-audit.md`,
findings F1–F7): JSON envelope shape, error path, params, decoration
flags, help text, and multi-space behaviour. Most of it is wiring
existing shared primitives into the commands that had drifted; one piece
(multi-space `check`) is a real behaviour change. An extended parity
test locks the conventions so they can't re-drift.

## Changes

- **Unified `--json` envelopes (F3)**: `migration log` emitted a bare
array and `migration graph` built its JSON inline; both now emit a `{
ok, … }` object with a co-located exported type (`MigrationLogResult` →
`{ ok, entries }` incl. the empty case; `MigrationGraphJsonResult`). The
other four already conformed.
- **One error path (F5)**: `migration check`'s inline ref-resolution
error strings now route through the shared `mapRefResolutionError`
(matching `show`/`status`), preserving its `PRECONDITION` exit. A new
`requireLiveDatabase` helper (`cli-errors.ts`) gives `log` and `status`
one identical missing-DB envelope with `meta.missingFlags`.
- **Shared path grammar (F2)**: `show`'s path-resolution helpers move to
`migration-path-target.ts` and are now shared with `check`, so
`migration check <path>` resolves a migration directory like `show`
does; both positional help strings describe the same forms.
- **`--ascii` where glyphs are drawn (F4)**: `status` (which hardcoded
unicode) and `log`'s table now honour `--ascii`, matching
`list`/`graph`. `show`/`check` draw no laned-tree glyphs and are
unchanged.
- **Help-text polish (F6)**: `check`'s see-also now links `migration
show`; every JSON-emitting verb has a `--json` example; offline/live
phrasing is uniform across the family.
- **`migration check` is multi-space (F1, the spine)**: the holistic
check validated only the app space; it now validates every contract
space by default, with `--space <id>` to narrow — reusing the same
`aggregate.spaces()` enumeration and `isValidSpaceId` /
`errorInvalidSpaceId` / `errorSpaceNotFound` machinery `list` uses.
`--space` also runs the aggregate integrity pass filtered to that space,
so narrowing never weakens validation. Single-target mode stays app-only
(noted as a follow-up); exit codes and result shape are unchanged.
- **Parity test as the lock (D7)**:
`migration-read-commands-parity.test.ts` (previously rendering-only) now
asserts the `{ ok, … }` envelope, see-also symmetry, the shared
missing-DB error shape, and `check`'s multi-space behaviour across all
six verbs.

## Why

The read-command redesign shipped `list`/`graph`/`status`/`log` as
separate verbs incrementally, so consistency drifted: the same
conceptual input (name a migration, name a contract space, hit a missing
DB) was handled differently per command. Routing each command through
the primitives that already existed — rather than inventing per-command
behaviour — is both the fix and the guard against recurrence, which is
why the parity test is part of the slice rather than a follow-up. The
one genuine behaviour change, multi-space `check`, also closes a latent
gap: integrity problems in non-app spaces previously passed silently.

`check` keeps its command-specific exit codes
(`OK`/`PRECONDITION`/`INTEGRITY_FAILED`) — that's Style-Guide-sanctioned
for a verify verb and intentionally left as-is.

**Out of scope**: `migrate` and the authoring verbs; the control-api ↔
CLI surface reconciliation
([TML-2780](https://linear.app/prisma-company/issue/TML-2780)); `ref
list`; whether `show`/`check` should accept the contract-reference
grammar; real `--space` on `show` (rejected — it resolves a single
pinned migration).

**Note for CI**: the `@prisma-next/cli` package runs vitest with
`isolate: false`, and there's a pre-existing order-dependent flake in
`test/control-api/client.test.ts` (and occasionally
`migration-list-json-golden.test.ts`) from config-loader mock bleed
across files. It reproduces on the base tree with this branch's test
files stashed, so it is not introduced here; the package typecheck,
`lint:deps`, and targeted suites are clean, and the full suite passes on
the large majority of runs.

Closes TML-2801.

🤖 Generated with [Claude Code](https://claude.com/claude-code)


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added --ascii rendering; migration show accepts a migration directory
path; migration check supports --space and multi-space checks.

* **Bug Fixes**
  * Clearer missing-DB errors that include which flags are missing.

* **Refactor**
* Standardized JSON envelopes for read commands (ok + typed payloads)
and more consistent CLI output and exit behavior; JSON output shapes for
migration graph/log refined.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: Will Madden <madden@prisma.io>
Signed-off-by: wmadden-electric <286902546+wmadden-electric@users.noreply.github.com>
Co-authored-by: Will Madden <madden@prisma.io>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: wmadden-electric <286902546+wmadden-electric@users.noreply.github.com>

Author: 3 people

packages/1-framework/1-core/errors/src/control.ts

@@ -239,6 +239,7 @@ export function errorDatabaseConnectionRequired(options?: {
   readonly why?: string;
   readonly commandName?: string;
   readonly retryCommand?: string;
+  readonly missingFlags?: readonly string[];
 }): CliStructuredError {
   const runHint = options?.retryCommand
     ? `Run \`${options.retryCommand}\``
@@ -249,6 +250,9 @@ export function errorDatabaseConnectionRequired(options?: {
     domain: 'CLI',
     why: options?.why ?? 'Database connection is required for this command',
     fix: `${runHint}, or set \`db: { connection: "postgres://…" }\` in prisma-next.config.ts`,
+    ...(options?.missingFlags !== undefined
+      ? { meta: { missingFlags: [...options.missingFlags] } }
+      : {}),
   });
 }