herdr-remote 0.2.18 → 0.2.20

package/dist/herdr-api.js

@@ -0,0 +1,246 @@
+/**
+ * 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:
+ *
+ *   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';
+/** 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(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.
+ */
+function subscribeHerdr(socketPath, subscriptions, onEvent, options = {}) {
+    const { connect = net.connect, retryBaseMs = SUBSCRIBE_RETRY_BASE_MS, retryMaxMs = SUBSCRIBE_RETRY_MAX_MS, } = 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(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;
+                }
+                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

@@ -0,0 +1,223 @@
+// 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.
+ */
+const MIN_HERDR_VERSION = '0.9.1';
+/** 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 keeps the executable bit in the extension instead of the mode. */
+function candidateNames(base = COMMAND_NAME) {
+    return process.platform === 'win32'
+        ? [base, `${base}.exe`, `${base}.cmd`, `${base}.bat`]
+        : [base];
+}
+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()) {
+    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) {
+    const trimmed = String(value || '').trim();
+    if (!trimmed)
+        return null;
+    if (looksLikePath(trimmed)) {
+        const absolute = path.resolve(trimmed);
+        if (isExecutableFile(absolute))
+            return absolute;
+        return findInDirectory(absolute);
+    }
+    return findOnSearchPath(searchPath, candidateNames(trimmed));
+}
+/**
+ * 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(), directories = fallbackDirectories(home), } = {}) {
+    const override = resolveOverride(env.HERDR_BIN_PATH, env.PATH);
+    if (override)
+        return { command: override, source: 'env', found: true };
+    const onPath = findOnSearchPath(env.PATH);
+    if (onPath)
+        return { command: onPath, source: 'path', found: true };
+    for (const directory of directories) {
+        const found = findInDirectory(directory);
+        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 });
+    }
+    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, background machine activation and large pastes 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(), directories = fallbackDirectories(home), } = {}) {
+    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

@@ -0,0 +1,116 @@
+// 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 });
+    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 };