cassis-cli 0.1.0__py3-none-any.whl

cassis_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Cassis CLI — run Cassis actions from your CI pipelines."""
+
+__version__ = "0.1.0"

cassis_cli/api.py

@@ -0,0 +1,56 @@
+"""Thin HTTP client for the Cassis API."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import httpx
+
+DEFAULT_API_URL = "https://app.getcassis.com"
+TIMEOUT_SECONDS = 60.0
+
+
+class ApiError(Exception):
+    """Transport or HTTP-level failure talking to the Cassis API."""
+
+
+class AuthError(ApiError):
+    """The API rejected the API key (401)."""
+
+
+def post_ontology_check(
+    *,
+    api_url: str,
+    api_key: str,
+    files: dict[str, str],
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """POST the ontology tree to /api/ci/ontology-check and return the response body."""
+    url = api_url.rstrip("/") + "/api/ci/ontology-check"
+    try:
+        with httpx.Client(timeout=TIMEOUT_SECONDS, transport=transport) as client:
+            response = client.post(
+                url,
+                json={"files": files},
+                headers={"Authorization": f"Bearer {api_key}"},
+            )
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
+
+    if response.status_code == 401:
+        raise AuthError("The Cassis API rejected the API key (invalid or expired).")
+    if response.status_code >= 400:
+        raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
+    try:
+        result = response.json()
+    except ValueError as exc:  # json.JSONDecodeError — e.g. a proxy or portal answering HTML with a 200
+        raise ApiError(
+            f"The Cassis API at {url} returned a non-JSON response — check the API URL and any proxy in between."
+        ) from exc
+    if (
+        not isinstance(result, dict)
+        or not all(key in result for key in ("passed", "title", "summary"))
+        or not isinstance(result.get("findings"), list)
+    ):
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result

cassis_cli/main.py

@@ -0,0 +1,23 @@
+"""Entry point for the `cassis` CLI."""
+
+from __future__ import annotations
+
+import typer
+from cassis_cli import __version__
+from cassis_cli.ontology import app as ontology_app
+
+app = typer.Typer(
+    no_args_is_help=True,
+    help="Cassis CLI — run Cassis actions from your CI pipelines.",
+)
+app.add_typer(ontology_app, name="ontology")
+
+
+@app.command()
+def version() -> None:
+    """Print the CLI version."""
+    typer.echo(__version__)
+
+
+if __name__ == "__main__":
+    app()

cassis_cli/ontology.py

@@ -0,0 +1,141 @@
+"""`cassis ontology` subcommands."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+import typer
+from cassis_cli.api import DEFAULT_API_URL, ApiError, AuthError, post_ontology_check
+
+app = typer.Typer(no_args_is_help=True, help="Ontology commands.")
+
+# Repository directory the ontology tree is exported under. Must match the
+# project's git-sync "Path" setting in Cassis (default "cassis").
+DEFAULT_BASE_PATH = "cassis"
+
+# Exit codes (documented in the README; stable contract for CI scripts).
+EXIT_OK = 0
+EXIT_VALIDATION_FAILED = 1
+EXIT_USAGE = 2
+EXIT_TRANSPORT = 3
+
+# Request ceilings of POST /api/ci/ontology-check, mirrored so oversized trees
+# fail fast with a clear message before any upload. Source of truth:
+# backend/app/schemas/ci.py (the server's 422 remains the backstop).
+MAX_FILES = 2000
+MAX_TOTAL_BYTES = 5 * 1024 * 1024
+
+
+def _collect_files(ontology_dir: Path) -> dict[str, str]:
+    """Read every YAML file under the ontology dir, keyed by posix relpath.
+
+    Exits 2 (usage) on an unreadable or non-UTF-8 file — a local checkout
+    problem, reported before anything is sent to the API.
+    """
+    files: dict[str, str] = {}
+    for pattern in ("**/*.yml", "**/*.yaml"):
+        for file in sorted(ontology_dir.glob(pattern)):
+            if file.is_file():
+                try:
+                    files[file.relative_to(ontology_dir).as_posix()] = file.read_text(encoding="utf-8")
+                except (UnicodeDecodeError, OSError) as exc:
+                    typer.secho(f"Cannot read {file}: {exc}", fg=typer.colors.RED, err=True)
+                    raise typer.Exit(EXIT_USAGE) from exc
+    return files
+
+
+@app.command()
+def check(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Repository checkout root (the directory containing the ontology export path).",
+    ),
+    api_key: Optional[str] = typer.Option(
+        None,
+        "--api-key",
+        envvar="CASSIS_API_KEY",
+        help="Cassis API key (sk-k6-...). Create one in Organization settings -> API keys.",
+    ),
+    api_url: str = typer.Option(
+        DEFAULT_API_URL,
+        "--api-url",
+        envvar="CASSIS_API_URL",
+        help="Cassis API base URL.",
+    ),
+    base_path: str = typer.Option(
+        DEFAULT_BASE_PATH,
+        "--base-path",
+        envvar="CASSIS_BASE_PATH",
+        help="Repository directory the ontology is exported under (the project's git-sync Path setting).",
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Print the raw JSON response."),
+) -> None:
+    """Validate the ontology files in a repository checkout.
+
+    Runs the same checks as the Cassis GitHub PR check (YAML parsing,
+    round-trip, import validation). Exits 0 when valid, 1 when validation
+    fails, 2 on usage errors, 3 on transport/API errors.
+    """
+    if not api_key:
+        typer.secho(
+            "No API key. Set CASSIS_API_KEY or pass --api-key "
+            "(create one in Cassis under Organization settings -> API keys).",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(EXIT_USAGE)
+
+    base_path = base_path.strip().strip("/")
+    if not base_path:
+        typer.secho("--base-path must not be empty.", fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_USAGE)
+
+    ontology_dir = path / Path(base_path)
+    if not ontology_dir.is_dir():
+        typer.secho(
+            f"No {base_path}/ directory found under {path}. "
+            "If the project exports to a custom path, pass it with --base-path (or CASSIS_BASE_PATH).",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(EXIT_USAGE)
+
+    files = _collect_files(ontology_dir)
+    if not files:
+        typer.secho(f"No YAML files found under {ontology_dir}.", fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_USAGE)
+
+    total_bytes = sum(len(content.encode()) for content in files.values())
+    if len(files) > MAX_FILES or total_bytes > MAX_TOTAL_BYTES:
+        typer.secho(
+            f"Ontology tree too large for the CI check: {len(files)} files / {total_bytes / (1024 * 1024):.1f} MB "
+            f"(limits: {MAX_FILES} files / {MAX_TOTAL_BYTES // (1024 * 1024)} MB). "
+            "Check that --base-path points at the ontology directory, not a larger tree.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(EXIT_USAGE)
+
+    try:
+        result = post_ontology_check(api_url=api_url, api_key=api_key, files=files)
+    except AuthError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_TRANSPORT) from exc
+    except ApiError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_TRANSPORT) from exc
+
+    if json_output:
+        typer.echo(json.dumps(result, indent=2))
+    elif result["passed"]:
+        typer.secho(f"✓ {result['summary']}", fg=typer.colors.GREEN)
+    else:
+        typer.secho(result["title"], fg=typer.colors.RED, bold=True)
+        typer.echo(result["summary"])
+        for finding in result["findings"]:
+            location = f"{base_path}/{finding.get('path')}: " if finding.get("path") else ""
+            typer.echo(f"  {location}{finding.get('message', '')} ({finding.get('stage', '?')})")
+
+    raise typer.Exit(EXIT_OK if result["passed"] else EXIT_VALIDATION_FAILED)

cassis_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: cassis-cli
+Version: 0.1.0
+Summary: Cassis CLI — run Cassis actions (ontology validation) from your CI pipelines
+License: Proprietary
+Keywords: cassis,ontology,ci,text-to-sql
+Author: Cassis
+Author-email: tech.admin@getcassis.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: httpx (>=0.24,<1.0)
+Requires-Dist: typer (>=0.12,<1.0)
+Description-Content-Type: text/markdown
+
+# Cassis CLI
+
+Run Cassis actions from your CI pipelines. The first command, `cassis ontology check`, validates the ontology files in your repository with the exact same checks as the Cassis GitHub PR check (YAML parsing, round-trip, import validation) — so you can gate merges in any CI system, not just GitHub.
+
+## Install
+
+```bash
+pip install cassis-cli
+```
+
+## Setup
+
+1. Create an API key in Cassis under **Organization settings → API keys** (keys start with `sk-k6-`).
+2. Store it as a CI secret and expose it as `CASSIS_API_KEY`.
+
+## Usage
+
+```bash
+# From the root of a repository synced with Cassis (contains the ontology export directory, cassis/ by default):
+cassis ontology check
+
+# Or point at the checkout explicitly:
+cassis ontology check /path/to/checkout
+
+# Machine-readable output:
+cassis ontology check --json
+```
+
+Configuration (flags take precedence over env vars):
+
+| Flag        | Env var          | Default                     |
+| ----------- | ---------------- | --------------------------- |
+| `--api-key` | `CASSIS_API_KEY` | — (required)                |
+| `--api-url` | `CASSIS_API_URL` | `https://app.getcassis.com` |
+| `--base-path` | `CASSIS_BASE_PATH` | `cassis` — must match the project's git-sync "Path" setting |
+
+### Exit codes
+
+| Code | Meaning                                                                        |
+| ---- | ------------------------------------------------------------------------------ |
+| 0    | Ontology is valid                                                              |
+| 1    | Validation failed (findings printed)                                           |
+| 2    | Usage error (missing API key, no ontology directory, unreadable file, tree over the size limits) |
+| 3    | Transport/API error (unreachable API, invalid key, unexpected response)        |
+
+The check accepts up to 2000 YAML files / 5 MB total — far above real
+ontologies (a few hundred small files). Beyond that the CLI fails fast with
+exit 2 before uploading anything; double-check `--base-path` if you hit it.
+
+### GitHub Actions example
+
+```yaml
+jobs:
+  ontology-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install cassis-cli
+      - run: cassis ontology check
+        env:
+          CASSIS_API_KEY: ${{ secrets.CASSIS_API_KEY }}
+```
+
+### GitLab CI example
+
+```yaml
+ontology-check:
+  image: python:3.12-slim
+  script:
+    - pip install cassis-cli
+    - cassis ontology check
+  variables:
+    CASSIS_API_KEY: $CASSIS_API_KEY
+```
+

cassis_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+cassis_cli/__init__.py,sha256=hJhksUVtIGULBAvWH4nYAhF_jhzyF6kdju2sHjlRvqI,87
+cassis_cli/api.py,sha256=9Owpt3gRYUOgxcEP1hp50LF1zQ0ZITLpv3919hbsupk,1921
+cassis_cli/main.py,sha256=w256-qwyygVNiHLhVB4CHEiTrEujG03-BXLv7KMzNoY,480
+cassis_cli/ontology.py,sha256=gVw7SqKz-TTCKjC29doy2bONmbU8ts8YQ_KcK_6HX-M,5408
+cassis_cli-0.1.0.dist-info/METADATA,sha256=nZIM7uVi9VIAiPbgHMuZwHwBkHHkkze_laCt1ts5CEg,3361
+cassis_cli-0.1.0.dist-info/WHEEL,sha256=kJCRJT_g0adfAJzTx2GUMmS80rTJIVHRCfG0DQgLq3o,88
+cassis_cli-0.1.0.dist-info/entry_points.txt,sha256=G0RioVCAagpy_yI1oDl3ty_v0I7kxC5Tlr-ofIKqgOU,46
+cassis_cli-0.1.0.dist-info/RECORD,,

cassis_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.3.1
+Root-Is-Purelib: true
+Tag: py3-none-any

cassis_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+cassis=cassis_cli.main:app
+