@anyslate/cli 0.1.0 → 0.3.0

package/src/auth.mjs

@@ -0,0 +1,310 @@
+// Bearer resolution and refresh for every command that talks to the server.
+//
+// THIS IS THE LOAD-BEARING PART OF THE OAUTH WORK. A static `as_mcp_` token
+// never expires, so `loadConfig().mcpToken` was the whole auth story. An OAuth
+// access token lives 3600 seconds, and hooks fire unattended in
+// non-interactive shells — so a token WILL expire mid-session, in a process
+// with no terminal, no browser, and a hard "must exit 0" contract.
+//
+// The rules that fall out of that:
+//
+//   * Refresh PROACTIVELY, 5 minutes ahead of expiry, before the call. Waiting
+//     for the 401 spends a round trip and, on the hook path, risks the 15s
+//     budget.
+//   * On a 401, refresh EXACTLY ONCE and retry EXACTLY ONCE. A loop here is a
+//     self-inflicted rate limit against an endpoint that is already refusing us.
+//   * Persist the rotated refresh token immediately (rotation is on server-side).
+//   * NEVER open a browser. This module is imported by `hook`; a browser launch
+//     from a lifecycle hook would spray tabs across the user's screen and hang
+//     a process that must not hang.
+//   * Never throw. Callers are fail-open paths; a rejected promise here would
+//     become an uncaught exception in a hook and a non-zero exit.
+
+import { readConfigFile, updateConfigFile, withRefreshLock } from './credentials.mjs';
+import { callTool } from './mcp-client.mjs';
+import { discover, refreshAccessToken, REFRESH_SKEW_MS } from './oauth.mjs';
+
+export { REFRESH_SKEW_MS };
+
+/** Everything a hook/checkpoint/upload path is allowed to say about auth. */
+export const RELOGIN_HINT = 'Run `anyslate login` to sign in again.';
+
+/**
+ * @param {unknown} expiresAt ISO 8601
+ * @returns {number|null} epoch ms, or null when unparseable
+ */
+export function expiryMs(expiresAt) {
+  if (typeof expiresAt !== 'string' || !expiresAt) return null;
+  const t = Date.parse(expiresAt);
+  return Number.isFinite(t) ? t : null;
+}
+
+/**
+ * Is this credential inside the refresh window (or already dead)?
+ *
+ * An UNPARSEABLE or ABSENT expiry counts as expiring. Treating "I do not know"
+ * as "still valid" is how a config written by a future version, or hand-edited,
+ * turns into a silent 401 loop.
+ *
+ * @param {{expires_at?: string}|null|undefined} oauth
+ * @param {number} [skewMs]
+ * @param {number} [now]
+ */
+export function isExpiring(oauth, skewMs = REFRESH_SKEW_MS, now = Date.now()) {
+  if (!oauth?.access_token) return true;
+  const t = expiryMs(oauth.expires_at);
+  if (t == null) return true;
+  return t - now <= skewMs;
+}
+
+/** Hard expiry, no skew — used for reporting, not for refresh decisions. */
+export function isExpired(oauth, now = Date.now()) {
+  return isExpiring(oauth, 0, now);
+}
+
+/** Minutes until expiry, for human output. Negative means already expired. */
+export function minutesUntilExpiry(oauth, now = Date.now()) {
+  const t = expiryMs(oauth?.expires_at);
+  if (t == null) return null;
+  return Math.round((t - now) / 60_000);
+}
+
+/** Does this config hold OAuth credentials worth using or refreshing? */
+export function hasOauthCredentials(oauth) {
+  return !!(oauth && (oauth.access_token || oauth.refresh_token));
+}
+
+/**
+ * Resolve the endpoints used for a refresh.
+ *
+ * `login` caches `token_endpoint`/`resource`/`root` alongside the tokens, so
+ * the common refresh costs ONE request rather than three. The cache is only
+ * trusted when it was recorded for the root we are actually calling — a
+ * `--api-url` switch from prod to dev must re-discover, because the two issue
+ * different client ids and different `resource` values.
+ *
+ * @returns {Promise<{ok: true, tokenEndpoint: string, resource: string}
+ *   | {ok: false, code: string, message: string}>}
+ */
+async function refreshEndpoints({ oauth, root, fetchImpl }) {
+  if (oauth?.root === root && oauth?.token_endpoint && oauth?.resource) {
+    return { ok: true, tokenEndpoint: oauth.token_endpoint, resource: oauth.resource };
+  }
+  const found = await discover({ root, fetchImpl });
+  if (!found.ok) return found;
+  return { ok: true, tokenEndpoint: found.tokenEndpoint, resource: found.resource };
+}
+
+/**
+ * Perform one refresh, under the lock, persisting the rotated token.
+ *
+ * `staleToken` is the access token that just failed. It exists because expiry
+ * alone cannot decide whether a refresh is still needed: a token the server
+ * rejected with a 401 may have an `expires_at` an hour in the future (revoked
+ * early, clock skew, a config restored from a backup). Without it, the
+ * "somebody else already refreshed" short-circuit hands the caller back the
+ * very token that just 401'd, and the retry fails identically.
+ *
+ * @param {{env: NodeJS.ProcessEnv, root: string, fetchImpl?: typeof fetch, now?: number,
+ *          staleToken?: string|null}} opts
+ * @returns {Promise<{ok: true, token: string, rotated: boolean, oauth: object}
+ *   | {ok: false, code: string, message: string}>}
+ */
+export async function refreshCredentials({ env, root, fetchImpl = fetch, now, staleToken = null }) {
+  return withRefreshLock(
+    async () => {
+      // Re-read INSIDE the lock. While we queued, a sibling hook may have done
+      // the whole refresh already — redeeming our (now-replaced) refresh token
+      // would fail and, worse, would overwrite theirs.
+      const disk = readConfigFile(env);
+      const oauth = disk.oauth && typeof disk.oauth === 'object' ? disk.oauth : null;
+
+      if (!hasOauthCredentials(oauth)) {
+        return { ok: false, code: 'no_oauth_credentials', message: 'anyslate: no OAuth credentials to refresh.' };
+      }
+
+      // Skip only when the on-disk token is BOTH unexpired AND different from
+      // the one we are replacing — i.e. genuinely somebody else's fresh token.
+      const supersededByPeer = staleToken ? oauth.access_token && oauth.access_token !== staleToken : true;
+      if (supersededByPeer && !isExpiring(oauth, REFRESH_SKEW_MS, now)) {
+        return { ok: true, token: oauth.access_token, rotated: false, oauth };
+      }
+      if (!oauth.refresh_token) {
+        return {
+          ok: false,
+          code: 'no_refresh_token',
+          message: `anyslate: the stored OAuth session has no refresh token and its access token has expired. ${RELOGIN_HINT}`,
+        };
+      }
+
+      const endpoints = await refreshEndpoints({ oauth, root, fetchImpl });
+      if (!endpoints.ok) return endpoints;
+
+      const res = await refreshAccessToken({
+        tokenEndpoint: endpoints.tokenEndpoint,
+        refreshToken: oauth.refresh_token,
+        clientId: oauth.client_id,
+        resource: endpoints.resource,
+        fetchImpl,
+        now,
+      });
+      if (!res.ok) {
+        return {
+          ok: false,
+          code: res.code || 'refresh_failed',
+          message: `${res.message} ${RELOGIN_HINT}`,
+        };
+      }
+
+      // Persist BEFORE returning. Rotation means the old refresh token is dead
+      // the instant the server answered; a crash between here and the next
+      // write would lose the only usable credential.
+      const next = {
+        ...oauth,
+        access_token: res.tokens.access_token,
+        // A response that omits refresh_token means "keep the one you have".
+        refresh_token: res.tokens.refresh_token || oauth.refresh_token,
+        expires_at: res.tokens.expires_at,
+        token_endpoint: endpoints.tokenEndpoint,
+        resource: endpoints.resource,
+        root,
+      };
+      try {
+        updateConfigFile((current) => ({ ...current, oauth: { ...(current.oauth ?? {}), ...next } }), env);
+      } catch (e) {
+        return {
+          ok: false,
+          code: 'persist_failed',
+          message: `anyslate: refreshed the OAuth session but could not write the config (${e?.message ?? e}).`,
+        };
+      }
+      return { ok: true, token: next.access_token, rotated: true, oauth: next };
+    },
+    { env },
+  );
+}
+
+/**
+ * The bearer for the next call, refreshing if needed.
+ *
+ * Precedence mirrors loadConfig: ANYSLATE_MCP_TOKEN → OAuth → static
+ * `mcp_token` → nothing. The one deliberate divergence: loadConfig cannot
+ * refresh (it is synchronous), so an EXPIRED OAuth credential falls through
+ * there while here it is refreshed and preferred. If the refresh fails and a
+ * static token also exists, we fall back to it rather than failing the call —
+ * with `warning` set, so the caller can say so.
+ *
+ * @param {{cfg: object, env: NodeJS.ProcessEnv, fetchImpl?: typeof fetch, force?: boolean, now?: number}} opts
+ * @returns {Promise<{ok: true, token: string, mode: 'env'|'oauth'|'static', refreshed: boolean, warning?: string}
+ *   | {ok: false, code: string, message: string, mode: string}>}
+ */
+export async function resolveBearer({ cfg, env, fetchImpl = fetch, force = false, now }) {
+  if (cfg?.sources?.mcpToken === 'env' && cfg.mcpToken) {
+    return { ok: true, token: cfg.mcpToken, mode: 'env', refreshed: false };
+  }
+
+  const oauth = cfg?.oauth ?? null;
+  if (hasOauthCredentials(oauth)) {
+    if (!force && !isExpiring(oauth, REFRESH_SKEW_MS, now)) {
+      return { ok: true, token: oauth.access_token, mode: 'oauth', refreshed: false };
+    }
+    // `force` means "the token we just used was rejected" — name it, so the
+    // lock's peer-refresh check cannot hand the same rejected token back.
+    const refreshed = await refreshCredentials({
+      env,
+      root: cfg.apiUrl,
+      fetchImpl,
+      now,
+      staleToken: force ? (oauth.access_token ?? null) : null,
+    });
+    if (refreshed.ok) {
+      return { ok: true, token: refreshed.token, mode: 'oauth', refreshed: refreshed.rotated };
+    }
+    if (cfg.staticToken) {
+      return {
+        ok: true,
+        token: cfg.staticToken,
+        mode: 'static',
+        refreshed: false,
+        warning: `anyslate: OAuth refresh failed (${refreshed.code}) — falling back to the static token in your config.`,
+      };
+    }
+    return { ...refreshed, mode: 'oauth' };
+  }
+
+  if (cfg?.mcpToken) {
+    return { ok: true, token: cfg.mcpToken, mode: 'static', refreshed: false };
+  }
+
+  return {
+    ok: false,
+    mode: 'none',
+    code: 'no_credentials',
+    message:
+      'no credentials configured. Run `anyslate login` to sign in with your browser, or `anyslate login --token <BEARER>` for CI. Mint a token in the AnySlate desktop app at Avatar (top-right) → API Tokens.',
+  };
+}
+
+/**
+ * `callTool` with the auth lifecycle wrapped around it: proactive refresh, then
+ * at most one refresh-and-retry on a 401.
+ *
+ * The retry is gated on `mode === 'oauth'`: a static token that 401s is revoked
+ * or mistyped, and re-sending it cannot help.
+ *
+ * @param {{cfg: object, env: NodeJS.ProcessEnv, toolName: string, args: object,
+ *          fetchImpl?: typeof fetch, timeoutMs?: number}} opts
+ * @returns {Promise<object>} the callTool result, plus `authMode` / `authWarning`,
+ *   or an auth failure shaped like a callTool failure (`authError: true`).
+ */
+export async function callToolWithAuth({ cfg, env, toolName, args, fetchImpl, timeoutMs }) {
+  const first = await resolveBearer({ cfg, env, fetchImpl });
+  if (!first.ok) {
+    return { ok: false, status: 0, data: first.message, raw: null, authError: true, authMode: first.mode };
+  }
+
+  const invoke = (token) =>
+    callTool({ apiUrl: cfg.apiUrl, token, toolName, args, fetchImpl, timeoutMs });
+
+  let res = await invoke(first.token);
+  res.authMode = first.mode;
+  if (first.warning) res.authWarning = first.warning;
+
+  const retryable = !res.ok && res.status === 401 && first.mode === 'oauth' && !first.refreshed;
+  if (!retryable) return res;
+
+  const second = await resolveBearer({ cfg, env, fetchImpl, force: true });
+  if (!second.ok) {
+    res.authError = true;
+    res.authRefreshFailed = second.message;
+    return res;
+  }
+  const retried = await invoke(second.token);
+  retried.authMode = second.mode;
+  retried.authRetried = true;
+  if (second.warning) retried.authWarning = second.warning;
+  return retried;
+}
+
+/**
+ * The failure line for a result that failed on AUTH rather than on transport.
+ *
+ * `formatCallFailure` renders `server ${status} — ${data}`, which for an auth
+ * failure that never reached the server would print `server 0` — an HTTP status
+ * that did not happen. Returns null when this is an ordinary failure and the
+ * existing formatter should be used instead.
+ *
+ * @param {string} prefix
+ * @param {object} res
+ * @returns {string|null}
+ */
+export function formatAuthFailure(prefix, res) {
+  if (!res?.authError) return null;
+  if (res.authRefreshFailed) {
+    return `${prefix}: server ${res.status} and the OAuth refresh failed — ${res.authRefreshFailed}\n`;
+  }
+  if (res.status === 0 && !res.networkError) {
+    return `${prefix}: ${typeof res.data === 'string' ? res.data : JSON.stringify(res.data)}\n`;
+  }
+  return null;
+}

package/src/commands/checkpoint.mjs

@@ -1,11 +1,22 @@
-// `anyslate checkpoint` — submit an explicit checkpoint to the Activity feed.
+// `anyslate checkpoint` - submit an explicit checkpoint to the Activity feed.
 //
 // Unlike `hook`, this is user-initiated, so we surface failures directly
 // (exit 1 on error). Use this in CI or one-off scripts where you actually
 // want to know if the submit failed.
+//
+// W2: "failure" now includes tool-level errors (HTTP 200 + result.isError).
+// Previously a handle denial printed `{"error":"handle_not_found","status":401}`
+// to STDOUT and exited 0 — documented as fail-closed, actually fail-open, and
+// on the stream a caller would pipe into the next command.
+//
+// stdout carries results only. Every error goes to stderr.
 
-import { loadConfig, requireToken } from '../config.mjs';
-import { callTool } from '../mcp-client.mjs';
+import { loadConfig, requireToken, apiUrlNormalizationNotice, DISABLED_NOTICE } from '../config.mjs';
+import { formatCallFailure } from '../mcp-client.mjs';
+import { callToolWithAuth, formatAuthFailure } from '../auth.mjs';
+import { recordRun } from '../runlog.mjs';
+import { VERSION } from '../version.mjs';
+import { makeIo } from '../io.mjs';
 
 const ALLOWED_KINDS = new Set([
   'topic_shift', 'decision_committed', 'task_completed', 'task_added',
@@ -14,25 +25,38 @@ const ALLOWED_KINDS = new Set([
 
 /**
  * @param {string[]} argv  arguments after `checkpoint`
+ * @param {{env?: NodeJS.ProcessEnv, fetchImpl?: typeof fetch}} [deps]
  * @returns {Promise<number>}
  */
-export async function runCheckpoint(argv) {
+export async function runCheckpoint(argv, deps = {}) {
+  const env = deps.env ?? process.env;
+  const { out, err } = makeIo(deps);
   const flags = parseFlags(argv);
   if (!flags.note) {
-    process.stderr.write('usage: anyslate checkpoint --note <text> [--kind <kind>] [--session <id>] [--host <hint>] [--source <source>]\n');
-    process.stderr.write(`  kinds: ${[...ALLOWED_KINDS].join(', ')}\n`);
+    err.write('usage: anyslate checkpoint --note <text> [--kind <kind>] [--session <id>] [--host <hint>] [--source <source>]\n');
+    err.write(`  kinds: ${[...ALLOWED_KINDS].join(', ')}\n`);
     return 2;
   }
   const kind = flags.kind || 'milestone';
   if (!ALLOWED_KINDS.has(kind)) {
-    process.stderr.write(`anyslate checkpoint: unsupported kind: ${kind}\n`);
+    err.write(`anyslate checkpoint: unsupported kind: ${kind}\n`);
     return 2;
   }
 
-  const cfg = loadConfig();
-  const tokenCheck = requireToken(cfg);
-  if (!tokenCheck.ok) {
-    process.stderr.write(`anyslate checkpoint: ${tokenCheck.error}\n`);
+  const cfg = loadConfig(env);
+  if (cfg.disabled) {
+    err.write(`${DISABLED_NOTICE}\n`);
+    return 0;
+  }
+
+  const notice = apiUrlNormalizationNotice(cfg);
+  if (notice) err.write(notice);
+
+  // Presence only — an expired OAuth token is refreshed by callToolWithAuth.
+  if (cfg.authMode === 'none') {
+    const error = requireToken({ mcpToken: null }).error;
+    err.write(`anyslate checkpoint: ${error}\n`);
+    recordRun({ command: 'checkpoint', ok: false, apiUrl: cfg.apiUrl, error, version: VERSION, exitCode: 1 }, env);
     return 1;
   }
 
@@ -52,21 +76,40 @@ export async function runCheckpoint(argv) {
   if (flags.session) args.session_id_hint = flags.session;
 
   try {
-    const res = await callTool({
-      apiUrl: cfg.apiUrl,
-      token: cfg.mcpToken,
+    const res = await callToolWithAuth({
+      cfg,
+      env,
       toolName: 'activity_submit',
       args,
+      fetchImpl: deps.fetchImpl,
     });
+    if (res.authWarning) err.write(`${res.authWarning}\n`);
     if (!res.ok) {
-      const msg = typeof res.data === 'string' ? res.data : JSON.stringify(res.data);
-      process.stderr.write(`anyslate checkpoint: server ${res.status} — ${msg}\n`);
+      const message = formatAuthFailure('anyslate checkpoint', res) ?? formatCallFailure('anyslate checkpoint', res);
+      err.write(message);
+      recordRun(
+        {
+          command: 'checkpoint',
+          ok: false,
+          apiUrl: cfg.apiUrl,
+          status: res.status,
+          isError: !!res.isError,
+          networkError: !!res.networkError,
+          error: message.trim(),
+          version: VERSION,
+          exitCode: 1,
+        },
+        env,
+      );
       return 1;
     }
-    process.stdout.write(`${JSON.stringify(res.data)}\n`);
+    recordRun({ command: 'checkpoint', ok: true, apiUrl: cfg.apiUrl, status: res.status, version: VERSION, exitCode: 0 }, env);
+    out.write(`${JSON.stringify(res.data)}\n`);
     return 0;
   } catch (e) {
-    process.stderr.write(`anyslate checkpoint: request failed (${e?.message ?? e})\n`);
+    const message = `anyslate checkpoint: request failed (${e?.message ?? e})\n`;
+    err.write(message);
+    recordRun({ command: 'checkpoint', ok: false, apiUrl: cfg.apiUrl, error: message.trim(), version: VERSION, exitCode: 1 }, env);
     return 1;
   }
 }