@flowscripter/dynamic-cli-framework 1.1.6 → 1.2.1

package/src/service/prompter/DefaultPrompterService.ts

@@ -0,0 +1,87 @@
+import type PrompterService from "../../api/service/core/PrompterService.ts";
+import {
+  type Prompt,
+  type PromptResult,
+  PromptType,
+} from "../../api/service/core/PrompterService.ts";
+import type Terminal from "../../terminal/Terminal.ts";
+import type KeyReader from "../../terminal/KeyReader.ts";
+import type PrinterService from "../../api/service/core/PrinterService.ts";
+import type { PromptContext } from "./prompt/PromptContext.ts";
+import promptSingleSelect from "./prompt/promptSingleSelect.ts";
+import promptMultiSelect from "./prompt/promptMultiSelect.ts";
+import promptAcknowledge from "./prompt/promptAcknowledge.ts";
+import promptToggle from "./prompt/promptToggle.ts";
+import promptText from "./prompt/promptText.ts";
+import promptOpenUrl from "./prompt/promptOpenUrl.ts";
+
+export interface PrompterServiceConfig {
+  readonly inputPromptCharacters: string;
+  readonly checkboxCheckedChars: string;
+  readonly checkboxUncheckedChars: string;
+  readonly scrollVisibleOptions: number;
+  readonly openUrl?: (url: string) => Promise<void>;
+}
+
+export const DEFAULT_PROMPTER_CONFIG: PrompterServiceConfig = {
+  inputPromptCharacters: "> ",
+  checkboxCheckedChars: "[x]",
+  checkboxUncheckedChars: "[ ]",
+  scrollVisibleOptions: 8,
+};
+
+export default class DefaultPrompterService implements PrompterService {
+  promptEnabled = true;
+
+  readonly #ctx: PromptContext;
+
+  public constructor(
+    config: PrompterServiceConfig,
+    terminal: Terminal,
+    keyReader: KeyReader,
+    printerService: PrinterService,
+  ) {
+    this.#ctx = { config, terminal, keyReader, printerService };
+  }
+
+  prompt(promptDef: Prompt): Promise<PromptResult> {
+    if (!this.promptEnabled) {
+      if (promptDef.defaultOption) {
+        return Promise.resolve({
+          name: promptDef.name,
+          value: promptDef.defaultOption.returnedValue,
+        });
+      }
+      return Promise.reject(
+        new Error(
+          `Prompting is disabled and no default for prompt: ${promptDef.name}`,
+        ),
+      );
+    }
+
+    switch (promptDef.type) {
+      case PromptType.SINGLE_SELECT:
+        return promptSingleSelect(this.#ctx, promptDef);
+      case PromptType.MULTI_SELECT:
+        return promptMultiSelect(this.#ctx, promptDef);
+      case PromptType.ACKNOWLEDGE:
+        return promptAcknowledge(this.#ctx, promptDef);
+      case PromptType.TOGGLE:
+        return promptToggle(this.#ctx, promptDef);
+      case PromptType.TEXT:
+        return promptText(this.#ctx, promptDef);
+      case PromptType.OPEN_URL:
+        return promptOpenUrl(this.#ctx, promptDef);
+    }
+  }
+
+  async promptAll(
+    prompts: ReadonlyArray<Prompt>,
+  ): Promise<ReadonlyArray<PromptResult>> {
+    const results: PromptResult[] = [];
+    for (const p of prompts) {
+      results.push(await this.prompt(p));
+    }
+    return results;
+  }
+}

package/src/service/prompter/PrompterServiceProvider.ts

@@ -0,0 +1,36 @@
+import type Context from "../../api/Context.ts";
+import type {
+  ServiceInfo,
+  ServiceProvider,
+} from "../../api/service/ServiceProvider.ts";
+import type PrompterService from "../../api/service/core/PrompterService.ts";
+import { PROMPTER_SERVICE_ID } from "../../api/service/core/PrompterService.ts";
+import NoPromptCommand from "./command/NoPromptCommand.ts";
+import type CLIConfig from "../../api/CLIConfig.ts";
+
+export default class PrompterServiceProvider implements ServiceProvider {
+  readonly serviceId: string = PROMPTER_SERVICE_ID;
+  readonly servicePriority: number;
+  readonly prompterService: PrompterService;
+
+  public constructor(
+    servicePriority: number,
+    prompterService: PrompterService,
+  ) {
+    this.servicePriority = servicePriority;
+    this.prompterService = prompterService;
+  }
+
+  public getServiceInfo(_cliConfig: CLIConfig): Promise<ServiceInfo> {
+    return Promise.resolve({
+      service: this.prompterService,
+      commands: [
+        new NoPromptCommand(this, this.servicePriority),
+      ],
+    });
+  }
+
+  initService(_context: Context): Promise<void> {
+    return Promise.resolve();
+  }
+}

package/src/service/prompter/command/NoPromptCommand.ts

@@ -0,0 +1,40 @@
+import type GlobalModifierCommand from "../../../api/command/GlobalModifierCommand.ts";
+import type GlobalCommandArgument from "../../../api/argument/GlobalCommandArgument.ts";
+import {
+  type ArgumentSingleValueType,
+  ArgumentValueTypeName,
+} from "../../../api/argument/ArgumentValueTypes.ts";
+import type Context from "../../../api/Context.ts";
+import type PrompterServiceProvider from "../PrompterServiceProvider.ts";
+
+export default class NoPromptCommand implements GlobalModifierCommand {
+  readonly name = "no-prompt";
+  readonly description = "Disable interactive prompting";
+  readonly enableConfiguration = true;
+  readonly argument: GlobalCommandArgument = {
+    type: ArgumentValueTypeName.BOOLEAN,
+    defaultValue: false,
+    configurationKey: "NO_PROMPT",
+  };
+  readonly executePriority: number;
+
+  readonly #prompterServiceProvider: PrompterServiceProvider;
+
+  public constructor(
+    prompterServiceProvider: PrompterServiceProvider,
+    executePriority: number,
+  ) {
+    this.#prompterServiceProvider = prompterServiceProvider;
+    this.executePriority = executePriority;
+  }
+
+  public execute(
+    _context: Context,
+    argumentValue: ArgumentSingleValueType,
+  ): Promise<void> {
+    this.#prompterServiceProvider.prompterService.promptEnabled =
+      !(argumentValue as boolean);
+
+    return Promise.resolve();
+  }
+}

package/src/service/prompter/prompt/PromptContext.ts

@@ -0,0 +1,47 @@
+import type { Prompt } from "../../../api/service/core/PrompterService.ts";
+import type Terminal from "../../../terminal/Terminal.ts";
+import type KeyReader from "../../../terminal/KeyReader.ts";
+import type PrinterService from "../../../api/service/core/PrinterService.ts";
+import type { PrompterServiceConfig } from "../DefaultPrompterService.ts";
+
+export interface PromptContext {
+  readonly config: PrompterServiceConfig;
+  readonly terminal: Terminal;
+  readonly keyReader: KeyReader;
+  readonly printerService: PrinterService;
+}
+
+export function physicalLineCount(
+  terminal: Terminal,
+  text: string,
+): number {
+  const cols = terminal.columns();
+  if (cols <= 0) return 1;
+  const width = Bun.stringWidth(text);
+  return Math.max(1, Math.ceil(width / cols));
+}
+
+export function headerLineCount(
+  terminal: Terminal,
+  promptDef: Prompt,
+): number {
+  let count = physicalLineCount(terminal, promptDef.promptText);
+  if (promptDef.description) {
+    count += physicalLineCount(terminal, promptDef.description);
+  }
+  return count;
+}
+
+export async function renderPromptHeader(
+  ctx: PromptContext,
+  promptDef: Prompt,
+): Promise<void> {
+  await ctx.terminal.write(
+    `${ctx.printerService.emphasised(promptDef.promptText)}\n`,
+  );
+  if (promptDef.description) {
+    await ctx.terminal.write(
+      `${ctx.printerService.secondary(promptDef.description)}\n`,
+    );
+  }
+}

package/src/service/prompter/prompt/promptAcknowledge.ts

@@ -0,0 +1,28 @@
+import {
+  type Prompt,
+  type PromptResult,
+  PromptType,
+} from "../../../api/service/core/PrompterService.ts";
+import type { PromptContext } from "./PromptContext.ts";
+import promptSingleSelect from "./promptSingleSelect.ts";
+
+export default function promptAcknowledge(
+  ctx: PromptContext,
+  promptDef: Prompt,
+): Promise<PromptResult> {
+  const yesNo: Prompt = {
+    name: promptDef.name,
+    promptText: promptDef.promptText,
+    description: promptDef.description,
+    type: PromptType.SINGLE_SELECT,
+    defaultOption: promptDef.defaultOption ?? {
+      displayValue: "No",
+      returnedValue: false,
+    },
+    options: [
+      { displayValue: "Yes", returnedValue: true },
+      { displayValue: "No", returnedValue: false },
+    ],
+  };
+  return promptSingleSelect(ctx, yesNo);
+}

package/src/service/prompter/prompt/promptMultiSelect.ts

@@ -0,0 +1,99 @@
+import type {
+  Prompt,
+  PromptResult,
+} from "../../../api/service/core/PrompterService.ts";
+import { SpecialKey } from "../../../terminal/KeyReader.ts";
+import ShutdownServiceProvider from "../../shutdown/ShutdownServiceProvider.ts";
+import { headerLineCount, renderPromptHeader } from "./PromptContext.ts";
+import type { PromptContext } from "./PromptContext.ts";
+
+export default async function promptMultiSelect(
+  ctx: PromptContext,
+  promptDef: Prompt,
+): Promise<PromptResult> {
+  const options = promptDef.options;
+  if (options.length === 0) {
+    throw new Error(`No options for prompt: ${promptDef.name}`);
+  }
+
+  let focusIndex = 0;
+  const checked = new Set<number>();
+  let scrollOffset = 0;
+  const visibleCount = Math.min(
+    ctx.config.scrollVisibleOptions,
+    options.length,
+  );
+
+  ctx.keyReader.enableRawMode();
+  try {
+    await ctx.terminal.hideCursor();
+    let firstRender = true;
+
+    while (true) {
+      if (scrollOffset > focusIndex) {
+        scrollOffset = focusIndex;
+      } else if (focusIndex >= scrollOffset + visibleCount) {
+        scrollOffset = focusIndex - visibleCount + 1;
+      }
+
+      const headerLines = headerLineCount(ctx.terminal, promptDef);
+
+      if (!firstRender) {
+        await ctx.terminal.clearUpLines(visibleCount + headerLines);
+      }
+      firstRender = false;
+
+      await renderPromptHeader(ctx, promptDef);
+
+      for (let i = scrollOffset; i < scrollOffset + visibleCount; i++) {
+        const option = options[i]!;
+        const isFocused = i === focusIndex;
+        const isChecked = checked.has(i);
+        const checkbox = isChecked
+          ? ctx.printerService.green(ctx.config.checkboxCheckedChars)
+          : ctx.printerService.secondary(
+            ctx.config.checkboxUncheckedChars,
+          );
+        const text = option.displayValue;
+        await ctx.terminal.write(
+          `${checkbox} ${
+            isFocused
+              ? ctx.printerService.cyan(text)
+              : ctx.printerService.secondary(text)
+          }\n`,
+        );
+      }
+
+      const keyEvent = await ctx.keyReader.readKey();
+      if (keyEvent.specialKey === SpecialKey.UP && focusIndex > 0) {
+        focusIndex--;
+      } else if (
+        keyEvent.specialKey === SpecialKey.DOWN &&
+        focusIndex < options.length - 1
+      ) {
+        focusIndex++;
+      } else if (keyEvent.specialKey === SpecialKey.SPACE) {
+        if (checked.has(focusIndex)) {
+          checked.delete(focusIndex);
+        } else {
+          checked.add(focusIndex);
+        }
+      } else if (keyEvent.specialKey === SpecialKey.ENTER) {
+        await ctx.terminal.showCursor();
+        const values = [...checked].sort().map(
+          (i) => options[i]!.returnedValue,
+        );
+        return { name: promptDef.name, value: values };
+      } else if (keyEvent.specialKey === SpecialKey.ESCAPE) {
+        await ctx.terminal.showCursor();
+        throw new Error("Prompt cancelled");
+      } else if (keyEvent.specialKey === SpecialKey.INTERRUPT) {
+        await ctx.terminal.showCursor();
+        ShutdownServiceProvider.onInterrupt();
+        throw new Error("Interrupted");
+      }
+    }
+  } finally {
+    ctx.keyReader.disableRawMode();
+  }
+}

package/src/service/prompter/prompt/promptOpenUrl.ts

@@ -0,0 +1,97 @@
+import type {
+  Prompt,
+  PromptResult,
+} from "../../../api/service/core/PrompterService.ts";
+import { SpecialKey } from "../../../terminal/KeyReader.ts";
+import ShutdownServiceProvider from "../../shutdown/ShutdownServiceProvider.ts";
+import { renderPromptHeader } from "./PromptContext.ts";
+import type { PromptContext } from "./PromptContext.ts";
+
+function isRemoteSession(): boolean {
+  return !!(
+    process.env.SSH_CONNECTION ||
+    process.env.SSH_CLIENT ||
+    process.env.SSH_TTY
+  );
+}
+
+async function defaultOpenUrl(url: string): Promise<void> {
+  const parsed = new URL(url);
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`Unsupported URL protocol: ${parsed.protocol}`);
+  }
+  const platform = process.platform;
+  let cmd: string[];
+  if (platform === "darwin") {
+    cmd = ["open", url];
+  } else if (platform === "win32") {
+    cmd = ["cmd", "/c", "start", "", url];
+  } else {
+    cmd = ["xdg-open", url];
+  }
+  const proc = Bun.spawn(cmd, { stdout: "ignore", stderr: "ignore" });
+  const exitCode = await proc.exited;
+  if (exitCode !== 0) {
+    throw new Error(`Failed to open URL (exit code ${exitCode})`);
+  }
+}
+
+export default async function promptOpenUrl(
+  ctx: PromptContext,
+  promptDef: Prompt,
+): Promise<PromptResult> {
+  if (promptDef.options.length === 0) {
+    throw new Error(`No URL option for prompt: ${promptDef.name}`);
+  }
+
+  const url = String(promptDef.options[0]!.returnedValue);
+  const displayLabel = promptDef.options[0]!.displayValue;
+  const openUrlFn = ctx.config.openUrl ?? defaultOpenUrl;
+  const canOpenBrowser = !isRemoteSession();
+
+  ctx.keyReader.enableRawMode();
+  try {
+    await renderPromptHeader(ctx, promptDef);
+
+    await ctx.terminal.write(
+      `${displayLabel}: ${ctx.printerService.cyan(url)}\n`,
+    );
+
+    const instruction = canOpenBrowser
+      ? "Press ENTER to open in the browser..."
+      : "Copy the URL above and open it in your local browser, then press ENTER to continue...";
+    await ctx.terminal.write(
+      `${ctx.printerService.secondary(instruction)}\n`,
+    );
+
+    while (true) {
+      const keyEvent = await ctx.keyReader.readKey();
+
+      if (keyEvent.specialKey === SpecialKey.ENTER) {
+        if (canOpenBrowser) {
+          try {
+            await openUrlFn(url);
+          } catch (e) {
+            await ctx.terminal.write(
+              `${
+                ctx.printerService.red(
+                  `Failed to open URL: ${
+                    e instanceof Error ? e.message : String(e)
+                  }`,
+                )
+              }\n`,
+            );
+          }
+        }
+        return { name: promptDef.name, value: url };
+      } else if (keyEvent.specialKey === SpecialKey.ESCAPE) {
+        throw new Error("Prompt cancelled");
+      } else if (keyEvent.specialKey === SpecialKey.INTERRUPT) {
+        ShutdownServiceProvider.onInterrupt();
+        throw new Error("Interrupted");
+      }
+    }
+  } finally {
+    ctx.keyReader.disableRawMode();
+  }
+}

package/src/service/prompter/prompt/promptSingleSelect.ts

@@ -0,0 +1,102 @@
+import type {
+  Prompt,
+  PromptResult,
+} from "../../../api/service/core/PrompterService.ts";
+import { SpecialKey } from "../../../terminal/KeyReader.ts";
+import ShutdownServiceProvider from "../../shutdown/ShutdownServiceProvider.ts";
+import { headerLineCount, renderPromptHeader } from "./PromptContext.ts";
+import type { PromptContext } from "./PromptContext.ts";
+
+export default async function promptSingleSelect(
+  ctx: PromptContext,
+  promptDef: Prompt,
+): Promise<PromptResult> {
+  const options = promptDef.options;
+  if (options.length === 0) {
+    throw new Error(`No options for prompt: ${promptDef.name}`);
+  }
+
+  let selectedIndex = 0;
+  if (promptDef.defaultOption) {
+    const idx = options.findIndex(
+      (o) => o.returnedValue === promptDef.defaultOption!.returnedValue,
+    );
+    if (idx >= 0) selectedIndex = idx;
+  }
+
+  let scrollOffset = 0;
+  const visibleCount = Math.min(
+    ctx.config.scrollVisibleOptions,
+    options.length,
+  );
+
+  ctx.keyReader.enableRawMode();
+  try {
+    await ctx.terminal.hideCursor();
+    let firstRender = true;
+
+    while (true) {
+      if (scrollOffset > selectedIndex) {
+        scrollOffset = selectedIndex;
+      } else if (selectedIndex >= scrollOffset + visibleCount) {
+        scrollOffset = selectedIndex - visibleCount + 1;
+      }
+
+      const headerLines = headerLineCount(ctx.terminal, promptDef);
+
+      if (!firstRender) {
+        await ctx.terminal.clearUpLines(visibleCount + headerLines);
+      }
+      firstRender = false;
+
+      await renderPromptHeader(ctx, promptDef);
+
+      for (let i = scrollOffset; i < scrollOffset + visibleCount; i++) {
+        const option = options[i]!;
+        const isSelected = i === selectedIndex;
+        const prefix = isSelected ? ctx.config.inputPromptCharacters : "  ";
+        const text = prefix + option.displayValue;
+        await ctx.terminal.write(
+          `${
+            isSelected
+              ? ctx.printerService.cyan(text)
+              : ctx.printerService.secondary(text)
+          }\n`,
+        );
+      }
+
+      const keyEvent = await ctx.keyReader.readKey();
+      if (keyEvent.specialKey === SpecialKey.UP && selectedIndex > 0) {
+        selectedIndex--;
+      } else if (
+        keyEvent.specialKey === SpecialKey.DOWN &&
+        selectedIndex < options.length - 1
+      ) {
+        selectedIndex++;
+      } else if (keyEvent.specialKey === SpecialKey.ENTER) {
+        await ctx.terminal.showCursor();
+        const option = options[selectedIndex]!;
+        const validationError = option.validate
+          ? option.validate(option.returnedValue)
+          : undefined;
+        if (validationError) {
+          await ctx.terminal.write(
+            `${ctx.printerService.red(validationError)}\n`,
+          );
+          firstRender = true;
+          continue;
+        }
+        return { name: promptDef.name, value: option.returnedValue };
+      } else if (keyEvent.specialKey === SpecialKey.ESCAPE) {
+        await ctx.terminal.showCursor();
+        throw new Error("Prompt cancelled");
+      } else if (keyEvent.specialKey === SpecialKey.INTERRUPT) {
+        await ctx.terminal.showCursor();
+        ShutdownServiceProvider.onInterrupt();
+        throw new Error("Interrupted");
+      }
+    }
+  } finally {
+    ctx.keyReader.disableRawMode();
+  }
+}

package/src/service/prompter/prompt/promptText.ts

@@ -0,0 +1,107 @@
+import type {
+  Prompt,
+  PromptResult,
+} from "../../../api/service/core/PrompterService.ts";
+import type { ArgumentSingleValueType } from "../../../api/argument/ArgumentValueTypes.ts";
+import { SpecialKey } from "../../../terminal/KeyReader.ts";
+import ShutdownServiceProvider from "../../shutdown/ShutdownServiceProvider.ts";
+import { renderPromptHeader } from "./PromptContext.ts";
+import type { PromptContext } from "./PromptContext.ts";
+
+export default async function promptText(
+  ctx: PromptContext,
+  promptDef: Prompt,
+): Promise<PromptResult> {
+  ctx.keyReader.enableRawMode();
+  try {
+    while (true) {
+      await renderPromptHeader(ctx, promptDef);
+      const promptMarker = ctx.printerService.cyan(
+        ctx.config.inputPromptCharacters,
+      );
+      await ctx.terminal.write(promptMarker);
+
+      let buffer = promptDef.defaultOption
+        ? String(promptDef.defaultOption.returnedValue)
+        : "";
+      if (buffer.length > 0) {
+        await ctx.terminal.write(buffer);
+      }
+
+      while (true) {
+        const keyEvent = await ctx.keyReader.readKey();
+
+        if (keyEvent.specialKey === SpecialKey.ENTER) {
+          await ctx.terminal.write("\n");
+          break;
+        } else if (keyEvent.specialKey === SpecialKey.ESCAPE) {
+          await ctx.terminal.write("\n");
+          throw new Error("Prompt cancelled");
+        } else if (keyEvent.specialKey === SpecialKey.INTERRUPT) {
+          await ctx.terminal.write("\n");
+          ShutdownServiceProvider.onInterrupt();
+          throw new Error("Interrupted");
+        } else if (keyEvent.specialKey === SpecialKey.BACKSPACE) {
+          if (buffer.length > 0) {
+            buffer = buffer.slice(0, -1);
+            await ctx.terminal.write("\b \b");
+          }
+        } else if (keyEvent.key) {
+          buffer += keyEvent.key;
+          const isSecret = promptDef.options.length > 0 &&
+            promptDef.options[0]!.displayValue === "__SECRET__";
+          await ctx.terminal.write(isSecret ? "*" : keyEvent.key);
+        }
+      }
+
+      if (buffer.length === 0 && !promptDef.defaultOption) {
+        await ctx.terminal.write(
+          ctx.printerService.red("Value required\n"),
+        );
+        continue;
+      }
+
+      const value: ArgumentSingleValueType = buffer;
+
+      const validationOption = promptDef.options.length > 0
+        ? promptDef.options[0]
+        : undefined;
+      if (validationOption?.validate) {
+        const error = validationOption.validate(value);
+        if (error) {
+          await ctx.terminal.write(
+            `${ctx.printerService.red(error)}\n`,
+          );
+          continue;
+        }
+      }
+
+      if (validationOption?.min !== undefined && typeof value === "string") {
+        const num = Number(value);
+        if (!isNaN(num) && num < validationOption.min) {
+          await ctx.terminal.write(
+            ctx.printerService.red(
+              `Value must be at least ${validationOption.min}\n`,
+            ),
+          );
+          continue;
+        }
+      }
+      if (validationOption?.max !== undefined && typeof value === "string") {
+        const num = Number(value);
+        if (!isNaN(num) && num > validationOption.max) {
+          await ctx.terminal.write(
+            ctx.printerService.red(
+              `Value must be at most ${validationOption.max}\n`,
+            ),
+          );
+          continue;
+        }
+      }
+
+      return { name: promptDef.name, value };
+    }
+  } finally {
+    ctx.keyReader.disableRawMode();
+  }
+}

package/src/service/prompter/prompt/promptToggle.ts

@@ -0,0 +1,28 @@
+import {
+  type Prompt,
+  type PromptResult,
+  PromptType,
+} from "../../../api/service/core/PrompterService.ts";
+import type { PromptContext } from "./PromptContext.ts";
+import promptSingleSelect from "./promptSingleSelect.ts";
+
+export default function promptToggle(
+  ctx: PromptContext,
+  promptDef: Prompt,
+): Promise<PromptResult> {
+  const trueFalse: Prompt = {
+    name: promptDef.name,
+    promptText: promptDef.promptText,
+    description: promptDef.description,
+    type: PromptType.SINGLE_SELECT,
+    defaultOption: promptDef.defaultOption ?? {
+      displayValue: "False",
+      returnedValue: false,
+    },
+    options: promptDef.options.length > 0 ? promptDef.options : [
+      { displayValue: "True", returnedValue: true },
+      { displayValue: "False", returnedValue: false },
+    ],
+  };
+  return promptSingleSelect(ctx, trueFalse);
+}