@platless/axom-cli 0.3.13 → 0.6.36

package/dist/workstation/tools/terminalRouter.js

@@ -0,0 +1,222 @@
+import { accessSync, constants, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { CREATE_KEYS, PTY_OPERATIONS } from '../keepers/terminal/pty.js';
+import { PTY_SESSION_LIMIT } from '../keepers/terminal/protocol.js';
+import { TERMINAL_NOT_FOUND } from '../keepers/legacy.js';
+import { identifier, integer, keys } from './validation.js';
+const LEGACY = 'legacy';
+/** The single-keeper form of {@link KitGenerations}: one generation named `kit`, running when it answers a hello. */
+function singleKit(kit) {
+    return {
+        servingGeneration: async () => ({ gen: 'kit', client: kit }),
+        running: async () => [{ gen: 'kit', client: kit }],
+    };
+}
+export class TerminalRouter {
+    deps;
+    owners = new Map();
+    kits;
+    /** Clients of the generations seen in the last listing, by generation. */
+    clients = new Map();
+    constructor(deps) {
+        this.deps = deps;
+        if (!deps.kits && !deps.kit)
+            throw new Error('TerminalRouter needs keeper-terminal');
+        this.kits = deps.kits ?? singleKit(deps.kit);
+    }
+    /** The current owner map (tests and diagnostics): `legacy`, or a generation (`kit` with a single keeper-terminal). */
+    ownerOf(id) { return this.owners.get(id); }
+    async request(method, params) {
+        const op = method.startsWith('terminal.') ? method.slice('terminal.'.length) : '';
+        if (op === 'list') {
+            keys(params, []);
+            return { sessions: await this.list() };
+        }
+        if (op === 'create')
+            return { ...await this.create(params) };
+        if (!PTY_OPERATIONS.has(op))
+            throw new Error('Unsupported workstation tool');
+        const id = identifier(params, 'id');
+        const owner = await this.resolveOwner(id);
+        if (!owner)
+            throw new Error(TERMINAL_NOT_FOUND);
+        const kit = owner === LEGACY ? undefined : this.clients.get(owner);
+        if (owner !== LEGACY && !kit)
+            throw new Error(TERMINAL_NOT_FOUND);
+        try {
+            const result = owner === LEGACY
+                ? await this.deps.legacy.request(method, params)
+                : { ...await kit[op].call(kit, params) };
+            if (op === 'close')
+                this.owners.delete(id);
+            return result;
+        }
+        catch (error) {
+            // The owner no longer has it (closed elsewhere, keeper restarted): forget it; the next request looks it up again.
+            if (error instanceof Error && error.message === TERMINAL_NOT_FOUND)
+                this.owners.delete(id);
+            throw error;
+        }
+    }
+    async list() {
+        const { legacy, kits } = await this.refresh();
+        const seen = new Set((legacy ?? []).map((session) => session.id));
+        const out = [...(legacy ?? [])];
+        for (const sessions of kits.values())
+            for (const session of sessions ?? [])
+                if (!seen.has(session.id)) {
+                    seen.add(session.id);
+                    out.push(session);
+                }
+        return out;
+    }
+    /** Lists every side once (keeper-terminal generations only if running) and refreshes the owners of every side that answered. */
+    async refresh() {
+        const [legacy, kits] = await Promise.all([this.legacySessions(), this.kitRefresh()]);
+        if (legacy)
+            this.replaceOwners(LEGACY, legacy);
+        else if (!this.deps.legacy?.live)
+            this.replaceOwners(LEGACY, []);
+        return { legacy, kits };
+    }
+    /**
+     * Lists every running keeper-terminal generation (never starts one) and refreshes their owners: a generation that answered gets
+     * exactly its sessions; one that did not answer keeps its owners; one that is no longer running loses them (its PTYs are gone).
+     */
+    async kitRefresh() {
+        const listed = new Map();
+        let running;
+        try {
+            running = await this.kits.running();
+        }
+        catch {
+            return listed;
+        }
+        await Promise.all(running.map(async ({ gen, client }) => {
+            this.clients.set(gen, client);
+            listed.set(gen, await this.sessionsOf(client));
+        }));
+        for (const [gen, sessions] of listed)
+            if (sessions)
+                this.replaceOwners(gen, sessions);
+        for (const [id, owner] of [...this.owners])
+            if (owner !== LEGACY && !listed.has(owner))
+                this.owners.delete(id);
+        for (const gen of [...this.clients.keys()])
+            if (!listed.has(gen))
+                this.clients.delete(gen);
+        return listed;
+    }
+    replaceOwners(side, sessions) {
+        for (const [id, owner] of this.owners)
+            if (owner === side)
+                this.owners.delete(id);
+        for (const session of sessions)
+            if (side === LEGACY || !this.owners.has(session.id))
+                this.owners.set(session.id, side);
+    }
+    /** The legacy keeper's sessions; `sessions()` probes it first (read-only), so a daemon that just started finds it too. */
+    async legacySessions() {
+        return this.deps.legacy ? this.deps.legacy.sessions() : null;
+    }
+    /** One generation's sessions if it is already running; null when it is not (or did not answer): nothing is started here. */
+    async sessionsOf(client) {
+        try {
+            if (!await client.runningHello())
+                return null;
+            return (await client.list()).sessions;
+        }
+        catch {
+            return null;
+        }
+    }
+    async resolveOwner(id) {
+        const known = this.owners.get(id);
+        if ((known !== undefined && known !== LEGACY && this.clients.has(known)) || (known === LEGACY && this.deps.legacy?.live))
+            return known;
+        await this.refresh();
+        return this.owners.get(id);
+    }
+    async create(params) {
+        // The legacy keeper's checks, wording and order (tools/terminal.ts at the merge-base: id, clientId, keys, cols, rows, name,
+        // then existing, limit, cwd), all before the cwd is resolved.
+        const id = identifier(params, 'id');
+        identifier(params, 'clientId');
+        keys(params, [...CREATE_KEYS]);
+        integer(params, 'cols', 20, 300, 100);
+        integer(params, 'rows', 5, 100, 30);
+        const name = params.name;
+        if (name !== undefined && (typeof name !== 'string' || !name.length || name.length > 128 || /[\x00-\x1f]/.test(name)))
+            throw new Error('Invalid terminal name');
+        const legacy = this.deps.legacy;
+        const knownOwner = this.owners.get(id);
+        if (legacy && (knownOwner === undefined || knownOwner === LEGACY)) {
+            // The legacy keeper never gains a session after the upgrade (creates go to keeper-terminal), so the ids of its first
+            // successful list answer "is this a retry of one of its sessions?" for good — even while it is busy or hung.
+            if (legacy.knownIds === null) {
+                const sessions = await legacy.sessions(); // bounded; null at once when it is busy or absent
+                if (sessions)
+                    this.replaceOwners(LEGACY, sessions);
+            }
+            if (legacy.live && legacy.knownIds?.has(id))
+                return legacy.request('terminal.create', params);
+        }
+        // Duplicate and limit first (the legacy order), against the keeper-terminal generations already running: an idempotent create
+        // (in whichever generation has the id) costs no files-host round trip. keeper-terminal re-checks both when it really creates.
+        const listed = await this.kitRefresh();
+        for (const [gen, sessions] of listed) {
+            const existing = sessions?.find((session) => session.id === id);
+            if (existing) {
+                this.owners.set(id, gen);
+                return existing;
+            }
+        }
+        const serving = await this.kits.servingGeneration();
+        const running = listed.get(serving.gen);
+        if (running && running.length >= PTY_SESSION_LIMIT)
+            throw new Error('Terminal session limit exceeded');
+        if (params.cwd !== undefined && typeof params.cwd !== 'string')
+            throw new Error('Invalid cwd');
+        const launch = await this.deps.launch(params.cwd);
+        const created = await serving.client.create({ ...params, ...launch });
+        this.clients.set(serving.gen, serving.client);
+        this.owners.set(id, serving.gen);
+        return created;
+    }
+}
+/**
+ * The shell a new PTY runs (as a login shell, `-l`): what the legacy keeper chose (`$SHELL`, else the account's shell, else
+ * `/bin/sh`), restricted to an absolute path to an executable file, which keeper-terminal requires.
+ */
+export function terminalShell(env = process.env) {
+    let account;
+    try {
+        account = os.userInfo().shell ?? undefined;
+    }
+    catch { /* no passwd entry (some containers) */ }
+    for (const candidate of [env.SHELL, account, '/bin/sh']) {
+        if (!candidate || !path.isAbsolute(candidate))
+            continue;
+        try {
+            if (statSync(candidate).isFile()) {
+                accessSync(candidate, constants.X_OK);
+                return candidate;
+            }
+        }
+        catch { /* next */ }
+    }
+    return '/bin/sh';
+}
+/**
+ * The environment a new PTY gets: the daemon's own (the legacy keeper gave its own process.env, which was the daemon's when it
+ * was spawned), never the access token (commands/workstation.ts already drops it from the daemon; dropped again here so a
+ * future spawn path cannot leak it). keeper-terminal adds TERM and COLORTERM.
+ */
+export function terminalEnv(env = process.env) {
+    const out = {};
+    for (const [name, value] of Object.entries(env))
+        if (value !== undefined && name !== 'AXOM_ACCESS_TOKEN')
+            out[name] = value;
+    return out;
+}

package/dist/workstation/tools/validation.js

@@ -6,7 +6,9 @@ export const TOOL_METHODS = new Set([
     'browser.list', 'browser.create', 'browser.attach', 'browser.frame', 'browser.navigate', 'browser.input', 'browser.takeover', 'browser.detach', 'browser.close',
     'tools.info', 'terminal.list', 'terminal.create', 'terminal.attach', 'terminal.poll',
     'terminal.write', 'terminal.resize', 'terminal.takeover', 'terminal.detach', 'terminal.close',
-    'files.list', 'files.read', 'files.mkdir', 'files.rename', 'files.delete',
+    'files.media.prepare', 'files.media.read', 'files.media.cancel',
+    'files.media.open', 'files.media.status', 'files.media.seek', 'files.media.interest', 'files.media.object', 'files.media.release',
+    'files.list', 'files.find', 'files.read', 'files.mkdir', 'files.rename', 'files.delete',
     'files.upload.begin', 'files.upload.chunk', 'files.upload.finish', 'files.upload.cancel',
 ]);
 export function object(value) {
@@ -47,4 +49,38 @@ export function validateRequest(method, params) {
         throw new Error('Unsupported workstation tool');
     if (!object(params) || Buffer.byteLength(JSON.stringify(params)) > TOOL_REQUEST_BYTES)
         throw new Error('Invalid or oversized tool parameters');
+    const shape = MEDIA_SHAPES[method];
+    if (shape) {
+        keys(params, [...shape, 'readOnly', 'filesystem']);
+        string(params, 'path');
+        identifier(params, 'consumerId');
+        if (method !== 'files.media.open' && !/^[a-f0-9]{64}$/.test(string(params, 'version', 64)))
+            throw new Error('Invalid version');
+        for (const flag of ['readOnly', 'filesystem', 'hls', 'playing']) {
+            if (params[flag] !== undefined && typeof params[flag] !== 'boolean')
+                throw new Error(`Invalid ${flag}`);
+        }
+        if (method === 'files.media.open' && typeof params.hls !== 'boolean')
+            throw new Error('Invalid hls');
+        if (method === 'files.media.seek' || method === 'files.media.interest')
+            integer(params, 'positionMs', 0, 21_600_000);
+        if (method === 'files.media.seek')
+            integer(params, 'revision', 0, Number.MAX_SAFE_INTEGER);
+        if (method === 'files.media.interest' && typeof params.playing !== 'boolean')
+            throw new Error('Invalid playing');
+        if (method === 'files.media.object') {
+            if (!/^[A-Za-z0-9_-]+$/.test(string(params, 'objectId', 128)))
+                throw new Error('Invalid objectId');
+            integer(params, 'offset', 0, Number.MAX_SAFE_INTEGER);
+            integer(params, 'length', 1, 256 * 1024);
+        }
+    }
 }
+const MEDIA_SHAPES = {
+    'files.media.open': ['path', 'consumerId', 'hls'],
+    'files.media.status': ['path', 'version', 'consumerId'],
+    'files.media.seek': ['path', 'version', 'consumerId', 'positionMs', 'revision'],
+    'files.media.interest': ['path', 'version', 'consumerId', 'positionMs', 'playing'],
+    'files.media.object': ['path', 'version', 'consumerId', 'objectId', 'offset', 'length'],
+    'files.media.release': ['path', 'version', 'consumerId'],
+};

package/dist/workstation/update/artifact.js

@@ -1,3 +1,4 @@
+import { deploymentDownloadURL } from '../control/serverIdentity.js';
 import { createHash, timingSafeEqual } from 'node:crypto';
 import { createWriteStream, promises as fs } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -16,7 +17,7 @@ function safeRelease(release, server) {
     if ((configured.protocol !== 'http:' && configured.protocol !== 'https:') || configured.username || configured.password) {
         throw new Error('Configured server URL must be an HTTP(S) origin without credentials');
     }
-    const url = new URL(release.url, configured);
+    const url = new URL(deploymentDownloadURL(server, release.url));
     // The release descriptor arrives over the authenticated management connection, but keeping the
     // download on that exact origin prevents an injected relative/absolute URL from turning the
     // client into a credentialed downloader. HTTP remains supported for private-network development

package/dist/workstation/update/coordinator.js

@@ -253,6 +253,9 @@ export class UpdateCoordinator {
                     this.options.tasks.accepting = true;
                 return this.transition(this.base(command, 'SUCCEEDED'));
             }
+            // Keeper-hosted agent sessions outlive this process: detach them first (head checkpoint, adapter untouched — no
+            // `session/cancel`, no failed turn), so the next daemon adopts them where they are (spec §5.5.5).
+            await this.options.tasks.detachDurableSessions();
             await this.options.restart();
             return restarting;
         }

package/dist/workstation/update/globalInstall.js

@@ -0,0 +1,116 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+/**
+ * `npm install --global <archive>` reinstalls an already-present package by renaming the old
+ * install directory aside ("retire") and extracting the new one in its place. On at least one
+ * observed host (a container whose target directory sits on the image's read-only layers, backed
+ * by `fuse-overlayfs`) that retire-then-extract sequence is unreliable: `npm`'s own tar/arborist
+ * step intermittently reports `TAR_ENTRY_ERROR EEXIST` on the package's top-level `package.json`,
+ * immediately followed by `ENOENT` when npm reads the same path back — on the *same* path, even
+ * starting from an empty directory, and reproducibly across repeated attempts. A plain `tar`
+ * extraction of the identical archive onto the identical path, and a non-global `npm install` run
+ * inside an already-extracted directory, both succeed every time: the bug is specific to npm's
+ * own global-package retire/link machinery, not to the archive, the dependencies, or the
+ * filesystem's ability to write there at all.
+ *
+ * This is therefore a fallback, not the primary path: it only runs after a real `npm install
+ * --global` attempt has already failed, and it reimplements only what that attempt was observably
+ * unable to do reliably --- replace the target directory's contents and its `bin` entry --- using
+ * the two operations proven to work. It intentionally does not run on Windows, where npm's global
+ * `bin` entries are shim files (`.cmd`/`.ps1`), not symlinks, and this path has no evidence either
+ * way.
+ */
+export async function attemptGlobalInstallFallback(npmPath, npmPrefix, archive, env, spawn = nodeSpawn) {
+    if (process.platform === 'win32')
+        throw new Error('No tested fallback for a global npm install on Windows');
+    const manifest = await readArchivePackageJson(archive, spawn);
+    const name = manifest.name;
+    if (typeof name !== 'string' || name.length === 0)
+        throw new Error('Archive package.json has no usable "name"');
+    const bin = manifest.bin;
+    const target = path.join(npmPrefix, 'lib/node_modules', name);
+    await fs.rm(target, { recursive: true, force: true });
+    await fs.mkdir(target, { recursive: true });
+    await run(spawn, 'tar', ['-xzf', archive, '-C', target, '--strip-components=1'], {});
+    const installEnv = { ...process.env, ...env };
+    delete installEnv.NPM_CONFIG_PREFIX;
+    delete installEnv.npm_config_prefix;
+    await run(spawn, npmPath, ['install', '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund'], { cwd: target, env: installEnv });
+    await relinkBinaries(npmPrefix, target, name, bin);
+}
+async function readArchivePackageJson(archive, spawn) {
+    const raw = await capture(spawn, 'tar', ['-xzf', archive, '-O', 'package/package.json'], {});
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error('Archive package.json is not valid JSON');
+    }
+}
+/** Reproduces npm's own `bin` linking: a relative symlink from `<prefix>/bin/<name>` to the script. */
+async function relinkBinaries(npmPrefix, target, packageName, bin) {
+    const entries = binEntries(packageName, bin);
+    if (entries.length === 0)
+        return;
+    const binDir = path.join(npmPrefix, 'bin');
+    await fs.mkdir(binDir, { recursive: true });
+    for (const [command, relativeScript] of entries) {
+        const script = path.join(target, relativeScript);
+        const link = path.join(binDir, command);
+        await fs.rm(link, { force: true });
+        await fs.symlink(path.relative(binDir, script), link);
+        await fs.chmod(script, 0o755).catch(() => undefined);
+    }
+}
+/** Exported for direct unit testing; same resolution npm itself applies to a package.json `bin` field. */
+export function binEntries(packageName, bin) {
+    if (typeof bin === 'string') {
+        const short = packageName.startsWith('@') ? packageName.split('/')[1] ?? packageName : packageName;
+        return [[short, bin]];
+    }
+    if (bin && typeof bin === 'object') {
+        return Object.entries(bin).filter((entry) => typeof entry[1] === 'string');
+    }
+    return [];
+}
+function run(spawn, command, args, options) {
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawn(command, args, { ...options, shell: false, stdio: 'ignore', windowsHide: true });
+        }
+        catch (error) {
+            reject(error instanceof Error ? error : new Error(String(error)));
+            return;
+        }
+        child.once('error', reject);
+        child.once('close', (code, signal) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`${command} failed: exit ${code ?? signal ?? 'unknown'}`));
+        });
+    });
+}
+function capture(spawn, command, args, options) {
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawn(command, args, { ...options, shell: false, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
+        }
+        catch (error) {
+            reject(error instanceof Error ? error : new Error(String(error)));
+            return;
+        }
+        let stdout = '';
+        child.stdout?.on('data', (chunk) => { stdout += chunk.toString(); });
+        child.once('error', reject);
+        child.once('close', (code, signal) => {
+            if (code === 0)
+                resolve(stdout);
+            else
+                reject(new Error(`${command} failed: exit ${code ?? signal ?? 'unknown'}`));
+        });
+    });
+}

package/dist/workstation/update/npmInstaller.js

@@ -1,6 +1,8 @@
+import { withWorkstationLock } from '../control/locks.js';
 import { spawn as nodeSpawn } from 'node:child_process';
 import { redactPaths, redactSecrets } from './redact.js';
 import { verifyOptionalPty } from './watchdog.js';
+import { attemptGlobalInstallFallback } from './globalInstall.js';
 const STDERR_LIMIT = 4096;
 function absolute(value, field) {
     if (!value.startsWith('/') || /[\u0000-\u001f\u007f]/.test(value))
@@ -21,33 +23,57 @@ export class NpmInstaller {
         this.spawn = options.spawn ?? nodeSpawn;
     }
     async install(archive) {
+        if (this.options.configDir && !this.options.installationLockHeld)
+            return withWorkstationLock(this.options.configDir, 'installation', () => this.installUnlocked(archive));
+        return this.installUnlocked(archive);
+    }
+    async installUnlocked(archive) {
         absolute(archive, 'archive');
-        // No `--prefix`: npm installs into its own configured global prefix, which is what puts `axom`
-        // on the user's PATH. Forcing a private prefix put the binary somewhere nothing looks, so every
-        // machine needed a hand-made symlink that nothing in this package created or documented.
-        // `npmPrefix` survives for the writability pre-check, the service definition, and rollback —
-        // it is derived from where this package actually sits, so it still names npm's real prefix.
+        // Pin the already selected installation, including ordinary global npm installs.
+        const env = { ...process.env, ...this.options.env, NPM_CONFIG_PREFIX: this.options.npmPrefix };
+        delete env.npm_config_prefix;
         const args = ['install', '--global', archive, '--ignore-scripts', '--no-audit', '--no-fund'];
-        await new Promise((resolve, reject) => {
-            let stderr = '';
-            let child;
+        try {
+            await new Promise((resolve, reject) => {
+                let stderr = '';
+                let child;
+                try {
+                    child = this.spawn(this.options.npmPath, args, { env, shell: false, stdio: ['ignore', 'ignore', 'pipe'], windowsHide: true });
+                }
+                catch (error) {
+                    reject(new Error(`npm install could not start: ${sanitizeNpmError(error instanceof Error ? error.message : String(error))}`));
+                    return;
+                }
+                child.stderr?.on('data', (chunk) => { if (stderr.length < STDERR_LIMIT)
+                    stderr += chunk.toString().slice(0, STDERR_LIMIT - stderr.length); });
+                child.once('error', (error) => reject(new Error(`npm install could not start: ${sanitizeNpmError(error.message)}`)));
+                child.once('close', (code, signal) => {
+                    if (code === 0)
+                        resolve();
+                    else
+                        reject(new Error(`npm install failed: ${sanitizeNpmError(stderr) || `exit ${code ?? signal ?? 'unknown'}`}`));
+                });
+            });
+        }
+        catch (primaryError) {
+            // `npm install --global` reinstalling an already-present package renames the old install
+            // directory aside and extracts the new one in its place; that sequence has been observed to
+            // fail unreliably on at least one host/filesystem combination even from an empty target (see
+            // globalInstall.ts). The fallback reproduces only the two operations proven to work there. A
+            // fallback failure surfaces the *original* error: it is the one a real npm bug report needs.
+            //
+            // Both console lines below are the only record of how often this fallback actually fires
+            // fleet-wide — there is no telemetry channel for "the primary path failed but we recovered",
+            // and a daemon's own stdout/stderr is already collected wherever this process's logs are.
+            console.warn(`npm install --global failed, attempting the tar/local-install fallback: ${sanitizeNpmError(primaryError instanceof Error ? primaryError.message : String(primaryError))}`);
             try {
-                child = this.spawn(this.options.npmPath, args, { shell: false, stdio: ['ignore', 'ignore', 'pipe'], windowsHide: true });
+                await attemptGlobalInstallFallback(this.options.npmPath, this.options.npmPrefix, archive, this.options.env, this.spawn);
             }
-            catch (error) {
-                reject(new Error(`npm install could not start: ${sanitizeNpmError(error instanceof Error ? error.message : String(error))}`));
-                return;
+            catch {
+                throw primaryError;
             }
-            child.stderr?.on('data', (chunk) => { if (stderr.length < STDERR_LIMIT)
-                stderr += chunk.toString().slice(0, STDERR_LIMIT - stderr.length); });
-            child.once('error', (error) => reject(new Error(`npm install could not start: ${sanitizeNpmError(error.message)}`)));
-            child.once('close', (code, signal) => {
-                if (code === 0)
-                    resolve();
-                else
-                    reject(new Error(`npm install failed: ${sanitizeNpmError(stderr) || `exit ${code ?? signal ?? 'unknown'}`}`));
-            });
-        });
+            console.warn('npm install --global fallback succeeded; the global reinstall step is unreliable on this host and should be investigated');
+        }
         await verifyOptionalPty(this.options.npmPrefix, this.spawn);
     }
     /** Packs the installed package locally; `--json` gives npm's own name/version validation input. */
@@ -60,7 +86,7 @@ export class NpmInstaller {
             let stderr = '';
             let child;
             try {
-                child = this.spawn(this.options.npmPath, args, { shell: false, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+                child = this.spawn(this.options.npmPath, args, { ...(this.options.env ? { env: this.options.env } : {}), shell: false, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
             }
             catch (error) {
                 reject(new Error(`npm pack could not start: ${sanitizeNpmError(error instanceof Error ? error.message : String(error))}`));

package/dist/workstation/update/ptyPreflight.js

@@ -1,5 +1,6 @@
 import { createRequire } from 'node:module';
 import path from 'node:path';
+import { PTY_UNAVAILABLE_ERROR } from '../keepers/terminal/protocol.js';
 const require = createRequire(import.meta.url);
 /**
  * Says once, at daemon start, when the installed CLI's optional `node-pty` does not load. There is
@@ -22,3 +23,23 @@ export async function preflightOptionalPty(context, deps = {}) {
         (deps.warn ?? console.warn)('[daemon] Optional node-pty does not load on this platform; the terminal tool stays unavailable.');
     }
 }
+export { PTY_UNAVAILABLE_ERROR };
+/**
+ * A cached load check of the node-pty copy the terminal would use (the same `require('node-pty')` from this package),
+ * done at most once per daemon. Answering `tools.info` must never start a keeper just to learn this.
+ */
+export function cachedPtyStatus(load = () => require('node-pty')) {
+    let status;
+    return () => {
+        if (status)
+            return status;
+        try {
+            load();
+            status = { terminal: true };
+        }
+        catch {
+            status = { terminal: false, terminalError: PTY_UNAVAILABLE_ERROR };
+        }
+        return status;
+    };
+}