git-reviewer 2.15.0 → 2.16.0

package/lib/claude-sessions.js

@@ -0,0 +1,229 @@
+'use strict';
+
+const fsp = require('fs').promises;
+const os = require('os');
+const path = require('path');
+
+const { canonicalRepoPath } = require('./review');
+
+/**
+ * Finding the Claude Code sessions that worked in a repository.
+ *
+ * The session worth asking about a change is the one that made it: it read
+ * the code, chose the approach and remembers why. Claude Code keeps each
+ * session's transcript as a JSON-lines file under its config directory,
+ * filed by the working directory it ran in, and that is what is read here --
+ * only the first and last few kilobytes of each, for its working directory,
+ * its name and the first thing it was asked.
+ */
+
+// Enough of the head for the first prompt and the working directory, and of
+// the tail for a name given later in the session, without reading a
+// transcript that can run to tens of megabytes.
+const SLICE_BYTES = 64 * 1024;
+const PROMPT_CHARS = 240;
+
+/** Where Claude Code keeps its state: `CLAUDE_CONFIG_DIR`, or `~/.claude`. */
+function claudeConfigDir(env = process.env) {
+  return env.CLAUDE_CONFIG_DIR ? path.resolve(env.CLAUDE_CONFIG_DIR) : path.join(os.homedir(), '.claude');
+}
+
+/**
+ * The directory name Claude Code files a working directory's sessions under:
+ * the path with every character that is not a letter or a digit turned into
+ * `-`. `/home/you/work/api` becomes `-home-you-work-api`.
+ *
+ * @param {string} dir
+ */
+function projectDirName(dir) {
+  return dir.replace(/[^A-Za-z0-9]/g, '-');
+}
+
+/** A session id as Claude Code writes them: a UUID. */
+const SESSION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * @param {string} file
+ * @param {number} start
+ * @param {number} length
+ * @returns {Promise<string>}
+ */
+async function readSlice(file, start, length) {
+  const handle = await fsp.open(file, 'r');
+  try {
+    const buffer = Buffer.alloc(length);
+    const { bytesRead } = await handle.read(buffer, 0, length, start);
+    return buffer.subarray(0, bytesRead).toString('utf-8');
+  } finally {
+    await handle.close();
+  }
+}
+
+/**
+ * The records in a slice of a transcript. A slice cut mid-line yields a
+ * fragment at either end, which does not parse and is skipped.
+ *
+ * @param {string} text
+ * @returns {object[]}
+ */
+function records(text) {
+  const parsed = [];
+  for (const line of text.split('\n')) {
+    if (!line.startsWith('{')) continue;
+    try {
+      parsed.push(JSON.parse(line));
+    } catch {
+      /* a fragment */
+    }
+  }
+  return parsed;
+}
+
+/**
+ * What a person typed, out of a transcript's user message -- not a tool
+ * result, and not the wrappers Claude Code puts around slash commands and
+ * reminders, which all open with a tag.
+ *
+ * @param {unknown} content
+ * @returns {string|null}
+ */
+function promptText(content) {
+  let text = null;
+  if (typeof content === 'string') {
+    text = content;
+  } else if (Array.isArray(content)) {
+    text = content.find(block => block?.type === 'text' && typeof block.text === 'string')?.text ?? null;
+  }
+  if (!text) return null;
+  text = text.trim();
+  if (text === '' || text.startsWith('<') || text.startsWith('Caveat:')) return null;
+  const flat = text.replace(/\s+/g, ' ');
+  return flat.length > PROMPT_CHARS ? `${flat.slice(0, PROMPT_CHARS - 1)}…` : flat;
+}
+
+/**
+ * @typedef {object} ClaudeSession
+ * @property {string} id
+ * @property {string} cwd the directory it ran in
+ * @property {string|null} title the name it was given, or Claude Code's summary of it
+ * @property {string|null} firstPrompt
+ * @property {string|null} branch git branch when it started
+ * @property {string} updatedAt when it last wrote anything
+ */
+
+/**
+ * Read what a transcript says about itself.
+ *
+ * @param {string} file
+ * @returns {Promise<ClaudeSession|null>} null for a file that is not a session transcript
+ */
+async function describeSession(file) {
+  const id = path.basename(file, '.jsonl');
+  if (!SESSION_ID_PATTERN.test(id)) return null;
+
+  const stat = await fsp.stat(file);
+  const head = await readSlice(file, 0, SLICE_BYTES);
+  const tail = stat.size > SLICE_BYTES ? await readSlice(file, stat.size - SLICE_BYTES, SLICE_BYTES) : '';
+
+  let cwd = null;
+  let branch = null;
+  let firstPrompt = null;
+  let title = null;
+  let summary = null;
+
+  for (const record of [...records(head), ...records(tail)]) {
+    if (typeof record.cwd === 'string') cwd ??= record.cwd;
+    if (typeof record.gitBranch === 'string' && record.gitBranch !== '') branch ??= record.gitBranch;
+    if (!firstPrompt && record.type === 'user' && !record.isMeta && !record.isSidechain) {
+      firstPrompt = promptText(record.message?.content);
+    }
+    // Later records win: a session renamed halfway through goes by its new name.
+    if (record.type === 'custom-title' && typeof record.customTitle === 'string') title = record.customTitle;
+    if (record.type === 'summary' && typeof record.summary === 'string') summary = record.summary;
+  }
+
+  if (!cwd) return null;
+  return { id, cwd, title: title ?? summary ?? null, firstPrompt, branch, updatedAt: stat.mtime.toISOString() };
+}
+
+/** @param {string} child @param {string} parent */
+function isInside(child, parent) {
+  const relative = path.relative(parent, child);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+/**
+ * Claude Code sessions that ran in a repository or any directory inside it,
+ * most recently active first.
+ *
+ * @param {string} repoPath
+ * @param {object} [options]
+ * @param {string} [options.configDir]
+ * @param {number} [options.limit]
+ * @returns {Promise<ClaudeSession[]>}
+ */
+async function listClaudeSessions(repoPath, { configDir = claudeConfigDir(), limit = 20 } = {}) {
+  const projects = path.join(configDir, 'projects');
+  const root = canonicalRepoPath(repoPath);
+  // The encoding loses information -- `/a/b-c` and `/a/b/c` share a name --
+  // so a matching directory is only a candidate. Each transcript's own
+  // working directory is what decides.
+  const prefixes = [...new Set([projectDirName(root), projectDirName(path.resolve(repoPath))])];
+
+  let dirs;
+  try {
+    dirs = (await fsp.readdir(projects, { withFileTypes: true }))
+      .filter(entry => entry.isDirectory() && prefixes.some(prefix => entry.name.startsWith(prefix)))
+      .map(entry => path.join(projects, entry.name));
+  } catch (error) {
+    if (error.code === 'ENOENT') return [];
+    throw error;
+  }
+
+  const candidates = [];
+  for (const dir of dirs) {
+    for (const entry of await fsp.readdir(dir, { withFileTypes: true }).catch(() => [])) {
+      if (!entry.isFile() || !entry.name.endsWith('.jsonl')) continue;
+      const file = path.join(dir, entry.name);
+      const stat = await fsp.stat(file).catch(() => null);
+      if (stat) candidates.push({ file, mtimeMs: stat.mtimeMs });
+    }
+  }
+  candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+
+  const sessions = [];
+  for (const { file } of candidates) {
+    if (sessions.length >= limit) break;
+    const session = await describeSession(file).catch(() => null);
+    if (!session || !(session.firstPrompt || session.title)) continue;
+    if (!isInside(canonicalRepoPath(session.cwd), root)) continue;
+    sessions.push(session);
+  }
+  return sessions;
+}
+
+/**
+ * One session of a repository, by id -- or null, which is the answer for an
+ * id that is malformed, unknown, or belongs to another repository.
+ *
+ * @param {string} repoPath
+ * @param {string} id
+ * @param {object} [options]
+ * @param {string} [options.configDir]
+ * @returns {Promise<ClaudeSession|null>}
+ */
+async function findClaudeSession(repoPath, id, { configDir = claudeConfigDir() } = {}) {
+  if (typeof id !== 'string' || !SESSION_ID_PATTERN.test(id)) return null;
+  const sessions = await listClaudeSessions(repoPath, { configDir, limit: Infinity });
+  return sessions.find(session => session.id === id) ?? null;
+}
+
+module.exports = {
+  listClaudeSessions,
+  findClaudeSession,
+  describeSession,
+  claudeConfigDir,
+  projectDirName,
+  promptText,
+  SESSION_ID_PATTERN
+};

package/lib/cli.js

@@ -2,6 +2,8 @@
 
 const path = require('path');
 
+const { KEY_PATTERN, AUTHOR_PATTERN } = require('./comments');
+
 /**
  * Command-line parsing for the `reviewer` command.
  *
@@ -15,6 +17,10 @@ function usage(name = 'git reviewer') {
 Usage:
   ${name} [repository] [options]
   ${name} export [repository] [--format json|prompt] [--file <path>]
+  ${name} connect [repository] [--session <id>] [--fork] [--list]
+  ${name} reply <key> <text | -> [--repo <path>] [--as <name>]
+  ${name} watch [repository]
+  ${name} channel [repository]
 
 One program, two names. git reviewer is the name the package is installed as
 -- git runs any git-<name> on your PATH as a subcommand -- and reviewer is the
@@ -38,6 +44,17 @@ Arguments:
 Commands:
   export            Print the saved review of a repository to stdout, for a
                     coding agent or another tool to consume.
+  connect           Resume the Claude Code session that worked in this
+                    repository with reviewer attached: every comment you
+                    write is sent to it, and it answers in the thread.
+                    --list shows the sessions; --session picks one.
+  reply             Post a reply in a comment thread, as an agent: the
+                    page shows it under the comment straight away. Use -
+                    as the text to read it from stdin.
+  watch             Print each new comment or reply from the reviewer as
+                    one JSON line, for an agent to follow and answer.
+  channel           The MCP server Claude Code runs for connect. Not
+                    something to run by hand.
 
 Options:
   -p, --port <n>    Port to listen on (default 4500; falls back to a free
@@ -49,6 +66,12 @@ Options:
       --json        Print one JSON line on stderr at startup instead of the banner
   -f, --format <f>  Export format: json (default) or prompt
       --file <path> Export comments for one repo-relative file
+      --session <id> connect: the Claude Code session to resume
+      --fork        connect: answer in a copy of the session
+      --list        connect: list this repository's sessions
+      --repo <path> reply: the repository (default: the current one)
+      --as <name>   reply: who the reply is from (default: claude inside
+                    Claude Code, agent elsewhere)
   -h, --help        Show this help
   -v, --version     Show the version
 
@@ -67,12 +90,17 @@ Examples:
       only the comments on one file
   ${name} export . --format prompt | claude -p "apply this review"
       hand over a review written earlier
+  ${name} connect
+      have the session that wrote the code answer your comments
 `;
 }
 
 /** Formats `reviewer export` can print. */
 const FORMATS = ['json', 'prompt'];
 
+/** Words that, first on the command line, name a subcommand. */
+const COMMANDS = ['export', 'connect', 'reply', 'watch', 'channel'];
+
 class UsageError extends Error {
   /** @param {string} message */
   constructor(message) {
@@ -83,7 +111,7 @@ class UsageError extends Error {
 
 /**
  * @typedef {object} CliOptions
- * @property {'serve'|'export'} command
+ * @property {'serve'|'export'|'connect'|'reply'|'watch'|'channel'} command
  * @property {string|null} repoPath absolute path, or null when not given
  * @property {number|null} port explicit port, or null to use the default
  * @property {boolean} open whether to launch a browser
@@ -93,6 +121,13 @@ class UsageError extends Error {
  * @property {boolean} json whether to print the startup info as one JSON line
  * @property {'json'|'prompt'} format for `export`
  * @property {string|null} file repo-relative file to export, or all files
+ * @property {string|null} session `connect`: Claude Code session id
+ * @property {boolean} fork `connect`: resume a copy of the session
+ * @property {boolean} list `connect`: list sessions instead of connecting
+ * @property {string|null} key `reply`: the comment to reply to
+ * @property {string|null} text `reply`: what to say
+ * @property {boolean} textFromStdin `reply`: the text is to be read from stdin
+ * @property {string|null} as `reply`: who it is from
  * @property {boolean} help
  * @property {boolean} version
  */
@@ -118,23 +153,48 @@ function parseArgs(argv, cwd = process.cwd()) {
     json: false,
     format: 'json',
     file: null,
+    session: null,
+    fork: false,
+    list: false,
+    key: null,
+    text: null,
+    textFromStdin: false,
+    as: null,
     help: false,
     version: false
   };
   let positional = null;
+  const positionals = [];
+  let replyRepo = null;
 
-  // A leading `export` is the subcommand. Anywhere else it is an ordinary
-  // path, so a directory that happens to be named `export` is still reviewable
-  // as `reviewer ./export`.
+  // A leading command word is the subcommand. Anywhere else it is an
+  // ordinary path, so a directory that happens to be named `export` is still
+  // reviewable as `reviewer ./export`.
   let rest = argv;
-  if (argv[0] === 'export') {
-    options.command = 'export';
+  if (COMMANDS.includes(argv[0])) {
+    options.command = argv[0];
     rest = argv.slice(1);
   }
 
   for (let i = 0; i < rest.length; i++) {
     const arg = rest[i];
 
+    // A reply is prose, and prose starts with "- " as often as anything:
+    // a Markdown list. After the key, a word that is not one of reply's own
+    // options is part of the reply, and `--` makes everything after it so.
+    if (options.command === 'reply') {
+      if (arg === '--') {
+        positionals.push(...rest.slice(i + 1));
+        break;
+      }
+      const ownOption = ['--repo', '--as', '-h', '--help', '-v', '--version'].includes(arg) ||
+        /^--(repo|as)=/.test(arg);
+      if (positionals.length > 0 && !ownOption) {
+        positionals.push(arg);
+        continue;
+      }
+    }
+
     switch (arg) {
       case '-h':
       case '--help':
@@ -188,6 +248,37 @@ function parseArgs(argv, cwd = process.cwd()) {
         break;
       }
 
+      case '--session': {
+        const value = rest[++i];
+        if (value === undefined || value.startsWith('-')) throw new UsageError('--session needs a session id');
+        options.session = value;
+        break;
+      }
+
+      case '--fork':
+        options.fork = true;
+        break;
+
+      case '--list':
+        options.list = true;
+        break;
+
+      case '--repo': {
+        const value = rest[++i];
+        if (value === undefined || value.startsWith('-')) throw new UsageError('--repo needs a repository path');
+        replyRepo = value;
+        break;
+      }
+
+      case '--as': {
+        const value = rest[++i];
+        if (value === undefined || !AUTHOR_PATTERN.test(value)) {
+          throw new UsageError('--as needs a short name, such as claude');
+        }
+        options.as = value;
+        break;
+      }
+
       default: {
         // Support --port=4500 as well as --port 4500.
         const inlinePort = arg.match(/^--port=(.*)$/);
@@ -208,10 +299,30 @@ function parseArgs(argv, cwd = process.cwd()) {
           break;
         }
 
+        const inlineRepo = arg.match(/^--repo=(.+)$/);
+        if (inlineRepo) {
+          replyRepo = inlineRepo[1];
+          break;
+        }
+
+        const inlineAs = arg.match(/^--as=(.*)$/);
+        if (inlineAs) {
+          if (!AUTHOR_PATTERN.test(inlineAs[1])) throw new UsageError('--as needs a short name, such as claude');
+          options.as = inlineAs[1];
+          break;
+        }
+
         if (arg.startsWith('-') && arg !== '-') {
           throw new UsageError(`Unknown option: ${arg}`);
         }
 
+        // `reply <key> <text...>` takes words, not a repository: the reply
+        // is everything after the key, so it need not be quoted.
+        if (options.command === 'reply') {
+          positionals.push(arg);
+          break;
+        }
+
         if (positional !== null) {
           throw new UsageError(`Unexpected argument: ${arg}`);
         }
@@ -225,6 +336,29 @@ function parseArgs(argv, cwd = process.cwd()) {
     options.repoPath = path.resolve(cwd, positional);
   }
 
+  if (options.command === 'reply') {
+    if (!options.help && !options.version) {
+      const [key, ...words] = positionals;
+      if (!key || !KEY_PATTERN.test(key)) throw new UsageError('reply needs the key of the comment to reply to');
+      const text = words.join(' ').trim();
+      if (text === '') throw new UsageError('reply needs the text of the reply, or - to read it from stdin');
+      options.key = key;
+      // `-` alone: the reply is on stdin, which suits an answer of several
+      // lines and quotes that a shell would otherwise have to survive.
+      options.text = text === '-' ? null : text;
+      options.textFromStdin = text === '-';
+    }
+    if (replyRepo !== null) options.repoPath = path.resolve(cwd, replyRepo);
+  } else if (replyRepo !== null) {
+    throw new UsageError('--repo is only valid with reviewer reply; name the repository directly');
+  }
+  if (options.as !== null && options.command !== 'reply') {
+    throw new UsageError('--as is only valid with reviewer reply');
+  }
+  for (const [flag, set] of [['--session', options.session !== null], ['--fork', options.fork], ['--list', options.list]]) {
+    if (set && options.command !== 'connect') throw new UsageError(`${flag} is only valid with reviewer connect`);
+  }
+
   if (options.file !== null && options.command !== 'export') {
     throw new UsageError('--file is only valid with reviewer export');
   }
@@ -242,6 +376,12 @@ function parseArgs(argv, cwd = process.cwd()) {
   if (options.json && options.command !== 'serve') {
     throw new UsageError('--json is only valid when serving a review');
   }
+  if (options.port !== null && options.command !== 'serve') {
+    throw new UsageError('--port is only valid when serving a review');
+  }
+  if (!options.open && options.command !== 'serve') {
+    throw new UsageError('--no-open is only valid when serving a review');
+  }
   return options;
 }
 
@@ -337,4 +477,4 @@ function invokedAs(env, argv1) {
 
 const USAGE = usage();
 
-module.exports = { parseArgs, buildUrl, UsageError, USAGE, FORMATS, usage, invokedAs };
+module.exports = { parseArgs, buildUrl, UsageError, USAGE, FORMATS, COMMANDS, usage, invokedAs };