explore: drive the CLI from an argtree Cli spec

[JPHutchins]

What this is

An exploration (not merge-ready — see Blockers) of replacing camas's hand-rolled argparse parser with a declarative argtree Cli spec, and consuming the typed result in dispatch instead of an Any-typed argparse.Namespace.

⛔ Blockers — resolve these argtree issues first

This PR rides on workarounds that should become first-class argtree support before merge:

• Allow build_parser/parse to use a custom ArgumentParser subclass (parser_class=) argtree#9 — parser_class= hook. camas's custom --help needs a CamasArgumentParser subclass; argtree owns parser construction. Bridged here via argparse's public parents=[...], but a real hook would drop the throwaway-parser dance.
• Support specs in mypyc/compiled packages (get_type_hints erases annotations) argtree#10 — mypyc support. argtree resolves field types at runtime via get_type_hints, which mypyc erases. Worked around by keeping the spec in an interpreted module (excluded from mypycify) + adding argtree to [build-system] requires. A documented pattern and/or an AST fallback would make this clean.
• Clearer error when a field name shadows a builtin used in another field's annotation argtree#11 — builtin-shadowing field names. A list field breaks get_type_hints for a later matrix: list[str]; renamed to list_. A clear ConfigError would have saved the head-scratch.

What changed

File	Change
src/camas/main/parser.py	Cli NamedTuple spec (one field per arg); build_parser builds it via argtree and adopts the actions into CamasArgumentParser through parents=; new reconstruct() wraps from_namespace. Excluded from mypyc.
src/camas/main/dispatch.py	Reads a typed Cli instead of poking the namespace; resolves the env-dependent --effects default here (None ⇒ absent ⇒ default_effects_expr(), "" ⇒ list Effects).
setup.py	parser.py added to _main_excluded (mypyc).
pyproject.toml	argtree added to runtime deps and [build-system] requires.
tests/main/test_parser.py	Read the typed Cli via reconstruct rather than the raw namespace.

The declarative spec is the core; three runtime/state-dependent behaviors stay imperative around it — the dynamic per-matrix-axis --PY flags, the task | expression positional metavar, and the --effects default. That "declarative core + imperative shell" shape is the honest result: argtree is great for the static surface, but camas's parser is unusually dynamic.

Why bother — the payoff

The win isn't the prettier spec; it's types. dispatch now consumes Cli (expression: str | None, dry_run: bool, …) instead of an argparse.Namespace where every field is Any. Under five strict type-checkers that removes a class of implicit-Any reads.

Verification (all green)

• --help output byte-identical to the current parser
• 639 tests pass, 100% coverage maintained
• All 5 type-checkers clean — mypy, pyright, ty, zuban, pyrefly
• mypyc wheel builds and runs end-to-end: compiled dispatch.so → interpreted parser.py → argtree get_type_hints(Cli), including dynamically-added --PY axis flags

Open question for review

Is the typed-dispatch readability worth (a) a new runtime dependency on a 0.x library and (b) parser.py no longer being mypyc-compiled? Leaning yes as an experiment; not an obvious slam-dunk over the working argparse.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (b6131bd) to head (2b9b1a3).

Additional details and impacted files

@@            Coverage Diff            @@
##              main       #31   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           54        54           
  Lines         5103      5116   +13     
  Branches       275       277    +2     
=========================================
+ Hits          5103      5116   +13     

Flag	Coverage Δ
unittests	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.