git-reviewer 2.15.0 → 2.17.0

package/lib/channel.js

@@ -0,0 +1,286 @@
+'use strict';
+
+const { updateSavedComments, readSavedComments } = require('./store');
+const { watchComments } = require('./watch');
+const { announce } = require('./presence');
+const { mintKey, isKey } = require('./comments');
+const { awaitingAnswer, newReviewerMessages, appendReply, describeThread, lastAuthor } = require('./threads');
+
+/**
+ * `reviewer channel`: a Claude Code channel for one repository's review.
+ *
+ * Claude Code runs this as an MCP server over stdio, and with channels
+ * enabled for it (`--dangerously-load-development-channels server:reviewer`
+ * during the research preview) it may push messages into the running
+ * session. Every comment the reviewer writes, and every reply they add in a
+ * thread, is pushed as one; the session answers by calling `reply`, which
+ * writes the answer into the thread, where the page shows it within a
+ * second. The session is the one the reviewer chose -- `reviewer connect`
+ * resumes the session that wrote the code -- so the answers come from the
+ * agent that knows why it wrote what it wrote.
+ *
+ * The protocol is spoken directly: MCP is JSON-RPC 2.0, one message per line,
+ * and this server needs four methods of it. The SDK would bring seventeen
+ * dependencies and a second major of express into a package that has three
+ * (#4).
+ */
+
+const PROTOCOL_VERSION = '2025-11-25';
+
+// At most this many waiting threads are pushed one by one when the session
+// connects; the rest are summarised, so connecting to an old review with
+// fifty open threads does not bury the session.
+const BACKLOG_ONE_BY_ONE = 8;
+
+/** @param {string} repoPath */
+function instructionsFor(repoPath) {
+  return [
+    `reviewer is a local code review tool. While this server is connected, every comment a reviewer leaves on`,
+    `the changes in ${repoPath}, and every reply they add to a thread, arrives as a`,
+    '<channel source="reviewer" key="..." file="..." line="..."> message holding the thread so far.',
+    '',
+    'Answer each one by calling the reply tool with its key. Your reply is shown under the reviewer\'s',
+    'comment exactly as written: keep it short and direct; Markdown is fine. Answer from what you know about',
+    'why the code is the way it is, and read files when you need to check. Do not change files because of a',
+    'comment unless it explicitly asks you to make the change now; otherwise say what you would change. If',
+    'several arrive together, answer each one separately. list_comments shows what is still waiting.'
+  ].join('\n');
+}
+
+const TOOLS = [
+  {
+    name: 'reply',
+    description: 'Post a reply in a review comment thread. The reviewer sees it under their comment straight away.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        key: { type: 'string', description: 'The key of the comment, from the channel message or list_comments' },
+        text: { type: 'string', description: 'The reply, in Markdown' }
+      },
+      required: ['key', 'text']
+    }
+  },
+  {
+    name: 'list_comments',
+    description: 'List the review\'s comment threads: by default only those whose last word is the reviewer\'s.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        all: { type: 'boolean', description: 'Include threads that already have an answer' }
+      }
+    }
+  }
+];
+
+/**
+ * A thread as the session is told about it.
+ *
+ * @param {import('./comments').Comment} comment
+ * @param {boolean} followUp whether this is a new reply in a thread rather than a new comment
+ */
+function channelMessage(comment, followUp) {
+  return {
+    content: [
+      followUp ? 'The reviewer replied in a comment thread:' : 'New review comment:',
+      '',
+      describeThread(comment),
+      '',
+      `Answer with the reply tool, key "${comment.key}".`
+    ].join('\n'),
+    meta: { key: comment.key, file: comment.file, line: String(comment.line) }
+  };
+}
+
+/**
+ * Run the channel until its input closes.
+ *
+ * @param {object} options
+ * @param {string} options.repoPath repository whose review this serves
+ * @param {string} options.reviewsDir
+ * @param {NodeJS.ReadableStream} [options.input]
+ * @param {NodeJS.WritableStream} [options.output]
+ * @param {NodeJS.ProcessEnv} [options.env]
+ * @param {string} [options.version]
+ * @param {string|null} [options.title] what the connected session is about, for the page
+ * @param {(line: string) => void} [options.log] diagnostics; stdout belongs to the protocol
+ * @returns {Promise<void>} settles when the input ends
+ */
+function runChannel({
+  repoPath,
+  reviewsDir,
+  input = process.stdin,
+  output = process.stdout,
+  env = process.env,
+  version = '0.0.0',
+  title = null,
+  log = line => process.stderr.write(`reviewer channel: ${line}\n`)
+}) {
+  const session = env.CLAUDE_CODE_SESSION_ID || null;
+  const send = message => output.write(`${JSON.stringify({ jsonrpc: '2.0', ...message })}\n`);
+  const notify = (method, params) => send({ method, params });
+
+  /** @type {import('./comments').Comment[]|null} */
+  let known = null;
+  let watcher = null;
+  let presence = null;
+  const working = new Set();
+
+  const setWorking = () => presence?.update({ working: [...working] });
+
+  const push = (comment, followUp) => {
+    notify('notifications/claude/channel', channelMessage(comment, followUp));
+    working.add(comment.key);
+  };
+
+  const start = () => {
+    if (watcher) return;
+    presence = announce(reviewsDir, repoPath, { kind: 'channel', agent: 'claude', session, title });
+    watcher = watchComments(reviewsDir, repoPath, state => {
+      const comments = state.comments;
+      if (known === null) {
+        const waiting = awaitingAnswer(comments);
+        waiting.slice(0, BACKLOG_ONE_BY_ONE).forEach(comment => push(comment, (comment.followUps ?? []).length > 0));
+        if (waiting.length > BACKLOG_ONE_BY_ONE) {
+          notify('notifications/claude/channel', {
+            content: `${waiting.length - BACKLOG_ONE_BY_ONE} more comment threads in this review are waiting for an answer. ` +
+              'Call list_comments to see them, and answer each with the reply tool.',
+            meta: { waiting: String(waiting.length - BACKLOG_ONE_BY_ONE) }
+          });
+        }
+      } else {
+        for (const { comment, followUp } of newReviewerMessages(known, comments)) push(comment, followUp !== null);
+      }
+      // A thread answered from somewhere else is no longer this session's to answer.
+      for (const key of working) {
+        const thread = comments.find(comment => comment.key === key);
+        if (!thread || lastAuthor(thread) !== null) working.delete(key);
+      }
+      known = comments;
+      setWorking();
+    }, { onError: error => log(`could not read the review: ${error.message}`) });
+  };
+
+  const tools = {
+    async reply({ key, text } = {}) {
+      if (!isKey(key)) return failure('key must be the key of a comment, from the channel message or list_comments.');
+      if (typeof text !== 'string' || text.trim() === '') return failure('text must be the reply to post.');
+
+      let found = false;
+      await updateSavedComments(reviewsDir, repoPath, current => {
+        const updated = appendReply(current.comments, key, {
+          key: mintKey(),
+          text: text.trim(),
+          timestamp: new Date().toISOString(),
+          by: 'claude',
+          ...(session ? { session } : {})
+        });
+        found = updated !== null;
+        return updated ? { comments: updated } : null;
+      });
+
+      // An unknown key fails out loud: a reply that silently went nowhere
+      // would read, to the session, exactly like one the reviewer received.
+      if (!found) return failure(`No comment with key "${key}" in this review. Call list_comments for the current ones.`);
+      working.delete(key);
+      setWorking();
+      return success('Posted. The reviewer can see it under their comment now.');
+    },
+
+    async list_comments({ all = false } = {}) {
+      const { comments } = await readSavedComments(reviewsDir, repoPath);
+      const shown = all ? comments : awaitingAnswer(comments);
+      const threads = shown.map(comment => ({
+        key: comment.key,
+        file: comment.file,
+        line: comment.line,
+        waiting: lastAuthor(comment) === null,
+        thread: describeThread(comment)
+      }));
+      return success(threads.length === 0
+        ? (all ? 'This review has no comments yet.' : 'Nothing is waiting for an answer.')
+        : JSON.stringify(threads, null, 2));
+    }
+  };
+
+  const handle = async message => {
+    const { id, method, params } = message;
+    const isRequest = id !== undefined && id !== null;
+
+    switch (method) {
+      case 'initialize':
+        return send({
+          id,
+          result: {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: { tools: {}, experimental: { 'claude/channel': {} } },
+            serverInfo: { name: 'reviewer', title: 'reviewer', version },
+            instructions: instructionsFor(repoPath)
+          }
+        });
+      case 'notifications/initialized':
+        return start();
+      case 'ping':
+        return send({ id, result: {} });
+      case 'tools/list':
+        return send({ id, result: { tools: TOOLS } });
+      case 'tools/call': {
+        const tool = tools[params?.name];
+        if (!tool) return send({ id, error: { code: -32602, message: `Unknown tool: ${params?.name}` } });
+        try {
+          return send({ id, result: await tool(params.arguments ?? {}) });
+        } catch (error) {
+          return send({ id, result: failure(error.message) });
+        }
+      }
+      default:
+        // Including `server/discover`, the 2026-07-28 revision's replacement
+        // for `initialize`. Claude Code tries it first and, answered "method
+        // not found", falls back to `initialize` -- the handshake channels
+        // are documented against.
+        if (isRequest) send({ id, error: { code: -32601, message: `Method not found: ${method}` } });
+        return undefined;
+    }
+  };
+
+  return new Promise(resolve => {
+    let buffered = '';
+    let pending = Promise.resolve();
+    input.setEncoding?.('utf-8');
+    input.on('data', chunk => {
+      buffered += chunk;
+      let newline;
+      while ((newline = buffered.indexOf('\n')) >= 0) {
+        const line = buffered.slice(0, newline).trim();
+        buffered = buffered.slice(newline + 1);
+        if (!line) continue;
+        let message;
+        try {
+          message = JSON.parse(line);
+        } catch {
+          send({ id: null, error: { code: -32700, message: 'Parse error' } });
+          continue;
+        }
+        // In order: a reply must not overtake the list it was based on.
+        pending = pending.then(() => handle(message)).catch(error => log(error.message));
+      }
+    });
+    input.on('end', async () => {
+      await pending;
+      watcher?.close();
+      await presence?.close();
+      resolve();
+    });
+  });
+}
+
+/** @param {string} text */
+function success(text) {
+  return { content: [{ type: 'text', text }] };
+}
+
+/** @param {string} text */
+function failure(text) {
+  return { content: [{ type: 'text', text }], isError: true };
+}
+
+module.exports = { runChannel, channelMessage, instructionsFor, TOOLS, PROTOCOL_VERSION };

package/lib/claude-background.js

@@ -0,0 +1,316 @@
+'use strict';
+
+const { spawn: spawnProcess } = require('child_process');
+const { EventEmitter } = require('events');
+
+const { describeThread } = require('./threads');
+
+/**
+ * A Claude Code session, resumed in the background to answer review comments.
+ *
+ * The session that wrote the code is the one worth asking about it, so this
+ * resumes it -- by default as a copy, `--fork-session`, so the original
+ * transcript is left exactly as it was and can still be opened in a terminal
+ * while reviewer is using the copy. One `claude -p` process is kept running
+ * with stream-json on both ends: each question is a user message written to
+ * its stdin, and the answer streams back on stdout as it is written, which is
+ * what lets the page show it arriving instead of a spinner and then a wall of
+ * text.
+ *
+ * The copy can read the repository and nothing else. `--tools` limits it to
+ * Read, Grep and Glob, `--strict-mcp-config` keeps every MCP server the user
+ * has configured out of it -- including ones that can send mail -- and
+ * `dontAsk` turns anything that would need permission into a refusal, since
+ * nobody is there to answer a prompt. Answering a question about code needs
+ * nothing more, and a background process holding someone's credentials
+ * should not be able to do more.
+ */
+
+const TOOLS = 'Read,Grep,Glob';
+
+// Generous: a question can send the session reading through several files.
+const ANSWER_TIMEOUT_MS = 10 * 60 * 1000;
+
+/**
+ * The message a thread is put to the session as.
+ *
+ * The instructions travel with every question rather than as a system
+ * prompt, because Claude Code records a session's system prompt once and
+ * reuses it on resume: anything appended at resume time would be dropped.
+ *
+ * @param {import('./comments').Comment} comment
+ * @returns {string}
+ */
+function questionFor(comment) {
+  return [
+    'A reviewer is going through the changes you made in this repository, in reviewer (a local code',
+    'review tool), and has left a comment on your code. Here is the thread:',
+    '',
+    describeThread(comment),
+    '',
+    'Reply to the reviewer\'s latest message. Your reply is posted under their comment exactly as you',
+    'write it, so write only the reply: short, direct, Markdown is fine. Answer from what you know about',
+    'why the code is the way it is, and read files if you need to check something. Do not change any',
+    'files; if a change is warranted, say what you would change.'
+  ].join('\n');
+}
+
+class BackgroundSession extends EventEmitter {
+  /**
+   * @param {object} options
+   * @param {string} options.sessionId Claude Code session to resume
+   * @param {string} options.cwd the directory that session ran in
+   * @param {boolean} [options.fork] answer in a copy of the session (the default) rather than in it
+   * @param {string} [options.name] display name for the copy, shown in Claude Code's /resume
+   * @param {string} [options.claude] the Claude Code executable
+   * @param {typeof spawnProcess} [options.spawn]
+   * @param {number} [options.answerTimeoutMs]
+   */
+  constructor({ sessionId, cwd, fork = true, name = null, claude = 'claude', spawn = spawnProcess, answerTimeoutMs = ANSWER_TIMEOUT_MS }) {
+    super();
+    this.sessionId = sessionId;
+    this.cwd = cwd;
+    this.fork = fork;
+    this.name = name;
+    this.claude = claude;
+    this.spawnProcess = spawn;
+    this.answerTimeoutMs = answerTimeoutMs;
+
+    /** The session answering: the copy's id once Claude Code reports it. */
+    this.answeringSession = fork ? null : sessionId;
+    /** @type {Array<{key: string, prompt: string}>} */
+    this.queue = [];
+    /** @type {{key: string, text: string, timer: NodeJS.Timeout, restarted: boolean}|null} */
+    this.current = null;
+    this.child = null;
+    this.stopped = false;
+    this.stderr = '';
+  }
+
+  /** The arguments `claude` is run with, so they can be shown and tested. */
+  args() {
+    const resume = this.answeringSession ?? this.sessionId;
+    return [
+      '-p',
+      '--input-format', 'stream-json',
+      '--output-format', 'stream-json',
+      '--verbose',
+      '--include-partial-messages',
+      '--resume', resume,
+      // Fork only the first time. Once the copy exists, a restart resumes
+      // the copy, so the answers so far stay in one conversation.
+      ...(this.fork && !this.answeringSession ? ['--fork-session'] : []),
+      ...(this.name && this.fork && !this.answeringSession ? ['--name', this.name] : []),
+      '--strict-mcp-config',
+      '--tools', TOOLS,
+      '--permission-mode', 'dontAsk'
+    ];
+  }
+
+  start() {
+    if (this.child || this.stopped) return;
+    this.stderr = '';
+    let child;
+    try {
+      child = this.spawnProcess(this.claude, this.args(), {
+        cwd: this.cwd,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: process.env,
+        windowsHide: true
+      });
+    } catch (error) {
+      // Some failures are thrown rather than emitted -- on Windows, a .cmd
+      // given without a shell is refused with EINVAL. Thrown from here, it
+      // would escape through `ask` into whatever called it; reported on the
+      // next tick it fails the same way an emitted one does.
+      process.nextTick(() => this.failToStart(error));
+      return;
+    }
+    this.child = child;
+
+    let buffered = '';
+    child.stdout.setEncoding('utf-8');
+    child.stdout.on('data', chunk => {
+      buffered += chunk;
+      let newline;
+      while ((newline = buffered.indexOf('\n')) >= 0) {
+        const line = buffered.slice(0, newline);
+        buffered = buffered.slice(newline + 1);
+        if (line.trim()) this.onLine(line);
+      }
+    });
+    child.stderr.setEncoding('utf-8');
+    child.stderr.on('data', chunk => {
+      // Kept for the error message if it exits; bounded, because a session
+      // can be chatty on stderr and this lives as long as the review.
+      this.stderr = (this.stderr + chunk).slice(-4000);
+    });
+    child.stdin.on('error', () => {}); // EPIPE when it has already gone; 'exit' reports why
+    child.on('error', error => this.onExit(null, null, error));
+    child.on('exit', (code, signal) => this.onExit(code, signal, null));
+  }
+
+  /** @param {string} line */
+  onLine(line) {
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      return; // not ours to understand
+    }
+
+    if (event.type === 'system' && event.subtype === 'init' && event.session_id) {
+      if (this.answeringSession !== event.session_id) {
+        this.answeringSession = event.session_id;
+        this.emit('session', { session: event.session_id, model: event.model ?? null });
+      }
+      return;
+    }
+
+    if (!this.current) return;
+
+    if (event.type === 'stream_event') {
+      const inner = event.event;
+      if (inner?.type === 'message_start') {
+        // A turn that reads a file first produces text, a tool call, then
+        // more text. What is shown is the message being written now.
+        this.current.text = '';
+      } else if (inner?.type === 'content_block_delta' && inner.delta?.type === 'text_delta') {
+        this.current.text += inner.delta.text;
+        this.emit('partial', { key: this.current.key, text: this.current.text });
+      }
+      return;
+    }
+
+    if (event.type === 'result') {
+      const { key, timer } = this.current;
+      clearTimeout(timer);
+      this.current = null;
+      const text = typeof event.result === 'string' ? event.result.trim() : '';
+      if (event.is_error || event.subtype !== 'success' || text === '') {
+        this.emit('failed', { key, message: text || `Claude Code could not answer (${event.subtype ?? 'error'}).` });
+      } else {
+        this.emit('answer', { key, text, session: event.session_id ?? this.answeringSession });
+      }
+      this.next();
+    }
+  }
+
+  /** @param {Error & {code?: string}} error */
+  describeSpawnError(error) {
+    const where = process.platform === 'win32' ? ' (the full path of claude.exe)' : '';
+    return ['ENOENT', 'EINVAL'].includes(error.code)
+      ? `Could not run "${this.claude}": is Claude Code installed and on your PATH? Set REVIEWER_CLAUDE to its path otherwise${where}.`
+      : `Could not run "${this.claude}": ${error.message}`;
+  }
+
+  /** It could not be started: everything waiting fails, once, with why. */
+  failToStart(error) {
+    const message = this.describeSpawnError(error);
+    for (const { key } of this.queue.splice(0)) this.emit('failed', { key, message });
+    this.emit('exit', { code: null, signal: null, stderr: '', message, fatal: true });
+  }
+
+  onExit(code, signal, error) {
+    if (!this.child) return;
+    this.child = null;
+    const current = this.current;
+    if (current) clearTimeout(current.timer);
+    this.current = null;
+
+    if (this.stopped) {
+      this.emit('exit', { code, signal, stderr: this.stderr });
+      return;
+    }
+
+    const message = error
+      ? this.describeSpawnError(error)
+      : (this.stderr.trim().split('\n').slice(-3).join('\n') || `Claude Code exited (${signal ?? `code ${code}`}).`);
+
+    // A process that dies mid-answer gets one more go with the same
+    // question; one that cannot even start reports why and stops trying.
+    if (current && !current.restarted && !error) {
+      this.queue.unshift({ key: current.key, prompt: current.prompt, restarted: true });
+      this.start();
+      this.next();
+      return;
+    }
+    if (current) this.emit('failed', { key: current.key, message });
+    // `fatal`: it could not be started at all, so asking again would only
+    // fail the same way. Whoever owns this session should give up on it.
+    if (error) {
+      for (const { key } of this.queue.splice(0)) this.emit('failed', { key, message });
+    }
+    this.emit('exit', { code, signal, stderr: this.stderr, message, fatal: Boolean(error) });
+  }
+
+  /**
+   * Put a thread to the session. Questions are answered one at a time, in
+   * order: a turn's answer is matched to its question by being the next to
+   * finish, so a second question is not written until the first is done.
+   *
+   * @param {string} key comment key the answer belongs to
+   * @param {string} prompt
+   */
+  ask(key, prompt) {
+    if (this.stopped) return;
+    this.queue.push({ key, prompt, restarted: false });
+    this.start();
+    this.next();
+  }
+
+  next() {
+    if (this.current || !this.child || this.queue.length === 0) return;
+    const { key, prompt, restarted } = this.queue.shift();
+    const timer = setTimeout(() => {
+      // Nothing came back. Stop this process; the question fails, and the
+      // next one starts a fresh process on the same conversation.
+      if (this.current?.key !== key) return;
+      this.current = null;
+      this.emit('failed', { key, message: 'No answer after ten minutes; gave up on this one.' });
+      this.child?.kill();
+    }, this.answerTimeoutMs);
+    timer.unref();
+    this.current = { key, prompt, text: '', timer, restarted };
+    this.emit('working', { key });
+    this.child.stdin.write(`${JSON.stringify({ type: 'user', message: { role: 'user', content: prompt } })}\n`);
+  }
+
+  /** Whether it is answering something or has questions waiting. */
+  get busy() {
+    return Boolean(this.current) || this.queue.length > 0;
+  }
+
+  /** Keys of the threads being answered or waiting, in order. */
+  get pending() {
+    return [...(this.current ? [this.current.key] : []), ...this.queue.map(item => item.key)];
+  }
+
+  /**
+   * Stop the process, now.
+   *
+   * Nothing it is in the middle of is wanted any more, and a turn can run
+   * for minutes -- left to finish, it would outlive the reviewer that started
+   * it. It is asked to stop straight away, and killed if it has not gone in
+   * three seconds.
+   *
+   * @returns {Promise<void>}
+   */
+  stop() {
+    this.stopped = true;
+    this.queue = [];
+    if (this.current) clearTimeout(this.current.timer);
+    const child = this.child;
+    if (!child) return Promise.resolve();
+    return new Promise(resolve => {
+      child.once('exit', () => resolve());
+      child.stdin.end();
+      child.kill('SIGTERM');
+      setTimeout(() => child.kill('SIGKILL'), 3000).unref();
+      // Never hold up a shutdown on a process that will not say it is gone.
+      setTimeout(resolve, 5000).unref();
+    });
+  }
+}
+
+module.exports = { BackgroundSession, questionFor, TOOLS };

package/lib/claude-command.js

@@ -0,0 +1,90 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * The Claude Code executable, as something `spawn` can start without a shell.
+ *
+ * Everywhere but Windows that is just the name: `spawn` searches the PATH.
+ * On Windows `spawn` runs only `.exe` and `.com` files without a shell, and
+ * refuses a `.cmd` outright (EINVAL, since Node 18.20.2 and 20.12.2). Claude
+ * Code installed through npm is reached through exactly that, a `claude.cmd`
+ * shim. The npm package carries the native `claude.exe` the shim starts,
+ * though, so that is found and run directly.
+ *
+ * A shell is never the answer here. The arguments include a session's title
+ * and an inline MCP config, and cmd.exe would read their quotes and
+ * metacharacters as its own.
+ *
+ * @param {string} command `claude`, or a path from REVIEWER_CLAUDE
+ * @param {object} [options] injectable for tests
+ * @param {string} [options.platform]
+ * @param {NodeJS.ProcessEnv} [options.env]
+ * @param {(file: string) => boolean} [options.exists]
+ * @param {(file: string) => string} [options.read]
+ * @returns {string}
+ */
+function resolveClaudeCommand(command, {
+  platform = process.platform,
+  env = process.env,
+  exists = fs.existsSync,
+  read = file => fs.readFileSync(file, 'utf-8')
+} = {}) {
+  if (platform !== 'win32') return command;
+  const win = path.win32;
+
+  const candidates = [];
+  if (/[\\/]/.test(command)) {
+    candidates.push(command);
+  } else {
+    const extensions = win.extname(command) ? [''] : ['.exe', '.com', '.cmd', '.bat'];
+    for (const dir of (env.PATH ?? env.Path ?? '').split(';').filter(Boolean)) {
+      for (const extension of extensions) candidates.push(win.join(dir, `${command}${extension}`));
+    }
+  }
+
+  for (const candidate of candidates) {
+    if (!exists(candidate)) continue;
+    const extension = win.extname(candidate).toLowerCase();
+    if (extension === '.exe' || extension === '.com') return candidate;
+    if (extension === '.cmd' || extension === '.bat') {
+      const target = shimTarget(candidate, { exists, read });
+      if (target) return target;
+    }
+  }
+
+  // Nothing better found: spawn fails, and the error says what to set.
+  return command;
+}
+
+/**
+ * The executable an npm `.cmd` shim starts.
+ *
+ * Where npm puts the package beside the shim, the binary is at a known
+ * place. Otherwise the shim names it: npm's shims start the target as
+ * `"%dp0%\path\to\target.exe"`, relative to the shim's own directory.
+ *
+ * @param {string} shim
+ * @param {{exists: (file: string) => boolean, read: (file: string) => string}} io
+ * @returns {string|null}
+ */
+function shimTarget(shim, { exists, read }) {
+  const win = path.win32;
+  const dir = win.dirname(shim);
+  const packaged = win.join(dir, 'node_modules', '@anthropic-ai', 'claude-code', 'bin', 'claude.exe');
+  if (exists(packaged)) return packaged;
+
+  let text;
+  try {
+    text = read(shim);
+  } catch {
+    return null;
+  }
+  const named = text.match(/"%~?dp0%?\\([^"]+\.exe)"/i);
+  if (!named) return null;
+  const target = win.join(dir, named[1]);
+  return exists(target) ? target : null;
+}
+
+module.exports = { resolveClaudeCommand };