# Spec: @suaveplan/cli

## Purpose

Enterprise-grade CLI framework. Composable fluent API with subcommand routing, option parsing, OTel tracing, and terminal UI primitives. Depends on `@suaveplan/readline`, `@suaveplan/error`, `@suaveplan/types`, `@opentelemetry/api`, `zod`.

## ADDED Requirements

### App / cli()
- `cli(name, version?)` factory shorthand
- `new App(config)` with name, version, description, writer, onError, enableVersion, enableHelp
- `app.run(argv?, opts?)` with AbortSignal support
- Delegates to root `Command` for subcommand routing

### Command
- Fluent: `description()`, `option(flags, desc, default?)`, `argument(spec, desc)`, `alias(name)`, `hidden()`, `example(str)`, `action(fn)`
- `execute(argv)` — parse args, route to subcommand or call action
- `helpText(parentName?)` — generates formatted help
- OTel span per `execute()` call

### Parser
- `parseArgs(argv, config?)` — options, positionals, rest (`--` separator), allowUnknown
- `parseOptionFlags(flags, desc?, default?)` — flag string → OptionConfig
- `parseArgumentSpec(spec, desc?)` — spec string → ArgumentConfig
- Types: boolean, string, number; choices validation; required options/arguments

### Style
- `createStyler(enabled?)` — returns Proxy-based chainable styler
- Codes: bold, dim, italic, underline, strikethrough, 8 fg colors, 8 bg colors
- `stripAnsi(text)`, `isColorSupported()`, `getStyleNames()`

### Output/Format
- `keyValue(obj, opts?)`, `list(items, opts?)`, `tree(node)`, `columns(rows)`, `json(obj, opts?)`
- `heading(text, level?)`, `divider(char?, width?)`, `indent(text, spaces?)`

### Output/Table
- `table(headers, rows, opts?)` — printTable variant
- Border styles: ascii, unicode, none

### Spinner
- `createSpinner(opts?)` — `start(text?)`, `stop()`, `succeed(text?)`, `fail(text?)`, `warn(text?)`, `update(text)`
- TTY: in-place frame animation via setInterval; non-TTY: newline-per-frame
- AbortSignal support

### Progress
- `createProgress(opts)` — `update(value)`, `complete(label?)`
- ASCII bar `[████░░░]` with percentage and count
- TTY in-place clear via clearLine/cursorTo; AbortSignal support

### Prompt
- `text(opts, reader?)`, `password(opts, reader?)`, `confirm(opts, reader?)`, `select(opts, reader?)`, `multiselect(opts, reader?)`
- Injectable `reader?: InputReader` for testing; `_setReaderFactory()` internal seam
- Validation, re-prompt on invalid, min/max for multiselect