cli-forge 0.2.5

Unified CLI framework: runtime command registration with styled output through one API.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

# cli-forge v0.1.0 — Scaffold

**The repository bootstrap.** v0.1.0 stands up the crate, the tooling, and the
quality gates the implementation is built on — and nothing more. There is no
domain logic in this release on purpose: the output tower, the command tree, the
help engine, and the auth seam land across the 0.x series, each behind a passing
gate. This tag exists so the first line of real code is written against a green
CI, a fixed toolchain contract, and a **frozen public interface**, rather than
into an empty directory.

## 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 extensions (tables, progress, gradients, layouts, shells)
all build on one output layer instead of bolting on five unrelated crates.

It owns four things: parsing (a recursive command tree), output (one styling
layer used three ways — plain, tag-parsed, builder), runtime command
registration (from anywhere, hideable, auth-gateable), and help (auto-generated,
customizable). It is the base of the `cli-collection`; sibling crates consume its
output API.

## What's in 0.1.0

### Crate manifest and toolchain contract

`Cargo.toml` declares the full publish metadata — description, keywords,
categories, repository, homepage, dual `Apache-2.0 OR MIT` license, and authors —
on Rust 2024 edition with MSRV 1.85. Features are additive: `std` and `color` on
by default (plain output stays complete with `color` off), and an opt-in `auth`
feature reserved for enforcing the `requires_auth` command flag.

### Quality gates, wired before the code

The CI matrix (`.github/workflows/ci.yml`) runs the full gate on Linux, macOS,
and Windows against both stable and the 1.85 MSRV: `cargo fmt --check`, clippy on
default and all features with `-D warnings`, the test suite on both feature sets,
and a documentation build with `-D warnings`. A separate security job runs
`cargo audit` and `cargo deny check`. The crate root sets
`#![forbid(unsafe_code)]` and `#![deny(missing_docs)]` from the first commit.

### The frozen interface

`docs/API.md` is not a sketch to be revised mid-build — it is the **frozen public
surface** the implementation fills in and that sibling crates and tools build
against: `out`/`err`, the three styling paths (`parse`, `style`, the named tag
registry), and the `Command`/`App` model with `hidden` and `requires_auth`.
Freezing the signatures up front is the anti-drift contract: bodies change across
the 0.x series, signatures do not. `dev/DIRECTIVES.md` records the definition of
done and the invariants the tests hold to — chiefly that `out` never parses or
allocates for styling, that the three styling paths render identically, and that
a command registered outside `main` behaves identically to one inside it (the
limitation that made the predecessor unusable). `dev/ROADMAP.md` front-loads the
hard part — the output tower and cross-platform terminal backend at v0.2.0 — under
an anti-deferral rule.

## Breaking changes

**None.** This is the first tag.

## Verification

```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
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
cargo +1.85 build --all-features
cargo audit
cargo deny check
```

Counts at this tag: 1 unit test (a build smoke test), 0 doctests — there is no
public surface to exercise yet.

## What's next

- **0.2.0 — Output tower + terminal backend.** The three styling paths over one
  system (`out`/`err` plain, `parse` tags, `style` builder) plus the named-tag
  registry, on a cross-platform terminal backend. `out` proven allocation-free by
  benchmark; the three paths proven byte-identical by test. This is the hard part,
  and it is not deferred.

## Installation

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

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)
- [CHANGELOG](https://github.com/jamesgober/cli-forge/blob/main/CHANGELOG.md)

---

**Changelog:** [`CHANGELOG.md`](https://github.com/jamesgober/cli-forge/blob/main/CHANGELOG.md).