io.eezo.db.cli

The database layer's commands, as library functions. Ported from example/Cli.scala, which was their specification (design/cli.md §3); the two rules of layer 1 apply to every entry point here: return values, never print; take capabilities, not connections. The http layer's are in io.eezo.http.cli.Commands, in the same shape.

dbSchema is the Postgres schema commands introspect, defaulting to public the way Introspect.snapshot does. It is a parameter for the same reason Freeze.defaultDbDir is: with it baked in, nothing here could be exercised outside the real database of whatever process is running; the suites isolate by Postgres schema, and pass their own.

freeze takes no capability: it diffs the committed snapshot against the code and writes files, and the live database is deliberately not consulted (that is sync's job). Front ends must not install a Database to run it.

What drop removed, by table name. The ledger is dropped too but not listed: Introspect hides it from every snapshot, so listing it here would name a table no other command admits exists.

The migration written, if there was drift to write. resolutions records what decide answered per change, so a front end can echo what was accepted, skipped, or hand written.

The four ways migrate ends. drift is DeployCheck's answer after the ledger is settled: empty means the database matches the model.

One on disk migration the ledger has not seen, as Migrator.status reports it.

The text front end's rendering: result values in, String out, printing left to the caller.

This is example/Cli.scala's output, moved. It stays a separate object from Commands because it is one front end among several (the JSON renderer is the same shape over the same values), and because layer 1's rule is that nothing in it decides what a user sees.

The machine front end: the same result values Render turns into text, as JSON.

This is design/objective.md's "every step emits machine-readable output" landing: an agent drives the loop on --json and never parses prose. It exists this cheaply only because layer 1 returns values; every function here is a fold over one of them.

The encoding is deliberately hand rolled over Json rather than derived: these shapes are a public contract for tools, and a contract should not silently change because a field was renamed in a Scala case class. Each object carries a "command" discriminator so a stream of results needs no out of band context.

Every change carries its sql alongside the classification, because the reader most likely to be here is deciding whether to run it.

The model/database diff. Empty means in sync.

The diff, what part of it blocks an unforced apply, and whether it was executed.

applied is false both when apply was never requested and when it was refused over blocked; the caller knows which flags it passed, so the distinction is the front end's to render rather than a field's to carry.