modular_cli_sdk 0.5.0

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.

example/example.dart

/// example/example.dart
/// Minimal runnable example — mirrors example/example.dart from modular_api.
///
/// Run:
///   dart run example/example.dart                  # the root command
///   dart run example/example.dart help             # the command catalog
///   dart run example/example.dart help --json      # the catalog as JSON
///   dart run example/example.dart version
///   dart run example/example.dart version --json
///   dart run example/example.dart greetings hello --name World
///   dart run example/example.dart greetings hello --name World --json
///   dart run example/example.dart math add --a 3 --b 7
///   dart run example/example.dart math add --a 3 --b 7 --json
///   dart run example/example.dart math multiply --a 4 --b 5 --json
///
/// Everything above reads. The one route that writes is told which of the two
/// it is doing, and refuses to guess:
///
///   dart run example/example.dart notes write today --plan
///   dart run example/example.dart notes write today --apply --autoapprove
///   dart run example/example.dart notes write today --plan --json
library;

import 'dart:io';

import 'package:modular_cli_sdk/modular_cli_sdk.dart';

import 'commands/status.dart';
import 'commands/version.dart';
import 'modules/greetings/greetings_builder.dart';
import 'modules/math/math_builder.dart';
import 'modules/notes/notes_builder.dart';

// ─── CLI ─────────────────────────────────────────────────────────────────────

Future<void> main(List<String> args) async {
  final code = await runExample(args);
  exit(code);
}

Future<int> runExample(
  List<String> args, {
  IOSink? stdout,
  IOSink? stderr,
  Approver? approver,
  PlanSink? planSink,
}) async {
  // [approver] and [planSink] are the two decisions the SDK leaves to the host:
  // how an approval is taken, and whether a plan is kept on disk. Passing them
  // in is also what lets the suite exercise `--apply` without a terminal.
  final cli = ModularCli(approver: approver, planSink: planSink);

  // The root command — what the bare invocation runs. Registering it means this
  // CLI, not the help, owns the empty invocation.
  cli.query<StatusInput, StatusOutput>(
    '',
    (req) => StatusQuery(StatusInput.fromCliRequest(req)),
    description: 'Show the CLI status',
  );

  // Root-level commands
  cli.query<VersionInput, VersionOutput>(
    'version',
    (req) => VersionQuery(VersionInput.fromCliRequest(req)),
    description: 'Print application version',
  );

  // Module-scoped commands
  cli.module('greetings', buildGreetingsModule);
  cli.module('math', buildMathModule);
  cli.module('notes', buildNotesModule);

  return cli.run(args, stdout: stdout, stderr: stderr);
}