54 lines
2.4 KiB
Markdown
54 lines
2.4 KiB
Markdown
# 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
|