@gramatr/client 0.5.1

package/AGENTS.md

@@ -0,0 +1,17 @@
+# Gramatr Codex Guidance
+
+## Repo Expectations
+
+- Prefer gramatr memory and project handoff context over ad hoc local summaries.
+- Treat Codex hook augmentation as authoritative when a `[GMTR Intelligence]` block is present.
+- If gramatr augmentation is missing, query gramatr memory before relying on stale local notes.
+- Prefer TypeScript implementations over shell scripts for client integration code unless the platform requires shell.
+- Maintain test coverage for new hook and utility logic.
+
+## Codex Integration
+
+- Repo-local Codex hooks are configured in `.codex/hooks.json`.
+- `UserPromptSubmit` is responsible for prompt enrichment.
+- `SessionStart` is responsible for session restore and continuity.
+- Hook failures must degrade cleanly and never block the user session.
+

package/CLAUDE.md

@@ -0,0 +1,18 @@
+<!-- GMTR-START — Do not edit between these markers. Managed by gramatr installer. -->
+# gramatr
+
+You have gramatr installed. A hook pre-classifies every user request and injects
+intelligence as `[GMTR Intelligence — ...]` into your context.
+
+**Follow the intelligence packet.** It contains behavioral directives, effort level,
+ISC scaffold, capability audit, phase templates, and composed agents.
+
+**Memory:** Use gramatr MCP tools (`search_semantic`, `create_entity`, `add_observation`),
+not local markdown files.
+
+**Identity:** Read from `~/gmtr-client/settings.json` — `daidentity` for your name,
+`principal` for the user's name.
+
+**If the server is unreachable:** Use 7-phase structure (OBSERVE → THINK → PLAN → BUILD →
+EXECUTE → VERIFY → LEARN). Create ISC before work. Never combine phases.
+<!-- GMTR-END -->

package/README.md

@@ -0,0 +1,108 @@
+# gramatr
+
+**Intelligence layer for AI coding agents.** Pre-classifies every request so Claude Code, Codex, and Gemini CLI spend tokens on your work, not on routing overhead.
+
+## What it does
+
+gramatr sits between you and your AI agent. Before the agent sees your prompt, gramatr's decision router (BERT classifiers running in <5ms) pre-classifies:
+
+- **Effort level** — instant, fast, standard, extended, advanced, deep, comprehensive
+- **Intent type** — search, retrieve, create, update, analyze, generate
+- **Skill matching** — which of 25 capabilities are relevant
+- **Memory tier** — what context to pre-load from your knowledge graph
+- **Reverse engineering** — what you want, what you don't want, gotchas
+
+The agent receives this as a pre-computed intelligence packet, saving ~2,700 tokens per request that would otherwise be spent on the agent figuring out what you need.
+
+## Install
+
+```bash
+npx @gramatr/client install claude-code
+```
+
+That's it. One command installs hooks, registers the MCP server, and configures your AI agent.
+
+### Non-interactive (CI, remote provisioning)
+
+```bash
+npx @gramatr/client install claude-code --yes --name "Your Name" --timezone "America/Chicago"
+```
+
+### Supported platforms
+
+| Platform | Status | Install |
+|---|---|---|
+| Claude Code | Stable | `npx @gramatr/client install claude-code` |
+| OpenAI Codex | Stable | Auto-detected during install |
+| Google Gemini CLI | Stable | Auto-detected during install |
+| Claude Desktop | Coming soon | — |
+| ChatGPT Desktop | Coming soon | — |
+
+## How it works
+
+```
+You type a prompt
+  |
+gramatr hooks intercept (UserPromptSubmit)
+  |
+Decision router classifies in <5ms (BERT on GPU)
+  |
+Intelligence packet injected into agent context
+  |
+Agent receives pre-classified request
+  = skips routing overhead
+  = starts working immediately
+  = saves ~2,700 tokens per request
+```
+
+### The flywheel
+
+Every interaction trains the classifier. Memory powers routing, routing generates patterns, patterns improve routing. The system gets smarter with use.
+
+## Architecture
+
+gramatr is a thin client + smart server:
+
+- **Client** (this package): 29 files, ~290KB. Hooks into your AI agent, forwards to server.
+- **Server**: Decision routing engine (BERT + Qwen), knowledge graph (PostgreSQL + pgvector), pattern learning.
+- **Protocol**: MCP (Model Context Protocol) for Claude Code/Codex, REST API for web/mobile.
+
+The client never stores intelligence locally. The server delivers everything: behavioral rules, skill routing, agent composition, ISC scaffolds, capability audits.
+
+## What gets installed
+
+```
+~/gmtr-client/          # Client runtime
+  hooks/                # 8 lifecycle hooks
+  core/                 # Shared routing + session logic
+  bin/                  # Status line, login, utilities
+  CLAUDE.md             # Minimal behavioral framework
+~/.claude/settings.json # Hook configuration (merged, not overwritten)
+~/.claude.json          # MCP server registration
+~/.gmtr.json            # Auth token (canonical source)
+```
+
+## Commands
+
+```bash
+gramatr install          # Interactive target selection
+gramatr install claude-code  # Install for Claude Code
+gramatr detect           # Show detected AI platforms
+gramatr doctor           # Health check (coming soon)
+gramatr uninstall        # Clean removal
+gramatr --version        # Show version
+```
+
+## Requirements
+
+- Node.js 20+
+- One of: Claude Code, OpenAI Codex, Google Gemini CLI
+
+## Links
+
+- [gramatr.com](https://gramatr.com)
+- [GitHub](https://github.com/gramatr/gramatr)
+
+## License
+
+MIT

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/clean-legacy-install.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+import { join } from 'path';
+import { runLegacyMigration } from '../core/migration.ts';
+
+function log(message: string): void {
+  process.stdout.write(`${message}\n`);
+}
+
+function main(): void {
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (!home) {
+    throw new Error('HOME is not set');
+  }
+
+  const apply = process.argv.includes('--apply');
+  const includeOptionalUx = process.env.GMTR_ENABLE_OPTIONAL_CLAUDE_UX === '1';
+  const clientDir = process.env.GMTR_DIR || join(home, 'gmtr-client');
+  runLegacyMigration({
+    homeDir: home,
+    clientDir,
+    includeOptionalUx,
+    apply,
+    log,
+  });
+}
+
+main();

package/bin/clear-creds.ts

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * gramatr clear-creds — Nuke ALL stored gramatr credentials.
+ *
+ * Stronger than `gramatr logout` (which only removes ~/.gmtr.json).
+ * This sweeps every credential location in the resolveAuthToken chain
+ * (core/auth.ts), so the next install/login is forced through OAuth.
+ *
+ * Locations cleared:
+ *   1. ~/.gmtr.json                              — deleted entirely
+ *   2. ~/gmtr-client/settings.json `auth.api_key` — stripped, file preserved
+ *
+ * Env vars (GRAMATR_API_KEY, GMTR_TOKEN) cannot be cleared from a child
+ * process — they live in the parent shell. We detect them and warn.
+ *
+ * Not-logged-in is not an error: exits 0 with a clean message.
+ */
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+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 log(msg: string = ""): void {
+  process.stdout.write(`${msg}\n`);
+}
+
+function showHelp(): void {
+  log(`gramatr clear-creds — Remove every stored gramatr credential
+
+Usage:
+  gramatr clear-creds   Sweep ~/.gmtr.json + auth.api_key from gmtr-client/settings.json
+
+After running, the next install or login will be forced through OAuth.
+
+Env vars (GRAMATR_API_KEY, GMTR_TOKEN) cannot be unset from this process.
+If they are set, this command warns and tells you the shell command to run.`);
+}
+
+interface ClearResult {
+  removedGmtrJson: boolean;
+  strippedLegacyKey: boolean;
+  envVarsSet: string[];
+}
+
+export function clearAll(): ClearResult {
+  const result: ClearResult = {
+    removedGmtrJson: false,
+    strippedLegacyKey: false,
+    envVarsSet: [],
+  };
+
+  // 1. ~/.gmtr.json — delete entirely
+  const gj = gmtrJsonPath();
+  if (existsSync(gj)) {
+    unlinkSync(gj);
+    result.removedGmtrJson = true;
+  }
+
+  // 2. ~/gmtr-client/settings.json — strip auth.api_key, preserve rest
+  const ls = legacySettingsPath();
+  if (existsSync(ls)) {
+    try {
+      const data = JSON.parse(readFileSync(ls, "utf8"));
+      if (data && data.auth && typeof data.auth === "object" && "api_key" in data.auth) {
+        delete data.auth.api_key;
+        // If auth is now empty, remove it too to keep the file tidy
+        if (Object.keys(data.auth).length === 0) delete data.auth;
+        writeFileSync(ls, `${JSON.stringify(data, null, 2)}\n`);
+        result.strippedLegacyKey = true;
+      }
+    } catch {
+      // malformed JSON — leave it alone, user can fix manually
+    }
+  }
+
+  // 3. Env vars — detect only, cannot mutate parent shell
+  for (const v of ["GRAMATR_API_KEY", "GMTR_TOKEN"]) {
+    if (process.env[v]) result.envVarsSet.push(v);
+  }
+
+  return result;
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    showHelp();
+    return 0;
+  }
+
+  const r = clearAll();
+
+  if (!r.removedGmtrJson && !r.strippedLegacyKey && r.envVarsSet.length === 0) {
+    log("No stored credentials found. Already fully cleared.");
+    return 0;
+  }
+
+  if (r.removedGmtrJson) log(`Removed ${gmtrJsonPath()}`);
+  if (r.strippedLegacyKey) log(`Stripped auth.api_key from ${legacySettingsPath()}`);
+
+  if (r.envVarsSet.length > 0) {
+    log("");
+    log(`WARNING: the following env vars are still set in your shell:`);
+    for (const v of r.envVarsSet) log(`  ${v}`);
+    log("");
+    log("These take precedence over file-based credentials. To clear them:");
+    log(`  unset ${r.envVarsSet.join(" ")}        # bash/zsh`);
+    log(`  Remove-Item Env:${r.envVarsSet.join(", Env:")}    # PowerShell`);
+    log("");
+    log("Until then, the next install will still resolve a token from the env.");
+    return 0;
+  }
+
+  log("");
+  log("All credentials cleared. Next 'gramatr login' or 'gramatr install' will use OAuth.");
+  return 0;
+}
+
+const isDirect = (() => {
+  try {
+    const invoked = process.argv[1] || "";
+    return invoked.endsWith("clear-creds.ts") || invoked.endsWith("clear-creds.js");
+  } catch {
+    return false;
+  }
+})();
+
+if (isDirect) {
+  process.exit(main());
+}

package/bin/get-token.py

@@ -0,0 +1,3 @@
+import json, os
+s = os.path.expanduser("~/gmtr-client/settings.json")
+print(json.load(open(s)).get("auth",{}).get("api_key",""))