gramatr 0.3.57 → 0.3.58

package/bin/add-api-key.ts

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+/**
+ * gramatr add-api-key — Explicit API key ingestion command (issue #484).
+ *
+ * Three modes:
+ *   1. Interactive prompt:    gramatr add-api-key
+ *   2. Piped stdin:           echo "gmtr_sk_..." | gramatr add-api-key
+ *   3. Env-sourced:           gramatr add-api-key --from-env GRAMATR_API_KEY
+ *
+ * The key is validated against the gramatr server before being written
+ * to ~/.gmtr.json. Use --force to skip server validation when offline.
+ *
+ * This command is the ONLY way to put an API key into ~/.gmtr.json.
+ * Installers never prompt for API keys — see packages/client/core/auth.ts.
+ */
+
+import { chmodSync, existsSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { createInterface } from "readline";
+
+function gmtrJsonPath(): string {
+  return join(process.env.HOME || process.env.USERPROFILE || homedir(), ".gmtr.json");
+}
+const SERVER_BASE = (process.env.GMTR_URL || "https://api.gramatr.com").replace(/\/mcp\/?$/, "");
+
+// Accept gmtr_sk_, gmtr_pk_, aios_sk_, aios_pk_ (legacy), and Firebase-style
+// long opaque tokens (length >= 32, base64url-ish characters).
+const KEY_FORMAT = /^(gmtr|aios)_(sk|pk)_[A-Za-z0-9_-]+$/;
+const LEGACY_OPAQUE = /^[A-Za-z0-9_.-]{32,}$/;
+
+function log(msg: string = ""): void {
+  process.stdout.write(`${msg}\n`);
+}
+
+function err(msg: string): void {
+  process.stderr.write(`${msg}\n`);
+}
+
+function parseArgs(argv: string[]): {
+  fromEnv?: string;
+  force: boolean;
+  help: boolean;
+} {
+  let fromEnv: string | undefined;
+  let force = false;
+  let help = false;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--from-env") {
+      fromEnv = argv[++i];
+    } else if (a === "--force") {
+      force = true;
+    } else if (a === "--help" || a === "-h") {
+      help = true;
+    }
+  }
+  return { fromEnv, force, help };
+}
+
+function showHelp(): void {
+  log(`gramatr add-api-key — Add a gramatr API key to ~/.gmtr.json
+
+Usage:
+  gramatr add-api-key                      Interactive prompt for the key
+  echo "gmtr_sk_..." | gramatr add-api-key Read key from piped stdin
+  gramatr add-api-key --from-env VAR       Read key from named env variable
+  gramatr add-api-key --force              Skip server validation (offline use)
+
+The key is validated against the gramatr server before being written.
+Server: ${SERVER_BASE}`);
+}
+
+function validateFormat(key: string): boolean {
+  if (KEY_FORMAT.test(key)) return true;
+  // Allow legacy opaque tokens (e.g. Firebase IDs) — must still be sane.
+  if (LEGACY_OPAQUE.test(key) && !key.includes(" ")) return true;
+  return false;
+}
+
+async function readPipedStdin(): Promise<string | null> {
+  if (process.stdin.isTTY) return null;
+  return new Promise((resolve) => {
+    const chunks: Buffer[] = [];
+    process.stdin.on("data", (c) => chunks.push(Buffer.from(c)));
+    process.stdin.on("end", () => {
+      const out = Buffer.concat(chunks).toString("utf8").trim();
+      resolve(out || null);
+    });
+    process.stdin.on("error", () => resolve(null));
+  });
+}
+
+async function readInteractive(): Promise<string> {
+  log("");
+  log("Paste your gramatr API key below.");
+  log("(Get one at https://gramatr.com/settings — keys start with gmtr_sk_)");
+  log("");
+  process.stdout.write("  Key: ");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.on("line", (line: string) => {
+      rl.close();
+      resolve(line.trim());
+    });
+  });
+}
+
+interface ValidationResult {
+  ok: boolean;
+  status?: number;
+  error?: string;
+}
+
+async function validateAgainstServer(key: string): Promise<ValidationResult> {
+  // Use the MCP aggregate_stats path the same way gmtr-login.ts does —
+  // this is the lightest authenticated endpoint we know works on every
+  // deployment without requiring a /api/v1/me route.
+  try {
+    const res = await fetch(`${SERVER_BASE}/mcp`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json, text/event-stream",
+        Authorization: `Bearer ${key}`,
+      },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "aggregate_stats", arguments: {} },
+      }),
+      signal: AbortSignal.timeout(10000),
+    });
+
+    const text = await res.text();
+
+    if (res.status === 401 || res.status === 403) {
+      return { ok: false, status: res.status, error: "Server rejected key (401/403)" };
+    }
+    if (
+      text.includes("JWT token is required") ||
+      text.includes("signature validation failed") ||
+      text.includes("Unauthorized")
+    ) {
+      return { ok: false, status: 401, error: "Server rejected key" };
+    }
+    if (res.status >= 500) {
+      return { ok: false, status: res.status, error: `Server error HTTP ${res.status}` };
+    }
+    if (!res.ok) {
+      return { ok: false, status: res.status, error: `HTTP ${res.status}` };
+    }
+    return { ok: true, status: res.status };
+  } catch (e: any) {
+    return { ok: false, error: e?.message || "Network failure" };
+  }
+}
+
+function writeKey(key: string): void {
+  let existing: Record<string, any> = {};
+  if (existsSync(gmtrJsonPath())) {
+    try {
+      existing = JSON.parse(readFileSync(gmtrJsonPath(), "utf8"));
+    } catch {
+      existing = {};
+    }
+  }
+  existing.token = key;
+  existing.token_type =
+    key.startsWith("gmtr_sk_") || key.startsWith("aios_sk_") ? "api_key" : "oauth";
+  existing.authenticated_at = new Date().toISOString();
+  writeFileSync(gmtrJsonPath(), `${JSON.stringify(existing, null, 2)}\n`, "utf8");
+  try {
+    chmodSync(gmtrJsonPath(), 0o600);
+  } catch {
+    /* ignore */
+  }
+}
+
+export async function main(argv: string[] = process.argv.slice(2)): Promise<number> {
+  const opts = parseArgs(argv);
+  if (opts.help) {
+    showHelp();
+    return 0;
+  }
+
+  let key: string | null = null;
+
+  // Source 1: --from-env
+  if (opts.fromEnv) {
+    const v = process.env[opts.fromEnv];
+    if (!v || !v.trim()) {
+      err(`ERROR: env var ${opts.fromEnv} is unset or empty`);
+      return 1;
+    }
+    key = v.trim();
+  }
+
+  // Source 2: piped stdin
+  if (!key) {
+    key = await readPipedStdin();
+  }
+
+  // Source 3: interactive
+  if (!key && process.stdin.isTTY) {
+    key = (await readInteractive()).trim();
+  }
+
+  if (!key) {
+    err("ERROR: no API key provided. See `gramatr add-api-key --help`.");
+    return 1;
+  }
+
+  // Format validation
+  if (!validateFormat(key)) {
+    err("ERROR: key format is invalid. Expected gmtr_sk_... or gmtr_pk_...");
+    return 1;
+  }
+
+  // Server validation
+  if (!opts.force) {
+    log("Validating key against gramatr server...");
+    const result = await validateAgainstServer(key);
+    if (!result.ok) {
+      if (result.status === 401 || result.status === 403) {
+        err(`ERROR: server rejected key — ${result.error}`);
+        err("Key was NOT written.");
+        return 1;
+      }
+      // Network or 5xx — surface as warning, exit non-zero unless --force.
+      err(`WARN: could not validate key — ${result.error}`);
+      err("Key was NOT written. Re-run with --force to skip server validation.");
+      return 1;
+    }
+    log("  OK Server accepted key");
+  } else {
+    log("  Skipping server validation (--force)");
+  }
+
+  writeKey(key);
+  log(`OK Key written to ${gmtrJsonPath()}`);
+  log("gramatr is now authenticated.");
+  return 0;
+}
+
+// Only auto-run when invoked directly, not when imported by tests.
+const isDirect = (() => {
+  try {
+    const invoked = process.argv[1] || "";
+    return invoked.endsWith("add-api-key.ts") || invoked.endsWith("add-api-key.js");
+  } catch {
+    return false;
+  }
+})();
+
+if (isDirect) {
+  main()
+    .then((code) => process.exit(code))
+    .catch((e) => {
+      err(`ERROR: ${e?.message || e}`);
+      process.exit(1);
+    });
+}

package/bin/gramatr.ts

@@ -301,6 +301,15 @@ function main(): void {
         installTarget(target.id);
       }
       return;
+    case 'login':
+      runTs(join(binDir, 'gmtr-login.ts'), forwardedFlags);
+      return;
+    case 'add-api-key':
+      runTs(join(binDir, 'add-api-key.ts'), raw.slice(1));
+      return;
+    case 'logout':
+      runTs(join(binDir, 'logout.ts'), raw.slice(1));
+      return;
     case 'detect':
       renderDetections();
       return;
@@ -320,6 +329,9 @@ function main(): void {
       log('');
       log('Commands:');
       log('  install [target]   Install gramatr (claude-code, codex, gemini-cli, all)');
+      log('  login              Authenticate with the gramatr server (OAuth)');
+      log('  add-api-key        Add an API key explicitly (interactive / piped / --from-env)');
+      log('  logout             Clear stored credentials (~/.gmtr.json)');
       log('  detect             Show detected CLI platforms');
       log('  doctor             Check installation health');
       log('  upgrade            Upgrade all installed targets');

package/bin/install.ts

@@ -15,10 +15,11 @@ import {
   readdirSync, statSync, chmodSync, rmSync,
 } from 'fs';
 import { join, dirname, basename, resolve } from 'path';
-import { execSync, spawnSync } from 'child_process';
+import { execSync } from 'child_process';
 import { createInterface } from 'readline';
 import { buildClaudeHooksFile } from '../core/install.ts';
 import { VERSION } from '../core/version.ts';
+import { resolveAuthToken } from '../core/auth.ts';
 
 // ── Constants ──
 
@@ -344,66 +345,37 @@ function installClaudeMd(): void {
 
 // ── Step 3: Auth ──
 
-// npx on Windows is shipped as `npx.cmd`. spawnSync without shell: true cannot
-// resolve .cmd shims, so we fall back to the platform-specific binary name.
-const NPX_BIN = process.platform === 'win32' ? 'npx.cmd' : 'npx';
-
 async function handleAuth(legacyToken: string): Promise<{ url: string; token: string }> {
   log('━━━ Step 3: Configuring gramatr MCP server ━━━');
   log('');
 
   const url = await prompt('gramatr server URL', DEFAULT_URL) || DEFAULT_URL;
 
-  // Token priority: env > ~/.gmtr.json > legacy > login
-  let token = process.env.GMTR_TOKEN || '';
-
-  if (token) {
-    log('OK Using GMTR_TOKEN from environment');
-  }
-
-  if (!token && existsSync(GMTR_JSON)) {
-    const existing = readJson(GMTR_JSON);
-    if (existing.token) {
-      token = existing.token;
-      log('OK Found existing auth token in ~/.gmtr.json');
-    }
-  }
-
-  if (!token && legacyToken) {
-    token = legacyToken;
-    log('OK Reusing auth token from legacy aios installation');
+  // Legacy aios token migration: if we cherry-picked a token from a prior
+  // aios install and there is no current ~/.gmtr.json token, seed it so the
+  // shared resolver picks it up.
+  if (legacyToken && !existsSync(GMTR_JSON)) {
+    try {
+      writeFileSync(GMTR_JSON, `${JSON.stringify({ token: legacyToken }, null, 2)}\n`, 'utf8');
+      try { chmodSync(GMTR_JSON, 0o600); } catch { /* ok */ }
+      log('OK Seeded ~/.gmtr.json from legacy aios installation token');
+    } catch { /* ignore */ }
   }
 
-  // No token — run gmtr-login directly (imported, not subprocess)
-  if (!token && isInteractive) {
-    log('');
-    log('  No auth token found. Starting gramatr login...');
-    log('');
-
-    const loginScript = join(CLIENT_DIR, 'bin', 'gmtr-login.ts');
-    if (existsSync(loginScript)) {
-      // Run gmtr-login as subprocess but with proper stdio handling
-      // Use spawnSync so stdin is properly passed through (no stall)
-      const result = spawnSync(NPX_BIN, ['tsx', loginScript], {
-        stdio: 'inherit',
-        env: { ...process.env },
-      });
-      void result;
-
-      // Re-read token after login
-      if (existsSync(GMTR_JSON)) {
-        const data = readJson(GMTR_JSON);
-        if (data.token) token = data.token;
-      }
-    }
-
-    if (!token) {
-      log('  Authentication skipped — run /gmtr-login later to authenticate');
-    }
+  // OAuth-first via shared helper (issue #484). The helper handles env vars,
+  // stored tokens, and spawning gmtr-login.ts when interactive. It throws a
+  // clean actionable error in headless environments.
+  let token = '';
+  try {
+    token = await resolveAuthToken({
+      interactive: isInteractive,
+      installerLabel: 'Claude Code',
+    });
+  } catch (e: any) {
     log('');
-  } else if (!token) {
+    log(e?.message || String(e));
     log('');
-    log('Non-interactive: no auth token. Set GMTR_TOKEN env var or run gmtr-login after install.');
+    log('Authentication skipped — run `gramatr login` later to authenticate');
     log('');
   }
 

package/bin/logout.ts

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * gramatr logout — Clear stored gramatr credentials (issue #484).
+ *
+ * Removes ~/.gmtr.json. With --keep-backup, renames it to
+ * ~/.gmtr.json.bak.<timestamp> instead of deleting.
+ *
+ * Not-logged-in is not an error: exits 0 with a clean message.
+ */
+
+import { existsSync, renameSync, unlinkSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+function gmtrJsonPath(): string {
+  return join(process.env.HOME || process.env.USERPROFILE || homedir(), ".gmtr.json");
+}
+
+function log(msg: string = ""): void {
+  process.stdout.write(`${msg}\n`);
+}
+
+function parseArgs(argv: string[]): { keepBackup: boolean; help: boolean } {
+  let keepBackup = false;
+  let help = false;
+  for (const a of argv) {
+    if (a === "--keep-backup") keepBackup = true;
+    else if (a === "--help" || a === "-h") help = true;
+  }
+  return { keepBackup, help };
+}
+
+function showHelp(): void {
+  log(`gramatr logout — Clear stored gramatr credentials
+
+Usage:
+  gramatr logout                Delete ~/.gmtr.json
+  gramatr logout --keep-backup  Rename to ~/.gmtr.json.bak.<timestamp> instead`);
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+  const opts = parseArgs(argv);
+  if (opts.help) {
+    showHelp();
+    return 0;
+  }
+
+  if (!existsSync(gmtrJsonPath())) {
+    log("Not logged in.");
+    return 0;
+  }
+
+  if (opts.keepBackup) {
+    const backup = `${gmtrJsonPath()}.bak.${Date.now()}`;
+    renameSync(gmtrJsonPath(), backup);
+    log(`Logged out. Token moved to ${backup}.`);
+    return 0;
+  }
+
+  unlinkSync(gmtrJsonPath());
+  log(`Logged out. Token removed from ${gmtrJsonPath()}.`);
+  return 0;
+}
+
+const isDirect = (() => {
+  try {
+    const invoked = process.argv[1] || "";
+    return invoked.endsWith("logout.ts") || invoked.endsWith("logout.js");
+  } catch {
+    return false;
+  }
+})();
+
+if (isDirect) {
+  process.exit(main());
+}

package/chatgpt/install.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
-import { dirname, join } from 'path';
+import { dirname } from 'path';
 import { homedir } from 'os';
 import {
   getChatGPTConfigPath,
@@ -9,6 +9,7 @@ import {
   buildMcpServerEntry,
   type ChatGPTConfig,
 } from './lib/chatgpt-install-utils.ts';
+import { resolveAuthToken } from '../core/auth.ts';
 
 const DEFAULT_MCP_URL = 'https://mcp.gramatr.com/mcp';
 const VALIDATION_ENDPOINT = 'https://api.gramatr.com/health';
@@ -26,43 +27,6 @@ function readJsonFile<T>(path: string, fallback: T): T {
   }
 }
 
-/**
- * Resolve API key from available sources.
- * Priority: CLI arg > GRAMATR_API_KEY env > ~/.gmtr.json token > gmtr-client/settings.json
- */
-function resolveApiKey(): string | null {
-  const home = homedir();
-
-  // 1. GRAMATR_API_KEY env var
-  if (process.env.GRAMATR_API_KEY) return process.env.GRAMATR_API_KEY;
-
-  // 2. GMTR_TOKEN env var (legacy compat)
-  if (process.env.GMTR_TOKEN) return process.env.GMTR_TOKEN;
-
-  // 3. ~/.gmtr.json
-  try {
-    const gmtrJsonPath = join(home, '.gmtr.json');
-    const gmtrJson = JSON.parse(readFileSync(gmtrJsonPath, 'utf8'));
-    if (gmtrJson.token) return gmtrJson.token;
-  } catch {
-    // Not found or parse error
-  }
-
-  // 4. ~/gmtr-client/settings.json
-  try {
-    const gmtrDir = process.env.GMTR_DIR || join(home, 'gmtr-client');
-    const settingsPath = join(gmtrDir, 'settings.json');
-    const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
-    if (settings.auth?.api_key && settings.auth.api_key !== 'REPLACE_WITH_YOUR_API_KEY') {
-      return settings.auth.api_key;
-    }
-  } catch {
-    // Not found or parse error
-  }
-
-  return null;
-}
-
 /**
  * Validate token against gramatr server health endpoint.
  * Returns true if server is reachable (we don't enforce auth for install — server validates on use).
@@ -80,18 +44,6 @@ async function validateServer(serverUrl: string): Promise<boolean> {
   }
 }
 
-async function promptForInput(prompt: string): Promise<string> {
-  process.stdout.write(prompt);
-  const reader = process.stdin;
-  reader.resume();
-  return new Promise((resolve) => {
-    reader.once('data', (data) => {
-      reader.pause();
-      resolve(data.toString().trim());
-    });
-  });
-}
-
 async function main(): Promise<void> {
   const home = homedir();
   const platform = process.platform;
@@ -101,22 +53,13 @@ async function main(): Promise<void> {
   log('====================================');
   log('');
 
-  // Step 1: Resolve auth
+  // Step 1: Resolve auth (OAuth-first via shared helper — issue #484)
   log('Step 1: Resolving authentication...');
-  let apiKey = resolveApiKey();
-
-  if (!apiKey) {
-    log('  No API key found in ~/.gmtr.json, GRAMATR_API_KEY env, or gmtr-client/settings.json.');
-    apiKey = await promptForInput('  Enter your gramatr API key: ');
-    if (!apiKey) {
-      log('');
-      log('ERROR: API key is required. Get one at https://gramatr.com/settings');
-      log('  Or set GRAMATR_API_KEY environment variable before running this installer.');
-      process.exit(1);
-    }
-  } else {
-    log('  OK Found existing API key');
-  }
+  const apiKey = await resolveAuthToken({
+    interactive: true,
+    installerLabel: 'ChatGPT Desktop',
+  });
+  log('  OK Authenticated');
 
   // Step 2: Validate server connectivity
   log('');

package/core/auth.ts

@@ -0,0 +1,170 @@
+/**
+ * Shared installer auth helper — OAuth-first credential resolution.
+ *
+ * Issue #484: Eliminates the paste-API-key prompt from installer flows.
+ * The only interactive auth path is OAuth via gmtr-login.ts. API key
+ * management is handled by the explicit `gramatr add-api-key` subcommand.
+ *
+ * Resolution chain (first non-empty wins):
+ *   1. GRAMATR_API_KEY env var
+ *   2. GMTR_TOKEN env var (legacy)
+ *   3. ~/.gmtr.json `token` field
+ *   4. ~/gmtr-client/settings.json `auth.api_key` (legacy, skips placeholder)
+ *   5. If interactive + TTY: spawn gmtr-login.ts (OAuth)
+ *   6. Otherwise: throw clean actionable error
+ *
+ * This helper NEVER prompts for paste. If you need to add an API key,
+ * use `gramatr add-api-key` (interactive / piped / --from-env).
+ */
+
+import { spawnSync } from "child_process";
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+export interface ResolveAuthTokenOptions {
+  interactive: boolean;
+  installerLabel: string;
+}
+
+const PLACEHOLDER_KEY = "REPLACE_WITH_YOUR_API_KEY";
+
+function readJsonSafe(path: string): Record<string, any> | null {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function getHome(): string {
+  return process.env.HOME || process.env.USERPROFILE || homedir();
+}
+
+function gmtrJsonPath(): string {
+  return join(getHome(), ".gmtr.json");
+}
+
+function legacySettingsPath(): string {
+  const gmtrDir = process.env.GMTR_DIR || join(getHome(), "gmtr-client");
+  return join(gmtrDir, "settings.json");
+}
+
+function tokenFromEnv(): string | null {
+  if (process.env.GRAMATR_API_KEY) return process.env.GRAMATR_API_KEY;
+  if (process.env.GMTR_TOKEN) return process.env.GMTR_TOKEN;
+  return null;
+}
+
+function tokenFromGmtrJson(): string | null {
+  const data = readJsonSafe(gmtrJsonPath());
+  if (data && typeof data.token === "string" && data.token.trim()) {
+    return data.token.trim();
+  }
+  return null;
+}
+
+function tokenFromLegacySettings(): string | null {
+  const data = readJsonSafe(legacySettingsPath());
+  if (!data) return null;
+  const key = data.auth?.api_key;
+  if (typeof key === "string" && key && key !== PLACEHOLDER_KEY) {
+    return key;
+  }
+  return null;
+}
+
+function findGmtrLoginScript(): string | null {
+  // Resolve gmtr-login.ts relative to this file. In source layout it's at
+  // ../bin/gmtr-login.ts; in installed layout the same relative path holds.
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidate = join(here, "..", "bin", "gmtr-login.ts");
+    if (existsSync(candidate)) return candidate;
+  } catch {
+    // ignore
+  }
+  // Fallback to installed client dir
+  const installedCandidate = join(
+    process.env.GMTR_DIR || join(getHome(), "gmtr-client"),
+    "bin",
+    "gmtr-login.ts",
+  );
+  if (existsSync(installedCandidate)) return installedCandidate;
+  return null;
+}
+
+function spawnOAuthLogin(): { ok: boolean; reason?: string } {
+  const script = findGmtrLoginScript();
+  if (!script) {
+    return { ok: false, reason: "gmtr-login.ts not found on disk" };
+  }
+  // Match the existing handleAuth() pattern in bin/install.ts:383-401 —
+  // npx tsx with inherited stdio so the browser-open message reaches
+  // the user and stdin works correctly.
+  const npxBin = process.platform === "win32" ? "npx.cmd" : "npx";
+  const result = spawnSync(npxBin, ["tsx", script], {
+    stdio: "inherit",
+    env: { ...process.env },
+  });
+  if (result.error) {
+    return { ok: false, reason: result.error.message };
+  }
+  if (typeof result.status === "number" && result.status !== 0) {
+    return { ok: false, reason: `gmtr-login exited with code ${result.status}` };
+  }
+  return { ok: true };
+}
+
+const HEADLESS_ERROR =
+  "No gramatr credentials found. Set one of:\n" +
+  "  - GRAMATR_API_KEY environment variable\n" +
+  "  - Run: gramatr login            (interactive, recommended)\n" +
+  "  - Run: gramatr add-api-key      (for headless / CI use)\n" +
+  "Then re-run the install.";
+
+const OAUTH_FAILED_ERROR =
+  'OAuth login failed. Run "gramatr login" to retry, ' +
+  'or "gramatr add-api-key" to use an API key instead.';
+
+/**
+ * Resolve a gramatr auth token, OAuth-first.
+ *
+ * Never prompts for an API key paste. If interactive and no token is
+ * stored, spawns gmtr-login.ts to run the OAuth flow. If headless or
+ * non-interactive, throws an actionable error pointing the user at the
+ * explicit `gramatr login` and `gramatr add-api-key` commands.
+ */
+export async function resolveAuthToken(opts: ResolveAuthTokenOptions): Promise<string> {
+  // 1 + 2: env vars
+  const envToken = tokenFromEnv();
+  if (envToken) return envToken;
+
+  // 3: ~/.gmtr.json
+  const stored = tokenFromGmtrJson();
+  if (stored) return stored;
+
+  // 4: legacy settings.json
+  const legacy = tokenFromLegacySettings();
+  if (legacy) return legacy;
+
+  // 5: spawn OAuth if interactive + TTY
+  const hasTty = Boolean(process.stdin.isTTY);
+  if (opts.interactive && hasTty) {
+    process.stdout.write(
+      `[${opts.installerLabel}] No gramatr credentials found. Starting OAuth login...\n`,
+    );
+    const result = spawnOAuthLogin();
+    if (!result.ok) {
+      throw new Error(OAUTH_FAILED_ERROR);
+    }
+    const after = tokenFromGmtrJson();
+    if (after) return after;
+    throw new Error("OAuth completed but no token was stored");
+  }
+
+  // 6: headless / non-interactive — clean actionable error
+  throw new Error(HEADLESS_ERROR);
+}

package/desktop/install.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
-import { dirname, join } from 'path';
+import { dirname } from 'path';
 import { homedir } from 'os';
 import {
   getDesktopConfigPath,
@@ -9,6 +9,7 @@ import {
   buildMcpServerEntry,
   type DesktopConfig,
 } from './lib/desktop-install-utils.ts';
+import { resolveAuthToken } from '../core/auth.ts';
 
 const DEFAULT_MCP_URL = 'https://mcp.gramatr.com/mcp';
 const VALIDATION_ENDPOINT = 'https://api.gramatr.com/health';
@@ -26,43 +27,6 @@ function readJsonFile<T>(path: string, fallback: T): T {
   }
 }
 
-/**
- * Resolve API key from available sources.
- * Priority: CLI arg > GRAMATR_API_KEY env > ~/.gmtr.json token > gmtr-client/settings.json
- */
-function resolveApiKey(): string | null {
-  const home = homedir();
-
-  // 1. GRAMATR_API_KEY env var
-  if (process.env.GRAMATR_API_KEY) return process.env.GRAMATR_API_KEY;
-
-  // 2. GMTR_TOKEN env var (legacy compat)
-  if (process.env.GMTR_TOKEN) return process.env.GMTR_TOKEN;
-
-  // 3. ~/.gmtr.json
-  try {
-    const gmtrJsonPath = join(home, '.gmtr.json');
-    const gmtrJson = JSON.parse(readFileSync(gmtrJsonPath, 'utf8'));
-    if (gmtrJson.token) return gmtrJson.token;
-  } catch {
-    // Not found or parse error
-  }
-
-  // 4. ~/gmtr-client/settings.json
-  try {
-    const gmtrDir = process.env.GMTR_DIR || join(home, 'gmtr-client');
-    const settingsPath = join(gmtrDir, 'settings.json');
-    const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
-    if (settings.auth?.api_key && settings.auth.api_key !== 'REPLACE_WITH_YOUR_API_KEY') {
-      return settings.auth.api_key;
-    }
-  } catch {
-    // Not found or parse error
-  }
-
-  return null;
-}
-
 /**
  * Validate token against gramatr server health endpoint.
  * Returns true if server is reachable (we don't enforce auth for install — server validates on use).
@@ -80,18 +44,6 @@ async function validateServer(serverUrl: string): Promise<boolean> {
   }
 }
 
-async function promptForInput(prompt: string): Promise<string> {
-  process.stdout.write(prompt);
-  const reader = process.stdin;
-  reader.resume();
-  return new Promise((resolve) => {
-    reader.once('data', (data) => {
-      reader.pause();
-      resolve(data.toString().trim());
-    });
-  });
-}
-
 async function main(): Promise<void> {
   const home = homedir();
   const platform = process.platform;
@@ -101,22 +53,13 @@ async function main(): Promise<void> {
   log('===================================');
   log('');
 
-  // Step 1: Resolve auth
+  // Step 1: Resolve auth (OAuth-first via shared helper — issue #484)
   log('Step 1: Resolving authentication...');
-  let apiKey = resolveApiKey();
-
-  if (!apiKey) {
-    log('  No API key found in ~/.gmtr.json, GRAMATR_API_KEY env, or gmtr-client/settings.json.');
-    apiKey = await promptForInput('  Enter your gramatr API key: ');
-    if (!apiKey) {
-      log('');
-      log('ERROR: API key is required. Get one at https://gramatr.com/settings');
-      log('  Or set GRAMATR_API_KEY environment variable before running this installer.');
-      process.exit(1);
-    }
-  } else {
-    log('  OK Found existing API key');
-  }
+  const apiKey = await resolveAuthToken({
+    interactive: true,
+    installerLabel: 'Claude Desktop',
+  });
+  log('  OK Authenticated');
 
   // Step 2: Validate server connectivity
   log('');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gramatr",
-  "version": "0.3.57",
+  "version": "0.3.58",
   "description": "grāmatr — context engineering layer for AI coding agents. Every prompt gets a pre-computed intelligence packet: decision routing, capability audit, behavioral directives, memory pre-load, and ISC scaffolds. Continuity across sessions for Claude Code, Codex, and Gemini CLI.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {