@tequila99/githuman 0.4.2 → 0.6.0

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

@@ -0,0 +1,167 @@
+import { randomUUID } from 'node:crypto';
+import { MAX_TERMINAL_SESSIONS, TERMINAL_IDLE_MS, TERMINAL_ORPHAN_MS } from "../../../shared/terminal/constants.js";
+import { TerminalLimitError, TerminalNotFoundError } from "../../errors/terminal.js";
+import { createBackend } from "./backend.js";
+import { processes } from "./processes.js";
+import { TerminalSession } from "./session.js";
+// Check the activity of every session this often.
+const POLL_MS = 5000;
+export class TerminalRegistry {
+    entries = new Map();
+    listeners = new Set();
+    closing = new Set();
+    poll;
+    creating = 0;
+    nextNumber = 1;
+    stopped = false;
+    checking = false;
+    options;
+    constructor(options) {
+        this.options = options;
+        this.poll = setInterval(() => {
+            void this.checkActivity();
+        }, options.pollMs ?? POLL_MS);
+        this.poll.unref();
+    }
+    get list() {
+        return [...this.entries.values()].map(entry => entry.session.info);
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    publish(message) {
+        for (const listener of this.listeners)
+            listener(message);
+    }
+    publishList() {
+        this.publish({ type: 'list', sessions: this.list });
+    }
+    now() {
+        return (this.options.now ?? Date.now)();
+    }
+    get(id) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            throw new TerminalNotFoundError('Terminal session no longer exists.');
+        return entry.session;
+    }
+    async create(cols, rows) {
+        if (this.stopped)
+            throw new TerminalNotFoundError('Terminal server is stopping.');
+        if (this.entries.size + this.creating >= MAX_TERMINAL_SESSIONS)
+            throw new TerminalLimitError('The terminal limit has been reached.');
+        this.creating++;
+        try {
+            const backend = await (this.options.backend ?? createBackend)(this.options.repositoryPath, cols, rows);
+            if (this.stopped) {
+                await backend.kill();
+                throw new TerminalNotFoundError('Terminal server is stopping.');
+            }
+            const id = randomUUID();
+            const session = new TerminalSession(id, `Terminal ${this.nextNumber++}`, backend, cols, rows, message => this.publish(message), () => {
+                void this.close(id);
+            });
+            this.entries.set(id, {
+                session,
+                subscribers: new Set(),
+                orphanedSince: this.now(),
+                idleSince: null
+            });
+            this.options.onLifecycle?.({ type: 'created', id, mode: backend.mode });
+            this.publishList();
+            return session;
+        }
+        finally {
+            this.creating--;
+        }
+    }
+    attach(id, subscriber) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            throw new TerminalNotFoundError('Terminal session no longer exists.');
+        entry.subscribers.add(subscriber);
+        entry.orphanedSince = null;
+        entry.idleSince = null;
+    }
+    detach(subscriber) {
+        for (const entry of this.entries.values()) {
+            if (!entry.subscribers.delete(subscriber) || entry.subscribers.size)
+                continue;
+            entry.orphanedSince = this.now();
+            entry.idleSince = entry.session.running === 'idle' ? this.now() : null;
+        }
+    }
+    async checkActivity() {
+        if (this.checking || this.stopped)
+            return;
+        this.checking = true;
+        try {
+            // One process list serves every session. A failed read leaves them unknown.
+            let rows;
+            if (this.entries.size > 0) {
+                try {
+                    rows = await (this.options.listProcesses ?? processes)();
+                }
+                catch {
+                    rows = undefined;
+                }
+            }
+            for (const [id, entry] of this.entries) {
+                const previous = entry.session.running;
+                entry.session.running =
+                    rows === undefined
+                        ? 'unknown'
+                        : await entry.session.backend.activity(rows);
+                if (previous !== entry.session.running)
+                    this.publishList();
+                if (entry.orphanedSince === null)
+                    continue;
+                const now = this.now();
+                if (entry.session.running === 'idle') {
+                    entry.idleSince ??= now;
+                }
+                else {
+                    entry.idleSince = null;
+                }
+                if (now - entry.orphanedSince >= TERMINAL_ORPHAN_MS ||
+                    (entry.idleSince !== null &&
+                        now - entry.idleSince >= TERMINAL_IDLE_MS)) {
+                    this.options.onLifecycle?.({ type: 'timeout', id });
+                    await this.close(id);
+                }
+            }
+        }
+        finally {
+            this.checking = false;
+        }
+    }
+    async resize(id, cols, rows) {
+        await this.get(id).resize(cols, rows);
+        this.publishList();
+    }
+    async close(id) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            return;
+        this.entries.delete(id);
+        this.options.onLifecycle?.({ type: 'closed', id });
+        this.publish({ type: 'exit', terminalId: id });
+        this.publishList();
+        const closing = entry.session.dispose();
+        this.closing.add(closing);
+        try {
+            await closing;
+        }
+        finally {
+            this.closing.delete(closing);
+        }
+    }
+    async dispose() {
+        this.stopped = true;
+        clearInterval(this.poll);
+        await Promise.all([...this.entries.keys()].map(id => this.close(id)));
+        await Promise.all(this.closing);
+        this.listeners.clear();
+    }
+}

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/server/utils/sse.js

@@ -1,11 +1,82 @@
+// Each connection must wait for backpressure before sending its next message.
+const SEND_QUEUES = new WeakMap();
 /**
- * Sends one SSE message and never fails. A client can leave at any time, and
- * `send` then rejects. Nothing awaits that promise, so Node would end the
- * process on the unhandled rejection.
+ * The maximum number of messages in the send queue of one connection. On a
+ * reconnect the agent stream replays every session buffer at once:
+ * MAX_AGENT_SESSIONS × MAX_BUFFERED_EVENTS, plus a `gap` and a `state` for
+ * each session. A lower limit closes the stream before its first send, and the
+ * client then reconnects in a loop. The limit is about twice that replay, so
+ * live events have room. This count bounds memory. There is no byte limit:
+ * most queued items point to events that the session buffers hold already (#85).
  */
+export const MAX_QUEUED_MESSAGES = 50_000;
+/**
+ * A send that has not finished after this time means that the client stopped
+ * reading. The check runs when a new message arrives, so it closes a dead
+ * connection before the count limit does. A slow client that still reads
+ * finishes each send sooner. The
+ * check uses `Date.now()`: a jump of the system clock can make a false stall,
+ * and the client then only reconnects.
+ */
+export const STALL_TIMEOUT_MS = 30_000;
+/**
+ * Closes a connection that does not read, and drops its queue. Dropping only
+ * some messages would hide the loss from the client. The client reconnects by
+ * itself: the agent stream resumes from `Last-Event-ID` or gets `gap`, and
+ * `/api/events` refetches after the reconnect. Nothing is logged: the Fastify
+ * logger is off, and the reconnect is the normal recovery (#85).
+ */
+function dropConnection(sse, queue) {
+    if (queue.closed)
+        return;
+    queue.closed = true;
+    queue.messages.length = 0;
+    try {
+        sse.close();
+    }
+    catch {
+        // The connection is already gone.
+    }
+}
+async function flush(sse, queue) {
+    queue.sending = true;
+    try {
+        while (!queue.closed && sse.isConnected && queue.messages.length) {
+            queue.sendStartedAt = Date.now();
+            await sse.send(queue.messages.shift());
+        }
+    }
+    catch {
+        // A disconnected client must not cause an unhandled rejection.
+    }
+    finally {
+        queue.messages.length = 0;
+        queue.sending = false;
+    }
+}
+/** Queue messages in order without concurrent writes to a slow client. */
 export function safeSend(sse, message) {
-    if (!sse.isConnected) {
+    if (!sse.isConnected)
+        return;
+    let queue = SEND_QUEUES.get(sse);
+    if (!queue) {
+        queue = { messages: [], sending: false, closed: false, sendStartedAt: 0 };
+        SEND_QUEUES.set(sse, queue);
+        const connectionQueue = queue;
+        sse.onClose?.(() => {
+            connectionQueue.closed = true;
+            connectionQueue.messages.length = 0;
+        });
+    }
+    if (queue.closed)
+        return;
+    // The queue grows only here, so the limits are checked only here.
+    if (queue.messages.length >= MAX_QUEUED_MESSAGES ||
+        (queue.sending && Date.now() - queue.sendStartedAt > STALL_TIMEOUT_MS)) {
+        dropConnection(sse, queue);
         return;
     }
-    sse.send(message).catch(() => { });
+    queue.messages.push(message);
+    if (!queue.sending)
+        void flush(sse, queue);
 }

package/dist/shared/agents/file-search.js

@@ -1,3 +1,4 @@
+import { isDirectoryPath, withoutTrailingSlash } from "./mention-paths.js";
 function isSubsequence(needle, haystack) {
     let at = 0;
     for (const char of haystack) {
@@ -13,7 +14,16 @@ function isSubsequence(needle, haystack) {
 /** Lower is better; undefined = no match. */
 function score(path, query) {
     const lower = path.toLowerCase();
-    const base = lower.slice(lower.lastIndexOf('/') + 1);
+    // A query that ends with `/` names a directory: `web/` or `src/web/` puts
+    // `src/web/` first, above the files in it.
+    if (query.endsWith('/') && isDirectoryPath(lower) && lower.endsWith(query)) {
+        const before = lower.length - query.length;
+        if (before === 0 || lower[before - 1] === '/')
+            return 0;
+    }
+    // The name of a directory is taken without the `/`: with it, the name is empty.
+    const name = withoutTrailingSlash(lower);
+    const base = name.slice(name.lastIndexOf('/') + 1);
     if (base === query)
         return 0;
     if (base.startsWith(query))
@@ -27,21 +37,23 @@ function score(path, query) {
     return undefined;
 }
 /**
- * Orders `files` by how well they match `query`: file name first (exact,
- * prefix, substring), then anywhere in the path, then as scattered letters.
- * Ties go to the shorter path. An empty query matches everything.
+ * Orders `paths` by how well they match `query`: name first (exact, prefix,
+ * substring), then anywhere in the path, then as scattered letters. Ties go
+ * to a file before a directory, then to the shorter path. An empty query
+ * matches everything, so files lead the list and short directories do not.
  */
-export function rankFiles(files, query) {
+export function rankPaths(paths, query) {
     const needle = query.trim().toLowerCase();
     const scored = [];
-    for (const path of files) {
+    for (const path of paths) {
         const rank = needle === '' ? 0 : score(path, needle);
         if (rank !== undefined) {
-            scored.push({ path, rank });
+            scored.push({ path, rank, directory: isDirectoryPath(path) ? 1 : 0 });
         }
     }
     return scored
         .sort((a, b) => a.rank - b.rank ||
+        a.directory - b.directory ||
         a.path.length - b.path.length ||
         a.path.localeCompare(b.path))
         .map(entry => entry.path);

package/dist/shared/agents/mention-paths.js

@@ -0,0 +1,40 @@
+/**
+ * A mentioned path that ends with `/` names a directory, as in agent CLIs.
+ * The context item keeps the path without that `/` (#80).
+ */
+export function isDirectoryPath(path) {
+    return path.endsWith('/');
+}
+/** The path without trailing `/`: the form that a `directory` context item holds. */
+export function withoutTrailingSlash(path) {
+    return path.replace(/\/+$/, '');
+}
+/**
+ * The files and every directory that holds one of them, a directory as `a/b/`.
+ * `git ls-files --others` already gives an untracked nested repository as
+ * `dir/`, so a path with a trailing `/` is a directory too.
+ */
+export function withDirectories(paths) {
+    const directories = new Set();
+    for (const path of paths) {
+        const parts = withoutTrailingSlash(path).split('/');
+        const last = isDirectoryPath(path) ? parts.length : parts.length - 1;
+        for (let end = 1; end <= last; end++) {
+            directories.add(`${parts.slice(0, end).join('/')}/`);
+        }
+    }
+    directories.delete('/');
+    return [...paths.filter(path => !isDirectoryPath(path)), ...directories];
+}
+/** Name, parent path and kind of a mentioned path, for chips and the popup. */
+export function mentionParts(path) {
+    const directory = isDirectoryPath(path);
+    const bare = withoutTrailingSlash(path);
+    const at = bare.lastIndexOf('/');
+    const name = at === -1 ? bare : bare.slice(at + 1);
+    return {
+        name: directory ? `${name}/` : name,
+        parent: at === -1 ? '' : bare.slice(0, at),
+        directory
+    };
+}