Metadata-Version: 2.4
Name: portpier
Version: 0.1.1
Summary: A gorgeous TUI dashboard for port and process monitoring on macOS
Project-URL: Homepage, https://github.com/fhswno/portpier
Project-URL: Repository, https://github.com/fhswno/portpier
Project-URL: Issues, https://github.com/fhswno/portpier/issues
Author-email: David Ohayon <davidohn.uk@hotmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.11
Requires-Dist: psutil>=6.0.0
Requires-Dist: textual>=0.80.0
Requires-Dist: tomli-w>=1.1.0
Description-Content-Type: text/markdown

# portpier

> Lightweight TUI dashboard for monitoring and managing ports on macOS.
> System ports (< 1024) are always hidden.

`portpier` shows every active user-space socket (all states) with full process
metadata, a live-updating table, one-keypress process termination, a rich detail
view, and a command palette.

---

## Install

**macOS (Homebrew):**

```bash
brew install fhswno/portpier/portpier
```

**Or run it instantly without installing** (needs [uv](https://docs.astral.sh/uv/)):

```bash
uvx portpier
```

**Other Python installers:**

```bash
uv tool install portpier
pipx install portpier
```

> Requires Python ≥ 3.11. macOS is the primary target; Linux works too.
> System ports (< 1024) are always hidden.

### From source (development)

[uv](https://docs.astral.sh/uv/) provisions the virtualenv *and* the Python
version — no need to install Python yourself.

```bash
# From the project root:
make install        # create the venv + install everything (runtime + dev tools)
make run            # launch portpier

# …or, globally (editable — code changes are picked up without reinstalling):
uv tool install -e .
portpier
```

---

## Keyboard reference

### Main dashboard

| Key | Action |
|---|---|
| `↑` / `↓` | Move row selection |
| `Enter` | Open the detail view for the selected process |
| `k` | Kill the selected process (opens the confirm dialog) |
| `/` | Focus the search box |
| `s` | Cycle the sort column |
| `Esc` | Clear the search |
| `Ctrl+P` | Open the command palette |
| `t` | Cycle theme |
| `r` | Force an immediate data refresh |
| `q` / `Ctrl+Q` | Quit |
| Click a row | Select it |
| Click a column header | Sort by that column (toggle asc/desc) |

Search filters client-side (case-insensitive substring) across port, process
name, type, state, and PID. The status bar shows the live match count.

### Detail view

| Key | Action |
|---|---|
| `Esc` / `q` | Return to the dashboard (same row stays selected) |
| `k` | Kill this process (opens the confirm dialog; returns to the dashboard on success) |
| `↑` / `↓` | Scroll the detail content |

### Kill dialog

| Key | Action |
|---|---|
| `Tab` / `←` `→` `↑` `↓` | Move between Graceful / Force Kill / Cancel |
| `Enter` | Activate the focused button (Graceful = SIGTERM, Force = SIGKILL) |
| `Esc` | Cancel / dismiss (no action) |

---

## Command palette (`Ctrl+P`)

| Command | Action |
|---|---|
| `theme <name>` | Switch theme — `dark`, `light`, `paper`, or `matrix` |
| `toggle <column>` | Show/hide a column (e.g. `toggle pid`). `PORT` is always visible. |
| `sort <column> [asc\|desc]` | Sort by `port`, `memory`, `cpu`, or `uptime` |
| `refresh <seconds>` | Set the refresh interval (0.5–60) |
| `port range <min> [max]` | Filter to a port range (e.g. `port range 3000 9999`) |
| `port range reset` | Clear the port-range filter (back to 1024–65535) |
| `help` | Show the command reference |

Every change is persisted immediately to the config file (below).

---

## Themes

| Name | Look |
|---|---|
| `dark` | Default. Dark canvas, high contrast, purple accent. |
| `light` | Clean light mode for daytime/bright terminals. |
| `paper` | Stark black on white — print-like, minimal. |
| `matrix` | Green-on-black, monospace terminal aesthetic. |

---

## Configuration

Config lives at `~/.config/portpier/config.toml`. It is created the first time
you change a setting (via the palette); a fresh install runs entirely on
defaults. To reset, just delete the file.

```toml
schema_version = 1

[display]
theme = "dark"                       # "dark" | "light" | "paper" | "matrix"
refresh_interval = 2.0               # seconds; clamped to [0.5, 60.0]
columns = ["port", "process", "type", "pid", "memory", "cpu", "state", "uptime"]
default_sort_column = "port"         # "port" | "memory" | "cpu" | "uptime"
default_sort_order = "asc"           # "asc" | "desc"

[filters]
min_port = 1024                      # hard floor: never below 1024
max_port = 65535
```

Unknown keys are ignored. An unknown/missing `schema_version` falls back to
defaults with a warning. `min_port` is always floored to `1024`.

---

## Notes

- **Without `sudo`:** processes you own are fully visible. Other users'
  processes raise `AccessDenied` and don't appear; the status bar then shows
  `⚠ Some processes require sudo to inspect`.
- **With `sudo`:** all processes are visible and the warning is absent.
- macOS sandboxes `open_files()` / `environ()`, so the detail view's
  **Open FDs** and **Environment** sections are often empty without `sudo` —
  this is expected, not a bug.

---

## Project layout

```
src/portpier/
├── __main__.py     # CLI entry point (--version / --help / launch)
├── app.py          # root Textual app
├── config.py       # TOML config (load/save, validation, atomic write)
├── data/           # psutil collection + immutable models
├── ui/             # screens, widgets, themes, command palette
└── utils/          # formatting, process-type inference, signals
tests/              # pytest suite (data layer + parsers + signals)
```

The data layer is fully testable without instantiating a Textual app.

## Common commands

```bash
make                # list all targets
make check          # typecheck + lint + test
make typecheck      # mypy --strict on src/
make lint           # ruff lint on src/
make fmt            # auto-format + auto-fix with ruff
make test           # run the test suite
make smoke          # live data-layer check against real ports
make clean          # remove the venv and all caches
```
