limitless-cli 1.0.0

A beginner-friendly environment diagnostic tool
Documentation
# Architecture

Limitless is a single Rust workspace-free crate (`limitless-cli`) that ships
one binary, `limit`, alongside a public library facade (`src/lib.rs`).

## Data flow

Every command follows the same pipeline:

```text
detect stack ──▶ run diagnostics ──▶ build snapshot ──▶ translate errors
    │                 │                    │                    │
    │                 │              HealthScore         Mentor messages
    │                 │                    │                    │
    └─────────────────┴────────▶ render (tui / planetary / plain)
                                         │
                                     auto-fix / arcade / badges
```

## Core types (`models.rs`)

- `ProjectStack` — detected stack (Node / Python / Rust / Docker / Unknown).
- `CheckStatus` — Pass / Warn / Fail, the vocabulary of every check.
- `DiagnosticResult` — one named check's status, message, and remediation.
- `EnvironmentState` — a full snapshot: stack + runtime + diagnostics +
  health score. Serializable for caching.
- `HealthScore` — 0–100% from Pass/Warn/Fail counts; Healthy ≥ 85,
  Caution ≥ 60, else Critical.
- `MentorMessage` — severity + plain_english + technical_detail +
  suggested_action.
- `ArcadeStats` — lifetime counters that drive the badge engine.

## Module responsibilities

| Module | Responsibility |
|---|---|
| `stack_detector` | Marker-file detection with priority Node → Python → Rust → Docker |
| `diagnostics` | Runs named checks (some in parallel with per-check timeouts), folds results into an `EnvironmentState` |
| `runtime_validator` | `node --version`, etc., compared against the version requirements of the detected stack |
| `env_auditor` | `.env` / `.env.example` presence audit |
| `port_watcher` | Parses `netstat` / `lsof` output; finds what holds `DEFAULT_DEV_PORTS` |
| `dependency_checker` | Manifest + lockfile health without assuming a package manager is installed |
| `translator` | Needle-based lookup that maps cryptic errors to `MentorMessage`s |
| `message_formatter` | Renders mentor advice as a fixed-width box (ANSI and plain twins) |
| `tui` | Frame-drawn dashboard; `render_dashboard` / `render_dashboard_plain` |
| `progress` | Spinner + progress-bar animation on a background task |
| `fixes` | One `Fix` per action, executed by `execute_fix` with verify-and-rollback |
| `auto_fix` | Orders `build_auto_fixes`, applies them, produces a `FixReport` |
| `planetary` | The same state rendered as a mission-control report |
| `arcade` | SyntaxBreaker typing game + `ArcadeScoreboard` persistence |
| `achievements` | `BADGES` registry, `check_badges`, `AchievementProgress` |
| `config` | `PersistenceManager` for config/stats/cache under `~/.limitless/` |

## Rendering twins

Every renderer that ships user-facing text has a **plain twin**
(`*_plain`) that emits zero ANSI escapes. The colored variants honor
`colored::control::set_override`, which main.rs drives from the
`--color`/`--no-color` flags and `~/.limitless/config.json`.

## Concurrency

`run_checks_parallel` spawns blocking checks on a dedicated runtime with a
per-check timeout; a hung check becomes a `CheckStatus::Fail` diagnostic
instead of freezing the CLI. `progress` runs an animation task stopped by the
caller through `Progress::finish`/`abort`.

## Persistence (`config.rs`)

All state lives under `~/.limitless/`: `config.json` (preferences),
`stats.json` (lifetime `ArcadeStats`), `cache.json` (last snapshot + unix
timestamp for a 5-minute TTL). Writes go through a temp-file + rename so a
crash never corrupts a live file. Tests use `PersistenceManager::at_dir` to
keep the real home directory untouched.

## Testing strategy

- Each module has `#[cfg(test)] mod tests` for hermetic unit tests.
- `tests/fixtures/` holds mock projects (node, python, rust, docker,
  multi-stack, unknown, env_sample) used by unit and integration tests,
  located via `env!("CARGO_MANIFEST_DIR")`.
- `tests/integration_test.rs` exercises the public API end-to-end.
- Tests never hit the network, never kill real processes, and never touch
  `~/.limitless`.

## Cross-compilation note

`.cargo/config.toml` pins the `x86_64-pc-windows-gnu` target and a mingw
`gcc` linker on Windows. CI installs the matching MSYS2 toolchain on the
Windows runner and removes the config on Linux/macOS runners so they build
natively.