@gramatr/client 0.5.1

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

package/chatgpt/install.ts

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname } from 'path';
+import { homedir } from 'os';
+import {
+  getChatGPTConfigPath,
+  mergeChatGPTConfig,
+  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';
+
+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 - ChatGPT 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: 'ChatGPT 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 ChatGPT Desktop...');
+  const configPath = getChatGPTConfigPath(home, platform);
+  const configDir = dirname(configPath);
+
+  if (platform === 'darwin') {
+    log('  Platform: macOS');
+  } else if (platform === 'win32') {
+    log('  Platform: Windows');
+  } else {
+    log(`  Platform: ${platform} (ChatGPT Desktop may not be available)`);
+  }
+  log(`  Config: ${configPath}`);
+
+  // Step 4: Read existing config
+  log('');
+  log('Step 4: Reading existing config...');
+  const existing = readJsonFile<ChatGPTConfig>(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 = mergeChatGPTConfig(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('Next steps:');
+  log('  1. Open ChatGPT Desktop');
+  log('  2. Go to Settings > Developer > MCP Servers');
+  log('  3. Verify "gramatr" appears in the server list');
+  log('  4. Start a conversation and gramatr tools will be available');
+  log('');
+  log('What was configured:');
+  log(`  MCP server:  ${serverUrl}`);
+  log(`  Config file: ${configPath}`);
+  log('');
+  log('Note: ChatGPT 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);
+});

package/chatgpt/lib/chatgpt-install-utils.ts

@@ -0,0 +1,89 @@
+import { join } from 'path';
+
+const DEFAULT_MCP_URL = 'https://mcp.gramatr.com/mcp';
+
+export interface ChatGPTMcpServerEntry {
+  gramatr: {
+    url?: string;
+    headers?: {
+      Authorization: string;
+    };
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+  };
+}
+
+export interface ChatGPTConfig {
+  mcpServers?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * Returns the ChatGPT Desktop config file path for the given platform.
+ *
+ * macOS: ~/.chatgpt/mcp.json
+ * Windows: %APPDATA%\ChatGPT\mcp.json (APPDATA = <home>\AppData\Roaming)
+ */
+export function getChatGPTConfigPath(
+  home: string,
+  platform: string = process.platform,
+): string {
+  if (platform === 'win32') {
+    return join(home, 'AppData', 'Roaming', 'ChatGPT', 'mcp.json');
+  }
+
+  // macOS (darwin) and fallback for other platforms
+  return join(home, '.chatgpt', 'mcp.json');
+}
+
+/**
+ * Build the mcpServers.gramatr entry for ChatGPT Desktop config.
+ *
+ * Two modes:
+ * - 'http' (default): StreamableHTTP transport — ChatGPT connects directly to the remote URL.
+ * - 'stdio': Local bridge process — ChatGPT spawns a local process that proxies to the server.
+ */
+export function buildMcpServerEntry(
+  apiKey: string,
+  serverUrl: string = DEFAULT_MCP_URL,
+  mode: 'http' | 'stdio' = 'http',
+): ChatGPTMcpServerEntry {
+  if (mode === 'stdio') {
+    return {
+      gramatr: {
+        command: 'npx',
+        args: ['-y', '@anthropic-ai/mcp-proxy', serverUrl],
+        env: {
+          GRAMATR_API_KEY: apiKey,
+        },
+      },
+    };
+  }
+
+  return {
+    gramatr: {
+      url: serverUrl,
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+      },
+    },
+  };
+}
+
+/**
+ * Safely merge a gramatr MCP server entry into an existing ChatGPT Desktop config.
+ * Preserves all other mcpServers and top-level config keys.
+ */
+export function mergeChatGPTConfig(
+  existing: ChatGPTConfig,
+  gramatrEntry: ChatGPTMcpServerEntry,
+): ChatGPTConfig {
+  return {
+    ...existing,
+    mcpServers: {
+      ...(existing.mcpServers || {}),
+      ...gramatrEntry,
+    },
+  };
+}

package/codex/README.md

@@ -0,0 +1,28 @@
+# Codex Integration
+
+This directory contains the first-pass Codex client scaffolding for gramatr.
+
+Current scope:
+- TypeScript hook implementations for `UserPromptSubmit` and `SessionStart`
+- pure formatting utilities with Vitest coverage
+- a repo-local `.codex/hooks.json` template
+- a fallback `AGENTS.md` template for Codex sessions
+
+Runtime approach:
+- use Codex hooks for interception and session restore
+- keep the hook code in TypeScript
+- keep formatting/decision logic in pure utility modules so coverage is meaningful
+
+Packaging direction:
+- hooks remain the runtime interception layer
+- plugin packaging remains the distribution/update layer
+
+Install locally with:
+- `pnpm --filter @gramatr/client install-codex`
+
+The installer:
+- syncs this Codex runtime into `~/gmtr-client/codex`
+- syncs the shared `gmtr-hook-utils.ts` dependency into `~/gmtr-client/hooks/lib`
+- merges `~/.codex/hooks.json`
+- enables `codex_hooks` in `~/.codex/config.toml`
+- upserts a managed gramatr block in `~/.codex/AGENTS.md`

package/codex/hooks/session-start.ts

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+import {
+  getGitContext,
+  readHookInput,
+} from '../../hooks/lib/gmtr-hook-utils.ts';
+import {
+  loadProjectHandoff,
+  normalizeSessionStartResponse,
+  persistSessionRegistration,
+  prepareProjectSessionState,
+  startRemoteSession,
+} from '../../core/session.ts';
+import {
+  buildCodexHookOutput,
+  buildSessionStartAdditionalContext,
+  type HandoffResponse,
+  type SessionStartResponse,
+} from '../lib/codex-hook-utils.ts';
+
+async function main(): Promise<void> {
+  try {
+    const input = await readHookInput();
+    const git = getGitContext();
+    if (!git) return;
+
+    const transcriptPath = input.transcript_path || '';
+    const sessionId = input.session_id || 'unknown';
+    const prepared = prepareProjectSessionState({
+      git,
+      sessionId,
+      transcriptPath,
+    });
+
+    const sessionStart = (await startRemoteSession({
+      clientType: 'codex',
+      sessionId: input.session_id,
+      projectId: prepared.projectId,
+      projectName: git.projectName,
+      gitRemote: git.remote,
+      directory: git.root,
+    })) as SessionStartResponse | null;
+
+    if (sessionStart) {
+      persistSessionRegistration(git.root, sessionStart);
+    }
+
+    const handoff = (await loadProjectHandoff(prepared.projectId)) as HandoffResponse | null;
+    const normalizedSessionStart = sessionStart
+      ? {
+          ...sessionStart,
+          interaction_id: normalizeSessionStartResponse(sessionStart).interactionId || undefined,
+        }
+      : null;
+
+    const additionalContext = buildSessionStartAdditionalContext(
+      prepared.projectId,
+      normalizedSessionStart,
+      handoff,
+    );
+    const output = buildCodexHookOutput(
+      'SessionStart',
+      additionalContext,
+      'gramatr session context loaded',
+    );
+
+    process.stdout.write(JSON.stringify(output));
+  } catch {
+    // Never block startup if the hook fails.
+  }
+}
+
+void main();

package/codex/hooks/stop.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+import {
+  getGitContext,
+  readHookInput,
+} from '../../hooks/lib/gmtr-hook-utils.ts';
+import { parseTranscript } from '../../hooks/lib/transcript-parser.ts';
+import { submitPendingClassificationFeedback } from '../../hooks/lib/classification-feedback.ts';
+
+async function main(): Promise<void> {
+  try {
+    const input = await readHookInput();
+    if (!input.transcript_path || !input.session_id) return;
+
+    const git = getGitContext();
+    if (!git) return;
+
+    const parsed = parseTranscript(input.transcript_path);
+    if (parsed.responseState !== 'completed') return;
+
+    await submitPendingClassificationFeedback({
+      rootDir: git.root,
+      sessionId: input.session_id,
+      originalPrompt: parsed.lastUserPrompt,
+      clientType: 'codex',
+      agentName: 'Codex',
+      downstreamProvider: 'openai',
+    });
+  } catch {
+    // Never block completion if the hook fails.
+  }
+}
+
+void main();

package/codex/hooks/user-prompt-submit.ts

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+
+import {
+  deriveProjectId,
+  getGitContext,
+  readHookInput,
+} from '../../hooks/lib/gmtr-hook-utils.ts';
+import {
+  describeRoutingFailure,
+  persistClassificationResult,
+  routePrompt,
+  shouldSkipPromptRouting,
+} from '../../core/routing.ts';
+import {
+  buildHookFailureAdditionalContext,
+  buildCodexHookOutput,
+  buildUserPromptAdditionalContext,
+  type RouteResponse,
+} from '../lib/codex-hook-utils.ts';
+
+async function main(): Promise<void> {
+  try {
+    const input = await readHookInput();
+    const prompt = (input.prompt || input.message || '').trim();
+
+    if (shouldSkipPromptRouting(prompt)) {
+      return;
+    }
+
+    const git = getGitContext();
+    const projectId = git ? deriveProjectId(git.remote, git.projectName) : undefined;
+    const result = await routePrompt({
+      prompt,
+      projectId,
+      sessionId: input.session_id,
+      timeoutMs: 15000,
+      // #496 Phase 3: ask the server for a composed [GMTR Status] block.
+      includeStatusline: true,
+      statuslineSize: 'small',
+    });
+    const route = result.route as RouteResponse | null;
+
+    if (!route) {
+      if (result.error) {
+        const failure = describeRoutingFailure(result.error);
+        const output = buildCodexHookOutput(
+          'UserPromptSubmit',
+          buildHookFailureAdditionalContext(failure),
+          'gramatr request routing unavailable',
+        );
+        process.stdout.write(JSON.stringify(output));
+      }
+      return;
+    }
+
+    const additionalContext = buildUserPromptAdditionalContext(route);
+    if (git) {
+      persistClassificationResult({
+        rootDir: git.root,
+        prompt,
+        route,
+        downstreamModel: null,
+        clientType: 'codex',
+        agentName: 'Codex',
+      });
+    }
+    const output = buildCodexHookOutput(
+      'UserPromptSubmit',
+      additionalContext,
+      'gramatr request routing active',
+    );
+
+    process.stdout.write(JSON.stringify(output));
+  } catch {
+    // Never block the user prompt if the hook fails.
+  }
+}
+
+void main();

package/codex/install.ts

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, copyFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import {
+  buildManagedHooks,
+  ensureCodexHooksFeature,
+  mergeHooksFile,
+  upsertManagedBlock,
+} from './lib/codex-install-utils.ts';
+
+const START_MARKER = '<!-- GMTR-CODEX-START -->';
+const END_MARKER = '<!-- GMTR-CODEX-END -->';
+
+function log(message: string): void {
+  process.stdout.write(`${message}\n`);
+}
+
+function ensureDir(path: string): void {
+  if (!existsSync(path)) mkdirSync(path, { recursive: true });
+}
+
+function copyRecursive(source: string, target: string): void {
+  const stats = statSync(source);
+
+  if (stats.isDirectory()) {
+    ensureDir(target);
+    for (const entry of readdirSync(source)) {
+      copyRecursive(join(source, entry), join(target, entry));
+    }
+    return;
+  }
+
+  ensureDir(dirname(target));
+  copyFileSync(source, target);
+}
+
+function readJsonFile<T>(path: string, fallback: T): T {
+  if (!existsSync(path)) return fallback;
+  return JSON.parse(readFileSync(path, 'utf8')) as T;
+}
+
+export function main(): void {
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (!home) {
+    throw new Error('HOME is not set');
+  }
+
+  const gmtrDir = process.env.GMTR_DIR || join(home, 'gmtr-client');
+  const codexHome = join(home, '.codex');
+  const hooksPath = join(codexHome, 'hooks.json');
+  const configPath = join(codexHome, 'config.toml');
+  const agentsPath = join(codexHome, 'AGENTS.md');
+
+  const currentFile = fileURLToPath(import.meta.url);
+  const codexSourceDir = dirname(currentFile);
+  const clientSourceDir = dirname(codexSourceDir);
+  const codexTargetDir = join(gmtrDir, 'codex');
+  const sharedHookUtilsSource = join(clientSourceDir, 'hooks', 'lib', 'gmtr-hook-utils.ts');
+  const sharedHookUtilsTarget = join(gmtrDir, 'hooks', 'lib', 'gmtr-hook-utils.ts');
+
+  // AGENTS.md: check package root first (npm install), then repo root (dev)
+  let managedAgentsContent = '';
+  const agentsMdCandidates = [
+    join(clientSourceDir, 'AGENTS.md'),               // npm package root
+    join(dirname(dirname(clientSourceDir)), 'AGENTS.md'), // monorepo root
+  ];
+  for (const candidate of agentsMdCandidates) {
+    if (existsSync(candidate)) {
+      managedAgentsContent = readFileSync(candidate, 'utf8');
+      break;
+    }
+  }
+  if (!managedAgentsContent) {
+    log('  WARN: AGENTS.md not found — skipping Codex agents block');
+  }
+
+  ensureDir(gmtrDir);
+  ensureDir(codexHome);
+
+  copyRecursive(codexSourceDir, codexTargetDir);
+  copyRecursive(sharedHookUtilsSource, sharedHookUtilsTarget);
+  log(`OK Synced Codex runtime to ${codexTargetDir}`);
+
+  const managedHooks = buildManagedHooks(gmtrDir);
+  const existingHooks = readJsonFile(hooksPath, { hooks: {} });
+  const mergedHooks = mergeHooksFile(existingHooks, managedHooks);
+  writeFileSync(hooksPath, `${JSON.stringify(mergedHooks, null, 2)}\n`, 'utf8');
+  log(`OK Updated ${hooksPath}`);
+
+  const existingConfig = existsSync(configPath) ? readFileSync(configPath, 'utf8') : '';
+  const updatedConfig = ensureCodexHooksFeature(existingConfig);
+  writeFileSync(configPath, updatedConfig, 'utf8');
+  log(`OK Enabled Codex hooks in ${configPath}`);
+
+  const existingAgents = existsSync(agentsPath) ? readFileSync(agentsPath, 'utf8') : '';
+  const managedAgents = upsertManagedBlock(
+    existingAgents,
+    managedAgentsContent,
+    START_MARKER,
+    END_MARKER,
+  );
+  writeFileSync(agentsPath, managedAgents, 'utf8');
+  log(`OK Updated ${agentsPath}`);
+
+  log('');
+  log('Codex installer complete.');
+  log('Restart Codex or start a new session to load the updated hook configuration.');
+}
+
+// Run directly when executed as a script
+const isDirectRun = typeof require !== 'undefined'
+  ? require.main === module
+  : !import.meta.url.includes('node_modules/gramatr/bin/');
+if (isDirectRun) main();

package/codex/lib/codex-hook-utils.ts

@@ -0,0 +1,48 @@
+import {
+  buildHookFailureAdditionalContext,
+  buildSessionStartAdditionalContext,
+  buildUserPromptAdditionalContext,
+} from '../../core/formatting.ts';
+import type {
+  HandoffResponse,
+  HookFailure,
+  RouteResponse,
+  SessionStartResponse,
+} from '../../core/types.ts';
+
+export type {
+  HandoffResponse,
+  HookFailure,
+  RouteResponse,
+  SessionStartResponse,
+};
+
+export interface CodexHookOutput {
+  continue: boolean;
+  hookSpecificOutput: {
+    hookEventName: 'UserPromptSubmit' | 'SessionStart';
+    additionalContext: string;
+  };
+  systemMessage?: string;
+}
+
+export {
+  buildHookFailureAdditionalContext,
+  buildSessionStartAdditionalContext,
+  buildUserPromptAdditionalContext,
+};
+
+export function buildCodexHookOutput(
+  hookEventName: 'UserPromptSubmit' | 'SessionStart',
+  additionalContext: string,
+  systemMessage?: string,
+): CodexHookOutput {
+  return {
+    continue: true,
+    hookSpecificOutput: {
+      hookEventName,
+      additionalContext,
+    },
+    ...(systemMessage ? { systemMessage } : {}),
+  };
+}