gramatr 0.3.0

package/hooks/lib/gmtr-hook-utils.ts

@@ -0,0 +1,771 @@
+/**
+ * gmtr-hook-utils.ts — Shared utilities for all gramatr hooks
+ *
+ * Provides common functions: stdin reading, git context, config management,
+ * MCP transport, auth token resolution, logging.
+ *
+ * ZERO external CLI dependencies — uses native TypeScript/Bun APIs only.
+ */
+
+import { execSync } from 'child_process';
+import { readFileSync, writeFileSync, renameSync, mkdirSync, existsSync } from 'fs';
+import { join, basename } from 'path';
+
+// ── Types ──
+
+export interface HookInput {
+  session_id: string;
+  transcript_path?: string;
+  cwd?: string;
+  permission_mode?: string;
+  hook_event_name?: string;
+  message?: string;
+  prompt?: string;
+  reason?: string;
+}
+
+export interface GitContext {
+  root: string;
+  remote: string;
+  branch: string;
+  commit: string;
+  projectName: string;
+}
+
+export interface GmtrConfig {
+  version?: string;
+  config_version?: string;
+  project_entity_id: string | null;
+  project_id?: string;
+  project_name?: string;
+  previously_known_as?: string[];
+  git_remote?: string;
+  current_session?: {
+    session_id?: string;
+    transcript_path?: string;
+    last_updated?: string;
+    token_limit?: number;
+    interaction_id?: string;
+    gmtr_entity_id?: string;
+    helper_pid?: number | null;
+    last_classification?: {
+      timestamp?: string;
+      original_prompt?: string;
+      effort_level?: string | null;
+      intent_type?: string | null;
+      confidence?: number | null;
+      classifier_model?: string | null;
+      downstream_model?: string | null;
+      client_type?: string | null;
+      agent_name?: string | null;
+      pending_feedback?: boolean;
+      feedback_submitted_at?: string | null;
+    };
+  };
+  last_compact?: {
+    timestamp?: string;
+    summary?: string;
+    turns?: unknown[];
+    metadata?: {
+      files_changed?: string[];
+      commits?: string[];
+    };
+  } | null;
+  continuity_stats?: {
+    successful_restores?: number;
+    failed_restores?: number;
+    total_sessions?: number;
+    total_compacts?: number;
+    total_clears?: number;
+    last_restore_quality?: string;
+    total_compacts_prevented?: number;
+  };
+  related_entities?: {
+    databases?: unknown[];
+    people?: unknown[];
+    services?: unknown[];
+    concepts?: unknown[];
+    projects?: unknown[];
+  };
+  last_session_id?: string;
+  metadata?: {
+    created?: string;
+    updated?: string;
+    last_session_end_reason?: string;
+  };
+  migrated_at?: string;
+}
+
+export interface MctToolCallError {
+  reason:
+    | 'auth'
+    | 'http_error'
+    | 'mcp_error'
+    | 'parse_error'
+    | 'timeout'
+    | 'network_error'
+    | 'unknown';
+  detail: string;
+  status?: number;
+}
+
+export interface MctToolCallResult<T = unknown> {
+  data: T | null;
+  error: MctToolCallError | null;
+  rawText: string | null;
+}
+
+// ── Constants ──
+
+const HOME = process.env.HOME || process.env.USERPROFILE || '';
+const DEFAULT_MCP_URL = 'https://api.gramatr.com/mcp';
+
+// ── Logging ──
+
+/** Write message to stderr (visible to user in terminal) */
+export function log(msg: string): void {
+  process.stderr.write(msg + '\n');
+}
+
+// ── Timestamps ──
+
+/** ISO timestamp in UTC */
+export function now(): string {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+
+// ── Stdin Reading ──
+
+/** Read and parse JSON from stdin (hook input) */
+export async function readHookInput(): Promise<HookInput> {
+  const chunks: Buffer[] = [];
+  await new Promise<void>((resolve) => {
+    const timeout = setTimeout(() => { process.stdin.destroy(); resolve(); }, 500);
+    process.stdin.on('data', (chunk: Buffer) => chunks.push(chunk));
+    process.stdin.on('end', () => { clearTimeout(timeout); resolve(); });
+    process.stdin.on('error', () => { clearTimeout(timeout); resolve(); });
+    process.stdin.resume();
+  });
+  const raw = Buffer.concat(chunks).toString('utf8');
+  if (!raw.trim()) return { session_id: 'unknown' };
+  return JSON.parse(raw) as HookInput;
+}
+
+// ── Git Context ──
+
+/** Get git context for current directory. Returns null if not in a git repo. */
+export function getGitContext(): GitContext | null {
+  try {
+    const isGit = execSync('git rev-parse --is-inside-work-tree', {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    if (isGit !== 'true') return null;
+
+    const root = execSync('git rev-parse --show-toplevel', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    let remote = 'no-remote';
+    try {
+      remote = execSync('git config --get remote.origin.url', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    } catch {
+      // no remote configured
+    }
+    const branch = execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    const commit = execSync('git rev-parse --short HEAD', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    const projectName = basename(root);
+
+    return { root, remote, branch, commit, projectName };
+  } catch {
+    return null;
+  }
+}
+
+// ── Project ID ──
+
+/**
+ * Derive normalized project_id from git remote URL.
+ * Handles: https://github.com/org/repo.git, git@github.com:org/repo.git, etc.
+ * Returns org/repo format, or fallback project name.
+ */
+export function deriveProjectId(gitRemote: string, fallbackName?: string): string {
+  if (!gitRemote || gitRemote === 'no-remote') {
+    return fallbackName || 'unknown';
+  }
+  const match = gitRemote.match(/[/:]([\w.-]+)\/([\w.-]+?)(?:\.git)?$/);
+  if (match) return `${match[1]}/${match[2]}`;
+  return fallbackName || 'unknown';
+}
+
+// ── Config Management ──
+
+/** Get the path to .gmtr/settings.json for a given root directory */
+export function getConfigPath(rootDir: string): string {
+  return join(rootDir, '.gmtr', 'settings.json');
+}
+
+/** Read .gmtr/settings.json. Returns null if not found or invalid. */
+export function readGmtrConfig(rootDir: string): GmtrConfig | null {
+  try {
+    const configPath = getConfigPath(rootDir);
+    if (!existsSync(configPath)) return null;
+    const raw = readFileSync(configPath, 'utf8');
+    return JSON.parse(raw) as GmtrConfig;
+  } catch {
+    return null;
+  }
+}
+
+/** Write .gmtr/settings.json atomically (write .tmp, then rename) */
+export function writeGmtrConfig(rootDir: string, config: GmtrConfig): void {
+  const configPath = getConfigPath(rootDir);
+  const tmpPath = configPath + '.tmp';
+  const dir = join(rootDir, '.gmtr');
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(tmpPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+  renameSync(tmpPath, configPath);
+}
+
+export function saveLastClassification(
+  rootDir: string,
+  classification: NonNullable<GmtrConfig['current_session']>['last_classification'],
+): void {
+  const config = readGmtrConfig(rootDir);
+  if (!config) return;
+  config.current_session = config.current_session || {};
+  config.current_session.last_classification = classification;
+  if (config.current_session.session_id && !config.last_session_id) {
+    config.last_session_id = config.current_session.session_id;
+  }
+  config.metadata = config.metadata || {};
+  config.metadata.updated = now();
+  writeGmtrConfig(rootDir, config);
+}
+
+export function markClassificationFeedbackSubmitted(rootDir: string, submittedAt: string = now()): void {
+  const config = readGmtrConfig(rootDir);
+  if (!config?.current_session?.last_classification) return;
+  config.current_session.last_classification.pending_feedback = false;
+  config.current_session.last_classification.feedback_submitted_at = submittedAt;
+  config.metadata = config.metadata || {};
+  config.metadata.updated = submittedAt;
+  writeGmtrConfig(rootDir, config);
+}
+
+/** Migrate config from v2.0 to v2.1 if needed */
+export function migrateConfig(config: GmtrConfig, projectId: string): GmtrConfig {
+  const version = config.config_version || '0';
+  if (version !== '0' && version !== 'null') {
+    // Already migrated — just ensure project_id is current
+    config.project_id = projectId;
+    return config;
+  }
+
+  log('  Migrating settings.json to v2.1...');
+
+  // Collect old identifiers
+  const oldProjectId = config.project_id || config.project_name || '';
+  const oldProjectName = config.project_name || '';
+
+  // Build previously_known_as list
+  const knownAs = new Set<string>(config.previously_known_as || []);
+  if (oldProjectId && oldProjectId !== projectId) {
+    knownAs.add(oldProjectId);
+  }
+  if (oldProjectName && oldProjectName !== projectId && oldProjectName !== oldProjectId) {
+    knownAs.add(oldProjectName);
+  }
+
+  config.config_version = '2.1';
+  config.project_id = projectId;
+  config.previously_known_as = Array.from(knownAs);
+  config.migrated_at = now();
+
+  log(`  Done migrating to v2.1 (project_id: ${projectId}, aliases: [${Array.from(knownAs).join(', ')}])`);
+
+  return config;
+}
+
+/** Create a fresh v2.1 config */
+export function createDefaultConfig(options: {
+  projectId: string;
+  projectName: string;
+  gitRemote: string;
+  sessionId: string;
+  transcriptPath: string;
+}): GmtrConfig {
+  const ts = now();
+  return {
+    version: '2.0',
+    config_version: '2.1',
+    project_entity_id: null,
+    project_id: options.projectId,
+    project_name: options.projectName,
+    previously_known_as: [],
+    git_remote: options.gitRemote,
+    current_session: {
+      session_id: options.sessionId,
+      transcript_path: options.transcriptPath,
+      last_updated: ts,
+      token_limit: 200000,
+    },
+    last_compact: null,
+    continuity_stats: {
+      successful_restores: 0,
+      failed_restores: 0,
+      total_sessions: 1,
+      total_compacts: 0,
+      total_clears: 0,
+      last_restore_quality: 'none',
+      total_compacts_prevented: 0,
+    },
+    related_entities: {
+      databases: [],
+      people: [],
+      services: [],
+      concepts: [],
+      projects: [],
+    },
+    last_session_id: options.sessionId,
+    metadata: {
+      created: ts,
+      updated: ts,
+      last_session_end_reason: 'new',
+    },
+  };
+}
+
+// ── Auth Token Resolution ──
+
+/**
+ * Resolve auth token. gramatr credentials NEVER live in CLI-specific config files.
+ *
+ * Priority:
+ *   1. ~/.gmtr.json (canonical, gramatr-owned, vendor-agnostic)
+ *   2. GMTR_TOKEN env var (CI, headless override)
+ *   3. ~/gmtr-client/settings.json auth.api_key (legacy, will be migrated)
+ *
+ * Token is NEVER stored in ~/.claude.json, ~/.codex/, or ~/.gemini/.
+ */
+export function resolveAuthToken(): string | null {
+  // 1. ~/.gmtr.json (canonical source — written by installer, read by all platforms)
+  try {
+    const configPath = join(HOME, '.gmtr.json');
+    const config = JSON.parse(readFileSync(configPath, 'utf8'));
+    if (config.token) return config.token;
+  } catch {
+    // No config file or parse error
+  }
+
+  // 2. GMTR_TOKEN env var (CI, headless, or shell profile override)
+  if (process.env.GMTR_TOKEN) return process.env.GMTR_TOKEN;
+
+  // 3. Legacy: AIOS_MCP_TOKEN env var (deprecated)
+  if (process.env.AIOS_MCP_TOKEN) return process.env.AIOS_MCP_TOKEN;
+
+  // 4. Legacy: ~/gmtr-client/settings.json (will be migrated to ~/.gmtr.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 {
+    // Settings file not found or parse error
+  }
+
+  return null;
+}
+
+// ── MCP URL Resolution ──
+
+/**
+ * Resolve MCP server URL from config files.
+ * Priority: ~/gmtr-client/settings.json > GMTR_URL env > ~/.claude.json > default
+ */
+export function resolveMcpUrl(): string {
+  // 1. ~/gmtr-client/settings.json (canonical, vendor-agnostic)
+  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?.server_url) return settings.auth.server_url;
+  } catch {
+    // Settings file not found or parse error
+  }
+
+  // 2. Environment variable
+  if (process.env.GMTR_URL) return process.env.GMTR_URL;
+
+  // 3. ~/.claude.json (Claude-specific MCP config)
+  try {
+    const claudeJson = join(HOME, '.claude.json');
+    if (existsSync(claudeJson)) {
+      const config = JSON.parse(readFileSync(claudeJson, 'utf8'));
+      const url = config?.mcpServers?.gramatr?.url;
+      if (url) return url;
+    }
+  } catch {
+    // Not found or parse error
+  }
+
+  // 3. ~/.claude/settings.json
+  try {
+    const settingsJson = join(HOME, '.claude', 'settings.json');
+    if (existsSync(settingsJson)) {
+      const config = JSON.parse(readFileSync(settingsJson, 'utf8'));
+      const url = config?.mcpServers?.gramatr?.url;
+      if (url) return url;
+    }
+  } catch {
+    // Not found or parse error
+  }
+
+  // 4. Default
+  return DEFAULT_MCP_URL;
+}
+
+// ── MCP Transport ──
+
+/**
+ * Call an MCP tool via the gramatr server.
+ * Handles SSE response parsing, auth, and timeouts.
+ */
+export async function callMcpTool(
+  toolName: string,
+  args: Record<string, unknown>,
+  timeoutMs: number = 10000,
+): Promise<unknown | null> {
+  const result = await callMcpToolDetailed(toolName, args, timeoutMs);
+  return result.data;
+}
+
+export async function callMcpToolDetailed<T = unknown>(
+  toolName: string,
+  args: Record<string, unknown>,
+  timeoutMs: number = 10000,
+): Promise<MctToolCallResult<T>> {
+  const mcpUrl = resolveMcpUrl();
+  const token = resolveAuthToken();
+
+  const payload = JSON.stringify({
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'tools/call',
+    params: {
+      name: toolName,
+      arguments: args,
+    },
+  });
+
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    Accept: 'application/json, text/event-stream',
+  };
+  if (token) {
+    headers['Authorization'] = `Bearer ${token}`;
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(mcpUrl, {
+      method: 'POST',
+      headers,
+      body: payload,
+      signal: controller.signal,
+    });
+
+    const text = await response.text();
+
+    if (
+      text.includes('JWT token is required') ||
+      text.includes('token is required') ||
+      text.includes('Unauthorized')
+    ) {
+      return {
+        data: null,
+        error: {
+          reason: 'auth',
+          detail: token
+            ? 'Auth token was sent but rejected by the server.'
+            : 'No auth token was found for the MCP request.',
+          status: response.status,
+        },
+        rawText: text,
+      };
+    }
+
+    if (!response.ok) {
+      return {
+        data: null,
+        error: {
+          reason: 'http_error',
+          detail: `HTTP ${response.status}: ${text.slice(0, 200)}`,
+          status: response.status,
+        },
+        rawText: text,
+      };
+    }
+
+    // Parse SSE response — look for data: lines
+    for (const line of text.split('\n')) {
+      if (line.startsWith('data: ')) {
+        try {
+          const d = JSON.parse(line.slice(6));
+          const errorText = d?.result?.content?.[0]?.text;
+          if (errorText && d?.result?.isError) {
+            return {
+              data: null,
+              error: {
+                reason: 'mcp_error',
+                detail: errorText,
+                status: response.status,
+              },
+              rawText: text,
+            };
+          }
+          const content = d?.result?.content?.[0]?.text;
+          if (content && !d?.result?.isError) {
+            return {
+              data: JSON.parse(content) as T,
+              error: null,
+              rawText: text,
+            };
+          }
+        } catch {
+          continue;
+        }
+      }
+    }
+
+    // Try direct JSON response (non-SSE)
+    try {
+      const direct = JSON.parse(text);
+      const errorText = direct?.result?.content?.[0]?.text;
+      if (errorText && direct?.result?.isError) {
+        return {
+          data: null,
+          error: {
+            reason: 'mcp_error',
+            detail: errorText,
+            status: response.status,
+          },
+          rawText: text,
+        };
+      }
+      const content = direct?.result?.content?.[0]?.text;
+      if (content && !direct?.result?.isError) {
+        return {
+          data: JSON.parse(content) as T,
+          error: null,
+          rawText: text,
+        };
+      }
+    } catch {
+      // Not parseable
+    }
+
+    return {
+      data: null,
+      error: {
+        reason: 'parse_error',
+        detail: `Could not parse response from ${mcpUrl}.`,
+      },
+      rawText: text,
+    };
+  } catch (error: unknown) {
+    if (error instanceof DOMException && error.name === 'AbortError') {
+      return {
+        data: null,
+        error: {
+          reason: 'timeout',
+          detail: `Request to ${mcpUrl} timed out after ${timeoutMs}ms.`,
+        },
+        rawText: null,
+      };
+    }
+
+    const message = error instanceof Error ? error.message : String(error);
+    const reason =
+      error instanceof TypeError ||
+      /unable to connect|fetch failed|network|econnrefused|enotfound/i.test(message)
+        ? 'network_error'
+        : 'unknown';
+    return {
+      data: null,
+      error: {
+        reason,
+        detail: message,
+      },
+      rawText: null,
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+/**
+ * Call MCP tool and return raw SSE inner JSON text (unparsed inner).
+ * Useful when you need to grep specific fields from the response.
+ */
+export async function callMcpToolRaw(
+  toolName: string,
+  args: Record<string, unknown>,
+  timeoutMs: number = 10000,
+): Promise<string | null> {
+  const result = await callMcpToolDetailed(toolName, args, timeoutMs);
+  if (result.data !== null) {
+    return JSON.stringify(result.data);
+  }
+  return null;
+}
+
+// ── Health Check ──
+
+/** Check gramatr server health. Returns true if reachable. */
+export async function checkServerHealth(timeoutMs: number = 5000): Promise<{ healthy: boolean; detail: string }> {
+  const mcpUrl = resolveMcpUrl();
+  const baseUrl = mcpUrl.replace(/\/mcp$/, '');
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(`${baseUrl}/health`, {
+      signal: controller.signal,
+    });
+
+    if (response.ok) {
+      const body = await response.text();
+      return { healthy: true, detail: body };
+    } else if (response.status === 404 || response.status === 405) {
+      return { healthy: true, detail: 'REACHABLE (no /health endpoint)' };
+    } else {
+      return { healthy: false, detail: `HTTP ${response.status}` };
+    }
+  } catch {
+    return { healthy: false, detail: `Cannot reach ${baseUrl}` };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+// ── File I/O Helpers ──
+
+/** Read a JSON file. Returns null on failure. */
+export function readJsonFile<T = unknown>(filePath: string): T | null {
+  try {
+    if (!existsSync(filePath)) return null;
+    return JSON.parse(readFileSync(filePath, 'utf8')) as T;
+  } catch {
+    return null;
+  }
+}
+
+/** Write JSON file (non-atomic, for temp files). */
+export function writeJsonFile(filePath: string, data: unknown): void {
+  const dir = filePath.substring(0, filePath.lastIndexOf('/'));
+  if (dir && !existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+}
+
+/** Append a line to a file */
+export function appendLine(filePath: string, line: string): void {
+  const dir = filePath.substring(0, filePath.lastIndexOf('/'));
+  if (dir && !existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  const { appendFileSync } = require('fs');
+  appendFileSync(filePath, line + '\n', 'utf8');
+}
+
+// ── Git Helpers ──
+
+/** Get commit count since a given timestamp */
+export function getCommitCountSince(since: string): number {
+  try {
+    const output = execSync(`git log --since="${since}" --oneline`, {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    if (!output) return 0;
+    return output.split('\n').length;
+  } catch {
+    return 0;
+  }
+}
+
+/** Get formatted commit log since a timestamp */
+export function getCommitLogSince(since: string, maxCount: number = 5): string[] {
+  try {
+    const output = execSync(
+      `git log --since="${since}" --pretty=format:"%h - %s (%ar)" -${maxCount}`,
+      { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] },
+    ).trim();
+    if (!output) return [];
+    return output.split('\n');
+  } catch {
+    return [];
+  }
+}
+
+/** Get short commit log (hash + subject) since a timestamp */
+export function getCommitsSince(since: string, maxCount: number = 5): string[] {
+  try {
+    const output = execSync(
+      `git log --since="${since}" --pretty=format:"%h %s" -${maxCount}`,
+      { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] },
+    ).trim();
+    if (!output) return [];
+    return output.split('\n');
+  } catch {
+    return [];
+  }
+}
+
+/** Get git status --short output */
+export function getGitStatusShort(maxLines: number = 10): string[] {
+  try {
+    const output = execSync('git status --short', {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    if (!output) return [];
+    return output.split('\n').slice(0, maxLines);
+  } catch {
+    return [];
+  }
+}
+
+/** Get files changed between two refs */
+export function getFilesChanged(fromRef: string, toRef: string = 'HEAD', maxCount: number = 10): string[] {
+  try {
+    const output = execSync(`git diff --name-only ${fromRef}..${toRef}`, {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    if (!output) return [];
+    return output.split('\n').slice(0, maxCount);
+  } catch {
+    return [];
+  }
+}
+
+/** Get recent commit log (formatted for display) */
+export function getRecentCommits(count: number = 3): string[] {
+  try {
+    const output = execSync(`git log --oneline -${count}`, {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    if (!output) return [];
+    return output.split('\n');
+  } catch {
+    return [];
+  }
+}