@flowscripter/dynamic-cli-framework 1.1.6 → 1.2.1

package/src/service/completion/CompletionServiceProvider.ts

@@ -0,0 +1,212 @@
+import type { ServiceProvider } from "../../api/service/ServiceProvider.ts";
+import type { ServiceInfo } from "../../api/service/ServiceProvider.ts";
+import type CLIConfig from "../../api/CLIConfig.ts";
+import type Context from "../../api/Context.ts";
+import { COMPLETION_SERVICE_ID } from "../../api/service/core/CompletionService.ts";
+import { ShellType } from "../../api/service/core/CompletionService.ts";
+import type DefaultCompletionService from "./DefaultCompletionService.ts";
+import { PROMPTER_SERVICE_ID } from "../../api/service/core/PrompterService.ts";
+import { PromptType } from "../../api/service/core/PrompterService.ts";
+import type PrompterService from "../../api/service/core/PrompterService.ts";
+import { KEY_VALUE_SERVICE_ID } from "../../api/service/core/KeyValueService.ts";
+import type KeyValueService from "../../api/service/core/KeyValueService.ts";
+import {
+  Icon,
+  PRINTER_SERVICE_ID,
+} from "../../api/service/core/PrinterService.ts";
+import type PrinterService from "../../api/service/core/PrinterService.ts";
+import getLogger from "../../util/logger.ts";
+
+const logger = getLogger("CompletionServiceProvider");
+
+export default class CompletionServiceProvider implements ServiceProvider {
+  readonly serviceId: string = COMPLETION_SERVICE_ID;
+  readonly servicePriority: number;
+  readonly #completionService: DefaultCompletionService;
+  #cliName = "";
+
+  public constructor(
+    servicePriority: number,
+    completionService: DefaultCompletionService,
+  ) {
+    this.servicePriority = servicePriority;
+    this.#completionService = completionService;
+  }
+
+  public getServiceInfo(cliConfig: CLIConfig): Promise<ServiceInfo> {
+    this.#cliName = cliConfig.name;
+    return Promise.resolve({
+      service: this.#completionService,
+      commands: [],
+    });
+  }
+
+  public async initService(context: Context): Promise<void> {
+    if (!context.doesServiceExist(PROMPTER_SERVICE_ID)) {
+      logger.debug(() => "PrompterService not available, skipping auto-prompt");
+      return;
+    }
+    if (!context.doesServiceExist(KEY_VALUE_SERVICE_ID)) {
+      logger.debug(
+        () => "KeyValueService not available, skipping auto-prompt",
+      );
+      return;
+    }
+
+    const keyValueService = context.getServiceById(
+      KEY_VALUE_SERVICE_ID,
+    ) as KeyValueService;
+    if (await keyValueService.hasKey("completion-status")) {
+      const status = await keyValueService.getKey("completion-status");
+      if (status === "installed" || status === "declined") {
+        logger.debug(
+          () => `Completion status is '${status}', skipping auto-prompt`,
+        );
+        return;
+      }
+    }
+
+    const prompterService = context.getServiceById(
+      PROMPTER_SERVICE_ID,
+    ) as PrompterService;
+    if (!prompterService.promptEnabled) {
+      logger.debug(() => "Prompting is disabled, skipping auto-prompt");
+      return;
+    }
+
+    const detectedShells = await this.#detectAvailableShells();
+    if (detectedShells.length === 0) {
+      logger.debug(
+        () => "No supported shells detected, skipping auto-prompt",
+      );
+      return;
+    }
+
+    let enableResult;
+    try {
+      enableResult = await prompterService.prompt({
+        name: "enable-completion",
+        promptText: "Would you like to enable autocompletion?",
+        description:
+          "This will set up your terminal so that pressing TAB while typing commands will show possible options and autocomplete arguments.\n(Enabling autocompletion will modify configuration files in your home directory.)",
+        type: PromptType.TOGGLE,
+        options: [
+          { displayValue: "Yes", returnedValue: true },
+          { displayValue: "No", returnedValue: false },
+        ],
+      });
+    } catch {
+      return;
+    }
+
+    if (enableResult.value !== true) {
+      await keyValueService.setKey("completion-status", "declined");
+      return;
+    }
+
+    let shellType: ShellType;
+
+    if (detectedShells.length === 1) {
+      shellType = detectedShells[0]!;
+    } else {
+      const shellOptions = detectedShells.map((shell) => ({
+        displayValue: shell,
+        returnedValue: shell,
+      }));
+
+      let shellResult;
+      try {
+        shellResult = await prompterService.prompt({
+          name: "shell-type",
+          promptText: "Which shell would you like to configure?",
+          type: PromptType.SINGLE_SELECT,
+          defaultOption: shellOptions[0],
+          options: shellOptions,
+        });
+      } catch {
+        return;
+      }
+
+      shellType = shellResult.value as ShellType;
+    }
+
+    try {
+      await this.#installCompletion(context, shellType);
+      await keyValueService.setKey("completion-status", "installed");
+    } catch (error) {
+      logger.error(
+        "Failed to install completion: %s",
+        (error as Error).message,
+      );
+      if (context.doesServiceExist(PRINTER_SERVICE_ID)) {
+        const printerService = context.getServiceById(
+          PRINTER_SERVICE_ID,
+        ) as PrinterService;
+        await printerService.error(
+          `Failed to install completion: ${(error as Error).message}`,
+          Icon.FAILURE,
+        );
+      }
+    }
+  }
+
+  async #detectAvailableShells(): Promise<ShellType[]> {
+    const available: ShellType[] = [];
+    for (const shell of Object.values(ShellType)) {
+      if (await this.#completionService.validateShellEnvironment(shell)) {
+        available.push(shell);
+      }
+    }
+    return available;
+  }
+
+  async #installCompletion(
+    context: Context,
+    shellType: ShellType,
+  ): Promise<void> {
+    const configPath = this.#completionService.getDefaultConfigPath(shellType);
+    const bootstrapScript = this.#completionService.getBootstrapScript(
+      shellType,
+      this.#cliName,
+    );
+    const beginMarker = `# BEGIN ${this.#cliName} completion`;
+    const endMarker = `# END ${this.#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);
+
+    if (context.doesServiceExist(PRINTER_SERVICE_ID)) {
+      const printerService = context.getServiceById(
+        PRINTER_SERVICE_ID,
+      ) as PrinterService;
+      await printerService.info(
+        `Shell completion installed for ${shellType}. Restart your shell or run 'source ${configPath}' to activate.`,
+        Icon.SUCCESS,
+      );
+    }
+  }
+}

package/src/service/completion/DefaultCompletionService.ts

@@ -0,0 +1,364 @@
+import type CompletionService from "../../api/service/core/CompletionService.ts";
+import {
+  type CompletionItem,
+  ShellType,
+} from "../../api/service/core/CompletionService.ts";
+import type CommandRegistry from "../../runtime/registry/CommandRegistry.ts";
+import type ShellHandler from "./shell/ShellHandler.ts";
+import BashShellHandler from "./shell/bash.ts";
+import ZshShellHandler from "./shell/zsh.ts";
+import FishShellHandler from "./shell/fish.ts";
+import PowerShellShellHandler from "./shell/powershell.ts";
+import type SubCommand from "../../api/command/SubCommand.ts";
+import type Option from "../../api/argument/Option.ts";
+
+export default class DefaultCompletionService implements CompletionService {
+  #commandRegistry: CommandRegistry | undefined;
+
+  readonly #shellHandlers: Map<ShellType, ShellHandler> = new Map([
+    [ShellType.BASH, new BashShellHandler()],
+    [ShellType.ZSH, new ZshShellHandler()],
+    [ShellType.FISH, new FishShellHandler()],
+    [ShellType.POWERSHELL, new PowerShellShellHandler()],
+  ]);
+
+  setCommandRegistry(registry: CommandRegistry): void {
+    this.#commandRegistry = registry;
+  }
+
+  getBootstrapScript(shellType: ShellType, cliName: string): string {
+    return this.#getHandler(shellType).getBootstrapScript(cliName);
+  }
+
+  getDefaultConfigPath(shellType: ShellType): string {
+    return this.#getHandler(shellType).getDefaultConfigPath();
+  }
+
+  validateShellEnvironment(shellType: ShellType): Promise<boolean> {
+    return this.#getHandler(shellType).validateEnvironment();
+  }
+
+  formatCompletions(
+    shellType: ShellType,
+    completions: ReadonlyArray<CompletionItem>,
+  ): string {
+    return this.#getHandler(shellType).formatCompletions(completions);
+  }
+
+  parseCompletionContext(
+    shell: ShellType,
+    args: ReadonlyArray<string>,
+  ): { line: string; cursorPosition: number } {
+    return this.#getHandler(shell).parseCompletionContext(args);
+  }
+
+  generateCompletions(
+    _shellType: ShellType,
+    line: string,
+    cursorPosition: number,
+  ): Promise<ReadonlyArray<CompletionItem>> {
+    if (!this.#commandRegistry) {
+      return Promise.resolve([]);
+    }
+
+    const beforeCursor = line.substring(0, cursorPosition);
+    const words = this.#tokenize(beforeCursor);
+
+    // Remove CLI name (first word)
+    const relevantWords = words.slice(1);
+    const currentWord = relevantWords[relevantWords.length - 1] ?? "";
+    const previousWords = relevantWords.slice(0, -1);
+    const endsWithSpace = beforeCursor.endsWith(" ");
+
+    if (
+      relevantWords.length === 0 ||
+      (relevantWords.length === 1 && !endsWithSpace)
+    ) {
+      return Promise.resolve(this.#completeCommandName(currentWord));
+    }
+
+    if (endsWithSpace) {
+      const commandWord = relevantWords[0]!;
+      return Promise.resolve(
+        this.#completeAfterCommand(commandWord, relevantWords.slice(1), ""),
+      );
+    }
+
+    const commandWord = previousWords[0];
+    if (commandWord) {
+      return Promise.resolve(
+        this.#completeAfterCommand(
+          commandWord,
+          previousWords.slice(1),
+          currentWord,
+        ),
+      );
+    }
+
+    return Promise.resolve(this.#completeCommandName(currentWord));
+  }
+
+  #completeAfterCommand(
+    commandWord: string,
+    intermediateWords: ReadonlyArray<string>,
+    currentWord: string,
+  ): ReadonlyArray<CompletionItem> {
+    // Check for group:member pattern
+    if (commandWord.includes(":")) {
+      const result = this.#commandRegistry!
+        .getGroupCommandAndMemberSubCommandByJoinedName(commandWord);
+      if (result) {
+        return this.#completeSubCommandArgs(
+          result.command,
+          intermediateWords,
+          currentWord,
+        );
+      }
+    }
+
+    // Check if partial group:member (e.g. "completions:" completing member)
+    if (currentWord.includes(":")) {
+      const colonIdx = currentWord.indexOf(":");
+      const groupPart = currentWord.substring(0, colonIdx);
+      const groupCommand = this.#commandRegistry!.getGroupCommandByName(
+        groupPart,
+      );
+      if (groupCommand) {
+        return groupCommand.memberSubCommands
+          .filter((sc) => `${groupPart}:${sc.name}`.startsWith(currentWord))
+          .map((sc) => ({
+            value: `${groupPart}:${sc.name}`,
+            description: sc.description,
+          }));
+      }
+    }
+
+    // Check sub-command
+    const subCommand = this.#commandRegistry!.getSubCommandByName(commandWord);
+    if (subCommand) {
+      return this.#completeSubCommandArgs(
+        subCommand,
+        intermediateWords,
+        currentWord,
+      );
+    }
+
+    // Check group command (suggest members)
+    const groupCommand = this.#commandRegistry!.getGroupCommandByName(
+      commandWord,
+    );
+    if (groupCommand) {
+      return groupCommand.memberSubCommands
+        .filter((sc) => sc.name.startsWith(currentWord))
+        .map((sc) => ({
+          value: `${commandWord}:${sc.name}`,
+          description: sc.description,
+        }));
+    }
+
+    return this.#completeCommandName(currentWord);
+  }
+
+  #completeCommandName(prefix: string): ReadonlyArray<CompletionItem> {
+    const completions: CompletionItem[] = [];
+
+    // Sub-commands
+    const subCommands = this.#commandRegistry!.getSubCommands();
+    for (const cmd of subCommands) {
+      if (cmd.name.startsWith(prefix)) {
+        completions.push({ value: cmd.name, description: cmd.description });
+      }
+    }
+
+    // Group:member joined names
+    const groupAndMembers = this.#commandRegistry!
+      .getGroupAndMemberCommandsByJoinedName();
+    for (const [joinedName, entry] of groupAndMembers) {
+      if (joinedName.startsWith(prefix)) {
+        completions.push({
+          value: joinedName,
+          description: entry.command.description,
+        });
+      }
+    }
+
+    // Group command names (to suggest further typing "group:")
+    const groupCommands = this.#commandRegistry!.getGroupCommands();
+    for (const cmd of groupCommands) {
+      if (cmd.name.startsWith(prefix) && !prefix.includes(":")) {
+        completions.push({
+          value: cmd.name,
+          description: cmd.description,
+        });
+      }
+    }
+
+    // Global commands (with -- prefix)
+    const globalCommands = this.#commandRegistry!.getGlobalCommands();
+    for (const cmd of globalCommands) {
+      const prefixed = `--${cmd.name}`;
+      if (prefixed.startsWith(prefix)) {
+        completions.push({ value: prefixed, description: cmd.description });
+      }
+    }
+
+    // Global modifier commands (with -- prefix)
+    const modifierCommands = this.#commandRegistry!
+      .getGlobalModifierCommands();
+    for (const cmd of modifierCommands) {
+      const prefixed = `--${cmd.name}`;
+      if (prefixed.startsWith(prefix)) {
+        completions.push({ value: prefixed, description: cmd.description });
+      }
+    }
+
+    return completions;
+  }
+
+  #completeSubCommandArgs(
+    subCommand: SubCommand,
+    previousArgs: ReadonlyArray<string>,
+    currentWord: string,
+  ): ReadonlyArray<CompletionItem> {
+    const completions: CompletionItem[] = [];
+
+    // If current word starts with --, complete option names
+    if (currentWord.startsWith("--")) {
+      const prefix = currentWord.substring(2);
+      for (const opt of subCommand.options) {
+        if ("name" in opt && (opt as Option).name.startsWith(prefix)) {
+          completions.push({
+            value: `--${(opt as Option).name}`,
+            description: (opt as Option).description,
+          });
+        }
+      }
+      return completions;
+    }
+
+    // If current word starts with -, complete short aliases
+    if (currentWord.startsWith("-") && currentWord.length <= 2) {
+      for (const opt of subCommand.options) {
+        if ("shortAlias" in opt && (opt as Option).shortAlias) {
+          const alias = `-${(opt as Option).shortAlias}`;
+          if (alias.startsWith(currentWord)) {
+            completions.push({
+              value: alias,
+              description: (opt as Option).description,
+            });
+          }
+        }
+      }
+      return completions;
+    }
+
+    // Check if previous word was an option expecting a value
+    const lastPrevWord = previousArgs[previousArgs.length - 1];
+    if (lastPrevWord && lastPrevWord.startsWith("--")) {
+      const optName = lastPrevWord.substring(2);
+      const option = subCommand.options.find(
+        (o) => "name" in o && (o as Option).name === optName,
+      ) as Option | undefined;
+      if (option && option.allowableValues) {
+        return option.allowableValues
+          .filter((v) => String(v).startsWith(currentWord))
+          .map((v) => ({ value: String(v) }));
+      }
+    }
+
+    // Suggest options that haven't been used
+    for (const opt of subCommand.options) {
+      if ("name" in opt) {
+        const optName = `--${(opt as Option).name}`;
+        if (
+          !previousArgs.includes(optName) && optName.startsWith(currentWord)
+        ) {
+          completions.push({
+            value: optName,
+            description: (opt as Option).description,
+          });
+        }
+      }
+    }
+
+    // Suggest positional allowable values
+    const positionalIndex = this.#countPositionalArgs(
+      previousArgs,
+      subCommand,
+    );
+    if (positionalIndex < subCommand.positionals.length) {
+      const positional = subCommand.positionals[positionalIndex]!;
+      if (positional.allowableValues) {
+        for (const v of positional.allowableValues) {
+          if (String(v).startsWith(currentWord)) {
+            completions.push({ value: String(v) });
+          }
+        }
+      }
+    }
+
+    return completions;
+  }
+
+  #countPositionalArgs(
+    args: ReadonlyArray<string>,
+    subCommand: SubCommand,
+  ): number {
+    let count = 0;
+    let i = 0;
+    while (i < args.length) {
+      const arg = args[i]!;
+      if (arg.startsWith("-")) {
+        // Skip option and its value
+        const optName = arg.startsWith("--") ? arg.substring(2) : undefined;
+        const option = optName
+          ? subCommand.options.find(
+            (o) => "name" in o && (o as Option).name === optName,
+          )
+          : undefined;
+        if (option && option.type !== undefined) {
+          i++; // skip the option value
+        }
+      } else {
+        count++;
+      }
+      i++;
+    }
+    return count;
+  }
+
+  #tokenize(input: string): string[] {
+    const words: string[] = [];
+    let current = "";
+    let inSingleQuote = false;
+    let inDoubleQuote = false;
+
+    for (let i = 0; i < input.length; i++) {
+      const ch = input[i]!;
+      if (ch === "'" && !inDoubleQuote) {
+        inSingleQuote = !inSingleQuote;
+      } else if (ch === '"' && !inSingleQuote) {
+        inDoubleQuote = !inDoubleQuote;
+      } else if (ch === " " && !inSingleQuote && !inDoubleQuote) {
+        if (current.length > 0) {
+          words.push(current);
+          current = "";
+        }
+      } else {
+        current += ch;
+      }
+    }
+    if (current.length > 0) {
+      words.push(current);
+    }
+    return words;
+  }
+
+  #getHandler(shellType: ShellType): ShellHandler {
+    const handler = this.#shellHandlers.get(shellType);
+    if (!handler) {
+      throw new Error(`Unsupported shell type: ${shellType}`);
+    }
+    return handler;
+  }
+}

package/src/service/completion/shell/ShellHandler.ts

@@ -0,0 +1,16 @@
+import type { CompletionItem } from "../../../api/service/core/CompletionService.ts";
+
+export interface CompletionContext {
+  readonly line: string;
+  readonly cursorPosition: number;
+}
+
+export default interface ShellHandler {
+  getDefaultConfigPath(): string;
+  getBootstrapScript(cliName: string): string;
+  validateEnvironment(): Promise<boolean>;
+  formatCompletions(completions: ReadonlyArray<CompletionItem>): string;
+  parseCompletionContext(
+    args: ReadonlyArray<string>,
+  ): CompletionContext;
+}

package/src/service/completion/shell/bash.ts

@@ -0,0 +1,47 @@
+import process from "node:process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { CompletionItem } from "../../../api/service/core/CompletionService.ts";
+import type ShellHandler from "./ShellHandler.ts";
+import type { CompletionContext } from "./ShellHandler.ts";
+
+// Reference: https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion.html
+
+export default class BashShellHandler implements ShellHandler {
+  getDefaultConfigPath(): string {
+    return join(homedir(), ".bashrc");
+  }
+
+  getBootstrapScript(cliName: string): string {
+    return [
+      `_${cliName}_completions() {`,
+      `  local IFS=$'\\n'`,
+      `  COMPREPLY=( $(${cliName} completions:complete bash "\${COMP_LINE}" "\${COMP_POINT}") )`,
+      `}`,
+      `complete -F _${cliName}_completions ${cliName}`,
+    ].join("\n");
+  }
+
+  validateEnvironment(): Promise<boolean> {
+    const shell = process.env.SHELL || "";
+    if (shell.endsWith("/bash")) {
+      return Promise.resolve(true);
+    }
+    try {
+      const result = Bun.spawnSync(["bash", "--version"]);
+      return Promise.resolve(result.exitCode === 0);
+    } catch {
+      return Promise.resolve(false);
+    }
+  }
+
+  formatCompletions(completions: ReadonlyArray<CompletionItem>): string {
+    return completions.map((c) => c.value).join("\n");
+  }
+
+  parseCompletionContext(args: ReadonlyArray<string>): CompletionContext {
+    const line = args[0] || "";
+    const cursorPosition = parseInt(args[1] || "0", 10) || line.length;
+    return { line, cursorPosition };
+  }
+}

package/src/service/completion/shell/fish.ts

@@ -0,0 +1,43 @@
+import process from "node:process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { CompletionItem } from "../../../api/service/core/CompletionService.ts";
+import type ShellHandler from "./ShellHandler.ts";
+import type { CompletionContext } from "./ShellHandler.ts";
+
+// Reference: https://fishshell.com/docs/current/completions.html
+
+export default class FishShellHandler implements ShellHandler {
+  getDefaultConfigPath(): string {
+    return join(homedir(), ".config", "fish", "config.fish");
+  }
+
+  getBootstrapScript(cliName: string): string {
+    return `complete -c ${cliName} -f -a '(${cliName} completions:complete fish (commandline -cp) (commandline -C))'`;
+  }
+
+  validateEnvironment(): Promise<boolean> {
+    const shell = process.env.SHELL || "";
+    if (shell.endsWith("/fish")) {
+      return Promise.resolve(true);
+    }
+    try {
+      const result = Bun.spawnSync(["fish", "--version"]);
+      return Promise.resolve(result.exitCode === 0);
+    } catch {
+      return Promise.resolve(false);
+    }
+  }
+
+  formatCompletions(completions: ReadonlyArray<CompletionItem>): string {
+    return completions
+      .map((c) => c.description ? `${c.value}\t${c.description}` : c.value)
+      .join("\n");
+  }
+
+  parseCompletionContext(args: ReadonlyArray<string>): CompletionContext {
+    const line = args[0] || "";
+    const cursorPosition = parseInt(args[1] || "0", 10) || line.length;
+    return { line, cursorPosition };
+  }
+}