[thekevinbot]

Fixes #1490

Verifies dirsql server --frontend through every distribution and documents it. There are no runtime changes: the frontend already ships in every artifact. This PR proves it and keeps it proven.

What changed

• internals/distcheck: a new frontend/ probe. Both the python (installed wheel) and node (installed npm package) flows run the installed dirsql server --frontend --port 0 twice, once without and once with -c. Each run must:
  • print Frontend at <url>;
  • serve / and /frontend.js byte-equal to packages/rust/src/cli/frontend.{html,js};
  • answer a real POST /query (a path-table query without -c, a declared-table query with it);
  • exit 0 on SIGTERM.
• packages/rust/tests/cli_e2e.rs: the standalone binary runs the same page, script, and query checks with and without -c, and confirms a graceful stop.
  • On unix it sends SIGTERM and requires exit 0.
  • On Windows it kills the process, so the Windows evidence (the Windows tests job runs cargo test --features cli --tests) covers serving and queries, not the signal path.
• packages/rust/tests/crate_contents.rs: the crate archive must list both asset files.
• Docs:
  • docs/reference/cli.md adds the startup output, invocation parity across npx/uvx/cargo, a path-table and a declared-table example, and shutdown.
  • docs/context/usage.md adds a short "Browser" section. It uses inline code only, because fenced uvx dirsql blocks are executed by context_examples_e2e.
  • PARITY.md now separates shared CLI support from programmatic server APIs; there are none in the Python or TS SDKs.
  • internals/distcheck/README.md describes the new probe.

No new Python or TS APIs.

Packaging evidence

Asset inclusion. Each artifact contains exactly one embedded copy (from grep -a over each artifact for a marker unique to the page and one unique to the script):

Artifact	Page copies	Script copies	Loose asset files
CLI binary	1	1	none
wheel _dirsql.abi3.so	1	1	none
napi dirsql.linux-x64-gnu.node	1	1	none

The main npm tarball and the wheel contain no frontend.* files. The sdist carries packages/rust/src/cli/frontend.{html,js}, as source to compile. cargo package --list lists both files, and crate_contents.rs asserts it.

Size deltas. Method: HEAD compared with the same tree built with both assets truncated to 0 bytes. Both builds used the release profile on linux-x64. The raw assets are 13,228 B, or 4,654 B gzip -9.

Artifact	Baseline	With frontend	Delta
CLI binary, raw	7,491,704	7,504,888	+13,184
CLI binary, gzip -9	3,424,903	3,429,515	+4,612
CLI binary, xz -9	2,617,640	2,621,536	+3,896
napi addon, gzip -9 (npm platform tarball proxy)	3,543,913	3,548,493	+4,580
wheel (zip)	3,680,308	3,685,515	+5,207

That is about 0.13% per compressed artifact, with no duplication.

Manual verification

All checks ran in a fixture with posts/{hello,second}.json and a .dirsql.toml declaring posts (on-file = "cat").

• Standalone binary. Ran target/release/dirsql server --frontend --port 7311 -c .dirsql.toml. It printed Frontend at http://localhost:7311/ and then Running at localhost:7311.
  • curl / returned 200 text/html, 3607 B.
  • /frontend/state returned the root and posts(title TEXT, author TEXT).
  • POST /query with SELECT title, author FROM posts returned both rows, and the path-table SELECT basename, size FROM './posts' returned both files.
  • SIGTERM ended it with exit 0.
• Headless Chrome (agent-browser) against the same server:
  • The page rendered the "Path-tables" and "Declared tables" sections.
  • Clicking posts and then Run showed 2 rows returned (Hello/alice, Second/bob).
  • The path-table starter query ran.
  • SELECT nope FROM posts showed Query error (HTTP 400): ... no such column: nope.
• Diagnostics. Ran dirsql server --frontend -c bad.toml with invalid TOML. /frontend/state returned 503 with the TOML parse diagnostic, and the browser showed "Configuration could not load", the diagnostic, and the restart hint.
• Launchers. Both flows exercise the packaged launchers through the new probe:
  • uv run --project internals/distcheck dirsql-distcheck python (wheel built with maturin, installed into a fresh venv) printed python packaging distcheck: OK.
  • pnpm build, then uv run --project internals/distcheck dirsql-distcheck node (packed and installed tarballs) printed node packaging distcheck: OK.

Choices made

• Distcheck is the launcher check. The installed-artifact frontend checks live in the existing packaging distcheck tier rather than a new suite. CI runs it on ubuntu for both packages on every packages/rust/** change.
• Windows evidence covers serving and queries only. The test cannot deliver SIGTERM or Ctrl-C to a child on Windows, so there it kills the process. The signal path is proven on unix in cli_e2e and in distcheck.
• No timeouts in the probe. It reads the first stdout line and makes blocking HTTP requests. A hang surfaces as the CI job timeout.
• Size baseline is HEAD with the assets truncated, not a previous release. This isolates the frontend from unrelated changes.

E2E Verification

No receipt is owed. The diff touches no scoped source: nothing under packages/rust/src, the bindings, or packages/*/tests/e2e. Commands run:

• cargo test -p dirsql --features cli --test cli_e2e --test crate_contents --test context_integration --test context_examples_e2e: pass.
• Both distcheck flows: OK (see above).

Changelog / Migrations

• No fragment needed: no public package source changed. The tests are under packages/rust/tests (exempt); the rest is internals/ and docs.