feat(cli-registry): drive install.sh and the Docker agent image from the CLI catalogue

[opticon454]

What this does

PR A made every run mode a data-driven CliEntry, but stopped at the server boundary. Everything outside the Node process still hand-maintains its own CLI list, and those lists have already drifted in ways that shipped:

• b6d0f1fa — "wire OMP into install.sh's CLI detection (it had none)". A user with only omp installed was told no AI CLI was found, and offered Claude Code.
• install.sh carried nine *_SEARCH_PATHS arrays, ~18 near-duplicate check_* / get_*_path functions, and three separate hand-written enumerations of all nine CLIs.
• The section comment above that code named six of the nine. The comment describing the drift had itself drifted.
• docker/agent.Dockerfile hardcoded its npm list, and the index.html hint describing the image omitted omp.

After this, adding a CLI to stock.ts and running npm run generate:cli-catalog wires it into the installer's detection, its install menu, its closing reminder, and the agent image's npm layer.

This is the second of the three PRs you staged: "install.sh + docker image reading the stock JSON, with the bash-3.2 fix and an enabled filter."

Shape

Neither consumer can import TypeScript, so the generator emits two committed artifacts:

Artifact	Consumer	Why not fetched
config/clis.stock.json	the Docker build, build-agent-image.mjs	a .mjs cannot import the TS registry
a marked block in install.sh	the installer itself	it runs via curl-pipe-bash before any checkout exists

npm run generate:cli-catalog writes both; --check fails on drift and runs in CI, and test/cli-catalog-sync.test.ts fails if either goes stale.

The embedded copy is the full catalogue. An earlier attempt fetched it with a hardcoded two-CLI fallback, which degrades silently on an empty response; there is no degraded mode to fall into now. An optional, opt-in refresh (CODEMAN_CLI_CATALOGUE_URL / CODEMAN_REFRESH_CLI_CATALOGUE=1) warns loudly on all three failure shapes.

Trust boundary, made mechanical

The server still never executes an entry's install command. install.sh executes only commands embedded in itself — same file, same TLS fetch, same commit as the one-liner that fetched it — and nothing pulled from the network at install time is ever run.

That is now structural rather than a convention: CLI_INSTALL_CMD_TRUSTED[] is written only by the generated block and is the array the menu executes; CLI_INSTALL_CMD_DISPLAY[] is what a refresh may overwrite and is display-only. test/install-sh-invariants.test.ts asserts the refresh function cannot write the executable array, and that it contains no eval.

The enabled filter

Your §3 finding: the earlier export carried no enabled field, so a CLI shipping disabled would still be baked into every image. The generated catalogue carries the flag and the image respects it.

It reads the stock catalogue, not the merged registry, so a user's ~/.codeman/clis.json cannot change what is inside an image tagged codeman/agent:base.

Every stock entry is enabled today, so that assertion would pass vacuously — a unit test feeds the pure helper a fabricated disabled entry so the fix is genuinely covered now rather than the first time someone ships one.

bash 3.2

macOS ships bash 3.2 and the documented install is a curl pipe into bash under set -euo pipefail, so no declare -A, mapfile, namerefs, ${x,,} or here-strings. The catalogue is parallel indexed arrays with offset/length windows into flat arrays rather than delimiters — safe for a $HOME with spaces, and a length-0 entry (the shell pseudo-CLI) is never iterated.

bash -n cannot see the failure mode that actually bites here: expanding an empty array under set -u is a runtime abort. So CI does both — bash -n, and executing the script inside a real bash:3.2 container with detection exercised end to end. That needed a sourcing guard (CODEMAN_INSTALL_SH_LIB) so the library half can be sourced without running the installer.

Behaviour changes, all in the installer

These are deliberate and worth your eye:

1. The install menu now offers five CLIs rather than two. It is built from the catalogue, so it lists every enabled CLI that is not installed and ships an install command. Gemini had a command in the registry and appeared in no list in the script at all.
2. Menu entries use the registry's labels — "Claude" rather than "Claude Code". Same trade already made for codeman doctor rows. A suffix map would just be the hand-maintained list again.
3. On a wget-only host the menu prints the commands instead of running them. The registry's commands call curl, whereas the two literals they replace went through download_to_stdout. Rewriting curl to wget inside a string about to be executed is the wrong instinct.
4. CODEMAN_NONINTERACTIVE=1 still defaults to Claude Code, unchanged.

docker/server.Dockerfile is deliberately untouched

#377 is still open and modifies it (#373 has since merged). Rather than edit a file another PR owns, its narrower CLI list is asserted as a declared omission list in test/docker-agent-image-coverage.test.ts, so the divergence is visible and reviewable without touching the file. Adding a CLI there, or changing the intent, now fails a test and forces the list to be restated.

Tests

Written in the order that makes each one non-vacuous, and each guard was proved by perturbing both sides.

File	What it pins
test/install-sh-detection-parity.test.ts	Written before deleting anything. The nine search-path arrays as literals, then that the registry's searchDirs × binaries reproduces them dir-major. They are not uniform (claude has ~/.claude/local, opencode has ~/go/bin and ~/.bun/bin), so silent narrowing means a user's installed CLI stops being found. Retargeted at the generated block afterwards.
test/cli-catalog-sync.test.ts	Both artifacts match stock.ts
test/install-sh-invariants.test.ts	Trust boundary, no eval in the refresh path, and no leftover per-CLI detection names — derived from CLI_IDS/CLI_ALL_BINS rather than an allowlist, which had already missed two
test/docker-agent-image-coverage.test.ts	Every enabled entry reaches the image via the arg or a special case carrying a written reason; no disabled entry does; a hostile package name is refused; the index.html hint names every binary
test/agent-image-build-args-parity.test.ts	The .mjs and the TS mirror produce the same packages, pairs and argv — two producers of one command line is exactly the shape that drifts, and the failure would be two different images under one tag

Verification: static gate green; bash -n clean; executed under a real bash:3.2.57 container; verified the Dockerfile ARG really word-splits (4 packages gives ARGC=4) and that the default still applies with no arg. Full suite diffed by test name against the master baseline — zero new failures.

Open questions for you

I did not want to decide these unilaterally:

1. Does "an enabled filter" mean the shipped flag only, or should install.sh also honour a user's ~/.codeman/clis.json disables? This does the shipped flag only.
2. Refresh opt-in (as here), or attempted by default with loud warnings?
3. Should CliDiscovery.install grow npmFlags / companionPackages so pi and deepseek stop being Dockerfile special cases? No for now, pinned with a test that demands a written reason for each.
4. Once fix(docker): bind-mount ownership, Compose override discovery, and the default runtime account #377 lands, should server.Dockerfile be wired to the catalogue (which would add pi/deepseek to the Compose image) or keep a deliberately narrower list?
5. shellcheck in CI now, or a follow-up issue?

Not in this PR

The frontend half — injecting window.__codemanCliCatalog and making mobile-overview.js / session-ui.js catalogue-driven — is held back as PR B2. Six of the thirteen open PRs touch those three files; splitting keeps this one conflict-free.

Separately, dsh_banner_probe in install.sh aborts on macOS bash 3.2 (local runner=() then "${runner[@]}" under set -u). It predates this PR and is reported rather than fixed here, to keep the diff reviewable.

Commits

• e71d954e test(install): pin install.sh's CLI detection paths before generating them
• 3c393196 feat(cli-registry): generate a CLI catalogue for install.sh and the Docker build
• 7c242802 refactor(install): drive CLI detection, the install menu and hints from the catalogue
• 9a1c1edf feat(docker): derive the agent image's npm CLI list from the catalogue
• e417b94d docs(cli-registry): document the catalogue's consumers and the trust boundary

🤖 Generated with Claude Code