AltimateAI / AltimateAI/altimate-code

[Feature] User-friendly error handling with error codes and suggestions

Aperta
#60 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
enhancement error-handling priority:high ux
Lingua principale
TypeScript
Stelle
811
Fork
134
Merge medio
3g 2h
PR unite (30g)
50

Descrizione

## Problem

Several error paths expose raw stack traces, internal file paths, and generic messages to users. This makes the tool look unpolished and leaves users unable to self-diagnose issues.

**Examples found during testing:**

1. **Invalid model:** `altimate run --model nonexistent/model "hello"` shows:
```
ProviderModelNotFoundError: ProviderModelNotFoundError
data: { providerID: "nonexistent", modelID: "model", suggestions: [] }
at getModel (src/provider/provider.ts:1157:13)
```

2. **Bridge timeout:** Shows `Bridge timeout: sql.execute (30000ms)` with no guidance on cause or fix

3. **Bridge crash:** Shows `Python bridge failed after max restarts` — cryptic, no recovery steps

4. **Warehouse failure:** Shows `Failed to connect to warehouse 'x'. Error: Unknown error` — no distinction between auth, network, or permission errors

5. **Generic fallback:** `FormatUnknownError` in `src/cli/error.ts` returns `error.stack` for any unrecognized error

## Proposed Solution

### 1. Error taxonomy with codes

Create an error classification system:

```
ALT-1xxx: Configuration errors (missing config, invalid JSON, bad model name)
ALT-2xxx: Authentication errors (invalid API key, expired token, missing credentials)
ALT-3xxx: Bridge errors (timeout, crash, restart failure, missing Python)
ALT-4xxx: Warehouse errors (connection refused, auth failed, driver missing, query timeout)
ALT-5xxx: SQL errors (parse failure, validation error, dialect mismatch)
ALT-6xxx: Tool errors (skill not found, MCP server failure)
```

### 2. Error message format

Replace stack traces with structured user-friendly messages:

```
✗ Could not connect to warehouse 'prod_snowflake' (ALT-4001)

Cause: Authentication failed — invalid password or expired credentials

Try:
• Verify your password in altimate-code.json or env var SNOWFLAKE_PASSWORD
• Test connection outside altimate: snowsql -a -u
• Check account name format: should be "xy12345.us-east-1"

Debug: altimate --print-logs --log-level DEBUG
Docs: https://altimate-code.sh/troubleshooting#ALT-4001
```

### 3. "Did you mean?" suggestions

Already partially implemented for models via fuzzysort. Extend to:
- Provider names
- Agent names
- Warehouse connection names
- Slash commands

### Key files to modify
- `packages/altimate-code/src/cli/error.ts` — `FormatUnknownError` function (remove `error.stack` from user output)
- `packages/altimate-code/src/bridge/client.ts` — Bridge timeout/crash error messages (lines ~54, 90, 140, 156)
- `packages/altimate-code/src/provider/provider.ts` — `ProviderModelNotFoundError` and provider init errors
- `packages/altimate-code/src/tool/warehouse-test.ts` — Warehouse connection error messages
- `packages/altimate-code/src/tool/sql-execute.ts` — SQL execution error messages
- All tool files in `packages/altimate-code/src/tool/` — Standardize error output format

### Industry patterns
- **Aider:** Never shows stack traces. Typo → suggests alternatives. Missing credential → lists exact env vars
- **Goose:** Categorizes errors (auth=401, rate-limit=429, server=500) with per-category retry behavior
- **Rust/Cargo:** Error codes with `--explain E0308` for detailed docs
- **Fuchsia CLI guidelines:** Unique error identifier (e.g., `fi-0123`) for searchable error catalog

### Acceptance criteria
- [ ] No stack traces in default user-facing output
- [ ] Stack traces logged to `~/.local/share/altimate-code/log/` and shown with `--print-logs --log-level DEBUG`
- [ ] Error codes follow `ALT-XXXX` format
- [ ] Bridge errors classified: timeout vs crash vs missing dependency vs auth
- [ ] Warehouse errors classified: connection refused vs auth failed vs driver missing
- [ ] Invalid model/provider names suggest alternatives via fuzzy matching
- [ ] Error messages include actionable "Try:" suggestions

Guida per i contributori

Apri la guida per i contributori

Valutazione

Questa issue non è ancora stata valutata.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.