@gramatr/client 0.5.1

package/core/version-check.ts

@@ -0,0 +1,219 @@
+/**
+ * version-check.ts — opportunistic npm registry version check.
+ *
+ * Queries https://registry.npmjs.org/gramatr/latest on a 3s timeout, caches
+ * the result for one hour under ~/.gmtr-client/.cache/version-check.json, and
+ * reports whether the installed client is behind the published version.
+ *
+ * Design constraints (see issue #468 sibling work):
+ *   - Never throws. Any failure returns null and the caller proceeds normally.
+ *   - Never writes to stdout — stdout is Claude Code's context channel.
+ *   - Fast cache-hit path (no network, no heavy work).
+ *   - Zero new runtime dependencies. Uses global fetch (Node 18+).
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { homedir } from 'os';
+
+const REGISTRY_URL = 'https://registry.npmjs.org/gramatr/latest';
+const FETCH_TIMEOUT_MS = 3000;
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+
+export interface VersionCheckResult {
+  latestVersion: string;
+  installedVersion: string;
+  isOutdated: boolean;
+  cached: boolean;
+}
+
+interface CacheFile {
+  latestVersion: string;
+  fetchedAt: number;
+  lastNotifiedVersion?: string;
+}
+
+/**
+ * Compare two semver-style version strings ("X.Y.Z").
+ * Returns:
+ *   -1 if a < b
+ *    0 if a === b
+ *    1 if a > b
+ *
+ * Non-numeric or missing segments are treated as 0.
+ */
+export function compareVersions(a: string, b: string): number {
+  const pa = a.split('.').map((x) => parseInt(x, 10) || 0);
+  const pb = b.split('.').map((x) => parseInt(x, 10) || 0);
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const av = pa[i] ?? 0;
+    const bv = pb[i] ?? 0;
+    if (av < bv) return -1;
+    if (av > bv) return 1;
+  }
+  return 0;
+}
+
+export function getCachePath(home: string = homedir()): string {
+  return join(home, '.gmtr-client', '.cache', 'version-check.json');
+}
+
+function readCache(path: string): CacheFile | null {
+  try {
+    if (!existsSync(path)) return null;
+    const raw = readFileSync(path, 'utf8');
+    const parsed = JSON.parse(raw) as CacheFile;
+    if (typeof parsed.latestVersion !== 'string' || typeof parsed.fetchedAt !== 'number') {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(path: string, data: CacheFile): void {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(data, null, 2) + '\n', 'utf8');
+  } catch {
+    // Cache is best-effort. Silent failure is acceptable.
+  }
+}
+
+async function fetchLatestVersion(): Promise<string | null> {
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+      const res = await fetch(REGISTRY_URL, {
+        signal: controller.signal,
+        headers: { Accept: 'application/json' },
+      });
+      if (!res.ok) return null;
+      const body = (await res.json()) as { version?: string };
+      if (typeof body?.version !== 'string') return null;
+      return body.version;
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check the installed version against the latest published on npm.
+ * Returns null on any failure — callers must treat this as optional.
+ */
+export async function checkLatestVersion(
+  installedVersion: string,
+  options: { cachePath?: string; now?: number } = {},
+): Promise<VersionCheckResult | null> {
+  try {
+    const cachePath = options.cachePath ?? getCachePath();
+    const now = options.now ?? Date.now();
+
+    const cached = readCache(cachePath);
+    if (cached && now - cached.fetchedAt < CACHE_TTL_MS) {
+      return {
+        latestVersion: cached.latestVersion,
+        installedVersion,
+        isOutdated: compareVersions(cached.latestVersion, installedVersion) > 0,
+        cached: true,
+      };
+    }
+
+    const latestVersion = await fetchLatestVersion();
+    if (!latestVersion) return null;
+
+    writeCache(cachePath, {
+      latestVersion,
+      fetchedAt: now,
+      lastNotifiedVersion: cached?.lastNotifiedVersion,
+    });
+
+    return {
+      latestVersion,
+      installedVersion,
+      isOutdated: compareVersions(latestVersion, installedVersion) > 0,
+      cached: false,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Record that the user has been notified for a given latest version.
+ * Suppresses repeat notifications until a newer version is published.
+ */
+export function markNotified(latestVersion: string, cachePath: string = getCachePath()): void {
+  try {
+    const current = readCache(cachePath);
+    if (!current) return;
+    writeCache(cachePath, { ...current, lastNotifiedVersion: latestVersion });
+  } catch {
+    // Best-effort.
+  }
+}
+
+export function shouldNotify(
+  result: VersionCheckResult,
+  cachePath: string = getCachePath(),
+): boolean {
+  if (!result.isOutdated) return false;
+  const cached = readCache(cachePath);
+  if (cached?.lastNotifiedVersion === result.latestVersion) return false;
+  return true;
+}
+
+/**
+ * Format the upgrade notification banner. Caller decides where to write it
+ * (must be stderr — stdout is reserved for Claude context).
+ */
+export function formatUpgradeNotification(installed: string, latest: string): string {
+  const bar = '\u2501'.repeat(60);
+  return [
+    bar,
+    '  gramatr update available',
+    '',
+    `  Installed: ${installed}`,
+    `  Latest:    ${latest}`,
+    '',
+    '  To upgrade:',
+    '    1. Type /exit to leave Claude Code',
+    '    2. Run: npx gramatr@latest install claude-code',
+    '    3. Restart: claude --resume',
+    '',
+    "  Why restart? gramatr's hooks are loaded by Claude Code at",
+    '  session start. New hook code requires a fresh session.',
+    bar,
+    '',
+  ].join('\n');
+}
+
+/**
+ * One-shot helper for hooks: check and, if appropriate, print the
+ * notification to stderr. Safe to call from any hook — never throws,
+ * never blocks longer than FETCH_TIMEOUT_MS in the cache-miss path.
+ */
+export async function runVersionCheckAndNotify(
+  installedVersion: string,
+  options: { cachePath?: string; stream?: NodeJS.WritableStream } = {},
+): Promise<VersionCheckResult | null> {
+  const stream = options.stream ?? process.stderr;
+  const cachePath = options.cachePath ?? getCachePath();
+  const result = await checkLatestVersion(installedVersion, { cachePath });
+  if (!result) return null;
+  if (shouldNotify(result, cachePath)) {
+    try {
+      stream.write(formatUpgradeNotification(result.installedVersion, result.latestVersion));
+    } catch {
+      // Silent — never break the hook.
+    }
+    markNotified(result.latestVersion, cachePath);
+  }
+  return result;
+}

package/core/version.ts

@@ -0,0 +1,47 @@
+/**
+ * version.ts — runtime resolution of the installed gramatr version.
+ *
+ * Reads `version` from the nearest package.json walking up from this module's
+ * location. package.json is the SINGLE source of truth — it's the file the
+ * version-bump process already updates, so there is zero possibility of drift.
+ *
+ * Works in two environments:
+ *   1. Source checkout: packages/client/core/version.ts →
+ *      packages/client/package.json (found one directory up).
+ *   2. Installed client: ~/gmtr-client/core/version.ts →
+ *      ~/gmtr-client/package.json (copied by installClientFiles()).
+ *
+ * If the file cannot be resolved (unexpected layout), falls back to '0.0.0'
+ * rather than throwing — the version check is opportunistic and must never
+ * break the hook.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+function findPackageJson(startDir: string): string | null {
+  let dir = startDir;
+  for (let i = 0; i < 5; i++) {
+    const candidate = join(dir, 'package.json');
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+export function resolveVersion(): string {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkgPath = findPackageJson(here);
+    if (!pkgPath) return '0.0.0';
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as { version?: string };
+    return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+export const VERSION: string = resolveVersion();

package/desktop/README.md

@@ -0,0 +1,72 @@
+# gramatr - Claude Desktop Integration
+
+Claude Desktop is a **Tier 3** integration target: MCP only, no hooks.
+
+gramatr connects to Claude Desktop via StreamableHTTP MCP transport. All intelligence (decision routing, memory, pattern learning) runs server-side.
+
+## Installation
+
+```bash
+# Interactive installer — resolves auth, detects platform, merges config
+bun packages/client/desktop/install.ts
+```
+
+The installer:
+1. Resolves your API key from `~/.gmtr.json`, `GRAMATR_API_KEY` env, or prompts
+2. Validates connectivity to the gramatr server
+3. Detects platform (macOS or Windows)
+4. Reads existing `claude_desktop_config.json` without overwriting other MCP servers
+5. Writes the gramatr MCP server entry
+
+### Config Locations
+
+| Platform | Path |
+|----------|------|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+
+### Manual Setup
+
+If you prefer to configure manually, add this to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "gramatr": {
+      "url": "https://mcp.gramatr.com/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+## .mcpb Package
+
+Build a `.mcpb` extension package for distribution:
+
+```bash
+bun packages/client/desktop/build-mcpb.ts
+# Output: dist/gramatr.mcpb/manifest.json
+```
+
+The `.mcpb` format follows [Anthropic's manifest v0.3 spec](https://github.com/anthropics/mcpb/blob/main/MANIFEST.md).
+
+## What Works
+
+Claude Desktop gets full access to gramatr's MCP tools:
+- Semantic search, entity management, knowledge graph
+- Decision routing, skill matching, pattern learning
+- Session state, handoffs, reflections
+
+## What Does Not Work
+
+Claude Desktop has no hook system, so these features are unavailable:
+- PreToolUse / PostToolUse hooks (security validation, algorithm tracking)
+- Session lifecycle hooks (auto session-start, session-end)
+- Prompt enrichment (intelligence packet injection)
+- Rating capture
+- Status line
+
+For the full gramatr experience, use Claude Code or Codex.

package/desktop/build-mcpb.ts

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+
+/**
+ * Build a .mcpb package for Claude Desktop.
+ *
+ * The .mcpb format (manifest v0.3) is Anthropic's extension packaging format
+ * for Claude Desktop. gramatr is a remote MCP server, so the package contains
+ * only the manifest — no local server binary.
+ *
+ * Reference: https://github.com/anthropics/mcpb/blob/main/MANIFEST.md
+ *
+ * Usage: bun desktop/build-mcpb.ts [--out <path>]
+ */
+
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const currentFile = fileURLToPath(import.meta.url);
+const desktopDir = dirname(currentFile);
+const clientDir = dirname(desktopDir);
+const packagesDir = dirname(clientDir);
+const repoRoot = dirname(packagesDir);
+
+interface McpbManifest {
+  manifest_version: string;
+  name: string;
+  display_name: string;
+  version: string;
+  description: string;
+  long_description: string;
+  author: {
+    name: string;
+    url: string;
+  };
+  homepage: string;
+  documentation: string;
+  repository: {
+    type: string;
+    url: string;
+  };
+  license: string;
+  keywords: string[];
+  server: {
+    type: string;
+    transport: string;
+    url: string;
+  };
+  user_config: Record<string, {
+    type: string;
+    title: string;
+    description: string;
+    sensitive?: boolean;
+    required: boolean;
+  }>;
+  compatibility: {
+    claude_desktop: string;
+    platforms: string[];
+  };
+  privacy_policies: string[];
+  tools_generated: boolean;
+  prompts_generated: boolean;
+}
+
+function readPackageVersion(): string {
+  try {
+    const pkgPath = join(clientDir, 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    return pkg.version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+function buildManifest(version: string): McpbManifest {
+  return {
+    manifest_version: '0.3',
+    name: 'gramatr',
+    display_name: 'gramatr',
+    version,
+    description: 'Intelligent AI middleware — decision routing, vector memory, and pattern learning for Claude Desktop.',
+    long_description: [
+      'gramatr is an intelligent middleware layer that makes Claude smarter and cheaper.',
+      'It pre-classifies every request using a lightweight model before expensive models burn tokens on routing overhead.',
+      '',
+      '**What you get:**',
+      '- Decision routing — effort level, intent, and skill classification',
+      '- Vector memory — persistent knowledge graph with semantic search',
+      '- Pattern learning — usage patterns that improve routing over time',
+      '- Token savings — ~2,700 tokens saved per request at scale',
+      '',
+      'Claude Desktop connects to the gramatr server via StreamableHTTP MCP transport.',
+      'All intelligence runs server-side — no local compute required.',
+    ].join('\n'),
+    author: {
+      name: 'gramatr',
+      url: 'https://gramatr.com',
+    },
+    homepage: 'https://gramatr.com',
+    documentation: 'https://docs.gramatr.com',
+    repository: {
+      type: 'git',
+      url: 'https://github.com/gramatr/gramatr',
+    },
+    license: 'MIT',
+    keywords: [
+      'ai',
+      'memory',
+      'routing',
+      'intelligence',
+      'mcp',
+      'knowledge-graph',
+      'vector-search',
+      'decision-routing',
+    ],
+    server: {
+      type: 'remote',
+      transport: 'streamable-http',
+      url: 'https://mcp.gramatr.com/mcp',
+    },
+    user_config: {
+      api_key: {
+        type: 'string',
+        title: 'API Key',
+        description: 'Your gramatr API key. Get one at https://gramatr.com/settings',
+        sensitive: true,
+        required: true,
+      },
+    },
+    compatibility: {
+      claude_desktop: '>=1.0.0',
+      platforms: ['darwin', 'win32'],
+    },
+    privacy_policies: ['https://gramatr.com/privacy'],
+    tools_generated: true,
+    prompts_generated: true,
+  };
+}
+
+function main(): void {
+  const args = process.argv.slice(2);
+  const outIndex = args.indexOf('--out');
+  const outDir = outIndex >= 0 && args[outIndex + 1]
+    ? args[outIndex + 1]
+    : join(repoRoot, 'dist');
+
+  const version = readPackageVersion();
+  const manifest = buildManifest(version);
+
+  // Create output directory
+  const mcpbDir = join(outDir, 'gramatr.mcpb');
+  if (!existsSync(mcpbDir)) {
+    mkdirSync(mcpbDir, { recursive: true });
+  }
+
+  // Write manifest.json
+  const manifestPath = join(mcpbDir, 'manifest.json');
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+
+  process.stdout.write(`OK Built .mcpb package\n`);
+  process.stdout.write(`   Manifest: ${manifestPath}\n`);
+  process.stdout.write(`   Version:  ${version}\n`);
+  process.stdout.write(`   Server:   ${manifest.server.url}\n`);
+}
+
+main();

package/desktop/install.ts

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname } from 'path';
+import { homedir } from 'os';
+import {
+  getDesktopConfigPath,
+  mergeDesktopConfig,
+  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';
+
+function log(message: string): void {
+  process.stdout.write(`${message}\n`);
+}
+
+function readJsonFile<T>(path: string, fallback: T): T {
+  if (!existsSync(path)) return fallback;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Validate token against gramatr server health endpoint.
+ * Returns true if server is reachable (we don't enforce auth for install — server validates on use).
+ */
+async function validateServer(serverUrl: string): Promise<boolean> {
+  try {
+    const baseUrl = serverUrl.replace(/\/mcp$/, '');
+    const response = await fetch(`${baseUrl}/health`, {
+      method: 'GET',
+      signal: AbortSignal.timeout(5000),
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+async function main(): Promise<void> {
+  const home = homedir();
+  const platform = process.platform;
+
+  log('');
+  log('gramatr - Claude Desktop installer');
+  log('===================================');
+  log('');
+
+  // Step 1: Resolve auth (OAuth-first via shared helper — issue #484)
+  log('Step 1: Resolving authentication...');
+  const apiKey = await resolveAuthToken({
+    interactive: true,
+    installerLabel: 'Claude Desktop',
+  });
+  log('  OK Authenticated');
+
+  // Step 2: Validate server connectivity
+  log('');
+  log('Step 2: Validating server connectivity...');
+  const serverUrl = process.env.GMTR_URL || DEFAULT_MCP_URL;
+  const serverReachable = await validateServer(serverUrl);
+  if (serverReachable) {
+    log(`  OK Server reachable at ${serverUrl.replace(/\/mcp$/, '')}`);
+  } else {
+    log(`  WARN Server not reachable at ${serverUrl.replace(/\/mcp$/, '')} — config will be written anyway`);
+  }
+
+  // Step 3: Detect platform and config path
+  log('');
+  log('Step 3: Detecting Claude Desktop...');
+  const configPath = getDesktopConfigPath(home, platform);
+  const configDir = dirname(configPath);
+
+  if (platform === 'darwin') {
+    log('  Platform: macOS');
+  } else if (platform === 'win32') {
+    log('  Platform: Windows');
+  } else {
+    log(`  Platform: ${platform} (Claude Desktop may not be available)`);
+  }
+  log(`  Config: ${configPath}`);
+
+  // Step 4: Read existing config
+  log('');
+  log('Step 4: Reading existing config...');
+  const existing = readJsonFile<DesktopConfig>(configPath, {});
+
+  const existingServerCount = existing.mcpServers ? Object.keys(existing.mcpServers).length : 0;
+  if (existingServerCount > 0) {
+    log(`  Found ${existingServerCount} existing MCP server(s)`);
+    if (existing.mcpServers?.gramatr) {
+      log('  Existing gramatr entry will be updated');
+    }
+  } else {
+    log('  No existing config (will create new)');
+  }
+
+  // Step 5: Merge and write config
+  log('');
+  log('Step 5: Writing config...');
+  const gramatrEntry = buildMcpServerEntry(apiKey, serverUrl);
+  const merged = mergeDesktopConfig(existing, gramatrEntry);
+
+  if (!existsSync(configDir)) {
+    mkdirSync(configDir, { recursive: true });
+    log(`  Created directory: ${configDir}`);
+  }
+
+  writeFileSync(configPath, `${JSON.stringify(merged, null, 2)}\n`, 'utf8');
+  log(`  OK Written to ${configPath}`);
+
+  // Summary
+  log('');
+  log('Installation complete.');
+  log('');
+  log('Restart Claude Desktop to connect to gramatr.');
+  log('');
+  log('What was configured:');
+  log(`  MCP server:  ${serverUrl}`);
+  log(`  Config file: ${configPath}`);
+  log('');
+  log('Note: Claude Desktop is Tier 3 (MCP only). Hooks and status line are not');
+  log('available — use Claude Code or Codex for the full gramatr experience.');
+}
+
+main().catch((err) => {
+  log(`ERROR: ${err.message}`);
+  process.exit(1);
+});