Metadata-Version: 2.4
Name: kentrawatch
Version: 0.1.0
Summary: A beautiful TUI replacement for `watch` with graphs, stats, and multiple views
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: textual>=1.0.0
Requires-Dist: textual-plotext>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typed-argument-parser>=1.12.0
Requires-Dist: loguru>=0.7.0

# kentraWATCH

A beautiful TUI replacement for `watch` with live graphs, stats dashboards, and structured output parsing.

![Python](https://img.shields.io/badge/python-%3E%3D3.12-blue) ![Textual](https://img.shields.io/badge/textual-8.2.7-purple)

## Features

- **Live command execution** — run any command at a configurable interval (0.5s–60s)
- **Output view** — colored diff with fade-away change highlighting, word wrap toggle, horizontal scroll
- **Graph view** — auto-detected numeric columns plotted as line charts over time
- **Stats view** — timing, history, uptime, and exit code dashboard
- **Structured output parsing** — auto-detects delimiters (comma, tab, pipe, semicolon, whitespace) and numeric columns with unit suffix parsing (K, M, G, T, P)
- **Settings modal** — categorized two-pane settings screen for all options
- **Config persistence** — `~/.kentrawatch/config.json` auto-saves on every change
- **Themes** — toggle between 21+ Textual themes
- **Pause/resume** — freeze execution without losing history
- **Maximize mode** — hide chrome for a focused view (`m`)
- **File logging** — `~/.kentrawatch/kentrawatch.log` with rotation

## Installation

```bash
pip install kentrawatch
```

Or from source:

```bash
git clone https://github.com/yourusername/kentrawatch
cd kentrawatch
pip install -e .
```

Requires Python ≥3.12.

## Usage

```bash
kentrawatch [options] <command>
kw [options] <command>
```

### Examples

```bash
# Watch disk usage
kentrawatch "df -h"

# Watch with custom interval and CSV parsing
kentrawatch -n 5 -d , "ps aux | awk '{print \$3,\$4}'"

# Disable change highlighting
kentrawatch --no-highlight "vm_stat"

# Set log level
kentrawatch --log-level DEBUG "ping -c 1 8.8.8.8"
```

### Options

| Flag | Default | Description |
|---|---|---|
| `-n`, `--interval` | `2.0` | Update interval in seconds (min 0.5) |
| `-d`, `--delimiter` | auto | Column delimiter for structured output |
| `--history` | `100` | Number of runs to keep in history |
| `--log-level` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL) |
| `--version` | — | Show version and exit |
| `--highlight` / `--no-highlight` | on | Enable/disable change highlighting |

### Keybindings

| Key | Action |
|---|---|
| `q` | Quit |
| `r` | Reset history |
| `p` | Pause/resume |
| `w` | Toggle word wrap |
| `s` | Open settings modal |
| `m` | Toggle maximize mode |
| `+` / `-` | Increase/decrease interval by 0.5s |

## Views

The interface has three tabs, navigable by clicking:

| Tab | Content |
|---|---|
| **Output** | Command stdout with diff highlighting and fade animation |
| **Graphs** | Live line charts for numeric columns across runs |
| **Stats** | Timing, command, history, and exit code dashboard |

## Settings Modal

Press `s` to open the categorized settings modal:

| Category | Settings |
|---|---|
| **Display** | Theme (21+ Textual themes), Highlight toggle, Word Wrap toggle |
| **Execution** | Interval, Delimiter, History Size |
| **Logging** | Log Level (DEBUG–CRITICAL) |

All changes apply immediately and persist to `~/.kentrawatch/config.json`.

## Configuration

Settings are saved to `~/.kentrawatch/config.json`:

```json
{
  "interval": 2.0,
  "delimiter": null,
  "history_size": 100,
  "theme": "dracula",
  "highlight": true,
  "wrap": true,
  "log_level": "INFO"
}
```

CLI flags override config file values.

## Logging

Logs are written to `~/.kentrawatch/kentrawatch.log` with automatic rotation at 10 MB (3 backups retained).

## Dependencies

- [Textual](https://textual.textualize.io/) — TUI framework
- [textual-plotext](https://github.com/Textualize/textual-plotext) — terminal plotting
- [Rich](https://rich.readthedocs.io/) — styled output
- [typed-argument-parser](https://github.com/axa-group/typed-argument-parser) — CLI args
- [Loguru](https://loguru.readthedocs.io/) — logging
