cassis-cli 1.5.1__tar.gz → 1.7.0__tar.gz

{cassis_cli-1.5.1 → cassis_cli-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cassis-cli
-Version: 1.5.1
+Version: 1.7.0
 Summary: Validate, test and evaluate your Cassis ontology from your terminal, then publish it
 License: Apache-2.0
 License-File: LICENSE
@@ -35,10 +35,11 @@ Validate, test and evaluate your ontology from your terminal, then publish it. T
 - `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 the detection run to finish and exits 0 only when it completed — the schema is stored and applied atomically with run completion, so exit 0 means the DDL parsed and the project now uses it.
+- `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. The file speaks only for the schemas it contains — a partial export (one schema of many) never removes the others; pass `--complete` when it is the project's complete source schema so schemas absent from it are treated as dropped. Waits for the detection run to finish and exits 0 only when it completed — the schema is stored and applied atomically with run completion, so exit 0 means the DDL parsed and the project now uses it.
 - `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 status` shows the project's published version (number, label, git commit), whether unpublished changes await publication, the git-sync binding, how many Data source review items are pending (with the breaking count, when there are any), 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 issues` triages the issues Cassis raised on the project — what it found wrong while answering questions (an ontology gap, missing data) — without leaving the checkout: `issues list` (filterable by status, impact and cause), `issues show <id>` for the diagnosis, suggested action and the occurrences behind it, `issues evidence <id> <occurrence-id>` for what the agent actually saw, and `issues resolve` / `dismiss` / `reopen` once you've acted on it.
+- `cassis source-changes` reads the project's Data source review queue — the schema drift Cassis detected between the source and what the ontology tracks: `source-changes list` (paginated, pending by default, breaking severity flagged) and `source-changes show <id>` for one change's impact references and suggested edit. Read-only: approving or dismissing stays in the webapp; fix headlessly by editing the ontology files and opening a pull request.
 - `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
@@ -131,6 +132,11 @@ cassis schema push schema.sql
 # List the projects the API key can reach (id, name, published version, dialect):
 cassis projects list
 
+# Refresh the issues from the conversations nobody has analyzed yet (the same pass as the
+# webapp's "Analyze conversations" button; waits for the result, --no-wait returns at once,
+# and Ctrl-C cancels the run server-side and exits 130):
+cassis issues analyze
+
 # Triage the issues Cassis raised (filter by --status/--impact/--cause; --json for raw output):
 cassis issues list --status open
 cassis issues show 019f0000-0000-7000-8000-0000000000e1
@@ -189,9 +195,9 @@ 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; add-case: duplicate question or gold SQL that does not run; delete-case: no such case in the project; issues: no such issue or occurrence in the project) |
+| 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; issues: no such issue or occurrence in the project; issues analyze: failed or cancelled analysis run; schema push: failed or cancelled detection run, or the project won't accept the push (a run is already in flight, or it is warehouse-connected rather than DDL-only); source-changes show: no such change 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 |
+| 3    | Transport/API error (unreachable API, invalid key, inaccessible project, unexpected response), another eval run or issue analysis already active, out of credits, or `--timeout` reached |
 
 Commands that send the local tree (`check`, `fmt`, `upload`, `eval run`, `test`) accept up to
 20,000 ontology files / 100 MB total (path + content bytes) — sized for ontologies of

{cassis_cli-1.5.1 → cassis_cli-1.7.0}/README.md

@@ -13,10 +13,11 @@ Validate, test and evaluate your ontology from your terminal, then publish it. T
 - `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 the detection run to finish and exits 0 only when it completed — the schema is stored and applied atomically with run completion, so exit 0 means the DDL parsed and the project now uses it.
+- `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. The file speaks only for the schemas it contains — a partial export (one schema of many) never removes the others; pass `--complete` when it is the project's complete source schema so schemas absent from it are treated as dropped. Waits for the detection run to finish and exits 0 only when it completed — the schema is stored and applied atomically with run completion, so exit 0 means the DDL parsed and the project now uses it.
 - `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 status` shows the project's published version (number, label, git commit), whether unpublished changes await publication, the git-sync binding, how many Data source review items are pending (with the breaking count, when there are any), 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 issues` triages the issues Cassis raised on the project — what it found wrong while answering questions (an ontology gap, missing data) — without leaving the checkout: `issues list` (filterable by status, impact and cause), `issues show <id>` for the diagnosis, suggested action and the occurrences behind it, `issues evidence <id> <occurrence-id>` for what the agent actually saw, and `issues resolve` / `dismiss` / `reopen` once you've acted on it.
+- `cassis source-changes` reads the project's Data source review queue — the schema drift Cassis detected between the source and what the ontology tracks: `source-changes list` (paginated, pending by default, breaking severity flagged) and `source-changes show <id>` for one change's impact references and suggested edit. Read-only: approving or dismissing stays in the webapp; fix headlessly by editing the ontology files and opening a pull request.
 - `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
@@ -109,6 +110,11 @@ cassis schema push schema.sql
 # List the projects the API key can reach (id, name, published version, dialect):
 cassis projects list
 
+# Refresh the issues from the conversations nobody has analyzed yet (the same pass as the
+# webapp's "Analyze conversations" button; waits for the result, --no-wait returns at once,
+# and Ctrl-C cancels the run server-side and exits 130):
+cassis issues analyze
+
 # Triage the issues Cassis raised (filter by --status/--impact/--cause; --json for raw output):
 cassis issues list --status open
 cassis issues show 019f0000-0000-7000-8000-0000000000e1
@@ -167,9 +173,9 @@ 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; add-case: duplicate question or gold SQL that does not run; delete-case: no such case in the project; issues: no such issue or occurrence in the project) |
+| 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; issues: no such issue or occurrence in the project; issues analyze: failed or cancelled analysis run; schema push: failed or cancelled detection run, or the project won't accept the push (a run is already in flight, or it is warehouse-connected rather than DDL-only); source-changes show: no such change 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 |
+| 3    | Transport/API error (unreachable API, invalid key, inaccessible project, unexpected response), another eval run or issue analysis already active, out of credits, or `--timeout` reached |
 
 Commands that send the local tree (`check`, `fmt`, `upload`, `eval run`, `test`) accept up to
 20,000 ontology files / 100 MB total (path + content bytes) — sized for ontologies of

{cassis_cli-1.5.1 → cassis_cli-1.7.0}/cassis_cli/api.py

@@ -218,6 +218,12 @@ def post_ontology_import(
     if response.status_code >= 400:
         raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
     result = _parse_json_response(response, url)
+    # The import runs as a background job on the server; once the response
+    # stream has started the status code is fixed at 200, so an in-job failure
+    # arrives as a body carrying only an ``error`` key (deliberately not the
+    # success shape, so older CLIs fail loudly instead of reporting success).
+    if isinstance(result, dict) and "error" in result and "domain_count" not in result:
+        raise UploadValidationError(str(result["error"]))
     if not isinstance(result, dict) or not all(
         key in result for key in ("domain_count", "table_count", "join_count", "metric_count", "published_version")
     ):
@@ -235,7 +241,10 @@ def get_ontology_export(
     """GET /api/ci/projects/{project_id}/ontology/export and return the files tree."""
     url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/ontology/export"
     try:
-        with _client(transport=transport) as client:
+        # Whole-tree download: serializing thousands of tables takes the
+        # server the better part of a minute, so the default budget is the
+        # thing that breaks first — use the tree ceiling.
+        with _client(timeout=ONTOLOGY_TREE_TIMEOUT_SECONDS, 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
@@ -354,13 +363,18 @@ def post_detect_from_ddl(
     api_key: str,
     project_id: str,
     ddl: str,
+    complete_source: bool = False,
     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}"})
+            response = client.post(
+                url,
+                json={"ddl": ddl, "complete_source": complete_source},
+                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
 
@@ -429,7 +443,9 @@ def post_eval_run_start(
     if case_ids is not None:
         body["test_case_ids"] = case_ids
     try:
-        with _client(transport=transport) as client:
+        # May carry the whole ontology tree in `files` — same budget as the
+        # other whole-tree endpoints.
+        with _client(timeout=ONTOLOGY_TREE_TIMEOUT_SECONDS, transport=transport) as client:
             response = client.post(url, json=body, 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
@@ -619,7 +635,11 @@ def post_eval_run_cancel(
 
 
 class IssueNotFoundError(ApiError):
-    """The project has no issue (or occurrence) with this id."""
+    """The project has no issue, occurrence or issue-analysis run with this id.
+
+    Raised off the server's exact 404 detail, so it separates "this id doesn't
+    exist" from "this project isn't in scope for your key", which 404s too.
+    """
 
 
 def _get_issue_json(
@@ -629,8 +649,14 @@ def _get_issue_json(
     *,
     params: Optional[dict[str, str]] = None,
     not_found_message: Optional[str] = None,
+    not_found_detail: str = "Issue not found",
 ) -> Any:
-    """GET an issues URL with the shared error mapping."""
+    """GET an issues URL with the shared error mapping.
+
+    `not_found_detail` is the server's exact 404 detail for "this id does not
+    exist in the project" — `"Issue not found"` for issues and occurrences,
+    `"Issue-analysis run not found"` for analysis runs.
+    """
     try:
         with _client(transport=transport) as client:
             response = client.get(url, params=params, headers={"Authorization": f"Bearer {api_key}"})
@@ -641,8 +667,8 @@ def _get_issue_json(
         raise AuthError("The Cassis API rejected the API key (invalid or expired).")
     # Exact-match wire contract with the issue endpoints' 404 detail (see the
     # issue routes in backend/app/endpoints/ci.py): it distinguishes a missing
-    # issue or occurrence (exit 1) from a project-scope 404 (exit 3).
-    if response.status_code == 404 and not_found_message and _detail_or_text(response) == "Issue not found":
+    # issue, occurrence or run (exit 1) from a project-scope 404 (exit 3).
+    if response.status_code == 404 and not_found_message and _detail_or_text(response) == not_found_detail:
         raise IssueNotFoundError(not_found_message)
     if response.status_code in (403, 404):
         raise _project_scope_error(response)
@@ -745,6 +771,80 @@ def post_issue_status(
     return result
 
 
+class SourceChangeNotFoundError(ApiError):
+    """The project has no source change with this id."""
+
+
+def get_source_changes(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    status: Optional[str] = None,
+    limit: Optional[int] = None,
+    offset: Optional[int] = None,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """GET /api/ci/projects/{project_id}/source-changes and return the {items, total} page."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/source-changes"
+    params: dict[str, str] = {}
+    if status:
+        params["status"] = status
+    if limit is not None:
+        params["limit"] = str(limit)
+    if offset is not None:
+        params["offset"] = str(offset)
+    try:
+        with _client(transport=transport) as client:
+            response = client.get(url, params=params or None, 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 not isinstance(result.get("items"), list) or "total" not in result:
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result
+
+
+def get_source_change(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    change_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """GET /api/ci/projects/{project_id}/source-changes/{change_id} and return the full change."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/source-changes/{change_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).")
+    # Exact-match wire contract with the source-change endpoints' 404 detail
+    # (see backend/app/endpoints/ci.py): it distinguishes a missing change
+    # (exit 1) from a project-scope 404 (exit 3).
+    if response.status_code == 404 and _detail_or_text(response) == "Source change not found":
+        raise SourceChangeNotFoundError(f"No source change {change_id} in project {project_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]}")
+    result = _parse_json_response(response, url)
+    if not isinstance(result, dict) or "id" not in result:
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result
+
+
 def post_ontology_fmt(
     *,
     api_url: str,
@@ -835,3 +935,102 @@ def post_ontology_test(
     if not isinstance(result, dict) or "status" not in result:
         raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
     return result
+
+
+class IssueAnalysisActiveError(ApiError):
+    """An issue-analysis run is already in flight for the project (HTTP 409)."""
+
+
+class NothingToAnalyzeError(ApiError):
+    """Every conversation on the project has already been analyzed (HTTP 422)."""
+
+
+_ANALYSIS_RUN_KEYS = ("id", "status", "total_chats", "chats_analyzed", "occurrences_created", "issues_touched")
+
+
+def _check_analysis_run_shape(result: Any, url: str) -> dict[str, Any]:
+    if not isinstance(result, dict) or not all(key in result for key in _ANALYSIS_RUN_KEYS):
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result
+
+
+def post_issue_analysis_start(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """POST /api/ci/projects/{project_id}/issue-analysis/runs and return the run record."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/issue-analysis/runs"
+    try:
+        with _client(transport=transport) as client:
+            response = client.post(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 == 409:
+        raise IssueAnalysisActiveError(
+            "An issue analysis is already running for this project — wait for it to finish, "
+            "or cancel it from the webapp's Issues page."
+        )
+    if response.status_code == 422 and "analyz" in response.text.lower():
+        # The route takes no body, so its 422 is the server's "nothing to
+        # analyze" answer; any other 422 falls through to the generic error.
+        raise NothingToAnalyzeError("Nothing to analyze: every conversation on this project has already been analyzed.")
+    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]}")
+    return _check_analysis_run_shape(_parse_json_response(response, url), url)
+
+
+def get_issue_analysis_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}/issue-analysis/runs/{run_id} and return the run record."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/issue-analysis/runs/{run_id}"
+    return _check_analysis_run_shape(
+        _get_issue_json(
+            url,
+            api_key,
+            transport,
+            not_found_message=f"No issue-analysis run {run_id} in this project.",
+            not_found_detail="Issue-analysis run not found",
+        ),
+        url,
+    )
+
+
+def post_issue_analysis_cancel(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    run_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> None:
+    """POST /api/ci/projects/{project_id}/issue-analysis/runs/{run_id}/cancel."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/issue-analysis/runs/{run_id}/cancel"
+    try:
+        with _client(transport=transport) as client:
+            response = client.post(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).")
+    # Same exact-match contract as `get_issue_analysis_run`: a missing run is
+    # not a project-scope problem.
+    if response.status_code == 404 and _detail_or_text(response) == "Issue-analysis run not found":
+        raise IssueNotFoundError(f"No issue-analysis run {run_id} in this project.")
+    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]}")

{cassis_cli-1.5.1 → cassis_cli-1.7.0}/cassis_cli/common.py

@@ -20,6 +20,9 @@ EXIT_OK = 0
 EXIT_VALIDATION_FAILED = 1
 EXIT_USAGE = 2
 EXIT_TRANSPORT = 3
+# Conventional "terminated by SIGINT" code: the user pressed Ctrl-C while a
+# command was waiting on a server-side run (which the command cancels first).
+EXIT_INTERRUPTED = 130
 
 # Request ceilings of the /api/ci file-tree endpoints, mirrored so oversized
 # trees fail fast with a clear message before any upload. Sized for ~10,000
@@ -30,6 +33,17 @@ MAX_FILES = 20_000
 MAX_TOTAL_BYTES = 100 * 1024 * 1024
 
 
+def api_failure(exc: Exception) -> "typer.Exit":
+    """Print a transport/API error and return the transport exit code."""
+    typer.secho(str(exc), fg=typer.colors.RED, err=True)
+    return typer.Exit(EXIT_TRANSPORT)
+
+
+def one_line(value: object) -> str:
+    """Collapse a possibly-multiline value into one trimmed line for list rows."""
+    return str(value or "").replace("\n", " ").strip()
+
+
 def is_ontology_file(rel_path: str) -> bool:
     """Whether a base-relative path is an ontology file the server reads.
 

{cassis_cli-1.5.1 → cassis_cli-1.7.0}/cassis_cli/eval.py

@@ -30,6 +30,7 @@ from cassis_cli.api import (
 )
 from cassis_cli.common import (
     DEFAULT_BASE_PATH,
+    EXIT_INTERRUPTED,
     EXIT_OK,
     EXIT_TRANSPORT,
     EXIT_USAGE,
@@ -41,7 +42,6 @@ from cassis_cli.common import (
 
 app = typer.Typer(no_args_is_help=True, help="Eval commands.")
 
-EXIT_INTERRUPTED = 130
 
 # Result statuses that count as "passed"; everything else is a failure or error.
 _PASSED = "passed"
@@ -134,6 +134,9 @@ def _print_results_table(results: list[dict[str, Any]]) -> None:
 
 def _print_summary(run: dict[str, Any]) -> None:
     summary = run.get("summary") or {}
+    if summary.get("error"):
+        # A failed run carries its reason here (e.g. the worker was lost).
+        typer.secho(f"Run error: {str(summary['error'])[:300]}", fg=typer.colors.RED)
     total = summary.get("total", run.get("total_cases"))
     passed = summary.get("passed", 0)
     accuracy = summary.get("accuracy")
@@ -498,7 +501,8 @@ def run(
             typer.echo(f"Follow it at: {run_url}")
         raise typer.Exit(EXIT_OK)
 
-    typer.echo(f"Eval run {run_id} started: {total} cases against {ontology_label!r}.")
+    # To stderr under --json so `cassis eval run --json | jq` gets only the record.
+    typer.echo(f"Eval run {run_id} started: {total} cases against {ontology_label!r}.", err=json_output)
 
     try:
         final_run, results = _wait_for_run(
@@ -509,13 +513,15 @@ def run(
             total=total,
             poll_interval=poll_interval,
             timeout=timeout,
+            json_output=json_output,
         )
     except KeyboardInterrupt:
-        typer.echo("")
-        typer.echo("Interrupted — cancelling the run...")
+        # To stderr under --json, for the same reason as `issues analyze`.
+        typer.echo("", err=json_output)
+        typer.echo("Interrupted — cancelling the run...", err=json_output)
         try:
             post_eval_run_cancel(api_url=api_url, api_key=api_key, project_id=project_id, run_id=run_id)
-            typer.echo("Run cancelled.")
+            typer.echo("Run cancelled.", err=json_output)
         except ApiError as exc:
             typer.secho(f"Could not cancel the run: {exc}", fg=typer.colors.RED, err=True)
         raise typer.Exit(EXIT_INTERRUPTED)
@@ -550,9 +556,12 @@ def _wait_for_run(
     total: int,
     poll_interval: float,
     timeout: float,
+    json_output: bool = False,
 ) -> "tuple[dict[str, Any], list[dict[str, Any]]]":
     """Poll the run until terminal. Returns (run, results).
 
+    Progress lines go to stderr under --json so stdout stays the JSON record.
+
     Exits 3 directly on timeout, on an auth failure (fail fast — retrying a
     revoked key can't succeed), or after several consecutive poll failures.
     The server-side run keeps going in all three cases.
@@ -587,7 +596,7 @@ def _wait_for_run(
         passed = sum(1 for r in results if r.get("status") == _PASSED)
         line = f"{done}/{total} cases done — {passed} ✓ {done - passed} ✗"
         if line != last_line:
-            typer.echo(line)
+            typer.echo(line, err=json_output)
             last_line = line
 
         if run_record.get("status") in _TERMINAL_RUN_STATUSES:

{cassis_cli-1.5.1 → cassis_cli-1.7.0}/cassis_cli/guide.py

@@ -31,7 +31,7 @@ GUIDE_FILENAME = "AGENTS.md"
 # Monotonic version of the doctrine text below. Bump it whenever
 # ontology_design_guide.md changes (a backend test enforces the pairing) — it
 # is what lets an older writer recognize a newer guide and leave it alone.
-DOCTRINE_VERSION = 5
+DOCTRINE_VERSION = 6
 
 # Must stay byte-identical to backend/app/services/ontology_guide.py::_BANNER —
 # the server-side git export writes the same file, and differing banners would

{cassis_cli-1.5.1 → cassis_cli-1.7.0}/cassis_cli/issues.py

@@ -3,12 +3,14 @@
 Issues are what the product found wrong while answering questions (an ontology
 gap, missing data). Listing, reading the evidence behind an occurrence, and
 resolving or dismissing them from a checkout keeps the fix loop next to the
-ontology files instead of in the webapp.
+ontology files instead of in the webapp; `analyze` refreshes them from the
+conversations that arrived since the last pass, without waiting for the nightly one.
 """
 
 from __future__ import annotations
 
 import json
+import time
 from pathlib import Path
 from typing import Any, Optional
 
@@ -18,17 +20,24 @@ from cassis_cli.api import (
     ApiError,
     AuthError,
     IssueNotFoundError,
+    NothingToAnalyzeError,
     get_issue,
+    get_issue_analysis_run,
     get_issue_evidence,
     get_issues,
+    post_issue_analysis_cancel,
+    post_issue_analysis_start,
     post_issue_status,
 )
 from cassis_cli.common import (
     DEFAULT_BASE_PATH,
+    EXIT_INTERRUPTED,
     EXIT_OK,
     EXIT_TRANSPORT,
     EXIT_USAGE,
     EXIT_VALIDATION_FAILED,
+    api_failure,
+    one_line,
     require_api_key,
     resolve_project_id,
 )
@@ -81,20 +90,11 @@ def _validate_choice(value: Optional[str], allowed: "tuple[str, ...]", flag: str
     raise typer.Exit(EXIT_USAGE)
 
 
-def _api_failure(exc: ApiError) -> "typer.Exit":
-    typer.secho(str(exc), fg=typer.colors.RED, err=True)
-    return typer.Exit(EXIT_TRANSPORT)
-
-
 def _not_found_failure(exc: IssueNotFoundError) -> "typer.Exit":
     typer.secho(str(exc), fg=typer.colors.YELLOW, err=True)
     return typer.Exit(EXIT_VALIDATION_FAILED)
 
 
-def _one_line(value: Any) -> str:
-    return str(value or "").replace("\n", " ").strip()
-
-
 def _field(label: str, value: Any, *, blank_line: bool = False) -> None:
     """Print a labelled block, indenting a multi-line value under its label."""
     if value in (None, "", [], {}):
@@ -145,7 +145,7 @@ def list_issues(
             cause=cause,
         )
     except (AuthError, ApiError) as exc:
-        raise _api_failure(exc) from exc
+        raise api_failure(exc) from exc
 
     if json_output:
         typer.echo(json.dumps(issues, indent=2))
@@ -159,7 +159,7 @@ def list_issues(
         occurrences = issue.get("occurrence_count_cache") or 0
         typer.echo(
             f"{issue.get('id')}  {issue.get('impact')}  x{occurrences}  "
-            f"{issue.get('status')}  {_one_line(issue.get('title'))}"
+            f"{issue.get('status')}  {one_line(issue.get('title'))}"
         )
     raise typer.Exit(EXIT_OK)
 
@@ -188,14 +188,14 @@ def show(
     except IssueNotFoundError as exc:
         raise _not_found_failure(exc) from exc
     except (AuthError, ApiError) as exc:
-        raise _api_failure(exc) from exc
+        raise api_failure(exc) from exc
 
     if json_output:
         typer.echo(json.dumps(issue, indent=2))
         raise typer.Exit(EXIT_OK)
 
     occurrences = issue.get("occurrences") or []
-    typer.echo(f"{issue.get('id')}  {_one_line(issue.get('title'))}")
+    typer.echo(f"{issue.get('id')}  {one_line(issue.get('title'))}")
     typer.echo(
         f"{issue.get('status')}  {issue.get('impact')}  {issue.get('cause')}  "
         f"{issue.get('occurrence_count_cache', len(occurrences))} occurrence(s)"
@@ -208,7 +208,7 @@ def show(
         typer.echo("")
         typer.echo("Occurrences:")
         for occurrence in occurrences:
-            typer.echo(f"  {occurrence.get('id')}  {_one_line(occurrence.get('symptom'))}")
+            typer.echo(f"  {occurrence.get('id')}  {one_line(occurrence.get('symptom'))}")
     raise typer.Exit(EXIT_OK)
 
 
@@ -245,7 +245,7 @@ def evidence(
     except IssueNotFoundError as exc:
         raise _not_found_failure(exc) from exc
     except (AuthError, ApiError) as exc:
-        raise _api_failure(exc) from exc
+        raise api_failure(exc) from exc
 
     if json_output:
         typer.echo(json.dumps(record, indent=2))
@@ -281,7 +281,7 @@ def _set_status(
     except IssueNotFoundError as exc:
         raise _not_found_failure(exc) from exc
     except (AuthError, ApiError) as exc:
-        raise _api_failure(exc) from exc
+        raise api_failure(exc) from exc
 
     typer.secho(f"✓ Issue {issue_id} is now {issue.get('status', status)}.", fg=typer.colors.GREEN)
     raise typer.Exit(EXIT_OK)
@@ -296,7 +296,7 @@ def resolve(
     api_url: str = _API_URL_OPTION,
     base_path: str = _BASE_PATH_OPTION,
 ) -> None:
-    """Mark an issue resolved — the ontology change that fixes it has landed.
+    """Mark an issue resolved — the ontology change that fixes it is published.
 
     Exits 0 on success, 1 when the issue does not exist in the project, 2 on
     usage errors, 3 on transport/API errors.
@@ -360,3 +360,178 @@ def reopen(
         api_url=api_url,
         base_path=base_path,
     )
+
+
+_TERMINAL_ANALYSIS_STATUSES = frozenset({"completed", "failed", "cancelled"})
+
+# Consecutive poll failures tolerated before giving up — same tolerance as
+# `eval run`: a transient blip must not abandon a multi-minute run, a
+# permanently broken poll must not spin until --timeout.
+_MAX_CONSECUTIVE_POLL_FAILURES = 5
+
+
+@app.command()
+def analyze(
+    path: Path = _PATH_OPTION,
+    project_id: Optional[str] = _PROJECT_OPTION,
+    api_key: Optional[str] = _API_KEY_OPTION,
+    api_url: str = _API_URL_OPTION,
+    base_path: str = _BASE_PATH_OPTION,
+    wait: bool = typer.Option(
+        True,
+        "--wait/--no-wait",
+        help="Wait for the analysis to finish and print its summary (default), or just print the run id.",
+    ),
+    poll_interval: float = typer.Option(5.0, "--poll-interval", help="Seconds between status polls."),
+    timeout: float = typer.Option(1800.0, "--timeout", help="Give up waiting after this many seconds."),
+    json_output: bool = typer.Option(False, "--json", help="Print the final run record as raw JSON."),
+) -> None:
+    """Analyze the conversations nobody has analyzed yet, turning what went wrong into issues.
+
+    The same pass as the webapp's "Analyze conversations" button — it runs on
+    Cassis's workers, so a Ctrl-C or a lost connection never kills it — started
+    on demand instead of waiting for the nightly one. When every conversation is
+    already analyzed the command is a no-op and exits 0, so a job re-running it
+    on a quiet project stays green. Exits 0 when the run completes, 1 when it
+    fails or is cancelled, 2 on usage errors, 3 on transport errors, when a run
+    is already in flight, or on --timeout (the run keeps going server-side).
+    Ctrl-C cancels the run and exits 130.
+    """
+    api_key = require_api_key(api_key)
+    project_id = resolve_project_id(project_id, path / Path(base_path), quiet=json_output)
+
+    try:
+        run = post_issue_analysis_start(api_url=api_url, api_key=api_key, project_id=project_id)
+    except NothingToAnalyzeError as exc:
+        if json_output:
+            typer.echo(json.dumps({"run": None, "message": str(exc)}, indent=2))
+        else:
+            typer.echo(str(exc))
+        raise typer.Exit(EXIT_OK) from exc
+    except (AuthError, ApiError) as exc:  # covers IssueAnalysisActiveError too
+        raise api_failure(exc) from exc
+
+    run_id = str(run["id"])
+    total = int(run.get("total_chats") or 0)
+
+    if not wait:
+        if json_output:
+            typer.echo(json.dumps({"run": run}, indent=2))
+        else:
+            typer.echo(f"Analysis run {run_id} started: {total} conversation(s) to analyze.")
+            typer.echo("It keeps going server-side; the results land on the webapp's Issues page.")
+        raise typer.Exit(EXIT_OK)
+
+    if not json_output:
+        typer.echo(f"Analysis run {run_id} started: {total} conversation(s) to analyze.")
+
+    try:
+        final_run = _wait_for_analysis(
+            api_url=api_url,
+            api_key=api_key,
+            project_id=project_id,
+            run_id=run_id,
+            poll_interval=poll_interval,
+            timeout=timeout,
+            quiet=json_output,
+        )
+    except KeyboardInterrupt:
+        # To stderr under --json: stdout is the machine's, and these lines would
+        # land in front of the JSON document a caller is parsing.
+        typer.echo("", err=json_output)
+        typer.echo("Interrupted — cancelling the analysis...", err=json_output)
+        try:
+            post_issue_analysis_cancel(api_url=api_url, api_key=api_key, project_id=project_id, run_id=run_id)
+            typer.echo("Analysis cancelled. Conversations analyzed so far keep their occurrences.", err=json_output)
+        except ApiError as exc:
+            typer.secho(f"Could not cancel the analysis: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_INTERRUPTED)
+
+    if json_output:
+        typer.echo(json.dumps({"run": final_run}, indent=2))
+    else:
+        _print_analysis_outcome(final_run)
+
+    if final_run.get("status") == "completed":
+        raise typer.Exit(EXIT_OK)
+    raise typer.Exit(EXIT_VALIDATION_FAILED)
+
+
+def _wait_for_analysis(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    run_id: str,
+    poll_interval: float,
+    timeout: float,
+    quiet: bool,
+) -> dict[str, Any]:
+    """Poll the run until terminal and return its final record.
+
+    Exits 3 directly on timeout, on an auth failure (fail fast — retrying a
+    revoked key can't succeed), or after several consecutive poll failures.
+    The server-side run keeps going in all three cases.
+    """
+    deadline = time.monotonic() + timeout
+    last_line = ""
+    failures = 0
+    while time.monotonic() < deadline:
+        try:
+            run = get_issue_analysis_run(api_url=api_url, api_key=api_key, project_id=project_id, run_id=run_id)
+        except AuthError as exc:
+            typer.secho(f"{exc} The analysis keeps going server-side.", fg=typer.colors.RED, err=True)
+            raise typer.Exit(EXIT_TRANSPORT) from exc
+        except IssueNotFoundError as exc:
+            # The run is gone (purged): nothing to keep polling for.
+            raise _not_found_failure(exc) from exc
+        except ApiError as exc:
+            failures += 1
+            if failures >= _MAX_CONSECUTIVE_POLL_FAILURES:
+                typer.secho(
+                    f"Polling failed {failures} times in a row ({exc}). "
+                    "Giving up — the analysis keeps going server-side; see the webapp's Issues page.",
+                    fg=typer.colors.RED,
+                    err=True,
+                )
+                raise typer.Exit(EXIT_TRANSPORT) from exc
+            typer.secho(f"(poll failed, retrying: {exc})", fg=typer.colors.YELLOW, err=True)
+            time.sleep(poll_interval)
+            continue
+        failures = 0
+
+        line = (
+            f"{run.get('chats_analyzed', 0)}/{run.get('total_chats', 0)} conversations analyzed — "
+            f"{run.get('occurrences_created', 0)} occurrence(s) found"
+        )
+        if not quiet and line != last_line:
+            typer.echo(line)
+            last_line = line
+
+        if run.get("status") in _TERMINAL_ANALYSIS_STATUSES:
+            return run
+        time.sleep(poll_interval)
+
+    typer.secho(
+        f"Timed out after {timeout:.0f}s waiting for analysis run {run_id}. "
+        "The analysis keeps going server-side — see the webapp's Issues page.",
+        fg=typer.colors.YELLOW,
+        err=True,
+    )
+    raise typer.Exit(EXIT_TRANSPORT)
+
+
+def _print_analysis_outcome(run: dict[str, Any]) -> None:
+    status = run.get("status")
+    if status == "completed":
+        typer.echo("")
+        typer.echo(
+            f"Analysis complete: {run.get('chats_analyzed', 0)} conversation(s) analyzed, "
+            f"{run.get('occurrences_created', 0)} occurrence(s) found, "
+            f"{run.get('issues_touched', 0)} issue(s) created or updated."
+        )
+        typer.echo("Review them with `cassis issues list`.")
+    elif status == "cancelled":
+        typer.secho("Analysis cancelled before it finished.", fg=typer.colors.YELLOW, err=True)
+    else:
+        typer.secho(f"Analysis failed: {run.get('error') or 'unknown error'}", fg=typer.colors.RED, err=True)

{cassis_cli-1.5.1 → cassis_cli-1.7.0}/cassis_cli/main.py

@@ -9,6 +9,7 @@ from cassis_cli.issues import app as issues_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.source_changes import app as source_changes_app
 from cassis_cli.status import status
 from cassis_cli.verify import verify
 
@@ -24,6 +25,7 @@ app.add_typer(eval_app, name="eval")
 app.add_typer(schema_app, name="schema")
 app.add_typer(projects_app, name="projects")
 app.add_typer(issues_app, name="issues")
+app.add_typer(source_changes_app, name="source-changes")
 app.command()(status)
 app.command()(verify)
 

{cassis_cli-1.5.1 → cassis_cli-1.7.0}/cassis_cli/ontology_design_guide.md

@@ -440,6 +440,15 @@ checkout:
 Merging the pull request syncs and publishes the ontology; nothing reaches
 production answers until then.
 
+When the change came from a Cassis issue, merging is still not the last step.
+Confirm the published version contains it (`cassis status`, or
+`get_project_status` over MCP), then propose resolving that issue —
+`cassis issues resolve <id>`, or `update_issue_status`. Propose it to whoever
+owns the project: resolving needs the editor or admin role, and it records an
+outcome without changing any ontology. Never resolve before publication, and
+never silently — an issue nobody resolves stays in the triage queue and reads
+as a gap that was never fixed.
+
 ---
 
 *This guide is the single canonical home for Cassis ontology modeling doctrine.

{cassis_cli-1.5.1 → cassis_cli-1.7.0}/cassis_cli/schema.py

@@ -175,17 +175,26 @@ def push(
         envvar="CASSIS_BASE_PATH",
         help="Repository directory the ontology is exported under (the project's git-sync Path setting).",
     ),
+    complete_source: bool = typer.Option(
+        False,
+        "--complete",
+        help="The file is the project's complete source schema: schemas absent from it are treated as dropped. "
+        "Without it, the upload only speaks for the schemas it contains.",
+    ),
     poll_interval: float = typer.Option(5.0, "--poll-interval", help="Seconds between polls."),
     timeout: float = typer.Option(600.0, "--timeout", help="Give up waiting after this many seconds."),
     json_output: bool = typer.Option(False, "--json", help="Print the run record as raw JSON."),
 ) -> None:
     """Upload a DDL file to detect source-schema changes (same as the webapp's "Update from DDL").
 
-    The DDL must contain at least one CREATE TABLE statement and represents the
-    project's complete source schema. Cassis diffs it against the ontology:
-    added, dropped, and changed objects appear in Ontology > Review > Data
-    source for approval. Re-uploading a corrected DDL supersedes the previous
-    one. Only works on DDL-only projects (no warehouse connection).
+    The DDL must contain at least one CREATE TABLE statement. Cassis diffs it
+    against the ontology: added, dropped, and changed objects appear in
+    Ontology > Review > Data source for approval. The file speaks only for the
+    schemas it contains — a partial export (one schema of many) never removes
+    the others; pass --complete when the file is the project's complete source
+    schema so schemas absent from it are treated as dropped. Re-uploading a
+    corrected DDL supersedes the previous one. Only works on DDL-only projects
+    (no warehouse connection).
 
     Always waits for the detection run to finish: the server parses the DDL
     inside the run (a large file takes a while, and an unparseable one fails
@@ -211,7 +220,9 @@ def push(
         raise typer.Exit(EXIT_USAGE)
 
     try:
-        run = post_detect_from_ddl(api_url=api_url, api_key=api_key, project_id=project_id, ddl=ddl_text)
+        run = post_detect_from_ddl(
+            api_url=api_url, api_key=api_key, project_id=project_id, ddl=ddl_text, complete_source=complete_source
+        )
     except SourceChangeConflictError as exc:
         typer.secho(str(exc), fg=typer.colors.RED, err=True)
         raise typer.Exit(EXIT_VALIDATION_FAILED) from exc
@@ -220,7 +231,8 @@ def push(
         raise typer.Exit(EXIT_TRANSPORT) from exc
 
     run_id = run["run_id"]
-    typer.echo(f"Detection run started: {run_id}")
+    # To stderr under --json so `cassis schema push --json | jq` gets only the record.
+    typer.echo(f"Detection run started: {run_id}", err=json_output)
 
     run = _wait_for_detection_run(
         api_url=api_url,
@@ -237,10 +249,21 @@ def push(
     run_status = run.get("status")
     if run_status == "completed":
         summary = run.get("summary") or {}
-        total = summary.get("total_changes", 0)
+        total = summary.get("reviewable_total")
+        if total is None:
+            total = sum(summary.get(key, 0) for key in ("changes_created", "changes_updated", "changes_reopened"))
+        if summary.get("partial_upload_suspected"):
+            typer.secho(
+                "Note: the file drops most of the tracked tables in the schemas it covers, which"
+                " often means a partial export. Removals of modeled tables wait for review;"
+                " re-push a complete export to undo unintended drops.",
+                fg=typer.colors.YELLOW,
+                err=True,
+            )
         typer.secho(
-            f"✓ Detection completed: {total} change(s) detected." if total else "✓ Detection completed: no changes.",
+            f"✓ Detection completed: {total} change(s) to review." if total else "✓ Detection completed: no changes.",
             fg=typer.colors.GREEN,
+            err=json_output,
         )
         raise typer.Exit(EXIT_OK)
     if run_status == "failed":

cassis_cli-1.7.0/cassis_cli/source_changes.py

@@ -0,0 +1,191 @@
+"""`cassis source-changes` — read the Data source review queue from the terminal.
+
+Source changes are the schema drift Cassis detected between the data source
+and what the ontology tracks (tables/columns added, removed, renamed,
+retyped). Reading them from a checkout lets an agent see that a breaking
+`column_removed` card is pending against a table it is editing — the fix then
+happens in the ontology files via a pull request. Read-only by design:
+reviewing (approve applies ontology edits, dismiss mutes the table) stays in
+the webapp.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Optional
+
+import typer
+from cassis_cli.api import (
+    DEFAULT_API_URL,
+    ApiError,
+    AuthError,
+    SourceChangeNotFoundError,
+    get_source_change,
+    get_source_changes,
+)
+from cassis_cli.common import (
+    DEFAULT_BASE_PATH,
+    EXIT_OK,
+    EXIT_USAGE,
+    EXIT_VALIDATION_FAILED,
+    api_failure,
+    one_line,
+    require_api_key,
+    resolve_project_id,
+)
+
+app = typer.Typer(no_args_is_help=True, help="Read the project's Data source review queue.")
+
+STATUSES = ("pending", "approved", "rejected", "superseded")
+
+_PATH_OPTION = typer.Option(
+    Path("."),
+    "--path",
+    help="Repository checkout root (holds <base-path>/project.yml for the --project default).",
+)
+_PROJECT_OPTION = typer.Option(
+    None,
+    "--project",
+    envvar="CASSIS_PROJECT_ID",
+    help="Target Cassis project ID (UUID). Defaults to the id in <base-path>/project.yml.",
+)
+_API_KEY_OPTION = typer.Option(
+    None,
+    "--api-key",
+    envvar="CASSIS_API_KEY",
+    help="Cassis API key (sk-k6-...). Create one in Organization settings -> API keys.",
+)
+_API_URL_OPTION = typer.Option(
+    DEFAULT_API_URL,
+    "--api-url",
+    envvar="CASSIS_API_URL",
+    help="Cassis API base URL.",
+)
+_BASE_PATH_OPTION = typer.Option(
+    DEFAULT_BASE_PATH,
+    "--base-path",
+    envvar="CASSIS_BASE_PATH",
+    help="Repository directory the ontology is exported under (holds project.yml for the --project default).",
+)
+
+
+def _target(change: dict[str, Any]) -> str:
+    parts = [change.get("target_schema"), change.get("target_table"), change.get("target_column")]
+    return ".".join(str(p) for p in parts if p)
+
+
+@app.command(name="list")
+def list_source_changes(
+    status: Optional[str] = typer.Option(
+        None, "--status", help=f"Filter by status ({', '.join(STATUSES)}). Defaults to pending."
+    ),
+    limit: int = typer.Option(100, "--limit", min=1, max=500, help="Page size."),
+    offset: int = typer.Option(0, "--offset", min=0, help="Page start, newest first."),
+    path: Path = _PATH_OPTION,
+    project_id: Optional[str] = _PROJECT_OPTION,
+    api_key: Optional[str] = _API_KEY_OPTION,
+    api_url: str = _API_URL_OPTION,
+    base_path: str = _BASE_PATH_OPTION,
+    json_output: bool = typer.Option(False, "--json", help="Print the page as raw JSON ({items, total})."),
+) -> None:
+    """List the pending Data source review items, newest first.
+
+    Prints each change's id, type, severity, status and target; the id is what
+    `cassis source-changes show` takes. A `breaking` severity means a curated
+    ontology object references the changed source object. Exits 0 on success,
+    2 on usage errors, 3 on transport/API errors.
+    """
+    if status is not None and status not in STATUSES:
+        typer.secho(f"--status must be one of {', '.join(STATUSES)}, got {status!r}.", fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_USAGE)
+    api_key = require_api_key(api_key)
+    project_id = resolve_project_id(project_id, path / Path(base_path), quiet=json_output)
+
+    try:
+        page = get_source_changes(
+            api_url=api_url,
+            api_key=api_key,
+            project_id=project_id,
+            status=status,
+            limit=limit,
+            offset=offset,
+        )
+    except (AuthError, ApiError) as exc:
+        raise api_failure(exc) from exc
+
+    if json_output:
+        typer.echo(json.dumps(page, indent=2))
+        raise typer.Exit(EXIT_OK)
+
+    items = page.get("items") or []
+    total = page.get("total", len(items))
+    if not items:
+        typer.echo("No source changes match." if status else "No pending source changes.")
+        raise typer.Exit(EXIT_OK)
+
+    for change in items:
+        typer.echo(
+            f"{change.get('id')}  {change.get('change_type')}  {change.get('severity')}  "
+            f"{change.get('status')}  {_target(change)}"
+        )
+    shown = len(items)
+    if offset + shown < total:
+        typer.echo(f"Showing {shown} of {total} (use --offset {offset + shown} for the next page).")
+    raise typer.Exit(EXIT_OK)
+
+
+@app.command()
+def show(
+    change_id: str = typer.Argument(..., help="Id of the change to show (from `cassis source-changes list`)."),
+    path: Path = _PATH_OPTION,
+    project_id: Optional[str] = _PROJECT_OPTION,
+    api_key: Optional[str] = _API_KEY_OPTION,
+    api_url: str = _API_URL_OPTION,
+    base_path: str = _BASE_PATH_OPTION,
+    json_output: bool = typer.Option(False, "--json", help="Print the change as raw JSON."),
+) -> None:
+    """Show one Data source review item: its impact and the suggested edit.
+
+    `impact` lists the curated ontology objects referencing the changed source
+    object; the suggested edit describes what approving in the webapp would do
+    — make the equivalent edit in the ontology files to fix headlessly. Exits
+    0 on success, 1 when the change does not exist in the project, 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), quiet=json_output)
+
+    try:
+        change = get_source_change(api_url=api_url, api_key=api_key, project_id=project_id, change_id=change_id)
+    except SourceChangeNotFoundError as exc:
+        typer.secho(str(exc), fg=typer.colors.YELLOW, err=True)
+        raise typer.Exit(EXIT_VALIDATION_FAILED) from exc
+    except (AuthError, ApiError) as exc:
+        raise api_failure(exc) from exc
+
+    if json_output:
+        typer.echo(json.dumps(change, indent=2))
+        raise typer.Exit(EXIT_OK)
+
+    typer.echo(f"{change.get('id')}  {change.get('change_type')}  {change.get('severity')}  {change.get('status')}")
+    typer.echo(f"Target: {_target(change)}")
+    typer.echo(f"Raised {change.get('times_raised', 1)}x, last {change.get('last_detected_at')}")
+    impact = change.get("impact") or []
+    if impact:
+        typer.echo("")
+        typer.echo("Impact:")
+        for ref in impact:
+            line = f"  {ref.get('kind')}  {ref.get('confidence')}  {one_line(ref.get('object_label'))}"
+            detail = ref.get("detail")
+            if detail:
+                line += f"  — {one_line(detail)}"
+            typer.echo(line)
+    edit = change.get("suggested_edit") or {}
+    summary = edit.get("human_summary") if isinstance(edit, dict) else None
+    if summary:
+        typer.echo("")
+        typer.echo(f"Suggested edit: {one_line(summary)}")
+        for note in edit.get("manual_review") or []:
+            typer.echo(f"  Manual review: {one_line(note)}")
+    raise typer.Exit(EXIT_OK)

{cassis_cli-1.5.1 → cassis_cli-1.7.0}/cassis_cli/status.py

@@ -87,6 +87,11 @@ def _render(status_record: "dict[str, Any]", comparison_text: str) -> None:
         typer.echo(f"Git sync: {git_sync['provider']} {git_sync['repo']} (path {git_sync['base_path']})")
     else:
         typer.echo("Git sync: not configured")
+    pending = status_record.get("pending_source_changes")
+    if pending and pending.get("total"):
+        breaking = pending.get("breaking") or 0
+        breaking_text = f", {breaking} breaking" if breaking else ""
+        typer.echo(f"Source changes pending review: {pending['total']}{breaking_text} (cassis source-changes list)")
     typer.echo(f"Local checkout: {comparison_text}")
 
 

{cassis_cli-1.5.1 → cassis_cli-1.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cassis-cli"
-version = "1.5.1"
+version = "1.7.0"
 description = "Validate, test and evaluate your Cassis ontology from your terminal, then publish it"
 readme = "README.md"
 license = { text = "Apache-2.0" }