pocketshell 0.3.30__tar.gz → 0.3.31__tar.gz

{pocketshell-0.3.30 → pocketshell-0.3.31}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pocketshell
-Version: 0.3.30
+Version: 0.3.31
 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
@@ -81,6 +81,7 @@ pocketshell sessions list [--by activity]   # tmux session summaries
 pocketshell jobs ...                        # tmux recurring jobs
 pocketshell agent-log ...                   # agent conversation logs
 pocketshell repos list ...                  # local / GitHub repositories
+pocketshell github status [--json]          # gh install / auth state
 pocketshell env ...                         # .env / .envrc management
 pocketshell hooks ...                       # Claude/Codex/OpenCode hooks
 pocketshell logs ...                        # server-side trace sink
@@ -164,6 +165,36 @@ Daemon mode caches `repos.list_local` for 10 s and `repos.list_remote`
 for 5 min. `--no-daemon` forces the in-process path; `--no-cache`
 forces the daemon to re-run upstream on the next call.
 
+### `pocketshell github status`
+
+Reports whether the GitHub CLI (`gh`) is installed and authenticated, as
+structured JSON the app consumes to gate GitHub features and prompt the
+user to configure `gh` when it is missing (epic #644, slice #645).
+
+```bash
+pocketshell github status          # human-readable summary
+pocketshell github status --json   # machine-readable JSON (consumed by the app)
+```
+
+Schema:
+
+```json
+{
+  "installed": true,             // shutil.which("gh") found the binary
+  "authenticated": true,         // `gh auth status` exited 0
+  "account": "alexeygrigorev",   // logged-in username, or null
+  "hint": null                   // actionable hint when something is missing
+}
+```
+
+The command always exits 0 — "gh missing" and "not authenticated" are
+normal, reportable states (not probe failures), so the app can poll the
+status without treating it as an error. When `gh` is absent the `hint` tells
+the user to install it and run `gh auth login`; when present but
+unauthenticated the `hint` tells them to run `gh auth login`. The only
+network access is whatever `gh auth status` itself performs (a token-validity
+check); the command does NOT call the GitHub API.
+
 ### `pocketshell qr-share`
 
 Builds a `pocketshell.ssh-import.v1` payload from an `~/.ssh/config`

{pocketshell-0.3.30 → pocketshell-0.3.31}/README.md

@@ -53,6 +53,7 @@ pocketshell sessions list [--by activity]   # tmux session summaries
 pocketshell jobs ...                        # tmux recurring jobs
 pocketshell agent-log ...                   # agent conversation logs
 pocketshell repos list ...                  # local / GitHub repositories
+pocketshell github status [--json]          # gh install / auth state
 pocketshell env ...                         # .env / .envrc management
 pocketshell hooks ...                       # Claude/Codex/OpenCode hooks
 pocketshell logs ...                        # server-side trace sink
@@ -136,6 +137,36 @@ Daemon mode caches `repos.list_local` for 10 s and `repos.list_remote`
 for 5 min. `--no-daemon` forces the in-process path; `--no-cache`
 forces the daemon to re-run upstream on the next call.
 
+### `pocketshell github status`
+
+Reports whether the GitHub CLI (`gh`) is installed and authenticated, as
+structured JSON the app consumes to gate GitHub features and prompt the
+user to configure `gh` when it is missing (epic #644, slice #645).
+
+```bash
+pocketshell github status          # human-readable summary
+pocketshell github status --json   # machine-readable JSON (consumed by the app)
+```
+
+Schema:
+
+```json
+{
+  "installed": true,             // shutil.which("gh") found the binary
+  "authenticated": true,         // `gh auth status` exited 0
+  "account": "alexeygrigorev",   // logged-in username, or null
+  "hint": null                   // actionable hint when something is missing
+}
+```
+
+The command always exits 0 — "gh missing" and "not authenticated" are
+normal, reportable states (not probe failures), so the app can poll the
+status without treating it as an error. When `gh` is absent the `hint` tells
+the user to install it and run `gh auth login`; when present but
+unauthenticated the `hint` tells them to run `gh auth login`. The only
+network access is whatever `gh auth status` itself performs (a token-validity
+check); the command does NOT call the GitHub API.
+
 ### `pocketshell qr-share`
 
 Builds a `pocketshell.ssh-import.v1` payload from an `~/.ssh/config`

{pocketshell-0.3.30 → pocketshell-0.3.31}/pyproject.toml

@@ -8,7 +8,7 @@ name = "pocketshell"
 # scripts/check-pypi-version.sh enforces this; .github/workflows/build.yml
 # runs that check before publishing to PyPI. See
 # tools/pocketshell/README.md ("Release flow") for the bump procedure.
-version = "0.3.30"
+version = "0.3.31"
 description = "Unified server-side Python utility for the PocketShell Android client."
 readme = "README.md"
 requires-python = ">=3.11"

{pocketshell-0.3.30 → pocketshell-0.3.31}/src/pocketshell/cli.py

@@ -24,6 +24,7 @@ import click
 from pocketshell import __version__
 from pocketshell.agent_log import agent_log_command
 from pocketshell.env import env_group
+from pocketshell.github import github_group
 from pocketshell.hooks import hooks_group
 from pocketshell.jobs import jobs_group
 from pocketshell.logs import logs_group
@@ -39,8 +40,8 @@ from pocketshell.usage import usage_command
         "Unified server-side helper for the PocketShell Android client.\n\n"
         "Subcommands replace the separately-installed `quse`, `tmuxctl`, "
         "and `qr-share` CLIs. Today `usage`, `jobs`, `sessions`, "
-        "`agent-log`, `repos`, `daemon`, and `qr-share` are wired up; "
-        "more subcommands will land in follow-up rounds."
+        "`agent-log`, `repos`, `github`, `daemon`, and `qr-share` are wired "
+        "up; more subcommands will land in follow-up rounds."
     ),
 )
 @click.version_option(__version__, "-V", "--version", prog_name="pocketshell")
@@ -53,6 +54,7 @@ cli.add_command(jobs_group, name="jobs")
 cli.add_command(sessions_group, name="sessions")
 cli.add_command(agent_log_command, name="agent-log")
 cli.add_command(repos_group, name="repos")
+cli.add_command(github_group, name="github")
 cli.add_command(env_group, name="env")
 cli.add_command(hooks_group, name="hooks")
 cli.add_command(logs_group, name="logs")

pocketshell-0.3.31/src/pocketshell/github.py

@@ -0,0 +1,174 @@
+"""`pocketshell github` subcommand group.
+
+First slice of the Git + GitHub integration epic
+([#644](https://github.com/alexeygrigorev/pocketshell/issues/644), slice 1 is
+[#645](https://github.com/alexeygrigorev/pocketshell/issues/645)).
+
+Server-side foundation: report whether the GitHub CLI (`gh`) is **installed**
+and **authenticated** as structured JSON the Android app can consume to gate
+GitHub features and show a "configure gh" hint when the tooling is missing.
+
+Unlike `pocketshell sessions`/`usage`, which proxy another binary's output
+byte-for-byte, this command generates its own JSON envelope. The shape is:
+
+```json
+{
+  "installed": true,
+  "authenticated": true,
+  "account": "alexeygrigorev",
+  "hint": null
+}
+```
+
+- `installed` — `shutil.which("gh")` found the binary on PATH.
+- `authenticated` — `gh auth status` exited 0 (a token is present and valid).
+- `account` — the logged-in GitHub username parsed from `gh auth status`,
+  or `null` when it could not be determined / not authenticated.
+- `hint` — a short, actionable string when something is missing (install `gh`,
+  or run `gh auth login`), or `null` when everything is ready.
+
+Why subprocess (`gh auth status`) instead of reading `~/.config/gh/hosts.yml`
+directly: `gh auth status` is the canonical liveness/validity check the user
+themselves would run, it validates the token rather than just checking that a
+config file exists, and it keeps this command decoupled from gh's on-disk
+layout. No network call beyond what `gh auth status` itself performs (a single
+token-validity check); the command does NOT hit the GitHub API.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+from typing import Optional
+
+import click
+
+# Hints surfaced to the user (and the app) when tooling is missing. Kept as
+# module constants so the test suite can assert on the exact wording.
+INSTALL_HINT = (
+    "install gh (https://cli.github.com) and run `gh auth login`"
+)
+AUTH_HINT = "run `gh auth login` to authenticate the GitHub CLI"
+
+# `gh auth status` prints e.g.
+#   ✓ Logged in to github.com account alexeygrigorev (keyring)
+# across gh versions. Capture the username after "account ".
+_ACCOUNT_RE = re.compile(r"account\s+(\S+)")
+
+
+def _resolve_gh_binary() -> Optional[str]:
+    """Locate the `gh` 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 gh`, which is the probe the app's bootstrap already runs.
+    """
+    return shutil.which("gh")
+
+
+def _run_gh_auth_status(gh_path: str) -> subprocess.CompletedProcess:
+    """Invoke ``gh auth status`` and capture its output.
+
+    Modern `gh` writes the status report to stdout on success and to
+    stderr when unauthenticated; we capture both and parse whichever
+    carries the text. The exit code is the authoritative auth signal.
+    """
+    return subprocess.run(
+        [gh_path, "auth", "status"],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+
+
+def _parse_account(text: str) -> Optional[str]:
+    """Best-effort extract of the logged-in GitHub username from gh output."""
+    match = _ACCOUNT_RE.search(text)
+    if match:
+        return match.group(1)
+    return None
+
+
+def gh_status() -> dict[str, object]:
+    """Build the structured gh install/auth status envelope.
+
+    Returns a plain dict with the stable shape documented at module level so
+    both the CLI (`--json`) and any in-process caller can reuse it.
+    """
+    gh_path = _resolve_gh_binary()
+    if gh_path is None:
+        return {
+            "installed": False,
+            "authenticated": False,
+            "account": None,
+            "hint": INSTALL_HINT,
+        }
+
+    completed = _run_gh_auth_status(gh_path)
+    authenticated = completed.returncode == 0
+    # `gh auth status` puts the report on stdout (authed) or stderr
+    # (unauthed) depending on version; scan both so account parsing is
+    # robust across gh releases.
+    combined = (completed.stdout or "") + "\n" + (completed.stderr or "")
+    account = _parse_account(combined) if authenticated else None
+
+    return {
+        "installed": True,
+        "authenticated": authenticated,
+        "account": account,
+        "hint": None if authenticated else AUTH_HINT,
+    }
+
+
+@click.group(
+    name="github",
+    context_settings={"help_option_names": ["-h", "--help"]},
+    help=(
+        "GitHub CLI (`gh`) integration helpers.\n\n"
+        "`status` reports whether `gh` is installed and authenticated as "
+        "structured JSON the PocketShell app uses to gate GitHub features "
+        "and prompt the user to configure `gh` when it is missing (issue "
+        "#645)."
+    ),
+)
+def github_group() -> None:
+    """Top-level group registered onto the root `pocketshell` CLI."""
+
+
+@github_group.command(
+    "status",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+@click.option(
+    "--json",
+    "as_json",
+    is_flag=True,
+    help="Emit the status as a single-line JSON object (consumed by the app).",
+)
+@click.pass_context
+def github_status(ctx: click.Context, as_json: bool) -> None:
+    """Report whether `gh` is installed and authenticated.
+
+    With ``--json`` emits a one-line JSON object the app parses to gate
+    GitHub features; without it prints a short human-readable summary. The
+    command always exits 0 — "gh missing" / "not authenticated" are normal,
+    reportable states, not errors, so the app can poll the status without
+    treating it as a failed probe.
+    """
+    status = gh_status()
+    if as_json:
+        click.echo(json.dumps(status, sort_keys=True))
+        return
+
+    if not status["installed"]:
+        click.echo("gh: not installed")
+        click.echo(f"hint: {status['hint']}")
+        return
+    if not status["authenticated"]:
+        click.echo("gh: installed, not authenticated")
+        click.echo(f"hint: {status['hint']}")
+        return
+    account = status["account"] or "(unknown account)"
+    click.echo(f"gh: installed, authenticated as {account}")

pocketshell-0.3.31/tests/test_github.py

@@ -0,0 +1,270 @@
+"""Unit tests for `pocketshell github status`.
+
+First slice of the Git + GitHub integration epic (#644 / #645). Exercises:
+
+- `pocketshell --help` lists the `github` subcommand.
+- `pocketshell github --help` lists the `status` subcommand.
+- gh missing (`shutil.which` -> None): installed=False, authenticated=False,
+  install hint present, account null.
+- gh installed but unauthenticated (`gh auth status` exit != 0):
+  installed=True, authenticated=False, auth hint present, account null.
+- gh installed and authenticated (`gh auth status` exit 0): installed=True,
+  authenticated=True, account parsed, hint null.
+- The `--json` envelope shape is stable and machine-parseable.
+- The command exits 0 in every state (missing/unauthed are reportable
+  states, not probe failures).
+- Human (non-JSON) output for each state.
+
+The tests stub `pocketshell.github._resolve_gh_binary` and
+`subprocess.run` so they never invoke a real `gh` binary or hit the
+network; the contract under test is "pocketshell reports gh state
+correctly", not "the GitHub CLI works".
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from typing import Sequence
+from unittest.mock import patch
+
+from click.testing import CliRunner
+
+from pocketshell.cli import cli
+from pocketshell.github import (
+    AUTH_HINT,
+    INSTALL_HINT,
+    gh_status,
+    github_group,
+)
+
+
+def _fake_completed(
+    stdout: str = "",
+    stderr: str = "",
+    returncode: int = 0,
+) -> subprocess.CompletedProcess:
+    return subprocess.CompletedProcess(
+        args=[],
+        returncode=returncode,
+        stdout=stdout,
+        stderr=stderr,
+    )
+
+
+# Realistic `gh auth status` output for an authenticated host (gh 2.x puts
+# this on stdout with exit 0).
+_AUTHED_STDOUT = (
+    "github.com\n"
+    "  ✓ Logged in to github.com account alexeygrigorev "
+    "(/home/alexey/.config/gh/hosts.yml)\n"
+    "  - Active account: true\n"
+    "  - Git operations protocol: ssh\n"
+    "  - Token scopes: 'repo', 'read:org'\n"
+)
+
+# `gh auth status` when no token is configured: non-zero exit, text on stderr.
+_UNAUTHED_STDERR = (
+    "You are not logged into any GitHub hosts. "
+    "To log in, run: gh auth login\n"
+)
+
+
+# ----- help wiring ---------------------------------------------------
+
+
+def test_top_level_help_lists_github_subcommand() -> None:
+    runner = CliRunner()
+    result = runner.invoke(cli, ["--help"])
+    assert result.exit_code == 0, result.output
+    assert "github" in result.output
+
+
+def test_github_help_lists_status_subcommand() -> None:
+    runner = CliRunner()
+    with patch("pocketshell.github.subprocess.run") as run:
+        result = runner.invoke(github_group, ["--help"])
+    assert result.exit_code == 0, result.output
+    assert "status" in result.output
+    run.assert_not_called()
+
+
+# ----- gh missing ----------------------------------------------------
+
+
+def test_status_json_when_gh_missing() -> None:
+    runner = CliRunner()
+    with patch(
+        "pocketshell.github._resolve_gh_binary", return_value=None
+    ), patch("pocketshell.github.subprocess.run") as run:
+        result = runner.invoke(github_group, ["status", "--json"])
+    assert result.exit_code == 0, result.output
+    payload = json.loads(result.output)
+    assert payload == {
+        "installed": False,
+        "authenticated": False,
+        "account": None,
+        "hint": INSTALL_HINT,
+    }
+    # gh missing -> we must NOT have tried to run `gh auth status`.
+    run.assert_not_called()
+
+
+def test_status_human_when_gh_missing() -> None:
+    runner = CliRunner()
+    with patch("pocketshell.github._resolve_gh_binary", return_value=None):
+        result = runner.invoke(github_group, ["status"])
+    assert result.exit_code == 0, result.output
+    assert "not installed" in result.output
+    assert INSTALL_HINT in result.output
+
+
+# ----- gh installed but unauthenticated ------------------------------
+
+
+def test_status_json_when_installed_unauthed() -> None:
+    runner = CliRunner()
+    with patch(
+        "pocketshell.github._resolve_gh_binary", return_value="/fake/gh"
+    ), patch(
+        "pocketshell.github.subprocess.run",
+        return_value=_fake_completed(stderr=_UNAUTHED_STDERR, returncode=1),
+    ) as run:
+        result = runner.invoke(github_group, ["status", "--json"])
+    assert result.exit_code == 0, result.output
+    payload = json.loads(result.output)
+    assert payload == {
+        "installed": True,
+        "authenticated": False,
+        "account": None,
+        "hint": AUTH_HINT,
+    }
+    invoked: Sequence[str] = run.call_args.args[0]
+    assert invoked == ["/fake/gh", "auth", "status"]
+
+
+def test_status_human_when_installed_unauthed() -> None:
+    runner = CliRunner()
+    with patch(
+        "pocketshell.github._resolve_gh_binary", return_value="/fake/gh"
+    ), patch(
+        "pocketshell.github.subprocess.run",
+        return_value=_fake_completed(stderr=_UNAUTHED_STDERR, returncode=1),
+    ):
+        result = runner.invoke(github_group, ["status"])
+    assert result.exit_code == 0, result.output
+    assert "not authenticated" in result.output
+    assert AUTH_HINT in result.output
+
+
+# ----- gh installed and authenticated --------------------------------
+
+
+def test_status_json_when_installed_authed() -> None:
+    runner = CliRunner()
+    with patch(
+        "pocketshell.github._resolve_gh_binary", return_value="/fake/gh"
+    ), patch(
+        "pocketshell.github.subprocess.run",
+        return_value=_fake_completed(stdout=_AUTHED_STDOUT, returncode=0),
+    ) as run:
+        result = runner.invoke(github_group, ["status", "--json"])
+    assert result.exit_code == 0, result.output
+    payload = json.loads(result.output)
+    assert payload == {
+        "installed": True,
+        "authenticated": True,
+        "account": "alexeygrigorev",
+        "hint": None,
+    }
+    invoked: Sequence[str] = run.call_args.args[0]
+    assert invoked == ["/fake/gh", "auth", "status"]
+
+
+def test_status_human_when_installed_authed() -> None:
+    runner = CliRunner()
+    with patch(
+        "pocketshell.github._resolve_gh_binary", return_value="/fake/gh"
+    ), patch(
+        "pocketshell.github.subprocess.run",
+        return_value=_fake_completed(stdout=_AUTHED_STDOUT, returncode=0),
+    ):
+        result = runner.invoke(github_group, ["status"])
+    assert result.exit_code == 0, result.output
+    assert "authenticated as alexeygrigorev" in result.output
+
+
+def test_status_authed_account_parsed_from_stderr_variant() -> None:
+    """Older gh writes the report to stderr even when exit code is 0.
+
+    Account parsing must scan both streams, so a stderr-only authed report
+    still yields the username.
+    """
+    runner = CliRunner()
+    with patch(
+        "pocketshell.github._resolve_gh_binary", return_value="/fake/gh"
+    ), patch(
+        "pocketshell.github.subprocess.run",
+        return_value=_fake_completed(stderr=_AUTHED_STDOUT, returncode=0),
+    ):
+        result = runner.invoke(github_group, ["status", "--json"])
+    assert result.exit_code == 0, result.output
+    payload = json.loads(result.output)
+    assert payload["authenticated"] is True
+    assert payload["account"] == "alexeygrigorev"
+
+
+def test_status_authed_without_parseable_account_yields_null() -> None:
+    """Authenticated but no parseable 'account <name>' -> account null, still authed."""
+    runner = CliRunner()
+    with patch(
+        "pocketshell.github._resolve_gh_binary", return_value="/fake/gh"
+    ), patch(
+        "pocketshell.github.subprocess.run",
+        return_value=_fake_completed(stdout="Logged in to github.com\n", returncode=0),
+    ):
+        result = runner.invoke(github_group, ["status", "--json"])
+    assert result.exit_code == 0, result.output
+    payload = json.loads(result.output)
+    assert payload["authenticated"] is True
+    assert payload["account"] is None
+    assert payload["hint"] is None
+
+
+# ----- JSON shape contract -------------------------------------------
+
+
+def test_json_envelope_shape_has_exact_keys() -> None:
+    """The app depends on a fixed key set; pin it so a rename is caught."""
+    runner = CliRunner()
+    with patch(
+        "pocketshell.github._resolve_gh_binary", return_value="/fake/gh"
+    ), patch(
+        "pocketshell.github.subprocess.run",
+        return_value=_fake_completed(stdout=_AUTHED_STDOUT, returncode=0),
+    ):
+        result = runner.invoke(github_group, ["status", "--json"])
+    payload = json.loads(result.output)
+    assert set(payload.keys()) == {
+        "installed",
+        "authenticated",
+        "account",
+        "hint",
+    }
+    # Single-line output so the app can read one line off stdout.
+    assert result.output.strip().count("\n") == 0
+
+
+# ----- in-process helper ---------------------------------------------
+
+
+def test_gh_status_helper_returns_dict_without_gh() -> None:
+    """The reusable `gh_status()` helper works independent of the CLI layer."""
+    with patch("pocketshell.github._resolve_gh_binary", return_value=None):
+        status = gh_status()
+    assert status == {
+        "installed": False,
+        "authenticated": False,
+        "account": None,
+        "hint": INSTALL_HINT,
+    }

{pocketshell-0.3.30 → pocketshell-0.3.31}/uv.lock

@@ -3,7 +3,7 @@ revision = 3
 requires-python = ">=3.11"
 
 [options]
-exclude-newer = "2026-05-30T11:30:48.503303377Z"
+exclude-newer = "2026-06-03T14:05:02.806775926Z"
 exclude-newer-span = "P7D"
 
 [[package]]
@@ -143,7 +143,7 @@ wheels = [
 
 [[package]]
 name = "pocketshell"
-version = "0.3.29"
+version = "0.3.30"
 source = { editable = "." }
 dependencies = [
     { name = "click" },