feat(preflight): make supported probe names discoverable #1589

Summary

Make the complete --preflight-tools contract discoverable from the Crabbox CLI, including accepted names, aliases, and target restrictions. When a user supplies an unknown name, point them to the same current list without acquiring a lease.

Problem to solve

crabbox run --help currently describes --preflight-tools as a comma-separated list but does not name the accepted values or identify a command that prints them:

-preflight-tools string
 comma-separated preflight tools to probe; overrides run.preflightTools

If a user chooses a conventional executable that is not registered, the command fails locally with no discovery path:

$ crabbox run --provider local-container \
 --preflight --preflight-tools curl -- true
unknown preflight tool "curl"
$ echo $?
2

The early exit is useful because a typo cannot silently remove diagnostics or create a provider resource. The problem is that the installed CLI does not tell the user which values would work. The complete list exists in the documentation and in the internal registry, but users must leave the failing command and search for it.

This gets harder as the registry grows. Current default probes, opt-in version probes, capability probes, aliases such as default, and platform-specific entries do not share one obvious naming rule. A valid name may also be skipped on a target where it has no supported command.

Proposed behavior

• Provide a CLI-owned way to inspect every accepted preflight probe name without provisioning, connecting to a coordinator, or selecting a provider.
• Include the special selection names such as default and none and explain what they do.
• Expose target support clearly enough to distinguish POSIX, WSL2, and native Windows behavior.
• Make the unknown-name diagnostic point to that discovery path or include a concise current alternative.
• Derive discovery output from the same contract used by validation so help and runtime acceptance cannot drift independently.
• Preserve exit 2 before lease acquisition for unsupported names.
• Keep run.preflightTools configuration aligned with the same discoverable names.

The exact interface can be a dedicated inspection command, generated command help, shell completion metadata, or another CLI-native form. The required outcome is that a user with only the installed binary can recover the accepted contract.

Acceptance criteria

• An installed Crabbox binary can print every name accepted by --preflight-tools without network access or provider mutation.
• The output includes default, none, every registered probe, and each probe's supported target class.
• Names accepted through run.preflightTools match the same output.
• Adding or removing a registry entry changes discovery output through the same source of truth or fails a drift test.
• crabbox run --help either includes the accepted contract or points to the command that prints it.
• An unknown name still exits 2 before acquisition and tells the user how to inspect valid names.
• The discovery path works without a configured coordinator or selected provider.
• Tests cover complete registry enumeration, special names, target metadata, help or error routing, and the unchanged pre-acquisition rejection.
• Run and configuration documentation describe the CLI discovery path rather than maintaining an unrelated list.

Affected area

• --preflight-tools help registration in internal/cli/run.go.
• The preflight registry and name validation in internal/cli/run_observability.go.
• CLI help or inspection-command tests in internal/cli.
• Run, observability, and configuration documentation.

These locations bind the feature because current source registers the flag separately from the registry that validates it.

Non-goals

• Accepting arbitrary executable names.
• Adding curl, Bash, Python virtual-environment readiness, or any other new probe.
• Changing the default probe set.
• Installing or upgrading remote tools.
• Running a probe as part of discovery.
• Turning an unsupported name into a warning or allowing the workload to continue.
• Replacing the detailed semantics already documented for individual capability probes.

Alternatives considered

Keep the list only in documentation

The current documentation is detailed, but it is separate from the binary that rejects a name. Users working offline or from a different release can read a list that does not match their installed executable.

Put every accepted value directly in the error

This helps one failure but can become noisy as the registry grows, and it does not provide a reusable inspection path for configuration authors or automation. A concise error that points to CLI-owned discovery keeps the failure readable.

Accept any executable name

That removes the discovery problem by weakening validation. It also loses target-specific command contracts and the current protection against misspellings before provider acquisition.

Supporting context

• Latest release baseline: v0.47.0 at 0a55378990265271f5830a465aa643605d7d41f3.
• Exact current main: c28a13005bb10dc093ecb81675b27181a796a069.
• Current-main binary SHA-256: 1f0b94d12838b66a256f94e85882e4a55c8bf3c4fe9b2d3e223880d3dd5a8e18.
• Build toolchain: go1.26.5 darwin/arm64.

The complete 10-commit range from v0.47.0 through exact current main, the full live corpus of 25 open issues, all 17 open issues authored by coygeek, all 19 open pull requests, and relevant closed issues and merged pull requests were checked. No current item requests a CLI-owned list of supported preflight probe names or routes unknown-name errors to one.

Open issue #1585 requests one new Bash probe and preserves the existing unknown-name guard. It does not make the complete registry discoverable. Merged pull request #1402 added the CMake probe and its documentation, but it also leaves registry discovery outside the installed CLI.