@ours.network/fleet 0.10.3 → 0.10.4

package/dist/web/service.js

@@ -0,0 +1,180 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync } from 'node:fs';
+import { userInfo } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { replaceFileAtomically } from '../atomic-file.js';
+import { FleetError } from '../application/errors.js';
+import { realExec } from '../exec.js';
+import { home, stateRoot } from '../paths.js';
+const VERSION = 2;
+export const WEB_SYSTEMD_UNIT = 'ours-fleet-web.service';
+export const WEB_LAUNCHD_LABEL = 'network.ours.fleet.web';
+export class WebServiceManager {
+    platform;
+    exec;
+    homeDir;
+    stateDir;
+    uid;
+    runtimeExecutable;
+    constructor(options = {}) {
+        const platform = options.platform ?? process.platform;
+        if (platform !== 'linux' && platform !== 'darwin')
+            throw new FleetError('capability_unavailable', `web service is unsupported on ${platform}`);
+        this.platform = platform;
+        this.exec = options.exec ?? realExec;
+        this.homeDir = options.homeDir ?? home();
+        this.stateDir = options.stateDir ?? join(stateRoot(), 'web');
+        this.uid = options.uid ?? process.getuid?.() ?? 501;
+        this.runtimeExecutable = options.runtimeExecutable ?? process.execPath;
+    }
+    get metadataPath() { return join(this.stateDir, 'service.json'); }
+    get definitionPath() {
+        return this.platform === 'linux'
+            ? join(this.homeDir, '.config', 'systemd', 'user', WEB_SYSTEMD_UNIT)
+            : join(this.homeDir, 'Library', 'LaunchAgents', `${WEB_LAUNCHD_LABEL}.plist`);
+    }
+    async install(script, port = 49_271, configuration) {
+        validatePort(port);
+        const resolvedScript = resolveExecutable(script, 'web CLI script');
+        const runtime = resolveExecutable(this.runtimeExecutable, 'Node runtime');
+        mkdirSync(dirname(this.definitionPath), { recursive: true, mode: 0o700 });
+        mkdirSync(this.stateDir, { recursive: true, mode: 0o700 });
+        chmodSync(this.stateDir, 0o700);
+        const config = configuration ? resolve(configuration) : undefined;
+        const metadata = {
+            version: VERSION, platform: this.platform, runtime, script: resolvedScript, port,
+            ...(config ? { configuration: config } : {}),
+        };
+        replaceFileAtomically(this.definitionPath, this.platform === 'linux'
+            ? systemdUnit(runtime, resolvedScript, port, config)
+            : launchdPlist(runtime, resolvedScript, port, config), 0o600);
+        replaceFileAtomically(this.metadataPath, JSON.stringify(metadata, null, 2) + '\n', 0o600);
+        if (this.platform === 'linux') {
+            await this.must('systemctl', ['--user', 'daemon-reload']);
+            await this.must('systemctl', ['--user', 'enable', WEB_SYSTEMD_UNIT]);
+            const linger = await this.exec('loginctl', ['show-user', userInfo().username, '-p', 'Linger', '--value']);
+            return [
+                `installed ${this.definitionPath}`,
+                linger.stdout.trim() === 'yes'
+                    ? 'login persistence available (linger enabled)'
+                    : `warning: login persistence requires linger; run: sudo loginctl enable-linger ${userInfo().username}`,
+            ];
+        }
+        return [`installed ${this.definitionPath}`, 'launchd service starts at login'];
+    }
+    async start() {
+        this.requireInstalled();
+        if (this.platform === 'linux') {
+            await this.must('systemctl', ['--user', 'start', WEB_SYSTEMD_UNIT]);
+            return;
+        }
+        const domain = `gui/${this.uid}`;
+        const loaded = await this.exec('launchctl', ['print', `${domain}/${WEB_LAUNCHD_LABEL}`]);
+        if (loaded.code === 0)
+            await this.must('launchctl', ['kickstart', `${domain}/${WEB_LAUNCHD_LABEL}`]);
+        else
+            await this.must('launchctl', ['bootstrap', domain, this.definitionPath]);
+    }
+    async stop() {
+        if (this.platform === 'linux') {
+            await this.must('systemctl', ['--user', 'stop', WEB_SYSTEMD_UNIT]);
+            return;
+        }
+        const result = await this.exec('launchctl', ['bootout', `gui/${this.uid}/${WEB_LAUNCHD_LABEL}`]);
+        if (result.code !== 0 && !/could not find service|no such process/i.test(`${result.stdout}\n${result.stderr}`))
+            throw new FleetError('control_unavailable', `launchctl bootout failed: ${result.stderr.trim()}`);
+    }
+    async restart() {
+        this.requireInstalled();
+        if (this.platform === 'linux') {
+            await this.must('systemctl', ['--user', 'restart', WEB_SYSTEMD_UNIT]);
+            return;
+        }
+        const result = await this.exec('launchctl', ['kickstart', '-k', `gui/${this.uid}/${WEB_LAUNCHD_LABEL}`]);
+        if (result.code !== 0) {
+            await this.stop();
+            await this.start();
+        }
+    }
+    async status() {
+        if (this.platform === 'linux') {
+            const result = await this.exec('systemctl', [
+                '--user', 'show', WEB_SYSTEMD_UNIT, '-p', 'LoadState', '-p', 'ActiveState',
+                '-p', 'SubState', '-p', 'ExecMainPID', '--no-pager',
+            ]);
+            return result.stdout.trim() || result.stderr.trim() || `exit ${result.code}`;
+        }
+        const result = await this.exec('launchctl', ['print', `gui/${this.uid}/${WEB_LAUNCHD_LABEL}`]);
+        return result.code === 0 ? result.stdout.trim() : `not loaded (${WEB_LAUNCHD_LABEL})`;
+    }
+    async uninstall() {
+        if (this.platform === 'linux') {
+            await this.exec('systemctl', ['--user', 'disable', '--now', WEB_SYSTEMD_UNIT]);
+            rmSync(this.definitionPath, { force: true });
+            rmSync(this.metadataPath, { force: true });
+            await this.exec('systemctl', ['--user', 'daemon-reload']);
+        }
+        else {
+            await this.stop();
+            rmSync(this.definitionPath, { force: true });
+            rmSync(this.metadataPath, { force: true });
+        }
+        return `uninstalled ${this.platform === 'linux' ? WEB_SYSTEMD_UNIT : WEB_LAUNCHD_LABEL}`;
+    }
+    readMetadata() {
+        try {
+            const parsed = JSON.parse(readFileSync(this.metadataPath, 'utf8'));
+            return parsed.version === VERSION && parsed.platform === this.platform
+                && typeof parsed.runtime === 'string' && typeof parsed.script === 'string'
+                && Number.isInteger(parsed.port) ? parsed : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    requireInstalled() {
+        if (!existsSync(this.definitionPath) || !this.readMetadata())
+            throw new FleetError('prerequisite_unavailable', 'web service is not installed; run `ours-fleet web install`');
+    }
+    async must(command, args) {
+        const result = await this.exec(command, args);
+        if (result.code !== 0)
+            throw new FleetError('control_unavailable', `${command} ${args.join(' ')} failed: ${result.stderr.trim() || `exit ${result.code}`}`);
+    }
+}
+function resolveExecutable(executable, label) {
+    const absolute = isAbsolute(executable) ? executable : resolve(executable);
+    try {
+        return realpathSync(absolute);
+    }
+    catch {
+        throw new FleetError('prerequisite_unavailable', `${label} does not exist: ${absolute}`);
+    }
+}
+function validatePort(port) {
+    if (!Number.isInteger(port) || port < 1 || port > 65_535)
+        throw new FleetError('invalid_request', 'service port must be between 1 and 65535');
+}
+function systemdQuote(value) {
+    return `"${value.replace(/[%\\"]/g, char => char === '%' ? '%%' : `\\${char}`)}"`;
+}
+export function systemdUnit(runtime, script, port, configuration) {
+    const config = configuration ? ` --configuration ${systemdQuote(configuration)}` : '';
+    return `[Unit]\nDescription=ours-fleet localhost web console\nAfter=default.target\n\n`
+        + `[Service]\nType=simple\nExecStart=${systemdQuote(runtime)} ${systemdQuote(script)} web serve --port ${port} --no-open${config}\n`
+        + `Restart=on-failure\nRestartSec=5\nTimeoutStopSec=15\n\n`
+        + `[Install]\nWantedBy=default.target\n`;
+}
+const xml = (value) => value.replace(/[&<>"']/g, char => ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;',
+}[char]));
+export function launchdPlist(runtime, script, port, configuration) {
+    const config = configuration
+        ? `<string>--configuration</string><string>${xml(configuration)}</string>` : '';
+    return `<?xml version="1.0" encoding="UTF-8"?>\n`
+        + `<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n`
+        + `<plist version="1.0"><dict>\n<key>Label</key><string>${WEB_LAUNCHD_LABEL}</string>\n`
+        + `<key>ProgramArguments</key><array><string>${xml(runtime)}</string><string>${xml(script)}</string><string>web</string>`
+        + `<string>serve</string><string>--port</string><string>${port}</string><string>--no-open</string>${config}</array>\n`
+        + `<key>RunAtLoad</key><true/><key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>\n`
+        + `<key>ProcessType</key><string>Background</string>\n</dict></plist>\n`;
+}

package/dist/web/terminal/bridge.d.ts

@@ -0,0 +1,27 @@
+import type { WebSocket } from 'ws';
+import { Tmux } from '../../tmux.js';
+import type { RoleRepository } from '../../application/role-repository.js';
+import type { AuditSink } from '../audit.js';
+type Constructor<T> = new (...args: any[]) => T;
+/** Node exposes these CommonJS xterm packages under `default`; Vite may expose named exports. */
+export declare function resolveModuleConstructor<T>(module: unknown, name: string): Constructor<T>;
+export interface TerminalBridgeManagerOptions {
+    repository: RoleRepository;
+    audit: AuditSink;
+    tmux?: Tmux;
+    maxBridges?: number;
+    graceMs?: number;
+    loadPty?: () => Promise<typeof import('node-pty')>;
+}
+export declare class TerminalBridgeManager {
+    private readonly options;
+    private readonly bridges;
+    private ptyModule?;
+    private ptyError?;
+    constructor(options: TerminalBridgeManagerOptions);
+    available(): Promise<boolean>;
+    diagnostic(): string | undefined;
+    connect(socket: WebSocket, roleId: string, hello: Record<string, unknown>): Promise<void>;
+    close(): Promise<void>;
+}
+export {};

package/dist/web/terminal/bridge.js

@@ -0,0 +1,317 @@
+import { randomUUID } from 'node:crypto';
+import { Tmux, tmuxArgs } from '../../tmux.js';
+import { FleetError } from '../../application/errors.js';
+const OUTPUT = 0x01;
+const INPUT = 0x02;
+const MAX_INPUT = 8 * 1024;
+const RING_BYTES = 2 * 1024 * 1024;
+const RING_FRAMES = 10_000;
+const LEASE_MS = 30_000;
+/** Node exposes these CommonJS xterm packages under `default`; Vite may expose named exports. */
+export function resolveModuleConstructor(module, name) {
+    const record = module && typeof module === 'object' ? module : {};
+    const fallback = record.default && typeof record.default === 'object'
+        ? record.default : {};
+    const value = record[name] ?? fallback[name];
+    if (typeof value !== 'function')
+        throw new FleetError('capability_unavailable', `${name} constructor is unavailable`);
+    return value;
+}
+export class TerminalBridgeManager {
+    options;
+    bridges = new Map();
+    ptyModule;
+    ptyError;
+    constructor(options) {
+        this.options = options;
+    }
+    async available() {
+        if (this.ptyModule)
+            return true;
+        if (this.ptyError)
+            return false;
+        try {
+            this.ptyModule = await (this.options.loadPty?.() ?? import('node-pty'));
+            return true;
+        }
+        catch (error) {
+            this.ptyError = error.message;
+            return false;
+        }
+    }
+    diagnostic() { return this.ptyError; }
+    async connect(socket, roleId, hello) {
+        const role = await this.options.repository.get(roleId);
+        if (!role)
+            throw new FleetError('role_not_found', `no such role '${roleId}'`);
+        if (role.configuredBackend !== 'tmux' && role.detectedBackend !== 'tmux')
+            throw new FleetError('capability_unavailable', 'terminal is only available for tmux roles');
+        if (!await this.available())
+            throw new FleetError('capability_unavailable', `node-pty unavailable: ${this.ptyError ?? 'not installed'}`);
+        let bridge = this.bridges.get(roleId);
+        if (!bridge) {
+            if (this.bridges.size >= (this.options.maxBridges ?? 12))
+                throw new FleetError('rate_limited', 'terminal bridge limit reached');
+            const tmux = this.options.tmux ?? new Tmux();
+            if (!await tmux.has(roleId))
+                throw new FleetError('offline', `tmux session '${roleId}' is offline`, { provesOffline: true });
+            bridge = await TerminalBridge.create(roleId, tmux, this.ptyModule, this.options.audit, () => this.bridges.delete(roleId), this.options.graceMs ?? 30_000);
+            this.bridges.set(roleId, bridge);
+        }
+        bridge.add(socket, hello);
+    }
+    async close() {
+        for (const bridge of this.bridges.values())
+            bridge.dispose('server_shutdown');
+        this.bridges.clear();
+    }
+}
+class TerminalBridge {
+    roleId;
+    pty;
+    projection;
+    audit;
+    onDisposed;
+    graceMs;
+    id = randomUUID();
+    viewers = new Map();
+    ring = [];
+    ringBytes = 0;
+    seq = 0n;
+    cols = 120;
+    rows = 36;
+    lease;
+    cleanupTimer;
+    disposed = false;
+    constructor(roleId, pty, projection, audit, onDisposed, graceMs) {
+        this.roleId = roleId;
+        this.pty = pty;
+        this.projection = projection;
+        this.audit = audit;
+        this.onDisposed = onDisposed;
+        this.graceMs = graceMs;
+    }
+    static async create(roleId, tmux, ptyModule, audit, onDisposed, graceMs) {
+        const [headless, serialization] = await Promise.all([
+            import('@xterm/headless'), import('@xterm/addon-serialize'),
+        ]);
+        const Terminal = resolveModuleConstructor(headless, 'Terminal');
+        const SerializeAddon = resolveModuleConstructor(serialization, 'SerializeAddon');
+        const terminal = new Terminal({ cols: 120, rows: 36, scrollback: 5_000, allowProposedApi: true });
+        const serialize = new SerializeAddon();
+        terminal.loadAddon(serialize);
+        const history = await tmux.captureHistory(roleId, 5_000).catch(() => '');
+        if (history)
+            await new Promise(resolve => terminal.write(history, resolve));
+        const env = Object.fromEntries(['PATH', 'HOME', 'LANG', 'LC_ALL'].flatMap(key => process.env[key] ? [[key, process.env[key]]] : []));
+        const pty = ptyModule.spawn('tmux', tmuxArgs(roleId, ['attach-session', '-t', roleId]), {
+            name: 'xterm-256color', cols: 120, rows: 36,
+            cwd: process.env.HOME ?? process.cwd(), env: { ...env, TERM: 'xterm-256color' },
+        });
+        const projection = {
+            write: (data, callback) => terminal.write(data, callback),
+            resize: (cols, rows) => terminal.resize(cols, rows),
+            dispose: () => { serialize.dispose(); terminal.dispose(); },
+            serialize: () => serialize.serialize(),
+        };
+        const bridge = new TerminalBridge(roleId, pty, projection, audit, onDisposed, graceMs);
+        pty.onData(data => bridge.output(new TextEncoder().encode(data)));
+        pty.onExit(() => bridge.dispose('tmux_client_exit'));
+        await audit.record({ roleId, action: 'terminal.bridge_open', result: 'succeeded' });
+        return bridge;
+    }
+    add(socket, hello) {
+        if (this.disposed)
+            throw new FleetError('stale_state', 'terminal bridge exited');
+        if (this.cleanupTimer)
+            clearTimeout(this.cleanupTimer);
+        const viewer = {
+            socket, sessionLabel: randomUUID().slice(0, 8), resyncPending: false,
+            tokens: 32 * 1024, tokenAt: Date.now(),
+        };
+        this.viewers.set(socket, viewer);
+        const lastSeq = parseSeq(hello.lastSeq);
+        const bridgeMatches = hello.bridgeId === this.id;
+        const first = this.ring[0]?.seq ?? this.seq;
+        if (bridgeMatches && lastSeq !== undefined && lastSeq >= first - 1n && lastSeq <= this.seq) {
+            for (const frame of this.ring)
+                if (frame.seq > lastSeq)
+                    socket.send(binaryFrame(frame));
+        }
+        else {
+            socket.send(JSON.stringify({
+                type: 'snapshot', atSeq: this.seq.toString(), encoding: 'utf8',
+                data: this.projection.serialize(),
+            }));
+        }
+        socket.send(JSON.stringify({
+            type: 'ready', bridgeId: this.id, firstSeq: first.toString(), lastSeq: this.seq.toString(),
+            mode: this.lease?.socket === socket ? 'controller' : 'viewer',
+            leaseExpiresAt: this.lease ? new Date(this.lease.expiresAt).toISOString() : null,
+        }));
+        socket.on('message', (data, binary) => this.message(viewer, data, binary));
+        socket.on('close', () => this.remove(socket));
+        void this.audit.record({ roleId: this.roleId, action: 'terminal.viewer_open', result: 'succeeded' });
+    }
+    output(bytes) {
+        if (this.disposed || bytes.byteLength === 0)
+            return;
+        this.seq++;
+        const frame = { seq: this.seq, bytes };
+        this.ring.push(frame);
+        this.ringBytes += bytes.byteLength;
+        while (this.ring.length > RING_FRAMES || this.ringBytes > RING_BYTES) {
+            this.ringBytes -= this.ring.shift().bytes.byteLength;
+        }
+        this.projection.write(bytes);
+        const payload = binaryFrame(frame);
+        for (const viewer of this.viewers.values()) {
+            if (viewer.socket.bufferedAmount > 4 * 1024 * 1024) {
+                viewer.socket.close(4408, 'slow consumer');
+                continue;
+            }
+            if (viewer.socket.bufferedAmount > 1024 * 1024) {
+                viewer.resyncPending = true;
+                continue;
+            }
+            if (viewer.resyncPending) {
+                viewer.socket.send(JSON.stringify({ type: 'resync.required', reason: 'slow_consumer' }));
+                viewer.resyncPending = false;
+                continue;
+            }
+            viewer.socket.send(payload);
+        }
+    }
+    message(viewer, data, binary) {
+        try {
+            if (binary) {
+                const bytes = new Uint8Array(data);
+                if (bytes.byteLength < 9 || bytes[0] !== INPUT || bytes.byteLength - 9 > MAX_INPUT)
+                    throw new FleetError('invalid_request', 'invalid terminal input frame');
+                if (!this.validLease(viewer.socket))
+                    throw new FleetError('forbidden', 'writer lease required');
+                const input = bytes.slice(9);
+                if (!this.consume(viewer, input.byteLength))
+                    throw new FleetError('rate_limited', 'terminal input rate exceeded');
+                this.pty.write(new TextDecoder().decode(input));
+                this.renewLease();
+                return;
+            }
+            const message = JSON.parse(data.toString());
+            if (message.type === 'lease.request')
+                this.requestLease(viewer);
+            else if (message.type === 'lease.release')
+                this.releaseLease(viewer.socket);
+            else if (message.type === 'resize')
+                this.resize(viewer, message);
+            else
+                throw new FleetError('invalid_request', 'unknown terminal control message');
+        }
+        catch (error) {
+            const fleet = error instanceof FleetError ? error : new FleetError('invalid_request', error.message);
+            viewer.socket.send(JSON.stringify({ type: 'error', code: fleet.code, message: fleet.message }));
+            if (fleet.code === 'rate_limited')
+                viewer.socket.close(4408, fleet.message);
+        }
+    }
+    requestLease(viewer) {
+        const now = Date.now();
+        if (this.lease && this.lease.expiresAt > now && this.lease.socket !== viewer.socket) {
+            viewer.socket.send(JSON.stringify({
+                type: 'error', code: 'lease_held',
+                message: `controlled by viewer ${this.viewers.get(this.lease.socket)?.sessionLabel ?? 'unknown'}`,
+            }));
+            return;
+        }
+        this.lease = { socket: viewer.socket, id: randomUUID(), expiresAt: now + LEASE_MS };
+        viewer.socket.send(JSON.stringify({
+            type: 'lease.granted', leaseId: this.lease.id,
+            leaseExpiresAt: new Date(this.lease.expiresAt).toISOString(),
+        }));
+        void this.audit.record({ roleId: this.roleId, action: 'terminal.lease_acquire', result: 'succeeded' });
+    }
+    releaseLease(socket) {
+        if (this.lease?.socket !== socket)
+            return;
+        this.lease = undefined;
+        socket.send(JSON.stringify({ type: 'lease.released' }));
+        void this.audit.record({ roleId: this.roleId, action: 'terminal.lease_release', result: 'succeeded' });
+    }
+    resize(viewer, message) {
+        if (!this.validLease(viewer.socket) || message.leaseId !== this.lease?.id)
+            throw new FleetError('forbidden', 'writer lease required');
+        const cols = clamp(Number(message.cols), 80, 240);
+        const rows = clamp(Number(message.rows), 24, 80);
+        this.cols = cols;
+        this.rows = rows;
+        this.pty.resize(cols, rows);
+        this.projection.resize(cols, rows);
+        this.renewLease();
+    }
+    validLease(socket) {
+        if (this.lease && this.lease.expiresAt <= Date.now())
+            this.lease = undefined;
+        return this.lease?.socket === socket;
+    }
+    renewLease() {
+        if (this.lease)
+            this.lease.expiresAt = Date.now() + LEASE_MS;
+    }
+    consume(viewer, amount) {
+        const now = Date.now();
+        viewer.tokens = Math.min(32 * 1024, viewer.tokens + (now - viewer.tokenAt) * 16);
+        viewer.tokenAt = now;
+        if (amount > viewer.tokens)
+            return false;
+        viewer.tokens -= amount;
+        return true;
+    }
+    remove(socket) {
+        this.releaseLease(socket);
+        this.viewers.delete(socket);
+        void this.audit.record({ roleId: this.roleId, action: 'terminal.viewer_close', result: 'succeeded' });
+        if (!this.viewers.size)
+            this.cleanupTimer = setTimeout(() => this.dispose('idle_grace_expired'), this.graceMs);
+    }
+    dispose(reason) {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        if (this.cleanupTimer)
+            clearTimeout(this.cleanupTimer);
+        for (const viewer of this.viewers.values()) {
+            if (viewer.socket.readyState === viewer.socket.OPEN) {
+                viewer.socket.send(JSON.stringify({ type: 'terminal.exit', reason }));
+                viewer.socket.close(1001, reason);
+            }
+        }
+        this.viewers.clear();
+        try {
+            this.pty.kill();
+        }
+        catch { /* already exited */ }
+        this.projection.dispose();
+        this.onDisposed();
+        void this.audit.record({ roleId: this.roleId, action: 'terminal.bridge_close', result: reason });
+    }
+}
+function binaryFrame(frame) {
+    const payload = new Uint8Array(9 + frame.bytes.byteLength);
+    payload[0] = OUTPUT;
+    new DataView(payload.buffer).setBigUint64(1, frame.seq);
+    payload.set(frame.bytes, 9);
+    return payload;
+}
+function parseSeq(value) {
+    try {
+        return value === undefined ? undefined : BigInt(String(value));
+    }
+    catch {
+        return undefined;
+    }
+}
+function clamp(value, min, max) {
+    if (!Number.isFinite(value))
+        throw new FleetError('invalid_request', 'terminal size must be numeric');
+    return Math.min(Math.max(Math.trunc(value), min), max);
+}