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

New issue

Closed

opened 2026-09-29 01:08:30 +01:00 by vnprc-agent · 0 comments

vnprc-agent commented

2026-09-29 01:08:30 +01:00

Contributor

Let someone who does not know a site's id find it from allod site itself, so a first use of allod site view does not end in reading the registry file by hand.

Primary goals:

No id, a list — allod site view and allod site serve --vm <name> with no site print the ids that have a preview, with their ports, beside the usage.
Wrong id, a list — unknown site names the known sites, and says which one is closest when one is.
The id is explained once — the help says a site id is the repository's key in the registry, and where that file is.

Current state

The id is the key of the repository's entry in scripts/repositories.json of the inventory. Nothing prints those keys. A site's id is its registry key, not its domain and not a shortened name, so a guess from the site's name fails.

Observed on a hypervisor, for a site the registry lists with a preview_port:

$ allod site view --vm <vm>
allod: site view needs a site id
Usage:
  allod site view [--vm <name>] [--port <n>] <site>

$ allod site view --vm <vm> --port <n> <shortened name>
allod: unknown site: <shortened name> has no entry in <inventory>/scripts/repositories.json

Neither message says what a valid id looks like or which ones exist. The second names a file, which is correct and leaves the reader to open it and find the key.

Receipts, at 3f917eb:

cmd/allod/site_view.go:27, site view needs a site id
cmd/allod/site_view.go:31 and cmd/allod/site_serve.go:145, unknown site
cmd/allod/site_serve.go:89, --vm needs a site id
cmd/allod/registry.go:62, registryEntries, which already holds every entry, and registry.go:28, previewPort

Default

The list is the registry's entries that carry a preview_port, sorted by id, one per line with the port. With view, and where vm-specs.json is readable, each line also names the machine that lists the site, since that is the other value view resolves. A registry with no such entry says so in one line.

For unknown site, the closest id is offered only when exactly one known id contains the given text or is within a small edit distance of it; otherwise the list alone.

A separate allod site list command is the alternative. It is left as a follow-up: the two error paths are where the reader is when they need the list.

Validation

With a fixture registry of three sites, two with a port: no id prints the two, sorted; an unknown id prints the same two; an id that is a prefix of one known id names that one.
A registry with no previewable site prints the one-line statement and exits 1.
Exit codes do not change: both paths still exit 1.

Scope

In: the two messages, the help text, their tests. Out: which registry a dev VM reads, tracked in allod/archetypes#119; a fallback port, filed separately.

Let someone who does not know a site's id find it from `allod site` itself, so a first use of `allod site view` does not end in reading the registry file by hand. Primary goals: - **No id, a list** — `allod site view` and `allod site serve --vm <name>` with no site print the ids that have a preview, with their ports, beside the usage. - **Wrong id, a list** — `unknown site` names the known sites, and says which one is closest when one is. - **The id is explained once** — the help says a site id is the repository's key in the registry, and where that file is. ### Current state The id is the key of the repository's entry in `scripts/repositories.json` of the inventory. Nothing prints those keys. A site's id is its registry key, not its domain and not a shortened name, so a guess from the site's name fails. Observed on a hypervisor, for a site the registry lists with a `preview_port`: ``` $ allod site view --vm <vm> allod: site view needs a site id Usage: allod site view [--vm <name>] [--port <n>] <site> $ allod site view --vm <vm> --port <n> <shortened name> allod: unknown site: <shortened name> has no entry in <inventory>/scripts/repositories.json ``` Neither message says what a valid id looks like or which ones exist. The second names a file, which is correct and leaves the reader to open it and find the key. Receipts, at `3f917eb`: - `cmd/allod/site_view.go:27`, `site view needs a site id` - `cmd/allod/site_view.go:31` and `cmd/allod/site_serve.go:145`, `unknown site` - `cmd/allod/site_serve.go:89`, `--vm needs a site id` - `cmd/allod/registry.go:62`, `registryEntries`, which already holds every entry, and `registry.go:28`, `previewPort` ### Default The list is the registry's entries that carry a `preview_port`, sorted by id, one per line with the port. With `view`, and where `vm-specs.json` is readable, each line also names the machine that lists the site, since that is the other value `view` resolves. A registry with no such entry says so in one line. For `unknown site`, the closest id is offered only when exactly one known id contains the given text or is within a small edit distance of it; otherwise the list alone. A separate `allod site list` command is the alternative. It is left as a follow-up: the two error paths are where the reader is when they need the list. ### Validation - With a fixture registry of three sites, two with a port: no id prints the two, sorted; an unknown id prints the same two; an id that is a prefix of one known id names that one. - A registry with no previewable site prints the one-line statement and exits 1. - Exit codes do not change: both paths still exit 1. ### Scope In: the two messages, the help text, their tests. Out: which registry a dev VM reads, tracked in allod/archetypes#119; a fallback port, filed separately.

vnprc-agent referenced this issue

2026-09-29 01:13:21 +01:00

site serve and view: pick a free port when the registry gives none, and report a held port as taken #249