quaestor-cli 0.1.0__py3-none-any.whl

quaestor_cli/__init__.py

@@ -0,0 +1,7 @@
+"""Quaestor CLI — a thin HTTP client for the Quaestor API.
+
+This package never imports the backend: it speaks HTTP only, so it can be
+installed and shipped independently of the server.
+"""
+
+__version__ = "0.1.0"

quaestor_cli/api.py

@@ -0,0 +1,224 @@
+"""Endpoint-level helpers shared by commands.
+
+Keeping the URL shapes in one module means a contract change is a one-file edit,
+and commands stay about presentation and validation.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import date, datetime
+from typing import Any
+
+from quaestor_cli.client import ApiResponse, Probe, QuaestorClient
+from quaestor_cli.models import DailyStat, Event, Identity, Streak, StreakReview, TimerSnapshot
+from quaestor_cli.window import DateWindow
+
+WHOAMI_PATH = "/auth/whoami"
+STREAKS_PATH = "/streaks"
+STREAKS_WITH_STATS_PATH = "/streaks/with-stats"
+EVENTS_PATH = "/events"
+STATS_DAILY_PATH = "/stats/daily"
+TIMERS_PATH = "/timers"
+TIMERS_STOP_PATH = "/timers/stop"
+TIMERS_ACTIVE_PATH = "/timers/active"
+HEALTHZ_PATH = "/healthz"
+
+# The server caps this at 200; the CLI always wants the full set for name matching.
+MAX_STREAKS = 200
+# The server's own maximum, passed explicitly rather than relying on its default of 20.
+EVENTS_FETCH_LIMIT = 1000
+
+
+@dataclass(frozen=True)
+class IdentityLookup:
+    """Outcome of `GET /auth/whoami`, including the "server is too old" case."""
+
+    probe: Probe
+    identity: Identity | None
+
+    @property
+    def is_success(self) -> bool:
+        """True when the identity and its scopes were read."""
+        return self.identity is not None
+
+    @property
+    def is_unsupported(self) -> bool:
+        """True when the endpoint is absent, so scopes are simply unknowable."""
+        return self.probe.is_unsupported
+
+
+def fetch_identity(client: QuaestorClient) -> IdentityLookup:
+    """Read the caller's identity and scopes, returning failures as data.
+
+    Unscoped on the server, so it doubles as the cheapest "is my credential
+    accepted?" check.
+    """
+    probe = client.probe(WHOAMI_PATH)
+    payload = probe.payload if isinstance(probe.payload, Mapping) else None
+    identity = Identity.from_payload(payload) if probe.is_success and payload else None
+    return IdentityLookup(probe=probe, identity=identity)
+
+
+def list_streaks(client: QuaestorClient, *, only_active: bool = True) -> list[Streak]:
+    """Fetch the streaks used for name resolution and the `streaks` listing."""
+    response = client.get(STREAKS_PATH, {"limit": MAX_STREAKS, "only_active": only_active})
+    return Streak.from_list(response.payload)
+
+
+@dataclass(frozen=True)
+class StreakDetail:
+    """One streak's full metadata plus the raw payload for --json."""
+
+    streak: Streak
+    raw: Any
+
+
+def get_streak(client: QuaestorClient, streak_id: str) -> StreakDetail:
+    """Fetch a single streak's full record."""
+    response = client.get(f"{STREAKS_PATH}/{streak_id}")
+    payload = response.payload if isinstance(response.payload, Mapping) else {}
+    return StreakDetail(streak=Streak.from_payload(payload), raw=response.payload)
+
+
+@dataclass(frozen=True)
+class CreatedEvent:
+    """A created (or deduplicated) event plus the raw payload for --json."""
+
+    event: Event
+    raw: Any
+    already_logged: bool
+
+
+def create_event(client: QuaestorClient, body: Mapping[str, Any]) -> CreatedEvent:
+    """POST an event; a 200 instead of 201 means the idempotency key already existed."""
+    response = client.post(EVENTS_PATH, body)
+    payload = response.payload if isinstance(response.payload, Mapping) else {}
+    return CreatedEvent(
+        event=Event.from_payload(payload),
+        raw=response.payload,
+        already_logged=response.status_code == 200,
+    )
+
+
+@dataclass(frozen=True)
+class EventPage:
+    """Events for a window, plus the raw payload and whether the fetch capped out."""
+
+    events: list[Event]
+    raw: Any
+    limit_reached: bool
+
+    @property
+    def count(self) -> int:
+        """How many events came back."""
+        return len(self.events)
+
+
+def list_events(client: QuaestorClient, *, streak_id: str, window: DateWindow) -> EventPage:
+    """Fetch a streak's events in a window, newest event date first."""
+    response = client.get(
+        EVENTS_PATH,
+        {
+            "streak_id": streak_id,
+            "date_from": window.date_from.isoformat(),
+            "date_to": window.date_to.isoformat(),
+            # The server sorts this descending, so the newest events survive truncation.
+            "sort_by": "event_date",
+            "limit": EVENTS_FETCH_LIMIT,
+        },
+    )
+    events = Event.from_list(response.payload)
+    return EventPage(events=events, raw=response.payload, limit_reached=len(events) >= EVENTS_FETCH_LIMIT)
+
+
+@dataclass(frozen=True)
+class DailySeries:
+    """Per-day rows for a window, plus the raw payload for --json."""
+
+    rows: list[DailyStat]
+    raw: Any
+
+    @property
+    def active_days(self) -> int:
+        """Days with at least one event."""
+        return sum(1 for row in self.rows if row.is_active)
+
+    @property
+    def total(self) -> float:
+        """Window total in the streak's own unit (seconds for TIME)."""
+        return sum(row.total for row in self.rows)
+
+
+def daily_stats(client: QuaestorClient, *, streak_id: str, window: DateWindow) -> DailySeries:
+    """Fetch zero-filled per-day totals, so missed days are visible."""
+    response = client.get(
+        STATS_DAILY_PATH,
+        {
+            "streak_id": streak_id,
+            "date_from": window.date_from.isoformat(),
+            "date_to": window.date_to.isoformat(),
+        },
+    )
+    return DailySeries(rows=DailyStat.from_list(response.payload), raw=response.payload)
+
+
+@dataclass(frozen=True)
+class TimerResult:
+    """A timer operation's snapshot plus the raw payload for --json."""
+
+    snapshot: TimerSnapshot
+    raw: Any
+
+
+def start_timer(client: QuaestorClient, *, streak_id: str, now_local: datetime) -> TimerResult:
+    """Start a timer that begins recording at `now_local`."""
+    body = {
+        "streak_id": streak_id,
+        "started_at_local": now_local.isoformat(),
+        "now_local": now_local.isoformat(),
+    }
+    response = client.post(TIMERS_PATH, body)
+    return TimerResult(snapshot=_snapshot(response), raw=response.payload)
+
+
+def stop_timer(client: QuaestorClient, *, now_local: datetime) -> TimerResult:
+    """Finalise the running block at `now_local`."""
+    response = client.post(TIMERS_STOP_PATH, {"now_local": now_local.isoformat()})
+    payload = response.payload if isinstance(response.payload, Mapping) else {}
+    return TimerResult(snapshot=TimerSnapshot.from_stop_payload(payload), raw=response.payload)
+
+
+def active_timer(client: QuaestorClient) -> TimerResult:
+    """Read the currently running timer, if any."""
+    response = client.get(TIMERS_ACTIVE_PATH)
+    return TimerResult(snapshot=_snapshot(response), raw=response.payload)
+
+
+@dataclass(frozen=True)
+class ReviewResult:
+    """Review rows plus the raw payload for --json."""
+
+    rows: list[StreakReview]
+    raw: Any
+
+
+def review(client: QuaestorClient, window: DateWindow, *, today: date) -> ReviewResult:
+    """Fetch streaks with stats for the window, using the caller's local today."""
+    response = client.get(
+        STREAKS_WITH_STATS_PATH,
+        {
+            "date_from": window.date_from.isoformat(),
+            "date_to": window.date_to.isoformat(),
+            "today": today.isoformat(),
+            "only_active": True,
+        },
+    )
+    return ReviewResult(rows=StreakReview.from_list(response.payload), raw=response.payload)
+
+
+def _snapshot(response: ApiResponse) -> TimerSnapshot:
+    """Read a TimerStateOut body into a snapshot, tolerating an empty body."""
+    payload = response.payload if isinstance(response.payload, Mapping) else {}
+    return TimerSnapshot.from_payload(payload)

quaestor_cli/client.py

@@ -0,0 +1,187 @@
+"""HTTP access to the Quaestor API.
+
+`httpx` is imported inside the request method on purpose: importing it at module
+level adds ~18ms to every invocation, including `qst --help`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from quaestor_cli.config import assert_safe_for_credential
+from quaestor_cli.errors import CliError, ExitCode
+
+API_PREFIX = "/api/v1"
+DEFAULT_TIMEOUT_SECONDS = 15.0
+
+# Maps an HTTP failure onto the exit code an agent should act on.
+_STATUS_EXIT_CODES: dict[int, ExitCode] = {
+    400: ExitCode.USAGE,
+    401: ExitCode.AUTH,
+    403: ExitCode.AUTH,
+    404: ExitCode.NOT_FOUND,
+    422: ExitCode.USAGE,
+}
+
+
+@dataclass(frozen=True)
+class ApiResponse:
+    """A decoded API response. `payload` is None for empty bodies."""
+
+    status_code: int
+    payload: Any
+
+    @property
+    def is_success(self) -> bool:
+        """True for any 2xx status."""
+        return 200 <= self.status_code < 300
+
+    @property
+    def detail(self) -> str:
+        """The server's `detail` string, falling back to a generic message."""
+        if isinstance(self.payload, Mapping):
+            detail = self.payload.get("detail")
+            if isinstance(detail, str) and detail:
+                return detail
+        if isinstance(self.payload, str) and self.payload:
+            return self.payload
+        return f"HTTP {self.status_code}"
+
+
+@dataclass(frozen=True)
+class Probe:
+    """A health check that never raises: transport failures are returned as data."""
+
+    reachable: bool
+    status_code: int | None
+    detail: str
+    payload: Any = None
+
+    @property
+    def is_success(self) -> bool:
+        """True when the server answered with a 2xx."""
+        return self.reachable and self.status_code is not None and 200 <= self.status_code < 300
+
+    @property
+    def is_unsupported(self) -> bool:
+        """True when the endpoint does not exist, i.e. the server predates it."""
+        return self.status_code == 404
+
+    @property
+    def rejected_credential(self) -> bool:
+        """True when the server refused the credential or its scopes."""
+        return self.status_code in (401, 403)
+
+
+class QuaestorClient:
+    """Thin authenticated wrapper over the Quaestor REST API."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        if api_key is not None:
+            assert_safe_for_credential(self.base_url)
+        self._api_key = api_key
+        self._timeout = timeout
+
+    def url_for(self, path: str) -> str:
+        """Absolute URL for an API path such as `/streaks`."""
+        return f"{self.base_url}{API_PREFIX}{path}"
+
+    def get(
+        self,
+        path: str,
+        params: Mapping[str, Any] | None = None,
+        *,
+        check: bool = True,
+    ) -> ApiResponse:
+        """GET an API path; `check=False` returns failures instead of raising."""
+        return self.request("GET", path, params=params, check=check)
+
+    def post(
+        self,
+        path: str,
+        body: Mapping[str, Any] | None = None,
+        *,
+        check: bool = True,
+    ) -> ApiResponse:
+        """POST a JSON body to an API path."""
+        return self.request("POST", path, body=body, check=check)
+
+    def probe(self, path: str, params: Mapping[str, Any] | None = None) -> Probe:
+        """GET a path for diagnostics, reporting any failure instead of raising."""
+        try:
+            response = self.request("GET", path, params=params, check=False)
+        except CliError as exc:
+            return Probe(reachable=False, status_code=None, detail=exc.message)
+        return Probe(
+            reachable=True,
+            status_code=response.status_code,
+            detail="ok" if response.is_success else response.detail,
+            payload=response.payload,
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        body: Mapping[str, Any] | None = None,
+        check: bool = True,
+    ) -> ApiResponse:
+        """Send one request, mapping transport and HTTP failures to CliError."""
+        import httpx  # Lazy: keeps `qst --help` fast.
+
+        url = self.url_for(path)
+        try:
+            raw = httpx.request(
+                method,
+                url,
+                params=_clean_params(params),
+                json=dict(body) if body is not None else None,
+                headers=self._headers(),
+                timeout=self._timeout,
+            )
+        except httpx.HTTPError as exc:
+            raise CliError(f"Cannot reach {url}: {exc}", ExitCode.SERVER) from exc
+
+        response = ApiResponse(status_code=raw.status_code, payload=_decode(raw))
+        if check and not response.is_success:
+            raise CliError(response.detail, _exit_code_for(response.status_code))
+        return response
+
+    def _headers(self) -> dict[str, str]:
+        """Build request headers, including bearer auth when a key is present."""
+        headers = {"Accept": "application/json"}
+        if self._api_key:
+            headers["Authorization"] = f"Bearer {self._api_key}"
+        return headers
+
+
+def _exit_code_for(status_code: int) -> ExitCode:
+    """Translate an HTTP status into the CLI's exit-code contract."""
+    return _STATUS_EXIT_CODES.get(status_code, ExitCode.SERVER)
+
+
+def _decode(raw: Any) -> Any:
+    """Decode a JSON body, falling back to text for non-JSON responses."""
+    if not raw.content:
+        return None
+    try:
+        return raw.json()
+    except ValueError:
+        return raw.text
+
+
+def _clean_params(params: Mapping[str, Any] | None) -> dict[str, Any] | None:
+    """Drop None-valued query params so the server applies its own defaults."""
+    if not params:
+        return None
+    return {key: value for key, value in params.items() if value is not None}

quaestor_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Command implementations, one module per command group."""

quaestor_cli/commands/auth.py

@@ -0,0 +1,152 @@
+"""`qst auth` — store, inspect and remove the API credential."""
+
+from __future__ import annotations
+
+import sys
+
+import typer
+
+from quaestor_cli import api
+from quaestor_cli.config import (
+    ENV_API_KEY,
+    Credential,
+    credentials_path,
+    delete_credential,
+    key_label,
+    save_credential,
+)
+from quaestor_cli.errors import CliError, ExitCode, usage_error
+from quaestor_cli.output import emit, emit_json, format_scopes, warn
+from quaestor_cli.runtime import CliState, JsonFlag, cli_state, execute
+
+app = typer.Typer(help="Manage the stored API credential.", no_args_is_help=True)
+
+_LEGACY_SERVER_NOTE = "unknown (this server has no /auth/whoami)"
+
+
+@app.command("login")
+def login(ctx: typer.Context, json_output: JsonFlag = False) -> None:
+    """Read an API key from stdin and store it, so it never lands in shell history."""
+    state = cli_state(ctx, json_output)
+    execute(lambda: _login(state))
+
+
+@app.command("whoami")
+def whoami(ctx: typer.Context, json_output: JsonFlag = False) -> None:
+    """Show which credential is in use and whether the API accepts it."""
+    state = cli_state(ctx, json_output)
+    execute(lambda: _whoami(state))
+
+
+@app.command("logout")
+def logout(ctx: typer.Context, json_output: JsonFlag = False) -> None:
+    """Delete the stored credential file."""
+    state = cli_state(ctx, json_output)
+    execute(lambda: _logout(state))
+
+
+def _login(state: CliState) -> None:
+    """Persist the key piped on stdin with 0600 permissions."""
+    if sys.stdin.isatty():
+        warn("Paste the API key and press Enter:")
+    key = _read_key_from_stdin()
+    path = save_credential(key)
+
+    label = key_label(key)
+    if state.json_output:
+        emit_json({"stored": str(path), "key_label": label, "mode": "0600"})
+        return
+    emit(f"Stored credential {label} in {path} (mode 0600).")
+
+
+def _whoami(state: CliState) -> None:
+    """Report the credential in use plus the identity and scopes the server grants."""
+    credential = state.config.require_credential()
+    lookup = api.fetch_identity(state.client())
+    if lookup.is_unsupported:
+        _whoami_without_scopes(state, credential)
+        return
+    identity = lookup.identity
+    if identity is None:
+        code = ExitCode.AUTH if lookup.probe.rejected_credential else ExitCode.SERVER
+        raise CliError(lookup.probe.detail, code)
+
+    if state.json_output:
+        emit_json(
+            {
+                "base_url": state.config.base_url,
+                "credential_source": credential.source,
+                "key_label": credential.label,
+                "authenticated": True,
+                "user": identity.auth_user_id,
+                "auth_method": identity.auth_method,
+                "api_key_id": identity.api_key_id,
+                "scopes": list(identity.scopes),
+            }
+        )
+        return
+    emit(
+        f"base url:   {state.config.base_url}",
+        f"credential: {credential.source} ({credential.label})",
+        "status:     authenticated",
+        f"user:       {identity.auth_user_id}",
+        f"method:     {identity.auth_method}",
+        f"key id:     {identity.api_key_id or '-'}",
+        f"scopes:     {format_scopes(identity.scopes)}",
+    )
+
+
+def _whoami_without_scopes(state: CliState, credential: Credential) -> None:
+    """Fall back to a plain authenticated read when the server has no whoami route."""
+    probe = state.client().probe(api.STREAKS_PATH, {"limit": 1})
+    if not probe.is_success:
+        code = ExitCode.AUTH if probe.rejected_credential else ExitCode.SERVER
+        raise CliError(probe.detail, code)
+
+    if state.json_output:
+        emit_json(
+            {
+                "base_url": state.config.base_url,
+                "credential_source": credential.source,
+                "key_label": credential.label,
+                "authenticated": True,
+                "user": None,
+                "auth_method": None,
+                "api_key_id": None,
+                "scopes": None,
+            }
+        )
+        return
+    emit(
+        f"base url:   {state.config.base_url}",
+        f"credential: {credential.source} ({credential.label})",
+        "status:     authenticated",
+        f"user:       {_LEGACY_SERVER_NOTE}",
+        f"scopes:     {_LEGACY_SERVER_NOTE}",
+    )
+
+
+def _logout(state: CliState) -> None:
+    """Remove the credential file and warn if the environment still holds a key."""
+    path = credentials_path()
+    removed = delete_credential()
+    env_key_present = state.config.credential is not None and state.config.credential.source == "env"
+
+    if state.json_output:
+        emit_json({"removed": removed, "path": str(path), "env_key_still_set": env_key_present})
+    elif removed:
+        emit(f"Removed {path}.")
+    else:
+        emit(f"No stored credential at {path}.")
+
+    if env_key_present:
+        warn(f"{ENV_API_KEY} is still set in the environment and takes precedence.")
+
+
+def _read_key_from_stdin() -> str:
+    """Take the first non-empty line of stdin as the key."""
+    for line in sys.stdin.read().splitlines():
+        candidate = line.strip()
+        if candidate:
+            return candidate
+    raise usage_error("No API key on stdin. Pipe it in, e.g. 'pbpaste | qst auth login'.")