Spec: create a managed database from the terminal and watch it come up #28

Problem Statement

The terminal UI shows what an account already has. It cannot add anything. Creating a managed database today means leaving the terminal, working a five-step browser wizard, and then watching a blurred overlay for about two minutes with nothing else to do. The CLI registers postgres create but answers not implemented yet, so a terminal user has no path to a new database at all.

Two things are missing, and they are the two halves of one task: a way to ask for a database, and an honest account of what the platform is doing while it builds one.

Solution

Create a managed database from the terminal, and watch it come up in the same screen.

The user picks the shape of the database on a form whose choices come from the platform, sees the exact request before it is sent, and confirms it. From there a receipt replaces the wait: one row per step the platform really ran, a marker on the row it is on right now, and an elapsed clock that stops when the run settles. A failed run names the step it died on and the reason.

The receipt is the same one the console shows, on purpose, and it holds the same rule: every row is confirmed by something the platform actually emitted. No row advances because time passed, no bar moves because a second went by. What nobody confirmed says so.

User Stories

1. As a terminal user, I want to create a managed database without leaving the terminal, so that I can stay in the tool I am already working in.
2. As a terminal user, I want the form to offer the engines, versions, regions, instance types and storage types the platform actually supports, so that I cannot ask for something that does not exist.
3. As a terminal user, I want each field checked as I fill it in, so that I learn about a bad value before the end.
4. As a terminal user, I want to see the exact request I am about to send, so that I know what I am buying.
5. As a terminal user, I want the estimated monthly cost before I confirm, so that price is part of the decision and not a surprise.
6. As a terminal user, I want confirming to be its own deliberate step, so that no single keystroke can spend money.
7. As a terminal user, I want the new database's progress shown while it builds, so that the wait is not a blank screen.
8. As a terminal user, I want every progress line to be confirmed by the platform, so that I can trust what the screen claims.
9. As a terminal user, I want to know which step is happening now, so that I can tell slow from stuck.
10. As a terminal user, I want the elapsed clock to freeze when the run ends, so that a finished database never looks like it is still building.
11. As a terminal user, I want a failed run to name the step it died on and the reason, so that I can act instead of guessing.
12. As a terminal user, I want the receipt rebuilt from the platform after a restart, so that a reload does not lose the progress I was watching.
13. As a terminal user, I want one list of everything provisioning right now, so that I can watch several at once.
14. As a terminal user, I want to open one instance's receipt from that list, so that I can read the steps of the one I care about.
15. As a terminal user, I want the new database to appear in the existing views as soon as the platform knows about it, so that I do not have to hunt for it.
16. As a terminal user, I want to be told when the platform refuses the request, in plain words, so that I know what to fix.
17. As a terminal user, I want the endpoint and credentials once the database is running, so that I can connect without visiting the console.
18. As a terminal user, I want credentials shown only when I ask for them, and never written to a file or a log, so that they cannot leak.
19. As a terminal user, I want demo mode to walk the same screens without creating anything, so that I can learn the flow safely.
20. As a maintainer, I want the receipt's rules in one pure function, so that the frontier and entailment rules are tested once and cannot drift between screens.
21. As a maintainer, I want the create request testable without sending it, so that no test can create a real database.

Implementation Decisions

• The receipt is a pure function of three things: the instance record, the activity-feed entries for that instance, and the current instant. Its rules, each one earned by a bug the console fixed:
  • the row in progress is the first unconfirmed row after the last confirmed one, never the first unconfirmed row anywhere, so one dropped event cannot leave a spinner under a ticked line;
  • a run that settled stops counting, on failure as well as on success, and falls back to the last beat observed rather than the current time;
  • the rows whose own event is hidden from the feed fall back to a signal that entails them, chained in order (an engine answering on its port was installed; an installed engine has a machine under it);
  • extra nodes of a high-availability instance are matched on the node's own identifier, and may be in progress at the same time as each other.
• Status is the authority for "connection open"; the feed only supplies a better stamp.
• A receipt is shown only for a genuine first provision. A restart, a resize or a configuration change emits none of these signals and must not produce a receipt that confirms nothing.
• The create is the platform's instance-create call, with the region as its query parameter and the chosen fields in the body. The response returns the new instance's identifier, and that is what the receipt opens on.
• The terminal UI writes to the platform API directly, in the same shape as its existing read plans. It does not go through the CLI's command layer, whose engine commands are registered but unimplemented; that layer can adopt the same calls later.
• Mutations are built as a request value that the source executes. The screen never posts for itself, which is what keeps the create path testable without a socket.
• The clock is a parameter of every row mapper. One load measures all rows against one instant, and a receipt renders identically in a test.
• Views to add: a provisioning list, the receipt behind a row, a create form, a review page, and a credentials panel for a running instance.
• While a run is in progress the view re-reads the record and the feed every few seconds and stops once every row has settled. A reply that arrives after the user has moved on is dropped.
• State shapes fixed by the prototype, kept as decided:
  • Step { label, detail, state: pending | active | done | failed, confirmedAt, elapsed }
  • Receipt { phase: in progress | ready | failed, steps, elapsed, failureDetail }

Testing Decisions

• A good test here names a behaviour a user would notice: the rows a payload produces, the sentence the footer shows, the request that would be sent. Private helpers are not tested directly.
• Read behaviour is tested at the mapper seam that already exists: pure functions over captured payloads. Prior art in this repo is the API mapper tests and the receipt-rule tests.
• Screen behaviour is tested by drawing to a test backend and reading the buffer, the way the existing layout tests do.
• Key handling is tested on the app state, the way the existing navigation tests do.
• The create path gets one new seam: a source that records the request instead of sending it. Tests assert the built request and the way a refusal is rendered.
• No test opens a socket, and no test can create a real database.

Out of Scope

• Receipts for resources created inside a project (the Coolify path), which report their own stages.
• "Talk to Database", query stats and log tails.
• Day-2 actions on an existing instance: start, stop, reboot, fork, resize, delete, failover.
• Wallet top-up, invoices, coupons and auto-recharge.
• Engine variants the terminal UI does not name yet: Kafka, vector and time-series flavours of Postgres.
• Cloud providers other than the organization's linked credentials.
• Making the CLI's own engine commands work; this spec is the terminal UI's path.

Further Notes

• The console's feature surface was scanned in three parts (database lifecycle, projects and deploys, account and platform). That backlog is wider than this spec; this spec is the provisioning path only, because it is the one path where the terminal has a real advantage: it can watch a long run better than a blurred overlay can.
• The Coolify resource receipt is the natural sibling, and shares the same receipt rules. It should reuse this spec's pure function rather than growing a second one.
• The two-minute wait is the reason this is worth building: it is the longest uninterrupted attention anyone gives a new database.