[STORY] Repository Administration from CLI

[jsbattig]

Part of: #648

Part of: #EPIC_TBD

[Conversation Reference: "Story 5: Repository Administration from CLI - User Story: As a CIDX administrator using CLI, I want to manage golden repositories (add, refresh, delete) and monitor repository status, so that I can administer the server without using REST API or web interface."]

Story Overview

Objective: Enable CIDX administrators to manage golden repositories from the CLI, including adding new repos, refreshing indexes, deleting repos, and monitoring status.

User Value: Administrators can perform routine repository management tasks from the command line, enabling scripting and automation without requiring web interface access.

Acceptance Criteria Summary: Add/refresh/delete golden repos, monitor indexing status, list repositories with detailed stats, manage branches.

Acceptance Criteria

AC1: Add Golden Repository

Scenario: Register a new repository for indexing

Given the user is connected as an administrator
When the user runs "cidx admin add-repo https://github.com/org/repo.git --alias backend"
Then the repository is registered for indexing
And a background job is created for initial indexing
And the CLI displays the job ID for monitoring
And supports --branch flag for non-default branch
And supports --enable-temporal flag for git history indexing

Technical Requirements:

• Create admin command group if not exists
• Implement add-repo command
• Support --alias flag (required)
• Support --branch flag (optional, default: main/master)
• Support --enable-temporal flag
• Return job_id for async monitoring
• Validate URL format and accessibility

AC2: Refresh Golden Repository

Scenario: Trigger re-indexing of existing repository

Given the user is connected as an administrator
When the user runs "cidx admin refresh-repo backend-global"
Then a git pull is triggered on the repository
And re-indexing job is created
And CLI displays job ID for monitoring
And supports --force flag to rebuild from scratch

Technical Requirements:

• Implement refresh-repo command
• Accept repository alias as argument
• Support --force flag for complete rebuild
• Return job_id for async monitoring
• Handle repository not found error

AC3: Delete Golden Repository

Scenario: Remove repository from server

Given the user is connected as an administrator
When the user runs "cidx admin delete-repo backend-global"
Then a confirmation prompt is displayed
And upon confirmation, repository and indexes are deleted
And supports --yes flag to skip confirmation
And displays completion confirmation

Technical Requirements:

• Implement delete-repo command
• Require confirmation (--yes to skip)
• Return job_id for async deletion
• Handle repository not found error
• Show warning about irreversibility

AC4: List Repositories with Status

Scenario: View all repositories with detailed status

Given the user is connected as an administrator
When the user runs "cidx admin list-repos"
Then all golden repositories are listed
And shows for each: alias, URL, branch, last refresh, file count, index status
And supports --format table|json flag
And supports --filter flag for searching

Technical Requirements:

• Implement list-repos command
• Display Rich table by default
• Support --json output format
• Support --filter for alias/URL search
• Show index health indicators

AC5: Show Repository Statistics

Scenario: Get detailed stats for specific repository

Given the user is connected as an administrator
When the user runs "cidx admin repo-stats backend-global"
Then detailed statistics are displayed
And includes: file count, storage size, last indexed, index types available
And shows language breakdown
And shows temporal index status if applicable

Technical Requirements:

• Implement repo-stats command
• Display comprehensive statistics
• Show available index types (semantic, FTS, temporal, SCIP)
• Show language distribution
• Support --json output format

AC6: Repository Branch Management

Scenario: List and switch repository branches

Given the user is connected as an administrator
When the user runs "cidx admin repo-branches backend-global"
Then all available branches are listed
When the user runs "cidx admin switch-branch backend-global develop"
Then the repository is switched to the develop branch
And re-indexing is triggered

Technical Requirements:

• Implement repo-branches command
• Implement switch-branch command
• Show current branch indicator
• Trigger re-indexing after switch
• Handle uncommitted changes in repo

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/client/
  admin_api_client.py       # AdminAPIClient class (extend if exists)
    # Repository operations
    - add_golden_repo()
    - refresh_golden_repo()
    - remove_golden_repo()
    - list_global_repos()
    - global_repo_status()
    - get_repository_statistics()
    - get_branches()
    - switch_branch()

src/code_indexer/cli/commands/
  admin.py                  # Admin command group

Command Group Structure

@cli.group()
@requires_mode(remote=True)
@requires_role('admin')
def admin():
    """Administrative operations (requires admin role)"""
    pass

@admin.command('add-repo')
@click.argument('url')
@click.option('--alias', required=True)
@click.option('--branch', default=None)
@click.option('--enable-temporal', is_flag=True)
@click.option('--json', 'output_json', is_flag=True)
def add_repo(url, alias, branch, enable_temporal, output_json):
    """Register a new repository for indexing"""
    client = get_admin_api_client()
    result = client.add_golden_repo(url, alias, branch, enable_temporal)
    # Display job_id and instructions for monitoring

@admin.command('list-repos')
@click.option('--filter', 'filter_text')
@click.option('--json', 'output_json', is_flag=True)
def list_repos(filter_text, output_json):
    """List all golden repositories"""
    pass

API Client Pattern

class AdminAPIClient:
    def __init__(self, remote_client: CIDXRemoteAPIClient):
        self.client = remote_client

    async def add_golden_repo(
        self,
        url: str,
        alias: str,
        branch: Optional[str] = None,
        enable_temporal: bool = False
    ) -> AddRepoResult:
        response = await self.client.post(
            "/api/v1/admin/golden-repos",
            json={
                "url": url,
                "alias": alias,
                "branch": branch,
                "enable_temporal": enable_temporal
            }
        )
        return AddRepoResult(**response)

    async def list_global_repos(self) -> List[GlobalRepoInfo]:
        response = await self.client.get("/api/v1/repos/global")
        return [GlobalRepoInfo(**r) for r in response["repositories"]]

Testing Requirements

Unit Test Coverage

• AdminAPIClient.add_golden_repo() sends correct payload
• AdminAPIClient.refresh_golden_repo() handles success/error
• AdminAPIClient.remove_golden_repo() requires confirmation handling
• List repos parses response correctly
• Statistics parsing works correctly

Integration Test Coverage

• Add repo creates indexing job
• Refresh repo triggers re-indexing
• Delete repo removes all data
• List repos shows all repositories
• Stats match actual repository state

E2E Test Coverage

• Full workflow: add -> refresh -> stats -> delete
• Branch switch triggers re-indexing
• Permission denied for non-admin users
• Async job monitoring works

Performance Requirements

Response Time Targets

• List repos: <2 seconds
• Add repo (initial response): <2 seconds (job is async)
• Repo stats: <3 seconds
• Delete repo (initial response): <2 seconds (job is async)

Resource Requirements

• Memory: Minimal (results streaming)
• Network: Standard REST calls
• CPU: Minimal

Error Handling Specifications

User-Friendly Error Messages

Error: Permission denied - admin role required
Current role: power_user
Suggestion: Contact server administrator for elevated access

Error: Repository URL not accessible
URL: https://github.com/org/private-repo.git
Details: Authentication required
Suggestion: Ensure repository is accessible or provide credentials

Error: Repository alias 'backend' already exists
Suggestion: Use different alias or delete existing repository first

Error: Repository 'unknown-repo' not found
Available repositories: backend-global, frontend-global

Recovery Guidance

• Permission denied: Contact admin
• URL not accessible: Check credentials/access
• Alias exists: Use different alias
• Repo not found: List available repos

Definition of Done

Functional Completion

• Add golden repository works
• Refresh golden repository works
• Delete golden repository works with confirmation
• List repositories with status works
• Repository statistics display works
• Branch management works

Quality Validation

• >90% test coverage achieved
• All tests passing (unit, integration, E2E)
• Code review approved
• Manual testing validated with evidence
• Performance benchmarks met

Integration Readiness

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

---

Story Points: Medium (6 operations)
Priority: Medium (administrator feature)
Dependencies: Story 1 (Mode Detection)
Success Metric: Administrators can manage repos entirely from CLI