@tequila99/githuman 0.4.1 → 0.5.0

package/README.md

@@ -171,3 +171,13 @@ pnpm run build       # server (tsc) + web (quasar build) → dist/
 ## Лицензия
 
 MIT, см. [LICENSE](LICENSE).
+
+## Встроенный терминал
+
+При запуске на loopback кнопка **Terminal** в шапке и меню открывает терминал в корне репозитория. ``Ctrl+Shift+` `` открывает или сворачивает окно. Окно можно перетаскивать и сворачивать; «+» добавляет вкладку, до восьми терминалов. Закрытие вкладки требует подтверждения и останавливает shell с его командами. Команда `exit` закрывает вкладку сразу.
+
+Сессии переживают обновление страницы и доступны из нескольких страниц браузера. История ограничена 5000 строками scrollback; после остановки сервера она теряется. Без подписчиков простаивающая сессия завершается через 15 минут, работающая или с неизвестным состоянием — не позднее часа.
+
+Если платформенный бинарник PTY недоступен, терминал работает в ограниченном режиме с баннером: команды вводятся в поле под выводом, Ctrl+C прерывает команду, Ctrl+D закрывает shell. `vim`, `less` и другие интерактивные программы требуют PTY. В LAN терминал отключён. Переключатель исходных цветов отключает минимальный контраст для программ со своей палитрой.
+
+Для разработки на другом порту backend можно передать `GITHUMAN_DEV_API=http://localhost:3848` при запуске Quasar dev-сервера.

package/dist/cli/index.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { errorMessage } from "../shared/utils/error-message.js";
 import { writeFileSync } from 'node:fs';
 import { parseServeArgs } from "./config.js";
 import { startServer, resolveRepositoryPath, resolveReviewsDbPath } from "./server-runtime.js";
@@ -7,6 +8,8 @@ import { parseListArgs, runList } from "./commands/list.js";
 import { parseExportArgs, runExport } from "./commands/export.js";
 import { createFileDatabase } from "../server/db/index.js";
 import { getAppVersion } from "../server/app-version.js";
+// Force exit when a graceful close hangs. It must exceed the terminal kill time: ps timeout plus grace.
+const SHUTDOWN_TIMEOUT_MS = 5000;
 /** Opens the reviews DB for the repo at cwd, shared by `list` and `export`. */
 async function openReviewsDb(dbPrefix) {
     const repositoryPath = await resolveRepositoryPath(process.cwd());
@@ -21,7 +24,29 @@ async function main(argv) {
     switch (command) {
         case 'serve': {
             const options = parseServeArgs(rest);
-            const { url } = await startServer(options);
+            const { app, url } = await startServer(options);
+            let stopping = false;
+            const shutdown = () => {
+                if (stopping)
+                    return;
+                stopping = true;
+                // Do not wait for a stuck connection forever. Unref lets a clean close end the process by itself.
+                const deadline = setTimeout(() => process.exit(1), SHUTDOWN_TIMEOUT_MS);
+                deadline.unref();
+                void app
+                    .close()
+                    .then(() => {
+                    clearTimeout(deadline);
+                    process.exitCode = 0;
+                    return undefined;
+                })
+                    .catch(error => {
+                    console.error(errorMessage(error));
+                    process.exitCode = 1;
+                });
+            };
+            process.once('SIGINT', shutdown);
+            process.once('SIGTERM', shutdown);
             console.log(formatStartupMessage(url, options.host));
             return;
         }
@@ -50,6 +75,6 @@ async function main(argv) {
     }
 }
 main(process.argv.slice(2)).catch((error) => {
-    console.error(error instanceof Error ? error.message : error);
+    console.error(errorMessage(error));
     process.exitCode = 1;
 });

package/dist/cli/server-runtime.js

@@ -64,6 +64,7 @@ export async function startServer(options) {
         db,
         watchFiles: true,
         apiDocs: options.apiDocs === true,
+        terminalEnabled: isLoopbackHost(options.host),
         // Agents can run commands, so they are only offered on a loopback bind.
         ...(isLoopbackHost(options.host)
             ? {

package/dist/server/app.js

@@ -4,6 +4,10 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import Fastify from 'fastify';
 import fastifyStatic from '@fastify/static';
+import fastifyWebsocket from '@fastify/websocket';
+import { terminalRoutes, TERMINAL_WEBSOCKET_OPTIONS } from "./routes/terminal.js";
+import { TerminalRegistry } from "./services/terminal/registry.js";
+import { loadPty, terminalSupported } from "./services/terminal/backend.js";
 import fastifySwagger from '@fastify/swagger';
 import fastifySwaggerUi from '@fastify/swagger-ui';
 // @fastify/sse's published types declare an ESM default export that doesn't match
@@ -32,6 +36,10 @@ export function buildApp(options = {}) {
     const repositoryPath = options.repositoryPath ?? process.cwd();
     const db = options.db ?? createTestDatabase();
     const eventBus = options.eventBus ?? createEventBus();
+    // Windows includes a PTY binary, but the shell and process list are Unix-only.
+    const terminalEnabled = options.terminalEnabled === true && terminalSupported();
+    if (terminalEnabled)
+        app.register(fastifyWebsocket, TERMINAL_WEBSOCKET_OPTIONS);
     app.register(fastifySse);
     // The spec collects routes as they are added, so it comes before them.
     app.register(fastifySwagger, openApiOptions());
@@ -40,7 +48,12 @@ export function buildApp(options = {}) {
     }
     app.register(openApiRoutes);
     app.register(healthRoutes);
-    app.register(appInfoRoutes);
+    app.register(appInfoRoutes, {
+        terminalCapability: async () => ({
+            available: terminalEnabled,
+            mode: terminalEnabled ? ((await loadPty()) ? 'pty' : 'pipe') : null
+        })
+    });
     app.register(diffRoutes, { repositoryPath });
     app.register(gitRoutes, { repositoryPath });
     app.register(reviewRoutes, { repositoryPath, db, eventBus });
@@ -50,6 +63,14 @@ export function buildApp(options = {}) {
         eventBus,
         instanceId: options.instanceId ?? randomUUID()
     });
+    if (terminalEnabled)
+        app.register(terminalRoutes, {
+            registry: options.terminalRegistry ??
+                new TerminalRegistry({
+                    repositoryPath,
+                    onLifecycle: event => app.log.info({ terminal: event }, 'Terminal lifecycle')
+                })
+        });
     if (options.agentPresets) {
         app.register(agentRoutes, {
             registry: createSessionRegistry({

package/dist/server/errors/terminal.js

@@ -0,0 +1,4 @@
+import createError from '@fastify/error';
+export const TerminalError = createError('GHT_TERMINAL', '%s', 409);
+export const TerminalNotFoundError = createError('GHT_TERMINAL_NOT_FOUND', '%s', 404);
+export const TerminalLimitError = createError('GHT_TERMINAL_LIMIT', '%s', 409);

package/dist/server/hooks/terminal/local-origin.js

@@ -0,0 +1,25 @@
+import { isLoopbackHost } from "../../../shared/network/loopback.js";
+import { ForbiddenError } from "../../errors/http.js";
+// Returns false on any malformed value: an invalid URL means an invalid origin.
+function isTerminalOrigin(host, origin) {
+    if (!host || !origin)
+        return false;
+    try {
+        const source = new URL(origin);
+        const target = new URL(`http://${host}`);
+        return (isLoopbackHost(target.hostname) &&
+            target.host === host &&
+            source.host === target.host &&
+            source.protocol === 'http:' &&
+            source.origin === origin &&
+            !target.username &&
+            !target.password);
+    }
+    catch {
+        return false;
+    }
+}
+export async function requireTerminalOrigin(request) {
+    if (!isTerminalOrigin(request.headers.host, request.headers.origin))
+        throw new ForbiddenError('Terminal endpoints only accept requests from this local server. Open the app via localhost.');
+}

package/dist/server/routes/app-info.js

@@ -1,6 +1,6 @@
 import { getAppVersion } from "../app-version.js";
 import { AppInfoSchema } from "../../shared/app/schemas.js";
-export async function appInfoRoutes(app) {
+export async function appInfoRoutes(app, options) {
     app.withTypeProvider().get('/api/app-info', {
         schema: {
             tags: ['app'],
@@ -8,6 +8,9 @@ export async function appInfoRoutes(app) {
             response: { 200: AppInfoSchema }
         }
     }, async () => {
-        return { version: getAppVersion() };
+        return {
+            version: getAppVersion(),
+            terminal: await options.terminalCapability()
+        };
     });
 }

package/dist/server/routes/terminal.js

@@ -0,0 +1,63 @@
+import { Type } from '@sinclair/typebox';
+import { TerminalTokenSchema } from "../../shared/terminal/schemas.js";
+import { TERMINAL_FRAME_BYTES } from "../../shared/terminal/constants.js";
+import { ForbiddenError } from "../errors/http.js";
+import { requireTerminalOrigin } from "../hooks/terminal/local-origin.js";
+import { TerminalTokens } from "../services/terminal/tokens.js";
+import { attachTerminalSocket } from "../services/terminal/socket.js";
+// Reject oversized values early. A real token has 43 characters.
+const MAX_TOKEN_LENGTH = 64;
+// Leave room for the JSON envelope around an input frame.
+const MAX_PAYLOAD_BYTES = TERMINAL_FRAME_BYTES * 2;
+// Apply the same frame limit to every terminal upgrade.
+export const TERMINAL_WEBSOCKET_OPTIONS = {
+    options: { maxPayload: MAX_PAYLOAD_BYTES }
+};
+export async function terminalRoutes(app, options) {
+    const tokens = new TerminalTokens();
+    const connections = new Set();
+    app.addHook('onError', async (_request, _reply, error) => {
+        // Request URLs contain credentials, so log only the rejection code.
+        app.log.warn({ code: error.code }, 'Terminal request rejected');
+    });
+    const api = app.withTypeProvider();
+    api.post('/api/terminal/token', {
+        onRequest: requireTerminalOrigin,
+        schema: {
+            tags: ['terminal'],
+            summary: 'Issue a terminal connection token',
+            response: { 200: TerminalTokenSchema }
+        }
+    }, async (request) => ({ token: tokens.issue(request.headers.origin ?? '') }));
+    api.get('/api/terminal/ws', {
+        websocket: true,
+        schema: {
+            hide: true,
+            querystring: Type.Object({
+                token: Type.String({
+                    maxLength: MAX_TOKEN_LENGTH,
+                    description: 'One-use connection credential.'
+                })
+            }, {
+                additionalProperties: false,
+                description: 'Terminal upgrade credential.'
+            })
+        },
+        onRequest: requireTerminalOrigin,
+        preValidation: async (request) => {
+            if (!tokens.consume(request.query.token, request.headers.origin ?? ''))
+                throw new ForbiddenError('Terminal connection token is invalid or expired.');
+        }
+    }, socket => {
+        const connection = attachTerminalSocket(socket, options.registry, {
+            onDisconnect: () => connections.delete(connection)
+        });
+        connections.add(connection);
+    });
+    app.addHook('onClose', async () => {
+        for (const connection of connections)
+            connection.close();
+        tokens.clear();
+        await options.registry.dispose();
+    });
+}

package/dist/server/services/diff.service.js

@@ -1,6 +1,7 @@
 import { diffLines } from 'diff';
 import { stat } from 'node:fs/promises';
 import { assertSafeRef, listChangedSummaries, resolveWithinRepo, getFileAtRef, getFilesAtRefBatch, listChangedPaths, listUntrackedPaths } from "./git.service.js";
+import { createPreambleReader } from "../../shared/diff/preamble.js";
 /** Unchanged lines kept around each change in a hunk, as in `git diff`. */
 const CONTEXT_LINES = 3;
 /** Stamp of a worktree file that cannot be read. */
@@ -57,6 +58,27 @@ function windowHunks(lines, contextLines = CONTEXT_LINES) {
     }
     return hunks;
 }
+/**
+ * Gives each hunk the unchanged lines above it, for the highlighter. A hunk with no new
+ * line (a deleted file) takes them from the old side. A side is split into lines only when
+ * a hunk needs it: a hunk at the top of a file has no preamble.
+ */
+function withPreambles(hunks, meta, oldContent, newContent) {
+    let oldReader;
+    let newReader;
+    return hunks.map(hunk => {
+        let preamble = [];
+        if (hunk.newStart > 1) {
+            newReader ??= createPreambleReader(meta.newPath, splitLines(newContent));
+            preamble = newReader(hunk.newStart);
+        }
+        else if (hunk.newStart === 0 && hunk.oldStart > 1) {
+            oldReader ??= createPreambleReader(meta.oldPath, splitLines(oldContent));
+            preamble = oldReader(hunk.oldStart);
+        }
+        return preamble.length > 0 ? { ...hunk, preamble } : hunk;
+    });
+}
 export function computeFileDiff(oldContent, newContent, meta) {
     const base = {
         oldPath: meta.oldPath,
@@ -105,7 +127,7 @@ export function computeFileDiff(oldContent, newContent, meta) {
             }
         }
     }
-    const hunks = windowHunks(lines);
+    const hunks = withPreambles(windowHunks(lines), meta, oldContent, newContent);
     return { ...base, additions, deletions, hunks };
 }
 /**

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));
+}