Initial Commit

openspec/archive/2026-04-20-enterprise-cli/specs/cli/spec.md

@@ -0,0 +1,53 @@
+# 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