toolroll 0.9.63 → 0.9.67

package/dist/live-terminal.d.ts

@@ -0,0 +1,269 @@
+import { type Git } from "./teardown-git.js";
+export type TerminalProgram = "claude" | "codex" | "shell";
+export declare const TERMINAL_PROGRAMS: readonly TerminalProgram[];
+/** At most this many running sessions per console, and this many kept at all (ended ones count until removed). */
+export declare const MAX_LIVE_TERMINALS = 8;
+export declare const MAX_KEPT_TERMINALS = 16;
+/** At most this many pages attached to one session (a desktop, a phone, a spare tab or two). */
+export declare const MAX_VIEWERS = 4;
+/** After SIGHUP, the terminal's processes have this long before SIGKILL. */
+export declare const CLOSE_GRACE_MS = 2000;
+/** Typed input not yet read by the program, per terminal: past this, more is refused until it reads. */
+export declare const MAX_PENDING_INPUT: number;
+/** How often a running terminal's processes are noted, so ones that outlive their parent are still known. */
+export declare const CUSTODY_REFRESH_MS = 5000;
+export declare const COLS: {
+    readonly min: 2;
+    readonly max: 500;
+};
+export declare const ROWS: {
+    readonly min: 1;
+    readonly max: 200;
+};
+/** The slice of node-pty this module uses, so tests can stand a fake in. */
+export type Pty = {
+    readonly pid: number;
+    /** The terminal device its processes have as their controlling terminal ("ttys012", "pts/3"); null when unknown. */
+    readonly tty: string | null;
+    /** Typed bytes queued for the program and not yet taken by the kernel; Infinity when it can't be measured. */
+    pendingInput(): number;
+    onData(listener: (data: string) => void): unknown;
+    onExit(listener: (exit: {
+        exitCode: number;
+        signal?: number;
+    }) => void): unknown;
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    kill(signal?: string): void;
+};
+export type PtySpawn = (file: string, args: string[], options: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    cols: number;
+    rows: number;
+}) => Pty;
+/** A device path as `ps` prints it: /dev/ttys012 → ttys012, /dev/pts/3 → pts/3. */
+export declare const ttyName: (path: unknown) => string | null;
+/**
+ * node-pty's write queue (@lydell/node-pty 1.2.0-beta.15, pinned exactly): typed input waits in its
+ * `_writeStream._writeQueue` until the kernel takes it. A shape this doesn't recognise is unmeasurable: Infinity, so
+ * input is refused rather than queued without bound (a test pins the shape against the installed package).
+ */
+export declare function pendingInputOf(pty: unknown): number;
+/** node-pty, if this install has it (an optional dependency with prebuilt binaries); null when it doesn't load. */
+export declare function loadPtySpawn(): PtySpawn | null;
+/** How many lines above the screen a terminal keeps for a page that attaches later. */
+export declare const SCREEN_SCROLLBACK_LINES = 5000;
+/**
+ * The terminal as a page would see it now: every byte the program writes is parsed by a headless xterm here, so a page
+ * that attaches later gets the screen, its scrollback and its modes (the alternate screen of a full-screen program, the
+ * cursor, colours, bracketed paste, mouse reporting) — never a replay of raw output cut at an arbitrary byte, which
+ * could split an escape sequence or redraw a full-screen program garbled.
+ */
+export declare class ScreenMirror {
+    private readonly lines;
+    private readonly terminal;
+    private readonly serializer;
+    constructor(cols: number, rows: number, lines?: number);
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    /** The screen as of this call (after everything written before it), handed to `done` once parsed. */
+    snapshot(done: (screen: string) => void): void;
+    dispose(): void;
+}
+/** One attached page. The host never waits on it. */
+export type TerminalViewer = {
+    output(data: Buffer): void;
+    control(message: TerminalControl): void;
+};
+export type TerminalControl = {
+    t: "hello";
+    cols: number;
+    rows: number;
+    program: TerminalProgram;
+    ended: boolean;
+} | {
+    t: "exit";
+    code: number | null;
+    signal: number | null;
+}
+/** The program isn't reading what's typed: input waits until it does. */
+ | {
+    t: "input-full";
+};
+export type TerminalSummary = {
+    id: string;
+    owner: string;
+    /** The owner's account generation at start: a rotated credential or a re-sign-in elsewhere no longer reaches it. */
+    generation: number;
+    repo: string;
+    program: TerminalProgram;
+    branch: string;
+    worktree: string;
+    startedAt: string;
+    endedAt: string | null;
+    exit: {
+        code: number | null;
+        signal: number | null;
+    } | null;
+    /** Who ended it, when Toolroll did. */
+    endedBy: "owner" | "console" | null;
+    /**
+     * After it ends: "clean" once every process known to be its own is proved gone; "uncertain" when one outlived
+     * SIGKILL or the process table couldn't be read. Null while it runs or is being swept.
+     */
+    cleanup: "clean" | "uncertain" | null;
+};
+/**
+ * Where a console's terminals are written down for the updater, which runs as another process (terminal-catalog.ts):
+ * a start is reserved before any work and refused while an update owns admission; a program is running until its
+ * sweep ends. The default keeps nothing (tests, a console without a database file).
+ */
+export type TerminalLedger = {
+    /** Throws (with the reason in words) when no terminal may start now. */
+    reserve(id: string): void;
+    running(id: string): void;
+    release(id: string, cleanup: "clean" | "uncertain" | null): void;
+    /** The terminal is removed (its worktree went after a clean sweep): nothing of it is left to count. */
+    forget(id: string): void;
+};
+export declare class TerminalError extends Error {
+    constructor(message: string);
+}
+export type TerminalHostOptions = {
+    spawn: PtySpawn;
+    worktreeRoot: string;
+    /** Git for making and removing worktrees: hardened by default (teardown-git.ts), since a build can write .git/config. */
+    git?: Git;
+    /** How each program starts; the default looks up `claude`, `codex` and the login shell on PATH. */
+    programs?: Partial<Record<TerminalProgram, {
+        file: string;
+        args: string[];
+    }>>;
+    env?: () => NodeJS.ProcessEnv;
+    clock?: () => Date;
+    /** Start, close and remove, for the event log (never input or output). */
+    record?: (event: "start" | "close" | "remove" | "exit", session: TerminalSummary) => void;
+    maxSessions?: number;
+    /** Lines above the screen a terminal keeps for a page that attaches later (SCREEN_SCROLLBACK_LINES). */
+    scrollbackLines?: number;
+    closeGraceMs?: number;
+    ledger?: TerminalLedger;
+    /** The process table (tests stand a failing one in); null when it can't be read. */
+    processes?: () => ProcessTable | null;
+    /** Who else works in a worktree (tests stand theirs in); default worktreeResidents. */
+    residents?: (table: ProcessTable, worktreeReal: string, terminalStartedMs: number) => Set<number> | null;
+};
+/** The executable on PATH, or null. */
+export declare function onPath(name: string, env?: NodeJS.ProcessEnv): string | null;
+export declare class TerminalHost {
+    private readonly options;
+    private readonly sessions;
+    private starting;
+    private stopped;
+    private readonly clock;
+    private readonly env;
+    private readonly ledger;
+    private readonly processes;
+    private custodyTimer;
+    constructor(options: TerminalHostOptions);
+    private summary;
+    /** This person's sessions, newest first. */
+    list(owner: string): TerminalSummary[];
+    get(id: string): TerminalSummary | null;
+    private running;
+    /**
+     * Make the worktree and start the program in it. `admit` is asked again right before the program starts (after the
+     * slow git work): a person whose access or project went in between starts nothing.
+     */
+    start({ name: owner, generation }: {
+        name: string;
+        generation: number;
+    }, repoPath: string, program: TerminalProgram, size?: {
+        cols: number;
+        rows: number;
+    }, admit?: () => string | null): Promise<TerminalSummary>;
+    /**
+     * Attach a page: it gets the screen as it is now (ScreenMirror), then `hello`, then live output — what the program
+     * writes meanwhile is held and sent after the screen, in order. Returns its detach.
+     */
+    attach(id: string, viewer: TerminalViewer): () => void;
+    /** How many pages are attached now. */
+    viewerCount(id: string): number;
+    /** Type into the program. False (nothing queued) while it has MAX_PENDING_INPUT unread, or can't be measured. */
+    input(id: string, data: string): boolean;
+    resize(id: string, cols: number, rows: number): void;
+    private noteTimer;
+    /** Activity (output, typing) usually means a command started: note processes shortly after, at most every 250 ms. */
+    private noteSoon;
+    /** Note every running terminal's processes now, and keep doing so while any runs. */
+    private noteCustody;
+    /**
+     * End the program and everything that is its own: SIGHUP to every member (an interactive shell gives each job its own
+     * process group, so the leader's group is not enough), then SIGKILL, re-reading the process table each time so a
+     * child started during the close is caught too. Membership is the leader's descendants, every process with this
+     * terminal as its controlling terminal (started before the program ended), and every one noted while it ran, by pid
+     * and start time. A process that detached itself from the terminal AND its parents before it was noted is not seen —
+     * the same as any terminal. Resolves when the sweep is done; never waits without bound.
+     */
+    close(id: string, by?: "owner" | "console"): Promise<void>;
+    private sweep;
+    /** Drop an ended session and its worktree (the branch stays: the work is there). Only after a clean sweep. */
+    remove(id: string): Promise<void>;
+    /** Whether new sessions may start (false once the console is stopping). */
+    get admitting(): boolean;
+    /**
+     * The console is stopping: admit nothing more, end every program, and wait (each sweep is bounded) for them.
+     * `clean` is false when any terminal's processes couldn't be proved gone.
+     */
+    stop(): Promise<{
+        clean: boolean;
+    }>;
+}
+/** One process: its parent, owner, controlling terminal and start time. */
+export type ProcessTable = Map<number, {
+    ppid: number;
+    uid: number;
+    tty: string;
+    started: string;
+}>;
+/** Every process from `ps` (macOS and Linux take these options); null when it can't be read, never an empty guess. */
+export declare function readProcessTable(): ProcessTable | null;
+/**
+ * A terminal's processes in this table, by pid and start time: what was noted while it ran (still the same process),
+ * the leader, everything whose controlling terminal is its terminal and that started before it ended (a later process
+ * on a reused device is someone else's), and every descendant of those. Never this console itself.
+ */
+export declare function membersOf(table: ProcessTable, session: {
+    leader: number;
+    tty: string | null;
+    known: ReadonlyMap<number, string>;
+    exitedAt: number | null;
+}): Map<number, string>;
+/**
+ * Each listed process's working directory (Linux: /proc; macOS: lsof), and which ones couldn't be read (a setgid
+ * helper such as ssh-agent is unreadable even to its own user). Null when the lookup itself failed: a timeout, a signal
+ * or partial output is never a smaller answer. A process gone in between is simply absent.
+ */
+export declare function cwdsOf(pids: readonly number[]): {
+    cwds: Map<number, string>;
+    unreadable: number[];
+} | null;
+/**
+ * This user's processes working inside a terminal's worktree, whoever started them. They are never signalled (one may
+ * be the person's own shell or a server they started from elsewhere); while any remains, the terminal's cleanup is
+ * uncertain and its worktree stays. Null when that can't be known: the lookup failed, or a process whose working
+ * directory can't be read started after the terminal did (one from before — a login's ssh-agent — can't be its own).
+ */
+export declare function worktreeResidents(table: ProcessTable, worktreeReal: string, terminalStartedMs?: number): Set<number> | null;
+/** One client frame, read strictly; null closes the socket. */
+export type TerminalInput = {
+    t: "in";
+    d: string;
+} | {
+    t: "resize";
+    cols: number;
+    rows: number;
+};
+export declare const MAX_FRAME_BYTES: number;
+export declare function parseTerminalFrame(text: string): TerminalInput | null;