overlord-cli 3.20.0 → 3.22.0

package/README.md

@@ -12,6 +12,9 @@ Install it globally so the `ovld` and `overlord` commands are available on your
 npm install -g overlord-cli
 ```
 
+Use Node.js 20 or newer for every CLI install or update.
+Run `ovld update` any time you want to refresh the global npm install to the latest release.
+
 ## Usage
 
 ```bash
@@ -29,6 +32,7 @@ ovld auth login
 ovld attach
 ovld create "Investigate the failing build"
 ovld prompt "Draft a fix for the onboarding flow"
+ovld update
 ovld setup codex
 ovld setup cursor
 ovld setup gemini
@@ -38,7 +42,7 @@ ovld doctor
 
 ## Requirements
 
-- Node.js 24 or newer
+- Node.js 20 or newer
 - Access to an Overlord instance when using authenticated commands
 
 ## Commands
@@ -52,6 +56,7 @@ ovld doctor
 - `protocol` - run ticket lifecycle commands
 - `connect`, `restart`, `run`, `resume`, `context` - launch or resume an agent session
 - `setup` - install the Overlord connector or plugin bundle for a supported agent
+- `update` - install the latest CLI release from npm
 - `doctor` - verify installed agent connectors and check whether a newer CLI version is available
 
 ## License

package/bin/_cli/cli-update.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const cliPackage = require('../../package.json');
+
+const CURRENT_CLI_VERSION = typeof cliPackage.version === 'string' ? cliPackage.version : '0.0.0';
+const CLI_PACKAGE_NAME =
+  typeof cliPackage.name === 'string' && cliPackage.name ? cliPackage.name : 'overlord-cli';
+
+const ORANGE = '\x1b[38;5;208m';
+const RESET = '\x1b[0m';
+
+function colorizeOrange(text) {
+  return `${ORANGE}${text}${RESET}`;
+}
+
+export function getCurrentCliVersion() {
+  return CURRENT_CLI_VERSION;
+}
+
+export function getCliPackageName() {
+  return CLI_PACKAGE_NAME;
+}
+
+export async function fetchLatestCliVersion({
+  fetchImpl = fetch,
+  packageName = CLI_PACKAGE_NAME,
+  timeoutMs = 2500
+} = {}) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetchImpl(`https://registry.npmjs.org/${packageName}/latest`, {
+      signal: controller.signal,
+      headers: { Accept: 'application/json' }
+    });
+
+    if (!response.ok) return null;
+
+    const payload = await response.json();
+    return typeof payload?.version === 'string' ? payload.version : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export async function checkForCliUpdate(options = {}) {
+  const currentVersion = options.currentVersion ?? CURRENT_CLI_VERSION;
+  const latestVersion = await fetchLatestCliVersion(options);
+  if (!latestVersion || latestVersion === currentVersion) return null;
+  return latestVersion;
+}
+
+export function formatCliUpdateNotice(latestVersion, { currentVersion = CURRENT_CLI_VERSION } = {}) {
+  return `New Overlord CLI version available: v${latestVersion} (installed v${currentVersion}). Run \`ovld update\` to update via npm.`;
+}
+
+export function printCliUpdateNotice(
+  latestVersion,
+  { currentVersion = CURRENT_CLI_VERSION, stream = process.stderr } = {}
+) {
+  if (!latestVersion) return false;
+  stream.write(`${colorizeOrange(formatCliUpdateNotice(latestVersion, { currentVersion }))}\n`);
+  return true;
+}
+
+export async function runCliUpdateCommand({
+  currentVersion = CURRENT_CLI_VERSION,
+  fetchLatestVersionFn = fetchLatestCliVersion,
+  logger = console,
+  npmCommand = 'npm',
+  packageName = CLI_PACKAGE_NAME,
+  spawnSyncImpl = spawnSync
+} = {}) {
+  const latestVersion = await fetchLatestVersionFn({ currentVersion, packageName });
+
+  if (latestVersion && latestVersion === currentVersion) {
+    logger.log(`Overlord CLI ${currentVersion} is already the latest version.`);
+    return { alreadyLatest: true, currentVersion, latestVersion };
+  }
+
+  const target = `${packageName}@latest`;
+  if (latestVersion) {
+    logger.log(`Updating Overlord CLI ${currentVersion} -> ${latestVersion} via npm...`);
+  } else {
+    logger.log(`Updating Overlord CLI via npm...`);
+  }
+
+  const result = spawnSyncImpl(npmCommand, ['install', '-g', target], {
+    env: process.env,
+    stdio: 'inherit'
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  if (typeof result.status === 'number' && result.status !== 0) {
+    throw new Error(`\`${npmCommand} install -g ${target}\` exited with status ${result.status}.`);
+  }
+
+  if (typeof result.signal === 'string') {
+    throw new Error(`\`${npmCommand} install -g ${target}\` was terminated by ${result.signal}.`);
+  }
+
+  if (latestVersion) {
+    logger.log(`Overlord CLI updated to v${latestVersion}.`);
+  } else {
+    logger.log('Overlord CLI update complete. Run `ovld version` to confirm the installed version.');
+  }
+
+  return { alreadyLatest: false, currentVersion, latestVersion, result };
+}

package/bin/_cli/index.mjs

@@ -2,6 +2,7 @@
 
 import { runAttachCommand } from './attach.mjs';
 import { runAuthCommand } from './auth.mjs';
+import { checkForCliUpdate, printCliUpdateNotice, runCliUpdateCommand } from './cli-update.mjs';
 import { runLauncherCommand } from './launcher.mjs';
 import { runProtocolCommand } from './protocol.mjs';
 import { runDoctorCommand, runSetupCommand } from './setup.mjs';
@@ -9,6 +10,18 @@ import { runTicketCommand } from './ticket.mjs';
 import { runTicketsCommand } from './tickets.mjs';
 import { runVersionCommand } from './version.mjs';
 
+const MIN_NODE_MAJOR = 20;
+
+function assertSupportedNodeVersion() {
+  const major = Number.parseInt(process.versions.node.split('.')[0] ?? '', 10);
+  if (Number.isNaN(major) || major < MIN_NODE_MAJOR) {
+    throw new Error(
+      `Overlord CLI requires Node.js ${MIN_NODE_MAJOR} or newer. Found ${process.version}.\n` +
+      `Update Node before running \`ovld\`. If you installed the desktop wrapper, you can also point it at a newer runtime with \`OVLD_NODE_BIN=/path/to/node\`.`
+    );
+  }
+}
+
 function printHelp(primaryCommand) {
   console.log(`Overlord CLI
 
@@ -26,6 +39,7 @@ Usage:
   ${primaryCommand} restart <agent>            Resume an agent session
   ${primaryCommand} context                    Print ticket context (requires TICKET_ID)
   ${primaryCommand} setup <agent|all>          Install Overlord agent connector
+  ${primaryCommand} update                    Install the latest CLI version from npm
   ${primaryCommand} doctor                     Validate installed agent connectors and check for CLI updates
   ${primaryCommand} version                    Show the installed CLI version
   ${primaryCommand} help                       Show this help message
@@ -52,7 +66,17 @@ Run a subcommand with --help for more detail.
 }
 
 export async function runCli({ primaryCommand }) {
+  assertSupportedNodeVersion();
   const [command, ...rest] = process.argv.slice(2);
+  const shouldCheckForUpdate =
+    Boolean(process.stdout.isTTY || process.stderr.isTTY) &&
+    command !== 'doctor' &&
+    command !== 'update';
+  const latestCliVersion = shouldCheckForUpdate ? await checkForCliUpdate() : null;
+
+  if (latestCliVersion && command !== 'doctor' && command !== 'update') {
+    printCliUpdateNotice(latestCliVersion);
+  }
 
   if (!command || command === 'help' || command === '--help' || command === '-h') {
     printHelp(primaryCommand);
@@ -106,8 +130,18 @@ export async function runCli({ primaryCommand }) {
     return;
   }
 
+  if (command === 'update') {
+    if (rest[0] === '--help' || rest[0] === '-h' || rest[0] === 'help') {
+      console.log(`Usage:
+  ${primaryCommand} update   Install the latest CLI version from npm`);
+      return;
+    }
+    await runCliUpdateCommand();
+    return;
+  }
+
   if (command === 'doctor') {
-    await runDoctorCommand();
+    await runDoctorCommand({ latestCliVersion });
     return;
   }
 

package/bin/_cli/setup.mjs

@@ -12,6 +12,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { checkForCliUpdate, getCurrentCliVersion, printCliUpdateNotice } from './cli-update.mjs';
 
 const BUNDLE_VERSION = '1.8.0';
 const MD_MARKER_START = '<!-- overlord:managed:start -->';
@@ -32,6 +33,7 @@ const CODEX_TARGET_RULES = path.join(os.homedir(), '.codex', 'rules', 'default.r
 const CODEX_LEGACY_AGENTS = path.join(os.homedir(), '.codex', 'AGENTS.md');
 const CODEX_RULES_START = '# overlord:permissions:start';
 const CODEX_RULES_END = '# overlord:permissions:end';
+const REQUIRED_NODE_MAJOR = 20;
 
 const supportedAgents = ['claude', 'codex', 'cursor', 'gemini', 'opencode'];
 
@@ -279,11 +281,6 @@ function readJsonFileOrNull(filePath) {
   }
 }
 
-function localCliVersion() {
-  const cliPackage = readJsonFileOrNull(path.resolve(__dirname, '..', '..', 'package.json'));
-  return typeof cliPackage?.version === 'string' ? cliPackage.version : null;
-}
-
 function writeJsonFile(filePath, data) {
   const dir = path.dirname(filePath);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
@@ -482,28 +479,6 @@ function currentContentHashForAgent(agent) {
   );
 }
 
-async function checkForCliUpdate() {
-  const currentVersion = localCliVersion();
-  if (!currentVersion) return null;
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), 2500);
-  try {
-    const response = await fetch('https://registry.npmjs.org/overlord-cli/latest', {
-      signal: controller.signal,
-      headers: { Accept: 'application/json' }
-    });
-    if (!response.ok) return null;
-    const payload = await response.json();
-    const latestVersion = typeof payload?.version === 'string' ? payload.version : null;
-    if (!latestVersion) return null;
-    return latestVersion === currentVersion ? null : latestVersion;
-  } catch {
-    return null;
-  } finally {
-    clearTimeout(timeout);
-  }
-}
-
 function codexSourcePluginDir() {
   if (fs.existsSync(PACKAGE_PLUGIN_DIR)) return PACKAGE_PLUGIN_DIR;
   if (fs.existsSync(REPO_PLUGIN_DIR)) return REPO_PLUGIN_DIR;
@@ -971,6 +946,10 @@ function doctorAgent(agent) {
   return true;
 }
 
+function currentNodeMajor() {
+  return Number.parseInt(process.versions.node.split('.')[0] ?? '', 10);
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -1030,22 +1009,31 @@ export async function runSetupCommand(args) {
   }
 }
 
-export async function runDoctorCommand() {
+export async function runDoctorCommand({ latestCliVersion = null } = {}) {
   console.log('Overlord agent bundle status:\n');
   let allOk = true;
+  const nodeMajor = currentNodeMajor();
+  if (Number.isNaN(nodeMajor) || nodeMajor < REQUIRED_NODE_MAJOR) {
+    console.log(
+      `  ✗ node: unsupported runtime (${process.version}; requires Node.js ${REQUIRED_NODE_MAJOR}+)`
+    );
+    allOk = false;
+  } else {
+    console.log(`  ✓ node: ${process.version}`);
+  }
+  console.log();
   for (const agent of supportedAgents) {
     if (!doctorAgent(agent)) allOk = false;
   }
-  const latestCliVersion = await checkForCliUpdate();
+  const updateVersion = latestCliVersion ?? (await checkForCliUpdate());
   console.log();
   if (allOk) {
     console.log('All bundles are up to date.');
   } else {
     console.log('Run `ovld setup <agent>` or `ovld setup all` to install/repair.');
   }
-  if (latestCliVersion) {
+  if (updateVersion) {
     console.log();
-    console.log(`CLI update available: ${latestCliVersion}`);
-    console.log('Run `npm install -g overlord-cli@latest` to update.');
+    printCliUpdateNotice(updateVersion, { currentVersion: getCurrentCliVersion(), stream: process.stdout });
   }
 }

package/bin/_cli/version.mjs

@@ -1,10 +1,7 @@
 #!/usr/bin/env node
 
-import { createRequire } from 'node:module';
-
-const require = createRequire(import.meta.url);
-const { version } = require('../../package.json');
+import { getCurrentCliVersion } from './cli-update.mjs';
 
 export function runVersionCommand() {
-  console.log(`Overlord CLI ${version}`);
+  console.log(`Overlord CLI ${getCurrentCliVersion()}`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord-cli",
-  "version": "3.20.0",
+  "version": "3.22.0",
   "description": "Overlord CLI — launch AI agents on tickets from anywhere",
   "type": "module",
   "bin": {
@@ -15,7 +15,7 @@
     "plugins/"
   ],
   "engines": {
-    "node": ">=24"
+    "node": ">=20"
   },
   "keywords": [
     "overlord",