# kmod-tui

A terminal UI for Linux sysadmins to browse and inspect loaded kernel modules.
Read-only — built for looking, not for changing module state.

## Why
`lsmod` shows a flat table. `modinfo <mod>` shows one module. This tool gives
you a navigable, filterable, sorted view of all loaded modules with rich
per-module detail (license, author, description, parameters, holders,
dependency info) a keystroke away.

## Data sources (read-only)
- `/proc/modules` — the loaded module list
- `/sys/module/<name>/` — refcnt, coresize, initsize, initstate, srcversion,
  taint, `parameters/`, `holders/`
- `modinfo <name>` — filename, license, description, author, depends,
  vermagic, retpoline, intree, signature info (fetched lazily, only when a
  module is selected for detail, so the list view stays fast)

## Install

**Option 1 — static binary (no toolchain needed)**

Grab it from the [v0.1.0 release](https://git.dhvlabs.space/hermes-agent-dhvlabs/kmod-tui/releases/tag/v0.1.0).
The binary is statically linked (musl) — no glibc, no Rust, no dependencies.
Runs on any Linux x86_64:

```sh
curl -LO "https://git.dhvlabs.space/hermes-agent-dhvlabs/kmod-tui/releases/download/v0.1.0/kmod-tui-linux-x86_64"
chmod +x kmod-tui-linux-x86_64
sudo mv kmod-tui-linux-x86_64 /usr/local/bin/kmod-tui
kmod-tui
```

If you already have the repo on a build box, just scp the binary anywhere:

```sh
scp target/x86_64-unknown-linux-musl/release/kmod-tui user@host:/usr/local/bin/kmod-tui
```

**Option 2 — build from source with rustup** (recommended if you want to hack on it)

```sh
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
cargo build --release
sudo mv target/release/kmod-tui /usr/local/bin/
```

**Option 3 — distro packages** (`apt install rustc cargo`) — works on Ubuntu
24.04+ (ships rustc 1.75, ratatui 0.28 needs ≥1.74). Older distros ship rust
that's too old; use rustup instead.

Runtime requirements (any distro has these): `/proc/modules`, `/sys/module`,
and the `modinfo` binary (kmod package) for the detail view's metadata.
The list view works without modinfo.

## Build & run
```sh
cargo run --release
# or
cargo build --release
./target/release/kmod-tui
# fully static build (any Linux x86_64, no glibc needed):
rustup target add x86_64-unknown-linux-musl
cargo build --release --target x86_64-unknown-linux-musl
```
Requires the Rust toolchain (rustup stable). No other deps; ratatui/crossterm
are vendored by cargo.

## Keys

List view:
```
j / ↓          move down
k / ↑          move up
g / Home       top
G / End        bottom
PgDn / PgUp    scroll by 10
Enter          open full-detail screen for the selected module
/              start filtering by module name (type, Esc to clear)
s              cycle sort: name → size → refcnt → dependents
r              refresh the module list from /proc/modules
?              toggle help overlay
q              quit
```

Full-detail view:
```
j / ↓ , k / ↑  move selection (stays in full-detail, reloads detail)
Esc / q        back to list
?              help
```

Filter mode (after `/`):
```
type           append to filter
Backspace      delete last char
Enter / Esc    exit filter (Esc also clears)
```

## Layout
- Top bar: module count + kernel version + current sort/filter.
- Middle: scrollable module table (#, name, size, refcnt, used-by, state).
- Bottom: two-column detail pane for the highlighted module.
- Footer: key hints (context-sensitive).

## Architecture
```
src/
  main.rs     CLI bootstrap, event loop, key dispatch
  app.rs      App state: module list, cursor, filter, sort, view mode, lazy fetches
  event.rs    crossterm input polling
  model.rs    Module/ModInfo types, /proc + /sys collection, modinfo parsing, tests
  ui/
    mod.rs     frame composition, status bar, footer, help overlay
    list.rs     module table
    detail.rs   detail pane + full-detail screen
```

## Tests
```sh
cargo test --release
```
Unit tests cover the /proc/modules `used-by` parser, the `modinfo` output
parser, and the human-readable size formatter.

## Non-goals (v1)
- Writing module parameters or loading/unloading modules — read-only by design.
- Showing all installable (not-yet-loaded) modules — planned for v1.1.
- Remote hosts — local only.

## Roadmap
- v1.1: dependency tree view, all-available-modules toggle, CSV/TSV export,
  config file (`~/.config/kmod-tui/config.toml`).
- v2: optional inotify auto-refresh on `/proc/modules`.