leviticus 0.0.1

Leviticus is a suite of tools which help developers build robust and maintainable applications across platforms, languages, frameworks, and runtimes.
Documentation
# Code Review & Future-Proof Architecture Proposal: `crates/loid`

This document provides a critical code review of the current `loid` daemon crate and proposes a future-proof architecture to transition it into a production-grade, resilient developer tool daemon.

---

## 1. Critical Code Review & Technical Debt

During our analysis of the `crates/loid` codebase, we identified several severe issues that cause runtime crashes, data loss risks, or security/portability failures.

### 🔴 High Risk: Destructive Side-Effects on User Projects
*   **Location**: [config.rs:L29-35]file:///Users/future/KB/project/app/loi/crates/loid/src/daemon/config.rs#L29-L35
*   **The Issue**: `sync_project_metadata` reads `Cargo.toml` in the current working directory, mutates the package version field directly to `"0.1.1"`, and writes it back:
    ```rust
    pub fn sync_project_metadata() {
        let mut cargo = read_cargo_toml();
        cargo.package.version = "0.1.1".to_string();
        write_cargo_toml(&cargo);
    }
    ```
*   **Impact**: If a user runs `loid` in a project with a custom version (e.g., `1.2.0`), `loid` will silently overwrite and downgrade their `Cargo.toml` configuration on startup, destroying local project state.

### 🔴 High Risk: Hardcoded Developer Paths
*   **Location**: [projection/document.rs:L49]file:///Users/future/KB/project/app/loi/crates/loid/src/projection/document.rs#L49
*   **The Issue**: The symbol path resolution logic contains a hardcoded absolute path to a specific local machine folder:
    ```rust
    let abs_path = format!("/Users/me/dev/loid/{}", path);
    ```
*   **Impact**: When running on any other machine or user account, file canonicalization and clickable links will point to non-existent directories, causing silent failures or broken links.

### 🟡 Medium Risk: Synchronous, Single-Threaded TCP Server (Blocking)
*   **Location**: [run.rs:L17-34]file:///Users/future/KB/project/app/loi/crates/loid/src/daemon/run.rs#L17-L34
*   **The Issue**: The IPC connection loop is synchronous and single-threaded:
    ```rust
    loop {
        let (mut socket, _) = listener.accept().await.unwrap();
        let mut buf = [0; 1024];
        let n = socket.read(&mut buf).await.unwrap();
        ...
    }
    ```
*   **Impact**: If a client establishes a TCP connection but does not send data, the server blocks indefinitely on `socket.read()`. This prevents any other client (e.g., calling `loid status`) from connecting, causing a complete denial of service.

### 🟡 Medium Risk: Fragile Relative Pathing
*   **Location**: [projection/document.rs:L17-23]file:///Users/future/KB/project/app/loi/crates/loid/src/projection/document.rs#L17-L23
*   **The Issue**: The daemon resolves static data directories relative to the current working directory:
    ```rust
    fn data_dir() -> PathBuf {
        PathBuf::from("src/daemon/data")
    }
    ```
*   **Impact**: If the daemon is run from the workspace root or any directory other than the `crates/loid` directory, it will fail to load `explain.json` or `symbols.json`, causing the daemon to fail silently.

### 🟡 Medium Risk: Widespread panic / unwrap / todo!() usage
*   **Location**: Throughout the codebase (e.g., `stop.rs`, `reload.rs`, `state.rs`, `resolver.rs`).
*   **The Issue**: Methods like `loid stop` and `loid reload` contain `todo!("Todo reload!")` which immediately panics when invoked. File reads/writes use `.unwrap()` directly on I/O results.
*   **Impact**: A simple filesystem lock or permissions error will instantly terminate the entire daemon process.

---

## 2. Proposed Future-Proof Architecture

To transition `loid` into a resilient, production-grade daemon, we suggest implementing the following architectural modules:

```mermaid
graph TD
    CLI[Loid CLI Client] -->|JSON-RPC over IPC| UDS[Unix Domain Socket / Named Pipe]
    UDS -->|Request| Server[IPC Server Loop]
    Server -->|Dispatch| Router[Command Router]
    Router -->|Mutate/Query| StateManager[State Actor / Channel]
    StateManager -->|Persist| DB[SQLite / Registry DB]
    StateManager -->|Trigger| Engine[Projection / VFS Engine]
```

### 1. Robust IPC: Unix Domain Sockets & Named Pipes
Instead of hardcoding a TCP port (`127.0.0.1:7788`) which is vulnerable to port conflicts and port scanning, use operating system native IPC:
*   **Unix-like systems (Linux, macOS)**: Use Unix Domain Sockets (UDS) bound to `~/.loid/socket`. UDS supports file-system level access permissions, keeping the socket secure.
*   **Windows**: Use Named Pipes (e.g., `\\.\pipe\loid`).
*   **Implementation**: Use the `interprocess` or `parity-tokio-ipc` crate to abstract UDS and Named Pipes under a single interface.

### 2. Standardized Communication Protocol (JSON-RPC)
Instead of parsing raw string comparisons like `cmd.trim() == "status"`, implement a structured RPC system:
*   Use a JSON-RPC 2.0 framework over the IPC connection.
*   Define clear API endpoints:
    *   `status()`: Returns health and state statistics.
    *   `stop()`: Safely closes resources and shuts down the daemon.
    *   `reload()`: Flushes caches and reloads workspace configs.
    *   `view_list()`: Lists all active and inactive projection views.
    *   `change_view(name)`: Switches the active projection.

### 3. Non-Blocking Event Loop (Tokio Task Spawning)
Resolve the blocking server issue by spawning a green thread (Tokio task) for every incoming connection:
```rust
async fn serve(listener: IpcListener) {
    loop {
        let socket = listener.accept().await.unwrap();
        tokio::spawn(async move {
            handle_client(socket).await;
        });
    }
}
```
If a client hangs, it will only block its spawned task, keeping the main daemon server responsive.

### 4. Actor-Based State & Projection Management
Keep the daemon state and compilation/projection engines synchronized without data races:
*   Run the active `CompileState` and `ProjectionEngine` inside separate long-running Tokio tasks (Actors).
*   Communicate with the state manager via message-passing channels (`tokio::sync::mpsc` and `tokio::sync::oneshot` for responses).
*   This removes complex thread-locking and ensures file updates, cache invalidations, and view switches happen sequentially and safely.

### 5. Safe Service Management (Daemonization)
Add true background execution support:
*   On Unix, use the `daemonize` crate to detach the process from the terminal, redirect `stdout`/`stderr` to `~/.loid/logs/loid.log`, and manage file descriptors.
*   Manage a PID file (`~/.loid/daemon.pid`) using a lockfile wrapper (e.g., `fs2` crate) to guarantee that only one instance of the daemon runs at any given time.