mesh-catalog/modules/i3status-rust/README.md

# i3status-rust

The bars as a module (novox/hq ADR 0208, research 026/05).

- Installs `i3status-rust`, and `pacman-contrib` for the update block's `checkupdates`. The `pacman` module declares `pacman-contrib` too; several modules may declare one package (novox/hq ADR 0303), so each declares what it needs.
  Claims the mesh's `node-bar` seat (no verbs yet, ADR 0208 §2) and renders the blocks other modules
  contribute to it (ADR 0255, below). Requires `x11-display` on its own
  machine: its bars are i3bar's.
- Owns `~/.config/i3status-rust/`, both bars (`top-bar.toml`, `bottom-bar.toml`) and their icon set
  (`icons/custom-icons.toml`).
- Places the two `bar { }` blocks as its own i3 drop-in, `~/.config/i3/config.d/60-i3status-rust.conf`:
  - the bottom bar shows the machine;
  - the top bar shows the focused window and the tray, on the primary output.
- Places two programs in `~/.local/bin`:
  - `i3status-updates`, the pending-updates block;
  - `i3bar-watchdog`, which brings back a bar that died.
- Starts the watchdog once per session, from the session's start (the `xinitrc` slot `normal`). It ends
  with the session's own process.

## Tools

| tool | does |
|---|---|
| `i3status_rust_reload` | the running bars re-read their files (i3status-rs restarts in place) |
| `i3status_rust_blocks` | each bar's blocks in order, kind and settings, and what each shows now (one run of the bar) |
| `i3status_rust_block_run` | one block alone, with the bar's theme and icons, to see what it shows or why it errors |
| `i3status_rust_themes` | the themes on the machine and the one each bar uses |

## Blocks other modules contribute (novox/hq ADR 0255)

A block that depends on the machine's hardware is not written here. The module that knows the hardware
contributes it to `node-bar` as data that says what it shows, and this module renders it:

- **What a contribution says:** which bar (`bottom`, `top`), which place (`resources`, beside the
  processor, memory and disks; `status`, beside the sound), an order from 0 to 99, what it shows
  (`battery`, `command`) and that kind's options. Nothing in it is i3status-rust's.
- **How it is rendered:** the claim's `renders.block` is a template (its source is `files/block.tmpl`)
  that turns one piece into a `[[block]]`. The controller runs it and places the result where each bar
  says `${contribution:node-bar:block:bar=…,place=…}`. Each bar places both of its places once; the
  catalogue check refuses a holder that misses one.
- **Where it applies:** a contribution may name a capability the machine must report. The `power`
  module's battery block names `battery` and its power-draw block names `power-meter`, so the laptop's
  bar gets both and a desktop only the power draw.
- **A value from the bus:** a block that `shows: state` names another module's state, such as
  `power.draw`. The mesh grants this module the read, because a module on its machine offers it; the
  manifest names no other module. This module's bundle watches it and leaves the value's text in the
  account's runtime directory (`i3status-rust/values/`), dated with the value's own `at`, and the block
  runs `~/.local/bin/i3status-value`, which prints it, or nothing when it was measured more than 30 s
  ago, so the block hides a value frozen at its source. A watch that says nothing for a minute is
  looked at once: a key that is gone has expired at its source and shows nothing; a key still there
  means the watch died, so it is watched again and that is logged once. A refused watch is logged and
  tried again, and a value no bar shows any more is no longer kept. The bus grants this module the one key each block shows (the machine's own unless
  the block names another, `[a-z0-9-]`). No file of another module is read: modules talk over the bus.
- **The battery** is i3status-rust's own battery block, which reads the kernel's power-supply class
  itself: the bar reading the machine, not another module.

Still left out:

- **The GPU's load,** the laptop's AMD block (commented out for NVIDIA on the desktop). A generic GPU
  block belongs to a generic module, which does not exist yet; a GPU's power is in the power draw.
- **Three Bluetooth headsets** by hardware address: one person's devices, not the bar's.

The second way the README once offered, blocks with i3status-rust's `if_command` that hide themselves on
a machine without the hardware, was rejected: the knowledge would stay in the bar, decided at run time.

## What it improves on what was found

- **The weather needs no key.** The found block used a weather service with an API key written in
  plain text in the file, and a fixed city. It now uses the Norwegian Meteorological Institute, which
  needs no key, located automatically.
- **The update count is the module's own,** adopted from the operator's `~/scripts/pkg-updates`. It
  counts AUR updates only where an AUR helper is installed. Clicking it lists the updates in the
  launcher's menu, instead of a theme from a cloned theme repository.
- **The memory is what programs hold** (`$mem_used`), not `$mem_total_used`, which counts the cache the
  kernel gives back when asked and read 96 % on a machine at 73 %. It is the figure the
  `memory-pressure` module judges by (changed 2026-10-08).
- **The faces** are JetBrains Mono Nerd Font, not Hack.
- **The watchdog is no longer a hand-enabled user unit** that ran on one workstation and not the
  other. It runs on both, once per session, and ends with the session.
- The docker block's click, which ran a program installed on neither machine, is gone.

## What it leaves as found

- `~/.config/i3status-rust/scripts/` (a mouse battery script for one device).
- `~/scripts/pkg-updates` and `~/scripts/i3-bar-watchdog`, replaced here.
- The user unit `~/.config/systemd/user/i3-bar-watchdog.service` and its enablement link.

## Migration (ADR 0182)

1. **Revoke the weather API key** that was in the found `bottom-bar.toml`. It sat in plain text on
   both workstations. The first push keeps the found file once and then writes the module's, which
   has no key.
2. Before the first push, on the laptop: `systemctl --user disable --now i3-bar-watchdog.service`.
   Otherwise two watchdogs run. Then delete the unit file, `~/scripts/i3-bar-watchdog` and
   `~/scripts/pkg-updates`.
3. Until the `i3` module carries the main configuration, the found `~/.config/i3/config` still has its
   own two `bar { }` blocks, and i3 shows four bars. The `i3` module's configuration has none.

## Blockers

- `node-bar`, `x11-display` and the `xinitrc` slot are ADR 0208's. Until the controller knows them,
  `mctl` reads them as unknown.
- The watchdog would be a user unit once user-scoped units ship (mesh-host #72). It is not, because it
  runs per session and ends with the session, as a session-start line already does.
- `pacman-contrib` is the `pacman` module's, which took it over as foreseen: a package is declared
  once per node.

## Its i3 lines are a contribution (changed 2026-10-05, novox/hq ADR 0212)

The module no longer writes a file into i3's `config.d`. Its window-manager lines (the source is still
under `files/i3/` where it had one) are a contribution to `node-display-session`. The i3 module places
them in its own configuration under a `# <module>` line, so this module depends on a window manager
being assigned beside it.