@commonlyai/cli 0.1.25 → 0.1.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "license": "Apache-2.0",
   "description": "The Commonly CLI \u2014 connect agents, manage pods, iterate fast",
   "type": "module",

package/src/commands/agent.js

@@ -1344,7 +1344,11 @@ export const performRun = ({
           recordHandledEvent(agentName, event._id);
         }
         try {
-          await client.post(`/api/agents/runtime/events/${event._id}/ack`, { result });
+          const deliveryId = event.payload?.deliveryId;
+          await client.post(`/api/agents/runtime/events/${event._id}/ack`, {
+            result,
+            ...(typeof deliveryId === 'string' && deliveryId ? { deliveryId } : {}),
+          });
         } catch (ackErr) {
           onError?.(new Error(`Ack failed for ${event._id}: ${ackErr.message}`));
         }

package/src/commands/login.js

@@ -6,8 +6,15 @@
  */
 
 import { createInterface } from 'readline';
-import { login as apiLogin } from '../lib/api.js';
+import { hostname } from 'os';
+import { createClient, login as apiLogin } from '../lib/api.js';
 import { saveInstance } from '../lib/config.js';
+import {
+  DeviceLoginCancelledError,
+  DeviceLoginDeniedError,
+  DeviceLoginExpiredError,
+  waitForDeviceAuthorization,
+} from '../lib/device-login.js';
 
 const prompt = (rl, question) => new Promise((resolve) => rl.question(question, resolve));
 
@@ -41,6 +48,7 @@ export const registerLogin = (program) => {
     .description('Authenticate to a Commonly instance')
     .option('--instance <url>', 'Instance URL (default: https://api.commonly.me)')
     .option('--key <name>', 'Config key to save as (default: "default" or "local")')
+    .option('--password', 'Use the legacy email/password prompt instead of device authorization')
     .addHelpText('after', `
 Examples:
   $ commonly login                                                   # production (default key)
@@ -58,26 +66,64 @@ Tokens are stored in ~/.commonly/config.json. Other commands take
       const isLocal = instanceUrl.includes('localhost') || instanceUrl.includes('127.0.0.1');
       const configKey = opts.key || (isLocal ? 'local' : 'default');
 
-      console.log(`Logging in to ${instanceUrl}`);
-
-      const rl = createInterface({ input: process.stdin, output: process.stdout });
-      const email = await prompt(rl, 'Email: ');
-      rl.close();
-
-      const password = await promptSecret('Password: ');
-
       try {
+        if (!opts.password) {
+          const client = createClient({ instance: instanceUrl, token: null });
+          const started = await client.post('/api/auth/device/start', {
+            clientName: 'commonly-cli',
+            clientVersion: program.version(),
+            hostname: hostname(),
+          });
+          const minutes = Math.ceil(started.expiresIn / 60);
+          console.log(`Logging in to ${instanceUrl} as a new device.\n`);
+          console.log(`  Open   ${started.verifyUrl}`);
+          console.log(`  Code   ${started.userCode}`);
+          console.log(`\nWaiting for approval… (expires in ${minutes}:00)  press o to open the browser, q to cancel`);
+          const data = await waitForDeviceAuthorization({
+            client,
+            deviceCode: started.deviceCode,
+            userCode: started.userCode,
+            verifyUrl: started.verifyUrl,
+            interval: started.interval,
+            expiresIn: started.expiresIn,
+            onStatus: (message) => console.log(message),
+          });
+
+          saveInstance({
+            key: configKey,
+            url: instanceUrl,
+            token: data.token,
+            userId: data.userId,
+            username: data.username,
+            tokenType: 'device',
+          });
+          const devicesUrl = new URL('/settings/devices', started.verifyUrl).toString();
+          console.log(`\n✓ Authorized as @${data.username} on ${configKey} (${instanceUrl})`);
+          console.log(`  Token saved to ~/.commonly/config.json · manage devices at ${devicesUrl}`);
+          return;
+        }
+
+        console.log(`Logging in to ${instanceUrl}`);
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const email = await prompt(rl, 'Email: ');
+        rl.close();
+        const password = await promptSecret('Password: ');
         const data = await apiLogin(instanceUrl, email.trim(), password);
         const token = data.token;
         const userId = data.user?._id || data.user?.id;
         const username = data.user?.username;
 
-        saveInstance({ key: configKey, url: instanceUrl, token, userId, username });
+        saveInstance({ key: configKey, url: instanceUrl, token, userId, username, tokenType: 'jwt' });
 
         console.log(`\nLogged in as ${username} (${configKey})`);
         console.log(`Token saved to ~/.commonly/config.json`);
       } catch (err) {
-        console.error(`Login failed: ${err.message}`);
+        const message = err instanceof DeviceLoginExpiredError
+          ? `Code expired after 10 minutes. Run commonly login --instance ${configKey} for a new code.`
+          : err instanceof DeviceLoginCancelledError || err instanceof DeviceLoginDeniedError
+            ? err.message
+            : `Login failed: ${err.message}`;
+        console.error(message);
         process.exit(1);
       }
     });
@@ -97,9 +143,29 @@ export const registerWhoami = (program) => {
         return;
       }
 
-      instances.forEach(({ key, url, username, active, savedAt }) => {
+      instances.forEach(({ key, url, username, active, token, tokenType }) => {
         const marker = active ? '→' : ' ';
-        console.log(`${marker} ${key}  ${username || '?'}@${url}  (saved ${new Date(savedAt).toLocaleDateString()})`);
+        console.log(`${marker} ${key}  ${username || '?'}@${url}  (${formatTokenStatus(token, tokenType, Date.now(), key)})`);
       });
     });
 };
+
+const decodeJwtExpiry = (token) => {
+  if (typeof token !== 'string' || token.split('.').length !== 3) return null;
+  try {
+    const payload = JSON.parse(Buffer.from(token.split('.')[1], 'base64url').toString('utf8'));
+    return typeof payload.exp === 'number' ? payload.exp * 1000 : null;
+  } catch {
+    return null;
+  }
+};
+
+export const formatTokenStatus = (token, tokenType, now = Date.now(), instanceKey = 'default') => {
+  if (tokenType === 'device' || String(token || '').startsWith('cm_')) return 'device token · no expiry';
+  const expiresAt = decodeJwtExpiry(token);
+  if (!expiresAt) return 'session token · expiry unknown';
+  const diff = expiresAt - now;
+  if (diff <= 0) return `expired — commonly login --instance ${instanceKey}`;
+  const hours = Math.max(1, Math.ceil(diff / (60 * 60 * 1000)));
+  return `expires in ${hours}h`;
+};

package/src/lib/api.js

@@ -5,7 +5,7 @@
  * unless overridden. This is the only place that makes HTTP calls.
  */
 
-import { resolveInstanceUrl, getToken } from './config.js';
+import { resolveInstanceUrl, getToken, resolveInstance } from './config.js';
 
 const headers = (token, extra = {}) => ({
   'Content-Type': 'application/json',
@@ -13,12 +13,21 @@ const headers = (token, extra = {}) => ({
   ...extra,
 });
 
-const handleResponse = async (res) => {
+const knownSessionFailure = (body) => [body?.msg, body?.error, body?.message]
+  .some((value) => ['Token is not valid', 'Invalid API token', 'Account no longer exists'].includes(value));
+
+export const sessionExpiredMessage = ({ instanceKey, baseUrl }) => (
+  `Session for ${instanceKey} (${baseUrl}) has expired.\nRun: commonly login --instance ${instanceKey}`
+);
+
+const handleResponse = async (res, session = null) => {
   const text = await res.text();
   let body;
   try { body = JSON.parse(text); } catch { body = { message: text }; }
   if (!res.ok) {
-    const msg = body?.error || body?.message || `HTTP ${res.status}`;
+    const msg = res.status === 401 && session && knownSessionFailure(body)
+      ? sessionExpiredMessage(session)
+      : body?.error || body?.message || body?.msg || `HTTP ${res.status}`;
     const err = new Error(msg);
     err.status = res.status;
     err.body = body;
@@ -27,32 +36,37 @@ const handleResponse = async (res) => {
   return body;
 };
 
-export const createClient = ({ instance = null, token = null } = {}) => {
+export const createClient = ({ instance = null, token = undefined } = {}) => {
   const baseUrl = resolveInstanceUrl(instance);
-  const authToken = token || getToken(instance);
+  const resolved = resolveInstance(instance);
+  const authToken = token === undefined ? getToken(instance) : token;
+  const session = {
+    instanceKey: resolved?.key || (typeof instance === 'string' && instance && !/^https?:\/\//i.test(instance) ? instance : 'default'),
+    baseUrl,
+  };
 
   const get = (path, params = {}) => {
     const url = new URL(`${baseUrl}${path}`);
     Object.entries(params).forEach(([k, v]) => v != null && url.searchParams.set(k, v));
-    return fetch(url.toString(), { headers: headers(authToken) }).then(handleResponse);
+    return fetch(url.toString(), { headers: headers(authToken) }).then((res) => handleResponse(res, session));
   };
 
   const post = (path, body = {}) => fetch(`${baseUrl}${path}`, {
     method: 'POST',
     headers: headers(authToken),
     body: JSON.stringify(body),
-  }).then(handleResponse);
+  }).then((res) => handleResponse(res, session));
 
   const patch = (path, body = {}) => fetch(`${baseUrl}${path}`, {
     method: 'PATCH',
     headers: headers(authToken),
     body: JSON.stringify(body),
-  }).then(handleResponse);
+  }).then((res) => handleResponse(res, session));
 
   const del = (path) => fetch(`${baseUrl}${path}`, {
     method: 'DELETE',
     headers: headers(authToken),
-  }).then(handleResponse);
+  }).then((res) => handleResponse(res, session));
 
   // Multipart upload via native FormData/Blob (Node 18+) — no runtime deps.
   // Content-Type is deliberately NOT set: fetch writes the multipart boundary.
@@ -72,7 +86,7 @@ export const createClient = ({ instance = null, token = null } = {}) => {
       method: 'POST',
       headers: authToken ? { Authorization: `Bearer ${authToken}` } : {},
       body: form,
-    }).then(handleResponse);
+    }).then((res) => handleResponse(res, session));
   };
 
   return {

package/src/lib/config.js

@@ -107,13 +107,16 @@ export const resolveInstanceUrl = (instanceArg = null) => {
   return DEFAULT_INSTANCE_URL;
 };
 
-export const saveInstance = ({ key = 'default', url, token, userId, username }) => {
+export const saveInstance = ({ key = 'default', url, token, userId, username, tokenType = null }) => {
   const config = read();
   config.instances[key] = {
     url: url.replace(/\/$/, ''),
     token,
     userId,
     username,
+    // Device bearers are long-lived until revoked. Preserve the explicit kind
+    // so `whoami` can say that without guessing from a future token format.
+    ...(tokenType ? { tokenType } : {}),
     savedAt: new Date().toISOString(),
   };
   config.active = key;

package/src/lib/device-login.js

@@ -0,0 +1,126 @@
+/**
+ * RFC 8628-shaped device-code interaction for `commonly login`.
+ *
+ * The browser owns password/OAuth; the terminal only ever receives the
+ * resulting per-device bearer once from /device/poll. This module keeps the
+ * timing and terminal-key behaviour testable without a live TTY.
+ */
+import { execFile as nodeExecFile } from 'child_process';
+import { platform } from 'os';
+import { emitKeypressEvents } from 'readline';
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export class DeviceLoginCancelledError extends Error {
+  constructor() {
+    super('Login cancelled.');
+    this.name = 'DeviceLoginCancelledError';
+  }
+}
+
+export class DeviceLoginDeniedError extends Error {
+  constructor() {
+    super('Denied in the browser. Nothing was saved.');
+    this.name = 'DeviceLoginDeniedError';
+  }
+}
+
+export class DeviceLoginExpiredError extends Error {
+  constructor() {
+    super('Device authorization code expired.');
+    this.name = 'DeviceLoginExpiredError';
+  }
+}
+
+const safeBrowserUrl = (value) => {
+  const url = new URL(value);
+  if (!['http:', 'https:'].includes(url.protocol)) {
+    throw new Error('Device authorization URL must use HTTP or HTTPS.');
+  }
+  return url.toString();
+};
+
+export const openBrowser = (url, execFile = nodeExecFile, currentPlatform = platform()) => {
+  const browserUrl = safeBrowserUrl(url);
+  // `cmd /c start <url>` routes a server-supplied URL through a shell. Use a
+  // direct executable on Windows just as we do on macOS/Linux, so `o` cannot
+  // turn a malicious verifyUrl into a second command.
+  const command = currentPlatform === 'darwin' ? 'open' : currentPlatform === 'win32' ? 'rundll32' : 'xdg-open';
+  const args = currentPlatform === 'win32'
+    ? ['url.dll,FileProtocolHandler', browserUrl]
+    : [browserUrl];
+  return new Promise((resolve) => {
+    execFile(command, args, () => resolve());
+  });
+};
+
+export const waitForDeviceAuthorization = async ({
+  client,
+  deviceCode,
+  userCode,
+  verifyUrl,
+  interval = 5,
+  expiresIn = 600,
+  stdin = process.stdin,
+  wait = sleep,
+  onOpen = openBrowser,
+  onStatus = () => undefined,
+  now = () => Date.now(),
+}) => {
+  const authorizeUrl = `${verifyUrl}?code=${encodeURIComponent(userCode)}`;
+  let cancelled = false;
+  let signalCancellation = () => {};
+  const cancellation = new Promise((resolve) => {
+    signalCancellation = resolve;
+  });
+  let currentInterval = Math.max(Number(interval) || 5, 1);
+  const deadline = now() + Math.max(Number(expiresIn) || 600, 1) * 1000;
+  const isTty = Boolean(stdin?.isTTY && typeof stdin.setRawMode === 'function');
+
+  const onKeypress = (value, key = {}) => {
+    if (key?.ctrl && key.name === 'c') {
+      cancelled = true;
+      signalCancellation();
+    }
+    if (value === 'q') {
+      cancelled = true;
+      signalCancellation();
+    }
+    if (value === 'o') void onOpen(authorizeUrl);
+  };
+
+  if (stdin?.on) {
+    emitKeypressEvents(stdin);
+    if (isTty) stdin.setRawMode(true);
+    stdin.on('keypress', onKeypress);
+  }
+
+  try {
+    while (now() < deadline) {
+      if (cancelled) throw new DeviceLoginCancelledError();
+      let result;
+      try {
+        result = await client.post('/api/auth/device/poll', { deviceCode });
+      } catch {
+        throw new Error('Unable to complete device authorization. Try again.');
+      }
+      if (result?.status === 'authorized' && result.token) return result;
+      if (result?.status === 'denied') throw new DeviceLoginDeniedError();
+      if (result?.status === 'expired') throw new DeviceLoginExpiredError();
+      if (result?.status === 'slow_down') {
+        currentInterval *= 2;
+        onStatus('Waiting for browser approval (slowing down)…');
+      } else if (result?.status !== 'authorization_pending') {
+        throw new DeviceLoginExpiredError();
+      }
+      await Promise.race([
+        wait(currentInterval * 1000),
+        cancellation,
+      ]);
+    }
+    throw new DeviceLoginExpiredError();
+  } finally {
+    if (stdin?.removeListener) stdin.removeListener('keypress', onKeypress);
+    if (isTty) stdin.setRawMode(false);
+  }
+};

package/src/lib/poller.js

@@ -47,8 +47,10 @@ export const startPoller = ({
 
         // Acknowledge the event
         try {
+          const deliveryId = event.payload?.deliveryId;
           await client.post(`/api/agents/runtime/events/${event._id}/ack`, {
             result,
+            ...(typeof deliveryId === 'string' && deliveryId ? { deliveryId } : {}),
           });
         } catch (ackErr) {
           // Non-fatal — event will be retried