@tequila99/githuman 0.4.1 → 0.5.0

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

@@ -0,0 +1,238 @@
+import headless from '@xterm/headless';
+import { SerializeAddon } from '@xterm/addon-serialize';
+import { TERMINAL_SCROLLBACK, TERMINAL_QUEUE_BYTES, TERMINAL_SNAPSHOT_BYTES, TERMINAL_FRAME_BYTES, TERMINAL_TITLE_LENGTH } from "../../../shared/terminal/constants.js";
+import { EscapeTail } from "./escape-tail.js";
+import { TerminalError } from "../../errors/terminal.js";
+// Join output that arrives within one display frame (about 60 Hz) into one write.
+const FLUSH_DELAY_MS = 16;
+// One UTF-16 unit takes up to 3 UTF-8 bytes. A divisor of 4 keeps a part below the frame limit.
+const FRAME_PART_UNITS = TERMINAL_FRAME_BYTES / 4;
+// Close the session when the parser queue grows to twice the pause limit.
+const QUEUE_CLOSE_BYTES = TERMINAL_QUEUE_BYTES * 2;
+// Resume the backend only after the parser queue falls well below the pause limit.
+const QUEUE_RESUME_BYTES = TERMINAL_QUEUE_BYTES / 4;
+// A high surrogate starts a pair. A part must not end after it.
+const HIGH_SURROGATE_FIRST = 0xd800;
+const HIGH_SURROGATE_LAST = 0xdbff;
+export class TerminalSession {
+    terminal;
+    serializer;
+    tail = new EscapeTail();
+    queue = Promise.resolve();
+    pendingBytes = 0;
+    staged = '';
+    flushTimer;
+    blocked = new Set();
+    sequence = 0;
+    stopped = false;
+    disposers = [];
+    title;
+    cols;
+    rows;
+    running = 'unknown';
+    id;
+    backend;
+    publish;
+    onExit;
+    constructor(id, title, backend, cols, rows, publish, onExit) {
+        this.id = id;
+        this.backend = backend;
+        this.publish = publish;
+        this.onExit = onExit;
+        this.title = title;
+        this.cols = cols;
+        this.rows = rows;
+        this.terminal = new headless.Terminal({
+            cols,
+            rows,
+            scrollback: TERMINAL_SCROLLBACK,
+            allowProposedApi: true
+        });
+        this.serializer = new SerializeAddon();
+        this.terminal.loadAddon(this.serializer);
+        this.disposers.push(backend.onData(data => this.output(data)), backend.onExit(onExit));
+        // Only the server answers terminal queries, even with multiple browsers.
+        this.disposers.push(() => this.terminal.dispose());
+        this.terminal.onData(data => {
+            if (!this.stopped && backend.mode === 'pty')
+                backend.write(data);
+        });
+        this.terminal.onTitleChange(shellTitle => {
+            this.title = shellTitle.slice(0, TERMINAL_TITLE_LENGTH);
+            publish({ type: 'title', terminalId: id, title: this.title });
+        });
+    }
+    get info() {
+        return {
+            id: this.id,
+            title: this.title,
+            cols: this.cols,
+            rows: this.rows,
+            mode: this.backend.mode,
+            running: this.running
+        };
+    }
+    output(data) {
+        if (this.stopped)
+            return;
+        this.staged += data;
+        if (Buffer.byteLength(this.staged) >= TERMINAL_FRAME_BYTES) {
+            this.flush();
+        }
+        else {
+            this.flushTimer ??= setTimeout(() => this.flush(), FLUSH_DELAY_MS);
+        }
+    }
+    flush() {
+        clearTimeout(this.flushTimer);
+        this.flushTimer = undefined;
+        const data = this.staged;
+        this.staged = '';
+        if (data)
+            this.enqueue(data);
+    }
+    enqueue(data) {
+        if (this.stopped)
+            return undefined;
+        // Bound each frame by UTF-8 bytes without splitting a surrogate pair.
+        for (let offset = 0; offset < data.length;) {
+            let end = Math.min(data.length, offset + FRAME_PART_UNITS);
+            if (end < data.length &&
+                data.charCodeAt(end - 1) >= HIGH_SURROGATE_FIRST &&
+                data.charCodeAt(end - 1) <= HIGH_SURROGATE_LAST)
+                end--;
+            const part = data.slice(offset, end);
+            offset = end;
+            const bytes = Buffer.byteLength(part);
+            this.pendingBytes += bytes;
+            if (this.pendingBytes > TERMINAL_QUEUE_BYTES)
+                this.updateFlow();
+            if (this.pendingBytes > QUEUE_CLOSE_BYTES) {
+                this.onExit();
+                return;
+            }
+            this.queue = this.queue
+                .then(async () => {
+                if (this.stopped)
+                    return undefined;
+                this.tail.push(part);
+                await new Promise(resolve => this.terminal.write(part, resolve));
+                this.sequence++;
+                this.publish({
+                    type: 'output',
+                    terminalId: this.id,
+                    data: part,
+                    cols: this.cols,
+                    rows: this.rows,
+                    sequence: this.sequence
+                });
+                return undefined;
+            })
+                .catch(() => this.onExit())
+                .finally(() => {
+                this.pendingBytes -= bytes;
+                if (!this.stopped && this.pendingBytes < QUEUE_RESUME_BYTES)
+                    this.updateFlow();
+            });
+        }
+    }
+    block(owner, blocked) {
+        if (blocked) {
+            this.blocked.add(owner);
+        }
+        else {
+            this.blocked.delete(owner);
+        }
+        this.updateFlow();
+    }
+    updateFlow() {
+        if (this.stopped)
+            return;
+        if (this.blocked.size || this.pendingBytes > TERMINAL_QUEUE_BYTES) {
+            this.backend.pause();
+        }
+        else {
+            this.backend.resume();
+        }
+    }
+    snapshot(send) {
+        this.flush();
+        this.queue = this.queue.then(() => {
+            if (this.stopped)
+                return undefined;
+            let scrollback = TERMINAL_SCROLLBACK;
+            let data = this.serializer.serialize({ scrollback }) + this.tail.tail;
+            while (Buffer.byteLength(data) > TERMINAL_SNAPSHOT_BYTES &&
+                scrollback > 0) {
+                scrollback = Math.floor(scrollback / 2);
+                data = this.serializer.serialize({ scrollback }) + this.tail.tail;
+            }
+            if (Buffer.byteLength(data) > TERMINAL_SNAPSHOT_BYTES)
+                throw new TerminalError('Terminal snapshot exceeds its limit.');
+            send({
+                type: 'snapshot',
+                terminalId: this.id,
+                data,
+                cols: this.cols,
+                rows: this.rows,
+                sequence: this.sequence
+            });
+            return undefined;
+        });
+        return this.queue;
+    }
+    write(data) {
+        if (!this.stopped)
+            this.backend.write(data);
+    }
+    line(data) {
+        if (this.backend.mode !== 'pipe')
+            throw new TerminalError('Line input requires limited mode.');
+        this.output(data.replace(/\n/g, '\r\n') + '\r\n');
+        this.backend.write(data + '\n');
+    }
+    signal(signal) {
+        if (signal === 'interrupt') {
+            this.backend.interrupt();
+        }
+        else {
+            this.onExit();
+        }
+    }
+    resize(cols, rows) {
+        this.flush();
+        this.queue = this.queue
+            .then(() => {
+            if (this.stopped || (cols === this.cols && rows === this.rows))
+                return undefined;
+            this.backend.resize(cols, rows);
+            this.terminal.resize(cols, rows);
+            this.cols = cols;
+            this.rows = rows;
+            // Order geometry changes with output so every viewer parses the same screen.
+            this.sequence++;
+            this.publish({
+                type: 'output',
+                terminalId: this.id,
+                data: '',
+                cols,
+                rows,
+                sequence: this.sequence
+            });
+            return undefined;
+        })
+            .catch(() => this.onExit());
+        return this.queue;
+    }
+    async dispose() {
+        if (this.stopped)
+            return undefined;
+        this.stopped = true;
+        clearTimeout(this.flushTimer);
+        this.staged = '';
+        await this.backend.kill();
+        await this.queue.catch(() => { });
+        for (const dispose of this.disposers)
+            dispose();
+    }
+}

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

@@ -0,0 +1,74 @@
+import { TERMINAL_SNAPSHOT_BYTES } from "../../../shared/terminal/constants.js";
+import { TerminalChannel } from "./channel.js";
+// Detect a dead peer: close the socket after one missed pong.
+const HEARTBEAT_MS = 30_000;
+function rawDataToText(data) {
+    if (Buffer.isBuffer(data))
+        return data.toString('utf8');
+    if (data instanceof ArrayBuffer)
+        return Buffer.from(data).toString('utf8');
+    return Buffer.concat(data).toString('utf8');
+}
+export function attachTerminalSocket(socket, registry, options = {}) {
+    let alive = true;
+    // oxlint-disable-next-line prefer-const -- close captures the channel while its constructor sends the first message
+    let channel;
+    const close = () => {
+        channel?.dispose();
+        socket.terminate();
+    };
+    const send = (message) => {
+        if (socket.readyState !== socket.OPEN)
+            return;
+        // A slow client must not make the server buffer without limit.
+        if (socket.bufferedAmount > TERMINAL_SNAPSHOT_BYTES) {
+            close();
+            return;
+        }
+        socket.send(JSON.stringify(message), error => {
+            if (error)
+                close();
+        });
+    };
+    channel = new TerminalChannel(registry, send, close);
+    socket.on('message', (data, binary) => {
+        // The protocol uses text frames only.
+        if (binary) {
+            close();
+            return;
+        }
+        try {
+            // The channel checks the shape of the message.
+            channel?.receive(JSON.parse(rawDataToText(data)));
+        }
+        catch {
+            close();
+        }
+    });
+    socket.on('pong', () => {
+        alive = true;
+    });
+    const heartbeat = setInterval(() => {
+        if (!alive) {
+            close();
+            return;
+        }
+        // The next pong must arrive before the next tick.
+        alive = false;
+        socket.ping();
+    }, options.heartbeatMs ?? HEARTBEAT_MS);
+    heartbeat.unref();
+    let ended = false;
+    // Both `close` and `error` events call this function, so it must run only once.
+    const cleanup = () => {
+        if (ended)
+            return;
+        ended = true;
+        clearInterval(heartbeat);
+        channel?.dispose();
+        options.onDisconnect?.();
+    };
+    socket.on('close', cleanup);
+    socket.on('error', cleanup);
+    return { close };
+}

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

@@ -0,0 +1,32 @@
+import { randomBytes } from 'node:crypto';
+import { TERMINAL_TOKEN_MS } from "../../../shared/terminal/constants.js";
+// Bound token memory when a page repeatedly requests credentials.
+const MAX_TOKENS = 256;
+export class TerminalTokens {
+    tokens = new Map();
+    now;
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    issue(origin) {
+        this.prune();
+        if (this.tokens.size >= MAX_TOKENS)
+            this.tokens.delete(this.tokens.keys().next().value ?? '');
+        const token = randomBytes(32).toString('base64url');
+        this.tokens.set(token, { origin, expires: this.now() + TERMINAL_TOKEN_MS });
+        return token;
+    }
+    consume(token, origin) {
+        const info = this.tokens.get(token);
+        this.tokens.delete(token);
+        return !!info && info.expires > this.now() && info.origin === origin;
+    }
+    prune() {
+        for (const [token, info] of this.tokens)
+            if (info.expires <= this.now())
+                this.tokens.delete(token);
+    }
+    clear() {
+        this.tokens.clear();
+    }
+}

package/dist/shared/app/schemas.js

@@ -1,6 +1,10 @@
+import { TerminalCapabilitySchema } from "../terminal/schemas.js";
 import { Type } from '@sinclair/typebox';
 export const AppInfoSchema = Type.Object({
-    version: Type.String({ description: 'githuman version from package.json.' })
+    version: Type.String({
+        description: 'githuman version from package.json.'
+    }),
+    terminal: TerminalCapabilitySchema
 }, { description: 'Facts about the running server.' });
 export const HealthSchema = Type.Object({
     status: Type.Literal('ok', { description: 'Always "ok".' })

package/dist/shared/diff/preamble.js

@@ -0,0 +1,77 @@
+// The farthest line, above a hunk, that its preamble may reach (ADR 0036). The reach is a
+// limit, not the size: the preamble starts at a safe line within it. A reach of 60 gave the
+// fewest wrong lines in a test on the history of this repository.
+export const PREAMBLE_REACH = 60;
+// A budget for one preamble, in characters. A minified file has lines of many kilobytes.
+const PREAMBLE_MAX_CHARS = 4000;
+// A line that closes a tag. At the start of a preamble it has no opening tag, and a markup
+// grammar then loses its state.
+const CLOSER = /^\s*(<\/|\/>|>)/;
+// A top-level block of a Vue file: the tag stands alone on its line, at column 0.
+const VUE_BLOCK_OPEN = /^<(template|script|style)\b[^>]*>\s*$/;
+/**
+ * For each line index, the opening tag of the Vue block that is open before that line.
+ * The list has one more entry than there are lines, so the end of the file has an entry too.
+ */
+function vueOpenTags(lines) {
+    const tags = [undefined];
+    let open;
+    for (const text of lines) {
+        const match = VUE_BLOCK_OPEN.exec(text);
+        if (match) {
+            open = { tag: match[1], text };
+        }
+        else if (open && text.startsWith(`</${open.tag}>`)) {
+            open = undefined;
+        }
+        tags.push(open?.text);
+    }
+    return tags;
+}
+/**
+ * Makes a reader of preambles for one side of a file. Use one reader for all hunks of the
+ * file: it scans the Vue blocks once, and only when a hunk needs them.
+ *
+ * The preamble starts at the farthest safe line within {@link PREAMBLE_REACH} lines above
+ * the hunk. A line is safe when it is indented no deeper than every line after it, up to the
+ * hunk, and does not close a tag. Then the preamble holds no line that closes a block
+ * opened above it, and the grammar keeps a sound state. In a Vue file the opening tag of the
+ * enclosing block comes first, so the parser knows the language. `sideLines` are all lines
+ * of the file on the side of the hunk.
+ */
+export function createPreambleReader(path, sideLines) {
+    const isVue = path.toLowerCase().endsWith('.vue');
+    let openTags;
+    return firstLine => {
+        const end = Math.min(firstLine - 1, sideLines.length);
+        if (end <= 0)
+            return [];
+        let start = end;
+        let chars = 0;
+        let shallowest = Infinity;
+        for (let i = end - 1; i >= Math.max(0, end - PREAMBLE_REACH); i--) {
+            const line = sideLines[i];
+            chars += line.length;
+            if (chars > PREAMBLE_MAX_CHARS)
+                break;
+            if (line.trim() === '')
+                continue;
+            const indent = line.length - line.trimStart().length;
+            if (indent <= shallowest && !CLOSER.test(line))
+                start = i;
+            shallowest = Math.min(shallowest, indent);
+        }
+        const lines = sideLines.slice(start, end);
+        if (isVue) {
+            openTags ??= vueOpenTags(sideLines);
+            const tag = openTags[start];
+            if (tag !== undefined)
+                lines.unshift(tag);
+        }
+        return lines;
+    };
+}
+/** The preamble of one hunk. For many hunks of one file, use {@link createPreambleReader}. */
+export function hunkPreamble(path, sideLines, firstLine) {
+    return createPreambleReader(path, sideLines)(firstLine);
+}

package/dist/shared/diff/schemas.js

@@ -27,7 +27,10 @@ export const DiffHunkSchema = Type.Object({
     newLines: Type.Integer({ description: 'Line count in the new file.' }),
     lines: Type.Array(DiffLineSchema, {
         description: 'Lines of the hunk in file order.'
-    })
+    }),
+    preamble: Type.Optional(Type.Array(Type.String(), {
+        description: 'Unchanged lines above the hunk, for syntax highlighting only. Bounded in count and size. In a Vue file the opening tag of the enclosing block comes first. Absent when there are none.'
+    }))
 }, { description: 'One hunk of a file diff.' });
 const diffFileFields = {
     oldPath: Type.String({

package/dist/shared/terminal/constants.js

@@ -0,0 +1,27 @@
+// Bound process and emulator memory for one repository.
+export const MAX_TERMINAL_SESSIONS = 8;
+// Keep useful history without retaining unlimited command output.
+export const TERMINAL_SCROLLBACK = 5000;
+// Confirmed idle sessions need less orphan time than running jobs.
+export const TERMINAL_IDLE_MS = 15 * 60 * 1000;
+// Output must not extend the lifetime of an orphaned command.
+export const TERMINAL_ORPHAN_MS = 60 * 60 * 1000;
+// Tokens are used only for an immediate connection attempt.
+export const TERMINAL_TOKEN_MS = 30_000;
+// Bound the shell title that the server stores and publishes.
+export const TERMINAL_TITLE_LENGTH = 256;
+// A smaller screen cannot show a shell prompt.
+export const TERMINAL_MIN_COLS = 2;
+export const TERMINAL_MIN_ROWS = 2;
+// Small screens and bounded snapshots need bounded cell dimensions.
+export const TERMINAL_MAX_COLS = 300;
+// Bound the visible buffer as well as scrollback.
+export const TERMINAL_MAX_ROWS = 100;
+// Keep individual input frames and output batches small.
+export const TERMINAL_FRAME_BYTES = 64 * 1024;
+// Pause the backend before parser queues grow without limit.
+export const TERMINAL_QUEUE_BYTES = 1024 * 1024;
+// Credit bounds each client's unacknowledged output.
+export const TERMINAL_CLIENT_BYTES = 4 * 1024 * 1024;
+// Snapshot frames may contain a bounded screen and history.
+export const TERMINAL_SNAPSHOT_BYTES = 16 * 1024 * 1024;

package/dist/shared/terminal/schemas.js

@@ -0,0 +1,114 @@
+import { Type } from '@sinclair/typebox';
+import { Nullable } from "../utils/schemas.js";
+import { TERMINAL_MAX_COLS, TERMINAL_MIN_COLS, TERMINAL_MIN_ROWS, TERMINAL_MAX_ROWS, TERMINAL_FRAME_BYTES, TERMINAL_TITLE_LENGTH, MAX_TERMINAL_SESSIONS } from "./constants.js";
+// Every command is validated before it reaches a shell.
+const id = Type.String({
+    minLength: 1,
+    maxLength: 64,
+    description: 'Terminal session identifier.'
+});
+const requestId = Type.String({
+    minLength: 1,
+    maxLength: 64,
+    description: 'Client operation identifier.'
+});
+const cols = Type.Integer({
+    minimum: TERMINAL_MIN_COLS,
+    maximum: TERMINAL_MAX_COLS,
+    description: 'Screen columns.'
+});
+const rows = Type.Integer({
+    minimum: TERMINAL_MIN_ROWS,
+    maximum: TERMINAL_MAX_ROWS,
+    description: 'Screen rows.'
+});
+const data = Type.String({
+    maxLength: TERMINAL_FRAME_BYTES,
+    description: 'Terminal data.'
+});
+function message(type, fields) {
+    return Type.Object({
+        type: Type.Literal(type, { description: 'Message discriminator.' }),
+        ...fields
+    }, { additionalProperties: false, description: `${type} terminal message.` });
+}
+export const TerminalModeSchema = Type.Union([Type.Literal('pty'), Type.Literal('pipe')], { description: 'Backend mode.' });
+export const TerminalRunningSchema = Type.Union([Type.Literal('idle'), Type.Literal('running'), Type.Literal('unknown')], { description: 'Confirmed process activity or unknown.' });
+export const TerminalInfoSchema = Type.Object({
+    id,
+    title: Type.String({
+        maxLength: TERMINAL_TITLE_LENGTH,
+        description: 'Shell title or fallback label.'
+    }),
+    cols,
+    rows,
+    mode: TerminalModeSchema,
+    running: TerminalRunningSchema
+}, { description: 'Live terminal session.' });
+export const TerminalCapabilitySchema = Type.Object({
+    available: Type.Boolean({
+        description: 'Terminal access is enabled on this bind.'
+    }),
+    mode: Nullable(TerminalModeSchema)
+}, { description: 'Server terminal capability.' });
+export const TerminalTokenSchema = Type.Object({ token: Type.String({ description: 'One-use connection token.' }) }, { description: 'WebSocket connection credential.' });
+export const TerminalClientMessageSchema = Type.Union([
+    message('create', { requestId, cols, rows }),
+    message('subscribe', { terminalId: id }),
+    message('snapshot', { terminalId: id }),
+    message('input', { terminalId: id, data }),
+    message('line', { terminalId: id, data }),
+    message('signal', {
+        terminalId: id,
+        signal: Type.Union([Type.Literal('interrupt'), Type.Literal('eof')], {
+            description: 'Limited-mode control action.'
+        })
+    }),
+    message('resize', { terminalId: id, cols, rows }),
+    message('close', { terminalId: id, requestId }),
+    message('ack', {
+        terminalId: id,
+        sequence: Type.Integer({
+            minimum: 0,
+            description: 'Last processed output sequence.'
+        })
+    }),
+    message('ping', {})
+], { description: 'Validated client terminal protocol.' });
+export const TerminalServerMessageSchema = Type.Union([
+    message('list', {
+        sessions: Type.Array(TerminalInfoSchema, {
+            maxItems: MAX_TERMINAL_SESSIONS,
+            description: 'Current server sessions.'
+        })
+    }),
+    message('created', { requestId, terminalId: id }),
+    message('snapshot', {
+        terminalId: id,
+        data: Type.String({ description: 'Serialized screen and parser tail.' }),
+        cols,
+        rows,
+        sequence: Type.Integer({
+            minimum: 0,
+            description: 'Snapshot output boundary.'
+        })
+    }),
+    message('output', {
+        terminalId: id,
+        data,
+        cols,
+        rows,
+        sequence: Type.Integer({ minimum: 1, description: 'Output sequence.' })
+    }),
+    message('title', {
+        terminalId: id,
+        title: Type.String({ description: 'Updated shell title.' })
+    }),
+    message('exit', { terminalId: id }),
+    message('error', {
+        requestId: Type.Optional(requestId),
+        code: Type.String({ description: 'Domain error code.' }),
+        message: Type.String({ description: 'Operation failure.' })
+    }),
+    message('pong', {})
+], { description: 'Server terminal protocol.' });

package/dist/shared/terminal/types.js

@@ -0,0 +1 @@
+export {};