limitless-cli 1.0.0

A beginner-friendly environment diagnostic tool
Documentation
# 03 — Runtime Behavior & Sequence Flows

This module traces the exact runtime sequence of the primary CLI operations using Mermaid sequence diagrams and code location mapping.

---

## 1. `limit check` — Full Pre-Flight Audit Sequence

```mermaid
sequenceDiagram
    autonumber
    actor User
    participant Main as main::route()
    participant Stack as stack_detector::detect()
    participant Engine as diagnostics::run_all()
    participant Probes as Probe Threads (Tokio)
    participant Translator as translator::translate()
    participant TUI as tui::render()

    User->>Main: Executing `limit` or `limit check`
    Main->>Stack: Probe Current Workspace Path
    Stack-->>Main: Return ProjectStack (e.g. Node)
    Main->>Engine: Spawn Diagnostic Suite (Parallel Threads)
    par Concurrent Probes
        Engine->>Probes: Probe 1: Port Occupancy (5432, 27017, etc.)
        Engine->>Probes: Probe 2: Env Auditor (.env vs .env.example)
        Engine->>Probes: Probe 3: Runtime Versions (node, python, cargo)
        Engine->>Probes: Probe 4: PATH Hygiene (Duplicates, Broken)
    end
    Probes-->>Engine: Raw Telemetry Results
    Engine->>Translator: Process Errors & Failures
    Translator-->>Engine: Plain-English Mentor Advice
    Engine-->>Main: DiagnosticReport (Score, Checks, Fixes)
    Main->>TUI: Render Visual Box Frame & Health Gauge
    TUI-->>User: Display Output & Exit Code (0 = Healthy, 1 = Caution/Fail)
```

---

## 2. `limit dev` — Smart Dev Launcher Sequence

```mermaid
sequenceDiagram
    autonumber
    actor User
    participant Main as main::route()
    participant Diag as diagnostics::run_all()
    participant Dev as dev_launcher::launch()
    participant OS as Host OS Process

    User->>Main: Executing `limit dev`
    Main->>Diag: Run Pre-Flight Diagnostics
    Diag-->>Main: DiagnosticReport
    alt Health Score == 100% (or --force flag passed)
        Main->>Dev: Resolve Dev Server Recipe for Stack
        Dev->>OS: Exec Command (e.g., `npm run dev` or `cargo run`)
        OS-->>User: Dev Server Logs Stream to Terminal
    else Health Score < 100%
        Main->>User: Display Health Warning, Block Dev Server Launch, & List Fixes
    end
```

---

## 3. `limit fix --all` — Automated Repair Sequence

```mermaid
sequenceDiagram
    autonumber
    actor User
    participant Main as main::route()
    participant AutoFix as auto_fix::run_all()
    participant FixEngine as fixes::execute_fix()
    participant OS as OS Process / File System

    User->>Main: Executing `limit fix --all`
    Main->>AutoFix: Gather Active Fix Suggestions
    loop For Each Detected Issue
        AutoFix->>FixEngine: Execute Recommended Fix
        alt Issue: Occupied Port (PID 6460)
            FixEngine->>OS: Execute `taskkill /PID 6460 /F` (or `kill -9`)
            OS-->>FixEngine: Return Status (Success or Access Denied)
        else Issue: Missing .env
            FixEngine->>OS: Copy .env.example -> .env
        end
    end
    FixEngine-->>AutoFix: Return Fix Success/Failure Summary
    AutoFix->>Main: Render Auto-Fix Report
    Main-->>User: Display Health Score Delta (e.g. 68% -> 100%)
```