herdr-remote 0.2.18 → 0.2.20

package/src/herdr-api.js

@@ -1,244 +0,0 @@
-'use strict';
-
-/**
- * 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.
- */
-
-const net = require('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;
-    }
-
-    socket.setEncoding('utf8');
-    socket.on('connect', () => {
-      socket.write(`${JSON.stringify({ id, method, params })}\n`);
-    });
-    socket.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 = new Error(message.error.message || 'Herdr API request failed');
-        error.code = message.error.code || 'herdr_api_error';
-        finish(error);
-        return;
-      }
-      finish(null, message.result);
-    });
-    socket.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.
-    socket.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;
-      while ((newline = buffer.indexOf('\n')) !== -1) {
-        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 {}
-        }
-      }
-    });
-    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();
-    },
-  };
-}
-
-module.exports = {
-  REQUEST_TIMEOUT_MS,
-  requestHerdr,
-  subscribeHerdr,
-};

package/src/herdr-command.js

@@ -1,231 +0,0 @@
-'use strict';
-
-// 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.
-
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
-const { spawnSync } = require('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.
-const { compareVersions } = require('./updater');
-
-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(' ');
-}
-
-module.exports = {
-  COMMAND_NAME,
-  FALLBACK_DIRECTORIES,
-  MIN_HERDR_VERSION,
-  fallbackDirectories,
-  findHerdrCommand,
-  herdrNotFoundMessage,
-  herdrOutdatedMessage,
-  herdrVersion,
-  meetsMinimum,
-  parseHerdrVersion,
-  resolveHerdrCommand,
-  verifyHerdrCommand,
-};

package/src/herdr-plugin.js

@@ -1,130 +0,0 @@
-'use strict';
-
-// 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.
-
-const fs = require('node:fs');
-const path = require('node:path');
-const { spawnSync } = require('node:child_process');
-const { PACKAGE_ROOT } = require('./config');
-const { herdrVersion, resolveHerdrCommand } = require('./herdr-command');
-
-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 herdrAvailable() {
-  return herdrVersion().ok;
-}
-
-function runHerdr(args, { timeout = 15_000 } = {}) {
-  const result = spawnSync(resolveHerdrCommand(), args, { encoding: 'utf8', timeout });
-  if (result.error && result.error.code === 'ENOENT') {
-    const error = new Error('herdr command not found');
-    error.code = 'HERDR_NOT_FOUND';
-    throw error;
-  }
-  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 && rawSource.includes(';') ? rawSource.slice(rawSource.indexOf(';') + 1).trim() : null,
-      localPath: source && 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: Boolean(entry.localPath) && path.resolve(entry.localPath) !== path.resolve(PACKAGE_ROOT),
-    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() };
-}
-
-module.exports = {
-  PLUGIN_ID,
-  manifestPath,
-  herdrAvailable,
-  parsePluginList,
-  registrationStatus,
-  register,
-  unregister,
-};