gramatr 0.3.56 → 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/README.md

@@ -0,0 +1,95 @@
+# gramatr - ChatGPT Desktop Integration
+
+Tier 3 integration: MCP only (no hooks, no status line).
+
+## Prerequisites
+
+- **ChatGPT Plus, Team, or Enterprise** subscription (free accounts do not support MCP)
+- **ChatGPT Desktop** app installed ([download](https://openai.com/chatgpt/desktop))
+- **Developer Mode** enabled in ChatGPT Desktop settings
+- A **gramatr API key** — get one at [gramatr.com/settings](https://gramatr.com/settings)
+
+## Installation
+
+### Method 1: Installer script (recommended)
+
+```bash
+cd packages/client
+bun chatgpt/install.ts
+```
+
+The installer will:
+1. Find your API key from `~/.gmtr.json`, `GRAMATR_API_KEY` env, or prompt you
+2. Validate connectivity to the gramatr server
+3. Detect your platform and locate the ChatGPT config file
+4. Merge the gramatr MCP server entry without overwriting existing servers
+5. Print verification instructions
+
+### Method 2: Environment variable
+
+```bash
+GRAMATR_API_KEY=your-key-here bun chatgpt/install.ts
+```
+
+### Method 3: Manual configuration
+
+Add to your ChatGPT MCP config file:
+
+**macOS:** `~/.chatgpt/mcp.json`
+**Windows:** `%APPDATA%\ChatGPT\mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "gramatr": {
+      "url": "https://mcp.gramatr.com/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+## Verification
+
+1. Open ChatGPT Desktop
+2. Go to **Settings > Developer > MCP Servers**
+3. Confirm "gramatr" appears in the list with a green status indicator
+4. Start a new conversation and type: "What gramatr tools are available?"
+5. ChatGPT should list the available MCP tools from the gramatr server
+
+## Config file locations
+
+| Platform | Path |
+|----------|------|
+| macOS | `~/.chatgpt/mcp.json` |
+| Windows | `%APPDATA%\ChatGPT\mcp.json` |
+
+## Limitations
+
+ChatGPT Desktop is a **Tier 3** integration:
+
+- MCP tools are available (search, create entities, route requests, etc.)
+- No PostToolUse hooks (no automatic metrics tracking)
+- No status line
+- No prompt enrichment hooks
+
+For the full gramatr experience with hooks, status line, and prompt enrichment, use Claude Code or Codex.
+
+## Troubleshooting
+
+**"gramatr" not showing in MCP servers:**
+- Ensure Developer Mode is enabled in ChatGPT Desktop settings
+- Check that the config file exists at the correct path
+- Restart ChatGPT Desktop after editing the config
+
+**Connection errors:**
+- Verify your API key is valid: `bun bin/gmtr-login.ts --status`
+- Check server health: `curl https://api.gramatr.com/health`
+- Ensure you have an active internet connection
+
+**Tools not appearing in conversation:**
+- MCP tools may take a moment to load after connecting
+- Try starting a new conversation
+- Check the MCP server status indicator in Settings > Developer