[Feature] Add workspace doctor command for health diagnostics and autofix

[Copilot]

Description

Adds extralit workspaces doctor CLI command to diagnose and autofix workspace infrastructure issues, particularly S3 bucket configurations that can break after environment changes or manual deletions.

Related Tickets & Documents

Closes #

What type of PR is this? (check all applicable)

• Refactor
• Feature
• Bug Fix
• Optimization
• Documentation Update

Implementation

Server API

• Endpoint: POST /api/v1/workspaces/{workspace_id}/doctor?autofix=true
• Health Checks:
  • S3 bucket existence (autofix: creates bucket with versioning)
  • Bucket versioning policy (informational)
  • RQ worker pool connectivity (informational)
  • Elasticsearch dataset indexes (informational)

Client & CLI

• WorkspacesAPI.doctor(workspace_id, autofix=True) method
• CLI command with rich table output showing check results, status emojis, and fix indicators

Usage

# Auto-fix mode (default)
extralit workspaces --name my-workspace doctor

# Diagnostic only
extralit workspaces --name my-workspace doctor --no-autofix

result = client.workspaces.doctor(workspace.id, autofix=True)
for check in result.checks:
    print(f"{check.check_name}: {check.status} - {check.message}")

Steps to QA

1. Create a workspace, manually delete its S3 bucket
2. Run extralit workspaces --name test doctor
3. Verify bucket is recreated and all checks display properly
4. Run --no-autofix variant, confirm no autofix occurs

Added/updated tests?

• Yes
• Unit tests: 5 test cases covering healthy/unhealthy scenarios, auth, autofix behavior
• Integration tests: CLI command execution with both flags

Added/updated documentations?

• Yes
• CLI guide: usage examples and check descriptions
• Workspace guide: programmatic API usage

Checklist

• I have added relevant notes to the CHANGELOG.md file (See https://keepachangelog.com/)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Create a extralit workspaces doctor command to autofix missing bucket issues</issue_title>
<issue_description>When a workspace is created, extralit-server automatically creates a S3 bucket (or equivalent with LocalFileClient), but the bucket may be deleted or has other environments env vars broken. Creating a extralit workspaces --name {ws_name} doctor CLI command can help users check that the S3 bucket exists for the workspace, and if it doesn't exist, then autofix it by creating one (provided the user's role has permission).

It may also display other useful status information, though these checks doesn't need autofix yet:

• The s3 bucket has appropriate proper file versioning policy
• Show that the connection to RQ worker pool from extralit_server.jobs.queues import DEFAULT_QUEUE works
• The workspace's datasets has elasticsearch indexes (only do this task if straightforward)

You'll need to modify files at extralit/src/extralit/cli (see existing patterns using Typer CLI) to call APIs defined in extralit-server/src/extralit_server/api/handlers/v1/files.py and extralit-server/src/extralit_server/api/handlers/v1/workspaces.py</issue_description>

Comments on the Issue (you are @copilot in this section)

Custom agent used: Python Backend and SDK Developer
Implements high-quality, maintainable code following clean architecture principles with pragmatic documentation

• Fixes Create a extralit workspaces doctor command to autofix missing bucket issues #163

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Sparshr04]

Thanks @JonnyTran for kicking off this feature!

I tested the extralit workspaces doctor command locally and found one integration issue on the client side.

Originally in the the CLI was calling client.workspaces.doctor(...) but, client.workspaces (fromextralit/src/extralit/client/resources.py) is the high-level resource manager and does not expose doctor(). The actual low-level API wrapper (which does include .doctor() and .get_by_name()) is located at client.api.workspaces (at extralit/src/extralit/_api/_workspaces.py)

So I switched the CLI to use the low-level WorkspacesAPI, which does include .get_by_name() and .doctor() updating the extralit/src/extralit/cli/workspaces/__main__.py file.

Essentially I replaced high-level resource manager with low-level WorkspacesAPI

api = client.api.workspaces
workspace_obj = api.get_by_name(workspace.name)
doctor_response = api.doctor(workspace_obj.id, autofix=autofix)

[Sparshr04]

Hey @JonnyTran, thanks for your patience on this one! The debugging took way longer than expected.

Fixed failing integration tests for the workspaces doctor command by switching from subprocess-based testing to Typer's CliRunner.

I mainly had to tweak the extralit/tests/integration/conftest.py file and the extralit/tests/integration/test_cli_commands.py file.

1. Used CliRunner instead of run_cli_command() to keep tests in-process where httpx_mock works
2. Added proper mock responses for /api/v1/me/workspaces endpoint with required fields (inserted_at, updated_at)
3. Added workspace_id to doctor endpoint mock responses to match Pydantic validation requirements

Both test variants --autofix and --no-autofix now pass 🚀