gramatr 0.3.55 → 0.3.57

package/bin/gramatr.js

@@ -3,25 +3,18 @@
  * gramatr CLI entry point — thin JS wrapper that bootstraps TypeScript.
  * tsx is a production dependency, resolved directly from node_modules.
  */
-const { spawnSync, execSync } = require('child_process');
+const { spawnSync } = require('child_process');
 const { join, dirname } = require('path');
 
 const script = join(__dirname, 'gramatr.ts');
 const args = process.argv.slice(2);
 
-// Try bun first (fastest)
-let hasBun = false;
-try {
-  execSync('bun --version', { stdio: 'ignore' });
-  hasBun = true;
-} catch {}
-
-if (hasBun) {
-  const r = spawnSync('bun', [script, ...args], { stdio: 'inherit' });
-  process.exit(r.status ?? 1);
-}
+// gramatr standardizes on `npx tsx` — see issue #468 for the architectural
+// rationale. bun detection was removed because it silently produced broken
+// hook + statusline configs on hosts where the install-time PATH did not
+// match the runtime PATH of spawned subprocesses.
 
-// Resolve tsx from node_modules (installed as dependency)
+// Resolve tsx from node_modules (tsx is a production dependency)
 try {
   const tsxBin = join(dirname(require.resolve('tsx/package.json')), 'dist', 'cli.mjs');
   const r = spawnSync(process.execPath, [tsxBin, script, ...args], { stdio: 'inherit' });

package/bin/gramatr.ts

@@ -6,14 +6,12 @@ import { homedir } from 'os';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { detectTargets, findTarget, summarizeDetectedLocalTargets, type IntegrationTargetId } from '../core/targets.ts';
+import { VERSION } from '../core/version.ts';
 import { findStaleArtifacts, runLegacyMigration } from '../core/migration.ts';
-import { detectTsRunner } from '../core/install.ts';
 import {
   formatDetectionLines,
   formatDoctorLines,
-  formatInstallMenuLines,
   formatRemoteGuidanceLines,
-  resolveInteractiveSelection,
 } from '../core/installer-cli.ts';
 
 const currentFile = fileURLToPath(import.meta.url);
@@ -45,34 +43,17 @@ function renderRemoteGuidance(): void {
   for (const line of formatRemoteGuidanceLines(detectTargets())) log(line);
 }
 
-function prompt(question: string): string {
-  process.stdout.write(question);
-  const input = spawnSync('bash', ['-lc', 'IFS= read -r line; printf "%s" "$line"'], {
-    stdio: ['inherit', 'pipe', 'inherit'],
-  });
-  return input.stdout?.toString('utf8').trim() || '';
-}
-
-function renderInstallMenu(): IntegrationTargetId[] {
-  const rendered = formatInstallMenuLines(detectTargets());
-  for (const line of rendered.lines) log(line);
-  return rendered.targetIds;
-}
-
 function runTs(script: string, extraArgs: string[] = []): void {
-  const runner = detectTsRunner();
-  if (runner === 'bun') {
-    run('bun', [script, ...extraArgs]);
-  } else {
-    // Resolve tsx from this package's node_modules (not CWD)
-    try {
-      const { dirname, join } = require('path');
-      const tsxCli = join(dirname(require.resolve('tsx/package.json')), 'dist', 'cli.mjs');
-      run(process.execPath, [tsxCli, script, ...extraArgs]);
-    } catch {
-      // Fallback: hope tsx is globally available
-      run('npx', ['tsx', script, ...extraArgs]);
-    }
+  // Resolve tsx from this package's node_modules (not CWD) so `npx tsx` works
+  // even on hosts where the user hasn't globally installed tsx.
+  try {
+    const { dirname, join } = require('path');
+    const tsxCli = join(dirname(require.resolve('tsx/package.json')), 'dist', 'cli.mjs');
+    run(process.execPath, [tsxCli, script, ...extraArgs]);
+  } catch {
+    // Fallback: global npx tsx
+    const npxBin = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+    run(npxBin, ['tsx', script, ...extraArgs]);
   }
 }
 
@@ -83,6 +64,122 @@ const forwardedFlags = process.argv.slice(2).filter(a =>
   (process.argv[process.argv.indexOf(a) - 1] === '--timezone')
 );
 
+interface InstallAllResult {
+  id: IntegrationTargetId;
+  label: string;
+  status: 'ok' | 'fail' | 'skipped';
+  message?: string;
+}
+
+const INSTALL_ALL_CANDIDATES: Array<{ id: IntegrationTargetId; label: string }> = [
+  { id: 'claude-code', label: 'Claude Code' },
+  { id: 'codex', label: 'Codex' },
+  { id: 'gemini-cli', label: 'Gemini CLI' },
+  { id: 'claude-desktop', label: 'Claude Desktop' },
+  { id: 'chatgpt-desktop', label: 'ChatGPT Desktop' },
+];
+
+function installAll(): void {
+  const detections = detectTargets();
+  const detectedIds = new Set(
+    detections.filter((t) => t.kind === 'local' && t.detection.detected).map((t) => t.id),
+  );
+
+  log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  log(`  gramatr v${VERSION} — install all detected`);
+  log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  log('');
+
+  const results: InstallAllResult[] = [];
+
+  for (const candidate of INSTALL_ALL_CANDIDATES) {
+    if (!detectedIds.has(candidate.id)) {
+      results.push({ id: candidate.id, label: candidate.label, status: 'skipped', message: 'not detected' });
+      continue;
+    }
+    log(`━━━ Installing ${candidate.label} ━━━`);
+    try {
+      installTargetForAll(candidate.id);
+      results.push({ id: candidate.id, label: candidate.label, status: 'ok' });
+    } catch (err: any) {
+      results.push({
+        id: candidate.id,
+        label: candidate.label,
+        status: 'fail',
+        message: err?.message || String(err),
+      });
+      log(`  X ${candidate.label} install failed: ${err?.message || err}`);
+    }
+    log('');
+  }
+
+  // Summary
+  log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  log('  gramatr install summary');
+  log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  const pad = (s: string, n: number) => s + ' '.repeat(Math.max(1, n - s.length));
+  for (const r of results) {
+    const statusStr =
+      r.status === 'ok' ? 'OK'
+      : r.status === 'fail' ? 'FAIL'
+      : 'not detected — skipped';
+    log(`  ${pad(r.label, 18)}${statusStr}${r.message && r.status === 'fail' ? ` (${r.message})` : ''}`);
+  }
+  log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  log('');
+
+  const okList = results.filter((r) => r.status === 'ok');
+  if (okList.length > 0) {
+    log('  Next steps:');
+    let step = 1;
+    for (const r of okList) {
+      switch (r.id) {
+        case 'claude-code':
+          log(`    ${step++}. Restart Claude Code to pick up MCP server config`);
+          break;
+        case 'codex':
+          log(`    ${step++}. Restart Codex to load updated hooks`);
+          break;
+        case 'gemini-cli':
+          log(`    ${step++}. Restart Gemini CLI to load the extension`);
+          break;
+        case 'claude-desktop':
+          log(`    ${step++}. Restart Claude Desktop to load MCP server`);
+          break;
+        case 'chatgpt-desktop':
+          log(`    ${step++}. Restart ChatGPT Desktop to load MCP server`);
+          break;
+      }
+    }
+    log('');
+  }
+
+  const anyFail = results.some((r) => r.status === 'fail');
+  if (anyFail) process.exit(1);
+}
+
+function installTargetForAll(targetId: IntegrationTargetId): void {
+  switch (targetId) {
+    case 'claude-code':
+      runTs(join(binDir, 'install.ts'), forwardedFlags);
+      return;
+    case 'codex':
+      runTs(join(clientDir, 'codex', 'install.ts'), forwardedFlags);
+      return;
+    case 'gemini-cli':
+      runTs(join(clientDir, 'gemini', 'install.ts'), forwardedFlags);
+      return;
+    case 'claude-desktop':
+      runTs(join(clientDir, 'desktop', 'install.ts'), forwardedFlags);
+      return;
+    case 'chatgpt-desktop':
+      runTs(join(clientDir, 'chatgpt', 'install.ts'), forwardedFlags);
+      return;
+    default:
+      throw new Error(`Cannot install remote target '${targetId}' via install-all`);
+  }
+}
+
 function installTarget(targetId: IntegrationTargetId): void {
   switch (targetId) {
     case 'claude-code':
@@ -154,31 +251,22 @@ function upgrade(): void {
   renderRemoteGuidance();
 }
 
-function interactiveInstall(): void {
-  renderDetections();
-  log('');
-  const targetIds = renderInstallMenu();
-  const defaultChoice = summarizeDetectedLocalTargets()[0] || 'claude-code';
-  const answer = prompt(`Install target(s) [${defaultChoice}]: `) || defaultChoice;
-  const selections = resolveInteractiveSelection(
-    answer,
-    targetIds,
-    summarizeDetectedLocalTargets(),
-    (id) => findTarget(id) as { id: IntegrationTargetId; kind: 'local' | 'remote' } | undefined,
-  );
-  if (selections.length === 0) {
-    throw new Error('No install targets selected');
-  }
-
-  for (const selection of selections) {
-    installTarget(selection);
-  }
-
-  renderRemoteGuidance();
-}
-
 function main(): void {
-  const [, , command = 'install', targetArg] = process.argv;
+  // Skip forwarded-only flags (--yes, --name <v>, --timezone <v>) when picking
+  // the command and target. Keep command-specific flags like --apply, --detect,
+  // --help, --version so existing subcommands continue to work.
+  const raw = process.argv.slice(2);
+  const FORWARDED_ONLY = new Set(['--yes', '-y']);
+  const FORWARDED_WITH_VALUE = new Set(['--name', '--timezone']);
+  const positionals: string[] = [];
+  for (let i = 0; i < raw.length; i++) {
+    const a = raw[i];
+    if (FORWARDED_ONLY.has(a)) continue;
+    if (FORWARDED_WITH_VALUE.has(a)) { i++; continue; }
+    positionals.push(a);
+  }
+  const command = positionals[0] ?? 'install';
+  const targetArg = positionals[1];
 
   switch (command) {
     case 'install':
@@ -186,22 +274,32 @@ function main(): void {
         renderDetections();
         return;
       }
-      if (targetArg) {
-        if (targetArg === 'all') {
-          const targets = summarizeDetectedLocalTargets();
-          if (targets.length === 0) {
-            log('No detected local targets to install.');
-            return;
-          }
-          for (const target of targets) installTarget(target);
-          return;
+      if (!targetArg || targetArg === 'all') {
+        installAll();
+        return;
+      }
+      if (targetArg === 'help' || targetArg === '--help' || targetArg === '-h') {
+        log('gramatr install — install gramatr into detected AI platforms');
+        log('');
+        log('Usage:');
+        log('  npx gramatr install              Detect every platform and install all');
+        log('  npx gramatr install all          Same as above (explicit)');
+        log('  npx gramatr install <platform>   Install a single platform');
+        log('');
+        log('Supported platforms:');
+        for (const c of INSTALL_ALL_CANDIDATES) {
+          log(`  ${c.id.padEnd(16)}${c.label}`);
         }
+        return;
+      }
+      {
         const target = findTarget(targetArg);
-        if (!target) throw new Error(`Unknown target: ${targetArg}`);
+        if (!target) {
+          log(`Unknown target: ${targetArg}. Run 'gramatr install help' for usage.`);
+          process.exit(1);
+        }
         installTarget(target.id);
-        return;
       }
-      interactiveInstall();
       return;
     case 'detect':
       renderDetections();
@@ -235,12 +333,7 @@ function main(): void {
       return;
     case '--version':
     case '-v':
-      try {
-        const { VERSION } = require('../core/version.ts');
-        log(VERSION);
-      } catch {
-        log('0.3.0');
-      }
+      log(VERSION);
       return;
     default:
       log(`Unknown command: ${command}. Run 'gramatr help' for usage.`);

package/bin/install.ts

@@ -17,7 +17,7 @@ import {
 import { join, dirname, basename, resolve } from 'path';
 import { execSync, spawnSync } from 'child_process';
 import { createInterface } from 'readline';
-import { buildClaudeHooksFile, detectTsRunner } from '../core/install.ts';
+import { buildClaudeHooksFile } from '../core/install.ts';
 import { VERSION } from '../core/version.ts';
 
 // ── Constants ──
@@ -141,7 +141,7 @@ function timestamp(): string {
 
 // ── Prerequisites ──
 
-async function checkPrereqs(): Promise<{ tsRunner: string }> {
+async function checkPrereqs(): Promise<void> {
   // Node.js
   const nodeVer = process.versions.node;
   const major = parseInt(nodeVer.split('.')[0], 10);
@@ -151,18 +151,8 @@ async function checkPrereqs(): Promise<{ tsRunner: string }> {
   }
   log(`OK Node.js v${nodeVer}`);
 
-  // Detect best TypeScript runner
-  const tsRunner = detectTsRunner();
-  if (tsRunner === 'bun') {
-    try {
-      const ver = execSync('bun --version', { encoding: 'utf8' }).trim();
-      log(`OK TS runner: bun ${ver}`);
-    } catch {
-      log(`OK TS runner: bun`);
-    }
-  } else {
-    log(`OK TS runner: npx tsx (install bun for faster hooks)`);
-  }
+  // TS runner is hardcoded to `npx tsx` (see core/install.ts and issue #468)
+  log('OK TS runner: npx tsx');
 
   // Claude Code
   if (!existsSync(CLAUDE_DIR)) {
@@ -170,8 +160,6 @@ async function checkPrereqs(): Promise<{ tsRunner: string }> {
     process.exit(1);
   }
   log('OK Claude Code directory exists');
-
-  return { tsRunner };
 }
 
 // ── Legacy Detection ──
@@ -287,6 +275,11 @@ function installClientFiles(): void {
   }
   log('OK Installed core modules');
 
+  // package.json — copied so core/version.ts can resolve the installed
+  // version at runtime. Single source of truth; see core/version.ts.
+  copyFileIfExists(join(SCRIPT_DIR, 'package.json'), join(CLIENT_DIR, 'package.json'));
+  log('OK Installed package.json (version source of truth)');
+
   // CLAUDE.md
   copyFileIfExists(join(SCRIPT_DIR, 'CLAUDE.md'), join(CLIENT_DIR, 'CLAUDE.md'));
   log('OK Installed CLAUDE.md (minimal — server delivers behavioral rules)');
@@ -351,7 +344,11 @@ function installClaudeMd(): void {
 
 // ── Step 3: Auth ──
 
-async function handleAuth(legacyToken: string, tsRunner: string): Promise<{ url: string; token: string }> {
+// 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('');
 
@@ -387,10 +384,11 @@ async function handleAuth(legacyToken: string, tsRunner: string): Promise<{ url:
     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(tsRunner, [loginScript], {
+      const result = spawnSync(NPX_BIN, ['tsx', loginScript], {
         stdio: 'inherit',
         env: { ...process.env },
       });
+      void result;
 
       // Re-read token after login
       if (existsSync(GMTR_JSON)) {
@@ -479,7 +477,7 @@ async function configureIdentity(): Promise<void> {
 
 // ── Step 4: Settings merge ──
 
-function updateClaudeSettings(tsRunner: string, url: string, token: string): void {
+function updateClaudeSettings(url: string, token: string): void {
   log('━━━ Step 4: Updating Claude Code settings ━━━');
   log('');
 
@@ -493,7 +491,7 @@ function updateClaudeSettings(tsRunner: string, url: string, token: string): voi
   log(`OK Backed up settings to ${basename(backup)}`);
 
   const includeOptionalUx = process.env.GMTR_ENABLE_OPTIONAL_CLAUDE_UX === '1';
-  const hooksConfig = buildClaudeHooksFile(CLIENT_DIR, { includeOptionalUx, tsRunner });
+  const hooksConfig = buildClaudeHooksFile(CLIENT_DIR, { includeOptionalUx });
 
   const settings = readJson(CLAUDE_SETTINGS);
 
@@ -529,7 +527,7 @@ function updateClaudeSettings(tsRunner: string, url: string, token: string): voi
   // Status line
   settings.statusLine = {
     type: 'command',
-    command: `${tsRunner} ${CLIENT_DIR}/bin/statusline.ts`,
+    command: `npx tsx ${CLIENT_DIR}/bin/statusline.ts`,
   };
   log('OK Configured status line');
 
@@ -586,47 +584,6 @@ function registerMcpServer(url: string, token: string): void {
   log('');
 }
 
-// ── Step 4c: Additional CLIs ──
-
-async function installAdditionalClis(): Promise<void> {
-  log('━━━ Step 4c: Additional CLI platforms ━━━');
-  log('');
-
-  // Codex
-  const codexDir = join(HOME, '.codex');
-  if (existsSync(codexDir) || which('codex')) {
-    log('  Codex CLI detected — installing gramatr hooks...');
-    try {
-      const { main: installCodex } = await import('../codex/install.ts');
-      installCodex();
-      log('  OK Codex hooks installed');
-    } catch (err: any) {
-      log(`  X Codex install failed (non-fatal): ${err.message}`);
-    }
-    log('');
-  } else {
-    log('  -- Codex CLI not detected (skipping)');
-  }
-
-  // Gemini
-  const geminiDir = join(HOME, '.gemini');
-  if (existsSync(geminiDir) || which('gemini')) {
-    log('  Gemini CLI detected — installing gramatr extension...');
-    try {
-      const { main: installGemini } = await import('../gemini/install.ts');
-      await installGemini();
-      log('  OK Gemini extension installed');
-    } catch (err: any) {
-      log(`  X Gemini install failed (non-fatal): ${err.message}`);
-    }
-    log('');
-  } else {
-    log('  -- Gemini CLI not detected (skipping)');
-  }
-
-  log('');
-}
-
 // ── Step 5: Verification ──
 
 function verify(url: string, token: string): boolean {
@@ -716,7 +673,7 @@ async function main(): Promise<void> {
   log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
   log('');
 
-  const { tsRunner } = await checkPrereqs();
+  await checkPrereqs();
   log('');
 
   const { legacyToken } = await handleLegacy();
@@ -724,11 +681,10 @@ async function main(): Promise<void> {
   installClientFiles();
   installClaudeMd();
 
-  const { url, token } = await handleAuth(legacyToken, tsRunner);
+  const { url, token } = await handleAuth(legacyToken);
   await configureIdentity();
-  updateClaudeSettings(tsRunner, url, token);
+  updateClaudeSettings(url, token);
   registerMcpServer(url, token);
-  await installAdditionalClis();
 
   const allOk = verify(url, token);
 

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