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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cassis-cli
-Version: 1.4.0
+Version: 1.5.0
 Summary: Cassis CLI — run Cassis actions (ontology validation, upload and publish) from your CI pipelines
 License: Apache-2.0
 License-File: LICENSE
@@ -35,9 +35,10 @@ Run Cassis actions from your CI pipelines:
 - `cassis ontology test` runs individual questions through the text-to-SQL agent using your local ontology files, so you can check that a change actually works (e.g. a new column gets picked) — where `eval run` only checks for regressions on existing eval cases.
 - `cassis eval add-case` adds a gold question/SQL case to the project's eval suite — after fixing an ontology issue, add the question users were failing on so `eval run` guards it from regressing.
 - `cassis eval list-cases` and `cassis eval delete-case` maintain the suite: list the current cases with their ids, and prune one that is stale or wrong (e.g. its gold SQL encodes a definition the ontology has since changed).
-- `cassis schema push` uploads a DDL file to detect source-schema changes on a DDL-only project (same as the webapp's "Update from DDL" button): Cassis diffs the DDL against the ontology and surfaces added, dropped, and changed objects in Ontology > Review > Data source for approval. Waits for completion by default; `--no-wait` returns immediately.
+- `cassis 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 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 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 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
@@ -60,7 +61,7 @@ The ontology tree under `<base-path>` (default `cassis/`) is:
 
 1. Create an API key in Cassis under **Organization settings → API keys** (keys start with `sk-k6-`).
 2. Store it as a CI secret and expose it as `CASSIS_API_KEY`.
-3. For `pull`, `upload`, `schema pull`, `eval run`, `ontology test`, and the `eval` case commands (`add-case`, `list-cases`, `delete-case`): the project ID (UUID) is taken from `<base-path>/project.yml` in the checkout (written by `pull` and by publishing) — so once a repo is pulled you don't need to pass it. To override, or before the first pull, set `CASSIS_PROJECT_ID` or pass `--project` (find the UUID 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).
+3. For `pull`, `upload`, `schema pull`, `eval run`, `ontology test`, the `eval` case commands (`add-case`, `list-cases`, `delete-case`), and the `issues` commands: 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
 
@@ -122,15 +123,25 @@ 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):
+# Push a DDL file to detect source-schema changes (DDL-only projects);
+# exits 0 only once the run completed and the schema is applied:
 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
 
+# 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
+
+# Read what the agent saw for one occurrence (ids from `issues show`):
+cassis issues evidence 019f0000-0000-7000-8000-0000000000e1 019f0000-0000-7000-8000-0000000000c1
+
+# Close the loop once the fix is published (or reopen):
+cassis issues resolve 019f0000-0000-7000-8000-0000000000e1
+cassis issues dismiss 019f0000-0000-7000-8000-0000000000e1
+cassis issues reopen 019f0000-0000-7000-8000-0000000000e1
+
 # Published version vs local checkout (add --watch to poll until your merge is published):
 cassis status
 cassis status --watch --timeout 600
@@ -147,7 +158,7 @@ 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` (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) |
+| `--project` (check, pull, upload, schema pull, eval run, eval add-case, eval list-cases, eval delete-case, test, issues) | `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 `--case <id>` (repeatable; run only the named
 cases, ids from `eval list-cases` or `add-case`), `--label` (run label in the Evals page; defaults
@@ -177,7 +188,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; add-case: duplicate question or gold SQL that does not run; delete-case: no such case 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) |
 | 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.4.0 → cassis_cli-1.5.0}/README.md

@@ -13,9 +13,10 @@ Run Cassis actions from your CI pipelines:
 - `cassis ontology test` runs individual questions through the text-to-SQL agent using your local ontology files, so you can check that a change actually works (e.g. a new column gets picked) — where `eval run` only checks for regressions on existing eval cases.
 - `cassis eval add-case` adds a gold question/SQL case to the project's eval suite — after fixing an ontology issue, add the question users were failing on so `eval run` guards it from regressing.
 - `cassis eval list-cases` and `cassis eval delete-case` maintain the suite: list the current cases with their ids, and prune one that is stale or wrong (e.g. its gold SQL encodes a definition the ontology has since changed).
-- `cassis schema push` uploads a DDL file to detect source-schema changes on a DDL-only project (same as the webapp's "Update from DDL" button): Cassis diffs the DDL against the ontology and surfaces added, dropped, and changed objects in Ontology > Review > Data source for approval. Waits for completion by default; `--no-wait` returns immediately.
+- `cassis 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 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 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 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
@@ -38,7 +39,7 @@ The ontology tree under `<base-path>` (default `cassis/`) is:
 
 1. Create an API key in Cassis under **Organization settings → API keys** (keys start with `sk-k6-`).
 2. Store it as a CI secret and expose it as `CASSIS_API_KEY`.
-3. For `pull`, `upload`, `schema pull`, `eval run`, `ontology test`, and the `eval` case commands (`add-case`, `list-cases`, `delete-case`): the project ID (UUID) is taken from `<base-path>/project.yml` in the checkout (written by `pull` and by publishing) — so once a repo is pulled you don't need to pass it. To override, or before the first pull, set `CASSIS_PROJECT_ID` or pass `--project` (find the UUID 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).
+3. For `pull`, `upload`, `schema pull`, `eval run`, `ontology test`, the `eval` case commands (`add-case`, `list-cases`, `delete-case`), and the `issues` commands: 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
 
@@ -100,15 +101,25 @@ 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):
+# Push a DDL file to detect source-schema changes (DDL-only projects);
+# exits 0 only once the run completed and the schema is applied:
 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
 
+# 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
+
+# Read what the agent saw for one occurrence (ids from `issues show`):
+cassis issues evidence 019f0000-0000-7000-8000-0000000000e1 019f0000-0000-7000-8000-0000000000c1
+
+# Close the loop once the fix is published (or reopen):
+cassis issues resolve 019f0000-0000-7000-8000-0000000000e1
+cassis issues dismiss 019f0000-0000-7000-8000-0000000000e1
+cassis issues reopen 019f0000-0000-7000-8000-0000000000e1
+
 # Published version vs local checkout (add --watch to poll until your merge is published):
 cassis status
 cassis status --watch --timeout 600
@@ -125,7 +136,7 @@ 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` (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) |
+| `--project` (check, pull, upload, schema pull, eval run, eval add-case, eval list-cases, eval delete-case, test, issues) | `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 `--case <id>` (repeatable; run only the named
 cases, ids from `eval list-cases` or `add-case`), `--label` (run label in the Evals page; defaults
@@ -155,7 +166,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; add-case: duplicate question or gold SQL that does not run; delete-case: no such case 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) |
 | 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.5.0/cassis_cli/__init__.py

@@ -0,0 +1,8 @@
+"""Cassis CLI — run Cassis actions from your CI pipelines."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("cassis-cli")
+except PackageNotFoundError:  # uninstalled source tree (no dist metadata)
+    __version__ = "0.0.0"

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

@@ -11,6 +11,14 @@ from cassis_cli import __version__
 DEFAULT_API_URL = "https://app.getcassis.com"
 TIMEOUT_SECONDS = 60.0
 
+# Whole-tree endpoints (check, fmt, import) parse and re-serialize every file
+# server-side, so their duration scales with the ontology: a few hundred files
+# is tens of seconds of pure CPU, and the 60s default cut real runs off. The
+# ceiling is deliberately far above what the edge allows (CloudFront's
+# origin_read_timeout, see infra) — a client-side timeout should never be the
+# thing that reports a slow server as "unreachable".
+ONTOLOGY_TREE_TIMEOUT_SECONDS = 300.0
+
 USER_AGENT = f"cassis-cli/{__version__}"
 
 # Response header the CI endpoints set to the newest cassis-cli on PyPI.
@@ -149,7 +157,7 @@ def post_ontology_check(
     else:
         url = api_url.rstrip("/") + "/api/ci/ontology-check"
     try:
-        with _client(transport=transport) as client:
+        with _client(timeout=ONTOLOGY_TREE_TIMEOUT_SECONDS, transport=transport) as client:
             response = client.post(
                 url,
                 json={"files": files},
@@ -190,7 +198,7 @@ def post_ontology_import(
     if label is not None:
         body["label"] = label
     try:
-        with _client(transport=transport) as client:
+        with _client(timeout=ONTOLOGY_TREE_TIMEOUT_SECONDS, transport=transport) as client:
             response = client.post(
                 url,
                 json=body,
@@ -610,6 +618,133 @@ def post_eval_run_cancel(
         raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
 
 
+class IssueNotFoundError(ApiError):
+    """The project has no issue (or occurrence) with this id."""
+
+
+def _get_issue_json(
+    url: str,
+    api_key: str,
+    transport: Optional[httpx.BaseTransport],
+    *,
+    params: Optional[dict[str, str]] = None,
+    not_found_message: Optional[str] = None,
+) -> Any:
+    """GET an issues URL with the shared error mapping."""
+    try:
+        with _client(transport=transport) as client:
+            response = client.get(url, params=params, 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 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":
+        raise IssueNotFoundError(not_found_message)
+    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 _parse_json_response(response, url)
+
+
+def get_issues(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    status: Optional[str] = None,
+    impact: Optional[str] = None,
+    cause: Optional[str] = None,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> list[dict[str, Any]]:
+    """GET /api/ci/projects/{project_id}/issues and return the issue list."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/issues"
+    params = {key: value for key, value in (("status", status), ("impact", impact), ("cause", cause)) if value}
+    result = _get_issue_json(url, api_key, transport, params=params)
+    if not isinstance(result, list) or not all(isinstance(issue, dict) and "id" in issue for issue in result):
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result
+
+
+def get_issue(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    issue_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """GET /api/ci/projects/{project_id}/issues/{issue_id} and return the issue with its occurrences."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/issues/{issue_id}"
+    result = _get_issue_json(
+        url,
+        api_key,
+        transport,
+        not_found_message=f"No issue {issue_id} in this project (or occurrence not found).",
+    )
+    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 get_issue_evidence(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    issue_id: str,
+    occurrence_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """GET the evidence of one occurrence and return it."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/issues/{issue_id}/occurrences/{occurrence_id}/evidence"
+    result = _get_issue_json(
+        url,
+        api_key,
+        transport,
+        not_found_message=f"No issue {issue_id} in this project (or occurrence not found).",
+    )
+    if not isinstance(result, dict):
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result
+
+
+def post_issue_status(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    issue_id: str,
+    status: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """POST /api/ci/projects/{project_id}/issues/{issue_id}/status and return the updated issue."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/issues/{issue_id}/status"
+    try:
+        with _client(transport=transport) as client:
+            response = client.post(url, json={"status": status}, 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 wire contract as the issue GETs above.
+    if response.status_code == 404 and _detail_or_text(response) == "Issue not found":
+        raise IssueNotFoundError(f"No issue {issue_id} in this project (or occurrence not found).")
+    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 "status" not in result:
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result
+
+
 def post_ontology_fmt(
     *,
     api_url: str,
@@ -620,7 +755,7 @@ def post_ontology_fmt(
     """POST the ontology tree to /api/ci/ontology-fmt and return the response body."""
     url = api_url.rstrip("/") + "/api/ci/ontology-fmt"
     try:
-        with _client(transport=transport) as client:
+        with _client(timeout=ONTOLOGY_TREE_TIMEOUT_SECONDS, transport=transport) as client:
             response = client.post(
                 url,
                 json={"files": files},

cassis_cli-1.5.0/cassis_cli/issues.py

@@ -0,0 +1,362 @@
+"""`cassis issues` — triage the issues Cassis raised on the project, from the terminal.
+
+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.
+"""
+
+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,
+    IssueNotFoundError,
+    get_issue,
+    get_issue_evidence,
+    get_issues,
+    post_issue_status,
+)
+from cassis_cli.common import (
+    DEFAULT_BASE_PATH,
+    EXIT_OK,
+    EXIT_TRANSPORT,
+    EXIT_USAGE,
+    EXIT_VALIDATION_FAILED,
+    require_api_key,
+    resolve_project_id,
+)
+
+app = typer.Typer(no_args_is_help=True, help="Triage the project's issues.")
+
+STATUSES = ("open", "resolved", "dismissed")
+IMPACTS = ("wrong_answer", "unreliable_answer", "no_answer", "inefficient")
+CAUSES = ("ontology_gap", "missing_data")
+
+# The five options every command in this subapp takes. Shared instances: typer
+# reads the option metadata at decoration time, so one constant per flag keeps
+# the six commands from repeating the same block.
+_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 _validate_choice(value: Optional[str], allowed: "tuple[str, ...]", flag: str) -> Optional[str]:
+    """Exit 2 (usage) when a filter value is not one the API knows."""
+    if value is None or value in allowed:
+        return value
+    typer.secho(f"{flag} must be one of {', '.join(allowed)}, got {value!r}.", fg=typer.colors.RED, err=True)
+    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, "", [], {}):
+        return
+    if blank_line:
+        typer.echo("")
+    text = value if isinstance(value, str) else json.dumps(value, indent=2)
+    lines = text.strip().splitlines()
+    if len(lines) == 1:
+        typer.echo(f"{label}: {lines[0]}")
+    else:
+        typer.echo(f"{label}:")
+        for line in lines:
+            typer.echo(f"  {line}")
+
+
+@app.command(name="list")
+def list_issues(
+    status: Optional[str] = typer.Option(None, "--status", help=f"Filter by status ({', '.join(STATUSES)})."),
+    impact: Optional[str] = typer.Option(None, "--impact", help=f"Filter by impact ({', '.join(IMPACTS)})."),
+    cause: Optional[str] = typer.Option(None, "--cause", help=f"Filter by cause ({', '.join(CAUSES)})."),
+    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 issues as raw JSON."),
+) -> None:
+    """List the project's issues, prioritized by impact then recurrence.
+
+    Prints each issue's id, impact, occurrence count, status and title; the id
+    is what `cassis issues show`, `resolve`, `dismiss` and `reopen` take. Exits
+    0 on success, 2 on usage errors, 3 on transport/API errors.
+    """
+    status = _validate_choice(status, STATUSES, "--status")
+    impact = _validate_choice(impact, IMPACTS, "--impact")
+    cause = _validate_choice(cause, CAUSES, "--cause")
+    api_key = require_api_key(api_key)
+    project_id = resolve_project_id(project_id, path / Path(base_path), quiet=json_output)
+
+    try:
+        issues = get_issues(
+            api_url=api_url,
+            api_key=api_key,
+            project_id=project_id,
+            status=status,
+            impact=impact,
+            cause=cause,
+        )
+    except (AuthError, ApiError) as exc:
+        raise _api_failure(exc) from exc
+
+    if json_output:
+        typer.echo(json.dumps(issues, indent=2))
+        raise typer.Exit(EXIT_OK)
+
+    if not issues:
+        typer.echo("No issues match." if (status or impact or cause) else "No issues on this project.")
+        raise typer.Exit(EXIT_OK)
+
+    for issue in 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'))}"
+        )
+    raise typer.Exit(EXIT_OK)
+
+
+@app.command()
+def show(
+    issue_id: str = typer.Argument(..., help="Id of the issue to show (from `cassis issues 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 issue as raw JSON."),
+) -> None:
+    """Show one issue: its diagnosis, suggested action, and occurrences.
+
+    Each occurrence's id feeds `cassis issues evidence`, which prints what the
+    agent saw. Exits 0 on success, 1 when the issue 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:
+        issue = get_issue(api_url=api_url, api_key=api_key, project_id=project_id, issue_id=issue_id)
+    except IssueNotFoundError as exc:
+        raise _not_found_failure(exc) from exc
+    except (AuthError, ApiError) as 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('status')}  {issue.get('impact')}  {issue.get('cause')}  "
+        f"{issue.get('occurrence_count_cache', len(occurrences))} occurrence(s)"
+    )
+    _field("Description", issue.get("description"), blank_line=True)
+    _field("Suggested action", issue.get("suggested_action"), blank_line=True)
+    typer.echo("")
+    typer.echo("Fix proposal: available (review it in Cassis)" if issue.get("fix_proposal") else "Fix proposal: none")
+    if occurrences:
+        typer.echo("")
+        typer.echo("Occurrences:")
+        for occurrence in occurrences:
+            typer.echo(f"  {occurrence.get('id')}  {_one_line(occurrence.get('symptom'))}")
+    raise typer.Exit(EXIT_OK)
+
+
+@app.command()
+def evidence(
+    issue_id: str = typer.Argument(..., help="Id of the issue (from `cassis issues list`)."),
+    occurrence_id: str = typer.Argument(..., help="Id of the occurrence (from `cassis issues show`)."),
+    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 evidence as raw JSON."),
+) -> None:
+    """Print the evidence behind one occurrence of an issue.
+
+    The evidence joined from the occurrence's source: the generated SQL and
+    its results, the agent's process log, and either the user's rating (chat)
+    or the judge's verdict (eval). Exits 0 on success, 1 when the issue or
+    occurrence 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:
+        record = get_issue_evidence(
+            api_url=api_url,
+            api_key=api_key,
+            project_id=project_id,
+            issue_id=issue_id,
+            occurrence_id=occurrence_id,
+        )
+    except IssueNotFoundError as exc:
+        raise _not_found_failure(exc) from exc
+    except (AuthError, ApiError) as exc:
+        raise _api_failure(exc) from exc
+
+    if json_output:
+        typer.echo(json.dumps(record, indent=2))
+        raise typer.Exit(EXIT_OK)
+
+    for key, value in record.items():
+        _field(key.replace("_", " ").capitalize(), value)
+    raise typer.Exit(EXIT_OK)
+
+
+def _set_status(
+    *,
+    issue_id: str,
+    status: str,
+    path: Path,
+    project_id: Optional[str],
+    api_key: Optional[str],
+    api_url: str,
+    base_path: str,
+) -> None:
+    """Post a new status for the issue and confirm it on one line."""
+    api_key = require_api_key(api_key)
+    project_id = resolve_project_id(project_id, path / Path(base_path))
+
+    try:
+        issue = post_issue_status(
+            api_url=api_url,
+            api_key=api_key,
+            project_id=project_id,
+            issue_id=issue_id,
+            status=status,
+        )
+    except IssueNotFoundError as exc:
+        raise _not_found_failure(exc) from exc
+    except (AuthError, ApiError) as 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)
+
+
+@app.command()
+def resolve(
+    issue_id: str = typer.Argument(..., help="Id of the issue to resolve (from `cassis issues 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,
+) -> None:
+    """Mark an issue resolved — the ontology change that fixes it has landed.
+
+    Exits 0 on success, 1 when the issue does not exist in the project, 2 on
+    usage errors, 3 on transport/API errors.
+    """
+    _set_status(
+        issue_id=issue_id,
+        status="resolved",
+        path=path,
+        project_id=project_id,
+        api_key=api_key,
+        api_url=api_url,
+        base_path=base_path,
+    )
+
+
+@app.command()
+def dismiss(
+    issue_id: str = typer.Argument(..., help="Id of the issue to dismiss (from `cassis issues 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,
+) -> None:
+    """Dismiss an issue — not worth acting on.
+
+    Exits 0 on success, 1 when the issue does not exist in the project, 2 on
+    usage errors, 3 on transport/API errors.
+    """
+    _set_status(
+        issue_id=issue_id,
+        status="dismissed",
+        path=path,
+        project_id=project_id,
+        api_key=api_key,
+        api_url=api_url,
+        base_path=base_path,
+    )
+
+
+@app.command()
+def reopen(
+    issue_id: str = typer.Argument(..., help="Id of the issue to reopen (from `cassis issues 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,
+) -> None:
+    """Reopen a resolved or dismissed issue.
+
+    Exits 0 on success, 1 when the issue does not exist in the project, 2 on
+    usage errors, 3 on transport/API errors.
+    """
+    _set_status(
+        issue_id=issue_id,
+        status="open",
+        path=path,
+        project_id=project_id,
+        api_key=api_key,
+        api_url=api_url,
+        base_path=base_path,
+    )

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

@@ -5,6 +5,7 @@ from __future__ import annotations
 import typer
 from cassis_cli import __version__
 from cassis_cli.eval import app as eval_app
+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
@@ -19,6 +20,7 @@ app.add_typer(ontology_app, name="ontology")
 app.add_typer(eval_app, name="eval")
 app.add_typer(schema_app, name="schema")
 app.add_typer(projects_app, name="projects")
+app.add_typer(issues_app, name="issues")
 app.command()(status)
 app.command()(verify)
 

{cassis_cli-1.4.0 → cassis_cli-1.5.0}/cassis_cli/schema.py

@@ -175,8 +175,7 @@ def push(
         envvar="CASSIS_BASE_PATH",
         help="Repository directory the ontology is exported under (the project's git-sync Path setting).",
     ),
-    wait: bool = typer.Option(True, "--wait/--no-wait", help="Wait for the detection run to complete."),
-    poll_interval: float = typer.Option(5.0, "--poll-interval", help="Seconds between polls with --wait."),
+    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:
@@ -186,9 +185,14 @@ def push(
     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). Exits 0 on
-    success, 1 on a failed detection run, 2 on usage errors, 3 on transport/API
-    errors or a --wait timeout.
+    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
+    the run rather than the upload request), so exit 0 means the schema parsed
+    AND was applied — there is no fire-and-forget mode. Exits 0 on success, 1
+    on a failed detection run, 2 on usage errors, 3 on transport/API errors or
+    a timeout.
     """
     api_key = require_api_key(api_key)
     project_id = resolve_project_id(project_id, path / base_path)
@@ -218,11 +222,6 @@ def push(
     run_id = run["run_id"]
     typer.echo(f"Detection run started: {run_id}")
 
-    if not wait:
-        if json_output:
-            typer.echo(json.dumps(run, indent=2))
-        raise typer.Exit(EXIT_OK)
-
     run = _wait_for_detection_run(
         api_url=api_url,
         api_key=api_key,

{cassis_cli-1.4.0 → cassis_cli-1.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cassis-cli"
-version = "1.4.0"
+version = "1.5.0"
 description = "Cassis CLI — run Cassis actions (ontology validation, upload and publish) from your CI pipelines"
 readme = "README.md"
 license = { text = "Apache-2.0" }

cassis_cli-1.4.0/cassis_cli/__init__.py

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