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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cassis-cli
-Version: 1.7.0
+Version: 2.0.0
 Summary: Validate, test and evaluate your Cassis ontology from your terminal, then publish it
 License: Apache-2.0
 License-File: LICENSE
@@ -35,11 +35,10 @@ Validate, test and evaluate your ontology from your terminal, then publish it. T
 - `cassis ontology test` runs individual questions through the text-to-SQL agent using your local ontology files, so you can check that a change actually works (e.g. a new column gets picked) — where `eval run` only checks for regressions on existing eval cases.
 - `cassis eval add-case` adds a gold question/SQL case to the project's eval suite — after fixing an ontology issue, add the question users were failing on so `eval run` guards it from regressing.
 - `cassis eval list-cases` and `cassis eval delete-case` maintain the suite: list the current cases with their ids, and prune one that is stale or wrong (e.g. its gold SQL encodes a definition the ontology has since changed).
-- `cassis schema push` uploads a DDL file to detect source-schema changes on a DDL-only project (same as the webapp's "Update from DDL" button): Cassis diffs the DDL against the ontology and surfaces added, dropped, and changed objects in Ontology > Review > Data source for approval. The file speaks only for the schemas it contains — a partial export (one schema of many) never removes the others; pass `--complete` when it is the project's complete source schema so schemas absent from it are treated as dropped. Waits for the detection run to finish and exits 0 only when it completed — the schema is stored and applied atomically with run completion, so exit 0 means the DDL parsed and the project now uses it.
+- `cassis schema plan <ddl>` (or `--warehouse` on a project connected to a warehouse) previews what a schema update would change before anything is applied: the source schema diff, the ontology changes Cassis will make (every change on a table placed in the ontology, with everything a drop takes with it) and warnings, terraform-style. `cassis schema apply <ddl>` (or `--plan <id>`) writes the resulting ontology files into the local checkout, app untouched, for review with `git diff`. `cassis schema push <ddl> [--publish]` pushes the new schema and the local ontology to the app (`--yes` in CI). The file speaks only for the schemas it contains — pass `--complete` when it is the project's complete source schema so schemas absent from it are treated as dropped. With `--warehouse` the server introspects the connected warehouse instead of parsing a file; the plan is always whole-source.
 - `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, how many Data source review items are pending (with the breaking count, when there are any), and how your local git HEAD relates to the published commit (in sync / N commits ahead / diverged). `cassis status --watch` polls until the published commit matches your local HEAD — e.g. right after merging a PR whose CI publishes the ontology — instead of watching the GitHub Actions tab.
+- `cassis status` shows the project's published version (number, label, git commit), whether unpublished changes await publication, the git-sync binding, a schema plan waiting to be applied, and how your local git HEAD relates to the published commit (in sync / N commits ahead / diverged). `cassis status --watch` polls until the published commit matches your local HEAD — e.g. right after merging a PR whose CI publishes the ontology — instead of watching the GitHub Actions tab.
 - `cassis issues` triages the issues Cassis raised on the project — what it found wrong while answering questions (an ontology gap, missing data) — without leaving the checkout: `issues list` (filterable by status, impact and cause), `issues show <id>` for the diagnosis, suggested action and the occurrences behind it, `issues evidence <id> <occurrence-id>` for what the agent actually saw, and `issues resolve` / `dismiss` / `reopen` once you've acted on it.
-- `cassis source-changes` reads the project's Data source review queue — the schema drift Cassis detected between the source and what the ontology tracks: `source-changes list` (paginated, pending by default, breaking severity flagged) and `source-changes show <id>` for one change's impact references and suggested edit. Read-only: approving or dismissing stays in the webapp; fix headlessly by editing the ontology files and opening a pull request.
 - `cassis verify` runs the full local gate in one verb — `ontology fmt --check`, `ontology check`, `eval run` — stopping at the first failure. One command in a checkout ("is this change safe to merge?"), one job in CI. `--no-eval` skips the eval suite.
 
 ## Install
@@ -125,9 +124,11 @@ 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);
-# exits 0 only once the run completed and the schema is applied:
-cassis schema push schema.sql
+# Preview, apply locally and push a schema update from a DDL file (DDL-only projects):
+cassis schema plan schema.sql --complete
+cassis schema apply schema.sql --complete      # writes cassis/ locally
+cassis schema push schema.sql --complete --yes  # schema + ontology to the app
+cassis schema plan --warehouse                   # warehouse-connected projects: introspect instead
 
 # List the projects the API key can reach (id, name, published version, dialect):
 cassis projects list
@@ -195,7 +196,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; issues: no such issue or occurrence in the project; issues analyze: failed or cancelled analysis run; schema push: failed or cancelled detection run, or the project won't accept the push (a run is already in flight, or it is warehouse-connected rather than DDL-only); source-changes show: no such change in the project) |
+| 1    | Validation failed (check: findings printed; upload: nothing imported; eval run: invalid tree, failed cases, or failed/cancelled run; test: invalid tree or a probe failed; add-case: duplicate question or gold SQL that does not run; delete-case: no such case in the project; issues: no such issue or occurrence in the project; issues analyze: failed or cancelled analysis run; schema plan/apply: the plan failed (unparseable or truncated DDL), is stale or expired, the apply failed, or the project won't accept it (a plan is being applied, a DDL was given for a warehouse-connected project, or --warehouse for a DDL-only one)) |
 | 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 eval run or issue analysis already active, out of credits, or `--timeout` reached |
 

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

@@ -13,11 +13,10 @@ Validate, test and evaluate your ontology from your terminal, then publish it. T
 - `cassis ontology test` runs individual questions through the text-to-SQL agent using your local ontology files, so you can check that a change actually works (e.g. a new column gets picked) — where `eval run` only checks for regressions on existing eval cases.
 - `cassis eval add-case` adds a gold question/SQL case to the project's eval suite — after fixing an ontology issue, add the question users were failing on so `eval run` guards it from regressing.
 - `cassis eval list-cases` and `cassis eval delete-case` maintain the suite: list the current cases with their ids, and prune one that is stale or wrong (e.g. its gold SQL encodes a definition the ontology has since changed).
-- `cassis schema push` uploads a DDL file to detect source-schema changes on a DDL-only project (same as the webapp's "Update from DDL" button): Cassis diffs the DDL against the ontology and surfaces added, dropped, and changed objects in Ontology > Review > Data source for approval. The file speaks only for the schemas it contains — a partial export (one schema of many) never removes the others; pass `--complete` when it is the project's complete source schema so schemas absent from it are treated as dropped. Waits for the detection run to finish and exits 0 only when it completed — the schema is stored and applied atomically with run completion, so exit 0 means the DDL parsed and the project now uses it.
+- `cassis schema plan <ddl>` (or `--warehouse` on a project connected to a warehouse) previews what a schema update would change before anything is applied: the source schema diff, the ontology changes Cassis will make (every change on a table placed in the ontology, with everything a drop takes with it) and warnings, terraform-style. `cassis schema apply <ddl>` (or `--plan <id>`) writes the resulting ontology files into the local checkout, app untouched, for review with `git diff`. `cassis schema push <ddl> [--publish]` pushes the new schema and the local ontology to the app (`--yes` in CI). The file speaks only for the schemas it contains — pass `--complete` when it is the project's complete source schema so schemas absent from it are treated as dropped. With `--warehouse` the server introspects the connected warehouse instead of parsing a file; the plan is always whole-source.
 - `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, how many Data source review items are pending (with the breaking count, when there are any), and how your local git HEAD relates to the published commit (in sync / N commits ahead / diverged). `cassis status --watch` polls until the published commit matches your local HEAD — e.g. right after merging a PR whose CI publishes the ontology — instead of watching the GitHub Actions tab.
+- `cassis status` shows the project's published version (number, label, git commit), whether unpublished changes await publication, the git-sync binding, a schema plan waiting to be applied, and how your local git HEAD relates to the published commit (in sync / N commits ahead / diverged). `cassis status --watch` polls until the published commit matches your local HEAD — e.g. right after merging a PR whose CI publishes the ontology — instead of watching the GitHub Actions tab.
 - `cassis issues` triages the issues Cassis raised on the project — what it found wrong while answering questions (an ontology gap, missing data) — without leaving the checkout: `issues list` (filterable by status, impact and cause), `issues show <id>` for the diagnosis, suggested action and the occurrences behind it, `issues evidence <id> <occurrence-id>` for what the agent actually saw, and `issues resolve` / `dismiss` / `reopen` once you've acted on it.
-- `cassis source-changes` reads the project's Data source review queue — the schema drift Cassis detected between the source and what the ontology tracks: `source-changes list` (paginated, pending by default, breaking severity flagged) and `source-changes show <id>` for one change's impact references and suggested edit. Read-only: approving or dismissing stays in the webapp; fix headlessly by editing the ontology files and opening a pull request.
 - `cassis verify` runs the full local gate in one verb — `ontology fmt --check`, `ontology check`, `eval run` — stopping at the first failure. One command in a checkout ("is this change safe to merge?"), one job in CI. `--no-eval` skips the eval suite.
 
 ## Install
@@ -103,9 +102,11 @@ 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);
-# exits 0 only once the run completed and the schema is applied:
-cassis schema push schema.sql
+# Preview, apply locally and push a schema update from a DDL file (DDL-only projects):
+cassis schema plan schema.sql --complete
+cassis schema apply schema.sql --complete      # writes cassis/ locally
+cassis schema push schema.sql --complete --yes  # schema + ontology to the app
+cassis schema plan --warehouse                   # warehouse-connected projects: introspect instead
 
 # List the projects the API key can reach (id, name, published version, dialect):
 cassis projects list
@@ -173,7 +174,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; issues: no such issue or occurrence in the project; issues analyze: failed or cancelled analysis run; schema push: failed or cancelled detection run, or the project won't accept the push (a run is already in flight, or it is warehouse-connected rather than DDL-only); source-changes show: no such change in the project) |
+| 1    | Validation failed (check: findings printed; upload: nothing imported; eval run: invalid tree, failed cases, or failed/cancelled run; test: invalid tree or a probe failed; add-case: duplicate question or gold SQL that does not run; delete-case: no such case in the project; issues: no such issue or occurrence in the project; issues analyze: failed or cancelled analysis run; schema plan/apply: the plan failed (unparseable or truncated DDL), is stale or expired, the apply failed, or the project won't accept it (a plan is being applied, a DDL was given for a warehouse-connected project, or --warehouse for a DDL-only one)) |
 | 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 eval run or issue analysis already active, out of credits, or `--timeout` reached |
 

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

@@ -353,11 +353,57 @@ def get_schema_export(
     return result
 
 
-class SourceChangeConflictError(ApiError):
-    """A concurrent detection run is already active, or the project has a connected data source."""
+class SchemaPlanConflictError(ApiError):
+    """409 from the schema-plan routes: a plan is already active, the project is connected, the plan is stale / expired / not ready."""
 
 
-def post_detect_from_ddl(
+class SchemaPlanNotFoundError(ApiError):
+    """404 with the server's exact detail `"Schema plan not found"` (a project-scope 404 is a different error)."""
+
+
+class ServerTooOldError(ApiError):
+    """The server has no schema-plan routes (bare FastAPI 404): upgrade the server first."""
+
+
+_SCHEMA_PLAN_NOT_FOUND = "Schema plan not found"
+
+
+def _raise_for_schema_plan_status(response: httpx.Response) -> None:
+    """Map the schema-plan routes' error statuses to the CLI's exceptions; return on 2xx.
+
+    One ladder for every plan route (start, read, apply, checkout): the 409
+    conflict and the exact-detail 404 are wire contracts cassis-cli matches.
+    A bare FastAPI 404 means the server predates schema plans altogether.
+    """
+    if response.status_code == 401:
+        raise AuthError("The Cassis API rejected the API key (invalid or expired).")
+    if response.status_code == 409:
+        raise SchemaPlanConflictError(str(_detail_or_text(response)))
+    if response.status_code == 404:
+        detail = _detail_or_text(response)
+        if detail == _SCHEMA_PLAN_NOT_FOUND:
+            raise SchemaPlanNotFoundError(_SCHEMA_PLAN_NOT_FOUND)
+        if detail == "Not Found":
+            raise ServerTooOldError(
+                "This Cassis server has no schema plans yet: upgrade the server first, "
+                "or pin cassis-cli<2.0 to keep the previous `schema push`."
+            )
+        raise _project_scope_error(response)
+    if response.status_code == 403:
+        raise _project_scope_error(response)
+    if response.status_code >= 400:
+        raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
+
+
+def _schema_plan_response(response: httpx.Response, url: str) -> dict[str, Any]:
+    _raise_for_schema_plan_status(response)
+    result = _parse_json_response(response, url)
+    if not isinstance(result, dict) or "id" not in result or "status" not in result:
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result
+
+
+def post_schema_plan(
     *,
     api_url: str,
     api_key: str,
@@ -366,10 +412,10 @@ def post_detect_from_ddl(
     complete_source: bool = False,
     transport: Optional[httpx.BaseTransport] = None,
 ) -> dict[str, Any]:
-    """POST /api/ci/projects/{project_id}/source-changes/detect-from-ddl and return the run record."""
-    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/source-changes/detect-from-ddl"
+    """POST /api/ci/projects/{project_id}/schema/plans and return the PLANNING plan record."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/schema/plans"
     try:
-        with _client(transport=transport) as client:
+        with _client(timeout=ONTOLOGY_TREE_TIMEOUT_SECONDS, transport=transport) as client:
             response = client.post(
                 url,
                 json={"ddl": ddl, "complete_source": complete_source},
@@ -377,49 +423,88 @@ def post_detect_from_ddl(
             )
     except httpx.HTTPError as exc:
         raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
+    return _schema_plan_response(response, url)
 
-    if response.status_code == 401:
-        raise AuthError("The Cassis API rejected the API key (invalid or expired).")
-    if response.status_code == 409:
-        raise SourceChangeConflictError(str(_detail_or_text(response)))
-    if response.status_code in (403, 404):
-        raise _project_scope_error(response)
-    if response.status_code >= 400:
-        raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
-    result = _parse_json_response(response, url)
-    if not isinstance(result, dict) or "run_id" not in result:
-        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
-    return result
 
+def post_schema_plan_warehouse(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """POST /api/ci/projects/{project_id}/schema/plans/warehouse and return the PLANNING plan record.
 
-def get_source_change_run(
+    The server introspects the project's connected warehouse instead of parsing
+    a DDL; the plan is always whole-source.
+    """
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/schema/plans/warehouse"
+    try:
+        with _client(transport=transport) as client:
+            response = client.post(url, headers={"Authorization": f"Bearer {api_key}"})
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
+    return _schema_plan_response(response, url)
+
+
+def get_schema_plan(
     *,
     api_url: str,
     api_key: str,
     project_id: str,
-    run_id: str,
+    plan_id: str,
     transport: Optional[httpx.BaseTransport] = None,
 ) -> dict[str, Any]:
-    """GET /api/ci/projects/{project_id}/source-changes/runs/{run_id} and return the run record."""
-    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/source-changes/runs/{run_id}"
+    """GET /api/ci/projects/{project_id}/schema/plans/{plan_id} and return the plan record."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/schema/plans/{plan_id}"
     try:
         with _client(transport=transport) as client:
             response = client.get(url, headers={"Authorization": f"Bearer {api_key}"})
     except httpx.HTTPError as exc:
         raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
+    return _schema_plan_response(response, url)
 
-    if response.status_code == 401:
-        raise AuthError("The Cassis API rejected the API key (invalid or expired).")
-    if response.status_code in (403, 404):
-        raise _project_scope_error(response)
-    if response.status_code >= 400:
-        raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
+
+def get_schema_plan_checkout(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    plan_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """GET /api/ci/projects/{project_id}/schema/plans/{plan_id}/checkout: the post-apply ontology tree."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/schema/plans/{plan_id}/checkout"
+    try:
+        with _client(timeout=ONTOLOGY_TREE_TIMEOUT_SECONDS, transport=transport) as client:
+            response = client.get(url, headers={"Authorization": f"Bearer {api_key}"})
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
+    _raise_for_schema_plan_status(response)
     result = _parse_json_response(response, url)
-    if not isinstance(result, dict) or "run_id" not in result:
+    if not isinstance(result, dict) or not isinstance(result.get("files"), dict):
         raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
     return result
 
 
+def post_schema_plan_apply(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    plan_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """POST /api/ci/projects/{project_id}/schema/plans/{plan_id}/apply and return the APPLYING plan record."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/schema/plans/{plan_id}/apply"
+    try:
+        with _client(transport=transport) as client:
+            response = client.post(url, headers={"Authorization": f"Bearer {api_key}"})
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
+    return _schema_plan_response(response, url)
+
+
 def post_eval_run_start(
     *,
     api_url: str,
@@ -771,80 +856,6 @@ def post_issue_status(
     return result
 
 
-class SourceChangeNotFoundError(ApiError):
-    """The project has no source change with this id."""
-
-
-def get_source_changes(
-    *,
-    api_url: str,
-    api_key: str,
-    project_id: str,
-    status: Optional[str] = None,
-    limit: Optional[int] = None,
-    offset: Optional[int] = None,
-    transport: Optional[httpx.BaseTransport] = None,
-) -> dict[str, Any]:
-    """GET /api/ci/projects/{project_id}/source-changes and return the {items, total} page."""
-    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/source-changes"
-    params: dict[str, str] = {}
-    if status:
-        params["status"] = status
-    if limit is not None:
-        params["limit"] = str(limit)
-    if offset is not None:
-        params["offset"] = str(offset)
-    try:
-        with _client(transport=transport) as client:
-            response = client.get(url, params=params or None, headers={"Authorization": f"Bearer {api_key}"})
-    except httpx.HTTPError as exc:
-        raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
-
-    if response.status_code == 401:
-        raise AuthError("The Cassis API rejected the API key (invalid or expired).")
-    if response.status_code in (403, 404):
-        raise _project_scope_error(response)
-    if response.status_code >= 400:
-        raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
-    result = _parse_json_response(response, url)
-    if not isinstance(result, dict) or not isinstance(result.get("items"), list) or "total" not in result:
-        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
-    return result
-
-
-def get_source_change(
-    *,
-    api_url: str,
-    api_key: str,
-    project_id: str,
-    change_id: str,
-    transport: Optional[httpx.BaseTransport] = None,
-) -> dict[str, Any]:
-    """GET /api/ci/projects/{project_id}/source-changes/{change_id} and return the full change."""
-    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/source-changes/{change_id}"
-    try:
-        with _client(transport=transport) as client:
-            response = client.get(url, headers={"Authorization": f"Bearer {api_key}"})
-    except httpx.HTTPError as exc:
-        raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
-
-    if response.status_code == 401:
-        raise AuthError("The Cassis API rejected the API key (invalid or expired).")
-    # Exact-match wire contract with the source-change endpoints' 404 detail
-    # (see backend/app/endpoints/ci.py): it distinguishes a missing change
-    # (exit 1) from a project-scope 404 (exit 3).
-    if response.status_code == 404 and _detail_or_text(response) == "Source change not found":
-        raise SourceChangeNotFoundError(f"No source change {change_id} in project {project_id}.")
-    if response.status_code in (403, 404):
-        raise _project_scope_error(response)
-    if response.status_code >= 400:
-        raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
-    result = _parse_json_response(response, url)
-    if not isinstance(result, dict) or "id" not in result:
-        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
-    return result
-
-
 def post_ontology_fmt(
     *,
     api_url: str,

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

@@ -5,11 +5,13 @@ from __future__ import annotations
 import os
 import re
 import subprocess
+import time
 from pathlib import Path
-from typing import Optional
+from typing import Callable, Optional, TypeVar
 from uuid import UUID
 
 import typer
+from cassis_cli.api import ApiError, AuthError
 
 # Repository directory the ontology tree is exported under. Must match the
 # project's git-sync "Path" setting in Cassis (default "cassis").
@@ -31,6 +33,15 @@ EXIT_INTERRUPTED = 130
 # backend/app/schemas/ci.py (the server's 422 remains the backstop).
 MAX_FILES = 20_000
 MAX_TOTAL_BYTES = 100 * 1024 * 1024
+# Mirrors the server's DDL upload ceiling (backend/app/endpoints/uploads.py).
+MAX_DDL_BYTES = 10 * 1024 * 1024
+
+# Consecutive poll failures tolerated before a wait gives up: covers transient
+# blips (LB hiccup, brief network loss) without letting a permanently broken
+# poll (deleted run/project) spin until --timeout.
+MAX_CONSECUTIVE_POLL_FAILURES = 5
+
+T = TypeVar("T")
 
 
 def api_failure(exc: Exception) -> "typer.Exit":
@@ -95,6 +106,151 @@ def git_file_states(directory: Path) -> Optional[tuple[set[str], set[str]]]:
     return tracked, dirty
 
 
+def sync_ontology_tree(
+    ontology_dir: Path,
+    files: "dict[str, str]",
+    *,
+    prune: bool = True,
+    skip_unchanged: bool = False,
+    before_delete: "Optional[Callable[[list[str]], None]]" = None,
+) -> "tuple[list[str], list[str], list[dict[str, str]]]":
+    """Write a server-rendered ontology tree under ``ontology_dir``; prune what git can restore.
+
+    The write/prune contract shared by ``ontology pull`` and ``schema apply``.
+    Returns ``(written, deleted, kept)``: ``written`` lists every file written
+    (with ``skip_unchanged``, only those whose content actually changed),
+    ``deleted`` the stale ontology files removed, ``kept`` the stale files left
+    in place as ``{"path", "reason"}`` entries. ``before_delete`` is called with
+    the paths about to be deleted, when there are any, so a command can announce
+    them first.
+
+    The server controls the paths: anything escaping ``ontology_dir`` exits 3
+    rather than being trusted. A file that cannot be written or deleted exits 2
+    (a local checkout problem: permissions, dir/file collision). Pruning only
+    ever deletes a stale file that is tracked and unmodified in git: an
+    untracked or locally modified file is user work Cassis has never seen, and
+    outside a git work tree nothing is deleted at all (#27).
+    """
+    ontology_dir = ontology_dir.resolve()
+    written: list[str] = []
+    for rel, content in sorted(files.items()):
+        dest = (ontology_dir / rel).resolve()
+        if not dest.is_relative_to(ontology_dir):
+            typer.secho(f"Refusing to write outside {ontology_dir}: {rel!r}", fg=typer.colors.RED, err=True)
+            raise typer.Exit(EXIT_TRANSPORT)
+        try:
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            if skip_unchanged and dest.exists() and dest.read_text(encoding="utf-8") == content:
+                continue
+            dest.write_text(content, encoding="utf-8")
+        except OSError as exc:
+            typer.secho(f"Cannot write {dest}: {exc}", fg=typer.colors.RED, err=True)
+            raise typer.Exit(EXIT_USAGE) from exc
+        written.append(rel)
+
+    deleted: list[str] = []
+    kept: list[dict[str, str]] = []
+    if prune and ontology_dir.is_dir():
+        stale = sorted(set(collect_files(ontology_dir)) - set(files))
+        if stale:
+            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 before_delete is not None:
+                before_delete(to_delete)
+            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)
+    return written, deleted, kept
+
+
+def _echo_error(exc: Exception) -> None:
+    typer.secho(str(exc), fg=typer.colors.RED, err=True)
+
+
+def echo_poll_retry(exc: ApiError) -> None:
+    """The standard "(poll failed, retrying: ...)" notice, for ``poll_until(on_retry=...)``."""
+    typer.secho(f"(poll failed, retrying: {exc})", fg=typer.colors.YELLOW, err=True)
+
+
+def poll_until(
+    fetch: "Callable[[], T]",
+    is_terminal: "Callable[[T], bool]",
+    *,
+    poll_interval: float,
+    timeout: float,
+    on_timeout: "Callable[[T], None]",
+    max_consecutive_failures: int = MAX_CONSECUTIVE_POLL_FAILURES,
+    on_progress: "Optional[Callable[[T], None]]" = None,
+    on_auth_error: "Optional[Callable[[AuthError], None]]" = None,
+    on_retry: "Optional[Callable[[ApiError], None]]" = None,
+    on_give_up: "Optional[Callable[[ApiError, int], None]]" = None,
+) -> T:
+    """Call ``fetch`` every ``poll_interval`` seconds until ``is_terminal`` accepts what it returned.
+
+    The one wait loop behind every ``--wait``: the record is fetched at least
+    once (so ``--timeout 0`` means "poll once"), ``on_progress`` sees every
+    record fetched, and the terminal record is returned. Exits 3 (transport),
+    after the matching callback has printed its message, when:
+
+    - the deadline passes while the record is still not terminal
+      (``on_timeout`` gets the last record);
+    - ``fetch`` raises ``AuthError`` (fail fast: retrying a revoked key can't
+      succeed; ``on_auth_error``, default: the error text);
+    - ``fetch`` raises ``ApiError`` ``max_consecutive_failures`` times in a row
+      (``on_give_up``, default: the error text). Each tolerated failure is
+      reported through ``on_retry`` (default: silent) and the wait continues,
+      so a transient blip never abandons a multi-minute run.
+
+    Anything else ``fetch`` raises, ``typer.Exit`` and ``KeyboardInterrupt``
+    included, propagates untouched: the caller decides whether to cancel the
+    server-side run on Ctrl-C.
+    """
+    deadline = time.monotonic() + timeout
+    failures = 0
+    while True:
+        try:
+            record = fetch()
+        except AuthError as exc:
+            (on_auth_error or _echo_error)(exc)
+            raise typer.Exit(EXIT_TRANSPORT) from exc
+        except ApiError as exc:
+            failures += 1
+            if failures >= max_consecutive_failures:
+                if on_give_up is not None:
+                    on_give_up(exc, failures)
+                else:
+                    _echo_error(exc)
+                raise typer.Exit(EXIT_TRANSPORT) from exc
+            if on_retry is not None:
+                on_retry(exc)
+            time.sleep(poll_interval)
+            continue
+        failures = 0
+        if on_progress is not None:
+            on_progress(record)
+        if is_terminal(record):
+            return record
+        if time.monotonic() >= deadline:
+            on_timeout(record)
+            raise typer.Exit(EXIT_TRANSPORT)
+        time.sleep(poll_interval)
+
+
 def is_legacy_domain_file(rel_path: str) -> bool:
     """Whether a base-relative path is a legacy (pre-Markdown) domain file.