herdr-remote 0.2.17 → 0.2.19

package/bin/herdr-remote.js

@@ -1,224 +1,6 @@
 #!/usr/bin/env node
-'use strict';
+// The `herdr-remote` command, and what herdr-plugin.toml runs.
 
-// herdr-remote command line entry point.
-//
-// With no arguments (and a real terminal) this opens the configuration TUI;
-// the subcommands exist for scripting and for the actions declared in
-// herdr-plugin.toml, which Herdr runs without a terminal attached.
+import { run } from '../dist/cli.js';
 
-const fs = require('node:fs');
-const path = require('node:path');
-const { pathToFileURL } = require('node:url');
-
-const {
-  LANGUAGES,
-  configPath,
-  loadConfig,
-  migrateLegacyConfig,
-  resolvePublicUrl,
-  stateDir,
-} = require('../src/config');
-const { createTranslator, detectLocale } = require('../src/i18n');
-const { preferredLanAddress } = require('../src/net-interfaces');
-
-const VERSION = require('../package.json').version;
-
-const USAGE = `herdr-remote ${VERSION} — browser access to Herdr workspaces
-
-Usage: herdr-remote [command] [options]
-
-Commands:
-  (none)               Open the configuration TUI
-  start                Start relay and host connector
-  stop                 Stop services
-  restart              Restart services
-  status [--json]      Show service status
-  pair [--json]        Create pairing code
-  url                  Print browser access URL
-  run [--daemon]       Run services in foreground (keep-alive)
-  keepalive <action>   install | uninstall | restart | status
-  plugin <action>      link | unlink | status  (Herdr plugin)
-
-Options:
-  --lang <zh|en>       Interface language
-  --json               JSON output
-  -h, --help           Show help
-  -v, --version        Show version
-
-Self-hosting: docs/self-hosted-relay.md
-`;
-
-function parseArgs(argv) {
-  const positional = [];
-  const flags = {};
-  for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index];
-    if (arg === '--json') { flags.json = true; continue; }
-    if (arg === '--daemon') { flags.daemon = true; continue; }
-    if (arg === '--help' || arg === '-h') { flags.help = true; continue; }
-    if (arg === '--version' || arg === '-v') { flags.version = true; continue; }
-    if (arg === '--lang') { flags.lang = argv[index + 1]; index += 1; continue; }
-    if (arg.startsWith('--lang=')) { flags.lang = arg.slice('--lang='.length); continue; }
-    if (arg.startsWith('-')) { flags.unknown = arg; continue; }
-    positional.push(arg);
-  }
-  return { positional, flags };
-}
-
-function printJson(value) {
-  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
-}
-
-function describeStatus(status, t) {
-  const lines = [];
-  lines.push(`${t('overview.mode')}: ${t(`mode.${status.mode}`)}`);
-  if (status.relay.local) {
-    lines.push(`${t('overview.relay')}: ${status.relay.alive ? t('common.running') : t('common.stopped')} (${status.relay.bind}:${status.relay.port})`);
-  } else {
-    lines.push(`${t('overview.relay')}: ${status.relay.remoteUrl}`);
-  }
-  lines.push(`${t('overview.host')}: ${status.host.alive ? t('common.running') : t('common.stopped')}`);
-  lines.push(`${t('overview.socket')}: ${status.host.socketPath}${status.host.socketExists ? '' : ` (${t('overview.socketMissing')})`}`);
-  lines.push(`${t('overview.webUrl')}: ${status.publicUrl}`);
-  if (status.keepalive) {
-    const state = status.keepalive.active ? t('common.running') : status.keepalive.installed ? t('common.installed') : t('common.notInstalled');
-    lines.push(`${t('overview.keepalive')}: ${status.keepalive.manager} — ${state}`);
-  }
-  if (status.relay.health && status.relay.health.ok === false) {
-    lines.push(`${t('overview.relay')}: ${t('overview.unreachable', { message: status.relay.health.message })}`);
-  }
-  return lines.join('\n');
-}
-
-async function runTui(options) {
-  // The TUI is an ESM bundle; import() keeps this entry point loadable on any
-  // Node 22 without relying on require(esm).
-  const bundle = path.join(__dirname, '..', 'dist', 'tui.mjs');
-  if (!fs.existsSync(bundle)) {
-    process.stderr.write(
-      'herdr-remote: TUI bundle missing. Build first:\n'
-      + '  npm run build -w herdr-remote\n',
-    );
-    process.exitCode = 1;
-    return;
-  }
-  const module = await import(pathToFileURL(bundle).href);
-  await module.startTui(options);
-}
-
-async function main(argv = process.argv.slice(2)) {
-  const { positional, flags } = parseArgs(argv);
-  const command = positional[0] || null;
-
-  migrateLegacyConfig();
-
-  // Ask the terminal for its colors while it is still a plain terminal: the
-  // TUI takes the screen a few lines below, and the services this command
-  // starts usually run detached with nothing to ask. Everything downstream
-  // inherits the answer through the environment.
-  require('../src/terminal-palette').captureTerminalPalette();
-
-  const config = loadConfig();
-  const preference = flags.lang && LANGUAGES.includes(flags.lang) ? flags.lang : config.ui.language;
-  const t = createTranslator(detectLocale({ preference }));
-
-  if (flags.help) { process.stdout.write(USAGE); return; }
-  if (flags.version) { process.stdout.write(`${VERSION}\n`); return; }
-
-  // Lazily required so that `--help` and the TUI do not pay for loading the
-  // service layer (which pulls in the relay package and node-pty).
-  const lifecycle = require('../src/lifecycle');
-  const service = require('../src/service');
-
-  switch (command) {
-    case null: {
-      if (process.stdin.isTTY && process.stdout.isTTY) {
-        await runTui({ language: flags.lang || null });
-        return;
-      }
-      // Herdr runs plugin panes and actions without a TTY; emit status instead
-      // of trying to paint an interface into a pipe.
-      printJson(await lifecycle.fullStatus(config));
-      return;
-    }
-    case 'start': {
-      const result = lifecycle.startAll(config);
-      if (flags.json) printJson(result);
-      else process.stdout.write(`${t('services.started')}\n${describeStatus(await lifecycle.fullStatus(config), t)}\n`);
-      return;
-    }
-    case 'stop': {
-      const result = lifecycle.stopAll(config);
-      if (flags.json) printJson(result);
-      else process.stdout.write(`${t('services.stopped')}\n`);
-      return;
-    }
-    case 'restart': {
-      const result = lifecycle.restartAll(config);
-      if (flags.json) printJson(result);
-      else process.stdout.write(`${t('services.restarted')}\n`);
-      return;
-    }
-    case 'status': {
-      const status = await lifecycle.fullStatus(config);
-      if (flags.json) printJson(status);
-      else process.stdout.write(`${describeStatus(status, t)}\n`);
-      return;
-    }
-    case 'pair': {
-      const pairing = await service.pair();
-      if (flags.json) { printJson(pairing); return; }
-      const code = service.extractPairingCode(pairing);
-      const url = pairing.pairUrl || `${resolvePublicUrl(config, preferredLanAddress())}/?pairCode=${encodeURIComponent(code)}`;
-      const minutes = `${Math.round((config.auth.pairingTtlMs || 600000) / 60000)}m`;
-      process.stdout.write(`${t('pair.code')}: ${code}\n${t('pair.url')}: ${url}\n${t('pair.expires', { minutes, time: new Date(pairing.expiresAt).toLocaleTimeString() })}\n`);
-      return;
-    }
-    case 'url': {
-      process.stdout.write(`${resolvePublicUrl(config, preferredLanAddress())}\n`);
-      return;
-    }
-    case 'run': {
-      const { runForeground } = require('../src/supervisor');
-      await runForeground({ logToFiles: Boolean(flags.daemon) });
-      return;
-    }
-    case 'keepalive': {
-      const keepalive = require('../src/keepalive');
-      const action = positional[1] || 'status';
-      if (action === 'install') printJson(keepalive.install(config));
-      else if (action === 'uninstall') printJson(keepalive.uninstall(config));
-      else if (action === 'restart') printJson(keepalive.restart(config));
-      else if (action === 'status') printJson(keepalive.status(config));
-      else throw new Error(`unknown keepalive action: ${action}`);
-      return;
-    }
-    case 'plugin': {
-      const plugin = require('../src/herdr-plugin');
-      const action = positional[1] || 'status';
-      if (action === 'link') printJson(plugin.register());
-      else if (action === 'unlink') printJson(plugin.unregister());
-      else if (action === 'status') printJson(plugin.registrationStatus());
-      else throw new Error(`unknown plugin action: ${action}`);
-      return;
-    }
-    case 'config': {
-      // Handy when reporting a problem: where does this install read from?
-      printJson({ configPath: configPath(), stateDir: stateDir(), config });
-      return;
-    }
-    default:
-      process.stderr.write(`herdr-remote: unknown command "${command}"\n\n${USAGE}`);
-      process.exitCode = 2;
-  }
-}
-
-if (require.main === module) {
-  main().catch((error) => {
-    process.stderr.write(`herdr-remote: ${error.message}\n`);
-    process.exitCode = 1;
-  });
-}
-
-module.exports = { main, parseArgs, describeStatus, USAGE, VERSION };
+run();

package/dist/agent-status.js

@@ -0,0 +1,130 @@
+/**
+ * What the agents on this workstation are doing, small enough to put in a
+ * status bar.
+ *
+ * The question a phone actually has is "does anything need me?", and the
+ * terminal is a poor way to ask it: finding a blocked agent means navigating
+ * Herdr's sidebar through a viewport the width of a hand. Herdr already knows
+ * the answer — it classifies every pane as idle, working, blocked, done or
+ * unknown — so this turns a session snapshot into the two-line version.
+ *
+ * Deliberately a pure function over a snapshot. The socket, the debounce and
+ * the retry live in the host connector; what counts as "needs me" lives here,
+ * where it can be tested without either.
+ */
+/** Herdr's own vocabulary, in the order a person cares about them. */
+const AGENT_STATUSES = ['blocked', 'done', 'working', 'idle', 'unknown'];
+/**
+ * How many agents travel with the summary.
+ *
+ * The counts are always exact; this caps only the named list, which exists so a
+ * future screen can say *which* agent is blocked. A workstation with more than
+ * this many live agents is not going to be read off a phone anyway.
+ */
+const MAX_LISTED_AGENTS = 16;
+/** Titles come from a remote program; keep them short and printable. */
+const MAX_TITLE_LENGTH = 48;
+function cleanText(value, limit = MAX_TITLE_LENGTH) {
+    if (typeof value !== 'string')
+        return null;
+    const collapsed = value
+        .replace(/[\u0000-\u001F\u007F-\u009F]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (!collapsed)
+        return null;
+    return collapsed.length > limit ? collapsed.slice(0, limit) : collapsed;
+}
+function normalizeStatus(value) {
+    return AGENT_STATUSES.includes(value)
+        ? value
+        : 'unknown';
+}
+function emptyCounts() {
+    return Object.fromEntries(AGENT_STATUSES.map((status) => [status, 0]));
+}
+/**
+ * Turn `session.snapshot` into the summary the browser receives.
+ *
+ * Sorted by how much each status wants attention, so the capped list keeps the
+ * agents worth naming rather than the first ones Herdr happened to report.
+ * `focusedPaneId` and `focusedAgent` also track the live pane selection,
+ * including shells and panes Herdr has not added to its agent summary.
+ */
+function summarizeAgents(snapshot) {
+    const entries = Array.isArray(snapshot?.agents) ? snapshot.agents : [];
+    const panes = Array.isArray(snapshot?.panes) ? snapshot.panes : [];
+    const reportedFocusId = typeof snapshot?.focused_pane_id === 'string' && snapshot.focused_pane_id
+        ? snapshot.focused_pane_id
+        : null;
+    // `focused_pane_id` is the primary signal in Herdr snapshots. The focused
+    // flags are a fallback for snapshots where that top-level field is absent.
+    const focusedPane = (reportedFocusId
+        ? panes.find((pane) => pane?.pane_id === reportedFocusId)
+        : panes.find((pane) => pane?.focused === true)) || null;
+    const focusedAgentEntry = (reportedFocusId
+        ? entries.find((entry) => entry?.pane_id === reportedFocusId)
+        : entries.find((entry) => entry?.focused === true)) || null;
+    const focusedPaneId = reportedFocusId ||
+        (typeof focusedPane?.pane_id === 'string' ? focusedPane.pane_id : null) ||
+        (typeof focusedAgentEntry?.pane_id === 'string' ? focusedAgentEntry.pane_id : null);
+    const focusedAgent = typeof focusedPane?.agent === 'string'
+        ? focusedPane.agent
+        : typeof focusedAgentEntry?.agent === 'string'
+            ? focusedAgentEntry.agent
+            : null;
+    const counts = emptyCounts();
+    const ranked = [];
+    for (const entry of entries) {
+        if (!entry || typeof entry.pane_id !== 'string')
+            continue;
+        const status = normalizeStatus(entry.agent_status);
+        counts[status] += 1;
+        ranked.push({
+            paneId: entry.pane_id,
+            workspaceId: typeof entry.workspace_id === 'string' ? entry.workspace_id : null,
+            agent: cleanText(entry.display_agent || entry.agent, 24),
+            title: cleanText(entry.terminal_title_stripped || entry.terminal_title),
+            status,
+            focused: entry.focused === true,
+        });
+    }
+    ranked.sort((left, right) => AGENT_STATUSES.indexOf(left.status) - AGENT_STATUSES.indexOf(right.status));
+    return {
+        focusedPaneId,
+        focusedAgent,
+        counts,
+        // Total rather than a sum the browser has to compute, and the one number a
+        // collapsed chip can show on its own.
+        total: ranked.length,
+        agents: ranked.slice(0, MAX_LISTED_AGENTS),
+    };
+}
+/** Whether two summaries say the same thing, so an unchanged one is not sent. */
+function sameSummary(left, right) {
+    if (!left || !right)
+        return left === right;
+    if (left.focusedPaneId !== right.focusedPaneId || left.focusedAgent !== right.focusedAgent)
+        return false;
+    if (left.total !== right.total)
+        return false;
+    for (const status of AGENT_STATUSES) {
+        if ((left.counts?.[status] || 0) !== (right.counts?.[status] || 0))
+            return false;
+    }
+    if (left.agents.length !== right.agents.length)
+        return false;
+    return left.agents.every((agent, index) => {
+        const other = right.agents[index];
+        return (other &&
+            agent.paneId === other.paneId &&
+            agent.status === other.status &&
+            agent.agent === other.agent &&
+            agent.title === other.title);
+    });
+}
+/** The summary of a workstation with nothing to report, or nothing to ask. */
+function emptySummary() {
+    return { focusedPaneId: null, focusedAgent: null, counts: emptyCounts(), total: 0, agents: [] };
+}
+export { AGENT_STATUSES, emptySummary, sameSummary, summarizeAgents };

package/dist/binary-plist.js

@@ -0,0 +1,157 @@
+/**
+ * Reads Apple binary property lists (`bplist00`), the format macOS writes its
+ * preference files in, and the NSKeyedArchiver graphs stored inside them.
+ *
+ * Terminal.app keeps each profile's font as an archived NSFont — a binary
+ * plist nested in a binary plist — and there is no command-line tool that
+ * turns that into something readable without asking Terminal itself (an
+ * AppleScript that prompts for Automation access). A reader this small is
+ * less intrusive than any of those.
+ */
+/** A reference to another object in a keyed archive (`CF$UID`). */
+class Uid {
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+}
+function readSizedInt(buffer, offset, size) {
+    let value = 0;
+    for (let i = 0; i < size; i += 1)
+        value = value * 256 + buffer[offset + i];
+    return value;
+}
+/**
+ * Parses a whole `bplist00` buffer into plain values: objects, arrays,
+ * strings, numbers, booleans, Buffers (data), Dates and `Uid`s. Throws on
+ * anything malformed; callers treat that as "no answer".
+ */
+function parseBinaryPlist(buffer) {
+    if (!Buffer.isBuffer(buffer) ||
+        buffer.length < 40 ||
+        buffer.toString('latin1', 0, 8) !== 'bplist00') {
+        throw new Error('not a binary plist');
+    }
+    const trailer = buffer.length - 32;
+    const offsetSize = buffer[trailer + 6];
+    const refSize = buffer[trailer + 7];
+    const count = readSizedInt(buffer, trailer + 8, 8);
+    const top = readSizedInt(buffer, trailer + 16, 8);
+    const tableOffset = readSizedInt(buffer, trailer + 24, 8);
+    if (!offsetSize || !refSize || count > 1_000_000 || tableOffset + count * offsetSize > trailer) {
+        throw new Error('corrupt binary plist trailer');
+    }
+    const offsets = [];
+    for (let i = 0; i < count; i += 1)
+        offsets.push(readSizedInt(buffer, tableOffset + i * offsetSize, offsetSize));
+    const parsing = new Set();
+    const parse = (index) => {
+        if (index >= count || parsing.has(index))
+            throw new Error('corrupt binary plist reference');
+        parsing.add(index);
+        try {
+            return parseObject(offsets[index]);
+        }
+        finally {
+            parsing.delete(index);
+        }
+    };
+    // A length stored in the marker's low nibble, or as the int object after it.
+    const lengthAt = (offset) => {
+        const low = buffer[offset] & 0x0f;
+        if (low !== 0x0f)
+            return { length: low, start: offset + 1 };
+        const marker = buffer[offset + 1];
+        if ((marker & 0xf0) !== 0x10)
+            throw new Error('corrupt binary plist length');
+        const size = 1 << (marker & 0x0f);
+        return { length: readSizedInt(buffer, offset + 2, size), start: offset + 2 + size };
+    };
+    const parseObject = (offset) => {
+        const marker = buffer[offset];
+        const type = marker >> 4;
+        const low = marker & 0x0f;
+        switch (type) {
+            case 0x0:
+                if (marker === 0x08)
+                    return false;
+                if (marker === 0x09)
+                    return true;
+                return null;
+            case 0x1: {
+                const size = 1 << low;
+                if (size === 8)
+                    return Number(buffer.readBigInt64BE(offset + 1));
+                return readSizedInt(buffer, offset + 1, size);
+            }
+            case 0x2:
+                return low === 2 ? buffer.readFloatBE(offset + 1) : buffer.readDoubleBE(offset + 1);
+            case 0x3:
+                return new Date(Date.UTC(2001, 0, 1) + buffer.readDoubleBE(offset + 1) * 1000);
+            case 0x4: {
+                const { length, start } = lengthAt(offset);
+                return buffer.subarray(start, start + length);
+            }
+            case 0x5: {
+                const { length, start } = lengthAt(offset);
+                return buffer.toString('latin1', start, start + length);
+            }
+            case 0x6: {
+                const { length, start } = lengthAt(offset);
+                return Buffer.from(buffer.subarray(start, start + length * 2))
+                    .swap16()
+                    .toString('utf16le');
+            }
+            case 0x8:
+                return new Uid(readSizedInt(buffer, offset + 1, low + 1));
+            case 0xa:
+            case 0xc: {
+                const { length, start } = lengthAt(offset);
+                const items = [];
+                for (let i = 0; i < length; i += 1)
+                    items.push(parse(readSizedInt(buffer, start + i * refSize, refSize)));
+                return items;
+            }
+            case 0xd: {
+                const { length, start } = lengthAt(offset);
+                const result = {};
+                for (let i = 0; i < length; i += 1) {
+                    const key = parse(readSizedInt(buffer, start + i * refSize, refSize));
+                    result[String(key)] = parse(readSizedInt(buffer, start + (length + i) * refSize, refSize));
+                }
+                return result;
+            }
+            default:
+                throw new Error(`unsupported binary plist object 0x${marker.toString(16)}`);
+        }
+    };
+    return parse(top);
+}
+/**
+ * The root object of an NSKeyedArchiver plist, with every `Uid` replaced by
+ * the object it points at (to a bounded depth; archives may be cyclic).
+ */
+function unarchiveKeyed(archive, depth = 6) {
+    const record = (value) => value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+    const objects = record(archive)?.$objects;
+    const rootRef = record(record(archive)?.$top)?.root;
+    if (!Array.isArray(objects) || !(rootRef instanceof Uid))
+        throw new Error('not a keyed archive');
+    const resolve = (value, level) => {
+        if (value instanceof Uid)
+            return level > depth ? null : resolve(objects[value.value], level + 1);
+        if (Array.isArray(value))
+            return value.map((item) => resolve(item, level));
+        if (value && typeof value === 'object' && !Buffer.isBuffer(value) && !(value instanceof Date)) {
+            const result = {};
+            for (const [key, item] of Object.entries(value))
+                result[key] = resolve(item, level);
+            return result;
+        }
+        return value === '$null' ? null : value;
+    };
+    return resolve(rootRef, 0);
+}
+export { parseBinaryPlist, unarchiveKeyed };