queue-watch 0.1.0__tar.gz

queue_watch-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+.ruff_cache/
+snapshot_report.html

queue_watch-0.1.0/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.

queue_watch-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,114 @@
+# 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/examples/queue-status.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""Example source for the ``command`` adapter: a queue kept as a JSON file.
+
+queue-watch runs this with no shell and reads one snapshot v1 object from
+stdout. Adapt the ``load`` function to whatever your system exposes: an HTTP
+API, a database query, a directory of ticket files.
+
+    [[source]]
+    id = "deploys"
+    adapter = "command"
+    command = ["python3", "examples/queue-status.py", "examples/queue.json"]
+"""
+
+import json
+import sys
+from datetime import UTC, datetime
+
+STATES = {"waiting": "queued", "deploying": "running", "held": "blocked"}
+
+
+def load(path: str) -> list[dict]:
+    with open(path) as handle:
+        return json.load(handle)
+
+
+def main() -> None:
+    entries = load(sys.argv[1])
+    records = [
+        {
+            "id": str(entry["id"]),
+            "kind": "queue_entry",
+            "state": STATES.get(entry["status"], "unknown"),
+            "raw_state": entry["status"],
+            "title": entry["title"],
+            "owner": entry.get("owner"),
+            "position": position,
+            "created_at": entry.get("since"),
+            "fields": {"target": entry.get("target")},
+        }
+        for position, entry in enumerate(entries, start=1)
+    ]
+    snapshot = {
+        "schema": "queue-watch.snapshot/1",
+        "observed_at": datetime.now(UTC).isoformat(),
+        "records": records,
+        "views": [
+            {
+                "kind": "queue_entry",
+                "label": "Deploys",
+                "columns": [
+                    {"key": "position", "label": "#", "width": 4},
+                    {"key": "state", "label": "State", "width": 12, "format": "state"},
+                    {"key": "title", "label": "Change", "width": 36},
+                    {"key": "fields.target", "label": "Target", "width": 12},
+                    {"key": "created_at", "label": "Waiting", "width": 9, "format": "age"},
+                ],
+            }
+        ],
+    }
+    json.dump(snapshot, sys.stdout)
+
+
+if __name__ == "__main__":
+    main()

queue_watch-0.1.0/examples/queue.json

@@ -0,0 +1,5 @@
+[
+  {"id": 41, "status": "deploying", "title": "Rotate API gateway certificates", "owner": "dana", "since": "2026-10-20T16:02:00+00:00", "target": "prod-eu"},
+  {"id": 42, "status": "waiting", "title": "Raise worker pool to 24", "owner": "lee", "since": "2026-10-20T16:10:00+00:00", "target": "prod-us"},
+  {"id": 43, "status": "held", "title": "Schema change: orders.index", "owner": "sam", "since": "2026-10-20T16:12:00+00:00", "target": "prod-us"}
+]

queue_watch-0.1.0/examples/sources.toml

@@ -0,0 +1,8 @@
+# queue-watch --config examples/sources.toml
+# Paths in `command` and `cwd` are relative to this file's directory.
+
+[[source]]
+id = "deploys"
+adapter = "command"
+label = "Deploys"
+command = ["python3", "queue-status.py", "queue.json"]

queue_watch-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "queue-watch"
+dynamic = ["version"]
+description = "Read-only terminal dashboard for CI runs and merge queues, with mouse support"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Wolfgang Schoenberger" }]
+requires-python = ">=3.11"
+dependencies = ["textual>=6,<7"]
+keywords = ["ci", "merge-queue", "github-actions", "tui", "textual", "dashboard"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: Software Development :: Testing",
+]
+
+[project.urls]
+Homepage = "https://github.com/wolfiesch/queue-watch"
+Issues = "https://github.com/wolfiesch/queue-watch/issues"
+Changelog = "https://github.com/wolfiesch/queue-watch/releases"
+
+[project.scripts]
+queue-watch = "queue_watch.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-textual-snapshot>=1.0.0",
+]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/queue_watch/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/examples", "/README.md", "/LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+extend-select = ["I", "B", "UP"]

queue_watch-0.1.0/src/queue_watch/__init__.py

@@ -0,0 +1,3 @@
+"""Read-only terminal dashboard for CI runs and merge queues."""
+
+__version__ = "0.1.0"

queue_watch-0.1.0/src/queue_watch/adapters/__init__.py

@@ -0,0 +1,34 @@
+"""Adapters turn one external system into snapshot v1 (see queue_watch.model)."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+
+class Adapter:
+    """Base class. Subclasses take their options as keyword-only arguments.
+
+    A ``config_dir`` parameter, when present, receives the directory of the config
+    file; it is supplied by the loader and cannot be set from configuration.
+    """
+
+    name: ClassVar[str]
+    label: ClassVar[str]
+    interval: ClassVar[float] = 15.0
+
+    async def snapshot(self) -> dict:
+        raise NotImplementedError
+
+    async def children(self, record: dict) -> list[dict]:
+        """Detail records (jobs, steps) for the inspector; inline by default."""
+        return record.get("children") or []
+
+
+def registry() -> dict[str, type[Adapter]]:
+    from .command import Command
+    from .flock_queue import FlockQueue
+    from .github_actions import GitHubActions
+    from .github_merge_queue import GitHubMergeQueue
+
+    adapters = (GitHubActions, GitHubMergeQueue, FlockQueue, Command)
+    return {adapter.name: adapter for adapter in adapters}

queue_watch-0.1.0/src/queue_watch/adapters/command.py

@@ -0,0 +1,54 @@
+"""Any program that prints one snapshot v1 JSON object on stdout.
+
+This is the extension point for systems without a built-in adapter (GitLab,
+Buildkite, Jenkins, Bors, in-house queues). ``command`` is an argument list run
+without a shell. Locally it runs in ``cwd``, which defaults to the directory of
+the config file. With ``host`` set it runs over SSH, in ``cwd`` on that host
+when given. A nonzero exit, a timeout or output that breaks the contract is
+shown as a source error, and the last good data stays on screen.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from ..process import check_host, over_ssh, run_json
+from . import Adapter
+
+
+class Command(Adapter):
+    name = "command"
+    label = "Command"
+    interval = 15.0
+
+    def __init__(
+        self,
+        *,
+        command: list[str],
+        host: str | None = None,
+        cwd: str | None = None,
+        timeout: float = 25,
+        config_dir: Path | None = None,
+    ):
+        if (
+            not isinstance(command, list)
+            or not command
+            or not all(isinstance(arg, str) and arg for arg in command)
+        ):
+            raise ValueError(
+                'command must be a list of arguments, for example ["./status", "--json"]'
+            )
+        if isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or timeout <= 0:
+            raise ValueError("timeout must be a positive number of seconds")
+        self.command, self.host, self.timeout = command, check_host(host), float(timeout)
+        if self.host is not None:
+            self.cwd = cwd
+        else:
+            base = config_dir or Path.cwd()
+            self.cwd = str(base / os.path.expanduser(cwd)) if cwd else str(base)
+
+    async def snapshot(self) -> dict:
+        if self.host is not None:
+            return await run_json(over_ssh(self.host, self.command, self.cwd), timeout=self.timeout)
+        return await run_json(self.command, cwd=self.cwd, timeout=self.timeout)