IF Commons GitHub

surfaces/askpass/terminal

Written to: 2 requirements: 2 proved, 0 partly, 0 failing, 0 with no test recorded. 0011-credential-prompt FR-008, 0011-credential-prompt FR-007

The terminal adapter of the credential port (commons headless 0011-credential-prompt FR-007): it draws a prompt on a terminal, reads the answer with no echo and gives it as a Secret, and is the same for every system because the terminal is a port of its own (TtyPort): what differs between Linux, macOS and Windows is how echo is turned off and which device is read, which is the port's, not the adapter's. Also here, the pure reader that turns the bytes of a terminal into a line (readerStep): backspace, enter, Ctrl-C and Ctrl-D.

The adapter never writes the value anywhere: the prompt goes to the terminal, the answer is read into a string held by the Secret, and a visible answer (confirm) is echoed by the terminal's own rules, not written by the adapter. A person who ends the input (Ctrl-C, Ctrl-D, the end of the stream) has cancelled, and so has an aborted signal.

import { readerStep, START } from "./terminal.ts";
readerStep(readerStep(START, "a").state, "\r").kind; // "line"

Source: commons/headless/src/surfaces/askpass/terminal.ts

7 of 11 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

TtyHandletype
type TtyHandle = { /** Writes text to the terminal (the prompt, and the line break after an answer that was not echoed… (473 characters)
type TtyHandle = {
  /** Writes text to the terminal (the prompt, and the line break after an answer that was not echoed). */
  readonly write: (text: string) => void;
  /** Reads one line, with the echo off for a secret; `undefined` where the person ended the input or the signal was aborted. */
  readonly readLine: (echo: boolean, signal: AbortSignal) => Promise<string | undefined>;
  /** Gives the terminal back (the echo on again). */
  readonly close: () => void;
};

What a terminal is, for the adapter: draw text, read an answer (with the echo on or off), and let go.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

NoTerminaltypeno test imports it
type NoTerminal = { readonly kind: "no-terminal"; readonly why: string };

Why a terminal could not be had.

TtyPorttype
type TtyPort = { readonly open: () => Promise<Result<TtyHandle, NoTerminal>> };

The terminal as a port: opened when a prompt is to be drawn.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

ReaderStatetypeno test imports it
type ReaderState = { readonly typed: string };

The state of the reader: what has been typed.

STARTconst
const START: ReaderState

The start of a line.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

ReaderSteptypeno test imports it
type ReaderStep =
  | { readonly kind: "reading"; readonly state: ReaderState }
  | { readonly kind: "line"; readonly line: string }
  | { readonly kind: "ended" };

What one chunk of bytes did to the line: still reading, a whole line, or the end of the input.

readerStepfunction
function readerStep(state: ReaderState, chunk: string): ReaderStep

The line of a terminal that sends characters as they are typed (raw mode, where the echo is off because nobody writes it): a character is added, backspace (\b, DEL) takes one away, enter (\r, \n) ends the line, and Ctrl-C and Ctrl-D end the input. Pure: the same state and chunk give the same step.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

drawPromptfunction
function drawPrompt(request: CredentialRequest): string

What the adapter writes for a request: the words, and a space after them where they do not end in one.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

terminalCredentialsfunction
function terminalCredentials(tty: TtyPort): CredentialPort

The credential port of a terminal.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

TtyDevicestypeno test imports it
type TtyDevices = {
  /** What is read from when standard input is not a terminal (the controlling terminal). */
  readonly input: string;
  readonly output: string;
  /** How the echo is turned off: by the program `stty` run on the terminal, or by the console's own input mode. */
  readonly echo: "stty" | "console-mode";
};

The devices of a system's terminal and how its echo is turned off: data the system adapter reads, so that the Windows variant is a row and not a branch of the adapter.

ttyDevicesOffunction
function ttyDevicesOf(os: "darwin" | "linux" | "windows"): TtyDevices

The terminal of a system: /dev/tty where there is a controlling terminal, CONIN$ and CONOUT$ on Windows.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.