diffsplain 0.5.0 → 0.7.0

package/scripts/present.mjs

@@ -1,12 +1,15 @@
 #!/usr/bin/env node
 
-import { spawn, spawnSync } from 'node:child_process';
-import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
 import {
-  existsSync,
+  chmodSync,
+  mkdirSync,
   mkdtempSync,
   readFileSync,
   rmSync,
+  statSync,
+  writeFileSync,
 } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
@@ -14,14 +17,88 @@ import { createInterface } from 'node:readline';
 import { fileURLToPath } from 'node:url';
 import { helpText, parseCliArgs } from './cli-args.mjs';
 import {
+  assertReasoningSupported,
   codingAgentBinary,
   commandAvailable,
   selectCodingAgent,
 } from './coding-agents.mjs';
 import { doctorReport } from './doctor.mjs';
+import { accessTokenDirectory } from './access-token.mjs';
+import { cacheStatus, clearCache, formatCacheStatus, pruneCache } from './cache.mjs';
+import {
+  agentFallbackRecordNeeded,
+  agentRunCompleted,
+  agentRunFailed,
+  agentRunNeeded,
+  agentRunSuperseded,
+  ensureBuiltAssets,
+  failedAgentRunForFingerprint,
+  nextAgentFingerprint,
+  openBrowser,
+} from './presenter-runtime.mjs';
+import {
+  createSupportRecorder,
+  formatSupportRecord,
+  safeCommandVersion,
+  writeSupportRecord,
+} from './support-record.mjs';
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const callerDirectory = process.cwd();
+const cacheArgs = process.argv.slice(2);
+
+function cacheUsage() {
+  console.error(
+    'Use: diffsplain cache [status|prune --age DAYS|prune --size BYTES|clear --yes]',
+  );
+  return 2;
+}
+
+function printCacheChange(result) {
+  console.log(
+    `Removed ${result.removed.length} inactive cache entries; kept ${result.retainedActive.length} active.`,
+  );
+  return 0;
+}
+
+function statusCommand(args) {
+  if (args.length !== 1 && args.length !== 2) return cacheUsage();
+  console.log(formatCacheStatus(cacheStatus()));
+  return 0;
+}
+
+function clearCommand(args) {
+  if (args.length !== 3 || args[2] !== '--yes') return cacheUsage();
+  return printCacheChange(clearCache());
+}
+
+function pruneOptions(flag, rawValue) {
+  const value = Number(rawValue);
+  if (!Number.isFinite(value) || value < 0) return undefined;
+  if (flag === '--age') return { maxAgeMs: value * 86_400_000 };
+  if (flag === '--size') return { maxBytes: value };
+  return undefined;
+}
+
+function pruneCommand(args) {
+  if (args.length !== 4) return cacheUsage();
+  const options = pruneOptions(args[2], args[3]);
+  return options ? printCacheChange(pruneCache(options)) : cacheUsage();
+}
+
+function runCacheCommand(args) {
+  const commands = {
+    status: statusCommand,
+    clear: clearCommand,
+    prune: pruneCommand,
+  };
+  const command = args[1] || 'status';
+  return commands[command]?.(args) ?? cacheUsage();
+}
+
+if (cacheArgs[0] === 'cache') {
+  process.exit(runCacheCommand(cacheArgs));
+}
 let cli;
 try {
   cli = parseCliArgs(process.argv.slice(2), { callerDirectory });
@@ -43,28 +120,102 @@ if (cli.version) {
   process.exit(0);
 }
 if (cli.doctor) {
-  const report = await doctorReport();
-  console.log(report.text);
+  if (cli.doctor.deep) {
+    console.error(
+      'Warning: deep checks run local provider commands. They do not send a provider prompt.',
+    );
+  }
+  const report = await doctorReport({ deep: cli.doctor.deep });
+  console.log(cli.doctor.json ? JSON.stringify(report.json, null, 2) : report.text);
   process.exit(report.ready ? 0 : 1);
 }
 
-const { agentEnabled, port } = cli;
+let supportRecorder;
+let supportRecordEmitted = false;
+
+function wantsSupportRecord() {
+  return cli.supportRecord || Boolean(cli.supportRecordFile);
+}
+
+function selectedProviderVersion(provider, binary) {
+  if (!binary) return null;
+  return safeCommandVersion(provider, binary);
+}
+
+function beginSupportRecord() {
+  if (supportRecorder) return;
+  if (!wantsSupportRecord()) return;
+  supportRecorder = createSupportRecorder();
+}
+
+function recordSelectedProvider(provider, binary) {
+  supportRecorder?.setProvider(
+    provider,
+    selectedProviderVersion(provider, binary),
+  );
+}
+
+function deliverSupportRecord(record) {
+  if (cli.supportRecordFile) {
+    writeSupportRecord(cli.supportRecordFile, record);
+    console.error(`Wrote support record to ${cli.supportRecordFile}`);
+    return;
+  }
+  process.stderr.write(
+    `Diffsplain support record:\n${formatSupportRecord(record)}`,
+  );
+}
+
+function emitSupportRecord(code = 1) {
+  if (!supportRecorder) return;
+  if (supportRecordEmitted) return;
+  supportRecordEmitted = true;
+  const record = supportRecorder.failure(code);
+  try {
+    deliverSupportRecord(record);
+  } catch {
+    console.error('Could not write the support record.');
+  }
+}
+
+const { agentEnabled, browserEnabled, host, port } = cli;
 const feedArgs = [...cli.feedArgs];
 const agentArgs = [...cli.agentArgs];
+let selectedAgent;
+beginSupportRecord();
 if (agentEnabled) {
+  const selectionStarted = performance.now();
   try {
-    const selectedAgent = await selectCodingAgent(
+    selectedAgent = await selectCodingAgent(
       cli.agent,
       (agent) =>
         commandAvailable(
           codingAgentBinary(agent, { codexBin: cli.codexBin }),
         ),
     );
+    assertReasoningSupported(selectedAgent, cli.reasoning);
+    const agentBinary = codingAgentBinary(selectedAgent, {
+      codexBin: cli.codexBin,
+    });
+    recordSelectedProvider(selectedAgent, agentBinary);
+    supportRecorder?.addStage(
+      'agent',
+      performance.now() - selectionStarted,
+    );
     agentArgs.push('--agent', selectedAgent);
   } catch (error) {
+    recordSelectedProvider(cli.agent || 'unknown');
+    supportRecorder?.addStage(
+      'agent',
+      performance.now() - selectionStarted,
+      'failed',
+    );
     console.error(error.message);
+    emitSupportRecord();
     process.exit(1);
   }
+} else {
+  feedArgs.push('--no-summaries');
 }
 const outputIndex = feedArgs.indexOf('--output');
 let runtimeDirectory;
@@ -95,23 +246,39 @@ const projectKey = createHash('sha256')
   )
   .digest('hex')
   .slice(0, 12);
+const accessDirectory = accessTokenDirectory();
+const accessPath = join(accessDirectory, `${projectKey}.token`);
+mkdirSync(accessDirectory, { recursive: true, mode: 0o700 });
+chmodSync(accessDirectory, 0o700);
+let previousAccess;
+try {
+  const savedAccess = readFileSync(accessPath, 'utf8').trim();
+  if (/^[A-Za-z0-9_-]{43}$/.test(savedAccess)) previousAccess = savedAccess;
+} catch {
+  // The first run for a project has no prior tab access value.
+}
+const access = randomBytes(32).toString('base64url');
+writeFileSync(accessPath, access, { mode: 0o600 });
+chmodSync(accessPath, 0o600);
 if (agentEnabled) {
   feedArgs.push('--ignore-summary-watch');
   agentArgs.push('--snapshot', outputPath);
 }
 
-const builtPage = resolve(root, 'dist/index.html');
-if (!existsSync(builtPage)) {
-  const result = spawnSync(
-    process.platform === 'win32' ? 'npm.cmd' : 'npm',
-    ['run', 'build'],
-    { cwd: root, stdio: 'inherit' },
+const snapshotStarted = performance.now();
+let snapshotReady = false;
+try {
+  ensureBuiltAssets({ root });
+} catch (error) {
+  const exitCode = Number.isInteger(error.exitCode) ? error.exitCode : 1;
+  supportRecorder?.addStage(
+    'snapshot',
+    performance.now() - snapshotStarted,
+    'failed',
   );
-  if (result.error) {
-    console.error(`Could not build the local page: ${result.error.message}`);
-    process.exit(1);
-  }
-  if (result.status !== 0) process.exit(result.status || 1);
+  console.error(error.message);
+  emitSupportRecord(exitCode);
+  process.exit(exitCode);
 }
 
 const feed = spawn(
@@ -127,39 +294,49 @@ let site;
 let agent;
 let agentTimer;
 let agentFingerprint;
+let completedAgentFingerprint;
+let failedAgentFingerprint;
 let queuedFingerprint;
 let browserOpened = false;
 let browserOpenTimer;
+let siteReady = false;
+let siteStarted;
 
-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];
+function handleConnectedTab(line) {
+  if (line !== 'Diffsplain tab: connected') return false;
+  if (!browserOpened && browserOpenTimer) {
+    clearTimeout(browserOpenTimer);
+    browserOpenTimer = undefined;
+    browserOpened = true;
+    console.log('Reusing the open Diffsplain tab.');
   }
+  return true;
+}
 
-  const opener = spawn(command, args, {
-    detached: true,
-    stdio: 'ignore',
-  });
-  opener.once('error', (error) => {
-    console.error(`Could not open the browser: ${error.message}`);
-  });
-  opener.unref();
+function markSiteReady(match) {
+  if (siteReady || !match) return;
+  siteReady = true;
+  supportRecorder?.addStage(
+    'serve',
+    performance.now() - siteStarted,
+  );
+}
+
+function scheduleBrowserOpen(match) {
+  if (!browserEnabled || browserOpened || browserOpenTimer || !match) return;
+  browserOpenTimer = setTimeout(() => {
+    browserOpenTimer = undefined;
+    browserOpened = true;
+    openBrowser(match[1], {
+      onError: (error) =>
+        console.error(`Could not open the browser: ${error.message}`),
+    });
+  }, 750);
 }
 
 function startSite() {
   if (closing || site) return;
+  siteStarted = performance.now();
   const child = spawn(
     process.execPath,
     [
@@ -168,8 +345,13 @@ function startSite() {
       outputPath,
       '--port',
       String(port),
+      '--host',
+      host,
       '--project',
       projectKey,
+      '--access',
+      access,
+      ...(previousAccess ? ['--previous-access', previousAccess] : []),
       ...(!cli.portWasPassed ? ['--increment-port'] : []),
     ],
     { cwd: root, stdio: ['ignore', 'pipe', 'inherit'] },
@@ -179,33 +361,36 @@ function startSite() {
   if (child.stdout) {
     const siteLines = createInterface({ input: child.stdout });
     siteLines.on('line', (line) => {
-      if (line === 'Diffsplain tab: connected') {
-        if (!browserOpened && browserOpenTimer) {
-          clearTimeout(browserOpenTimer);
-          browserOpenTimer = undefined;
-          browserOpened = true;
-          console.log('Reusing the open Diffsplain tab.');
-        }
-        return;
-      }
+      if (handleConnectedTab(line)) return;
       console.log(line);
       const match = line.match(/^Diffsplain: (http:\/\/\S+)$/);
-      if (!browserOpened && !browserOpenTimer && match) {
-        browserOpenTimer = setTimeout(() => {
-          browserOpenTimer = undefined;
-          browserOpened = true;
-          openBrowser(match[1]);
-        }, 750);
-      }
+      markSiteReady(match);
+      scheduleBrowserOpen(match);
     });
   }
 
   child.on('exit', (code, signal) => {
-    if (!closing) stop(code || (signal ? 1 : 0));
+    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);
     }
   });
@@ -216,12 +401,19 @@ function snapshotState() {
     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,
+          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 = {
@@ -263,6 +455,56 @@ function snapshotFingerprint() {
   return snapshotState()?.fingerprint;
 }
 
+function recordAgentFallbackStage(needed, startedAt) {
+  if (!needed) return;
+  supportRecorder?.addStage(
+    'agent',
+    performance.now() - startedAt,
+    'failed',
+  );
+}
+
+function releaseAgentChild(child) {
+  if (agent === child) agent = undefined;
+  agentFingerprint = undefined;
+}
+
+function recordAgentRunResult({
+  closing,
+  code,
+  error,
+  signal,
+  superseded,
+  finishedFingerprint,
+}) {
+  if (agentRunCompleted({ code, error, signal, superseded })) {
+    completedAgentFingerprint = finishedFingerprint;
+  }
+  if (!agentRunFailed({ closing, code, error, signal, superseded })) return;
+  failedAgentFingerprint = finishedFingerprint;
+  if (error) console.error(error.message);
+  console.error(
+    'The coding agent could not write notes. It will retry after the diff changes or Diffsplain restarts.',
+  );
+}
+
+function scheduleNextAgentFingerprint({
+  pendingFingerprint,
+  finishedFingerprint,
+}) {
+  const nextFingerprint = nextAgentFingerprint({
+    queuedFingerprint: pendingFingerprint,
+    observedFingerprint: snapshotFingerprint(),
+    finishedFingerprint,
+  });
+  queuedFingerprint = undefined;
+  if (nextFingerprint) scheduleAgent(nextFingerprint);
+}
+
+function emitAgentFallbackRecord(needed, code) {
+  if (needed) emitSupportRecord(code || 1);
+}
+
 function runAgent(fingerprint) {
   if (closing || !agentEnabled) return;
   if (agent) {
@@ -273,6 +515,7 @@ function runAgent(fingerprint) {
     return;
   }
   agentFingerprint = fingerprint;
+  const agentStarted = performance.now();
   const child = spawn(
     process.execPath,
     [resolve(root, 'scripts/generate-summaries.mjs'), ...agentArgs],
@@ -284,17 +527,32 @@ function runAgent(fingerprint) {
     if (settled) return;
     settled = true;
     const finishedFingerprint = agentFingerprint;
-    if (agent === child) agent = undefined;
-    agentFingerprint = finishedFingerprint;
-    if (!closing && (error || code || signal)) {
-      if (error) console.error(error.message);
-      console.error(
-        'The coding agent could not write notes. The diff page will stay open.',
-      );
-    }
-    const latest = queuedFingerprint || snapshotFingerprint();
-    queuedFingerprint = undefined;
-    if (latest && latest !== finishedFingerprint) scheduleAgent(latest);
+    const pendingFingerprint = queuedFingerprint;
+    const superseded = agentRunSuperseded(
+      pendingFingerprint,
+      finishedFingerprint,
+    );
+    const needsFallbackRecord = agentFallbackRecordNeeded({
+      closing,
+      queuedFingerprint: pendingFingerprint,
+      error,
+      signal,
+    });
+    recordAgentFallbackStage(needsFallbackRecord, agentStarted);
+    releaseAgentChild(child);
+    recordAgentRunResult({
+      closing,
+      code,
+      error,
+      signal,
+      superseded,
+      finishedFingerprint,
+    });
+    scheduleNextAgentFingerprint({
+      pendingFingerprint,
+      finishedFingerprint,
+    });
+    emitAgentFallbackRecord(needsFallbackRecord, code);
   };
   child.on('error', (error) => finish(1, undefined, error));
   child.on('exit', (code, signal) => finish(code, signal));
@@ -303,16 +561,28 @@ function runAgent(fingerprint) {
 function scheduleAgent(fingerprint) {
   const state = snapshotState();
   const selectedFingerprint = fingerprint || state?.fingerprint;
+  failedAgentFingerprint = failedAgentRunForFingerprint(
+    failedAgentFingerprint,
+    selectedFingerprint,
+  );
   if (
     !cli.forceSummaryRegeneration &&
     !agentFingerprint &&
     state?.hasCurrentAgentNotes &&
     selectedFingerprint === state.fingerprint
   ) {
-    agentFingerprint = selectedFingerprint;
+    console.log('Reusing current agent notes.');
+    return;
+  }
+  if (
+    !agentRunNeeded(selectedFingerprint, {
+      activeFingerprint: agentFingerprint,
+      completedFingerprint: completedAgentFingerprint,
+      failedFingerprint: failedAgentFingerprint,
+    })
+  ) {
     return;
   }
-  if (!selectedFingerprint || selectedFingerprint === agentFingerprint) return;
   if (agent) {
     if (selectedFingerprint !== agentFingerprint) {
       queuedFingerprint = selectedFingerprint;
@@ -325,17 +595,44 @@ function scheduleAgent(fingerprint) {
   agentTimer = setTimeout(() => runAgent(selectedFingerprint), delay);
 }
 
+function markSnapshotReady() {
+  if (snapshotReady) return;
+  snapshotReady = true;
+  try {
+    supportRecorder?.addBytes('snapshot', statSync(outputPath).size);
+  } catch {}
+  supportRecorder?.addStage(
+    'snapshot',
+    performance.now() - snapshotStarted,
+  );
+}
+
+function isSnapshotLine(line) {
+  return line.startsWith('Wrote ') || line === 'No diff-data changes';
+}
+
+function startSnapshotDependents() {
+  markSnapshotReady();
+  startSite();
+  if (agentEnabled) scheduleAgent();
+}
+
+function shouldPrintFeedLine(line) {
+  return line !== 'No diff-data changes' || !agentEnabled;
+}
+
+function handleFeedLine(line) {
+  if (isSnapshotLine(line)) startSnapshotDependents();
+  if (shouldPrintFeedLine(line)) console.log(line);
+}
+
 if (feed.stdout) {
   const feedLines = createInterface({ input: feed.stdout });
-  feedLines.on('line', (line) => {
-    const snapshotReady =
-      line.startsWith('Wrote ') || line === 'No diff-data changes';
-    if (snapshotReady) {
-      startSite();
-      if (agentEnabled) scheduleAgent();
-    }
-    if (line !== 'No diff-data changes' || !agentEnabled) console.log(line);
-  });
+  feedLines.on('line', handleFeedLine);
+}
+
+function stopChild(child) {
+  if (child && !child.killed) child.kill('SIGTERM');
 }
 
 function stop(code = 0) {
@@ -343,18 +640,30 @@ function stop(code = 0) {
   closing = true;
   clearTimeout(browserOpenTimer);
   clearTimeout(agentTimer);
-  if (!feed.killed) feed.kill('SIGTERM');
-  if (site && !site.killed) site.kill('SIGTERM');
-  if (agent && !agent.killed) agent.kill('SIGTERM');
+  [feed, site, agent].forEach(stopChild);
   process.exitCode = code;
 }
 
 feed.on('exit', (code, signal) => {
-  if (!closing && (code || signal)) stop(code || 1);
+  if (!closing && (code || signal)) {
+    supportRecorder?.addStage(
+      'snapshot',
+      performance.now() - snapshotStarted,
+      'failed',
+    );
+    emitSupportRecord(code || 1);
+    stop(code || 1);
+  }
 });
 feed.on('error', (error) => {
   if (!closing) {
+    supportRecorder?.addStage(
+      'snapshot',
+      performance.now() - snapshotStarted,
+      'failed',
+    );
     console.error(`Could not start the diff watcher: ${error.message}`);
+    emitSupportRecord();
     stop(1);
   }
 });