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

{quaestor_cli-0.3.0 → quaestor_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quaestor-cli
-Version: 0.3.0
+Version: 0.3.1
 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
@@ -39,10 +39,9 @@ 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:
+The CLI uses the hosted production API automatically. 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
 ```
@@ -54,9 +53,9 @@ 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.
+Logging in again replaces the key while preserving an existing server override.
+`qst doctor` reports authentication as unknown when the server cannot verify it;
+only an explicit authentication refusal means the key was rejected.
 
 ## The evening diary workflow
 
@@ -219,3 +218,15 @@ documentation](https://github.com/neuromaxer/quaestor-lite/blob/main/docs/featur
 
 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.
+
+## Developer configuration
+
+Use `qst --dev doctor` to target `http://localhost:8000` for that invocation.
+The development flag is hidden from normal help and never persists a local URL.
+
+Staging and self-hosted deployments can still use `QUAESTOR_URL` or an existing
+`base_url` in the credential store. Resolution order is `--dev`, environment, stored
+URL, then the hosted production default. Ordinary hosted setup needs no override.
+
+`qst` refuses to send a key over plain HTTP except to loopback. Set
+`QUAESTOR_ALLOW_INSECURE=1` only for deliberate plaintext development deployments.

{quaestor_cli-0.3.0 → quaestor_cli-0.3.1}/README.md

@@ -17,10 +17,9 @@ 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:
+The CLI uses the hosted production API automatically. 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
 ```
@@ -32,9 +31,9 @@ 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.
+Logging in again replaces the key while preserving an existing server override.
+`qst doctor` reports authentication as unknown when the server cannot verify it;
+only an explicit authentication refusal means the key was rejected.
 
 ## The evening diary workflow
 
@@ -197,3 +196,15 @@ documentation](https://github.com/neuromaxer/quaestor-lite/blob/main/docs/featur
 
 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.
+
+## Developer configuration
+
+Use `qst --dev doctor` to target `http://localhost:8000` for that invocation.
+The development flag is hidden from normal help and never persists a local URL.
+
+Staging and self-hosted deployments can still use `QUAESTOR_URL` or an existing
+`base_url` in the credential store. Resolution order is `--dev`, environment, stored
+URL, then the hosted production default. Ordinary hosted setup needs no override.
+
+`qst` refuses to send a key over plain HTTP except to loopback. Set
+`QUAESTOR_ALLOW_INSECURE=1` only for deliberate plaintext development deployments.

{quaestor_cli-0.3.0 → quaestor_cli-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "quaestor-cli"
-version = "0.3.0"
+version = "0.3.1"
 description = "Command-line client for the Quaestor API — built for humans and agents."
 readme = "README.md"
 requires-python = ">=3.12"

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

@@ -10,7 +10,7 @@ from quaestor_cli import __version__, api
 from quaestor_cli.client import QuaestorClient
 from quaestor_cli.config import ENV_API_KEY, credentials_path
 from quaestor_cli.errors import CliError, ExitCode
-from quaestor_cli.output import emit, emit_json, format_scopes
+from quaestor_cli.output import emit, emit_json, format_scopes, warn
 from quaestor_cli.runtime import CliState, JsonFlag, cli_state, execute
 
 UNKNOWN = "unknown"
@@ -45,7 +45,7 @@ class Diagnosis:
     credential_source: str
     key_label: str
     reachable: bool
-    authenticated: bool
+    authenticated: bool | None
     scopes: list[str] | None
     """None when the server has no /auth/whoami, i.e. scopes are unknowable."""
     user: str | None = None
@@ -58,6 +58,8 @@ class Diagnosis:
         """Worst problem found decides the exit code."""
         if not self.reachable:
             return ExitCode.SERVER
+        if self.authenticated is None:
+            return ExitCode.SERVER
         if not self.authenticated:
             return ExitCode.AUTH
         return ExitCode.OK
@@ -77,7 +79,12 @@ def _run(state: CliState) -> None:
     else:
         emit(*_lines(diagnosis))
     if diagnosis.exit_code is not ExitCode.OK:
-        raise CliError(diagnosis.detail or "Health check failed.", diagnosis.exit_code)
+        detail = diagnosis.detail or "Health check failed."
+        if state.json_output:
+            # The diagnosis already includes the failure; keep stdout one JSON document.
+            warn(detail)
+            raise typer.Exit(code=int(diagnosis.exit_code))
+        raise CliError(detail, diagnosis.exit_code)
 
 
 def diagnose(state: CliState) -> Diagnosis:
@@ -86,13 +93,14 @@ def diagnose(state: CliState) -> Diagnosis:
     anonymous = QuaestorClient(base_url=state.config.base_url)
     health = anonymous.probe(api.HEALTHZ_PATH)
 
-    authenticated = False
+    authenticated: bool | None = None
     scopes: list[str] | None = None
     user: str | None = None
     detail: str | None = None
     if not health.is_success:
         detail = health.detail
     elif credential is None:
+        authenticated = False
         detail = f"No API key: set {ENV_API_KEY} or run 'qst auth login'."
     else:
         auth = _check_credential(state)
@@ -106,7 +114,7 @@ def diagnose(state: CliState) -> Diagnosis:
         base_url=state.config.base_url,
         credential_source=credential.source if credential else "none",
         key_label=credential.label if credential else "-",
-        reachable=health.is_success,
+        reachable=health.reachable,
         authenticated=authenticated,
         scopes=scopes,
         user=user,
@@ -119,7 +127,7 @@ def diagnose(state: CliState) -> Diagnosis:
 class _CredentialCheck:
     """What the identity lookup could establish about the credential."""
 
-    authenticated: bool
+    authenticated: bool | None
     scopes: list[str] | None
     user: str | None
     detail: str | None
@@ -138,12 +146,17 @@ def _check_credential(state: CliState) -> _CredentialCheck:
             detail=None,
         )
     if not lookup.is_unsupported:
-        return _CredentialCheck(authenticated=False, scopes=None, user=None, detail=lookup.probe.detail)
+        return _CredentialCheck(
+            authenticated=False if lookup.probe.rejected_credential else None,
+            scopes=None,
+            user=None,
+            detail=lookup.probe.detail,
+        )
 
     # Server predates /auth/whoami: doctor must still say whether the key works.
     fallback = client.probe(api.STREAKS_PATH, {"limit": 1})
     return _CredentialCheck(
-        authenticated=fallback.is_success,
+        authenticated=True if fallback.is_success else False if fallback.rejected_credential else None,
         scopes=None,
         user=None,
         detail=None if fallback.is_success else fallback.detail,
@@ -154,19 +167,31 @@ def _lines(diagnosis: Diagnosis) -> tuple[str, ...]:
     """Render the diagnosis as aligned human-readable lines."""
     if diagnosis.scopes is not None:
         scopes = format_scopes(diagnosis.scopes)
+    elif not diagnosis.reachable:
+        scopes = f"{UNKNOWN} (host unreachable)"
+    elif diagnosis.authenticated is None:
+        scopes = f"{UNKNOWN} (authentication check failed)"
+    elif diagnosis.credential_source == "none":
+        scopes = f"{UNKNOWN} (no API key)"
     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)"
+    if not diagnosis.reachable:
+        authenticated = f"{UNKNOWN} (host unreachable)"
+    elif diagnosis.authenticated is None:
+        authenticated = f"{UNKNOWN} (authentication check failed)"
+    else:
+        authenticated = "yes" if diagnosis.authenticated else "no"
     fields = (
         ("cli version", diagnosis.cli_version),
         ("base url", diagnosis.base_url),
         ("credential", f"{diagnosis.credential_source} ({diagnosis.key_label})"),
         ("store", str(credentials_path())),
         ("reachable", "yes" if diagnosis.reachable else "no"),
-        ("authenticated", "yes" if diagnosis.authenticated else "no"),
+        ("authenticated", authenticated),
         ("user", diagnosis.user or "-"),
         ("scopes", scopes),
     )

{quaestor_cli-0.3.0 → quaestor_cli-0.3.1}/src/quaestor_cli/config.py

@@ -1,9 +1,4 @@
-"""Credential and base-URL resolution.
-
-The environment is the primary mechanism (`QUAESTOR_API_KEY`, `QUAESTOR_URL`);
-`~/.config/quaestor/credentials.json` is the fallback store written by
-`qst auth login`. The environment always wins over the file.
-"""
+"""Resolve credentials and developer URL overrides, defaulting to hosted Quaestor."""
 
 from __future__ import annotations
 
@@ -16,7 +11,8 @@ from urllib.parse import urlparse
 
 from quaestor_cli.errors import auth_error, server_error, usage_error
 
-DEFAULT_BASE_URL = "http://localhost:8000"
+DEFAULT_BASE_URL = "https://ql-backend-fniqyq6lfa-ey.a.run.app"
+LOCAL_BASE_URL = "http://localhost:8000"
 ENV_API_KEY = "QUAESTOR_API_KEY"
 ENV_BASE_URL = "QUAESTOR_URL"
 
@@ -79,8 +75,8 @@ def credentials_path() -> Path:
     return config_dir() / "credentials.json"
 
 
-def load_config() -> Config:
-    """Resolve base URL and credential from the environment, then the file."""
+def load_config(*, dev: bool = False) -> Config:
+    """Resolve an explicit dev target, then environment, file, and hosted defaults."""
     stored = _read_credentials_file()
     env_key = os.environ.get(ENV_API_KEY, "").strip()
 
@@ -91,7 +87,7 @@ def load_config() -> Config:
         credential = Credential(api_key=stored.api_key, source="file")
 
     env_url = os.environ.get(ENV_BASE_URL, "").strip()
-    base_url = (env_url or stored.base_url or DEFAULT_BASE_URL).rstrip("/")
+    base_url = (LOCAL_BASE_URL if dev else env_url or stored.base_url or DEFAULT_BASE_URL).rstrip("/")
     return Config(base_url=base_url, credential=credential)
 
 
@@ -157,7 +153,11 @@ def save_credential(api_key: str) -> Path:
     os.chmod(directory, _CREDENTIALS_DIR_MODE)
 
     path = credentials_path()
-    payload = json.dumps({"api_key": key}, indent=2) + "\n"
+    stored = _read_credentials_file()
+    contents = {"api_key": key}
+    if stored.base_url:
+        contents["base_url"] = stored.base_url
+    payload = json.dumps(contents, indent=2) + "\n"
     # Open with the mode up front so the secret is never briefly world-readable,
     # then chmod as well for the case where the file already existed.
     fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, _CREDENTIALS_FILE_MODE)

{quaestor_cli-0.3.0 → quaestor_cli-0.3.1}/src/quaestor_cli/main.py

@@ -47,12 +47,13 @@ def main(
         help="Reuse this key when retrying a write (add, note, log) so it is applied once.",
     ),
     version: bool = typer.Option(False, "--version", help="Print the CLI version and exit."),
+    dev: bool = typer.Option(False, "--dev", hidden=True, help="Use the local development API."),
 ) -> None:
     """Accept global flags before the subcommand, e.g. `qst --json streaks`."""
     if version:
         typer.echo(__version__)
         raise typer.Exit()
-    ctx.obj = RootFlags(json_output=json_output, dry_run=dry_run, idempotency_key=idempotency_key)
+    ctx.obj = RootFlags(json_output=json_output, dry_run=dry_run, idempotency_key=idempotency_key, dev=dev)
 
 
 def _with_window_rules(summary: str) -> str:

{quaestor_cli-0.3.0 → quaestor_cli-0.3.1}/src/quaestor_cli/runtime.py

@@ -36,6 +36,7 @@ class RootFlags:
     json_output: bool = False
     dry_run: bool = False
     idempotency_key: str | None = None
+    dev: bool = False
 
 
 def _default_idempotency_key() -> str:
@@ -74,7 +75,7 @@ def cli_state(ctx: typer.Context, json_output: bool = False, dry_run: bool = Fal
     return CliState(
         json_output=json_output or root.json_output,
         dry_run=dry_run or root.dry_run,
-        config=load_config(),
+        config=load_config(dev=root.dev),
         **extra,
     )
 

{quaestor_cli-0.3.0 → quaestor_cli-0.3.1}/tests/test_cli_auth.py

@@ -10,7 +10,7 @@ import pytest
 import respx
 from typer.testing import CliRunner
 
-from conftest import FAKE_KEY
+from conftest import BASE_URL, FAKE_KEY
 from factories import (
     API_KEY_ID,
     AUTH_USER_ID,
@@ -18,7 +18,7 @@ from factories import (
     streak_payload,
     whoami_payload,
 )
-from quaestor_cli.config import credentials_path
+from quaestor_cli.config import DEFAULT_BASE_URL, LOCAL_BASE_URL, credentials_path, load_config
 from quaestor_cli.main import app
 
 STORED_KEY = "qst_live_fedcba9876543210_stored-secret"
@@ -44,6 +44,76 @@ def test_login_without_input_exits_one(runner: CliRunner) -> None:
     assert "No API key on stdin" in result.stderr
 
 
+def test_login_preserves_stored_server_when_replacing_key(
+    runner: CliRunner, api_mock: respx.MockRouter, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Logging in again keeps the server that subsequent commands use."""
+    path = credentials_path()
+    path.parent.mkdir(parents=True)
+    path.write_text(json.dumps({"api_key": FAKE_KEY, "base_url": BASE_URL}))
+    monkeypatch.delenv("QUAESTOR_URL")
+    monkeypatch.delenv("QUAESTOR_API_KEY")
+    api_mock.get("/auth/whoami").mock(return_value=httpx.Response(200, json=whoami_payload()))
+
+    login = runner.invoke(app, ["auth", "login"], input=f"{STORED_KEY}\n")
+
+    assert login.exit_code == 0, login.output
+    assert json.loads(path.read_text()) == {"api_key": STORED_KEY, "base_url": BASE_URL}
+    assert stat.S_IMODE(path.stat().st_mode) == 0o600
+    whoami = runner.invoke(app, ["auth", "whoami", "--json"])
+    assert whoami.exit_code == 0, whoami.output
+    assert json.loads(whoami.stdout)["base_url"] == BASE_URL
+    assert api_mock.calls.last.request.headers["authorization"] == f"Bearer {STORED_KEY}"
+
+
+def test_login_uses_hosted_api_without_url_configuration(
+    runner: CliRunner, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Fresh setup reaches production after storing only the API key."""
+    monkeypatch.delenv("QUAESTOR_URL")
+    monkeypatch.delenv("QUAESTOR_API_KEY")
+    assert DEFAULT_BASE_URL.startswith("https://")
+    assert DEFAULT_BASE_URL != LOCAL_BASE_URL
+
+    login = runner.invoke(app, ["auth", "login"], input=f"{STORED_KEY}\n")
+
+    assert login.exit_code == 0, login.output
+    with respx.mock(base_url=f"{DEFAULT_BASE_URL}/api/v1") as mock:
+        whoami = mock.get("/auth/whoami").mock(return_value=httpx.Response(200, json=whoami_payload()))
+        result = runner.invoke(app, ["auth", "whoami", "--json"])
+
+    assert result.exit_code == 0, result.output
+    assert json.loads(result.stdout)["base_url"] == DEFAULT_BASE_URL
+    assert whoami.calls.last.request.headers["authorization"] == f"Bearer {STORED_KEY}"
+
+
+def test_dev_flag_overrides_other_servers_without_changing_the_store(
+    runner: CliRunner,
+) -> None:
+    """Local testing is explicit and does not change the server for later commands."""
+    path = credentials_path()
+    path.parent.mkdir(parents=True)
+    contents = {"api_key": STORED_KEY, "base_url": "https://staging.example"}
+    path.write_text(json.dumps(contents))
+
+    with respx.mock(base_url=f"{LOCAL_BASE_URL}/api/v1") as mock:
+        mock.get("/auth/whoami").mock(return_value=httpx.Response(200, json=whoami_payload()))
+        result = runner.invoke(app, ["--dev", "auth", "whoami", "--json"])
+
+    assert result.exit_code == 0, result.output
+    assert json.loads(result.stdout)["base_url"] == LOCAL_BASE_URL
+    assert json.loads(path.read_text()) == contents
+    assert load_config().base_url == BASE_URL
+
+
+def test_dev_flag_is_not_shown_in_normal_help(runner: CliRunner) -> None:
+    """Development configuration stays out of the normal setup path."""
+    result = runner.invoke(app, ["--help"], color=False)
+
+    assert result.exit_code == 0, result.output
+    assert "--dev" not in result.stdout
+
+
 def test_stored_key_is_used_when_environment_is_empty(
     runner: CliRunner, api_mock: respx.MockRouter, monkeypatch: pytest.MonkeyPatch
 ) -> None:

{quaestor_cli-0.3.0 → quaestor_cli-0.3.1}/tests/test_cli_timer_review_doctor.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import json
 
 import httpx
+import pytest
 import respx
 from typer.testing import CliRunner
 
@@ -277,9 +278,76 @@ def test_doctor_reports_unreachable_backend(runner: CliRunner, api_mock: respx.M
 
     assert result.exit_code == 4
     assert "reachable:     no" in result.stdout
+    assert "authenticated: unknown (host unreachable)" in result.stdout
+    assert "scopes:        unknown (host unreachable)" in result.stdout
+    assert "credential was rejected" not in result.stdout
     assert "Cannot reach" in result.stderr
 
 
+def test_doctor_reports_unknown_authentication_in_json_when_unreachable(
+    runner: CliRunner, api_mock: respx.MockRouter
+) -> None:
+    """An unreachable host cannot establish whether the credential works."""
+    api_mock.get("/healthz").mock(side_effect=httpx.ConnectError("connection refused"))
+
+    result = runner.invoke(app, ["doctor", "--json"])
+
+    assert result.exit_code == 4, result.output
+    diagnosis = json.loads(result.stdout)
+    assert diagnosis["reachable"] is False
+    assert diagnosis["authenticated"] is None
+    assert diagnosis["scopes"] is None
+    assert len(api_mock.calls) == 1
+
+
+@pytest.mark.parametrize("response", ["connection", "server"])
+def test_doctor_reports_unknown_when_authentication_check_fails(
+    runner: CliRunner, api_mock: respx.MockRouter, response: str
+) -> None:
+    """A working health check does not turn a failed identity lookup into rejection."""
+    api_mock.get("/healthz").mock(return_value=httpx.Response(200, json={"ok": True}))
+    identity = api_mock.get("/auth/whoami")
+    if response == "connection":
+        identity.mock(side_effect=httpx.ConnectError("connection refused"))
+    else:
+        identity.mock(return_value=httpx.Response(503, json={"detail": "Unavailable"}))
+
+    result = runner.invoke(app, ["doctor"])
+
+    assert result.exit_code == 4, result.output
+    assert "reachable:     yes" in result.stdout
+    assert "authenticated: unknown (authentication check failed)" in result.stdout
+    assert "credential was rejected" not in result.stdout
+
+
+def test_doctor_reports_reachable_but_unhealthy_server(runner: CliRunner, api_mock: respx.MockRouter) -> None:
+    """A server that answers with 503 is reachable, but cannot verify the key."""
+    api_mock.get("/healthz").mock(return_value=httpx.Response(503, json={"detail": "Unavailable"}))
+
+    result = runner.invoke(app, ["doctor", "--json"])
+
+    assert result.exit_code == 4, result.output
+    diagnosis = json.loads(result.stdout)
+    assert diagnosis["reachable"] is True
+    assert diagnosis["authenticated"] is None
+    assert diagnosis["detail"] == "Unavailable"
+    assert len(api_mock.calls) == 1
+
+
+def test_doctor_does_not_claim_rejection_when_no_key_is_configured(
+    runner: CliRunner, api_mock: respx.MockRouter, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A missing credential has never been presented for authentication."""
+    monkeypatch.delenv("QUAESTOR_API_KEY")
+    api_mock.get("/healthz").mock(return_value=httpx.Response(200, json={"ok": True}))
+
+    result = runner.invoke(app, ["doctor"])
+
+    assert result.exit_code == 2, result.output
+    assert "scopes:        unknown (no API key)" in result.stdout
+    assert "credential was rejected" not in result.stdout
+
+
 def test_doctor_reports_bad_credential(runner: CliRunner, api_mock: respx.MockRouter) -> None:
     """Backend is up but the key is rejected; doctor exits with the auth code."""
     api_mock.get("/healthz").mock(return_value=httpx.Response(200, json={"ok": True}))

{quaestor_cli-0.3.0 → quaestor_cli-0.3.1}/uv.lock

@@ -416,7 +416,7 @@ wheels = [
 
 [[package]]
 name = "quaestor-cli"
-version = "0.3.0"
+version = "0.3.1"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },