Desktop workbench: connections, catalogue, run, shell, compose, declare

Status

Done

Version

1.0.0

Component

desktop — packages/sape-desktop

Commits

e0eb53b, 44f3b60, fede633, 2eb2ddf, 20ef519, 79987b8, 89db51a

Description

A desktop window onto sapedb databases, built with Wails v2 — Go underneath, a webview on top. Go because the protocol client is Go and nothing has to be reimplemented in another language to reach the server; a webview because a tree and a data grid are two things a native toolkit makes hard and a browser engine makes ordinary.

The shape of the room is a professional database tool's: navigator on the left, tabs in the middle, results below, status bar along the bottom. What hangs in the navigator is not tables and there is nowhere to type SQL, because this database has neither. What a caller may do is an operation somebody declared; what an operator may do besides that is a typed access with exactly the shapes a declaration may have.

What works:

• Several connections at once, each its own socket with its own catalogue and its own tabs; closing one leaves the rest alone.
• The navigator, read from the server — collections with their indexes, and operations, fetched with the protocol's own catalogue request.
• Running a declared operation, through a form built from what the operation declares, with arguments converted to the declared types before they are sent.
• Exploring a collection — a get, a scan or a count, the only three shapes the server lets an operator type, with the declaration shown next to the rows.
• An interactive shell tab, reusing the connection's own socket.
• Composing and declaring — pick legs, pin versions, see the ceiling, and the Declare button writes it over this connection's socket. No restart, no other connection dropped. SAPE-19 and SAPE-20 are what this screen spends.
• Calling an older version by number, for any version the window has seen declared — SAPE-23.

Why it was in 1.0.0

It is the first thing that spends the release's protocol work on somebody who is not writing code, and it is the only place the new frames were exercised by a long-lived process holding connections open — which is exactly the case that made "many connections alive" and "add an operation" mutually exclusive before SAPE-19.

It also turned the protocol's silences into visible product decisions. An empty tree and a refused catalogue look identical and mean opposite things; a window has to pick one, and picking it forced the server's challenge-for-the-secret rule to be stated rather than assumed.

How it was verified

1. go test ./... builds sapedbd and sapedb from the sibling package, starts a server on a port of its own with a data directory of its own, declares a schema, and runs every method of the workbench against it — internal/workbench/live_test.go, plus declare_live_test.go, compose_live_test.go and shell_live_test.go. Nothing is stubbed: both of the bugs these tests exist for were the server telling the truth and a client misreading it, and no mock catches that.
2. Two rules those tests keep, each already paid for once: an empty list of tests is not a passing run — every file's first test is a known-positive on the same path as the ones after it, so a green run cannot be a run where nothing happened; and a refusal proves nothing without the acceptance next to it — every must-fail case runs the same path with valid input first and fails loudly if that does not succeed.
3. The window's own half: frontend/ npm test, with frontend/src/shape.test.ts covering the one place the window converts the server's shapes.
4. 89db51a is the workbench following SAPE-22: a count declares its walk here too, and one test's premise inverted when it did — measured, not assumed.
5. scripts/demo-server.sh prints two connection strings, the second for a database with nothing declared in it, because that is the case every new user meets first.

What it did not do

• It cannot declare a collection. That still needs the server stopped and sapedb apply run by hand, and the window says so rather than offering a button that would only fail. Blocked on SAPE-14.
• No Commanders, no Shapes, no collection creation, and no External Operations administration screen. Commanders and Shapes appear in the navigator marked planned, in the place they will live — space left rather than the idea left out.
• No signed or notarised build, no auto-update, and no published artifact; wails build produces a bundle in build/bin and that is where it stops. The bundle identifier is set (e8b86fd), which is the part that cannot be changed later for free.
• The Go toolchain it is developed against is not installed system-wide, so every documented command wants GOROOT pointed at it. That is a note in a README, not a packaging story.
• It presents no scope grant, because the Go client it is built on gained Present and the window has no screen for one — ISS-11's lifecycle question is unanswered here too.
• The status bar says the account, the database, whether the connection may explore and the last round trip — but not which build of the server answered, which SAPE-1 now makes available in the welcome.