feat: add install triggers (#10)

Co-authored-by: Felix Angelov <[email protected]>

Author: renancaraujo

example/lib/src/command_runner.dart

@@ -1,4 +1,5 @@
 import 'package:args/command_runner.dart';
+import 'package:cli_completion/cli_completion.dart';
 import 'package:example/src/commands/commands.dart';
 import 'package:mason_logger/mason_logger.dart';
 
@@ -13,7 +14,7 @@ const description = 'Example for cli_completion';
 /// $ example_cli --version
 /// ```
 /// {@endtemplate}
-class ExampleCommandRunner extends CommandRunner<int> {
+class ExampleCommandRunner extends CompletionCommandRunner<int> {
   /// {@macro example_command_runner}
   ExampleCommandRunner({
     Logger? logger,

example/pubspec.yaml

@@ -8,6 +8,8 @@ environment:
 
 dependencies:
   args: ^2.3.1
+  cli_completion:
+    path: ../
   mason_logger: ^0.2.0
 
 dev_dependencies:

lib/cli_completion.dart

@@ -0,0 +1,6 @@
+/// Contains the completion command runner based elements to add completion to
+/// dart command line applications.
+library cli_completion;
+
+export 'src/command_runner/commands/commands.dart';
+export 'src/command_runner/completion_command_runner.dart';

lib/src/command_runner/commands/commands.dart

@@ -0,0 +1,2 @@
+export 'handle_completion_command.dart';
+export 'install_completion_files_command.dart';

lib/src/command_runner/commands/handle_completion_command.dart

@@ -0,0 +1,45 @@
+import 'dart:async';
+
+import 'package:args/command_runner.dart';
+import 'package:cli_completion/src/command_runner/completion_command_runner.dart';
+
+import 'package:mason_logger/mason_logger.dart';
+
+/// {@template handle_completion_request_command}
+/// A hidden [Command] added by [CompletionCommandRunner] that handles the
+/// "completion" sub command.
+/// This is called by a shell function when the user presses "tab".
+/// Any output to stdout during this call will be interpreted as suggestions
+/// for completions.
+/// {@endtemplate}
+class HandleCompletionRequestCommand<T> extends Command<T> {
+  /// {@macro handle_completion_request_command}
+  HandleCompletionRequestCommand(this.logger);
+
+  @override
+  String get description {
+    return 'Handles shell completion (should never be called manually)';
+  }
+
+  /// The string that the shell will use to call for completion suggestions
+  static const commandName = 'completion';
+
+  @override
+  String get name => commandName;
+
+  @override
+  bool get hidden => true;
+
+  /// The [Logger] used to display the completion suggestions
+  final Logger logger;
+
+  @override
+  FutureOr<T>? run() {
+    logger
+      ..info('USA')
+      ..info('Brazil')
+      ..info('Netherlands');
+
+    return null;
+  }
+}

lib/src/command_runner/commands/install_completion_files_command.dart

@@ -0,0 +1,54 @@
+import 'dart:async';
+
+import 'package:args/command_runner.dart';
+import 'package:cli_completion/src/command_runner/completion_command_runner.dart';
+
+import 'package:mason_logger/mason_logger.dart';
+
+/// {@template install_completion_command}
+/// A hidden [Command] added by [CompletionCommandRunner] that can be used to
+/// manually install the completion files
+/// (otherwise automatically installed by [CompletionCommandRunner]).
+/// {@endtemplate}
+///
+/// Differently from the auto installation performed by
+/// [CompletionCommandRunner] on any command run,
+/// this command logs messages during the installation process.
+class InstallCompletionFilesCommand<T> extends Command<T> {
+  /// {@macro install_completion_command}
+  InstallCompletionFilesCommand() {
+    argParser.addFlag(
+      'verbose',
+      abbr: 'v',
+      help: 'Verbose output',
+      negatable: false,
+    );
+  }
+
+  @override
+  String get description {
+    return 'Manually installs completion files for the current shell.';
+  }
+
+  /// The string that the user can call to manually install completion files
+  static const commandName = 'install-completion-files';
+
+  @override
+  String get name => commandName;
+
+  @override
+  bool get hidden => true;
+
+  @override
+  CompletionCommandRunner<T> get runner {
+    return super.runner! as CompletionCommandRunner<T>;
+  }
+
+  @override
+  FutureOr<T>? run() {
+    final verbose = argResults!['verbose'] as bool;
+    final level = verbose ? Level.verbose : Level.info;
+    runner.tryInstallCompletionFiles(level);
+    return null;
+  }
+}

lib/src/command_runner/completion_command_runner.dart

@@ -0,0 +1,84 @@
+import 'dart:async';
+
+import 'package:args/args.dart';
+import 'package:args/command_runner.dart';
+import 'package:cli_completion/src/command_runner/commands/commands.dart';
+import 'package:cli_completion/src/exceptions.dart';
+import 'package:cli_completion/src/install/completion_installation.dart';
+import 'package:cli_completion/src/system_shell.dart';
+import 'package:mason_logger/mason_logger.dart';
+import 'package:meta/meta.dart';
+
+/// {@template completion_command_runner}
+/// A [CommandRunner] that takes care of installing shell completion scripts
+/// and handle completion requests.
+/// {@endtemplate}
+///
+/// It tries to install completion scripts upon any command run.
+///
+/// Adds [HandleCompletionRequestCommand] to route completion requests to
+/// other sub commands.
+///
+/// Adds [InstallCompletionFilesCommand] to enable the user to
+/// manually install completion files.
+abstract class CompletionCommandRunner<T> extends CommandRunner<T> {
+  /// {@macro completion_command_runner}
+  CompletionCommandRunner(super.executableName, super.description) {
+    addCommand(HandleCompletionRequestCommand<T>(completionLogger));
+    addCommand(InstallCompletionFilesCommand<T>());
+  }
+
+  /// The [Logger] used to prompt the completion suggestions.
+  final Logger completionLogger = Logger();
+
+  /// The [Logger] used to display messages during completion installation.
+  final Logger completionInstallationLogger = Logger();
+
+  /// Environment map which can be overridden for testing purposes.
+  @visibleForTesting
+  Map<String, String>? environmentOverride;
+
+  SystemShell? get _systemShell =>
+      SystemShell.current(environmentOverride: environmentOverride);
+
+  CompletionInstallation? _completionInstallation;
+
+  /// The [CompletionInstallation] used to install completion files.
+  CompletionInstallation get completionInstallation {
+    var completionInstallation = _completionInstallation;
+
+    completionInstallation ??= CompletionInstallation.fromSystemShell(
+      systemShell: _systemShell,
+      logger: completionInstallationLogger,
+    );
+
+    return _completionInstallation = completionInstallation;
+  }
+
+  @override
+  @mustCallSuper
+  Future<T?> runCommand(ArgResults topLevelResults) async {
+    final reservedCommands = [
+      HandleCompletionRequestCommand.commandName,
+      InstallCompletionFilesCommand.commandName,
+    ];
+
+    if (!reservedCommands.contains(topLevelResults.command?.name)) {
+      // When auto installing, use error level to display messages.
+      tryInstallCompletionFiles(Level.error);
+    }
+
+    return super.runCommand(topLevelResults);
+  }
+
+  /// Tries to install completion files for the current shell.
+  @internal
+  void tryInstallCompletionFiles(Level level) {
+    try {
+      completionInstallationLogger.level = level;
+      completionInstallation.install(executableName);
+    } on CompletionInstallationException catch (e) {
+      completionInstallationLogger.err(e.toString());
+    }
+  }
+}

lib/src/install/completion_installation.dart

@@ -24,16 +24,20 @@ class CompletionInstallation {
 
   /// Creates a [CompletionInstallation] given the current [SystemShell].
   factory CompletionInstallation.fromSystemShell({
-    required SystemShell systemShell,
+    required SystemShell? systemShell,
     required Logger logger,
     bool? isWindowsOverride,
     Map<String, String>? environmentOverride,
   }) {
     final isWindows = isWindowsOverride ?? Platform.isWindows;
     final environment = environmentOverride ?? Platform.environment;
 
+    final configuration = systemShell == null
+        ? null
+        : ShellCompletionConfiguration.fromSystemShell(systemShell);
+
     return CompletionInstallation(
-      configuration: ShellCompletionConfiguration.fromSystemShell(systemShell),
+      configuration: configuration,
       logger: logger,
       isWindows: isWindows,
       environment: environment,
@@ -51,7 +55,7 @@ class CompletionInstallation {
   final Map<String, String> environment;
 
   /// The associated [ShellCompletionConfiguration].
-  final ShellCompletionConfiguration configuration;
+  final ShellCompletionConfiguration? configuration;
 
   /// Define the [Directory] in which the
   /// completion configuration files will be stored.
@@ -71,6 +75,15 @@ class CompletionInstallation {
   /// Install completion configuration hooks for a [rootCommand] in the
   /// current shell.
   void install(String rootCommand) {
+    final configuration = this.configuration;
+
+    if (configuration == null) {
+      throw CompletionInstallationException(
+        message: 'Unknown shell.',
+        rootCommand: rootCommand,
+      );
+    }
+
     logger.detail(
       'Installing completion for the command $rootCommand '
       'on ${configuration.name}',
@@ -87,13 +100,13 @@ class CompletionInstallation {
   void createCompletionConfigDir() {
     final completionConfigDirPath = completionConfigDir.path;
 
-    logger.detail(
+    logger.info(
       'Creating completion configuration directory '
       'at $completionConfigDirPath',
     );
 
     if (completionConfigDir.existsSync()) {
-      logger.detail(
+      logger.warn(
         'A ${completionConfigDir.path} directory was already found.',
       );
       return;
@@ -106,20 +119,21 @@ class CompletionInstallation {
   /// identified shell.
   @visibleForTesting
   void writeCompletionScriptForCommand(String rootCommand) {
+    final configuration = this.configuration!;
     final completionConfigDirPath = completionConfigDir.path;
     final commandScriptName = '$rootCommand.${configuration.name}';
     final commandScriptPath = path.join(
       completionConfigDirPath,
       commandScriptName,
     );
-    logger.detail(
+    logger.info(
       'Writing completion script for $rootCommand on $commandScriptPath',
     );
 
     final scriptFile = File(commandScriptPath);
 
     if (scriptFile.existsSync()) {
-      logger.detail(
+      logger.warn(
         'A script file for $rootCommand was already found on '
         '$commandScriptPath.',
       );
@@ -133,18 +147,19 @@ class CompletionInstallation {
   /// [writeCompletionScriptForCommand] the the global completion config file.
   @visibleForTesting
   void writeCompletionConfigForShell(String rootCommand) {
+    final configuration = this.configuration!;
     final completionConfigDirPath = completionConfigDir.path;
 
     final configPath = path.join(
       completionConfigDirPath,
       configuration.completionConfigForShellFileName,
     );
-    logger.detail('Adding config for $rootCommand config entry to $configPath');
+    logger.info('Adding config for $rootCommand config entry to $configPath');
 
     final configFile = File(configPath);
 
     if (!configFile.existsSync()) {
-      logger.detail('No file found at $configPath, creating one now');
+      logger.info('No file found at $configPath, creating one now');
       configFile.createSync();
     }
     final commandScriptName = '$rootCommand.${configuration.name}';
@@ -153,7 +168,7 @@ class CompletionInstallation {
         configFile.readAsStringSync().contains(commandScriptName);
 
     if (containsLine) {
-      logger.detail(
+      logger.warn(
         'A config entry for $rootCommand was already found on $configPath.',
       );
       return;
@@ -167,13 +182,15 @@ class CompletionInstallation {
   }
 
   String get _shellRCFilePath =>
-      _resolveHome(configuration.shellRCFile, environment);
+      _resolveHome(configuration!.shellRCFile, environment);
 
   /// Write a source to the completion global script in the shell configuration
   /// file, which its location is described by the [configuration]
   @visibleForTesting
   void writeToShellConfigFile(String rootCommand) {
-    logger.detail(
+    final configuration = this.configuration!;
+
+    logger.info(
       'Adding dart cli completion config entry '
       'to $_shellRCFilePath',
     );
@@ -190,15 +207,15 @@ class CompletionInstallation {
     if (!shellRCFile.existsSync()) {
       throw CompletionInstallationException(
         rootCommand: rootCommand,
-        message: 'No file found at ${shellRCFile.path}',
+        message: 'No configuration file found at ${shellRCFile.path}',
       );
     }
 
     final containsLine =
         shellRCFile.readAsStringSync().contains(completionConfigPath);
 
     if (containsLine) {
-      logger.detail('A completion config entry was found on'
+      logger.warn('A completion config entry was already found on'
           ' $_shellRCFilePath.');
       return;
     }
@@ -235,13 +252,13 @@ class CompletionInstallation {
       '''
 ## [$scriptName] 
 ## $description
-${configuration.sourceLineTemplate(scriptPath)}
+${configuration!.sourceLineTemplate(scriptPath)}
 ## [/$scriptName]
 
 ''',
     );
 
-    logger.detail('Added config to $configFilePath');
+    logger.info('Added config to $configFilePath');
   }
 }
 

pubspec.yaml

@@ -7,6 +7,7 @@ environment:
   sdk: ">=2.18.0 <3.0.0"
 
 dependencies:
+  args: ^2.3.1
   mason_logger: ^0.2.2
   meta: ^1.8.0
   path: ^1.8.2