@remcp/remcp 0.2.13 → 0.2.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remcp/remcp",
-  "version": "0.2.13",
+  "version": "0.2.18",
   "description": "ReMCP device client: pair a computer with ReMCP and run the outbound-only agent that hosts the local MCP runtime.",
   "type": "module",
   "license": "MIT",
@@ -18,7 +18,7 @@
     "README.md"
   ],
   "scripts": {
-    "check": "node --check bin/remcp.mjs && node --check src/cli.mjs && node --check src/agent.mjs && node --check src/runtime.mjs && node --check src/version.mjs",
+    "check": "node --check bin/remcp.mjs && node --check src/cli.mjs && node --check src/agent.mjs && node --check src/runtime.mjs && node --check src/version.mjs && node --check src/npm.mjs",
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {

package/src/agent.mjs

@@ -6,14 +6,20 @@ import { spawn, spawnSync } from 'node:child_process';
 import WebSocket from 'ws';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { resolveNpm } from './npm.mjs';
 import { isRuntimeSpecFor, normalizeRuntime } from './runtime.mjs';
 import { VERSION } from './version.mjs';
 
-const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+// See src/npm.mjs: a service started by launchd or systemd has a minimal PATH, so npm is resolved
+// from the running node instead of being looked up on PATH.
+const npm = resolveNpm();
 const UPDATE_CHECK_INTERVAL_MS = 6 * 60 * 60 * 1000;
 const UPDATE_CHECK_TIMEOUT_MS = 5000;
 // A version that failed to install is retried after this cooldown instead of on every reconnect.
 const UPDATE_RETRY_COOLDOWN_MS = 30 * 60 * 1000;
+// How long a handing-over agent waits for its replacement to take the device over before it keeps
+// running itself. Long enough for a fresh process to install nothing, connect and be registered.
+const REPLACEMENT_HANDOVER_TIMEOUT_MS = 20_000;
 const METRICS_INTERVAL_MS = 60_000;
 const TELEMETRY_QUEUE_LIMIT = 500;
 const TELEMETRY_BATCH_LIMIT = 100;
@@ -30,12 +36,12 @@ const RUNTIME_RESTART_MAX_MS = 30_000;
 const CALL_TIMEOUT_MARGIN_MS = 10_000;
 
 function globalNodeModules() {
-  const result = spawnSync(npmCommand, ['root', '--global'], { encoding: 'utf8' });
+  const result = spawnSync(npm.command, [...npm.args, 'root', '--global'], { encoding: 'utf8' });
   if (result.error || result.status !== 0) throw new Error('Could not locate the global npm modules directory');
   return String(result.stdout || '').trim();
 }
 
-function localRuntimeEntry(runtimeValue) {
+export function localRuntimeEntry(runtimeValue) {
   const runtime = normalizeRuntime(runtimeValue);
   const candidate = path.join(globalNodeModules(), ...runtime.packageName.split('/'), ...runtime.entry.split(/[\\/]+/));
   if (!existsSync(candidate)) throw new Error('ReMCP local runtime is not installed. Run `remcp install`.');
@@ -106,7 +112,7 @@ export function updateDecision({ advertised, cliVersion, runtimeVersion, runtime
 // Applies a freshly installed version. Exiting is what a supervisor needs; without one the new CLI is
 // started in this process' place. Either way the agent stops holding a stale runtime, which is what
 // makes an update actually take effect on a machine that no service manager watches.
-async function restartToApplyUpdate(cli, stopAgent, markStopping, onRuntimeRepaired) {
+async function restartToApplyUpdate(cli, stopAgent, markStopping, onRuntimeRepaired, isStopping) {
   try {
     const installed = globalInstalledVersion();
     if (installed && !isNewer(installed, VERSION)) {
@@ -116,9 +122,26 @@ async function restartToApplyUpdate(cli, stopAgent, markStopping, onRuntimeRepai
       await onRuntimeRepaired?.();
       return;
     }
-    console.log(`ReMCP ${installed || 'a newer version'} installed; restarting to apply it.`);
+    // Handing over to a version that cannot start would take the machine offline with nobody left to
+    // retry. The new CLI has to answer `--version` before this process steps aside.
+    const probe = spawnSync(process.execPath, [cli, '--version'], { encoding: 'utf8', timeout: 30000 });
+    const reported = String(probe.stdout || '').trim();
+    if (probe.error || probe.status !== 0 || !/^\d+\.\d+\.\d+/.test(reported)) {
+      console.error(`The installed ReMCP ${installed || 'update'} did not run (${probe.error?.message || `exit ${probe.status}`}${reported ? `: ${reported}` : ''}). Keeping ${VERSION} running; retry with: remcp update`);
+      return;
+    }
+    console.log(`ReMCP ${installed || 'a newer version'} installed and verified (${reported}); restarting to apply it.`);
     if (!supervisorRestart()) {
       spawn(process.execPath, [cli, 'start'], { detached: true, stdio: 'ignore', env: { ...process.env } }).unref();
+      // Stepping aside is only safe once the replacement really holds the device: the relay closes
+      // this socket with 1012 ('replaced') the moment another agent takes the machine over, and that
+      // close is what stops this process. Without the wait, a replacement that cannot start left the
+      // machine connected in `/health` and offline everywhere else, with nobody left to retry.
+      await new Promise(resolve => setTimeout(resolve, REPLACEMENT_HANDOVER_TIMEOUT_MS));
+      if (!isStopping()) {
+        console.error(`The replacement agent did not take over within ${Math.round(REPLACEMENT_HANDOVER_TIMEOUT_MS / 1000)}s; keeping ${VERSION} running. Retry with: remcp update`);
+        return;
+      }
     }
     markStopping();
     await stopAgent().catch(() => {});
@@ -147,14 +170,32 @@ function globalInstalledVersion() {
   }
 }
 
-function supervisorRestart() {
-  if (process.env.INVOCATION_ID || process.env.JOURNAL_STREAM) return 'systemd';
-  try { if (existsSync('/.dockerenv')) return 'docker'; } catch {}
+// True when this process is the one a service manager owns: launchd and systemd's system manager run
+// a unit's main process as a child of PID 1, and `systemd --user` runs it as a child of the user
+// manager. Anything else — a terminal, a shell inside another unit, a CI runner job — has nobody
+// waiting to start the agent again.
+function parentIsServiceManager() {
+  if (process.ppid === 1) return true;
+  if (process.platform === 'win32') return false;
+  try { return readFileSync(`/proc/${process.ppid}/comm`, 'utf8').trim() === 'systemd'; } catch { return false; }
+}
+
+// What starts the agent again after it exits to apply an update, or null when it has to start its own
+// replacement. systemd sets INVOCATION_ID and JOURNAL_STREAM for a unit and every child of that unit
+// inherits them, so a `remcp start` run from a shell inside a service (a CI runner, a systemd-run
+// scope, another agent) believed a supervisor would bring it back: the update exited into nothing and
+// the workspace showed the machine offline until someone started the agent by hand. Only the unit's
+// own main process is restarted, so that is what the check requires.
+//
+// Injectable for tests: the verdict must not depend on the machine that runs them.
+export function supervisorRestart({ platform = process.platform, dockerenv = existsSync('/.dockerenv'), parentOurs = parentIsServiceManager() } = {}) {
+  if (parentOurs) return platform === 'darwin' ? 'launchd' : 'systemd';
+  if (dockerenv) return 'docker';
   return null;
 }
 
 function globalCliEntry() {
-  const prefix = spawnSync(npmCommand, ['prefix', '--global'], { encoding: 'utf8' });
+  const prefix = spawnSync(npm.command, [...npm.args, 'prefix', '--global'], { encoding: 'utf8' });
   if (prefix.error || prefix.status !== 0) return null;
   const base = String(prefix.stdout || '').trim();
   return process.platform === 'win32'
@@ -489,7 +530,7 @@ export async function runAgent(options) {
             runtimeError = error instanceof Error ? error.message : String(error);
           }
           if (!runtimeDown && !stopping) await startRuntime();
-        });
+        }, () => stopping);
       });
       child.on('error', error => {
         updateInFlight = false;

package/src/cli.mjs

@@ -4,7 +4,8 @@ import path from 'node:path';
 import process from 'node:process';
 import { spawnSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import { runAgent } from './agent.mjs';
+import { localRuntimeEntry, runAgent, supervisorRestart } from './agent.mjs';
+import { npmVersion, resolveNpm } from './npm.mjs';
 import { isRuntimeSpecFor, normalizeRuntime } from './runtime.mjs';
 import { PACKAGE_NAME, VERSION } from './version.mjs';
 
@@ -18,7 +19,9 @@ const macServiceLabel = 'com.remcp.agent';
 const macServiceFile = path.join(home, 'Library', 'LaunchAgents', `${macServiceLabel}.plist`);
 const macLogFile = path.join(home, 'Library', 'Logs', 'remcp-agent.log');
 const windowsTaskName = 'ReMCP Agent';
-const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+// How npm is invoked is resolved from the running node when possible: a background service has a
+// minimal PATH, which is why auto-update used to find no npm on macOS. See src/npm.mjs.
+const npm = resolveNpm();
 const officialOrigin = 'https://remcp.delio24.com';
 
 function parse(argv) {
@@ -130,7 +133,7 @@ function servicePlatform() {
 }
 
 function globalPrefix() {
-  return output(npmCommand, ['prefix', '--global']);
+  return output(npm.command, [...npm.args, 'prefix', '--global']);
 }
 
 function globalCliPath() {
@@ -139,7 +142,7 @@ function globalCliPath() {
 }
 
 function npmGlobalInstall(...specs) {
-  run(npmCommand, ['install', '--global', ...specs, '--no-audit', '--no-fund', '--loglevel=error']);
+  run(npm.command, [...npm.args, 'install', '--global', ...specs, '--no-audit', '--no-fund', '--loglevel=error']);
 }
 
 function quoteSystemd(value) {
@@ -192,9 +195,28 @@ function installPersistentAgent(config) {
   if (platform === 'linux') installLinuxService(cliPath);
   else if (platform === 'darwin') installMacService(cliPath);
   else installWindowsService(cliPath);
+  saveConfig({ ...config, serviceInstalled: true });
   console.log('ReMCP is installed as a background service. Future updates: remcp update');
 }
 
+// A machine that was installed as a service must still be one after an update: if the job is missing
+// (a failed install, a cleaned LaunchAgents directory, a re-imaged user), the next update recreates
+// it instead of leaving a hand-over to a process nobody supervises.
+function ensureServiceIfRecorded(config) {
+  if (config?.serviceInstalled !== true) return false;
+  try {
+    const cliPath = globalCliPath();
+    const platform = servicePlatform();
+    if (platform === 'linux') { if (!fs.existsSync(linuxServiceFile)) installLinuxService(cliPath); }
+    else if (platform === 'darwin') { if (!fs.existsSync(macServiceFile)) installMacService(cliPath); }
+    else if (platform === 'win32') installWindowsService(cliPath);
+    return true;
+  } catch (error) {
+    console.error(`Could not ensure the background service: ${error instanceof Error ? error.message : String(error)}`);
+    return false;
+  }
+}
+
 function restartPersistentServiceIfInstalled() {
   const platform = servicePlatform();
   if (platform === 'linux' && fs.existsSync(linuxServiceFile)) {
@@ -219,19 +241,69 @@ function restartPersistentServiceIfInstalled() {
 // The agent the user installed with `remcp install` is the one this CLI manages. A machine can also
 // be supervised by its own systemd unit, by Docker, or by a terminal, and in those cases installing
 // a new version is not enough: the running process keeps the old code until something restarts it.
-// systemd marks every unit process with INVOCATION_ID and Docker leaves /.dockerenv, so those two
-// cases can be handed over by exiting (the supervisor starts the new build); anything else gets an
-// explicit instruction instead of a silent exit that would take the device offline.
-function supervisorRestart() {
-  if (process.env.INVOCATION_ID || process.env.JOURNAL_STREAM) return 'systemd';
-  try { if (fs.existsSync('/.dockerenv')) return 'docker'; } catch {}
-  return null;
+// `supervisorRestart` (agent.mjs) answers which of those is true, and only reports a service manager
+// when it really owns this process: a terminal gets an explicit instruction instead of a silent exit
+// that would take the device offline.
+// One real handshake with the local runtime, plus everything needed to explain a failure: where the
+// entry resolved, whether the package is installed, the node that would run it, and the exact error.
+async function diagnoseLocalRuntime(cfg) {
+  const packageName = cfg.runtime?.packageName || '';
+  const diagnosis = {
+    platform: `${process.platform} ${process.arch}`,
+    node: process.execPath,
+    nodeVersion: process.versions.node,
+    packageName,
+    packageSpec: cfg.runtime?.packageSpec || '',
+    installedRuntime: installedVersion(packageName),
+    installedClient: installedVersion(PACKAGE_NAME),
+  };
+  const resolved = resolveNpm();
+  const npmInfo = npmVersion(resolved);
+  diagnosis.npm = npmInfo ? { version: npmInfo.version, source: npmInfo.source } : { error: `npm could not be executed (tried ${resolved.source})` };
+  let entry = '';
+  try {
+    entry = localRuntimeEntry(cfg.runtime);
+    diagnosis.entry = entry;
+    diagnosis.entryExists = fs.existsSync(entry);
+  } catch (error) {
+    diagnosis.entry = null;
+    diagnosis.entryExists = false;
+    diagnosis.verdict = 'runtime-not-installed';
+    diagnosis.error = error instanceof Error ? error.message : String(error);
+    diagnosis.hint = `Reinstall with: npx --yes ${PACKAGE_NAME}@latest update`;
+    return diagnosis;
+  }
+  if (!diagnosis.entryExists) {
+    diagnosis.verdict = 'runtime-entry-missing';
+    diagnosis.hint = `Reinstall with: npx --yes ${PACKAGE_NAME}@latest update`;
+    return diagnosis;
+  }
+  try {
+    const { Client } = await import('@modelcontextprotocol/sdk/client/index.js');
+    const { StdioClientTransport } = await import('@modelcontextprotocol/sdk/client/stdio.js');
+    const client = new Client({ name: 'remcp-doctor', version: VERSION });
+    const stdio = new StdioClientTransport({ command: process.execPath, args: [entry], env: { ...process.env }, maxBufferSize: 4 * 1024 * 1024 });
+    const stderr = [];
+    stdio.onerror = error => stderr.push(String(error?.message || error));
+    await client.connect(stdio);
+    diagnosis.runtimeVersion = client.getServerVersion()?.version || 'unknown';
+    const tools = await client.listTools(undefined, { timeout: 20000 });
+    diagnosis.tools = tools.tools.length;
+    diagnosis.verdict = 'ok';
+    await client.close();
+    return diagnosis;
+  } catch (error) {
+    diagnosis.verdict = 'runtime-handshake-failed';
+    diagnosis.error = error instanceof Error ? error.message : String(error);
+    diagnosis.hint = 'Run the entry above by hand to see its output, then reinstall with: npx --yes @remcp/remcp@latest update';
+    return diagnosis;
+  }
 }
 
 // Reads the version a freshly installed global package reports, so an update that installed
 // nothing (wrong prefix, npm cache, permissions) is reported instead of assumed successful.
 function installedVersion(packageName) {
-  const prefix = spawnSync(npmCommand, ['prefix', '--global'], { encoding: 'utf8' });
+  const prefix = spawnSync(npm.command, [...npm.args, 'prefix', '--global'], { encoding: 'utf8' });
   if (prefix.error || prefix.status !== 0) return null;
   const manifest = path.join(String(prefix.stdout || '').trim(), 'lib', 'node_modules', ...packageName.split('/'), 'package.json');
   try { return JSON.parse(fs.readFileSync(manifest, 'utf8')).version || null; } catch { return null; }
@@ -353,8 +425,25 @@ export async function main(argv = process.argv.slice(2)) {
 
   if (command === 'status' || command === 'doctor') {
     const cfg = loadConfig();
-    const health = await fetch(`${cfg.serverUrl}/health?fresh=${Date.now()}`, { cache: 'no-store' }).then(r => r.json());
-    console.log(JSON.stringify({ configured: true, cliVersion: VERSION, deviceId: cfg.deviceId, deviceName: cfg.deviceName, server: cfg.serverUrl, runtime: cfg.runtime, telemetry: telemetryState(), serverHealth: health }, null, 2));
+    const health = await fetch(`${cfg.serverUrl}/health?fresh=${Date.now()}`, { cache: 'no-store' }).then(r => r.json()).catch(error => ({ error: error.message }));
+    const report = {
+      configured: true,
+      cliVersion: VERSION,
+      deviceId: cfg.deviceId,
+      deviceName: cfg.deviceName,
+      server: cfg.serverUrl,
+      runtime: cfg.runtime,
+      telemetry: telemetryState(),
+      serverHealth: health,
+    };
+    // `doctor` answers the question the workspace cannot: is this machine actually able to run a
+    // tool? It resolves the runtime entry, installs nothing, and tries one real MCP handshake with
+    // the runtime, so the failure is visible here instead of only as "runtime not running".
+    if (command === 'doctor') {
+      report.diagnosis = await diagnoseLocalRuntime(cfg);
+    }
+    console.log(JSON.stringify(report, null, 2));
+    if (command === 'doctor' && report.diagnosis.verdict !== 'ok') process.exitCode = 1;
     return;
   }
 
@@ -401,6 +490,7 @@ export async function main(argv = process.argv.slice(2)) {
       return;
     }
     const before = { cli: VERSION, runtime: installedVersion(cfg.runtime.packageName) };
+    ensureServiceIfRecorded(cfg);
     console.log(`Updating ReMCP to the latest published version (${runtimeSpec})…`);
     npmGlobalInstall(`${PACKAGE_NAME}@latest`, runtimeSpec);
     // Only a validated spec is persisted, so a failed update cannot leave the install unable to start.
@@ -425,7 +515,7 @@ export async function main(argv = process.argv.slice(2)) {
     if (flags.purge) {
       const cfg = loadConfig(false);
       const specs = [PACKAGE_NAME, ...(cfg?.runtime?.packageName ? [cfg.runtime.packageName] : [])];
-      run(npmCommand, ['uninstall', '--global', ...specs, '--no-audit', '--no-fund', '--loglevel=error']);
+      run(npm.command, [...npm.args, 'uninstall', '--global', ...specs, '--no-audit', '--no-fund', '--loglevel=error']);
     }
     return;
   }

package/src/npm.mjs

@@ -0,0 +1,83 @@
+import { existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { spawnSync } from 'node:child_process';
+
+// A background service does not inherit the PATH a terminal has: a launchd agent, a systemd unit and
+// a Windows scheduled task all start with a minimal environment where `npm` is often not on PATH at
+// all. That is how auto-update silently stopped working on macOS — the agent looked for `npm`, did
+// not find it, and told the user to run the command by hand.
+//
+// npm is a JavaScript entry point, so the reliable answer is to run it with the same node that is
+// already executing us, and only fall back to a PATH lookup. The resolver also accepts an explicit
+// override (REMCP_NPM) for unusual installations.
+const NPM_CLI_RELATIVE = ['lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'];
+
+export function npmCandidates({ nodePath = process.execPath, home = os.homedir(), platform = process.platform } = {}) {
+  const nodeDir = path.dirname(nodePath);
+  const cli = [];
+  // nvm, n, the official installer and the Docker image all place npm beside node like this.
+  cli.push(path.join(nodeDir, '..', NPM_CLI_RELATIVE.join(path.sep)));
+  cli.push(path.join(nodeDir, NPM_CLI_RELATIVE.join(path.sep)));
+  if (platform === 'darwin') {
+    cli.push(path.join('/opt/homebrew', NPM_CLI_RELATIVE.join(path.sep)));
+    cli.push(path.join('/usr/local', NPM_CLI_RELATIVE.join(path.sep)));
+  } else if (platform === 'win32') {
+    cli.push(path.join(nodeDir, 'node_modules', 'npm', 'bin', 'npm-cli.js'));
+  } else {
+    cli.push(path.join('/usr', NPM_CLI_RELATIVE.join(path.sep)));
+    cli.push(path.join('/usr/local', NPM_CLI_RELATIVE.join(path.sep)));
+  }
+  cli.push(path.join(home, '.local', NPM_CLI_RELATIVE.join(path.sep)));
+  const binaries = [
+    path.join(nodeDir, platform === 'win32' ? 'npm.cmd' : 'npm'),
+    path.join(nodeDir, '..', 'bin', platform === 'win32' ? 'npm.cmd' : 'npm'),
+    platform === 'darwin' ? '/opt/homebrew/bin/npm' : '',
+    platform === 'win32' ? '' : '/usr/local/bin/npm',
+    platform === 'win32' ? '' : '/usr/bin/npm',
+    platform === 'win32' ? '' : path.join(home, '.local', 'bin', 'npm'),
+  ].filter(Boolean);
+  return { cli: [...new Set(cli)], binaries: [...new Set(binaries)] };
+}
+
+// Resolves how to run npm. `source` is reported by `remcp doctor` and logged at agent startup so a
+// machine where npm cannot be found is obvious before an update is needed.
+//
+// `exists` is injectable so a test can describe a machine with no npm at all instead of asking the
+// machine running the test: the Linux candidate list carries fixed prefixes (/usr, /usr/local) that
+// a CI runner or a developer laptop usually does have, which made that case untestable there.
+export function resolveNpm({ nodePath = process.execPath, home = os.homedir(), platform = process.platform, exists = existsSync } = {}) {
+  const override = String(process.env.REMCP_NPM || '').trim();
+  if (override) return { command: override, args: [], source: `REMCP_NPM=${override}` };
+  const { cli, binaries } = npmCandidates({ nodePath, home, platform });
+  for (const candidate of cli) {
+    if (exists(candidate)) return { command: nodePath, args: [candidate], source: `node ${candidate}` };
+  }
+  for (const candidate of binaries) {
+    if (exists(candidate)) return { command: candidate, args: [], source: candidate };
+  }
+  return { command: platform === 'win32' ? 'npm.cmd' : 'npm', args: [], source: 'PATH' };
+}
+
+// The version npm itself reports, or null when it cannot be executed at all.
+export function npmVersion(resolved = resolveNpm()) {
+  const result = spawnSync(resolved.command, [...resolved.args, '--version'], { encoding: 'utf8', timeout: 15000 });
+  if (result.error || result.status !== 0) {
+    // A login shell may still find npm (nvm and Homebrew write their PATH into the profile).
+    const shell = process.platform === 'win32' ? null : spawnSync('/bin/sh', ['-lc', 'command -v npm'], { encoding: 'utf8', timeout: 15000 });
+    const found = String(shell?.stdout || '').trim().split('\n').pop();
+    if (found && existsSync(found)) {
+      const retry = spawnSync(found, ['--version'], { encoding: 'utf8', timeout: 15000 });
+      if (!retry.error && retry.status === 0) return { version: String(retry.stdout).trim(), source: found };
+    }
+    return null;
+  }
+  return { version: String(result.stdout).trim(), source: resolved.source };
+}
+
+// Runs npm with the resolved command, so callers never depend on PATH.
+export function npmRun(args, { encoding = 'utf8', stdio = 'inherit' } = {}) {
+  const resolved = resolveNpm();
+  return spawnSync(resolved.command, [...resolved.args, ...args], { encoding, stdio });
+}