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

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