# cli-forge — Roadmap

> Path from scaffold to a stable 1.0. Hard parts are front-loaded; each phase has hard exit criteria.
>
> **Anti-deferral rule:** no listed hard task moves to a later phase unless this file records the move and the reason.

---

## v0.1.0 — Scaffold (DONE)

Compiles, CI green, structure correct, no domain logic.

- [x] Manifest, README, CHANGELOG, REPS, dual license, CI, deny, clippy, rustfmt.
- [x] Frozen public interface sketched in `docs/API.md`.

---

## v0.2.0 — Output tower + terminal backend (DONE, shipped in 0.2.5)

The output layer is the load-bearing piece every sibling crate depends on, so it
is built and proven first. Deliver the three styling paths over ONE system:
`out`/`err` (plain, no parsing, near-direct write), `parse` (tag strings with
named AND hex/rgb colors), and the `style(..)` builder. Plus the named-tag
registry (`define_tag`/`tag`) so a style is defined once and reused. All of it
sits on a single cross-platform terminal backend that isolates ANSI vs
Windows-console so the public API never exposes the difference.

Exit criteria:
- [x] `out` proven allocation-free / no-parse by benchmark, not by claim. (`tests/allocation.rs` + `benches/bench.rs`.)
- [x] The three styling paths render byte-identical output for the same intent (test). (`src/crosspath_tests.rs`.)
- [x] Named + hex + rgb colors work; graceful degradation on limited terminals (test).
- [x] Verified on Linux, macOS, and Windows console. (Linux via WSL2 + Windows directly; macOS shares the identical non-Windows code path.)
- [x] Every public item has rustdoc + a runnable example.

---

## v0.3.0 — Command tree + runtime registration (DONE)

The recursive `Command` tree with args/flags, and an `App` registry that accepts
commands registered FROM ANYWHERE (not main-only) — the limitation that killed
the predecessor. Commands support `.hidden()` and the `.requires_auth()` flag.

Exit criteria:
- [x] A command registered from a non-`main` module is reachable and behaves identically (test). (`tests/registration.rs`.)
- [x] Hidden commands are absent from help but still invokable (test). (Excluded from the visible-command listing; still dispatch.)
- [x] Arg/flag parsing handles the standard cases; malformed input returns structured errors, never panics. (`ParseError`; parser proptest-fuzzed.)

---

## v0.4.0 — Help engine + customization (DONE)

Auto-generated help rendered through the output layer, with injectable
`help_header`/`help_footer` slots and per-command styling. Errors render through
the same system. Also folded in the small conveniences a base CLI expects:
command aliases, `--help`/`-h`, and `--version`/`-V`.

Exit criteria:
- [x] Help is styleable and respects custom header/footer (test). (Section headers styled through the output layer; `App::help()` + header/footer asserted.)
- [x] Hidden/auth-gated commands honored in help generation. (Both excluded from listings; tested.)

---

## v0.5.0 — Auth seam, feature freeze (DONE)

The auth hook that enforces `requires_auth` (login/logout state supplied by the
consumer or a sibling `cli-auth` crate — core holds the seam, not the logic).
Public surface declared frozen.

Exit criteria:
- [x] An auth-gated command does not run unless the hook authorizes it (test). (`App::auth` hook; `enforce_auth` fails closed; tested both feature sets.)
- [x] API surface documented as frozen in `docs/API.md`. (See the Stability section.)

---

## v0.6.0 — Argument conveniences (DONE)

Strictly-additive polish within the frozen surface — the small, common argument
kinds a base CLI is expected to have, added without changing anything existing.

- [x] Counting flags: `Arg::count` + `Matches::count` (`-vvv` verbosity).
- [x] Multiple values: `Arg::multiple` (repeatable options + variadic positionals)
      + `Matches::values`.
- [x] Comprehensive edge-case tests on both feature sets; docs and an example.

---

## v1.0.0 — API freeze (DONE)

The parse + output + registration + help surface is stable and frozen until 2.0.
No new public API, only documentation, tests, and internal optimisation.
Sibling crates (`cli-table`, `cli-progress`, gradients, layouts, shell) build on
this frozen base.

Exit criteria:
- [x] `docs/API.md` marked stable; SemVer promise recorded. (See the Stability section.)
- [x] Full test + benchmark suite green on all three platforms. (Windows + Linux verified directly; macOS via the CI matrix on the shared non-Windows path. Output + command-parse benchmarks green.)
