herdr-remote 0.2.39 → 0.3.31

package/dist/herdr-api.js

@@ -1,254 +0,0 @@
-/**
- * One question for Herdr's local socket API.
- *
- * Everything else in this package talks to Herdr by spawning a client into a
- * PTY and shipping the bytes. That is the terminal. This is the side channel:
- * the one place that asks Herdr *about* itself rather than drawing it, so a
- * phone can answer "does anything need me?" without navigating a TUI through a
- * 40-column viewport.
- *
- * The wire format is newline-delimited JSON over the Unix socket or, on
- * Windows, the named pipe it names:
- *
- *   request   {"id":"…","method":"session.snapshot","params":{}}
- *   response  {"id":"…","result":{…}}  or  {"id":"…","error":{"code","message"}}
- *
- * One request per connection, which is why this is a function and not a client.
- * Herdr closes the socket once it has answered: against 0.9.1 a second request
- * written to the same connection meets `EPIPE`. A long-lived client that
- * reconnects on close therefore turns into a connect-answer-close loop about
- * once a second, busy regardless of how rarely it actually asks anything. The
- * `herdr` CLI connects per command for the same reason, and so does this.
- *
- * Subscriptions are the exception Herdr does keep open — `events.subscribe`
- * holds the connection. Focus and agent-detection events let the caller refresh
- * the focused pane immediately, with a slow poll retained as a fallback.
- *
- * Nothing here may affect a terminal session. Herdr's server is an ordinary
- * process that can be restarted under a running herdr-remote, and when it is,
- * the PTYs keep streaming while this quietly fails and is asked again later.
- */
-import net from 'node:net';
-import { herdrEndpoint } from './socket-discovery.js';
-/** How long one question waits, connection included. */
-const REQUEST_TIMEOUT_MS = 10_000;
-/** An answer this long is not an answer. Guards a socket that never newlines. */
-const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
-/** A subscription that disappears should recover without keeping a dead socket busy. */
-const SUBSCRIBE_RETRY_BASE_MS = 1_000;
-const SUBSCRIBE_RETRY_MAX_MS = 10_000;
-let requestCounter = 0;
-/**
- * Ask Herdr one thing.
- *
- * Resolves with the `result` object, rejects for a refused connection, a
- * timeout, an unparseable answer, or an `error` response — in which case
- * `error.code` is Herdr's own code.
- */
-function requestHerdr(socketPath, method, params = {}, options = {}) {
-    const { timeout = REQUEST_TIMEOUT_MS, connect = net.connect } = options;
-    requestCounter += 1;
-    const id = `herdr-remote:${requestCounter}`;
-    return new Promise((resolve, reject) => {
-        let socket;
-        let buffer = '';
-        let settled = false;
-        const finish = (error, result) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timer);
-            if (socket) {
-                socket.removeAllListeners();
-                socket.destroy();
-            }
-            if (error)
-                reject(error);
-            else
-                resolve(result);
-        };
-        const timer = setTimeout(() => finish(new Error(`Herdr API did not answer ${method} in time`)), timeout);
-        if (typeof timer.unref === 'function')
-            timer.unref();
-        try {
-            socket = connect(herdrEndpoint(socketPath));
-        }
-        catch (error) {
-            finish(error);
-            return;
-        }
-        const connection = socket;
-        connection.setEncoding('utf8');
-        connection.on('connect', () => {
-            connection.write(`${JSON.stringify({ id, method, params })}\n`);
-        });
-        connection.on('data', (chunk) => {
-            buffer += chunk;
-            if (buffer.length > MAX_RESPONSE_BYTES) {
-                finish(new Error('Herdr API sent an oversized response'));
-                return;
-            }
-            const newline = buffer.indexOf('\n');
-            if (newline === -1)
-                return;
-            let message;
-            try {
-                message = JSON.parse(buffer.slice(0, newline));
-            }
-            catch {
-                finish(new Error('Herdr API sent a line that is not JSON'));
-                return;
-            }
-            if (message.error) {
-                const error = Object.assign(new Error(message.error.message || 'Herdr API request failed'), {
-                    code: message.error.code || 'herdr_api_error',
-                });
-                finish(error);
-                return;
-            }
-            finish(null, message.result);
-        });
-        connection.on('error', (error) => finish(error));
-        // Herdr hanging up before it answered is the ordinary shape of "the server
-        // is not running", not something that needs its own diagnosis.
-        connection.on('close', () => finish(new Error(`Herdr API closed before answering ${method}`)));
-    });
-}
-/**
- * Subscribe to Herdr's event stream and reconnect if its local server restarts.
- *
- * The initial response is an acknowledgement (`result.type` is
- * `subscription_started`); later lines are envelopes with `event` and `data`.
- * They share a socket, but are separate NDJSON messages. A subscription never
- * starts or writes to a terminal, so an unavailable socket is only a reason to
- * retry this side channel.
- *
- * Events are not replayed across connections, and from Herdr 0.9.2 a reader
- * that falls behind gets an `events_lost` error carrying the request id and a
- * closed socket. Both end in a reconnect, and `onStarted` fires on every
- * acknowledgement so the caller can re-read what it may have missed.
- */
-function subscribeHerdr(socketPath, subscriptions, onEvent, options = {}) {
-    const { connect = net.connect, retryBaseMs = SUBSCRIBE_RETRY_BASE_MS, retryMaxMs = SUBSCRIBE_RETRY_MAX_MS, onStarted, } = options;
-    let socket = null;
-    let reconnectTimer = null;
-    let handshakeTimer = null;
-    let retryCount = 0;
-    let closed = false;
-    const scheduleReconnect = () => {
-        if (closed || reconnectTimer)
-            return;
-        const delay = Math.min(retryBaseMs * 2 ** retryCount, retryMaxMs);
-        retryCount += 1;
-        reconnectTimer = setTimeout(() => {
-            reconnectTimer = null;
-            open();
-        }, delay);
-        if (typeof reconnectTimer.unref === 'function')
-            reconnectTimer.unref();
-    };
-    const open = () => {
-        if (closed)
-            return;
-        let current;
-        try {
-            current = connect(herdrEndpoint(socketPath));
-        }
-        catch {
-            scheduleReconnect();
-            return;
-        }
-        socket = current;
-        let buffer = '';
-        let requestId = null;
-        let acknowledged = false;
-        const clearHandshake = () => {
-            if (handshakeTimer)
-                clearTimeout(handshakeTimer);
-            handshakeTimer = null;
-        };
-        current.setEncoding('utf8');
-        current.on('connect', () => {
-            requestCounter += 1;
-            requestId = `herdr-remote:subscription:${requestCounter}`;
-            current.write(`${JSON.stringify({
-                id: requestId,
-                method: 'events.subscribe',
-                params: { subscriptions },
-            })}\n`);
-            handshakeTimer = setTimeout(() => current.destroy(), REQUEST_TIMEOUT_MS);
-            if (typeof handshakeTimer.unref === 'function')
-                handshakeTimer.unref();
-        });
-        current.on('data', (chunk) => {
-            buffer += chunk;
-            if (Buffer.byteLength(buffer, 'utf8') > MAX_RESPONSE_BYTES) {
-                current.destroy();
-                return;
-            }
-            let newline = buffer.indexOf('\n');
-            for (; newline !== -1; newline = buffer.indexOf('\n')) {
-                const line = buffer.slice(0, newline);
-                buffer = buffer.slice(newline + 1);
-                if (!line)
-                    continue;
-                let message;
-                try {
-                    message = JSON.parse(line);
-                }
-                catch {
-                    current.destroy();
-                    return;
-                }
-                if (message?.id === requestId) {
-                    clearHandshake();
-                    if (message.error) {
-                        current.destroy();
-                        return;
-                    }
-                    acknowledged = true;
-                    retryCount = 0;
-                    onStarted?.();
-                }
-                else if (acknowledged &&
-                    typeof message?.event === 'string' &&
-                    message.data &&
-                    typeof message.data === 'object') {
-                    try {
-                        onEvent(message);
-                    }
-                    catch (error) {
-                        // A handler's bug must not end the subscription, but must not vanish either.
-                        process.stderr.write(`herdr-remote: Herdr event handler failed: ${error instanceof Error ? error.message : error}\n`);
-                    }
-                }
-            }
-        });
-        current.on('error', () => { });
-        current.on('close', () => {
-            clearHandshake();
-            if (socket === current)
-                socket = null;
-            scheduleReconnect();
-        });
-    };
-    open();
-    return {
-        close() {
-            if (closed)
-                return;
-            closed = true;
-            if (reconnectTimer)
-                clearTimeout(reconnectTimer);
-            if (handshakeTimer)
-                clearTimeout(handshakeTimer);
-            reconnectTimer = null;
-            handshakeTimer = null;
-            const active = socket;
-            socket = null;
-            if (active)
-                active.destroy();
-        },
-    };
-}
-export { requestHerdr, subscribeHerdr };

package/dist/herdr-command.js

@@ -1,245 +0,0 @@
-// How a spawned Herdr is located.
-//
-// `HERDR_BIN_PATH` is what the service layer hands to the host connector, and
-// it is also the escape hatch for an install that is not on `PATH`. Neither is
-// enough on its own once a service manager is in the picture: `systemd --user`
-// and `launchd` start their units with a minimal `PATH` that contains none of
-// the directories a user-level install writes to. A bare `herdr` then reaches
-// `execvp(3)` inside the forked PTY child, which prints
-// "execvp(3) failed.: No such file or directory" and exits — the failure the
-// browser sees as an endless reconnect loop.
-//
-// So the name is resolved to an absolute path here, ahead of any spawn:
-// an honoured override first, then `PATH`, then the handful of directories
-// installers actually use.
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { spawnSync } from 'node:child_process';
-// The same MAJOR.MINOR.PATCH comparison the self-updater uses. A second copy
-// would be a second place for 0.9.10 to sort below 0.9.9.
-import { compareVersions } from './updater.js';
-const COMMAND_NAME = 'herdr';
-/**
- * The oldest Herdr this release is written against.
- *
- * 0.9.0 gave every client its own view, which is what one PTY per browser
- * window rests on. 0.9.1 is what makes that model behave: window titles follow
- * each client's own view instead of another client's selection, activating a
- * machine in the background stops resizing somebody else's focused pane, and a
- * large paste no longer disconnects the client — and pasting is how an image
- * reaches an agent from a phone.
- *
- * 0.9.3 because a browser types through escape sequences: 0.9.2 stopped a tap
- * on a pane from sending a stray Escape to a working agent and stopped mouse
- * reports split across reads from leaking into the shell, and it also broke
- * Escape followed by a key — Alt+B, Alt+F, Alt+Backspace — which 0.9.3 mends.
- */
-const MIN_HERDR_VERSION = '0.9.3';
-/** Where a user-level install lands, in the order we trust it. */
-const FALLBACK_DIRECTORIES = [
-    '~/.local/bin',
-    '~/.cargo/bin',
-    '~/bin',
-    '/opt/homebrew/bin',
-    '/usr/local/bin',
-    '/home/linuxbrew/.linuxbrew/bin',
-    '/usr/bin',
-];
-function expandHome(directory, home) {
-    if (directory === '~')
-        return home;
-    if (directory.startsWith('~/'))
-        return path.join(home, directory.slice(2));
-    return directory;
-}
-/** Windows only publishes Herdr as an executable; shell scripts need a shell. */
-function candidateNames(base = COMMAND_NAME, platform = process.platform) {
-    if (platform !== 'win32')
-        return [base];
-    return [/\.exe$/i.test(base) ? base : `${base}.exe`];
-}
-function isExecutableFile(candidate) {
-    try {
-        if (!fs.statSync(candidate).isFile())
-            return false;
-        fs.accessSync(candidate, fs.constants.X_OK);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-function findInDirectory(directory, names = candidateNames()) {
-    if (!directory)
-        return null;
-    for (const name of names) {
-        const candidate = path.join(directory, name);
-        if (isExecutableFile(candidate))
-            return candidate;
-    }
-    return null;
-}
-function findOnSearchPath(searchPath, names = candidateNames()) {
-    for (const entry of String(searchPath || '').split(path.delimiter)) {
-        const found = findInDirectory(entry.trim(), names);
-        if (found)
-            return found;
-    }
-    return null;
-}
-function fallbackDirectories(home = os.homedir(), platform = process.platform, env = process.env) {
-    if (platform === 'win32') {
-        return [
-            path.join(env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'), 'Programs', 'Herdr', 'bin'),
-            path.join(home, '.cargo', 'bin'),
-            path.join(home, 'scoop', 'shims'),
-        ];
-    }
-    return FALLBACK_DIRECTORIES.map((directory) => expandHome(directory, home));
-}
-function looksLikePath(value) {
-    return value.includes('/') || value.includes(path.sep);
-}
-/**
- * Honour `HERDR_BIN_PATH`.
- *
- * It is documented as the executable, but a directory is an easy thing to
- * write there, and a bare name — someone copying `herdr` into a unit file —
- * still has to go through the search. A value that resolves to nothing is
- * treated as absent rather than fatal: a stale override left behind by a
- * moved install is precisely the case we are trying to survive.
- */
-function resolveOverride(value, searchPath, platform) {
-    const trimmed = String(value || '').trim();
-    if (!trimmed)
-        return null;
-    if (looksLikePath(trimmed)) {
-        const absolute = path.resolve(trimmed);
-        if (isExecutableFile(absolute))
-            return absolute;
-        if (platform === 'win32' && path.extname(absolute) === '') {
-            const executable = `${absolute}.exe`;
-            if (isExecutableFile(executable))
-                return executable;
-        }
-        return findInDirectory(absolute, candidateNames(COMMAND_NAME, platform));
-    }
-    return findOnSearchPath(searchPath, candidateNames(trimmed, platform));
-}
-/**
- * Everything known about where Herdr is, so callers can report it and not only
- * spawn it.
- *
- * `source` is `env` for an honoured `HERDR_BIN_PATH`, `path` for a hit on
- * `PATH`, `fallback` for one of the well-known install directories, and
- * `unresolved` when nothing matched. In that last case `command` is still the
- * bare name: `PATH` may be right in a way we cannot see from here, and letting
- * the spawn proceed keeps the old behaviour for anyone relying on it.
- */
-function findHerdrCommand({ env = process.env, home = os.homedir(), platform = process.platform, directories = fallbackDirectories(home, platform, env), } = {}) {
-    const names = candidateNames(COMMAND_NAME, platform);
-    const override = resolveOverride(env.HERDR_BIN_PATH, env.PATH, platform);
-    if (override)
-        return { command: override, source: 'env', found: true };
-    const onPath = findOnSearchPath(env.PATH, names);
-    if (onPath)
-        return { command: onPath, source: 'path', found: true };
-    for (const directory of directories) {
-        const found = findInDirectory(directory, names);
-        if (found)
-            return { command: found, source: 'fallback', found: true };
-    }
-    return { command: COMMAND_NAME, source: 'unresolved', found: false };
-}
-function resolveHerdrCommand(options) {
-    return findHerdrCommand(options).command;
-}
-/**
- * Re-check a command resolved earlier. A connector outlives the install that
- * was missing when it started, and an absolute path outlives the binary it
- * pointed at, so neither answer stays true for the life of the service.
- */
-function verifyHerdrCommand(command, options = {}) {
-    if (typeof command === 'string' && looksLikePath(command) && isExecutableFile(command)) {
-        return { command, source: 'verified', found: true };
-    }
-    return findHerdrCommand(options);
-}
-/** `herdr 0.9.1`, `herdr 0.10.0-preview.2` — the three numbers are all we compare. */
-function parseHerdrVersion(output) {
-    const match = /(\d+)\.(\d+)\.(\d+)/.exec(String(output || ''));
-    return match ? `${match[1]}.${match[2]}.${match[3]}` : null;
-}
-/**
- * Whether an install is new enough.
- *
- * An unreadable version counts as new enough. Not knowing is not evidence of an
- * old Herdr, and a warning nobody can act on is worse than no warning.
- */
-function meetsMinimum(version, minimum = MIN_HERDR_VERSION) {
-    if (!version)
-        return true;
-    return compareVersions(version, minimum) >= 0;
-}
-/**
- * Ask an install what it is.
- *
- * Deliberately the binary and not the socket: `--version` answers before the
- * server is up, which is when the TUI and the plugin registration ask.
- *
- * `ok` is whether the command ran at all — the presence check registration has
- * always used. `version` is null whenever the output could not be read, and
- * `supported` is true in that case for the reason `meetsMinimum` explains.
- */
-function herdrVersion({ command, timeout = 10_000, ...lookup } = {}) {
-    const resolved = command || resolveHerdrCommand(lookup);
-    const unknown = {
-        command: resolved,
-        version: null,
-        raw: null,
-        supported: true,
-        ok: false,
-    };
-    let result;
-    try {
-        result = spawnSync(resolved, ['--version'], {
-            encoding: 'utf8',
-            timeout,
-            windowsHide: true,
-        });
-    }
-    catch {
-        return unknown;
-    }
-    // Status 1 has always counted as present: a binary that answers at all is
-    // installed, whatever it thinks of the flag.
-    if (result.error || (result.status !== 0 && result.status !== 1))
-        return unknown;
-    const raw = `${result.stdout || ''}${result.stderr || ''}`.trim();
-    const version = parseHerdrVersion(raw);
-    return {
-        command: resolved,
-        version,
-        raw: raw || null,
-        supported: meetsMinimum(version),
-        ok: true,
-    };
-}
-/** The one line that tells a user why an older Herdr is a problem here. */
-function herdrOutdatedMessage(version) {
-    return (`Herdr ${version} is older than ${MIN_HERDR_VERSION}, which herdr-remote is written against. ` +
-        'Run "herdr update" — window titles, large pastes, taps on a pane and Alt shortcuts all ' +
-        'misbehave in browser windows before that release.');
-}
-/** The one message a user needs to fix a missing install themselves. */
-function herdrNotFoundMessage({ env = process.env, home = os.homedir(), platform = process.platform, directories = fallbackDirectories(home, platform, env), } = {}) {
-    const override = String(env.HERDR_BIN_PATH || '').trim();
-    const parts = [`Herdr executable "${COMMAND_NAME}" was not found.`];
-    if (override)
-        parts.push(`HERDR_BIN_PATH=${override} does not point at an executable.`);
-    parts.push(directories.length ? `Searched PATH and ${directories.join(', ')}.` : 'Searched PATH.');
-    parts.push('Install Herdr or set HERDR_BIN_PATH to its full path, then restart herdr-remote.');
-    return parts.join(' ');
-}
-export { FALLBACK_DIRECTORIES, MIN_HERDR_VERSION, fallbackDirectories, findHerdrCommand, herdrNotFoundMessage, herdrOutdatedMessage, herdrVersion, meetsMinimum, parseHerdrVersion, resolveHerdrCommand, verifyHerdrCommand, };

package/dist/herdr-plugin.js

@@ -1,120 +0,0 @@
-// Registration with the Herdr CLI.
-//
-// Installing from npm puts this package somewhere under a global node_modules
-// tree; Herdr learns about it with `herdr plugin link <path>`. Doing that from
-// here means the user never has to find the install directory themselves.
-import fs from 'node:fs';
-import path from 'node:path';
-import { spawnSync } from 'node:child_process';
-import { PACKAGE_ROOT } from './paths.js';
-import { herdrVersion, resolveHerdrCommand } from './herdr-command.js';
-const PLUGIN_ID = 'herdr.remote.web';
-const MANIFEST_NAME = 'herdr-plugin.toml';
-function manifestPath() {
-    return path.join(PACKAGE_ROOT, MANIFEST_NAME);
-}
-// Registration also runs from `herdr plugin` actions and from the service
-// manager, neither of which is guaranteed the PATH the user installed with, so
-// the command is resolved rather than named.
-function runHerdr(args, { timeout = 15_000 } = {}) {
-    const result = spawnSync(resolveHerdrCommand(), args, {
-        encoding: 'utf8',
-        timeout,
-        windowsHide: true,
-    });
-    if (result.error?.code === 'ENOENT') {
-        throw Object.assign(new Error('herdr command not found'), { code: 'HERDR_NOT_FOUND' });
-    }
-    return result;
-}
-/**
- * Parse `herdr plugin list`. Lines look like:
- *   - herdr.remote.web (Herdr Remote Web) enabled [local:/path/to/package]
- *
- * Herdr appends diagnostics inside the brackets when something is wrong, e.g.
- * `[local:/path; 1 warning(s)]`, so everything from the first `;` is dropped
- * before the path is read.
- */
-function parsePluginList(output) {
-    const plugins = [];
-    for (const line of String(output || '').split('\n')) {
-        const match = /^-\s+(\S+)\s+\((.*?)\)\s+(\S+)(?:\s+\[(.*)\])?/.exec(line.trim());
-        if (!match)
-            continue;
-        const [, id, name, state, rawSource] = match;
-        const source = rawSource ? rawSource.split(';')[0].trim() : null;
-        plugins.push({
-            id,
-            name,
-            enabled: state === 'enabled',
-            source,
-            warnings: rawSource?.includes(';')
-                ? rawSource.slice(rawSource.indexOf(';') + 1).trim()
-                : null,
-            localPath: source?.startsWith('local:') ? source.slice('local:'.length) : null,
-        });
-    }
-    return plugins;
-}
-function registrationStatus() {
-    if (!fs.existsSync(manifestPath())) {
-        return { available: false, registered: false, reason: 'manifest missing' };
-    }
-    // Carried on every answer: the screen that shows registration is also the one
-    // that has to say the installed Herdr is too old for this plugin.
-    const { version, supported } = herdrVersion();
-    const installed = { version, versionSupported: supported };
-    let result;
-    try {
-        result = runHerdr(['plugin', 'list']);
-    }
-    catch (error) {
-        if (error.code === 'HERDR_NOT_FOUND')
-            return { available: false, registered: false, reason: 'herdr not found' };
-        throw error;
-    }
-    if (result.status !== 0) {
-        return {
-            available: true,
-            registered: false,
-            reason: String(result.stderr || '').trim(),
-            ...installed,
-        };
-    }
-    const plugins = parsePluginList(result.stdout);
-    const entry = plugins.find((plugin) => plugin.id === PLUGIN_ID);
-    if (!entry)
-        return { available: true, registered: false, packageRoot: PACKAGE_ROOT, ...installed };
-    return {
-        available: true,
-        registered: true,
-        enabled: entry.enabled,
-        linkedPath: entry.localPath,
-        // A stale link pointing at an old checkout is the main failure mode after
-        // switching from a source install to npm.
-        stale: entry.localPath ? path.resolve(entry.localPath) !== path.resolve(PACKAGE_ROOT) : false,
-        packageRoot: PACKAGE_ROOT,
-        ...installed,
-    };
-}
-function register() {
-    const current = registrationStatus();
-    if (current.registered && current.stale) {
-        // Herdr refuses to link a second plugin with the same id, so drop the old
-        // link before pointing it at this install.
-        runHerdr(['plugin', 'unlink', PLUGIN_ID]);
-    }
-    const result = runHerdr(['plugin', 'link', PACKAGE_ROOT]);
-    if (result.status !== 0) {
-        throw new Error(String(result.stderr || result.stdout || '').trim() || 'herdr plugin link failed');
-    }
-    return { ok: true, path: PACKAGE_ROOT, output: String(result.stdout || '').trim() };
-}
-function unregister() {
-    const result = runHerdr(['plugin', 'unlink', PLUGIN_ID]);
-    if (result.status !== 0) {
-        throw new Error(String(result.stderr || result.stdout || '').trim() || 'herdr plugin unlink failed');
-    }
-    return { ok: true, output: String(result.stdout || '').trim() };
-}
-export { parsePluginList, registrationStatus, register, unregister };