overlord-cli 5.0.0 → 5.1.1

package/README.md

@@ -25,6 +25,14 @@ overlord help
 The CLI exposes the same command set under both names.
 `ovld auth login` opens a browser when possible and also prints a verification URL/code so login can be completed from another machine over SSH.
 
+Desktop-installed wrappers default `OVERLORD_URL` to `https://www.ovld.ai` unless you override it explicitly.
+For local dev against the web app on port 3000, export the override before running auth or protocol commands:
+
+```bash
+export OVERLORD_URL=http://localhost:3000
+ovld auth login
+```
+
 Common commands:
 
 ```bash

package/bin/_cli/auth.mjs

@@ -144,6 +144,17 @@ function snippet(value, max = 180) {
   return normalized.length <= max ? normalized : `${normalized.slice(0, max)}...`;
 }
 
+function describeNetworkError(error, context) {
+  const cause = error?.cause;
+  const details = [cause?.code, cause?.message].filter(Boolean).join(': ');
+  if (details) {
+    return new Error(`${context}: ${details}`);
+  }
+
+  const message = error instanceof Error ? error.message : String(error);
+  return new Error(`${context}: ${message}`);
+}
+
 async function readJsonOrThrow(res, context, baseUrl) {
   const contentType = res.headers.get('content-type') ?? '';
   const bodyText = await res.text();
@@ -165,9 +176,14 @@ async function readJsonOrThrow(res, context, baseUrl) {
 }
 
 async function fetchAuthConfig(platformUrl, localSecret) {
-  const res = await fetch(`${platformUrl}/api/auth/config`, {
-    headers: buildAuthHeaders('', localSecret)
-  });
+  let res;
+  try {
+    res = await fetch(`${platformUrl}/api/auth/config`, {
+      headers: buildAuthHeaders('', localSecret)
+    });
+  } catch (error) {
+    throw describeNetworkError(error, `Failed to fetch auth config from ${platformUrl}`);
+  }
   if (!res.ok) {
     throw new Error(
       `Failed to fetch auth config (${res.status}). Check that Overlord is running at ${platformUrl}.`
@@ -181,10 +197,18 @@ async function fetchAuthConfig(platformUrl, localSecret) {
 }
 
 async function requestDeviceAuthorization(platformUrl, localSecret) {
-  const res = await fetch(`${platformUrl}/api/auth/device/request`, {
-    method: 'POST',
-    headers: buildAuthHeaders('', localSecret)
-  });
+  let res;
+  try {
+    res = await fetch(`${platformUrl}/api/auth/device/request`, {
+      method: 'POST',
+      headers: buildAuthHeaders('', localSecret)
+    });
+  } catch (error) {
+    throw describeNetworkError(
+      error,
+      `Device authorization request failed for ${platformUrl}`
+    );
+  }
 
   if (!res.ok) {
     const text = await res.text();
@@ -195,14 +219,22 @@ async function requestDeviceAuthorization(platformUrl, localSecret) {
 }
 
 async function pollDeviceAuthorization(platformUrl, deviceCode, localSecret) {
-  const res = await fetch(`${platformUrl}/api/auth/device/poll`, {
-    method: 'POST',
-    headers: {
-      ...buildAuthHeaders('', localSecret),
-      'Content-Type': 'application/json'
-    },
-    body: JSON.stringify({ device_code: deviceCode })
-  });
+  let res;
+  try {
+    res = await fetch(`${platformUrl}/api/auth/device/poll`, {
+      method: 'POST',
+      headers: {
+        ...buildAuthHeaders('', localSecret),
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({ device_code: deviceCode })
+    });
+  } catch (error) {
+    throw describeNetworkError(
+      error,
+      `Device authorization poll failed for ${platformUrl}`
+    );
+  }
 
   const body = await readJsonOrThrow(res, 'Device authorization poll', platformUrl);
 
@@ -220,17 +252,25 @@ function sleep(ms) {
 }
 
 async function exchangeCodeForSupabaseTokens(supabaseUrl, clientId, code, codeVerifier, redirectUri) {
-  const res = await fetch(`${supabaseUrl}/auth/v1/oauth/token`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-    body: new URLSearchParams({
-      grant_type: 'authorization_code',
-      code,
-      client_id: clientId,
-      redirect_uri: redirectUri,
-      code_verifier: codeVerifier
-    })
-  });
+  let res;
+  try {
+    res = await fetch(`${supabaseUrl}/auth/v1/oauth/token`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        grant_type: 'authorization_code',
+        code,
+        client_id: clientId,
+        redirect_uri: redirectUri,
+        code_verifier: codeVerifier
+      })
+    });
+  } catch (error) {
+    throw describeNetworkError(
+      error,
+      `Token exchange failed for ${new URL(supabaseUrl).host}`
+    );
+  }
 
   if (!res.ok) {
     const text = await res.text();
@@ -474,8 +514,8 @@ async function promptForOrganization(organizations, preselectedId = null) {
 // Public auth commands
 // ---------------------------------------------------------------------------
 
-export function resolveLoginPlatformUrl(runtime = null) {
-  return process.env.OVERLORD_URL ?? runtime?.platform_url ?? getDefaultOverlordUrl();
+export function resolveLoginPlatformUrl(runtime = null, storedPlatformUrl = null) {
+  return process.env.OVERLORD_URL ?? storedPlatformUrl ?? runtime?.platform_url ?? getDefaultOverlordUrl();
 }
 
 function parseOrganizationFlag(args) {
@@ -491,7 +531,8 @@ function parseOrganizationFlag(args) {
 
 export async function authLogin(args = []) {
   const preselectedOrganizationId = parseOrganizationFlag(args);
-  const platformUrl = resolveLoginPlatformUrl();
+  const storedCredentials = loadCredentials();
+  const platformUrl = resolveLoginPlatformUrl(null, storedCredentials?.platform_url ?? null);
   const runtime = loadRuntime(platformUrl);
   const localSecret = runtime?.local_secret ?? process.env.OVERLORD_LOCAL_SECRET ?? '';
 

package/bin/_cli/credentials.mjs

@@ -9,6 +9,7 @@ import { fileURLToPath } from 'node:url';
 
 const CREDENTIALS_DIR = path.join(os.homedir(), '.ovld');
 const CLI_CREDENTIALS_FILE = path.join(CREDENTIALS_DIR, 'credentials.cli.json');
+const DESKTOP_CREDENTIALS_FILE = path.join(CREDENTIALS_DIR, 'credentials.desktop.json');
 const LEGACY_CREDENTIALS_FILE = path.join(CREDENTIALS_DIR, 'credentials.json');
 const LEGACY_ELECTRON_CREDENTIALS_FILE = path.join(CREDENTIALS_DIR, 'electron-credentials.json');
 const LEGACY_MIGRATION_MARKER = path.join(CREDENTIALS_DIR, '.cli-migrated');
@@ -24,7 +25,8 @@ const LOCAL_SECRET_HEADER = 'X-Overlord-Local-Secret';
  *   refresh_token?: string,
  *   organization_id?: number | null,
  *   platform_url: string,
- *   user_email?: string
+ *   user_email?: string,
+ *   updated_at?: string
  * }} Credentials
  */
 
@@ -93,6 +95,9 @@ function parseStoredCredentialsData(parsed, { requireAuthData = false } = {}) {
     ...(organizationId ? { organization_id: organizationId } : {}),
     ...(typeof parsed.user_email === 'string' && parsed.user_email.trim()
       ? { user_email: parsed.user_email.trim() }
+      : {}),
+    ...(typeof parsed.updated_at === 'string' && parsed.updated_at.trim()
+      ? { updated_at: parsed.updated_at.trim() }
       : {})
   };
 }
@@ -112,7 +117,8 @@ function normalizeCredentialsForSave(data) {
       ? { access_token_expires_at: parsed.access_token_expires_at }
       : {}),
     ...(parsed.organization_id ? { organization_id: parsed.organization_id } : {}),
-    ...(parsed.user_email ? { user_email: parsed.user_email } : {})
+    ...(parsed.user_email ? { user_email: parsed.user_email } : {}),
+    ...(parsed.updated_at ? { updated_at: parsed.updated_at } : {})
   };
 }
 
@@ -140,13 +146,57 @@ function migrateLegacyCredentials() {
   return source;
 }
 
+function resolveAccessTokenExpiry(credentials) {
+  if (!credentials?.access_token) return null;
+  if (credentials.access_token_expires_at) {
+    const parsed = Date.parse(credentials.access_token_expires_at);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  const jwtExp = decodeJwtExpiry(credentials.access_token);
+  return jwtExp ? jwtExp * 1000 : null;
+}
+
+function isAccessTokenFresh(credentials) {
+  const expiresAt = resolveAccessTokenExpiry(credentials);
+  if (expiresAt === null) return false;
+  return expiresAt - Date.now() > 60_000;
+}
+
+function credentialsUpdatedAt(credentials) {
+  const parsed = Date.parse(credentials?.updated_at ?? '');
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+function selectStoredCredentials() {
+  const candidates = [
+    {
+      source: 'credentials.cli.json',
+      credentials: parseStoredCredentialsData(readJsonFile(CLI_CREDENTIALS_FILE), {
+        requireAuthData: true
+      })
+    },
+    {
+      source: 'credentials.desktop.json',
+      credentials: parseStoredCredentialsData(readJsonFile(DESKTOP_CREDENTIALS_FILE), {
+        requireAuthData: true
+      })
+    }
+  ].filter(candidate => candidate.credentials?.refresh_token);
+
+  if (candidates.length === 0) return null;
+
+  const fresh = candidates.filter(candidate => isAccessTokenFresh(candidate.credentials));
+  const pool = fresh.length > 0 ? fresh : candidates;
+  return pool.sort(
+    (left, right) =>
+      credentialsUpdatedAt(right.credentials) - credentialsUpdatedAt(left.credentials)
+  )[0];
+}
+
 /** @returns {Credentials | null} */
 export function loadCredentials() {
-  const cliCredentials = parseStoredCredentialsData(readJsonFile(CLI_CREDENTIALS_FILE), {
-    requireAuthData: true
-  });
-
-  if (cliCredentials?.refresh_token) return cliCredentials;
+  const selected = selectStoredCredentials();
+  if (selected?.credentials) return selected.credentials;
 
   return migrateLegacyCredentials();
 }
@@ -161,6 +211,16 @@ export function saveCredentials(data) {
   writeJsonFileAtomic(CLI_CREDENTIALS_FILE, { ...credentials, updated_at: new Date().toISOString() });
 }
 
+function saveCredentialsToSource(data, source) {
+  const credentials = normalizeCredentialsForSave(data);
+  if (!credentials) {
+    throw new Error('Cannot save empty Overlord credentials.');
+  }
+
+  const filePath = source === 'credentials.desktop.json' ? DESKTOP_CREDENTIALS_FILE : CLI_CREDENTIALS_FILE;
+  writeJsonFileAtomic(filePath, { ...credentials, updated_at: new Date().toISOString() });
+}
+
 export function clearCredentials() {
   try {
     fs.unlinkSync(CLI_CREDENTIALS_FILE);
@@ -170,10 +230,8 @@ export function clearCredentials() {
 }
 
 function getCredentialFileSource() {
-  const cliCredentials = parseStoredCredentialsData(readJsonFile(CLI_CREDENTIALS_FILE), {
-    requireAuthData: true
-  });
-  if (cliCredentials?.refresh_token) return 'credentials.cli.json';
+  const selected = selectStoredCredentials();
+  if (selected) return selected.source;
 
   if (fileExists(LEGACY_CREDENTIALS_FILE)) {
     const legacyShared = parseStoredCredentialsData(readJsonFile(LEGACY_CREDENTIALS_FILE), {
@@ -338,29 +396,29 @@ function computeAccessTokenExpiry(data) {
   return jwtExp ? new Date(jwtExp * 1000).toISOString() : null;
 }
 
-function resolveAccessTokenExpiry(credentials) {
-  if (!credentials?.access_token) return null;
-  if (credentials.access_token_expires_at) {
-    const parsed = Date.parse(credentials.access_token_expires_at);
-    if (Number.isFinite(parsed)) return parsed;
+function describeNetworkError(error, context) {
+  const cause = error?.cause;
+  const details = [cause?.code, cause?.message].filter(Boolean).join(': ');
+  if (details) {
+    return new Error(`${context}: ${details}`);
   }
-  const jwtExp = decodeJwtExpiry(credentials.access_token);
-  return jwtExp ? jwtExp * 1000 : null;
-}
 
-function isAccessTokenFresh(credentials) {
-  const expiresAt = resolveAccessTokenExpiry(credentials);
-  if (expiresAt === null) return false;
-  return expiresAt - Date.now() > 60_000;
+  const message = error instanceof Error ? error.message : String(error);
+  return new Error(`${context}: ${message}`);
 }
 
 const authConfigCache = new Map();
 
 async function fetchAuthConfig(platformUrl, localSecret) {
   if (authConfigCache.has(platformUrl)) return authConfigCache.get(platformUrl);
-  const res = await fetch(`${platformUrl}/api/auth/config`, {
-    headers: buildAuthHeaders('', localSecret)
-  });
+  let res;
+  try {
+    res = await fetch(`${platformUrl}/api/auth/config`, {
+      headers: buildAuthHeaders('', localSecret)
+    });
+  } catch (error) {
+    throw describeNetworkError(error, `Failed to fetch auth config from ${platformUrl}`);
+  }
   if (!res.ok) {
     throw new Error(`Failed to fetch auth config (${res.status}).`);
   }
@@ -378,15 +436,23 @@ async function refreshOAuthAccessToken(platformUrl, refreshToken, localSecret) {
     throw new Error('OAuth is not configured for Overlord CLI auth.');
   }
 
-  const res = await fetch(`${supabaseUrl}/auth/v1/oauth/token`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-    body: new URLSearchParams({
-      grant_type: 'refresh_token',
-      refresh_token: refreshToken,
-      client_id: clientId
-    })
-  });
+  let res;
+  try {
+    res = await fetch(`${supabaseUrl}/auth/v1/oauth/token`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        grant_type: 'refresh_token',
+        refresh_token: refreshToken,
+        client_id: clientId
+      })
+    });
+  } catch (error) {
+    throw describeNetworkError(
+      error,
+      `OAuth token refresh failed for ${new URL(supabaseUrl).host}`
+    );
+  }
 
   if (!res.ok) {
     const text = await res.text().catch(() => '');
@@ -459,7 +525,8 @@ function isLocalDevCli() {
  * Refreshes OAuth access tokens when possible.
  */
 export async function resolveAuth() {
-  const creds = loadCredentials();
+  const selectedCredentials = selectStoredCredentials();
+  const creds = selectedCredentials?.credentials ?? migrateLegacyCredentials();
   const overlordUrlFromEnv = normalizePlatformUrl(process.env.OVERLORD_URL);
   const overlordUrlFromCreds = normalizeStoredPlatformUrl(creds?.platform_url);
 
@@ -516,11 +583,11 @@ export async function resolveAuth() {
           access_token_expires_at: refreshed.access_token_expires_at,
           refresh_token: refreshed.refresh_token || creds.refresh_token
         };
-        saveCredentials(nextCredentials);
+        saveCredentialsToSource(nextCredentials, selectedCredentials?.source);
       } catch (refreshError) {
-        if (!creds.access_token) throw refreshError;
-        // Transient refresh failure — keep the existing access token and let the server
-        // reject it if it's truly expired/revoked.
+        throw new Error(
+          `Stored Overlord session expired and refresh failed. ${refreshError instanceof Error ? refreshError.message : String(refreshError)} Run \`ovld auth login\` again.`
+        );
       }
     }
 
@@ -584,7 +651,7 @@ export async function getAuthStatus() {
   }
 
   return {
-    isLoggedIn: tokenSource !== 'fallback',
+    isLoggedIn: tokenSource !== 'fallback' && !error,
     platformUrl: resolved.platformUrl,
     platformUrlSource,
     tokenPresent: tokenSource !== 'fallback',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord-cli",
-  "version": "5.0.0",
+  "version": "5.1.1",
   "description": "Overlord CLI — launch AI agents on tickets from anywhere",
   "type": "module",
   "bin": {