cassis-cli 1.1.1__tar.gz → 1.3.0__tar.gz

{cassis_cli-1.1.1 → cassis_cli-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cassis-cli
-Version: 1.1.1
+Version: 1.3.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,8 @@ 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.
+- `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 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.
 - `cassis ontology pull` downloads the project's unpublished ontology into your repository checkout (full sync — stale local ontology files are pruned), so you can start editing from the current state, or bootstrap a repo that isn't git-synced (e.g. Bitbucket).
@@ -33,6 +34,11 @@ Run Cassis actions from your CI pipelines:
 - `cassis eval run` runs the project's eval suite against your local ontology files (scored in-memory — nothing is pushed to Cassis) and prints per-question results, so you can test the changes on your git branch before merging.
 - `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
 
@@ -54,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`, `eval run`, `ontology test`, and `eval add-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).
+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
 
@@ -91,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
 
@@ -101,6 +110,34 @@ cassis ontology test --project ... -q "How much was refunded last month?" -q "Ne
 # Add a gold case to the eval suite (rejected if the exact question already exists):
 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):
@@ -110,9 +147,10 @@ Configuration (flags take precedence over env vars):
 | `--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 |
-| `--project` (pull, upload, eval run, eval add-case, test) | `CASSIS_PROJECT_ID` | — (required)      |
+| `--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),
@@ -139,7 +177,7 @@ cassis ontology fmt --check
 | Code | Meaning                                                                        |
 | ---- | ------------------------------------------------------------------------------ |
 | 0    | Ontology is valid (check) / pulled (pull) / uploaded (upload) / eval run completed all-passed (eval run) / every probe completed (test — whatever its outcome; probes are informational, don't gate CI on them) |
-| 1    | Validation failed (check: findings printed; upload: nothing imported; eval run: invalid tree, failed cases, or failed/cancelled run; test: invalid tree or a probe failed) |
+| 1    | Validation failed (check: findings printed; upload: nothing imported; eval run: invalid tree, failed cases, or failed/cancelled run; test: invalid tree or a probe failed; add-case: duplicate question or gold SQL that does not run; delete-case: no such case in the project) |
 | 2    | Usage error (missing API key or project, no ontology directory, unreadable file, tree over the size limits) |
 | 3    | Transport/API error (unreachable API, invalid key, inaccessible project, unexpected response), another run already active, out of credits, or `--timeout` reached |
 

{cassis_cli-1.1.1 → cassis_cli-1.3.0}/README.md

@@ -2,7 +2,8 @@
 
 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.
+- `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 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.
 - `cassis ontology pull` downloads the project's unpublished ontology into your repository checkout (full sync — stale local ontology files are pruned), so you can start editing from the current state, or bootstrap a repo that isn't git-synced (e.g. Bitbucket).
@@ -11,6 +12,11 @@ Run Cassis actions from your CI pipelines:
 - `cassis eval run` runs the project's eval suite against your local ontology files (scored in-memory — nothing is pushed to Cassis) and prints per-question results, so you can test the changes on your git branch before merging.
 - `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
 
@@ -32,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`, `eval run`, `ontology test`, and `eval add-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).
+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
 
@@ -69,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
 
@@ -79,6 +88,34 @@ cassis ontology test --project ... -q "How much was refunded last month?" -q "Ne
 # Add a gold case to the eval suite (rejected if the exact question already exists):
 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):
@@ -88,9 +125,10 @@ Configuration (flags take precedence over env vars):
 | `--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 |
-| `--project` (pull, upload, eval run, eval add-case, test) | `CASSIS_PROJECT_ID` | — (required)      |
+| `--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),
@@ -117,7 +155,7 @@ cassis ontology fmt --check
 | Code | Meaning                                                                        |
 | ---- | ------------------------------------------------------------------------------ |
 | 0    | Ontology is valid (check) / pulled (pull) / uploaded (upload) / eval run completed all-passed (eval run) / every probe completed (test — whatever its outcome; probes are informational, don't gate CI on them) |
-| 1    | Validation failed (check: findings printed; upload: nothing imported; eval run: invalid tree, failed cases, or failed/cancelled run; test: invalid tree or a probe failed) |
+| 1    | Validation failed (check: findings printed; upload: nothing imported; eval run: invalid tree, failed cases, or failed/cancelled run; test: invalid tree or a probe failed; add-case: duplicate question or gold SQL that does not run; delete-case: no such case in the project) |
 | 2    | Usage error (missing API key or project, no ontology directory, unreadable file, tree over the size limits) |
 | 3    | Transport/API error (unreachable API, invalid key, inaccessible project, unexpected response), another run already active, out of credits, or `--timeout` reached |
 

{cassis_cli-1.1.1 → cassis_cli-1.3.0}/cassis_cli/__init__.py

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

{cassis_cli-1.1.1 → cassis_cli-1.3.0}/cassis_cli/api.py

@@ -134,10 +134,19 @@ def post_ontology_check(
     api_url: str,
     api_key: str,
     files: dict[str, str],
+    project_id: Optional[str] = None,
     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"
+    """POST the ontology tree to the check endpoint and return the response body.
+
+    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.
+    """
+    if project_id:
+        url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/ontology/check"
+    else:
+        url = api_url.rstrip("/") + "/api/ci/ontology-check"
     try:
         with _client(transport=transport) as client:
             response = client.post(
@@ -150,6 +159,8 @@ def post_ontology_check(
 
     if response.status_code == 401:
         raise AuthError("The Cassis API rejected the API key (invalid or expired).")
+    if project_id and 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)
@@ -232,6 +243,160 @@ 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."""
+
+
+def get_schema_export(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """GET /api/ci/projects/{project_id}/schema and return the response body."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/schema"
+    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).")
+    # "No source schema" is the marker the server's export endpoint puts in its
+    # 404 detail (backend endpoints/ci.py::export_source_schema — reworded only
+    # with a paired CLI release). Without this routing, a schema-less project
+    # would surface as the misleading "check --project / key access" hint below.
+    if response.status_code == 404 and "No source schema" in response.text:
+        raise NoSourceSchemaError(str(_detail_or_text(response)))
+    if response.status_code in (400, 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 not isinstance(result.get("tables"), list)
+        or not isinstance(result.get("schema_version"), dict)
+    ):
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    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,
@@ -240,6 +405,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."""
@@ -251,6 +417,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}"})
@@ -321,6 +489,54 @@ def post_eval_case_create(
     return result
 
 
+class EvalCaseNotFoundError(ApiError):
+    """The project has no current eval case with this id."""
+
+
+def get_eval_cases(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> list[dict[str, Any]]:
+    """GET /api/ci/projects/{project_id}/eval/cases and return the case list."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/eval/cases"
+    result = _get_eval_json(url, api_key, transport)
+    if not isinstance(result, list):
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result
+
+
+def delete_eval_case(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    case_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> None:
+    """DELETE /api/ci/projects/{project_id}/eval/cases/{case_id}."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/eval/cases/{case_id}"
+    try:
+        with _client(transport=transport) as client:
+            response = client.delete(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).")
+    # Exact-match wire contract with the DELETE endpoint's 404 detail (see
+    # `delete_eval_case` in backend/app/endpoints/ci.py): it distinguishes a
+    # missing case (exit 1) from a project-scope 404 (exit 3).
+    if response.status_code == 404 and _detail_or_text(response) == "Eval case not found":
+        raise EvalCaseNotFoundError(f"No current eval case {case_id} in this project (already deleted, or wrong id?).")
+    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]}")
+
+
 def _get_eval_json(url: str, api_key: str, transport: Optional[httpx.BaseTransport]) -> Any:
     """GET an eval-run URL with the shared error mapping."""
     try:

{cassis_cli-1.1.1 → cassis_cli-1.3.0}/cassis_cli/common.py

@@ -93,20 +93,27 @@ def read_project_id_from_dir(ontology_dir: Path) -> Optional[str]:
     return None
 
 
-def resolve_project_id(project_id: Optional[str], ontology_dir: Path) -> str:
+def resolve_project_id(
+    project_id: Optional[str], ontology_dir: Path, *, optional: bool = False, quiet: bool = False
+) -> Optional[str]:
     """Resolve the target project id, defaulting to the checkout's ``project.yml``.
 
     Precedence: an explicit ``--project`` / ``CASSIS_PROJECT_ID`` wins; otherwise
     the ``project_id`` recorded in ``<base-path>/project.yml`` (written by
     ``pull`` / publish) is used, and where it came from is noted on stderr so a
-    stale value in a copied repo is visible. Exits 2 (usage) when neither is
-    available or the value isn't a UUID.
+    stale value in a copied repo is visible (``quiet`` suppresses the note for
+    machine-readable output). Exits 2 (usage) when the value isn't a UUID, or —
+    unless ``optional`` — when no value is available at all; with ``optional``,
+    an unbound checkout returns None (``check`` falls back to the project-less
+    validation).
     """
     from_file = False
     if not project_id:
         project_id = read_project_id_from_dir(ontology_dir)
         from_file = project_id is not None
     if not project_id:
+        if optional:
+            return None
         typer.secho(
             f"No project. Pass --project (or set CASSIS_PROJECT_ID), or run in a checkout whose "
             f"{ontology_dir.name}/project.yml records it (written by `cassis ontology pull` or a publish).",
@@ -119,7 +126,7 @@ def resolve_project_id(project_id: Optional[str], ontology_dir: Path) -> str:
     except ValueError:
         typer.secho(f"--project must be a project ID (UUID), got {project_id!r}.", fg=typer.colors.RED, err=True)
         raise typer.Exit(EXIT_USAGE)
-    if from_file:
+    if from_file and not quiet:
         typer.secho(f"Using project {project_id} from {ontology_dir.name}/project.yml.", fg=typer.colors.CYAN, err=True)
     return project_id