netstorage/dist/src/cli/utils/index.d.ts

A TypeScript API and CLI for the Akamai NetStorage REST interface

import { createLogger, type NetStorageFile, type WinstonLogLevel, type NetStorageClientConfig } from '../../index';
/**
 * Sets the result of the last executed command.
 *
 * @param result - The result to store.
 */
export declare function setLastCommandResult(result: unknown): void;
/**
 * Retrieves the result of the last executed command.
 *
 * @returns The stored result.
 */
export declare function getLastCommandResult(): unknown;
/**
 * Clears the result of the last executed command.
 */
export declare function clearLastCommandResult(): void;
/**
 * Specifies how each positional argument of a command should be resolved.
 *
 * Each key is a command string mapping to an object where keys are argument
 * indices and values indicate resolution mode:
 * - 'local': argument is a local path.
 * - 'remote': argument is a remote path.
 * - 'passthrough': argument is passed through as-is without resolution.
 */
export interface CommandArgResolutionSpec {
    [command: string]: {
        [index: number]: 'local' | 'remote' | 'passthrough';
    };
}
/**
 * Validates and parses a timeout value from a string.
 *
 * @param v - The timeout value as a string.
 * @returns The parsed timeout as a number.
 * @throws If the value cannot be parsed into a valid number.
 */
export declare function validateTimeout(v: string): number;
/**
 * Validates and parses a cancel-after value from a string.
 *
 * @param v - The cancel-after value as a string.
 * @returns The parsed cancel-after value as a number.
 * @throws If the value cannot be parsed into a valid number.
 */
export declare function validateCancelAfter(v: string): number;
/**
 * Resolves an AbortSignal that triggers after the given number of
 * milliseconds.
 *
 * @param cancelAfter - Time in milliseconds to wait before aborting.
 * @returns An AbortSignal if cancelAfter is provided; otherwise,
 * undefined.
 */
export declare function resolveAbortSignalCLI(cancelAfter?: number): AbortSignal | undefined;
/**
 * Handles CLI-related errors and logs a user-friendly message.
 * Exits the process with status code 1.
 *
 * @param err - The error object caught during execution.
 * @param logger - The logger instance to use for logging.
 */
export declare function handleCliError(err: unknown, logger: ReturnType<typeof createLogger>): void;
/**
 * Resolves the appropriate Winston log level override based on CLI options.
 *
 * @param logLevel - Optional string log level explicitly provided.
 * @param verbose - Whether verbose logging is enabled.
 * @returns An object containing the log level override, or undefined if
 * invalid.
 */
export declare function getLogLevelOverride(logLevel?: string, verbose?: boolean): Partial<{
    logLevel: WinstonLogLevel;
}> | undefined;
/**
 * Prints data to stdout as a JSON string.
 *
 * @param data - The data to stringify and print.
 * @param pretty - Whether to pretty-print the JSON with indentation.
 */
export declare function printJson(data: unknown, pretty?: boolean): void;
/**
 * Sorts NetStorage entries by type priority and alphabetically by name.
 *
 * @param entries - The entries to sort.
 */
export declare function sortEntriesByTypeAndName(entries: NetStorageFile[]): void;
/**
 * Formats a single entry with detailed metadata.
 *
 * @param entry - The NetStorage file entry.
 * @param maxSizeLength - Width for right-aligned file sizes.
 * @returns A formatted string.
 */
export declare function formatDetailedEntry(entry: NetStorageFile, maxSizeLength: number): string;
/**
 * Formats a single entry for simple (non-detailed) output.
 *
 * @param entry - The NetStorage file entry.
 * @returns A formatted string.
 */
export declare function formatSimpleEntry(entry: NetStorageFile): string;
/**
 * Resolves a relative or absolute path against the current remote working
 * directory.
 *
 * - Normalizes redundant slashes.
 * - Ensures path starts with a single leading slash.
 * - Trims any trailing slashes (except root).
 *
 * @param input - The path input from the user (may be relative or
 * absolute).
 * @param currentPath - The current working directory path.
 * @returns A normalized, absolute path.
 */
export declare function resolvePath(input: string | undefined, currentPath: string): string;
/**
 * Applies terminal colorization to a NetStorage entry name based on its
 * type.
 *
 * - Directories are cyan.
 * - Symlinks are blue.
 * - Files are gray.
 *
 * @param name - The display name of the entry.
 * @param type - The entry type: 'dir', 'file', or 'symlink'.
 * @returns The colorized name string.
 */
export declare function colorizeName(name: string, type: string): string;
/**
 * Asserts that the provided config is valid for REPL usage.
 *
 * Specifically ensures that `cpCode` is defined, since REPL operations
 * often require a default CP code for scoped commands.
 *
 * @param config - The NetStorageClientConfig to validate.
 * @throws ConfigValidationError if cpCode is not set.
 */
export declare function assertReplConfig(config: {
    cpCode?: string;
}): void;
/**
 * Returns a list of local files and directories that match the provided
 * prefix.
 *
 * @param {string} prefix - The prefix to filter local files and directories
 * by.
 * @returns {string[]} A list of matching local files and directories.
 */
export declare function getLocalCompletions(prefix: string): string[];
/**
 * Generates tab completions for REPL commands based on specified local and
 * remote argument positions.
 *
 * Supports commands where multiple positional arguments may be resolved as
 * either local or remote paths.
 *
 * @param line - The raw REPL input line.
 * @param tokens - Tokenized input from the REPL.
 * @param arg - The current argument token being completed.
 * @param remoteEntries - Remote NetStorage entry names.
 * @param options - Object with Sets identifying which argument indices
 * should resolve as local or remote.
 * @returns A tuple of matching completions and the replacement prefix.
 */
export declare function getReplCompletions(line: string, tokens: string[], arg: string, remoteEntries: string[], options: {
    localArgIndices?: Set<number>;
    remoteArgIndices?: Set<number>;
}): [string[], string];
/**
 * Parses the input string to extract command, arguments, and options using
 * yargs-parser.
 *
 * All returned args and options are coerced to strings.
 * Handles both short (e.g., -v) and long (e.g., --verbose) options.
 *
 * @param input - The raw input string from the REPL.
 * @returns An object containing the command, args, and options as string
 * arrays.
 */
export declare function parseReplInput(input: string): {
    command: string;
    args: string[];
    options: string[];
};
/**
 * Resolves CLI arguments based on resolution spec and working directory.
 *
 * For arguments marked as 'remote' that are missing, infers the value using
 * the basename of a corresponding local argument (if available) or
 * defaults to the current remote working directory.
 *
 * Supports multiple remote, local, or passthrough positions defined via the
 * resolutionSpec.
 * Arguments marked as 'passthrough' are preserved as-is without
 * resolution.
 *
 * @param args - Raw user-provided arguments.
 * @param resolutionSpec - Map indicating whether each positional argument
 * should resolve as 'local', 'remote', or 'passthrough'.
 * @param cwd - Current remote working directory.
 * @returns Fully resolved list of arguments for CLI execution.
 */
export declare function resolveCliArgs(args: string[], resolutionSpec: CommandArgResolutionSpec[string], cwd: string): string[];
/**
 * Resolves a complete NetStorage client config from layered configuration sources.
 *
 * Resolution order (highest to lowest priority):
 * 1. CLI options (explicit flags passed to CLI command)
 * 2. Environment variables (NETSTORAGE_* keys)
 * 3. Project-level config file (`netstorage.json` in the current directory)
 * 4. Persistent config (`~/.config/netstorage/.netstorage.json`)
 *
 * @param {Partial<NetStorageClientConfig>} [cliOptions] - Optional config overrides from CLI flags.
 * @returns {Promise<NetStorageClientConfig>} Fully resolved configuration object.
 */
export declare function loadClientConfig(cliOptions?: Partial<NetStorageClientConfig>): Promise<NetStorageClientConfig>;
/**
 * Loads the persisted NetStorage client configuration from the user's config file.
 *
 * @returns {Partial<NetStorageClientConfig>} The saved configuration, or an empty object if none exists.
 */
export declare function loadPersistentConfig(): Partial<NetStorageClientConfig>;
/**
 * Merges and saves the provided configuration with the existing persisted config.
 * Creates the config directory if it does not exist.
 *
 * @param {Partial<NetStorageClientConfig>} update - Configuration values to persist.
 */
export declare function savePersistentConfig(update: Partial<NetStorageClientConfig>): void;
/**
 * Deletes the persisted NetStorage configuration file if it exists.
 */
export declare function clearPersistentConfig(): void;
/**
 * Deletes a specific key from the persisted NetStorage configuration file.
 *
 * @param {keyof NetStorageClientConfig} key - The configuration key to remove.
 */
export declare function clearPersistentConfigKey(key: keyof NetStorageClientConfig): void;
/**
 * Returns the path to the persistent configuration file.
 *
 * @returns {string} The absolute path to the saved config file.
 */
export declare function getPersistentConfigPath(): string;
/**
 * Returns a spinner instance based on the logging level configuration.
 *
 * @param {Partial<NetStorageClientConfig>} config - The configuration object
 *   containing the logging level.
 * @returns {yoctoSpinner.Spinners} A spinner instance if `logLevel` is not set
 *   or is set to `'info'`. Otherwise returns `null`.
 */
export declare function getSpinner(config: Partial<NetStorageClientConfig>): import("yocto-spinner").Spinner | null;
/**
 * Writes the given input string or array of strings to the standard output.
 *
 * @param {string|string[]} input - The string or array of strings to write.
 * @returns {void} No return value.
 */
export declare function writeOut(input?: unknown): void;