@platless/axom-cli 0.5.9 → 0.6.52

package/dist/workstation/keepers/terminal/sessions.js

@@ -0,0 +1,526 @@
+import { randomUUID } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { KeeperMethodError } from '../kit/protocol.js';
+import { TERMINAL_GRID_LIMITS as limits, } from './gridProtocol.js';
+import { TerminalFrames } from './frames.js';
+import { TerminalScreen } from './screen.js';
+import { createTerminalInput } from './input.js';
+import { createTerminalMetadata } from './metadata.js';
+export const NATIVE_PTY_OPERATIONS = new Set(['attach', 'poll', 'resize', 'input', 'scroll', 'detach', 'close']);
+const bad = (message) => { throw new KeeperMethodError('bad_request', message); };
+const fail = (code, message) => { throw new KeeperMethodError(code, message); };
+const ok = { ok: true };
+const nativeScheduler = {
+    schedule(callback, delay) { const timer = setTimeout(callback, delay); timer.unref(); return { dispose: () => clearTimeout(timer) }; },
+};
+const basename = (name) => path.basename(name.trim()).replace(/^-/, '');
+/** Keeper-owned sessions: ordered within a PTY, independent between PTYs. */
+export class NativePtySessions {
+    options;
+    sessions = new Map();
+    now;
+    scheduler;
+    module;
+    unavailable;
+    disposed = false;
+    constructor(options = {}) {
+        this.options = options;
+        this.now = options.now ?? Date.now;
+        this.scheduler = options.scheduler ?? nativeScheduler;
+        try {
+            this.module = (options.loadPty ?? (() => createRequire(import.meta.url)('node-pty')))();
+        }
+        catch {
+            this.unavailable = 'Terminal native dependency unavailable; reinstall CLI with optional node-pty support';
+        }
+    }
+    list() {
+        return { schema: 1, limits: { ...limits }, sessions: [...this.sessions.values()].map(s => this.descriptor(s)) };
+    }
+    async create(params, launch) {
+        this.available();
+        request(params);
+        keys(params, ['id', 'cwd', 'registrationId']);
+        const id = identifier(params, 'id');
+        if (params.registrationId !== undefined)
+            identifier(params, 'registrationId');
+        if (params.cwd !== undefined && (typeof params.cwd !== 'string' || params.cwd.includes('\0')))
+            bad('Invalid cwd');
+        const existing = this.sessions.get(id);
+        if (existing)
+            return this.descriptor(existing);
+        this.checkLimit();
+        const resolved = await launch();
+        this.available();
+        const concurrent = this.sessions.get(id);
+        if (concurrent)
+            return this.descriptor(concurrent);
+        this.checkLimit();
+        const cols = 100;
+        const rows = 30;
+        const screen = new TerminalScreen(cols, rows);
+        let pty;
+        try {
+            pty = this.module.spawn(resolved.shell, ['-l'], { name: 'xterm-256color', cwd: resolved.cwd, cols, rows, env: { ...resolved.env, TERM: 'xterm-256color', COLORTERM: 'truecolor' } });
+        }
+        catch (error) {
+            screen.dispose();
+            throw error;
+        }
+        const createdAt = this.now();
+        const shell = basename(resolved.shell);
+        const s = {
+            value: { id, ...(typeof params.registrationId === 'string' ? { registrationId: params.registrationId } : {}), incarnation: randomUUID(), title: 'Terminal', cwd: resolved.cwd, cwdSource: 'launch', cols, rows, createdAt, exited: false, exitCode: null },
+            shell, shellNames: new Set([shell]), shellNameStarted: false, pty, screen, frames: new TerminalFrames(), attachments: new Map(), geometry: 1,
+            closed: false, queue: Promise.resolve(), rendered: Promise.resolve(), pendingBytes: 0, dirty: true, capturedAt: -Infinity,
+            listeners: [], input: createTerminalInput(screen), exitedAt: 0, observed: { label: shell, state: 'idle', since: createdAt },
+        };
+        const context = { pty, screen, session: () => this.descriptor(s), changed: () => this.dirty(s) };
+        try {
+            s.input = this.options.createInput?.(context) ?? s.input;
+            s.metadata = (this.options.createMetadata ?? createTerminalMetadata)(context);
+            this.capture(s, true);
+            s.listeners.push(disposable(pty.onData(data => this.output(s, data))), disposable(pty.onExit(event => {
+                if (s.closed)
+                    return;
+                s.shellNameTimer?.dispose();
+                s.shellNameTimer = undefined;
+                s.value.exited = true;
+                s.value.exitCode = event.exitCode;
+                s.exitedAt = this.now();
+                this.dirty(s);
+            })), screen.onReply(data => { if (!s.closed && !s.value.exited) {
+                try {
+                    pty.write(data);
+                }
+                catch (error) {
+                    this.failed(s, error);
+                }
+            } }));
+            this.sessions.set(id, s);
+        }
+        catch (error) {
+            await this.close(s);
+            throw error;
+        }
+        return this.descriptor(s);
+    }
+    async operate(op, params) {
+        request(params);
+        const id = identifier(params, 'id');
+        const incarnation = identifier(params, 'incarnation');
+        const s = this.sessions.get(id);
+        if (!s) {
+            if (op === 'close' || op === 'detach')
+                return ok;
+            return fail('pty_not_found', 'Terminal session not found; keeper restart loses live PTYs');
+        }
+        if (s.value.incarnation !== incarnation)
+            return fail('pty_incarnation_mismatch', 'Terminal incarnation no longer matches');
+        return this.ordered(s, async () => {
+            if (s.closed) {
+                if (op === 'close' || op === 'detach')
+                    return ok;
+                return fail('pty_not_found', 'Terminal session is closed');
+            }
+            if (op === 'close') {
+                keys(params, ['id', 'incarnation']);
+                await this.close(s);
+                return ok;
+            }
+            await this.expire(s);
+            const clientId = identifier(params, 'clientId');
+            const ref = ['id', 'incarnation', 'clientId'];
+            if (op === 'detach') {
+                keys(params, ref);
+                this.release(s, clientId);
+                await this.capacity(s);
+                return ok;
+            }
+            if (op === 'attach') {
+                keys(params, [...ref, 'cols', 'rows']);
+                const cols = integer(params, 'cols', limits.minCols, limits.maxCols);
+                const rows = integer(params, 'rows', limits.minRows, limits.maxRows);
+                if (!s.attachments.has(clientId) && s.attachments.size >= limits.maxAttachments)
+                    return fail('pty_limit', 'Terminal attachment limit exceeded');
+                const previous = s.attachments.get(clientId);
+                s.attachments.set(clientId, { cols, rows, expires: this.now() + limits.leaseMs });
+                try {
+                    await this.capacity(s);
+                    await this.settle(s);
+                    this.capture(s, true);
+                }
+                catch (error) {
+                    if (previous)
+                        s.attachments.set(clientId, previous);
+                    else
+                        this.release(s, clientId);
+                    try {
+                        await this.capacity(s);
+                    }
+                    catch (rollback) {
+                        this.failed(s, rollback);
+                    }
+                    throw error;
+                }
+                this.scheduleLease(s);
+                return s.frames.poll(0);
+            }
+            const attachment = s.attachments.get(clientId);
+            if (!attachment)
+                return fail('pty_attachment_expired', 'Terminal attachment expired; attach again');
+            if (op === 'poll') {
+                keys(params, [...ref, 'after']);
+                const after = integer(params, 'after', 0, Number.MAX_SAFE_INTEGER);
+                attachment.expires = this.now() + limits.leaseMs;
+                this.scheduleLease(s);
+                await this.captureDue(s);
+                return s.frames.poll(after);
+            }
+            if (op === 'resize') {
+                keys(params, [...ref, 'cols', 'rows']);
+                const cols = integer(params, 'cols', limits.minCols, limits.maxCols);
+                const rows = integer(params, 'rows', limits.minRows, limits.maxRows);
+                const previous = { ...attachment };
+                attachment.cols = cols;
+                attachment.rows = rows;
+                try {
+                    await this.capacity(s);
+                }
+                catch (error) {
+                    Object.assign(attachment, previous);
+                    throw error;
+                }
+            }
+            else if (op === 'input') {
+                const event = input(params, ref);
+                await this.settle(s);
+                this.assertRunning(s);
+                if (event.kind === 'pointer' || event.kind === 'button')
+                    this.coordinates(s, event);
+                const data = s.input.input(event, clientId, this.inputContext(s));
+                if (data)
+                    s.pty.write(data);
+            }
+            else if (op === 'scroll') {
+                keys(params, [...ref, 'lines', 'x', 'y', 'modifiers', 'geometry']);
+                const gesture = { lines: integer(params, 'lines', -Number.MAX_SAFE_INTEGER, Number.MAX_SAFE_INTEGER), ...position(params), modifiers: integer(params, 'modifiers', 0, 15) };
+                await this.settle(s);
+                this.coordinates(s, gesture);
+                const data = s.input.scroll(gesture, clientId, this.inputContext(s));
+                if (data) {
+                    this.assertRunning(s);
+                    s.pty.write(data);
+                }
+                else if (data === undefined && s.screen.state().buffer === 'normal') {
+                    s.screen.scroll(gesture.lines);
+                    this.dirty(s);
+                }
+            }
+            else
+                return bad('Unsupported terminal operation');
+            attachment.expires = this.now() + limits.leaseMs;
+            this.scheduleLease(s);
+            return ok;
+        });
+    }
+    activity() {
+        const metrics = { ptyOpen: 0, ptyActive: 0, ptyExited: 0 };
+        const items = [...this.sessions.values()].map(s => {
+            if (s.value.exited) {
+                metrics.ptyExited++;
+                return { type: 'pty', id: s.value.id, label: s.shell.slice(0, 64), state: 'exited', sinceEpochMs: s.exitedAt };
+            }
+            metrics.ptyOpen++;
+            let foreground = '';
+            try {
+                foreground = basename(s.pty.process);
+            }
+            catch { /* process can disappear during exit */ }
+            const active = foreground !== '' && !s.shellNames.has(foreground);
+            const label = (active ? foreground : s.shell).slice(0, 64);
+            const state = active ? 'active' : 'idle';
+            if (active)
+                metrics.ptyActive++;
+            if (s.observed.label !== label || s.observed.state !== state)
+                s.observed = { label, state, since: this.now() };
+            return { type: 'pty', id: s.value.id, label, state, sinceEpochMs: s.observed.since };
+        });
+        return { metrics, items };
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        await Promise.all([...this.sessions.values()].map(s => this.ordered(s, () => this.close(s))));
+    }
+    descriptor(s) { return { ...s.value, ...s.metadata?.read() }; }
+    available() {
+        if (this.disposed)
+            fail('pty_unavailable', 'Terminal host is disposed');
+        if (!this.module)
+            fail('pty_unavailable', this.unavailable ?? 'Terminal native dependency unavailable');
+    }
+    checkLimit() { if (this.sessions.size >= limits.maxSessions)
+        fail('pty_limit', 'Terminal session limit exceeded'); }
+    scheduleShellName(s, attempt = 0) {
+        const live = () => !s.closed && !s.value.exited && !this.disposed;
+        if (!live())
+            return;
+        s.shellNameTimer = this.scheduler.schedule(() => {
+            s.shellNameTimer = undefined;
+            if (!live())
+                return;
+            const retry = () => { if (attempt < 2)
+                this.scheduleShellName(s, attempt + 1); };
+            // Query the original shell PID: the foreground process may be a running command.
+            void Promise.resolve().then(() => live() ? (this.options.shellProcessName ?? defaultShellProcessName)(s.pty.pid) : null).then(name => {
+                if (!live())
+                    return;
+                const shell = name && basename(name);
+                if (shell && shell !== 'spawn-helper')
+                    s.shellNames.add(shell);
+                else
+                    retry();
+            }, retry);
+        }, this.options.shellNameDelayMs ?? 250);
+    }
+    ordered(s, action) {
+        const operation = s.queue.then(action);
+        s.queue = operation.catch(() => { });
+        return operation;
+    }
+    async settle(s) {
+        for (;;) {
+            const rendered = s.rendered;
+            await rendered;
+            if (rendered === s.rendered)
+                break;
+        }
+        if (s.failure)
+            throw s.failure;
+    }
+    output(s, data) {
+        if (s.closed || !data || s.failure)
+            return;
+        // node-pty initially runs a spawn-helper trampoline at this PID. First output
+        // starts the bounded lookup after shell startup, once per session.
+        if (!s.shellNameStarted) {
+            s.shellNameStarted = true;
+            this.scheduleShellName(s);
+        }
+        const bytes = Buffer.byteLength(data);
+        s.pendingBytes += bytes;
+        try {
+            if (s.pendingBytes > 256 * 1024)
+                s.pty.pause();
+            s.metadata?.onData?.(data);
+            // Submit directly to xterm's ordered parser; chaining writes costs one timer per PTY chunk.
+            s.rendered = s.screen.write(data);
+            void s.rendered.then(() => {
+                s.pendingBytes -= bytes;
+                try {
+                    if (!s.closed && !s.value.exited && s.pendingBytes < 64 * 1024)
+                        s.pty.resume();
+                }
+                catch (error) {
+                    this.failed(s, error);
+                }
+                this.dirty(s);
+            }, error => this.failed(s, error));
+            this.dirty(s);
+        }
+        catch (error) {
+            this.failed(s, error);
+        }
+    }
+    failed(s, error) { if (!s.closed) {
+        s.failure = error;
+        s.captureTimer?.dispose();
+        s.captureTimer = undefined;
+    } }
+    dirty(s) {
+        if (s.closed || s.failure)
+            return;
+        s.dirty = true;
+        if (!s.captureTimer)
+            s.captureTimer = this.scheduler.schedule(() => {
+                s.captureTimer = undefined;
+                void this.ordered(s, async () => { if (s.closed)
+                    return; await this.settle(s); this.capture(s); }).catch(error => { if (!(error instanceof KeeperMethodError && error.code === 'pty_snapshot_too_large'))
+                    this.failed(s, error); });
+            }, Math.max(0, 50 - (this.now() - s.capturedAt)));
+    }
+    async captureDue(s) {
+        if (s.dirty && this.now() - s.capturedAt < 50) {
+            s.captureTimer?.dispose();
+            s.captureTimer = undefined;
+            await new Promise(resolve => this.scheduler.schedule(resolve, 50 - (this.now() - s.capturedAt)));
+        }
+        await this.settle(s);
+        this.capture(s, true);
+    }
+    capture(s, force = false) {
+        if (!s.dirty || (!force && this.now() - s.capturedAt < 50))
+            return;
+        s.frames.publish(s.screen.capture(), this.descriptor(s), s.geometry);
+        s.dirty = false;
+        s.capturedAt = this.now();
+        s.captureTimer?.dispose();
+        s.captureTimer = undefined;
+    }
+    async capacity(s) {
+        if (!s.attachments.size)
+            return;
+        const cols = Math.min(...[...s.attachments.values()].map(a => a.cols));
+        const rows = Math.min(...[...s.attachments.values()].map(a => a.rows));
+        if (cols === s.value.cols && rows === s.value.rows)
+            return;
+        await this.settle(s);
+        if (!s.value.exited)
+            s.pty.resize(cols, rows);
+        try {
+            await s.screen.resize(cols, rows);
+            await this.settle(s);
+        }
+        catch (error) {
+            // A native emulator failure may have changed part of the grid. Never publish or accept input against uncertain geometry.
+            this.failed(s, error);
+            try {
+                if (!s.value.exited)
+                    s.pty.resize(s.value.cols, s.value.rows);
+            }
+            catch (rollback) {
+                this.failed(s, rollback);
+            }
+            throw error;
+        }
+        s.value.cols = cols;
+        s.value.rows = rows;
+        s.geometry++;
+        this.dirty(s);
+    }
+    inputContext(s) { return { cols: s.value.cols, rows: s.value.rows, geometry: s.geometry, modes: s.screen.state().modes }; }
+    coordinates(s, event) {
+        if (event.geometry !== s.geometry)
+            fail('pty_geometry_mismatch', 'Terminal geometry changed');
+        if (event.x >= s.value.cols || event.y >= s.value.rows)
+            bad('Terminal coordinates outside geometry');
+    }
+    assertRunning(s) { if (s.value.exited)
+        fail('pty_exited', 'Terminal has exited'); }
+    release(s, clientId) {
+        if (s.attachments.delete(clientId))
+            s.input.release(clientId);
+        this.scheduleLease(s);
+    }
+    async expire(s) {
+        let changed = false;
+        for (const [id, attachment] of s.attachments)
+            if (attachment.expires <= this.now()) {
+                this.release(s, id);
+                changed = true;
+            }
+        if (changed)
+            await this.capacity(s);
+    }
+    scheduleLease(s) {
+        s.leaseTimer?.dispose();
+        s.leaseTimer = undefined;
+        if (s.closed || this.disposed || !s.attachments.size)
+            return;
+        const expires = Math.min(...[...s.attachments.values()].map(attachment => attachment.expires));
+        s.leaseTimer = this.scheduler.schedule(() => {
+            s.leaseTimer = undefined;
+            void this.ordered(s, () => this.expire(s)).catch(error => this.failed(s, error)).finally(() => this.scheduleLease(s));
+        }, Math.max(0, expires - this.now()));
+    }
+    async close(s) {
+        if (s.closed)
+            return;
+        s.closed = true;
+        if (this.sessions.get(s.value.id) === s)
+            this.sessions.delete(s.value.id);
+        s.shellNameTimer?.dispose();
+        s.shellNameTimer = undefined;
+        s.captureTimer?.dispose();
+        s.captureTimer = undefined;
+        s.leaseTimer?.dispose();
+        s.leaseTimer = undefined;
+        for (const listener of s.listeners)
+            listener.dispose();
+        for (const id of [...s.attachments.keys()])
+            this.release(s, id);
+        s.input.dispose();
+        s.metadata?.dispose?.();
+        try {
+            if (!s.value.exited)
+                s.pty.kill();
+        }
+        finally {
+            s.screen.dispose();
+            await s.rendered.catch(() => { });
+        }
+    }
+}
+function disposable(value) {
+    return value && typeof value.dispose === 'function' ? value : { dispose: () => { } };
+}
+function request(params) { if (Buffer.byteLength(JSON.stringify(params)) > limits.maxRequestBytes)
+    bad('Terminal request exceeds limit'); }
+function keys(params, allowed) { if (Object.keys(params).some(key => !allowed.includes(key)))
+    bad('Unexpected terminal parameter'); }
+function identifier(params, name) {
+    const value = params[name];
+    if (typeof value !== 'string' || !/^[A-Za-z0-9_.:-]{1,128}$/.test(value))
+        return bad(`Invalid ${name}`);
+    return value;
+}
+function integer(params, name, min, max) {
+    const value = params[name];
+    if (!Number.isSafeInteger(value) || value < min || value > max)
+        return bad(`Invalid ${name}`);
+    return value;
+}
+function position(params) {
+    return { x: integer(params, 'x', 0, limits.maxCols - 1), y: integer(params, 'y', 0, limits.maxRows - 1), geometry: integer(params, 'geometry', 1, Number.MAX_SAFE_INTEGER) };
+}
+function input(params, ref) {
+    switch (params.kind) {
+        case 'text':
+        case 'paste':
+            keys(params, [...ref, 'kind', 'text']);
+            if (typeof params.text !== 'string' || Buffer.byteLength(params.text) > limits.maxInputBytes)
+                return bad('Terminal input exceeds limit');
+            return { kind: params.kind, text: params.text };
+        case 'key':
+            keys(params, [...ref, 'kind', 'usage', 'down', 'modifiers']);
+            if (typeof params.down !== 'boolean')
+                return bad('Invalid down');
+            return { kind: 'key', usage: integer(params, 'usage', 0, 65535), down: params.down, modifiers: integer(params, 'modifiers', 0, 15) };
+        case 'pointer':
+        case 'button': {
+            keys(params, [...ref, 'kind', 'x', 'y', 'geometry', 'modifiers', ...(params.kind === 'button' ? ['button', 'down'] : [])]);
+            const point = { ...position(params), modifiers: integer(params, 'modifiers', 0, 15) };
+            if (params.kind === 'pointer')
+                return { kind: 'pointer', ...point };
+            if (typeof params.down !== 'boolean')
+                return bad('Invalid down');
+            return { kind: 'button', ...point, button: integer(params, 'button', 0, 2), down: params.down };
+        }
+        case 'release':
+            keys(params, [...ref, 'kind']);
+            return { kind: 'release' };
+        default: return bad('Invalid terminal input kind');
+    }
+}
+/** This lookup is never awaited by poll/input/activity and never exposes process arguments. */
+function defaultShellProcessName(pid) {
+    if (process.platform !== 'darwin')
+        return Promise.resolve(null);
+    return new Promise(resolve => {
+        execFile('ps', ['-o', 'ucomm=', '-p', String(pid)], { timeout: 1000 }, (error, stdout) => resolve(error ? null : stdout.trim() || null));
+    });
+}

package/dist/workstation/managedInstall.js

@@ -0,0 +1,57 @@
+import { lstatSync, readFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { LocalControlError } from './control/protocol.js';
+const schema = z.object({ schemaVersion: z.literal(1), source: z.literal('managed'), prefix: z.string(), nodePath: z.string(), npmPath: z.string(), cliPath: z.string(), entryPath: z.string(), runtimeVersion: z.string().regex(/^24\.\d+\.\d+$/), architecture: z.enum(['arm64', 'x64']) }).strict();
+function plannedRealPath(value) {
+    try {
+        return realpathSync(value);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT' || path.dirname(value) === value)
+            throw error;
+        return path.join(plannedRealPath(path.dirname(value)), path.basename(value));
+    }
+}
+/** This synchronous variant is shared by the existing synchronous service-context constructors. */
+export function loadManagedCliInstallSync(packageRoot) {
+    let root;
+    try {
+        root = realpathSync(packageRoot);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    const prefix = path.resolve(root, '../../../..');
+    if (root !== path.join(prefix, 'lib/node_modules/@platless/axom-cli'))
+        return null;
+    const file = path.join(prefix, 'install.json');
+    let found = false;
+    try {
+        const stat = lstatSync(file);
+        found = true;
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 16384 || (process.getuid && stat.uid !== process.getuid()) || (stat.mode & 0o077))
+            throw Error('Unsafe metadata');
+        const value = schema.parse(JSON.parse(readFileSync(file, 'utf8')));
+        const home = path.resolve(prefix, '../..');
+        const runtime = path.join(home, '.axom/runtime/node', `${value.runtimeVersion}-darwin-${value.architecture}`);
+        if (prefix !== path.join(home, '.axom/cli') || realpathSync(value.prefix) !== prefix || realpathSync(value.cliPath) !== path.join(root, 'dist/cli.js') || realpathSync(value.nodePath) !== path.join(runtime, 'bin/node') || realpathSync(value.npmPath) !== path.join(runtime, 'bin/npm') || plannedRealPath(value.entryPath) !== path.join(home, '.local/bin/axom'))
+            throw Error('Metadata does not describe this installation');
+        return value;
+    }
+    catch (error) {
+        if (!found && error.code === 'ENOENT')
+            return null;
+        throw new LocalControlError('UNSUPPORTED_INSTALLATION', 'The managed CLI installation needs repair');
+    }
+}
+export async function loadManagedCliInstall(packageRoot) { return loadManagedCliInstallSync(packageRoot); }
+export function npmExecutionContext(install, inherited) {
+    if (!install)
+        return { ...inherited };
+    const result = { ...inherited, NPM_CONFIG_PREFIX: install.prefix, PATH: `${path.dirname(install.nodePath)}:${inherited.PATH ?? '/usr/bin:/bin'}` };
+    delete result.npm_config_prefix;
+    return result;
+}