pocketshell 0.1.0__py3-none-any.whl

pocketshell/__init__.py

@@ -0,0 +1,14 @@
+"""Unified server-side Python utility for the PocketShell Android client.
+
+This package is intended to replace the separately-installed `quse` and
+`tmuxctl` utilities the PocketShell app currently probes for. The first PR
+ships the skeleton plus the `pocketshell usage` subcommand only; later PRs
+will add `jobs`, `agent-log`, `sessions`, `repos`, and daemon mode.
+
+See https://github.com/alexeygrigorev/pocketshell/issues/170.
+"""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+__version__ = "0.1.0"

pocketshell/__main__.py

@@ -0,0 +1,14 @@
+"""Allow `python -m pocketshell` as an alternative to the installed entry point.
+
+Used in CI and developer environments where the console-script shim from
+`pip install -e .` / `uv tool install pocketshell-cli` is not on PATH.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from pocketshell.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

pocketshell/cli.py

@@ -0,0 +1,67 @@
+"""Top-level Click dispatcher for the unified `pocketshell` CLI.
+
+This is the skeleton landed in the first PR of issue
+[#170](https://github.com/alexeygrigorev/pocketshell/issues/170). Only the
+`usage` subcommand is wired up today; later PRs will add `jobs`,
+`agent-log`, `sessions`, `repos`, and `daemon`.
+
+Per the D22 locked principle (no backwards compatibility, hard cuts only)
+the eventual goal is for the PocketShell Android app to probe for this
+single binary instead of `quse` / `tmuxctl`. The first PR keeps the
+existing probes in place — parallel detection, not legacy detection — so
+the app keeps working while we ramp up `pocketshell`'s feature parity.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Optional, Sequence
+
+import click
+
+from pocketshell import __version__
+from pocketshell.usage import usage_command
+
+
+@click.group(
+    context_settings={"help_option_names": ["-h", "--help"]},
+    help=(
+        "Unified server-side helper for the PocketShell Android client.\n\n"
+        "Subcommands replace the separately-installed `quse` and `tmuxctl` "
+        "CLIs. The first PR ships `usage` only; more subcommands will land "
+        "in follow-up rounds."
+    ),
+)
+@click.version_option(__version__, "-V", "--version", prog_name="pocketshell")
+def cli() -> None:
+    """Top-level group. Each subcommand is registered below."""
+
+
+cli.add_command(usage_command, name="usage")
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    """Entrypoint for both the console-script and `python -m pocketshell`.
+
+    Returns an integer exit code rather than letting Click call
+    `sys.exit` so the function is testable from the unit suite.
+    """
+    try:
+        result = cli.main(args=list(argv) if argv is not None else None,
+                          prog_name="pocketshell",
+                          standalone_mode=False)
+    except click.exceptions.Exit as exc:
+        return int(exc.exit_code)
+    except click.ClickException as exc:
+        exc.show()
+        return int(exc.exit_code)
+    if result is None:
+        return 0
+    try:
+        return int(result)
+    except (TypeError, ValueError):
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pocketshell/usage.py

@@ -0,0 +1,115 @@
+"""`pocketshell usage` subcommand.
+
+First-PR implementation: delegate to the existing `quse` CLI via
+`subprocess.run`. The arguments and stdout are proxied through verbatim
+so the JSON payload (and human-readable lines) are byte-identical to
+`quse [provider] [--json]`. The existing Kotlin `QuseUsageJsonParser`
+keeps working when the Android app eventually switches its probe over.
+
+Why subprocess instead of `import quse`:
+
+- `quse` is currently not published to PyPI; declaring it as a normal
+  `pyproject.toml` dependency would break `uv tool install
+  pocketshell-cli` for any user (including the maintainer's dev box).
+- Subprocess delegation keeps `pocketshell-cli` decoupled from `quse`'s
+  internal module layout, so updates to `quse` don't break the wrapper.
+- The PATH-discovery story for `quse` is already solved on the app side
+  (see issue #41 + the `pathOverride` column on `HostEntity`). Wrapping
+  `quse` here means the app's existing PATH override mechanism keeps
+  working without re-implementation.
+
+Later PRs will fold the provider-detection logic in directly so
+`pocketshell-cli` is the canonical implementation and the subprocess
+hop disappears, but that is explicit non-scope here per the brief on
+issue [#170](https://github.com/alexeygrigorev/pocketshell/issues/170).
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from typing import Optional, Sequence
+
+import click
+
+
+def _resolve_quse_binary() -> Optional[str]:
+    """Locate the `quse` CLI on PATH, or return ``None`` if absent.
+
+    Pulled out as a function so the unit suite can monkeypatch it.
+    `shutil.which` returns the same path the user would see from
+    `command -v quse`, which is the probe the Android app already runs.
+    """
+    return shutil.which("quse")
+
+
+def _run_quse(args: Sequence[str]) -> int:
+    """Invoke `quse` with [args]; proxy stdout/stderr and exit code.
+
+    Using `subprocess.run(..., check=False)` and forwarding the captured
+    output rather than `os.execvp` keeps the call testable (the test
+    suite can monkeypatch `subprocess.run`) and lets us decorate the
+    failure mode with a friendly hint when `quse` is missing.
+    """
+    quse_path = _resolve_quse_binary()
+    if quse_path is None:
+        # Same wording the bootstrap sheet uses so the user sees a
+        # consistent message whether they hit the bin via `pocketshell
+        # usage` or the app's poll loop.
+        click.echo(
+            "pocketshell: `quse` is not installed on this host. "
+            "Install it via `uv tool install quse` or `pipx install quse` "
+            "and re-run.",
+            err=True,
+        )
+        return 127
+
+    completed = subprocess.run(
+        [quse_path, *args],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    # Echo verbatim so the JSON output is byte-identical to `quse --json`.
+    if completed.stdout:
+        sys.stdout.write(completed.stdout)
+    if completed.stderr:
+        sys.stderr.write(completed.stderr)
+    return completed.returncode
+
+
+@click.command(
+    context_settings={"help_option_names": ["-h", "--help"], "ignore_unknown_options": True},
+)
+@click.argument("provider", required=False)
+@click.option(
+    "--json",
+    "json_output",
+    is_flag=True,
+    help="Emit machine-readable JSON output identical to `quse --json`.",
+)
+@click.pass_context
+def usage_command(
+    ctx: click.Context,
+    provider: Optional[str] = None,
+    json_output: bool = False,
+) -> None:
+    """Report quota / usage for coding-agent providers on this host.
+
+    Delegates to the `quse` CLI via subprocess. Output shape (both human
+    and JSON) is byte-identical to `quse [provider] [--json]` so any
+    consumer that already parses `quse` output keeps working when the
+    PocketShell app routes through `pocketshell usage` instead.
+    """
+    args: list[str] = []
+    if provider:
+        args.append(provider)
+    if json_output:
+        args.append("--json")
+    exit_code = _run_quse(args)
+    # Click ignores the return value of a callback by default; we need to
+    # explicitly propagate non-zero exit codes through `ctx.exit` so the
+    # outer `main()` (and the OS) sees the same exit code `quse` reported.
+    if exit_code != 0:
+        ctx.exit(exit_code)

pocketshell-0.1.0.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: pocketshell
+Version: 0.1.0
+Summary: Unified server-side Python utility for the PocketShell Android client.
+Project-URL: Homepage, https://github.com/alexeygrigorev/pocketshell
+Project-URL: Issues, https://github.com/alexeygrigorev/pocketshell/issues
+Author: Alexey Grigorev
+License: MIT
+Keywords: agents,pocketshell,ssh,tmux,usage
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Software Development
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Requires-Dist: click>=8.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.15.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pocketshell-cli
+
+Unified server-side Python utility for the [PocketShell](https://github.com/alexeygrigorev/pocketshell)
+Android client. Replaces the separately-installed `quse` and `tmuxctl`
+utilities the app currently probes for on every remote host.
+
+This first release ships the **skeleton plus the `pocketshell usage`
+subcommand only**. Follow-up rounds will add `jobs`, `agent-log`,
+`sessions`, `repos`, and an optional daemon mode. See
+[issue #170](https://github.com/alexeygrigorev/pocketshell/issues/170) for
+the design spike and phased roll-out plan.
+
+## Install
+
+The recommended path is `uv tool install`, which lands the binary on PATH
+under `~/.local/bin/`:
+
+```bash
+uv tool install pocketshell-cli
+```
+
+For local development from a clone:
+
+```bash
+cd tools/pocketshell-cli
+uv venv
+uv pip install -e .
+pocketshell --help
+```
+
+`pipx install pocketshell-cli` works the same way for users who prefer
+pipx. Both install paths produce a `pocketshell` binary that the
+PocketShell app's bootstrap probe detects.
+
+## Usage
+
+```text
+pocketshell usage           # human-readable lines, one per provider
+pocketshell usage --json    # machine-readable JSON (consumed by the app)
+pocketshell usage codex     # filter to a single provider
+```
+
+The output shape is byte-identical to `quse [provider] [--json]` so any
+consumer that already parses `quse` output keeps working when the app
+routes through `pocketshell usage` instead. Under the hood the first
+release delegates to the `quse` CLI via subprocess; later rounds will
+fold the provider-detection logic in directly and drop the subprocess
+hop.
+
+If `quse` is not installed, `pocketshell usage` exits with code 127 and
+prints an install hint to stderr.
+
+## Development
+
+```bash
+cd tools/pocketshell-cli
+uv venv
+uv pip install -e ".[dev]"
+uv run pytest
+```
+
+Or via the dependency-group:
+
+```bash
+uv sync --group dev
+uv run pytest
+```
+
+The tests stub `quse.usage.collect_usage` so they run in seconds without
+hitting any provider API.
+
+## Why a unified CLI?
+
+The PocketShell app previously probed for two binaries (`quse`,
+`tmuxctl`) on every host. That meant two installs to keep up to date,
+two probes to surface failures from, and two PATH-discovery edge cases
+(see [issue #41](https://github.com/alexeygrigorev/pocketshell/issues/41)).
+A single `pocketshell` binary collapses those into one install, one
+probe, one bootstrap row. The app keeps detecting `quse` and `tmuxctl`
+as a parallel path while `pocketshell` ramps up to feature parity; once
+parity is reached, the legacy probes are removed in a hard-cut follow-up
+(no compat shim — see decision D22 in `docs/decisions.md`).

pocketshell-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+pocketshell/__init__.py,sha256=eFpihxo-FUOOyZmY5Xv9rbtU4n57-okAzai3FRHSJN0,517
+pocketshell/__main__.py,sha256=DQ0VPFw3Flj0Qm92SIEOKqKg6ESov4fcmxiWTTVKJ20,361
+pocketshell/cli.py,sha256=4PzpqH4E7tK39aKuH-BEA3WQ8gL5socFg1uujGP_1Yw,2221
+pocketshell/usage.py,sha256=JoefJo6TnuF5dinwb-tSH7Yp5xQIA1OTrDDa6mrFBvU,4271
+pocketshell-0.1.0.dist-info/METADATA,sha256=fyyPDngTt1eDZmJjENpdguzqymtdRCS-q4KcBbFiERU,3659
+pocketshell-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+pocketshell-0.1.0.dist-info/entry_points.txt,sha256=XR1LQMp6m3b5B1jQlNocYv5OZf9PJqxKIDWOdiqduHo,53
+pocketshell-0.1.0.dist-info/RECORD,,

pocketshell-0.1.0.dist-info/WHEEL

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

pocketshell-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pocketshell = pocketshell.cli:main