@anyslate/cli 0.1.0 → 0.3.0

package/src/commands/logout.mjs

@@ -0,0 +1,131 @@
+// `anyslate logout` - revoke the OAuth session, then clear local credentials.
+//
+// This was genuinely missing. Before OAuth the only way to "log out" was to
+// hand-edit or delete `~/.anyslate/cli.json`, which also threw away the apiUrl
+// and handle — so the documented recovery was "delete the file and set
+// everything up again". With refresh tokens that gap becomes a security
+// problem, not just an annoyance: a 30-day refresh token stays live on disk
+// with no supported way to invalidate it.
+//
+// ORDER MATTERS, AND SO DOES FAILING SOFT. Revoke first (best effort), clear
+// second, ALWAYS. If revocation is skipped on a network error the user is left
+// holding a credential they believe is dead. If clearing is skipped because
+// revocation failed, `logout` becomes unusable exactly when it is most needed —
+// offline, or against a server that is down. So a failed revoke is reported and
+// the local credential is removed regardless.
+//
+// What is deliberately NOT removed: `apiUrl`, `handle`, and the cached
+// `oauth_clients` map. The client registration is not a credential (it grants
+// nothing on its own), and dropping it would burn one of the 10-per-hour
+// Dynamic Client Registrations on the next login.
+
+import { join } from 'node:path';
+import { anyslateDir, loadConfig } from '../config.mjs';
+import { readConfigFile, writeConfigFile } from '../credentials.mjs';
+import { discover, revocationEndpointFor, revokeToken } from '../oauth.mjs';
+import { makeIo } from '../io.mjs';
+
+/**
+ * @param {string[]} argv  arguments after `logout`
+ * @param {{env?: NodeJS.ProcessEnv, fetchImpl?: typeof fetch}} [deps]
+ * @returns {Promise<number>}
+ */
+export async function runLogout(argv = [], deps = {}) {
+  const env = deps.env ?? process.env;
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const { out, err } = makeIo(deps);
+  const flags = parseFlags(argv);
+
+  const cfg = loadConfig(env);
+  const current = readConfigFile(env);
+  const oauth = current.oauth && typeof current.oauth === 'object' ? current.oauth : null;
+  const hadOauth = !!(oauth && (oauth.access_token || oauth.refresh_token));
+  const hadStatic = !!(current.mcp_token || current.token);
+
+  if (!hadOauth && !hadStatic) {
+    out.write('anyslate: no stored credentials — nothing to log out of.\n');
+    if (env.ANYSLATE_MCP_TOKEN) {
+      out.write('anyslate: note — ANYSLATE_MCP_TOKEN is set in your environment; unset it to fully sign out.\n');
+    }
+    return 0;
+  }
+
+  // --- 1. Revoke (best effort) --------------------------------------------
+  if (hadOauth && !flags.local) {
+    const root = oauth.root || cfg.apiUrl;
+    const discovery = await discover({ root, fetchImpl });
+    const endpoint = revocationEndpointFor(discovery.ok ? discovery : null, root);
+
+    // Revoke the refresh token first: it is the long-lived one (30 days), and
+    // it is what an attacker with a stale config file would actually use.
+    const targets = [
+      oauth.refresh_token ? { token: oauth.refresh_token, hint: 'refresh_token' } : null,
+      oauth.access_token ? { token: oauth.access_token, hint: 'access_token' } : null,
+    ].filter(Boolean);
+
+    let revoked = 0;
+    let failed = null;
+    for (const t of targets) {
+      const res = await revokeToken({
+        revocationEndpoint: endpoint,
+        token: t.token,
+        clientId: oauth.client_id,
+        tokenTypeHint: t.hint,
+        fetchImpl,
+      });
+      if (res.ok) revoked += 1;
+      else failed = res.detail ?? 'unknown error';
+    }
+
+    if (revoked === targets.length) {
+      out.write(`anyslate: revoked the OAuth session at ${hostOf(endpoint)}.\n`);
+    } else {
+      err.write(
+        `anyslate: warning — could not revoke the OAuth session at ${hostOf(endpoint)} (${failed}). ` +
+          'Clearing the local credentials anyway; revoke the token in the app if that matters.\n',
+      );
+    }
+  } else if (hadOauth && flags.local) {
+    err.write('anyslate: --local given — skipping revocation; the server-side session stays live until it expires.\n');
+  }
+
+  // --- 2. Clear (always) ---------------------------------------------------
+  const path = join(anyslateDir(env), 'cli.json');
+  try {
+    const disk = readConfigFile(env);
+    delete disk.oauth;
+    delete disk.mcp_token;
+    delete disk.token;
+    writeConfigFile(disk, env);
+  } catch (e) {
+    err.write(`anyslate logout: could not update ${path} (${e?.message ?? e})\n`);
+    return 1;
+  }
+
+  const cleared = [hadOauth && 'OAuth session', hadStatic && 'static token'].filter(Boolean).join(' and ');
+  out.write(`anyslate: cleared the ${cleared} from ${path}.\n`);
+  out.write('anyslate: apiUrl and handle were kept. Run `anyslate login` to sign in again.\n');
+  if (env.ANYSLATE_MCP_TOKEN) {
+    err.write(
+      'anyslate: warning — ANYSLATE_MCP_TOKEN is still set in your environment and overrides the config, so capture keeps working. Unset it to fully sign out.\n',
+    );
+  }
+  return 0;
+}
+
+function hostOf(url) {
+  try {
+    return new URL(url).host;
+  } catch {
+    return String(url);
+  }
+}
+
+/** @param {string[]} argv */
+function parseFlags(argv) {
+  const out = { local: false };
+  for (const a of argv) {
+    if (a === '--local' || a === '--no-revoke') out.local = true;
+  }
+  return out;
+}

package/src/commands/upload-artifact.mjs

@@ -1,4 +1,4 @@
-// `anyslate upload-artifact` — upload a file (or stdin) as an MCP artifact.
+// `anyslate upload-artifact` - upload a file (or stdin) as an MCP artifact.
 //
 // Usage:
 //   anyslate upload-artifact --session <id> --kind code_block --file ./diff.patch
@@ -6,63 +6,122 @@
 //
 // Returns the cloud://artifact/<id> URI on stdout (one per line) so callers
 // can pipe it into a subsequent `anyslate checkpoint --note ...` if desired.
+//
+// W11: `--file` used to `readFileSync(path, 'utf8')`, which silently mangles
+// binaries (measured: 64 raw bytes in → 124 bytes uploaded, exit 0). The
+// `upload_artifact` MCP tool is a TEXT channel, so we detect and refuse rather
+// than pretend. Both `--file` and stdin honour the same 5 MB cap; the stdin
+// path must never fall back to readStdin's 1 MB default.
 
 import { readFileSync } from 'node:fs';
 import { basename } from 'node:path';
-import { loadConfig, requireToken } from '../config.mjs';
-import { callTool } from '../mcp-client.mjs';
-import { readStdin } from '../stdin.mjs';
+import { loadConfig, requireToken, apiUrlNormalizationNotice, DISABLED_NOTICE } from '../config.mjs';
+import { formatCallFailure } from '../mcp-client.mjs';
+import { callToolWithAuth, formatAuthFailure } from '../auth.mjs';
+import { readStdin, stdinTimeoutFromEnv } from '../stdin.mjs';
+import { recordRun } from '../runlog.mjs';
+import { VERSION } from '../version.mjs';
+import { makeIo } from '../io.mjs';
 
 const ALLOWED_KINDS = new Set([
   'code_block', 'file_path', 'error_message', 'shell_command',
   'config_snippet', 'url_reference', 'fenced_quote',
 ]);
 
-const MAX_CONTENT_BYTES = 5_000_000;
+export const MAX_CONTENT_BYTES = 5_000_000;
+
+/** Uploading over a pipe may legitimately be slow; give stdin more idle room. */
+const STDIN_IDLE_TIMEOUT_MS = 60_000;
+
+/**
+ * A Buffer round-trips through utf8 iff it *is* valid utf8. Node replaces
+ * invalid sequences with U+FFFD, so re-encoding produces different bytes.
+ *
+ * @param {Buffer} buf
+ * @returns {boolean}
+ */
+export function isValidUtf8(buf) {
+  return Buffer.compare(Buffer.from(buf.toString('utf8'), 'utf8'), buf) === 0;
+}
 
 /**
  * @param {string[]} argv  arguments after `upload-artifact`
+ * @param {{env?: NodeJS.ProcessEnv, fetchImpl?: typeof fetch, stdin?: NodeJS.ReadableStream}} [deps]
  * @returns {Promise<number>}
  */
-export async function runUploadArtifact(argv) {
+export async function runUploadArtifact(argv, deps = {}) {
+  const env = deps.env ?? process.env;
+  const { out, err } = makeIo(deps);
   const flags = parseFlags(argv);
   if (!flags.session || !flags.kind) {
-    process.stderr.write('usage: anyslate upload-artifact --session <id> --kind <kind> [--file <path> | <stdin>] [--language <lang>] [--path-hint <name>]\n');
-    process.stderr.write(`  kinds: ${[...ALLOWED_KINDS].join(', ')}\n`);
+    err.write('usage: anyslate upload-artifact --session <id> --kind <kind> [--file <path> | <stdin>] [--language <lang>] [--path-hint <name>]\n');
+    err.write(`  kinds: ${[...ALLOWED_KINDS].join(', ')}\n`);
     return 2;
   }
   if (!ALLOWED_KINDS.has(flags.kind)) {
-    process.stderr.write(`anyslate upload-artifact: unsupported kind: ${flags.kind}\n`);
+    err.write(`anyslate upload-artifact: unsupported kind: ${flags.kind}\n`);
     return 2;
   }
 
-  const cfg = loadConfig();
-  const tokenCheck = requireToken(cfg);
-  if (!tokenCheck.ok) {
-    process.stderr.write(`anyslate upload-artifact: ${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 upload-artifact: ${error}\n`);
+    recordRun({ command: 'upload-artifact', ok: false, apiUrl: cfg.apiUrl, error, version: VERSION, exitCode: 1 }, env);
     return 1;
   }
 
   let content;
   let pathHint = flags.pathHint;
   if (flags.file) {
+    let buf;
     try {
-      content = readFileSync(flags.file, 'utf8');
-      if (!pathHint) pathHint = basename(flags.file);
+      buf = readFileSync(flags.file);
     } catch (e) {
-      process.stderr.write(`anyslate upload-artifact: cannot read ${flags.file} (${e?.message ?? e})\n`);
+      err.write(`anyslate upload-artifact: cannot read ${flags.file} (${e?.message ?? e})\n`);
+      return 1;
+    }
+    if (buf.byteLength > MAX_CONTENT_BYTES) {
+      err.write(`anyslate upload-artifact: content exceeds ${MAX_CONTENT_BYTES} byte cap\n`);
       return 1;
     }
+    if (!isValidUtf8(buf)) {
+      err.write(
+        `anyslate: ${flags.file} is not valid UTF-8. Binary artifacts are not supported by upload-artifact.\n`,
+      );
+      return 1;
+    }
+    content = buf.toString('utf8');
+    if (!pathHint) pathHint = basename(flags.file);
   } else {
-    content = await readStdin();
+    // The 5 MB cap MUST be passed explicitly — readStdin's default is 1 MB and
+    // silently truncates.
+    try {
+      content = await readStdin(deps.stdin ?? process.stdin, {
+        maxBytes: MAX_CONTENT_BYTES,
+        timeoutMs: stdinTimeoutFromEnv(env, STDIN_IDLE_TIMEOUT_MS),
+      });
+    } catch (e) {
+      err.write(`anyslate upload-artifact: stdin read failed (${e?.message ?? e})\n`);
+      return 1;
+    }
   }
 
   if (!content || !content.length) {
-    process.stderr.write('anyslate upload-artifact: empty content (provide --file or pipe data on stdin)\n');
+    err.write('anyslate upload-artifact: empty content (provide --file or pipe data on stdin)\n');
     return 1;
   }
   if (Buffer.byteLength(content, 'utf8') > MAX_CONTENT_BYTES) {
-    process.stderr.write(`anyslate upload-artifact: content exceeds ${MAX_CONTENT_BYTES} byte cap\n`);
+    err.write(`anyslate upload-artifact: content exceeds ${MAX_CONTENT_BYTES} byte cap\n`);
     return 1;
   }
 
@@ -76,25 +135,76 @@ export async function runUploadArtifact(argv) {
   if (pathHint) args.path_hint = pathHint;
 
   try {
-    const res = await callTool({
-      apiUrl: cfg.apiUrl,
-      token: cfg.mcpToken,
+    const res = await callToolWithAuth({
+      cfg,
+      env,
       toolName: 'upload_artifact',
       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 upload-artifact: server ${res.status} — ${msg}\n`);
+      const message =
+        formatAuthFailure('anyslate upload-artifact', res) ?? formatCallFailure('anyslate upload-artifact', res);
+      err.write(message);
+      recordRun(
+        {
+          command: 'upload-artifact',
+          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: 'upload-artifact', ok: true, apiUrl: cfg.apiUrl, status: res.status, version: VERSION, exitCode: 0 }, env);
+    out.write(`${formatUploadArtifactOutput(res.data)}\n`);
     return 0;
   } catch (e) {
-    process.stderr.write(`anyslate upload-artifact: request failed (${e?.message ?? e})\n`);
+    const message = `anyslate upload-artifact: request failed (${e?.message ?? e})\n`;
+    err.write(message);
+    recordRun({ command: 'upload-artifact', ok: false, apiUrl: cfg.apiUrl, error: message.trim(), version: VERSION, exitCode: 1 }, env);
     return 1;
   }
 }
 
+/**
+ * @param {unknown} data
+ * @returns {string}
+ */
+export function formatUploadArtifactOutput(data) {
+  const uri = extractArtifactUri(data);
+  return uri || JSON.stringify(data);
+}
+
+/**
+ * @param {unknown} data
+ * @returns {string|null}
+ */
+function extractArtifactUri(data) {
+  if (typeof data === 'string') {
+    return data.startsWith('cloud://artifact/') ? data : null;
+  }
+  if (!data || typeof data !== 'object') return null;
+  for (const key of ['cloud_uri', 'cloudUri', 'uri', 'artifact_uri', 'artifactUri']) {
+    const v = data[key];
+    if (typeof v === 'string' && v.startsWith('cloud://artifact/')) return v;
+  }
+  const artifact = data.artifact;
+  if (artifact && typeof artifact === 'object') {
+    const nestedUri = extractArtifactUri(artifact);
+    if (nestedUri) return nestedUri;
+  }
+  const id = data.artifact_id || data.artifactId || data.id;
+  return typeof id === 'string' && id.length > 0 ? `cloud://artifact/${id}` : null;
+}
+
 /** @param {string[]} argv */
 function parseFlags(argv) {
   const out = {};

package/src/config.mjs

@@ -5,12 +5,28 @@
 //   2. ~/.anyslate/cli.json (preferred CLI config)
 //   3. ~/.anyslate/session.json (legacy, only the `mcp_token` / `handle` keys)
 //
+// BEARER precedence specifically (`mcpToken`), narrower than the above:
+//   ANYSLATE_MCP_TOKEN → oauth.access_token (present AND unexpired) → mcp_token
+//
+// `loadConfig` is synchronous, so it cannot refresh — an OAuth credential past
+// its expiry falls through here as if absent. That is deliberate: the raw
+// `oauth` block is returned alongside, and src/auth.mjs (async) is what decides
+// to refresh it. Making this function "smart" would mean every config read
+// could block on the network, including inside `doctor`'s own diagnostics.
+//
 // Defaults:
 //   - apiUrl  → https://mcp.anyslate.io
 //
 // All file reads tolerate missing / unreadable files; the CLI fails open so
 // `anyslate hook session-start` never breaks a Claude Code session because of
-// a missing config — it just no-ops with a warning to stderr.
+// a missing config - it just no-ops with a warning to stderr.
+//
+// URL normalization (W1): the CLI wants the service ROOT and appends `/mcp`
+// itself. A config whose apiUrl already ends in `/mcp` produced `/mcp/mcp` and
+// a permanent 404 that masked every token verdict (the 404 fires at
+// app.notFound() BEFORE auth middleware). We therefore normalize on the READ
+// path, not only in `login`, so already-broken configs self-heal without a
+// re-login.
 
 import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -18,22 +34,89 @@ import { join } from 'node:path';
 
 export const DEFAULT_API_URL = 'https://mcp.anyslate.io';
 
-const CONFIG_PATHS = [
-  () => join(homedir(), '.anyslate', 'cli.json'),
-  () => join(homedir(), '.anyslate', 'session.json'),
-];
+/** Where the desktop app / CLI keep their state. `ANYSLATE_HOME` overrides. */
+export function anyslateDir(env = process.env) {
+  if (env.ANYSLATE_HOME && env.ANYSLATE_HOME.trim()) return env.ANYSLATE_HOME.trim();
+  return join(homedir(), '.anyslate');
+}
+
+export function configPaths(env = process.env) {
+  const dir = anyslateDir(env);
+  return [join(dir, 'cli.json'), join(dir, 'session.json')];
+}
+
+/**
+ * Strip trailing slashes AND every trailing `/mcp` segment.
+ *
+ * `(\/mcp)+$` — not `\/mcp$`. The single-segment form leaves an already
+ * double-suffixed `…/mcp/mcp` broken (defect #45).
+ *
+ * @param {unknown} u
+ * @returns {string}
+ */
+export function normalizeApiRoot(u) {
+  return String(u ?? '')
+    .trim()
+    .replace(/\/+$/, '')
+    .replace(/(\/mcp)+$/i, '');
+}
+
+/**
+ * The dedicated capture kill switch (Q5). Deliberately NOT implemented by
+ * changing the falsy-coalescing of ANYSLATE_MCP_TOKEN — an empty string there
+ * still falls through to the file token, and scripts that clear variables by
+ * emptying them must keep working.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {boolean}
+ */
+export function isCaptureDisabled(env = process.env) {
+  const v = env.ANYSLATE_DISABLE;
+  if (v === undefined || v === null) return false;
+  const s = String(v).trim().toLowerCase();
+  if (s === '' || s === '0' || s === 'false' || s === 'no' || s === 'off') return false;
+  return true;
+}
+
+export const DISABLED_NOTICE =
+  'anyslate: ANYSLATE_DISABLE is set — capture disabled for this shell (no network call made).';
+
+/**
+ * Is this stored OAuth credential still usable without a refresh?
+ * An absent or unparseable `expires_at` counts as expired — "I cannot tell"
+ * must never resolve to "still good".
+ *
+ * @param {{access_token?: string, expires_at?: string}|null|undefined} oauth
+ * @param {number} [now]
+ * @returns {boolean}
+ */
+export function oauthTokenUsable(oauth, now = Date.now()) {
+  if (!oauth || typeof oauth !== 'object') return false;
+  if (typeof oauth.access_token !== 'string' || !oauth.access_token) return false;
+  const t = Date.parse(String(oauth.expires_at ?? ''));
+  if (!Number.isFinite(t)) return false;
+  return t > now;
+}
 
 /**
  * @param {NodeJS.ProcessEnv} env
  * @param {() => string[]} [paths] override for tests
- * @returns {{apiUrl: string, mcpToken: string|null, handle: string|null, source: string}}
+ * @returns {{
+ *   apiUrl: string, apiUrlRaw: string, apiUrlNormalized: boolean,
+ *   mcpToken: string|null, handle: string|null,
+ *   oauth: object|null, staticToken: string|null, authMode: 'env'|'oauth'|'static'|'none',
+ *   oauthClients: Record<string, string>,
+ *   source: string, sources: {apiUrl: string, mcpToken: string, handle: string},
+ *   disabled: boolean
+ * }}
  */
 export function loadConfig(env = process.env, paths) {
-  const candidates = paths ? paths() : CONFIG_PATHS.map((fn) => fn());
+  const candidates = paths ? paths() : configPaths(env);
 
-  /** @type {{apiUrl?: string, mcp_token?: string, handle?: string}} */
+  /** @type {{apiUrl?: string, api_url?: string, mcp_token?: string, token?: string, handle?: string}} */
   let fileConfig = {};
   let source = 'env';
+  let filePath = null;
   for (const p of candidates) {
     try {
       const raw = readFileSync(p, 'utf8');
@@ -41,18 +124,84 @@ export function loadConfig(env = process.env, paths) {
       if (parsed && typeof parsed === 'object') {
         fileConfig = parsed;
         source = p;
+        filePath = p;
         break;
       }
     } catch {
-      // ignore — fall through to next candidate
+      // ignore - fall through to next candidate
     }
   }
 
-  const apiUrl = (env.ANYSLATE_API_URL || fileConfig.apiUrl || fileConfig.api_url || DEFAULT_API_URL).replace(/\/+$/, '');
-  const mcpToken = env.ANYSLATE_MCP_TOKEN || fileConfig.mcp_token || fileConfig.token || null;
+  // Per-key provenance. `source` alone is misleading: it names the file that
+  // parsed, while an env var may still be winning for an individual key
+  // (defect #38 / W4 check #1).
+  const layerOf = (envValue, fileValue) => {
+    if (envValue) return 'env';
+    if (fileValue) return filePath ?? 'default';
+    return 'default';
+  };
+
+  const apiUrlRaw = String(
+    env.ANYSLATE_API_URL || fileConfig.apiUrl || fileConfig.api_url || DEFAULT_API_URL,
+  ).trim();
+  const apiUrl = normalizeApiRoot(apiUrlRaw);
+  const apiUrlNormalized = apiUrl !== apiUrlRaw.replace(/\/+$/, '');
+
+  const oauth = fileConfig.oauth && typeof fileConfig.oauth === 'object' ? fileConfig.oauth : null;
+  const oauthClients =
+    fileConfig.oauth_clients && typeof fileConfig.oauth_clients === 'object' ? fileConfig.oauth_clients : {};
+  const staticToken = fileConfig.mcp_token || fileConfig.token || null;
+  const liveOauthToken = oauthTokenUsable(oauth) ? oauth.access_token : null;
+
+  const mcpToken = env.ANYSLATE_MCP_TOKEN || liveOauthToken || staticToken || null;
   const handle = env.ANYSLATE_HANDLE || fileConfig.handle || null;
 
-  return { apiUrl, mcpToken, handle, source };
+  /** Which layer supplied the bearer — what `doctor` renders as the auth mode. */
+  const authMode = env.ANYSLATE_MCP_TOKEN
+    ? 'env'
+    : liveOauthToken
+      ? 'oauth'
+      : staticToken
+        ? 'static'
+        : oauth
+          ? 'oauth' // credentials exist but need a refresh; auth.mjs handles it
+          : 'none';
+
+  return {
+    apiUrl,
+    apiUrlRaw,
+    apiUrlNormalized,
+    mcpToken,
+    handle,
+    oauth,
+    oauthClients,
+    staticToken,
+    authMode,
+    source,
+    sources: {
+      apiUrl: layerOf(env.ANYSLATE_API_URL, fileConfig.apiUrl || fileConfig.api_url),
+      // The bearer's provenance follows the same three-way precedence as the
+      // value itself, so `doctor` cannot report "from file" for an env token.
+      mcpToken: layerOf(env.ANYSLATE_MCP_TOKEN, liveOauthToken || staticToken),
+      handle: layerOf(env.ANYSLATE_HANDLE, fileConfig.handle),
+    },
+    disabled: isCaptureDisabled(env),
+  };
+}
+
+/**
+ * Exact user-facing notice for a rewritten apiUrl. Silent correction teaches
+ * the user nothing, so every command that resolves a rewritten URL says so.
+ *
+ * @param {{apiUrlRaw: string, apiUrl: string, apiUrlNormalized: boolean}} cfg
+ * @returns {string|null}
+ */
+export function apiUrlNormalizationNotice(cfg) {
+  if (!cfg?.apiUrlNormalized) return null;
+  return (
+    `anyslate: apiUrl "${cfg.apiUrlRaw}" ends in /mcp — the CLI wants the service ROOT and appends /mcp itself.\n` +
+    `anyslate: using "${cfg.apiUrl}". Run \`anyslate login --api-url ${cfg.apiUrl}\` to persist.\n`
+  );
 }
 
 /**
@@ -64,7 +213,7 @@ export function requireToken(cfg) {
     return {
       ok: false,
       error:
-        'no MCP token configured. Run `anyslate login --token <BEARER>` or set ANYSLATE_MCP_TOKEN. Mint a token at Settings → AI Memory → Connect in the AnySlate desktop app.',
+        'no MCP token configured. Run `anyslate login` to sign in with your browser, or `anyslate login --token <BEARER>` / set ANYSLATE_MCP_TOKEN for CI. Mint a token in the AnySlate desktop app at Avatar (top-right) → API Tokens.',
     };
   }
   return { ok: true };