Skip to content

[STORY] Enhanced Help System and Mode Awareness #655

New issue
New issue
Open
Open
[STORY] Enhanced Help System and Mode Awareness#655
Labels
backlogfeat:help-system-enhancementpriority-2storyUser story issue
@jsbattig

Description

@jsbattig
jsbattig
opened on Dec 31, 2025

Part of: #648

Part of: #EPIC_TBD

[Conversation Reference: "Story 7: Enhanced Help System and Mode Awareness - User Story: As a CIDX CLI user, I want clear help documentation showing which commands are available in my current mode (local/remote), so that I understand what capabilities I have without trial-and-error."]

Story Overview

Objective: Enhance the CLI help system to display mode-specific command availability, provide clear error messages when commands are unavailable, and show current mode in status output.

User Value: Users immediately understand which commands are available in their current mode (local vs remote), reducing confusion and trial-and-error. Clear guidance helps users understand how to access unavailable features.

Acceptance Criteria Summary: --help shows mode-specific groups, error messages guide users, status displays current mode with connection details.

Acceptance Criteria

AC1: Mode-Aware Help Display

Scenario: Help output shows command availability by mode

Given the user is in local mode
When the user runs "cidx --help"
Then commands are grouped by availability:
  - "Local & Remote Commands" (work in both)
  - "Local Only Commands" (marked with [local])
  - "Remote Only Commands" (marked with [remote], grayed/dimmed)
And each command shows its mode indicator
And unavailable commands show "requires remote connection" note

Technical Requirements:

  • Extend Click help formatter to show mode indicators
  • Group commands by mode availability
  • Dim/gray unavailable commands in current mode
  • Show short note for unavailable commands
  • Maintain consistent formatting with existing help

AC2: Command-Specific Help with Mode Info

Scenario: Individual command help shows mode requirements

Given the user runs "cidx scip --help"
Then the help output shows:
  - Command description
  - Mode requirement: "Available in: local, remote" or "Available in: remote only"
  - When in wrong mode: note about how to enable
And shows all options including mode-specific ones

Technical Requirements:

  • Add mode info to each command's help text
  • Show mode-specific options clearly
  • Include guidance for enabling unavailable commands
  • Maintain consistent formatting

AC3: Informative Error Messages for Mode Mismatches

Scenario: Clear error when running unavailable command

Given the user is in local mode
When the user runs a remote-only command like "cidx admin list-repos"
Then the CLI displays a helpful error:
  "Command 'admin list-repos' requires remote server connection"
  ""
  "To use this command:"
  "  1. Connect to a remote server: cidx remote connect <server>"
  "  2. Or use cidx config --remote <server> to set default"
  ""
  "Current mode: local"
And exits with status code 1

Technical Requirements:

  • Create informative error messages for mode mismatches
  • Include recovery steps in error output
  • Show current mode in error context
  • Use consistent error formatting
  • Log mode mismatch for debugging

AC4: Status Command Shows Mode and Connection

Scenario: Status displays comprehensive mode information

Given the user runs "cidx status"
Then the output includes:
  Mode: local
  -or-
  Mode: remote
    Server: https://cidx.example.com
    Connected as: alice@example.com
    Role: power_user
    Token expires: 2024-01-15 10:30:00 (in 2 hours)
    Connection: healthy
And shows available command categories in current mode

Technical Requirements:

  • Extend status command with mode section
  • Show server details for remote mode
  • Show authentication info (username, role)
  • Show token expiration warning if applicable
  • Show connection health status
  • List available command categories

AC5: Mode Indicator in Prompt/Banner

Scenario: Clear visual indicator of current mode

Given the user runs any cidx command in remote mode
Then the output includes a subtle mode indicator:
  "[remote: cidx.example.com]" in output header
And when in local mode:
  "[local]" in output header
And the indicator is consistent across all commands

Technical Requirements:

  • Add mode indicator to command output
  • Make indicator subtle but visible
  • Consistent placement across commands
  • Configurable via --no-banner or config

AC6: Documentation for Mode System

Scenario: Help includes mode system documentation

Given the user runs "cidx help modes"
Then comprehensive mode documentation is displayed:
  - What local mode means
  - What remote mode means
  - How to switch modes
  - How to connect to servers
  - How to check current mode
  - Which commands work in which mode

Technical Requirements:

  • Create 'help modes' subcommand
  • Document all aspects of mode system
  • Include examples for common workflows
  • Link to full documentation

Implementation Status

Progress Tracking:

  • Core implementation complete
  • Unit tests passing (X/Y tests)
  • Integration tests passing (X/Y tests)
  • E2E tests passing (X/Y tests)
  • Code review approved
  • Manual E2E testing completed by Claude Code
  • Documentation updated

Completion: 0/7 tasks complete (0%)

Technical Implementation Details

Component Structure

src/code_indexer/cli/
  help_formatter.py         # Custom Click help formatter
    - ModeAwareHelpFormatter class
    - format_command_modes()
    - format_mode_indicator()

  mode_errors.py            # Mode-specific error handling
    - ModeError exception class
    - format_mode_error()
    - recovery_suggestions()

src/code_indexer/cli/commands/
  help.py                   # Extended help commands
    - modes subcommand

Custom Help Formatter

class ModeAwareHelpFormatter(click.HelpFormatter):
    def __init__(self, current_mode: str):
        super().__init__()
        self.current_mode = current_mode

    def write_dl(self, rows, col_max=30, col_spacing=2):
        """Override to add mode indicators to command list"""
        formatted_rows = []
        for name, help_text in rows:
            mode_info = get_command_mode(name)
            if mode_info == 'both':
                indicator = ''
            elif mode_info == 'local':
                indicator = ' [local]'
            elif mode_info == 'remote':
                indicator = ' [remote]'

            available = is_available_in_mode(name, self.current_mode)
            if not available:
                # Dim the text for unavailable commands
                name = click.style(name, dim=True)
                help_text = click.style(f"{help_text} (requires {mode_info})", dim=True)

            formatted_rows.append((f"{name}{indicator}", help_text))

        super().write_dl(formatted_rows, col_max, col_spacing)

Mode Error Handler

class ModeError(click.ClickException):
    def __init__(self, command: str, required_mode: str, current_mode: str):
        self.command = command
        self.required_mode = required_mode
        self.current_mode = current_mode

    def format_message(self) -> str:
        return f"""
Command '{self.command}' requires {self.required_mode} mode

To use this command:
{self._get_recovery_steps()}

Current mode: {self.current_mode}
"""

    def _get_recovery_steps(self) -> str:
        if self.required_mode == 'remote':
            return """  1. Connect to a remote server: cidx remote connect <server>
  2. Or use cidx config --remote <server> to set default"""
        else:
            return """  1. Disconnect from remote: cidx remote disconnect
  2. Or run command with --local flag"""

Help Command Extension

@cli.group()
def help():
    """Extended help and documentation"""
    pass

@help.command('modes')
def help_modes():
    """Documentation about local and remote modes"""
    console = Console()
    console.print(Panel("""
[bold]CIDX Operating Modes[/bold]

[underline]Local Mode[/underline]
  - Default mode when no remote connection configured
  - Indexes stored in .code-indexer/ directory
  - All query and indexing commands available
  - No network required

[underline]Remote Mode[/underline]
  - Connected to CIDX server instance
  - Commands route to server via REST API
  - Additional commands: admin, git, files
  - Requires authentication

[underline]Switching Modes[/underline]
  Connect to remote:  cidx remote connect https://server.example.com
  Disconnect:         cidx remote disconnect
  Check status:       cidx status

[underline]Mode Indicators[/underline]
  [local]  - Command only works in local mode
  [remote] - Command only works in remote mode
  (none)   - Command works in both modes
""", title="Mode Documentation"))

Testing Requirements

Unit Test Coverage

  • Help formatter adds correct mode indicators
  • Mode error formatting is correct
  • Status shows mode information
  • Command grouping by mode works
  • Recovery suggestions are accurate

Integration Test Coverage

  • Help output changes based on current mode
  • Error messages include recovery steps
  • Status displays correct server info in remote mode
  • Mode banner appears in command output

E2E Test Coverage

  • --help shows mode indicators in both modes
  • Mode error provides actionable guidance
  • cidx help modes displays documentation
  • Status shows complete mode information

Performance Requirements

Response Time Targets

  • Help output: <100ms (no additional latency)
  • Status with mode info: <500ms
  • Error formatting: Instant

Resource Requirements

  • Memory: Minimal
  • Network: None for help, single call for status
  • CPU: Minimal

Error Handling Specifications

User-Friendly Error Messages

Command 'git status' requires remote server connection

To use this command:
  1. Connect to a remote server: cidx remote connect <server>
  2. Or use cidx config --remote <server> to set default

Current mode: local
Run 'cidx help modes' for more information about modes

Recovery Guidance

  • Always include specific commands to run
  • Show current mode for context
  • Reference help documentation
  • Provide multiple options when available

Definition of Done

Functional Completion

  • --help shows mode indicators for all commands
  • Commands grouped by mode availability
  • Mode error messages provide recovery steps
  • Status shows comprehensive mode information
  • help modes documentation is complete

Quality Validation

  • >90% test coverage achieved
  • All tests passing (unit, integration, E2E)
  • Code review approved
  • Manual testing validated with evidence
  • Help text is clear and accurate

Integration Readiness

  • Story delivers working, deployable software
  • Full vertical slice implemented
  • No broken functionality
  • Documentation complete

Story Points: Medium (polish and UX)
Priority: Medium (usability improvement)
Dependencies: Stories 2-6 (to document all commands)
Success Metric: Users understand mode system without confusion

Metadata

Metadata

Assignees

No one assigned

    Labels

    backlogfeat:help-system-enhancementpriority-2storyUser story issue

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions