@tequila99/githuman 0.4.2 → 0.6.0

package/dist/server/services/terminal/backend.js

@@ -0,0 +1,216 @@
+import { spawn } from 'node:child_process';
+import { PromptTracker, TERMINAL_PROMPT_MARKER } from "./prompt-tracker.js";
+import { basename } from 'node:path';
+import { TerminalError } from "../../errors/terminal.js";
+import { classifyProcessActivity, processActivity, signalProcess, terminateProcesses } from "./processes.js";
+// Stop waiting for the first prompt marker after this time.
+const STARTUP_TIMEOUT_MS = 2000;
+// Stop waiting for the first prompt marker after this many output characters.
+const STARTUP_BUFFER_CHARS = 65536;
+// Shells that accept `-l -i` and set the prompt through `PS1`. Other shells get no prompt marker.
+const POSIX_SHELLS = ['bash', 'zsh', 'sh', 'dash', 'ksh'];
+// Windows includes a PTY binary, but the shell and process list are Unix-only.
+export function terminalSupported(platform = process.platform) {
+    return platform !== 'win32';
+}
+function promptPrefix(shellName) {
+    if (shellName === 'bash')
+        return "'\\[\\e]133;A\\a\\]'";
+    if (shellName === 'zsh')
+        return '"%{$(printf \'\\033]133;A\\007\')%}"';
+    return '"$(printf \'\\033]133;A\\007\')"';
+}
+// Bash stores this typed line, so delete that entry before the marker.
+function promptSetup(shellName) {
+    const assign = `PS1=${promptPrefix(shellName)}"$PS1"`;
+    const marker = "printf '\\033]133;A\\007'";
+    if (shellName === 'bash')
+        return `${assign}; history -d $HISTCMD || true; ${marker}`;
+    return `${assign}; ${marker}`;
+}
+async function shellActivity(pid, prompt, rows) {
+    const activity = rows === undefined
+        ? await processActivity(pid)
+        : classifyProcessActivity(rows, pid);
+    if (activity !== 'idle')
+        return activity;
+    return prompt.idle ? 'idle' : 'unknown';
+}
+let modulePromise;
+export function loadPty() {
+    modulePromise ??= import('@lydell/node-pty').catch(() => null);
+    return modulePromise;
+}
+export class NodePtyBackend {
+    mode = 'pty';
+    pty;
+    prompt = new PromptTracker();
+    listeners = new Set();
+    disposeData;
+    startupTimer;
+    constructor(pty, shellName) {
+        this.pty = pty;
+        const integrated = shellName !== undefined && POSIX_SHELLS.includes(shellName);
+        let ready = !integrated;
+        let startup = '';
+        const emit = (data) => {
+            for (const listener of this.listeners)
+                listener(data);
+        };
+        this.disposeData = pty.onData(data => {
+            this.prompt.output(data);
+            if (ready) {
+                emit(data);
+                return;
+            }
+            startup += data;
+            const boundary = startup.indexOf(TERMINAL_PROMPT_MARKER);
+            if (boundary >= 0) {
+                ready = true;
+                emit(startup.slice(boundary));
+                startup = '';
+                clearTimeout(this.startupTimer);
+            }
+            else if (startup.length > STARTUP_BUFFER_CHARS) {
+                ready = true;
+                emit(startup);
+                startup = '';
+                clearTimeout(this.startupTimer);
+            }
+        });
+        if (integrated) {
+            this.startupTimer = setTimeout(() => {
+                ready = true;
+                emit(startup);
+                startup = '';
+            }, STARTUP_TIMEOUT_MS);
+            this.startupTimer.unref();
+            // Preserve the user's prompt and add an invisible activity marker.
+            if (shellName !== undefined)
+                pty.write(`${promptSetup(shellName)}\r`);
+        }
+    }
+    get pid() {
+        return this.pty.pid;
+    }
+    write(data) {
+        this.prompt.input();
+        this.pty.write(data);
+    }
+    resize(cols, rows) {
+        this.pty.resize(cols, rows);
+    }
+    pause() {
+        this.pty.pause();
+    }
+    resume() {
+        this.pty.resume();
+    }
+    interrupt() {
+        this.write('\x03');
+    }
+    activity(rows) {
+        return shellActivity(this.pid, this.prompt, rows);
+    }
+    async kill() {
+        clearTimeout(this.startupTimer);
+        await terminateProcesses(this.pid);
+        this.disposeData.dispose();
+        this.listeners.clear();
+    }
+    onData(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    onExit(listener) {
+        const disposable = this.pty.onExit(listener);
+        return () => disposable.dispose();
+    }
+}
+export class PipeBackend {
+    mode = 'pipe';
+    prompt = new PromptTracker();
+    child;
+    dataListeners = new Set();
+    exitListeners = new Set();
+    constructor(cwd) {
+        // Merge both output descriptors so prompts cannot overtake stdout.
+        this.child = spawn('/bin/sh', ['-c', 'exec /bin/sh -i 2>&1'], {
+            cwd,
+            detached: true,
+            env: {
+                ...process.env,
+                TERM: 'dumb',
+                FORCE_COLOR: '1',
+                CLICOLOR_FORCE: '1',
+                PS1: TERMINAL_PROMPT_MARKER + '$ '
+            },
+            stdio: ['pipe', 'pipe', 'pipe']
+        });
+        this.child.stdout.setEncoding('utf8');
+        this.child.stdout.on('data', (data) => {
+            this.prompt.output(data);
+            for (const listener of this.dataListeners)
+                listener(data.replace(/\n/g, '\r\n'));
+        });
+        this.child.on('error', () => {
+            for (const listener of this.exitListeners)
+                listener();
+        });
+        this.child.on('exit', () => {
+            for (const listener of this.exitListeners)
+                listener();
+        });
+        this.child.stdin.on('error', () => { });
+    }
+    get pid() {
+        return this.child.pid ?? 0;
+    }
+    write(data) {
+        this.prompt.input();
+        this.child.stdin.write(data);
+    }
+    resize() { }
+    pause() {
+        this.child.stdout.pause();
+    }
+    resume() {
+        this.child.stdout.resume();
+    }
+    interrupt() {
+        if (this.pid > 1)
+            signalProcess(-this.pid, 'SIGINT');
+    }
+    activity(rows) {
+        return shellActivity(this.pid, this.prompt, rows);
+    }
+    async kill() {
+        if (this.pid > 1)
+            await terminateProcesses(this.pid);
+    }
+    onData(listener) {
+        this.dataListeners.add(listener);
+        return () => this.dataListeners.delete(listener);
+    }
+    onExit(listener) {
+        this.exitListeners.add(listener);
+        return () => this.exitListeners.delete(listener);
+    }
+}
+export async function createBackend(cwd, cols, rows) {
+    if (!terminalSupported())
+        throw new TerminalError('The terminal is not available on Windows.');
+    const module = await loadPty();
+    if (!module)
+        return new PipeBackend(cwd);
+    const shell = process.env.SHELL || '/bin/sh';
+    const args = POSIX_SHELLS.includes(basename(shell)) ? ['-l', '-i'] : ['-i'];
+    const pty = module.spawn(shell, args, {
+        cwd,
+        cols,
+        rows,
+        name: 'xterm-256color',
+        env: { ...process.env, TERM: 'xterm-256color', COLORTERM: 'truecolor' }
+    });
+    return new NodePtyBackend(pty, basename(shell));
+}

package/dist/server/services/terminal/channel.js

@@ -0,0 +1,200 @@
+import { Value } from '@sinclair/typebox/value';
+import { TerminalClientMessageSchema } from "../../../shared/terminal/schemas.js";
+import { TERMINAL_CLIENT_BYTES } from "../../../shared/terminal/constants.js";
+import { errorMessage } from "../../../shared/utils/error-message.js";
+// Close the connection when a client queues more commands than it can need.
+const MAX_PENDING_COMMANDS = 128;
+// Disconnect a client that stays blocked for this long.
+const SLOW_CLIENT_MS = 5000;
+// Block the output of a session when a client holds this much unacknowledged data.
+const CREDIT_PAUSE_BYTES = TERMINAL_CLIENT_BYTES / 16;
+export class TerminalChannel {
+    subscribed = new Set();
+    subscribing = new Set();
+    credit = new Map();
+    unsubscribe;
+    stopped = false;
+    commands = Promise.resolve();
+    pendingCommands = 0;
+    registry;
+    send;
+    disconnect;
+    slowClientMs;
+    constructor(registry, send, disconnect, slowClientMs = SLOW_CLIENT_MS) {
+        this.registry = registry;
+        this.send = send;
+        this.disconnect = disconnect;
+        this.slowClientMs = slowClientMs;
+        this.unsubscribe = registry.subscribe(message => this.event(message));
+        send({ type: 'list', sessions: registry.list });
+    }
+    receive(value) {
+        if (!Value.Check(TerminalClientMessageSchema, value)) {
+            this.disconnect();
+            return;
+        }
+        if (++this.pendingCommands > MAX_PENDING_COMMANDS) {
+            this.disconnect();
+            return;
+        }
+        this.commands = this.commands
+            .then(async () => {
+            if (this.stopped)
+                return undefined;
+            try {
+                switch (value.type) {
+                    case 'create': {
+                        const session = await this.registry.create(value.cols, value.rows);
+                        if (!this.stopped)
+                            this.send({
+                                type: 'created',
+                                requestId: value.requestId,
+                                terminalId: session.id
+                            });
+                        break;
+                    }
+                    case 'subscribe':
+                        await this.attach(value.terminalId);
+                        break;
+                    case 'snapshot':
+                        await this.snapshot(value.terminalId);
+                        break;
+                    case 'input':
+                        this.registry.get(value.terminalId).write(value.data);
+                        break;
+                    case 'line':
+                        this.registry.get(value.terminalId).line(value.data);
+                        break;
+                    case 'signal':
+                        this.registry.get(value.terminalId).signal(value.signal);
+                        break;
+                    case 'resize':
+                        await this.registry.resize(value.terminalId, value.cols, value.rows);
+                        break;
+                    case 'close':
+                        await this.registry.close(value.terminalId);
+                        break;
+                    case 'ack':
+                        this.ack(value.terminalId, value.sequence);
+                        break;
+                    case 'ping':
+                        this.send({ type: 'pong' });
+                        break;
+                }
+            }
+            catch (error) {
+                if (!this.stopped)
+                    this.send({
+                        type: 'error',
+                        ...('requestId' in value ? { requestId: value.requestId } : {}),
+                        code: 'GHT_TERMINAL',
+                        message: errorMessage(error)
+                    });
+            }
+            return undefined;
+        })
+            .finally(() => {
+            this.pendingCommands--;
+        });
+    }
+    async attach(id) {
+        if (this.subscribed.has(id) || this.subscribing.has(id))
+            return;
+        this.subscribing.add(id);
+        try {
+            this.registry.attach(id, this);
+            await this.snapshot(id);
+        }
+        finally {
+            this.subscribing.delete(id);
+        }
+    }
+    async snapshot(id) {
+        const session = this.registry.get(id);
+        await session.snapshot(message => {
+            if (this.stopped)
+                return undefined;
+            clearTimeout(this.credit.get(id)?.timeout);
+            session.block(this, false);
+            this.credit.set(id, {
+                bytes: 0,
+                frames: new Map(),
+                lastSequence: message.type === 'snapshot' ? message.sequence : 0
+            });
+            this.subscribed.add(id);
+            this.send(message);
+            return undefined;
+        });
+    }
+    ack(id, sequence) {
+        const credit = this.credit.get(id);
+        if (!credit)
+            return;
+        if (sequence > credit.lastSequence) {
+            this.disconnect();
+            return;
+        }
+        for (const [key, bytes] of credit.frames)
+            if (key <= sequence) {
+                credit.bytes -= bytes;
+                credit.frames.delete(key);
+            }
+        this.flow(id, credit);
+    }
+    flow(id, credit) {
+        if (credit.bytes > CREDIT_PAUSE_BYTES) {
+            this.registry.get(id).block(this, true);
+            credit.timeout ??= setTimeout(() => this.disconnect(), this.slowClientMs);
+        }
+        else {
+            clearTimeout(credit.timeout);
+            credit.timeout = undefined;
+            this.registry.get(id).block(this, false);
+        }
+    }
+    event(message) {
+        if (this.stopped)
+            return undefined;
+        if (message.type === 'output') {
+            if (!this.subscribed.has(message.terminalId))
+                return;
+            const credit = this.credit.get(message.terminalId);
+            if (!credit)
+                return;
+            const bytes = Buffer.byteLength(message.data);
+            credit.bytes += bytes;
+            credit.frames.set(message.sequence, bytes);
+            credit.lastSequence = message.sequence;
+            this.flow(message.terminalId, credit);
+            if (credit.bytes > TERMINAL_CLIENT_BYTES) {
+                this.disconnect();
+                return;
+            }
+        }
+        else if (message.type === 'exit') {
+            clearTimeout(this.credit.get(message.terminalId)?.timeout);
+            this.subscribed.delete(message.terminalId);
+            this.credit.delete(message.terminalId);
+        }
+        this.send(message);
+    }
+    dispose() {
+        if (this.stopped)
+            return undefined;
+        this.stopped = true;
+        for (const [id, credit] of this.credit) {
+            clearTimeout(credit.timeout);
+            try {
+                this.registry.get(id).block(this, false);
+            }
+            catch {
+                /* The session already exited. */
+            }
+        }
+        this.unsubscribe();
+        this.registry.detach(this);
+        this.subscribed.clear();
+        this.subscribing.clear();
+        this.credit.clear();
+    }
+}

package/dist/server/services/terminal/escape-tail.js

@@ -0,0 +1,93 @@
+// Drop an unfinished control string that is too long to keep for a snapshot.
+const MAX_ESCAPE_TAIL = 8192;
+export class EscapeTail {
+    // text: no sequence is open. escape: after ESC. csi: control sequence, ends with a final byte.
+    // string: OSC, DCS, PM or APC data, ends with BEL or ST. string-escape: after ESC inside a string.
+    state = 'text';
+    value = '';
+    get tail() {
+        return this.value;
+    }
+    push(data) {
+        for (const char of data) {
+            // 8-bit CSI (U+009B) starts a control sequence in any state.
+            if (char === '\u009b') {
+                this.state = 'csi';
+                this.value = char;
+                continue;
+            }
+            // 8-bit OSC, DCS, SOS, PM and APC start a control string in any state.
+            if (['\u009d', '\u0090', '\u0098', '\u009e', '\u009f'].includes(char)) {
+                this.state = 'string';
+                this.value = char;
+                continue;
+            }
+            if (this.state === 'text') {
+                // ESC opens a new sequence. Other text is not part of the tail.
+                if (char === '\x1b') {
+                    this.state = 'escape';
+                    this.value = char;
+                }
+                continue;
+            }
+            this.value += char;
+            // A long OSC, DCS or APC string must not close the shell.
+            if (this.value.length > MAX_ESCAPE_TAIL) {
+                this.reset();
+                continue;
+            }
+            // CAN and SUB cancel the open sequence.
+            if (char === '\x18' || char === '\x1a') {
+                this.reset();
+                continue;
+            }
+            if (this.state === 'escape') {
+                if (char === '[') {
+                    // ESC [ starts a control sequence.
+                    this.state = 'csi';
+                }
+                else if (']PX^_'.includes(char)) {
+                    // ESC ] P X ^ _ start OSC, DCS, SOS, PM and APC strings.
+                    this.state = 'string';
+                }
+                else if (char >= '0' && char <= '~') {
+                    // A final byte ends a short escape sequence, for example ESC 7.
+                    this.reset();
+                }
+            }
+            else if (this.state === 'csi') {
+                if (char >= '@' && char <= '~') {
+                    // A final byte ends the control sequence.
+                    this.reset();
+                }
+                else if (char === '\x1b') {
+                    // ESC aborts the control sequence and opens a new one.
+                    this.state = 'escape';
+                    this.value = char;
+                }
+            }
+            else if (this.state === 'string') {
+                if (char === '\x07' || char === '\u009c') {
+                    // BEL or 8-bit ST ends the string.
+                    this.reset();
+                }
+                else if (char === '\x1b') {
+                    // ESC can start the two-character ST (ESC \).
+                    this.state = 'string-escape';
+                }
+            }
+            else if (char === '\\') {
+                // ESC \ is ST: it ends the string.
+                this.reset();
+            }
+            else {
+                // ESC with any other character is part of the string data.
+                this.state = 'string';
+            }
+        }
+    }
+    reset() {
+        this.state = 'text';
+        this.value = '';
+    }
+}

package/dist/server/services/terminal/processes.js

@@ -0,0 +1,115 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+// Give processes time to react to SIGHUP before SIGKILL.
+const TERMINATE_GRACE_MS = 200;
+// A slow `ps` must not block the caller. The caller treats a timeout as unknown.
+const PS_TIMEOUT_MS = 2000;
+// Bound the memory for the `ps` output on a host with many processes.
+const PS_MAX_BUFFER_BYTES = 4 * 1024 * 1024;
+// PID 1 is init. PID 0 and -1 make kill() reach many processes. Never signal them.
+const INIT_PID = 1;
+// Share the Node callback adapter without starting a shell.
+const execute = promisify(execFile);
+export async function processes() {
+    const { stdout } = await execute('ps', ['-axo', 'pid=,ppid=,pgid='], {
+        timeout: PS_TIMEOUT_MS,
+        maxBuffer: PS_MAX_BUFFER_BYTES
+    });
+    return stdout
+        .trim()
+        .split('\n')
+        .map(line => {
+        const [pid, parent, group] = line.trim().split(/\s+/).map(Number);
+        return { pid, parent, group };
+    })
+        .filter(row => Number.isInteger(row.pid) &&
+        Number.isInteger(row.parent) &&
+        Number.isInteger(row.group) &&
+        row.pid > 0);
+}
+// Returns the process and its descendants, each parent before its children.
+// One pass over a parent-to-children map keeps the cost linear.
+export function descendants(rows, pid) {
+    const byPid = new Map();
+    const children = new Map();
+    for (const row of rows) {
+        byPid.set(row.pid, row);
+        const siblings = children.get(row.parent);
+        if (siblings) {
+            siblings.push(row.pid);
+        }
+        else {
+            children.set(row.parent, [row.pid]);
+        }
+    }
+    // The queue grows while the loop reads it: this is a breadth-first walk.
+    const order = [pid];
+    const seen = new Set(order);
+    for (const id of order) {
+        for (const child of children.get(id) ?? []) {
+            if (seen.has(child))
+                continue;
+            seen.add(child);
+            order.push(child);
+        }
+    }
+    return order.flatMap(id => byPid.get(id) ?? []);
+}
+export function classifyProcessActivity(rows, pid) {
+    if (!rows.some(row => row.pid === pid))
+        return 'unknown';
+    return descendants(rows, pid).some(row => row.pid !== pid)
+        ? 'running'
+        : 'idle';
+}
+export async function processActivity(pid) {
+    try {
+        return classifyProcessActivity(await processes(), pid);
+    }
+    catch {
+        return 'unknown';
+    }
+}
+export function signalProcess(pid, signal) {
+    // PID 0 and -1 would reach the server's own group or every process of the user.
+    if (!Number.isInteger(pid) || Math.abs(pid) <= INIT_PID)
+        return;
+    try {
+        process.kill(pid, signal);
+    }
+    catch {
+        /* The process may have exited before the signal. */
+    }
+}
+export async function terminateProcesses(pid) {
+    if (!Number.isInteger(pid) || pid <= INIT_PID)
+        return;
+    // One snapshot keeps the targets and the group owners consistent.
+    let all = [];
+    try {
+        all = await processes();
+    }
+    catch {
+        /* The backend still terminates its shell. */
+    }
+    const targets = descendants(all, pid);
+    const ids = new Set(targets.map(row => row.pid));
+    // Only signal groups that are wholly owned by this shell tree.
+    const groups = [
+        ...new Set(targets.map(row => row.group).filter(group => group > INIT_PID))
+    ].filter(group => all.filter(row => row.group === group).every(row => ids.has(row.pid)));
+    // oxlint-disable-next-line unicorn/no-array-reverse -- the type-aware checker lacks toReversed in this module
+    const childrenFirst = targets.slice().reverse();
+    const signalAll = (signal) => {
+        // A group also reaches a child that started after the snapshot.
+        for (const group of groups)
+            signalProcess(-group, signal);
+        for (const row of childrenFirst)
+            signalProcess(row.pid, signal);
+        signalProcess(pid, signal);
+    };
+    signalAll('SIGHUP');
+    await new Promise(resolve => setTimeout(resolve, TERMINATE_GRACE_MS));
+    // A PID can be reused in the grace time. The risk is accepted: PIDs wrap slowly.
+    signalAll('SIGKILL');
+}

package/dist/server/services/terminal/prompt-tracker.js

@@ -0,0 +1,15 @@
+// OSC 133 marks a prompt without adding visible characters.
+export const TERMINAL_PROMPT_MARKER = '\x1b]133;A\x07';
+export class PromptTracker {
+    idle = false;
+    tail = '';
+    input() {
+        this.idle = false;
+    }
+    output(data) {
+        const combined = this.tail + data;
+        if (combined.includes(TERMINAL_PROMPT_MARKER))
+            this.idle = true;
+        this.tail = combined.slice(-(TERMINAL_PROMPT_MARKER.length - 1));
+    }
+}