gramatr 0.3.55 → 0.3.56

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

@@ -23,7 +23,7 @@ interface HookSpec {
 }
 
 interface ClaudeHookOptions {
-  tsRunner?: string;
+  includeOptionalUx?: boolean;
 }
 
 const CLAUDE_HOOKS: HookSpec[] = [
@@ -62,21 +62,14 @@ const CODEX_HOOKS: HookSpec[] = [
 ];
 
 /**
- * Detect the best available TypeScript runner.
- * Priority: bun (fastest) > npx tsx (universal Node fallback)
+ * All hook commands are invoked via `npx tsx`. This is the single, portable
+ * runner for every gramatr client install. See issue #468 for the architectural
+ * rationale: bun detection at install time silently produced broken configs on
+ * hosts where the runtime PATH did not match the installer's PATH.
  */
-export function detectTsRunner(): string {
-  try {
-    const { execSync } = require('child_process');
-    execSync('bun --version', { stdio: 'ignore' });
-    return 'bun';
-  } catch {
-    return 'npx tsx';
-  }
-}
+const TS_RUNNER = 'npx tsx';
 
-function buildHooksFile(clientDir: string, specs: HookSpec[], tsRunner?: string): InstallHooksFile {
-  const runner = tsRunner || detectTsRunner();
+function buildHooksFile(clientDir: string, specs: HookSpec[]): InstallHooksFile {
   const hooks: Record<string, InstallHookMatcherEntry[]> = {};
 
   for (const spec of specs) {
@@ -84,7 +77,7 @@ function buildHooksFile(clientDir: string, specs: HookSpec[], tsRunner?: string)
       hooks: [
         {
           type: 'command',
-          command: `${runner} "${clientDir}/${spec.relativeCommand}"`,
+          command: `${TS_RUNNER} "${clientDir}/${spec.relativeCommand}"`,
           statusMessage: spec.statusMessage,
           timeout: spec.timeout,
         },
@@ -104,11 +97,11 @@ function buildHooksFile(clientDir: string, specs: HookSpec[], tsRunner?: string)
 
 export function buildClaudeHooksFile(
   clientDir: string,
-  options: ClaudeHookOptions = {},
+  _options: ClaudeHookOptions = {},
 ): InstallHooksFile {
-  return buildHooksFile(clientDir, CLAUDE_HOOKS, options.tsRunner);
+  return buildHooksFile(clientDir, CLAUDE_HOOKS);
 }
 
-export function buildCodexHooksFile(clientDir: string, tsRunner?: string): InstallHooksFile {
-  return buildHooksFile(clientDir, CODEX_HOOKS, tsRunner);
+export function buildCodexHooksFile(clientDir: string): InstallHooksFile {
+  return buildHooksFile(clientDir, CODEX_HOOKS);
 }

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

@@ -1,2 +1,47 @@
-/** Auto-generated by version-sync.ts — do not edit */
-export const VERSION = '0.3.55';
+/**
+ * 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/gemini/lib/gemini-install-utils.ts

@@ -88,7 +88,7 @@ export function buildGeminiHooksFile(): GeminiHooksFile {
           hooks: [
             {
               type: 'command',
-              command: 'bun "${extensionPath}/hooks/session-start.ts"',
+              command: 'npx tsx "${extensionPath}/hooks/session-start.ts"',
               name: 'gramatr-session-start',
               timeout: 15,
               description: 'Load gramatr session context and handoff',
@@ -101,7 +101,7 @@ export function buildGeminiHooksFile(): GeminiHooksFile {
           hooks: [
             {
               type: 'command',
-              command: 'bun "${extensionPath}/hooks/user-prompt-submit.ts"',
+              command: 'npx tsx "${extensionPath}/hooks/user-prompt-submit.ts"',
               name: 'gramatr-prompt-routing',
               timeout: 15,
               description: 'Route prompt through gramatr intelligence',
@@ -114,7 +114,7 @@ export function buildGeminiHooksFile(): GeminiHooksFile {
           hooks: [
             {
               type: 'command',
-              command: 'bun "${extensionPath}/hooks/stop.ts"',
+              command: 'npx tsx "${extensionPath}/hooks/stop.ts"',
               name: 'gramatr-session-end',
               timeout: 10,
               description: 'Submit classification feedback to gramatr',

package/hooks/session-start.hook.ts

@@ -33,6 +33,8 @@ import {
   writeCurrentProjectContextFile,
   persistSessionRegistration,
 } from '../core/session.ts';
+import { runVersionCheckAndNotify } from '../core/version-check.ts';
+import { VERSION } from '../core/version.ts';
 
 // ── stdout (Claude context injection) ──
 // Claude Code captures stdout from SessionStart hooks and injects it as context.
@@ -172,7 +174,8 @@ function syncRatingsInBackground(): void {
   const syncScript = join(process.env.GMTR_DIR || join(process.env.HOME || '', 'gmtr-client'), 'hooks', 'sync-ratings.hook.ts');
   if (existsSync(syncScript)) {
     try {
-      const child = spawn('bun', ['run', syncScript], {
+      const npxBin = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+      const child = spawn(npxBin, ['tsx', syncScript], {
         detached: true,
         stdio: 'ignore',
       });
@@ -477,6 +480,14 @@ async function main(): Promise<void> {
       }
     }
 
+    // Opportunistic npm version check — prints a notification to stderr if a
+    // newer gramatr is published. Never blocks or crashes the session start.
+    try {
+      await runVersionCheckAndNotify(VERSION);
+    } catch {
+      // Silent — version check is strictly optional.
+    }
+
     log('');
     log('\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501');
     log('Session initialization complete');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gramatr",
-  "version": "0.3.55",
+  "version": "0.3.56",
   "description": "grāmatr — context engineering layer for AI coding agents. Every prompt gets a pre-computed intelligence packet: decision routing, capability audit, behavioral directives, memory pre-load, and ISC scaffolds. Continuity across sessions for Claude Code, Codex, and Gemini CLI.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -43,11 +43,9 @@
     "lint": "pnpm exec biome lint --files-ignore-unknown=true package.json bin chatgpt codex core desktop gemini hooks lib tools web vitest.config.ts",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
-    "version:patch": "npm version patch --no-git-tag-version && npm run version:sync",
-    "version:minor": "npm version minor --no-git-tag-version && npm run version:sync",
-    "version:major": "npm version major --no-git-tag-version && npm run version:sync",
-    "version:sync": "npx tsx bin/version-sync.ts",
-    "prepublishOnly": "npm run version:sync"
+    "version:patch": "npm version patch --no-git-tag-version",
+    "version:minor": "npm version minor --no-git-tag-version",
+    "version:major": "npm version major --no-git-tag-version"
   },
   "engines": {
     "node": ">=20.0.0"

package/bin/version-sync.ts

@@ -1,46 +0,0 @@
-#!/usr/bin/env node
-/**
- * version-sync — stamps the current package.json version into files that display it.
- *
- * Called automatically by:
- *   npm run version:patch   →  0.3.0 → 0.3.1
- *   npm run version:minor   →  0.3.0 → 0.4.0
- *   npm run version:major   →  0.3.0 → 1.0.0
- *   npm run prepublishOnly  →  ensures sync before publish
- */
-
-import { readFileSync, writeFileSync, existsSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const clientDir = dirname(__dirname);
-const pkg = JSON.parse(readFileSync(join(clientDir, 'package.json'), 'utf8'));
-const version = pkg.version;
-
-console.log(`gramatr version: ${version}`);
-
-// 1. Stamp into settings.json template (install.ts writes this)
-//    No file to patch — install.ts reads package.json at runtime.
-
-// 2. Stamp into CLAUDE.md if it has a version marker
-const claudeMd = join(clientDir, 'CLAUDE.md');
-if (existsSync(claudeMd)) {
-  let content = readFileSync(claudeMd, 'utf8');
-  const versionPattern = /gramatr\s+v[\d.]+/g;
-  const newContent = content.replace(versionPattern, `gramatr v${version}`);
-  if (newContent !== content) {
-    writeFileSync(claudeMd, newContent);
-    console.log(`  OK Stamped version in CLAUDE.md`);
-  }
-}
-
-// 3. Write a version.ts module that other TS files can import
-const versionTs = join(clientDir, 'core', 'version.ts');
-writeFileSync(versionTs, `/** Auto-generated by version-sync.ts — do not edit */\nexport const VERSION = '${version}';\n`);
-console.log(`  OK Wrote core/version.ts`);
-
-// 4. Log next steps
-console.log('');
-console.log(`  To publish: npm publish --access public`);
-console.log(`  To tag:     git tag v${version} && git push origin v${version}`);