overlord-cli 3.21.0 → 3.22.0

package/README.md

@@ -13,6 +13,7 @@ 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
 
@@ -31,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
@@ -54,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';
@@ -38,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
@@ -66,6 +68,15 @@ 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);
@@ -119,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 -->';
@@ -280,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 });
@@ -483,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;
@@ -1035,7 +1009,7 @@ 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();
@@ -1051,18 +1025,15 @@ export async function runDoctorCommand() {
   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(
-      `Update with Node.js ${REQUIRED_NODE_MAJOR}+ and reinstall the installed CLI wrapper if needed.`
-    );
+    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.21.0",
+  "version": "3.22.0",
   "description": "Overlord CLI — launch AI agents on tickets from anywhere",
   "type": "module",
   "bin": {