@link-assistant/hive-mind 2.0.12 → 2.0.13

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @link-assistant/hive-mind
 
+## 2.0.13
+
+### Patch Changes
+
+- ca7c412: fix(branch): validate `--base-branch` existence up-front and stop misreporting a missing base branch as an empty repository (#1959)
+
+  A `/solve` run from the Telegram bot crashed with the unactionable message
+  `Branch operation failed`. Root cause: the user passed `--base-branch issue-375-8a4323e580780`
+  — a **one-character typo** of the real branch `issue-375-8a4323e58078`. The branch did not
+  exist, but nothing validated that before the run started. The solver cloned 72 MB, then
+  `git checkout -b … origin/issue-375-8a4323e580780` failed with
+  `fatal: 'origin/…' is not a commit`. Worse, the branch-creation error handler **misdiagnosed**
+  this as "the repository appears to be empty (no commits)" and suggested `--auto-init-repository`,
+  which is wrong for a non-empty repo. The top level then collapsed everything to the bare
+  `Branch operation failed` comment on GitHub.
+
+  Defense-in-depth fix applied across the codebase:
+  - `validateGitHubEntityExistence()` (`src/github-entity-validation.lib.mjs`) gains a new
+    base-branch step: when `--base-branch` is supplied, `checkBaseBranchExists()` verifies it
+    via `gh api repos/{owner}/{repo}/branches/{branch}` **before** cloning, in the same fail-fast
+    gate that already checks user/repo/issue/PR. A definitive 404 fails the run; transient
+    errors fail open so a network hiccup never blocks a valid run.
+  - New helpers `levenshteinDistance()` and `findClosestBranchName()` power a "did you mean
+    '<closest-existing-branch>'?" suggestion built from the repo's actual branch list, so the
+    exact real-world typo points the user straight at `issue-375-8a4323e58078`.
+  - Both entry points share the gate: `src/solve.mjs` (CLI + the GitHub comment path) and
+    `src/telegram-bot.mjs` (the bot pre-flight) now pass `baseBranch` in, so a missing base
+    branch fails immediately at every level — including in Telegram, before the solve command
+    is queued or spawned.
+  - `handleBranchCreationError()` (`src/solve.branch-errors.lib.mjs`) now receives `baseBranch`
+    and `branchSource`. When a custom base branch is the missing ref it reports the real root
+    cause instead of the bogus empty-repository advice; the genuine empty-repository path
+    (creating from the default branch) is preserved. `createOrCheckoutBranch()`
+    (`src/solve.branch.lib.mjs`) threads the base branch and its source into the handler.
+
+  Adds `tests/test-base-branch-existence.mjs` (17 offline assertions covering the helpers and
+  the misdiagnosis fix), `tests/test-base-branch-existence-integration.mjs`
+  (`@hive-mind-integration`, the real `gh` gate), and a deep case study in
+  `docs/case-studies/issue-1959/`.
+
 ## 2.0.12
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "2.0.12",
+  "version": "2.0.13",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/github-entity-validation.lib.mjs

@@ -10,8 +10,135 @@ import { ghCmdRetry } from './lib.mjs';
 import { ghPrView, ghIssueView } from './github.lib.mjs';
 
 /**
- * Validate existence of GitHub entities (user/org, repository, issue/PR) before executing a command.
- * Checks each level in order: user/org → repository → issue/PR, failing fast at the first missing entity.
+ * Compute the Levenshtein edit distance between two strings.
+ * Used to suggest the closest existing branch name when a requested base
+ * branch is not found (issue #1959 — typos like an extra trailing character).
+ *
+ * @param {string} a - First string
+ * @param {string} b - Second string
+ * @returns {number} The minimum number of single-character edits
+ */
+export function levenshteinDistance(a, b) {
+  a = String(a);
+  b = String(b);
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+
+  // Single-row dynamic programming to keep memory at O(min(len)).
+  let previousRow = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 0; i < a.length; i++) {
+    const currentRow = [i + 1];
+    for (let j = 0; j < b.length; j++) {
+      const insertCost = currentRow[j] + 1;
+      const deleteCost = previousRow[j + 1] + 1;
+      const replaceCost = previousRow[j] + (a[i] === b[j] ? 0 : 1);
+      currentRow.push(Math.min(insertCost, deleteCost, replaceCost));
+    }
+    previousRow = currentRow;
+  }
+  return previousRow[b.length];
+}
+
+/**
+ * Find the closest matching branch name to a (likely mistyped) target.
+ * Returns the nearest candidate only when it is close enough to be a plausible
+ * typo, so we never suggest an unrelated branch.
+ *
+ * @param {string} target - The requested (not found) branch name
+ * @param {string[]} candidates - Existing branch names to compare against
+ * @returns {string|null} The closest branch name, or null if none is close enough
+ */
+export function findClosestBranchName(target, candidates) {
+  if (!target || !Array.isArray(candidates) || candidates.length === 0) {
+    return null;
+  }
+  // Allow a larger edit budget for longer names, but cap it so unrelated
+  // branches are never suggested (e.g. a 1-char typo on a 23-char branch).
+  const maxDistance = Math.max(2, Math.floor(target.length * 0.34));
+  let best = null;
+  let bestDistance = Infinity;
+  for (const candidate of candidates) {
+    if (!candidate || candidate === target) continue;
+    const distance = levenshteinDistance(target, candidate);
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      best = candidate;
+    }
+  }
+  return bestDistance <= maxDistance ? best : null;
+}
+
+/**
+ * Check whether a branch exists in the given repository using the GitHub API.
+ * Works without cloning the repo, so it can run during early validation
+ * (before the heavy clone/spawn work) for both the CLI and the Telegram bot.
+ *
+ * @param {Object} options
+ * @param {string} options.owner - Repository owner
+ * @param {string} options.repo - Repository name
+ * @param {string} options.baseBranch - Branch name to check
+ * @param {boolean} [options.verbose=false] - Verbose logging
+ * @returns {Promise<{exists: boolean, indeterminate?: boolean}>}
+ *   - exists: true if the branch is present (or the check was inconclusive — fail open)
+ *   - indeterminate: true when a non-404 error prevented a definitive answer
+ */
+export async function checkBaseBranchExists({ owner, repo, baseBranch, verbose = false }) {
+  try {
+    const result = await ghCmdRetry(() => $`gh api repos/${owner}/${repo}/branches/${baseBranch} --jq .name`, { label: `check branch ${baseBranch}` });
+    if (result.code === 0) {
+      return { exists: true };
+    }
+    const errorOutput = (result.stderr ? result.stderr.toString() : '') + (result.stdout ? result.stdout.toString() : '');
+    if (errorOutput.includes('404') || errorOutput.includes('Not Found') || errorOutput.includes('Branch not found')) {
+      return { exists: false };
+    }
+    // Non-404 errors (network, auth, rate limit): fail open so we don't block on transient issues.
+    verbose && console.log(`[VERBOSE] Entity check: Could not verify branch '${baseBranch}': ${errorOutput.trim()}`);
+    return { exists: true, indeterminate: true };
+  } catch (e) {
+    verbose && console.log(`[VERBOSE] Entity check: Branch check error for '${baseBranch}': ${e.message}`);
+    return { exists: true, indeterminate: true };
+  }
+}
+
+/**
+ * Build a user-facing error message for a missing base branch, optionally
+ * including a "did you mean" suggestion derived from the repo's branches.
+ *
+ * @param {Object} options
+ * @param {string} options.owner
+ * @param {string} options.repo
+ * @param {string} options.baseBranch
+ * @param {boolean} [options.verbose=false]
+ * @returns {Promise<string>} The formatted error message
+ */
+export async function buildMissingBaseBranchErrorMessage({ owner, repo, baseBranch, verbose = false }) {
+  let suggestion = '';
+  try {
+    const listResult = await ghCmdRetry(() => $`gh api repos/${owner}/${repo}/branches --paginate --jq .[].name`, { label: `list branches ${owner}/${repo}` });
+    if (listResult.code === 0) {
+      const branches = listResult.stdout
+        .toString()
+        .split('\n')
+        .map(s => s.trim())
+        .filter(Boolean);
+      const closest = findClosestBranchName(baseBranch, branches);
+      if (closest) {
+        suggestion = `\n\n💡 Did you mean '${closest}'? (closest existing branch)`;
+      }
+    }
+  } catch (e) {
+    verbose && console.log(`[VERBOSE] Entity check: Could not list branches for suggestion: ${e.message}`);
+  }
+  const listCmd = `gh api repos/${owner}/${repo}/branches --paginate --jq .[].name`;
+  return `Base branch '${baseBranch}' does not exist in ${owner}/${repo}.${suggestion}\n\n💡 Please check:\n• The branch name is spelled correctly\n• The branch has not been deleted or renamed\n• Omit --base-branch to use the repository's default branch\n• List existing branches: ${listCmd}`;
+}
+
+/**
+ * Validate existence of GitHub entities (user/org, repository, base branch, issue/PR)
+ * before executing a command. Checks each level in order, failing fast at the first
+ * missing entity: user/org → repository → base branch → issue/PR.
  *
  * When autoAcceptInvite is enabled, invitations should be accepted BEFORE calling this function,
  * so that newly-accepted repos/orgs are visible to the API checks.
@@ -21,6 +148,9 @@ import { ghPrView, ghIssueView } from './github.lib.mjs';
  * @param {string} options.repo - Repository name
  * @param {number|string} [options.number] - Issue or PR number (if applicable)
  * @param {string} [options.type] - URL type: 'issue' or 'pull'
+ * @param {string} [options.baseBranch] - Custom base branch (from --base-branch/--target-branch).
+ *   When provided, its existence is verified up-front so a typo fails fast with a clear
+ *   message instead of an opaque "Branch operation failed" after cloning (issue #1959).
  * @param {boolean} [options.verbose=false] - Whether verbose logging is enabled
  * @param {boolean} [options.autoAcceptInvite=false] - Whether the caller already passed
  *   `--auto-accept-invite`. When true, the repo-404 message omits the suggestion to
@@ -28,10 +158,10 @@ import { ghPrView, ghIssueView } from './github.lib.mjs';
  * @returns {Promise<{valid: boolean, error?: string, level?: string, details?: string}>}
  *   - valid: true if all entities exist and are accessible
  *   - error: user-facing error message (when valid=false)
- *   - level: which entity level failed ('user', 'repo', 'issue', 'pull')
+ *   - level: which entity level failed ('user', 'repo', 'branch', 'issue', 'pull')
  *   - details: additional context for verbose logging
  */
-export async function validateGitHubEntityExistence({ owner, repo, number, type, verbose = false, autoAcceptInvite = false }) {
+export async function validateGitHubEntityExistence({ owner, repo, number, type, baseBranch, verbose = false, autoAcceptInvite = false }) {
   // Step 1: Check user/organization existence
   try {
     const userResult = await ghCmdRetry(() => $`gh api users/${owner} --jq .login`, { label: `check user ${owner}` });
@@ -73,6 +203,24 @@ export async function validateGitHubEntityExistence({ owner, repo, number, type,
     verbose && console.log(`[VERBOSE] Entity check: Repo check error for '${owner}/${repo}': ${e.message}`);
   }
 
+  // Step 2.5: Check base branch existence (issue #1959)
+  // When the user passes --base-branch/--target-branch, verify it exists in the
+  // canonical repository up-front. A typo (e.g. an extra trailing character) would
+  // otherwise surface only after cloning as an opaque "Branch operation failed",
+  // and was even misdiagnosed as an "empty repository". Failing here gives the
+  // same fast, explicit feedback we already provide for repo/issue/PR — in the CLI
+  // and in the GitHub comment, and BEFORE the Telegram bot starts the solve run.
+  if (baseBranch) {
+    const branchCheck = await checkBaseBranchExists({ owner, repo, baseBranch, verbose });
+    if (!branchCheck.exists) {
+      return {
+        valid: false,
+        error: await buildMissingBaseBranchErrorMessage({ owner, repo, baseBranch, verbose }),
+        level: 'branch',
+      };
+    }
+  }
+
   // Step 3: Check issue or PR existence (if number is provided)
   if (number) {
     if (type === 'pull') {

package/src/solve.branch-errors.lib.mjs

@@ -219,7 +219,7 @@ export async function handleBranchCheckoutError({ branchName, prNumber, errorOut
   }
 }
 
-export async function handleBranchCreationError({ branchName, errorOutput, tempDir, owner, repo, formatAligned, log }) {
+export async function handleBranchCreationError({ branchName, errorOutput, tempDir, owner, repo, baseBranch, branchSource, formatAligned, log }) {
   await log(`${formatAligned('❌', 'BRANCH CREATION FAILED', '')}`, { level: 'error' });
   await log('');
   await log('  🔍 What happened:');
@@ -234,6 +234,31 @@ export async function handleBranchCreationError({ branchName, errorOutput, tempD
   }
   await log('');
 
+  // Issue #1959: A failure to create the branch from origin/<baseBranch> looks
+  // identical at the git level to an empty repository ("is not a commit"). Only
+  // treat it as "empty repo" when the failing ref is NOT a custom base branch.
+  // When a custom base branch is involved and the error references it, report the
+  // real root cause: the requested base branch does not exist on the remote.
+  const errorMentionsBaseRef = baseBranch && (errorOutput.includes(`origin/${baseBranch}`) || errorOutput.includes(`'${baseBranch}'`));
+  const looksLikeMissingRef = errorOutput.includes('is not a commit') || errorOutput.includes('not a valid object name') || errorOutput.includes('unknown revision') || errorOutput.includes('did not match any');
+  const isMissingBaseBranchError = branchSource === 'custom' && errorMentionsBaseRef && looksLikeMissingRef;
+
+  if (isMissingBaseBranchError) {
+    await log('  💡 Root cause:');
+    await log(`     The requested base branch '${baseBranch}' does not exist on the remote.`);
+    await log('     A branch cannot be created from a base branch that is not there.');
+    await log('');
+    await log('  🔧 How to fix:');
+    await log('     • Check the branch name for typos (a single extra/missing character is enough)');
+    await log('     • Omit --base-branch to use the repository default branch');
+    if (owner && repo) {
+      await log(`     • List existing branches: gh api repos/${owner}/${repo}/branches --paginate --jq .[].name`);
+    } else {
+      await log('     • List existing branches: git branch -r');
+    }
+    return;
+  }
+
   // Check if this is an empty repository error (no commits to branch from)
   const isEmptyRepoError = errorOutput.includes('is not a commit') || errorOutput.includes('not a valid object name') || errorOutput.includes('unknown revision');
   if (isEmptyRepoError) {

package/src/solve.branch.lib.mjs

@@ -308,6 +308,10 @@ export async function createOrCheckoutBranch({ isContinueMode, prBranch, issueNu
   // Create a branch for the issue or checkout existing PR branch
   let branchName;
   let checkoutResult;
+  // Tracked across the create path so the error handler can report the real
+  // root cause when branch creation fails from a missing base branch (issue #1959).
+  let baseBranchForError = null;
+  let branchSourceForError = null;
 
   if (isContinueMode && prBranch) {
     // Continue mode: checkout existing PR branch
@@ -324,6 +328,8 @@ export async function createOrCheckoutBranch({ isContinueMode, prBranch, issueNu
     // Use user-specified base branch if provided, otherwise use repository default
     const baseBranch = argv.baseBranch || defaultBranch;
     const branchSource = argv.baseBranch ? 'custom' : 'default';
+    baseBranchForError = baseBranch;
+    branchSourceForError = branchSource;
 
     // Defense-in-depth: validate base branch name even if already validated at CLI parsing (issue #1482)
     const baseBranchValidation = validateBranchName(baseBranch);
@@ -391,6 +397,8 @@ export async function createOrCheckoutBranch({ isContinueMode, prBranch, issueNu
         tempDir,
         owner,
         repo,
+        baseBranch: baseBranchForError,
+        branchSource: branchSourceForError,
         formatAligned,
         log,
       });

package/src/solve.mjs

@@ -289,7 +289,7 @@ if (!hasWriteAccess) {
 }
 
 // Issue #1552: Validate entity existence AFTER permissions (cascade: user/org → repo → issue/PR)
-const entityCheck = await (await import('./github-entity-validation.lib.mjs')).validateGitHubEntityExistence({ owner, repo, number: urlNumber, type: isIssueUrl ? 'issue' : isPrUrl ? 'pull' : undefined, verbose: argv.verbose, autoAcceptInvite: !!argv.autoAcceptInvite });
+const entityCheck = await (await import('./github-entity-validation.lib.mjs')).validateGitHubEntityExistence({ owner, repo, number: urlNumber, type: isIssueUrl ? 'issue' : isPrUrl ? 'pull' : undefined, baseBranch: argv.baseBranch, verbose: argv.verbose, autoAcceptInvite: !!argv.autoAcceptInvite });
 if (!entityCheck.valid) {
   await log(`\n❌ ${entityCheck.error}\n`, { level: 'error' });
   await safeExit(1, `GitHub entity not found (${entityCheck.level})`);

package/src/telegram-bot.mjs

@@ -873,7 +873,7 @@ async function handleSolveCommand(ctx) {
   }
   // Issue #1714: read the parsed argv (default-on per #1694) instead of the raw args list,
   // so the invite hint is suppressed on the default-on path where the literal flag is absent.
-  const entityCheck = await validateGitHubEntityExistence({ owner: validation.parsed.owner, repo: validation.parsed.repo, number: validation.parsed.number, type: validation.parsed.type, verbose: VERBOSE, autoAcceptInvite: !!parsedSolveArgs?.autoAcceptInvite });
+  const entityCheck = await validateGitHubEntityExistence({ owner: validation.parsed.owner, repo: validation.parsed.repo, number: validation.parsed.number, type: validation.parsed.type, baseBranch: parsedSolveArgs?.baseBranch, verbose: VERBOSE, autoAcceptInvite: !!parsedSolveArgs?.autoAcceptInvite });
   if (!entityCheck.valid) {
     await safeReply(ctx, `❌ ${escapeMarkdown(entityCheck.error)}`, { reply_to_message_id: ctx.message.message_id });
     return;