Interactive Prompts

/**
 * Creates a text input prompt for single-line text entry
 * @param opts - Configuration options for the text prompt
 * @returns Promise resolving to entered text or cancellation symbol
 */
function text(opts: TextOptions): Promise<string | symbol>;

interface TextOptions {
  /** The prompt message displayed to the user */
  message: string;
  /** Placeholder text shown when input is empty */
  placeholder?: string;
  /** Default value used when user submits without input */
  defaultValue?: string;
  /** Initial value pre-filled in the input */
  initialValue?: string;
  /** Validation function returning error message or undefined for valid input */
  validate?: (value: string) => string | Error | undefined;
}

import { text, isCancel, cancel } from "@clack/prompts";

// Basic text input
const name = await text({
  message: "What's your name?",
});

if (isCancel(name)) {
  cancel("Operation cancelled");
  process.exit(0);
}

// Text input with validation
const email = await text({
  message: "Enter your email address:",
  placeholder: "user@example.com",
  validate: (value) => {
    if (!value.includes("@")) return "Please enter a valid email address";
  }
});

// Text input with default value
const projectName = await text({
  message: "Project name:",
  defaultValue: "my-awesome-project",
  initialValue: "starter-",
});

/**
 * Creates a password input prompt with masked characters
 * @param opts - Configuration options for the password prompt
 * @returns Promise resolving to entered password or cancellation symbol
 */
function password(opts: PasswordOptions): Promise<string | symbol>;

interface PasswordOptions {
  /** The prompt message displayed to the user */
  message: string;
  /** Character used to mask password input (defaults to bullet point) */
  mask?: string;
  /** Validation function returning error message or undefined for valid input */
  validate?: (value: string) => string | Error | undefined;
}

import { password, isCancel, cancel } from "@clack/prompts";

// Basic password input
const userPassword = await password({
  message: "Enter your password:",
});

if (isCancel(userPassword)) {
  cancel("Operation cancelled");
  process.exit(0);
}

// Password with custom mask and validation
const strongPassword = await password({
  message: "Create a strong password:",
  mask: "*",
  validate: (value) => {
    if (value.length < 8) return "Password must be at least 8 characters";
    if (!/[A-Z]/.test(value)) return "Password must contain uppercase letter";
    if (!/[0-9]/.test(value)) return "Password must contain a number";
  }
});

/**
 * Creates a confirmation prompt for yes/no decisions
 * @param opts - Configuration options for the confirmation prompt
 * @returns Promise resolving to boolean choice or cancellation symbol
 */
function confirm(opts: ConfirmOptions): Promise<boolean | symbol>;

interface ConfirmOptions {
  /** The prompt message displayed to the user */
  message: string;
  /** Text displayed for the "yes" option (defaults to "Yes") */
  active?: string;
  /** Text displayed for the "no" option (defaults to "No") */
  inactive?: string;
  /** Initial selection state (defaults to true) */
  initialValue?: boolean;
}

import { confirm, isCancel, cancel } from "@clack/prompts";

// Basic confirmation
const shouldContinue = await confirm({
  message: "Do you want to continue?",
});

if (isCancel(shouldContinue)) {
  cancel("Operation cancelled");
  process.exit(0);
}

// Custom confirmation with labels
const deleteConfirm = await confirm({
  message: "This will permanently delete all files. Are you sure?",
  active: "Delete",
  inactive: "Keep",
  initialValue: false, // Default to "Keep"
});

if (deleteConfirm) {
  console.log("Files deleted");
} else {
  console.log("Files preserved");
}

import { text, isCancel, cancel } from "@clack/prompts";

const result = await text({ message: "Enter something:" });

if (isCancel(result)) {
  cancel("Operation was cancelled by user");
  process.exit(0);
}

// result is now guaranteed to be a string
console.log(`You entered: ${result}`);

const validatedInput = await text({
  message: "Enter a number between 1 and 100:",
  validate: (value) => {
    const num = parseInt(value);
    if (isNaN(num)) return "Please enter a valid number";
    if (num < 1 || num > 100) return "Number must be between 1 and 100";
    // Return undefined for valid input
  }
});