A declared, typed contract for a program's arguments and environment
variables — one model describing both surfaces together, instead of
hand-rolled flag parsing plus undocumented env::var calls scattered
through a codebase.
What it is
A Rust library (argenv) plus a companion CLI (argenv-cli) built on
top of it. The core idea: declare Input<T>, Type, Arg, and Env
values once, and get argument parsing, environment-variable reading,
--help/usage text, a JSON Schema of the whole contract, and lint
diagnostics (typo suggestions on flag/env names, domain-rule
violations, deprecation warnings with compile-checked successor
references) all generated from that single declaration — rather than
kept in sync by hand across a parser, a help string, and a README.
Why it exists
Written first as a general-purpose crate, adopted as the CLI/env
foundation for atpret
(the automated, cross-platform DPI-bypass orchestrator under the
sync-dot-mesh org) rather than each project hand-rolling its own
argument parsing. atpret is its first real consumer and the source
of the "developed in parallel, battle-tested by real use" feedback
loop mentioned in the brainstorms below.
Structure
crates/argenv— the library: theInput<T>/Type/Arg/Envmodel,Invocation/resolve, lint diagnostics, JSON Schema generation.crates/argenv-cli— a companion binary (schema/check/lint/usagesubcommands), not published to crates.io.
Licensing
Dual MIT OR Apache-2.0 — the standard choice for a general-purpose
Rust library meant for arbitrary other projects to depend on. This is
deliberately different from atpret's own AGPLv3: AGPL on a
dependency would drag network-copyleft obligations onto every project
that adopts argenv, which is actively hostile to a crate with no
network behavior of its own.
Published
argenv on crates.io — currently
0.1.0. Releases are automated via git-cliff + release-plz: every
push to main maintains a standing release PR with the version bump
and changelog already computed; merging it triggers the actual
cargo publish and a GitHub Release.
This README is the current, synthesized shape of the project. The
reasoning behind each decision — including the mistakes and the
corrections — lives chronologically in
brainstorms/, one file per session, newest at the
bottom of the index there.