feat: add print completion-script command

.gitignore

@@ -7,3 +7,6 @@ build/
 pubspec.lock
 
 coverage/
+
+# VM service artifacts created by the test runner
+*.dart.vm.json

README.md

@@ -57,6 +57,12 @@ When `enableAutoInstall` is set to false, users will have to call `install-compl
 $ example_cli install-completion-files
 ```
 
+Additionally, when `enableAutoInstall` is disabled a `completion-script` command is exposed. It prints the completion script for the current shell to stdout, so users can install it wherever they prefer:
+
+```bash
+$ example_cli completion-script >> ~/.zshrc
+```
+
 ## Documentation 📝
 
 For an overview of how this package works, check out the [documentation][docs_link].

doc/README.md

@@ -26,7 +26,7 @@ We call this process [parsing](#how-parsing-completion-works).
 
 The class `CompletionCommandRunner` tries to create these files upon any command run. It does nothing if the completion files exist and displays a short error message if there is an error in the process.
 
-To disable this behavior, set `enableAutoInstall` to false on your `CompletionCommandRunner` subclass.
+To disable this behavior, set `enableAutoInstall` to false on your `CompletionCommandRunner` subclass. In that case, users can install the completion files manually with the `install-completion-files` command, or print the completion script for the current shell with the `completion-script` command (e.g. `example_cli completion-script >> ~/.zshrc`), which is only available while auto installation is disabled.
 
 ### How Parsing Completion Works
 

lib/src/command_runner/commands/commands.dart

@@ -1,3 +1,4 @@
 export 'handle_completion_command.dart';
 export 'install_completion_files_command.dart';
+export 'print_completion_script_command.dart';
 export 'uninstall_completion_files_command.dart';

lib/src/command_runner/commands/print_completion_script_command.dart

@@ -0,0 +1,48 @@
+import 'dart:async';
+
+import 'package:args/command_runner.dart';
+import 'package:cli_completion/cli_completion.dart';
+
+/// {@template print_completion_script_command}
+/// A [Command] added by [CompletionCommandRunner] only when auto installation
+/// is disabled that prints the completion script for the current shell to
+/// stdout.
+///
+/// It allows users to install the completion script manually by piping the
+/// output into their shell configuration file, for example:
+/// ```sh
+/// my_cli completion-script >> ~/.zshrc
+/// ```
+///
+/// This mirrors the approach used by other CLIs such as npm and the GitHub CLI.
+///
+/// Unlike the other completion commands, this command is intentionally left
+/// visible in `--help` (it does not override [hidden]) so that users can
+/// discover it.
+/// {@endtemplate}
+class PrintCompletionScriptCommand<T> extends Command<T> {
+  /// {@macro print_completion_script_command}
+  PrintCompletionScriptCommand();
+
+  @override
+  String get description {
+    return 'Prints the completion script for the current shell to stdout.';
+  }
+
+  /// The string that the user can call to print the completion script.
+  static const commandName = 'completion-script';
+
+  @override
+  String get name => commandName;
+
+  @override
+  CompletionCommandRunner<T> get runner {
+    return super.runner! as CompletionCommandRunner<T>;
+  }
+
+  @override
+  FutureOr<T>? run() {
+    runner.printCompletionScript();
+    return null;
+  }
+}

lib/src/command_runner/completion_command_runner.dart

@@ -20,6 +20,10 @@ import 'package:meta/meta.dart';
 ///
 /// Adds [InstallCompletionFilesCommand] to enable the user to
 /// manually install completion files.
+///
+/// When [enableAutoInstall] is disabled, it also adds
+/// [PrintCompletionScriptCommand] so the user can print the completion script
+/// and install it manually.
 abstract class CompletionCommandRunner<T> extends CommandRunner<T> {
   /// {@macro completion_command_runner}
   CompletionCommandRunner(
@@ -31,6 +35,13 @@ abstract class CompletionCommandRunner<T> extends CommandRunner<T> {
     addCommand(HandleCompletionRequestCommand<T>());
     addCommand(InstallCompletionFilesCommand<T>());
     addCommand(UnistallCompletionFilesCommand<T>());
+
+    // The print completion script command is only useful when the completion
+    // files are not installed automatically. Otherwise, users should rely on
+    // the auto installation (or the `install-completion-files` command).
+    if (!enableAutoInstall) {
+      addCommand(PrintCompletionScriptCommand<T>());
+    }
   }
 
   /// The [Logger] used to prompt the completion suggestions.
@@ -102,6 +113,25 @@ abstract class CompletionCommandRunner<T> extends CommandRunner<T> {
     }
   }
 
+  /// Prints the completion script for the current shell to stdout.
+  ///
+  /// This is used by [PrintCompletionScriptCommand] to allow users to install
+  /// the completion script manually, for example:
+  /// ```sh
+  /// my_cli completion-script >> ~/.zshrc
+  /// ```
+  @internal
+  void printCompletionScript() {
+    try {
+      final script = completionInstallation.completionScriptFor(executableName);
+      completionLogger.info(script);
+    } on CompletionInstallationException catch (e) {
+      completionInstallationLogger.warn(e.toString());
+    } on Exception catch (e) {
+      completionInstallationLogger.err(e.toString());
+    }
+  }
+
   /// Tries to uninstall completion files for the current shell.
   @internal
   void tryUninstallCompletionFiles(Level level) {

lib/src/installer/completion_installation.dart

@@ -112,14 +112,7 @@ class CompletionInstallation {
   /// if they already exist. If false, it will check if is already installed, or
   /// if it has been explicitly uninstalled before installing it.
   void install(String rootCommand, {bool force = false}) {
-    final configuration = this.configuration;
-
-    if (configuration == null) {
-      throw CompletionInstallationException(
-        message: 'Unknown shell.',
-        rootCommand: rootCommand,
-      );
-    }
+    final configuration = _configurationOrThrow(rootCommand);
 
     if (!force && !_shouldInstall(rootCommand)) {
       return;
@@ -156,6 +149,39 @@ class CompletionInstallation {
         .writeTo(completionConfigurationFile);
   }
 
+  /// Returns the completion script for the [rootCommand] on the current shell
+  /// without writing it to any file.
+  ///
+  /// This can be used to print the completion script to stdout so that a user
+  /// can source it manually, for example:
+  /// ```sh
+  /// my_cli completion-script >> ~/.zshrc
+  /// ```
+  ///
+  /// Throws a [CompletionInstallationException] if the current shell is
+  /// unknown.
+  String completionScriptFor(String rootCommand) {
+    final configuration = _configurationOrThrow(rootCommand);
+
+    return configuration.scriptTemplate(rootCommand);
+  }
+
+  /// Returns the current [configuration] or throws a
+  /// [CompletionInstallationException] if it is null (i.e. the current shell is
+  /// unknown).
+  ShellCompletionConfiguration _configurationOrThrow(String rootCommand) {
+    final configuration = this.configuration;
+
+    if (configuration == null) {
+      throw CompletionInstallationException(
+        message: 'Unknown shell.',
+        rootCommand: rootCommand,
+      );
+    }
+
+    return configuration;
+  }
+
   /// Wether the completion configuration files for a [rootCommand] should be
   /// installed or not.
   ///
@@ -191,9 +217,7 @@ class CompletionInstallation {
     );
 
     if (completionConfigDir.existsSync()) {
-      logger.warn(
-        'A ${completionConfigDir.path} directory was already found.',
-      );
+      logger.warn('A ${completionConfigDir.path} directory was already found.');
       return;
     }
 
@@ -374,10 +398,7 @@ class CompletionInstallation {
         '''
 ## $description
 ${configuration!.sourceLineTemplate(scriptPath)}''';
-    ScriptConfigurationEntry(scriptName).appendTo(
-      configFile,
-      content: content,
-    );
+    ScriptConfigurationEntry(scriptName).appendTo(configFile, content: content);
 
     logger.info('Added config to $configFilePath');
   }
@@ -483,10 +504,7 @@ ${configuration!.sourceLineTemplate(scriptPath)}''';
 }
 
 /// Resolve the home from a path string
-String _resolveHome(
-  String originalPath,
-  Map<String, String> environment,
-) {
+String _resolveHome(String originalPath, Map<String, String> environment) {
   final after = originalPath.split('~/').last;
   final home = path.absolute(environment['HOME']!);
   return path.join(home, after);

test/src/command_runner/commands/print_completion_script_command_test.dart

@@ -0,0 +1,111 @@
+import 'package:cli_completion/cli_completion.dart';
+import 'package:cli_completion/installer.dart';
+import 'package:mason_logger/mason_logger.dart';
+import 'package:mocktail/mocktail.dart';
+import 'package:test/test.dart';
+
+class _MockLogger extends Mock implements Logger {}
+
+class _MockCompletionInstallation extends Mock
+    implements CompletionInstallation {}
+
+class _TestCompletionCommandRunner extends CompletionCommandRunner<int> {
+  _TestCompletionCommandRunner() : super('test', 'Test command runner');
+
+  @override
+  bool get enableAutoInstall => false;
+
+  @override
+  // Override acceptable for test files
+  // ignore: overridden_fields
+  final Logger completionLogger = _MockLogger();
+
+  @override
+  // Override acceptable for test files
+  // ignore: overridden_fields
+  final Logger completionInstallationLogger = _MockLogger();
+
+  @override
+  final CompletionInstallation completionInstallation =
+      _MockCompletionInstallation();
+}
+
+void main() {
+  group('PrintCompletionScriptCommand', () {
+    late _TestCompletionCommandRunner commandRunner;
+
+    setUp(() {
+      commandRunner = _TestCompletionCommandRunner();
+    });
+
+    test('can be instantiated', () {
+      expect(PrintCompletionScriptCommand<int>(), isNotNull);
+    });
+
+    test('is not hidden', () {
+      expect(PrintCompletionScriptCommand<int>().hidden, isFalse);
+    });
+
+    test('description', () {
+      expect(
+        PrintCompletionScriptCommand<int>().description,
+        'Prints the completion script for the current shell to stdout.',
+      );
+    });
+
+    group('completion-script', () {
+      test('prints the completion script to stdout', () async {
+        when(
+          () => commandRunner.completionInstallation.completionScriptFor(
+            commandRunner.executableName,
+          ),
+        ).thenReturn('some completion script');
+
+        await commandRunner.run(['completion-script']);
+
+        verify(
+          () => commandRunner.completionLogger.info('some completion script'),
+        ).called(1);
+      });
+
+      test(
+        'logs a warning when it throws a CompletionInstallationException',
+        () async {
+          when(
+            () => commandRunner.completionInstallation.completionScriptFor(
+              commandRunner.executableName,
+            ),
+          ).thenThrow(
+            CompletionInstallationException(
+              message: 'oops',
+              rootCommand: 'test',
+            ),
+          );
+
+          await commandRunner.run(['completion-script']);
+
+          verify(
+            () => commandRunner.completionInstallationLogger.warn(any()),
+          ).called(1);
+        },
+      );
+
+      test(
+        'logs an error when an unknown exception happens',
+        () async {
+          when(
+            () => commandRunner.completionInstallation.completionScriptFor(
+              commandRunner.executableName,
+            ),
+          ).thenThrow(Exception('oops'));
+
+          await commandRunner.run(['completion-script']);
+
+          verify(
+            () => commandRunner.completionInstallationLogger.err(any()),
+          ).called(1);
+        },
+      );
+    });
+  });
+}

test/src/command_runner/completion_command_runner_test.dart

@@ -34,6 +34,15 @@ class _TestCompletionCommandRunner extends CompletionCommandRunner<int> {
       mockCompletionInstallation ?? super.completionInstallation;
 }
 
+class _TestNoAutoInstallCompletionCommandRunner
+    extends CompletionCommandRunner<int> {
+  _TestNoAutoInstallCompletionCommandRunner()
+    : super('test', 'Test command runner');
+
+  @override
+  bool get enableAutoInstall => false;
+}
+
 class _TestUserCommand extends Command<int> {
   @override
   String get description => 'some command';
@@ -114,6 +123,32 @@ void main() {
       );
     });
 
+    group('print completion script command', () {
+      test(
+        'is not added when auto install is enabled',
+        () {
+          final commandRunner = _TestCompletionCommandRunner();
+
+          expect(
+            commandRunner.commands.keys,
+            isNot(contains('completion-script')),
+          );
+        },
+      );
+
+      test(
+        'is added when auto install is disabled',
+        () {
+          final commandRunner = _TestNoAutoInstallCompletionCommandRunner();
+
+          expect(
+            commandRunner.commands.keys,
+            contains('completion-script'),
+          );
+        },
+      );
+    });
+
     group('auto install', () {
       test('Tries to install completion files on test subcommand', () async {
         final commandRunner = _TestCompletionCommandRunner()