@in-the-loop-labs/pair-review 3.8.0 → 3.9.1

package/src/interactive-analysis-config.js

@@ -0,0 +1,152 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+/**
+ * Shared helpers for threading per-run CLI instructions into analysis.
+ *
+ * `resolveCliInstructions` reads `--instructions` / `--instructions-file`.
+ *
+ * `buildInteractiveAnalysisConfig` / `prepareInteractiveAnalysisConfig` bridge the
+ * CLI to the browser-side auto-analyze: interactive `--ai` / `--council` runs open
+ * the web UI and trigger analysis via the `?analyze=true` URL, which has no slot
+ * for custom instructions. To honor `--instructions` there too (instead of
+ * silently dropping it), the CLI resolves the full review config + instructions
+ * and threads a short id through the URL as `analysisConfigId`. The PR/local
+ * browser code already resolves that id before starting analysis (see
+ * `_fetchAutoAnalysisConfigFromUrl` in public/js/pr.js and the local auto-analyze
+ * in public/js/local.js).
+ *
+ * The resolution is split so the same config object serves two storage targets:
+ *   - `buildInteractiveAnalysisConfig` — PURE, returns the resolved config object
+ *     (no storage). Reused by the delegation path, which POSTs it to a server
+ *     running in ANOTHER process (the in-memory store below is per-process).
+ *   - `prepareInteractiveAnalysisConfig` — the cold-start wrapper that stashes the
+ *     built config in the in-memory bulk-analysis-config store (same process that
+ *     then starts the server) and returns the id.
+ *
+ * Living in its own module keeps both CLI entry points — `handlePullRequest`
+ * (src/main.js) and `handleLocalReview` (src/local-review.js) — able to import
+ * it without a require cycle through main.js.
+ */
+
+const fs = require('fs');
+const { resolveReviewConfig } = require('./review-config');
+const { createBulkAnalysisConfig } = require('./routes/bulk-analysis-configs');
+
+const MAX_INSTRUCTIONS_CHARS = 5000;
+
+/**
+ * Resolve per-run custom instructions ("requestInstructions") from CLI flags.
+ *
+ * Precedence: `--instructions <text>` is used directly; otherwise
+ * `--instructions-file <path>` is read from disk. The result is trimmed and
+ * capped at 5000 chars (parity with the web analyze routes). Returns `null`
+ * when neither flag is supplied.
+ *
+ * @param {Object} flags - Parsed CLI flags
+ * @returns {Promise<string|null>}
+ * @throws {Error} On unreadable instructions file or when the text exceeds the cap.
+ */
+async function resolveCliInstructions(flags) {
+  let text = null;
+
+  if (typeof flags.instructions === 'string') {
+    text = flags.instructions;
+  } else if (typeof flags.instructionsFile === 'string') {
+    try {
+      text = await fs.promises.readFile(flags.instructionsFile, 'utf8');
+    } catch (err) {
+      throw new Error(`Failed to read --instructions-file "${flags.instructionsFile}": ${err.message}`);
+    }
+  }
+
+  if (text == null) return null;
+
+  text = text.trim();
+  if (text.length === 0) return null;
+
+  if (text.length > MAX_INSTRUCTIONS_CHARS) {
+    throw new Error(
+      `Custom instructions exceed the ${MAX_INSTRUCTIONS_CHARS}-character limit (got ${text.length}).`
+    );
+  }
+
+  return text;
+}
+
+/**
+ * For an interactive `--ai` / `--council` run that ALSO carries
+ * `--instructions[-file]`, resolve the full review config (single provider/model
+ * or council) plus the instruction text into the analysis-config object the
+ * browser-side analyze code consumes. PURE: it performs no storage, so it serves
+ * both the in-process cold-start path (via `prepareInteractiveAnalysisConfig`)
+ * and the cross-process delegation path (which POSTs the object to the running
+ * server — see `storeAnalysisConfigRemote` in src/single-port.js).
+ *
+ * Returns `null` when no instructions were supplied, so callers keep their prior
+ * URL shape (bare `?analyze=true` + optional `&council=`) unchanged.
+ *
+ * The returned config is shape-compatible with what the browser-side analyze code
+ * consumes: a single pick becomes `{ provider, model, customInstructions }`; a
+ * council becomes an inline snapshot `{ isCouncil, configType, councilConfig,
+ * councilName, customInstructions }` (the snapshot forces the analysis route to
+ * use the exact resolved council rather than re-fetching by id).
+ *
+ * @param {Object} params
+ * @param {Object} params.db - Database instance
+ * @param {Object} params.config - Loaded global config
+ * @param {Object} params.flags - Parsed CLI flags (council/model/instructions)
+ * @param {string} params.repository - owner/repo (for repo-default resolution)
+ * @returns {Promise<Object|null>} The analysisConfig object, or null when no instructions.
+ */
+async function buildInteractiveAnalysisConfig({ db, config, flags, repository }) {
+  const requestInstructions = await resolveCliInstructions(flags);
+  if (!requestInstructions) return null;
+
+  const reviewConfig = await resolveReviewConfig(
+    db,
+    repository,
+    { council: flags.council, model: flags.model },
+    config
+  );
+
+  return reviewConfig.type === 'council'
+    ? {
+        isCouncil: true,
+        configType: reviewConfig.configType,
+        councilConfig: reviewConfig.councilConfig,
+        councilName: reviewConfig.council.name || null,
+        customInstructions: requestInstructions
+      }
+    : {
+        provider: reviewConfig.provider,
+        model: reviewConfig.model,
+        customInstructions: requestInstructions
+      };
+}
+
+/**
+ * Thin in-process wrapper around `buildInteractiveAnalysisConfig`: resolve the
+ * analysis config and, when present, stash it in the in-memory
+ * bulk-analysis-config store, returning the id to thread through the browser URL
+ * as `analysisConfigId`. Used by the cold-start handlers (`handlePullRequest`,
+ * `handleLocalReview`) that go on to start the server in THIS process, so the
+ * in-process store is the one the browser tab will read from.
+ *
+ * Returns `null` when no instructions were supplied (callers keep their prior URL
+ * shape unchanged).
+ *
+ * @param {Object} params - See `buildInteractiveAnalysisConfig`.
+ * @returns {Promise<string|null>} The analysisConfigId, or null when no instructions.
+ */
+async function prepareInteractiveAnalysisConfig({ db, config, flags, repository }) {
+  const analysisConfig = await buildInteractiveAnalysisConfig({ db, config, flags, repository });
+  if (!analysisConfig) return null;
+
+  const { id } = createBulkAnalysisConfig(analysisConfig);
+  return id;
+}
+
+module.exports = {
+  resolveCliInstructions,
+  buildInteractiveAnalysisConfig,
+  prepareInteractiveAnalysisConfig
+};

package/src/local-review.js

@@ -14,6 +14,7 @@ const execAsync = promisify(exec);
 const { STOPS, scopeIncludes, includesBranch, DEFAULT_SCOPE, scopeLabel, reviewScope } = require('./local-scope');
 const { initializeDatabase, ReviewRepository, RepoSettingsRepository } = require('./database');
 const { resolveCouncilHandle } = require('./councils/resolve-council');
+const { prepareInteractiveAnalysisConfig } = require('./interactive-analysis-config');
 const { startServer } = require('./server');
 const { localReviewDiffs } = require('./routes/shared');
 const summaryGenerator = require('./ai/summary-generator');
@@ -703,9 +704,14 @@ async function generateLocalDiff(repoPath, options = {}) {
  * @param {Object} params.config - Loaded config
  * @param {string} params.repoPath - Path to the working tree (already validated)
  * @param {Object} [params.flags] - CLI flags / options
+ * @param {boolean} [params.startBackgroundJobs=true] - When false, skip the
+ *   fire-and-forget summary/tour generation jobs. The interactive UI wants them
+ *   (they populate the review while the human reads the diff), but a one-shot
+ *   headless run does not: they would spend provider budget after the JSON
+ *   result is already printed and keep the event loop alive (CLI hang).
  * @returns {Promise<{sessionId: number, repoPath: string, branch: string, repository: string, headSha: string, diff: string, stats: Object, digest: string|null, branchInfo: Object|null, scopeStart: string, scopeEnd: string, baseBranch: string|null}>}
  */
-async function setupLocalReviewSession({ db, config, repoPath, flags = {} }) {
+async function setupLocalReviewSession({ db, config, repoPath, flags = {}, startBackgroundJobs = true }) {
   const headSha = await module.exports.getHeadSha(repoPath);
   console.log(`HEAD SHA: ${headSha}`);
 
@@ -837,25 +843,30 @@ async function setupLocalReviewSession({ db, config, repoPath, flags = {} }) {
     logger.warn(`Could not persist diff to database: ${persistError.message}`);
   }
 
-  summaryGenerator.kickOffSummaryJob({
-    db,
-    config,
-    reviewId: sessionId,
-    diffText: diff,
-    worktreePath: repoPath,
-    reviewContext: { prTitle: branch },
-    trigger: 'auto'
-  })?.catch((err) => logger.warn(`Hunk summary job failed for review ${sessionId}: ${err.message}`));
-
-  tourGenerator.kickOffTourJob({
-    db,
-    config,
-    reviewId: sessionId,
-    diffText: diff,
-    worktreePath: repoPath,
-    reviewContext: { prTitle: branch },
-    trigger: 'auto'
-  })?.catch((err) => logger.warn(`Tour job failed for review ${sessionId}: ${err.message}`));
+  // Fire-and-forget summary/tour generation. Skipped for headless one-shot runs
+  // (startBackgroundJobs:false) — they would spend provider budget after the
+  // result is reported and keep the event loop alive, hanging the CLI.
+  if (startBackgroundJobs) {
+    summaryGenerator.kickOffSummaryJob({
+      db,
+      config,
+      reviewId: sessionId,
+      diffText: diff,
+      worktreePath: repoPath,
+      reviewContext: { prTitle: branch },
+      trigger: 'auto'
+    })?.catch((err) => logger.warn(`Hunk summary job failed for review ${sessionId}: ${err.message}`));
+
+    tourGenerator.kickOffTourJob({
+      db,
+      config,
+      reviewId: sessionId,
+      diffText: diff,
+      worktreePath: repoPath,
+      reviewContext: { prTitle: branch },
+      trigger: 'auto'
+    })?.catch((err) => logger.warn(`Tour job failed for review ${sessionId}: ${err.message}`));
+  }
 
   return {
     sessionId,
@@ -928,7 +939,18 @@ async function handleLocalReview(targetPath, flags = {}) {
     let url = `http://localhost:${port}/local/${session.sessionId}`;
     const shouldAnalyze = flags.ai || flags.council;
     if (shouldAnalyze) url += '?analyze=true';
-    if (councilSelection) url += `&council=${councilSelection.id}`;
+    // When the run carries --instructions, stash the resolved analysis config and
+    // thread its id so the browser-side auto-analyze honors the instructions
+    // instead of silently dropping them (mirrors handlePullRequest). The id
+    // encodes the council selection, so prefer it over the bare &council= param.
+    const analysisConfigId = shouldAnalyze
+      ? await prepareInteractiveAnalysisConfig({ db, config, flags, repository: session.repository })
+      : null;
+    if (analysisConfigId) {
+      url += `&analysisConfigId=${analysisConfigId}`;
+    } else if (councilSelection) {
+      url += `&council=${councilSelection.id}`;
+    }
     console.log(`\nOpening browser to: ${url}`);
     await open(url);