@flowscripter/dynamic-cli-framework 1.1.6 → 1.2.1

package/src/cli/BaseCLI.ts

@@ -23,19 +23,38 @@ import UsageCommand from "../command/UsageCommand.ts";
 import {
   isGlobalCommand,
   isGlobalModifierCommand,
+  isGroupCommand,
   isSubCommand,
 } from "../runtime/command/CommandTypeGuards.ts";
 import CommandValidator from "../runtime/command/CommandValidator.ts";
 import ShutdownServiceProvider from "../service/shutdown/ShutdownServiceProvider.ts";
+import { shutdownState } from "../service/shutdown/ShutdownState.ts";
 import ConfigurationServiceProvider from "../service/configuration/ConfigurationServiceProvider.ts";
 import PrinterServiceProvider from "../service/printer/PrinterServiceProvider.ts";
+import TableGeneratorServiceProvider from "../service/tableGenerator/TableGeneratorServiceProvider.ts";
 import { run } from "../runtime/runner.ts";
 
 import { WritableStream } from "node:stream/web";
-import Terminal from "../service/printer/terminal/Terminal.ts";
-import PrinterService from "../api/service/core/PrinterService.ts";
+import type Terminal from "../terminal/Terminal.ts";
+import type PrinterService from "../api/service/core/PrinterService.ts";
 import DefaultPrinterService from "../service/printer/DefaultPrinterService.ts";
-import Styler from "../service/printer/terminal/Styler.ts";
+import type Styler from "../terminal/Styler.ts";
+import type KeyReader from "../terminal/KeyReader.ts";
+import type BaseCLIFeatureOptions from "../api/BaseCLIFeatureOptions.ts";
+import DefaultPrompterService, {
+  DEFAULT_PROMPTER_CONFIG,
+} from "../service/prompter/DefaultPrompterService.ts";
+import PrompterServiceProvider from "../service/prompter/PrompterServiceProvider.ts";
+import DefaultArgumentPrompterService from "../service/argumentPrompter/DefaultArgumentPrompterService.ts";
+import ArgumentPrompterServiceProvider from "../service/argumentPrompter/ArgumentPrompterServiceProvider.ts";
+import DefaultCompletionService from "../service/completion/DefaultCompletionService.ts";
+import CompletionServiceProvider from "../service/completion/CompletionServiceProvider.ts";
+import ImagePrinterServiceProvider from "../service/imagePrinter/ImagePrinterServiceProvider.ts";
+import {
+  CompletionCompleteSubCommand,
+  CompletionGroupCommand,
+  CompletionIntegrationSubCommand,
+} from "../command/CompletionCommand.ts";
 const logger = getLogger("BaseCLI");
 
 /**
@@ -46,10 +65,15 @@ const logger = getLogger("BaseCLI");
  * * {@link ShutdownServiceProvider}
  * * {@link PrinterServiceProvider}
  * * {@link ConfigurationServiceProvider}
+ * * {@link TableGeneratorServiceProvider}
  *
  * NOTE: The `ConfigurationServiceProvider` will not be added if the required `allow-read` and `allow-write`
  * permissions are not granted. It can also be excluded if desired via a constructor argument.
  *
+ * Optionally enabled via {@link BaseCLIFeatureOptions}:
+ *
+ * * {@link ImagePrinterServiceProvider}
+ *
  * By default the following commands are added:
  *
  * * {@link SingleCommandCliHelpSubCommand} or {@link MultiCommandCliHelpSubCommand}
@@ -59,47 +83,32 @@ const logger = getLogger("BaseCLI");
  */
 export default class BaseCLI implements CLI {
   readonly #cliConfig: CLIConfig;
-  readonly #envVarsEnabled: boolean;
-  readonly #configEnabled: boolean;
-  readonly #keyValueServiceEnabled: boolean;
+  readonly #options: Required<BaseCLIFeatureOptions>;
+  readonly #keyReader: KeyReader;
+  readonly #stderrTerminal: Terminal;
   readonly #addedNonModifierCommands: Array<Command>;
   readonly #serviceProviderRegistry: DefaultServiceProviderRegistry;
   readonly #commandRegistry: DefaultCommandRegistry;
   readonly #context: DefaultContext;
   readonly #printerService: PrinterService;
+  readonly #stdoutTerminal: Terminal;
 
-  /**
-   * Constructor configures the instance with the specified CLI application details and WritableStream instances.
-   *
-   * @param cliConfig the {@link CLIConfig} for the CLI application.
-   * @param stdoutWritableStream the WritableStream to use for stderr output.
-   * @param stderrWritableStream the WritableStream to use for stderr output.
-   * @param stdoutIsColor true if stdout supports color.
-   * @param stderrIsColor true if stderr supports color.
-   * @param terminal the Terminal implementation to use.
-   * @param styler the Styler implementation to use.
-   * @param envVarsEnabled optionally support checking env variables for default argument values.
-   * @param configEnabled optionally enable configuration file support for default argument values.
-   * @param keyValueServiceEnabled optionally provide a {@link KeyValueService} implementation: `configEnabled` must be true in this case
-   * @param validateAllCommands optionally force validation of all i.e. include validation of core commands.
-   */
   constructor(
     cliConfig: CLIConfig,
     stdoutWritableStream: WritableStream,
     stderrWritableStream: WritableStream,
     stdoutIsColor: boolean,
     stderrIsColor: boolean,
+    stdoutTerminal: Terminal,
     stderrTerminal: Terminal,
     styler: Styler,
-    envVarsEnabled = false,
-    configEnabled = false,
-    keyValueServiceEnabled = false,
-    validateAllCommands = false,
+    keyReader: KeyReader,
+    options?: BaseCLIFeatureOptions,
   ) {
     if (cliConfig.name.length === 0) {
       throw new Error("Invalid empty CLI name provided");
     }
-    if (cliConfig.name[0].match(/[0-9\-_]/)) {
+    if (cliConfig.name[0]!.match(/[0-9\-_]/)) {
       throw new Error(
         `Invalid CLI name starting with a digit or dash provided: '${cliConfig.name}'`,
       );
@@ -114,14 +123,23 @@ export default class BaseCLI implements CLI {
       throw new Error("Invalid empty CLI version provided");
     }
     this.#cliConfig = cliConfig;
-    this.#envVarsEnabled = envVarsEnabled;
-    this.#configEnabled = configEnabled;
-    this.#keyValueServiceEnabled = keyValueServiceEnabled;
+    this.#options = {
+      configFileSupportEnabled: false,
+      envVarsSupportEnabled: false,
+      keyValueServiceEnabled: false,
+      secretServiceEnabled: false,
+      argumentPrompterServiceEnabled: false,
+      completionServiceEnabled: false,
+      imagePrinterServiceEnabled: false,
+      validateAllCommands: false,
+      ...options,
+    };
+    this.#keyReader = keyReader;
+    this.#stderrTerminal = stderrTerminal;
     this.#addedNonModifierCommands = [];
 
-    // create a validator if required
     let commandValidator: CommandValidator | undefined;
-    if (validateAllCommands) {
+    if (this.#options.validateAllCommands) {
       commandValidator = new CommandValidator(this.#cliConfig);
     }
 
@@ -134,11 +152,13 @@ export default class BaseCLI implements CLI {
     // create a context
     this.#context = new DefaultContext(this.#cliConfig);
 
+    this.#stdoutTerminal = stdoutTerminal;
     this.#printerService = new DefaultPrinterService(
       stdoutWritableStream,
       stderrWritableStream,
       stdoutIsColor,
       stderrIsColor,
+      stdoutTerminal,
       stderrTerminal,
       styler,
     );
@@ -184,11 +204,12 @@ export default class BaseCLI implements CLI {
 
     if (
       (this.#addedNonModifierCommands.length === 1) &&
-      !isSubCommand(this.#addedNonModifierCommands[0]) &&
-      !isGlobalCommand(this.#addedNonModifierCommands[0])
+      !isSubCommand(this.#addedNonModifierCommands[0]!) &&
+      !isGlobalCommand(this.#addedNonModifierCommands[0]!) &&
+      !isGroupCommand(this.#addedNonModifierCommands[0]!)
     ) {
       throw new Error(
-        "If only one command is added, if must be a global command or sub-command!",
+        "If only one command is added, it must be a global command, sub-command, or group command!",
       );
     }
 
@@ -200,12 +221,45 @@ export default class BaseCLI implements CLI {
         this.#printerService,
       ),
     );
+    this.addServiceProvider(new TableGeneratorServiceProvider(70));
+
+    const prompterService = new DefaultPrompterService(
+      DEFAULT_PROMPTER_CONFIG,
+      this.#stderrTerminal,
+      this.#keyReader,
+      this.#printerService,
+    );
+    this.addServiceProvider(new PrompterServiceProvider(75, prompterService));
+
+    if (this.#options.argumentPrompterServiceEnabled) {
+      const argumentPrompterService = new DefaultArgumentPrompterService(
+        prompterService,
+      );
+      this.addServiceProvider(
+        new ArgumentPrompterServiceProvider(65, argumentPrompterService),
+      );
+    }
+
+    if (this.#options.imagePrinterServiceEnabled) {
+      this.addServiceProvider(
+        new ImagePrinterServiceProvider(55, this.#stdoutTerminal),
+      );
+    }
+
+    let completionService: DefaultCompletionService | undefined;
+    if (this.#options.completionServiceEnabled) {
+      completionService = new DefaultCompletionService();
+      this.addServiceProvider(
+        new CompletionServiceProvider(60, completionService),
+      );
+    }
 
     const configurationServiceProvider = new ConfigurationServiceProvider(
       90,
-      this.#envVarsEnabled,
-      this.#configEnabled,
-      this.#keyValueServiceEnabled,
+      this.#options.envVarsSupportEnabled,
+      this.#options.configFileSupportEnabled,
+      this.#options.keyValueServiceEnabled,
+      this.#options.secretServiceEnabled,
     );
     this.addServiceProvider(configurationServiceProvider);
 
@@ -213,7 +267,7 @@ export default class BaseCLI implements CLI {
       const serviceProvider of this.#serviceProviderRegistry
         .getServiceProviders()
     ) {
-      const serviceInfo = await serviceProvider.provide(this.#cliConfig);
+      const serviceInfo = await serviceProvider.getServiceInfo(this.#cliConfig);
 
       if (serviceInfo.service) {
         this.#context.addServiceInstance(
@@ -235,27 +289,30 @@ export default class BaseCLI implements CLI {
 
     try {
       // setup help commands and default command based on the number of commands explicitly added via {@link addCommand)
-      if (this.#addedNonModifierCommands.length === 1) {
+      if (
+        this.#addedNonModifierCommands.length === 1 &&
+        !isGroupCommand(this.#addedNonModifierCommands[0]!)
+      ) {
         // a single-command CLI
         defaultCommand = this.#addedNonModifierCommands[0];
         helpSubCommand = new SingleCommandCliHelpSubCommand(
-          this.#envVarsEnabled,
+          this.#options.envVarsSupportEnabled,
           defaultCommand as SubCommand,
           this.#commandRegistry,
         );
         helpGlobalCommand = new SingleCommandCliHelpGlobalCommand(
-          this.#envVarsEnabled,
+          this.#options.envVarsSupportEnabled,
           defaultCommand as SubCommand,
           this.#commandRegistry,
         );
       } else {
         // a multi-command CLI
         helpSubCommand = new MultiCommandCliHelpSubCommand(
-          this.#envVarsEnabled,
+          this.#options.envVarsSupportEnabled,
           this.#commandRegistry,
         );
         helpGlobalCommand = new MultiCommandCliHelpGlobalCommand(
-          this.#envVarsEnabled,
+          this.#options.envVarsSupportEnabled,
           this.#commandRegistry,
         );
       }
@@ -267,6 +324,16 @@ export default class BaseCLI implements CLI {
       // register the version command
       this.#commandRegistry.addCommand(new VersionCommand());
 
+      // register completion commands (need CommandRegistry reference like help commands)
+      if (completionService) {
+        completionService.setCommandRegistry(this.#commandRegistry);
+        const integrationCommand = new CompletionIntegrationSubCommand();
+        const completeCommand = new CompletionCompleteSubCommand();
+        this.#commandRegistry.addCommand(
+          new CompletionGroupCommand(integrationCommand, completeCommand),
+        );
+      }
+
       // run...
       const runResult = await run(
         args,
@@ -299,7 +366,12 @@ export default class BaseCLI implements CLI {
       }
       return runResult;
     } catch (error) {
-      // An unexpected error in the framework
+      if (
+        shutdownState.shutdownRequested ||
+        (error as Error).message === "Interrupted"
+      ) {
+        return { runState: RunState.INTERRUPTED };
+      }
       logger.error("Runtime error: %s", (error as Error).message);
       return {
         runState: RunState.RUNTIME_ERROR,

package/src/cli/DefaultRuntimeCLI.ts

@@ -3,25 +3,21 @@ import BaseCLI from "./BaseCLI.ts";
 import type RunResult from "../api/RunResult.ts";
 import { RunState } from "../api/RunResult.ts";
 import type CLIConfig from "../api/CLIConfig.ts";
+import type BaseCLIFeatureOptions from "../api/BaseCLIFeatureOptions.ts";
 import { Writable } from "node:stream";
-import TtyTerminal from "../service/printer/terminal/TtyTerminal.ts";
-import TtyStyler from "../service/printer/terminal/TtyStyler.ts";
+import TtyTerminal from "../terminal/TtyTerminal.ts";
+import TtyKeyReader from "../terminal/TtyKeyReader.ts";
+import TtyStyler from "../terminal/TtyStyler.ts";
 import supportsColor from "supports-color";
+import supportsHyperlinks from "../terminal/supportsHyperlinks.ts";
 
 /**
  * Default Bun implementation of a {@link CLI} using `process.stdout`, `process.stderr` and `process.argv`.
  */
 export default class DefaultRuntimeCLI extends BaseCLI {
-  /**
-   * Constructor configures the instance with the specified CLI application details
-   * and making use of `process.stdout` and `process.stderr`.
-   */
   constructor(
     cliConfig: CLIConfig,
-    envVarsEnabled = false,
-    configEnabled = false,
-    keyValueServiceEnabled = false,
-    validateAllCommands = false,
+    options?: BaseCLIFeatureOptions,
   ) {
     super(
       cliConfig,
@@ -29,21 +25,17 @@ export default class DefaultRuntimeCLI extends BaseCLI {
       Writable.toWeb(process.stderr),
       supportsColor.stdout !== false,
       supportsColor.stderr !== false,
+      new TtyTerminal(process.stdout),
       new TtyTerminal(process.stderr),
       new TtyStyler(
         supportsColor.stderr === false ? 1 : supportsColor.stderr.level,
+        supportsHyperlinks(process.stderr),
       ),
-      envVarsEnabled,
-      configEnabled,
-      keyValueServiceEnabled,
-      validateAllCommands,
+      new TtyKeyReader(process.stdin),
+      options,
     );
   }
 
-  /**
-   * Run the CLI using `process.argv` for the arguments and call `process.exit()` passing the
-   * {@link RunState} value resulting from the invocation.
-   */
   override async run(): Promise<RunResult> {
     const runResult = await super.run(process.argv.slice(2));
     if (runResult.runState === RunState.RUNTIME_ERROR) {

package/src/command/CompletionCommand.ts

@@ -0,0 +1,179 @@
+import type GroupCommand from "../api/command/GroupCommand.ts";
+import type SubCommand from "../api/command/SubCommand.ts";
+import type Option from "../api/argument/Option.ts";
+import type Positional from "../api/argument/Positional.ts";
+import type Context from "../api/Context.ts";
+import {
+  type ArgumentValues,
+  ArgumentValueTypeName,
+} from "../api/argument/ArgumentValueTypes.ts";
+import {
+  COMPLETION_SERVICE_ID,
+  ShellType,
+} from "../api/service/core/CompletionService.ts";
+import type DefaultCompletionService from "../service/completion/DefaultCompletionService.ts";
+import {
+  Icon,
+  PRINTER_SERVICE_ID,
+} from "../api/service/core/PrinterService.ts";
+import type PrinterService from "../api/service/core/PrinterService.ts";
+
+export class CompletionIntegrationSubCommand implements SubCommand {
+  readonly name = "integration";
+  readonly description = "Install shell completion integration";
+  readonly enableConfiguration = false;
+
+  readonly options: ReadonlyArray<Option> = [
+    {
+      name: "config-path",
+      type: ArgumentValueTypeName.STRING,
+      isOptional: true,
+      description: "Path to shell configuration file",
+    },
+  ];
+
+  readonly positionals: ReadonlyArray<Positional> = [
+    {
+      name: "shell",
+      type: ArgumentValueTypeName.STRING,
+      allowableValues: Object.values(ShellType),
+      description: "Shell type to configure",
+    },
+  ];
+
+  async execute(
+    context: Context,
+    argumentValues: ArgumentValues,
+  ): Promise<void> {
+    const completionService = context.getServiceById(
+      COMPLETION_SERVICE_ID,
+    ) as DefaultCompletionService;
+    const printerService = context.getServiceById(
+      PRINTER_SERVICE_ID,
+    ) as PrinterService;
+
+    const shellType = argumentValues.shell as ShellType;
+    const configPathArg = argumentValues["config-path"] as string | undefined;
+
+    const isValid = await completionService.validateShellEnvironment(shellType);
+    if (!isValid) {
+      await printerService.warn(
+        `Shell '${shellType}' was not detected in the current environment. Proceeding anyway.\n`,
+        Icon.ALERT,
+      );
+    }
+
+    const configPath = configPathArg ||
+      completionService.getDefaultConfigPath(shellType);
+    const cliName = context.cliConfig.name;
+    const bootstrapScript = completionService.getBootstrapScript(
+      shellType,
+      cliName,
+    );
+
+    const beginMarker = `# BEGIN ${cliName} completion`;
+    const endMarker = `# END ${cliName} completion`;
+    const block = `${beginMarker}\n${bootstrapScript}\n${endMarker}`;
+
+    let existingContent = "";
+    try {
+      existingContent = await Bun.file(configPath).text();
+    } catch {
+      // File doesn't exist yet
+    }
+
+    let newContent: string;
+    const beginIdx = existingContent.indexOf(beginMarker);
+    const endIdx = existingContent.indexOf(endMarker);
+    if (beginIdx !== -1 && endIdx !== -1) {
+      newContent = existingContent.substring(0, beginIdx) +
+        block +
+        existingContent.substring(endIdx + endMarker.length);
+    } else {
+      const separator = existingContent.length > 0 &&
+          !existingContent.endsWith("\n")
+        ? "\n\n"
+        : existingContent.length > 0
+        ? "\n"
+        : "";
+      newContent = existingContent + separator + block + "\n";
+    }
+
+    await Bun.write(configPath, newContent);
+
+    await printerService.info(
+      `Shell completion installed for ${shellType}. Restart your shell or run 'source ${configPath}' to activate.\n`,
+    );
+  }
+}
+
+export class CompletionCompleteSubCommand implements SubCommand {
+  readonly name = "complete";
+  readonly description = "Generate completions for shell integration";
+  readonly enableConfiguration = false;
+
+  readonly options: ReadonlyArray<Option> = [];
+
+  readonly positionals: ReadonlyArray<Positional> = [
+    {
+      name: "shell",
+      type: ArgumentValueTypeName.STRING,
+      allowableValues: Object.values(ShellType),
+      description: "Shell type",
+    },
+    {
+      name: "args",
+      type: ArgumentValueTypeName.STRING,
+      isVarargMultiple: true,
+      isVarargOptional: true,
+      description: "Shell-specific completion context arguments",
+    },
+  ];
+
+  async execute(
+    context: Context,
+    argumentValues: ArgumentValues,
+  ): Promise<void> {
+    const completionService = context.getServiceById(
+      COMPLETION_SERVICE_ID,
+    ) as DefaultCompletionService;
+    const printerService = context.getServiceById(
+      PRINTER_SERVICE_ID,
+    ) as PrinterService;
+
+    const shellType = argumentValues.shell as ShellType;
+    const args = (argumentValues.args || []) as string[];
+
+    const completionContext = completionService.parseCompletionContext(
+      shellType,
+      args,
+    );
+    const completions = await completionService.generateCompletions(
+      shellType,
+      completionContext.line,
+      completionContext.cursorPosition,
+    );
+
+    const output = completionService.formatCompletions(shellType, completions);
+    if (output.length > 0) {
+      await printerService.print(output + "\n");
+    }
+  }
+}
+
+export class CompletionGroupCommand implements GroupCommand {
+  readonly name = "completions";
+  readonly description = "Manage shell auto-completion";
+  readonly enableConfiguration = false;
+  readonly memberSubCommands: ReadonlyArray<SubCommand>;
+
+  constructor(
+    integrationCommand: CompletionIntegrationSubCommand,
+    completeCommand: CompletionCompleteSubCommand,
+  ) {
+    this.memberSubCommands = [integrationCommand, completeCommand];
+  }
+
+  async execute(_context: Context): Promise<void> {
+  }
+}

package/src/command/MultiCommandCliHelpCommand.ts

@@ -26,6 +26,8 @@ import {
   Icon,
   PRINTER_SERVICE_ID,
 } from "../api/service/core/PrinterService.ts";
+import type TableGeneratorService from "../api/service/core/TableGeneratorService.ts";
+import { TABLE_GENERATOR_SERVICE_ID } from "../api/service/core/TableGeneratorService.ts";
 
 /**
  * Provides common implementation for both {@link MultiCommandCliHelpGlobalCommand} and {@link MultiCommandCliHelpSubCommand}.
@@ -178,6 +180,9 @@ abstract class MultiCommandCliAbstractHelpCommand {
     const printerService = context.getServiceById(
       PRINTER_SERVICE_ID,
     ) as PrinterService;
+    const tableGeneratorService = context.getServiceById(
+      TABLE_GENERATOR_SERVICE_ID,
+    ) as TableGeneratorService;
 
     const globalModifierCommands = this.#commandRegistry
       .getGlobalModifierCommands();
@@ -210,7 +215,11 @@ abstract class MultiCommandCliAbstractHelpCommand {
       ),
     );
 
-    await printHelpSections(printerService, helpSections);
+    await printHelpSections(
+      printerService,
+      tableGeneratorService,
+      helpSections,
+    );
   }
 
   protected async printUsageHelp(
@@ -220,6 +229,9 @@ abstract class MultiCommandCliAbstractHelpCommand {
     const printerService = context.getServiceById(
       PRINTER_SERVICE_ID,
     ) as PrinterService;
+    const tableGeneratorService = context.getServiceById(
+      TABLE_GENERATOR_SERVICE_ID,
+    ) as TableGeneratorService;
 
     const groupCommands = this.#commandRegistry.getGroupCommands();
     const subCommands = this.#commandRegistry.getSubCommands();
@@ -300,7 +312,11 @@ abstract class MultiCommandCliAbstractHelpCommand {
       ...getCommandExamplesHelpSections(printerService, context, subCommand),
     );
 
-    await printHelpSections(printerService, helpSections);
+    await printHelpSections(
+      printerService,
+      tableGeneratorService,
+      helpSections,
+    );
   }
 }
 

package/src/command/SingleCommandCliHelpCommand.ts

@@ -17,6 +17,8 @@ import type GroupCommand from "../api/command/GroupCommand.ts";
 import type CommandRegistry from "../runtime/registry/CommandRegistry.ts";
 import type PrinterService from "../api/service/core/PrinterService.ts";
 import { PRINTER_SERVICE_ID } from "../api/service/core/PrinterService.ts";
+import type TableGeneratorService from "../api/service/core/TableGeneratorService.ts";
+import { TABLE_GENERATOR_SERVICE_ID } from "../api/service/core/TableGeneratorService.ts";
 
 /**
  * Provides common implementation for both {@link SingleCommandCliHelpGlobalCommand} and {@link SingleCommandCliHelpSubCommand}.
@@ -149,6 +151,9 @@ abstract class SingleCommandCliAbstractHelpCommand {
     const printerService = context.getServiceById(
       PRINTER_SERVICE_ID,
     ) as PrinterService;
+    const tableGeneratorService = context.getServiceById(
+      TABLE_GENERATOR_SERVICE_ID,
+    ) as TableGeneratorService;
 
     helpSections.push(
       ...getCommandExamplesHelpSections(
@@ -158,7 +163,11 @@ abstract class SingleCommandCliAbstractHelpCommand {
       ),
     );
 
-    await printHelpSections(printerService, helpSections);
+    await printHelpSections(
+      printerService,
+      tableGeneratorService,
+      helpSections,
+    );
   }
 }