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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cassis-cli
-Version: 1.2.0
+Version: 1.3.0
 Summary: Cassis CLI — run Cassis actions (ontology validation, upload and publish) from your CI pipelines
 License: Apache-2.0
 License-File: LICENSE
@@ -35,6 +35,10 @@ Run Cassis actions from your CI pipelines:
 - `cassis ontology test` runs individual questions through the text-to-SQL agent using your local ontology files, so you can check that a change actually works (e.g. a new column gets picked) — where `eval run` only checks for regressions on existing eval cases.
 - `cassis eval add-case` adds a gold question/SQL case to the project's eval suite — after fixing an ontology issue, add the question users were failing on so `eval run` guards it from regressing.
 - `cassis eval list-cases` and `cassis eval delete-case` maintain the suite: list the current cases with their ids, and prune one that is stale or wrong (e.g. its gold SQL encodes a definition the ontology has since changed).
+- `cassis schema push` uploads a DDL file to detect source-schema changes on a DDL-only project (same as the webapp's "Update from DDL" button): Cassis diffs the DDL against the ontology and surfaces added, dropped, and changed objects in Ontology > Review > Data source for approval. Waits for completion by default; `--no-wait` returns immediately.
+- `cassis projects list` lists the projects your API key can reach — id (what `--project` and `CASSIS_PROJECT_ID` take), name, published ontology version, and data-source dialect — so a pipeline or agent can discover the project id from the terminal instead of fishing it out of a webapp URL.
+- `cassis status` shows the project's published version (number, label, git commit), whether unpublished changes await publication, the git-sync binding, and how your local git HEAD relates to the published commit (in sync / N commits ahead / diverged). `cassis status --watch` polls until the published commit matches your local HEAD — e.g. right after merging a PR whose CI publishes the ontology — instead of watching the GitHub Actions tab.
+- `cassis verify` runs the full local gate in one verb — `ontology fmt --check`, `ontology check`, `eval run` — stopping at the first failure. One command in a checkout ("is this change safe to merge?"), one job in CI. `--no-eval` skips the eval suite.
 
 ## Install
 
@@ -56,7 +60,7 @@ The ontology tree under `<base-path>` (default `cassis/`) is:
 
 1. Create an API key in Cassis under **Organization settings → API keys** (keys start with `sk-k6-`).
 2. Store it as a CI secret and expose it as `CASSIS_API_KEY`.
-3. For `pull`, `upload`, `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 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`, and the `eval` case commands (`add-case`, `list-cases`, `delete-case`): the project ID (UUID) is taken from `<base-path>/project.yml` in the checkout (written by `pull` and by publishing) — so once a repo is pulled you don't need to pass it. To override, or before the first pull, set `CASSIS_PROJECT_ID` or pass `--project` (find the UUID with `cassis projects list`, or in the project's URL). `ontology check` uses the same resolution but treats it as optional: unbound checkouts get the project-less validation (no schema reference warnings).
 
 ## Usage
 
@@ -93,6 +97,9 @@ cassis eval run --project ...
 # Run against an existing Cassis ontology branch, or the unpublished ontology:
 cassis eval run --project ... --branch feature-x
 
+# Run only specific cases (repeatable) — e.g. prove a fresh add-case in seconds:
+cassis eval run --project ... --case 019f0000-0000-7000-8000-0000000000ca
+
 # Start the run and return immediately (poll in the webapp):
 cassis eval run --project ... --no-wait
 
@@ -104,12 +111,33 @@ cassis ontology test --project ... -q "How much was refunded last month?" -q "Ne
 cassis eval add-case --project ... -q "How much was refunded last month?" \
   --gold-sql "SELECT SUM(refunded_cents) / 100.0 FROM public.orders WHERE ..."
 
+# Multi-line gold SQL: read it from a file instead (no shell quoting pitfalls):
+cassis eval add-case --project ... -q "How much was refunded last month?" \
+  --gold-sql-file refunds.sql
+
 # List the suite's cases (id + question; --json adds the gold SQL), then prune one:
 cassis eval list-cases --project ...
 cassis eval delete-case 019f0000-0000-7000-8000-0000000000ca --project ...
 
 # Pull the source schema into <base-path>/.schema.json (gitignored local snapshot):
 cassis schema pull
+
+# Push a DDL file to detect source-schema changes (DDL-only projects):
+cassis schema push schema.sql
+
+# Push and return immediately (poll in the webapp):
+cassis schema push schema.sql --no-wait
+
+# List the projects the API key can reach (id, name, published version, dialect):
+cassis projects list
+
+# Published version vs local checkout (add --watch to poll until your merge is published):
+cassis status
+cassis status --watch --timeout 600
+
+# The full local gate in one verb (fmt --check, check, eval run; stops at the first failure):
+cassis verify
+cassis verify --no-eval
 ```
 
 Configuration (flags take precedence over env vars):
@@ -121,7 +149,8 @@ Configuration (flags take precedence over env vars):
 | `--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) |
 
-`cassis eval run` also accepts `--label` (run label in the Evals page; defaults
+`cassis eval run` also accepts `--case <id>` (repeatable; run only the named
+cases, ids from `eval list-cases` or `add-case`), `--label` (run label in the Evals page; defaults
 to the branch name from the CI environment or the local git checkout; rejected
 with `--branch`, whose runs are labelled with the branch name), `--wait/--no-wait`, `--poll-interval` (5 s),
 `--timeout` (30 min — the run keeps going server-side if the CLI stops waiting),

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

@@ -13,6 +13,10 @@ Run Cassis actions from your CI pipelines:
 - `cassis ontology test` runs individual questions through the text-to-SQL agent using your local ontology files, so you can check that a change actually works (e.g. a new column gets picked) — where `eval run` only checks for regressions on existing eval cases.
 - `cassis eval add-case` adds a gold question/SQL case to the project's eval suite — after fixing an ontology issue, add the question users were failing on so `eval run` guards it from regressing.
 - `cassis eval list-cases` and `cassis eval delete-case` maintain the suite: list the current cases with their ids, and prune one that is stale or wrong (e.g. its gold SQL encodes a definition the ontology has since changed).
+- `cassis schema push` uploads a DDL file to detect source-schema changes on a DDL-only project (same as the webapp's "Update from DDL" button): Cassis diffs the DDL against the ontology and surfaces added, dropped, and changed objects in Ontology > Review > Data source for approval. Waits for completion by default; `--no-wait` returns immediately.
+- `cassis projects list` lists the projects your API key can reach — id (what `--project` and `CASSIS_PROJECT_ID` take), name, published ontology version, and data-source dialect — so a pipeline or agent can discover the project id from the terminal instead of fishing it out of a webapp URL.
+- `cassis status` shows the project's published version (number, label, git commit), whether unpublished changes await publication, the git-sync binding, and how your local git HEAD relates to the published commit (in sync / N commits ahead / diverged). `cassis status --watch` polls until the published commit matches your local HEAD — e.g. right after merging a PR whose CI publishes the ontology — instead of watching the GitHub Actions tab.
+- `cassis verify` runs the full local gate in one verb — `ontology fmt --check`, `ontology check`, `eval run` — stopping at the first failure. One command in a checkout ("is this change safe to merge?"), one job in CI. `--no-eval` skips the eval suite.
 
 ## Install
 
@@ -34,7 +38,7 @@ The ontology tree under `<base-path>` (default `cassis/`) is:
 
 1. Create an API key in Cassis under **Organization settings → API keys** (keys start with `sk-k6-`).
 2. Store it as a CI secret and expose it as `CASSIS_API_KEY`.
-3. For `pull`, `upload`, `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 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`, and the `eval` case commands (`add-case`, `list-cases`, `delete-case`): the project ID (UUID) is taken from `<base-path>/project.yml` in the checkout (written by `pull` and by publishing) — so once a repo is pulled you don't need to pass it. To override, or before the first pull, set `CASSIS_PROJECT_ID` or pass `--project` (find the UUID with `cassis projects list`, or in the project's URL). `ontology check` uses the same resolution but treats it as optional: unbound checkouts get the project-less validation (no schema reference warnings).
 
 ## Usage
 
@@ -71,6 +75,9 @@ cassis eval run --project ...
 # Run against an existing Cassis ontology branch, or the unpublished ontology:
 cassis eval run --project ... --branch feature-x
 
+# Run only specific cases (repeatable) — e.g. prove a fresh add-case in seconds:
+cassis eval run --project ... --case 019f0000-0000-7000-8000-0000000000ca
+
 # Start the run and return immediately (poll in the webapp):
 cassis eval run --project ... --no-wait
 
@@ -82,12 +89,33 @@ cassis ontology test --project ... -q "How much was refunded last month?" -q "Ne
 cassis eval add-case --project ... -q "How much was refunded last month?" \
   --gold-sql "SELECT SUM(refunded_cents) / 100.0 FROM public.orders WHERE ..."
 
+# Multi-line gold SQL: read it from a file instead (no shell quoting pitfalls):
+cassis eval add-case --project ... -q "How much was refunded last month?" \
+  --gold-sql-file refunds.sql
+
 # List the suite's cases (id + question; --json adds the gold SQL), then prune one:
 cassis eval list-cases --project ...
 cassis eval delete-case 019f0000-0000-7000-8000-0000000000ca --project ...
 
 # Pull the source schema into <base-path>/.schema.json (gitignored local snapshot):
 cassis schema pull
+
+# Push a DDL file to detect source-schema changes (DDL-only projects):
+cassis schema push schema.sql
+
+# Push and return immediately (poll in the webapp):
+cassis schema push schema.sql --no-wait
+
+# List the projects the API key can reach (id, name, published version, dialect):
+cassis projects list
+
+# Published version vs local checkout (add --watch to poll until your merge is published):
+cassis status
+cassis status --watch --timeout 600
+
+# The full local gate in one verb (fmt --check, check, eval run; stops at the first failure):
+cassis verify
+cassis verify --no-eval
 ```
 
 Configuration (flags take precedence over env vars):
@@ -99,7 +127,8 @@ Configuration (flags take precedence over env vars):
 | `--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) |
 
-`cassis eval run` also accepts `--label` (run label in the Evals page; defaults
+`cassis eval run` also accepts `--case <id>` (repeatable; run only the named
+cases, ids from `eval list-cases` or `add-case`), `--label` (run label in the Evals page; defaults
 to the branch name from the CI environment or the local git checkout; rejected
 with `--branch`, whose runs are labelled with the branch name), `--wait/--no-wait`, `--poll-interval` (5 s),
 `--timeout` (30 min — the run keeps going server-side if the CLI stops waiting),

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

@@ -243,6 +243,57 @@ def get_ontology_export(
     return result["files"]
 
 
+def get_projects(
+    *,
+    api_url: str,
+    api_key: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> list[dict[str, Any]]:
+    """GET /api/ci/projects and return the project list."""
+    url = api_url.rstrip("/") + "/api/ci/projects"
+    try:
+        with _client(transport=transport) as client:
+            response = client.get(url, headers={"Authorization": f"Bearer {api_key}"})
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
+
+    if response.status_code == 401:
+        raise AuthError("The Cassis API rejected the API key (invalid or expired).")
+    if response.status_code >= 400:
+        raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
+    result = _parse_json_response(response, url)
+    if not isinstance(result, list) or not all(isinstance(p, dict) and "id" in p and "name" in p for p in result):
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result
+
+
+def get_project_status(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """GET /api/ci/projects/{project_id}/status and return the status record."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/status"
+    try:
+        with _client(transport=transport) as client:
+            response = client.get(url, headers={"Authorization": f"Bearer {api_key}"})
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
+
+    if response.status_code == 401:
+        raise AuthError("The Cassis API rejected the API key (invalid or expired).")
+    if response.status_code in (403, 404):
+        raise _project_scope_error(response)
+    if response.status_code >= 400:
+        raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
+    result = _parse_json_response(response, url)
+    if not isinstance(result, dict) or "has_unpublished_changes" not in result:
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result
+
+
 class NoSourceSchemaError(ApiError):
     """The project's data source has no introspected schema to pull."""
 
@@ -284,6 +335,68 @@ def get_schema_export(
     return result
 
 
+class SourceChangeConflictError(ApiError):
+    """A concurrent detection run is already active, or the project has a connected data source."""
+
+
+def post_detect_from_ddl(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    ddl: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """POST /api/ci/projects/{project_id}/source-changes/detect-from-ddl and return the run record."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/source-changes/detect-from-ddl"
+    try:
+        with _client(transport=transport) as client:
+            response = client.post(url, json={"ddl": ddl}, headers={"Authorization": f"Bearer {api_key}"})
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
+
+    if response.status_code == 401:
+        raise AuthError("The Cassis API rejected the API key (invalid or expired).")
+    if response.status_code == 409:
+        raise SourceChangeConflictError(str(_detail_or_text(response)))
+    if response.status_code in (403, 404):
+        raise _project_scope_error(response)
+    if response.status_code >= 400:
+        raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
+    result = _parse_json_response(response, url)
+    if not isinstance(result, dict) or "run_id" not in result:
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result
+
+
+def get_source_change_run(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    run_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """GET /api/ci/projects/{project_id}/source-changes/runs/{run_id} and return the run record."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/source-changes/runs/{run_id}"
+    try:
+        with _client(transport=transport) as client:
+            response = client.get(url, headers={"Authorization": f"Bearer {api_key}"})
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
+
+    if response.status_code == 401:
+        raise AuthError("The Cassis API rejected the API key (invalid or expired).")
+    if response.status_code in (403, 404):
+        raise _project_scope_error(response)
+    if response.status_code >= 400:
+        raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
+    result = _parse_json_response(response, url)
+    if not isinstance(result, dict) or "run_id" not in result:
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result
+
+
 def post_eval_run_start(
     *,
     api_url: str,
@@ -292,6 +405,7 @@ def post_eval_run_start(
     files: Optional[dict[str, str]] = None,
     branch: Optional[str] = None,
     label: Optional[str] = None,
+    case_ids: Optional[list[str]] = None,
     transport: Optional[httpx.BaseTransport] = None,
 ) -> dict[str, Any]:
     """POST to /api/ci/projects/{project_id}/eval/runs and return the run record."""
@@ -303,6 +417,8 @@ def post_eval_run_start(
         body["branch"] = branch
     if label is not None:
         body["label"] = label
+    if case_ids is not None:
+        body["test_case_ids"] = case_ids
     try:
         with _client(transport=transport) as client:
             response = client.post(url, json=body, headers={"Authorization": f"Bearer {api_key}"})

{cassis_cli-1.2.0 → cassis_cli-1.3.0}/cassis_cli/eval.py

@@ -7,7 +7,7 @@ import os
 import subprocess
 import time
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any, List, Optional
 from uuid import UUID
 
 import typer
@@ -164,11 +164,16 @@ def add_case(
         "--question",
         help="The natural-language question the case guards.",
     ),
-    gold_sql: str = typer.Option(
-        ...,
+    gold_sql: Optional[str] = typer.Option(
+        None,
         "--gold-sql",
         help="The correct SQL for the question; executed at run time to produce the expected output.",
     ),
+    gold_sql_file: Optional[Path] = typer.Option(
+        None,
+        "--gold-sql-file",
+        help="Read the gold SQL from this file instead of --gold-sql (no shell quoting of multi-line SQL).",
+    ),
     api_key: Optional[str] = typer.Option(
         None,
         "--api-key",
@@ -195,13 +200,31 @@ def add_case(
     failing on becomes a gold case, so `cassis eval run` guards it from
     regressing. On an executable data source the gold SQL is run before the
     case is stored, so a case that cannot execute never enters the suite.
+    The SQL comes from --gold-sql (inline) or --gold-sql-file (a file path;
+    prefer it for multi-line SQL, which shell quoting mangles inline).
     Exits 0 on creation, 1 on a duplicate question or gold SQL that does not
     run, 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))
+    if (gold_sql is None) == (gold_sql_file is None):
+        typer.secho("Pass exactly one of --gold-sql or --gold-sql-file.", fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_USAGE)
+    if gold_sql_file is not None:
+        try:
+            gold_sql = gold_sql_file.read_text(encoding="utf-8")
+        # Two separate handlers: the repo-wide black targets py314 and would
+        # strip the parens off a tuple form, which is a SyntaxError on the
+        # CLI's supported Python (>=3.10).
+        except OSError as exc:
+            typer.secho(f"Cannot read {gold_sql_file}: {exc}", fg=typer.colors.RED, err=True)
+            raise typer.Exit(EXIT_USAGE) from exc
+        except UnicodeDecodeError as exc:
+            typer.secho(f"Cannot read {gold_sql_file}: {exc}", fg=typer.colors.RED, err=True)
+            raise typer.Exit(EXIT_USAGE) from exc
+    assert gold_sql is not None
     if not question.strip() or not gold_sql.strip():
-        typer.secho("--question and --gold-sql must not be empty.", fg=typer.colors.RED, err=True)
+        typer.secho("--question and the gold SQL must not be empty.", fg=typer.colors.RED, err=True)
         raise typer.Exit(EXIT_USAGE)
 
     try:
@@ -388,6 +411,11 @@ def run(
         "--branch",
         help="Run against an existing Cassis ontology branch by name instead of local files.",
     ),
+    case: Optional[List[str]] = typer.Option(
+        None,
+        "--case",
+        help="Run only this eval case id (repeatable; ids from `eval list-cases` or `add-case`).",
+    ),
     label: Optional[str] = typer.Option(
         None,
         "--label",
@@ -412,11 +440,19 @@ def run(
 
     Uploads the local ontology file tree and scores it in-memory — nothing is pushed or
     persisted in Cassis besides the eval run itself. With --branch, runs against
-    an existing Cassis branch instead (no files are sent). Exits 0 when the run
-    completes with every case passed, 1 on any failed case / failed run /
-    invalid tree, 2 on usage errors, 3 on transport errors or --timeout.
+    an existing Cassis branch instead (no files are sent). With --case, only the
+    named case(s) run — e.g. proving one fresh `add-case` in seconds instead of
+    rerunning the whole suite. Exits 0 when the run completes with every case
+    passed, 1 on any failed case / failed run / invalid tree, 2 on usage
+    errors, 3 on transport errors or --timeout.
     """
     api_key = require_api_key(api_key)
+    for case_id in case or []:
+        try:
+            UUID(case_id)
+        except ValueError:
+            typer.secho(f"--case must be an eval case ID (UUID), got {case_id!r}.", fg=typer.colors.RED, err=True)
+            raise typer.Exit(EXIT_USAGE)
     if branch is not None and label is not None:
         typer.secho(
             "--label cannot be used with --branch: branch runs are labelled with the branch name.",
@@ -440,6 +476,7 @@ def run(
             files=files,
             branch=branch,
             label=label,
+            case_ids=case,
         )
     except EvalStartValidationError as exc:
         _print_validation_failure(exc.detail, base_path)

{cassis_cli-1.2.0 → cassis_cli-1.3.0}/cassis_cli/main.py

@@ -6,7 +6,10 @@ import typer
 from cassis_cli import __version__
 from cassis_cli.eval import app as eval_app
 from cassis_cli.ontology import app as ontology_app
+from cassis_cli.projects import app as projects_app
 from cassis_cli.schema import app as schema_app
+from cassis_cli.status import status
+from cassis_cli.verify import verify
 
 app = typer.Typer(
     no_args_is_help=True,
@@ -15,6 +18,9 @@ app = typer.Typer(
 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.command()(status)
+app.command()(verify)
 
 
 @app.command()

cassis_cli-1.3.0/cassis_cli/projects.py

@@ -0,0 +1,69 @@
+"""`cassis projects` — discover the projects an API key can reach.
+
+Every other CI route is project-scoped, so the very first thing a pipeline or
+checkout agent needs is a project id. `projects list` answers that from the
+terminal instead of fishing the UUID out of a webapp URL.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+import typer
+from cassis_cli.api import DEFAULT_API_URL, ApiError, AuthError, get_projects
+from cassis_cli.common import EXIT_OK, EXIT_TRANSPORT, require_api_key
+
+app = typer.Typer(help="Discover the projects this API key can reach.")
+
+
+@app.command(name="list")
+def list_projects(
+    api_key: Optional[str] = typer.Option(
+        None,
+        "--api-key",
+        envvar="CASSIS_API_KEY",
+        help="Cassis API key (sk-k6-...). Create one in Organization settings -> API keys.",
+    ),
+    api_url: str = typer.Option(
+        DEFAULT_API_URL,
+        "--api-url",
+        envvar="CASSIS_API_URL",
+        help="Cassis API base URL.",
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Print the raw JSON response."),
+) -> None:
+    """List the projects available to the API key.
+
+    Prints each project's id (what --project and CASSIS_PROJECT_ID take), name,
+    published ontology version, and data-source dialect. A schema-only source
+    (no connection) is marked "not executable": SQL is generated but never run.
+    Exits 0 on success, 2 on usage errors, 3 on transport/API errors.
+    """
+    api_key = require_api_key(api_key)
+
+    try:
+        projects = get_projects(api_url=api_url, api_key=api_key)
+    except (AuthError, ApiError) as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_TRANSPORT) from exc
+
+    if json_output:
+        typer.echo(json.dumps(projects, indent=2))
+        raise typer.Exit(EXIT_OK)
+
+    if not projects:
+        typer.echo("No projects visible to this API key.")
+        raise typer.Exit(EXIT_OK)
+
+    for project in projects:
+        version = project.get("published_version")
+        version_text = f"v{version}" if version is not None else "unpublished"
+        source = project.get("data_source")
+        if source:
+            dialect = source.get("sql_dialect") or "?"
+            source_text = dialect if source.get("is_executable") else f"{dialect}, not executable"
+        else:
+            source_text = "no data source"
+        typer.echo(f"{project['id']}  {project['name']}  ({version_text}; {source_text})")
+    raise typer.Exit(EXIT_OK)

cassis_cli-1.3.0/cassis_cli/schema.py

@@ -0,0 +1,295 @@
+"""`cassis schema` — local snapshot of the data source's source schema.
+
+The source schema is OBSERVED state (the warehouse is authoritative), so the
+snapshot is a gitignored cache, never a committed file: `pull` writes
+`<base-path>/.schema.json` and keeps it out of git via the ontology dir's
+`.gitignore`. Agents working in a checkout grep it instead of paging through
+the MCP `get_source_schema` tool; `pulled_at` records how stale it is.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+import typer
+from cassis_cli.api import (
+    DEFAULT_API_URL,
+    ApiError,
+    AuthError,
+    SourceChangeConflictError,
+    get_schema_export,
+    get_source_change_run,
+    post_detect_from_ddl,
+)
+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(help="Pull or push the data source's schema.")
+
+_TERMINAL_RUN_STATUSES = {"completed", "failed", "cancelled"}
+_MAX_CONSECUTIVE_POLL_FAILURES = 5
+
+SNAPSHOT_FILENAME = ".schema.json"
+_GITIGNORE_HEADER = "# Cassis local caches (observed state — never commit)"
+
+
+@app.command()
+def pull(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Repository checkout root (the directory containing the ontology export path).",
+    ),
+    project_id: Optional[str] = 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: Optional[str] = typer.Option(
+        None,
+        "--api-key",
+        envvar="CASSIS_API_KEY",
+        help="Cassis API key (sk-k6-...). Create one in Organization settings -> API keys.",
+    ),
+    api_url: str = typer.Option(
+        DEFAULT_API_URL,
+        "--api-url",
+        envvar="CASSIS_API_URL",
+        help="Cassis API base URL.",
+    ),
+    base_path: str = typer.Option(
+        DEFAULT_BASE_PATH,
+        "--base-path",
+        envvar="CASSIS_BASE_PATH",
+        help="Repository directory the ontology is exported under (the project's git-sync Path setting).",
+    ),
+) -> None:
+    """Download the source schema into `<base-path>/.schema.json` (gitignored).
+
+    The snapshot is the schema as Cassis last introspected it from the
+    warehouse (or parsed from an uploaded DDL) — every table with its columns
+    and types, plus a `pulled_at` stamp so staleness is visible. Re-run after
+    a warehouse sync to refresh. Exits 0 on success, 2 on usage errors, 3 on
+    transport/API errors.
+    """
+    api_key = require_api_key(api_key)
+    ontology_dir = path / base_path
+    project_id = resolve_project_id(project_id, ontology_dir)
+
+    try:
+        result = get_schema_export(api_url=api_url, api_key=api_key, project_id=project_id)
+    except (AuthError, ApiError) as exc:
+        # NoSourceSchemaError lands here too: the server's message already says
+        # what to do (sync or upload a DDL); the class exists so api.py doesn't
+        # bury it under the misleading project-scope hint.
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_TRANSPORT) from exc
+
+    snapshot = {
+        "pulled_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        "project_id": project_id,
+        "schema_version": result["schema_version"],
+        "tables": result["tables"],
+    }
+
+    try:
+        ontology_dir.mkdir(parents=True, exist_ok=True)
+        snapshot_path = ontology_dir / SNAPSHOT_FILENAME
+        snapshot_path.write_text(json.dumps(snapshot, indent=2) + "\n", encoding="utf-8")
+        ensure_gitignored(ontology_dir)
+    except OSError as exc:
+        # Usage-class exit (2), like the other local-file failures in the exit
+        # table — the API call succeeded, the checkout is what's broken.
+        typer.secho(f"Could not write the snapshot: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_USAGE) from exc
+
+    table_count = len(result["tables"])
+    column_count = sum(len(t.get("columns") or []) for t in result["tables"])
+    version = result["schema_version"].get("version")
+    typer.secho(
+        f"✓ Pulled source schema v{version}: {table_count} tables, {column_count} columns "
+        f"-> {snapshot_path} (gitignored)",
+        fg=typer.colors.GREEN,
+    )
+
+
+def ensure_gitignored(ontology_dir: Path) -> None:
+    """Make sure the snapshot never lands in git: keep `.gitignore` covering it.
+
+    Appends to (or creates) the ontology dir's own `.gitignore` — local to the
+    export directory, so it survives repo-level `.gitignore` rewrites and needs
+    no knowledge of the checkout layout.
+    """
+    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)
+        existing = ""
+    if SNAPSHOT_FILENAME in existing.splitlines():
+        return
+    prefix = "" if not existing else existing.rstrip("\n") + "\n"
+    gitignore.write_text(f"{prefix}{_GITIGNORE_HEADER}\n{SNAPSHOT_FILENAME}\n", encoding="utf-8")
+
+
+@app.command()
+def push(
+    ddl_file: Path = typer.Argument(
+        ..., help="Path to the DDL file (.sql, .ddl, .txt) containing CREATE TABLE statements."
+    ),
+    path: Path = typer.Option(
+        Path("."),
+        help="Repository checkout root (the directory containing the ontology export path).",
+    ),
+    project_id: Optional[str] = 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: Optional[str] = typer.Option(
+        None,
+        "--api-key",
+        envvar="CASSIS_API_KEY",
+        help="Cassis API key (sk-k6-...). Create one in Organization settings -> API keys.",
+    ),
+    api_url: str = typer.Option(
+        DEFAULT_API_URL,
+        "--api-url",
+        envvar="CASSIS_API_URL",
+        help="Cassis API base URL.",
+    ),
+    base_path: str = typer.Option(
+        DEFAULT_BASE_PATH,
+        "--base-path",
+        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."),
+    timeout: float = typer.Option(600.0, "--timeout", help="Give up waiting after this many seconds."),
+    json_output: bool = typer.Option(False, "--json", help="Print the run record as raw JSON."),
+) -> None:
+    """Upload a DDL file to detect source-schema changes (same as the webapp's "Update from DDL").
+
+    The DDL must contain at least one CREATE TABLE statement and represents the
+    project's complete source schema. Cassis diffs it against the ontology:
+    added, dropped, and changed objects appear in Ontology > Review > Data
+    source for approval. Re-uploading a corrected DDL supersedes the previous
+    one. Only works on DDL-only projects (no warehouse connection). Exits 0 on
+    success, 1 on a failed detection run, 2 on usage errors, 3 on transport/API
+    errors or a --wait timeout.
+    """
+    api_key = require_api_key(api_key)
+    project_id = resolve_project_id(project_id, path / base_path)
+
+    try:
+        ddl_text = ddl_file.read_text(encoding="utf-8")
+    except OSError as exc:
+        typer.secho(f"Cannot read {ddl_file}: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_USAGE) from exc
+    except UnicodeDecodeError as exc:
+        typer.secho(f"Cannot read {ddl_file}: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_USAGE) from exc
+
+    if not ddl_text.strip():
+        typer.secho("DDL file is empty.", fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_USAGE)
+
+    try:
+        run = post_detect_from_ddl(api_url=api_url, api_key=api_key, project_id=project_id, ddl=ddl_text)
+    except SourceChangeConflictError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_VALIDATION_FAILED) from exc
+    except (AuthError, ApiError) as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_TRANSPORT) from exc
+
+    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,
+        project_id=project_id,
+        run_id=run_id,
+        poll_interval=poll_interval,
+        timeout=timeout,
+    )
+
+    if json_output:
+        typer.echo(json.dumps(run, indent=2))
+
+    run_status = run.get("status")
+    if run_status == "completed":
+        summary = run.get("summary") or {}
+        total = summary.get("total_changes", 0)
+        typer.secho(
+            f"✓ Detection completed: {total} change(s) detected." if total else "✓ Detection completed: no changes.",
+            fg=typer.colors.GREEN,
+        )
+        raise typer.Exit(EXIT_OK)
+    if run_status == "failed":
+        error = run.get("error") or "unknown error"
+        typer.secho(f"Detection failed: {error}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_VALIDATION_FAILED)
+    if run_status == "cancelled":
+        typer.secho("Detection run was cancelled.", fg=typer.colors.YELLOW, err=True)
+        raise typer.Exit(EXIT_VALIDATION_FAILED)
+    typer.secho(f"Detection run ended with unexpected status: {run_status}", fg=typer.colors.RED, err=True)
+    raise typer.Exit(EXIT_TRANSPORT)
+
+
+def _wait_for_detection_run(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    run_id: str,
+    poll_interval: float,
+    timeout: float,
+) -> "dict[str, Any]":
+    """Poll until the detection run reaches a terminal status."""
+    deadline = time.monotonic() + timeout
+    consecutive_failures = 0
+    while True:
+        try:
+            run = get_source_change_run(api_url=api_url, api_key=api_key, project_id=project_id, run_id=run_id)
+            consecutive_failures = 0
+        except AuthError as exc:
+            typer.secho(str(exc), fg=typer.colors.RED, err=True)
+            raise typer.Exit(EXIT_TRANSPORT) from exc
+        except ApiError as exc:
+            consecutive_failures += 1
+            if consecutive_failures >= _MAX_CONSECUTIVE_POLL_FAILURES:
+                typer.secho(str(exc), fg=typer.colors.RED, err=True)
+                raise typer.Exit(EXIT_TRANSPORT) from exc
+            time.sleep(poll_interval)
+            continue
+
+        if run.get("status") in _TERMINAL_RUN_STATUSES:
+            return run
+
+        if time.monotonic() >= deadline:
+            typer.secho(
+                f"Timed out after {timeout:.0f}s: the detection run is still {run.get('status', '?')}.",
+                fg=typer.colors.YELLOW,
+                err=True,
+            )
+            raise typer.Exit(EXIT_TRANSPORT)
+        time.sleep(poll_interval)

cassis_cli-1.3.0/cassis_cli/status.py

@@ -0,0 +1,184 @@
+"""`cassis status` — published version vs repository head, from the terminal.
+
+One command answers what previously needed the webapp or the GitHub Actions
+tab: which version is published, whether it matches the local checkout, and
+whether anything is awaiting publication. `--watch` polls until the published
+version catches up with the local head (e.g. right after merging a PR whose
+CI publishes the ontology).
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import time
+from pathlib import Path
+from typing import Any, Optional, Tuple
+
+import typer
+from cassis_cli.api import DEFAULT_API_URL, ApiError, AuthError, get_project_status
+from cassis_cli.common import (
+    DEFAULT_BASE_PATH,
+    EXIT_OK,
+    EXIT_TRANSPORT,
+    EXIT_USAGE,
+    require_api_key,
+    resolve_project_id,
+)
+
+
+def _git(path: Path, *args: str) -> Optional[str]:
+    """Run a git command in the checkout; None on failure, stdout (possibly empty) on success."""
+    try:
+        proc = subprocess.run(
+            ["git", *args],
+            cwd=path,
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    # Two separate handlers: the repo-wide black targets py314 and would strip
+    # the parens off a tuple form, which is a SyntaxError on the CLI's
+    # supported Python (>=3.10).
+    except OSError:
+        return None
+    except subprocess.TimeoutExpired:
+        return None
+    if proc.returncode != 0:
+        return None
+    return proc.stdout.strip()
+
+
+def _local_comparison(path: Path, head: Optional[str], published_sha: Optional[str]) -> "Tuple[str, bool]":
+    """Describe the local checkout vs the published commit. Returns (text, in_sync)."""
+    if head is None:
+        return "not a git checkout (no local comparison)", False
+    if published_sha is None:
+        return f"at {head[:9]} (the published version records no git commit)", False
+    if head == published_sha:
+        return f"in sync with the published version ({head[:9]})", True
+    if _git(path, "merge-base", "--is-ancestor", published_sha, "HEAD") is not None:
+        count = _git(path, "rev-list", "--count", f"{published_sha}..HEAD") or "?"
+        return f"{count} commit(s) ahead of the published version ({published_sha[:9]})", False
+    if _git(path, "cat-file", "-e", f"{published_sha}^{{commit}}") is None:
+        return (
+            f"published commit {published_sha[:9]} not found locally (run git fetch, or the checkout is behind)",
+            False,
+        )
+    if _git(path, "merge-base", "--is-ancestor", "HEAD", published_sha) is not None:
+        count = _git(path, "rev-list", "--count", f"HEAD..{published_sha}") or "?"
+        return f"{count} commit(s) behind the published version ({published_sha[:9]}), run git pull", False
+    return f"diverged from the published commit {published_sha[:9]}", False
+
+
+def _render(status_record: "dict[str, Any]", comparison_text: str) -> None:
+    published = status_record.get("published_version")
+    if published:
+        label = f" {published['label']!r}" if published.get("label") else ""
+        sha = published.get("git_commit_sha")
+        sha_text = f", commit {sha[:9]}" if sha else ""
+        typer.echo(f"Published: v{published['version']}{label} ({published.get('published_at')}{sha_text})")
+    else:
+        typer.echo("Published: nothing yet")
+    changes = "yes" if status_record.get("has_unpublished_changes") else "no"
+    typer.echo(f"Unpublished changes: {changes}")
+    git_sync = status_record.get("git_sync")
+    if git_sync:
+        typer.echo(f"Git sync: {git_sync['provider']} {git_sync['repo']} (path {git_sync['base_path']})")
+    else:
+        typer.echo("Git sync: not configured")
+    typer.echo(f"Local checkout: {comparison_text}")
+
+
+def status(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Repository checkout root (the directory containing the ontology export path).",
+    ),
+    project_id: Optional[str] = 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: Optional[str] = typer.Option(
+        None,
+        "--api-key",
+        envvar="CASSIS_API_KEY",
+        help="Cassis API key (sk-k6-...). Create one in Organization settings -> API keys.",
+    ),
+    api_url: str = typer.Option(
+        DEFAULT_API_URL,
+        "--api-url",
+        envvar="CASSIS_API_URL",
+        help="Cassis API base URL.",
+    ),
+    base_path: str = typer.Option(
+        DEFAULT_BASE_PATH,
+        "--base-path",
+        envvar="CASSIS_BASE_PATH",
+        help="Repository directory the ontology is exported under (the project's git-sync Path setting).",
+    ),
+    watch: bool = typer.Option(
+        False,
+        "--watch",
+        help="Poll until the published version's commit matches the local git HEAD.",
+    ),
+    poll_interval: float = typer.Option(5.0, "--poll-interval", help="Seconds between polls with --watch."),
+    timeout: float = typer.Option(600.0, "--timeout", help="Give up watching after this many seconds."),
+    json_output: bool = typer.Option(False, "--json", help="Print the status as raw JSON."),
+) -> None:
+    """Show the project's published version vs the local checkout.
+
+    Prints the published head (version, label, commit), whether unpublished
+    changes are awaiting publication, the git-sync binding, and how the local
+    git HEAD relates to the published commit. With --watch, polls until the
+    published commit equals the local HEAD (a publish of your merge landing),
+    then exits 0. Exits 0 on success, 2 on usage errors, 3 on transport/API
+    errors or a --watch timeout.
+    """
+    api_key = require_api_key(api_key)
+    project_id = resolve_project_id(project_id, path / base_path, quiet=json_output)
+    head = _git(path, "rev-parse", "HEAD")
+
+    if watch and head is None:
+        typer.secho("--watch needs a git checkout (no local HEAD to compare against).", fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_USAGE)
+
+    deadline = time.monotonic() + timeout
+    last_line: Optional[str] = None
+    while True:
+        try:
+            record = get_project_status(api_url=api_url, api_key=api_key, project_id=project_id)
+        except (AuthError, ApiError) as exc:
+            typer.secho(str(exc), fg=typer.colors.RED, err=True)
+            raise typer.Exit(EXIT_TRANSPORT) from exc
+
+        published = record.get("published_version") or {}
+        published_sha = published.get("git_commit_sha")
+        comparison_text, in_sync = _local_comparison(path, head, published_sha)
+
+        if json_output:
+            typer.echo(json.dumps({**record, "local": {"head": head, "in_sync": in_sync}}, indent=2))
+        elif not watch:
+            _render(record, comparison_text)
+        else:
+            version_text = f"v{published['version']}" if published else "nothing published"
+            line = f"{version_text} (commit {published_sha[:9] if published_sha else 'none'}); local: {comparison_text}"
+            if line != last_line:
+                typer.echo(line)
+                last_line = line
+
+        if not watch:
+            raise typer.Exit(EXIT_OK)
+        if in_sync:
+            typer.secho("✓ Published version matches the local HEAD.", fg=typer.colors.GREEN)
+            raise typer.Exit(EXIT_OK)
+        if time.monotonic() >= deadline:
+            typer.secho(
+                f"Timed out after {timeout:.0f}s: the published version still does not match the local HEAD.",
+                fg=typer.colors.YELLOW,
+                err=True,
+            )
+            raise typer.Exit(EXIT_TRANSPORT)
+        time.sleep(poll_interval)

cassis_cli-1.3.0/cassis_cli/verify.py

@@ -0,0 +1,123 @@
+"""`cassis verify` — the full local gate in one verb: fmt --check, check, eval run.
+
+Every edit session recites the same litany by hand, and the README's CI
+examples chain the same three commands as separate jobs. `verify` runs them in
+order and stops at the first failure, so "is this change safe to merge?" is
+one command in a checkout and one job in CI.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Callable, Optional
+
+import typer
+from cassis_cli.api import DEFAULT_API_URL
+from cassis_cli.common import DEFAULT_BASE_PATH, EXIT_OK, require_api_key
+from cassis_cli.eval import run as eval_run
+from cassis_cli.ontology import check as ontology_check
+from cassis_cli.ontology import fmt as ontology_fmt
+
+
+def _step(title: str, fn: "Callable[[], None]") -> int:
+    """Run one gate; return its exit code (commands exit via typer.Exit)."""
+    typer.secho(f"==> {title}", bold=True)
+    try:
+        fn()
+    except typer.Exit as exc:
+        return exc.exit_code
+    return EXIT_OK
+
+
+def verify(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Repository checkout root (the directory containing the ontology export path).",
+    ),
+    project_id: Optional[str] = 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: Optional[str] = typer.Option(
+        None,
+        "--api-key",
+        envvar="CASSIS_API_KEY",
+        help="Cassis API key (sk-k6-...). Create one in Organization settings -> API keys.",
+    ),
+    api_url: str = typer.Option(
+        DEFAULT_API_URL,
+        "--api-url",
+        envvar="CASSIS_API_URL",
+        help="Cassis API base URL.",
+    ),
+    base_path: str = typer.Option(
+        DEFAULT_BASE_PATH,
+        "--base-path",
+        envvar="CASSIS_BASE_PATH",
+        help="Repository directory the ontology is exported under (the project's git-sync Path setting).",
+    ),
+    run_eval: bool = typer.Option(
+        True,
+        "--eval/--no-eval",
+        help="Run the project's eval suite as the last gate (default: run it).",
+    ),
+) -> None:
+    """Run the three local gates in order: `ontology fmt --check`, `ontology check`, `eval run`.
+
+    The same sequence the README's CI examples chain as separate jobs, stopping
+    at the first failure. `fmt` runs in --check mode and writes nothing. Pass
+    --no-eval to skip the eval suite (e.g. a project with no cases yet).
+    Exits with the first failing gate's code: 0 all gates passed, 1 validation
+    or eval failure, 2 usage errors, 3 transport/API errors, 130 interrupted.
+    """
+    api_key = require_api_key(api_key)
+
+    code = _step(
+        "cassis ontology fmt --check",
+        lambda: ontology_fmt(path=path, api_key=api_key, api_url=api_url, base_path=base_path, check_only=True),
+    )
+    if code != EXIT_OK:
+        typer.secho("Not canonical: run `cassis ontology fmt` and review the diff.", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code)
+
+    code = _step(
+        "cassis ontology check",
+        lambda: ontology_check(
+            path=path,
+            project_id=project_id,
+            api_key=api_key,
+            api_url=api_url,
+            base_path=base_path,
+            json_output=False,
+        ),
+    )
+    if code != EXIT_OK:
+        raise typer.Exit(code)
+
+    if run_eval:
+        # Kwargs must track eval_run's signature; a new required param breaks here.
+        code = _step(
+            "cassis eval run",
+            lambda: eval_run(
+                path=path,
+                project_id=project_id,
+                api_key=api_key,
+                api_url=api_url,
+                base_path=base_path,
+                branch=None,
+                case=None,
+                label=None,
+                wait=True,
+                poll_interval=5.0,
+                timeout=1800.0,
+                json_output=False,
+                app_url=None,
+            ),
+        )
+        if code != EXIT_OK:
+            raise typer.Exit(code)
+
+    typer.secho("✓ verify passed" + ("" if run_eval else " (eval skipped)"), fg=typer.colors.GREEN, bold=True)
+    raise typer.Exit(EXIT_OK)

{cassis_cli-1.2.0 → cassis_cli-1.3.0}/pyproject.toml

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

cassis_cli-1.2.0/cassis_cli/schema.py

@@ -1,129 +0,0 @@
-"""`cassis schema` — local snapshot of the data source's source schema.
-
-The source schema is OBSERVED state (the warehouse is authoritative), so the
-snapshot is a gitignored cache, never a committed file: `pull` writes
-`<base-path>/.schema.json` and keeps it out of git via the ontology dir's
-`.gitignore`. Agents working in a checkout grep it instead of paging through
-the MCP `get_source_schema` tool; `pulled_at` records how stale it is.
-"""
-
-from __future__ import annotations
-
-import json
-from datetime import datetime, timezone
-from pathlib import Path
-from typing import Optional
-
-import typer
-from cassis_cli.api import DEFAULT_API_URL, ApiError, AuthError, get_schema_export
-from cassis_cli.common import (
-    DEFAULT_BASE_PATH,
-    EXIT_OK,
-    EXIT_TRANSPORT,
-    EXIT_USAGE,
-    require_api_key,
-    resolve_project_id,
-)
-
-app = typer.Typer(help="Pull a local, gitignored snapshot of the data source's schema.")
-
-SNAPSHOT_FILENAME = ".schema.json"
-_GITIGNORE_HEADER = "# Cassis local caches (observed state — never commit)"
-
-
-@app.command()
-def pull(
-    path: Path = typer.Argument(
-        Path("."),
-        help="Repository checkout root (the directory containing the ontology export path).",
-    ),
-    project_id: Optional[str] = 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: Optional[str] = typer.Option(
-        None,
-        "--api-key",
-        envvar="CASSIS_API_KEY",
-        help="Cassis API key (sk-k6-...). Create one in Organization settings -> API keys.",
-    ),
-    api_url: str = typer.Option(
-        DEFAULT_API_URL,
-        "--api-url",
-        envvar="CASSIS_API_URL",
-        help="Cassis API base URL.",
-    ),
-    base_path: str = typer.Option(
-        DEFAULT_BASE_PATH,
-        "--base-path",
-        envvar="CASSIS_BASE_PATH",
-        help="Repository directory the ontology is exported under (the project's git-sync Path setting).",
-    ),
-) -> None:
-    """Download the source schema into `<base-path>/.schema.json` (gitignored).
-
-    The snapshot is the schema as Cassis last introspected it from the
-    warehouse (or parsed from an uploaded DDL) — every table with its columns
-    and types, plus a `pulled_at` stamp so staleness is visible. Re-run after
-    a warehouse sync to refresh. Exits 0 on success, 2 on usage errors, 3 on
-    transport/API errors.
-    """
-    api_key = require_api_key(api_key)
-    ontology_dir = path / base_path
-    project_id = resolve_project_id(project_id, ontology_dir)
-
-    try:
-        result = get_schema_export(api_url=api_url, api_key=api_key, project_id=project_id)
-    except (AuthError, ApiError) as exc:
-        # NoSourceSchemaError lands here too: the server's message already says
-        # what to do (sync or upload a DDL); the class exists so api.py doesn't
-        # bury it under the misleading project-scope hint.
-        typer.secho(str(exc), fg=typer.colors.RED, err=True)
-        raise typer.Exit(EXIT_TRANSPORT) from exc
-
-    snapshot = {
-        "pulled_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
-        "project_id": project_id,
-        "schema_version": result["schema_version"],
-        "tables": result["tables"],
-    }
-
-    try:
-        ontology_dir.mkdir(parents=True, exist_ok=True)
-        snapshot_path = ontology_dir / SNAPSHOT_FILENAME
-        snapshot_path.write_text(json.dumps(snapshot, indent=2) + "\n", encoding="utf-8")
-        ensure_gitignored(ontology_dir)
-    except OSError as exc:
-        # Usage-class exit (2), like the other local-file failures in the exit
-        # table — the API call succeeded, the checkout is what's broken.
-        typer.secho(f"Could not write the snapshot: {exc}", fg=typer.colors.RED, err=True)
-        raise typer.Exit(EXIT_USAGE) from exc
-
-    table_count = len(result["tables"])
-    column_count = sum(len(t.get("columns") or []) for t in result["tables"])
-    version = result["schema_version"].get("version")
-    typer.secho(
-        f"✓ Pulled source schema v{version}: {table_count} tables, {column_count} columns "
-        f"-> {snapshot_path} (gitignored)",
-        fg=typer.colors.GREEN,
-    )
-
-
-def ensure_gitignored(ontology_dir: Path) -> None:
-    """Make sure the snapshot never lands in git: keep `.gitignore` covering it.
-
-    Appends to (or creates) the ontology dir's own `.gitignore` — local to the
-    export directory, so it survives repo-level `.gitignore` rewrites and needs
-    no knowledge of the checkout layout.
-    """
-    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)
-        existing = ""
-    if SNAPSHOT_FILENAME in existing.splitlines():
-        return
-    prefix = "" if not existing else existing.rstrip("\n") + "\n"
-    gitignore.write_text(f"{prefix}{_GITIGNORE_HEADER}\n{SNAPSHOT_FILENAME}\n", encoding="utf-8")