slopguard-cli 0.1.1__tar.gz → 0.2.0__tar.gz

{slopguard_cli-0.1.1 → slopguard_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slopguard-cli
-Version: 0.1.1
+Version: 0.2.0
 Summary: Defend developers and AI coding agents against slopsquatting (hallucinated package names).
 Project-URL: Homepage, https://github.com/hariomunknownslab/slopguard
 Project-URL: Repository, https://github.com/hariomunknownslab/slopguard

{slopguard_cli-0.1.1 → slopguard_cli-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "slopguard-cli"
-version = "0.1.1"
+version = "0.2.0"
 description = "Defend developers and AI coding agents against slopsquatting (hallucinated package names)."
 readme = "README.md"
 license = { text = "MIT" }

{slopguard_cli-0.1.1 → slopguard_cli-0.2.0}/slopguard/__init__.py

@@ -2,6 +2,6 @@
 
 from __future__ import annotations
 
-__version__ = "0.1.1"
+__version__ = "0.2.0"
 
 __all__ = ["__version__"]

{slopguard_cli-0.1.1 → slopguard_cli-0.2.0}/slopguard/cli.py

@@ -270,6 +270,13 @@ def scan_cmd(
         int | None, typer.Option("--concurrency", help="Maximum concurrent registry probes.")
     ] = None,
     verbose: Annotated[bool, typer.Option("--verbose", "-v", help="Show debug logs.")] = False,
+    upload: Annotated[
+        bool,
+        typer.Option(
+            "--upload",
+            help="Upload the scan to the SlopGuard SaaS after scanning. Requires `slopguard login`.",
+        ),
+    ] = False,
 ) -> None:
     """Scan a project for slopsquatted / hallucinated dependencies."""
     if verbose:
@@ -304,18 +311,192 @@ def scan_cmd(
     else:
         render_terminal_report(report, duration_seconds=duration)
 
+    if upload:
+        _upload_report(report, duration_ms=int(duration * 1000))
+
     raise typer.Exit(code=report.exit_code)
 
 
+def _upload_report(report: ScanReport, *, duration_ms: int) -> None:
+    """Persist a completed ScanReport to the SaaS via POST /v1/scans."""
+    from slopguard.saas import load_credentials
+    from slopguard.saas.client import ApiError, list_projects, post_scan
+
+    creds = load_credentials()
+    if creds is None:
+        raise _error_exit("upload requires `slopguard login` first.")
+    if creds.organization_id is None:
+        raise _error_exit(
+            "credentials missing organization_id; run `slopguard logout` then `slopguard login` again."
+        )
+
+    try:
+        projects = list_projects(creds.api_url, creds.token, creds.organization_id)
+    except ApiError as exc:
+        raise _error_exit(f"could not list projects: {exc.detail} (status {exc.status})") from exc
+    if not projects:
+        raise _error_exit("no project on this organization; visit the dashboard and create one.")
+    project_id = projects[0]["id"]
+
+    payload: dict[str, object] = {
+        "project_id": project_id,
+        "report": report.model_dump(mode="json"),
+        "source": _detect_runner(),
+        "duration_ms": duration_ms,
+    }
+    try:
+        created = post_scan(creds.api_url, creds.token, payload)
+    except ApiError as exc:
+        raise _error_exit(f"upload failed: {exc.detail} (status {exc.status})") from exc
+
+    Console().print(
+        f"[green]Uploaded[/green] to {creds.api_url}/app/{creds.org_slug}/scans/{created['id']}"
+    )
+
+
+def _detect_runner() -> str:
+    import os
+
+    if os.environ.get("GITHUB_ACTIONS") == "true":
+        return "ci"
+    if os.environ.get("CI") == "true":
+        return "ci"
+    return "cli"
+
+
 @app.command("version")
 def version_cmd() -> None:
     """Print the SlopGuard version and exit 0."""
     print(__version__)
 
 
-@app.command("update", hidden=True)
+@app.command("update")
 def update_cmd() -> None:
-    """(Stub) refresh the embedded hallucination database. See TODO(v0.2)."""
+    """Refresh the local hallucination DB from the SlopGuard SaaS feed.
+
+    No auth required. Downloads the public registry from
+    ``$SLOPGUARD_API_URL/v1/hallucinations`` (default: the SlopGuard SaaS)
+    and caches it at ``~/.cache/slopguard/hallucinations_db.json`` for the
+    next scan to read.
+    """
     from slopguard.update import run
 
     raise typer.Exit(code=run())
+
+
+# --- SaaS auth subcommands -------------------------------------------------
+#
+# Free, unauthenticated scanning never touches these — the imports below are
+# deferred so the CLI keeps starting fast and offline.
+
+
+def _resolve_api_url(flag_value: str | None) -> str:
+    """API URL resolution order: --api-url > $SLOPGUARD_API_URL > default."""
+    import os
+
+    from slopguard.saas.client import DEFAULT_API_URL
+
+    return flag_value or os.environ.get("SLOPGUARD_API_URL") or DEFAULT_API_URL
+
+
+@app.command("login")
+def login_cmd(
+    token: Annotated[
+        str | None,
+        typer.Option(
+            "--token",
+            help="API token. If omitted, you'll be prompted (paste hidden).",
+        ),
+    ] = None,
+    api_url: Annotated[
+        str | None,
+        typer.Option(
+            "--api-url",
+            help="SlopGuard API base URL. Defaults to $SLOPGUARD_API_URL or production.",
+        ),
+    ] = None,
+) -> None:
+    """Authenticate the CLI with a SlopGuard API token.
+
+    Mint a token in the dashboard at *<api>/app/<org>/tokens* and paste it
+    here. The token is stored at ``~/.config/slopguard/credentials.toml``
+    with mode 0600.
+    """
+    from slopguard.saas import Credentials, save_credentials
+    from slopguard.saas.client import ApiError, get_me
+
+    api = _resolve_api_url(api_url)
+    plaintext = token or typer.prompt("API token (input hidden)", hide_input=True)
+    if not plaintext.startswith(("sg_live_", "sg_test_")):
+        raise _error_exit(
+            "token must start with sg_live_ or sg_test_; mint one at "
+            f"{api.rstrip('/')}/app/<org-slug>/tokens"
+        )
+
+    try:
+        me = get_me(api, plaintext)
+    except ApiError as exc:
+        raise _error_exit(
+            f"could not verify token against {api}: {exc.detail} (status {exc.status})"
+        ) from exc
+
+    save_credentials(
+        Credentials(
+            api_url=api,
+            token=plaintext,
+            org_slug=me.active_org.slug,
+            organization_id=me.active_org.id,
+            user_email=me.email,
+        )
+    )
+
+    console = Console()
+    console.print(
+        f"[green]Authenticated.[/green] Org: [bold]{me.active_org.name}[/bold] "
+        f"([cyan]{me.active_org.slug}[/cyan], plan: {me.active_org.plan})"
+    )
+    console.print("Credentials saved to ~/.config/slopguard/credentials.toml (mode 600).")
+
+
+@app.command("whoami")
+def whoami_cmd() -> None:
+    """Print the active org context for the saved credentials."""
+    from slopguard.saas import load_credentials
+    from slopguard.saas.client import ApiError, get_me
+
+    creds = load_credentials()
+    if creds is None:
+        raise _error_exit(
+            "not authenticated. Run `slopguard login` first.",
+        )
+
+    try:
+        me = get_me(creds.api_url, creds.token)
+    except ApiError as exc:
+        if exc.status in (401, 403):
+            raise _error_exit(
+                "saved token rejected. Run `slopguard logout` then `slopguard login` again."
+            ) from exc
+        raise _error_exit(f"API call failed: {exc.detail} (status {exc.status})") from exc
+
+    console = Console()
+    console.print(f"[bold]Email:[/bold] {me.email or '—'}")
+    console.print(
+        f"[bold]Active org:[/bold] {me.active_org.name} ([cyan]{me.active_org.slug}[/cyan])"
+    )
+    console.print(f"[bold]Role:[/bold] {me.active_org.role}")
+    console.print(f"[bold]Plan:[/bold] {me.active_org.plan}")
+    console.print(f"[bold]API:[/bold] {creds.api_url}")
+
+
+@app.command("logout")
+def logout_cmd() -> None:
+    """Forget the saved credentials."""
+    from slopguard.saas import delete_credentials
+
+    removed = delete_credentials()
+    console = Console()
+    if removed:
+        console.print("[green]Logged out.[/green] Credentials file removed.")
+    else:
+        console.print("[yellow]Not logged in.[/yellow] No credentials file to remove.")

{slopguard_cli-0.1.1 → slopguard_cli-0.2.0}/slopguard/data/__init__.py

@@ -5,14 +5,38 @@ from __future__ import annotations
 import json
 from functools import lru_cache
 from importlib.resources import files
+from pathlib import Path
 
 from slopguard.models import Ecosystem, HallucinationDB, HallucinationEntry, PopularPackages
 
+# Override path written by ``slopguard update``. When present, it takes
+# precedence over the bundled seed so users get the freshest list
+# without reinstalling.
+CACHE_OVERRIDE = Path.home() / ".cache" / "slopguard" / "hallucinations_db.json"
+
 
 @lru_cache(maxsize=1)
 def load_hallucination_db() -> HallucinationDB:
-    """Load and validate the embedded hallucination seed database."""
-    raw = files("slopguard.data").joinpath("hallucinations_seed.json").read_text(encoding="utf-8")
+    """Load and validate the hallucination database.
+
+    Prefers the user cache (refreshed by ``slopguard update``) over the
+    embedded seed. Falls back transparently if the cache is missing or
+    malformed.
+    """
+    raw: str
+    if CACHE_OVERRIDE.is_file():
+        try:
+            raw = CACHE_OVERRIDE.read_text(encoding="utf-8")
+        except OSError:
+            raw = (
+                files("slopguard.data")
+                .joinpath("hallucinations_seed.json")
+                .read_text(encoding="utf-8")
+            )
+    else:
+        raw = (
+            files("slopguard.data").joinpath("hallucinations_seed.json").read_text(encoding="utf-8")
+        )
     payload = json.loads(raw)
     # Strip non-schema keys (operator notes, etc.) before validating.
     keep = {"schema_version", "updated", "entries"}

slopguard_cli-0.2.0/slopguard/saas/__init__.py

@@ -0,0 +1,26 @@
+"""SaaS integration: credentials store + HTTP client for the SlopGuard API.
+
+Free, unauthenticated CLI invocations never touch this module. It is only
+imported when the user runs ``slopguard login``, ``slopguard whoami``,
+``slopguard logout``, or ``slopguard scan --upload``.
+"""
+
+from __future__ import annotations
+
+from slopguard.saas.credentials import (
+    DEFAULT_CREDENTIALS_PATH,
+    Credentials,
+    CredentialsError,
+    delete_credentials,
+    load_credentials,
+    save_credentials,
+)
+
+__all__ = [
+    "DEFAULT_CREDENTIALS_PATH",
+    "Credentials",
+    "CredentialsError",
+    "delete_credentials",
+    "load_credentials",
+    "save_credentials",
+]

slopguard_cli-0.2.0/slopguard/saas/client.py

@@ -0,0 +1,114 @@
+"""Tiny HTTP client for the SlopGuard API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+DEFAULT_API_URL = "https://api.slopguard.io"
+
+
+class ApiError(Exception):
+    def __init__(self, status: int, detail: str) -> None:
+        self.status = status
+        self.detail = detail
+        super().__init__(f"API {status}: {detail}")
+
+
+@dataclass(frozen=True)
+class MeOrg:
+    id: str
+    name: str
+    slug: str
+    plan: str
+    role: str
+
+
+@dataclass(frozen=True)
+class MeResponse:
+    user_id: str | None
+    email: str | None
+    principal_kind: str
+    active_org: MeOrg
+
+
+def get_me(api_url: str, token: str, *, timeout: float = 10.0) -> MeResponse:
+    """Synchronous /v1/me call. Used by login/whoami/--upload."""
+    try:
+        response = httpx.get(
+            f"{api_url.rstrip('/')}/v1/me",
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=timeout,
+        )
+    except httpx.RequestError as exc:
+        raise ApiError(0, f"network error: {exc}") from exc
+
+    if response.status_code != 200:
+        detail = _extract_detail(response)
+        raise ApiError(response.status_code, detail)
+    payload = response.json()
+    active = payload["active_organization"]
+    return MeResponse(
+        user_id=payload.get("user_id"),
+        email=payload.get("email"),
+        principal_kind=payload["principal_kind"],
+        active_org=MeOrg(
+            id=active["id"],
+            name=active["name"],
+            slug=active["slug"],
+            plan=active["plan"],
+            role=active["role"],
+        ),
+    )
+
+
+def post_scan(
+    api_url: str, token: str, payload: dict[str, Any], *, timeout: float = 30.0
+) -> dict[str, Any]:
+    """POST /v1/scans. Returns the parsed ScanSummary response."""
+    try:
+        response = httpx.post(
+            f"{api_url.rstrip('/')}/v1/scans",
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Content-Type": "application/json",
+            },
+            json=payload,
+            timeout=timeout,
+        )
+    except httpx.RequestError as exc:
+        raise ApiError(0, f"network error: {exc}") from exc
+    if response.status_code not in (200, 201):
+        raise ApiError(response.status_code, _extract_detail(response))
+    return response.json()  # type: ignore[no-any-return]
+
+
+def list_projects(
+    api_url: str, token: str, organization_id: str, *, timeout: float = 10.0
+) -> list[dict[str, Any]]:
+    try:
+        response = httpx.get(
+            f"{api_url.rstrip('/')}/v1/projects",
+            params={"organization_id": organization_id},
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=timeout,
+        )
+    except httpx.RequestError as exc:
+        raise ApiError(0, f"network error: {exc}") from exc
+    if response.status_code != 200:
+        raise ApiError(response.status_code, _extract_detail(response))
+    return response.json()  # type: ignore[no-any-return]
+
+
+def _extract_detail(response: httpx.Response) -> str:
+    try:
+        body = response.json()
+    except ValueError:
+        body = None
+    if isinstance(body, dict):
+        detail = body.get("detail")
+        if isinstance(detail, str):
+            return detail
+    return response.text[:200] or response.reason_phrase

slopguard_cli-0.2.0/slopguard/saas/credentials.py

@@ -0,0 +1,118 @@
+"""Read/write the CLI credentials file.
+
+Stored at ``~/.config/slopguard/credentials.toml`` with mode 0600 so other
+users on the machine cannot read it (spec §6.6).
+
+Layout::
+
+    [active]
+    api_url = "https://api.slopguard.io"
+    token = "sg_live_..."
+    org_slug = "acme-security"
+    organization_id = "..."
+    user_email = "harry@unknownslab.com"
+
+A future ``slopguard switch`` could let multiple profiles live side-by-
+side; for now only ``[active]`` is read or written.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_CREDENTIALS_PATH = Path.home() / ".config" / "slopguard" / "credentials.toml"
+
+
+class CredentialsError(Exception):
+    """Raised when credentials cannot be read or written."""
+
+
+@dataclass(frozen=True)
+class Credentials:
+    api_url: str
+    token: str
+    org_slug: str | None = None
+    organization_id: str | None = None
+    user_email: str | None = None
+
+
+def load_credentials(path: Path | None = None) -> Credentials | None:
+    """Return the active credentials, or None if the file doesn't exist."""
+    if path is None:
+        path = DEFAULT_CREDENTIALS_PATH
+    if not path.exists():
+        return None
+    try:
+        with path.open("rb") as fh:
+            data = tomllib.load(fh)
+    except tomllib.TOMLDecodeError as exc:
+        raise CredentialsError(f"invalid credentials file {path}: {exc}") from exc
+
+    active = data.get("active")
+    if not isinstance(active, dict):
+        return None
+    token = active.get("token")
+    api_url = active.get("api_url")
+    if not isinstance(token, str) or not isinstance(api_url, str):
+        return None
+    return Credentials(
+        api_url=api_url,
+        token=token,
+        org_slug=active.get("org_slug") if isinstance(active.get("org_slug"), str) else None,
+        organization_id=(
+            active.get("organization_id")
+            if isinstance(active.get("organization_id"), str)
+            else None
+        ),
+        user_email=(
+            active.get("user_email") if isinstance(active.get("user_email"), str) else None
+        ),
+    )
+
+
+def save_credentials(creds: Credentials, path: Path | None = None) -> None:
+    """Write ``creds`` to the file at ``path``. Creates parent dirs and chmod 0600."""
+    if path is None:
+        path = DEFAULT_CREDENTIALS_PATH
+    path.parent.mkdir(parents=True, exist_ok=True)
+    body = _render(creds)
+    # Write to a temp sibling then atomic-rename so a crash mid-write can't
+    # leave a half-written credentials file.
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(body, encoding="utf-8")
+    os.chmod(tmp, 0o600)
+    tmp.replace(path)
+
+
+def delete_credentials(path: Path | None = None) -> bool:
+    """Remove the credentials file. Returns True if a file was deleted."""
+    if path is None:
+        path = DEFAULT_CREDENTIALS_PATH
+    if not path.exists():
+        return False
+    path.unlink()
+    return True
+
+
+def _render(creds: Credentials) -> str:
+    lines = [
+        "# slopguard CLI credentials — do not share. chmod 600.",
+        "",
+        "[active]",
+        f'api_url = "{_escape(creds.api_url)}"',
+        f'token = "{_escape(creds.token)}"',
+    ]
+    if creds.org_slug:
+        lines.append(f'org_slug = "{_escape(creds.org_slug)}"')
+    if creds.organization_id:
+        lines.append(f'organization_id = "{_escape(creds.organization_id)}"')
+    if creds.user_email:
+        lines.append(f'user_email = "{_escape(creds.user_email)}"')
+    return "\n".join(lines) + "\n"
+
+
+def _escape(value: str) -> str:
+    return value.replace("\\", "\\\\").replace('"', '\\"')

slopguard_cli-0.2.0/slopguard/update.py

@@ -0,0 +1,94 @@
+"""``slopguard update`` — refresh the local hallucination DB.
+
+Fetches the curated DB from the SlopGuard GitHub Pages site (no API,
+no account, no auth) and writes a seed-shaped file to
+``~/.cache/slopguard/hallucinations_db.json``. The next ``slopguard
+scan`` prefers this cached file over the bundled seed (see
+``slopguard.data.load_hallucination_db``).
+
+Source of truth:
+  https://hariomunknownslab.github.io/slopguard/db.json
+
+Updated daily by the probe-cron GitHub Action; each entry goes through
+PR review before publication (see probe-data/README.md in the repo).
+
+Override the URL with ``SLOPGUARD_DB_URL`` to fetch from a fork or
+mirror. The legacy ``SLOPGUARD_API_URL`` env var still works for the
+0.1.x SaaS endpoint shape — used as a fallback for backward
+compatibility.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+DEFAULT_DB_URL = "https://hariomunknownslab.github.io/slopguard/db.json"
+CACHE_PATH = Path.home() / ".cache" / "slopguard" / "hallucinations_db.json"
+
+
+def _db_url() -> str:
+    """Where to fetch the published DB.
+
+    Precedence: ``SLOPGUARD_DB_URL`` > legacy
+    ``SLOPGUARD_API_URL/v1/hallucinations`` > default GitHub Pages.
+    """
+    if explicit := os.environ.get("SLOPGUARD_DB_URL"):
+        return explicit
+    if legacy := os.environ.get("SLOPGUARD_API_URL"):
+        return legacy.rstrip("/") + "/v1/hallucinations"
+    return DEFAULT_DB_URL
+
+
+def _convert(wire: dict[str, Any]) -> dict[str, Any]:
+    """Map the API wire payload to the local seed schema."""
+    entries: list[dict[str, Any]] = []
+    for row in wire.get("entries", []):
+        entries.append(
+            {
+                "name": row["package_name"],
+                "ecosystem": row["ecosystem"],
+                "first_seen": row["first_observed_at"][:10],
+                "recurrence_rate": row["recurrence_rate"],
+                "models_observed": [],
+                "notes": (
+                    f"Promoted from SlopGuard probe — {row['total_observations']}x "
+                    f"observations, published {row['published_at'][:10]}"
+                ),
+            }
+        )
+    return {
+        "schema_version": 1,
+        "updated": wire.get("generated_at", datetime.now(tz=UTC).isoformat())[:10],
+        "entries": entries,
+    }
+
+
+def run() -> int:
+    url = _db_url()
+    try:
+        resp = httpx.get(url, timeout=15.0)
+        resp.raise_for_status()
+    except httpx.HTTPError as exc:
+        print(f"slopguard update: failed to reach {url}: {exc}")
+        return 1
+
+    try:
+        payload = _convert(resp.json())
+    except (ValueError, KeyError) as exc:
+        print(f"slopguard update: invalid response payload ({exc})")
+        return 1
+
+    CACHE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    tmp = CACHE_PATH.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    tmp.replace(CACHE_PATH)
+
+    count = len(payload["entries"])
+    print(f"slopguard update: cached {count} entries -> {CACHE_PATH}")
+    return 0

{slopguard_cli-0.1.1 → slopguard_cli-0.2.0}/tests/test_cli.py

@@ -107,7 +107,7 @@ def runner() -> CliRunner:
 def test_version_subcommand(runner: CliRunner) -> None:
     result = runner.invoke(app, ["version"])
     assert result.exit_code == 0
-    assert result.stdout.strip() == "0.1.1"
+    assert result.stdout.strip() == "0.2.0"
 
 
 def test_scan_fixtures_no_network_terminal(runner: CliRunner, fixtures_dir: Path) -> None:
@@ -183,4 +183,4 @@ def test_module_main_runs() -> None:
         check=False,
     )
     assert result.returncode == 0
-    assert result.stdout.strip() == "0.1.1"
+    assert result.stdout.strip() == "0.2.0"

{slopguard_cli-0.1.1 → slopguard_cli-0.2.0}/tests/test_misc.py

@@ -32,10 +32,22 @@ def test_main_entry_invokes_typer(monkeypatch: pytest.MonkeyPatch) -> None:
     assert exc_info.value.code == 0
 
 
-def test_update_stub_runs() -> None:
-    from slopguard.update import run
-
-    assert run() == 0
+@respx.mock
+def test_update_writes_cache_when_api_reachable(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Smoke test: with a mocked API the update path returns 0 and writes a cache."""
+    from slopguard import update
+
+    monkeypatch.setattr(update, "CACHE_PATH", tmp_path / "h.json")
+    monkeypatch.setenv("SLOPGUARD_API_URL", "http://api.test")
+    respx.get("http://api.test/v1/hallucinations").mock(
+        return_value=httpx.Response(
+            200,
+            json={"generated_at": "2026-05-23T22:00:00Z", "count": 0, "entries": []},
+        )
+    )
+    assert update.run() == 0
 
 
 def test_npm_parser_lockfile_v1(tmp_path: Path) -> None: