cassis-cli 1.2.0__tar.gz → 1.4.0__tar.gz

{cassis_cli-1.2.0 → cassis_cli-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cassis-cli
-Version: 1.2.0
+Version: 1.4.0
 Summary: Cassis CLI — run Cassis actions (ontology validation, upload and publish) from your CI pipelines
 License: Apache-2.0
 License-File: LICENSE
@@ -24,7 +24,7 @@ Description-Content-Type: text/markdown
 
 Run Cassis actions from your CI pipelines:
 
-- `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. In a checkout bound to a project (`project.yml`, `--project`, or `CASSIS_PROJECT_ID`), it also cross-checks the tree against the project's source schema: references to tables or columns the warehouse doesn't have print as **warnings** — advisory only (the object may simply not be built or synced yet), never a failed check.
+- `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. It then prints advisory **ontology quality warnings** for a tree that parsed — tables not assigned to any domain, joins/metrics pointing at unknown tables or columns, missing table/column descriptions (the same findings `ontology test` reports, without the agent run). In a checkout bound to a project (`project.yml`, `--project`, or `CASSIS_PROJECT_ID`), it also cross-checks the tree against the project's source schema: references to tables or columns the warehouse doesn't have print as **warnings** too — advisory only (the object may simply not be built or synced yet). Warnings never fail the check.
 - `cassis schema pull` downloads the data source's full source schema (as Cassis last introspected it) into `<base-path>/.schema.json` — a **gitignored** local snapshot (the command maintains the ignore entry) with a `pulled_at` stamp. The warehouse stays authoritative; the snapshot is a cache for offline/bulk work — e.g. a coding agent grepping table and column names during a modeling pass instead of paging through the MCP `get_source_schema` tool. Re-run to refresh.
 - `cassis ontology fmt` rewrites the ontology files in canonical form (think `black`/`gofmt` for the ontology), so hand or agent edits pass the round-trip check.
 - `cassis ontology upload` uploads the ontology files to a Cassis project (full replace) and, by default, publishes them immediately as a new version — so a merge to your main branch can go live in one CI step.
@@ -35,6 +35,10 @@ Run Cassis actions from your CI pipelines:
 - `cassis ontology test` runs individual questions through the text-to-SQL agent using your local ontology files, so you can check that a change actually works (e.g. a new column gets picked) — where `eval run` only checks for regressions on existing eval cases.
 - `cassis eval add-case` adds a gold question/SQL case to the project's eval suite — after fixing an ontology issue, add the question users were failing on so `eval run` guards it from regressing.
 - `cassis eval list-cases` and `cassis eval delete-case` maintain the suite: list the current cases with their ids, and prune one that is stale or wrong (e.g. its gold SQL encodes a definition the ontology has since changed).
+- `cassis schema push` uploads a DDL file to detect source-schema changes on a DDL-only project (same as the webapp's "Update from DDL" button): Cassis diffs the DDL against the ontology and surfaces added, dropped, and changed objects in Ontology > Review > Data source for approval. Waits for completion by default; `--no-wait` returns immediately.
+- `cassis projects list` lists the projects your API key can reach — id (what `--project` and `CASSIS_PROJECT_ID` take), name, published ontology version, and data-source dialect — so a pipeline or agent can discover the project id from the terminal instead of fishing it out of a webapp URL.
+- `cassis status` shows the project's published version (number, label, git commit), whether unpublished changes await publication, the git-sync binding, and how your local git HEAD relates to the published commit (in sync / N commits ahead / diverged). `cassis status --watch` polls until the published commit matches your local HEAD — e.g. right after merging a PR whose CI publishes the ontology — instead of watching the GitHub Actions tab.
+- `cassis verify` runs the full local gate in one verb — `ontology fmt --check`, `ontology check`, `eval run` — stopping at the first failure. One command in a checkout ("is this change safe to merge?"), one job in CI. `--no-eval` skips the eval suite.
 
 ## Install
 
@@ -56,7 +60,7 @@ The ontology tree under `<base-path>` (default `cassis/`) is:
 
 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`.
-3. For `pull`, `upload`, `schema pull`, `eval run`, `ontology test`, and the `eval` case commands (`add-case`, `list-cases`, `delete-case`): the project ID (UUID) is taken from `<base-path>/project.yml` in the checkout (written by `pull` and by publishing) — so once a repo is pulled you don't need to pass it. To override, or before the first pull, set `CASSIS_PROJECT_ID` or pass `--project` (find the UUID in the project's URL). `ontology check` uses the same resolution but treats it as optional: unbound checkouts get the project-less validation (no schema reference warnings).
+3. For `pull`, `upload`, `schema pull`, `eval run`, `ontology test`, and the `eval` case commands (`add-case`, `list-cases`, `delete-case`): the project ID (UUID) is taken from `<base-path>/project.yml` in the checkout (written by `pull` and by publishing) — so once a repo is pulled you don't need to pass it. To override, or before the first pull, set `CASSIS_PROJECT_ID` or pass `--project` (find the UUID with `cassis projects list`, or in the project's URL). `ontology check` uses the same resolution but treats it as optional: unbound checkouts get the project-less validation (no schema reference warnings).
 
 ## Usage
 
@@ -93,6 +97,9 @@ cassis eval run --project ...
 # Run against an existing Cassis ontology branch, or the unpublished ontology:
 cassis eval run --project ... --branch feature-x
 
+# Run only specific cases (repeatable) — e.g. prove a fresh add-case in seconds:
+cassis eval run --project ... --case 019f0000-0000-7000-8000-0000000000ca
+
 # Start the run and return immediately (poll in the webapp):
 cassis eval run --project ... --no-wait
 
@@ -104,12 +111,33 @@ cassis ontology test --project ... -q "How much was refunded last month?" -q "Ne
 cassis eval add-case --project ... -q "How much was refunded last month?" \
   --gold-sql "SELECT SUM(refunded_cents) / 100.0 FROM public.orders WHERE ..."
 
+# Multi-line gold SQL: read it from a file instead (no shell quoting pitfalls):
+cassis eval add-case --project ... -q "How much was refunded last month?" \
+  --gold-sql-file refunds.sql
+
 # List the suite's cases (id + question; --json adds the gold SQL), then prune one:
 cassis eval list-cases --project ...
 cassis eval delete-case 019f0000-0000-7000-8000-0000000000ca --project ...
 
 # Pull the source schema into <base-path>/.schema.json (gitignored local snapshot):
 cassis schema pull
+
+# Push a DDL file to detect source-schema changes (DDL-only projects):
+cassis schema push schema.sql
+
+# Push and return immediately (poll in the webapp):
+cassis schema push schema.sql --no-wait
+
+# List the projects the API key can reach (id, name, published version, dialect):
+cassis projects list
+
+# Published version vs local checkout (add --watch to poll until your merge is published):
+cassis status
+cassis status --watch --timeout 600
+
+# The full local gate in one verb (fmt --check, check, eval run; stops at the first failure):
+cassis verify
+cassis verify --no-eval
 ```
 
 Configuration (flags take precedence over env vars):
@@ -121,7 +149,8 @@ Configuration (flags take precedence over env vars):
 | `--base-path` | `CASSIS_BASE_PATH` | `cassis` — must match the project's git-sync "Path" setting |
 | `--project` (check, pull, upload, schema pull, eval run, eval add-case, eval list-cases, eval delete-case, test) | `CASSIS_PROJECT_ID` | the id in `<base-path>/project.yml` (required before the first pull; `check` alone falls back to the project-less validation when unbound) |
 
-`cassis eval run` also accepts `--label` (run label in the Evals page; defaults
+`cassis eval run` also accepts `--case <id>` (repeatable; run only the named
+cases, ids from `eval list-cases` or `add-case`), `--label` (run label in the Evals page; defaults
 to the branch name from the CI environment or the local git checkout; rejected
 with `--branch`, whose runs are labelled with the branch name), `--wait/--no-wait`, `--poll-interval` (5 s),
 `--timeout` (30 min — the run keeps going server-side if the CLI stops waiting),

{cassis_cli-1.2.0 → cassis_cli-1.4.0}/README.md

@@ -2,7 +2,7 @@
 
 Run Cassis actions from your CI pipelines:
 
-- `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. In a checkout bound to a project (`project.yml`, `--project`, or `CASSIS_PROJECT_ID`), it also cross-checks the tree against the project's source schema: references to tables or columns the warehouse doesn't have print as **warnings** — advisory only (the object may simply not be built or synced yet), never a failed check.
+- `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. It then prints advisory **ontology quality warnings** for a tree that parsed — tables not assigned to any domain, joins/metrics pointing at unknown tables or columns, missing table/column descriptions (the same findings `ontology test` reports, without the agent run). In a checkout bound to a project (`project.yml`, `--project`, or `CASSIS_PROJECT_ID`), it also cross-checks the tree against the project's source schema: references to tables or columns the warehouse doesn't have print as **warnings** too — advisory only (the object may simply not be built or synced yet). Warnings never fail the check.
 - `cassis schema pull` downloads the data source's full source schema (as Cassis last introspected it) into `<base-path>/.schema.json` — a **gitignored** local snapshot (the command maintains the ignore entry) with a `pulled_at` stamp. The warehouse stays authoritative; the snapshot is a cache for offline/bulk work — e.g. a coding agent grepping table and column names during a modeling pass instead of paging through the MCP `get_source_schema` tool. Re-run to refresh.
 - `cassis ontology fmt` rewrites the ontology files in canonical form (think `black`/`gofmt` for the ontology), so hand or agent edits pass the round-trip check.
 - `cassis ontology upload` uploads the ontology files to a Cassis project (full replace) and, by default, publishes them immediately as a new version — so a merge to your main branch can go live in one CI step.
@@ -13,6 +13,10 @@ Run Cassis actions from your CI pipelines:
 - `cassis ontology test` runs individual questions through the text-to-SQL agent using your local ontology files, so you can check that a change actually works (e.g. a new column gets picked) — where `eval run` only checks for regressions on existing eval cases.
 - `cassis eval add-case` adds a gold question/SQL case to the project's eval suite — after fixing an ontology issue, add the question users were failing on so `eval run` guards it from regressing.
 - `cassis eval list-cases` and `cassis eval delete-case` maintain the suite: list the current cases with their ids, and prune one that is stale or wrong (e.g. its gold SQL encodes a definition the ontology has since changed).
+- `cassis schema push` uploads a DDL file to detect source-schema changes on a DDL-only project (same as the webapp's "Update from DDL" button): Cassis diffs the DDL against the ontology and surfaces added, dropped, and changed objects in Ontology > Review > Data source for approval. Waits for completion by default; `--no-wait` returns immediately.
+- `cassis projects list` lists the projects your API key can reach — id (what `--project` and `CASSIS_PROJECT_ID` take), name, published ontology version, and data-source dialect — so a pipeline or agent can discover the project id from the terminal instead of fishing it out of a webapp URL.
+- `cassis status` shows the project's published version (number, label, git commit), whether unpublished changes await publication, the git-sync binding, and how your local git HEAD relates to the published commit (in sync / N commits ahead / diverged). `cassis status --watch` polls until the published commit matches your local HEAD — e.g. right after merging a PR whose CI publishes the ontology — instead of watching the GitHub Actions tab.
+- `cassis verify` runs the full local gate in one verb — `ontology fmt --check`, `ontology check`, `eval run` — stopping at the first failure. One command in a checkout ("is this change safe to merge?"), one job in CI. `--no-eval` skips the eval suite.
 
 ## Install
 
@@ -34,7 +38,7 @@ The ontology tree under `<base-path>` (default `cassis/`) is:
 
 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`.
-3. For `pull`, `upload`, `schema pull`, `eval run`, `ontology test`, and the `eval` case commands (`add-case`, `list-cases`, `delete-case`): the project ID (UUID) is taken from `<base-path>/project.yml` in the checkout (written by `pull` and by publishing) — so once a repo is pulled you don't need to pass it. To override, or before the first pull, set `CASSIS_PROJECT_ID` or pass `--project` (find the UUID in the project's URL). `ontology check` uses the same resolution but treats it as optional: unbound checkouts get the project-less validation (no schema reference warnings).
+3. For `pull`, `upload`, `schema pull`, `eval run`, `ontology test`, and the `eval` case commands (`add-case`, `list-cases`, `delete-case`): the project ID (UUID) is taken from `<base-path>/project.yml` in the checkout (written by `pull` and by publishing) — so once a repo is pulled you don't need to pass it. To override, or before the first pull, set `CASSIS_PROJECT_ID` or pass `--project` (find the UUID with `cassis projects list`, or in the project's URL). `ontology check` uses the same resolution but treats it as optional: unbound checkouts get the project-less validation (no schema reference warnings).
 
 ## Usage
 
@@ -71,6 +75,9 @@ cassis eval run --project ...
 # Run against an existing Cassis ontology branch, or the unpublished ontology:
 cassis eval run --project ... --branch feature-x
 
+# Run only specific cases (repeatable) — e.g. prove a fresh add-case in seconds:
+cassis eval run --project ... --case 019f0000-0000-7000-8000-0000000000ca
+
 # Start the run and return immediately (poll in the webapp):
 cassis eval run --project ... --no-wait
 
@@ -82,12 +89,33 @@ cassis ontology test --project ... -q "How much was refunded last month?" -q "Ne
 cassis eval add-case --project ... -q "How much was refunded last month?" \
   --gold-sql "SELECT SUM(refunded_cents) / 100.0 FROM public.orders WHERE ..."
 
+# Multi-line gold SQL: read it from a file instead (no shell quoting pitfalls):
+cassis eval add-case --project ... -q "How much was refunded last month?" \
+  --gold-sql-file refunds.sql
+
 # List the suite's cases (id + question; --json adds the gold SQL), then prune one:
 cassis eval list-cases --project ...
 cassis eval delete-case 019f0000-0000-7000-8000-0000000000ca --project ...
 
 # Pull the source schema into <base-path>/.schema.json (gitignored local snapshot):
 cassis schema pull
+
+# Push a DDL file to detect source-schema changes (DDL-only projects):
+cassis schema push schema.sql
+
+# Push and return immediately (poll in the webapp):
+cassis schema push schema.sql --no-wait
+
+# List the projects the API key can reach (id, name, published version, dialect):
+cassis projects list
+
+# Published version vs local checkout (add --watch to poll until your merge is published):
+cassis status
+cassis status --watch --timeout 600
+
+# The full local gate in one verb (fmt --check, check, eval run; stops at the first failure):
+cassis verify
+cassis verify --no-eval
 ```
 
 Configuration (flags take precedence over env vars):
@@ -99,7 +127,8 @@ Configuration (flags take precedence over env vars):
 | `--base-path` | `CASSIS_BASE_PATH` | `cassis` — must match the project's git-sync "Path" setting |
 | `--project` (check, pull, upload, schema pull, eval run, eval add-case, eval list-cases, eval delete-case, test) | `CASSIS_PROJECT_ID` | the id in `<base-path>/project.yml` (required before the first pull; `check` alone falls back to the project-less validation when unbound) |
 
-`cassis eval run` also accepts `--label` (run label in the Evals page; defaults
+`cassis eval run` also accepts `--case <id>` (repeatable; run only the named
+cases, ids from `eval list-cases` or `add-case`), `--label` (run label in the Evals page; defaults
 to the branch name from the CI environment or the local git checkout; rejected
 with `--branch`, whose runs are labelled with the branch name), `--wait/--no-wait`, `--poll-interval` (5 s),
 `--timeout` (30 min — the run keeps going server-side if the CLI stops waiting),

{cassis_cli-1.2.0 → cassis_cli-1.4.0}/cassis_cli/__init__.py

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

{cassis_cli-1.2.0 → cassis_cli-1.4.0}/cassis_cli/api.py

@@ -139,9 +139,10 @@ def post_ontology_check(
 ) -> dict[str, Any]:
     """POST the ontology tree to the check endpoint and return the response body.
 
+    Both routes return advisory ``audit`` quality findings in ``warnings``.
     With ``project_id``, calls the project-scoped route, which additionally
-    cross-checks the tree against the project's source schema and returns
-    advisory ``warnings``; without it, the pure tree check.
+    cross-checks the tree against the project's source schema and adds
+    ``references`` warnings; without it, the pure tree check.
     """
     if project_id:
         url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/ontology/check"
@@ -243,6 +244,57 @@ def get_ontology_export(
     return result["files"]
 
 
+def get_projects(
+    *,
+    api_url: str,
+    api_key: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> list[dict[str, Any]]:
+    """GET /api/ci/projects and return the project list."""
+    url = api_url.rstrip("/") + "/api/ci/projects"
+    try:
+        with _client(transport=transport) as client:
+            response = client.get(url, 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]}")
+    result = _parse_json_response(response, url)
+    if not isinstance(result, list) or not all(isinstance(p, dict) and "id" in p and "name" in p for p in result):
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result
+
+
+def get_project_status(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """GET /api/ci/projects/{project_id}/status and return the status record."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/status"
+    try:
+        with _client(transport=transport) as client:
+            response = client.get(url, 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 in (403, 404):
+        raise _project_scope_error(response)
+    if response.status_code >= 400:
+        raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
+    result = _parse_json_response(response, url)
+    if not isinstance(result, dict) or "has_unpublished_changes" not in result:
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result
+
+
 class NoSourceSchemaError(ApiError):
     """The project's data source has no introspected schema to pull."""
 
@@ -284,6 +336,68 @@ def get_schema_export(
     return result
 
 
+class SourceChangeConflictError(ApiError):
+    """A concurrent detection run is already active, or the project has a connected data source."""
+
+
+def post_detect_from_ddl(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    ddl: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """POST /api/ci/projects/{project_id}/source-changes/detect-from-ddl and return the run record."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/source-changes/detect-from-ddl"
+    try:
+        with _client(transport=transport) as client:
+            response = client.post(url, json={"ddl": ddl}, 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 == 409:
+        raise SourceChangeConflictError(str(_detail_or_text(response)))
+    if response.status_code in (403, 404):
+        raise _project_scope_error(response)
+    if response.status_code >= 400:
+        raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
+    result = _parse_json_response(response, url)
+    if not isinstance(result, dict) or "run_id" not in result:
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result
+
+
+def get_source_change_run(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    run_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """GET /api/ci/projects/{project_id}/source-changes/runs/{run_id} and return the run record."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/source-changes/runs/{run_id}"
+    try:
+        with _client(transport=transport) as client:
+            response = client.get(url, 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 in (403, 404):
+        raise _project_scope_error(response)
+    if response.status_code >= 400:
+        raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
+    result = _parse_json_response(response, url)
+    if not isinstance(result, dict) or "run_id" not in result:
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result
+
+
 def post_eval_run_start(
     *,
     api_url: str,
@@ -292,6 +406,7 @@ def post_eval_run_start(
     files: Optional[dict[str, str]] = None,
     branch: Optional[str] = None,
     label: Optional[str] = None,
+    case_ids: Optional[list[str]] = None,
     transport: Optional[httpx.BaseTransport] = None,
 ) -> dict[str, Any]:
     """POST to /api/ci/projects/{project_id}/eval/runs and return the run record."""
@@ -303,6 +418,8 @@ def post_eval_run_start(
         body["branch"] = branch
     if label is not None:
         body["label"] = label
+    if case_ids is not None:
+        body["test_case_ids"] = case_ids
     try:
         with _client(transport=transport) as client:
             response = client.post(url, json=body, headers={"Authorization": f"Bearer {api_key}"})

{cassis_cli-1.2.0 → cassis_cli-1.4.0}/cassis_cli/eval.py

@@ -7,7 +7,7 @@ import os
 import subprocess
 import time
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any, List, Optional
 from uuid import UUID
 
 import typer
@@ -164,11 +164,16 @@ def add_case(
         "--question",
         help="The natural-language question the case guards.",
     ),
-    gold_sql: str = typer.Option(
-        ...,
+    gold_sql: Optional[str] = typer.Option(
+        None,
         "--gold-sql",
         help="The correct SQL for the question; executed at run time to produce the expected output.",
     ),
+    gold_sql_file: Optional[Path] = typer.Option(
+        None,
+        "--gold-sql-file",
+        help="Read the gold SQL from this file instead of --gold-sql (no shell quoting of multi-line SQL).",
+    ),
     api_key: Optional[str] = typer.Option(
         None,
         "--api-key",
@@ -195,13 +200,31 @@ def add_case(
     failing on becomes a gold case, so `cassis eval run` guards it from
     regressing. On an executable data source the gold SQL is run before the
     case is stored, so a case that cannot execute never enters the suite.
+    The SQL comes from --gold-sql (inline) or --gold-sql-file (a file path;
+    prefer it for multi-line SQL, which shell quoting mangles inline).
     Exits 0 on creation, 1 on a duplicate question or gold SQL that does not
     run, 2 on usage errors, 3 on transport/API errors.
     """
     api_key = require_api_key(api_key)
     project_id = resolve_project_id(project_id, path / Path(base_path))
+    if (gold_sql is None) == (gold_sql_file is None):
+        typer.secho("Pass exactly one of --gold-sql or --gold-sql-file.", fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_USAGE)
+    if gold_sql_file is not None:
+        try:
+            gold_sql = gold_sql_file.read_text(encoding="utf-8")
+        # Two separate handlers: the repo-wide black targets py314 and would
+        # strip the parens off a tuple form, which is a SyntaxError on the
+        # CLI's supported Python (>=3.10).
+        except OSError as exc:
+            typer.secho(f"Cannot read {gold_sql_file}: {exc}", fg=typer.colors.RED, err=True)
+            raise typer.Exit(EXIT_USAGE) from exc
+        except UnicodeDecodeError as exc:
+            typer.secho(f"Cannot read {gold_sql_file}: {exc}", fg=typer.colors.RED, err=True)
+            raise typer.Exit(EXIT_USAGE) from exc
+    assert gold_sql is not None
     if not question.strip() or not gold_sql.strip():
-        typer.secho("--question and --gold-sql must not be empty.", fg=typer.colors.RED, err=True)
+        typer.secho("--question and the gold SQL must not be empty.", fg=typer.colors.RED, err=True)
         raise typer.Exit(EXIT_USAGE)
 
     try:
@@ -388,6 +411,11 @@ def run(
         "--branch",
         help="Run against an existing Cassis ontology branch by name instead of local files.",
     ),
+    case: Optional[List[str]] = typer.Option(
+        None,
+        "--case",
+        help="Run only this eval case id (repeatable; ids from `eval list-cases` or `add-case`).",
+    ),
     label: Optional[str] = typer.Option(
         None,
         "--label",
@@ -412,11 +440,19 @@ def run(
 
     Uploads the local ontology file tree and scores it in-memory — nothing is pushed or
     persisted in Cassis besides the eval run itself. With --branch, runs against
-    an existing Cassis branch instead (no files are sent). Exits 0 when the run
-    completes with every case passed, 1 on any failed case / failed run /
-    invalid tree, 2 on usage errors, 3 on transport errors or --timeout.
+    an existing Cassis branch instead (no files are sent). With --case, only the
+    named case(s) run — e.g. proving one fresh `add-case` in seconds instead of
+    rerunning the whole suite. Exits 0 when the run completes with every case
+    passed, 1 on any failed case / failed run / invalid tree, 2 on usage
+    errors, 3 on transport errors or --timeout.
     """
     api_key = require_api_key(api_key)
+    for case_id in case or []:
+        try:
+            UUID(case_id)
+        except ValueError:
+            typer.secho(f"--case must be an eval case ID (UUID), got {case_id!r}.", fg=typer.colors.RED, err=True)
+            raise typer.Exit(EXIT_USAGE)
     if branch is not None and label is not None:
         typer.secho(
             "--label cannot be used with --branch: branch runs are labelled with the branch name.",
@@ -440,6 +476,7 @@ def run(
             files=files,
             branch=branch,
             label=label,
+            case_ids=case,
         )
     except EvalStartValidationError as exc:
         _print_validation_failure(exc.detail, base_path)

{cassis_cli-1.2.0 → cassis_cli-1.4.0}/cassis_cli/main.py

@@ -6,7 +6,10 @@ import typer
 from cassis_cli import __version__
 from cassis_cli.eval import app as eval_app
 from cassis_cli.ontology import app as ontology_app
+from cassis_cli.projects import app as projects_app
 from cassis_cli.schema import app as schema_app
+from cassis_cli.status import status
+from cassis_cli.verify import verify
 
 app = typer.Typer(
     no_args_is_help=True,
@@ -15,6 +18,9 @@ app = typer.Typer(
 app.add_typer(ontology_app, name="ontology")
 app.add_typer(eval_app, name="eval")
 app.add_typer(schema_app, name="schema")
+app.add_typer(projects_app, name="projects")
+app.command()(status)
+app.command()(verify)
 
 
 @app.command()

{cassis_cli-1.2.0 → cassis_cli-1.4.0}/cassis_cli/ontology.py

@@ -85,11 +85,14 @@ def check(
     """Validate the ontology files in a repository checkout.
 
     Runs the same checks as the Cassis GitHub PR check (YAML parsing,
-    round-trip, import validation). When the checkout is bound to a project
+    round-trip, import validation), then prints advisory quality warnings
+    (unassigned tables, broken joins/metrics, missing descriptions) for a
+    tree that parsed. When the checkout is bound to a project
     (``project.yml``, ``--project``, or ``CASSIS_PROJECT_ID``), the tree is
     additionally cross-checked against the project's source schema; unmatched
-    references print as warnings and never fail the check. Exits 0 when valid,
-    1 when validation fails, 2 on usage errors, 3 on transport/API errors.
+    references print as warnings too. Warnings never fail the check or change
+    the exit code. Exits 0 when valid, 1 when validation fails, 2 on usage
+    errors, 3 on transport/API errors.
     """
     api_key = _require_api_key(api_key)
     files, base_path = _collect_tree(path, base_path)
@@ -114,13 +117,17 @@ def check(
         raise typer.Exit(EXIT_TRANSPORT) from exc
 
     warnings = result.get("warnings") or []
+    ref_warnings = [w for w in warnings if w.get("stage") == "references"]
+    # Everything else is the quality audit; bucketing by "not references" keeps
+    # a warning stage this CLI predates visible instead of silently dropped.
+    audit_warnings = [w for w in warnings if w.get("stage") != "references"]
     if json_output:
         typer.echo(json.dumps(result, indent=2))
     elif result["passed"]:
         typer.secho(f"✓ {result['summary']}", fg=typer.colors.GREEN)
         # Disambiguate silence: "no warnings" must never read as "references
         # verified" when the stage didn't run.
-        if project_id and result.get("references_checked") and not warnings:
+        if project_id and result.get("references_checked") and not ref_warnings:
             typer.secho("✓ Schema references resolve against the source schema.", fg=typer.colors.GREEN)
         elif project_id and not result.get("references_checked"):
             typer.secho(
@@ -135,14 +142,23 @@ def check(
             location = f"{base_path}/{finding.get('path')}: " if finding.get("path") else ""
             typer.echo(f"  {location}{finding.get('message', '')} ({finding.get('stage', '?')})")
 
-    if warnings and not json_output:
+    if ref_warnings and not json_output:
         typer.secho(
-            f"{len(warnings)} schema reference warning(s) — advisory, expected if the objects "
+            f"{len(ref_warnings)} schema reference warning(s) — advisory, expected if the objects "
             "haven't been built or synced yet:",
             fg=typer.colors.YELLOW,
             bold=True,
         )
-        for warning in warnings:
+        for warning in ref_warnings:
+            typer.secho(f"  {warning.get('message', '')}", fg=typer.colors.YELLOW)
+    if audit_warnings and not json_output:
+        # Same wording as `ontology test` so the two commands read alike.
+        typer.secho(
+            f"{len(audit_warnings)} ontology quality warning(s) — advisory, never fail the check:",
+            fg=typer.colors.YELLOW,
+            bold=True,
+        )
+        for warning in audit_warnings:
             typer.secho(f"  {warning.get('message', '')}", fg=typer.colors.YELLOW)
 
     raise typer.Exit(EXIT_OK if result["passed"] else EXIT_VALIDATION_FAILED)

cassis_cli-1.4.0/cassis_cli/projects.py

@@ -0,0 +1,69 @@
+"""`cassis projects` — discover the projects an API key can reach.
+
+Every other CI route is project-scoped, so the very first thing a pipeline or
+checkout agent needs is a project id. `projects list` answers that from the
+terminal instead of fishing the UUID out of a webapp URL.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+import typer
+from cassis_cli.api import DEFAULT_API_URL, ApiError, AuthError, get_projects
+from cassis_cli.common import EXIT_OK, EXIT_TRANSPORT, require_api_key
+
+app = typer.Typer(help="Discover the projects this API key can reach.")
+
+
+@app.command(name="list")
+def list_projects(
+    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.",
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Print the raw JSON response."),
+) -> None:
+    """List the projects available to the API key.
+
+    Prints each project's id (what --project and CASSIS_PROJECT_ID take), name,
+    published ontology version, and data-source dialect. A schema-only source
+    (no connection) is marked "not executable": SQL is generated but never run.
+    Exits 0 on success, 2 on usage errors, 3 on transport/API errors.
+    """
+    api_key = require_api_key(api_key)
+
+    try:
+        projects = get_projects(api_url=api_url, api_key=api_key)
+    except (AuthError, 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(projects, indent=2))
+        raise typer.Exit(EXIT_OK)
+
+    if not projects:
+        typer.echo("No projects visible to this API key.")
+        raise typer.Exit(EXIT_OK)
+
+    for project in projects:
+        version = project.get("published_version")
+        version_text = f"v{version}" if version is not None else "unpublished"
+        source = project.get("data_source")
+        if source:
+            dialect = source.get("sql_dialect") or "?"
+            source_text = dialect if source.get("is_executable") else f"{dialect}, not executable"
+        else:
+            source_text = "no data source"
+        typer.echo(f"{project['id']}  {project['name']}  ({version_text}; {source_text})")
+    raise typer.Exit(EXIT_OK)