cli-forge 1.0.0

# cli-forge v1.0.0 — Stable

**The API is frozen.** Everything built across the 0.x series — plain output and
three styling paths over one cross-platform terminal backend, a recursive command
tree with runtime registration, the help engine, and the auth seam — is now
guaranteed under Semantic Versioning. No new public API in this release: 1.0.0 is
the commitment that the surface won't break before 2.0.

## What is cli-forge?

A unified command-line framework: argument parsing and styled output through one
API, with commands that register at runtime. It targets the lightness of argh with
the reach of clap, and — unlike either — keeps output styling in the *same* system
as parsing, so the sibling crates in the cli collection (`cli-table`,
`cli-progress`, gradients, layouts, shell) all build on one output layer.

## The 1.0 surface

Frozen and guaranteed:

- **Output** — `out`, `err`: the plain path, allocation-free for a string literal.
- **Styling** — `style` / `Style`, inline `parse` tags, and the `define_tag` /
  `tag` / `Tag` registry. All three render to identical bytes for the same intent;
  24-bit color degrades gracefully; the Windows console is handled behind the same
  API.
- **Commands** — `App`, `Command`, `Arg`, `Matches`, `ParseError`. A recursive
  tree registered from anywhere, with aliases, hidden and auth-gated flags; the
  full argument model (flags, counting flags, options, positionals, with
  repeatable/variadic collection); auto-generated `--help` / `--version`; and
  structured, non-panicking errors.
- **Auth seam** *(feature `auth`)* — `App::auth`, `AuthRequest`. Gate commands
  behind a consumer-supplied hook; fails closed.

## The SemVer promise

- **No breaking change before 2.0.** Every public item's signature and documented
  behavior — including the `auth` seam and the feature flags — is guaranteed. A
  breaking change requires a MAJOR bump.
- **Additions are minor.** New public API arrives only in `1.x` releases and is
  strictly additive.
- **Fixes and optimization are patch.** No API change in `1.0.x`.
- **MSRV (1.85)** rises only in a minor release, never a patch.
- **Feature flags are additive** — the default build stays fully functional.

The full promise lives in the [Stability](https://github.com/jamesgober/cli-forge/blob/main/docs/API.md#stability)
section of `docs/API.md`.

## What's new in 1.0.0

No new public API. This release:

- **Declares the surface stable** and records the SemVer promise in `docs/API.md`;
  updates the README/API status from "pre-1.0 / frozen" to "1.0 — stable".
- **Rounds out the benchmark suite** with command-parse benchmarks
  (`parse_simple`, `parse_rich`) alongside the existing output-layer benches.
- **Corrects doc comments** that still referenced upcoming milestones now that
  every milestone has shipped.

## Performance

Latest local Criterion means (Windows x86_64, Rust stable, release build):

| Operation | Time |
|-----------|-----:|
| `out` plain write (`&str`) | ~7 ns |
| named-registry styled render | ~45 ns |
| builder render, 24-bit color | ~77 ns |
| parse a simple invocation | ~420 ns |
| parse a rich invocation (counts, repeats, variadics) | ~1.2 µs |

The plain output path is allocation-free — proven by a counting-allocator test,
not asserted. Reproduce with `cargo bench --bench bench`.

## Breaking changes

**None.** 1.0.0 is byte-compatible with 0.6.0 at the API level; it only adds the
stability guarantee (plus internal benchmarks and doc corrections).

## Verification

Run on Windows x86_64, Rust stable 1.95.x; the same commands pass on Linux (WSL2
Ubuntu). macOS is covered by the CI matrix (Linux/macOS/Windows × stable/1.85),
which shares the identical non-Windows code path verified on Linux.

```bash
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo clippy --all-targets --all-features -- -D warnings
cargo test
cargo test --all-features
cargo build --no-default-features
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
RUSTUP_TOOLCHAIN=1.85 cargo test --all-features
cargo bench --bench bench
cargo deny check
cargo audit
```

All green, with no runtime dependencies beyond the Windows-only, `color`-gated
ANSI-enable helper. Counts at this tag (`--all-features`):

- 76 unit tests (including 7 property tests).
- 4 integration tests (allocation proof + non-`main` registration).
- 50 documentation tests.

## What's next

- **The sibling crates.** `cli-table`, `cli-progress`, gradients, layouts, and a
  shell layer build on this frozen output/command base — each its own crate in the
  cli collection, depending on cli-forge.
- **1.x** — strictly-additive conveniences (repeatable-value niceties, multicall,
  …) as they prove their weight, plus fixes and optimization. Nothing existing
  changes before 2.0.

## Installation

```toml
[dependencies]
cli-forge = "1.0"

# With the auth seam:
cli-forge = { version = "1.0", features = ["auth"] }

# Plain output only (no escape sequences; the API stays complete):
cli-forge = { version = "1.0", default-features = false, features = ["std"] }
```

MSRV: Rust 1.85.

## Documentation

- [README](https://github.com/jamesgober/cli-forge/blob/main/README.md)
- [API Reference](https://github.com/jamesgober/cli-forge/blob/main/docs/API.md)
- [Roadmap](https://github.com/jamesgober/cli-forge/blob/main/dev/ROADMAP.md)
- [CHANGELOG](https://github.com/jamesgober/cli-forge/blob/main/CHANGELOG.md)

---

**Full diff:** [`v0.6.0...v1.0.0`](https://github.com/jamesgober/cli-forge/compare/v0.6.0...v1.0.0).
**Changelog:** [`CHANGELOG.md`](https://github.com/jamesgober/cli-forge/blob/main/CHANGELOG.md#100---2026-07-01).