@mxalbert/context-mode 2.0.0

package/hooks/session-helpers.mjs

@@ -0,0 +1,428 @@
+/**
+ * Shared session helpers for context-mode hooks.
+ * Used by posttooluse.mjs, precompact.mjs, sessionstart.mjs,
+ * and platform-specific hooks (Gemini CLI, VS Code Copilot).
+ *
+ * All functions accept an optional `opts` parameter for platform-specific
+ * configuration. Defaults to Claude Code settings for backward compatibility.
+ *
+ * ─── PATH / HASH HELPERS ARE BOUND, NOT REIMPLEMENTED ──────────────────
+ * Hash + worktree-suffix + legacy migration logic lives in TypeScript at
+ * `src/session/db.ts` and is bundled to `hooks/session-db.bundle.mjs` by
+ * the existing esbuild step in `npm run bundle`. This file imports those
+ * exports via the bundle so the JS hooks and the TS server cannot drift
+ * again — the same drift that produced rounds 5 and 6 of case-fold fixes.
+ *
+ * Bundle-first / build-fallback resolution mirrors the pattern in
+ * `session-loaders.mjs` for marketplace installs that ship `build/`
+ * artifacts instead of pre-built bundles.
+ */
+
+import { join, dirname } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+// ─────────────────────────────────────────────────────────
+// Bundle binding — single source of truth for path/hash logic.
+// ─────────────────────────────────────────────────────────
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+async function loadSessionDbModule() {
+  // Bundle is co-located with this file in published installs.
+  const bundlePath = join(__dirname, "session-db.bundle.mjs");
+  if (existsSync(bundlePath)) {
+    return await import(pathToFileURL(bundlePath).href);
+  }
+  // Marketplace fallback: build/session/db.js when bundles are absent.
+  const buildPath = join(__dirname, "..", "build", "session", "db.js");
+  return await import(pathToFileURL(buildPath).href);
+}
+
+const _sessionDb = await loadSessionDbModule();
+const {
+  ensureWritableStorageDir,
+  hashProjectDirCanonical,
+  hashProjectDirLegacy,
+  normalizeWorktreePath,
+  resolveDefaultSessionDir,
+  resolveSessionStorageDir,
+  resolveSessionPath: _resolveSessionPath,
+  getWorktreeSuffix: _getWorktreeSuffixBundle,
+} = _sessionDb;
+
+// ─────────────────────────────────────────────────────────
+// Cross-process worktree-suffix cache — hook-fork-only optimisation.
+// ─────────────────────────────────────────────────────────
+//
+// The TS bundle's getWorktreeSuffix has an in-process cache, but every
+// Pre/PostToolUse hook is a fresh `node` fork — that cache is dead on
+// arrival. The marker file in tmpdir keyed by sha256(projectDir) lets
+// subsequent forks short-circuit the 12-50ms `git worktree list` cost.
+// The marker filename uses the canonical hash (case-folded on Mac/Win)
+// so two terminals with different casing of the same physical worktree
+// share one marker (and one cached suffix) — same correctness guarantee
+// as the canonical DB filename.
+
+let _wtCacheInProcess;
+
+function workTreeMarkerPath(projectDir) {
+  return join(
+    tmpdir(),
+    `cm-wt-${hashProjectDirCanonical(normalizeWorktreePath(projectDir))}.txt`,
+  );
+}
+
+function getWorktreeSuffix(projectDir = process.cwd()) {
+  const envSuffix = process.env.CONTEXT_MODE_SESSION_SUFFIX;
+  const normalizedProjectDir = normalizeWorktreePath(projectDir);
+
+  if (
+    _wtCacheInProcess &&
+    _wtCacheInProcess.projectDir === normalizedProjectDir &&
+    _wtCacheInProcess.envSuffix === envSuffix
+  ) {
+    return _wtCacheInProcess.suffix;
+  }
+
+  let suffix;
+  if (envSuffix !== undefined) {
+    suffix = envSuffix ? `__${envSuffix}` : "";
+  } else {
+    // Try cross-process marker first.
+    const markerPath = workTreeMarkerPath(projectDir);
+    try {
+      suffix = readFileSync(markerPath, "utf-8");
+      _wtCacheInProcess = { projectDir: normalizedProjectDir, envSuffix, suffix };
+      return suffix;
+    } catch {
+      // marker missing → delegate to bundle for the canonical computation.
+    }
+
+    // Single source of truth: the bundle's getWorktreeSuffix runs the
+    // git subprocess, the case-fold comparison, and the suffix hashing.
+    // We just persist the result so other forks can skip the git call.
+    try {
+      suffix = _getWorktreeSuffixBundle(projectDir);
+    } catch {
+      // git not available or not a git repo — no suffix
+      suffix = "";
+    }
+
+    // Best-effort write so subsequent hook forks short-circuit.
+    try {
+      writeFileSync(markerPath, suffix, "utf-8");
+    } catch {
+      // tmpdir not writable — degrade gracefully
+    }
+  }
+
+  _wtCacheInProcess = { projectDir: normalizedProjectDir, envSuffix, suffix };
+  return suffix;
+}
+
+// ─────────────────────────────────────────────────────────
+// Platform options (hook-only — the server doesn't fork hooks).
+// ─────────────────────────────────────────────────────────
+
+/** Claude Code platform options (default). */
+const CLAUDE_OPTS = {
+  configDir: ".claude",
+  configDirEnv: "CLAUDE_CONFIG_DIR",
+  projectDirEnv: "CLAUDE_PROJECT_DIR",
+  sessionIdEnv: "CLAUDE_SESSION_ID",
+};
+
+/** Gemini CLI platform options. */
+export const GEMINI_OPTS = {
+  configDir: ".gemini",
+  configDirEnv: "GEMINI_CLI_HOME",
+  projectDirEnv: "GEMINI_PROJECT_DIR",
+  sessionIdEnv: undefined,
+};
+
+/**
+ * Antigravity CLI (`agy`) platform options. Shares the Gemini-family session
+ * root (~/.gemini/context-mode/sessions). agy supplies the conversation id and
+ * workspace path inside the hook payload (mapped to session_id/cwd before these
+ * opts are consulted), so no env-var fallbacks are needed.
+ */
+export const ANTIGRAVITY_CLI_OPTS = {
+  configDir: ".gemini",
+  configDirEnv: undefined,
+  projectDirEnv: undefined,
+  sessionIdEnv: undefined,
+};
+
+/** VS Code Copilot platform options. */
+export const VSCODE_OPTS = {
+  configDir: ".vscode",
+  configDirEnv: undefined,
+  projectDirEnv: "VSCODE_CWD",
+  sessionIdEnv: undefined,
+};
+
+/** GitHub Copilot CLI platform options. */
+export const COPILOT_OPTS = {
+  configDir: ".copilot",
+  configDirEnv: "COPILOT_HOME",
+  projectDirEnv: undefined,
+  sessionIdEnv: undefined,
+};
+
+/** Cursor platform options. */
+export const CURSOR_OPTS = {
+  configDir: ".cursor",
+  configDirEnv: undefined,
+  projectDirEnv: "CURSOR_CWD",
+  sessionIdEnv: "CURSOR_SESSION_ID",
+};
+
+/** Codex CLI platform options. */
+export const CODEX_OPTS = {
+  configDir: ".codex",
+  configDirEnv: "CODEX_HOME",
+  projectDirEnv: undefined,   // Codex passes cwd in hook stdin, no env var
+  sessionIdEnv: undefined,    // Uses session_id from hook stdin or ppid fallback
+};
+
+/** Kiro CLI platform options. */
+export const KIRO_OPTS = {
+  configDir: ".kiro",
+  configDirEnv: undefined,
+  projectDirEnv: undefined,   // Kiro CLI provides cwd in hook stdin, no env var
+  sessionIdEnv: undefined,    // No session ID env var — uses ppid fallback
+};
+
+/** Kimi Code CLI platform options.
+ *
+ * `KIMI_CODE_HOME` is documented at
+ *   refs/platforms/kimi-code/docs/zh/configuration/env-vars.md:11-21
+ *   refs/platforms/kimi-code/docs/en/configuration/env-vars.md:9-21
+ * and is read by MoonshotAI's own first-party plugins
+ *   refs/platforms/kimi-code/plugins/official/kimi-datasource/bin/
+ *     kimi-datasource.mjs:207-210
+ * so context-mode must honour it too — otherwise relocated Kimi installs
+ * keep the user's data root at `$KIMI_CODE_HOME` while context-mode keeps
+ * its session DB stranded at `~/.kimi-code/context-mode/sessions/`.
+ */
+export const KIMI_OPTS = {
+  configDir: ".kimi-code",
+  configDirEnv: "KIMI_CODE_HOME",
+  projectDirEnv: undefined,   // Kimi Code passes cwd in hook stdin, no env var
+  sessionIdEnv: undefined,    // Uses session_id from hook stdin or ppid fallback
+};
+
+/** JetBrains Copilot platform options. */
+export const JETBRAINS_OPTS = {
+  configDir: ".config/JetBrains",
+  configDirEnv: undefined,
+  projectDirEnv: "IDEA_INITIAL_DIRECTORY",
+  sessionIdEnv: undefined,
+};
+
+/**
+ * Resolve the platform config directory, respecting env var overrides.
+ * Platforms like Claude Code (CLAUDE_CONFIG_DIR), Gemini CLI (GEMINI_CLI_HOME),
+ * and Codex CLI (CODEX_HOME) allow users to customize the config location.
+ * Falls back to ~/<configDir> when no env var is set.
+ */
+export function resolveConfigDir(opts = CLAUDE_OPTS) {
+  if (opts.configDirEnv) {
+    const envVal = process.env[opts.configDirEnv];
+    if (envVal) {
+      if (envVal.startsWith("~")) return join(homedir(), envVal.replace(/^~[/\\]?/, ""));
+      return envVal;
+    }
+  }
+  return join(homedir(), opts.configDir);
+}
+
+/**
+ * Safely parse raw stdin string as JSON.
+ * Returns empty object for empty/whitespace/BOM-only input instead of throwing.
+ * Strips BOM prefix before parsing. Throws on genuinely malformed JSON.
+ */
+export function parseStdin(raw) {
+  const cleaned = raw.replace(/^\uFEFF/, "").trim();
+  return cleaned ? JSON.parse(cleaned) : {};
+}
+
+/**
+ * Read all of stdin as a string (event-based, cross-platform safe).
+ *
+ * Idle-timeout semantics (override via env `CONTEXT_MODE_HOOK_STDIN_IDLE_MS`,
+ * default 1500 ms):
+ * - EOF before any data \u2192 resolve("")  \u2014 the original well-behaved path.
+ * - EOF after data       \u2192 resolve(buffer) with BOM strip (#139 \u2014 Cursor on
+ *                          Windows can emit a leading U+FEFF that crashes
+ *                          downstream JSON.parse).
+ * - Idle with 0 bytes    \u2192 resolve("")  \u2014 covers hosts that hold the pipe open
+ *                          without ever closing it (issue #639 \u2014 Bun re-exec
+ *                          EOF path) so the hook still terminates.
+ * - Idle with > 0 bytes  \u2192 reject(Error) \u2014 partial data after a stall MUST NOT
+ *                          be silently truncated, otherwise downstream
+ *                          JSON.parse corrupts on large `tool_response`
+ *                          payloads (issue #242 \u2014 Gemini AfterTool >1MB).
+ *                          Visible non-zero exit is correct here; the host
+ *                          surfaces the failure in its hook diagnostics.
+ */
+export function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = "";
+    const idleMs = Number(process.env.CONTEXT_MODE_HOOK_STDIN_IDLE_MS || 1500);
+    let done = false;
+    let timer;
+
+    const cleanup = () => {
+      clearTimeout(timer);
+      process.stdin.removeListener("data", onData);
+      process.stdin.removeListener("end", onEnd);
+      process.stdin.removeListener("error", onError);
+      try { process.stdin.pause(); } catch {}
+      try { process.stdin.destroy?.(); } catch {}
+    };
+    const resolveBuffer = () => {
+      if (done) return;
+      done = true;
+      cleanup();
+      // Preserves #139 BOM strip \u2014 applies on both EOF and idle-empty paths.
+      resolve(data.replace(/^\uFEFF/, ""));
+    };
+    const rejectIdle = () => {
+      if (done) return;
+      done = true;
+      cleanup();
+      reject(new Error(
+        `stdin idle for ${idleMs}ms with ${data.length} bytes buffered`,
+      ));
+    };
+    const onIdle = () => {
+      // Zero-buffer idle = host never wrote anything (issue #639). Resolve
+      // empty so the hook can no-op. Non-zero buffer = partial data, which
+      // must reject to avoid silent JSON.parse corruption (issue #242).
+      if (data.length === 0) {
+        resolveBuffer();
+      } else {
+        rejectIdle();
+      }
+    };
+    const arm = () => {
+      clearTimeout(timer);
+      timer = setTimeout(onIdle, idleMs);
+      timer.unref?.();
+    };
+    const onData = (chunk) => {
+      data += chunk;
+      arm();
+    };
+    const onEnd = () => resolveBuffer();
+    const onError = (error) => {
+      if (done) return;
+      done = true;
+      cleanup();
+      reject(error);
+    };
+
+    process.stdin.setEncoding("utf-8");
+    process.stdin.on("data", onData);
+    process.stdin.on("end", onEnd);
+    process.stdin.on("error", onError);
+    process.stdin.resume();
+    arm();
+  });
+}
+
+/**
+ * Get the project directory for the current platform.
+ * Uses the platform-specific env var, falls back to cwd.
+ */
+export function getProjectDir(opts = CLAUDE_OPTS) {
+  return process.env[opts.projectDirEnv] || process.cwd();
+}
+
+/**
+ * Get the project directory from hook input when available.
+ * Falls back to the platform env var and finally process.cwd().
+ */
+export function getInputProjectDir(input, opts = CLAUDE_OPTS) {
+  if (typeof input?.cwd === "string" && input.cwd.length > 0) {
+    return input.cwd;
+  }
+  if (Array.isArray(input?.workspace_roots) && input.workspace_roots.length > 0) {
+    return String(input.workspace_roots[0]);
+  }
+  return getProjectDir(opts);
+}
+
+/**
+ * Derive session ID from hook input.
+ * Priority: transcript_path UUID > sessionId (camelCase) > session_id > env var > ppid fallback.
+ */
+export function getSessionId(input, opts = CLAUDE_OPTS) {
+  if (input.transcript_path) {
+    const match = input.transcript_path.match(/([a-f0-9-]{36})\.jsonl$/);
+    if (match) return match[1];
+  }
+  if (input.conversation_id) return input.conversation_id;
+  if (input.sessionId) return input.sessionId;
+  if (input.session_id) return input.session_id;
+  if (opts.sessionIdEnv && process.env[opts.sessionIdEnv]) {
+    return process.env[opts.sessionIdEnv];
+  }
+  return `pid-${process.ppid}`;
+}
+
+// ─────────────────────────────────────────────────────────
+// Per-project file paths — thin wrappers around resolveSessionPath.
+// ─────────────────────────────────────────────────────────
+
+function resolveSessionDir(opts) {
+  return ensureWritableStorageDir(
+    resolveSessionStorageDir(() => resolveDefaultSessionDir({
+      configDir: opts.configDir,
+      configDirEnv: opts.configDirEnv,
+    })),
+  );
+}
+
+function _resolveProjectFile(opts, projectDirOverride, ext) {
+  const projectDir = normalizeWorktreePath(projectDirOverride ?? getProjectDir(opts));
+  const sessionsDir = resolveSessionDir(opts);
+  mkdirSync(sessionsDir, { recursive: true });
+  return _resolveSessionPath({
+    projectDir,
+    sessionsDir,
+    suffix: getWorktreeSuffix(projectDir),
+    ext,
+  });
+}
+
+/**
+ * Return the per-project session DB path.
+ * Creates the directory if it doesn't exist.
+ * Path: ~/<configDir>/context-mode/sessions/<canonicalHash><suffix>.db
+ */
+export function getSessionDBPath(opts = CLAUDE_OPTS, projectDirOverride) {
+  return _resolveProjectFile(opts, projectDirOverride, ".db");
+}
+
+/**
+ * Return the per-project session events file path.
+ * Used by sessionstart hook (write) and MCP server (read + auto-index).
+ * Path: ~/<configDir>/context-mode/sessions/<canonicalHash><suffix>-events.md
+ */
+export function getSessionEventsPath(opts = CLAUDE_OPTS, projectDirOverride) {
+  return _resolveProjectFile(opts, projectDirOverride, "-events.md");
+}
+
+/**
+ * Return the per-project cleanup flag path.
+ * Used to detect true fresh starts vs --continue (which fires startup+resume).
+ * Path: ~/<configDir>/context-mode/sessions/<canonicalHash><suffix>.cleanup
+ */
+export function getCleanupFlagPath(opts = CLAUDE_OPTS, projectDirOverride) {
+  return _resolveProjectFile(opts, projectDirOverride, ".cleanup");
+}