[STORY] User and Job Management from CLI

[jsbattig]

Part of: #648

Part of: #EPIC_TBD

[Conversation Reference: "Story 6: User and Job Management from CLI - User Story: As a CIDX administrator using CLI, I want to manage user accounts and monitor background jobs, so that I can perform administrative tasks without switching to web interface or API tools."]

Story Overview

Objective: Enable CIDX administrators to manage user accounts and monitor/control background jobs from the CLI, providing complete administrative capability without web interface.

User Value: Administrators can script and automate user management and job monitoring, integrate with existing automation tools, and perform administrative tasks remotely via SSH.

Acceptance Criteria Summary: User CRUD operations (create/list/show/update/delete/change-password), Job management (list/status/cancel/stats/cleanup).

Acceptance Criteria

AC1: Create User Account

Scenario: Create new user with specified role

Given the user is connected as an administrator
When the user runs "cidx admin create-user alice --role power_user --password 'secure123'"
Then a new user account is created
And the CLI displays the created user info
And supports --api-key flag to generate initial API key
And supports reading password from stdin for security

Technical Requirements:

• Implement create-user command under admin group
• Support --role flag (admin, power_user, normal_user)
• Support --password flag or stdin input
• Support --api-key flag to generate API key
• Validate password strength if server requires
• Return user details including generated API key if requested

AC2: List Users

Scenario: View all user accounts

Given the user is connected as an administrator
When the user runs "cidx admin list-users"
Then all user accounts are listed
And shows for each: username, role, created_at, last_login
And supports --role filter to show only specific role
And supports --json output format

Technical Requirements:

• Implement list-users command
• Display Rich table by default
• Support --role filter
• Support --json output format
• Show total user count

AC3: Show User Details

Scenario: View detailed information for specific user

Given the user is connected as an administrator
When the user runs "cidx admin show-user alice"
Then detailed user information is displayed
And shows: username, role, created_at, last_login, API keys (masked), activated repos
And supports --json output format

Technical Requirements:

• Implement show-user command
• Display comprehensive user details
• Mask API key values (show last 4 chars only)
• Show user's activated repositories
• Support --json output format

AC4: Update User Role

Scenario: Change user's role

Given the user is connected as an administrator
When the user runs "cidx admin update-user alice --role admin"
Then the user's role is updated
And confirmation is displayed
And prevents demoting last admin

Technical Requirements:

• Implement update-user command
• Support --role flag for role changes
• Validate role is valid value
• Prevent demoting last admin
• Display update confirmation

AC5: Delete User Account

Scenario: Remove user account

Given the user is connected as an administrator
When the user runs "cidx admin delete-user alice"
Then a confirmation prompt is displayed
And upon confirmation, user is deleted
And all user's activated repositories are deactivated
And supports --yes flag to skip confirmation

Technical Requirements:

• Implement delete-user command
• Require confirmation (--yes to skip)
• Handle cleanup of user's resources
• Prevent deleting self
• Prevent deleting last admin

AC6: Change User Password

Scenario: Reset user's password

Given the user is connected as an administrator
When the user runs "cidx admin change-password alice --password 'newpassword'"
Then the user's password is changed
And supports reading password from stdin
And validates password strength

Technical Requirements:

• Implement change-password command
• Support --password flag or stdin
• Validate password strength
• Force password change on next login (optional flag)

AC7: List Background Jobs

Scenario: View all background jobs with status

Given the user is connected as an administrator
When the user runs "cidx admin list-jobs"
Then all background jobs are listed
And shows: job_id, type, status, progress, started_at, repository
And supports --status filter (pending, running, completed, failed)
And supports --limit flag for pagination

Technical Requirements:

• Implement list-jobs command
• Display Rich table by default
• Support --status filter
• Support --limit and --offset for pagination
• Support --json output format
• Show progress percentage where applicable

AC8: Show Job Details

Scenario: View detailed status of specific job

Given the user is connected as an administrator
When the user runs "cidx admin job-status <job_id>"
Then detailed job information is displayed
And shows: status, progress, started_at, completed_at, error details if failed
And supports --follow flag to stream updates

Technical Requirements:

• Implement job-status command
• Display comprehensive job details
• Show error information for failed jobs
• Support --follow for live updates
• Support --json output format

AC9: Cancel Running Job

Scenario: Cancel a running background job

Given the user is connected as an administrator
When the user runs "cidx admin cancel-job <job_id>"
Then the job is marked for cancellation
And confirmation is displayed
And job status changes to 'cancelled'

Technical Requirements:

• Implement cancel-job command
• Handle already-completed jobs gracefully
• Display cancellation confirmation
• Support --yes flag to skip confirmation

AC10: Job Statistics and Cleanup

Scenario: View job statistics and cleanup old jobs

Given the user is connected as an administrator
When the user runs "cidx admin job-stats"
Then job statistics are displayed: total, by status, by type
When the user runs "cidx admin cleanup-jobs --older-than 7d"
Then completed/failed jobs older than 7 days are removed

Technical Requirements:

• Implement job-stats command
• Implement cleanup-jobs command
• Support --older-than flag with duration format
• Display cleanup summary
• Require confirmation for cleanup

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)
    # User operations
    - create_user()
    - list_users()
    - get_user()
    - update_user()
    - delete_user()
    - change_password()
    # Job operations
    - list_jobs()
    - get_job_status()
    - cancel_job()
    - get_job_statistics()
    - cleanup_jobs()

src/code_indexer/cli/commands/
  admin.py                  # Extend with user/job subgroups

Command Group Structure

@admin.group()
def users():
    """User management commands"""
    pass

@users.command('create')
@click.argument('username')
@click.option('--role', type=click.Choice(['admin', 'power_user', 'normal_user']), default='normal_user')
@click.option('--password', prompt=True, hide_input=True, confirmation_prompt=True)
@click.option('--api-key', is_flag=True, help='Generate initial API key')
@click.option('--json', 'output_json', is_flag=True)
def create_user(username, role, password, api_key, output_json):
    """Create a new user account"""
    pass

@admin.group()
def jobs():
    """Background job management commands"""
    pass

@jobs.command('list')
@click.option('--status', type=click.Choice(['pending', 'running', 'completed', 'failed', 'cancelled']))
@click.option('--limit', default=50)
@click.option('--json', 'output_json', is_flag=True)
def list_jobs(status, limit, output_json):
    """List background jobs"""
    pass

@jobs.command('status')
@click.argument('job_id')
@click.option('--follow', '-f', is_flag=True)
@click.option('--json', 'output_json', is_flag=True)
def job_status(job_id, follow, output_json):
    """Show detailed job status"""
    pass

Testing Requirements

Unit Test Coverage

• User CRUD operations send correct payloads
• Password masking works in output
• Job listing parses response correctly
• Job status polling works with --follow
• Role validation works correctly

Integration Test Coverage

• Create user appears in list
• Update user role persists
• Delete user removes all resources
• Job status reflects actual state
• Cancel job stops execution

E2E Test Coverage

• Full user lifecycle: create -> update -> delete
• Job monitoring: start job -> monitor -> complete
• Job cleanup removes old jobs
• Permission denied for non-admin

Performance Requirements

Response Time Targets

• List users: <2 seconds
• List jobs: <2 seconds (with pagination)
• User CRUD: <1 second each
• Job status: <1 second

Resource Requirements

• Memory: Minimal
• Network: Standard REST calls
• CPU: Minimal

Error Handling Specifications

User-Friendly Error Messages

Error: User 'alice' already exists
Suggestion: Use different username or update existing user

Error: Cannot delete last administrator
Details: At least one admin account is required
Suggestion: Create another admin before deleting this one

Error: Job not found: abc123
Suggestion: Run 'cidx admin list-jobs' to see available jobs

Error: Cannot cancel completed job
Job status: completed
Suggestion: Job has already finished execution

Error: Weak password
Requirements: Minimum 8 characters, 1 uppercase, 1 number

Recovery Guidance

• User exists: Suggest update or different name
• Last admin: Create another admin first
• Job not found: List available jobs
• Weak password: Show requirements

Definition of Done

Functional Completion

• User create/list/show/update/delete works
• Password change works
• Job list/status/cancel works
• Job statistics and cleanup work

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: Large (10 operations)
Priority: Medium (administrator feature)
Dependencies: Story 1 (Mode Detection)
Success Metric: Complete admin operations available from CLI