acuvo-code 0.2.1 → 0.3.1

package/lib/device-login.mjs

@@ -0,0 +1,208 @@
+/**
+ * ── ⭐⭐⭐ `acuvo` LOGS ITSELF IN ────────────────────────────────────────────
+ *
+ * Roman, 2026-08-22: *"paying users should be able to type acuvo into a terminal
+ * and then it works... like how I pay and I can type claude and it works, but it
+ * probably works for anyone, but they have to log in."*
+ *
+ * RFC 8628 device-authorization grant, client half. Replaces the five-step
+ * manual path (sign in → find Settings → create key → copy → `acuvo --login
+ * xxi_live_…`) with: run `acuvo`, approve in the browser, done.
+ *
+ * ⚠️ EVERY PIECE OF IO IS INJECTED — `fetchImpl`, `openBrowser`, `sleep`, `now`.
+ * Not for purity's sake: this module's whole job is a timing loop against a
+ * remote service, and a version that can only be tested by actually waiting two
+ * seconds a tick against production is a version nobody tests. The CLI's success
+ * path had zero coverage once before, for exactly this reason.
+ */
+
+import { DEFAULT_GATEWAY_URL } from './account.mjs';
+
+/**
+ * The gateway constant points at the completions endpoint; the device endpoints
+ * are siblings of it. Derived rather than duplicated so a self-hosted or staging
+ * gateway moves all three together.
+ */
+export function deviceEndpoints(gatewayUrl = DEFAULT_GATEWAY_URL) {
+  const base = String(gatewayUrl).replace(/\/api\/cli\/v1\/chat\/completions\/?$/, '');
+  return {
+    code: `${base}/api/cli/v1/device/code`,
+    token: `${base}/api/cli/v1/device/token`,
+  };
+}
+
+/** Ask for a device code. Returns the server's payload, or throws a readable error. */
+export async function requestDeviceCode(gatewayUrl = DEFAULT_GATEWAY_URL, { fetchImpl = fetch, timeoutMs = 15000 } = {}) {
+  const { code } = deviceEndpoints(gatewayUrl);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let res;
+  try {
+    res = await fetchImpl(code, { method: 'POST', signal: controller.signal });
+  } catch (e) {
+    throw new Error(`could not reach Acuvo to start a login (${e?.message ?? e}). Check your connection.`);
+  } finally {
+    clearTimeout(timer);
+  }
+
+  /**
+   * ⚠️ A NON-JSON BODY IS THE SYMPTOM THAT MATTERS HERE. If the middleware ever
+   * stops exempting this path, the response is a 307 to an HTML login page —
+   * and "unexpected token < in JSON" tells the user nothing they can act on.
+   * That exact failure has shipped on this path before.
+   */
+  const text = await res.text();
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    throw new Error(
+      `Acuvo returned a ${res.status} that was not JSON — the login endpoint is not reachable. ` +
+      `This is a server-side problem, not something you can fix locally.`,
+    );
+  }
+  if (!res.ok) throw new Error(json?.error ? `login could not start: ${json.error}` : `login could not start (HTTP ${res.status})`);
+  if (!json?.device_code || !json?.user_code) throw new Error('Acuvo did not return a login code.');
+  return json;
+}
+
+/** RFC 8628 statuses that mean "keep waiting" rather than "stop". */
+const PENDING = new Set(['authorization_pending', 'slow_down']);
+
+/**
+ * Poll until the human approves, denies, or the code expires.
+ *
+ * @returns {Promise<{api_key: string, tenant_id: string|null}>}
+ */
+export async function pollForKey(
+  gatewayUrl,
+  deviceCode,
+  {
+    intervalMs = 2000,
+    expiresInMs = 600000,
+    fetchImpl = fetch,
+    sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+    now = () => Date.now(),
+    onTick = () => {},
+  } = {},
+) {
+  const { token } = deviceEndpoints(gatewayUrl);
+  const deadline = now() + expiresInMs;
+  let wait = intervalMs;
+
+  while (now() < deadline) {
+    await sleep(wait);
+    onTick();
+
+    let res;
+    let json = {};
+    try {
+      res = await fetchImpl(token, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ device_code: deviceCode }),
+      });
+      json = await res.json().catch(() => ({}));
+    } catch {
+      /**
+       * ⚠️ A DROPPED POLL IS NOT A FAILED LOGIN. Wifi blips mid-approval are
+       * ordinary; aborting here would throw away an approval the user already
+       * gave. Keep waiting until the code itself expires.
+       */
+      continue;
+    }
+
+    if (res.ok && json.api_key) return { api_key: json.api_key, tenant_id: json.tenant_id ?? null };
+
+    const err = String(json.error ?? '');
+    if (err === 'access_denied') throw new Error('login was denied in the browser.');
+    if (err === 'expired_token') throw new Error('the login code expired. Run `acuvo --login` again.');
+    if (err === 'already_claimed') throw new Error('that login code was already used. Run `acuvo --login` again.');
+    if (err === 'invalid_grant') throw new Error('that login code is not recognised. Run `acuvo --login` again.');
+
+    // `slow_down` is the server asking for room; honouring it is the difference
+    // between a polite client and one that gets rate-limited mid-login.
+    if (err === 'slow_down') wait = Math.min(wait * 2, 10000);
+    else if (!PENDING.has(err) && !res.ok && res.status >= 500) wait = Math.min(wait * 2, 10000);
+  }
+
+  throw new Error('the login code expired before it was approved. Run `acuvo --login` again.');
+}
+
+/**
+ * Best-effort browser open. NEVER throws and never blocks the flow.
+ *
+ * ⚠️ THE URL IS ALWAYS PRINTED TOO, and that is not redundancy — this runs over
+ * SSH, in containers, and in terminals with no desktop session, where opening a
+ * browser is impossible by definition. A flow that depends on the open
+ * succeeding is a flow that strands every remote user.
+ */
+export function openBrowser(url, { platform = process.platform, spawn } = {}) {
+  if (!spawn) return false;
+  const cmd = platform === 'win32' ? 'cmd' : platform === 'darwin' ? 'open' : 'xdg-open';
+  const args = platform === 'win32' ? ['/c', 'start', '', url] : [url];
+  try {
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+    child.unref?.();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * ── ⭐⭐⭐ ONE LOGIN FLOW, TWO DOORS ─────────────────────────────────────────
+ *
+ * Drives the whole grant: ask for a code, show it, open a browser, wait, save.
+ * Reached from `acuvo --login` AND from a bare `acuvo` that finds no
+ * credential — the second of which is what makes typing `acuvo` enough, the
+ * way typing `claude` is.
+ *
+ * ⚠️ IT LIVES HERE, NOT IN `bin/`. The first version was written inline inside
+ * the `--login` branch and was needed by a second caller within the hour. A fix
+ * that lives inside one caller is a fix for one caller — this codebase has paid
+ * for that three times today alone. Extracted before the second copy existed
+ * rather than after.
+ *
+ * ⚠️ IT THROWS RATHER THAN EXITING. `bin/` owns exit codes and phrasing; a
+ * library that calls `process.exit` cannot be tested and cannot be reused.
+ *
+ * @returns {Promise<{token: string, restricted: boolean|null, userCode: string}>}
+ */
+export async function runDeviceLogin({
+  gatewayUrl,
+  write = (s) => process.stderr.write(s),
+  spawn,
+  requestCode = requestDeviceCode,
+  poll = pollForKey,
+  open = openBrowser,
+  saveAccount,
+} = {}) {
+  const start = await requestCode(gatewayUrl);
+  const url = start.verification_uri_complete || start.verification_uri;
+
+  /**
+   * ⚠️ THE URL AND CODE ARE PRINTED WHETHER OR NOT THE BROWSER OPENS. This runs
+   * over SSH, in containers, and in terminals with no desktop session, where
+   * opening a browser is impossible by definition — a flow that assumes the
+   * open worked strands every remote user.
+   */
+  write(`\nYour code:  ${start.user_code}\n\n`);
+  const opened = open(url, { spawn });
+  write(opened
+    ? `Opened your browser to approve it. If nothing appeared:\n  ${url}\n\n`
+    : `Open this to approve it:\n  ${url}\n\n`);
+  write('Waiting for approval… (Ctrl-C to cancel)\n');
+
+  const granted = await poll(gatewayUrl, start.device_code, {
+    intervalMs: (start.interval ?? 2) * 1000,
+    expiresInMs: (start.expires_in ?? 600) * 1000,
+  });
+
+  const saved = saveAccount ? saveAccount(granted.api_key) : null;
+  return {
+    token: granted.api_key,
+    restricted: saved && typeof saved.restricted === 'boolean' ? saved.restricted : null,
+    userCode: start.user_code,
+  };
+}

package/lib/self-update.mjs

@@ -0,0 +1,174 @@
+/**
+ * ── ⭐⭐⭐ USERS GET UPDATES WITHOUT BEING ASKED TO ──────────────────────────
+ *
+ * Roman, 2026-08-22: *"how do we do self updates so all users get updates as
+ * soon as we do it, and we just advertise the new npm version instead of having
+ * users constantly download new versions, like Claude."*
+ *
+ * npm is IMMUTABLE — a published version can never be changed — so shipping a
+ * fix means publishing a new version, and without this module every user sits on
+ * whatever they first installed, forever. A bug we fixed in an hour would live
+ * on their machine for months.
+ *
+ * ── ⚠️⚠️ WHAT THIS MUST NEVER DO, WHICH IS MOST OF THE DESIGN ───────────────
+ *
+ * It must never block a run, never throw, never slow the first token, and never
+ * swap files underneath a session that is already executing. An update mechanism
+ * that can break the tool is worse than no update mechanism: the failure lands
+ * on someone who was in the middle of real work and did not ask for any of it.
+ *
+ * So: the check is THROTTLED to once a day against a cache, the install runs
+ * DETACHED after the decision, and the new version applies on the NEXT run —
+ * never the current one.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { accountDir } from './account.mjs';
+
+export const PACKAGE_NAME = 'acuvo-code';
+
+/** How long between registry checks. A day is plenty and keeps npm quiet. */
+export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Compare two semver-ish strings.
+ *
+ * ⚠️ NUMERIC PER SEGMENT, NOT LEXICOGRAPHIC. `'0.10.0' > '0.9.0'` is TRUE
+ * numerically and FALSE as strings — so a string compare stops offering updates
+ * exactly when the minor version reaches 10, and does it silently.
+ *
+ * @returns 1 if a > b, -1 if a < b, 0 if equal
+ */
+export function compareVersions(a, b) {
+  const parse = (v) =>
+    String(v ?? '')
+      .trim()
+      .replace(/^v/, '')
+      // A prerelease suffix (`1.0.0-beta.1`) is dropped rather than ranked. We
+      // do not publish them, and inventing an ordering for something that does
+      // not exist is how you offer people a "newer" version that is older.
+      .split('-')[0]
+      .split('.')
+      .map((n) => Number.parseInt(n, 10) || 0);
+  const [x, y] = [parse(a), parse(b)];
+  for (let i = 0; i < Math.max(x.length, y.length); i += 1) {
+    const d = (x[i] ?? 0) - (y[i] ?? 0);
+    if (d !== 0) return d > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+export function updateCachePath(env = process.env) {
+  return join(accountDir(env), 'update-check.json');
+}
+
+function readCache(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(path, value) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value), 'utf8');
+  } catch {
+    // A read-only home is not a reason to fail a run. Worst case we check again
+    // next time, which costs one HTTP request.
+  }
+}
+
+/**
+ * Is there a newer published version?
+ *
+ * @returns {Promise<{latest: string, isNewer: boolean, checked: boolean}>}
+ */
+export async function checkForUpdate({
+  current,
+  fetchImpl = fetch,
+  now = () => Date.now(),
+  cachePath = updateCachePath(),
+  intervalMs = CHECK_INTERVAL_MS,
+  timeoutMs = 3000,
+  force = false,
+} = {}) {
+  const cached = readCache(cachePath);
+  if (!force && cached && now() - (cached.at ?? 0) < intervalMs) {
+    return { latest: cached.latest ?? current, isNewer: compareVersions(cached.latest, current) > 0, checked: false };
+  }
+
+  let latest = current;
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    /**
+     * ⚠️ THE `latest` ENDPOINT, NOT THE FULL PACKUMENT. The full document for
+     * this package is megabytes of version history; this one is a few hundred
+     * bytes. On a slow connection that difference is the whole reason the check
+     * finishes inside its timeout instead of being abandoned every run.
+     */
+    const res = await fetchImpl(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`, {
+      signal: controller.signal,
+      headers: { accept: 'application/json' },
+    });
+    clearTimeout(timer);
+    const json = await res.json();
+    if (typeof json?.version === 'string') latest = json.version;
+  } catch {
+    // Offline, DNS down, npm having a moment. None of these are the user's
+    // problem and none should surface.
+    return { latest: current, isNewer: false, checked: false };
+  }
+
+  writeCache(cachePath, { at: now(), latest });
+  return { latest, isNewer: compareVersions(latest, current) > 0, checked: true };
+}
+
+/**
+ * Install the newer version, DETACHED, so it applies to the next run.
+ *
+ * ⚠️⚠️ NEVER IN-PROCESS AND NEVER AWAITED. Rewriting `lib/*.mjs` underneath a
+ * session that is mid-task is how an update becomes a crash in someone else's
+ * work — and the person it lands on never asked for the update at all.
+ *
+ * @returns {boolean} whether the install was successfully STARTED (not finished)
+ */
+export function applyUpdate({ spawn, version = 'latest' } = {}) {
+  if (!spawn) return false;
+  try {
+    const child = spawn(
+      process.platform === 'win32' ? 'npm.cmd' : 'npm',
+      ['install', '-g', `${PACKAGE_NAME}@${version}`],
+      { stdio: 'ignore', detached: true },
+    );
+    child.unref?.();
+    return true;
+  } catch {
+    // A global install can fail on permissions (a root-owned prefix is common).
+    // Silently — the notice below still tells them the command to run.
+    return false;
+  }
+}
+
+/** The one line a user sees. Deliberately small; nobody wants a changelog here. */
+export function updateNotice(current, latest, applied) {
+  return applied
+    ? `\nacuvo ${latest} is available (you have ${current}) — installing in the background, it will apply next run.\n`
+    : `\nacuvo ${latest} is available (you have ${current}) — update with:  npm i -g ${PACKAGE_NAME}@latest\n`;
+}
+
+/**
+ * Whether we should look at all.
+ *
+ * ⚠️ OFF FOR CI AND FOR ANYONE WHO SAYS SO. A build machine that silently
+ * upgrades its own toolchain mid-pipeline produces results nobody can reproduce,
+ * which is precisely the thing CI exists to prevent.
+ */
+export function updatesEnabled(env = process.env) {
+  if (String(env.ACUVO_NO_UPDATE ?? '') === '1') return false;
+  if (String(env.CI ?? '').toLowerCase() === 'true' || env.CI === '1') return false;
+  return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acuvo-code",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Acuvo Code — the terminal client for the Acuvo capability registry. Zero dependencies, by design.",
   "type": "module",
   "bin": {