diffsplain 0.1.0 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # Diffsplain
 
-Review a Git diff one file at a time, with a short Codex note beside each
+Review a Git diff one file at a time, with a short coding agent note beside each
 patch.
 
 ## Use
@@ -11,9 +11,11 @@ Run from a Git checkout:
 npx diffsplain
 ```
 
-The command opens [http://localhost:3000](http://localhost:3000) and compares
-the checkout with its default branch. You need Node.js 22.13 or newer and a
-signed-in Codex CLI. Pull requests also need a signed-in GitHub CLI.
+The command opens a local page and compares the checkout with its default
+branch. It starts at port `2299` and uses the next free port when needed. You
+need Node.js 22.13 or newer and a signed-in Codex, Claude, Copilot, or OpenCode
+CLI. Diffsplain tries them in that order. Pull requests also need a signed-in
+GitHub CLI.
 
 Common targets:
 
@@ -33,13 +35,15 @@ Arguments:
 | `--branch NAME` | Compare a remote branch with its default branch. |
 | `--worktree` | Review tracked and untracked changes against `HEAD`. |
 | `--base REF --head REF` | Review an exact local range. |
-| `--agent [codex]`, `--no-agent` | Enable Codex notes, or show a plain diff. |
-| `--model NAME` | Choose the Codex model used for notes. |
+| `--agent NAME`, `--no-agent` | Choose a coding agent, or show a plain diff. |
+| `--model NAME` | Choose the model used for notes. |
 | `--reasoning LEVEL` | Set `minimal`, `low`, `medium`, `high`, or `xhigh`. |
-| `--batch-size COUNT` | Set files per Codex pass. The default is `4`. |
+| `--batch-size COUNT` | Set files per agent pass. The default is `4`. |
+| `--force` | Regenerate all agent notes instead of using cached notes. |
 | `--remote NAME\|URL` | Choose the Git remote. The default is `origin`. |
-| `--port NUMBER` | Choose the local port. The default is `3000`. |
-| `--help` | Show command help. |
+| `--port NUMBER` | Choose an exact local port. The default starts at `2299`. |
+| `-h`, `--help` | Show command help. |
+| `-v`, `--version` | Show the installed version. |
 
 ## Local development
 

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "diffsplain",
-  "version": "0.1.0",
-  "description": "Review Git diffs one file at a time with Codex notes beside each patch.",
+  "version": "0.2.1",
+  "description": "Review Git diffs one file at a time with coding agent notes beside each patch.",
   "keywords": [
     "codex",
+    "claude",
+    "copilot",
+    "opencode",
     "diff",
     "git",
     "github",
@@ -12,11 +15,11 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/itsjling/diff-presenter.git"
+    "url": "git+https://github.com/itsjling/diffsplain.git"
   },
-  "homepage": "https://github.com/itsjling/diff-presenter#readme",
+  "homepage": "https://github.com/itsjling/diffsplain#readme",
   "bugs": {
-    "url": "https://github.com/itsjling/diff-presenter/issues"
+    "url": "https://github.com/itsjling/diffsplain/issues"
   },
   "bin": {
     "diffsplain": "scripts/present.mjs"
@@ -29,12 +32,13 @@
     "node": ">=22.13.0"
   },
   "scripts": {
-    "dev": "vite --port 3000",
+    "dev": "vite --port 2299",
     "docs:dev": "cd docs && blume dev",
     "docs:build": "cd docs && blume build",
     "docs:check": "cd docs && blume check && blume validate",
     "docs:preview": "cd docs && blume preview",
     "present": "node scripts/present.mjs",
+    "release": "node scripts/release.mjs",
     "summarize": "node scripts/generate-summaries.mjs",
     "snapshot": "node scripts/build-diff-data.mjs",
     "watch:diff": "node scripts/build-diff-data.mjs --watch",

package/scripts/cli-args.mjs

@@ -1,5 +1,6 @@
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { codingAgents } from './coding-agents.mjs';
 
 const valueOptions = new Set([
   '--repo',
@@ -19,8 +20,10 @@ const valueOptions = new Set([
 ]);
 const flagOptions = new Set([
   '--help',
+  '--version',
   '--agent',
   '--no-agent',
+  '--force',
   '--worktree',
 ]);
 const pathOptions = new Set([
@@ -45,26 +48,33 @@ Targets:
 Options:
   --repo PATH|URL|OWNER/NAME
                       Repo to review (default: current repo)
-  --agent [codex]     Coding agent (default: codex)
+  --agent NAME        Use codex, claude, copilot, or opencode
   --no-agent          Do not write agent notes
-  --model NAME        Codex model for agent notes
-  --reasoning LEVEL   Codex reasoning effort for agent notes
+  --model NAME        Model for agent notes
+  --reasoning LEVEL   Agent reasoning effort when supported
   --batch-size COUNT  Files per agent pass (default: 4)
+  --force             Regenerate all agent notes
   --remote NAME|URL   Git remote (default: origin)
-  --port NUMBER       Local page port (default: 3000)
-  --help              Show this help
+  --port NUMBER       Local page port (default: 2299)
+  -h, --help          Show this help
+  -v, --version       Show the installed version
+
+Agent fallback:
+  codex, claude, copilot, opencode
 
 Examples:
   diffsplain
   diffsplain --repo owner/project --pr 42
   diffsplain owner/project --branch feature/search
-  diffsplain --agent codex`;
+  diffsplain --agent claude`;
 
 function fail(message) {
   throw new Error(message);
 }
 
 function splitOption(argument) {
+  if (argument === '-h') return { name: '--help', value: undefined };
+  if (argument === '-v') return { name: '--version', value: undefined };
   if (!argument.startsWith('--')) return undefined;
   const separator = argument.indexOf('=');
   if (separator === -1) return { name: argument, value: undefined };
@@ -108,7 +118,7 @@ export function parseCliArgs(
 ) {
   const options = new Map();
   const positionals = [];
-  let agent = 'codex';
+  let agent;
   let agentSet = false;
   let noAgent = false;
 
@@ -121,18 +131,15 @@ export function parseCliArgs(
     }
 
     if (parsed.name === '--agent') {
+      agentSet = true;
       if (parsed.value !== undefined) {
         if (!parsed.value) fail('--agent needs a value');
         agent = parsed.value;
-        agentSet = true;
       } else {
         const next = rawArgs[index + 1];
         if (next && !next.startsWith('-')) {
           agent = next;
-          agentSet = true;
           index += 1;
-        } else {
-          agentSet = true;
         }
       }
       continue;
@@ -168,13 +175,16 @@ export function parseCliArgs(
   }
 
   if (options.has('--help')) return { help: true };
+  if (options.has('--version')) return { version: true };
   if (positionals.length > 1) fail('Pass at most one repo');
   if (positionals.length && options.has('--repo')) {
     fail('Pass the repo once, either as REPO or with --repo');
   }
   if (noAgent && agentSet) fail('--agent and --no-agent cannot be used together');
-  if (!noAgent && agent !== 'codex') {
-    fail(`Unsupported agent "${agent}". Only "codex" is supported for now.`);
+  if (!noAgent && agent && !codingAgents.includes(agent)) {
+    fail(
+      `Unsupported agent "${agent}". Choose ${codingAgents.join(', ')}.`,
+    );
   }
 
   const branch = options.get('--branch');
@@ -243,6 +253,7 @@ export function parseCliArgs(
   }
 
   const agentArgs = [...commonArgs];
+  if (options.has('--force')) agentArgs.push('--force');
   for (const name of [
     '--codex-bin',
     '--model',
@@ -277,17 +288,21 @@ export function parseCliArgs(
     fail('--batch-size must be a number from 1 to 50');
   }
 
-  const portValue = options.get('--port') || '3000';
+  const portValue = options.get('--port') || '2299';
   if (!/^\d+$/.test(portValue) || Number(portValue) > 65_535) {
     fail('--port must be a number from 0 to 65535');
   }
 
   return {
     help: false,
+    version: false,
     agentEnabled: !noAgent,
     agent,
+    codexBin: options.get('--codex-bin'),
     feedArgs: commonArgs,
     agentArgs,
     port: Number(portValue),
+    portWasPassed: options.has('--port'),
+    forceSummaryRegeneration: options.has('--force'),
   };
 }

package/scripts/coding-agents.mjs

@@ -0,0 +1,212 @@
+import { constants } from 'node:fs';
+import { access } from 'node:fs/promises';
+import { delimiter, dirname, isAbsolute, join } from 'node:path';
+
+export const codingAgents = ['codex', 'claude', 'copilot', 'opencode'];
+
+async function executable(path) {
+  try {
+    await access(
+      path,
+      process.platform === 'win32' ? constants.F_OK : constants.X_OK,
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function commandAvailable(
+  command,
+  {
+    env = process.env,
+    platform = process.platform,
+  } = {},
+) {
+  if (
+    isAbsolute(command) ||
+    command.includes('/') ||
+    command.includes('\\')
+  ) {
+    return executable(command);
+  }
+
+  const extensions =
+    platform === 'win32'
+      ? (env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';')
+      : [''];
+  const directories = (env.PATH || '').split(delimiter).filter(Boolean);
+  for (const directory of directories) {
+    for (const extension of extensions) {
+      if (await executable(join(directory, `${command}${extension}`))) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+export async function selectCodingAgent(
+  requested,
+  available = commandAvailable,
+) {
+  if (requested) {
+    if (!codingAgents.includes(requested)) {
+      throw new Error(
+        `Unsupported agent "${requested}". Choose ${codingAgents.join(', ')}.`,
+      );
+    }
+    if (!(await available(requested))) {
+      throw new Error(`Coding agent "${requested}" is not available.`);
+    }
+    return requested;
+  }
+
+  for (const agent of codingAgents) {
+    if (await available(agent)) return agent;
+  }
+  throw new Error(
+    `No coding agent is available. Install one of: ${codingAgents.join(', ')}.`,
+  );
+}
+
+export function codingAgentBinary(
+  agent,
+  {
+    codexBin,
+    env = process.env,
+  } = {},
+) {
+  if (agent === 'codex') return codexBin || env.CODEX_BIN || agent;
+  return env[`${agent.toUpperCase()}_BIN`] || agent;
+}
+
+function parseJsonText(text, agent) {
+  const trimmed = text.trim();
+  const fenced = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+  try {
+    return JSON.parse(fenced ? fenced[1] : trimmed);
+  } catch {
+    throw new Error(`${agent} did not return valid summary JSON`);
+  }
+}
+
+export function parseAgentResponse(agent, stdout) {
+  if (agent === 'claude') {
+    const envelope = parseJsonText(stdout, 'Claude');
+    if (envelope?.structured_output) return envelope.structured_output;
+    if (typeof envelope?.result === 'string') {
+      return parseJsonText(envelope.result, 'Claude');
+    }
+    return envelope;
+  }
+
+  if (agent === 'opencode') {
+    const parts = stdout
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => {
+        try {
+          return JSON.parse(line);
+        } catch {
+          return undefined;
+        }
+      })
+      .filter((event) => event?.type === 'text' && event.part?.text)
+      .map((event) => event.part.text);
+    if (parts.length) return parseJsonText(parts.join(''), 'OpenCode');
+  }
+
+  const label = agent === 'copilot' ? 'Copilot' : 'Codex';
+  return parseJsonText(stdout, label);
+}
+
+export function agentCommand({
+  agent,
+  binary = agent,
+  model,
+  reasoning,
+  prompt,
+  schema,
+  schemaPath,
+  inputPath,
+  workingDirectory,
+}) {
+  if (agent === 'codex') {
+    const args = [
+      'exec',
+      '--ephemeral',
+      '--sandbox',
+      'read-only',
+      '--ignore-user-config',
+      '--color',
+      'never',
+      '--skip-git-repo-check',
+      '-C',
+      workingDirectory,
+      '--output-schema',
+      schemaPath,
+    ];
+    if (model) args.push('--model', model);
+    if (reasoning) {
+      args.push(
+        '--config',
+        `model_reasoning_effort=${JSON.stringify(reasoning)}`,
+      );
+    }
+    args.push(prompt);
+    return { command: binary, args, input: 'stdin' };
+  }
+
+  if (agent === 'claude') {
+    const args = [
+      '--print',
+      '--output-format',
+      'json',
+      '--json-schema',
+      JSON.stringify(schema),
+      '--tools',
+      '',
+      '--no-session-persistence',
+    ];
+    if (model) args.push('--model', model);
+    args.push(prompt);
+    return { command: binary, args, input: 'stdin' };
+  }
+
+  if (agent === 'copilot') {
+    const schemaText = JSON.stringify(schema);
+    const args = [
+      '--silent',
+      '--no-ask-user',
+      '--no-color',
+      '--no-custom-instructions',
+      '--no-remote',
+      '--no-remote-export',
+      `--add-dir=${dirname(inputPath)}`,
+    ];
+    if (model) args.push('--model', model);
+    args.push(
+      '--prompt',
+      `${prompt}\n\nRead the snapshot from @${inputPath}. Return JSON that matches this schema:\n${schemaText}`,
+    );
+    return { command: binary, args, input: 'none' };
+  }
+
+  const args = [
+    'run',
+    '--pure',
+    '--format',
+    'json',
+    '--dir',
+    workingDirectory,
+    '--file',
+    inputPath,
+  ];
+  if (model) args.push('--model', model);
+  if (reasoning) args.push('--variant', reasoning);
+  args.push(
+    `${prompt}\n\nThe attached JSON file is the snapshot. Return JSON that matches this schema:\n${JSON.stringify(schema)}`,
+  );
+  return { command: binary, args, input: 'none' };
+}

package/scripts/generate-summaries.mjs

@@ -13,6 +13,13 @@ import {
 import { tmpdir } from 'node:os';
 import { dirname, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import {
+  agentCommand,
+  codingAgentBinary,
+  commandAvailable,
+  parseAgentResponse,
+  selectCodingAgent,
+} from './coding-agents.mjs';
 import { summaryPath } from './summary-path.mjs';
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
@@ -29,12 +36,13 @@ const valueFlags = new Set([
   '--summaries',
   '--output',
   '--cache-dir',
+  '--agent',
   '--codex-bin',
   '--model',
   '--reasoning',
   '--batch-size',
 ]);
-const booleanFlags = new Set(['--checkout', '--worktree']);
+const booleanFlags = new Set(['--checkout', '--force', '--worktree']);
 
 function fail(message) {
   console.error(message);
@@ -76,10 +84,12 @@ Options:
   --summaries FILE    Agent note file
   --output FILE       Rebuilt Diffsplain JSON
   --cache-dir PATH    Bare cache for fetched Git objects
+  --agent NAME        Use codex, claude, copilot, or opencode
   --codex-bin FILE    Codex CLI path (default: codex)
-  --model NAME        Model passed to codex exec
-  --reasoning LEVEL   Reasoning effort passed to codex exec
-  --batch-size COUNT  Files per Codex pass (default: 4)`);
+  --model NAME        Model passed to the coding agent
+  --reasoning LEVEL   Agent reasoning effort when supported
+  --batch-size COUNT  Files per agent pass (default: 4)
+  --force             Regenerate all notes instead of using cached notes`);
   process.exit(0);
 }
 
@@ -88,7 +98,18 @@ const outputPath = resolve(
   callerDirectory,
   option('--output') || resolve(root, '.cache/diff-data.json'),
 );
-const codexBin = option('--codex-bin') || process.env.CODEX_BIN || 'codex';
+const codexBin = option('--codex-bin') || process.env.CODEX_BIN;
+let selectedAgent;
+try {
+  selectedAgent = await selectCodingAgent(
+    option('--agent'),
+    (agent) =>
+      commandAvailable(codingAgentBinary(agent, { codexBin })),
+  );
+} catch (error) {
+  fail(error.message);
+}
+const agentBinary = codingAgentBinary(selectedAgent, { codexBin });
 const model = option('--model');
 const reasoning = option('--reasoning');
 const batchSizeValue = option('--batch-size') || '4';
@@ -113,6 +134,7 @@ const pr = option('--pr');
 const branch = option('--branch');
 const checkout = rawArgs.includes('--checkout');
 const remote = option('--remote') || 'origin';
+const force = rawArgs.includes('--force');
 
 if (range && (base || head)) {
   fail('--range cannot be used with --base or --head');
@@ -575,6 +597,7 @@ try {
     const changedPaths = [];
     for (const path of paths) {
       if (
+        !force &&
         previousFingerprints[path] === fileFingerprints[path] &&
         completeFileNote(previousFiles[path])
       ) {
@@ -584,6 +607,7 @@ try {
       }
     }
     const changeNeedsRefresh =
+      force ||
       previousSummaries.meta?.reviewFingerprint !==
         rawSnapshot.notes.reviewFingerprint ||
       !completeChangeNote(previousSummaries.change);
@@ -626,40 +650,36 @@ try {
         `${JSON.stringify(outputSchema(batchPaths), null, 2)}\n`,
       );
 
-      const codexArgs = [
-        'exec',
-        '--ephemeral',
-        '--sandbox',
-        'read-only',
-        '--ignore-user-config',
-        '--color',
-        'never',
-        '-C',
-        root,
-        '--output-schema',
+      const input = batchInput(
+        snapshot,
+        rawSnapshot,
+        batchPaths,
+        workingSummaries.files,
+      );
+      const inputPath = resolve(
+        temporaryDirectory,
+        `summary-input-${index + 1}.json`,
+      );
+      writeFileSync(inputPath, input);
+      const invocation = agentCommand({
+        agent: selectedAgent,
+        binary: agentBinary,
+        model,
+        reasoning,
+        prompt: promptFor(batchPaths),
+        schema: outputSchema(batchPaths),
         schemaPath,
-      ];
-      if (model) codexArgs.push('--model', model);
-      if (reasoning) {
-        codexArgs.push(
-          '--config',
-          `model_reasoning_effort=${JSON.stringify(reasoning)}`,
-        );
-      }
-      codexArgs.push(promptFor(batchPaths));
+        inputPath,
+        workingDirectory: root,
+      });
 
       console.error(
-        `Asking Codex for batch ${index + 1} of ${batches.length} (${batchPaths.length} changed files)...`,
+        `Asking ${selectedAgent} for batch ${index + 1} of ${batches.length} (${batchPaths.length} changed files)...`,
       );
-      const result = spawnSync(codexBin, codexArgs, {
+      const result = spawnSync(invocation.command, invocation.args, {
         cwd: root,
         encoding: 'utf8',
-        input: batchInput(
-          snapshot,
-          rawSnapshot,
-          batchPaths,
-          workingSummaries.files,
-        ),
+        input: invocation.input === 'stdin' ? input : undefined,
         maxBuffer: 10 * 1024 * 1024,
         stdio: ['pipe', 'pipe', 'pipe'],
       });
@@ -667,24 +687,21 @@ try {
       if (result.status !== 0) {
         const detail = result.stderr
           .split('\n')
-          .filter(
-            (line) =>
-              line.length < 600 &&
-              /\b(error|failed|denied|unauthorized|forbidden)\b/i.test(line),
+          .map((line) =>
+            line.replace(
+              /\u001b\[[0-?]*[ -/]*[@-~]/g,
+              '',
+            ),
           )
-          .slice(-5)
+          .filter((line) => line.trim() && line.length < 600)
+          .slice(-8)
           .join('\n');
         throw new Error(
-          `Codex exited with status ${result.status}${detail ? `\n${detail}` : ''}`,
+          `${selectedAgent} exited with status ${result.status}${detail ? `\n${detail}` : ''}`,
         );
       }
 
-      let response;
-      try {
-        response = JSON.parse(result.stdout);
-      } catch {
-        throw new Error('Codex did not return valid summary JSON');
-      }
+      const response = parseAgentResponse(selectedAgent, result.stdout);
       const normalized = normalizeResponse(response, batchPaths);
       workingSummaries = {
         change: normalized.change,

package/scripts/present.mjs

@@ -2,11 +2,22 @@
 
 import { spawn, spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
 import { createInterface } from 'node:readline';
 import { fileURLToPath } from 'node:url';
 import { helpText, parseCliArgs } from './cli-args.mjs';
+import {
+  codingAgentBinary,
+  commandAvailable,
+  selectCodingAgent,
+} from './coding-agents.mjs';
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const callerDirectory = process.cwd();
@@ -23,16 +34,46 @@ if (cli.help) {
   console.log(helpText);
   process.exit(0);
 }
+if (cli.version) {
+  const packageJson = JSON.parse(
+    readFileSync(resolve(root, 'package.json'), 'utf8'),
+  );
+  console.log(`diffsplain ${packageJson.version}`);
+  process.exit(0);
+}
 
 const { agentEnabled, port } = cli;
 const feedArgs = [...cli.feedArgs];
 const agentArgs = [...cli.agentArgs];
+if (agentEnabled) {
+  try {
+    const selectedAgent = await selectCodingAgent(
+      cli.agent,
+      (agent) =>
+        commandAvailable(
+          codingAgentBinary(agent, { codexBin: cli.codexBin }),
+        ),
+    );
+    agentArgs.push('--agent', selectedAgent);
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}
 const outputIndex = feedArgs.indexOf('--output');
+let runtimeDirectory;
 
 if (outputIndex === -1) {
-  feedArgs.push('--output', resolve(root, '.cache/diff-data.json'));
-  agentArgs.push('--output', resolve(root, '.cache/diff-data.json'));
+  runtimeDirectory = mkdtempSync(join(tmpdir(), 'diffsplain-live-'));
+  const liveOutput = resolve(runtimeDirectory, 'diff-data.json');
+  feedArgs.push('--output', liveOutput);
+  agentArgs.push('--output', liveOutput);
 }
+process.on('exit', () => {
+  if (runtimeDirectory) {
+    rmSync(runtimeDirectory, { recursive: true, force: true });
+  }
+});
 if (!feedArgs.includes('--watch')) feedArgs.push('--watch');
 const outputPath = resolve(
   callerDirectory,
@@ -71,14 +112,55 @@ const site = spawn(
     outputPath,
     '--port',
     String(port),
+    ...(!cli.portWasPassed ? ['--increment-port'] : []),
   ],
-  { cwd: root, stdio: 'inherit' },
+  { cwd: root, stdio: ['ignore', 'pipe', 'inherit'] },
 );
 let closing = false;
 let agent;
 let agentTimer;
 let agentFingerprint;
 let queuedFingerprint;
+let browserOpened = false;
+
+function openBrowser(url) {
+  let command;
+  let args;
+  if (process.env.BROWSER) {
+    command = process.env.BROWSER;
+    args = [url];
+  } else if (process.platform === 'darwin') {
+    command = 'open';
+    args = [url];
+  } else if (process.platform === 'win32') {
+    command = 'cmd.exe';
+    args = ['/d', '/s', '/c', 'start', '', url];
+  } else {
+    command = 'xdg-open';
+    args = [url];
+  }
+
+  const opener = spawn(command, args, {
+    detached: true,
+    stdio: 'ignore',
+  });
+  opener.once('error', (error) => {
+    console.error(`Could not open the browser: ${error.message}`);
+  });
+  opener.unref();
+}
+
+if (site.stdout) {
+  const siteLines = createInterface({ input: site.stdout });
+  siteLines.on('line', (line) => {
+    console.log(line);
+    const match = line.match(/^Diffsplain: (http:\/\/\S+)$/);
+    if (!browserOpened && match) {
+      browserOpened = true;
+      openBrowser(match[1]);
+    }
+  });
+}
 
 function snapshotState() {
   try {
@@ -170,6 +252,7 @@ function scheduleAgent(fingerprint) {
   const state = snapshotState();
   const selectedFingerprint = fingerprint || state?.fingerprint;
   if (
+    !cli.forceSummaryRegeneration &&
     !agentFingerprint &&
     state?.hasCurrentAgentNotes &&
     selectedFingerprint === state.fingerprint

package/scripts/release.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+
+function runNpm(args) {
+  const result = spawnSync(npm, args, {
+    cwd: root,
+    stdio: 'inherit',
+  });
+  if (result.error) throw result.error;
+  return result.status ?? 1;
+}
+
+export function runRelease(versionArgs, run = runNpm) {
+  if (!versionArgs[0] || versionArgs[0].startsWith('-')) {
+    throw new Error(
+      'Usage: npm run release -- <version> [npm version options]',
+    );
+  }
+
+  const steps = [
+    ['version', ...versionArgs],
+    ['publish', '--access', 'public'],
+  ];
+  for (const args of steps) {
+    const status = run(args);
+    if (status !== 0) return status;
+  }
+  return 0;
+}
+
+if (resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    process.exitCode = runRelease(process.argv.slice(2));
+    if (process.exitCode === 0) {
+      console.log(
+        'Published. Push the version commit and tag with: git push origin main --follow-tags',
+      );
+    }
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 2;
+  }
+}

package/scripts/serve-built.mjs

@@ -21,10 +21,12 @@ function option(name, fallback) {
 }
 
 const output = resolve(option('--output', resolve(root, '.cache/diff-data.json')));
-const portValue = option('--port', '3000');
+const portValue = option('--port', '2299');
 if (!/^\d+$/.test(portValue) || Number(portValue) > 65_535) {
   throw new Error('--port must be a number from 0 to 65535');
 }
+const incrementPort =
+  rawArgs.includes('--increment-port') || !rawArgs.includes('--port');
 
 const contentTypes = {
   '.css': 'text/css; charset=utf-8',
@@ -115,13 +117,34 @@ const server = createServer(async (request, response) => {
   }
 });
 
-server.listen(Number(portValue), '127.0.0.1', () => {
-  const address = server.address();
-  const selectedPort =
-    address && typeof address === 'object' ? address.port : Number(portValue);
-  console.log(`Diffsplain: http://127.0.0.1:${selectedPort}`);
+let selectedPort = Number(portValue);
+
+function listen() {
+  server.listen(selectedPort, '127.0.0.1', () => {
+    const address = server.address();
+    const readyPort =
+      address && typeof address === 'object' ? address.port : selectedPort;
+    console.log(`Diffsplain: http://127.0.0.1:${readyPort}`);
+  });
+}
+
+server.on('error', (error) => {
+  if (
+    error.code === 'EADDRINUSE' &&
+    incrementPort &&
+    selectedPort > 0 &&
+    selectedPort < 65_535
+  ) {
+    selectedPort += 1;
+    listen();
+    return;
+  }
+  console.error(`Could not start Diffsplain: ${error.message}`);
+  process.exitCode = 1;
 });
 
+listen();
+
 let closing = false;
 function close() {
   if (closing) return;