@settlemint/sdk-utils/dist/terminal.d.cts

Shared utilities and helper functions for SettleMint SDK modules

import { SpawnOptionsWithoutStdio } from "node:child_process";
import { Spinner } from "yocto-spinner";

//#region src/terminal/ascii.d.ts

/**
 * Prints the SettleMint ASCII art logo to the console in magenta color.
 * Used for CLI branding and visual identification.
 *
 * @example
 * import { ascii } from "@settlemint/sdk-utils/terminal";
 *
 * // Prints the SettleMint logo
 * ascii();
 */
declare const ascii: () => void;
//#endregion
//#region src/terminal/cancel.d.ts
/**
 * Error class used to indicate that the operation was cancelled.
 * This error is used to signal that the operation should be aborted.
 */
declare class CancelError extends Error {}
/**
 * Displays an error message in red inverse text and throws a CancelError.
 * Used to terminate execution with a visible error message.
 * Any sensitive tokens in the message are masked before display.
 *
 * @param msg - The error message to display
 * @returns never - Function does not return as it throws an error
 * @example
 * import { cancel } from "@settlemint/sdk-utils/terminal";
 *
 * // Exits process with error message
 * cancel("An error occurred");
 */
declare const cancel: (msg: string) => never;
//#endregion
//#region src/terminal/execute-command.d.ts
/**
 * Options for executing a command, extending SpawnOptionsWithoutStdio
 */
interface ExecuteCommandOptions extends SpawnOptionsWithoutStdio {
  /** Whether to suppress output to stdout/stderr */
  silent?: boolean;
}
/**
 * Error class for command execution errors
 * @extends Error
 */
declare class CommandError extends Error {
  readonly code: number;
  readonly output: string[];
  /**
   * Constructs a new CommandError
   * @param message - The error message
   * @param code - The exit code of the command
   * @param output - The output of the command
   */
  constructor(message: string, code: number, output: string[]);
}
/**
 * Executes a command with the given arguments in a child process.
 * Pipes stdin to the child process and captures stdout/stderr output.
 * Masks any sensitive tokens in the output before displaying or returning.
 * In quiet mode (when CLAUDECODE, REPL_ID, or AGENT env vars are set),
 * output is suppressed unless the command errors out.
 *
 * @param command - The command to execute
 * @param args - Array of arguments to pass to the command
 * @param options - Options for customizing command execution
 * @returns Array of output strings from stdout and stderr
 * @throws {CommandError} If the process fails to start or exits with non-zero code
 * @example
 * import { executeCommand } from "@settlemint/sdk-utils/terminal";
 *
 * // Execute git clone
 * await executeCommand("git", ["clone", "repo-url"]);
 *
 * // Execute silently
 * await executeCommand("npm", ["install"], { silent: true });
 */
declare function executeCommand(command: string, args: string[], options?: ExecuteCommandOptions): Promise<string[]>;
//#endregion
//#region src/terminal/intro.d.ts
/**
 * Displays an introductory message in magenta text with padding.
 * Any sensitive tokens in the message are masked before display.
 *
 * @param msg - The message to display as introduction
 * @example
 * import { intro } from "@settlemint/sdk-utils/terminal";
 *
 * // Display intro message
 * intro("Starting deployment...");
 */
declare const intro: (msg: string) => void;
//#endregion
//#region src/terminal/list.d.ts
/**
 * Displays a list of items in a formatted manner, supporting nested items.
 *
 * @param title - The title of the list
 * @param items - The items to display, can be strings or arrays for nested items
 * @returns The formatted list
 * @example
 * import { list } from "@settlemint/sdk-utils/terminal";
 *
 * // Simple list
 * list("Use cases", ["use case 1", "use case 2", "use case 3"]);
 *
 * // Nested list
 * list("Providers", [
 *   "AWS",
 *   ["us-east-1", "eu-west-1"],
 *   "Azure",
 *   ["eastus", "westeurope"]
 * ]);
 */
declare function list(title: string, items: Array<string | string[]>): void;
//#endregion
//#region src/terminal/note.d.ts
/**
 * Displays a note message with optional warning or error level formatting.
 * Regular notes are displayed in normal text, warnings are shown in yellow, and errors in red.
 * Any sensitive tokens in the message are masked before display.
 * Warnings and errors are always displayed, even in quiet mode (when CLAUDECODE, REPL_ID, or AGENT env vars are set).
 * When an Error object is provided with level "error", the stack trace is automatically included.
 *
 * @param message - The message to display as a note. Can be either:
 *   - A string: Displayed directly with appropriate styling
 *   - An Error object: The error message is displayed, and for level "error", the stack trace is automatically included
 * @param level - The note level: "info" (default), "warn" for warning styling, or "error" for error styling
 * @example
 * import { note } from "@settlemint/sdk-utils/terminal";
 *
 * // Display info note
 * note("Operation completed successfully");
 *
 * // Display warning note
 * note("Low disk space remaining", "warn");
 *
 * // Display error note (string)
 * note("Operation failed", "error");
 *
 * // Display error with stack trace automatically (Error object)
 * try {
 *   // some operation
 * } catch (error) {
 *   // If error is an Error object and level is "error", stack trace is included automatically
 *   note(error, "error");
 * }
 */
declare const note: (message: string | Error, level?: "info" | "warn" | "error") => void;
//#endregion
//#region src/terminal/outro.d.ts
/**
 * Displays a closing message in green inverted text with padding.
 * Any sensitive tokens in the message are masked before display.
 *
 * @param msg - The message to display as conclusion
 * @example
 * import { outro } from "@settlemint/sdk-utils/terminal";
 *
 * // Display outro message
 * outro("Deployment completed successfully!");
 */
declare const outro: (msg: string) => void;
//#endregion
//#region src/terminal/spinner.d.ts
/**
 * Error class used to indicate that the spinner operation failed.
 * This error is used to signal that the operation should be aborted.
 */
declare class SpinnerError extends Error {
  readonly originalError: Error;
  constructor(message: string, originalError: Error);
}
/**
 * Options for configuring the spinner behavior
 */
interface SpinnerOptions<R> {
  /** Message to display when spinner starts */
  startMessage: string;
  /** Async task to execute while spinner is active */
  task: (spinner?: Spinner) => Promise<R>;
  /** Message to display when spinner completes successfully */
  stopMessage: string;
}
/**
 * Displays a loading spinner while executing an async task.
 * Shows progress with start/stop messages and handles errors.
 * Spinner is disabled in CI environments.
 *
 * @param options - Configuration options for the spinner
 * @returns The result from the executed task
 * @throws Will exit process with code 1 if task fails
 * @example
 * import { spinner } from "@settlemint/sdk-utils/terminal";
 *
 * // Show spinner during async task
 * const result = await spinner({
 *   startMessage: "Deploying...",
 *   task: async () => {
 *     // Async work here
 *     return "success";
 *   },
 *   stopMessage: "Deployed successfully!"
 * });
 */
declare const spinner: <R>(options: SpinnerOptions<R>) => Promise<R>;
//#endregion
//#region src/terminal/table.d.ts
/**
 * Displays data in a formatted table in the terminal.
 *
 * @param title - Title to display above the table
 * @param data - Array of objects to display in table format
 * @example
 * import { table } from "@settlemint/sdk-utils/terminal";
 *
 * const data = [
 *   { name: "Item 1", value: 100 },
 *   { name: "Item 2", value: 200 }
 * ];
 *
 * table("My Table", data);
 */
declare function table(title: string, data: unknown[]): void;
//#endregion
//#region src/logging/mask-tokens.d.ts
/**
 * Masks sensitive SettleMint tokens in output text by replacing them with asterisks.
 * Handles personal access tokens (PAT), application access tokens (AAT), and service account tokens (SAT).
 *
 * @param output - The text string that may contain sensitive tokens
 * @returns The text with any sensitive tokens masked with asterisks
 * @example
 * import { maskTokens } from "@settlemint/sdk-utils/terminal";
 *
 * // Masks a token in text
 * const masked = maskTokens("Token: sm_pat_****"); // "Token: ***"
 */
declare const maskTokens: (output: string) => string;
//#endregion
export { CancelError, CommandError, type ExecuteCommandOptions, SpinnerError, type SpinnerOptions, ascii, cancel, executeCommand, intro, list, maskTokens, note, outro, spinner, table };
//# sourceMappingURL=terminal.d.cts.map