projectmemory-cli 0.1.0__tar.gz

projectmemory_cli-0.1.0/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: projectmemory-cli
+Version: 0.1.0
+Summary: Project Memory CLI — developer context in your terminal
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: keyring>=25
+Requires-Dist: platformdirs>=4
+Requires-Dist: pydantic>=2
+Requires-Dist: questionary>=2
+Requires-Dist: rich>=13
+Requires-Dist: tomli-w>=1
+Requires-Dist: typer[all]>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest-mock>=3; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Project Memory CLI
+
+Developer context in your terminal — a Python CLI client for [projectmemory.app](https://projectmemory.app).
+
+## Installation
+
+```bash
+pip install projectmemory-cli
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/your-org/projectmemory-cli
+cd projectmemory-cli
+pip install -e ".[dev]"
+```
+
+Both `pm` and `projectmemory` are registered as executable names.
+
+## Quick Start
+
+```bash
+# Authenticate (opens browser)
+pm login
+
+# Create a project and start its first session
+pm project create
+
+# Or resume an existing project/session
+pm resume "My App"
+
+# See your current context
+pm memory show
+
+# Work with tasks
+pm task list
+pm task add "Implement login"
+pm task done 42      # completes task, then optionally links a commit
+pm done              # interactive task completion shortcut
+
+# Capture notes
+pm capture "Don't forget to update the Stripe webhook URL"
+
+# Report an issue
+pm issue add "Login fails on mobile Safari"
+
+# End your session with the shared backend review
+pm session end
+```
+
+## Commands
+
+### Authentication
+| Command | Description |
+|---|---|
+| `pm login` | Authenticate via browser |
+| `pm logout` | Revoke token |
+| `pm whoami` | Show current user |
+| `pm auth status` | Check auth status |
+| `pm doctor` | Diagnose CLI config, auth, backend, project, session, and Git state |
+
+### Projects
+| Command | Description |
+|---|---|
+| `pm project list` | List all projects |
+| `pm project create` | Create a project (interactive) |
+| `pm project current` | Show current project + session |
+| `pm project link` | Link this directory to a project |
+| `pm project unlink` | Remove directory mapping |
+| `pm web` | Open project in browser |
+
+### Work Sessions
+| Command | Description |
+|---|---|
+| `pm resume [project]` | Start or resume a session |
+| `pm session status` | Show all active sessions |
+| `pm session end` | End the current session |
+
+### Project Memory
+| Command | Description |
+|---|---|
+| `pm memory show` | Display all memory fields |
+| `pm memory status set [text]` | Update Current Status |
+| `pm memory context set [text]` | Update Important Context |
+| `pm memory update` | Interactive memory update, including open issues |
+
+### Next Action
+| Command | Description |
+|---|---|
+| `pm next` | Show current Next Action |
+| `pm next set [text]` | Set Next Action (interactive menu) |
+| `pm next task <id>` | Link a task as Next Action |
+| `pm next issue <id>` | Link an issue as Next Action |
+| `pm next clear` | Clear Next Action |
+
+### Tasks
+| Command | Description |
+|---|---|
+| `pm task list` | List tasks; supports `--open`, `--completed`, `--snoozed`, `--all` |
+| `pm task add [title]` | Create a task |
+| `pm task done <id>` | Complete task + optional commit link |
+| `pm done` | Interactive task completion shortcut |
+| `pm task snooze <id>` | Snooze task |
+| `pm task reopen <id>` | Reopen task |
+| `pm task edit <id>` | Edit task |
+| `pm task delete <id>` | Delete task |
+
+### Notes
+| Command | Description |
+|---|---|
+| `pm note list` | List notes |
+| `pm note add [content]` | Create a note; supports `--title`, `--editor`, `--stdin` |
+| `pm note search <query>` | Search notes |
+| `pm capture [text]` | Quick note shortcut |
+| `pm note edit <id>` | Edit a note |
+| `pm note delete <id>` | Delete a note |
+
+### Issues
+| Command | Description |
+|---|---|
+| `pm issue list` | List issues; supports `--open`, `--resolved`, `--all` |
+| `pm issue add [description]` | Report an issue |
+| `pm issue resolve <id>` | Mark issue as resolved |
+| `pm issue reopen <id>` | Reopen issue |
+| `pm issue edit <id>` | Edit issue |
+| `pm issue delete <id>` | Delete issue |
+
+### Commits
+| Command | Description |
+|---|---|
+| `pm commit link` | Interactive recovery flow for linking a commit to a completed task |
+| `pm commit link HEAD --task 24` | Directly link a commit/ref to a completed task |
+
+## Configuration
+
+Configuration is stored at `~/.config/projectmemory/config.toml`.
+
+The default `api_url` is the Project Memory site root, for example `https://projectmemory.app`. The CLI adds API paths such as `/api/cli/...` internally.
+
+```bash
+pm config show         # show all settings
+pm config set api_url https://your-instance.example.com
+pm config reset        # restore defaults
+```
+
+### Environment variables
+
+| Variable | Description |
+|---|---|
+| `PROJECTMEMORY_API_URL` | API base URL |
+| `PROJECTMEMORY_TOKEN` | Token override (skip keyring) |
+| `PROJECTMEMORY_PROJECT` | Current project ID override |
+| `PROJECTMEMORY_NO_COLOR` | Disable color output |
+
+
+## Diagnostics
+
+Run a read-only diagnostic report when troubleshooting local configuration or support issues:
+
+```bash
+pm doctor
+pm doctor --json
+pm doctor --verbose
+pm doctor --no-network
+```
+
+`pm doctor` never prints authentication tokens, refresh tokens, passwords, private keys, or OAuth secrets. It exits with `0` when healthy, `1` when warnings are present, and `2` when critical issues prevent normal CLI use.
+
+## Directory Linking
+
+Link the current git repository to a project so `pm` knows which project to use automatically:
+
+```bash
+cd ~/code/my-app
+pm project link "My App"
+
+# Now pm commands in this directory use "My App" automatically
+pm task list    # no --project needed
+```
+
+## How Sessions Work
+
+The CLI shares the session model with the web app. Sessions must be active for write operations (creating tasks, notes, issues, updating memory).
+
+- `pm resume` starts or resumes the backend session for the selected project
+- `pm session end` shows the shared backend Session Review and finalizes that exact session
+- If the web app ends your session, the CLI will show a clear error and ask you to `pm resume` again
+- A user can have active sessions in multiple projects, but the CLI has one current project
+- Switching projects can end the current project session, keep it active, or cancel
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run with coverage
+pytest --cov=projectmemory_cli --cov-report=term-missing
+
+# Lint
+ruff check projectmemory_cli/
+
+# Type check
+mypy projectmemory_cli/
+```
+
+## Security
+
+- Tokens are stored in the OS keyring (or `~/.config/projectmemory/credentials.json` with `chmod 600` as fallback)
+- Passwords are never stored
+- The `PROJECTMEMORY_TOKEN` environment variable overrides stored credentials (read-only)
+- Tokens can be revoked remotely via `pm logout` or from the web app at projectmemory.app/settings

projectmemory_cli-0.1.0/README.md

@@ -0,0 +1,216 @@
+# Project Memory CLI
+
+Developer context in your terminal — a Python CLI client for [projectmemory.app](https://projectmemory.app).
+
+## Installation
+
+```bash
+pip install projectmemory-cli
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/your-org/projectmemory-cli
+cd projectmemory-cli
+pip install -e ".[dev]"
+```
+
+Both `pm` and `projectmemory` are registered as executable names.
+
+## Quick Start
+
+```bash
+# Authenticate (opens browser)
+pm login
+
+# Create a project and start its first session
+pm project create
+
+# Or resume an existing project/session
+pm resume "My App"
+
+# See your current context
+pm memory show
+
+# Work with tasks
+pm task list
+pm task add "Implement login"
+pm task done 42      # completes task, then optionally links a commit
+pm done              # interactive task completion shortcut
+
+# Capture notes
+pm capture "Don't forget to update the Stripe webhook URL"
+
+# Report an issue
+pm issue add "Login fails on mobile Safari"
+
+# End your session with the shared backend review
+pm session end
+```
+
+## Commands
+
+### Authentication
+| Command | Description |
+|---|---|
+| `pm login` | Authenticate via browser |
+| `pm logout` | Revoke token |
+| `pm whoami` | Show current user |
+| `pm auth status` | Check auth status |
+| `pm doctor` | Diagnose CLI config, auth, backend, project, session, and Git state |
+
+### Projects
+| Command | Description |
+|---|---|
+| `pm project list` | List all projects |
+| `pm project create` | Create a project (interactive) |
+| `pm project current` | Show current project + session |
+| `pm project link` | Link this directory to a project |
+| `pm project unlink` | Remove directory mapping |
+| `pm web` | Open project in browser |
+
+### Work Sessions
+| Command | Description |
+|---|---|
+| `pm resume [project]` | Start or resume a session |
+| `pm session status` | Show all active sessions |
+| `pm session end` | End the current session |
+
+### Project Memory
+| Command | Description |
+|---|---|
+| `pm memory show` | Display all memory fields |
+| `pm memory status set [text]` | Update Current Status |
+| `pm memory context set [text]` | Update Important Context |
+| `pm memory update` | Interactive memory update, including open issues |
+
+### Next Action
+| Command | Description |
+|---|---|
+| `pm next` | Show current Next Action |
+| `pm next set [text]` | Set Next Action (interactive menu) |
+| `pm next task <id>` | Link a task as Next Action |
+| `pm next issue <id>` | Link an issue as Next Action |
+| `pm next clear` | Clear Next Action |
+
+### Tasks
+| Command | Description |
+|---|---|
+| `pm task list` | List tasks; supports `--open`, `--completed`, `--snoozed`, `--all` |
+| `pm task add [title]` | Create a task |
+| `pm task done <id>` | Complete task + optional commit link |
+| `pm done` | Interactive task completion shortcut |
+| `pm task snooze <id>` | Snooze task |
+| `pm task reopen <id>` | Reopen task |
+| `pm task edit <id>` | Edit task |
+| `pm task delete <id>` | Delete task |
+
+### Notes
+| Command | Description |
+|---|---|
+| `pm note list` | List notes |
+| `pm note add [content]` | Create a note; supports `--title`, `--editor`, `--stdin` |
+| `pm note search <query>` | Search notes |
+| `pm capture [text]` | Quick note shortcut |
+| `pm note edit <id>` | Edit a note |
+| `pm note delete <id>` | Delete a note |
+
+### Issues
+| Command | Description |
+|---|---|
+| `pm issue list` | List issues; supports `--open`, `--resolved`, `--all` |
+| `pm issue add [description]` | Report an issue |
+| `pm issue resolve <id>` | Mark issue as resolved |
+| `pm issue reopen <id>` | Reopen issue |
+| `pm issue edit <id>` | Edit issue |
+| `pm issue delete <id>` | Delete issue |
+
+### Commits
+| Command | Description |
+|---|---|
+| `pm commit link` | Interactive recovery flow for linking a commit to a completed task |
+| `pm commit link HEAD --task 24` | Directly link a commit/ref to a completed task |
+
+## Configuration
+
+Configuration is stored at `~/.config/projectmemory/config.toml`.
+
+The default `api_url` is the Project Memory site root, for example `https://projectmemory.app`. The CLI adds API paths such as `/api/cli/...` internally.
+
+```bash
+pm config show         # show all settings
+pm config set api_url https://your-instance.example.com
+pm config reset        # restore defaults
+```
+
+### Environment variables
+
+| Variable | Description |
+|---|---|
+| `PROJECTMEMORY_API_URL` | API base URL |
+| `PROJECTMEMORY_TOKEN` | Token override (skip keyring) |
+| `PROJECTMEMORY_PROJECT` | Current project ID override |
+| `PROJECTMEMORY_NO_COLOR` | Disable color output |
+
+
+## Diagnostics
+
+Run a read-only diagnostic report when troubleshooting local configuration or support issues:
+
+```bash
+pm doctor
+pm doctor --json
+pm doctor --verbose
+pm doctor --no-network
+```
+
+`pm doctor` never prints authentication tokens, refresh tokens, passwords, private keys, or OAuth secrets. It exits with `0` when healthy, `1` when warnings are present, and `2` when critical issues prevent normal CLI use.
+
+## Directory Linking
+
+Link the current git repository to a project so `pm` knows which project to use automatically:
+
+```bash
+cd ~/code/my-app
+pm project link "My App"
+
+# Now pm commands in this directory use "My App" automatically
+pm task list    # no --project needed
+```
+
+## How Sessions Work
+
+The CLI shares the session model with the web app. Sessions must be active for write operations (creating tasks, notes, issues, updating memory).
+
+- `pm resume` starts or resumes the backend session for the selected project
+- `pm session end` shows the shared backend Session Review and finalizes that exact session
+- If the web app ends your session, the CLI will show a clear error and ask you to `pm resume` again
+- A user can have active sessions in multiple projects, but the CLI has one current project
+- Switching projects can end the current project session, keep it active, or cancel
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run with coverage
+pytest --cov=projectmemory_cli --cov-report=term-missing
+
+# Lint
+ruff check projectmemory_cli/
+
+# Type check
+mypy projectmemory_cli/
+```
+
+## Security
+
+- Tokens are stored in the OS keyring (or `~/.config/projectmemory/credentials.json` with `chmod 600` as fallback)
+- Passwords are never stored
+- The `PROJECTMEMORY_TOKEN` environment variable overrides stored credentials (read-only)
+- Tokens can be revoked remotely via `pm logout` or from the web app at projectmemory.app/settings

projectmemory_cli-0.1.0/projectmemory_cli/__init__.py

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

projectmemory_cli-0.1.0/projectmemory_cli/api/__init__.py

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

projectmemory_cli-0.1.0/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-0.1.0/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,
+        )