kmod-tui/SPEC.md

# kmod-tui — Kernel Module Inspector (Rust TUI)

A terminal UI for Linux sysadmins to browse and inspect loaded kernel modules.

## Goal
Show all loaded kernel modules in a navigable, filterable list, with a detail
view for each module's metadata, dependencies, parameters, and holders.

## Data Sources (verified on this host, kernel 6.8.0-137-generic, 130 modules)
- `/proc/modules` — one line per loaded module:
  `name  size  refcnt  used-by  state  addr`
  (e.g. `wireguard 114688 0 - Live 0xffffffffc125d000`)
- `/sys/module/<name>/` — per-module sysfs dir with:
  `refcnt`, `initstate`, `coresize`, `initsize`, `version`, `srcversion`,
  `taint`, `holders/` (modules depending on this one), `parameters/` (tunable params)
- `modinfo <name>` — richest metadata: filename, license, description, author,
  depends, retpoline, intree, vermagic, signature info

## Tech Stack
- Rust (stable)
- `ratatui` — TUI rendering (modern maintained fork of tui-rs)
- `crossterm` — terminal backend (cross-platform, works everywhere)
- `clap` — CLI args (optional: --sort, --filter, --no-modinfo for speed)
- No shell-out to `modinfo`; parse `/proc/modules` + walk `/sys/module` directly.
  (Avoids a process spawn per module; modinfo data like license/description/author
   comes from the .ko file's modinfo section — we parse the relevant sysfs files
   and, where sysfs lacks it, read the module file's modinfo section directly.
   Decision: for v1, shell out to `modinfo` lazily only when a module is selected
   for detail — keeps the list fast and detail rich. Revisit later.)

## UI Layout
```
┌─ kmod-tui — 130 modules loaded (kernel 6.8.0-137-generic) ──────────────┐
│ Filter: [_____________]  Sort: name▼  Loaded only: on                    │
├────┬──────────────────┬────────┬──────┬────────────────────┬────────────┤
│ #  │ Module           │ Size   │ Refc │ Used by            │ State      │
├────┼──────────────────┼────────┼──────┼────────────────────┼────────────┤
│  1 │ cpuid            │ 12288  │ 0    │ -                  │ Live       │
│  2 │ wireguard        │ 114688 │ 0    │ -                  │ Live       │
│  3 │ curve25519_x86_64│ 36864  │ 1    │ wireguard          │ Live       │
│ .. │ ..               │ ..     │ ..   │ ..                 │ ..         │
├────┴──────────────────┴────────┴──────┴────────────────────┴────────────┤
│ Detail: wireguard                                                       │
│   Filename: /lib/modules/.../wireguard.ko.zst                            │
│   License: GPL     Description: ...     Author: ...                      │
│   Depends: (none)   Holders: (none)   Parameters: (none)                 │
│   Coresize: 114688  Initsize: 0  Refcnt: 0  Srcversion: ...               │
└────────────────────────────────────────────────────────────────────────┘
 ↑/↓ move  Enter expand  / filter  s sort  q quit
```

Two-pane layout: scrollable module list (top ~70%), detail pane (bottom ~30%).
Selecting a row populates the detail pane. Enter opens a full-screen detail
view for the selected module with all sysfs fields, parameters, holders,
and a dependency tree.

## Features
### v1 (MVP — the "nice looking, human-navigable" baseline)
1. Module list from /proc/modules with columns: #, name, size (human-readable),
   refcnt, used-by, state.
2. Detail pane for highlighted module: filename, license, description, author,
   depends, holders, parameters (name + current value), coresize, initsize,
   refcnt, srcversion, taint, vermagic.
3. Vim-style navigation: j/k or ↑/↓ to move, Enter for full detail, Esc/q back.
4. Live filter (`/` then type, fuzzy or substring match on name).
5. Sort cycle (`s`): name, size, refcnt, dependents-count.
6. Footer help bar.
7. Color: state (Live=green, Loading/Unloading=yellow), refcnt>0 (bold),
   module-with-dependents highlighted.
8. Header shows module count, kernel version (from `uname -r`).

### v1.1 (polish)
- Dependency tree view (expand a module → see what it depends on and what
  depends on it, recursively).
- Parameter inspection with current values read from /sys/module/<n>/parameters.
- Export current view to file (CSV/TSV).
- Config file (~/.config/kmod-tui/config.toml) for default sort, columns.

### v2 (nice-to-have, later)
- Show ALL installable modules (from /lib/modules/$(uname -r)/), not just
  loaded — mark loaded vs available-not-loaded.
- Toggle between "loaded only" and "all available".
- modprobe/insmod/rmmod actions (guarded, with confirmation — but see note:
  this is read-only for v1; mutating is a separate, deliberate decision).
- Module loading state watch (inotify on /proc/modules, auto-refresh).

## Architecture (v1)
```
src/
  main.rs        — CLI args, app bootstrap, event loop
  app.rs        — App state: module list, cursor, filter, sort mode, focus
  model.rs      — Module struct, data collection from /proc + /sys
  ui/
    mod.rs      — frame composition, layout
    list.rs     — module list table rendering
    detail.rs   — detail pane + full detail view
    help.rs     — help bar / overlay
  event.rs      — crossterm input polling
  config.rs     — (v1.1) config file load
```

Data flow:
  collect_modules() → Vec<Module>  (once on startup; refresh on 'r')
  App holds Vec<Module> + filter/sort/cursor state
  ratatui draws from App state each frame
  crossterm polls input; key handlers mutate App state; redraw on change
  (or redraw on a fixed tick — simpler: event-driven redraw)

## Open Decisions (for Isaac)
1. Shelling out to `modinfo` for detail metadata (filename/license/desc/author)
   vs parsing .ko files directly? Recommend: shell out lazily on selection —
   simple and correct. We only parse /proc + /sys for the list.
2. Read-only for v1 (no rmmod/modprobe)? Recommend: YES, read-only v1.
3. Project location: /root/kmod-tui ? Recommend: yes.
4. Install Rust via rustup (recommended) or apt rustc package?
   Recommend: rustup (stable toolchain, latest ratatui).
5. Naming: `kmod-tui` ok?

## Build & Run
  cargo run --release
  (or `cargo build --release` then ./target/release/kmod-tui)

## Non-goals (v1)
- Editing module parameters (write to /sys) — risky, out of scope.
- Loading/unloading modules — risky, out of scope.
- Remote hosts — local only (could add SSH later).
- Persistent state — none needed.