@remcp/remcp 0.2.33 → 0.2.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remcp/remcp",
-  "version": "0.2.33",
+  "version": "0.2.35",
   "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/agent.mjs && node --check src/cli.mjs && node --check src/cli/config.mjs && node --check src/cli/connect.mjs && node --check src/cli/doctor.mjs && node --check src/cli/env.mjs && node --check src/cli/service.mjs && node --check src/cli/shell.mjs && node --check src/fs-access.mjs && node --check src/npm.mjs && node --check src/runtime.mjs && node --check src/version.mjs",
+    "check": "node --check bin/remcp.mjs && node --check src/agent-update.mjs && node --check src/agent.mjs && node --check src/cli.mjs && node --check src/cli/config.mjs && node --check src/cli/connect.mjs && node --check src/cli/doctor.mjs && node --check src/cli/env.mjs && node --check src/cli/service.mjs && node --check src/cli/shell.mjs && node --check src/cli/update.mjs && node --check src/fs-access.mjs && node --check src/npm.mjs && node --check src/runtime.mjs && node --check src/version.mjs",
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {

package/src/agent-update.mjs

@@ -0,0 +1,180 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { spawn, spawnSync } from 'node:child_process';
+import { resolveNpm } from './npm.mjs';
+import { isRuntimeSpecFor, normalizeRuntime } from './runtime.mjs';
+import { VERSION } from './version.mjs';
+
+const npm = resolveNpm();
+// 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 connect and be registered.
+const REPLACEMENT_HANDOVER_TIMEOUT_MS = 20_000;
+
+function globalNodeModules() {
+  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();
+}
+
+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`.');
+  return candidate;
+}
+
+function parseVersion(value) {
+  // Prerelease and build metadata are kept, because comparing only the numeric core made
+  // 1.0.0 look newer than 1.0.0-beta.2 and left a machine stuck on the prerelease forever.
+  const match = String(value || '').match(/(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/);
+  return match ? { parts: [Number(match[1]), Number(match[2]), Number(match[3])], prerelease: match[4] || '' } : null;
+}
+
+function isNewer(candidate, current) {
+  const a = parseVersion(candidate);
+  const b = parseVersion(current);
+  if (!a || !b) return false;
+  for (let index = 0; index < 3; index += 1) {
+    if (a.parts[index] > b.parts[index]) return true;
+    if (a.parts[index] < b.parts[index]) return false;
+  }
+  // Same numeric core: a release is newer than a prerelease, and two prereleases compare by
+  // identifier (numeric identifiers order numerically, as semver requires).
+  if (!a.prerelease && b.prerelease) return true;
+  if (a.prerelease && !b.prerelease) return false;
+  if (!a.prerelease && !b.prerelease) return false;
+  const left = a.prerelease.split('.');
+  const right = b.prerelease.split('.');
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const one = left[index];
+    const two = right[index];
+    if (one === undefined) return false;
+    if (two === undefined) return true;
+    if (one === two) continue;
+    const oneNumeric = /^\d+$/.test(one);
+    const twoNumeric = /^\d+$/.test(two);
+    if (oneNumeric && twoNumeric) return Number(one) > Number(two);
+    if (oneNumeric !== twoNumeric) return oneNumeric;
+    return one > two;
+  }
+  return false;
+}
+
+// What the agent should install, if anything. The client version alone is not enough: a machine
+// that already runs the newest client but an older local runtime would otherwise never catch up,
+// because its runtime is what executes the tools.
+export function updateDecision({ advertised, cliVersion, runtimeVersion, runtimePackageName, runtimeDown = false }) {
+  const cliSpec = String(advertised?.cli || '');
+  const advertisedRuntime = String(advertised?.runtime || '');
+  // A spec that is not a plain version of the configured runtime package is ignored rather than
+  // installed: this is the only place a server-chosen string reaches npm.
+  const runtimeSpec = runtimePackageName && advertisedRuntime && !isRuntimeSpecFor(runtimePackageName, advertisedRuntime) ? '' : advertisedRuntime;
+  const installedRuntime = String(runtimeVersion || '');
+  const runtimeKnown = Boolean(installedRuntime) && !/^unknown$/i.test(installedRuntime);
+  if (isNewer(cliSpec, cliVersion)) return { needed: true, target: cliSpec, runtime: runtimeSpec, reason: 'client' };
+  if (runtimeSpec && runtimeKnown && isNewer(runtimeSpec, installedRuntime)) {
+    return { needed: true, target: cliSpec || `@remcp/remcp@${cliVersion}`, runtime: runtimeSpec, reason: 'runtime' };
+  }
+  // A runtime that never reported a version cannot be compared, so a device whose runtime is down
+  // (or was never installed) would never repair itself. The cooldown in checkForUpdate keeps this
+  // from becoming an install loop.
+  if (runtimeSpec && !runtimeKnown && runtimeDown) {
+    return { needed: true, target: cliSpec || `@remcp/remcp@${cliVersion}`, runtime: runtimeSpec, reason: 'runtime-repair' };
+  }
+  return { needed: false, target: cliSpec, runtime: runtimeSpec, reason: 'current' };
+}
+
+// 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.
+export async function restartToApplyUpdate(cli, stopAgent, markStopping, onRuntimeRepaired, isStopping) {
+  try {
+    const installed = globalInstalledVersion();
+    if (installed && !isNewer(installed, VERSION)) {
+      // The client is current, so the update was a runtime repair: restart the runtime rather than
+      // the whole agent, or a device with no usable runtime would stay broken.
+      console.log(`ReMCP ${VERSION} is already the installed version; restarting the local runtime.`);
+      await onRuntimeRepaired?.();
+      return;
+    }
+    // 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(() => {});
+    setTimeout(() => process.exit(0), 100);
+  } catch (error) {
+    console.error(`Could not restart after the update: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+// The version of the globally installed client, read from the package the CLI resolves to.
+export function globalInstalledVersion() {
+  try {
+    const cli = globalCliEntry();
+    if (!cli) return null;
+    const base = path.dirname(cli);
+    const candidates = [
+      path.join(base, '..', 'lib', 'node_modules', '@remcp', 'remcp', 'package.json'),
+      path.join(base, '..', 'node_modules', '@remcp', 'remcp', 'package.json'),
+    ];
+    for (const manifest of candidates) {
+      try { return JSON.parse(readFileSync(manifest, 'utf8')).version || null; } catch {}
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// 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;
+}
+
+export function globalCliEntry() {
+  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'
+    ? path.join(base, 'remcp.cmd')
+    : path.join(base, 'bin', 'remcp');
+}

package/src/agent.mjs

@@ -1,25 +1,26 @@
 import os from 'node:os';
-import { existsSync, readFileSync } from 'node:fs';
-import path from 'node:path';
+import { existsSync } from 'node:fs';
 import process from 'node:process';
-import { spawn, spawnSync } from 'node:child_process';
+import { spawn } 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';
+import {
+  globalCliEntry,
+  globalInstalledVersion,
+  localRuntimeEntry,
+  restartToApplyUpdate,
+  supervisorRestart,
+  updateDecision,
+} from './agent-update.mjs';
+
+export { localRuntimeEntry, supervisorRestart, updateDecision } from './agent-update.mjs';
 
-// 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;
@@ -38,174 +39,6 @@ const RUNTIME_RESTART_MAX_MS = 30_000;
 // timeout while the device keeps working invisibly.
 const CALL_TIMEOUT_MARGIN_MS = 10_000;
 
-function globalNodeModules() {
-  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();
-}
-
-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`.');
-  return candidate;
-}
-
-function parseVersion(value) {
-  // Prerelease and build metadata are kept, because comparing only the numeric core made
-  // 1.0.0 look newer than 1.0.0-beta.2 and left a machine stuck on the prerelease forever.
-  const match = String(value || '').match(/(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/);
-  return match ? { parts: [Number(match[1]), Number(match[2]), Number(match[3])], prerelease: match[4] || '' } : null;
-}
-
-function isNewer(candidate, current) {
-  const a = parseVersion(candidate);
-  const b = parseVersion(current);
-  if (!a || !b) return false;
-  for (let index = 0; index < 3; index += 1) {
-    if (a.parts[index] > b.parts[index]) return true;
-    if (a.parts[index] < b.parts[index]) return false;
-  }
-  // Same numeric core: a release is newer than a prerelease, and two prereleases compare by
-  // identifier (numeric identifiers order numerically, as semver requires).
-  if (!a.prerelease && b.prerelease) return true;
-  if (a.prerelease && !b.prerelease) return false;
-  if (!a.prerelease && !b.prerelease) return false;
-  const left = a.prerelease.split('.');
-  const right = b.prerelease.split('.');
-  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
-    const one = left[index];
-    const two = right[index];
-    if (one === undefined) return false;
-    if (two === undefined) return true;
-    if (one === two) continue;
-    const oneNumeric = /^\d+$/.test(one);
-    const twoNumeric = /^\d+$/.test(two);
-    if (oneNumeric && twoNumeric) return Number(one) > Number(two);
-    if (oneNumeric !== twoNumeric) return oneNumeric;
-    return one > two;
-  }
-  return false;
-}
-
-// What the agent should install, if anything. The client version alone is not enough: a machine
-// that already runs the newest client but an older local runtime would otherwise never catch up,
-// because its runtime is what executes the tools.
-export function updateDecision({ advertised, cliVersion, runtimeVersion, runtimePackageName, runtimeDown = false }) {
-  const cliSpec = String(advertised?.cli || '');
-  const advertisedRuntime = String(advertised?.runtime || '');
-  // A spec that is not a plain version of the configured runtime package is ignored rather than
-  // installed: this is the only place a server-chosen string reaches npm.
-  const runtimeSpec = runtimePackageName && advertisedRuntime && !isRuntimeSpecFor(runtimePackageName, advertisedRuntime) ? '' : advertisedRuntime;
-  const installedRuntime = String(runtimeVersion || '');
-  const runtimeKnown = Boolean(installedRuntime) && !/^unknown$/i.test(installedRuntime);
-  if (isNewer(cliSpec, cliVersion)) return { needed: true, target: cliSpec, runtime: runtimeSpec, reason: 'client' };
-  if (runtimeSpec && runtimeKnown && isNewer(runtimeSpec, installedRuntime)) {
-    return { needed: true, target: cliSpec || `@remcp/remcp@${cliVersion}`, runtime: runtimeSpec, reason: 'runtime' };
-  }
-  // A runtime that never reported a version cannot be compared, so a device whose runtime is down
-  // (or was never installed) would never repair itself. The cooldown in checkForUpdate keeps this
-  // from becoming an install loop.
-  if (runtimeSpec && !runtimeKnown && runtimeDown) {
-    return { needed: true, target: cliSpec || `@remcp/remcp@${cliVersion}`, runtime: runtimeSpec, reason: 'runtime-repair' };
-  }
-  return { needed: false, target: cliSpec, runtime: runtimeSpec, reason: 'current' };
-}
-
-// 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, isStopping) {
-  try {
-    const installed = globalInstalledVersion();
-    if (installed && !isNewer(installed, VERSION)) {
-      // The client is current, so the update was a runtime repair: restart the runtime rather than
-      // the whole agent, or a device with no usable runtime would stay broken.
-      console.log(`ReMCP ${VERSION} is already the installed version; restarting the local runtime.`);
-      await onRuntimeRepaired?.();
-      return;
-    }
-    // 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(() => {});
-    setTimeout(() => process.exit(0), 100);
-  } catch (error) {
-    console.error(`Could not restart after the update: ${error instanceof Error ? error.message : String(error)}`);
-  }
-}
-
-// The version of the globally installed client, read from the package the CLI resolves to.
-function globalInstalledVersion() {
-  try {
-    const cli = globalCliEntry();
-    if (!cli) return null;
-    const base = path.dirname(cli);
-    const candidates = [
-      path.join(base, '..', 'lib', 'node_modules', '@remcp', 'remcp', 'package.json'),
-      path.join(base, '..', 'node_modules', '@remcp', 'remcp', 'package.json'),
-    ];
-    for (const manifest of candidates) {
-      try { return JSON.parse(readFileSync(manifest, 'utf8')).version || null; } catch {}
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
-
-// 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(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'
-    ? path.join(base, 'remcp.cmd')
-    : path.join(base, 'bin', 'remcp');
-}
-
 function jitter(ms) {
   return Math.round(ms * (0.75 + Math.random() * 0.5));
 }

package/src/cli/connect.mjs

@@ -8,13 +8,22 @@ import { ensureMachineId } from './config.mjs';
 import { officialOrigin } from './env.mjs';
 import { sleep } from './shell.mjs';
 
+// Keep the server-provided approval URL as data all the way to the OS. In particular, do not route it
+// through `cmd /c start` on Windows: cmd reparses metacharacters such as `&`, so a custom pairing
+// server could otherwise turn a verification URL into a local shell command.
+export function browserLaunchCommand(url, platform = process.platform) {
+  const target = String(url);
+  if (platform === 'darwin') return { command: 'open', args: [target] };
+  if (platform === 'win32') return { command: 'explorer.exe', args: [target] };
+  return { command: 'xdg-open', args: [target] };
+}
+
 // Opens the approval page in the person's browser. A machine that nobody is looking at only gets the
 // printed URL, so every failure here is silent and non-fatal.
 export function openInBrowser(url) {
   try {
-    const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
-    const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
-    const child = spawn(command, args, { stdio: 'ignore', detached: true });
+    const { command, args } = browserLaunchCommand(url);
+    const child = spawn(command, args, { stdio: 'ignore', detached: true, shell: false });
     child.on('error', () => {});
     child.unref();
   } catch {}

package/src/cli/update.mjs

@@ -0,0 +1,74 @@
+// `remcp update`: install what the server advertises, then let whoever supervises the agent restart
+// it. Only a spec the configured package can satisfy is installed, so a pairing response from a
+// custom server cannot point this machine at a different package or run a git/URL spec.
+import fs from 'node:fs';
+import process from 'node:process';
+
+import { supervisorRestart } from '../agent.mjs';
+import { isRuntimeSpecFor, normalizeRuntime } from '../runtime.mjs';
+import { PACKAGE_NAME, VERSION } from '../version.mjs';
+
+import { loadConfig, saveConfig } from './config.mjs';
+import { installedVersion } from './doctor.mjs';
+import { linuxServiceFile, macServiceFile, officialOrigin } from './env.mjs';
+import { ensureServiceIfRecorded, npmGlobalInstall, restartPersistentServiceIfInstalled } from './service.mjs';
+
+export async function updateCommand(flags) {
+  const cfg = loadConfig();
+  // The server advertises which runtime version it expects; an agent that is updating
+  // itself passes it through so client and runtime move together.
+  const requested = typeof flags.runtime === 'string' ? flags.runtime.trim() : '';
+  // Whatever the server advertises is installed globally, so it is validated exactly like the
+  // metadata from a pairing response: same package as the configured runtime, a spec that
+  // parses, and an explicit --trust-runtime before a custom server may change it.
+  let runtimeSpec = cfg.runtime.packageSpec;
+  if (requested) {
+    // Only `<configured package>@<semver>` is installable: an alias, a git/URL/file spec, a tag or
+    // a range would run code the user never agreed to.
+    if (!isRuntimeSpecFor(cfg.runtime.packageName, requested)) {
+      throw new Error(`--runtime must be ${cfg.runtime.packageName}@<version>`);
+    }
+    const trusted = cfg.trustRuntime === true
+      || Boolean(flags['trust-runtime'])
+      || process.env.REMCP_TRUST_RUNTIME === '1'
+      // A configuration written before the field existed paired with the official server, which is
+      // trusted by definition; refusing it would silently stop every existing device updating.
+      || new URL(cfg.serverUrl).origin === officialOrigin;
+    if (!trusted) {
+      throw new Error(`This machine was paired without trusting ${cfg.serverUrl} to choose a runtime version. Re-run with --trust-runtime if you trust that server.`);
+    }
+    runtimeSpec = normalizeRuntime({ kind: 'npm', packageName: cfg.runtime.packageName, packageSpec: requested, entry: cfg.runtime.entry }).packageSpec;
+  }
+  if (flags.check) {
+    console.log(JSON.stringify({
+      current: VERSION,
+      installedRuntime: installedVersion(cfg.runtime.packageName),
+      runtimeSpec: runtimeSpec,
+      available: `${PACKAGE_NAME}@latest`,
+      managedService: fs.existsSync(linuxServiceFile) || fs.existsSync(macServiceFile),
+      supervisor: supervisorRestart() ?? 'none',
+    }, null, 2));
+    return;
+  }
+  const before = { cli: VERSION, runtime: installedVersion(cfg.runtime.packageName) };
+  console.log(`Updating ReMCP to the latest published version (${runtimeSpec})…`);
+  npmGlobalInstall(`${PACKAGE_NAME}@latest`, runtimeSpec);
+  // The npm prefix can change across Node-manager upgrades. Repair an existing persistent-service
+  // launcher only after the install, when globalCliPath() points at the CLI we just installed.
+  ensureServiceIfRecorded(cfg);
+  // Only a validated spec is persisted, so a failed update cannot leave the install unable to start.
+  if (requested && runtimeSpec !== cfg.runtime.packageSpec) saveConfig({ ...cfg, runtime: { ...cfg.runtime, packageSpec: runtimeSpec } });
+  const after = { cli: installedVersion(PACKAGE_NAME), runtime: installedVersion(cfg.runtime.packageName) };
+  const restarted = restartPersistentServiceIfInstalled();
+  if (restarted) {
+    console.log(`ReMCP updated and ${restarted} restarted (client ${before.cli} → ${after.cli ?? '?'}, runtime ${before.runtime ?? '?'} → ${after.runtime ?? '?'}).`);
+    return;
+  }
+  // This process is the updater, not the agent: exiting here would restart nothing. The agent sees
+  // the exit status, verifies the installed version, and restarts itself.
+  console.log(`ReMCP updated (client ${before.cli} → ${after.cli ?? '?'}, runtime ${before.runtime ?? '?'} → ${after.runtime ?? '?'}). The running agent restarts itself to apply it.`);
+  if (after.cli === before.cli && after.runtime === before.runtime) {
+    console.log('Nothing changed: the installed versions already match the requested ones.');
+  }
+  return;
+}

package/src/cli.mjs

@@ -1,18 +1,18 @@
-import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
-import { runAgent, supervisorRestart } from './agent.mjs';
-import { isRuntimeSpecFor, normalizeRuntime } from './runtime.mjs';
+import { runAgent } from './agent.mjs';
+import { normalizeRuntime } from './runtime.mjs';
 import { PACKAGE_NAME, VERSION } from './version.mjs';
 import { probeFilesystemAccess } from './fs-access.mjs';
 
 import { ensureMachineId, loadConfig, readJsonFile, saveConfig, setTelemetry, telemetryState, writeJsonFile } from './cli/config.mjs';
 import { assertRuntimeTrust, pairWithDeviceCode } from './cli/connect.mjs';
-import { diagnoseLocalRuntime, installedVersion, runtimeAllowedRoots } from './cli/doctor.mjs';
-import { configFile, linuxServiceFile, macServiceFile, npm, officialOrigin, runtimeConfigFile } from './cli/env.mjs';
-import { ensureServiceIfRecorded, globalCliPath, installPersistentAgent, npmGlobalInstall, restartPersistentServiceIfInstalled, uninstallPersistentService } from './cli/service.mjs';
+import { diagnoseLocalRuntime, runtimeAllowedRoots } from './cli/doctor.mjs';
+import { configFile, npm, officialOrigin, runtimeConfigFile } from './cli/env.mjs';
+import { installPersistentAgent, restartPersistentServiceIfInstalled, uninstallPersistentService } from './cli/service.mjs';
 import { run } from './cli/shell.mjs';
+import { updateCommand } from './cli/update.mjs';
 function parse(argv) {
   const [command = 'help', ...rest] = argv;
   const flags = {};
@@ -208,62 +208,7 @@ export async function main(argv = process.argv.slice(2)) {
   }
 
   if (command === 'update') {
-    const cfg = loadConfig();
-    // The server advertises which runtime version it expects; an agent that is updating
-    // itself passes it through so client and runtime move together.
-    const requested = typeof flags.runtime === 'string' ? flags.runtime.trim() : '';
-    // Whatever the server advertises is installed globally, so it is validated exactly like the
-    // metadata from a pairing response: same package as the configured runtime, a spec that
-    // parses, and an explicit --trust-runtime before a custom server may change it.
-    let runtimeSpec = cfg.runtime.packageSpec;
-    if (requested) {
-      // Only `<configured package>@<semver>` is installable: an alias, a git/URL/file spec, a tag or
-      // a range would run code the user never agreed to.
-      if (!isRuntimeSpecFor(cfg.runtime.packageName, requested)) {
-        throw new Error(`--runtime must be ${cfg.runtime.packageName}@<version>`);
-      }
-      const trusted = cfg.trustRuntime === true
-        || Boolean(flags['trust-runtime'])
-        || process.env.REMCP_TRUST_RUNTIME === '1'
-        // A configuration written before the field existed paired with the official server, which is
-        // trusted by definition; refusing it would silently stop every existing device updating.
-        || new URL(cfg.serverUrl).origin === officialOrigin;
-      if (!trusted) {
-        throw new Error(`This machine was paired without trusting ${cfg.serverUrl} to choose a runtime version. Re-run with --trust-runtime if you trust that server.`);
-      }
-      runtimeSpec = normalizeRuntime({ kind: 'npm', packageName: cfg.runtime.packageName, packageSpec: requested, entry: cfg.runtime.entry }).packageSpec;
-    }
-    if (flags.check) {
-      console.log(JSON.stringify({
-        current: VERSION,
-        installedRuntime: installedVersion(cfg.runtime.packageName),
-        runtimeSpec: runtimeSpec,
-        available: `${PACKAGE_NAME}@latest`,
-        managedService: fs.existsSync(linuxServiceFile) || fs.existsSync(macServiceFile),
-        supervisor: supervisorRestart() ?? 'none',
-      }, null, 2));
-      return;
-    }
-    const before = { cli: VERSION, runtime: installedVersion(cfg.runtime.packageName) };
-    console.log(`Updating ReMCP to the latest published version (${runtimeSpec})…`);
-    npmGlobalInstall(`${PACKAGE_NAME}@latest`, runtimeSpec);
-    // The npm prefix can change across Node-manager upgrades. Repair an existing persistent-service
-    // launcher only after the install, when globalCliPath() points at the CLI we just installed.
-    ensureServiceIfRecorded(cfg);
-    // Only a validated spec is persisted, so a failed update cannot leave the install unable to start.
-    if (requested && runtimeSpec !== cfg.runtime.packageSpec) saveConfig({ ...cfg, runtime: { ...cfg.runtime, packageSpec: runtimeSpec } });
-    const after = { cli: installedVersion(PACKAGE_NAME), runtime: installedVersion(cfg.runtime.packageName) };
-    const restarted = restartPersistentServiceIfInstalled();
-    if (restarted) {
-      console.log(`ReMCP updated and ${restarted} restarted (client ${before.cli} → ${after.cli ?? '?'}, runtime ${before.runtime ?? '?'} → ${after.runtime ?? '?'}).`);
-      return;
-    }
-    // This process is the updater, not the agent: exiting here would restart nothing. The agent sees
-    // the exit status, verifies the installed version, and restarts itself.
-    console.log(`ReMCP updated (client ${before.cli} → ${after.cli ?? '?'}, runtime ${before.runtime ?? '?'} → ${after.runtime ?? '?'}). The running agent restarts itself to apply it.`);
-    if (after.cli === before.cli && after.runtime === before.runtime) {
-      console.log('Nothing changed: the installed versions already match the requested ones.');
-    }
+    await updateCommand(flags);
     return;
   }
 
@@ -278,4 +223,4 @@ export async function main(argv = process.argv.slice(2)) {
   }
 
   printHelp();
-}
+}

package/src/macos-permissions.mjs

@@ -1,38 +0,0 @@
-import os from 'node:os';
-import path from 'node:path';
-import { readdir } from 'node:fs/promises';
-
-// macOS gates Desktop, Documents, Downloads and iCloud Drive behind TCC. A paired Mac can be online,
-// healthy and answering tools, and still fail every write into Desktop with `EACCES: permission
-// denied` — the failure people actually report, because the workspace and the model only ever see the
-// errno. `remcp doctor` is the one place that can look at the machine itself, so it reports which of
-// those folders this process may use.
-//
-// The probe is read-only on purpose: reading a directory is what TCC gates, so a directory that
-// cannot be listed is a directory that cannot be written either, and listing one cannot change it.
-export const MACOS_PROTECTED_FOLDERS = Object.freeze(['Desktop', 'Documents', 'Downloads']);
-
-export function macosPermissionHint(execPath = process.execPath) {
-  return `macOS is blocking one or more protected folders. Grant access by hand: System Settings → Privacy & Security → Full Disk Access → + → ${execPath}, then restart the agent with \`remcp start\`. Folders outside Desktop, Documents, Downloads and iCloud Drive need no new permission.`;
-}
-
-export async function probeMacosFolderAccess({ platform = process.platform, home = os.homedir(), list = readdir } = {}) {
-  if (platform !== 'darwin' || !home) return { supported: false, folders: [] };
-  const candidates = MACOS_PROTECTED_FOLDERS.map(name => ({ name, path: path.join(home, name) }));
-  // iCloud Drive only exists when it is switched on; a missing folder is not a permission problem.
-  candidates.push({ name: 'iCloud Drive', path: path.join(home, 'Library', 'Mobile Documents') });
-  const folders = [];
-  for (const candidate of candidates) {
-    try {
-      await list(candidate.path);
-      folders.push({ ...candidate, state: 'ok' });
-    } catch (error) {
-      const code = typeof error?.code === 'string' ? error.code : '';
-      if (code === 'ENOENT') folders.push({ ...candidate, state: 'missing' });
-      else if (code === 'EACCES' || code === 'EPERM') folders.push({ ...candidate, state: 'denied', code });
-      else folders.push({ ...candidate, state: 'error', code: code || 'unknown' });
-    }
-  }
-  const denied = folders.filter(folder => folder.state === 'denied');
-  return { supported: true, folders, ...(denied.length ? { denied: denied.map(folder => folder.name), hint: macosPermissionHint() } : {}) };
-}