queue-watch 0.1.0__py3-none-any.whl

queue_watch-0.1.0.dist-info/METADATA

@@ -0,0 +1,141 @@
+Metadata-Version: 2.5
+Name: queue-watch
+Version: 0.1.0
+Summary: Read-only terminal dashboard for CI runs and merge queues, with mouse support
+Project-URL: Homepage, https://github.com/wolfiesch/queue-watch
+Project-URL: Issues, https://github.com/wolfiesch/queue-watch/issues
+Project-URL: Changelog, https://github.com/wolfiesch/queue-watch/releases
+Author: Wolfgang Schoenberger
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ci,dashboard,github-actions,merge-queue,textual,tui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: textual<7,>=6
+Description-Content-Type: text/markdown
+
+# queue-watch
+
+Read-only terminal dashboard for CI runs and merge queues. It joins records from every source into one row per change, so a branch's CI runs and its merge-queue entry read together, and draws each merge queue as a chain of chips in queue order. queue-watch never reruns, cancels, merges or takes a lock.
+
+![queue-watch showing a merge queue of four changes, the Changes table grouped by state, and the inspector for a failed change](https://raw.githubusercontent.com/wolfiesch/queue-watch/main/docs/screenshot.png)
+
+## Install
+
+```sh
+uv tool install queue-watch     # or: pipx install queue-watch
+uvx queue-watch                 # run once without installing
+```
+
+Requires Python 3.11+. The GitHub adapters use an authenticated [GitHub CLI](https://cli.github.com/) (`gh auth login`).
+
+## Use
+
+```sh
+queue-watch                              # inside a GitHub checkout
+queue-watch --repo owner/repo            # Actions plus the merge queue, if any
+queue-watch --profile work               # ~/.config/queue-watch/work.toml
+queue-watch --config sources.toml        # any combination of sources
+queue-watch --repo owner/repo --once     # one JSON snapshot, no TUI
+queue-watch --theme nord --ascii         # any Textual theme; ASCII glyphs only
+queue-watch --density comfortable        # title, owner and PR on a second line
+```
+
+With no flags, queue-watch looks for a `.queue-watch.toml` at the root of the current Git checkout. Without one, it watches the checkout's GitHub repository: Actions runs, plus the merge queue when the default branch has one. `--profile NAME` reads `$XDG_CONFIG_HOME/queue-watch/NAME.toml` (default `~/.config`).
+
+The Changes tab groups changes into Needs attention, Running, Queued and Done; every view a source reports also gets its own tab. Done starts folded while any other group has changes; press enter on a group row, or click it, to fold or unfold it. Select a change or a queue chip to see its CI checks, the jobs of the most notable one, its queue position and ETA, and recent history in the inspector.
+
+Each merge queue gets a strip above the tabs: its entries in merge order, when it should clear, merges in the last hour, and how long recent attempts took. Queue depth over the session appears as a sparkline once two fetches have answered; sources report only the current queue, so the history starts when queue-watch does. On terminals under 30 rows the entries shrink to one line each.
+
+Keyboard: arrows to move, `1` to `9` for tabs, `/` to search (esc to clear), `o` to open the selection in a browser, `c` to copy its SHA, `d` to switch row density, `r` to refresh, `p` to pause, `q` to quit. The mouse works too: click tabs, rows, chips and the inspector buttons, and scroll with the wheel. When a source fails, its last good data stays on screen and its status pill turns stale.
+
+### Repository configs need trust
+
+A config can run commands and open SSH connections, so a `.queue-watch.toml` that arrives with a clone does nothing until you review it and run:
+
+```sh
+queue-watch trust
+```
+
+Trust covers the file's exact bytes (SHA-256, stored in `$XDG_STATE_HOME/queue-watch/trusted.json`). After any edit, queue-watch refuses the file and names the command to run again. Files passed with `--config` or `--profile` are yours and load without this step.
+
+## Sources
+
+A config file lists sources as `[[source]]` tables. `id` and `adapter` are required; `label` and `interval` (seconds) are optional; every other key is an adapter option.
+
+```toml
+[[source]]
+id = "ci"
+adapter = "github-actions"
+repo = "owner/repo"
+
+[[source]]
+id = "merge-queue"
+adapter = "github-merge-queue"
+repo = "owner/repo"
+branch = "main"                          # optional; default branch otherwise
+
+[[source]]
+id = "deploys"
+adapter = "command"
+command = ["./bin/deploy-status", "--json"]
+timeout = 20                             # optional seconds, default 25
+
+[[source]]
+id = "merges"
+adapter = "flock-queue"
+host = "build-host"                      # optional SSH destination
+root = "~/src/project"                   # Git checkout that defines {git_dir}
+lock = "{git_dir}/merge.lock"
+tickets = "{git_dir}/merge.queue/*.ticket"
+process = "merge.py"
+owner_flag = "--owner"
+history = "{git_dir}/merge-history.jsonl"
+history_columns = [{ key = "fields.duration_seconds", label = "Took", format = "seconds" }]
+```
+
+| Adapter | Watches | Options |
+|---|---|---|
+| `github-actions` | Workflow runs, with jobs and steps in the inspector | `repo` |
+| `github-merge-queue` | GitHub's native merge queue: position, state, author and GitHub's merge estimate per pull request | `repo`, `branch` |
+| `command` | Anything else: a program that prints one snapshot | `command`, `host`, `cwd`, `timeout` |
+| `flock-queue` | A Linux FIFO of flock-held ticket files guarding one merge lock, plus an optional JSON Lines attempt log | `lock`, `tickets`, `process`, `root`, `host`, `interpreters`, `owner_flag`, `history`, `history_limit`, `history_columns` |
+
+Merge queue states map as `QUEUED` and `MERGEABLE` to queued, `AWAITING_CHECKS` and `LOCKED` to running, and `UNMERGEABLE` to blocked. A branch without a queue shows a warning instead of an error.
+
+`flock-queue` reads lock holders from `/proc/locks` rather than acquiring them. With `host` set, the probe goes to `python3 -` over SSH on stdin and nothing is installed on the host.
+
+### Command sources
+
+Use the `command` adapter for GitLab, Buildkite, Jenkins, Bors or an in-house queue. `command` is an argument list run without a shell. Locally it runs in `cwd`, which defaults to the config file's directory; relative paths resolve against that directory too. With `host` set, it runs over SSH (`BatchMode`, every argument quoted for the remote shell), in `cwd` on the host when given.
+
+The program must exit zero and print one snapshot (below) on stdout within `timeout` seconds. Anything else, including a snapshot that breaks the contract, shows as a source error while the last good data stays on screen. [`examples/`](https://github.com/wolfiesch/queue-watch/tree/main/examples) has a working script and config.
+
+## Snapshot contract
+
+Every adapter emits the same versioned snapshot (`queue-watch.snapshot/1`): a list of records with `id`, `kind`, `state` and `title`, plus optional `ref`, `sha`, `owner`, `position`, timestamps, `url`, `fields` and `children`. `state` is one of `queued`, `running`, `blocked`, `success`, `failure`, `cancelled`, `neutral` or `unknown`; the adapter's own term is kept in `raw_state`. Records that share a `ref` or `sha` describe the same change across sources. [`model.py`](https://github.com/wolfiesch/queue-watch/blob/main/src/queue_watch/model.py) defines and validates the contract, and `--once` prints it.
+
+## Development
+
+```sh
+uv sync
+uv run pytest -q                        # includes SVG snapshot tests
+uv run pytest -q --snapshot-update      # after an intended layout change
+```
+
+`docs/screenshot.png` is the wide layout snapshot rendered in a browser. To release, bump `__version__` in `src/queue_watch/__init__.py`, merge, and push a matching `vX.Y.Z` tag; the release workflow tests, builds, publishes to PyPI with trusted publishing, and creates the GitHub release.
+
+## License
+
+MIT

queue_watch-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+queue_watch/__init__.py,sha256=Et5F4b-CXY5wbs5dYw7ZsLbuTxmhuVI5EPOg-1ssgso,88
+queue_watch/app.py,sha256=H6zkvLQs8DKjQNq3smrj3ReWujExQkr0RypEFVPkxgI,36828
+queue_watch/changes.py,sha256=7rwtEm8vWHQH7Ra1IhxLX7GeGgLXm0QTvhU93oU7OzY,6379
+queue_watch/cli.py,sha256=AGHMbKuf1e-Ah3NWpTUNLzonxfwI2_J4Fe8j4hEAAX0,5269
+queue_watch/config.py,sha256=Ig3i5AXyWPKjlZoRuXDghmOTMGShcCpmf6yg96T0A7g,3672
+queue_watch/discovery.py,sha256=BwKx5JU6A115hqJmJbEqP845Kx8oR0X2lKQjfRyZEWA,4890
+queue_watch/model.py,sha256=Vp0i4OBHCn7VRJ-93XJfBfX7cvCy4W5NRLA7Gh5E8Mw,7896
+queue_watch/process.py,sha256=JkqioMiWoKoNb0IrPBekz4GGOE1jvZbfgo3L6FUYc1w,2610
+queue_watch/widgets.py,sha256=aLwlecVY_x9yYPmnzxmocqr16sRE9ZYeNpdHN6mrwDk,28667
+queue_watch/adapters/__init__.py,sha256=v9qpSUMFtJNNb4N7paQaDrfxiGlH7BmQqM14A8W5IT4,1101
+queue_watch/adapters/command.py,sha256=dxATISUXWNuQmFTQxq8zeuJINq9p6OssaZZEPw1Q1qY,1990
+queue_watch/adapters/flock_queue.py,sha256=EHKB1wLqVF0qui7qdHkIeJs-mMfQ6qtRGJ-GPXYzY6I,11847
+queue_watch/adapters/github_actions.py,sha256=v3QxW_agqd4GJUd59ZE1iPw52hoOGFivz1w46xeVoqs,6118
+queue_watch/adapters/github_merge_queue.py,sha256=ZpRYlyfEoWSai2DtoP5CE6QVBUdTu3yx_XvgFlDgiYs,5140
+queue_watch-0.1.0.dist-info/METADATA,sha256=Oq0Pz9DgKuqBBKgJ5p-dAmDP7F3sSF_67Svmi8wl4PQ,8376
+queue_watch-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+queue_watch-0.1.0.dist-info/entry_points.txt,sha256=vpoaPvrxU-TWgiVefYwd2kFh22naV-OMAVkqVM3XUn8,53
+queue_watch-0.1.0.dist-info/licenses/LICENSE,sha256=JKzPXq3f7o1e4rX_LdIS1izSmmLRlPsMW8aBssenlzA,1078
+queue_watch-0.1.0.dist-info/RECORD,,

queue_watch-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

queue_watch-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+queue-watch = queue_watch.cli:main

queue_watch-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wolfgang Schoenberger
+
+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.