projectmemory-cli 0.1.0__py3-none-any.whl

projectmemory_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Project Memory CLI package."""
+
+__version__ = "0.1.0"

projectmemory_cli/api/__init__.py

@@ -0,0 +1 @@
+"""API package."""

projectmemory_cli/api/auth.py

@@ -0,0 +1,94 @@
+"""Device authorization flow API calls."""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+
+from projectmemory_cli.api.client import APIClient
+from projectmemory_cli.api.errors import APIError
+
+
+@dataclass
+class DeviceAuthStart:
+    device_code: str
+    user_code: str
+    verification_uri: str
+    verification_uri_complete: str
+    expires_in: int
+    interval: int
+    authorization_id: int
+
+
+@dataclass
+class DeviceAuthResult:
+    access_token: str
+    token_type: str
+    token_id: int
+    user: dict
+
+
+def start_device_auth(client: APIClient, device_name: str = "Project Memory CLI") -> DeviceAuthStart:
+    data = client.post("/api/cli/auth/device/", json={"device_name": device_name})
+    return DeviceAuthStart(
+        device_code=data["device_code"],
+        user_code=data["user_code"],
+        verification_uri=data["verification_uri"],
+        verification_uri_complete=data["verification_uri_complete"],
+        expires_in=data["expires_in"],
+        interval=data["interval"],
+        authorization_id=data["authorization_id"],
+    )
+
+
+def poll_device_auth(
+    client: APIClient,
+    device_code: str,
+    *,
+    interval: int = 5,
+    timeout: int = 900,
+    on_pending: object = None,
+) -> DeviceAuthResult:
+    """Poll until the authorization is approved, denied, or expired.
+
+    Calls `on_pending()` (if callable) on each pending response.
+    Raises APIError on denial, expiry, or timeout.
+    """
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        try:
+            data = client.post("/api/cli/auth/device/poll/", json={"device_code": device_code})
+            return DeviceAuthResult(
+                access_token=data["access_token"],
+                token_type=data["token_type"],
+                token_id=data["token_id"],
+                user=data["user"],
+            )
+        except APIError as exc:
+            err_data = getattr(exc, "data", {}) or {}
+            err_code = err_data.get("error", "")
+            if err_code == "authorization_pending":
+                if callable(on_pending):
+                    on_pending()  # type: ignore[call-arg]
+                time.sleep(interval)
+                continue
+            if err_code == "expired_token":
+                raise APIError("Authorization code expired. Run `pm login` to try again.")
+            if err_code == "access_denied":
+                raise APIError("Authorization was denied in the browser.")
+            if err_code == "authorization_consumed":
+                raise APIError("This authorization code was already used.")
+            raise
+    raise APIError("Authorization timed out. Run `pm login` to try again.")
+
+
+def revoke_token(client: APIClient) -> bool:
+    data = client.post("/api/cli/auth/logout/")
+    return bool(data.get("revoked"))
+
+
+def whoami(client: APIClient) -> dict:
+    return client.get("/api/cli/whoami/")
+
+
+def auth_status(client: APIClient) -> dict:
+    return client.get("/api/cli/auth/status/")

projectmemory_cli/api/client.py

@@ -0,0 +1,135 @@
+"""HTTPX-based API client.
+
+Injects:
+  - Authorization: Bearer <token>
+  - X-Project-Memory-Session: <session_id>   (when provided)
+  - User-Agent: projectmemory-cli/<version>
+  - Content-Type: application/json
+
+All requests go through _request() which translates HTTP errors into
+structured APIError subclasses via api.errors.raise_for_response().
+"""
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from projectmemory_cli import output
+from projectmemory_cli.api.errors import NetworkError, raise_for_response
+
+_VERSION = "0.1.0"
+_TIMEOUT = 30.0
+
+
+class APIClient:
+    def __init__(
+        self,
+        base_url: str,
+        token: str | None = None,
+        session_id: int | str | None = None,
+        debug: bool = False,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.session_id = session_id
+        self.debug = debug
+
+    def _headers(self, extra: dict | None = None) -> dict[str, str]:
+        headers: dict[str, str] = {
+            "User-Agent": f"projectmemory-cli/{_VERSION}",
+            "Accept": "application/json",
+        }
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        if self.session_id is not None:
+            headers["X-Project-Memory-Session"] = str(self.session_id)
+        if extra:
+            headers.update(extra)
+        return headers
+
+    def _log_request(self, method: str, url: str, body: Any = None) -> None:
+        if not self.debug:
+            return
+        token_hint = " [token=pmcli_***]" if self.token else ""
+        output.debug(f"{method} {url}{token_hint}")
+        if body:
+            import json
+            output.debug(f"  body={json.dumps(body, default=str)[:300]}")
+
+    def _log_response(self, resp: httpx.Response) -> None:
+        if self.debug:
+            output.debug(f"  -> {resp.status_code}")
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: dict | None = None,
+        project_name: str = "",
+    ) -> Any:
+        url = f"{self.base_url}{path}"
+        self._log_request(method, url, json)
+        try:
+            with httpx.Client(timeout=_TIMEOUT) as client:
+                resp = client.request(
+                    method,
+                    url,
+                    headers=self._headers(),
+                    json=json,
+                    params=params,
+                )
+        except httpx.TimeoutException:
+            raise NetworkError("Request timed out. Check your connection.")
+        except httpx.ConnectError:
+            raise NetworkError(
+                "Cannot reach the Project Memory API.\n"
+                "Check your connection or try again later."
+            )
+        except httpx.RequestError as exc:
+            raise NetworkError(f"Network error: {exc}")
+
+        self._log_response(resp)
+
+        if resp.status_code == 204:
+            return {}
+
+        try:
+            data = resp.json()
+        except Exception:
+            data = {"detail": resp.text[:500]}
+
+        if not resp.is_success:
+            raise_for_response(resp.status_code, data, project_name=project_name)
+
+        return data
+
+    def get(self, path: str, *, params: dict | None = None, project_name: str = "") -> Any:
+        return self._request("GET", path, params=params, project_name=project_name)
+
+    def post(self, path: str, *, json: Any = None, project_name: str = "") -> Any:
+        return self._request("POST", path, json=json or {}, project_name=project_name)
+
+    def patch(self, path: str, *, json: Any = None, project_name: str = "") -> Any:
+        return self._request("PATCH", path, json=json or {}, project_name=project_name)
+
+    def delete(self, path: str, *, project_name: str = "") -> Any:
+        return self._request("DELETE", path, project_name=project_name)
+
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        session_id: int | str | None = None,
+        debug: bool = False,
+    ) -> "APIClient":
+        """Build a client using current config + stored credentials."""
+        from projectmemory_cli import config, credentials
+        return cls(
+            base_url=config.get_api_url(),
+            token=credentials.get_token(),
+            session_id=session_id,
+            debug=debug,
+        )

projectmemory_cli/api/errors.py

@@ -0,0 +1,124 @@
+"""Structured API error types and HTTP→CLI exit code mapping."""
+from __future__ import annotations
+
+from typing import Any
+
+
+class APIError(Exception):
+    """Base API error."""
+    exit_code: int = 1
+
+    def __init__(self, message: str, status_code: int = 0, data: Any = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.data = data or {}
+
+    def __str__(self) -> str:
+        return self.args[0]
+
+
+class AuthenticationError(APIError):
+    """401 — token missing, expired, or revoked."""
+    exit_code = 2
+
+
+class PermissionError(APIError):
+    """403 — permission denied, read-only, email verification required."""
+    exit_code = 3
+
+
+class ValidationError(APIError):
+    """400/422 — validation failure."""
+    exit_code = 4
+
+
+class NotFoundError(APIError):
+    """404 — resource not found."""
+    exit_code = 5
+
+
+class NetworkError(APIError):
+    """Connection / timeout error."""
+    exit_code = 6
+
+
+class CancelledError(APIError):
+    """User cancelled the operation."""
+    exit_code = 7
+
+
+class SessionConflictError(APIError):
+    """409 — session conflict (no active session or already finalized)."""
+    exit_code = 8
+
+
+class NoActiveSessionError(SessionConflictError):
+    """No active session for a project."""
+
+
+class SessionAlreadyFinalizedError(SessionConflictError):
+    """Session was already ended by another client."""
+
+
+def raise_for_response(status_code: int, data: dict, project_name: str = "") -> None:
+    """Convert an API error response into a structured exception."""
+    code = data.get("code", "")
+    detail = data.get("detail", "") or data.get("error", "") or str(data)
+
+    if status_code == 401:
+        raise AuthenticationError(
+            "Your session has expired or is invalid.\n\nRun:\n  pm login",
+            status_code=status_code,
+            data=data,
+        )
+
+    if status_code == 403:
+        ev = data.get("email_verification_required")
+        if ev:
+            raise PermissionError(
+                "Email verification is required before using this action.\n\n"
+                "Open:\n  https://projectmemory.app/settings/security",
+                status_code=status_code,
+                data=data,
+            )
+        if "read-only" in detail.lower() or "read_only" in str(data).lower():
+            raise PermissionError(
+                "This account is currently read-only because it exceeds the Free plan limit.\n\n"
+                "Upgrade or reduce the number of projects in the web app.",
+                status_code=status_code,
+                data=data,
+            )
+        raise PermissionError(detail or "Permission denied.", status_code=status_code, data=data)
+
+    if status_code == 404:
+        raise NotFoundError(detail or "Resource not found.", status_code=status_code, data=data)
+
+    if status_code == 409:
+        if code == "no_active_session":
+            name = project_name or "this project"
+            raise NoActiveSessionError(
+                f"No active session for {name}.\n\nRun:\n  pm resume",
+                status_code=status_code,
+                data=data,
+            )
+        if "already been finalized" in detail or "already finalized" in detail:
+            raise SessionAlreadyFinalizedError(
+                "This session was already ended from another client.\n\nRun:\n  pm resume\n\nto begin a new session.",
+                status_code=status_code,
+                data=data,
+            )
+        raise SessionConflictError(detail, status_code=status_code, data=data)
+
+    if status_code in (400, 422):
+        # Format field errors nicely
+        if isinstance(data, dict) and any(isinstance(v, list) for v in data.values()):
+            lines = []
+            for field, msgs in data.items():
+                if isinstance(msgs, list):
+                    lines.append(f"  {field}: {', '.join(str(m) for m in msgs)}")
+                else:
+                    lines.append(f"  {field}: {msgs}")
+            raise ValidationError("\n".join(lines), status_code=status_code, data=data)
+        raise ValidationError(detail or str(data), status_code=status_code, data=data)
+
+    raise APIError(detail or f"Unexpected error ({status_code})", status_code=status_code, data=data)

projectmemory_cli/api/sessions.py

@@ -0,0 +1,25 @@
+"""Session-related API calls."""
+from __future__ import annotations
+
+from projectmemory_cli.api.client import APIClient
+
+
+def get_session_status(client: APIClient) -> dict:
+    return client.get("/api/cli/session/status/")
+
+
+def get_session_review(client: APIClient, session_id: int | str) -> dict:
+    return client.get("/api/cli/session/review/", params={"session_id": str(session_id)})
+
+
+def end_session(client: APIClient, session_id: int | str, *, payload: dict | None = None) -> dict:
+    body = {"session_id": int(session_id), **(payload or {})}
+    return client.post("/api/cli/session/end/", json=body)
+
+
+def resume_project(client: APIClient, project_id: int | str) -> dict:
+    return client.post(f"/api/cli/projects/{project_id}/resume/")
+
+
+def get_project_sessions(client: APIClient, project_id: int | str) -> dict:
+    return client.get(f"/api/cli/projects/{project_id}/sessions/")

projectmemory_cli/app.py

@@ -0,0 +1,80 @@
+"""Typer application and global options."""
+from __future__ import annotations
+
+import typer
+
+from projectmemory_cli import config as pm_config
+from projectmemory_cli import output
+from projectmemory_cli.commands import (
+    auth as auth_cmd,
+    commits as commits_cmd,
+    config as config_cmd,
+    doctor as doctor_cmd,
+    issues as issues_cmd,
+    memory as memory_cmd,
+    next_action as next_action_cmd,
+    notes as notes_cmd,
+    projects as projects_cmd,
+    resume as resume_cmd,
+    sessions as sessions_cmd,
+    tasks as tasks_cmd,
+)
+
+app = typer.Typer(
+    name="pm",
+    help="Project Memory — developer context in your terminal.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+    pretty_exceptions_enable=False,
+)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    json: bool = typer.Option(False, "--json", help="Output JSON where supported."),
+    plain: bool = typer.Option(False, "--plain", help="Use plain text output."),
+    quiet: bool = typer.Option(False, "--quiet", help="Only print essential output."),
+    no_color: bool = typer.Option(False, "--no-color", help="Disable color output."),
+    debug: bool = typer.Option(False, "--debug", help="Show redacted debug information."),
+) -> None:
+    """Configure process-wide output options before command execution."""
+    no_color = no_color or not bool(pm_config.get("color", True))
+    output.configure(
+        json_mode=json,
+        plain_mode=plain,
+        quiet_mode=quiet,
+        debug_mode=debug,
+        no_color=no_color,
+    )
+    ctx.obj = {"json": json, "plain": plain, "quiet": quiet, "no_color": no_color, "debug": debug}
+
+
+app.add_typer(projects_cmd.app, name="project")
+app.add_typer(sessions_cmd.app, name="session")
+app.add_typer(memory_cmd.app, name="memory")
+app.add_typer(next_action_cmd.app, name="next")
+app.add_typer(tasks_cmd.app, name="task")
+app.add_typer(notes_cmd.app, name="note")
+app.add_typer(issues_cmd.app, name="issue")
+app.add_typer(commits_cmd.app, name="commit")
+
+app.command("login")(auth_cmd.login)
+app.command("logout")(auth_cmd.logout)
+app.command("whoami")(auth_cmd.whoami)
+app.command("doctor")(doctor_cmd.doctor)
+
+auth_app = typer.Typer(help="Authentication commands.", no_args_is_help=True)
+auth_app.command("status")(auth_cmd.status)
+app.add_typer(auth_app, name="auth")
+
+config_app = typer.Typer(help="Configuration commands.", no_args_is_help=True)
+config_app.command("show")(config_cmd.show)
+config_app.command("set")(config_cmd.set_value)
+config_app.command("reset")(config_cmd.reset)
+app.add_typer(config_app, name="config")
+
+app.command("resume")(resume_cmd.resume)
+app.command("web")(projects_cmd.web)
+app.command("done")(tasks_cmd.done_interactive)
+app.command("capture")(notes_cmd.capture)

projectmemory_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Commands package."""

projectmemory_cli/commands/auth.py

@@ -0,0 +1,163 @@
+"""Authentication commands: pm login, pm logout, pm whoami, pm auth status."""
+from __future__ import annotations
+
+import sys
+import webbrowser
+
+import typer
+
+from projectmemory_cli import credentials, output
+from projectmemory_cli.api import auth as auth_api
+from projectmemory_cli.api.client import APIClient
+from projectmemory_cli.api.errors import APIError, AuthenticationError
+
+
+def _make_client(require_auth: bool = False) -> APIClient:
+    client = APIClient.from_env()
+    if require_auth and not client.token:
+        output.error("Not logged in. Run: pm login")
+        raise SystemExit(2)
+    return client
+
+
+def login(
+    device_name: str = typer.Option(
+        "Project Memory CLI",
+        "--device-name",
+        help="Name for this CLI session token.",
+    ),
+) -> None:
+    """Authenticate via browser-based device authorization."""
+    client = APIClient.from_env()
+
+    output.info("Requesting authorization from Project Memory...")
+    try:
+        auth = auth_api.start_device_auth(client, device_name=device_name)
+    except APIError as exc:
+        output.error(str(exc))
+        raise SystemExit(exc.exit_code)
+
+    output.blank()
+    output.info(f"[bold]Code:[/bold] [bright_cyan]{auth.user_code}[/bright_cyan]")
+    output.blank()
+
+    opened = webbrowser.open(auth.verification_uri_complete)
+    if opened:
+        output.info("Opening Project Memory in your browser...")
+    else:
+        output.warn("Could not open browser automatically.")
+        output.info("Visit:")
+        output.info(f"  [link]{auth.verification_uri_complete}[/link]")
+    output.blank()
+    output.info("[dim]Waiting for authorization...[/dim]")
+
+    dots = [0]
+
+    def on_pending() -> None:
+        dots[0] += 1
+        if dots[0] % 6 == 0:  # every ~30s
+            output.info("[dim]Still waiting...[/dim]")
+
+    try:
+        result = auth_api.poll_device_auth(
+            client,
+            auth.device_code,
+            interval=auth.interval,
+            timeout=auth.expires_in,
+            on_pending=on_pending,
+        )
+    except APIError as exc:
+        output.blank()
+        output.error(str(exc))
+        raise SystemExit(exc.exit_code)
+
+    # Store token
+    used_keyring = credentials.save_token(result.access_token)
+
+    output.blank()
+    user = result.user
+    email = user.get("email", "")
+    plan = user.get("plan", "free")
+    output.success(f"Logged in as [bold]{email}[/bold]  [dim]({plan})[/dim]")
+    if not used_keyring:
+        output.hint("Token saved to fallback credentials file (keyring not available).")
+
+
+def logout() -> None:
+    """Revoke CLI token and remove it locally."""
+    token = credentials.get_token()
+    if not token:
+        output.warn("Not currently logged in.")
+        raise SystemExit(0)
+
+    client = APIClient.from_env()
+    try:
+        auth_api.revoke_token(client)
+        output.success("Token revoked on server.")
+    except AuthenticationError:
+        output.warn("Token was already invalid on the server.")
+    except APIError as exc:
+        output.warn(f"Could not revoke token remotely: {exc}")
+
+    credentials.delete_token()
+    output.success("Logged out.")
+
+
+def whoami() -> None:
+    """Show the currently authenticated user."""
+    client = _make_client(require_auth=True)
+    try:
+        data = auth_api.whoami(client)
+    except APIError as exc:
+        output.error(str(exc))
+        raise SystemExit(exc.exit_code)
+
+    user = data.get("user", {})
+    email = user.get("email", "—")
+    name = user.get("name", "")
+    plan = user.get("plan", "free")
+    verified = user.get("email_verified", True)
+
+    output.blank()
+    output.kv("Email", email)
+    if name:
+        output.kv("Name", name)
+    output.kv("Plan", plan.capitalize())
+    output.kv("Email verified", "Yes" if verified else "[yellow]No[/yellow]")
+
+    limits = user.get("limits", {})
+    usage = user.get("usage", {})
+    if usage:
+        projects_used = usage.get("projects", "—")
+        projects_max = limits.get("max_projects") or "unlimited"
+        output.kv("Projects", f"{projects_used} / {projects_max}")
+
+
+def status() -> None:
+    """Show authentication status (alias for pm auth status)."""
+    token = credentials.get_token()
+    if not token:
+        output.warn("Not logged in.")
+        output.hint("Run: pm login")
+        raise SystemExit(2)
+
+    client = APIClient.from_env()
+    try:
+        data = auth_api.auth_status(client)
+    except AuthenticationError:
+        output.error("Token is expired or revoked.")
+        output.hint("Run: pm login")
+        raise SystemExit(2)
+    except APIError as exc:
+        output.error(str(exc))
+        raise SystemExit(exc.exit_code)
+
+    authenticated = data.get("authenticated", False)
+    user = data.get("user", {})
+    email = user.get("email", "—")
+
+    if authenticated:
+        output.success(f"Authenticated as [bold]{email}[/bold]")
+    else:
+        output.warn("Not authenticated.")
+        raise SystemExit(2)