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

cassis_cli-1.4.1/README.md → cassis_cli-1.5.1/PKG-INFO

@@ -1,21 +1,44 @@
+Metadata-Version: 2.4
+Name: cassis-cli
+Version: 1.5.1
+Summary: Validate, test and evaluate your Cassis ontology from your terminal, then publish it
+License: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: cassis,ontology,cli,ci,text-to-sql
+Author: Cassis
+Author-email: tech.admin@getcassis.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Database
+Requires-Dist: httpx (>=0.24,<1.0)
+Requires-Dist: typer (>=0.12,<1.0)
+Project-URL: Documentation, https://github.com/GetCassis/cassis-cli#readme
+Project-URL: Homepage, https://getcassis.com
+Project-URL: Repository, https://github.com/GetCassis/cassis-cli
+Description-Content-Type: text/markdown
+
 # Cassis CLI
 
-Run Cassis actions from your CI pipelines:
+Validate, test and evaluate your ontology from your terminal, then publish it. The same commands gate your pull requests in CI:
 
 - `cassis ontology check` validates the ontology files in your repository with the exact same checks as the Cassis GitHub PR check (YAML parsing, round-trip, import validation) — so you can gate merges in any CI system, not just GitHub. It then prints advisory **ontology quality warnings** for a tree that parsed — tables not assigned to any domain, joins/metrics pointing at unknown tables or columns, missing table/column descriptions (the same findings `ontology test` reports, without the agent run). In a checkout bound to a project (`project.yml`, `--project`, or `CASSIS_PROJECT_ID`), it also cross-checks the tree against the project's source schema: references to tables or columns the warehouse doesn't have print as **warnings** too — advisory only (the object may simply not be built or synced yet). Warnings never fail the check.
 - `cassis schema pull` downloads the data source's full source schema (as Cassis last introspected it) into `<base-path>/.schema.json` — a **gitignored** local snapshot (the command maintains the ignore entry) with a `pulled_at` stamp. The warehouse stays authoritative; the snapshot is a cache for offline/bulk work — e.g. a coding agent grepping table and column names during a modeling pass instead of paging through the MCP `get_source_schema` tool. Re-run to refresh.
 - `cassis ontology fmt` rewrites the ontology files in canonical form (think `black`/`gofmt` for the ontology), so hand or agent edits pass the round-trip check.
 - `cassis ontology upload` uploads the ontology files to a Cassis project (full replace) and, by default, publishes them immediately as a new version — so a merge to your main branch can go live in one CI step.
-- `cassis ontology pull` downloads the project's unpublished ontology into your repository checkout (full sync — stale local ontology files are pruned), so you can start editing from the current state, or bootstrap a repo that isn't git-synced (e.g. Bitbucket).
+- `cassis ontology pull` downloads the project's unpublished ontology into your repository checkout (full sync — stale local ontology files are pruned), so you can start editing from the current state, or bootstrap a repo that isn't git-synced (e.g. Bitbucket). Pruning only deletes files that are tracked and unmodified in git (i.e. restorable with `git checkout`); untracked or locally modified files are kept and listed, and every deleted path is printed.
 - `cassis ontology pull` and `cassis ontology fmt` also write `<base-path>/AGENTS.md`, the Cassis ontology modeling guide, into the checkout (default `cassis/AGENTS.md`) — a managed file (generated banner; the CLI overwrites local edits) so a repo-aware coding agent loads current Cassis modeling doctrine by convention. It sits inside the ontology directory but is not part of the ontology tree (which is the YAML files plus the domain Markdown files `domains/**/README.md`), so it is never uploaded, validated, or pruned. Commit it alongside your ontology changes. The guide text ships inside the CLI package, so its version tracks the **installed cassis-cli version** — upgrade the CLI (`pip install -U cassis-cli`) and re-run `fmt` to pick up doctrine updates; an unpinned `pip install cassis-cli` in CI gets them automatically. The banner stamps a doctrine version, and the CLI never *downgrades* the file: if the checkout's `AGENTS.md` was written by a newer doctrine (a newer CLI, or Cassis itself on a publish), `fmt`/`pull` leave it in place, print an upgrade notice, and `fmt --check` still passes.
 - The CLI identifies itself to the API (`User-Agent: cassis-cli/<version>`), and successful API responses advertise the newest published version — when you are behind, commands print a one-line upgrade notice on stderr (purely informational; output and exit codes are unchanged).
 - `cassis eval run` runs the project's eval suite against your local ontology files (scored in-memory — nothing is pushed to Cassis) and prints per-question results, so you can test the changes on your git branch before merging.
 - `cassis ontology test` runs individual questions through the text-to-SQL agent using your local ontology files, so you can check that a change actually works (e.g. a new column gets picked) — where `eval run` only checks for regressions on existing eval cases.
 - `cassis eval add-case` adds a gold question/SQL case to the project's eval suite — after fixing an ontology issue, add the question users were failing on so `eval run` guards it from regressing.
 - `cassis eval list-cases` and `cassis eval delete-case` maintain the suite: list the current cases with their ids, and prune one that is stale or wrong (e.g. its gold SQL encodes a definition the ontology has since changed).
-- `cassis schema push` uploads a DDL file to detect source-schema changes on a DDL-only project (same as the webapp's "Update from DDL" button): Cassis diffs the DDL against the ontology and surfaces added, dropped, and changed objects in Ontology > Review > Data source for approval. Waits for completion by default; `--no-wait` returns immediately.
+- `cassis 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 +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
 
@@ -50,7 +73,8 @@ cassis ontology check
 cassis ontology check /path/to/checkout
 
 # Download the project's unpublished ontology into the checkout (full sync;
-# review with git diff — pass --no-prune to keep local files it would delete):
+# review with git diff — untracked/modified files are never deleted, and
+# --no-prune keeps even the tracked stale files it would otherwise delete):
 cassis ontology pull --project 019f0000-0000-7000-8000-000000000000
 
 # Upload the ontology to a project and publish it immediately:
@@ -100,15 +124,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 +159,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,14 +189,14 @@ 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 |
 
 Commands that send the local tree (`check`, `fmt`, `upload`, `eval run`, `test`) accept up to
-2000 ontology files / 5 MB total — far above real ontologies (a few hundred small
-files). Beyond that the CLI fails fast with exit 2 before uploading anything;
-double-check `--base-path` if you hit it.
+20,000 ontology files / 100 MB total (path + content bytes) — sized for ontologies of
+roughly 10,000 modeled tables. Beyond that the CLI fails fast with exit 2 before
+uploading anything; double-check `--base-path` if you hit it.
 
 `upload` replaces the project's entire ontology with the uploaded tree. A
 never-published project always goes live immediately on first upload (even
@@ -264,3 +298,4 @@ requires an account.
 ## License
 
 Apache License 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).
+

cassis_cli-1.4.1/PKG-INFO → cassis_cli-1.5.1/README.md

@@ -1,43 +1,22 @@
-Metadata-Version: 2.4
-Name: cassis-cli
-Version: 1.4.1
-Summary: Cassis CLI — run Cassis actions (ontology validation, upload and publish) from your CI pipelines
-License: Apache-2.0
-License-File: LICENSE
-License-File: NOTICE
-Keywords: cassis,ontology,ci,text-to-sql
-Author: Cassis
-Author-email: tech.admin@getcassis.com
-Requires-Python: >=3.10,<4.0
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: Topic :: Database
-Requires-Dist: httpx (>=0.24,<1.0)
-Requires-Dist: typer (>=0.12,<1.0)
-Project-URL: Documentation, https://github.com/GetCassis/cassis-cli#readme
-Project-URL: Homepage, https://getcassis.com
-Project-URL: Repository, https://github.com/GetCassis/cassis-cli
-Description-Content-Type: text/markdown
-
 # Cassis CLI
 
-Run Cassis actions from your CI pipelines:
+Validate, test and evaluate your ontology from your terminal, then publish it. The same commands gate your pull requests in CI:
 
 - `cassis ontology check` validates the ontology files in your repository with the exact same checks as the Cassis GitHub PR check (YAML parsing, round-trip, import validation) — so you can gate merges in any CI system, not just GitHub. It then prints advisory **ontology quality warnings** for a tree that parsed — tables not assigned to any domain, joins/metrics pointing at unknown tables or columns, missing table/column descriptions (the same findings `ontology test` reports, without the agent run). In a checkout bound to a project (`project.yml`, `--project`, or `CASSIS_PROJECT_ID`), it also cross-checks the tree against the project's source schema: references to tables or columns the warehouse doesn't have print as **warnings** too — advisory only (the object may simply not be built or synced yet). Warnings never fail the check.
 - `cassis schema pull` downloads the data source's full source schema (as Cassis last introspected it) into `<base-path>/.schema.json` — a **gitignored** local snapshot (the command maintains the ignore entry) with a `pulled_at` stamp. The warehouse stays authoritative; the snapshot is a cache for offline/bulk work — e.g. a coding agent grepping table and column names during a modeling pass instead of paging through the MCP `get_source_schema` tool. Re-run to refresh.
 - `cassis ontology fmt` rewrites the ontology files in canonical form (think `black`/`gofmt` for the ontology), so hand or agent edits pass the round-trip check.
 - `cassis ontology upload` uploads the ontology files to a Cassis project (full replace) and, by default, publishes them immediately as a new version — so a merge to your main branch can go live in one CI step.
-- `cassis ontology pull` downloads the project's unpublished ontology into your repository checkout (full sync — stale local ontology files are pruned), so you can start editing from the current state, or bootstrap a repo that isn't git-synced (e.g. Bitbucket).
+- `cassis ontology pull` downloads the project's unpublished ontology into your repository checkout (full sync — stale local ontology files are pruned), so you can start editing from the current state, or bootstrap a repo that isn't git-synced (e.g. Bitbucket). Pruning only deletes files that are tracked and unmodified in git (i.e. restorable with `git checkout`); untracked or locally modified files are kept and listed, and every deleted path is printed.
 - `cassis ontology pull` and `cassis ontology fmt` also write `<base-path>/AGENTS.md`, the Cassis ontology modeling guide, into the checkout (default `cassis/AGENTS.md`) — a managed file (generated banner; the CLI overwrites local edits) so a repo-aware coding agent loads current Cassis modeling doctrine by convention. It sits inside the ontology directory but is not part of the ontology tree (which is the YAML files plus the domain Markdown files `domains/**/README.md`), so it is never uploaded, validated, or pruned. Commit it alongside your ontology changes. The guide text ships inside the CLI package, so its version tracks the **installed cassis-cli version** — upgrade the CLI (`pip install -U cassis-cli`) and re-run `fmt` to pick up doctrine updates; an unpinned `pip install cassis-cli` in CI gets them automatically. The banner stamps a doctrine version, and the CLI never *downgrades* the file: if the checkout's `AGENTS.md` was written by a newer doctrine (a newer CLI, or Cassis itself on a publish), `fmt`/`pull` leave it in place, print an upgrade notice, and `fmt --check` still passes.
 - The CLI identifies itself to the API (`User-Agent: cassis-cli/<version>`), and successful API responses advertise the newest published version — when you are behind, commands print a one-line upgrade notice on stderr (purely informational; output and exit codes are unchanged).
 - `cassis eval run` runs the project's eval suite against your local ontology files (scored in-memory — nothing is pushed to Cassis) and prints per-question results, so you can test the changes on your git branch before merging.
 - `cassis ontology test` runs individual questions through the text-to-SQL agent using your local ontology files, so you can check that a change actually works (e.g. a new column gets picked) — where `eval run` only checks for regressions on existing eval cases.
 - `cassis eval add-case` adds a gold question/SQL case to the project's eval suite — after fixing an ontology issue, add the question users were failing on so `eval run` guards it from regressing.
 - `cassis eval list-cases` and `cassis eval delete-case` maintain the suite: list the current cases with their ids, and prune one that is stale or wrong (e.g. its gold SQL encodes a definition the ontology has since changed).
-- `cassis schema push` uploads a DDL file to detect source-schema changes on a DDL-only project (same as the webapp's "Update from DDL" button): Cassis diffs the DDL against the ontology and surfaces added, dropped, and changed objects in Ontology > Review > Data source for approval. Waits for completion by default; `--no-wait` returns immediately.
+- `cassis 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 +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
 
@@ -72,7 +51,8 @@ cassis ontology check
 cassis ontology check /path/to/checkout
 
 # Download the project's unpublished ontology into the checkout (full sync;
-# review with git diff — pass --no-prune to keep local files it would delete):
+# review with git diff — untracked/modified files are never deleted, and
+# --no-prune keeps even the tracked stale files it would otherwise delete):
 cassis ontology pull --project 019f0000-0000-7000-8000-000000000000
 
 # Upload the ontology to a project and publish it immediately:
@@ -122,15 +102,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 +137,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,14 +167,14 @@ 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 |
 
 Commands that send the local tree (`check`, `fmt`, `upload`, `eval run`, `test`) accept up to
-2000 ontology files / 5 MB total — far above real ontologies (a few hundred small
-files). Beyond that the CLI fails fast with exit 2 before uploading anything;
-double-check `--base-path` if you hit it.
+20,000 ontology files / 100 MB total (path + content bytes) — sized for ontologies of
+roughly 10,000 modeled tables. Beyond that the CLI fails fast with exit 2 before
+uploading anything; double-check `--base-path` if you hit it.
 
 `upload` replaces the project's entire ontology with the uploaded tree. A
 never-published project always goes live immediately on first upload (even
@@ -286,4 +276,3 @@ requires an account.
 ## License
 
 Apache License 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).
-

cassis_cli-1.5.1/cassis_cli/__init__.py

@@ -0,0 +1,11 @@
+"""Validate, test and evaluate your ontology from your terminal, then publish it.
+
+The same commands gate your pull requests in CI.
+"""
+
+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.1 → cassis_cli-1.5.1}/cassis_cli/api.py

@@ -618,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,

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

@@ -2,7 +2,9 @@
 
 from __future__ import annotations
 
+import os
 import re
+import subprocess
 from pathlib import Path
 from typing import Optional
 from uuid import UUID
@@ -20,10 +22,12 @@ EXIT_USAGE = 2
 EXIT_TRANSPORT = 3
 
 # Request ceilings of the /api/ci file-tree endpoints, mirrored so oversized
-# trees fail fast with a clear message before any upload. Source of truth:
+# trees fail fast with a clear message before any upload. Sized for ~10,000
+# modeled tables (a 6,000-table tree is ~8,600 files / ~60 MB). Source of
+# truth: backend/app/services/ontology_check.py, enforced by
 # backend/app/schemas/ci.py (the server's 422 remains the backstop).
-MAX_FILES = 2000
-MAX_TOTAL_BYTES = 5 * 1024 * 1024
+MAX_FILES = 20_000
+MAX_TOTAL_BYTES = 100 * 1024 * 1024
 
 
 def is_ontology_file(rel_path: str) -> bool:
@@ -41,6 +45,42 @@ def is_ontology_file(rel_path: str) -> bool:
     return rel_path.startswith("domains/") and rel_path.endswith("/README.md")
 
 
+def git_file_states(directory: Path) -> Optional[tuple[set[str], set[str]]]:
+    """(tracked, dirty) path sets for files under ``directory``, relative to it.
+
+    ``tracked`` is every git-tracked file below the directory; ``dirty`` the
+    subset whose working-tree content differs from the index (modified or
+    missing). Returns ``None`` when the directory is not inside a git work tree
+    or git is unavailable — callers must then treat every file as
+    unrecoverable and refuse to delete it.
+    """
+    # GIT_OPTIONAL_LOCKS=0: read-only queries must not take the index lock
+    # (and fail) when another git process is running.
+    env = {**os.environ, "GIT_OPTIONAL_LOCKS": "0"}
+    try:
+        tracked_proc = subprocess.run(
+            ["git", "ls-files", "-z"],
+            cwd=directory,
+            env=env,
+            capture_output=True,
+            check=True,
+            text=True,
+        )
+        dirty_proc = subprocess.run(
+            ["git", "ls-files", "-z", "--modified"],
+            cwd=directory,
+            env=env,
+            capture_output=True,
+            check=True,
+            text=True,
+        )
+    except (OSError, subprocess.CalledProcessError, UnicodeDecodeError):
+        return None
+    tracked = {p for p in tracked_proc.stdout.split("\0") if p}
+    dirty = {p for p in dirty_proc.stdout.split("\0") if p}
+    return tracked, dirty
+
+
 def is_legacy_domain_file(rel_path: str) -> bool:
     """Whether a base-relative path is a legacy (pre-Markdown) domain file.
 
@@ -84,7 +124,7 @@ def read_project_id_from_dir(ontology_dir: Path) -> Optional[str]:
     """Return the ``project_id`` recorded in ``<ontology_dir>/project.yml``, or None."""
     try:
         text = (ontology_dir / "project.yml").read_text(encoding="utf-8")
-    except (OSError, UnicodeDecodeError) as _exc:  # `as` keeps black from stripping the parens (3.14-only syntax)
+    except (OSError, UnicodeDecodeError):
         return None
     for line in text.splitlines():
         match = _PROJECT_ID_LINE.match(line.strip())
@@ -171,7 +211,9 @@ def collect_tree(path: Path, base_path: str) -> "tuple[dict[str, str], str]":
         typer.secho(f"No ontology files found under {ontology_dir}.", fg=typer.colors.RED, err=True)
         raise typer.Exit(EXIT_USAGE)
 
-    total_bytes = sum(len(content.encode()) for content in files.values())
+    # Count path bytes too, exactly like the server's _validate_tree_files —
+    # a tree accepted here must never come back as a server-side 422.
+    total_bytes = sum(len(rel.encode()) + len(content.encode()) for rel, content in files.items())
     if len(files) > MAX_FILES or total_bytes > MAX_TOTAL_BYTES:
         typer.secho(
             f"Ontology tree too large: {len(files)} files / {total_bytes / (1024 * 1024):.1f} MB "

cassis_cli-1.5.1/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.1 → cassis_cli-1.5.1}/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
@@ -13,12 +14,16 @@ from cassis_cli.verify import verify
 
 app = typer.Typer(
     no_args_is_help=True,
-    help="Cassis CLI — run Cassis actions from your CI pipelines.",
+    help=(
+        "Cassis CLI: validate, test and evaluate your ontology from your terminal, "
+        "then publish it. The same commands gate your pull requests in CI."
+    ),
 )
 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.1 → cassis_cli-1.5.1}/cassis_cli/ontology.py

@@ -28,6 +28,7 @@ from cassis_cli.common import (
 )
 from cassis_cli.common import collect_files as _collect_files
 from cassis_cli.common import collect_tree as _collect_tree
+from cassis_cli.common import git_file_states as _git_file_states
 from cassis_cli.common import is_legacy_domain_file as _is_legacy_domain_file
 from cassis_cli.common import require_api_key as _require_api_key
 from cassis_cli.common import resolve_project_id as _resolve_project_id
@@ -197,7 +198,11 @@ def pull(
     prune: bool = typer.Option(
         True,
         "--prune/--no-prune",
-        help="Delete local ontology files that no longer exist in the project's ontology (default: prune).",
+        help=(
+            "Delete local ontology files that no longer exist in the project's ontology "
+            "(default: prune). Only files that are tracked and unmodified in git are "
+            "deleted; untracked or locally modified files are always kept and reported."
+        ),
     ),
     json_output: bool = typer.Option(False, "--json", help="Print a JSON summary of written/deleted files."),
 ) -> None:
@@ -205,7 +210,9 @@ def pull(
 
     Writes the ontology tree under the export path (full sync: files are
     overwritten and, unless --no-prune, stale local ontology files are deleted,
-    so the checkout ends up matching the project exactly). Review the changes with
+    so the checkout ends up matching the project exactly). Pruning never touches
+    files git could not restore: untracked or locally modified files are kept
+    and listed, and every deleted path is named. Review the changes with
     git diff before committing. Exits 0 on success, 2 on usage errors, 3 on
     transport/API errors.
     """
@@ -243,15 +250,38 @@ def pull(
         written.append(rel)
 
     deleted: list[str] = []
+    kept: list[dict[str, str]] = []
     if prune and ontology_dir.is_dir():
         local = _collect_files(ontology_dir)
-        for rel in sorted(set(local) - set(files)):
-            try:
-                (ontology_dir / rel).unlink()
-            except OSError as exc:
-                typer.secho(f"Cannot delete {ontology_dir / rel}: {exc}", fg=typer.colors.RED, err=True)
-                raise typer.Exit(EXIT_USAGE) from exc
-            deleted.append(rel)
+        stale = sorted(set(local) - set(files))
+        if stale:
+            # Only delete what git can restore. An untracked or locally
+            # modified file is user work Cassis has never seen — pruning it
+            # would be unrecoverable data loss (#27).
+            states = _git_file_states(ontology_dir)
+            to_delete: list[str] = []
+            if states is None:
+                kept = [{"path": rel, "reason": "not in a git repository"} for rel in stale]
+            else:
+                tracked, dirty = states
+                for rel in stale:
+                    if rel not in tracked:
+                        kept.append({"path": rel, "reason": "untracked in git"})
+                    elif rel in dirty:
+                        kept.append({"path": rel, "reason": "locally modified"})
+                    else:
+                        to_delete.append(rel)
+            if to_delete and not json_output:
+                typer.echo(f"Deleting {len(to_delete)} stale ontology file(s):")
+                for rel in to_delete:
+                    typer.echo(f"  {base_path}/{rel}")
+            for rel in to_delete:
+                try:
+                    (ontology_dir / rel).unlink()
+                except OSError as exc:
+                    typer.secho(f"Cannot delete {ontology_dir / rel}: {exc}", fg=typer.colors.RED, err=True)
+                    raise typer.Exit(EXIT_USAGE) from exc
+                deleted.append(rel)
 
     # Managed modeling guide: refresh AGENTS.md so a repo-aware agent loads
     # current Cassis doctrine. Not part of the ontology tree (YAML-only), so it
@@ -266,14 +296,31 @@ def pull(
         _warn_newer_guide(base_path)
 
     if json_output:
-        typer.echo(json.dumps({"written": written, "deleted": deleted, "guide_written": guide_written}, indent=2))
+        typer.echo(
+            json.dumps(
+                {"written": written, "deleted": deleted, "kept": kept, "guide_written": guide_written},
+                indent=2,
+            )
+        )
     else:
         summary = f"✓ Pulled {len(written)} files into {ontology_dir}"
         if deleted:
-            summary += f" ({len(deleted)} stale files deleted)"
+            summary += f" ({len(deleted)} stale files deleted, listed above)"
         if guide_written:
             summary += f"; wrote {base_path}/{GUIDE_FILENAME}"
         typer.secho(f"{summary}.", fg=typer.colors.GREEN)
+        if kept:
+            typer.secho(
+                f"Kept {len(kept)} local file(s) not in the project ontology "
+                "(only files tracked and unmodified in git are pruned):",
+                fg=typer.colors.YELLOW,
+            )
+            for entry in kept:
+                typer.secho(f"  {base_path}/{entry['path']} ({entry['reason']})", fg=typer.colors.YELLOW)
+            typer.secho(
+                "  Commit them if they are intentional, or delete them manually.",
+                fg=typer.colors.YELLOW,
+            )
         migrated = sum(1 for rel in deleted if _is_legacy_domain_file(rel))
         if migrated:
             typer.secho(

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

@@ -134,7 +134,7 @@ def ensure_gitignored(ontology_dir: Path) -> None:
     gitignore = ontology_dir / ".gitignore"
     try:
         existing = gitignore.read_text(encoding="utf-8")
-    except (OSError, UnicodeDecodeError) as _exc:  # `as` keeps black from stripping the parens (3.14-only syntax)
+    except (OSError, UnicodeDecodeError):
         existing = ""
     if SNAPSHOT_FILENAME in existing.splitlines():
         return
@@ -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.1 → cassis_cli-1.5.1}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "cassis-cli"
-version = "1.4.1"
-description = "Cassis CLI — run Cassis actions (ontology validation, upload and publish) from your CI pipelines"
+version = "1.5.1"
+description = "Validate, test and evaluate your Cassis ontology from your terminal, then publish it"
 readme = "README.md"
 license = { text = "Apache-2.0" }
 authors = [{ name = "Cassis", email = "tech.admin@getcassis.com" }]
-keywords = ["cassis", "ontology", "ci", "text-to-sql"]
+keywords = ["cassis", "ontology", "cli", "ci", "text-to-sql"]
 classifiers = [
     "License :: OSI Approved :: Apache Software License",
     "Environment :: Console",
@@ -43,3 +43,10 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+
+[tool.black]
+# The package ships for Python >=3.10 (see requires-python above): formatting
+# must target the floor, or black under the monorepo's 3.14 rewrites syntax
+# into 3.14-only forms (e.g. stripping parens from multi-exception `except`).
+line-length = 120
+target-version = ["py310"]

cassis_cli-1.4.1/cassis_cli/__init__.py

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