From d51de3fc638ac8fd91c6278d360904d3c6e78eb4 Mon Sep 17 00:00:00 2001 From: Andrew Bryant Date: Sun, 25 Oct 2026 09:04:41 -0400 Subject: [PATCH] Rule out a CLI in this package MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- GOALS.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/GOALS.md b/GOALS.md index 77f1bc4..3ee51e9 100644 --- a/GOALS.md +++ b/GOALS.md @@ -85,6 +85,38 @@ Invoice Ninja account to contribute. comparison in `COVERAGE.md`. The divergences — JSON instead of `form_params`, keeping the whole validation `errors` map, exposing bulk `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 identity map, lazy relationship loading, or transparent entity caching.** Three separate refusals with one theme — the client stays