wado-cli

The wado binary. It drives wado-compiler and wado-lsp, hosts the wasmtime runtime for run / serve / test, and owns the Kiln and dependency backends.

How to use the CLI is the wado-cli skill, not this file.

Rules

• Argument parsing is hand-rolled on lexopt. Do not introduce clap or another parser framework. Each subcommand parses its own options and owns its usage and help text in its own module. run shares its parser with the runners, in wado_host::runner.
• Shared knobs are declared once in wado_host::options, in three families. knobs.rs holds what applies them to wado's own types. CompileKnobs / CompileKnobOpt carry what the compiler is told: -O, --log-level, --allocator, -f, --no-cache. RuntimeKnobs / RuntimeKnobOpt carry what the wasmtime engine is built with: --collector, --gc-heap-initial, --report-fuel, --deny-process, --process-read, --process-trace. HostKnobs / HostKnobOpt carry how the wado process itself runs: --retain-memory, which main installs before the subcommand runs. A subcommand lists the subset it accepts and holds one field per family it uses. It declares no field, parse arm, or spec of its own for a shared knob, and a new one is added in wado_host::options only.
• --profile is not a shared knob, though run, serve and test all take it. Each accepts different modes and carries a different caveat, so each states its own spec.
• A short flag means one thing across the subcommands that compile: -f is --feature there, never --filter or --format. Outside that family only init -f (--force) claims it.
• -O takes its level attached and explicit (-O2); a bare -O is an error.
• process::exit belongs to main() alone. A subcommand returns CliExit (args.rs) from both its parse and its run, so there is exactly one exit path. Use CliExit::silent_failure when the subcommand has already printed its own diagnostics.
• Adding a subcommand means adding a Cmd variant in main.rs — it must appear in ALL and gain a name, args, and desc arm — plus its module. The name is taken for good: external.rs resolves only what Cmd does not hold, so a new builtin retires that name from wado-<name> on PATH. help is the one without a module: it answers out of the Cmd table and the PATH lookup, and both live in main.rs.
• The binary sets mimalloc as the global allocator: wado serve is allocation-heavy per request and the system allocator contends across threads.

Module Map

The modules a subcommand is named after hold that subcommand. The rest:

• runtime.rs — what only wado adds to the host wado_host::guest holds: the test-only imports, and the engines test and serve run on.
• kiln_provider.rs, kiln_wit.rs — how wado resolves a Kiln generator to its component. The pipeline and the runtime it feeds live in wado-host's kiln/. check runs the same pipeline compile does, writes included.
• manifest.rs, build.rs, build_dep.rs, dep_component.rs, fetch.rs, git.rs, oci.rs, registry.rs, publish.rs — wado.toml handling and the dependency backends behind wado-manifest's DependencyProvider seam.
• discover.rs, test_report.rs — source file discovery (shared by test, format, and query) and the progress digest. A directory argument goes through files_in_dir and a project-wide walk through discover_tree; a file named directly is taken as given, filters and all. The subcommand supplies only a Filters callback: filters_at naming its manifest section, or no_filters where a package's excludes must not apply (query references spans them). Directory expansion has no second implementation to drift from.
• external.rs — the wado-<name> files on PATH that wado --list names and wado help <name> runs. PATH only, and never an entry that is empty or relative, which the OS search would read as the current directory. See WEP: External Subcommands.
• run_cache.rs — what one CLI run resolves once and holds fixed: AOT generator components, generator resolutions, and a watch over the sources it read. wado test shares one across every fixture, so a mid-run edit cannot split the run and is named in the failure at the end. A scoped view of it also records what one compile read.
• input_cache.rs, fingerprint.rs — what a compile produced, keyed by the compiler and the run's options and checked against the files and environment variables it read. wado test keeps a pass in one (test_cache.rs) and run / serve a component (build.rs); core:eval's outcome cache shares the fingerprint. A file in no package caches in the user cache (cache::derived_dir), never beside itself.