quaestor-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{quaestor_cli-0.2.0 → quaestor_cli-0.3.0}/.gitignore

@@ -28,4 +28,10 @@ coverage/
 terraform.tfvars
 terraform.tfstate
 .terraform/
+
+# Local agent tooling
+.playwright-mcp/
+.claude/
+
+# Playwright MCP screenshots and snapshots
 .playwright-mcp/

quaestor_cli-0.3.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.5
+Name: quaestor-cli
+Version: 0.3.0
+Summary: Command-line client for the Quaestor API — built for humans and agents.
+Project-URL: Homepage, https://quaestor.app
+Project-URL: Repository, https://github.com/neuromaxer/quaestor-lite
+Project-URL: Documentation, https://github.com/neuromaxer/quaestor-lite/blob/main/apps/cli/README.md
+Project-URL: Issues, https://github.com/neuromaxer/quaestor-lite/issues
+Keywords: agent,ai,cli,habit-tracker,quaestor
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: typer>=0.16
+Description-Content-Type: text/markdown
+
+# quaestor-cli
+
+`qst` — a command-line client for [Quaestor](https://quaestor.app), an agent-native
+platform for diary-based life management. An evening diary becomes tracked habits,
+quest progress, and a morning plan.
+
+Built for two users at once: a person in a terminal, and an AI assistant acting on their
+behalf. That second audience shapes most of the design — commands are task-shaped rather
+than endpoint-shaped, streaks and quests are addressed by name, failures are
+distinguishable by exit code, and the server's own error message is printed verbatim so
+an agent can relay something true.
+
+```bash
+uv tool install quaestor-cli
+```
+
+## Setup
+
+Create an API key in the Quaestor web app under **Profile → Developer Access**.
+Set the backend URL, then store the key from stdin. On macOS, copy the key and run:
+
+```bash
+export QUAESTOR_URL="https://your-quaestor-backend"   # defaults to http://localhost:8000
+pbpaste | qst auth login
+qst doctor
+```
+
+On other systems, run `qst auth login`, paste the key, press Enter, then signal
+end-of-input (Ctrl-D on Unix).
+
+The key is stored at `~/.config/quaestor/credentials.json` with mode `0600`. The
+CLI also supports `QUAESTOR_API_KEY`; an existing environment variable takes
+precedence over the file, but it is not needed for this setup.
+
+`qst` refuses to send a key over plain HTTP to anything but a loopback host. Set
+`QUAESTOR_ALLOW_INSECURE=1` only if you are knowingly running a plaintext self-hosted
+backend.
+
+## The evening diary workflow
+
+Spend 10–15 minutes writing or recording your day. Your agent uses `qst` to log
+measured habits, record quest progress, and plan the work you want to do tomorrow.
+It reports what changed and prepares a short morning plan with Main and Side Quests.
+
+Keep the original diary with your agent or in a place you choose. The CLI stores
+habit records and quest-specific notes in Quaestor, not a general diary entry.
+Those original entries become a record of your progress and a story worth keeping.
+
+## Commands
+
+```
+qst streaks                      List streaks with mode, unit and target
+qst show <streak>                Full configuration plus per-day totals, including missed days
+qst log <streak> <value>         Log a COUNT amount
+qst log <streak> --minutes 45    Log a TIME block (45, 45m, 1h30m, 1.5h)
+qst events <streak>              Individual entries, newest first, with the source of each
+qst review                       Totals, active days and current streak per streak
+qst timer start|stop|status      Control the single running timer
+qst auth login|whoami|logout     Manage the stored credential
+qst doctor                       Check URL, reachability, credential and granted scopes
+
+qst agenda [--week|--days N]     Overdue, past deadline, ready to plan, and each day's quests
+qst quests [words] [filters]     Find quests: --status, --overdue, --on, --from/--to,
+                                 --deadline-by, --under <quest>, --archived, --sort, --limit
+qst quest show <quest>           Status, dates, sub-quest progress, description, latest Quest Log
+qst quest log <quest>            Quest Log entries, newest first (--date for one day)
+qst quest add <title>            --under <quest> --on fri --due <date> --priority high --emoji 🚀 ...
+qst quest edit <quest>           --title --emoji --priority --start/--due (or 'none') --under/--top-level
+qst quest status <quest> <s>     backlog | todo | in-progress | done | archived
+qst quest archive <quest>        Hide it and its sub-quests (there is no delete)
+qst quest plan <quest> <day>...  Plan days; a Backlog quest becomes Todo
+qst quest unplan <quest> <day>   Remove a planned day (never demotes)
+qst quest reschedule <q> <from> [to]   Move one planned day (to today by default)
+qst quest check <quest>          Check off a day (--date, --undo); starts Backlog/Todo quests
+qst quest note <quest> <text>    Append to that day's Quest Log entry (--date, --replace)
+qst quest link|unlink <quest> <streak>  Link a streak (context only, nothing syncs)
+```
+
+Every command takes `--json` for machine-readable output on stdout. Every write takes
+`--dry-run`, which prints the request and sends nothing.
+
+### Windows
+
+`events`, `show` and `review` share one set of window flags: `--today`, `--week`
+(default), `--days N`, or an explicit `--from` / `--to`. The explicit and relative forms
+cannot be combined. Dates accept `today`, `yesterday`, a weekday (`mon`..`sun`, meaning
+the most recent past one), `YYYY-MM-DD`, or an offset like `-3d`.
+
+### Streaks are named, never UUIDs
+
+`<streak>` is a name. Resolution tries exact match, then unique prefix, then unique
+substring. On zero or multiple matches it exits `3`, lists the candidates, and writes
+nothing — it never guesses.
+
+```
+$ qst log r 1
+Streak 'r' is ambiguous — candidates: Reading, Running. Nothing was written.
+```
+
+### Quests are named too — by title or path
+
+`<quest>` is a title, or a path of titles that names the parents as well:
+`"Launch > Backend > Schema"` (`›` works too). The server resolves it — exact, then unique
+prefix, then unique substring; archived quests only when nothing live matches — and on
+zero or several matches `qst` exits `3`, prints the candidates' full paths, and writes
+nothing.
+
+```
+$ qst quest check "write migration"
+Quest 'write migration' is ambiguous — 2 quests match: Launch › Backend › Write migration;
+Blog › Write migration. Use a path such as 'Launch > Backend > Write migration' to pick one.
+Nothing was written.
+```
+
+With `--json`, the failure is one JSON document on stdout: `{"error": {"exit_code": 3,
+"message": ..., "candidates": [...]}}`.
+
+### Which way date words point
+
+Where you plan (`add --on/--due/--start`, `plan`, a reschedule target, `agenda`/`quests
+--from/--to`), a weekday means the **coming** one: `fri` on a Wednesday is this Friday,
+and today if it is Friday; `next fri` is a week later; `+1w` is a week from today.
+Where you record (`check --date`, `note --date`, streak commands), a weekday is the most
+recent one and `last fri` is strictly before today; `check` refuses future days.
+Where you name a day the quest already has (`reschedule`'s first day, `unplan`), a
+weekday picks the quest's own date on that weekday within a week of today, in either
+direction — so `qst quest reschedule report tue thu` works whether Tuesday was yesterday
+or is next week.
+
+### Retrying writes safely
+
+Dropped connections are retried automatically with the same idempotency key. If a write
+still fails with exit 4, the message includes the key; re-run with
+`qst --idempotency-key <key> ...` (or set `QUAESTOR_IDEMPOTENCY_KEY`) and the server
+replays the original write instead of creating a duplicate.
+
+Quest reads send your local date (`today=`), so overdue and "today" match the web app.
+Writes that change a status automatically say so (`Status: Todo → In progress.`).
+
+### `--unit` is a safety check, not data
+
+Units belong to the streak, not the event, so `--unit` is never sent to the API. It
+asserts what you believe the streak measures and fails before writing if you are wrong —
+which is what stops an assistant logging "5 miles" as 5 km.
+
+```
+$ qst log running 5 --unit miles
+'Running' is measured in km, not miles.
+```
+
+## Exit codes
+
+An agent's only reliable error channel, so they are stable:
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 1 | Bad arguments or unparseable input |
+| 2 | Authentication failed, or the key lacks the required scope |
+| 3 | Unknown or ambiguous streak or quest |
+| 4 | Server or network error |
+
+On failure the server's `detail` message is printed verbatim to stderr.
+
+## Scopes
+
+A key only carries the permissions granted when it was created, and the server enforces
+them. Insufficient scope returns a message naming what is missing, so it is clear whether
+something is a bug or a deliberate restriction:
+
+```
+$ qst log reading 5
+API key is missing required scope(s): events:write
+```
+
+Deleting a streak has no scope at all — it is web-app only, because it also destroys every
+event, total and milestone beneath it. The same goes for deleting a quest or a Quest Log
+entry: `qst` has no delete command, and a key can archive a quest instead.
+
+Quest commands need `quests:read` (agenda, lists, show, log) and `quests:write`
+(everything else, archive included). Both are pre-checked when a key is created; older
+keys lack them, and `qst doctor` lists the scopes a key actually holds plus a hint naming
+the quest commands that will fail.
+
+## Using this with an AI assistant
+
+The repository ships an [Agent
+Skill](https://github.com/neuromaxer/quaestor-lite/blob/main/skills/quaestor/SKILL.md)
+that teaches an assistant when and how to use these commands, following the
+[agentskills.io](https://agentskills.io) format. Copy it to `~/.agents/skills/` (OpenClaw)
+or `~/.hermes/skills/` (Hermes Agent).
+
+Design notes and the security model are in the [feature
+documentation](https://github.com/neuromaxer/quaestor-lite/blob/main/docs/features/agent-connect/agent-connect.md).
+
+## Requirements
+
+Python 3.12+. Depends only on `httpx` and `typer` — it speaks HTTP and never imports the
+Quaestor backend, so it installs in seconds and tolerates version skew against the server.

quaestor_cli-0.3.0/README.md

@@ -0,0 +1,199 @@
+# quaestor-cli
+
+`qst` — a command-line client for [Quaestor](https://quaestor.app), an agent-native
+platform for diary-based life management. An evening diary becomes tracked habits,
+quest progress, and a morning plan.
+
+Built for two users at once: a person in a terminal, and an AI assistant acting on their
+behalf. That second audience shapes most of the design — commands are task-shaped rather
+than endpoint-shaped, streaks and quests are addressed by name, failures are
+distinguishable by exit code, and the server's own error message is printed verbatim so
+an agent can relay something true.
+
+```bash
+uv tool install quaestor-cli
+```
+
+## Setup
+
+Create an API key in the Quaestor web app under **Profile → Developer Access**.
+Set the backend URL, then store the key from stdin. On macOS, copy the key and run:
+
+```bash
+export QUAESTOR_URL="https://your-quaestor-backend"   # defaults to http://localhost:8000
+pbpaste | qst auth login
+qst doctor
+```
+
+On other systems, run `qst auth login`, paste the key, press Enter, then signal
+end-of-input (Ctrl-D on Unix).
+
+The key is stored at `~/.config/quaestor/credentials.json` with mode `0600`. The
+CLI also supports `QUAESTOR_API_KEY`; an existing environment variable takes
+precedence over the file, but it is not needed for this setup.
+
+`qst` refuses to send a key over plain HTTP to anything but a loopback host. Set
+`QUAESTOR_ALLOW_INSECURE=1` only if you are knowingly running a plaintext self-hosted
+backend.
+
+## The evening diary workflow
+
+Spend 10–15 minutes writing or recording your day. Your agent uses `qst` to log
+measured habits, record quest progress, and plan the work you want to do tomorrow.
+It reports what changed and prepares a short morning plan with Main and Side Quests.
+
+Keep the original diary with your agent or in a place you choose. The CLI stores
+habit records and quest-specific notes in Quaestor, not a general diary entry.
+Those original entries become a record of your progress and a story worth keeping.
+
+## Commands
+
+```
+qst streaks                      List streaks with mode, unit and target
+qst show <streak>                Full configuration plus per-day totals, including missed days
+qst log <streak> <value>         Log a COUNT amount
+qst log <streak> --minutes 45    Log a TIME block (45, 45m, 1h30m, 1.5h)
+qst events <streak>              Individual entries, newest first, with the source of each
+qst review                       Totals, active days and current streak per streak
+qst timer start|stop|status      Control the single running timer
+qst auth login|whoami|logout     Manage the stored credential
+qst doctor                       Check URL, reachability, credential and granted scopes
+
+qst agenda [--week|--days N]     Overdue, past deadline, ready to plan, and each day's quests
+qst quests [words] [filters]     Find quests: --status, --overdue, --on, --from/--to,
+                                 --deadline-by, --under <quest>, --archived, --sort, --limit
+qst quest show <quest>           Status, dates, sub-quest progress, description, latest Quest Log
+qst quest log <quest>            Quest Log entries, newest first (--date for one day)
+qst quest add <title>            --under <quest> --on fri --due <date> --priority high --emoji 🚀 ...
+qst quest edit <quest>           --title --emoji --priority --start/--due (or 'none') --under/--top-level
+qst quest status <quest> <s>     backlog | todo | in-progress | done | archived
+qst quest archive <quest>        Hide it and its sub-quests (there is no delete)
+qst quest plan <quest> <day>...  Plan days; a Backlog quest becomes Todo
+qst quest unplan <quest> <day>   Remove a planned day (never demotes)
+qst quest reschedule <q> <from> [to]   Move one planned day (to today by default)
+qst quest check <quest>          Check off a day (--date, --undo); starts Backlog/Todo quests
+qst quest note <quest> <text>    Append to that day's Quest Log entry (--date, --replace)
+qst quest link|unlink <quest> <streak>  Link a streak (context only, nothing syncs)
+```
+
+Every command takes `--json` for machine-readable output on stdout. Every write takes
+`--dry-run`, which prints the request and sends nothing.
+
+### Windows
+
+`events`, `show` and `review` share one set of window flags: `--today`, `--week`
+(default), `--days N`, or an explicit `--from` / `--to`. The explicit and relative forms
+cannot be combined. Dates accept `today`, `yesterday`, a weekday (`mon`..`sun`, meaning
+the most recent past one), `YYYY-MM-DD`, or an offset like `-3d`.
+
+### Streaks are named, never UUIDs
+
+`<streak>` is a name. Resolution tries exact match, then unique prefix, then unique
+substring. On zero or multiple matches it exits `3`, lists the candidates, and writes
+nothing — it never guesses.
+
+```
+$ qst log r 1
+Streak 'r' is ambiguous — candidates: Reading, Running. Nothing was written.
+```
+
+### Quests are named too — by title or path
+
+`<quest>` is a title, or a path of titles that names the parents as well:
+`"Launch > Backend > Schema"` (`›` works too). The server resolves it — exact, then unique
+prefix, then unique substring; archived quests only when nothing live matches — and on
+zero or several matches `qst` exits `3`, prints the candidates' full paths, and writes
+nothing.
+
+```
+$ qst quest check "write migration"
+Quest 'write migration' is ambiguous — 2 quests match: Launch › Backend › Write migration;
+Blog › Write migration. Use a path such as 'Launch > Backend > Write migration' to pick one.
+Nothing was written.
+```
+
+With `--json`, the failure is one JSON document on stdout: `{"error": {"exit_code": 3,
+"message": ..., "candidates": [...]}}`.
+
+### Which way date words point
+
+Where you plan (`add --on/--due/--start`, `plan`, a reschedule target, `agenda`/`quests
+--from/--to`), a weekday means the **coming** one: `fri` on a Wednesday is this Friday,
+and today if it is Friday; `next fri` is a week later; `+1w` is a week from today.
+Where you record (`check --date`, `note --date`, streak commands), a weekday is the most
+recent one and `last fri` is strictly before today; `check` refuses future days.
+Where you name a day the quest already has (`reschedule`'s first day, `unplan`), a
+weekday picks the quest's own date on that weekday within a week of today, in either
+direction — so `qst quest reschedule report tue thu` works whether Tuesday was yesterday
+or is next week.
+
+### Retrying writes safely
+
+Dropped connections are retried automatically with the same idempotency key. If a write
+still fails with exit 4, the message includes the key; re-run with
+`qst --idempotency-key <key> ...` (or set `QUAESTOR_IDEMPOTENCY_KEY`) and the server
+replays the original write instead of creating a duplicate.
+
+Quest reads send your local date (`today=`), so overdue and "today" match the web app.
+Writes that change a status automatically say so (`Status: Todo → In progress.`).
+
+### `--unit` is a safety check, not data
+
+Units belong to the streak, not the event, so `--unit` is never sent to the API. It
+asserts what you believe the streak measures and fails before writing if you are wrong —
+which is what stops an assistant logging "5 miles" as 5 km.
+
+```
+$ qst log running 5 --unit miles
+'Running' is measured in km, not miles.
+```
+
+## Exit codes
+
+An agent's only reliable error channel, so they are stable:
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 1 | Bad arguments or unparseable input |
+| 2 | Authentication failed, or the key lacks the required scope |
+| 3 | Unknown or ambiguous streak or quest |
+| 4 | Server or network error |
+
+On failure the server's `detail` message is printed verbatim to stderr.
+
+## Scopes
+
+A key only carries the permissions granted when it was created, and the server enforces
+them. Insufficient scope returns a message naming what is missing, so it is clear whether
+something is a bug or a deliberate restriction:
+
+```
+$ qst log reading 5
+API key is missing required scope(s): events:write
+```
+
+Deleting a streak has no scope at all — it is web-app only, because it also destroys every
+event, total and milestone beneath it. The same goes for deleting a quest or a Quest Log
+entry: `qst` has no delete command, and a key can archive a quest instead.
+
+Quest commands need `quests:read` (agenda, lists, show, log) and `quests:write`
+(everything else, archive included). Both are pre-checked when a key is created; older
+keys lack them, and `qst doctor` lists the scopes a key actually holds plus a hint naming
+the quest commands that will fail.
+
+## Using this with an AI assistant
+
+The repository ships an [Agent
+Skill](https://github.com/neuromaxer/quaestor-lite/blob/main/skills/quaestor/SKILL.md)
+that teaches an assistant when and how to use these commands, following the
+[agentskills.io](https://agentskills.io) format. Copy it to `~/.agents/skills/` (OpenClaw)
+or `~/.hermes/skills/` (Hermes Agent).
+
+Design notes and the security model are in the [feature
+documentation](https://github.com/neuromaxer/quaestor-lite/blob/main/docs/features/agent-connect/agent-connect.md).
+
+## Requirements
+
+Python 3.12+. Depends only on `httpx` and `typer` — it speaks HTTP and never imports the
+Quaestor backend, so it installs in seconds and tolerates version skew against the server.

quaestor_cli-0.3.0/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "quaestor-cli"
+version = "0.3.0"
+description = "Command-line client for the Quaestor API — built for humans and agents."
+readme = "README.md"
+requires-python = ">=3.12"
+# NOTE: no `license` yet — the repository has no LICENSE file, so publishing one here
+# would be inventing a licensing decision. Until one is chosen, PyPI shows no license,
+# which legally means all rights reserved.
+keywords = ["quaestor", "habit-tracker", "cli", "agent", "ai"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    # 0.16 is the first release that defaults pretty_exceptions_show_locals to False.
+    # Older versions render local variables — including the API key — into a crash
+    # traceback. main.py also sets the flag explicitly; this floor is belt and braces.
+    "typer>=0.16",
+]
+
+[project.urls]
+Homepage = "https://quaestor.app"
+Repository = "https://github.com/neuromaxer/quaestor-lite"
+Documentation = "https://github.com/neuromaxer/quaestor-lite/blob/main/apps/cli/README.md"
+Issues = "https://github.com/neuromaxer/quaestor-lite/issues"
+
+[project.scripts]
+qst = "quaestor_cli.main:app"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "ruff>=0.6",
+    "mypy>=1.11",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/quaestor_cli"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 110
+target-version = "py312"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_unreachable = true

{quaestor_cli-0.2.0 → quaestor_cli-0.3.0}/src/quaestor_cli/client.py

@@ -6,6 +6,7 @@ level adds ~18ms to every invocation, including `qst --help`.
 
 from __future__ import annotations
 
+import time
 from collections.abc import Mapping
 from dataclasses import dataclass
 from typing import Any
@@ -15,6 +16,7 @@ from quaestor_cli.errors import CliError, ExitCode
 
 API_PREFIX = "/api/v1"
 DEFAULT_TIMEOUT_SECONDS = 15.0
+RETRY_BACKOFF_SECONDS = 0.5  # 0.5s, then 1s: enough to ride out a blip, short for an agent turn
 
 # Maps an HTTP failure onto the exit code an agent should act on.
 _STATUS_EXIT_CODES: dict[int, ExitCode] = {
@@ -135,26 +137,40 @@ class QuaestorClient:
         params: Mapping[str, Any] | None = None,
         body: Mapping[str, Any] | None = None,
         check: bool = True,
+        retries: int = 0,
     ) -> ApiResponse:
-        """Send one request, mapping transport and HTTP failures to CliError."""
+        """Send one request, mapping transport and HTTP failures to CliError.
+
+        `retries` re-sends the *same* request after a transport failure (timeout, dropped
+        connection), never after an HTTP error. Only pass it for requests that are safe to
+        repeat: idempotent ones, or writes carrying an idempotency key.
+        """
         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
+        attempt = 0
+        while True:
+            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,
+                )
+                break
+            except httpx.TransportError as exc:
+                if attempt >= retries:
+                    raise CliError(f"Cannot reach {url}: {exc}", ExitCode.SERVER) from exc
+                attempt += 1
+                time.sleep(RETRY_BACKOFF_SECONDS * attempt)
+            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))
+            raise CliError(response.detail, exit_code_for(response.status_code))
         return response
 
     def _headers(self) -> dict[str, str]:
@@ -165,7 +181,7 @@ class QuaestorClient:
         return headers
 
 
-def _exit_code_for(status_code: int) -> ExitCode:
+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)
 

{quaestor_cli-0.2.0 → quaestor_cli-0.3.0}/src/quaestor_cli/commands/doctor.py

@@ -15,6 +15,26 @@ from quaestor_cli.runtime import CliState, JsonFlag, cli_state, execute
 
 UNKNOWN = "unknown"
 
+# Scopes a key needs for each command family. Keys made before Quests existed lack
+# the quest scopes; new keys get them by default (both pre-checked in the dashboard).
+FEATURE_SCOPES: dict[str, str] = {
+    "quests:read": "qst agenda, qst quests, qst quest show/log",
+    "quests:write": "qst quest add/plan/check/note/link/archive",
+}
+NEW_KEY_HINT = (
+    "Create a new key in the web app (Profile → Developer Access): "
+    "new keys include quests:read and quests:write by default."
+)
+
+
+def scope_hints(scopes: list[str] | None) -> list[str]:
+    """Explain which commands a key's missing scopes switch off, and how to fix it."""
+    if scopes is None:
+        return []
+    missing = [scope for scope in FEATURE_SCOPES if scope not in scopes]
+    hints = [f"{scope} not granted — {FEATURE_SCOPES[scope]} will fail (403)." for scope in missing]
+    return [*hints, NEW_KEY_HINT] if hints else []
+
 
 @dataclass(frozen=True)
 class Diagnosis:
@@ -30,6 +50,8 @@ class Diagnosis:
     """None when the server has no /auth/whoami, i.e. scopes are unknowable."""
     user: str | None = None
     detail: str | None = None
+    hints: tuple[str, ...] = ()
+    """Advice that isn't a failure, e.g. scopes a key was created without."""
 
     @property
     def exit_code(self) -> ExitCode:
@@ -89,6 +111,7 @@ def diagnose(state: CliState) -> Diagnosis:
         scopes=scopes,
         user=user,
         detail=detail,
+        hints=tuple(scope_hints(scopes)),
     )
 
 
@@ -129,11 +152,14 @@ def _check_credential(state: CliState) -> _CredentialCheck:
 
 def _lines(diagnosis: Diagnosis) -> tuple[str, ...]:
     """Render the diagnosis as aligned human-readable lines."""
-    scopes = (
-        format_scopes(diagnosis.scopes)
-        if diagnosis.scopes is not None
-        else f"{UNKNOWN} (this server has no /auth/whoami)"
-    )
+    if diagnosis.scopes is not None:
+        scopes = format_scopes(diagnosis.scopes)
+    elif not diagnosis.authenticated:
+        # The credential was rejected, so scopes were never knowable. Blaming the
+        # server's age here points the reader at the wrong problem.
+        scopes = f"{UNKNOWN} (credential was rejected)"
+    else:
+        scopes = f"{UNKNOWN} (this server has no /auth/whoami)"
     fields = (
         ("cli version", diagnosis.cli_version),
         ("base url", diagnosis.base_url),
@@ -144,4 +170,6 @@ def _lines(diagnosis: Diagnosis) -> tuple[str, ...]:
         ("user", diagnosis.user or "-"),
         ("scopes", scopes),
     )
-    return tuple(f"{label + ':':<15}{value}" for label, value in fields)
+    lines = [f"{label + ':':<15}{value}" for label, value in fields]
+    lines += [f"{'hint:':<15}{hint}" for hint in diagnosis.hints]
+    return tuple(lines)