Add a local interface, served by the package itself

[Elnazkarami]

A GUI a lab can install and use on its own machine.

Why the old one could not be that

It was a static page that read JSON someone dragged into it — no way to reach a drive or run anything. A browser page cannot do either. So the interface is now served by a small local server that calls the same functions the command line does, rather than reimplementing the standard in TypeScript.

ndos gui

Binds to loopback, prints a URL, opens it. Nothing is exposed to the network.

The query page was giving a wrong answer

This is the part worth reading.

The page decided for itself which sessions matched, by comparing strings in the browser. A session whose species had never been entered compared unequal to mouse and was dropped. So it answered a question about missing evidence as though it were a question about contradicting evidence — and showed a cohort cleaner than the data supports. That is the one mistake this project exists to prevent.

It happened because the standard was implemented twice: once in Python, once in TypeScript. The query now runs where the rules live. The page sends constraints and renders what comes back — matched, excluded, and cannot be ruled out — with the evidence that placed each session in its group.

On a real project:

considered 11 · matched 0 · excluded 0 · unresolved 11
"11 could not be ruled out because species was never entered."

The old page showed 0 of 11, which reads as none of these are mice. None of them are anything yet. Nobody has said.

Four new endpoints, all read-only

open	Read a JSON document by name, instead of making someone drag a file in
link	Build a project's linked records in memory — table check --emit writes a file; nothing here needs that file to exist
check	Check the metadata tables against each other. The entry form judges one value at a time and cannot see across three files
query	The above

browse now offers files as well as folders, so a manifest is chosen the way a person refers to it: by name. Every other page follows — Manifest opens from disk, Validate checks the tables a project already has, and the home page no longer calls itself browser-only, because it reads drives now.

Security

This serves a program that will read any path it is pointed at, so it is treated as one: loopback only; a token generated at startup and given only to the page it opened; a local Host required; any foreign Origin refused — which is what stops a site you have open in another tab from reading your disk. All four are tested.

Keeping the shipped copy honest

The interface ships built, so installing the package is the whole install: no Node, no npm, no build step. The risk is that the bundle falls behind its sources invisibly — hashed filenames, unreadable contents. scripts/vendor_gui.py records a fingerprint of gui/ beside the build and a test fails when they diverge. The check needs no Node, so it runs everywhere the tests do; CI separately builds from source and byte-diffs against the committed copy, which passes.

The drift is fixed at the source

Field definitions are generated from ndos_table instead of copied by hand. The copy had drifted: the interface offered male/female where the standard says F/M, and could not express lesion — a lab doing lesion studies had no way to record one.

What testing found rather than assuming

• The first wheel contained no interface files at all. The publish workflow now opens the wheel and refuses without it.
• scan reported a file count climbing towards no total and no time remaining. progress asks for terminal output, but was also silently deciding whether to count the work up front — so a page passing progress=False plus a callback got neither. Now 3,598 of 28,345 · ~7s left.
• Two faults vite build cannot report because it does not typecheck: the router was never handed the query client its root route declares, so it wrapped the tree in a provider containing undefined; and the field adapter set optional properties to undefined rather than omitting them.
• A relative API path, so a page opened at /local/ would have 404ed every call.
• An unflushed startup banner — and that banner carries the token, the only way in.
• Picking a file instead of a folder returned a 500 showing the word ValueError.
• npm ci could not install: package.json and package-lock.json disagreed about ajv, and had before any of this work. Invisible because an existing node_modules made npm run build succeed.
• CI found two more in this branch: the fingerprint hashed files as they sit on disk (Windows gets CRLF) and sorted Path objects (case-folded on Windows only). Both fixed by reproducing the exact fingerprints CI reported.

Also removed

The error reporting left over from the editor this was started in — a vendor's global hook, dead outside their preview. A tool that reads research drives should not carry a reporting path nobody asked for.

Verified

Every page rendered in a real browser, headless: all four mount, every picker lists actual directories, and each endpoint answers over HTTP. A query nobody can parse comes back as words, not a stack trace. A wheel installs into a clean venv, pulls in nothing third-party, and serves the page.

319 → 364 tests. All ten CI jobs green.