@nia-teams/four-tools 0.0.0-stage → 0.1.0

package/dist/node/process-runner.js

@@ -0,0 +1,221 @@
+import { spawn } from 'node:child_process';
+import { openSync, writeSync, closeSync } from 'node:fs';
+import * as fs from 'node:fs/promises';
+import { join } from 'node:path/posix';
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:os';
+const signalNumbers = constants.signals;
+import { signalProcessGroup } from './process-group.js';
+export class OutputBuffer {
+    head = Buffer.alloc(0);
+    tail = Buffer.alloc(0);
+    total = 0;
+    max;
+    headMax;
+    constructor(max = 50 * 1024) {
+        this.max = Math.max(1, Math.trunc(max));
+        this.headMax = Math.ceil((this.max * 32) / 50);
+    }
+    add(chunk) {
+        this.total += chunk.length;
+        const headTake = Math.min(chunk.length, this.headMax - this.head.length);
+        if (headTake)
+            this.head = Buffer.concat([this.head, chunk.subarray(0, headTake)]);
+        const rest = chunk.subarray(headTake);
+        const tailMax = this.max - this.headMax;
+        if (rest.length && tailMax)
+            this.tail = Buffer.concat([this.tail, rest]).subarray(-tailMax);
+    }
+    get truncated() {
+        return this.total > this.max;
+    }
+    get text() {
+        return (this.head.toString('utf8') +
+            (this.truncated ? '\n[... output truncated; see spillPath ...]\n' : '') +
+            this.tail.toString('utf8'));
+    }
+}
+export async function startProcess(input) {
+    const options = input.options ?? {};
+    options.signal?.throwIfAborted();
+    await fs.mkdir(input.logDir, { recursive: true, mode: 0o700 });
+    const logPath = join(input.logDir, `${input.logId ?? `exec-${randomUUID()}`}.log`);
+    const fd = openSync(logPath, 'wx', 0o600);
+    let child;
+    try {
+        child = spawn(input.shell, ['-c', input.command], {
+            cwd: input.cwd,
+            env: { ...process.env, ...options.env },
+            detached: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    }
+    catch (error) {
+        closeSync(fd);
+        await fs.unlink(logPath);
+        throw error;
+    }
+    const output = new OutputBuffer(options.maxOutputBytes), stdout = new OutputBuffer(options.maxOutputBytes), stderr = new OutputBuffer(options.maxOutputBytes);
+    let timedOut = false, aborted = false, exited = false, finished = false;
+    let exitCode = null, exitSignal = null;
+    let drainTimer;
+    let timeoutTimer;
+    const kill = (signal = 'SIGKILL') => {
+        if (child.pid)
+            signalProcessGroup(child.pid, signal, input.platform);
+    };
+    let resolve;
+    let reject;
+    const done = new Promise((yes, no) => {
+        resolve = yes;
+        reject = no;
+    });
+    const abort = () => {
+        aborted = true;
+        kill();
+    };
+    const finish = (error) => {
+        if (finished)
+            return;
+        finished = true;
+        clearTimeout(drainTimer);
+        clearTimeout(timeoutTimer);
+        options.signal?.removeEventListener('abort', abort);
+        child.stdout?.destroy();
+        child.stderr?.destroy();
+        closeSync(fd);
+        if (error)
+            reject(error);
+        else
+            resolve({
+                output: output.text,
+                stdout: stdout.text,
+                stderr: stderr.text,
+                exitCode,
+                signal: exitSignal,
+                timedOut,
+                aborted,
+                truncated: output.truncated,
+                ...(output.truncated ? { spillPath: logPath } : {}),
+            });
+    };
+    const armDrain = () => {
+        clearTimeout(drainTimer);
+        drainTimer = setTimeout(() => finish(), 150);
+    };
+    const consume = (chunk, stream) => {
+        try {
+            // Synchronous fd writes apply backpressure before another pipe chunk is accepted.
+            for (let at = 0; at < chunk.length;)
+                at += writeSync(fd, chunk, at, chunk.length - at);
+            output.add(chunk);
+            (stream === 'stdout' ? stdout : stderr).add(chunk);
+            options.onOutput?.(chunk, stream);
+            if (exited)
+                armDrain();
+        }
+        catch (error) {
+            kill();
+            finish(error);
+        }
+    };
+    child.stdout?.on('data', (chunk) => consume(chunk, 'stdout'));
+    child.stderr?.on('data', (chunk) => consume(chunk, 'stderr'));
+    child.on('error', (error) => finish(error));
+    child.on('exit', (code, signal) => {
+        exited = true;
+        exitCode = signal ? 128 + (signalNumbers[signal] ?? 0) : code;
+        exitSignal = signal;
+        armDrain();
+    });
+    child.on('close', () => finish());
+    options.signal?.addEventListener('abort', abort, { once: true });
+    if (options.signal?.aborted)
+        abort();
+    if (options.timeoutMs !== undefined)
+        timeoutTimer = setTimeout(() => {
+            timedOut = true;
+            kill();
+        }, Math.max(0, options.timeoutMs));
+    return { child, output, logPath, done, kill };
+}
+export async function startManagedProcess(input) {
+    await fs.mkdir(input.logDir, { recursive: true, mode: 0o700 });
+    const logPath = join(input.logDir, `${input.logId}.log`);
+    const fd = openSync(logPath, 'wx', 0o600);
+    let child;
+    try {
+        child = spawn(input.shell, ['-c', input.command], {
+            cwd: input.cwd,
+            env: { ...process.env, ...input.options?.env },
+            detached: true,
+            stdio: ['ignore', fd, fd],
+        });
+    }
+    catch (error) {
+        await fs.unlink(logPath).catch(() => { });
+        throw error;
+    }
+    finally {
+        closeSync(fd);
+    }
+    const snapshot = async () => {
+        const result = new OutputBuffer(input.options?.maxOutputBytes);
+        const handle = await fs.open(logPath, 'r');
+        try {
+            const { size } = await handle.stat();
+            const head = Buffer.alloc(Math.min(size, Math.ceil((result.max * 32) / 50)));
+            const h = await handle.read(head, 0, head.length, 0);
+            result.add(head.subarray(0, h.bytesRead));
+            const tailSize = Math.min(size - h.bytesRead, result.max - h.bytesRead);
+            if (tailSize > 0) {
+                const tail = Buffer.alloc(tailSize);
+                const t = await handle.read(tail, 0, tailSize, Math.max(h.bytesRead, size - tailSize));
+                result.add(tail.subarray(0, t.bytesRead));
+            }
+            result.total = size;
+            return result;
+        }
+        finally {
+            await handle.close();
+        }
+    };
+    const groupAlive = () => {
+        if (!child.pid)
+            return false;
+        try {
+            process.kill(-child.pid, 0);
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'ESRCH')
+                return false;
+            if (error.code === 'EPERM')
+                return true;
+            throw error;
+        }
+    };
+    const done = new Promise((resolve, reject) => {
+        child.once('error', reject);
+        child.once('exit', (exitCode, signal) => {
+            if (signal)
+                exitCode = 128 + (signalNumbers[signal] ?? 0);
+            void snapshot().then((preview) => resolve({
+                output: preview.text,
+                stdout: preview.text,
+                stderr: '',
+                exitCode,
+                signal,
+                timedOut: false,
+                aborted: false,
+                truncated: preview.truncated,
+                ...(preview.truncated ? { spillPath: logPath } : {}),
+            }), reject);
+        });
+    });
+    const kill = (signal = 'SIGKILL') => {
+        if (child.pid)
+            signalProcessGroup(child.pid, signal, input.platform);
+    };
+    return { child, logPath, done, kill, snapshot, groupAlive };
+}

package/dist/node/read-range.d.ts

@@ -0,0 +1,7 @@
+import type { ReadRangeResult } from '../core/env.js';
+export declare function readRange(file: string, options?: {
+    offsetLine?: number;
+    limitLines?: number;
+    maxBytes?: number;
+    signal?: AbortSignal;
+}): Promise<ReadRangeResult>;

package/dist/node/read-range.js

@@ -0,0 +1,69 @@
+import * as fs from 'node:fs/promises';
+export async function readRange(file, options = {}) {
+    const startLine = Math.max(1, Math.trunc(options.offsetLine ?? 1));
+    const limit = Math.max(1, Math.trunc(options.limitLines ?? 2000));
+    const maxBytes = Math.max(1, Math.trunc(options.maxBytes ?? 50 * 1024));
+    const handle = await fs.open(file, 'r');
+    const pieces = [];
+    let bytes = 0, line = 1, totalBytes = 0, lastByte = -1, endLine = startLine - 1, truncatedByBytes = false, singleLineExceeded = false;
+    let selectedLineBytes = 0;
+    try {
+        const chunk = Buffer.allocUnsafe(64 * 1024);
+        while (true) {
+            options.signal?.throwIfAborted();
+            const { bytesRead } = await handle.read(chunk, 0, chunk.length, null);
+            if (!bytesRead)
+                break;
+            if (!totalBytes && chunk.subarray(0, bytesRead).includes(0))
+                return {
+                    content: '',
+                    startLine,
+                    endLine: startLine - 1,
+                    totalLines: 0,
+                    truncatedByBytes: false,
+                    isBinary: true,
+                };
+            totalBytes += bytesRead;
+            lastByte = chunk[bytesRead - 1];
+            let at = 0;
+            while (at < bytesRead) {
+                const newline = chunk.indexOf(10, at);
+                const stop = newline >= 0 && newline < bytesRead ? newline + 1 : bytesRead;
+                if (line >= startLine && line < startLine + limit) {
+                    const size = stop - at;
+                    selectedLineBytes += size;
+                    const take = Math.min(size, maxBytes - bytes);
+                    if (take > 0) {
+                        pieces.push(Buffer.from(chunk.subarray(at, at + take)));
+                        bytes += take;
+                        endLine = line;
+                    }
+                    if (take < size)
+                        truncatedByBytes = true;
+                    if (selectedLineBytes > maxBytes)
+                        singleLineExceeded = true;
+                }
+                if (stop > at && chunk[stop - 1] === 10) {
+                    line++;
+                    selectedLineBytes = 0;
+                }
+                at = stop;
+            }
+        }
+        // Drop an incomplete UTF-8 sequence at the byte cap instead of emitting replacement text.
+        const data = Buffer.concat(pieces, bytes);
+        const decoder = new TextDecoder('utf-8', { ignoreBOM: true });
+        const content = decoder.decode(data, { stream: truncatedByBytes });
+        return {
+            content,
+            startLine,
+            endLine,
+            totalLines: totalBytes === 0 ? 0 : line - (lastByte === 10 ? 1 : 0),
+            truncatedByBytes,
+            ...(singleLineExceeded ? { singleLineExceeded: true } : {}),
+        };
+    }
+    finally {
+        await handle.close();
+    }
+}

package/dist/node/terminal-manager.d.ts

@@ -0,0 +1,36 @@
+import type { ManagedTerminalBackend, TerminalInfo, TerminalExitEvent, Platform } from '../core/env.js';
+export interface TerminalManagerOptions {
+    cwd: string;
+    platform: Platform;
+    terminalDir: string;
+    shell: () => Promise<string>;
+    onExit?: (event: TerminalExitEvent) => void | Promise<void>;
+    onError?: (error: unknown) => void;
+}
+export declare class PosixTerminalManager implements ManagedTerminalBackend {
+    private readonly options;
+    private readonly entries;
+    private closed;
+    constructor(options: TerminalManagerOptions);
+    private start;
+    private notify;
+    private get;
+    execWithHandoff(input: Parameters<ManagedTerminalBackend['execWithHandoff']>[0]): ReturnType<ManagedTerminalBackend['execWithHandoff']>;
+    create(input: Parameters<ManagedTerminalBackend['create']>[0]): Promise<TerminalInfo>;
+    list(): Promise<TerminalInfo[]>;
+    read(input: Parameters<ManagedTerminalBackend['read']>[0]): Promise<{
+        status: import("../core/env.js").TerminalStatus;
+        exitCode: number | null;
+        nextOffset?: number | undefined;
+        content: string;
+        startLine: number;
+        endLine: number;
+        totalLines: number;
+    }>;
+    signal(input: Parameters<ManagedTerminalBackend['signal']>[0]): Promise<TerminalInfo>;
+    destroy(input: {
+        id: string;
+    }): Promise<void>;
+    closeAll(): Promise<void>;
+    dispose(): Promise<void>;
+}

package/dist/node/terminal-manager.js

@@ -0,0 +1,228 @@
+import * as fs from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { startManagedProcess } from './process-runner.js';
+import { readRange } from './read-range.js';
+export class PosixTerminalManager {
+    options;
+    entries = new Map();
+    closed = false;
+    constructor(options) {
+        this.options = options;
+    }
+    async start(input, notify, prefix = 'term') {
+        if (this.closed)
+            throw new Error('Terminal manager is disposed');
+        const id = `${prefix}_${randomUUID().replace(/-/g, '').slice(0, 16)}`;
+        const running = await startManagedProcess({
+            command: input.command,
+            cwd: input.cwd ?? this.options.cwd,
+            shell: await this.options.shell(),
+            platform: this.options.platform,
+            logDir: this.options.terminalDir,
+            logId: id,
+            options: { env: input.env, maxOutputBytes: input.maxOutputBytes },
+        });
+        const info = {
+            id,
+            name: input.name ?? '',
+            command: input.command,
+            cwd: input.cwd ?? this.options.cwd,
+            status: 'running',
+            exitCode: null,
+            signal: null,
+            startedAt: Date.now(),
+        };
+        const entry = {
+            info,
+            running,
+            done: running.done,
+            notify,
+            notified: false,
+            destroyed: false,
+        };
+        entry.done = running.done.then(async (result) => {
+            if (entry.completionSignal) {
+                result.exitCode = { SIGINT: 130, SIGTERM: 143, SIGKILL: 137 }[entry.completionSignal];
+                result.signal = entry.completionSignal;
+            }
+            Object.assign(info, {
+                status: result.signal ? 'signaled' : 'exited',
+                exitCode: result.exitCode,
+                signal: result.signal,
+                endedAt: Date.now(),
+            });
+            await this.notify(entry);
+            return result;
+        }, (error) => {
+            Object.assign(info, { status: 'error', endedAt: Date.now() });
+            void this.notify(entry).catch((error) => this.options.onError?.(error));
+            throw error;
+        });
+        // Background spawn errors are observed even if no foreground caller awaits done.
+        void entry.done.catch((error) => this.options.onError?.(error));
+        this.entries.set(id, entry);
+        if (this.closed) {
+            await this.destroy({ id });
+            throw new Error('Terminal manager is disposed');
+        }
+        return entry;
+    }
+    async notify(entry) {
+        if (!entry.notify ||
+            entry.notified ||
+            entry.destroyed ||
+            entry.info.status === 'running')
+            return;
+        try {
+            const preview = await entry.running.snapshot();
+            if (entry.destroyed || entry.notified)
+                return;
+            entry.notified = true;
+            const info = entry.info;
+            const event = {
+                ...info,
+                status: info.status,
+                durationMs: (info.endedAt ?? Date.now()) - info.startedAt,
+                outputPreview: preview.text,
+                logPath: entry.running.logPath,
+            };
+            void Promise.resolve(this.options.onExit?.(event)).catch((error) => this.options.onError?.(error));
+        }
+        catch (error) {
+            if (!entry.destroyed)
+                this.options.onError?.(error);
+        }
+    }
+    get(id) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            throw new Error(`Unknown terminal: ${id}`);
+        return entry;
+    }
+    async execWithHandoff(input) {
+        const entry = await this.start(input, false, 'exec');
+        let timer;
+        let abort;
+        const handoff = new Promise((resolve) => {
+            timer = setTimeout(() => resolve('handoff'), Math.max(0, input.handoffAfterMs));
+            abort = () => resolve('abort');
+            input.signal?.addEventListener('abort', abort, { once: true });
+            if (input.signal?.aborted)
+                abort();
+        });
+        try {
+            const winner = await Promise.race([entry.done, handoff]);
+            if (typeof winner !== 'string' && !entry.running.groupAlive()) {
+                if (!winner.truncated)
+                    await fs.unlink(entry.running.logPath);
+                this.entries.delete(entry.info.id);
+                return {
+                    completed: true,
+                    output: winner.output,
+                    stdout: winner.stdout,
+                    stderr: winner.stderr,
+                    exitCode: winner.exitCode,
+                    signal: winner.signal,
+                    truncated: winner.truncated,
+                    spillPath: winner.spillPath,
+                };
+            }
+            if (winner === 'abort' && input.onAbort === 'kill') {
+                entry.running.kill();
+                const result = await entry.done;
+                if (!result.truncated)
+                    await fs.unlink(entry.running.logPath);
+                this.entries.delete(entry.info.id);
+                return {
+                    completed: true,
+                    output: result.output,
+                    exitCode: result.exitCode,
+                    signal: result.signal,
+                    truncated: result.truncated,
+                    spillPath: result.spillPath,
+                };
+            }
+            entry.notify = true;
+            await this.notify(entry);
+            return {
+                completed: false,
+                terminal: { ...entry.info },
+                partialOutput: (await entry.running.snapshot()).text,
+                handoffReason: winner === 'abort' ? 'abort' : 'timeout',
+            };
+        }
+        catch (error) {
+            await fs.unlink(entry.running.logPath).catch(() => { });
+            this.entries.delete(entry.info.id);
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+            input.signal?.removeEventListener('abort', abort);
+        }
+    }
+    async create(input) {
+        return { ...(await this.start(input, input.notifyOnExit !== false)).info };
+    }
+    async list() {
+        return [...this.entries.values()].map((entry) => ({ ...entry.info }));
+    }
+    async read(input) {
+        const entry = this.get(input.id);
+        const offset = input.offset ?? 0, limit = input.limit;
+        if (!Number.isSafeInteger(offset) || offset < 0)
+            throw new Error('Terminal read offset must be a non-negative safe integer');
+        if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 0))
+            throw new Error('Terminal read limit must be a non-negative safe integer');
+        const range = await readRange(entry.running.logPath, {
+            offsetLine: offset + 1,
+            limitLines: limit === 0 ? 1 : (limit ?? Number.MAX_SAFE_INTEGER),
+        });
+        const endLine = limit === 0 ? offset : range.endLine;
+        return {
+            content: limit === 0 ? '' : range.content,
+            startLine: range.startLine,
+            endLine,
+            totalLines: range.totalLines,
+            ...(endLine < range.totalLines ? { nextOffset: endLine } : {}),
+            status: entry.info.status,
+            exitCode: entry.info.exitCode,
+        };
+    }
+    async signal(input) {
+        const entry = this.get(input.id);
+        if (!['SIGINT', 'SIGTERM', 'SIGKILL'].includes(input.signal))
+            throw new Error('Invalid signal');
+        if (entry.info.status !== 'running')
+            throw new Error('Terminal is not running');
+        const previous = entry.completionSignal;
+        entry.completionSignal = input.signal;
+        try {
+            entry.running.kill(input.signal);
+        }
+        catch (error) {
+            entry.completionSignal = previous;
+            throw error;
+        }
+        return { ...entry.info };
+    }
+    async destroy(input) {
+        const entry = this.get(input.id);
+        entry.destroyed = true;
+        // Kill the group even if its shell exited while descendants were still running.
+        entry.running.kill();
+        await entry.done.catch(() => { });
+        await fs.unlink(entry.running.logPath).catch((error) => {
+            if (error.code !== 'ENOENT')
+                throw error;
+        });
+        this.entries.delete(input.id);
+    }
+    async closeAll() {
+        await this.dispose();
+    }
+    async dispose() {
+        this.closed = true;
+        await Promise.all([...this.entries.keys()].map((id) => this.destroy({ id })));
+    }
+}