modular_cli_sdk 0.3.4

Command-centric SDK for building modular CLIs with Dart — Command/Input/Output contract, structured errors, output formatting, and automatic TTY detection. Built on cli_router.

Changelog

All notable changes to this project will be documented in this file.

The format loosely follows Keep a Changelog and the project adheres to Semantic Versioning.

0.3.4

Fixed

• An incomplete invocation is no longer reported as an unknown command. Typing the beginning of a registered route without reaching its end — math where math add exists — answered unknown command 'math' followed by the whole catalog. The name was real; what was missing was the end of it, and the user was sent looking for a typo they had not made. The error path now asks the catalog whether what was typed continues into any route, says so, and lists only those continuations

  The rule is stated over routes rather than modules on purpose. api graphql is not a module — it is the first segment of the route api graphql compile — so a module-only check would have left it reported as unknown. Prefix-of-a-route covers the module without an action and the half-typed route as the one case they are, and is the simpler rule of the two

  A name that begins no registered route keeps exactly the behaviour it had: it is named, and the full catalog follows. The exit code is unchanged for both, and is now pinned by a test rather than inherited

  No public API was added. The completions are rendered by narrowing what HelpRenderer is given rather than teaching it a new shape, which keeps it the only place help text is produced

Notes

• This does not give the surface position help of its own. api graphql --help still renders nothing; what changes is that the error stops calling it unknown. Whether a CLI should have three levels at all is a question for the CLIs built on this SDK, not for the SDK

0.3.3

Fixed

• A command with positionals can be asked for its contract. The router cannot match show <id> until the id is supplied, so show --help fell to the error path — the user had to provide the very argument he was asking about. A command is now named by its route without positional placeholders, so both show --help and help show render its contract. show 1 --help keeps working

Added

• CommandContract.name — the route without its positional placeholders, i.e. the tokens a user types to name the command
• CommandCatalog.forName — lookup by that name

0.3.2

Fixed

• A command can now declare that it accepts no options, and be enforced. params defaulted to const [], so declaring an empty contract was the same value as declaring none: a zero-argument command was indistinguishable from an undeclared one and its arguments went unchecked — init --host foo ran, silently doing nothing the flag implied. params is now nullable (null = declares nothing, unenforced, as before; [] = declares no options, and any option is rejected)

Changed

• ModularCli.command / ModuleBuilder.command take List<CliParam>? params (was List<CliParam> params = const []). Source-compatible: omitting params behaves exactly as before
• CommandContract.params is List<CliParam>?, with isDeclared and declaredParams for the two readings

0.3.1

Fixed

• A registered root route owns the empty invocation. ModularCli rewrote bare <cli> into help unconditionally, on the assumption that no route can serve the empty invocation. A CLI that registers one — a dashboard, a status screen, a banner — had that command silently replaced by the help. The rewrite now applies only when nothing claims the empty route; a CLI without a root route is unaffected
• The help listing names the root route. Having no token to type, it rendered as a description hanging off a blank column. It is now listed as (no arguments) — the only way it can be invoked

Added

• The example registers a root command, so the bare invocation is exercised. Its absence is why no test could see either defect above

0.3.0

Added

• Command contract — CliParam declares a command's parameters (kind, type, short alias, required, default, allowed values) on its Input, and command(...) accepts them via params: (#7)
• Native help — help, no arguments, --help and -h print the command list to stdout with exit 0. Unknown or invalid usage stays on stderr with exit 64. A help command registered by the developer overrides the built-in one
• Focused help — <command> --help renders that command's contract; <module> --help renders every command in the module
• help --json — the full contract catalog as JSON (help.json), the machine twin of the text help, through the existing JsonCliOutput
• Enforcement — the declaration governs parsing: aliases resolved, declared defaults applied, values coerced to their declared type, undeclared options and values outside allowed rejected with exit 7. A rejected invocation is answered with the contract it failed to honour

Changed

• Input.schemaFields is now typed List<CliParam>? (was List<dynamic>?, documented as reserved)
• Requires cli_router: ^0.1.0, which adds the onNotFound hook the SDK uses to render its own catalog on the error path, and route metadata for positionals

Notes

• Commands that declare no params behave exactly as before: not described in help, not enforced

0.2.1

Added

• Output.toText() — override for custom text formatting (#5)
  • When non-null, TextCliOutput uses this value directly instead of iterating toJson() fields
  • JSON mode is unaffected — it always uses toJson()
  • Non-breaking: defaults to null, preserving existing behavior

0.2.0

Added

• ModularCli.command<I, O>() — register root-level commands without a module prefix
• Root commands reuse the full Command<I, O> lifecycle (validate → execute → format)
• Root commands honor --json, --quiet, CommandException, and semantic exit codes
• Example version root command in example/commands/version.dart
• 4 new integration tests for root commands

0.1.0

Added

• ModularCli — entry point that orchestrates modules, global flags, and TTY detection
• ModuleBuilder — per-module command registration via command()
• Command<I, O> — abstract unit of work with validate() and execute() lifecycle
• Input — abstract inbound DTO (deserialize from CliRequest flags/params)
• Output — abstract outbound DTO with toJson() and exitCode
• CommandException — structured error with code, message, details, isRetryable
• ExitCode — semantic exit code constants (0, 1, 2, 4, 5, 6, 7, 64)
• CliOutput / JsonCliOutput / TextCliOutput — output formatting abstraction
• --json global flag — machine-readable JSON output
• --quiet / -q global flag — suppress informational messages
• Working example with two modules (greetings + math)
• Full test suite (unit + integration)