paratext

import _default from 'paratext';
import { ansiEscapesFor, beep, beginSynchronizedOutput, … } from 'paratext';

function ansiEscapesFor(runtime: Runtime): AnsiEscapes;

function check(candidate: object): string[];

function emit(runtime: Runtime, name: string, fields?: Fields): string;

function fieldsUsed(template: string): string[];

function register(capability: Capability): void;

function registerBuiltins(): void;

function render(template: string, fields: Fields): string;

function supports(runtime: Runtime, capability: {
    readonly when: Support;
}): boolean;

class CapabilityError extends Error {
    readonly code: CapabilityErrorCode;
    constructor(code: CapabilityErrorCode, message: string);
}

const _default: Readonly<{
    beep: "\u0007";
    image: (data: Uint8Array | string, options?: ImageOptions) => string;
    link: (text: string, url: string) => string;
    setCwd: (cwd?: string) => string;
    cursorTo: (x: number, y?: number) => string;
    cursorMove: (x: number, y?: number) => string;
    cursorUp: (count?: number) => string;
    cursorDown: (count?: number) => string;
    cursorForward: (count?: number) => string;
    cursorBackward: (count?: number) => string;
    cursorLeft: "\u001B[G";
    cursorSavePosition: "\u001B7" | "\u001B[s";
    cursorRestorePosition: "\u001B8" | "\u001B[u";
    cursorGetPosition: "\u001B[6n";
    cursorNextLine: "\u001B[E";
    cursorPrevLine: "\u001B[F";
    cursorHide: "\u001B[?25l";
    cursorShow: "\u001B[?25h";
    eraseEndLine: "\u001B[K";
    eraseStartLine: "\u001B[1K";
    eraseLine: "\u001B[2K";
    eraseDown: "\u001B[J";
    eraseUp: "\u001B[1J";
    eraseScreen: "\u001B[2J";
    scrollUp: "\u001B[S";
    scrollDown: "\u001B[T";
    eraseLines: (count: number) => string;
    clearScreen: "\u001Bc";
    clearViewport: "\u001B[2J\u001B[H";
    clearTerminal: "\u001B[2J\u001B[3J\u001B[H";
    enterAlternativeScreen: "\u001B[?1049h";
    exitAlternativeScreen: "\u001B[?1049l";
    beginSynchronizedOutput: "\u001B[?2026h";
    endSynchronizedOutput: "\u001B[?2026l";
    synchronizedOutput: (text: string) => string;
}>;

const beep = "\u0007";

const bell: Capability;

const builtins: readonly Capability[];

const capabilities: () => string[];

const capability: (name: string) => Capability | undefined;

const clipboard: Capability;

const ConEmu: NotImplemented;

const cwd: Capability;

const DEPRECATED = "deprecated: ";

const image: (data: Uint8Array | string, options?: ImageOptions) => string;

const isDeprecation: (line: string) => boolean;

const iTerm: NotImplemented;

const link: (text: string, url: string) => string;

const notify: Capability;

const processRuntime: () => Runtime;

const refusals: (lines: readonly string[]) => string[];

const reset: () => void;

const setCwd: (cwd?: string) => string;

const title: Capability;

interface AnsiEscapes {
    /** The bell, as a string — the incumbent's `beep`. */
    beep: string;
    /** OSC 8. Projects to `text (url)`. */
    link: (text: string, url: string) => string;
    /** OSC 1337. Projects to `options.caption`. */
    image: (data: Uint8Array | string, options?: ImageOptions) => string;
    /** OSC 50 + OSC 9;9, the two halves upstream concatenates. Projects to nothing. */
    setCwd: (cwd?: string) => string;
}

interface Capability {
    /** How callers name it: `link`, `image`, `clipboard`, or anything a third party invents. */
    readonly name: string;
    /** The OSC code, or `BEL`. Documentation for a reader, and a key for `check`. */
    readonly osc: number | 'BEL';
    readonly when: Support;
    /** The bytes, as a template, for a terminal that does understand. */
    readonly encode: string;
    /**
     * What to print when it does not — PRINCIPLES rule 6, and the reason this package exists.
     * An image becomes its caption, a notification a printed line, a hyperlink `text (url)`.
     * A capability without one is refused at `register`, because a sequence a terminal cannot
     * read is not a feature, it is `]1337;File=inline=1;…` across a user's screen. An empty
     * string is a legitimate projection — a window title has nothing to say in a log — but it
     * has to be written down rather than left out.
     */
    readonly fallback: string;
}

interface ImageOptions {
    /** Cells, pixels (`20px`) or percent (`50%`) — passed through as the incumbent passes it. */
    width?: number | string;
    height?: number | string;
    /** `false` writes `preserveAspectRatio=0`, exactly as upstream does. */
    preserveAspectRatio?: boolean;
    /**
     * What a terminal that cannot draw the image prints instead. paratext's addition, and not
     * optional in spirit: an image with no caption projects to nothing, which is silence where
     * the incumbent would have written bytes nobody can read.
     */
    caption?: string;
}

interface Runtime {
    env: Record<string, string | undefined>;
    /**
     * `stderr` is optional and falls back to `stdout` when absent.
     */
    isTTY: {
        stdout: boolean;
        stderr?: boolean;
    };
    /**
     * The working directory, for the one capability that has to name it.
     */
    cwd?: string;
    /**
     * The command line and the OS, for `paratext/terminal-link` alone: `supports-hyperlinks`
     * reads `--no-hyperlink` / `--color` flags and refuses win32 outside Windows Terminal, and
     * a drop-in that ignored them would link where the incumbent did not. Optional for the
     * reason `cwd` is.
     */
    argv?: readonly string[];
    platform?: string;
    /**
     * The output mode a host that composes has already decided — roundel's `outputMode(rt)`:
     * `tty`, `pipe`, `ci`, `accessible` or `json`. Anything but `tty` is a static projection,
     * so every capability renders its `fallback`, the rule flagstaff's `hoist()` follows.
     */
    mode?: string;
}

interface Support {
    /** Refuse a pipe. Almost always true: a file that receives OSC gets control bytes in it. */
    readonly tty?: boolean;
    /** Any one of these `TERM_PROGRAM` values. */
    readonly termProgram?: readonly string[];
    /** Any one of these environment variables merely being set, as VTE announces itself. */
    readonly envAny?: readonly string[];
    /** An exact `TERM`, for the terminals that identify that way. */
    readonly term?: string;
}

type Fields = Readonly<Record<string, string | undefined>>;

type NotImplemented = undefined;