feat: add doctor command for CLI diagnostics

[francoischalifour]

Context

The CLI previously had no single command for diagnosing its local configuration, credential backends, and connectivity to Altertable’s two API planes.

Troubleshooting required combining several commands while understanding:

• which profile was selected and why;
• whether credentials came from environment variables, a file, or macOS Keychain;
• the distinction between management and lakehouse authentication;
• whether failures came from configuration, credential storage, authentication, transport, or an incompatible API response;
• which existing operations could refresh or provision credentials as a side effect.

Command-reference generation also wrote files during verification. Although drift was detected, the workflow mixed intentional regeneration with CI validation.

Solution

Add altertable doctor, a read-only diagnostic command with human-readable and structured JSON output.

The command evaluates seven checks:

1. CLI version and runtime
2. Selected profile and endpoints
3. Secret store accessibility
4. Management credentials
5. Management API identity
6. Lakehouse credentials
7. Lakehouse API query execution

Checks declare their dependencies explicitly. Independent management and lakehouse branches run concurrently, while dependent checks are skipped with a clear blocker when an earlier check fails.

altertable doctor
altertable doctor --offline
altertable --json doctor

Preview

Success

1 failure

Read-only behavior

Doctor uses a dedicated read-only execution context and disables authentication recovery for its HTTP probes.

It does not:

• create or modify profiles;
• refresh OAuth tokens;
• provision lakehouse credentials;
• recover from authentication failures by writing new credentials;
• run the automatic CLI update check.

--offline suppresses both Altertable API probes while retaining the local profile and credential checks.

A completed diagnostic exits successfully even when the report is unhealthy. Automation should inspect the JSON healthy field and individual findings.

Diagnostic ownership

Profile configuration and secret-backed authentication inspection are now separate operations.

This ensures:

• profile parsing failures belong to the Profile check;
• unsafe credential-file permissions belong to the Secret store check;
• macOS Keychain lookup failures are distinguished from missing entries;
• management and lakehouse authentication checks consume the credential state established by the Secret store check;
• stale active_profile references are reported instead of silently falling back to default.

API validation and error reporting

Successful HTTP status codes are not sufficient to mark an API healthy.

The management probe validates /whoami against the generated OpenAPI response shape. The lakehouse probe parses the NDJSON response and verifies that SELECT 1 returned the numeric value 1.

Failed findings preserve structured CLI error information, including:

• stable error code;
• HTTP status;
• parsed server details;
• remediation guidance;
• check duration.

Output

Human output presents an aligned diagnostic report with status icons, actionable remediation, and a final health summary.

JSON output includes:

• the selected profile;
• overall health;
• pass, warning, failure, and skipped counts;
• ordered check results;
• structured error and endpoint details;
• individual durations.

Generated artifacts

Generated-artifact handling now has explicit write and check modes shared by:

• OpenAPI type generation;
• OpenAPI operation-index generation;
• COMMANDS.md generation.

New scripts provide intentional regeneration and non-mutating verification:

cd cli
bun run generate:commands
bun run generate:check

The repository verification script now checks generated content without rewriting the working tree. COMMANDS.md remains generated from command metadata and includes the new doctor command.

Testing

Coverage includes:

• healthy and unhealthy doctor reports;
• offline operation without materializing the default profile;
• management and lakehouse probes;
• malformed successful API responses;
• structured HTTP error details;
• unsafe credential-file attribution;
• Keychain lookup failures;
• stale active-profile references;
• dependency blocking and intentional skips;
• concurrent independent checks with stable output ordering;
• human and JSON rendering;
• updater suppression;
• non-mutating generated-artifact checks;
• black-box CLI behavior.

[albert20260301]

Required: Please add an [Unreleased] / Added changelog entry for altertable doctor before merge. This is a user-facing feature with new human and JSON output, and the repository’s release policy requires it to be documented alongside the README and command reference.

[leonkenneth]

I don't follow how this makes it RO

[francoischalifour]

Name is misleading, it just means that it doesn't mutate anything, so it's safe to call whenever. I did a pass on naming and renamed that one resolveProfileReference().