site serve and view: name the known sites when the id is missing or unknown #250

Merged

vnprc merged 6 commits from agent/site-name-known-sites into master

2026-09-29 02:02:01 +01:00

allod-agent commented

2026-09-29 01:47:43 +01:00

Member

allod site view and allod site serve now print the sites that have a preview when no site id is given or the id is not in the registry, so the id can be found from the command itself. Only messages and help text change; nothing that starts, stops or forwards a preview is touched.

What changes for a running machine: three refusals say more. allod site view with no site, allod site serve --vm <name> with no site, and an unknown id in either command now list the known sites with their ports, and name the closest id when exactly one is close.
What stays identical: every exit code (still 1 on these paths), every message's first line, where the messages go (standard error), and every path that succeeds today.
What proves it: tests over a fixture registry for each case in the issue, and the built binary run by hand; the output is under Validation.
If it is wrong: revert this PR. It keeps no state and changes no file format.

Closes allod/tools#248

What it looks like

$ allod site view example/bl
allod: unknown site: example/bl has no entry in <inventory>/scripts/repositories.json
allod: closest known id: example/blog
Known sites:
  example/bad   preview_port is not usable
  example/blog  18601  (vm-one)
  example/docs  18602  (vm-one vm-two)

$ allod site view
allod: site view needs a site id
Known sites:
  example/bad   preview_port is not usable
  example/blog  18601  (vm-one)
  example/docs  18602  (vm-one vm-two)
Usage:
  allod site view [--vm <name>] [--port <n>] <site>

Run 'allod site view --help' for details.

What changed

cmd/allod/site_list.go, new: the list, the closest-id rule, and the two messages.
cmd/allod/site_view.go, cmd/allod/site_serve.go: the four call sites, one line each.
cmd/allod/site_common.go: the usage block is rendered by a function both refusals share, and help text can name the registry file the running command actually reads.
serve --help and view --help gain one paragraph: a site id is the repository's key under repositories in the registry, with the path of that file.

Decisions the issue left open:

The closest id is decided in two tiers. If exactly one known id contains the typed text, it is named. Edit distance, at most 2, is consulted only when no id contains the text. Two or more candidates in the deciding tier name none. One pool for both rules fails on any registry whose ids share an owner prefix: example/bad is two edits from example/bl and made the prefix of example/blog ambiguous.
An entry whose preview_port is malformed is listed, marked preview_port is not usable. It is neither hidden nor allowed to stop the list.
The machines that list a site are shown on all four paths when vm-specs.json is readable, and left out silently when it is not.
A registry with no previewable site prints one line naming the registry file.
allod site serve with no site and no --vm is unchanged: the site is the checkout the current directory sits in.

Risk

R1. The change is confined to refusal paths that exit before anything is resolved, started or forwarded.

Worst credible failure: a misleading hint, or a list that omits a site. The reader is where they are today, with the registry file named in the first line.
The list reads registryPath(), so on a dev VM it lists what that machine's registry holds. Which registry that is belongs to allod/archetypes#119.
This branch and the one for allod/tools#249 both edit site_view.go and site_serve.go, on different lines. Whichever merges second needs master merged into it first.

Validation

Run on this branch at 99a55cf:

go test ./..., go test -tags site ./..., go test -tags secret ./..., go test -tags site,secret ./..., each with -count=1: all seven packages ok in each of the four runs.
go vet ./... and gofmt -l .: no output.
allod check: All 11 steps passed (checks: 9 built).
The built binary against a registry of four entries, two with a port, one without, one with "preview_port": "80": site view, site serve --vm vm-one, site view example/bl, site view example/d, site view example. Each exits 1. The second and third name example/blog and example/docs; example, which three ids contain, names none. Two of those runs are quoted above.
The closest-id test was shown failing on the one-pool rule before the rule was changed, and the edit-distance boundary test was shown failing with the threshold set to 1.

The last commit changes comments only: no line outside a comment differs from 99a55cf, apart from blank lines. On it the four go test runs, go vet and gofmt -l were repeated and are clean. allod check and the runs by hand were not repeated on it.

Not run: nothing on a second machine. None of these paths reaches ssh, nix or systemd-run.

Review

R1, so no external reviewer. The integrator's read found the one-pool defect above by running the binary against a registry the tests did not have, and one fix round followed.

`allod site view` and `allod site serve` now print the sites that have a preview when no site id is given or the id is not in the registry, so the id can be found from the command itself. Only messages and help text change; nothing that starts, stops or forwards a preview is touched. - **What changes for a running machine:** three refusals say more. `allod site view` with no site, `allod site serve --vm <name>` with no site, and an unknown id in either command now list the known sites with their ports, and name the closest id when exactly one is close. - **What stays identical:** every exit code (still 1 on these paths), every message's first line, where the messages go (standard error), and every path that succeeds today. - **What proves it:** tests over a fixture registry for each case in the issue, and the built binary run by hand; the output is under Validation. - **If it is wrong:** revert this PR. It keeps no state and changes no file format. Closes allod/tools#248 ## What it looks like ``` $ allod site view example/bl allod: unknown site: example/bl has no entry in <inventory>/scripts/repositories.json allod: closest known id: example/blog Known sites: example/bad preview_port is not usable example/blog 18601 (vm-one) example/docs 18602 (vm-one vm-two) ``` ``` $ allod site view allod: site view needs a site id Known sites: example/bad preview_port is not usable example/blog 18601 (vm-one) example/docs 18602 (vm-one vm-two) Usage: allod site view [--vm <name>] [--port <n>] <site> Run 'allod site view --help' for details. ``` ## What changed - `cmd/allod/site_list.go`, new: the list, the closest-id rule, and the two messages. - `cmd/allod/site_view.go`, `cmd/allod/site_serve.go`: the four call sites, one line each. - `cmd/allod/site_common.go`: the usage block is rendered by a function both refusals share, and help text can name the registry file the running command actually reads. - `serve --help` and `view --help` gain one paragraph: a site id is the repository's key under `repositories` in the registry, with the path of that file. Decisions the issue left open: - **The closest id is decided in two tiers.** If exactly one known id contains the typed text, it is named. Edit distance, at most 2, is consulted only when no id contains the text. Two or more candidates in the deciding tier name none. One pool for both rules fails on any registry whose ids share an owner prefix: `example/bad` is two edits from `example/bl` and made the prefix of `example/blog` ambiguous. - **An entry whose `preview_port` is malformed is listed, marked `preview_port is not usable`.** It is neither hidden nor allowed to stop the list. - **The machines that list a site are shown on all four paths** when `vm-specs.json` is readable, and left out silently when it is not. - A registry with no previewable site prints one line naming the registry file. - `allod site serve` with no site and no `--vm` is unchanged: the site is the checkout the current directory sits in. ## Risk R1. The change is confined to refusal paths that exit before anything is resolved, started or forwarded. - Worst credible failure: a misleading hint, or a list that omits a site. The reader is where they are today, with the registry file named in the first line. - The list reads `registryPath()`, so on a dev VM it lists what that machine's registry holds. Which registry that is belongs to allod/archetypes#119. - This branch and the one for allod/tools#249 both edit `site_view.go` and `site_serve.go`, on different lines. Whichever merges second needs master merged into it first. ## Validation Run on this branch at `99a55cf`: - `go test ./...`, `go test -tags site ./...`, `go test -tags secret ./...`, `go test -tags site,secret ./...`, each with `-count=1`: all seven packages `ok` in each of the four runs. - `go vet ./...` and `gofmt -l .`: no output. - `allod check`: `All 11 steps passed (checks: 9 built).` - The built binary against a registry of four entries, two with a port, one without, one with `"preview_port": "80"`: `site view`, `site serve --vm vm-one`, `site view example/bl`, `site view example/d`, `site view example`. Each exits 1. The second and third name `example/blog` and `example/docs`; `example`, which three ids contain, names none. Two of those runs are quoted above. - The closest-id test was shown failing on the one-pool rule before the rule was changed, and the edit-distance boundary test was shown failing with the threshold set to 1. The last commit changes comments only: no line outside a comment differs from `99a55cf`, apart from blank lines. On it the four `go test` runs, `go vet` and `gofmt -l` were repeated and are clean. `allod check` and the runs by hand were not repeated on it. Not run: nothing on a second machine. None of these paths reaches `ssh`, `nix` or `systemd-run`. ## Review R1, so no external reviewer. The integrator's read found the one-pool defect above by running the binary against a registry the tests did not have, and one fix round followed.

allod-agent added 5 commits

2026-09-29 01:47:43 +01:00

Give the no-id usage lines a renderer the new case can share 9e91940e12

siteCommandUsageError's Usage:/--help tail moves into
siteCommandUsageLines so a second caller can print it after its own
content instead of duplicating it. siteUsageText and siteCommandHelp
now pass their assembled text through renderSiteDetail, which fills
in a registry-path placeholder at render time rather than baking a
stale one in at init(), since the path depends on $INVENTORY.

Refs allod/tools#248

Name the known sites when a site id is missing or unknown 6f567779c3

'site view' and 'site serve --vm' with no id, and an id the registry
does not list in either command, used to leave the reader with a bare
message and a file path. They now print the registry's ids that carry
a preview_port, sorted, with their port and, where vm-specs.json is
readable, the machines that list them; a malformed preview_port is
shown marked unusable rather than hidden or fatal. An unknown id also
gets a closest-match guess when exactly one known id contains it or is
within 2 edits of it (Levenshtein, written out: standard library
only) - two qualifying ids name neither. An empty list states so in
one line naming the registry file. Exit codes are unchanged: every one
of these paths still exits 1.

The new logic lives in site_list.go/site_list_test.go, away from
site_serve.go and site_view.go, which allod/tools#249 is editing at
the same time; only the four call sites move to the new functions.
The help for 'serve' and 'view' gains one shared paragraph, via the
existing siteSharedDetail mechanism, naming what a site id is and
where the registry file is.

Refs allod/tools#248

Decide the closest site id by tier, not one pool b0d468b9c2

siteListClosest counted containment and edit distance as one pool, so
an unrelated id within edit distance of the given text could make an
otherwise unique containment match look ambiguous - real on any
registry where ids share a long owner prefix. Now: containment decides
alone when any id qualifies (one names it, two or more name none,
whatever the distances); edit distance is only consulted when no id
contains the given text at all.

Refs allod/tools#248

Align the known-sites list columns 85f0157478

Pad each entry's id to the width of the longest one so the ports (and
the machines, when shown) line up.

Refs allod/tools#248

Trim comments to a contract, a trap, or a pointer 99a55cf39e

No behavior change. Drops narration of what the code already says by
its names, and of which issue and which other file's edits this was
kept away from - git and the forge already carry that. What's left:
the one trap siteListEntries' own comment names (previewPort dies,
this must not), and one line per remaining function stating what its
name does not.

Refs allod/tools#248

allod-agent commented

2026-09-29 01:58:48 +01:00

Author

Member

Owner request: cut down the verbose comments in this PR, as on allod/archetypes#120. Follow-up commit to come on this branch; no behaviour change.

allod-agent added 1 commit

2026-09-29 02:00:43 +01:00

Cut the known-sites comments down ef380c8d32

Each comment that stays names a trap in one to three lines. The ones that
said what a function or a test does are gone: the names say it. No code
changes.

Refs allod/tools#248