kadi-deploy 0.19.0

package/src/cli/colors.ts

@@ -0,0 +1,216 @@
+/**
+ * CLI Color Utilities
+ *
+ * Provides a consistent color scheme across kadi-deploy.
+ * Wraps the `chalk` library with semantic color functions.
+ *
+ * @module cli/colors
+ */
+
+import chalk from 'chalk';
+
+/**
+ * Success message color (green)
+ *
+ * @example
+ * ```typescript
+ * console.log(success('Deployment complete!'));
+ * ```
+ */
+export const success = chalk.green;
+
+/**
+ * Error message color (red)
+ *
+ * @example
+ * ```typescript
+ * console.error(error('Deployment failed'));
+ * ```
+ */
+export const error = chalk.red;
+
+/**
+ * Warning message color (yellow)
+ *
+ * @example
+ * ```typescript
+ * console.log(warning('Certificate will expire soon'));
+ * ```
+ */
+export const warning = chalk.yellow;
+
+/**
+ * Info message color (blue)
+ *
+ * @example
+ * ```typescript
+ * console.log(info('Loading profile...'));
+ * ```
+ */
+export const info = chalk.blue;
+
+/**
+ * Dim/subtle text color (gray)
+ *
+ * @example
+ * ```typescript
+ * console.log(dim('Using default settings'));
+ * ```
+ */
+export const dim = chalk.dim;
+
+/**
+ * Bold text
+ *
+ * @example
+ * ```typescript
+ * console.log(bold('IMPORTANT:'), 'Read this carefully');
+ * ```
+ */
+export const bold = chalk.bold;
+
+/**
+ * Cyan color for highlights
+ *
+ * @example
+ * ```typescript
+ * console.log(`Deploying to ${highlight('mainnet')}`);
+ * ```
+ */
+export const highlight = chalk.cyan;
+
+/**
+ * Magenta color for special values
+ *
+ * @example
+ * ```typescript
+ * console.log(`DSEQ: ${special('12345')}`);
+ * ```
+ */
+export const special = chalk.magenta;
+
+/**
+ * Underlined text
+ *
+ * @example
+ * ```typescript
+ * console.log(underline('https://provider.akash.network'));
+ * ```
+ */
+export const underline = chalk.underline;
+
+/**
+ * Strikethrough text
+ *
+ * @example
+ * ```typescript
+ * console.log(strikethrough('deprecated option'));
+ * ```
+ */
+export const strikethrough = chalk.strikethrough;
+
+/**
+ * Formats a URL for display
+ *
+ * @param url - URL to format
+ * @returns Formatted URL string (cyan + underline)
+ *
+ * @example
+ * ```typescript
+ * console.log(`Visit: ${formatUrl('https://akash.network')}`);
+ * ```
+ */
+export function formatUrl(url: string): string {
+  return underline(highlight(url));
+}
+
+/**
+ * Formats a key-value pair for display
+ *
+ * @param key - Key name
+ * @param value - Value to display
+ * @returns Formatted string
+ *
+ * @example
+ * ```typescript
+ * console.log(formatKeyValue('Network', 'mainnet'));
+ * // Output: "Network: mainnet" (with colors)
+ * ```
+ */
+export function formatKeyValue(key: string, value: string | number): string {
+  return `${dim(key + ':')} ${value}`;
+}
+
+/**
+ * Formats a code/command for display
+ *
+ * @param code - Code or command string
+ * @returns Formatted code string (gray background)
+ *
+ * @example
+ * ```typescript
+ * console.log(`Run ${formatCode('kadi deploy --profile prod')}`);
+ * ```
+ */
+export function formatCode(code: string): string {
+  return chalk.bgGray.white(` ${code} `);
+}
+
+/**
+ * Formats a price/cost value
+ *
+ * @param amount - Amount value
+ * @param currency - Currency symbol or code
+ * @returns Formatted price string (green)
+ *
+ * @example
+ * ```typescript
+ * console.log(formatPrice('10.50', 'AKT'));
+ * // Output: "10.50 AKT" (green)
+ * ```
+ */
+export function formatPrice(amount: string | number, currency: string): string {
+  return success(`${amount} ${currency}`);
+}
+
+/**
+ * Formats a section header
+ *
+ * @param title - Section title
+ * @returns Formatted header string (bold + cyan)
+ *
+ * @example
+ * ```typescript
+ * console.log(formatHeader('Deployment Summary'));
+ * ```
+ */
+export function formatHeader(title: string): string {
+  return bold(highlight(`\n${title}`));
+}
+
+/**
+ * Formats a list item with a bullet
+ *
+ * @param text - Item text
+ * @param bullet - Bullet character (defaults to '•')
+ * @returns Formatted list item
+ *
+ * @example
+ * ```typescript
+ * console.log(formatListItem('Service deployed'));
+ * console.log(formatListItem('Profile loaded', '→'));
+ * ```
+ */
+export function formatListItem(text: string, bullet: string = '•'): string {
+  return `${dim(bullet)} ${text}`;
+}
+
+/**
+ * Raw chalk instance for advanced usage
+ *
+ * @example
+ * ```typescript
+ * console.log(chalk.bgBlue.white('Custom styling'));
+ * ```
+ */
+export { chalk };

package/src/cli/index.ts

@@ -0,0 +1,11 @@
+/**
+ * CLI Utilities Barrel Export
+ *
+ * Centralized export point for all CLI helper functions.
+ *
+ * @module cli
+ */
+
+export * from './spinners.js';
+export * from './prompts.js';
+export * from './colors.js';

package/src/cli/prompts.ts

@@ -0,0 +1,190 @@
+/**
+ * CLI Interactive Prompts
+ *
+ * Provides a consistent interface for user input across kadi-deploy.
+ * Wraps the `enquirer` library with type-safe prompt methods.
+ *
+ * @module cli/prompts
+ */
+
+import enquirer from 'enquirer';
+
+/**
+ * Prompts user to confirm an action (yes/no)
+ *
+ * @param message - Question to ask the user
+ * @param defaultValue - Default answer if user presses Enter (defaults to false)
+ * @returns Promise resolving to boolean (true = yes, false = no)
+ *
+ * @example
+ * ```typescript
+ * const proceed = await confirmPrompt('Deploy to mainnet?', false);
+ * if (proceed) {
+ *   // ... deploy ...
+ * }
+ * ```
+ */
+export async function confirmPrompt(
+  message: string,
+  defaultValue: boolean = false
+): Promise<boolean> {
+  const response = await enquirer.prompt<{ confirmed: boolean }>({
+    type: 'confirm',
+    name: 'confirmed',
+    message,
+    initial: defaultValue,
+  });
+  return response.confirmed;
+}
+
+/**
+ * Prompts user to input text
+ *
+ * @param message - Prompt message
+ * @param defaultValue - Default value if user presses Enter
+ * @param required - Whether input is required (defaults to true)
+ * @returns Promise resolving to user's input string
+ *
+ * @example
+ * ```typescript
+ * const projectId = await textPrompt(
+ *   'Enter WalletConnect Project ID:',
+ *   undefined,
+ *   true
+ * );
+ * ```
+ */
+export async function textPrompt(
+  message: string,
+  defaultValue?: string,
+  required: boolean = true
+): Promise<string> {
+  const response = await enquirer.prompt<{ value: string }>({
+    type: 'input',
+    name: 'value',
+    message,
+    initial: defaultValue,
+    validate: required ? (input: string) => input.length > 0 || 'Input is required' : undefined,
+  });
+  return response.value;
+}
+
+/**
+ * Prompts user to input a password (hidden)
+ *
+ * @param message - Prompt message
+ * @param required - Whether input is required (defaults to true)
+ * @returns Promise resolving to user's password
+ *
+ * @example
+ * ```typescript
+ * const password = await passwordPrompt('Enter wallet password:');
+ * ```
+ */
+export async function passwordPrompt(
+  message: string,
+  required: boolean = true
+): Promise<string> {
+  const response = await enquirer.prompt<{ password: string }>({
+    type: 'password',
+    name: 'password',
+    message,
+    validate: required ? (input: string) => input.length > 0 || 'Password is required' : undefined,
+  });
+  return response.password;
+}
+
+/**
+ * Prompts user to select from a list of choices
+ *
+ * @param message - Prompt message
+ * @param choices - Array of choice strings
+ * @param defaultChoice - Index of default choice (optional)
+ * @returns Promise resolving to selected choice
+ *
+ * @example
+ * ```typescript
+ * const network = await selectPrompt(
+ *   'Select network:',
+ *   ['mainnet', 'testnet'],
+ *   1
+ * );
+ * ```
+ */
+export async function selectPrompt(
+  message: string,
+  choices: string[],
+  defaultChoice?: number
+): Promise<string> {
+  const response = await enquirer.prompt<{ selected: string }>({
+    type: 'select',
+    name: 'selected',
+    message,
+    choices,
+    initial: defaultChoice,
+  });
+  return response.selected;
+}
+
+/**
+ * Prompts user to select multiple items from a list
+ *
+ * @param message - Prompt message
+ * @param choices - Array of choice strings
+ * @param defaultChoices - Array of initially selected indices (optional)
+ * @returns Promise resolving to array of selected choices
+ *
+ * @example
+ * ```typescript
+ * const services = await multiSelectPrompt(
+ *   'Select services to deploy:',
+ *   ['api', 'web', 'worker'],
+ *   [0, 1]
+ * );
+ * ```
+ */
+export async function multiSelectPrompt(
+  message: string,
+  choices: string[],
+  defaultChoices?: number[]
+): Promise<string[]> {
+  const response = await enquirer.prompt<{ selected: string[] }>({
+    type: 'multiselect',
+    name: 'selected',
+    message,
+    choices,
+    initial: defaultChoices,
+  });
+  return response.selected;
+}
+
+/**
+ * Prompts user with a custom enquirer prompt
+ *
+ * Use this for advanced prompt scenarios not covered by the convenience methods.
+ *
+ * @param options - Enquirer prompt options
+ * @returns Promise resolving to prompt response
+ *
+ * @example
+ * ```typescript
+ * const result = await customPrompt({
+ *   type: 'autocomplete',
+ *   name: 'provider',
+ *   message: 'Select provider:',
+ *   choices: providerList
+ * });
+ * ```
+ */
+export async function customPrompt<T = Record<string, unknown>>(
+  options: {
+    type: string;
+    name: string;
+    message: string;
+    choices?: string[] | { name: string; value: unknown }[];
+    initial?: unknown;
+    validate?: (value: unknown) => boolean | string;
+  }
+): Promise<T> {
+  return await enquirer.prompt<T>(options);
+}

package/src/cli/spinners.ts

@@ -0,0 +1,165 @@
+/**
+ * CLI Spinner Utilities
+ *
+ * Provides a consistent interface for progress indicators across kadi-deploy.
+ * Wraps the `ora` library with additional convenience methods.
+ *
+ * @module cli/spinners
+ */
+
+import ora, { Ora } from 'ora';
+
+/**
+ * Creates and starts a spinner with a message
+ *
+ * @param message - Initial spinner message
+ * @returns Ora spinner instance
+ *
+ * @example
+ * ```typescript
+ * const spinner = startSpinner('Deploying to Akash...');
+ * // ... do work ...
+ * spinner.succeed('Deployed successfully!');
+ * ```
+ */
+export function startSpinner(message: string): Ora {
+  return ora(message).start();
+}
+
+/**
+ * Creates a spinner without starting it
+ *
+ * Useful when you need to prepare a spinner but start it later.
+ *
+ * @param message - Spinner message
+ * @returns Ora spinner instance (not started)
+ *
+ * @example
+ * ```typescript
+ * const spinner = createSpinner('Processing...');
+ * // ... some setup ...
+ * spinner.start();
+ * ```
+ */
+export function createSpinner(message: string): Ora {
+  return ora(message);
+}
+
+/**
+ * Updates spinner message while it's running
+ *
+ * @param spinner - Active spinner instance
+ * @param message - New message to display
+ *
+ * @example
+ * ```typescript
+ * const spinner = startSpinner('Step 1...');
+ * updateSpinner(spinner, 'Step 2...');
+ * updateSpinner(spinner, 'Step 3...');
+ * spinner.succeed('Complete!');
+ * ```
+ */
+export function updateSpinner(spinner: Ora, message: string): void {
+  spinner.text = message;
+}
+
+/**
+ * Completes spinner with success message
+ *
+ * @param spinner - Active spinner instance
+ * @param message - Success message (optional)
+ *
+ * @example
+ * ```typescript
+ * const spinner = startSpinner('Deploying...');
+ * // ... work ...
+ * succeedSpinner(spinner, 'Deployment complete!');
+ * ```
+ */
+export function succeedSpinner(spinner: Ora, message?: string): void {
+  if (message) {
+    spinner.succeed(message);
+  } else {
+    spinner.succeed();
+  }
+}
+
+/**
+ * Completes spinner with failure message
+ *
+ * @param spinner - Active spinner instance
+ * @param message - Failure message (optional)
+ *
+ * @example
+ * ```typescript
+ * const spinner = startSpinner('Deploying...');
+ * try {
+ *   // ... work ...
+ * } catch (error) {
+ *   failSpinner(spinner, 'Deployment failed');
+ * }
+ * ```
+ */
+export function failSpinner(spinner: Ora, message?: string): void {
+  if (message) {
+    spinner.fail(message);
+  } else {
+    spinner.fail();
+  }
+}
+
+/**
+ * Completes spinner with warning message
+ *
+ * @param spinner - Active spinner instance
+ * @param message - Warning message (optional)
+ *
+ * @example
+ * ```typescript
+ * const spinner = startSpinner('Checking certificate...');
+ * warnSpinner(spinner, 'Certificate expired, creating new one');
+ * ```
+ */
+export function warnSpinner(spinner: Ora, message?: string): void {
+  if (message) {
+    spinner.warn(message);
+  } else {
+    spinner.warn();
+  }
+}
+
+/**
+ * Completes spinner with info message
+ *
+ * @param spinner - Active spinner instance
+ * @param message - Info message (optional)
+ *
+ * @example
+ * ```typescript
+ * const spinner = startSpinner('Loading profile...');
+ * infoSpinner(spinner, 'Using profile: production');
+ * ```
+ */
+export function infoSpinner(spinner: Ora, message?: string): void {
+  if (message) {
+    spinner.info(message);
+  } else {
+    spinner.info();
+  }
+}
+
+/**
+ * Stops spinner without any completion message
+ *
+ * @param spinner - Active spinner instance
+ *
+ * @example
+ * ```typescript
+ * const spinner = startSpinner('Loading...');
+ * stopSpinner(spinner);
+ * console.log('Custom message here');
+ * ```
+ */
+export function stopSpinner(spinner: Ora): void {
+  spinner.stop();
+}