@w3cj/fwd 0.0.0-stage → 0.1.0

package/src/commands/completion.js

@@ -0,0 +1,230 @@
+import { FwdError } from '../errors.js';
+import { commands, optionsFor } from './index.js';
+
+/** @typedef {import('./common.js').Completion} Completion */
+/** @typedef {Exclude<Completion, 'commands'>} Candidates Completion with command names filled in. */
+
+/**
+ * The parts of the command definitions that completion scripts need.
+ */
+function model() {
+  const visible = commands.filter((cmd) => !cmd.hidden);
+  const names = visible.map((cmd) => cmd.name);
+  // Command names are fixed when the script is generated.
+  /** @type {(c: Completion) => Candidates} */
+  const resolve = (c) => (c === 'commands' ? names : c);
+  return {
+    commands: visible.map((cmd) => ({
+      name: cmd.name,
+      summary: cmd.summary,
+      positionals: (cmd.positionals ?? []).map(resolve),
+      options: Object.entries(optionsFor(cmd)).map(([name, opt]) => ({
+        flag: `--${name}`,
+        help: opt.help,
+        takesValue: opt.type === 'string',
+        complete: opt.complete && resolve(opt.complete),
+      })),
+    })),
+    // Flags whose next word is a value, not a positional argument.
+    valueFlags: [
+      ...new Set(
+        visible.flatMap((cmd) =>
+          Object.entries(optionsFor(cmd))
+            .filter(([, opt]) => opt.type === 'string')
+            .map(([name]) => `--${name}`),
+        ),
+      ),
+    ],
+  };
+}
+
+/** @param {string} text */
+function quote(text) {
+  return `'${text.replaceAll("'", `'\\''`)}'`;
+}
+
+/**
+ * Shell code (bash and zsh share the syntax) producing candidate words.
+ * @param {'hosts' | 'ports'} completion
+ */
+function wordsCommand(completion) {
+  return completion === 'hosts'
+    ? 'fwd __complete hosts 2>/dev/null'
+    : 'fwd __complete ports "${host[@]}" 2>/dev/null';
+}
+
+// Shared by bash and zsh: walk the words before the cursor, counting
+// positional arguments and noting --host so `ports` uses the right host.
+/**
+ * @param {ReturnType<typeof model>} m
+ * @param {string} words The shell's array of words.
+ * @param {number} first Index of the first word after the subcommand.
+ * @param {string} current Index of the word being completed.
+ */
+function scanWords(m, words, first, current) {
+  return `  for ((i = ${first}; i < ${current}; i++)); do
+    case \${${words}[i]} in
+      --host) host=(--host "\${${words}[i+1]}"); ((i++)) ;;
+      ${m.valueFlags.filter((f) => f !== '--host').join('|')}) ((i++)) ;;
+      -*) ;;
+      *) ((pos++)) ;;
+    esac
+  done`;
+}
+
+/** @param {ReturnType<typeof model>} m */
+function bash(m) {
+  /** @param {Candidates} c */
+  const words = (c) => (Array.isArray(c) ? c.join(' ') : `$(${wordsCommand(c)})`);
+  const cases = m.commands.map((cmd) => {
+    const values = cmd.options
+      .filter((o) => o.takesValue)
+      .map((o) => (o.complete ? `${o.flag}) words="${words(o.complete)}" ;;` : `${o.flag}) return ;;`));
+    const positionals = cmd.positionals.map((c, i) => `${i}) words="${words(c)}" ;;`);
+    return `    ${cmd.name})
+      opts=${quote(cmd.options.map((o) => o.flag).join(' '))}
+      case $prev in ${values.join(' ')} *) case $pos in ${positionals.join(' ')} esac ;; esac ;;`;
+  });
+  return `# bash completion for fwd. Generated by \`fwd completion bash\`.
+_fwd() {
+  local cur=\${COMP_WORDS[COMP_CWORD]} prev=\${COMP_WORDS[COMP_CWORD-1]} cmd=\${COMP_WORDS[1]}
+  local opts='' words='' i pos=0 host=()
+  if ((COMP_CWORD == 1)); then
+    COMPREPLY=($(compgen -W ${quote(`${m.commands.map((c) => c.name).join(' ')} --help --version`)} -- "$cur"))
+    return
+  fi
+${scanWords(m, 'COMP_WORDS', 2, 'COMP_CWORD')}
+  case $cmd in
+${cases.join('\n')}
+  esac
+  if [[ $cur == -* ]]; then
+    COMPREPLY=($(compgen -W "$opts" -- "$cur"))
+  else
+    COMPREPLY=($(compgen -W "$words" -- "$cur"))
+  fi
+}
+complete -F _fwd fwd
+`;
+}
+
+/** @param {ReturnType<typeof model>} m */
+function zsh(m) {
+  /** @param {Candidates} c */
+  const words = (c) => (Array.isArray(c) ? `(${c.join(' ')})` : `(\${(f)"$(${wordsCommand(c)})"})`);
+  /** @param {{ name: string, help: string }[]} items */
+  const described = (items) => items.map((i) => quote(`${i.name}:${i.help}`)).join(' ');
+  const cases = m.commands.map((cmd) => {
+    const values = cmd.options
+      .filter((o) => o.takesValue)
+      .map((o) => (o.complete ? `${o.flag}) vals=${words(o.complete)} ;;` : `${o.flag}) return ;;`));
+    const positionals = cmd.positionals.map((c, i) => `${i}) vals=${words(c)} ;;`);
+    return `    ${cmd.name})
+      opts=(${described(cmd.options.map((o) => ({ name: o.flag, help: o.help })))})
+      case $prev in ${values.join(' ')} *) case $pos in ${positionals.join(' ')} esac ;; esac ;;`;
+  });
+  return `#compdef fwd
+# zsh completion for fwd. Generated by \`fwd completion zsh\`.
+_fwd() {
+  local cmd=\${words[2]} prev=\${words[CURRENT-1]} i pos=0
+  local -a host opts vals
+  if ((CURRENT == 2)); then
+    local -a cmds=(${described(m.commands.map((c) => ({ name: c.name, help: c.summary })))})
+    _describe -t commands command cmds
+    return
+  fi
+${scanWords(m, 'words', 3, 'CURRENT')}
+  case $cmd in
+${cases.join('\n')}
+  esac
+  if [[ \${words[CURRENT]} == -* ]]; then
+    _describe -t options option opts
+  else
+    compadd -a vals
+  fi
+}
+if [[ \${zsh_eval_context[-1]} == loadautofunc ]]; then
+  _fwd "$@"
+else
+  compdef _fwd fwd
+fi
+`;
+}
+
+/** @param {ReturnType<typeof model>} m */
+function fish(m) {
+  /** @param {Candidates} c */
+  const words = (c) =>
+    Array.isArray(c) ? quote(c.join(' ')) : `'(fwd __complete ${c}${c === 'ports' ? ' (__fwd_host)' : ''} 2>/dev/null)'`;
+  /** @param {string} cmd */
+  const seen = (cmd) => `__fish_seen_subcommand_from ${cmd}`;
+  const lines = [
+    '# fish completion for fwd. Generated by `fwd completion fish`.',
+    '',
+    '# Number of positional arguments before the cursor, after the subcommand.',
+    'function __fwd_pos',
+    '    set -l n 0',
+    '    set -l skip 0',
+    '    for t in (commandline -opc)[3..-1]',
+    '        if test $skip = 1',
+    '            set skip 0',
+    '        else if contains -- $t ' + m.valueFlags.join(' '),
+    '            set skip 1',
+    "        else if not string match -q -- '-*' $t",
+    '            set n (math $n + 1)',
+    '        end',
+    '    end',
+    '    echo $n',
+    'end',
+    '',
+    '# "--host <host>" if given on the command line, for completing saved ports.',
+    'function __fwd_host',
+    '    set -l tokens (commandline -opc)',
+    '    if set -l i (contains -i -- --host $tokens); and set -q tokens[(math $i + 1)]',
+    '        echo --host',
+    '        echo $tokens[(math $i + 1)]',
+    '    end',
+    'end',
+    '',
+    'complete -c fwd -f',
+    "complete -c fwd -n __fish_use_subcommand -s h -l help -d 'Show help'",
+    "complete -c fwd -n __fish_use_subcommand -s v -l version -d 'Show the version'",
+    ...m.commands.map((c) => `complete -c fwd -n __fish_use_subcommand -a ${c.name} -d ${quote(c.summary)}`),
+  ];
+  for (const cmd of m.commands) {
+    lines.push('');
+    for (const o of cmd.options) {
+      const value = o.takesValue ? ` -x${o.complete ? ` -a ${words(o.complete)}` : ''}` : '';
+      lines.push(`complete -c fwd -n '${seen(cmd.name)}' -l ${o.flag.slice(2)}${value} -d ${quote(o.help)}`);
+    }
+    cmd.positionals.forEach((c, i) => {
+      lines.push(`complete -c fwd -n '${seen(cmd.name)}; and test (__fwd_pos) -eq ${i}' -a ${words(c)}`);
+    });
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+const generators = { bash, zsh, fish };
+
+/** @type {import('./common.js').Command} */
+export default {
+  name: 'completion',
+  summary: 'Print a shell completion script',
+  usage: ['fwd completion bash|zsh|fish'],
+  description: [
+    'Install with:',
+    '  bash   fwd completion bash > ~/.local/share/bash-completion/completions/fwd',
+    '  zsh    fwd completion zsh > "${fpath[1]}/_fwd"   (or add `source <(fwd completion zsh)` to ~/.zshrc)',
+    '  fish   fwd completion fish > ~/.config/fish/completions/fwd.fish',
+  ].join('\n'),
+  args: [1, 1],
+  host: 'none',
+  readonly: true,
+  positionals: [Object.keys(generators)],
+
+  async run({ args: [shell] }) {
+    if (!Object.hasOwn(generators, shell)) {
+      throw new FwdError(`Unknown shell "${shell}". Use ${Object.keys(generators).join(', ')}.`);
+    }
+    process.stdout.write(generators[/** @type {keyof typeof generators} */ (shell)](model()));
+  },
+};

package/src/commands/config.js

@@ -0,0 +1,47 @@
+import { FwdError } from '../errors.js';
+import { saveState } from '../state.js';
+import { validateHost } from './common.js';
+
+/** @type {import('./common.js').Command} */
+export default {
+  name: 'config',
+  summary: 'Get or set the default host',
+  usage: ['fwd config set host <host>', 'fwd config get host', 'fwd config unset host'],
+  description: [
+    'The default host is used when --host is not given. An ~/.ssh/config alias works',
+    'best, so keys, user and IP all come from your SSH setup:',
+    '',
+    '  Host vm',
+    '    HostName 192.168.64.7',
+    '    User cj',
+    '',
+    '  fwd config set host vm',
+  ].join('\n'),
+  args: [2, 3],
+  host: 'none',
+  positionals: [['set', 'get', 'unset'], ['host'], 'hosts'],
+
+  async run({ args: [action, key, value], state }) {
+    if (key !== 'host') throw new FwdError(`Unknown config key "${key}". Valid keys: host.`);
+    if ((action === 'set') !== (value !== undefined)) {
+      throw new FwdError(action === 'set' ? 'Missing value. Usage: fwd config set host <host>' : `Unexpected argument "${value}".`);
+    }
+
+    switch (action) {
+      case 'get':
+        if (!state.defaultHost) return 1;
+        return void console.log(state.defaultHost);
+      case 'set':
+        validateHost(value);
+        state.defaultHost = value;
+        await saveState(state);
+        return void console.log(`Default host set to ${value}`);
+      case 'unset':
+        state.defaultHost = null;
+        await saveState(state);
+        return void console.log('Default host cleared');
+      default:
+        throw new FwdError(`Unknown action "${action}". Use set, get or unset.`);
+    }
+  },
+};

package/src/commands/down.js

@@ -0,0 +1,22 @@
+import { checkMaster, removeSocket, stopMaster } from '../ssh.js';
+import { getForwards } from '../state.js';
+
+/** @type {import('./common.js').Command} */
+export default {
+  name: 'down',
+  summary: 'Stop the SSH master (saved forwards are kept)',
+  usage: ['fwd down [--host <host>]'],
+  description: 'Closes the connection and every forward on it. Saved forwards are kept so `fwd up` can restore them.',
+  args: [0, 0],
+
+  async run({ state, host }) {
+    if (!(await checkMaster(host)).alive) {
+      await removeSocket(host);
+      return void console.log(`SSH master for ${host} is not running.`);
+    }
+    await stopMaster(host);
+    console.log(`Stopped SSH master for ${host}.`);
+    const count = getForwards(state, host).length;
+    if (count) console.log(`${count} saved forward${count === 1 ? '' : 's'} kept; \`fwd up\` restores them.`);
+  },
+};

package/src/commands/help.js

@@ -0,0 +1,21 @@
+import { FwdError } from '../errors.js';
+import { commandHelp, mainHelp } from '../help.js';
+import { findCommand } from './index.js';
+
+/** @type {import('./common.js').Command} */
+export default {
+  name: 'help',
+  summary: 'Show help for fwd or a command',
+  usage: ['fwd help [<command>]'],
+  args: [0, 1],
+  host: 'none',
+  readonly: true,
+  positionals: ['commands'],
+
+  async run({ args: [name] }) {
+    if (name === undefined) return void console.log(mainHelp());
+    const cmd = findCommand(name);
+    if (cmd.hidden) throw new FwdError(`Unknown command "${name}". Run \`fwd help\` to see the commands.`);
+    console.log(commandHelp(cmd));
+  },
+};

package/src/commands/index.js

@@ -0,0 +1,45 @@
+import add from './add.js';
+import complete from './complete.js';
+import completion from './completion.js';
+import config from './config.js';
+import down from './down.js';
+import help from './help.js';
+import ls from './ls.js';
+import rm from './rm.js';
+import status from './status.js';
+import up from './up.js';
+import watch from './watch.js';
+import { FwdError } from '../errors.js';
+
+/** @typedef {import('./common.js').Command} Command */
+/** @typedef {import('./common.js').Option} Option */
+
+/** @type {Command[]} */
+export const commands = [add, rm, ls, up, down, status, watch, config, completion, help, complete];
+
+/**
+ * @param {string} name
+ * @returns {Command}
+ */
+export function findCommand(name) {
+  const cmd = commands.find((c) => c.name === name);
+  if (!cmd) throw new FwdError(`Unknown command "${name}". Run \`fwd help\` to see the commands.`);
+  return cmd;
+}
+
+/** @type {Record<string, Option>} */
+export const hostOption = {
+  host: { type: 'string', value: 'host', complete: 'hosts', help: 'SSH host to use instead of the default' },
+};
+
+/** @type {Record<string, Option>} */
+export const helpOption = { help: { type: 'boolean', short: 'h', help: 'Show this help' } };
+
+/**
+ * Every option a command accepts, including the shared ones.
+ * @param {Command} cmd
+ * @returns {Record<string, Option>}
+ */
+export function optionsFor(cmd) {
+  return { ...cmd.options, ...(cmd.host === 'none' ? {} : hostOption), ...helpOption };
+}

package/src/commands/ls.js

@@ -0,0 +1,89 @@
+import { FwdError } from '../errors.js';
+import { describe } from '../spec.js';
+import { checkMaster } from '../ssh.js';
+import { getForwards } from '../state.js';
+import { forwardStatus, pidSuffix, resolveHost } from './common.js';
+
+/** @typedef {import('../state.js').State} State */
+
+/** @param {string | undefined} iso */
+function formatDate(iso) {
+  const date = iso ? new Date(iso) : null;
+  if (!date || Number.isNaN(date.getTime())) return '-';
+  /** @param {number} n */
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+
+/**
+ * @param {State} state
+ * @param {string} host
+ */
+async function hostStatus(state, host) {
+  const master = await checkMaster(host);
+  const forwards = await Promise.all(
+    getForwards(state, host).map(async (fwd) => ({ ...fwd, status: await forwardStatus(fwd, master.alive) })),
+  );
+  return { host, master: { alive: master.alive, pid: master.alive ? master.pid : null }, forwards };
+}
+
+/**
+ * @param {State} state
+ * @param {Awaited<ReturnType<typeof hostStatus>>} status
+ */
+function print(state, { host, master, forwards }) {
+  console.log(`${host}: master ${master.alive ? `running${pidSuffix(master.pid)}` : 'not running'}`);
+  if (!forwards.length) return void console.log('No saved forwards. Add one with `fwd add <port>`.');
+
+  const rows = [
+    ['FORWARD', 'STATUS', 'ADDED'],
+    ...forwards.map((f) => [describe(f, host), f.status, formatDate(f.addedAt)]),
+  ];
+  const widths = rows[0].map((_, i) => Math.max(...rows.map((r) => r[i].length)));
+  for (const row of rows) {
+    console.log(row.map((cell, i) => cell.padEnd(widths[i])).join('  ').trimEnd());
+  }
+  if (forwards.some((f) => f.status !== 'active')) {
+    const flag = host === state.defaultHost ? '' : ` --host ${host}`;
+    console.log(`\nRun \`fwd up${flag}\` to restore forwards that are down or broken.`);
+  }
+}
+
+/** @type {import('./common.js').Command} */
+export default {
+  name: 'ls',
+  summary: 'List saved forwards and their status',
+  usage: ['fwd ls [--json] [--host <host> | --all-hosts]'],
+  description: [
+    'Statuses:',
+    '  active   the local port is forwarded',
+    '  down     the SSH master is not running (`fwd up` restores it)',
+    '  broken   the master is up but the port is not listening (`fwd up` re-applies it)',
+    '',
+    'Local forwards are checked by connecting to the local port, which ssh passes on',
+    'to the remote port, so the remote service sees a brief connection. Reverse',
+    'forwards listen on the host and are reported active whenever the master is up.',
+  ].join('\n'),
+  args: [0, 0],
+  host: 'self',
+  readonly: true,
+  options: {
+    'all-hosts': { type: 'boolean', help: 'List forwards for every host' },
+    json: { type: 'boolean', help: 'Print machine-readable JSON' },
+  },
+
+  async run({ flags, state }) {
+    if (flags['all-hosts'] && flags.host !== undefined) throw new FwdError('Use either --host or --all-hosts, not both.');
+    const hosts = flags['all-hosts'] ? Object.keys(state.hosts) : [resolveHost(state, flags.host)];
+    const statuses = await Promise.all(hosts.map((host) => hostStatus(state, host)));
+
+    if (flags.json) {
+      return void console.log(JSON.stringify(flags['all-hosts'] ? statuses : statuses[0], null, 2));
+    }
+    if (!statuses.length) return void console.log('No saved forwards. Add one with `fwd add <port>`.');
+    statuses.forEach((status, i) => {
+      if (i > 0) console.log();
+      print(state, status);
+    });
+  },
+};

package/src/commands/rm.js

@@ -0,0 +1,63 @@
+import { FwdError } from '../errors.js';
+import { isPortListening } from '../ports.js';
+import { describe, forwardKey, keyOf, parsePort } from '../spec.js';
+import { cancelForward, checkMaster } from '../ssh.js';
+import { findForward, getForwards, removeForward, saveState } from '../state.js';
+
+/** @type {import('./common.js').Command} */
+export default {
+  name: 'rm',
+  summary: 'Stop forwarding a port and forget it',
+  usage: ['fwd rm <port> [--reverse] [--host <host>]', 'fwd rm --all [--host <host>]'],
+  description: [
+    'Cancels the forward and removes it from saved state. If the SSH master is not',
+    'running, only the saved state is updated. <port> is the listening port: the',
+    'local port, or the remote port with --reverse.',
+  ].join('\n'),
+  args: [0, 1],
+  positionals: ['ports'],
+  options: {
+    all: { type: 'boolean', help: 'Remove every forward for the host' },
+    reverse: { type: 'boolean', help: 'Remove the reverse forward listening on <port> on the host' },
+  },
+
+  async run({ args, flags, state, host }) {
+    if (Boolean(flags.all) === (args.length === 1)) {
+      throw new FwdError('Pass either a port or --all. Usage: fwd rm <port> or fwd rm --all');
+    }
+    let targets = getForwards(state, host);
+    if (!flags.all) {
+      const port = parsePort(args[0], 'port');
+      const direction = flags.reverse ? 'remote' : 'local';
+      const fwd = findForward(state, host, forwardKey(direction, port));
+      if (!fwd) {
+        const flipped = findForward(state, host, forwardKey(direction === 'local' ? 'remote' : 'local', port));
+        const hint = flipped ? ` Did you mean \`fwd rm ${port}${flags.reverse ? '' : ' --reverse'}\`?` : ' See `fwd ls`.';
+        throw new FwdError(`No saved ${flags.reverse ? 'reverse ' : ''}forward on port ${port} for ${host}.${hint}`);
+      }
+      targets = [fwd];
+    }
+    if (!targets.length) return void console.log(`No saved forwards for ${host}.`);
+
+    const master = await checkMaster(host);
+    let failed = 0;
+    for (const fwd of targets) {
+      try {
+        if (master.alive) await cancelForward(host, fwd);
+      } catch (err) {
+        // Cancel fails if the forward wasn't active (e.g. "broken"); that's
+        // fine to forget. If a local port is still listening, keep it saved.
+        if (fwd.direction === 'local' && (await isPortListening(fwd.local))) {
+          console.error(`fwd: ${/** @type {Error} */ (err).message}`);
+          console.error(`fwd: kept port ${fwd.local} in state; \`fwd down\` stops all forwards for ${host}.`);
+          failed++;
+          continue;
+        }
+      }
+      removeForward(state, host, keyOf(fwd));
+      console.log(`Removed ${describe(fwd, host)}`);
+    }
+    await saveState(state);
+    return failed ? 1 : 0;
+  },
+};

package/src/commands/status.js

@@ -0,0 +1,26 @@
+import { checkMaster, logPath, socketPath } from '../ssh.js';
+import { getForwards, statePath } from '../state.js';
+
+/** @type {import('./common.js').Command} */
+export default {
+  name: 'status',
+  summary: 'Show the SSH master for a host',
+  usage: ['fwd status [--host <host>]'],
+  description: 'Shows the host, control socket, whether the master is alive, and its PID.',
+  args: [0, 0],
+  readonly: true,
+
+  async run({ state, host }) {
+    const master = await checkMaster(host);
+    const rows = [
+      ['Host', `${host}${host === state.defaultHost ? ' (default)' : ''}`],
+      ['Master', master.alive ? 'running' : 'not running'],
+      ['PID', master.alive && master.pid ? String(master.pid) : '-'],
+      ['Forwards', `${getForwards(state, host).length} saved`],
+      ['Socket', socketPath(host)],
+      ['Log', logPath(host)],
+      ['State', statePath()],
+    ];
+    for (const [label, value] of rows) console.log(`${label.padEnd(9)} ${value}`);
+  },
+};

package/src/commands/up.js

@@ -0,0 +1,18 @@
+import { getForwards } from '../state.js';
+import { bringUp, pidSuffix, printResults } from './common.js';
+
+/** @type {import('./common.js').Command} */
+export default {
+  name: 'up',
+  summary: 'Start the SSH master and restore saved forwards',
+  usage: ['fwd up [--host <host>]'],
+  description: 'Use after a reboot, VM restart or network drop. Forwards that are already active are left alone.',
+  args: [0, 0],
+
+  async run({ state, host }) {
+    const { started, pid, results } = await bringUp(host, getForwards(state, host));
+    if (!started) console.log(`SSH master for ${host} is already running${pidSuffix(pid)}`);
+    printResults(host, results);
+    return results.some((r) => r.error) ? 1 : 0;
+  },
+};

package/src/commands/watch.js

@@ -0,0 +1,84 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { FwdError } from '../errors.js';
+import { withLock } from '../lock.js';
+import { checkMaster } from '../ssh.js';
+import { getForwards, loadState } from '../state.js';
+import { bringUp, forwardStatus, printResults, resolveHost } from './common.js';
+
+/** @typedef {import('./common.js').Log} Log */
+
+/** @type {Log} */
+function log(message) {
+  console.log(`[${new Date().toTimeString().slice(0, 8)}] ${message}`);
+}
+
+/**
+ * Check one host and repair it if the master is down or a forward is broken.
+ * State is re-read every time so forwards added or removed meanwhile are
+ * picked up.
+ * @param {string} host
+ */
+async function check(host) {
+  const forwards = getForwards(await loadState(), host);
+  if (!forwards.length) return;
+  const master = await checkMaster(host);
+  const statuses = await Promise.all(forwards.map((fwd) => forwardStatus(fwd, master.alive)));
+  if (statuses.every((s) => s === 'active')) return;
+
+  log(master.alive ? `${host}: some forwards are broken, re-applying` : `${host}: master is down, reconnecting`);
+  await withLock(async () => {
+    const { results } = await bringUp(host, getForwards(await loadState(), host), log);
+    printResults(host, results.filter((r) => r.result !== 'active'), log);
+  });
+}
+
+/** @type {import('./common.js').Command} */
+export default {
+  name: 'watch',
+  summary: 'Keep forwards up, reconnecting when the connection drops',
+  usage: ['fwd watch [--interval <seconds>] [--host <host> | --all-hosts]'],
+  description: [
+    'Runs in the foreground, checking every few seconds. If the master has died',
+    '(VM restart, sleep, network change) it reconnects and restores saved forwards;',
+    'if a local forward stopped listening it is re-applied. Stop with Ctrl+C; the',
+    'master keeps running.',
+  ].join('\n'),
+  args: [0, 0],
+  host: 'self',
+  readonly: true,
+  options: {
+    interval: { type: 'string', value: 'seconds', help: 'How often to check (default 5)' },
+    'all-hosts': { type: 'boolean', help: 'Watch every host with saved forwards' },
+  },
+
+  async run({ flags, state }) {
+    if (flags['all-hosts'] && flags.host !== undefined) throw new FwdError('Use either --host or --all-hosts, not both.');
+    const host = flags['all-hosts'] ? null : resolveHost(state, flags.host);
+    const seconds = flags.interval === undefined ? 5 : Number(flags.interval);
+    if (!(seconds > 0)) throw new FwdError(`Invalid --interval "${flags.interval}": expected a positive number of seconds.`);
+
+    const stop = new AbortController();
+    for (const signal of /** @type {const} */ (['SIGINT', 'SIGTERM'])) process.once(signal, () => stop.abort());
+
+    log(`Watching ${host ?? 'all hosts'} every ${seconds}s. Press Ctrl+C to stop.`);
+    // Only report an error when it changes, so an unreachable host doesn't
+    // print the same line every interval.
+    /** @type {Map<string, string>} */
+    const lastError = new Map();
+    while (!stop.signal.aborted) {
+      const hosts = host ? [host] : Object.keys((await loadState()).hosts);
+      for (const h of hosts) {
+        try {
+          await check(h);
+          if (lastError.delete(h)) log(`${h}: recovered`);
+        } catch (err) {
+          const message = /** @type {Error} */ (err).message;
+          if (lastError.get(h) !== message) log(`${h}: ${message}`);
+          lastError.set(h, message);
+        }
+      }
+      await sleep(seconds * 1000, undefined, { signal: stop.signal }).catch(() => {});
+    }
+    log('Stopped watching.');
+  },
+};

package/src/errors.js

@@ -0,0 +1,9 @@
+// Errors that are expected and should be shown to the user as a plain message,
+// without a stack trace.
+export class FwdError extends Error {
+  /** @param {string} message */
+  constructor(message) {
+    super(message);
+    this.name = 'FwdError';
+  }
+}