Module watch

Source
Expand description

§Configuration Watch Command

The watch command monitors a TOML configuration file for changes and automatically converts it to JSON when modifications are detected. This enables a live-reload workflow where users can edit their configuration and immediately see changes reflected in the running shell.

§Usage

# Watch default config location
fernctl watch

# Watch a specific file
fernctl watch --config ./my-config.toml

# Custom output location
fernctl watch --config config.toml --output theme.json

# Adjust debounce timing (milliseconds)
fernctl watch --debounce 200

# Disable desktop notifications
fernctl watch --quiet

§How It Works

The watch command uses operating system facilities to efficiently monitor files for changes:

PlatformTechnology
Linuxinotify
macOSFSEvents
WindowsReadDirectoryChangesW

This is more efficient than polling — the process sleeps until the OS signals that the file has changed.

§Event Flow

┌─────────────────────────────────────────────────────────────────────┐
│                        Watch Loop                                   │
│                                                                     │
│  ┌──────────────┐   ┌──────────────┐   ┌──────────────────────────┐│
│  │   inotify    │   │   Debounce   │   │      Convert & Notify    ││
│  │  (or equiv)  │──▶│   (100ms)    │──▶│                          ││
│  └──────────────┘   └──────────────┘   │  ┌─────────┐             ││
│        ▲                               │  │  Parse  │             ││
│        │                               │  │  TOML   │             ││
│        │                               │  └────┬────┘             ││
│   File modified                        │       │                  ││
│   by user                              │       ▼                  ││
│                                        │  ┌─────────┐             ││
│                                        │  │Validate │             ││
│                                        │  └────┬────┘             ││
│                                        │       │                  ││
│                                        │       ▼                  ││
│                                        │  ┌─────────┐  ┌────────┐ ││
│                                        │  │  Write  │  │ Notify │ ││
│                                        │  │  JSON   │──▶│  User  │ ││
│                                        │  └─────────┘  └────────┘ ││
│                                        └──────────────────────────┘│
└─────────────────────────────────────────────────────────────────────┘

§Debouncing

Editors often trigger multiple file system events when saving a file:

  1. File truncated (write begins)
  2. Data written
  3. File closed
  4. Metadata updated

Without debouncing, we might try to parse a half-written file. The debouncer waits for events to settle before processing:

Events:  ┃━━━━━━━━━━┃     ┃━━━━┃                    ┃
         │ truncate │     │write│                    │
         │  modify  │     │close│                    │
Time:    ──────────────────────────────────────────────▶
         0ms       10ms  50ms  100ms (debounce expires)
                                 │
                                 ▼
                           Process file

§Error Handling

The watch command is designed to be resilient — configuration errors should not crash the watcher. Instead:

Error TypeBehavior
Parse errorNotify user, keep watching
Validation errorNotify user, keep watching
File deletedNotify user, keep watching
Watch system errorExit with error

This allows users to fix mistakes without restarting the watcher:

$ fernctl watch
Watching ~/.config/fern/config.toml...

[14:32:01] ✓ Config reloaded
[14:32:15] ✗ Parse error at line 5 (keep editing...)
[14:32:28] ✓ Config reloaded

§Desktop Notifications

When notifications are enabled (the default), the watch command sends desktop notifications via the freedesktop.org notification spec:

ScenarioNotification
Success“Config Reloaded” (info)
Warning“Unknown Key: colour” (warning)
Error“Invalid Color: #gg0000” (error)

These appear in whatever notification daemon is running (fern-shell’s own notification center, dunst, mako, etc.).

§Integration with QuickShell

QuickShell watches the JSON file using its own FileView component. When we write a new JSON file, QuickShell automatically reloads:

┌────────────┐      ┌─────────────┐      ┌────────────────┐
│  User      │      │  fernctl    │      │  QuickShell    │
│  edits     │──────▶  watch     │──────▶│  reloads       │
│  TOML      │      │  writes    │      │  UI updates    │
└────────────┘      │  JSON      │      └────────────────┘
                    └─────────────┘

No IPC is needed — file watching on both sides creates a clean decoupled architecture.

§Exit Codes

CodeMeaning
0Normal exit (Ctrl+C)
1Initialization error (file not found, etc.)
2Watch system error

§Programmatic Usage

ⓘ
use fernctl::commands::watch::{run, WatchOptions, WatchEvent};
use fernctl::adapters::{TomlConfigAdapter, FileSystemAdapter};

let config_adapter = TomlConfigAdapter::new();
let persist_adapter = FileSystemAdapter::new();

let options = WatchOptions {
    debounce_ms: 100,
    notify_on_success: true,
    notify_on_error: true,
    verbose: true,
};

// Run the watch loop (blocks until interrupted)
run(
    &config_path,
    &json_path,
    options,
    &config_adapter,
    &persist_adapter,
    |event| {
        // Custom event handler
        match event {
            WatchEvent::Reloaded { warnings } => { /* ... */ }
            WatchEvent::Error { error } => { /* ... */ }
        }
    },
)?;

§Resource Usage

The watch command is designed to be lightweight:

  • CPU: Near-zero when idle (event-driven, not polling)
  • Memory: ~5-10 MB baseline
  • File descriptors: 2-3 per watched file

It’s safe to run indefinitely in the background.

Structs§

WatchOptions
Options for the watch command.

Enums§

WatchEvent
Events emitted during the watch loop.

Functions§

convert_and_report 🔒
Converts the config and reports the result.
notify_on_error 🔒
Callback wrapper that sends errors as notifications.
run
Runs the configuration watch loop.
send_notification 🔒
Sends a desktop notification.
timestamp 🔒
Returns the current time formatted for log output.

Type Aliases§

EventHandler
A callback function for watch events.