limitless-cli 1.0.0

A beginner-friendly environment diagnostic tool
Documentation
<p align="center">
  <img src="assets/logo.svg" alt="Limitless CLI Logo" width="220" />
</p>

<h1 align="center">๐Ÿš€ Limitless CLI</h1>

<p align="center">
  <b>The Intelligent, Stack-Aware Development Environment Pre-flight Engine & Auto-Repair Suite</b>
</p>

<p align="center">
  <a href="https://crates.io/crates/limitless-cli"><img src="https://img.shields.io/badge/crates.io-v1.0.0-orange.svg?style=for-the-badge&logo=rust" alt="Crates.io"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge" alt="License"></a>
  <a href="https://www.rust-lang.org"><img src="https://img.shields.io/badge/rust-1.75%2B-brightgreen.svg?style=for-the-badge&logo=rust" alt="Rust Version"></a>
  <a href="#"><img src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg?style=for-the-badge" alt="Platforms"></a>
</p>

<p align="center">
  <a href="#-why-limitless">Why Limitless?</a> โ€ข
  <a href="#-feature-showcase">Feature Showcase</a> โ€ข
  <a href="#-installation">Installation</a> โ€ข
  <a href="#-command-cheatsheet">Command Cheatsheet</a> โ€ข
  <a href="#-stack-detection-matrix">Stack Matrix</a> โ€ข
  <a href="#-gamification--badges">Badges</a> โ€ข
  <a href="#-configuration">Configuration</a>
</p>

---

## ๐Ÿ’ก Why Limitless?

Ever spent 45 minutes debugging why your app won't launch, only to realize:
* ๐Ÿ”ด **Port 5432 or 27017** was silently hijacked by a ghost PostgreSQL/MongoDB process?
* ๐Ÿ”ด Your local **`.env`** file was missing required keys present in `.env.example`?
* ๐Ÿ”ด **`node_modules`** was out of sync with `package-lock.json` or `pnpm-lock.yaml`?
* ๐Ÿ”ด Your system **`PATH`** contained 13 duplicate folders and 4 broken paths?

**Limitless CLI (`limit`)** runs **19+ concurrent pre-flight checks in milliseconds**, scores your environment health (0โ€“100%), translates cryptic OS errors into plain English mentor advice, and automatically applies fixes safely.

```text
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ ๐Ÿš€ LIMITLESS v1.0.0 โ€” SYSTEM ENVIRONMENT PRE-FLIGHT                      โ”‚
โ”‚ โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ โ”‚
โ”‚                                                                          โ”‚
โ”‚ [โœ“] Env Audit: .env file matches .env.example                            โ”‚
โ”‚ [โœ“] Dependency audit: manifest and lock file are present                 โ”‚
โ”‚ [โœ“] Runtime Check: Node v22.23.2 meets recommended version (>= 18.0.0)   โ”‚
โ”‚ [โœ–] Port 5432: Port 5432 is occupied by PID 6460 (postgres)              โ”‚
โ”‚ [โœ–] Port 27017: Port 27017 is occupied by PID 4620 (mongod)              โ”‚
โ”‚ [โœ“] Tool rustc: rustc 1.98.0                                             โ”‚
โ”‚ [โœ“] Tool node: node v22.23.2                                             โ”‚
โ”‚ [โœ“] Tool go: go version go1.26.3 windows/amd64                           โ”‚
โ”‚                                                                          โ”‚
โ”‚ Health Score: 68% [โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘]                                 โ”‚
โ”‚ Status: CAUTION                                                          โ”‚
โ”‚                                                                          โ”‚
โ”‚ ๐Ÿ’ก MENTOR NOTE:                                                          โ”‚
โ”‚     No default editor is configured, so command-line tools may pick a   โ”‚
โ”‚     random one or fail. It's like having mail delivered but no default  โ”‚
โ”‚     address on file.                                                     โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
```

---

## โœจ Feature Showcase

### 1. ๐Ÿ” Full Environment Pre-Flight Audit (`limit`)
Scans runtime versions, process tables, lockfiles, proxy configurations, and PATH hygiene simultaneously using Rust's async Tokio worker threads.

### 2. ๐Ÿ›ก๏ธ Pre-Flight Dev Server Launcher (`limit dev`)
Performs a deep audit before starting your development server. If health is 100%, it automatically spawns the project's dev server (`npm run dev`, `cargo run`, `python main.py`, `go run .`, etc.). If unhealthy, it halts launch to prevent infinite crash loops and highlights the fix.

### 3. ๐Ÿ”ง Automated & Interactive Fix Suite (`limit fix`)
* **Interactive Mode (`limit fix`):** Prompts for approval step-by-step before modifying system state.
* **Automated Mode (`limit fix --all`):** Terminates port-blocking PIDs, generates `.env` files from `.env.example`, repairs missing `.gitignore`/`.editorconfig`, and installs out-of-sync dependencies. Includes permission guards for elevated Windows/Unix processes.

### 4. ๐ŸŒŒ Planetary Mission Control Mode (`limit orbit`)
Renders environment diagnostics inside a retro sci-fi space station telemetry dashboard:

```text
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ ๐ŸŒŒ PLANETARY MODE โ€” MISSION CONTROL REPORT               โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚                                                          โ”‚
โ”‚ ๐Ÿ›ก๏ธ Shield Generator (.env)                               โ”‚
โ”‚     [โœ“] Status: OPERATIONAL                              โ”‚
โ”‚                                                          โ”‚
โ”‚ ๐Ÿ”ง System Components Bay (node_modules/)                 โ”‚
โ”‚     [โš ] Status: MINOR ALERT                              โ”‚
โ”‚     โ†’ Run `npm list` to check dependency health         โ”‚
โ”‚                                                          โ”‚
โ”‚ Mission Health: 68% [โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘]               โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
```

### 5. โš”๏ธ SyntaxBreaker Arcade Game (`limit arcade`)
A built-in terminal typing arcade game featuring developer code snippets, real-time WPM/accuracy tracking, live timers, and persistent top-5 high scores saved to disk.

```text
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ โš”๏ธ SYNTAXBREAKER ARCADE GAME                             โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚ Type the code snippet:                                   โ”‚
โ”‚ function hello() { }                                     โ”‚
โ”‚                                                          โ”‚
โ”‚ Your input: function hello()_                            โ”‚
โ”‚                                                          โ”‚
โ”‚ Score: 120  |  Time: 45s  |  WPM: 64                     โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
```

---

## โšก Installation

### Option A: Via Cargo (Recommended)

```bash
# Build and install globally from source
cargo install --path .

# Or install directly from Crates.io
cargo install limitless-cli
```

### Option B: Build from Source

```bash
git clone https://github.com/limitless-cli/limitless.git
cd limitless
cargo build --release
```

*For platform-specific installation scripts (Homebrew, APT, Chocolatey), see [`docs/INSTALLATION.md`](docs/INSTALLATION.md).*

---

## ๐Ÿ“– Command Cheatsheet

```bash
limit             # Run full environment audit
limit dev         # Pre-flight check + dev server launch (when healthy)
limit fix --all   # Automatically resolve all detected issues
limit orbit       # Sci-fi mission-control diagnostic dashboard
limit arcade      # Launch SyntaxBreaker typing minigame
limit --help      # Render built-in terminal documentation
```

### Global Execution Flags

| Flag | Description |
| :--- | :--- |
| **`--fast`** / **`-f`** | Skips animations and spinners for instant result rendering. |
| **`--verbose`** / **`-v`** | Outputs technical telemetry behind every check, including full error stack traces. |
| **`--no-color`** | Disables ANSI color output (useful for plain-text logging and CI/CD pipelines). |
| **`--color`** | Forces ANSI color output regardless of environment defaults. |

---

## ๐Ÿ› ๏ธ Stack Auto-Detection Matrix

Limitless automatically detects your project stack by probing workspace manifests in priority order:

| Priority | Stack | Project Markers | Auto-Launched Dev Command (`limit dev`) |
| :---: | :--- | :--- | :--- |
| 1 | **Node.js** | `package.json`, `pnpm-lock.yaml`, `yarn.lock` | `pnpm dev` / `yarn dev` / `npm run dev` |
| 2 | **Python** | `requirements.txt`, `manage.py`, `main.py`, `app.py` | `python manage.py runserver` / `uvicorn main:app` / `python app.py` |
| 3 | **Rust** | `Cargo.toml` | `cargo run` |
| 4 | **Go** | `go.mod` | `go run .` |
| 5 | **Java** | `build.gradle`, `pom.xml` | `./gradlew bootRun` / `mvn spring-boot:run` |
| 6 | **Docker** | `Dockerfile`, `docker-compose.yml` | Secondary stack audit & port verification |

---

## ๐Ÿ† Gamification & Badges

As you run diagnostics and repair your workspace, Limitless awards persistent developer badges saved locally to `~/.limitless/`:

* ๐Ÿ›ก๏ธ **Port Whisperer:** Successfully freed a blocked port holding up your server.
* โšก **Env Master:** Fixed or generated missing `.env` configurations.
* ๐Ÿ•น๏ธ **Arcade Champion:** Achieved a top-5 high score in SyntaxBreaker Arcade.
* ๐Ÿฆ‰ **Night Owl:** Executed diagnostics between 1:00 AM and 4:00 AM.
* ๐Ÿš€ **Speed Runner:** Achieved a 100% environment health score on the first scan.

---

## โš™๏ธ Configuration (`~/.limitless/config.json`)

Customize Limitless behavior globally by modifying `~/.limitless/config.json`:

```json
{
  "preferred_stack": null,
  "auto_approve_safe_fixes": false,
  "color_enabled": true,
  "animation_enabled": true,
  "verbose_mode": false
}
```

---

## ๐Ÿ“š Complete Documentation Index

| Document | Description |
| :--- | :--- |
| ๐Ÿ“ฅ **[INSTALLATION.md]docs/INSTALLATION.md** | Step-by-step setup for Windows, macOS, Ubuntu/Debian, and Homebrew. |
| ๐Ÿ’ก **[USAGE.md]docs/USAGE.md** | Full command reference, flag combinations, and CLI usage patterns. |
| ๐Ÿ—๏ธ **[ARCHITECTURE.md]docs/ARCHITECTURE.md** | Technical deep-dive into async Tokio runtime, diagnostic engine, and TUI renderer. |
| ๐Ÿค **[CONTRIBUTING.md]docs/CONTRIBUTING.md** | Guidelines for adding new stack detectors, checks, and arcade snippets. |
| โ“ **[TROUBLESHOOTING.md]docs/TROUBLESHOOTING.md** | FAQ covering elevated OS permissions, broken PATH entries, and port conflicts. |

---

## ๐Ÿงช Development & Testing

```bash
# Run unit & integration test suite
cargo test

# Run strict linter checks
cargo clippy --all-targets -- -D warnings

# Build release artifact
cargo build --release
```

---

## ๐Ÿ“„ License

Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for full details.