import type { Palette } from "./colors.ts";
/**
 * The minimal writable surface the CLI needs. We type against this rather than `NodeJS.WriteStream` so output is testable with a trivial in-memory capture - and so the
 * abstraction states exactly what it uses: a `write` and an `isTTY` hint. (`Buffer extends Uint8Array`, so this accepts raw fMP4 frames as readily as text.)
 *
 * @category CLI
 */
export interface OutputStream {
    isTTY?: boolean;
    write(chunk: string | Uint8Array): boolean;
}
/**
 * Construction options for {@link Output}. All optional; the defaults bind to the real process streams and environment. A command that pipes a binary payload to stdout
 * constructs its `Output` with `stream: process.stderr` so every human-readable line lands on stderr and the stdout byte stream stays pristine.
 *
 * @category CLI
 */
export interface OutputOptions {
    colorize?: boolean;
    env?: NodeJS.ProcessEnv;
    stream?: OutputStream;
}
/**
 * `Output` is the one place the CLI decides *where* a byte goes and *whether* it is colored. Every command writes human-readable output through an `Output`; nothing
 * calls `console` (which the lint preset flags) or pokes `process.stdout` for text directly. Centralizing it is what makes the stdout-versus-stderr contract a property
 * of the design rather than a convention each command must remember - the binary-piping commands point their `Output` at stderr, and everything they log is automatically
 * kept clear of the payload on stdout.
 *
 * @category CLI
 */
export declare class Output {
    #private;
    /** The resolved color palette for this output's stream. Commands call `output.colors.dim(...)` and never branch on whether color is enabled. */
    readonly colors: Palette;
    constructor(opts?: OutputOptions);
    /**
     * Write text with no trailing newline.
     *
     * @param text - The text to write.
     */
    write(text: string): void;
    /**
     * Write a line of text, appending a newline.
     *
     * @param text - The line to write; defaults to an empty line.
     */
    line(text?: string): void;
    /**
     * Write one value as a single line of compact JSON. Called once per record, this method produces NDJSON - the line-delimited capture format that `jq` and
     * fixture-replay tooling consume - which is exactly what `watch events --json` emits, one event per line with no truncation and no color. Object keys are emitted in
     * deterministic sorted order (see {@link sortKeysReplacer}), so a captured stream diffs and replays identically regardless of the order the wire delivered fields in.
     *
     * @param value - The value to serialize.
     */
    json(value: unknown): void;
    /**
     * Write one value as indented, human-readable JSON. For single-shot dumps (a controller summary, a device record) where readability beats line-delimited density.
     * Object keys are emitted in deterministic sorted order (see {@link sortKeysReplacer}), so a bootstrap or a reduced-state dump reads the same way every time.
     *
     * @param value - The value to serialize.
     */
    jsonPretty(value: unknown): void;
    /**
     * Render a column-aligned table. Each column is padded to the width of its widest cell (header included); the header row is emphasized via the palette. Cells are
     * coerced to strings by the caller, so a column can carry pre-colored text and still align correctly - we measure visible width with the ANSI escapes stripped.
     *
     * @param headers - The column headers.
     * @param rows    - The data rows; each row must have one cell per header.
     */
    table(headers: string[], rows: string[][]): void;
}
/**
 * Render a list of label/description pairs as aligned lines: every label is right-padded to the widest label so the descriptions line up in one column. The single home
 * for the CLI's "name then description" lists - the top-level command list, the `watch` subcommand list, and the top-level examples block - so they all align by the same
 * rule and an added entry can never leave a list ragged (the width is measured from the entries, not hand-spaced). Each line is indented two spaces, with two spaces
 * between the columns.
 *
 * @param rows - The `[label, description]` pairs, in display order.
 *
 * @returns One formatted line per row.
 *
 * @category CLI
 */
export declare function alignedList(rows: readonly (readonly [string, string])[]): string[];
/**
 * Format an epoch-millisecond instant as an ISO-8601 string. We render times unambiguously (UTC, with the offset explicit) rather than in an unstated local zone, because
 * CLI output is frequently piped, logged, and compared across machines.
 *
 * @param epochMs - Milliseconds since the Unix epoch.
 *
 * @returns The ISO-8601 representation.
 *
 * @category CLI
 */
export declare function formatTimestamp(epochMs: number): string;
/**
 * The current wall-clock time as a compact HH:MM:SS.mmm stamp - enough to correlate streaming output (events, state changes, segments) without the date noise of a full
 * ISO string on every line. The single source for the CLI's streaming-line timestamp.
 *
 * @returns The HH:MM:SS.mmm stamp for now.
 *
 * @category CLI
 */
export declare function nowStamp(): string;
/**
 * Format a byte count as a compact, binary-prefixed size (e.g. "4.0 KiB", "1.3 MiB"). Used for livestream segment sizes and capture totals, where the order of magnitude
 * matters more than the exact byte count.
 *
 * @param bytes - The byte count.
 *
 * @returns The formatted size.
 *
 * @category CLI
 */
export declare function formatBytes(bytes: number): string;
/**
 * Format a duration in milliseconds as a compact, human-readable string - the two most significant non-zero units, e.g. "3d 4h" or "12m 8s". Used for controller uptime
 * and inter-segment gaps, where a precise millisecond count is noise but the order of magnitude is the point.
 *
 * @param ms - The duration in milliseconds.
 *
 * @returns The compact representation, or "0s" when the duration rounds down to zero whole seconds (any value under one second, a non-positive one included).
 *
 * @category CLI
 */
export declare function formatDuration(ms: number): string;
/**
 * Compare two strings by UTF-16 code unit - the default, locale-independent string ordering. The single comparator behind every deterministic sort the CLI performs (the
 * JSON key ordering below and the usage-screen command lists), so "sorted" means one thing, identical on every machine, everywhere the CLI orders by string.
 *
 * @param a - The first string.
 * @param b - The second string.
 *
 * @returns A negative number when `a` precedes `b`, positive when it follows, zero when equal.
 *
 * @category CLI
 */
export declare function compareCodeUnit(a: string, b: string): number;
//# sourceMappingURL=format.d.ts.map