driftwatch-llm 0.1.0__tar.gz

driftwatch_llm-0.1.0/.gitignore

@@ -0,0 +1,94 @@
+# ---------------------------------------------------------------------------
+# DriftWatch .gitignore
+# Rule of thumb: nothing that holds a secret, a local path, a build output or
+# runtime data belongs in git. If a pattern here ever stops matching a file you
+# need, fix the pattern; do not force-add the file.
+# ---------------------------------------------------------------------------
+
+# --- Secrets and local environment ------------------------------------------
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+*.pfx
+credentials.json
+secrets.yaml
+# Local tooling config: points assistants at a Supabase project, and local
+# permission settings can hold tokens.
+.mcp.json
+.claude/
+# A folder linked with `driftwatch init` (project id only). Stays on the machine.
+.driftwatch/
+
+# --- Python ---------------------------------------------------------------
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+.venv/
+venv/
+env/
+*.egg
+*.egg-info/
+.eggs/
+dist/
+build/
+wheelhouse/
+*.whl
+
+# --- Test, coverage and lint output ----------------------------------------
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.tox/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.playwright-cli/
+playwright-report/
+test-results/
+
+# --- Node / Next.js (frontend) ---------------------------------------------
+node_modules/
+.next/
+out/
+.vercel/
+*.tsbuildinfo
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# --- Runtime data, databases and reports ------------------------------------
+*.db
+*.db-journal
+*.sqlite
+*.sqlite3
+*.sqlite3-wal
+*.sqlite3-shm
+eval_reports/
+data/baseline_embeddings/
+data/canary_probes/
+data/synthetic_degradation/
+logs/
+*.log
+
+# --- Local planning and scratch (kept out of the public repo) ---------------
+# Docs/ holds specs, plans and decision logs. It is NOT backed up by git: copy
+# it somewhere safe (a private repo, cloud drive) if you change machines.
+Docs/
+.superpowers/
+
+# --- OS and editors ----------------------------------------------------------
+.DS_Store
+Thumbs.db
+desktop.ini
+.vscode/
+.idea/
+*.swp
+*.swo

driftwatch_llm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rajvardhan Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

driftwatch_llm-0.1.0/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.5
+Name: driftwatch-llm
+Version: 0.1.0
+Summary: Command-line tool for DriftWatch, a drift monitor for LLM apps.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: keyring>=25
+Requires-Dist: platformdirs>=4
+Requires-Dist: tomli>=2; python_version < '3.11'
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# driftwatch-llm
+
+Command-line tool for [DriftWatch](https://drift-watch-rouge.vercel.app), a drift monitor for LLM apps.
+
+**Status: early.** This release only links a project folder to your DriftWatch account:
+
+```
+pip install driftwatch-llm
+driftwatch init      # sign in through your browser and link this folder to a project
+driftwatch status
+driftwatch logout
+```
+
+It does not monitor anything yet. The background agent and the local dashboard come in later releases.
+
+What it stores on your machine: one project API key in your OS keychain (or a private file if no
+keychain exists), a trust record, and `.driftwatch/config.toml` in your project folder, which holds a
+project id and nothing else. Installing the package changes nothing; only the commands above do.
+
+MIT licensed.

driftwatch_llm-0.1.0/driftwatch_llm/README.md

@@ -0,0 +1,20 @@
+# driftwatch-llm
+
+Command-line tool for [DriftWatch](https://drift-watch-rouge.vercel.app), a drift monitor for LLM apps.
+
+**Status: early.** This release only links a project folder to your DriftWatch account:
+
+```
+pip install driftwatch-llm
+driftwatch init      # sign in through your browser and link this folder to a project
+driftwatch status
+driftwatch logout
+```
+
+It does not monitor anything yet. The background agent and the local dashboard come in later releases.
+
+What it stores on your machine: one project API key in your OS keychain (or a private file if no
+keychain exists), a trust record, and `.driftwatch/config.toml` in your project folder, which holds a
+project id and nothing else. Installing the package changes nothing; only the commands above do.
+
+MIT licensed.

driftwatch_llm-0.1.0/driftwatch_llm/__init__.py

@@ -0,0 +1,7 @@
+"""DriftWatch command-line tool.
+
+Importing this package has no side effects: it reads no files, opens no sockets
+and installs no hooks. Everything happens only when a command runs.
+"""
+
+__version__ = "0.1.0"

driftwatch_llm-0.1.0/driftwatch_llm/__main__.py

@@ -0,0 +1,4 @@
+from driftwatch_llm.cli import app
+
+if __name__ == "__main__":
+    app()

driftwatch_llm-0.1.0/driftwatch_llm/api.py

@@ -0,0 +1,140 @@
+"""The CLI's only network client: PostgREST RPC calls to the pinned DriftWatch project.
+
+It sends the publishable key and nothing else (no session, no service key). Every error becomes a
+fixed, user-safe sentence: request bodies (device codes, API keys) and raw server text never appear.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from driftwatch_llm import __version__
+from driftwatch_llm.endpoints import Endpoints
+from driftwatch_llm.secrets import KEY_RE
+from driftwatch_llm.validate import clean_text, is_uuid
+
+_DEVICE_CODE_RE = re.compile(r"^[0-9a-f]{64}$")
+_USER_CODE_RE = re.compile(r"^[BCDFGHJKLMNPQRSTVWXZ]{8}$")
+_STATUSES = {"authorization_pending", "slow_down", "approved", "access_denied", "expired_token", "key_limit"}
+_UNEXPECTED = "Unexpected response from DriftWatch. Try again, or update driftwatch-llm."
+_UNREACHABLE = "Could not reach DriftWatch. Check your connection and try again."
+
+
+class ApiError(Exception):
+    """A failed call. The message is safe to print."""
+
+
+@dataclass(frozen=True)
+class DeviceStart:
+    device_code: str
+    user_code: str
+    expires_in: int
+    interval: int
+
+
+@dataclass(frozen=True)
+class PollResult:
+    status: str
+    api_key: str | None = None
+    project_id: str | None = None
+    project_name: str | None = None
+
+    def __repr__(self) -> str:  # never let a key reach a log line through repr()
+        return f"PollResult(status={self.status!r}, project_id={self.project_id!r})"
+
+
+def _is_int(value: object, low: int, high: int) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool) and low <= value <= high
+
+
+def _error_for(status: int, body: object) -> ApiError:
+    code = body.get("code") if isinstance(body, dict) else None
+    message = body.get("message") if isinstance(body, dict) else None
+    if code == "PT429" or status == 429:
+        return ApiError("Too many sign-in requests. Try again in a minute.")
+    if code == "PT422":
+        # PT422 texts are written by our own SQL; anything long or odd gets a fixed sentence.
+        text = clean_text(message, 120)
+        return ApiError(text if text and isinstance(message, str) and len(message) <= 120 else "That request was not accepted.")
+    if status in (401, 403):
+        return ApiError("Your request was not accepted.")
+    return ApiError(f"DriftWatch had a problem (HTTP {status}). Try again later.")
+
+
+class Api:
+    def __init__(
+        self,
+        endpoints: Endpoints,
+        transport: httpx.BaseTransport | None = None,
+        timeout: float = 15.0,
+    ) -> None:
+        self._ep = endpoints
+        self._transport = transport
+        self._timeout = timeout
+
+    def _rpc(self, fn: str, body: dict[str, Any], *, want_json: bool = True) -> Any:
+        url = f"{self._ep.supabase_url}/rest/v1/rpc/{fn}"
+        headers = {
+            "apikey": self._ep.publishable_key,
+            "content-type": "application/json",
+            "user-agent": f"driftwatch-llm/{__version__}",
+        }
+        try:
+            with httpx.Client(transport=self._transport, timeout=self._timeout, follow_redirects=False) as client:
+                response = client.post(url, json=body, headers=headers)
+        except httpx.HTTPError:
+            raise ApiError(_UNREACHABLE) from None
+        if response.status_code >= 400:
+            try:
+                parsed: object = response.json()
+            except ValueError:
+                parsed = None
+            raise _error_for(response.status_code, parsed)
+        if not want_json:
+            return None
+        try:
+            return response.json()
+        except ValueError:
+            raise ApiError(_UNEXPECTED) from None
+
+    def start_device_login(self, device_name: str, device_os: str) -> DeviceStart:
+        data = self._rpc("start_device_login", {"p_device_name": device_name, "p_device_os": device_os})
+        if not isinstance(data, dict):
+            raise ApiError(_UNEXPECTED)
+        device_code, user_code = data.get("device_code"), data.get("user_code")
+        expires_in, interval = data.get("expires_in"), data.get("interval")
+        if (
+            not isinstance(device_code, str) or not _DEVICE_CODE_RE.match(device_code)
+            or not isinstance(user_code, str) or not _USER_CODE_RE.match(user_code)
+            or not _is_int(expires_in, 1, 3600) or not _is_int(interval, 1, 60)
+        ):
+            raise ApiError(_UNEXPECTED)
+        return DeviceStart(device_code=device_code, user_code=user_code, expires_in=expires_in, interval=interval)
+
+    def poll_device_login(self, device_code: str) -> PollResult:
+        data = self._rpc("poll_device_login", {"p_device_code": device_code})
+        if not isinstance(data, dict):
+            raise ApiError(_UNEXPECTED)
+        status = data.get("status")
+        if status not in _STATUSES:
+            raise ApiError(_UNEXPECTED)
+        if status != "approved":
+            if "api_key" in data:
+                raise ApiError(_UNEXPECTED)  # a key outside "approved" is never accepted
+            return PollResult(status=status)
+        key, project_id = data.get("api_key"), data.get("project_id")
+        if not isinstance(key, str) or not KEY_RE.match(key) or not is_uuid(project_id):
+            raise ApiError(_UNEXPECTED)
+        return PollResult(
+            status="approved",
+            api_key=key,
+            project_id=project_id,
+            project_name=clean_text(data.get("project_name")) or "your project",
+        )
+
+    def revoke_api_key(self, api_key: str) -> None:
+        self._rpc("revoke_api_key_by_secret", {"p_api_key": api_key}, want_json=False)

driftwatch_llm-0.1.0/driftwatch_llm/cli.py

@@ -0,0 +1,331 @@
+"""The `driftwatch` command.
+
+Nothing runs in the background yet. These commands link a project folder to a DriftWatch project
+(init, login, logout, trust, status) and clean up (uninstall). Services (API client, keychain, trust
+store, clock) are injected through the Typer context so tests need no network and no real keychain.
+"""
+
+from __future__ import annotations
+
+import platform
+import shutil
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Mapping, NoReturn
+
+import typer
+
+from driftwatch_llm import __version__, paths
+from driftwatch_llm.api import Api, ApiError, PollResult
+from driftwatch_llm.device_flow import LoginDenied, LoginExpired, LoginFailed, run_device_login
+from driftwatch_llm.endpoints import EndpointError, Endpoints, resolve
+from driftwatch_llm.hooks import remove_autostart_hook
+from driftwatch_llm.project import (
+    ConfigError,
+    ProjectConfig,
+    ensure_gitignore,
+    find_project_root,
+    read_config,
+    write_config,
+)
+from driftwatch_llm.secrets import SecretStore
+from driftwatch_llm.trust import TrustStore
+from driftwatch_llm.validate import clean_text
+
+app = typer.Typer(
+    help="DriftWatch: link a project folder to drift monitoring.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+@dataclass
+class Services:
+    endpoints: Endpoints
+    api: Any
+    secrets: SecretStore
+    trust: TrustStore
+    home: Path
+    cwd: Callable[[], Path] = Path.cwd
+    open_url: Callable[[str], object] | None = None
+    sleep: Callable[[float], None] = time.sleep
+    clock: Callable[[], float] = time.monotonic
+    device_name: str | None = None
+    device_os: str | None = None
+
+
+def build_services(dev: bool, env: Mapping[str, str] | None = None) -> Services:
+    endpoints = resolve(dev, env)
+    home = paths.config_dir()
+    return Services(
+        endpoints=endpoints,
+        api=Api(endpoints),
+        secrets=SecretStore(home=home),
+        trust=TrustStore(home=home),
+        home=home,
+    )
+
+
+def _version(value: bool) -> None:
+    if value:
+        typer.echo(f"driftwatch-llm {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    version: bool = typer.Option(False, "--version", callback=_version, is_eager=True, help="Show the version and exit."),
+    dev: bool = typer.Option(False, "--dev", hidden=True, help="Use DRIFTWATCH_DEV_* endpoints (development only)."),
+) -> None:
+    """DriftWatch: link a project folder to drift monitoring."""
+    if ctx.obj is None:
+        try:
+            ctx.obj = build_services(dev)
+        except EndpointError as exc:
+            typer.echo(f"Error: {exc}.", err=True)
+            raise typer.Exit(2) from None
+
+
+def _svc(ctx: typer.Context) -> Services:
+    return ctx.obj  # type: ignore[no-any-return]
+
+
+def _fail(message: str, code: int = 1) -> NoReturn:
+    typer.echo(message, err=True)
+    raise typer.Exit(code)
+
+
+def _device_name(s: Services) -> str:
+    return s.device_name or clean_text(platform.node()) or "unknown device"
+
+
+def _device_os(s: Services) -> str:
+    return s.device_os or clean_text(f"{platform.system()} {platform.release()}") or "unknown OS"
+
+
+def _device_login(s: Services, open_browser: bool) -> PollResult:
+    try:
+        return run_device_login(
+            s.api,
+            device_name=_device_name(s),
+            device_os=_device_os(s),
+            web_origin=s.endpoints.web_origin,
+            open_browser=open_browser,
+            echo=typer.echo,
+            open_url=s.open_url,
+            sleep=s.sleep,
+            clock=s.clock,
+        )
+    except KeyboardInterrupt:
+        typer.echo("Cancelled.")
+        raise typer.Exit(130) from None
+    except (LoginDenied, LoginExpired, LoginFailed, ApiError) as exc:
+        _fail(f"Error: {exc}")
+
+
+def _revoke_quietly(s: Services, key: str) -> None:
+    try:
+        s.api.revoke_api_key(key)
+    except Exception:  # noqa: BLE001 - best effort; the key is also visible on the keys page
+        pass
+
+
+def _read_config(root: Path) -> ProjectConfig:
+    try:
+        cfg = read_config(root)
+    except ConfigError as exc:
+        _fail(f"Error: {exc}.")
+    if cfg is None:
+        _fail("Error: no .driftwatch/config.toml here.")
+    return cfg
+
+
+def _project(s: Services) -> tuple[Path, ProjectConfig]:
+    root = find_project_root(s.cwd())
+    if root is None:
+        _fail("No DriftWatch project here. Run `driftwatch init` first.")
+    return root, _read_config(root)
+
+
+def _store_key(s: Services, project_id: str, key: str) -> str:
+    """Save the new key, then revoke the key it replaces (never one that came from the environment)."""
+    previous = s.secrets.load(project_id)
+    where = s.secrets.save(project_id, key)
+    if previous and previous[1] != "env" and previous[0] != key:
+        _revoke_quietly(s, previous[0])
+    return where
+
+
+@app.command()
+def init(
+    ctx: typer.Context,
+    force: bool = typer.Option(False, "--force", help="Link this folder again, even if it already has a config."),
+    no_browser: bool = typer.Option(False, "--no-browser", help="Print the link instead of opening a browser."),
+) -> None:
+    """Sign in through your browser and link this folder to a DriftWatch project."""
+    s = _svc(ctx)
+    root = s.cwd()
+    try:
+        cfg = read_config(root)
+    except ConfigError as exc:
+        _fail(f"Error: {exc}.")
+    if cfg is not None and not force:
+        if s.trust.is_trusted(root, cfg.project_id):
+            typer.echo(f"Already linked to project {cfg.project_id}. Use --force to link again.")
+            return
+        _fail(
+            f"This folder already has a .driftwatch/config.toml for project {cfg.project_id}, "
+            "but you have not trusted it.\n"
+            "  To use that project, run: driftwatch trust\n"
+            "  To link this folder to a project of your own, run: driftwatch init --force"
+        )
+
+    typer.echo(
+        "This will:\n"
+        "  - sign you in through your browser\n"
+        "  - write .driftwatch/config.toml (a project id, nothing else)\n"
+        "  - add .driftwatch/ to .gitignore\n"
+        "  - store a project key in your OS keychain (or a private file if there is none)\n"
+        "  - mark this folder as trusted\n"
+        "Nothing runs in the background yet."
+    )
+    result = _device_login(s, open_browser=not no_browser)
+    assert result.api_key and result.project_id  # guaranteed by the client for "approved"
+
+    try:
+        write_config(root, result.project_id)
+        ensure_gitignore(root)
+        where = _store_key(s, result.project_id, result.api_key)
+        s.trust.trust(root, result.project_id)
+    except (OSError, ConfigError):
+        _revoke_quietly(s, result.api_key)
+        s.secrets.delete(result.project_id)
+        _fail("Error: could not save the link on this machine. The new key was revoked. Check the folder permissions and try again.")
+
+    place = "your OS keychain" if where == "keychain" else "a private file in your user config folder"
+    typer.echo(f'Linked to project "{result.project_name}" ({result.project_id}).')
+    typer.echo(f"Key stored in {place}.")
+
+
+@app.command()
+def login(
+    ctx: typer.Context,
+    no_browser: bool = typer.Option(False, "--no-browser", help="Print the link instead of opening a browser."),
+) -> None:
+    """Get a fresh key for this folder's project (for example on a new machine)."""
+    s = _svc(ctx)
+    root, cfg = _project(s)
+    if not s.trust.is_trusted(root, cfg.project_id):
+        _fail("This folder is not trusted yet. Run `driftwatch trust` first.")
+    result = _device_login(s, open_browser=not no_browser)
+    assert result.api_key and result.project_id
+    if result.project_id != cfg.project_id:
+        _revoke_quietly(s, result.api_key)
+        _fail(
+            "You approved a different project than the one this folder is linked to. Nothing changed.\n"
+            "To link this folder to that project instead, run: driftwatch init --force"
+        )
+    _store_key(s, cfg.project_id, result.api_key)
+    typer.echo("Signed in. A new key is stored on this machine.")
+
+
+@app.command()
+def logout(ctx: typer.Context) -> None:
+    """Revoke this machine's key for the project and remove it."""
+    s = _svc(ctx)
+    _, cfg = _project(s)
+    found = s.secrets.load(cfg.project_id)
+    if found is None:
+        typer.echo("No key is stored for this project on this machine.")
+        return
+    key, source = found
+    if source == "env":
+        typer.echo("The key comes from DRIFTWATCH_API_KEY, which logout does not change. Unset the variable yourself.")
+        return
+    try:
+        s.api.revoke_api_key(key)
+        typer.echo("Key revoked on the server.")
+    except ApiError as exc:
+        typer.echo(f"Could not revoke the key on the server ({exc}). Revoke it on the keys page of the website.")
+    s.secrets.delete(cfg.project_id)
+    typer.echo("Removed the key from this machine.")
+
+
+@app.command()
+def trust(
+    ctx: typer.Context,
+    yes: bool = typer.Option(False, "--yes", "-y", help="Do not ask for confirmation."),
+) -> None:
+    """Trust this folder's .driftwatch config (needed for a folder you cloned)."""
+    s = _svc(ctx)
+    root = find_project_root(s.cwd())
+    if root is None:
+        _fail("Error: no .driftwatch/config.toml found in this folder or above.")
+    cfg = _read_config(root)
+    if s.trust.is_trusted(root, cfg.project_id):
+        typer.echo("Already trusted.")
+        return
+    typer.echo(f"Folder:  {root}\nProject: {cfg.project_id}")
+    if cfg.ignored_keys:
+        typer.echo(f"Ignored settings in that file (DriftWatch never reads them): {', '.join(cfg.ignored_keys)}")
+    if not yes and not typer.confirm("Trust this folder for this project?", default=False):
+        typer.echo("Not trusted.")
+        raise typer.Exit(1)
+    s.trust.trust(root, cfg.project_id)
+    typer.echo("Trusted. Run `driftwatch login` to get a key for this machine.")
+
+
+@app.command()
+def status(ctx: typer.Context) -> None:
+    """Show what this folder is linked to. Never prints a key."""
+    s = _svc(ctx)
+    typer.echo(f"server: {s.endpoints.web_origin}")
+    root = find_project_root(s.cwd())
+    if root is None:
+        typer.echo("No DriftWatch project found from here. Run `driftwatch init` to link this folder.")
+        return
+    cfg = _read_config(root)
+    trusted = s.trust.is_trusted(root, cfg.project_id)
+    typer.echo(f"project: {cfg.project_id}")
+    typer.echo(f"folder: {root}")
+    typer.echo(f"trusted: {'yes' if trusted else 'no'}")
+    typer.echo(f"key: {s.secrets.source(cfg.project_id)}")
+    if cfg.ignored_keys:
+        typer.echo(f"ignored settings in the config: {', '.join(cfg.ignored_keys)}")
+    if not trusted:
+        typer.echo("This folder is not trusted. Run `driftwatch trust` if you want to use it.")
+
+
+@app.command()
+def uninstall(
+    ctx: typer.Context,
+    yes: bool = typer.Option(False, "--yes", "-y", help="Do not ask for confirmation."),
+    project: bool = typer.Option(False, "--project", help="Also remove this folder's .driftwatch directory."),
+) -> None:
+    """Remove everything this tool stored on this machine."""
+    s = _svc(ctx)
+    typer.echo("This will remove, from this machine only:")
+    typer.echo("  - every stored project key (keychain and private file)")
+    typer.echo("  - the list of trusted folders")
+    typer.echo("  - the autostart hook, if one was installed")
+    if project:
+        typer.echo("  - this folder's .driftwatch directory")
+    if not yes and not typer.confirm("Continue?", default=False):
+        typer.echo("Cancelled.")
+        raise typer.Exit(1)
+    s.secrets.delete_all()
+    s.trust.clear()
+    remove_autostart_hook()
+    try:
+        s.home.rmdir()  # only succeeds when nothing else lives there
+    except OSError:
+        pass
+    if project:
+        root = find_project_root(s.cwd())
+        if root is not None:
+            shutil.rmtree(root / ".driftwatch", ignore_errors=True)
+    typer.echo("Removed.")
+    typer.echo("To finish, run: pip uninstall driftwatch-llm")
+    typer.echo("Keys you created stay valid on the server until you revoke them on the keys page of the website.")

driftwatch_llm-0.1.0/driftwatch_llm/device_flow.py

@@ -0,0 +1,89 @@
+"""Browser sign-in for the CLI (RFC 8628 device authorization).
+
+The CLI shows a short code and a link, the user approves on the website, and the CLI polls until it
+receives a project key. Time, sleeping, printing and the browser are injected so tests need no
+network and no real waiting.
+"""
+
+from __future__ import annotations
+
+import time
+import webbrowser
+from typing import Callable
+from urllib.parse import quote
+
+from driftwatch_llm.api import Api, ApiError, PollResult
+
+_MAX_CONSECUTIVE_ERRORS = 3
+
+
+class LoginDenied(Exception):
+    """The user chose Deny on the website."""
+
+
+class LoginExpired(Exception):
+    """The code expired before anyone approved it."""
+
+
+class LoginFailed(Exception):
+    """Sign-in could not finish. The message is safe to print."""
+
+
+def run_device_login(
+    api: Api,
+    *,
+    device_name: str,
+    device_os: str,
+    web_origin: str,
+    open_browser: bool = True,
+    echo: Callable[[str], None] = print,
+    open_url: Callable[[str], object] | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+    clock: Callable[[], float] = time.monotonic,
+) -> PollResult:
+    start = api.start_device_login(device_name, device_os)
+    dashed = f"{start.user_code[:4]}-{start.user_code[4:]}"
+    url = f"{web_origin}/auth/device?code={quote(dashed)}"
+
+    echo(f"Your code: {dashed}")
+    echo("Open this link in your browser to approve it:")
+    echo(f"  {url}")
+    echo("Only approve this if you started it yourself.")
+    if open_browser:
+        opener = open_url or webbrowser.open
+        try:
+            opened = bool(opener(url))
+        except Exception:  # noqa: BLE001 - a missing browser must never stop sign-in
+            opened = False
+        if not opened:
+            echo("Could not open a browser here. Open the link above yourself.")
+    echo("Waiting for approval (Ctrl+C to cancel)...")
+
+    deadline = clock() + start.expires_in
+    interval = float(start.interval)
+    errors = 0
+    while True:
+        sleep(interval)
+        try:
+            result = api.poll_device_login(start.device_code)
+            errors = 0
+        except ApiError as exc:
+            errors += 1
+            if errors > _MAX_CONSECUTIVE_ERRORS:
+                raise LoginFailed(str(exc)) from None
+            if clock() >= deadline:
+                raise LoginExpired("The sign-in code expired. Run the command again.") from None
+            continue
+
+        if result.status == "approved":
+            return result
+        if result.status == "access_denied":
+            raise LoginDenied("The sign-in was denied.")
+        if result.status == "expired_token":
+            raise LoginExpired("The sign-in code expired. Run the command again.")
+        if result.status == "key_limit":
+            raise LoginFailed("This project already has 10 active keys. Revoke one on the website and try again.")
+        if result.status == "slow_down":
+            interval += 5
+        if clock() >= deadline:
+            raise LoginExpired("The sign-in code expired. Run the command again.")

driftwatch_llm-0.1.0/driftwatch_llm/endpoints.py

@@ -0,0 +1,61 @@
+"""Where the CLI talks to. Pinned in the package so a project's own files can never redirect it.
+
+Only the global `--dev` flag lets `DRIFTWATCH_DEV_*` environment variables override these values,
+and even then plain http is accepted only for loopback hosts.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Mapping
+from urllib.parse import urlsplit
+
+
+class EndpointError(ValueError):
+    """A dev endpoint override was refused. The message names the setting, never its value."""
+
+
+@dataclass(frozen=True)
+class Endpoints:
+    supabase_url: str
+    publishable_key: str  # public by design: it only identifies the project to the API gateway
+    web_origin: str
+
+
+PINNED = Endpoints(
+    supabase_url="https://zaodlvgqowhdqobvvhpx.supabase.co",
+    publishable_key="sb_publishable_mMch89F43lrLgpGHPKbhgg_Z43-lzes",
+    web_origin="https://drift-watch-rouge.vercel.app",
+)
+
+_LOOPBACK = {"localhost", "127.0.0.1", "::1"}
+
+
+def _checked_url(setting: str, value: str) -> str:
+    parts = urlsplit(value)
+    if parts.username or parts.password:
+        raise EndpointError(f"{setting} must not contain credentials")
+    if parts.scheme == "https" and parts.hostname:
+        return value.rstrip("/")
+    if parts.scheme == "http" and parts.hostname in _LOOPBACK:
+        return value.rstrip("/")
+    raise EndpointError(f"{setting} must be an https URL, or http on localhost")
+
+
+def resolve(dev: bool, env: Mapping[str, str] | None = None) -> Endpoints:
+    if not dev:
+        return PINNED
+    env = os.environ if env is None else env
+
+    def pick(name: str, fallback: str, *, url: bool = True) -> str:
+        raw = (env.get(name) or "").strip()
+        if not raw:
+            return fallback
+        return _checked_url(name, raw) if url else raw
+
+    return Endpoints(
+        supabase_url=pick("DRIFTWATCH_DEV_SUPABASE_URL", PINNED.supabase_url),
+        publishable_key=pick("DRIFTWATCH_DEV_SUPABASE_KEY", PINNED.publishable_key, url=False),
+        web_origin=pick("DRIFTWATCH_DEV_WEB_ORIGIN", PINNED.web_origin),
+    )

driftwatch_llm-0.1.0/driftwatch_llm/fileutil.py

@@ -0,0 +1,37 @@
+"""Small file helpers: private (owner-only) atomic writes."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+_POSIX = os.name == "posix"
+
+
+def write_private(path: Path, text: str) -> None:
+    """Write `text` to `path` atomically, readable only by the current user (POSIX: 0600, dir 0700).
+
+    On Windows the file inherits the user profile ACL, which is owner-only by default.
+    """
+    path = Path(path)
+    parent = path.parent
+    created = not parent.exists()
+    parent.mkdir(parents=True, exist_ok=True)
+    if created and _POSIX:
+        os.chmod(parent, 0o700)
+    fd, tmp = tempfile.mkstemp(dir=parent, prefix=".tmp-")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as f:
+            f.write(text)
+            f.flush()
+            os.fsync(f.fileno())
+        if _POSIX:
+            os.chmod(tmp, 0o600)
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise

driftwatch_llm-0.1.0/driftwatch_llm/hooks.py

@@ -0,0 +1,37 @@
+"""The optional autostart hook (installed by a later release; `uninstall` already knows how to remove it).
+
+Only an explicit `driftwatch init` may ever install this file, and `driftwatch uninstall` removes it.
+The wheel itself ships no .pth file.
+"""
+
+from __future__ import annotations
+
+import site
+from pathlib import Path
+from typing import Iterable
+
+AUTOSTART_PTH = "driftwatch_llm_autostart.pth"
+
+
+def _site_dirs() -> list[Path]:
+    dirs: list[str] = []
+    for getter in (site.getsitepackages, lambda: [site.getusersitepackages()]):
+        try:
+            dirs.extend(getter())
+        except Exception:  # noqa: BLE001 - some embedded or virtual environments lack these
+            pass
+    return [Path(d) for d in dirs]
+
+
+def remove_autostart_hook(site_dirs: Iterable[Path] | None = None) -> list[Path]:
+    """Delete our own .pth file from the given (or the current environment's) site directories."""
+    removed: list[Path] = []
+    for directory in site_dirs if site_dirs is not None else _site_dirs():
+        target = Path(directory) / AUTOSTART_PTH
+        try:
+            if target.is_file():
+                target.unlink()
+                removed.append(target)
+        except OSError:
+            pass
+    return removed

driftwatch_llm-0.1.0/driftwatch_llm/paths.py

@@ -0,0 +1,16 @@
+"""Where the CLI keeps its per-user files (trust record, fallback credentials)."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import platformdirs
+
+
+def config_dir() -> Path:
+    """`DRIFTWATCH_HOME` wins (tests, containers); otherwise the platform user config directory."""
+    override = os.environ.get("DRIFTWATCH_HOME")
+    if override:
+        return Path(override)
+    return Path(platformdirs.user_config_dir("driftwatch-llm", appauthor=False))

driftwatch_llm-0.1.0/driftwatch_llm/project.py

@@ -0,0 +1,106 @@
+"""The per-project folder: `.driftwatch/config.toml` and the `.gitignore` entry.
+
+The config file holds a project id and a mode, nothing else. It never holds an endpoint or a
+secret (hardening item C1): a cloned repository can ship any config it likes, so this module
+reads two keys, ignores the rest, and nothing else in the package reads the file.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # Python 3.10
+    import tomli as tomllib  # type: ignore[no-redef]
+
+from driftwatch_llm.validate import is_uuid
+
+CONFIG_DIR_NAME = ".driftwatch"
+CONFIG_FILE_NAME = "config.toml"
+MAX_CONFIG_BYTES = 8192
+_KNOWN = {"project_id", "mode"}
+_SAFE_NAME = re.compile(r"^[A-Za-z0-9_.-]{1,40}$")
+_GITIGNORE_ENTRIES = {".driftwatch", ".driftwatch/", "/.driftwatch", "/.driftwatch/"}
+
+
+class ConfigError(ValueError):
+    """The project config is missing something or malformed. Messages never quote the file."""
+
+
+@dataclass(frozen=True)
+class ProjectConfig:
+    project_id: str
+    mode: str
+    ignored_keys: tuple[str, ...] = ()
+
+
+def config_path(root: Path) -> Path:
+    return Path(root) / CONFIG_DIR_NAME / CONFIG_FILE_NAME
+
+
+def write_config(root: Path, project_id: str) -> Path:
+    if not is_uuid(project_id):
+        raise ConfigError("project id must be a UUID")
+    path = config_path(root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        "# Written by `driftwatch init`.\n"
+        "# This folder holds a project id and nothing else: no endpoint and no secret belongs here.\n"
+        f'project_id = "{project_id}"\n'
+        'mode = "cloud"\n',
+        encoding="utf-8",
+        newline="\n",
+    )
+    return path
+
+
+def read_config(root: Path) -> ProjectConfig | None:
+    path = config_path(root)
+    try:
+        raw = path.read_bytes()
+    except FileNotFoundError:
+        return None
+    except OSError:
+        raise ConfigError("could not read the project config") from None
+    if len(raw) > MAX_CONFIG_BYTES:
+        raise ConfigError("the project config is too large")
+    try:
+        data = tomllib.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, tomllib.TOMLDecodeError):
+        raise ConfigError("the project config is not valid TOML") from None
+    project_id = data.get("project_id")
+    if not is_uuid(project_id):
+        raise ConfigError("the project config needs a project_id that is a UUID")
+    if data.get("mode") != "cloud":
+        raise ConfigError('the project config needs mode = "cloud"')
+    ignored = sorted(
+        {(k if _SAFE_NAME.match(k) else "<invalid name>") for k in data if k not in _KNOWN}
+    )
+    return ProjectConfig(project_id=str(project_id), mode="cloud", ignored_keys=tuple(ignored))
+
+
+def find_project_root(start: Path) -> Path | None:
+    """Walk up from `start` to the nearest folder that has `.driftwatch/config.toml`."""
+    here = Path(start).resolve()
+    for folder in (here, *here.parents):
+        if config_path(folder).is_file():
+            return folder
+    return None
+
+
+def ensure_gitignore(root: Path) -> bool:
+    """Make sure `.driftwatch/` is git-ignored. Returns True if the file changed."""
+    path = Path(root) / ".gitignore"
+    try:
+        existing = path.read_bytes().decode("utf-8", errors="replace")
+    except FileNotFoundError:
+        existing = ""
+    if any(line.strip() in _GITIGNORE_ENTRIES for line in existing.splitlines()):
+        return False
+    eol = "\r\n" if "\r\n" in existing else "\n"
+    prefix = "" if not existing or existing.endswith(("\n", "\r")) else eol
+    path.write_bytes((existing + prefix + ".driftwatch/" + eol).encode("utf-8"))
+    return True

driftwatch_llm-0.1.0/driftwatch_llm/secrets.py

@@ -0,0 +1,172 @@
+"""Where the project API key lives on this machine.
+
+Lookup order: OS keychain, then the `DRIFTWATCH_API_KEY` environment variable, then a private
+file (`credentials.json`, mode 0600) in the user config dir. Saving tries the keychain first and
+falls back to the file when no keychain exists (Docker, CI, WSL, headless Linux).
+
+Nothing here ever prints, logs or raises with a key in its message.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import Any, Mapping
+
+from driftwatch_llm import paths
+from driftwatch_llm.fileutil import write_private
+from driftwatch_llm.validate import is_uuid
+
+SERVICE = "driftwatch-llm"
+ENV_VAR = "DRIFTWATCH_API_KEY"
+KEY_RE = re.compile(r"^dw_[0-9a-f]{10}_[0-9a-f]{64}$")
+
+
+class SecretError(ValueError):
+    """Invalid input to the secret store. Messages never contain the value."""
+
+
+def _default_backend() -> Any | None:
+    try:
+        import keyring
+        from keyring.backends import fail
+
+        kr = keyring.get_keyring()
+        if isinstance(kr, fail.Keyring) or getattr(kr, "priority", 1) <= 0:
+            return None
+        return keyring
+    except Exception:  # noqa: BLE001 - any keychain problem means "no keychain"
+        return None
+
+
+class SecretStore:
+    def __init__(
+        self,
+        home: Path | None = None,
+        backend: Any | None = None,
+        env: Mapping[str, str] | None = None,
+    ) -> None:
+        self._home = Path(home) if home is not None else paths.config_dir()
+        self._injected = backend is not None
+        self._backend = backend
+        self._env = os.environ if env is None else env
+
+    def __repr__(self) -> str:
+        return f"SecretStore(home={str(self._home)!r})"
+
+    # -- file -----------------------------------------------------------------
+    @property
+    def _file(self) -> Path:
+        return self._home / "credentials.json"
+
+    def _read(self) -> dict[str, Any]:
+        empty: dict[str, Any] = {"version": 1, "keys": {}, "keychain_projects": []}
+        try:
+            data = json.loads(self._file.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return empty
+        if not isinstance(data, dict):
+            return empty
+        keys = data.get("keys")
+        index = data.get("keychain_projects")
+        return {
+            "version": 1,
+            "keys": (
+                {k: v for k, v in keys.items() if isinstance(k, str) and isinstance(v, str)}
+                if isinstance(keys, dict)
+                else {}
+            ),
+            "keychain_projects": [p for p in index if isinstance(p, str)] if isinstance(index, list) else [],
+        }
+
+    def _write(self, data: dict[str, Any]) -> None:
+        if not data["keys"] and not data["keychain_projects"]:
+            try:
+                self._file.unlink()
+            except OSError:
+                pass
+            return
+        write_private(self._file, json.dumps(data, indent=2) + "\n")
+
+    # -- keychain -------------------------------------------------------------
+    def _kr(self) -> Any | None:
+        if self._injected:
+            return self._backend
+        if self._backend is None:
+            self._backend = _default_backend()
+        return self._backend
+
+    # -- public API -----------------------------------------------------------
+    def save(self, project_id: str, key: str) -> str:
+        """Store `key` for the project. Returns where it went: "keychain" or "file"."""
+        if not is_uuid(project_id):
+            raise SecretError("invalid project id")
+        if not isinstance(key, str) or not KEY_RE.match(key):
+            raise SecretError("invalid API key format")
+        data = self._read()
+        kr = self._kr()
+        if kr is not None:
+            try:
+                kr.set_password(SERVICE, project_id, key)
+                data["keys"].pop(project_id, None)  # drop a stale file copy
+                if project_id not in data["keychain_projects"]:
+                    data["keychain_projects"].append(project_id)
+                self._write(data)
+                return "keychain"
+            except Exception:  # noqa: BLE001 - never surface keychain errors: they can echo the value
+                pass
+        data["keys"][project_id] = key
+        data["keychain_projects"] = [p for p in data["keychain_projects"] if p != project_id]
+        self._write(data)
+        return "file"
+
+    def load(self, project_id: str) -> tuple[str, str] | None:
+        """Return (key, source) with source in {"keychain", "env", "file"}, or None."""
+        if not is_uuid(project_id):
+            return None
+        kr = self._kr()
+        if kr is not None:
+            try:
+                value = kr.get_password(SERVICE, project_id)
+                if isinstance(value, str) and KEY_RE.match(value):
+                    return value, "keychain"
+            except Exception:  # noqa: BLE001
+                pass
+        env_key = (self._env.get(ENV_VAR) or "").strip()
+        if KEY_RE.match(env_key):
+            return env_key, "env"
+        value = self._read()["keys"].get(project_id)
+        if isinstance(value, str) and KEY_RE.match(value):
+            return value, "file"
+        return None
+
+    def source(self, project_id: str) -> str:
+        found = self.load(project_id)
+        return found[1] if found else "none"
+
+    def delete(self, project_id: str) -> None:
+        """Remove this machine's stored key for the project (never touches the environment)."""
+        if not is_uuid(project_id):
+            return
+        kr = self._kr()
+        if kr is not None:
+            try:
+                kr.delete_password(SERVICE, project_id)
+            except Exception:  # noqa: BLE001
+                pass
+        data = self._read()
+        data["keys"].pop(project_id, None)
+        data["keychain_projects"] = [p for p in data["keychain_projects"] if p != project_id]
+        self._write(data)
+
+    def delete_all(self) -> None:
+        """Remove every key this machine stored, for every project."""
+        data = self._read()
+        for project_id in set(data["keychain_projects"]) | set(data["keys"]):
+            self.delete(project_id)
+        try:
+            self._file.unlink()
+        except OSError:
+            pass

driftwatch_llm-0.1.0/driftwatch_llm/trust.py

@@ -0,0 +1,69 @@
+"""Trust-on-first-use for project folders (hardening item C1).
+
+A folder is trusted only when the user ran `driftwatch init` or `driftwatch trust` there. The record
+is keyed by a hash of the folder's real path AND holds the project id, so a cloned repository that
+ships its own `.driftwatch/config.toml` stays inactive until the user says otherwise, and a trusted
+repository whose config is later changed to another project is untrusted again.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from driftwatch_llm import paths
+from driftwatch_llm.fileutil import write_private
+from driftwatch_llm.validate import is_uuid
+
+
+class TrustStore:
+    def __init__(self, home: Path | None = None) -> None:
+        self._home = Path(home) if home is not None else paths.config_dir()
+
+    @property
+    def _file(self) -> Path:
+        return self._home / "trust.json"
+
+    @staticmethod
+    def _key(root: Path) -> str:
+        normal = os.path.normcase(str(Path(root).resolve()))
+        return hashlib.sha256(normal.encode("utf-8")).hexdigest()
+
+    def _read(self) -> dict[str, str]:
+        try:
+            data: Any = json.loads(self._file.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return {}
+        folders = data.get("folders") if isinstance(data, dict) else None
+        if not isinstance(folders, dict):
+            return {}
+        return {k: v for k, v in folders.items() if isinstance(k, str) and isinstance(v, str)}
+
+    def _write(self, folders: dict[str, str]) -> None:
+        write_private(self._file, json.dumps({"version": 1, "folders": folders}, indent=2) + "\n")
+
+    def is_trusted(self, root: Path, project_id: str) -> bool:
+        if not is_uuid(project_id):
+            return False
+        return self._read().get(self._key(root)) == project_id
+
+    def trust(self, root: Path, project_id: str) -> None:
+        if not is_uuid(project_id):
+            raise ValueError("invalid project id")
+        folders = self._read()
+        folders[self._key(root)] = project_id
+        self._write(folders)
+
+    def untrust(self, root: Path) -> None:
+        folders = self._read()
+        if folders.pop(self._key(root), None) is not None:
+            self._write(folders)
+
+    def clear(self) -> None:
+        try:
+            self._file.unlink()
+        except OSError:
+            pass

driftwatch_llm-0.1.0/driftwatch_llm/validate.py

@@ -0,0 +1,20 @@
+"""Tiny shared validators."""
+
+from __future__ import annotations
+
+import re
+
+_UUID_RE = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.IGNORECASE)
+_CONTROL_RE = re.compile(r"[\x00-\x1f\x7f-\x9f]+")
+
+
+def is_uuid(value: object) -> bool:
+    return isinstance(value, str) and _UUID_RE.match(value) is not None
+
+
+def clean_text(value: object, limit: int = 64) -> str:
+    """Make server- or device-supplied text safe to print: no control characters (so no terminal
+    escape sequences), single spaces, at most `limit` characters."""
+    if not isinstance(value, str):
+        return ""
+    return " ".join(_CONTROL_RE.sub(" ", value).split())[:limit]

driftwatch_llm-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "driftwatch-llm"
+dynamic = ["version"]
+description = "Command-line tool for DriftWatch, a drift monitor for LLM apps."
+readme = "driftwatch_llm/README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = [
+  "typer>=0.12",
+  "httpx>=0.27",
+  "keyring>=25",
+  "platformdirs>=4",
+  'tomli>=2; python_version < "3.11"',
+]
+
+[project.scripts]
+driftwatch = "driftwatch_llm.cli:app"
+
+[tool.hatch.version]
+path = "driftwatch_llm/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["driftwatch_llm"]
+
+[tool.hatch.build.targets.sdist]
+include = ["driftwatch_llm", "pyproject.toml", "LICENSE"]