@link-assistant/hive-mind 0.54.5 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @link-assistant/hive-mind
 
+## 1.0.0
+
+### Major Changes
+
+- 4e8d141: Rename `--auto-continue-on-limit-reset` to `--auto-resume-on-limit-reset` for clarity
+
+  BREAKING CHANGE: The `--auto-continue-on-limit-reset` option has been renamed to `--auto-resume-on-limit-reset`. Users must update their commands and configurations to use the new flag name.
+
+  The option is related to `--resume` for `claude` command and has an entirely different meaning from `--auto-continue` mode. This rename makes the distinction clearer and aligns the terminology with the resume functionality.
+
+  Migration:
+  - Replace `--auto-continue-on-limit-reset` with `--auto-resume-on-limit-reset` in all commands
+  - Update environment variables and configuration files accordingly
+
+## 0.54.6
+
+### Patch Changes
+
+- f734d5d: feat: Add --base-branch to /help and implement option typo suggestions
+  - Added --base-branch option to Telegram bot /help command
+  - Implemented intelligent option name suggestions using Levenshtein distance
+  - Added --base-branch to README.md solve options section
+  - Enhanced error messages with helpful suggestions for typos (e.g., --branch → --base-branch)
+
 ## 0.54.5
 
 ### Patch Changes

package/README.md

@@ -223,12 +223,12 @@ See [docs/HELM.md](./docs/HELM.md) for detailed Helm configuration options.
        --attach-logs
        --verbose
        --no-tool-check
-       --auto-continue-on-limit-reset
+       --auto-resume-on-limit-reset
      TELEGRAM_SOLVE_OVERRIDES:
        --attach-logs
        --verbose
        --no-tool-check
-       --auto-continue-on-limit-reset
+       --auto-resume-on-limit-reset
      TELEGRAM_BOT_VERBOSE: true
    "
 
@@ -250,12 +250,12 @@ See [docs/HELM.md](./docs/HELM.md) for detailed Helm configuration options.
      --attach-logs
      --verbose
      --no-tool-check
-     --auto-continue-on-limit-reset
+     --auto-resume-on-limit-reset
    )" --solve-overrides "(
      --attach-logs
      --verbose
      --no-tool-check
-     --auto-continue-on-limit-reset
+     --auto-resume-on-limit-reset
    )" --verbose
 
    # Press CTRL + A + D for detach from screen
@@ -332,10 +332,11 @@ solve <issue-url> [options]
 
 **Most frequently used options:**
 
-| Option    | Alias | Description                             | Default |
-| --------- | ----- | --------------------------------------- | ------- |
-| `--model` | `-m`  | AI model to use (sonnet, opus, haiku)   | sonnet  |
-| `--think` |       | Thinking level (low, medium, high, max) | -       |
+| Option          | Alias | Description                             | Default   |
+| --------------- | ----- | --------------------------------------- | --------- |
+| `--model`       | `-m`  | AI model to use (sonnet, opus, haiku)   | sonnet    |
+| `--think`       |       | Thinking level (low, medium, high, max) | -         |
+| `--base-branch` | `-b`  | Target branch for PR                    | (default) |
 
 **Other useful options:**
 

package/package.json

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

package/src/claude.command-builder.lib.mjs

@@ -9,7 +9,7 @@
  *
  *   (cd "/path/to/workdir" && claude --resume <session-id>)
  *
- * This is the same pattern used by --auto-continue-on-limit-reset and allows users to:
+ * This is the same pattern used by --auto-resume-on-limit-reset and allows users to:
  * 1. Resume sessions directly using Claude CLI (not through solve.mjs)
  * 2. Investigate issues interactively in the working directory
  * 3. Continue work after usage limits reset
@@ -26,7 +26,7 @@
  *
  * This generates a copy-pasteable command that users can execute directly
  * to resume a Claude session in interactive mode. This is the same pattern
- * used by --auto-continue-on-limit-reset.
+ * used by --auto-resume-on-limit-reset.
  *
  * The command includes all necessary flags to match how the original session was run:
  * - --resume <sessionId>: Resume from the specified session

package/src/hive.config.lib.mjs

@@ -202,9 +202,9 @@ export const createYargsConfig = yargsInstance => {
       description: 'Pass --auto-continue to solve for each issue (continues with existing PRs instead of creating new ones)',
       default: true,
     })
-    .option('auto-continue-on-limit-reset', {
+    .option('auto-resume-on-limit-reset', {
       type: 'boolean',
-      description: 'Automatically continue when AI tool limit resets (calculates reset time and waits). Passed to solve command.',
+      description: 'Automatically resume when AI tool limit resets (calculates reset time and waits). Passed to solve command.',
       default: false,
     })
     .option('think', {

package/src/hive.mjs

@@ -745,7 +745,7 @@ if (isDirectExecution) {
             if (argv.dryRun) args.push('--dry-run');
             if (argv.skipToolConnectionCheck || argv.toolConnectionCheck === false) args.push('--skip-tool-connection-check');
             args.push(argv.autoContinue ? '--auto-continue' : '--no-auto-continue');
-            if (argv.autoContinueOnLimitReset) args.push('--auto-continue-on-limit-reset');
+            if (argv.autoResumeOnLimitReset) args.push('--auto-resume-on-limit-reset');
             if (argv.think) args.push('--think', argv.think);
             if (argv.promptPlanSubAgent) args.push('--prompt-plan-sub-agent');
             if (!argv.sentry) args.push('--no-sentry');

package/src/option-suggestions.lib.mjs

@@ -0,0 +1,180 @@
+// Option suggestion utility for providing helpful error messages
+// when users mistype command-line option names
+
+/**
+ * Calculate Levenshtein distance between two strings
+ * Measures the minimum number of single-character edits (insertions, deletions, or substitutions)
+ * required to change one string into the other.
+ *
+ * @param {string} a - First string
+ * @param {string} b - Second string
+ * @returns {number} - Levenshtein distance
+ */
+export function calculateLevenshteinDistance(a, b) {
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+
+  const matrix = [];
+
+  // Initialize first column of matrix
+  for (let i = 0; i <= b.length; i++) {
+    matrix[i] = [i];
+  }
+
+  // Initialize first row of matrix
+  for (let j = 0; j <= a.length; j++) {
+    matrix[0][j] = j;
+  }
+
+  // Fill in the rest of the matrix
+  for (let i = 1; i <= b.length; i++) {
+    for (let j = 1; j <= a.length; j++) {
+      if (b.charAt(i - 1) === a.charAt(j - 1)) {
+        matrix[i][j] = matrix[i - 1][j - 1];
+      } else {
+        matrix[i][j] = Math.min(
+          matrix[i - 1][j - 1] + 1, // substitution
+          matrix[i][j - 1] + 1, // insertion
+          matrix[i - 1][j] + 1 // deletion
+        );
+      }
+    }
+  }
+
+  return matrix[b.length][a.length];
+}
+
+/**
+ * Find similar option names based on Levenshtein distance
+ *
+ * @param {string} unknownOption - The option name that was not recognized (e.g., "branch")
+ * @param {Object} yargsInstance - The yargs instance with defined options
+ * @param {number} maxSuggestions - Maximum number of suggestions to return (default: 3)
+ * @param {number} distanceThreshold - Maximum distance to consider for suggestions (default: 5)
+ * @returns {string[]} - Array of suggested option names, sorted by similarity
+ */
+export function findSimilarOptions(unknownOption, yargsInstance, maxSuggestions = 3, distanceThreshold = 5) {
+  // Remove leading dashes from the unknown option
+  const cleanUnknown = unknownOption.replace(/^-+/, '');
+
+  // Get all available options from yargs
+  const availableOptions = yargsInstance.getOptions();
+  const allOptions = new Set();
+
+  // Collect all option names (both long form and aliases)
+  if (availableOptions.key) {
+    // Ensure it's an array before iterating
+    const keys = Array.isArray(availableOptions.key) ? availableOptions.key : Object.keys(availableOptions.key || {});
+    keys.forEach(opt => {
+      allOptions.add(opt);
+    });
+  }
+
+  // Collect aliases
+  if (availableOptions.alias) {
+    Object.entries(availableOptions.alias).forEach(([key, aliases]) => {
+      allOptions.add(key);
+      if (Array.isArray(aliases)) {
+        aliases.forEach(alias => allOptions.add(alias));
+      } else if (aliases) {
+        // If it's not an array but exists, add it as a single alias
+        allOptions.add(String(aliases));
+      }
+    });
+  }
+
+  // Calculate distance for each option
+  const distances = [];
+  allOptions.forEach(option => {
+    const distance = calculateLevenshteinDistance(cleanUnknown, option);
+    if (distance <= distanceThreshold) {
+      // Calculate bonus score for substring matches
+      // If the unknown option is a substring of the valid option, it's likely what the user meant
+      // Check both directions: is unknown a substring of option, or is option a substring of unknown
+      const unknownInOption = option.includes(cleanUnknown);
+      const optionInUnknown = cleanUnknown.includes(option);
+
+      // Strong bonus for when user typed a word that appears in the option name
+      // e.g., "branch" appears in "base-branch"
+      const substringBonus = unknownInOption ? -10 : optionInUnknown ? -5 : 0;
+
+      // Also prioritize options with similar length (user likely tried to type the full name)
+      const lengthDiff = Math.abs(option.length - cleanUnknown.length);
+      const lengthBonus = lengthDiff < 3 ? -1 : 0;
+
+      distances.push({
+        option,
+        distance,
+        effectiveDistance: distance + substringBonus + lengthBonus,
+      });
+    }
+  });
+
+  // Sort by effective distance (closest first), then by actual distance
+  return distances
+    .sort((a, b) => {
+      if (a.effectiveDistance !== b.effectiveDistance) {
+        return a.effectiveDistance - b.effectiveDistance;
+      }
+      return a.distance - b.distance;
+    })
+    .slice(0, maxSuggestions)
+    .map(item => item.option);
+}
+
+/**
+ * Format suggestions into a user-friendly error message
+ *
+ * @param {string[]} suggestions - Array of suggested option names
+ * @returns {string} - Formatted suggestion message
+ */
+export function formatSuggestions(suggestions) {
+  if (suggestions.length === 0) {
+    return '';
+  }
+
+  if (suggestions.length === 1) {
+    return `\n\nDid you mean --${suggestions[0]}?`;
+  }
+
+  // For multiple suggestions, format them nicely
+  const formattedOptions = suggestions.map(opt => {
+    // If it's a single character, show as -x, otherwise --option-name
+    return opt.length === 1 ? `-${opt}` : `--${opt}`;
+  });
+
+  return `\n\nDid you mean one of these?\n${formattedOptions.map(opt => `  • ${opt}`).join('\n')}`;
+}
+
+/**
+ * Create an enhanced error message with suggestions for unknown arguments
+ *
+ * @param {string} originalError - The original error message from yargs
+ * @param {Object} yargsInstance - The yargs instance with defined options
+ * @returns {string} - Enhanced error message with suggestions
+ */
+export function enhanceErrorMessage(originalError, yargsInstance) {
+  // Extract the unknown option name from the error message
+  // Typical format: "Unknown argument: branch" or "Unknown arguments: branch, test"
+  const unknownMatch = originalError.match(/Unknown arguments?:\s*(.+?)(?:\s|$)/i);
+
+  if (!unknownMatch) {
+    return originalError;
+  }
+
+  // Get the first unknown argument (if multiple, focus on the first)
+  const unknownArgs = unknownMatch[1].split(',').map(arg => arg.trim());
+  const firstUnknown = unknownArgs[0];
+
+  // Find similar options
+  const suggestions = findSimilarOptions(firstUnknown, yargsInstance);
+
+  // Format the enhanced message
+  let enhancedMessage = originalError;
+
+  if (suggestions.length > 0) {
+    enhancedMessage += formatSuggestions(suggestions);
+  }
+
+  return enhancedMessage;
+}

package/src/solve.auto-continue.lib.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
-// Auto-continue module for solve command
+// Session continuation module for solve command
+// Handles session resumption, PR detection, and limit reset waiting
 // Extracted from solve.mjs to keep files under 1500 lines
 
 // Use use-m to dynamically import modules for cross-runtime compatibility
@@ -103,9 +104,9 @@ export const autoContinueWhenLimitResets = async (issueUrl, sessionId, argv, sho
       sessionId,
     ];
 
-    // Preserve auto-continue flag
-    if (argv.autoContinueOnLimitReset) {
-      resumeArgs.push('--auto-continue-on-limit-reset');
+    // Preserve auto-resume flag
+    if (argv.autoResumeOnLimitReset) {
+      resumeArgs.push('--auto-resume-on-limit-reset');
     }
 
     // Preserve other flags from original invocation

package/src/solve.config.lib.mjs

@@ -7,6 +7,8 @@
 // Note: Strict options validation is now handled by yargs built-in .strict() mode (see below)
 // This approach was adopted per issue #482 feedback to minimize custom code maintenance
 
+import { enhanceErrorMessage } from './option-suggestions.lib.mjs';
+
 // Export an initialization function that accepts 'use'
 export const initializeConfig = async use => {
   // Import yargs with specific version for hideBin support
@@ -143,9 +145,9 @@ export const createYargsConfig = yargsInstance => {
         description: 'Continue with existing PR when issue URL is provided (instead of creating new PR)',
         default: true,
       })
-      .option('auto-continue-on-limit-reset', {
+      .option('auto-resume-on-limit-reset', {
         type: 'boolean',
-        description: 'Automatically continue when AI tool limit resets (calculates reset time and waits)',
+        description: 'Automatically resume when AI tool limit resets (calculates reset time and waits)',
         default: false,
       })
       .option('auto-resume-on-errors', {
@@ -310,6 +312,7 @@ export const parseArguments = async (yargs, hideBin) => {
   // See: https://github.com/yargs/yargs/issues - .strict() only works with .parse()
 
   let argv;
+  let yargsInstance;
   try {
     // Suppress stderr output from yargs during parsing to prevent validation errors from appearing
     // This prevents "YError: Not enough arguments" from polluting stderr (issue #583)
@@ -330,7 +333,8 @@ export const parseArguments = async (yargs, hideBin) => {
     };
 
     try {
-      argv = await createYargsConfig(yargs()).parse(rawArgs);
+      yargsInstance = createYargsConfig(yargs());
+      argv = await yargsInstance.parse(rawArgs);
     } finally {
       // Always restore stderr.write
       process.stderr.write = originalStderrWrite;
@@ -345,9 +349,29 @@ export const parseArguments = async (yargs, hideBin) => {
     }
   } catch (error) {
     // Yargs throws errors for validation issues
-    // If the error is about unknown arguments (strict mode), re-throw it
-    if (error.message && error.message.includes('Unknown arguments')) {
-      throw error;
+    // If the error is about unknown arguments (strict mode), enhance it with suggestions
+    // Check if this error has already been enhanced to avoid re-processing
+    if (error.message && /Unknown argument/.test(error.message) && !error._enhanced) {
+      try {
+        // Enhance the error message with helpful suggestions
+        // Use the yargsInstance we already created, or create a new one if needed
+        const yargsWithConfig = yargsInstance || createYargsConfig(yargs());
+        const enhancedMessage = enhanceErrorMessage(error.message, yargsWithConfig);
+        const enhancedError = new Error(enhancedMessage);
+        enhancedError.name = error.name;
+        enhancedError._enhanced = true; // Mark as enhanced to prevent re-processing
+        throw enhancedError;
+      } catch (enhanceErr) {
+        // If enhancing fails, just throw the original error
+        if (global.verboseMode) {
+          console.error('[VERBOSE] Failed to enhance error message:', enhanceErr.message);
+        }
+        // If the enhance error itself is already enhanced, throw it
+        if (enhanceErr._enhanced) {
+          throw enhanceErr;
+        }
+        throw error;
+      }
     }
     // For other validation errors, show a warning in verbose mode
     if (error.message && global.verboseMode) {

package/src/solve.mjs

@@ -104,7 +104,16 @@ await log('🔧 Raw command executed:');
 await log(`   ${rawCommand}`);
 await log('');
 
-const argv = await parseArguments(yargs, hideBin);
+let argv;
+try {
+  argv = await parseArguments(yargs, hideBin);
+} catch (error) {
+  // Handle argument parsing errors with helpful messages
+  await log(`❌ ${error.message}`, { level: 'error' });
+  await log('', { level: 'error' });
+  await log('Use /help to see available options', { level: 'error' });
+  await safeExit(1, 'Invalid command-line arguments');
+}
 global.verboseMode = argv.verbose;
 
 // If user specified a custom log directory, we would need to move the log file
@@ -883,10 +892,10 @@ try {
 
   // Handle limit reached scenario
   if (limitReached) {
-    const shouldAutoContinueOnReset = argv.autoContinueOnLimitReset;
+    const shouldAutoResumeOnReset = argv.autoResumeOnLimitReset;
 
-    // If limit was reached but auto-continue-on-limit-reset is NOT enabled, fail immediately
-    if (!shouldAutoContinueOnReset) {
+    // If limit was reached but auto-resume-on-limit-reset is NOT enabled, fail immediately
+    if (!shouldAutoResumeOnReset) {
       await log('\n❌ USAGE LIMIT REACHED!');
       await log('   The AI tool has reached its usage limit.');
 
@@ -963,9 +972,9 @@ try {
         }
       }
 
-      await safeExit(1, 'Usage limit reached - use --auto-continue-on-limit-reset to wait for reset');
+      await safeExit(1, 'Usage limit reached - use --auto-resume-on-limit-reset to wait for reset');
     } else {
-      // auto-continue-on-limit-reset is enabled - attach logs and/or post waiting comment
+      // auto-resume-on-limit-reset is enabled - attach logs and/or post waiting comment
       if (prNumber && global.limitResetTime) {
         // If --attach-logs is enabled, upload logs with usage limit details
         if (shouldAttachLogs && sessionId) {
@@ -1021,7 +1030,7 @@ try {
             // Build Claude CLI resume command
             const tool = argv.tool || 'claude';
             const resumeCmd = tool === 'claude' ? buildClaudeResumeCommand({ tempDir, sessionId, model: argv.model }) : null;
-            const waitingComment = `⏳ **Usage Limit Reached - Waiting to Continue**\n\nThe AI tool has reached its usage limit. Auto-continue is enabled with \`--auto-continue-on-limit-reset\`.\n\n**Reset time:** ${global.limitResetTime}\n**Wait time:** ${formatWaitTime(waitMs)} (days:hours:minutes:seconds)\n\nThe session will automatically resume when the limit resets.\n\nSession ID: \`${sessionId}\`${resumeCmd ? `\n\nTo resume manually:\n\`\`\`bash\n${resumeCmd}\n\`\`\`` : ''}`;
+            const waitingComment = `⏳ **Usage Limit Reached - Waiting to Continue**\n\nThe AI tool has reached its usage limit. Auto-resume is enabled with \`--auto-resume-on-limit-reset\`.\n\n**Reset time:** ${global.limitResetTime}\n**Wait time:** ${formatWaitTime(waitMs)} (days:hours:minutes:seconds)\n\nThe session will automatically resume when the limit resets.\n\nSession ID: \`${sessionId}\`${resumeCmd ? `\n\nTo resume manually:\n\`\`\`bash\n${resumeCmd}\n\`\`\`` : ''}`;
 
             const commentResult = await $`gh pr comment ${prNumber} --repo ${owner}/${repo} --body ${waitingComment}`;
             if (commentResult.code === 0) {
@@ -1035,9 +1044,9 @@ try {
     }
   }
 
-  // Handle failure cases, but skip exit if limit reached with auto-continue enabled
+  // Handle failure cases, but skip exit if limit reached with auto-resume enabled
   // This allows the code to continue to showSessionSummary() where autoContinueWhenLimitResets() is called
-  const shouldSkipFailureExitForAutoLimitContinue = limitReached && argv.autoContinueOnLimitReset;
+  const shouldSkipFailureExitForAutoLimitContinue = limitReached && argv.autoResumeOnLimitReset;
 
   if (!success && !shouldSkipFailureExitForAutoLimitContinue) {
     // Show claude resume command only for --tool claude (or default) on failure

package/src/solve.repository.lib.mjs

@@ -1171,7 +1171,7 @@ export const checkoutPrBranch = async (tempDir, branchName, prForkRemote, prFork
 // Cleanup temporary directory
 export const cleanupTempDirectory = async (tempDir, argv, limitReached) => {
   // Determine if we should skip cleanup
-  const shouldKeepDirectory = !argv.autoCleanup || argv.resume || limitReached || (argv.autoContinueOnLimitReset && global.limitResetTime);
+  const shouldKeepDirectory = !argv.autoCleanup || argv.resume || limitReached || (argv.autoResumeOnLimitReset && global.limitResetTime);
 
   if (!shouldKeepDirectory) {
     try {

package/src/solve.results.lib.mjs

@@ -27,7 +27,7 @@ import { safeExit } from './exit-handler.lib.mjs';
 const githubLib = await import('./github.lib.mjs');
 const { sanitizeLogContent, attachLogToGitHub } = githubLib;
 
-// Import auto-continue functions
+// Import continuation functions (session resumption, PR detection)
 const autoContinue = await import('./solve.auto-continue.lib.mjs');
 const { autoContinueWhenLimitResets } = autoContinue;
 
@@ -376,8 +376,8 @@ export const showSessionSummary = async (sessionId, limitReached, argv, issueUrl
     if (limitReached) {
       await log('⏰ LIMIT REACHED DETECTED!');
 
-      if (argv.autoContinueOnLimitReset && global.limitResetTime) {
-        await log(`\n🔄 AUTO-CONTINUE ON LIMIT RESET ENABLED - Will resume at ${global.limitResetTime}`);
+      if (argv.autoResumeOnLimitReset && global.limitResetTime) {
+        await log(`\n🔄 AUTO-RESUME ON LIMIT RESET ENABLED - Will resume at ${global.limitResetTime}`);
         await autoContinueWhenLimitResets(issueUrl, sessionId, argv, shouldAttachLogs);
       } else {
         if (global.limitResetTime) {

package/src/telegram-bot.mjs

@@ -807,11 +807,12 @@ bot.command('help', async ctx => {
   message += '*/version* - Show bot and runtime versions\n';
   message += '*/help* - Show this help message\n\n';
   message += '⚠️ *Note:* /solve, /hive, /limits and /version commands only work in group chats.\n\n';
-  message += '🔧 *Available Options:*\n';
-  message += '• `--model <model>` - Specify AI model (sonnet, opus, haiku, haiku-3-5, haiku-3)\n';
+  message += '🔧 *Common Options:*\n';
+  message += '• `--model <model>` or `-m` - Specify AI model (sonnet, opus, haiku, haiku-3-5, haiku-3)\n';
+  message += '• `--base-branch <branch>` or `-b` - Target branch for PR (default: repo default branch)\n';
   message += '• `--think <level>` - Thinking level (low/medium/high/max)\n';
-  message += '• `--verbose` - Verbose output\n';
-  message += '• `--attach-logs` - Attach logs to PR\n';
+  message += '• `--verbose` or `-v` - Verbose output | `--attach-logs` - Attach logs to PR\n';
+  message += '\n💡 *Tip:* Many more options available. See full documentation for complete list.\n';
 
   if (allowedChats) {
     message += '\n🔒 *Restricted Mode:* This bot only accepts commands from authorized chats.\n';