pinghue 0.1.0__tar.gz

pinghue-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - macos-latest
+        python-version:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package
+        run: python -m pip install -e ".[dev]"
+      - name: Ruff
+        run: ruff check .
+      - name: Mypy
+        run: mypy src
+      - name: Tests
+        run: pytest
+      - name: Build
+        run: python -m build
+      - name: Check package
+        run: twine check dist/*

pinghue-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,52 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.12"
+      - name: Install build tooling
+        run: python -m pip install build==1.5.0 setuptools==82.0.1 twine==6.2.0 wheel==0.47.0
+      - name: Build
+        run: python -m build --no-isolation
+      - name: Check package
+        run: twine check dist/*
+      - name: Upload distributions
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: dist
+          path: dist/*
+          if-no-files-found: error
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: build
+    environment: pypi
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: dist
+          path: dist
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v3
+        with:
+          files: dist/*

pinghue-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+This project follows semantic versioning once it reaches `1.0.0`. Before `1.0.0`, CLI flags and JSON output may change; breaking JSON changes increment `schema_version`.
+
+## 0.1.0 - 2026-05-14
+
+- Initial public release candidate.
+- Added concurrent ICMP and TCP probing.
+- Added Textual TUI with Slate + Signal colors.
+- Added no-TUI mode for scripting and package smoke tests.
+- Added `--check` environment doctor for macOS/Linux ICMP readiness.
+- Added schema-versioned JSON export.
+- Added terminal display sanitization for operator-visible target and error text.
+- Added pinned GitHub Actions release workflow for PyPI trusted publishing.

pinghue-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,14 @@
+# Code of Conduct
+
+This project expects professional, respectful collaboration.
+
+## Expected Behavior
+
+- Be direct and constructive.
+- Keep technical discussions focused on evidence and maintainability.
+- Respect maintainer time.
+- Avoid harassment, insults, and personal attacks.
+
+## Reporting
+
+Report conduct issues through the repository maintainers. If the issue is security-sensitive, use the process in `SECURITY.md`.

pinghue-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing
+
+## Development Setup
+
+```sh
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e ".[dev]"
+pytest
+ruff check .
+mypy src
+```
+
+## Commit and PR Policy
+
+- Work on branches named with conventional prefixes such as `feat/`, `fix/`, `docs/`, `ci/`, or `release/`.
+- Submit changes through pull requests.
+- Keep commits signed and verified.
+- Keep changes focused; avoid unrelated refactors.
+- Include tests for behavior changes.
+- Update README, schema examples, or release docs when user-facing behavior changes.
+
+Useful local defaults:
+
+```sh
+git config commit.gpgsign true
+git config tag.gpgsign true
+git config gpg.format ssh
+```
+
+## Required Checks Before Merge
+
+```sh
+pytest
+ruff check .
+mypy src
+python -m build
+twine check dist/*
+```
+
+## Release Policy
+
+Releases are tag-driven. The publish workflow requires:
+
+- a signed release tag
+- GitHub Actions CI passing
+- PyPI trusted publishing configured for `inxbit/pinghue`
+- a protected `pypi` GitHub environment
+
+See `docs/release-checklist.md`.

pinghue-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 inxbit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pinghue-0.1.0/MANIFEST.in

@@ -0,0 +1,15 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include SECURITY.md
+include CONTRIBUTING.md
+include CODE_OF_CONDUCT.md
+include pinghue-threat-model.md
+include security-best-practices-report.md
+recursive-include schemas *.json
+recursive-include examples *.json
+recursive-include docs *.md *.svg
+recursive-include packaging *.rb
+recursive-include scripts *.sh
+recursive-include tests *.py
+recursive-include .github/workflows *.yml

pinghue-0.1.0/PKG-INFO

@@ -0,0 +1,315 @@
+Metadata-Version: 2.4
+Name: pinghue
+Version: 0.1.0
+Summary: Colored, concurrent ICMP/TCP ping monitor for the terminal
+Author: inxbit
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/inxbit/pinghue
+Project-URL: Repository, https://github.com/inxbit/pinghue
+Project-URL: Issues, https://github.com/inxbit/pinghue/issues
+Project-URL: Changelog, https://github.com/inxbit/pinghue/blob/main/CHANGELOG.md
+Project-URL: Security, https://github.com/inxbit/pinghue/security
+Keywords: ping,icmp,tcp,monitoring,tui,network
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Networking :: Monitoring
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: icmplib<4,>=3.0.4
+Requires-Dist: textual~=8.2.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: jsonschema>=4.22; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pytest>=8.2; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Dynamic: license-file
+
+# pinghue
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/inxbit/pinghue/main/docs/assets/pinghue-hero.svg" alt="pinghue - terminal ping monitor for maintenance windows" width="920">
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/pinghue/"><img alt="PyPI" src="https://img.shields.io/pypi/v/pinghue?color=58a6ff"></a>
+  <a href="https://pypi.org/project/pinghue/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/pinghue?color=7ee787"></a>
+  <a href="https://github.com/inxbit/pinghue/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/inxbit/pinghue/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://github.com/inxbit/pinghue/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/inxbit/pinghue?color=f2cc60"></a>
+</p>
+
+`pinghue` is a colored, concurrent ICMP/TCP ping monitor for maintenance windows. It gives operators a dense terminal view for many hosts at once and can also write structured JSON for reports, cron jobs, and CI checks.
+
+Current version: `0.1.0`.
+
+This is pre-1.0 software. CLI flags and JSON output may change before `1.0.0`; breaking JSON changes increment `schema_version`.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/inxbit/pinghue/main/docs/assets/pinghue-demo.svg" alt="animated pinghue terminal demo" width="920">
+</p>
+
+## What This Is
+
+- A focused terminal monitor for maintenance windows, migrations, and quick reachability checks.
+- A concurrent ICMP/TCP probe runner with a readable Textual TUI.
+- A scriptable probe tool with `--no-tui`, `--count`, `--duration`, and `--output`.
+- A JSON-producing report helper for post-maintenance evidence.
+- A local operator tool designed for macOS and Linux.
+
+## What This Is Not
+
+- Not a Prometheus, Smokeping, Zabbix, or NMS replacement.
+- Not a long-running metrics database or alerting system.
+- Not a privileged daemon.
+- Not a packet capture or traceroute tool.
+- Not a service that accepts remote network requests.
+
+## Install
+
+Recommended isolated installs:
+
+```sh
+uv tool install pinghue
+```
+
+or:
+
+```sh
+pipx install pinghue
+```
+
+Plain pip also works inside a virtual environment:
+
+```sh
+python -m pip install pinghue
+```
+
+Install the current development tree:
+
+```sh
+python -m pip install -e ".[dev]"
+```
+
+Homebrew support is planned through `inxbit/tap` after the first PyPI sdist is published.
+
+## Quick Start
+
+```sh
+pinghue 1.1.1.1 8.8.8.8 example.com
+pinghue -f hosts.txt
+pinghue -p 443 example.com
+pinghue -p 1 127.0.0.1 -c 1 --no-tui
+pinghue --output maintenance.json 1.1.1.1 example.com
+```
+
+Host files are plain text. Blank lines and lines starting with `#` are ignored.
+
+```text
+# edge and core checks
+1.1.1.1
+8.8.8.8
+example.com
+internal-db.corp
+```
+
+## Modes
+
+`pinghue` defaults to ICMP mode:
+
+```sh
+pinghue 1.1.1.1 example.com
+```
+
+TCP mode is enabled by passing a port:
+
+```sh
+pinghue -p 443 example.com api.internal
+```
+
+Use no-TUI mode for scripts, cron, CI, and package smoke tests:
+
+```sh
+pinghue -p 443 example.com -c 3 --no-tui
+```
+
+Example no-TUI output:
+
+```text
+2026-05-14T18:32:11.420000+00:00 1.1.1.1 ok latency=9.20ms
+2026-05-14T18:32:11.421000+00:00 example.com ok latency=14.08ms
+2026-05-14T18:32:12.420000+00:00 api.internal timeout latency=-
+```
+
+## CLI Reference
+
+```text
+pinghue [OPTIONS] [TARGET ...]
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `TARGET ...` | none | Hostnames or IP addresses to probe. Required unless `--check` is used. |
+| `-f, --file PATH` | none | Read targets from a plain-text host file. Blank lines and `#` comments are ignored. |
+| `-p, --port PORT` | ICMP | Enable TCP connect checks against `PORT`. Valid range: `1-65535`. |
+| `-4, --ipv4` | off | Force IPv4 resolution/probing. |
+| `-6, --ipv6` | off | Force IPv6 resolution/probing. |
+| `-n, --numeric` | off | Skip DNS and require IP literals. |
+| `-i, --interval SEC` | `1.0` | Seconds between probes. Minimum: `0.1`. |
+| `--timeout SEC` | interval | Per-probe timeout in seconds. Must be greater than `0`. |
+| `-c, --count N` | continuous | Stop after `N` probes per target. |
+| `--duration SEC` | continuous | Stop after elapsed seconds. |
+| `--no-tui` | off | Print one line per probe instead of launching the TUI. |
+| `--output PATH` | none | Write a JSON run summary on exit. |
+| `--no-samples` | off | Omit per-probe samples from JSON output. |
+| `--concurrency N` | `64` | Maximum concurrent probes. |
+| `--jitter-threshold MS` | `50.0` | Mark jitter as attention-worthy above this standard deviation. |
+| `--fail-threshold COUNT` | `3` | Classify a host as down after this many consecutive failed probes. |
+| `--history-style STYLE` | `bar` | One of `bar`, `dots`, `sparkline`, or `none`. |
+| `--check` | off | Run the environment doctor and exit. |
+| `--quiet` | off | With `--check`, suppress output and use only the exit code. |
+| `-v, --version` | none | Print the installed version. |
+| `-h, --help` | none | Print help. |
+
+## TUI Controls
+
+| Key | Action |
+| --- | --- |
+| `q` | Quit. |
+| `a` | Show or hide resolved addresses. |
+| `r` | Reset the selected host. |
+| `R` | Reset all hosts. |
+| `b` | Probe the selected host immediately. |
+| `B` | Probe all hosts immediately. |
+
+## History Legend
+
+The default history style is a fixed-scale colored bar:
+
+- Green bar: successful probe.
+- Amber bar: successful probe at or above the slow-latency threshold.
+- Red `.` / `·`: timeout, loss, or down state.
+- Amber `!`: TCP refused.
+
+Successful latency uses `▁▂▃▄▅▆▇█`.
+
+The fixed mapping keeps rows comparable:
+
+| Latency | Glyph |
+| --- | --- |
+| `<=1ms` | `▁` |
+| `<=3ms` | `▂` |
+| `<=10ms` | `▃` |
+| `<=30ms` | `▄` |
+| `<=100ms` | `▅` |
+| `<=300ms` | `▆` |
+| `<=1000ms` | `▇` |
+| `>1000ms` | `█` |
+
+Use `--history-style dots`, `--history-style sparkline`, or `--history-style none` when a terminal font or workflow needs a simpler display.
+
+## Doctor
+
+Run the doctor before relying on ICMP mode:
+
+```sh
+pinghue --check
+```
+
+Linux may block unprivileged ICMP sockets. TCP mode does not need special privileges:
+
+```sh
+pinghue -p 443 example.com
+```
+
+If `pinghue --check` reports that your GID is outside `net.ipv4.ping_group_range`, the preferred fix is:
+
+```sh
+sudo sysctl -w net.ipv4.ping_group_range="0 2147483647"
+echo 'net.ipv4.ping_group_range=0 2147483647' \
+  | sudo tee /etc/sysctl.d/99-pinghue.conf
+```
+
+The capability alternative is available but must be re-applied after binary upgrades:
+
+```sh
+sudo setcap cap_net_raw+ep "$(command -v pinghue)"
+```
+
+Do not set capabilities on a shared Python interpreter.
+
+## JSON Output
+
+`--output PATH` writes one JSON document per run. The schema lives at `schemas/output-v1.schema.json`, and an example lives at `examples/pinghue-output-example.json`.
+
+```sh
+pinghue -f hosts.txt --duration 180 --output maintenance.json
+```
+
+Use `--no-samples` when you only need final per-target statistics.
+
+Every output document includes:
+
+- `schema_version`
+- `pinghue_version`
+- run metadata
+- probe configuration
+- ordered target results
+- per-target stats
+- optional per-probe samples
+
+## Security Model
+
+`pinghue` is a local CLI/TUI. It does not run a server, accept remote requests, store credentials, or require secrets. The security-sensitive areas are:
+
+- terminal rendering of operator-supplied hostnames and OS error strings
+- Linux ICMP privilege configuration
+- local output paths selected by the operator
+- release workflow integrity
+
+See `pinghue-threat-model.md`, `security-best-practices-report.md`, and `SECURITY.md`.
+
+## Release Channels
+
+Planned release path for `0.1.0`:
+
+1. GitHub repository: `inxbit/pinghue`
+2. GitHub Actions CI on Linux and macOS
+3. GitHub Release with sdist and wheel artifacts
+4. PyPI trusted publishing through a protected `pypi` environment
+5. Homebrew formula generation after the PyPI sdist exists
+
+The release workflow is tag-driven:
+
+```sh
+git tag -s v0.1.0 -m "Release v0.1.0"
+git push origin v0.1.0
+```
+
+## Development
+
+```sh
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e ".[dev]"
+pytest
+ruff check .
+mypy src
+python -m build
+twine check dist/*
+```
+
+## License
+
+MIT. See `LICENSE`.