@hangtime/grip-connect-cli/dist/utils.d.ts

CLI tool for Grip Connect devices

/**
 * Shared CLI utilities: prompts, connect helper, output formatting,
 * signal handling, and colored terminal output.
 */
import type { Action, CliDevice, ForceMeasurement, OutputContext } from "./types.js";
/**
 * Resolves the {@link OutputContext} from the root Commander program options.
 *
 * Call this inside every command action to pick up `--json` / `--no-color`.
 *
 * @param program - The root Commander program instance.
 * @returns The resolved output context.
 */
export declare function resolveContext(program: {
    opts(): Record<string, unknown>;
}): OutputContext;
/**
 * Formats a single force measurement as a human-readable string with color.
 * When distribution (left/center/right) is present, appends e.g. "Left: 0.00 kg Center: 0.00 kg Right: 0.00 kg".
 *
 * @param data - The force measurement to format.
 * @returns A formatted string such as `"12.34 kg  Peak: 15.00 kg  Mean: 11.20 kg  Left: 0.00 kg Center: 0.00 kg Right: 0.00 kg"`.
 */
export declare function formatMeasurement(data: ForceMeasurement): string;
/**
 * Writes a JSON line to stdout (newline-delimited JSON).
 *
 * @param value - Any JSON-serializable value.
 */
export declare function outputJson(value: unknown): void;
/**
 * Prints a labelled result value to stdout with colored label.
 *
 * @param label - The label text (e.g. `"Battery:"`).
 * @param value - The value to display, or `undefined` for "Not supported".
 */
export declare function printResult(label: string, value: string | undefined): void;
/**
 * Prints a section header with a horizontal rule.
 *
 * @param title - The header text.
 */
export declare function printHeader(title: string): void;
/**
 * Prints a success message in green.
 *
 * @param message - The message to display.
 */
export declare function printSuccess(message: string): void;
/**
 * Prints an error message in red and throws so the top-level handler
 * in `index.ts` can exit cleanly.
 *
 * @param message - The error message.
 * @throws {Error} Always throws with the given message.
 */
export declare function fail(message: string): never;
/**
 * Prompts the user to pick a device from the registry.
 *
 * @returns The lowercase device key (e.g. `"progressor"`).
 */
export declare function pickDevice(): Promise<string>;
/**
 * Prompts the user to pick an action from a list.
 *
 * @param actions - Available actions for the current device.
 * @returns The selected {@link Action} object.
 */
export declare function pickAction(actions: Action[]): Promise<Action>;
/**
 * Resolves a device key, prompting interactively if not provided.
 *
 * @param deviceKey - Optional device key from the command line.
 * @returns The resolved lowercase device key.
 */
export declare function resolveDeviceKey(deviceKey: string | undefined): Promise<string>;
/**
 * Instantiates a {@link CliDevice} from the registry.
 *
 * @param deviceKey - The device key to look up.
 * @returns An object containing the device instance and its display name.
 * @throws {Error} If the device key is unknown.
 */
export declare function createDevice(deviceKey: string): {
    device: CliDevice;
    name: string;
};
/**
 * Registers SIGINT and SIGTERM handlers that gracefully disconnect the
 * device before exiting.
 *
 * @param device - The connected device to disconnect on signal.
 * @param onCleanup - Optional extra work to run before exit (e.g. print summary).
 */
export declare function setupSignalHandlers(device: CliDevice, onCleanup?: () => void): void;
/**
 * Returns true if the device requires an active stream for tare to work.
 * Stream devices expose both stream and tare; tare collects samples or
 * captures current weight during streaming.
 */
export declare function isStreamDevice(d: CliDevice): boolean;
/**
 * Registers the standard force-measurement notify callback on a device.
 *
 * In JSON mode it emits newline-delimited JSON; otherwise it prints a
 * colored line.  Call {@link muteNotify} to silence output between actions.
 *
 * @param device - The device to register the callback on.
 * @param ctx - Output context for JSON / color flags.
 */
export declare function setupNotify(device: CliDevice, ctx: OutputContext): void;
/**
 * Silences the notify callback so no force data is printed.
 *
 * Useful between actions in interactive mode or after a stream completes.
 *
 * @param device - The device to mute.
 */
export declare function muteNotify(device: CliDevice): void;
/**
 * Options for {@link waitForKeyToStop}.
 */
export interface WaitForKeyOptions {
    /** Message to print (e.g. "Press Esc to stop"). */
    message?: string;
    /** Extra key handlers: key char code -> callback. Deferred with setImmediate. */
    extraKeys?: Record<number, () => void>;
}
/**
 * Returns a promise that resolves when the user presses Escape (stdin TTY only).
 * Uses readline keypress events to avoid conflicts with chart rendering.
 *
 * @param messageOrOptions - Message string, or options with message and extra key handlers.
 * @returns A promise that resolves when Escape is pressed, or never when not a TTY.
 */
export declare function waitForKeyToStop(messageOrOptions?: string | WaitForKeyOptions): Promise<void>;
/**
 * Connects to a device with a spinner, runs a callback, then disconnects.
 *
 * Sets up formatted stream output (via {@link setupNotify}) as soon as we're
 * connected so every device shows human-readable force lines (or NDJSON when
 * `--json`). Actions that stream may call setupNotify again to refresh unit.
 *
 * @param device - The device to connect to.
 * @param name - The human-readable device name (for spinner text).
 * @param callback - Async work to perform once connected.
 * @param ctx - Output context for JSON / color flags.
 */
export declare function connectAndRun(device: CliDevice, name: string, callback: (device: CliDevice) => Promise<void>, ctx?: OutputContext): Promise<void>;
/**
 * Builds the full list of actions for a device: shared actions first,
 * then device-specific actions, then disconnect.
 *
 * Shared actions are derived dynamically from the device capabilities
 * (e.g. `stream`, `battery`, `tare`, `download`).
 *
 * @param deviceKey - The device registry key.
 * @param ctx - Optional output context for dynamic labels (e.g. Unit (kg)).
 * @returns An ordered array of {@link Action} objects.
 */
export declare function buildActions(deviceKey: string, ctx?: OutputContext): Action[];
//# sourceMappingURL=utils.d.ts.map