@tsed/cli-prompts 7.0.0-beta.11

package/src/fn/password.ts

@@ -0,0 +1,13 @@
+import {password as clackPassword} from "@clack/prompts";
+
+import type {NormalizedPromptQuestion} from "../interfaces/NormalizedPromptQuestion.js";
+import {processPrompt} from "../utils/processPrompt.js";
+
+export async function password(question: NormalizedPromptQuestion, answers: Record<string, unknown>) {
+  return processPrompt(question, answers, () =>
+    clackPassword({
+      message: question.message,
+      mask: question.mask === false ? undefined : String(question.mask || "•")
+    })
+  );
+}

package/src/fn/prompts.spec.ts

@@ -0,0 +1,175 @@
+import {normalizeChoices} from "../utils/normalizeChoices.js";
+import {autocomplete} from "./autocomplete.js";
+import {checkbox} from "./checkbox.js";
+import {confirm} from "./confirm.js";
+import {input} from "./input.js";
+import {list} from "./list.js";
+import {password} from "./password.js";
+
+const SEARCH_ACTION = "__tsed_cli_search_again__";
+
+const clack = vi.hoisted(() => ({
+  text: vi.fn(),
+  select: vi.fn(),
+  multiselect: vi.fn(),
+  confirm: vi.fn(),
+  password: vi.fn(),
+  note: vi.fn(),
+  isCancel: vi.fn().mockReturnValue(false),
+  cancel: vi.fn()
+}));
+
+vi.mock("@clack/prompts", () => clack);
+
+describe("prompt handlers", () => {
+  beforeEach(() => {
+    clack.text.mockReset();
+    clack.select.mockReset();
+    clack.multiselect.mockReset();
+    clack.confirm.mockReset();
+    clack.password.mockReset();
+    clack.note.mockReset();
+    clack.isCancel.mockReset().mockReturnValue(false);
+    clack.cancel.mockReset();
+  });
+
+  it("input should resolve responses from clack text prompt", async () => {
+    clack.text.mockResolvedValue("Jane Doe");
+
+    const result = await input(
+      {
+        type: "input",
+        name: "fullName",
+        message: "Your name?",
+        default: "John"
+      },
+      {}
+    );
+
+    expect(clack.text).toHaveBeenCalledWith({message: "Your name?", initialValue: "John"});
+    expect(result).toBe("Jane Doe");
+  });
+
+  it("password should mask the prompt by default", async () => {
+    clack.password.mockResolvedValue("secret");
+
+    const result = await password(
+      {
+        type: "password",
+        name: "token",
+        message: "Token?"
+      },
+      {}
+    );
+
+    expect(clack.password).toHaveBeenCalledWith({message: "Token?", mask: "•"});
+    expect(result).toBe("secret");
+  });
+
+  it("confirm should pass boolean default as initialValue", async () => {
+    clack.confirm.mockResolvedValue(true);
+
+    const result = await confirm(
+      {
+        type: "confirm",
+        name: "proceed",
+        message: "Continue?",
+        default: false
+      },
+      {}
+    );
+
+    expect(clack.confirm).toHaveBeenCalledWith({message: "Continue?", initialValue: false});
+    expect(result).toBe(true);
+  });
+
+  it("list should render normalized choices and return selection", async () => {
+    clack.select.mockResolvedValue("b");
+    const choices = normalizeChoices(["a", "b"]);
+
+    const result = await list(
+      {
+        type: "list",
+        name: "choice",
+        message: "Pick",
+        choices
+      },
+      {}
+    );
+
+    expect(clack.select).toHaveBeenCalledWith({
+      message: "Pick",
+      options: choices.map((choice) => ({label: choice.label, value: choice.value, hint: choice.hint})),
+      initialValue: "a",
+      maxItems: undefined
+    });
+    expect(result).toBe("b");
+  });
+
+  it("checkbox should respect default values", async () => {
+    clack.multiselect.mockResolvedValue(["two"]);
+
+    const result = await checkbox(
+      {
+        type: "checkbox",
+        name: "features",
+        message: "Select",
+        choices: [
+          {label: "One", value: "one"},
+          {label: "Two", value: "two", checked: true}
+        ],
+        default: ["two"]
+      },
+      {}
+    );
+
+    expect(clack.multiselect).toHaveBeenCalledWith({
+      message: "Select",
+      options: [
+        {label: "One", value: "one", hint: undefined},
+        {label: "Two", value: "two", hint: undefined}
+      ],
+      initialValues: ["two"]
+    });
+    expect(result).toEqual(["two"]);
+  });
+
+  it("list should throw when no choices are provided", async () => {
+    await expect(
+      list(
+        {
+          type: "list",
+          name: "empty",
+          message: "Empty",
+          choices: []
+        },
+        {}
+      )
+    ).rejects.toThrow('Question "empty" does not provide any choices');
+  });
+
+  it("autocomplete should support search flow and selection", async () => {
+    clack.select.mockResolvedValueOnce(SEARCH_ACTION).mockResolvedValueOnce("beta");
+    clack.text.mockResolvedValueOnce("b");
+
+    const result = await autocomplete(
+      {
+        type: "autocomplete",
+        name: "plugin",
+        message: "Plugin?",
+        pageSize: 5,
+        source: (answers, keyword = "") => {
+          expect(answers).toHaveProperty("prefilled", true);
+          return Promise.resolve(["alpha", "beta"].filter((entry) => entry.includes(keyword)));
+        }
+      },
+      {prefilled: true}
+    );
+
+    expect(clack.text).toHaveBeenCalledWith({
+      message: "Plugin? (no matches, type to search)",
+      initialValue: ""
+    });
+    expect(result).toBe("beta");
+  });
+});

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./errors/PromptCancelledError.js";
+export * from "./interfaces/PromptQuestion.js";
+export * from "./PromptRunner.js";

package/src/interfaces/NormalizedPromptQuestion.ts

@@ -0,0 +1,10 @@
+import type {NormalizedChoice} from "../utils/normalizeChoices.js";
+import type {PromptAutocompleteQuestion, PromptQuestion} from "./PromptQuestion.js";
+
+export type NormalizedPromptQuestion = PromptQuestion & {
+  message: string;
+  choices?: NormalizedChoice[];
+  source?: PromptAutocompleteQuestion["source"];
+  default?: unknown;
+  mask?: string | boolean;
+};

package/src/interfaces/PromptQuestion.ts

@@ -0,0 +1,172 @@
+type MaybePromise<T> = T | Promise<T>;
+
+/**
+ * Enumerates the built-in prompt types supported by the Ts.ED CLI.
+ */
+export type PromptType = "input" | "password" | "confirm" | "list" | "checkbox" | "autocomplete";
+
+/**
+ * Represents a single choice entry usable by select, checkbox, and autocomplete prompts.
+ */
+export interface PromptChoice<Value = any> {
+  /**
+   * Human friendly label displayed in the prompt list.
+   */
+  name?: string;
+  /**
+   * Raw value returned when the choice is selected.
+   */
+  value?: Value;
+  /**
+   * Optional short label shown beside the main choice name.
+   */
+  short?: string;
+  /**
+   * Marks the choice as disabled (boolean or reason string).
+   */
+  disabled?: boolean | string;
+  /**
+   * For checkbox prompts, marks the choice as checked by default.
+   */
+  checked?: boolean;
+}
+
+/**
+ * Choice definition accepted by prompts. A plain value will be coerced to a `PromptChoice`.
+ */
+export type PromptChoiceInput<Value = any> = PromptChoice<Value> | Value;
+
+/**
+ * Transforms user input before it becomes part of the command context.
+ */
+export type PromptTransformer = (input: any, answers: Record<string, any>, flags?: {isFinal?: boolean}) => any;
+
+/**
+ * Validates the user input, returning `true`, `false`, or an error string.
+ */
+export type PromptValidator = (input: any, answers: Record<string, any>) => MaybePromise<boolean | string>;
+
+/**
+ * Filters the answer into a different representation before persistence.
+ */
+export type PromptFilter = (input: any, answers: Record<string, any>) => MaybePromise<any>;
+
+/**
+ * Determines whether a prompt should run.
+ */
+export type PromptWhen = boolean | ((answers: Record<string, any>) => MaybePromise<boolean>);
+
+/**
+ * Base contract shared by every question type.
+ */
+export interface PromptBaseQuestion<Value = any> {
+  /**
+   * Prompt type to render.
+   */
+  type: PromptType;
+  /**
+   * Unique answer key assigned to the prompt.
+   */
+  name: string;
+  /**
+   * Prompt label. Accepts a string or function (resolved at runtime).
+   */
+  message: string | ((answers: Record<string, any>) => MaybePromise<string>);
+  /**
+   * Allows skipping the prompt based on previous answers.
+   */
+  when?: PromptWhen;
+  /**
+   * Default input value or factory function returning one.
+   */
+  default?: Value | ((answers: Record<string, any>) => MaybePromise<Value>);
+  /**
+   * Mutates the visual input while the user types.
+   */
+  transformer?: PromptTransformer;
+  /**
+   * Validates user input. Return `false`/string to display an error.
+   */
+  validate?: PromptValidator;
+  /**
+   * Mutates the stored answer after validation.
+   */
+  filter?: PromptFilter;
+  /**
+   * Optional max number of rows visible in select/checkbox prompts.
+   */
+  pageSize?: number;
+  /**
+   * Whether select prompts loop when reaching boundaries.
+   */
+  loop?: boolean;
+}
+
+/**
+ * Plain text prompt.
+ */
+export interface PromptInputQuestion extends PromptBaseQuestion<string> {
+  type: "input";
+}
+
+/**
+ * Hidden text prompt (e.g., passwords or tokens).
+ */
+export interface PromptPasswordQuestion extends PromptBaseQuestion<string> {
+  type: "password";
+  /**
+   * Character used to mask input (default: •). Set `false` to show raw input.
+   */
+  mask?: string | boolean;
+}
+
+/**
+ * Boolean confirmation prompt (yes/no).
+ */
+export interface PromptConfirmQuestion extends PromptBaseQuestion<boolean> {
+  type: "confirm";
+}
+
+/**
+ * Single-select prompt with predefined choices.
+ */
+export interface PromptListQuestion extends PromptBaseQuestion<any> {
+  type: "list";
+  /**
+   * Available choices displayed to the user.
+   */
+  choices: PromptChoiceInput[];
+}
+
+/**
+ * Multi-select prompt where the result is an array of chosen values.
+ */
+export interface PromptCheckboxQuestion extends PromptBaseQuestion<any[]> {
+  type: "checkbox";
+  /**
+   * Available choices displayed to the user.
+   */
+  choices: PromptChoiceInput[];
+}
+
+/**
+ * Searchable prompt that fetches choices dynamically.
+ */
+export interface PromptAutocompleteQuestion extends PromptBaseQuestion<any> {
+  type: "autocomplete";
+  /**
+   * Async loader returning the set of choices filtered by the keyword.
+   */
+  source: (answers: Record<string, any>, keyword?: string) => MaybePromise<PromptChoiceInput[]>;
+}
+
+/**
+ * Union describing every supported Ts.ED CLI question type.
+ */
+export type PromptQuestion =
+  | PromptInputQuestion
+  | PromptPasswordQuestion
+  | PromptConfirmQuestion
+  | PromptListQuestion
+  | PromptCheckboxQuestion
+  | PromptAutocompleteQuestion;

package/src/utils/applyTransforms.ts

@@ -0,0 +1,15 @@
+import type {PromptQuestion} from "../interfaces/PromptQuestion.js";
+
+export async function applyTransforms(question: PromptQuestion, answers: Record<string, any>, value: unknown) {
+  let next = value;
+
+  if (question.transformer) {
+    next = await question.transformer(next, answers, {isFinal: true});
+  }
+
+  if (question.filter) {
+    next = await question.filter(next, answers);
+  }
+
+  return next;
+}

package/src/utils/ensureNotCancelled.ts

@@ -0,0 +1,12 @@
+import {cancel as cancelPrompt, isCancel} from "@clack/prompts";
+
+import {PromptCancelledError} from "../errors/PromptCancelledError.js";
+
+export function ensureNotCancelled<T>(value: T | symbol): T {
+  if (isCancel(value)) {
+    cancelPrompt();
+    throw new PromptCancelledError();
+  }
+
+  return value;
+}

package/src/utils/getValidationError.ts

@@ -0,0 +1,21 @@
+import {isString} from "@tsed/core";
+
+import type {PromptQuestion} from "../interfaces/PromptQuestion.js";
+
+export async function getValidationError(question: PromptQuestion, answers: Record<string, unknown>, value: unknown) {
+  if (!question.validate) {
+    return undefined;
+  }
+
+  const result = await question.validate(value, answers);
+
+  if (result === false) {
+    return "Invalid value.";
+  }
+
+  if (isString(result)) {
+    return result;
+  }
+
+  return undefined;
+}

package/src/utils/normalizeChoices.ts

@@ -0,0 +1,28 @@
+import type {PromptChoiceInput} from "../interfaces/PromptQuestion.js";
+
+export type NormalizedChoice = {
+  label: string;
+  value: any;
+  hint?: string;
+  checked?: boolean;
+};
+
+export function normalizeChoices(inputs: PromptChoiceInput[] = []): NormalizedChoice[] {
+  return inputs.map((choice) => {
+    if (typeof choice === "object" && choice !== null && "value" in choice) {
+      const resolvedValue = choice.value ?? choice.name;
+
+      return {
+        label: choice.name ?? String(resolvedValue ?? ""),
+        value: resolvedValue,
+        hint: choice.short,
+        checked: choice.checked
+      };
+    }
+
+    return {
+      label: String(choice),
+      value: choice
+    };
+  });
+}

package/src/utils/normalizeQuestion.ts

@@ -0,0 +1,31 @@
+import type {NormalizedPromptQuestion} from "../interfaces/NormalizedPromptQuestion.js";
+import type {PromptQuestion} from "../interfaces/PromptQuestion.js";
+import {normalizeChoices} from "./normalizeChoices.js";
+import {resolveMaybe} from "./resolveMaybe.js";
+
+export async function normalizeQuestion(question: PromptQuestion, answers: Record<string, unknown>) {
+  const normalized: NormalizedPromptQuestion = {
+    ...(question as any),
+    name: question.name,
+    type: question.type,
+    message: await resolveMaybe(question.message, answers)
+  };
+
+  if ("default" in question && question.default !== undefined) {
+    normalized.default = await resolveMaybe(question.default, answers);
+  }
+
+  if ("choices" in question && question.choices?.length) {
+    normalized.choices = normalizeChoices([...question.choices]);
+  }
+
+  if ("source" in question && question.source) {
+    const source = question.source;
+
+    normalized.source = (state: Record<string, any>, keyword?: string) => {
+      return source({...answers, ...state}, keyword);
+    };
+  }
+
+  return normalized;
+}

package/src/utils/processPrompt.ts

@@ -0,0 +1,29 @@
+import {note} from "@clack/prompts";
+
+import type {PromptQuestion} from "../interfaces/PromptQuestion.js";
+import {applyTransforms} from "./applyTransforms.js";
+import {ensureNotCancelled} from "./ensureNotCancelled.js";
+import {getValidationError} from "./getValidationError.js";
+
+export const CONTINUE = Symbol.for("prompt:continue");
+type PromptExecutor = () => Promise<unknown> | unknown;
+
+export async function processPrompt(question: PromptQuestion, answers: Record<string, unknown>, cb: PromptExecutor) {
+  while (true) {
+    const result = await cb();
+
+    if (result === CONTINUE) {
+      continue;
+    }
+
+    const value = ensureNotCancelled(result);
+    const transformed = await applyTransforms(question, answers, value);
+    const error = await getValidationError(question, answers, transformed);
+
+    if (!error) {
+      return transformed;
+    }
+
+    note(error, "Validation error");
+  }
+}

package/src/utils/resolveListDefault.ts

@@ -0,0 +1,22 @@
+import type {PromptAutocompleteQuestion, PromptListQuestion} from "../interfaces/PromptQuestion.js";
+import type {NormalizedChoice} from "./normalizeChoices.js";
+
+export function resolveListDefault(
+  question: Pick<PromptListQuestion | PromptAutocompleteQuestion, "default">,
+  choices: NormalizedChoice[]
+) {
+  if (question.default !== undefined) {
+    if (typeof question.default === "number") {
+      return choices[question.default]?.value ?? choices[0]?.value;
+    }
+
+    return question.default;
+  }
+
+  const checked = choices.find((choice) => choice.checked);
+  if (checked) {
+    return checked.value;
+  }
+
+  return choices[0]?.value;
+}

package/src/utils/resolveMaybe.ts

@@ -0,0 +1,10 @@
+export function resolveMaybe<T>(
+  value: T | ((answers: Record<string, any>) => T | Promise<T>) | undefined,
+  answers: Record<string, any>
+): Promise<T> | T {
+  if (typeof value === "function") {
+    return (value as any)(answers) as Promise<T> | T;
+  }
+
+  return value as T;
+}

package/src/utils/shouldAsk.ts

@@ -0,0 +1,13 @@
+import type {PromptQuestion} from "../interfaces/PromptQuestion.js";
+
+export async function shouldAsk(question: PromptQuestion, answers: Record<string, any>) {
+  if (question.when === undefined) {
+    return true;
+  }
+
+  if (typeof question.when === "function") {
+    return !!(await question.when(answers));
+  }
+
+  return question.when;
+}