cornerlibstone 0.1.0

Lib Cornerstone — a zero-dependency foundation for building command-line tools in Rust: argument parsing, nested subcommands, themeable help in multiple presets, structured errors and exit codes, config loading, interactive prompts, shell-completion and man/markdown generation, logging, JSON output, and root/destructive-operation guards.
Documentation
# Lib Cornerstone

[![crates.io](https://img.shields.io/crates/v/libcornerstone.svg)](https://crates.io/crates/libcornerstone)
[![docs.rs](https://docs.rs/libcornerstone/badge.svg)](https://docs.rs/libcornerstone)
[![license](https://img.shields.io/crates/l/libcornerstone.svg)](#license)

A **zero-dependency foundation for building command-line tools in Rust.** Declare *what your commands are and what they do*; Cornerstone supplies everything else — parsing, help, output, errors, config, prompts, completions, and guards — so a new CLI is a list of commands and their bodies, not a pile of boilerplate.

> The package is published as `libcornerstone`, but the library is imported as `cornerstone`:
> ```rust
> use cornerstone::prelude::*;
> ```

## Install

```toml
[dependencies]
libcornerstone = "0.1"
```

## Quick start

```rust
use cornerstone::prelude::*;

fn main() {
    App::new("greet")
        .about("A tiny greeter")
        .version(env!("CARGO_PKG_VERSION"))
        .command_with(
            "hello",
            "Greet someone",
            |c| c.arg("name", "Who to greet").switch("shout", Some('s'), "Greet loudly"),
            |ctx| {
                let name = ctx.arg("name")?;
                let msg = format!("Hello, {}!", name);
                ctx.info(if ctx.flag("shout") { msg.to_uppercase() } else { msg });
                Ok(())
            },
        )
        .run();
}
```

```console
$ greet hello world
Hello, world!
$ greet hello world --shout
HELLO, WORLD!
$ greet --help
```

`.run()` parses `argv`, handles `--help`/`--version`/global flags, sets up color and quiet state, dispatches, runs lifecycle hooks, and turns a returned error into a printed message plus the right exit code. Use `.run_with(args)` in tests — it returns the exit code instead of exiting.

## What you get

- **Argument parsing** — long/short/bundled flags, `--key=value`, `-svalue`, `--` passthrough, required/optional/variadic positionals. No dependencies.
- **Nested subcommands** — `App::group("remote", …, |g| g.command("add", …))` to any depth.
- **Help in three presets** — `Standard` (clap-like), `Banner`, and `Sections`, each rendering app help, per-subcommand help, and short (`-h`) / long (`--help`) tiers. Or plug in your own `HelpRenderer`.
- **Global flags for free** — `-h/--help`, `-V/--version`, `-q/--quiet`, `-v/-vv`, `--json`, `--dry-run`, `--sudo`.
- **Structured errors and stable exit codes** — `Error::{msg,usage,not_found,permission,cancelled}`, plus `ErrorSet` for the collect-all-failures-then-report pattern.
- **Output helpers** — leveled messages, auto-aligned `Table`, `Tree`, key/value blocks, `Progress` bars, `Spinner`, `Timer`. All respect quiet/color/pipe state.
- **Config loading** — TOML-subset / INI / JSON, environment overlay, and `flag > env > file > default` precedence.
- **Interactive prompts** — confirm, text, hidden password, select, multiselect, and range-checked number.
- **Shell completions** — bash / zsh / fish generated from your command specs, via a built-in `completions <shell>` command.
- **Docs generation** — man page and Markdown reference from the same specs, via a built-in `docs <man|markdown>` command.
- **Logging** — leveled logger, verbosity-gated console output plus an always-on file sink.
- **JSON output** — a small `Json` builder with correct escaping for `--json` modes.
- **Fuzzy suggestions** — "did you mean?" on unknown commands.
- **Signal handling** — clean Ctrl-C and correct SIGPIPE behavior (no panic when piped into `head`).
- **Guards** — `ctx.require_root()` (checks `--sudo` and real `geteuid() == 0`) and `ctx.require_confirmation(...)` for destructive operations, with `--dry-run` bypassing confirmation.

## Themeable and non-prescriptive

Cornerstone ships **neutral** — no decorative glyphs, no house style — so tools built on it look generic and professional out of the box. Every glyph, label, color, and confirmation wording is overridable through a `Theme`, and help layout through `HelpStyle` or a custom `HelpRenderer`, without forking the crate.

```rust
let theme = Theme::default()
    .success_glyph("»")
    .error_label("fatal:")
    .progress_cells("=", " ");
App::new("tool").theme(theme) /* ... */;
```

## Platform notes

The guards, hidden-password prompt, and signal handling use Unix syscalls validated on Linux x86-64 (glibc). They degrade gracefully elsewhere. The crate is `#![forbid(unsafe_code)]`-adjacent — it uses small, contained `extern "C"` calls only for `isatty`, `geteuid`, terminal echo, and signal setup.

## Minimum supported Rust version

Rust 1.74 or newer.

## License

Licensed under either of

- Apache License, Version 2.0 ([LICENSE-APACHE]LICENSE-APACHE)
- MIT license ([LICENSE-MIT]LICENSE-MIT)

at your option.