pocketshell 0.3.29__tar.gz → 0.3.31__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pocketshell
-Version: 0.3.29
+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.29 → 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.29 → 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.29"
+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.29 → 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.29 → pocketshell-0.3.31}/src/pocketshell/usage.py

@@ -61,6 +61,17 @@ import click
 
 _CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage"
 _CODEX_AUTH_PATH = Path.home() / ".codex" / "auth.json"
+_CODEX_COMPATIBLE_PROVIDERS = {
+    "codex",
+    "openai",
+    "openai-codex",
+    "openai_codex",
+    "chatgpt",
+}
+_CLAUDE_USAGE_AUTH_SETUP_MESSAGE = (
+    "Claude usage authentication needs setup on this host. "
+    "Open Claude Code on the host and complete sign-in, then refresh usage."
+)
 
 
 def _resolve_quse_binary() -> Optional[str]:
@@ -151,16 +162,78 @@ def _percent_remaining_from_used(value: Any) -> Optional[float]:
     return round(max(0.0, min(100.0, 100.0 - used)), 2)
 
 
-def _window_from_detail(detail: Any) -> Optional[dict[str, Any]]:
+def _reset_after_seconds_to_iso(
+    value: Any,
+    *,
+    now: Optional[datetime] = None,
+) -> Optional[str]:
+    if value is None:
+        return None
+    try:
+        seconds = float(value)
+    except (TypeError, ValueError):
+        return None
+    if seconds < 0:
+        return None
+    base = now or datetime.now(timezone.utc)
+    if base.tzinfo is None:
+        base = base.replace(tzinfo=timezone.utc)
+    reset_at = base.astimezone(timezone.utc).timestamp() + seconds
+    try:
+        parsed = datetime.fromtimestamp(reset_at, tz=timezone.utc)
+    except (OverflowError, OSError, ValueError):
+        return None
+    return parsed.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _window_label_from_seconds(value: Any) -> Optional[str]:
+    try:
+        seconds = int(float(value))
+    except (TypeError, ValueError, OverflowError):
+        return None
+    if seconds <= 0:
+        return None
+    units = (
+        (24 * 60 * 60, "d"),
+        (60 * 60, "h"),
+        (60, "m"),
+    )
+    for unit_seconds, suffix in units:
+        if seconds >= unit_seconds and seconds % unit_seconds == 0:
+            return f"{seconds // unit_seconds}{suffix}"
+    return f"{seconds}s"
+
+
+def _window_label_from_detail(detail: dict[str, Any]) -> Optional[str]:
+    label = _window_label_from_seconds(detail.get("limit_window_seconds"))
+    if label is not None:
+        return label
+    try:
+        minutes = float(detail.get("window_minutes"))
+    except (TypeError, ValueError):
+        return None
+    return _window_label_from_seconds(minutes * 60)
+
+
+def _window_from_detail(
+    detail: Any,
+    *,
+    now: Optional[datetime] = None,
+) -> Optional[dict[str, Any]]:
     if not isinstance(detail, dict):
         return None
     percent_remaining = _percent_remaining_from_used(detail.get("used_percent"))
-    reset_at = _normalize_reset_at(detail.get("reset_at"))
-    if percent_remaining is None and reset_at is None:
+    reset_at = _normalize_reset_at(detail.get("reset_at")) or _reset_after_seconds_to_iso(
+        detail.get("reset_after_seconds"),
+        now=now,
+    )
+    window = _window_label_from_detail(detail)
+    if percent_remaining is None and reset_at is None and window is None:
         return None
     return {
         "percent_remaining": percent_remaining,
         "reset_at": reset_at,
+        "window": window,
     }
 
 
@@ -169,6 +242,7 @@ def _merge_window(
     detail: Any,
     *,
     prefer_detail_percent: bool = False,
+    now: Optional[datetime] = None,
 ) -> Any:
     if not isinstance(current, dict):
         if not isinstance(detail, dict):
@@ -177,14 +251,21 @@ def _merge_window(
     else:
         current = dict(current)
 
-    detail_window = _window_from_detail(detail)
+    detail_window = _window_from_detail(detail, now=now)
     if detail_window is not None:
         if prefer_detail_percent or current.get("percent_remaining") is None:
             current["percent_remaining"] = detail_window.get("percent_remaining")
         if current.get("reset_at") is None:
             current["reset_at"] = detail_window.get("reset_at")
+        if current.get("window") is None and detail_window.get("window") is not None:
+            current["window"] = detail_window.get("window")
 
-    current["reset_at"] = _normalize_reset_at(current.get("reset_at"))
+    reset_after_seconds = current.get("reset_after_seconds")
+    current["reset_at"] = _normalize_reset_at(current.get("reset_at")) or _reset_after_seconds_to_iso(
+        reset_after_seconds,
+        now=now,
+    )
+    current.pop("reset_after_seconds", None)
     return current
 
 
@@ -195,15 +276,19 @@ def _actionable_error(provider: str, error: Any) -> Optional[str]:
     if not text:
         return None
     lower = text.lower()
+    if provider == "claude" and (
+        "claude " + "/login" in lower
+        or "run `claude" in lower
+        or "run claude" in lower
+        or "authentication " + "failed" in lower
+    ):
+        return _CLAUDE_USAGE_AUTH_SETUP_MESSAGE
     if provider == "claude" and (
         "http error 401" in lower
         or "unauthorized" in lower
         or lower in {"no-credentials", "no credentials"}
     ):
-        return (
-            "Claude Code authentication failed on this host. "
-            "Run `claude /login` in the host shell, then refresh usage."
-        )
+        return _CLAUDE_USAGE_AUTH_SETUP_MESSAGE
     if provider == "codex" and lower in {"no auth token", "no-auth-token", "no credentials"}:
         return (
             "Codex authentication is missing on this host. "
@@ -261,14 +346,30 @@ def _codex_needs_source_patch(record: dict[str, Any], detail_windows: dict[str,
     ):
         top_level = record.get(top_level_key)
         detail = detail_windows.get(detail_key)
-        top_level_reset = top_level.get("reset_at") if isinstance(top_level, dict) else None
-        detail_reset = detail.get("reset_at") if isinstance(detail, dict) else None
+        top_level_reset = None
+        if isinstance(top_level, dict):
+            top_level_reset = top_level.get("reset_at")
+            if top_level_reset is None:
+                top_level_reset = top_level.get("reset_after_seconds")
+        detail_reset = None
+        if isinstance(detail, dict):
+            detail_reset = detail.get("reset_at")
+            if detail_reset is None:
+                detail_reset = detail.get("reset_after_seconds")
         if top_level_reset is None and detail_reset is None:
             return True
     return False
 
 
-def normalize_usage_record(record: dict[str, Any]) -> dict[str, Any]:
+def _is_codex_compatible_provider(provider: str) -> bool:
+    return provider.replace(" ", "_").lower() in _CODEX_COMPATIBLE_PROVIDERS
+
+
+def normalize_usage_record(
+    record: dict[str, Any],
+    *,
+    now: Optional[datetime] = None,
+) -> dict[str, Any]:
     """Normalize a provider record emitted by ``quse --json``.
 
     PocketShell owns the app-facing schema even when it delegates provider
@@ -282,7 +383,7 @@ def normalize_usage_record(record: dict[str, Any]) -> dict[str, Any]:
     if not isinstance(detail_windows, dict):
         detail_windows = {}
 
-    if provider == "codex":
+    if _is_codex_compatible_provider(provider):
         # Codex's ChatGPT usage response exposes the real primary/secondary
         # windows under details. Older quse versions hard-code short_term to
         # 100% and lose epoch reset timestamps, which regressed issue #501.
@@ -297,6 +398,7 @@ def normalize_usage_record(record: dict[str, Any]) -> dict[str, Any]:
             normalized.get("short_term"),
             detail_windows.get("primary_window"),
             prefer_detail_percent=True,
+            now=now,
         )
         if short_term is not None:
             normalized["short_term"] = short_term
@@ -304,6 +406,7 @@ def normalize_usage_record(record: dict[str, Any]) -> dict[str, Any]:
             normalized.get("long_term"),
             detail_windows.get("secondary_window"),
             prefer_detail_percent=True,
+            now=now,
         )
         if long_term is not None:
             normalized["long_term"] = long_term
@@ -311,20 +414,22 @@ def normalize_usage_record(record: dict[str, Any]) -> dict[str, Any]:
         short_term = _merge_window(
             normalized.get("short_term"),
             detail_windows.get("five_hour"),
+            now=now,
         )
         if short_term is not None:
             normalized["short_term"] = short_term
         long_term = _merge_window(
             normalized.get("long_term"),
             detail_windows.get("seven_day"),
+            now=now,
         )
         if long_term is not None:
             normalized["long_term"] = long_term
     else:
         if isinstance(normalized.get("short_term"), dict):
-            normalized["short_term"] = _merge_window(normalized.get("short_term"), None)
+            normalized["short_term"] = _merge_window(normalized.get("short_term"), None, now=now)
         if isinstance(normalized.get("long_term"), dict):
-            normalized["long_term"] = _merge_window(normalized.get("long_term"), None)
+            normalized["long_term"] = _merge_window(normalized.get("long_term"), None, now=now)
 
     actionable = _actionable_error(provider, normalized.get("error"))
     if actionable != normalized.get("error"):
@@ -332,7 +437,11 @@ def normalize_usage_record(record: dict[str, Any]) -> dict[str, Any]:
     return normalized
 
 
-def normalize_usage_stdout(stdout: str) -> str:
+def normalize_usage_stdout(
+    stdout: str,
+    *,
+    now: Optional[datetime] = None,
+) -> str:
     """Normalize NDJSON stdout from ``quse --json`` for app consumption."""
     if not stdout.strip():
         return stdout
@@ -348,7 +457,7 @@ def normalize_usage_stdout(stdout: str) -> str:
             return stdout
         if not isinstance(parsed, dict):
             return stdout
-        normalized = normalize_usage_record(parsed)
+        normalized = normalize_usage_record(parsed, now=now)
         changed = changed or normalized != parsed
         lines.append(json.dumps(normalized, sort_keys=True))
     suffix = "\n" if stdout.endswith("\n") else ""

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.29 → pocketshell-0.3.31}/tests/test_usage.py

@@ -20,13 +20,19 @@ from __future__ import annotations
 
 import json
 import subprocess
+from datetime import datetime, timezone
 from typing import Sequence
 from unittest.mock import patch
 
 from click.testing import CliRunner
 
 from pocketshell.cli import cli, main
-from pocketshell.usage import usage_command
+from pocketshell.usage import (
+    _CLAUDE_USAGE_AUTH_SETUP_MESSAGE,
+    _actionable_error,
+    normalize_usage_record,
+    usage_command,
+)
 
 
 def _fake_completed(
@@ -112,10 +118,12 @@ def test_usage_json_normalizes_codex_detail_windows_and_epoch_resets() -> None:
                         "windows": {
                             "primary_window": {
                                 "used_percent": 12,
+                                "limit_window_seconds": 18000,
                                 "reset_at": 1780828285,
                             },
                             "secondary_window": {
                                 "used_percent": 31,
+                                "limit_window_seconds": 604800,
                                 "reset_at": 1781137638,
                             },
                         },
@@ -148,15 +156,29 @@ def test_usage_json_normalizes_codex_detail_windows_and_epoch_resets() -> None:
     assert codex["short_term"] == {
         "percent_remaining": 88.0,
         "reset_at": "2026-06-07T10:31:25Z",
+        "window": "5h",
     }
     assert codex["long_term"] == {
         "percent_remaining": 69.0,
         "reset_at": "2026-06-11T00:27:18Z",
+        "window": "7d",
     }
-    assert "claude /login" in lines[1]["error"]
+    assert lines[1]["error"] == _CLAUDE_USAGE_AUTH_SETUP_MESSAGE
+    assert "claude " + "/login" not in lines[1]["error"]
+    assert "authentication " + "failed" not in lines[1]["error"].lower()
     assert "HTTP Error 401" not in lines[1]["error"]
 
 
+def test_claude_stale_auth_telemetry_error_is_usage_unavailable() -> None:
+    stale_error = (
+        "Claude Code authentication "
+        + "failed on this host. Run `claude "
+        + "/login` in the host shell."
+    )
+
+    assert _actionable_error("claude", stale_error) == _CLAUDE_USAGE_AUTH_SETUP_MESSAGE
+
+
 def test_usage_json_patches_codex_resets_from_source_when_quse_dropped_them() -> None:
     raw = json.dumps(
         {
@@ -182,8 +204,16 @@ def test_usage_json_patches_codex_resets_from_source_when_quse_dropped_them() ->
     ), patch(
         "pocketshell.usage._fetch_codex_detail_windows",
         return_value={
-            "primary_window": {"used_percent": 13, "reset_at": 1780828285},
-            "secondary_window": {"used_percent": 31, "reset_at": 1781137638},
+            "primary_window": {
+                "used_percent": 13,
+                "limit_window_seconds": 18000,
+                "reset_at": 1780828285,
+            },
+            "secondary_window": {
+                "used_percent": 31,
+                "limit_window_seconds": 604800,
+                "reset_at": 1781137638,
+            },
         },
     ):
         result = runner.invoke(usage_command, ["--json"])
@@ -193,10 +223,124 @@ def test_usage_json_patches_codex_resets_from_source_when_quse_dropped_them() ->
     assert codex["short_term"] == {
         "percent_remaining": 87.0,
         "reset_at": "2026-06-07T10:31:25Z",
+        "window": "5h",
     }
     assert codex["long_term"] == {
         "percent_remaining": 69.0,
         "reset_at": "2026-06-11T00:27:18Z",
+        "window": "7d",
+    }
+
+
+def test_usage_json_normalizes_openai_compatible_detail_windows() -> None:
+    raw = json.dumps(
+        {
+            "provider": "openai",
+            "status": "ok",
+            "short_term": {"percent_remaining": 100.0, "reset_at": None},
+            "long_term": {"percent_remaining": 35.0, "reset_at": None},
+            "block_reason": None,
+            "error": None,
+            "details": {
+                "windows": {
+                    "primary_window": {
+                        "used_percent": 22,
+                        "limit_window_seconds": 18000,
+                        "reset_at": "2026-06-08T02:19:59Z",
+                    },
+                    "secondary_window": {
+                        "used_percent": 65,
+                        "limit_window_seconds": 604800,
+                        "reset_at": "2026-06-11T00:27:17Z",
+                    },
+                },
+            },
+        },
+    )
+    runner = CliRunner()
+    with patch("pocketshell.usage._resolve_quse_binary", return_value="/fake/quse"), patch(
+        "pocketshell.usage.subprocess.run",
+        return_value=_fake_completed(stdout=raw + "\n"),
+    ):
+        result = runner.invoke(usage_command, ["--json"])
+
+    assert result.exit_code == 0, result.output
+    record = json.loads(result.output)
+    assert record["short_term"] == {
+        "percent_remaining": 78.0,
+        "reset_at": "2026-06-08T02:19:59Z",
+        "window": "5h",
+    }
+    assert record["long_term"] == {
+        "percent_remaining": 35.0,
+        "reset_at": "2026-06-11T00:27:17Z",
+        "window": "7d",
+    }
+
+
+def test_normalize_usage_record_preserves_codex_reset_after_seconds() -> None:
+    record = normalize_usage_record(
+        {
+            "provider": "codex",
+            "status": "ok",
+            "short_term": {"percent_remaining": 35.0, "reset_at": None},
+            "long_term": {"percent_remaining": 69.0, "reset_at": None},
+            "block_reason": None,
+            "error": None,
+            "details": {
+                "windows": {
+                    "primary_window": {
+                        "used_percent": 65,
+                        "window_minutes": 300,
+                        "reset_after_seconds": 3600,
+                    },
+                    "secondary_window": {
+                        "used_percent": 31,
+                        "limit_window_seconds": 604800,
+                        "reset_after_seconds": "604800",
+                    },
+                },
+            },
+        },
+        now=datetime(2026, 6, 8, 10, 0, tzinfo=timezone.utc),
+    )
+
+    assert record["short_term"] == {
+        "percent_remaining": 35.0,
+        "reset_at": "2026-06-08T11:00:00Z",
+        "window": "5h",
+    }
+    assert record["long_term"] == {
+        "percent_remaining": 69.0,
+        "reset_at": "2026-06-15T10:00:00Z",
+        "window": "7d",
+    }
+
+
+def test_normalize_usage_record_converts_top_level_reset_after_seconds() -> None:
+    with patch("pocketshell.usage._fetch_codex_detail_windows", return_value=None):
+        record = normalize_usage_record(
+            {
+                "provider": "codex",
+                "status": "ok",
+                "short_term": {
+                    "percent_remaining": 35.0,
+                    "reset_at": None,
+                    "reset_after_seconds": 3600,
+                    "window": "5h",
+                },
+                "long_term": None,
+                "block_reason": None,
+                "error": None,
+                "details": {},
+            },
+            now=datetime(2026, 6, 8, 10, 0, tzinfo=timezone.utc),
+        )
+
+    assert record["short_term"] == {
+        "percent_remaining": 35.0,
+        "reset_at": "2026-06-08T11:00:00Z",
+        "window": "5h",
     }
 
 

{pocketshell-0.3.29 → 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" },