diffsplain 0.5.0 → 0.6.0

package/scripts/cache.mjs

@@ -0,0 +1,301 @@
+import { randomUUID } from 'node:crypto';
+import {
+  chmodSync,
+  closeSync,
+  linkSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  unlinkSync,
+  utimesSync,
+  writeFileSync,
+} from 'node:fs';
+import { hostname } from 'node:os';
+import { dirname, join } from 'node:path';
+import { defaultCacheRoot } from './summary-path.mjs';
+
+export const leaseDurationMs = 5 * 60_000;
+
+function files(root) {
+  try {
+    return readdirSync(root, { withFileTypes: true }).flatMap((entry) => {
+      const path = join(root, entry.name);
+      return entry.isDirectory() ? files(path) : [path];
+    });
+  } catch {
+    return [];
+  }
+}
+
+function leaseRecord(path) {
+  try {
+    const value = JSON.parse(readFileSync(path, 'utf8'));
+    return typeof value?.token === 'string' ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function leaseIsActive(path, now = Date.now(), duration = leaseDurationMs) {
+  try {
+    return now - statSync(path).mtimeMs < duration;
+  } catch {
+    return false;
+  }
+}
+
+function createLease(path, record, duration) {
+  const descriptor = openSync(path, 'wx', 0o600);
+  writeFileSync(descriptor, `${JSON.stringify(record)}\n`);
+  closeSync(descriptor);
+  return { path, token: record.token, duration };
+}
+
+function renameLease(path, stalePath) {
+  try {
+    renameSync(path, stalePath);
+    return true;
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+    return false;
+  }
+}
+
+function restoreLease(path, stalePath) {
+  try {
+    linkSync(stalePath, path);
+  } catch (error) {
+    if (error?.code !== 'EEXIST') throw error;
+  }
+  rmSync(stalePath, { force: true });
+}
+
+export function removeStaleLease(path, observedToken) {
+  const stalePath = `${path}.stale-${randomUUID()}`;
+  if (!renameLease(path, stalePath)) return false;
+  if (leaseRecord(stalePath)?.token === observedToken) {
+    rmSync(stalePath, { force: true });
+    return true;
+  }
+  restoreLease(path, stalePath);
+  return false;
+}
+
+function rejectNonConflict(error) {
+  if (error?.code !== 'EEXIST') throw error;
+}
+
+function rejectActiveLease(active, path) {
+  if (active) {
+    throw new Error(`Notes for this target are already being generated: ${path}`);
+  }
+}
+
+function handleLeaseConflict(error, path, now, duration) {
+  rejectNonConflict(error);
+  const observed = leaseRecord(path);
+  rejectActiveLease(leaseIsActive(path, now, duration), path);
+  removeStaleLease(path, observed?.token);
+}
+
+export function acquireLease(path, {
+  token = randomUUID(),
+  now = Date.now(),
+  duration = leaseDurationMs,
+  pid = process.pid,
+  leaseHostname = hostname(),
+} = {}) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  for (;;) {
+    try {
+      return createLease(
+        path,
+        { token, startedAt: now, pid, hostname: leaseHostname },
+        duration,
+      );
+    } catch (error) {
+      handleLeaseConflict(error, path, now, duration);
+    }
+  }
+}
+
+function assertLease(lease) {
+  if (leaseRecord(lease.path)?.token !== lease.token) {
+    throw new Error('This process no longer owns the note cache');
+  }
+}
+
+export function refreshLease(lease, now = Date.now()) {
+  assertLease(lease);
+  utimesSync(lease.path, new Date(now), new Date(now));
+  assertLease(lease);
+}
+
+export function releaseLease(lease) {
+  assertLease(lease);
+  unlinkSync(lease.path);
+}
+
+export function writePrivateFile(path, value) {
+  writeFileAtomic(path, value, 0o600);
+}
+
+function existingFileMode(path) {
+  try {
+    return statSync(path).mode & 0o777;
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+    return undefined;
+  }
+}
+
+function chmodIfSet(path, mode) {
+  if (mode !== undefined) chmodSync(path, mode);
+}
+
+function writeFileAtomic(path, value, mode) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  const outputMode = mode === undefined ? existingFileMode(path) : mode;
+  writeFileSync(
+    temporary,
+    value,
+    outputMode === undefined ? undefined : { mode: outputMode },
+  );
+  chmodIfSet(temporary, outputMode);
+  renameSync(temporary, path);
+  chmodIfSet(path, outputMode);
+}
+
+export function publishLeaseFile(
+  lease,
+  path,
+  value,
+  { privateFile = true } = {},
+) {
+  assertLease(lease);
+  refreshLease(lease);
+  if (privateFile) writePrivateFile(path, value);
+  else writeFileAtomic(path, value);
+  assertLease(lease);
+}
+
+function active(path, now) {
+  return leaseIsActive(`${path}.lock`, now);
+}
+
+function sameEntry(left, right) {
+  return (
+    left.dev === right.dev &&
+    left.ino === right.ino &&
+    left.size === right.size &&
+    left.mtimeMs === right.mtimeMs
+  );
+}
+
+function fileSize(path) {
+  try {
+    return statSync(path).size;
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+    return undefined;
+  }
+}
+
+function removedCacheEntry() {
+  return { removed: true, retainedActive: false, size: 0 };
+}
+
+function cacheEntryState(entry, removedPath, now) {
+  return {
+    changed: !sameEntry(entry, statSync(removedPath)),
+    retainedActive: active(entry.path, now),
+    replaced: typeof fileSize(entry.path) === 'number',
+  };
+}
+
+function restoreCacheEntry(entry, removedPath, retainedActive) {
+  restoreLease(entry.path, removedPath);
+  return {
+    removed: false,
+    retainedActive,
+    size: fileSize(entry.path) ?? 0,
+  };
+}
+
+export function removeCacheEntry(entry, now = Date.now()) {
+  const removedPath = `${entry.path}.remove-${randomUUID()}`;
+  if (!renameLease(entry.path, removedPath)) return removedCacheEntry();
+  const state = cacheEntryState(entry, removedPath, now);
+  if ([state.changed, state.retainedActive, state.replaced].includes(true)) {
+    return restoreCacheEntry(entry, removedPath, state.retainedActive);
+  }
+  rmSync(removedPath, { force: true });
+  return removedCacheEntry();
+}
+
+function entries(cacheRoot) {
+  return files(join(cacheRoot, 'summaries'))
+    .filter((path) => path.endsWith('.json'))
+    .map((path) => ({ path, ...statSync(path) }));
+}
+
+function activeLeases(cacheRoot, now) {
+  return files(join(cacheRoot, 'summaries')).filter(
+    (path) => path.endsWith('.json.lock') && leaseIsActive(path, now),
+  );
+}
+
+export function cacheStatus({ cacheRoot = defaultCacheRoot(), now = Date.now() } = {}) {
+  const cached = entries(cacheRoot);
+  const bytes = cached.reduce((sum, entry) => sum + entry.size, 0);
+  const ages = cached.map((entry) => now - entry.mtimeMs);
+  return {
+    location: cacheRoot,
+    entries: cached.length,
+    bytes,
+    ageMs: ages.length ? Math.max(...ages) : 0,
+    active: activeLeases(cacheRoot, now).length,
+  };
+}
+
+function shouldPrune(entry, { maxAgeMs, maxBytes, now, bytes }) {
+  const overAge =
+    maxAgeMs !== undefined && now - entry.mtimeMs > maxAgeMs;
+  const overSize = maxBytes !== undefined && bytes > maxBytes;
+  return overAge || overSize;
+}
+
+function applyPruneResult(entry, result, removed, retainedActive) {
+  if (result.removed) {
+    removed.push(entry.path);
+    return -entry.size;
+  }
+  if (result.retainedActive) retainedActive.push(entry.path);
+  return result.size - entry.size;
+}
+
+export function pruneCache({ cacheRoot = defaultCacheRoot(), maxAgeMs, maxBytes, now = Date.now() } = {}) {
+  const cached = entries(cacheRoot).sort((a, b) => a.mtimeMs - b.mtimeMs);
+  let bytes = cached.reduce((sum, entry) => sum + entry.size, 0);
+  const removed = [];
+  const retainedActive = [];
+  for (const entry of cached) {
+    if (!shouldPrune(entry, { maxAgeMs, maxBytes, now, bytes })) continue;
+    const result = removeCacheEntry(entry, now);
+    bytes += applyPruneResult(entry, result, removed, retainedActive);
+  }
+  return { removed, retainedActive, bytes };
+}
+
+export function clearCache(options) {
+  return pruneCache({ ...options, maxAgeMs: 0 });
+}
+
+export function formatCacheStatus(status) {
+  return `Location: ${status.location}\nSize: ${status.bytes} bytes\nOldest entry: ${Math.floor(status.ageMs / 1000)} seconds\nActive use: ${status.active} target${status.active === 1 ? '' : 's'}`;
+}

package/scripts/cli-args.mjs

@@ -1,38 +1,70 @@
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { codingAgents } from './coding-agents.mjs';
-
-const valueOptions = new Set([
-  '--repo',
-  '--branch',
-  '--pr',
-  '--base',
-  '--head',
-  '--remote',
-  '--summaries',
-  '--output',
-  '--cache-dir',
-  '--codex-bin',
-  '--model',
-  '--reasoning',
-  '--batch-size',
-  '--jobs',
-  '--port',
-]);
-const flagOptions = new Set([
-  '--help',
-  '--version',
-  '--agent',
-  '--no-agent',
-  '--force',
-  '--worktree',
-]);
-const pathOptions = new Set([
-  '--summaries',
-  '--output',
-  '--cache-dir',
-  '--codex-bin',
-]);
+import {
+  assertReasoningSupported,
+  codingAgents,
+  enabledCodingAgents,
+} from './coding-agents.mjs';
+
+function defineCliOptions(records) {
+  return Object.freeze(
+    Object.fromEntries(
+      Object.entries(records).map(([name, record]) => [
+        name,
+        Object.freeze(record),
+      ]),
+    ),
+  );
+}
+
+export const cliOptions = defineCliOptions({
+  '--repo': { kind: 'value' },
+  '--branch': { kind: 'value' },
+  '--pr': { kind: 'value' },
+  '--base': { kind: 'value' },
+  '--head': { kind: 'value' },
+  '--remote': { kind: 'value' },
+  '--summaries': { kind: 'value', path: true },
+  '--output': { kind: 'value', path: true },
+  '--cache-dir': { kind: 'value', path: true },
+  '--codex-bin': { kind: 'value', path: true },
+  '--support-record-file': { kind: 'value', path: true },
+  '--model': { kind: 'value' },
+  '--reasoning': { kind: 'value' },
+  '--batch-size': { kind: 'value', default: 12, min: 1, max: 50 },
+  '--jobs': { kind: 'value', default: 3, min: 1, max: 8 },
+  '--port': { kind: 'value', default: 2299, min: 0, max: 65_535 },
+  '--host': { kind: 'value', default: 'localhost' },
+  '--help': { kind: 'flag' },
+  '--version': { kind: 'flag' },
+  '--agent': { kind: 'agent' },
+  '--no-agent': { kind: 'no-agent' },
+  '--force': { kind: 'flag' },
+  '--worktree': { kind: 'flag' },
+  '--no-browser': { kind: 'flag' },
+  '--support-record': { kind: 'flag' },
+});
+
+const valueOptions = new Set(
+  Object.entries(cliOptions)
+    .filter(([, record]) => record.kind === 'value')
+    .map(([name]) => name),
+);
+const flagOptions = new Set(
+  Object.entries(cliOptions)
+    .filter(([, record]) => record.kind === 'flag')
+    .map(([name]) => name),
+);
+const pathOptions = new Set(
+  Object.entries(cliOptions)
+    .filter(([, record]) => record.path)
+    .map(([name]) => name),
+);
+
+const batchSizeOption = cliOptions['--batch-size'];
+const jobsOption = cliOptions['--jobs'];
+const portOption = cliOptions['--port'];
+const hostOption = cliOptions['--host'];
 
 export const helpText = `Usage: diffsplain [REPO] [options]
 
@@ -40,7 +72,9 @@ Show the current checkout against its default branch:
   diffsplain
 
 Commands:
-  doctor              Check Git, GitHub CLI, and coding agents
+  doctor [--json] [--deep]
+                      Check review, agent, and pull request capabilities
+  cache               Show or prune saved agent notes
 
 Targets:
   --branch NAME       Show a remote branch against its default branch
@@ -52,24 +86,39 @@ Targets:
 Options:
   --repo PATH|URL|OWNER/NAME
                       Repo to review (default: current repo)
-  --agent NAME        Use codex, claude, copilot, cursor, or opencode
+  --agent NAME        Use codex, claude, copilot, or opencode
   --no-agent          Do not write agent notes
   --model NAME        Model for agent notes
   --reasoning LEVEL   Agent reasoning effort when supported
-  --batch-size COUNT  Maximum files per agent pass (default: 12)
-  --jobs COUNT        Agent passes to run at once (default: 3)
+  --batch-size COUNT  Maximum files per agent pass (default: ${batchSizeOption.default})
+  --jobs COUNT        Agent passes to run at once (default: ${jobsOption.default})
   --force             Regenerate all agent notes
+  --support-record    Print a safe record if agent notes fail
+  --support-record-file FILE
+                      Write a safe record if agent notes fail
   --remote NAME|URL   Git remote (default: origin)
-  --port NUMBER       Local page port (default: 2299)
+  --port NUMBER       Local page port (default: ${portOption.default})
+  --host ADDRESS      Page bind address (default: ${hostOption.default})
+  --no-browser        Do not open the page in a browser
+  --summaries FILE    Saved agent-note file
+  --output FILE       Live snapshot file
+  --cache-dir PATH    Bare Git cache folder
+  --codex-bin PATH    Codex executable
   -h, --help          Show this help
   -v, --version       Show the installed version
 
 Agent fallback:
-  codex, claude, copilot, cursor, opencode
+  codex, claude, copilot, opencode
+
+Cursor:
+  Disabled because Cursor Agent has no supported read-only, no-network,
+  no-tool mode
 
 Examples:
   diffsplain
   diffsplain doctor
+  diffsplain doctor --json
+  diffsplain cache status
   diffsplain --repo owner/project --pr 42
   diffsplain owner/project --branch feature/search
   diffsplain --agent claude`;
@@ -101,6 +150,19 @@ function githubRepoFromPullRequest(value) {
   }
 }
 
+function validPullRequest(value) {
+  if (/^[1-9]\d*$/.test(value)) return true;
+  try {
+    const url = new URL(value);
+    return (
+      (url.protocol === 'https:' || url.protocol === 'http:') &&
+      /^\/[^/]+\/[^/]+\/pull\/[1-9]\d*(?:\/|$)/.test(url.pathname)
+    );
+  } catch {
+    return false;
+  }
+}
+
 function remoteRepo(value, callerDirectory, pathExists) {
   if (pathExists(resolve(callerDirectory, value))) return undefined;
   if (
@@ -123,8 +185,16 @@ export function parseCliArgs(
   } = {},
 ) {
   if (rawArgs[0] === 'doctor') {
-    if (rawArgs.length > 1) fail('doctor does not take arguments or options');
-    return { doctor: true };
+    const options = new Set(rawArgs.slice(1));
+    for (const option of options) {
+      if (!['--json', '--deep'].includes(option)) {
+        fail('doctor only accepts --json and --deep');
+      }
+    }
+    if (options.size !== rawArgs.length - 1) {
+      fail('doctor options can only be passed once');
+    }
+    return { doctor: { json: options.has('--json'), deep: options.has('--deep') } };
   }
 
   const options = new Map();
@@ -137,32 +207,38 @@ export function parseCliArgs(
     const argument = rawArgs[index];
     const parsed = splitOption(argument);
     if (!parsed) {
+      if (argument.startsWith('-')) fail(`Unknown option: ${argument}`);
+      if (!argument) fail('Repo cannot be empty');
       positionals.push(argument);
       continue;
     }
 
     if (parsed.name === '--agent') {
+      if (agentSet) fail('--agent was passed more than once');
       agentSet = true;
       if (parsed.value !== undefined) {
         if (!parsed.value) fail('--agent needs a value');
         agent = parsed.value;
       } else {
         const next = rawArgs[index + 1];
-        if (next && !next.startsWith('-')) {
-          agent = next;
-          index += 1;
-        }
+        if (!next || splitOption(next)) fail('--agent needs a value');
+        agent = next;
+        index += 1;
       }
       continue;
     }
 
     if (parsed.name === '--no-agent') {
+      if (noAgent) fail('--no-agent was passed more than once');
       if (parsed.value !== undefined) fail('--no-agent does not take a value');
       noAgent = true;
       continue;
     }
 
     if (flagOptions.has(parsed.name)) {
+      if (options.has(parsed.name)) {
+        fail(`${parsed.name} was passed more than once`);
+      }
       if (parsed.value !== undefined) {
         fail(`${parsed.name} does not take a value`);
       }
@@ -178,7 +254,7 @@ export function parseCliArgs(
     let value = parsed.value;
     if (value === undefined) {
       value = rawArgs[index + 1];
-      if (!value || value.startsWith('--')) fail(`${parsed.name} needs a value`);
+      if (!value || splitOption(value)) fail(`${parsed.name} needs a value`);
       index += 1;
     }
     if (!value) fail(`${parsed.name} needs a value`);
@@ -192,9 +268,25 @@ export function parseCliArgs(
     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 && options.has('--summaries')) {
+    fail('--no-agent cannot be used with --summaries');
+  }
+  if (
+    noAgent &&
+    (options.has('--support-record') ||
+      options.has('--support-record-file'))
+  ) {
+    fail('--no-agent cannot be used with a support record');
+  }
+  if (
+    options.has('--support-record') &&
+    options.has('--support-record-file')
+  ) {
+    fail('Pass either --support-record or --support-record-file, not both');
+  }
   if (!noAgent && agent && !codingAgents.includes(agent)) {
     fail(
-      `Unsupported agent "${agent}". Choose ${codingAgents.join(', ')}.`,
+      `Unsupported agent "${agent}". Choose ${enabledCodingAgents.join(', ')}.`,
     );
   }
 
@@ -214,6 +306,9 @@ export function parseCliArgs(
   if (!branch && !pullRequest && !worktree && Boolean(base) !== Boolean(head)) {
     fail('--base and --head must be used together');
   }
+  if (pullRequest && !validPullRequest(pullRequest)) {
+    fail('--pr must be a positive number or a pull request URL');
+  }
 
   const repoArgument = positionals[0] || options.get('--repo');
   let remote = options.get('--remote');
@@ -263,14 +358,20 @@ export function parseCliArgs(
     }
   }
 
+  const feedArgs = [...commonArgs];
+  const supportRecordFile = options.get('--support-record-file');
+  if (supportRecordFile) {
+    feedArgs.push(
+      '--exclude-output',
+      resolve(callerDirectory, supportRecordFile),
+    );
+  }
   const agentArgs = [...commonArgs];
   if (options.has('--force')) agentArgs.push('--force');
   for (const name of [
     '--codex-bin',
     '--model',
     '--reasoning',
-    '--batch-size',
-    '--jobs',
   ]) {
     const value = options.get(name);
     if (value) {
@@ -280,6 +381,23 @@ export function parseCliArgs(
       );
     }
   }
+  if (!noAgent) {
+    for (const name of ['--batch-size', '--jobs']) {
+      agentArgs.push(
+        name,
+        options.get(name) || String(cliOptions[name].default),
+      );
+    }
+  }
+  if (supportRecordFile) {
+    agentArgs.push(
+      '--support-record-file',
+      resolve(callerDirectory, supportRecordFile),
+    );
+  }
+  if (options.has('--support-record')) {
+    agentArgs.push('--support-record');
+  }
 
   const reasoning = options.get('--reasoning');
   if (
@@ -292,36 +410,67 @@ export function parseCliArgs(
       '--reasoning must be minimal, low, medium, high, or xhigh',
     );
   }
+  if (reasoning && agent) assertReasoningSupported(agent, reasoning);
   const batchSize = options.get('--batch-size');
   if (
     batchSize &&
-    (!/^[1-9]\d*$/.test(batchSize) || Number(batchSize) > 50)
+    (
+      !/^[1-9]\d*$/.test(batchSize) ||
+      Number(batchSize) < batchSizeOption.min ||
+      Number(batchSize) > batchSizeOption.max
+    )
   ) {
-    fail('--batch-size must be a number from 1 to 50');
+    fail(
+      `--batch-size must be a number from ${batchSizeOption.min} to ${batchSizeOption.max}`,
+    );
   }
   const jobs = options.get('--jobs');
   if (
     jobs &&
-    (!/^[1-9]\d*$/.test(jobs) || Number(jobs) > 8)
+    (
+      !/^[1-9]\d*$/.test(jobs) ||
+      Number(jobs) < jobsOption.min ||
+      Number(jobs) > jobsOption.max
+    )
   ) {
-    fail('--jobs must be a number from 1 to 8');
+    fail(
+      `--jobs must be a number from ${jobsOption.min} to ${jobsOption.max}`,
+    );
   }
 
-  const portValue = options.get('--port') || '2299';
-  if (!/^\d+$/.test(portValue) || Number(portValue) > 65_535) {
-    fail('--port must be a number from 0 to 65535');
+  const portValue = options.get('--port') || String(portOption.default);
+  if (
+    !/^\d+$/.test(portValue) ||
+    Number(portValue) < portOption.min ||
+    Number(portValue) > portOption.max
+  ) {
+    fail(
+      `--port must be a number from ${portOption.min} to ${portOption.max}`,
+    );
   }
+  const host = (options.get('--host') || hostOption.default).replace(
+    /^\[|\]$/g,
+    '',
+  );
 
   return {
     help: false,
     version: false,
     agentEnabled: !noAgent,
     agent,
+    model: options.get('--model'),
+    reasoning,
     codexBin: options.get('--codex-bin'),
-    feedArgs: commonArgs,
+    feedArgs,
     agentArgs,
+    supportRecord: options.has('--support-record'),
+    supportRecordFile: supportRecordFile
+      ? resolve(callerDirectory, supportRecordFile)
+      : undefined,
     port: Number(portValue),
     portWasPassed: options.has('--port'),
+    host,
+    browserEnabled: !options.has('--no-browser'),
     forceSummaryRegeneration: options.has('--force'),
   };
 }