@platless/axom-cli 0.1.0 → 0.3.13

package/dist/workstation/tools/client.js

@@ -0,0 +1,269 @@
+import { resolveBrowserBinding, browserCapability } from '../desktop/binding.js';
+import { createHash, randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import net from 'node:net';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { object, TOOL_REQUEST_BYTES, TOOL_RESULT_BYTES, validateRequest } from './validation.js';
+/** Unix socket paths must remain below macOS/Linux's ~104-byte sockaddr_un limit. */
+export function keeperPaths(options, temporaryDirectory = os.tmpdir(), platform = process.platform, kind = 'terminal') {
+    const identity = createHash('sha256').update(JSON.stringify([path.resolve(options.configDir), options.workstationId, options.server, ...(kind === 'browser' ? ['browser'] : [])])).digest('hex').slice(0, 32);
+    const namespace = `axom-${kind === 'browser' ? 'browser' : 'tools'}-${process.getuid?.() ?? 'user'}`;
+    // macOS /var/folders/.../T often exhausts sockaddr_un before adding a private namespace. Honor
+    // TMPDIR where it fits on Linux; the short system temporary root is checked for private ownership.
+    let dir = path.join(platform === 'darwin' ? '/tmp' : temporaryDirectory, namespace, identity);
+    if (Buffer.byteLength(path.join(dir, 'keeper.sock')) > 100)
+        dir = path.join('/tmp', namespace, identity);
+    // Browser ports are disjoint from terminal startup and the normal Linux ephemeral range.
+    return { dir, socket: path.join(dir, 'keeper.sock'), lock: path.join(dir, 'startup.lock'), pidFile: path.join(dir, 'keeper.pid.json'), lockPort: kind === 'browser' ? 10000 + Number.parseInt(identity.slice(0, 8), 16) % 8000 : 20000 + Number.parseInt(identity.slice(0, 8), 16) % 40000, unit: `axom-${kind === 'browser' ? 'browser' : 'tools'}-keeper-${identity}` };
+}
+export async function privateDirectory(dir) {
+    await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+    const stat = await fs.lstat(dir);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || (process.getuid && stat.uid !== process.getuid()))
+        throw new Error('Unsafe keeper state directory');
+    await fs.chmod(dir, 0o700);
+}
+export function keeperRpc(socketPath, method, params, timeoutMs = 7000) {
+    const id = randomUUID();
+    const request = JSON.stringify({ id, method, params }) + '\n';
+    if (Buffer.byteLength(request) > TOOL_REQUEST_BYTES)
+        return Promise.reject(new Error('Tool request too large'));
+    return new Promise((resolve, reject) => {
+        const socket = net.createConnection(socketPath);
+        let buffered = '';
+        let done = false;
+        const finish = (error, result) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            socket.destroy();
+            if (error)
+                reject(error);
+            else
+                resolve(result);
+        };
+        const timer = setTimeout(() => finish(new Error('Workstation tool request timed out; mutation outcome may be unknown')), timeoutMs);
+        socket.setEncoding('utf8');
+        socket.on('connect', () => socket.end(request));
+        socket.on('data', chunk => {
+            buffered += chunk;
+            if (Buffer.byteLength(buffered) > TOOL_RESULT_BYTES) {
+                finish(new Error('Keeper response too large'));
+                return;
+            }
+            const newline = buffered.indexOf('\n');
+            if (newline < 0)
+                return;
+            try {
+                const reply = JSON.parse(buffered.slice(0, newline));
+                if (!object(reply) || reply.id !== id || typeof reply.ok !== 'boolean' || !object(reply.result) || !(reply.error === null || typeof reply.error === 'string') || (reply.ok ? reply.error !== null : !reply.error))
+                    throw new Error('Invalid keeper response');
+                finish(reply.ok ? undefined : new Error(reply.error), reply.result);
+            }
+            catch (error) {
+                finish(error instanceof Error ? error : new Error('Invalid keeper response'));
+            }
+        });
+        socket.on('error', error => finish(error));
+        socket.on('close', () => finish(new Error('Workstation tools keeper disconnected')));
+    });
+}
+const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+function pidAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+export class ToolsClient {
+    options;
+    kind;
+    paths;
+    starting;
+    browser;
+    constructor(options, kind = 'terminal') {
+        this.options = options;
+        this.kind = kind;
+        this.paths = keeperPaths(options, undefined, undefined, kind);
+    }
+    async probe(timeoutMs = 250) {
+        try {
+            const reply = await keeperRpc(this.paths.socket, 'keeper.ping', {}, timeoutMs);
+            if (reply.identity !== this.paths.unit || !Number.isSafeInteger(reply.pid))
+                return null;
+            return { pid: reply.pid };
+        }
+        catch {
+            return null;
+        }
+    }
+    async request(method, params) {
+        validateRequest(method, params);
+        const binding = resolveBrowserBinding(this.options.browserBinding);
+        if (!binding && method === 'tools.info') {
+            // Desktop sharing is optional. Checking terminal/files must not start a
+            // separate browser or require its dependencies when no VNC was configured.
+            const metadata = { browser: false, browserMode: 'shared', browserBinding: browserCapability(undefined) };
+            return this.kind === 'browser' ? metadata : { ...await this.localRequest(method, params), ...metadata };
+        }
+        if (binding && (method.startsWith('browser.') || method === 'tools.info')) {
+            const metadata = { browser: true, browserMode: 'shared', browserBinding: browserCapability(binding) };
+            if (method === 'browser.list')
+                return { ...metadata, sessions: [] };
+            if (method === 'tools.info')
+                return this.kind === 'browser' ? metadata : { ...await this.localRequest(method, params), ...metadata };
+            throw new Error('Shared browser uses the live desktop viewer; legacy browser session operations are unavailable');
+        }
+        if (this.kind === 'terminal' && (method.startsWith('browser.') || method === 'tools.info')) {
+            this.browser ??= new ToolsClient(this.options, 'browser');
+            if (method.startsWith('browser.'))
+                return this.browser.request(method, params);
+            const [terminal, browser] = await Promise.all([this.localRequest(method, params), this.browser.request(method, params).catch(error => ({ browser: false, browserError: error.message }))]);
+            const result = { ...terminal, ...browser, browserMode: 'legacy', browserBinding: browserCapability(undefined) };
+            if (result.browser)
+                delete result.browserError;
+            return result;
+        }
+        return this.localRequest(method, params);
+    }
+    async localRequest(method, params) {
+        const deadline = Date.now() + 7500;
+        await this.ensure(deadline);
+        // Never automatically retry a request: terminal input and file mutations may have executed
+        // even if their response was lost. Chunk retry is a caller decision with exact offset/data.
+        return keeperRpc(this.paths.socket, method, params, Math.max(1, deadline - Date.now()));
+    }
+    ensure(deadline) {
+        if (!this.starting) {
+            this.starting = this.start(deadline).finally(() => { this.starting = undefined; });
+        }
+        return this.starting;
+    }
+    async start(deadline) {
+        await privateDirectory(path.dirname(this.paths.dir));
+        await privateDirectory(this.paths.dir);
+        if (await this.probe())
+            return;
+        while (Date.now() < deadline - 500) {
+            if (await this.probe())
+                return;
+            let lock;
+            try {
+                lock = await this.acquireStartupLock();
+            }
+            catch (error) {
+                if (error.code !== 'EADDRINUSE')
+                    throw error;
+                await delay(50);
+                continue;
+            }
+            try {
+                if (await this.probe())
+                    return;
+                // A probe timeout is not process death. A busy emulator can delay ping; unlinking its live
+                // socket would orphan every PTY. The startup PID manifest is written before initialization.
+                while (await this.liveManifest()) {
+                    if (await this.probe())
+                        return;
+                    if (Date.now() >= deadline - 300)
+                        throw new Error('Tools keeper is alive but busy or unavailable; retry later');
+                    await delay(50);
+                }
+                await fs.unlink(this.paths.socket).catch(error => { if (error.code !== 'ENOENT')
+                    throw error; });
+                const launchConfig = Buffer.from(JSON.stringify({ socket: this.paths.socket, identity: this.paths.unit, home: this.options.home, roots: this.options.roots ?? [], kind: this.kind, profileRoot: path.join(path.resolve(this.options.configDir), 'browser-profiles', this.paths.unit), executablePath: this.options.browserExecutable ?? process.env.AXOM_BROWSER_EXECUTABLE, proxy: this.options.browserProxy ?? process.env.AXOM_BROWSER_PROXY })).toString('base64');
+                const script = fileURLToPath(new URL('./keeperProcess.js', import.meta.url));
+                if (script.endsWith('/src/workstation/tools/keeperProcess.js'))
+                    throw new Error('Tools keeper requires built CLI distribution');
+                let isolated = false;
+                if (process.platform === 'linux' && this.options.useSystemd !== false && await this.systemdAvailable()) {
+                    // setsid/detached cannot escape systemd's KillMode=control-group. A separate user service
+                    // gives keeper/PTYS their own cgroup and allows the transport daemon to restart safely.
+                    isolated = await this.systemdLaunch(script, launchConfig, deadline);
+                    if (!isolated) {
+                        // An existing user unit may still be starting. Never spawn a same-cgroup fallback
+                        // on a systemd host, where a daemon restart would silently kill every live terminal.
+                        while (Date.now() < deadline - 100) {
+                            if (await this.probe())
+                                return;
+                            await delay(50);
+                        }
+                        throw new Error('Cannot start isolated tools keeper user service');
+                    }
+                }
+                if (!isolated) {
+                    const child = spawn(process.execPath, [script, launchConfig], { detached: true, stdio: 'ignore' });
+                    child.on('error', () => { });
+                    child.unref();
+                }
+                while (Date.now() < deadline - 100) {
+                    if (await this.probe())
+                        return;
+                    await delay(50);
+                }
+                throw new Error('Workstation tools keeper failed to start');
+            }
+            finally {
+                await new Promise(resolve => lock.close(() => resolve()));
+            }
+        }
+        throw new Error('Workstation tools keeper startup is busy or timed out');
+    }
+    /** A kernel bind is an atomic cross-process lock with automatic release on process death.
+     * It carries no requests, and needs no stale-file unlink or ownership-blind finally cleanup.
+     * Rare identity-port collisions only serialize startup; all data still uses the private socket. */
+    acquireStartupLock() {
+        return new Promise((resolve, reject) => {
+            const lock = net.createServer(socket => socket.destroy());
+            lock.once('error', reject);
+            lock.listen({ host: '127.0.0.1', port: this.paths.lockPort, exclusive: true }, () => resolve(lock));
+        });
+    }
+    async liveManifest() {
+        try {
+            const stat = await fs.lstat(this.paths.pidFile);
+            if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 4096)
+                throw new Error('Invalid tools keeper PID manifest');
+            const value = JSON.parse(await fs.readFile(this.paths.pidFile, 'utf8'));
+            if (value.identity !== this.paths.unit)
+                throw new Error('Tools keeper identity mismatch');
+            return pidAlive(value.pid);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return false;
+            throw error;
+        }
+    }
+    async systemdAvailable() {
+        return new Promise(resolve => {
+            const child = spawn('systemctl', ['--user', 'show-environment'], { stdio: 'ignore' });
+            let done = false;
+            const finish = (ok) => { if (done)
+                return; done = true; clearTimeout(timer); resolve(ok); };
+            const timer = setTimeout(() => { child.kill(); finish(false); }, 500);
+            child.on('error', () => finish(false));
+            child.on('exit', code => finish(code === 0));
+        });
+    }
+    async systemdLaunch(script, config, deadline) {
+        return new Promise(resolve => {
+            const child = spawn('systemd-run', ['--user', '--quiet', '--collect', `--unit=${this.paths.unit}`, '--property=Type=exec', '--property=Restart=on-failure', '--property=RestartSec=1', '--', process.execPath, script, config], { stdio: 'ignore' });
+            let done = false;
+            const finish = (ok) => { if (done)
+                return; done = true; clearTimeout(timer); resolve(ok); };
+            const timer = setTimeout(() => { child.kill(); finish(false); }, Math.max(1, Math.min(2000, deadline - Date.now() - 500)));
+            child.on('error', () => finish(false));
+            child.on('exit', code => finish(code === 0));
+        });
+    }
+}

package/dist/workstation/tools/core.js

@@ -0,0 +1,50 @@
+import os from 'node:os';
+import { StructuredFiles } from './files.js';
+import { PersistentTerminals } from './terminal.js';
+import { keys, validateRequest, TOOL_RESULT_BYTES } from './validation.js';
+/** All mutations are serialized across clients; shell processes continue independently. */
+export class ToolsCore {
+    files;
+    terminals;
+    queue = Promise.resolve();
+    disposed = false;
+    timer;
+    constructor(files, terminals, ttl) {
+        this.files = files;
+        this.terminals = terminals;
+        this.timer = setInterval(() => { this.queue = this.queue.then(() => this.files.expire()).catch(() => { }); }, Math.min(ttl, 60_000));
+        this.timer.unref();
+    }
+    static async create(options = {}) {
+        const files = await StructuredFiles.create(options.home ?? os.homedir(), options.roots ?? [], options.uploadTtlMs, options.uploadStateDir);
+        return new ToolsCore(files, new PersistentTerminals(files, options), options.uploadTtlMs ?? 15 * 60_000);
+    }
+    dispatch(method, params = {}) {
+        const task = this.queue.then(async () => {
+            if (this.disposed)
+                throw new Error('Workstation tools keeper stopped');
+            validateRequest(method, params);
+            let result;
+            if (method === 'tools.info') {
+                keys(params, []);
+                result = { version: 1, terminal: this.terminals.available, browser: false, files: true, home: this.files.home, roots: this.files.roots, downloads: this.files.downloads, ...(this.terminals.error ? { terminalError: this.terminals.error } : {}), browserError: 'Browser tools are not enabled in this release' };
+            }
+            else if (method.startsWith('terminal.'))
+                result = await this.terminals.dispatch(method, params);
+            else
+                result = await this.files.dispatch(method, params);
+            if (Buffer.byteLength(JSON.stringify(result)) > TOOL_RESULT_BYTES - 1024)
+                throw new Error('Tool result too large');
+            return result;
+        });
+        this.queue = task.catch(() => { });
+        return task;
+    }
+    async dispose() {
+        this.disposed = true;
+        clearInterval(this.timer);
+        await this.queue;
+        await this.terminals.dispose();
+        await this.files.dispose();
+    }
+}