diffsplain 0.8.3 → 0.10.0

package/scripts/local-target.mjs

@@ -0,0 +1,106 @@
+import { spawnSync } from 'node:child_process';
+
+export function isBaseWorktreeTarget({
+  base,
+  branch,
+  checkout,
+  head,
+  pullRequest,
+  worktree,
+}) {
+  return Boolean(base) && [branch, checkout, head, pullRequest, worktree]
+    .every((value) => !value);
+}
+
+const checkoutTargetKinds = new Set([
+  'checkout',
+  'worktree',
+  'base-worktree',
+]);
+
+function localTargetKind({ checkout, worktree }) {
+  if (checkout) return 'checkout';
+  if (worktree) return 'worktree';
+  return undefined;
+}
+
+function remoteTargetKind({ branch, pullRequest }) {
+  if (pullRequest) return 'pr';
+  if (branch) return 'branch';
+  return undefined;
+}
+
+function hasRangeTarget({ base, head, range }) {
+  return Boolean(range || base || head);
+}
+
+function gitTargetKind(options) {
+  const { base, branch, checkout, head, pullRequest, worktree } = options;
+  if (isBaseWorktreeTarget({
+    base,
+    branch,
+    checkout,
+    head,
+    pullRequest,
+    worktree,
+  })) return 'base-worktree';
+  if (hasRangeTarget(options)) return 'range';
+  return undefined;
+}
+
+function explicitTargetKind(options) {
+  return localTargetKind(options) ||
+    remoteTargetKind(options) ||
+    gitTargetKind(options);
+}
+
+function resolvedTargetKind(options) {
+  const explicit = explicitTargetKind(options);
+  if (explicit) return explicit;
+  if (options.snapshotSupplied) return undefined;
+  return 'worktree';
+}
+
+export function reviewAccessMode({
+  repo,
+  base,
+  branch,
+  checkout,
+  head,
+  noCheckoutAccess = false,
+  pullRequest,
+  range,
+  snapshotSupplied = false,
+  worktree,
+}) {
+  if (noCheckoutAccess) {
+    return { mode: 'snapshot-only', reason: 'disabled' };
+  }
+  const targetKind = resolvedTargetKind({
+    base,
+    branch,
+    checkout,
+    head,
+    pullRequest,
+    range,
+    snapshotSupplied,
+    worktree,
+  });
+  if (checkoutTargetKinds.has(targetKind)) {
+    return { mode: 'checkout-read-only', root: repo };
+  }
+  return { mode: 'snapshot-only', reason: 'target-mismatch' };
+}
+
+export function resolveBaseWorktreeCommit(repo, base) {
+  const result = spawnSync(
+    'git',
+    ['-C', repo, 'rev-parse', '--verify', `${base}^{commit}`],
+    { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+  );
+  const oid = result.status === 0 ? result.stdout.trim() : '';
+  if (!oid) {
+    throw new Error(`Could not resolve base ref "${base}" to a commit.`);
+  }
+  return oid;
+}

package/scripts/present.mjs

@@ -7,6 +7,7 @@ import {
   mkdirSync,
   mkdtempSync,
   readFileSync,
+  renameSync,
   rmSync,
   statSync,
   writeFileSync,
@@ -16,12 +17,20 @@ 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 { applyAgentConfigOperation } from './agent-config.mjs';
 import {
+  agentReadOnlyWarning,
   assertReasoningSupported,
+  codingAgentFromSelectionError,
   codingAgentAvailability,
   codingAgentBinary,
   selectCodingAgent,
 } from './coding-agents.mjs';
+import {
+  isBaseWorktreeTarget,
+  reviewAccessMode,
+  resolveBaseWorktreeCommit,
+} from './local-target.mjs';
 import { doctorReport } from './doctor.mjs';
 import { accessTokenDirectory } from './access-token.mjs';
 import { cacheStatus, clearCache, formatCacheStatus, pruneCache } from './cache.mjs';
@@ -119,6 +128,22 @@ if (cli.version) {
   console.log(`diffsplain ${packageJson.version}`);
   process.exit(0);
 }
+if (cli.config) {
+  try {
+    const result = applyAgentConfigOperation(cli.config);
+    if (result.kind === 'show') {
+      console.log(result.agent ?? 'No default coding agent is configured.');
+    } else if (result.kind === 'set') {
+      console.log(`Default coding agent set to "${result.agent}".`);
+    } else {
+      console.log('Default coding agent unset.');
+    }
+    process.exit(0);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
 if (cli.doctor) {
   if (cli.doctor.deep) {
     console.error(
@@ -178,33 +203,90 @@ function emitSupportRecord(code = 1) {
   }
 }
 
+function targetOption(args, name) {
+  const index = args.indexOf(name);
+  return index === -1 ? undefined : args[index + 1];
+}
+
 const { agentEnabled, browserEnabled, host, port } = cli;
 const feedArgs = [...cli.feedArgs];
 const agentArgs = [...cli.agentArgs];
+const base = targetOption(feedArgs, '--base');
+const head = targetOption(feedArgs, '--head');
+const branch = targetOption(feedArgs, '--branch');
+const checkout = feedArgs.includes('--checkout');
+const reviewRepo = targetOption(feedArgs, '--repo');
+const accessMode = reviewAccessMode({
+  repo: reviewRepo,
+  base,
+  branch,
+  checkout,
+  head,
+  noCheckoutAccess: cli.noCheckoutAccess,
+  pullRequest: targetOption(feedArgs, '--pr'),
+  worktree: feedArgs.includes('--worktree'),
+});
+if (isBaseWorktreeTarget({
+  base,
+  branch,
+  checkout,
+  head,
+  pullRequest: targetOption(feedArgs, '--pr'),
+  worktree: feedArgs.includes('--worktree'),
+})) {
+  try {
+    resolveBaseWorktreeCommit(targetOption(feedArgs, '--repo'), base);
+  } catch (error) {
+    console.error(error.message);
+    process.exit(2);
+  }
+}
 let selectedAgent;
+let selectedAgentBinary;
 beginSupportRecord();
 if (agentEnabled) {
   const selectionStarted = performance.now();
   try {
     selectedAgent = await selectCodingAgent(
       cli.agent,
-      (agent) =>
-        codingAgentAvailability(agent, {
-          binary: codingAgentBinary(agent, { codexBin: cli.codexBin }),
-        }),
+      {
+        available: (agent) =>
+          codingAgentAvailability(agent, {
+            binary: codingAgentBinary(agent, { codexBin: cli.codexBin }),
+          }),
+      },
     );
     assertReasoningSupported(selectedAgent, cli.reasoning);
-    const agentBinary = codingAgentBinary(selectedAgent, {
+    selectedAgentBinary = codingAgentBinary(selectedAgent, {
       codexBin: cli.codexBin,
     });
-    recordSelectedProvider(selectedAgent, agentBinary);
+    recordSelectedProvider(selectedAgent, selectedAgentBinary);
     supportRecorder?.addStage(
       'agent',
       performance.now() - selectionStarted,
     );
     agentArgs.push('--agent', selectedAgent);
+    if (
+      accessMode.mode === 'snapshot-only' &&
+      accessMode.reason === 'target-mismatch'
+    ) {
+      console.log(
+        'Warning: This target does not map to the live checkout. Agent notes will use the supplied snapshot only.',
+      );
+      agentArgs.push('--access-warning-emitted');
+    }
+    const readOnlyWarning = agentReadOnlyWarning(selectedAgent, accessMode);
+    if (readOnlyWarning) {
+      console.log(readOnlyWarning);
+      agentArgs.push('--provider-read-only-warning-emitted');
+    }
   } catch (error) {
-    recordSelectedProvider(cli.agent || 'unknown');
+    recordSelectedProvider(
+      codingAgentFromSelectionError(error) ||
+        selectedAgent ||
+        cli.agent ||
+        'unknown',
+    );
     supportRecorder?.addStage(
       'agent',
       performance.now() - selectionStarted,
@@ -217,6 +299,12 @@ if (agentEnabled) {
 } else {
   feedArgs.push('--no-summaries');
 }
+if (agentEnabled) {
+  agentArgs.push('--access-mode', accessMode.mode);
+  if (accessMode.mode === 'snapshot-only') {
+    agentArgs.push('--access-reason', accessMode.reason);
+  }
+}
 const outputIndex = feedArgs.indexOf('--output');
 let runtimeDirectory;
 
@@ -226,16 +314,27 @@ if (outputIndex === -1) {
   feedArgs.push('--output', liveOutput);
   agentArgs.push('--output', liveOutput);
 }
+const outputPath = resolve(
+  callerDirectory,
+  feedArgs[feedArgs.indexOf('--output') + 1],
+);
+let rawSnapshotPath = outputPath;
+if (agentEnabled) {
+  if (!runtimeDirectory) {
+    runtimeDirectory = mkdtempSync(join(tmpdir(), 'diffsplain-live-'));
+  }
+  rawSnapshotPath = resolve(runtimeDirectory, 'raw-diff-data.json');
+  const feedOutputIndex = feedArgs.indexOf('--output');
+  feedArgs[feedOutputIndex + 1] = rawSnapshotPath;
+  feedArgs.push('--exclude-output', outputPath);
+}
+const reviewSnapshotPath = agentEnabled ? rawSnapshotPath : outputPath;
 process.on('exit', () => {
   if (runtimeDirectory) {
     rmSync(runtimeDirectory, { recursive: true, force: true });
   }
 });
 if (!feedArgs.includes('--watch')) feedArgs.push('--watch');
-const outputPath = resolve(
-  callerDirectory,
-  feedArgs[feedArgs.indexOf('--output') + 1],
-);
 const repoIndex = feedArgs.indexOf('--repo');
 const remoteIndex = feedArgs.indexOf('--remote');
 const projectKey = createHash('sha256')
@@ -262,7 +361,7 @@ writeFileSync(accessPath, access, { mode: 0o600 });
 chmodSync(accessPath, 0o600);
 if (agentEnabled) {
   feedArgs.push('--ignore-summary-watch');
-  agentArgs.push('--snapshot', outputPath);
+  agentArgs.push('--snapshot', rawSnapshotPath);
 }
 
 const snapshotStarted = performance.now();
@@ -334,118 +433,185 @@ function scheduleBrowserOpen(match) {
   }, 750);
 }
 
+function optionalSiteArgument(flag, value) {
+  return value ? [flag, value] : [];
+}
+
+function chatAccessArguments() {
+  if (accessMode.mode !== 'checkout-read-only') return [];
+  return ['--chat-access-root', accessMode.root];
+}
+
+function chatAgentArguments() {
+  if (!agentEnabled) return [];
+  return [
+    '--chat-agent',
+    selectedAgent,
+    '--chat-binary',
+    selectedAgentBinary,
+    '--chat-access-mode',
+    accessMode.mode,
+    ...chatAccessArguments(),
+    ...optionalSiteArgument('--chat-model', cli.model),
+    ...optionalSiteArgument('--chat-reasoning', cli.reasoning),
+  ];
+}
+
+function siteArguments() {
+  return [
+    resolve(root, 'scripts/serve-built.mjs'),
+    '--output',
+    outputPath,
+    '--port',
+    String(port),
+    '--host',
+    host,
+    '--project',
+    projectKey,
+    '--access',
+    access,
+    ...optionalSiteArgument('--previous-access', previousAccess),
+    '--chat-snapshot',
+    outputPath,
+    ...chatAgentArguments(),
+    ...(!cli.portWasPassed ? ['--increment-port'] : []),
+  ];
+}
+
+function handleSiteLine(line) {
+  if (handleConnectedTab(line)) return;
+  console.log(line);
+  const match = line.match(/^Diffsplain: (http:\/\/\S+)$/);
+  markSiteReady(match);
+  scheduleBrowserOpen(match);
+}
+
+function listenForSiteLines(child) {
+  if (!child.stdout) return;
+  createInterface({ input: child.stdout }).on('line', handleSiteLine);
+}
+
+function siteFailed(code, signal) {
+  return Boolean(code || signal);
+}
+
+function recordSiteFailure(code) {
+  supportRecorder?.addStage('serve', performance.now() - siteStarted, 'failed');
+  emitSupportRecord(code || 1);
+}
+
+function handleSiteExit(code, signal) {
+  if (closing) return;
+  if (siteFailed(code, signal)) recordSiteFailure(code);
+  stop(code || (signal ? 1 : 0));
+}
+
+function handleSiteError(error) {
+  if (closing) return;
+  supportRecorder?.addStage('serve', performance.now() - siteStarted, 'failed');
+  console.error(`Could not start the local page: ${error.message}`);
+  emitSupportRecord();
+  stop(1);
+}
+
 function startSite() {
   if (closing || site) return;
   siteStarted = performance.now();
-  const child = spawn(
-    process.execPath,
-    [
-      resolve(root, 'scripts/serve-built.mjs'),
-      '--output',
-      outputPath,
-      '--port',
-      String(port),
-      '--host',
-      host,
-      '--project',
-      projectKey,
-      '--access',
-      access,
-      ...(previousAccess ? ['--previous-access', previousAccess] : []),
-      ...(!cli.portWasPassed ? ['--increment-port'] : []),
-    ],
-    { cwd: root, stdio: ['ignore', 'pipe', 'inherit'] },
-  );
+  const child = spawn(process.execPath, siteArguments(), {
+    cwd: root,
+    stdio: ['ignore', 'pipe', 'inherit'],
+  });
   site = child;
+  listenForSiteLines(child);
+  child.on('exit', handleSiteExit);
+  child.on('error', handleSiteError);
+}
+
+function savedReviewFingerprint(notes) {
+  if (!notes) return undefined;
+  if (notes.agentReviewFingerprint) return notes.agentReviewFingerprint;
+  return notes.reviewFingerprint;
+}
+
+function snapshotReviewFingerprint(snapshot) {
+  const savedFingerprint = savedReviewFingerprint(snapshot.notes);
+  if (savedFingerprint) return savedFingerprint;
+  const reviewData = {
+    repo: {
+      name: snapshot.repo.name,
+      base: snapshot.repo.base,
+      head: snapshot.repo.head,
+      branch: snapshot.repo.branch,
+      baseBranch: snapshot.repo.baseBranch,
+      remote: snapshot.repo.remote,
+      targetKind: snapshot.repo.target?.kind,
+    },
+    change: {
+      title: snapshot.change.title,
+      number: snapshot.change.number,
+    },
+    files: snapshot.files.map((file) => ({
+      path: file.path,
+      oldPath: file.oldPath,
+      status: file.status,
+      additions: file.additions,
+      deletions: file.deletions,
+      isBinary: file.isBinary,
+      patch: file.patch,
+    })),
+  };
+  return createHash('sha256')
+    .update(JSON.stringify(reviewData))
+    .digest('hex');
+}
 
-  if (child.stdout) {
-    const siteLines = createInterface({ input: child.stdout });
-    siteLines.on('line', (line) => {
-      if (handleConnectedTab(line)) return;
-      console.log(line);
-      const match = line.match(/^Diffsplain: (http:\/\/\S+)$/);
-      markSiteReady(match);
-      scheduleBrowserOpen(match);
-    });
-  }
+function noteMetadataMatches(notes, fingerprint) {
+  return [
+    notes.complete,
+    notes.fresh,
+    notes.generatedFor === fingerprint,
+    notes.accessMode === accessMode.mode,
+  ].every(Boolean);
+}
 
-  child.on('exit', (code, signal) => {
-    if (!closing) {
-      if (code || signal) {
-        supportRecorder?.addStage(
-          'serve',
-          performance.now() - siteStarted,
-          'failed',
-        );
-        emitSupportRecord(code || 1);
-      }
-      stop(code || (signal ? 1 : 0));
-    }
-  });
-  child.on('error', (error) => {
-    if (!closing) {
-      supportRecorder?.addStage(
-        'serve',
-        performance.now() - siteStarted,
-        'failed',
-      );
-      console.error(`Could not start the local page: ${error.message}`);
-      emitSupportRecord();
-      stop(1);
-    }
-  });
+function normalizedAgentSetting(value) {
+  return value ?? null;
+}
+
+function agentSettingsMatch(notes) {
+  return [
+    notes.agent === selectedAgent,
+    normalizedAgentSetting(notes.model) === normalizedAgentSetting(cli.model),
+    normalizedAgentSetting(notes.reasoning) ===
+      normalizedAgentSetting(cli.reasoning),
+  ].every(Boolean);
+}
+
+function emptyReview(files) {
+  return Array.isArray(files) && files.length === 0;
+}
+
+function hasCurrentAgentNotes(snapshot, fingerprint) {
+  const notes = snapshot.notes;
+  if (!savedReviewFingerprint(notes)) return false;
+  if (!noteMetadataMatches(notes, fingerprint)) return false;
+  if (emptyReview(snapshot.files)) return true;
+  return agentSettingsMatch(notes);
+}
+
+function snapshotStateFromSnapshot(snapshot) {
+  const fingerprint = snapshotReviewFingerprint(snapshot);
+  return {
+    fingerprint,
+    hasCurrentAgentNotes: hasCurrentAgentNotes(snapshot, fingerprint),
+  };
 }
 
 function snapshotState() {
   try {
-    const snapshot = JSON.parse(readFileSync(outputPath, 'utf8'));
-    if (snapshot.notes?.reviewFingerprint) {
-      const fingerprint = snapshot.notes.reviewFingerprint;
-      const emptyReview =
-        Array.isArray(snapshot.files) && snapshot.files.length === 0;
-      return {
-        fingerprint,
-        hasCurrentAgentNotes:
-          snapshot.notes.complete &&
-          snapshot.notes.fresh &&
-          snapshot.notes.generatedFor === fingerprint &&
-          (emptyReview ||
-            (snapshot.notes.agent === selectedAgent &&
-              (snapshot.notes.model || null) === (cli.model || null) &&
-              (snapshot.notes.reasoning || null) ===
-                (cli.reasoning || null))),
-      };
-    }
-    const reviewData = {
-      repo: {
-        name: snapshot.repo.name,
-        base: snapshot.repo.base,
-        head: snapshot.repo.head,
-        branch: snapshot.repo.branch,
-        baseBranch: snapshot.repo.baseBranch,
-        remote: snapshot.repo.remote,
-        targetKind: snapshot.repo.target?.kind,
-      },
-      change: {
-        title: snapshot.change.title,
-        number: snapshot.change.number,
-      },
-      files: snapshot.files.map((file) => ({
-        path: file.path,
-        oldPath: file.oldPath,
-        status: file.status,
-        additions: file.additions,
-        deletions: file.deletions,
-        isBinary: file.isBinary,
-        patch: file.patch,
-      })),
-    };
-    return {
-      fingerprint: createHash('sha256')
-        .update(JSON.stringify(reviewData))
-        .digest('hex'),
-      hasCurrentAgentNotes: false,
-    };
+    return snapshotStateFromSnapshot(
+      JSON.parse(readFileSync(reviewSnapshotPath, 'utf8')),
+    );
   } catch {
     return undefined;
   }
@@ -586,12 +752,16 @@ function scheduleAgent(fingerprint) {
   if (agent) {
     if (selectedFingerprint !== agentFingerprint) {
       queuedFingerprint = selectedFingerprint;
+      console.log(
+        'Review changed while notes were generated. Restarting agent notes...',
+      );
       agent.kill('SIGTERM');
     }
     return;
   }
   clearTimeout(agentTimer);
   const delay = agentFingerprint ? 300 : 0;
+  console.log('Preparing agent notes...');
   agentTimer = setTimeout(() => runAgent(selectedFingerprint), delay);
 }
 
@@ -599,7 +769,7 @@ function markSnapshotReady() {
   if (snapshotReady) return;
   snapshotReady = true;
   try {
-    supportRecorder?.addBytes('snapshot', statSync(outputPath).size);
+    supportRecorder?.addBytes('snapshot', statSync(reviewSnapshotPath).size);
   } catch {}
   supportRecorder?.addStage(
     'snapshot',
@@ -607,11 +777,55 @@ function markSnapshotReady() {
   );
 }
 
+function snapshotForPresentation(snapshot) {
+  if (snapshotStateFromSnapshot(snapshot).hasCurrentAgentNotes) {
+    return snapshot;
+  }
+  const content = {
+    ...snapshot,
+    notes: {
+      ...snapshot.notes,
+      complete: false,
+      status: 'generating',
+    },
+  };
+  delete content.version;
+  delete content.generatedAt;
+  return {
+    version: createHash('sha256')
+      .update(JSON.stringify(content))
+      .digest('hex')
+      .slice(0, 12),
+    generatedAt: new Date().toISOString(),
+    ...content,
+  };
+}
+
+function seedPresentationSnapshot() {
+  const snapshot = snapshotForPresentation(
+    JSON.parse(readFileSync(rawSnapshotPath, 'utf8')),
+  );
+  mkdirSync(dirname(outputPath), { recursive: true });
+  const pendingOutput = `${outputPath}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
+  writeFileSync(pendingOutput, `${JSON.stringify(snapshot, null, 2)}\n`);
+  renameSync(pendingOutput, outputPath);
+}
+
 function isSnapshotLine(line) {
   return line.startsWith('Wrote ') || line === 'No diff-data changes';
 }
 
-function startSnapshotDependents() {
+function startSnapshotDependents({ rawSnapshotWritten = false } = {}) {
+  if (agentEnabled && rawSnapshotWritten) {
+    try {
+      seedPresentationSnapshot();
+    } catch (error) {
+      console.error(`Could not publish the live snapshot: ${error.message}`);
+      emitSupportRecord();
+      stop(1);
+      return;
+    }
+  }
   markSnapshotReady();
   startSite();
   if (agentEnabled) scheduleAgent();
@@ -622,7 +836,9 @@ function shouldPrintFeedLine(line) {
 }
 
 function handleFeedLine(line) {
-  if (isSnapshotLine(line)) startSnapshotDependents();
+  if (isSnapshotLine(line)) {
+    startSnapshotDependents({ rawSnapshotWritten: line.startsWith('Wrote ') });
+  }
   if (shouldPrintFeedLine(line)) console.log(line);
 }