netstorage/dist/src/cli/commands/createReplCommand.d.ts

A TypeScript API and CLI for the Akamai NetStorage REST interface

import { type REPLServer } from 'node:repl';
import { Command } from 'commander';
import { type NetStorageClientConfig, type NetStorageFile } from '../../index';
import { type CommandArgResolutionSpec } from '../utils';
import type winston from 'winston';
/**
 * Defines resolution specifications for read-based NetStorage commands.
 *
 * Each command maps its positional arguments to how they should be resolved:
 * - 'remote': argument should resolve to a remote path.
 */
export declare const CLIGetOperationCommands: CommandArgResolutionSpec;
/**
 * Defines resolution specifications for write-based NetStorage commands.
 *
 * Each command maps its positional arguments to how they should be resolved:
 * - 'local': argument should resolve to a local path.
 * - 'remote': argument should resolve to a remote path.
 * - 'passthrough': argument is preserved as-is without resolution.
 */
export declare const CLIPutOperationCommands: CommandArgResolutionSpec;
/**
 * Combined resolution specification for all supported CLI commands.
 *
 * Merges `GetCommands` and `PutCommands` to support tab completion and
 * argument resolution logic for the interactive REPL shell.
 */
export declare const CLIOperationCommands: CommandArgResolutionSpec;
/**
 * Resolution specification for the `config` command.
 */
export declare const CLIConfigCommand: CommandArgResolutionSpec;
/**
 * List of internal REPL commands handled directly by the REPL shell. These
 * commands do not invoke the main CLI parser.
 */
export declare const REPLCommands: readonly ["cd", "ls", "ll", "pwd", "clear", "exit"];
/**
 * Interface representing the remote context for the interactive NetStorage
 * shell. Provides methods for managing the current remote path, caching
 * directory entries, and retrieving/updating directory contents.
 */
export interface RemoteContext {
    getPath(): string;
    setPath(path: string): void;
    getEntries(): Promise<NetStorageFile[]>;
    loadEntries(path: string): Promise<{
        rootMeta?: NetStorageFile;
        entries: NetStorageFile[];
    }>;
    clearCache(): void;
    setCachedEntries(path: string, entries: NetStorageFile[]): void;
}
/**
 * Creates a remote context object for interacting with the NetStorage working
 * directory. The context manages the current remote path, caches directory
 * entries, and exposes methods to retrieve or update remote directory contents.
 *
 * @param config - The NetStorage client configuration.
 * @returns A RemoteContext object providing access to path and entries
 * management.
 */
export declare function createRemoteContext(config: NetStorageClientConfig): RemoteContext;
/**
 * Creates an in-memory cache utility for directory listings in the REPL. Stores
 * entries for a single directory path and clears when navigating to a new path.
 *
 * @returns An object with methods to get, set, and clear cached entries.
 */
export declare function createRemoteDirectoryCache(): {
    /**
     * Retrieves cached entries for the specified path, if present.
     *
     * @param path - Path to look up in the cache.
     * @returns Cached entries array, or undefined if not cached.
     */
    getCachedEntries(path: string): NetStorageFile[] | undefined;
    /**
     * Stores entries for a specific path in the cache.
     *
     * @param path - Path to associate with the cached entries.
     * @param entries - Array of NetStorageFile entries to cache.
     */
    setCachedEntries(path: string, entries: NetStorageFile[]): void;
    /**
     * Clears the current cached path and entries.
     */
    clear(): void;
};
/**
 * Executes the `cd` command in the REPL. Resolves the target path, verifies it's
 * a directory, and updates the remote context. Logs a warning if the path is
 * invalid or not a directory.
 *
 * @param target - Target path to change to (relative or absolute).
 * @param ctx - RemoteContext instance for managing remote path state.
 * @param logger - Logger for outputting warnings and errors.
 * @returns Promise that resolves when the operation is complete.
 */
export declare function handleCdCommand(target: string | undefined, ctx: RemoteContext, logger: winston.Logger): Promise<void>;
/**
 * Executes the `ls` or `ll` command in the REPL. Fetches and displays directory
 * entries for the target or current path, optionally showing detailed metadata.
 * Entries are sorted by type and name.
 *
 * @param detailed - Whether to show detailed output (type, size, modified time,
 * colorized name).
 * @param ctx - RemoteContext instance for retrieving entries.
 * @param target - Optional target path to list.
 * @returns Promise that resolves when the command finishes.
 */
export declare function handleLsCommand(detailed: boolean, ctx: RemoteContext, target?: string): Promise<void>;
/**
 * Refreshes the completer function with the latest entries from the remote context.
 *
 * @param {RemoteContext} context - The remote context to retrieve entries from.
 * @return {function} A synchronous tab-completion function for the REPL.
 */
export declare function refreshCompleter(context: RemoteContext): Promise<(line: string) => [string[], string]>;
/**
 * Creates a synchronous tab-completion function for the REPL. Provides
 * command-aware completion for REPL and CLI commands, suggesting appropriate
 * entries or commands.
 *
 * @param entries - Array of NetStorageFile entries to use for completion
 * suggestions.
 * @returns A function compatible with the REPL completer API.
 */
export declare function createCompleterSync(entries: NetStorageFile[]): (line: string) => [string[], string];
/**
 * Resumes the interactive shell by updating the prompt and requesting user input.
 *
 * @returns {void} No return value.
 */
export declare function resumeShell(context: RemoteContext, shell: REPLServer): void;
/**
 * Handles internal REPL commands, such as `cd`, `ls`, and `pwd`.
 *
 * @param command - The command to handle.
 * @param args - The arguments for the command.
 * @param options - The options for the command.
 */
export declare const runReplCommand: (config: NetStorageClientConfig, context: RemoteContext, command: string, args: string[], options: string[]) => Promise<void>;
/**
 * Handles CLI commands.
 *
 * @param config - The NetStorage client configuration.
 * @param context - The remote context for the REPL.
 * @param command - The command to handle.
 * @param args - The arguments for the command.
 * @param options - The options for the command.
 */
export declare const runClICommand: (config: NetStorageClientConfig, context: RemoteContext, command: string, args: string[], options: string[]) => Promise<{
    config: NetStorageClientConfig;
    context: RemoteContext;
}>;
/**
 * Constructs the `repl` command for the NetStorage CLI. Launches an interactive
 * shell that accepts NetStorage CLI commands and routes them through Commander.
 *
 * @returns Commander Command instance for the REPL.
 */
export declare function createReplCommand(): Command;