Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

3.0 KB
Raw Blame
/**
 * How init opens a file it did not write (b5 review): transcripts, how-to
 * files, and the pointers in its own record, which an agent can edit.
 *
 * - `openPlain` never waits on a FIFO or a device (O_NONBLOCK, then a
 *   plain-file check on the open descriptor, so a file swapped after a stat
 *   is still caught) and, unless asked, never follows a link.
 * - `claudeTranscript` says whether a path is a transcript where Claude Code
 *   keeps them, `~/.claude/projects/<folder>/<name>.jsonl` (HOME from env, as
 *   discovery reads it), reached with no link on the way: a file the agent
 *   wrote anywhere else, or linked into that folder, is not one.
 */
import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync } from 'node:fs';
import { homedir } from 'node:os';
import { basename, dirname, join } from 'node:path';

/** A read-only descriptor of a plain file, or a throw. `follow`: a link to a plain file is allowed. */
export function openPlain(path: string, opts: { follow?: boolean } = {}): number {
  const flags = constants.O_RDONLY | (constants.O_NONBLOCK ?? 0) | (opts.follow ? 0 : constants.O_NOFOLLOW ?? 0);
  // Windows has no O_NOFOLLOW, and open follows a link there: refuse one seen before the open.
  if (!opts.follow && constants.O_NOFOLLOW === undefined && lstatSync(path).isSymbolicLink()) throw new Error('a link');
  const fd = openSync(path, flags);
  try {
    if (!fstatSync(fd).isFile()) throw new Error('not a plain file');
  } catch (e) {
    closeSync(fd);
    throw e;
  }
  return fd;
}

/** A plain file's text (no link, no FIFO) of at most `max` bytes; null otherwise. Never throws. */
export function readPlain(path: string, max: number): string | null {
  let fd = -1;
  try {
    fd = openPlain(path);
    const size = fstatSync(fd).size;
    if (size > max) return null;
    const buf = Buffer.alloc(size);
    const n = readSync(fd, buf, 0, size, 0);
    return buf.toString('utf8', 0, n);
  } catch {
    return null;
  } finally {
    if (fd >= 0) try { closeSync(fd); } catch { /* closed */ }
  }
}

/** Claude Code's projects folder for `env`, real path; null when there is none. */
export function claudeProjectsDir(env: NodeJS.ProcessEnv = process.env): string | null {
  try {
    return realpathSync(join(env.HOME || homedir(), '.claude', 'projects'));
  } catch {
    return null;
  }
}

/** `path` is `<projects>/<folder>/<name>.jsonl`, a plain file, with no link in the folder or the file itself. */
export function claudeTranscript(path: string, env: NodeJS.ProcessEnv = process.env): boolean {
  try {
    if (typeof path !== 'string' || !path.endsWith('.jsonl')) return false;
    const root = claudeProjectsDir(env);
    if (!root) return false;
    // Neither the file nor its folder is a link, and the folder is one of the projects folder's own.
    if (!lstatSync(path).isFile() || !lstatSync(dirname(path)).isDirectory()) return false;
    const folder = realpathSync(dirname(path));
    return dirname(folder) === root && lstatSync(join(root, basename(folder))).isDirectory();
  } catch {
    return false;
  }
}