Rule out a CLI in this package
A command-line client over this library is a reasonable thing to want, and the reason is sharper than it was a week ago: the e-invoicing and integration methods return `serde_json::Value` and were verified against mocks rather than a live service, so "what does this endpoint actually return" is now a question the crate cannot answer without a new example per call. It still belongs in a sibling crate rather than this one. An argument parser would be the first dependency here that the library does not itself need, along with the first optional dependency and the first `[features]` section, in a `Cargo.toml` where every line currently justifies itself. It would couple the library's MSRV to a floor that moves on someone else's schedule — not a break today, `clap` 4.6.7 declares 1.85 against this crate's 1.88, so the entry records the figure with the date it was checked. And a CLI's flags are a compatibility surface, which one version number would force to move in lockstep with a library that tells callers to expect breaks in minor releases. For probing, `examples/` already covers it at no cost: `capture_shapes`, `seed_sample_data` and `smoke_test` are CLI-shaped programs configured from the environment, with the `IN_SMOKE_WRITE_HOST` guard to copy for anything that writes. Recorded the same way as the `updated_at` sync engine in the open questions — a different product, written down so the option is not forgotten rather than because it is rejected outright. No changelog entry: nothing about crate behaviour changed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
@@ -85,6 +85,38 @@ Invoice Ninja account to contribute.
|
|||||||
comparison in `COVERAGE.md`. The divergences — JSON instead of
|
comparison in `COVERAGE.md`. The divergences — JSON instead of
|
||||||
`form_params`, keeping the whole validation `errors` map, exposing bulk
|
`form_params`, keeping the whole validation `errors` map, exposing bulk
|
||||||
`download` only on PDF-rendering entities — are deliberate.
|
`download` only on PDF-rendering entities — are deliberate.
|
||||||
|
- **No CLI, and no binary at all, in this package.** A command-line client
|
||||||
|
over this library is a reasonable thing to want — it is the obvious way to
|
||||||
|
ask "what does this endpoint actually return", which matters here because
|
||||||
|
the e-invoicing and integration methods are typed as
|
||||||
|
`serde_json::Value` and were verified against mocks rather than a live
|
||||||
|
service. It belongs in a sibling crate (`invoiceninjars-cli`) in a
|
||||||
|
workspace, not in this one, for three reasons:
|
||||||
|
|
||||||
|
- *Dependencies.* Every entry in `Cargo.toml` is there because the library
|
||||||
|
needs it, and three of the five are already in the tree via `reqwest`.
|
||||||
|
An argument parser would be the first dependency that is not
|
||||||
|
load-bearing for the library, along with the project's first optional
|
||||||
|
dependency and first `[features]` section.
|
||||||
|
- *MSRV.* Not a break today — `clap` 4.6.7 declares 1.85, under this
|
||||||
|
crate's 1.88 (checked 2026-10-25). The cost is the coupling: a second
|
||||||
|
floor that moves on someone else's release schedule, in a project where
|
||||||
|
three places must agree on the number and a documented procedure exists
|
||||||
|
for rechecking it. A separate crate keeps it out of the library's graph.
|
||||||
|
- *Versioning.* Pre-1.0 this crate tells callers to pin an exact version
|
||||||
|
and expect breaking changes in minor releases. A CLI's flags are a
|
||||||
|
compatibility surface too, and one version number would force the two to
|
||||||
|
move in lockstep. `cargo install invoiceninjars` silently needing
|
||||||
|
`--features cli` is a smaller version of the same problem.
|
||||||
|
|
||||||
|
For ad-hoc probing, `examples/` already covers it and costs nothing:
|
||||||
|
`capture_shapes`, `seed_sample_data` and `smoke_test` are CLI-shaped
|
||||||
|
programs configured from environment variables, with the
|
||||||
|
`IN_SMOKE_WRITE_HOST` guard to copy for anything that writes.
|
||||||
|
|
||||||
|
Same shape of decision as the `updated_at` sync engine in the open
|
||||||
|
questions: a different product from this crate, recorded so the option is
|
||||||
|
not forgotten.
|
||||||
- **No sync/blocking API.** Async only.
|
- **No sync/blocking API.** Async only.
|
||||||
- **No identity map, lazy relationship loading, or transparent entity
|
- **No identity map, lazy relationship loading, or transparent entity
|
||||||
caching.** Three separate refusals with one theme — the client stays
|
caching.** Three separate refusals with one theme — the client stays
|
||||||
|
|||||||
Reference in New Issue
Block a user