dataspring-cli 0.4.0__tar.gz → 0.4.2__tar.gz

{dataspring_cli-0.4.0 → dataspring_cli-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dataspring-cli
-Version: 0.4.0
+Version: 0.4.2
 Summary: DataSpring CLI - Query metrics and manage dashboards from the terminal
 Project-URL: Homepage, https://dataspring.app
 Project-URL: Documentation, https://dataspring.app/docs
@@ -79,13 +79,17 @@ dataspring query -m total_revenue --format json > data.json
 ### Authentication
 
 ```bash
-dataspring login          # Login via Google OAuth (opens browser)
-dataspring whoami         # Show current user and organization
-dataspring logout         # Clear stored credentials
+dataspring auth login     # Device flow: approve the code in a browser signed in to DataSpring
+dataspring whoami --json  # The person, the org, where the org came from (org_from), the role
+dataspring auth logout    # Revoke this machine's keys and forget them
 dataspring org list       # List your organizations
-dataspring org switch ID  # Switch to a different organization
 ```
 
+Every command names its organization: `--org <org>`, else `DATASPRING_ORG`
+then `FORSPRING_ORG`, else `.forspring.json` (`{"org": "<org>"}`) in this
+directory or a parent, else `DATASPRING_API_KEY`'s own org, else the only
+stored key; otherwise it is refused with `org_required` (exit 2).
+
 ### Querying Metrics
 
 ```bash

{dataspring_cli-0.4.0 → dataspring_cli-0.4.2}/README.md

@@ -47,13 +47,17 @@ dataspring query -m total_revenue --format json > data.json
 ### Authentication
 
 ```bash
-dataspring login          # Login via Google OAuth (opens browser)
-dataspring whoami         # Show current user and organization
-dataspring logout         # Clear stored credentials
+dataspring auth login     # Device flow: approve the code in a browser signed in to DataSpring
+dataspring whoami --json  # The person, the org, where the org came from (org_from), the role
+dataspring auth logout    # Revoke this machine's keys and forget them
 dataspring org list       # List your organizations
-dataspring org switch ID  # Switch to a different organization
 ```
 
+Every command names its organization: `--org <org>`, else `DATASPRING_ORG`
+then `FORSPRING_ORG`, else `.forspring.json` (`{"org": "<org>"}`) in this
+directory or a parent, else `DATASPRING_API_KEY`'s own org, else the only
+stored key; otherwise it is refused with `org_required` (exit 2).
+
 ### Querying Metrics
 
 ```bash

dataspring_cli-0.4.2/cli/auth.py

@@ -0,0 +1,487 @@
+"""CLI authentication: suite standard §3 (/home/dev/workspace/forspring/docs/suite-standards.md).
+
+``dataspring auth login`` runs the device flow (RFC 8628 with PKCE,
+backend/routes_device.py): the CLI shows a code and a URL, a person signed in
+to DataSpring in any browser (this machine needs none) approves it, and the
+CLI collects an ordinary ``ds_`` API key labelled ``CLI on <hostname>`` (one
+per org with ``--all-orgs``).
+
+Credentials live in ``~/.dataspring/credentials.json`` (mode 0600): a profile
+(a key) per org. Nothing machine-wide says which one a command uses (hub
+D-99: ``auth use`` went, because two agents on one machine moved each other
+between orgs); every command resolves its org afresh, in this order
+(:meth:`CLIAuthManager.resolve`):
+
+1. ``--org`` on the command;
+2. ``DATASPRING_ORG``, then ``FORSPRING_ORG``;
+3. ``.forspring.json`` (``{"org": "noon"}``) in this directory or a parent;
+4. the key's own org, when ``DATASPRING_API_KEY`` is set (a key belongs to
+   one org);
+5. the only stored profile;
+
+else it refuses with ``org_required``, the stored orgs and the three ways to
+name one, and never prompts. ``DATASPRING_API_KEY`` always wins over the
+stored keys: with it, a named org that is not the key's is ``org_mismatch``.
+``--key`` stores a key you already have, for CI. ``dataspring auth logout``
+revokes the stored keys on the server, then forgets them.
+
+Who the person is and which org a key is for are the server's answer to
+``/api/me``; nothing here opens Firestore.
+"""
+
+import base64
+import hashlib
+import json
+import os
+import secrets
+import socket
+import time
+import webbrowser
+from dataclasses import dataclass
+from pathlib import Path
+
+import httpx
+
+from cli.refusals import EN, NAME_AN_ORG, Refusal, classify, from_body
+
+ENV_KEY = "DATASPRING_API_KEY"
+
+#: Step 2 of the org order: the product's own variable, then the suite's.
+ORG_ENV_VARS = ("DATASPRING_ORG", "FORSPRING_ORG")
+
+#: Step 3: the per-project file, committed next to the code (``{"org": "noon"}``).
+PROJECT_FILE = ".forspring.json"
+
+#: ``org_from`` for steps 4 and 5.
+FROM_KEY = ENV_KEY
+FROM_ONLY_PROFILE = "only_profile"
+
+#: Step 1, ``--org``: set by the root command (``cli.main``) for this
+#: invocation; ``None`` when not given.
+_org_flag: str | None = None
+
+
+def set_org_flag(org: str | None) -> None:
+    """``--org`` for this invocation (``cli.main``'s root callback)."""
+    global _org_flag
+    _org_flag = (org or "").strip() or None
+
+
+def _host() -> str:
+    """The backend's root (https://dataspring.app; locally http://localhost:8000)."""
+    from settings import get_settings
+
+    return get_settings().mcp_server_base_url.removesuffix("/api")
+
+
+@dataclass(frozen=True)
+class UserContext:
+    """The signed-in user as ``GET /api/me`` reports them.
+
+    Mirrors the fields of ``services.auth.UserContext`` that the CLI shows,
+    without importing the service layer: the CLI wheel ships without it.
+    """
+
+    uid: str
+    email: str
+    org_id: str | None
+    org_name: str | None
+    role: str | None
+
+    @property
+    def has_org(self) -> bool:
+        """False for an account no administrator has added to an org yet.
+
+        Since D25 sign-up creates no organization, so ``/api/me`` answers 200
+        with the three org fields null. The CLI says so rather than crashing
+        on a ``KeyError`` the way it would have.
+        """
+        return self.org_id is not None
+
+
+class AuthenticationError(Exception):
+    """Raised when authentication fails or user is not logged in.
+
+    ``exit_code`` is what the CLI ends with (suite standards §6): 1, a plain
+    failure, unless a subclass says otherwise.
+    """
+
+    exit_code = 1
+
+
+class Refused(AuthenticationError):
+    """A D-99 refusal (``cli.refusals``): not signed in, no org named, a key
+    for another org, or the server's own refusal of the key."""
+
+    def __init__(self, reason: str, note: str, fix: str | None = None):
+        self.refusal = Refusal(reason, note, fix)
+        super().__init__(self.refusal.message)
+
+    @property
+    def reason(self) -> str:
+        return self.refusal.reason
+
+    @property
+    def exit_code(self) -> int:  # type: ignore[override]
+        return self.refusal.exit_code
+
+
+class ProjectFileError(AuthenticationError):
+    """A ``.forspring.json`` that names no org: invalid input (2)."""
+
+    exit_code = 2
+
+
+@dataclass(frozen=True)
+class ResolvedOrg:
+    """Which key a command sends, for which org, and where the org came from.
+
+    ``org_id`` is ``None`` only for ``DATASPRING_API_KEY`` with no org named
+    and no stored profile holding that key: the key knows its org, and the
+    server says which (``GET /api/me``). ``org_from`` is ``--org``,
+    ``DATASPRING_ORG``, ``FORSPRING_ORG``, ``.forspring.json``,
+    ``DATASPRING_API_KEY`` or ``only_profile``; ``org_file`` is the file
+    step 3 read.
+    """
+
+    key: str
+    org_id: str | None
+    org_from: str
+    org_file: str | None = None
+
+
+def _not_signed_in(detail: str = "Not logged in.") -> Refused:
+    return Refused("not_signed_in", detail, "Run 'dataspring auth login' (or set DATASPRING_API_KEY).")
+
+
+def find_project_file(start: Path | None = None) -> Path | None:
+    """The nearest ``.forspring.json`` in ``start`` (default: the working
+    directory) or a parent."""
+    here = (start or Path.cwd()).resolve()
+    for directory in (here, *here.parents):
+        candidate = directory / PROJECT_FILE
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def read_project_org(path: Path) -> str:
+    """The ``org`` a ``.forspring.json`` names; a file that names none is an error."""
+    shape = '{"org": "<org>"}'
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as e:
+        raise ProjectFileError(f"{path} is not valid JSON ({e}); it should hold {shape}.")
+    org = data.get("org") if isinstance(data, dict) else None
+    if not isinstance(org, str) or not org.strip():
+        raise ProjectFileError(f"{path} names no org; it should hold {shape}.")
+    return org.strip()
+
+
+def named_org() -> tuple[str, str, str | None] | None:
+    """Steps 1-3 of the org order: ``(org, org_from, file)``, or None."""
+    if _org_flag:
+        return _org_flag, "--org", None
+    for var in ORG_ENV_VARS:
+        value = (os.environ.get(var) or "").strip()
+        if value:
+            return value, var, None
+    path = find_project_file()
+    if path is not None:
+        return read_project_org(path), PROJECT_FILE, str(path)
+    return None
+
+
+class CLIAuthManager:
+    """API keys for the CLI: device-flow login, a profile per org, the env var."""
+
+    CONFIG_DIR = Path.home() / ".dataspring"
+    CREDENTIALS_FILE = CONFIG_DIR / "credentials.json"
+    CONFIG_FILE = CONFIG_DIR / "config.json"
+
+    def __init__(self):
+        """Initialize the auth manager."""
+        self._ensure_config_dir()
+
+    def _ensure_config_dir(self):
+        """Create config directory if it doesn't exist."""
+        self.CONFIG_DIR.mkdir(mode=0o700, parents=True, exist_ok=True)
+
+    # -- stored profiles -------------------------------------------------
+
+    def _load(self) -> dict:
+        """``{profiles: {org: {api_key, key_id, org_name, email}}}``; empty
+        for none, or for what an older CLI stored (Google credentials, or CLI
+        tokens): those sign nobody in now. A ``current`` an older CLI wrote
+        (``auth use``) is ignored: nothing machine-wide picks the org (D-99)."""
+        if not self.CREDENTIALS_FILE.exists():
+            return {}
+        try:
+            data = json.loads(self.CREDENTIALS_FILE.read_text())
+        except json.JSONDecodeError:
+            return {}
+        return data if isinstance(data.get("profiles"), dict) else {}
+
+    def _save(self, data: dict) -> None:
+        data.pop("current", None)
+        self.CREDENTIALS_FILE.write_text(json.dumps(data, indent=2))
+        self.CREDENTIALS_FILE.chmod(0o600)
+
+    def _add_profile(self, data: dict, entry: dict, email: str | None) -> None:
+        data.setdefault("profiles", {})[entry["org_id"]] = {
+            "api_key": entry["api_key"],
+            "key_id": entry.get("key_id"),
+            "org_name": entry.get("org_name") or entry["org_id"],
+            "email": email,
+        }
+
+    def profiles(self) -> dict[str, dict]:
+        return self._load().get("profiles", {})
+
+    # -- which org, which key (hub D-99) ---------------------------------
+
+    def resolve(self) -> ResolvedOrg:
+        """The org and key for this command, in the D-99 order (module doc).
+
+        Raises:
+            Refused: ``not_signed_in`` (no key at all, or none stored for the
+                org named), ``org_required`` (several stored, none named;
+                never a prompt), ``org_mismatch`` (``DATASPRING_API_KEY`` is
+                a key for another org than the one named).
+            ProjectFileError: a ``.forspring.json`` that names no org.
+        """
+        named = named_org()
+        env_key = os.environ.get(ENV_KEY)
+        profiles = self.profiles()
+
+        if env_key:
+            stored_org = next((org for org, p in profiles.items() if p.get("api_key") == env_key), None)
+            if named is None:
+                return ResolvedOrg(env_key, stored_org, FROM_KEY)
+            org, source, path = named
+            key_org = stored_org or self._key_org(env_key)
+            if key_org != org:
+                raise Refused(
+                    "org_mismatch",
+                    f"DATASPRING_API_KEY is a key for '{key_org}', but {source} names '{org}'.",
+                    f"Name '{key_org}', or set DATASPRING_API_KEY to a key for '{org}' "
+                    "(or unset it to use a stored key).",
+                )
+            return ResolvedOrg(env_key, org, source, path)
+
+        if not profiles:
+            raise _not_signed_in()
+        if named is not None:
+            org, source, path = named
+            profile = profiles.get(org)
+            if profile is None:
+                raise Refused(
+                    "not_signed_in",
+                    f"No key for '{org}' on this machine ({source} names it); "
+                    f"stored: {', '.join(sorted(profiles))}.",
+                    f"Run 'dataspring auth login' and approve {org}, or name one of the stored orgs.",
+                )
+            return ResolvedOrg(profile["api_key"], org, source, path)
+        if len(profiles) == 1:
+            org, profile = next(iter(profiles.items()))
+            return ResolvedOrg(profile["api_key"], org, FROM_ONLY_PROFILE)
+        raise Refused(
+            "org_required",
+            "Several organizations have keys on this machine and this command names none: "
+            f"{', '.join(sorted(profiles))}.",
+            f"Name one: {NAME_AN_ORG}.",
+        )
+
+    def _key_org(self, key: str) -> str | None:
+        """The org a key not stored here belongs to, as the server says.
+        Synchronous: :meth:`resolve` runs inside the async commands too."""
+        r = httpx.get(f"{_host()}/api/me", headers={"Authorization": f"Bearer {key}"}, timeout=15.0)
+        return self._me_answer(r).get("org_id")
+
+    def resolved_org(self) -> str | None:
+        """The org a command here would use, or None when none resolves."""
+        try:
+            return self.resolve().org_id
+        except AuthenticationError:
+            return None
+
+    # -- login -----------------------------------------------------------
+
+    async def login(self, *, all_orgs: bool = False, open_browser: bool = True, timeout: float = 600.0) -> "UserContext":
+        """The device flow: show a code, wait for approval in a browser, store the key(s)."""
+        verifier = secrets.token_urlsafe(48)
+        challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode("ascii")).digest()).rstrip(b"=").decode("ascii")
+        try:
+            r = httpx.post(f"{_host()}/api/device/code", json={
+                "code_challenge": challenge, "code_challenge_method": "S256",
+                "hostname": socket.gethostname(), "all_orgs": all_orgs,
+            }, timeout=15.0)
+        except httpx.HTTPError as e:
+            raise AuthenticationError(f"Could not reach DataSpring: {e}")
+        if r.status_code != 200:
+            raise AuthenticationError(f"Could not start the sign-in (HTTP {r.status_code})")
+        start = r.json()
+        # flush: an agent runs this with stdout redirected, where Python
+        # buffers it; unflushed, the code appeared only after the CLI exited,
+        # too late for anyone to approve it (tick 373).
+        print(f"To sign in, open {start['verification_uri']} and enter the code {start['user_code']}")
+        print(f"  (or open {start['verification_uri_complete']})", flush=True)
+        if open_browser:
+            try:
+                webbrowser.open(start["verification_uri_complete"])
+            except Exception:
+                pass  # no browser on this machine: the URL above is enough
+
+        interval = float(start.get("interval", 5))
+        deadline = time.monotonic() + min(timeout, float(start.get("expires_in", 600)))
+        while time.monotonic() < deadline:
+            time.sleep(interval)
+            r = httpx.post(f"{_host()}/api/device/token", json={"device_code": start["device_code"], "code_verifier": verifier}, timeout=15.0)
+            if r.status_code == 200:
+                body = r.json()
+                data = self._load()
+                self._add_profile(data, body, body.get("email"))
+                for other in body.get("other_orgs") or []:
+                    self._add_profile(data, other, body.get("email"))
+                self._save(data)
+                if body.get("email"):
+                    self._save_config({"email": body["email"]})
+                # The approved org's key: the one this login is about, whatever
+                # else is stored.
+                return self._context(await self._me(body["api_key"]))
+            error = (r.json() or {}).get("error") if r.headers.get("content-type", "").startswith("application/json") else None
+            if error in ("authorization_pending", "temporarily_unavailable"):
+                continue  # temporarily_unavailable: the Forspring account did not answer; the approval waits
+            if error == "slow_down":
+                interval += 5
+                continue
+            if error == "access_denied":
+                raise AuthenticationError("The sign-in was denied in the browser.")
+            raise AuthenticationError("The sign-in expired or failed. Run 'dataspring auth login' again.")
+        raise AuthenticationError("The sign-in timed out. Run 'dataspring auth login' again.")
+
+    async def store_key(self, key: str) -> "UserContext":
+        """``--key``: keep a key you already have (CI). The server says which org it is for."""
+        me = await self._me(key)
+        data = self._load()
+        self._add_profile(data, {"api_key": key, "key_id": None, "org_id": me["org_id"], "org_name": me.get("org_name")}, me.get("email"))
+        self._save(data)
+        return self._context(me)
+
+    # -- using the key ---------------------------------------------------
+
+    def get_access_token(self) -> str:
+        """The key this command sends: ``DATASPRING_API_KEY`` if set, else the
+        stored key for the org :meth:`resolve` names.
+
+        Raises:
+            Refused: not signed in, no org named among several, or a mismatch
+        """
+        return self.resolve().key
+
+    async def _me(self, key: str) -> dict:
+        async with httpx.AsyncClient(timeout=15.0) as client:
+            r = await client.get(f"{_host()}/api/me", headers={"Authorization": f"Bearer {key}"})
+        return self._me_answer(r)
+
+    @staticmethod
+    def _me_answer(r: httpx.Response) -> dict:
+        """``GET /api/me``'s body, or the refusal it answered with (D-99)."""
+        if r.status_code == 200:
+            return r.json()
+        try:
+            body = r.json()
+        except ValueError:
+            body = None
+        refusal = from_body(body)
+        if refusal is not None:
+            raise Refused(refusal.reason, refusal.note, refusal.fix)
+        if r.status_code == 401:
+            raise _not_signed_in("This key is unknown, revoked or expired.")
+        # ``note`` since tick 3sb, ``detail`` from older servers and FastAPI.
+        detail = (body.get("note") or body.get("detail")) if isinstance(body, dict) else None
+        if r.status_code == 403:
+            text = str(detail or "Access denied")
+            raise Refused(
+                classify(text) or "not_a_member", text,
+                "An owner or admin of the org fixes this at https://account.forspring.ai; "
+                "or run 'dataspring auth login' again.",
+            )
+        if r.status_code == 503:
+            raise Refused("account_unavailable", str(detail or "The Forspring account cannot be reached."),
+                          EN["account_unavailable"]["fix"])
+        raise AuthenticationError(f"Failed to resolve user context (HTTP {r.status_code})")
+
+    @staticmethod
+    def _context(me: dict) -> "UserContext":
+        org_id = me.get("org_id")
+        return UserContext(uid=me["uid"], email=me.get("email") or "", org_id=org_id,
+                           org_name=me.get("org_name") or org_id, role=me.get("org_role"))
+
+    async def get_user(self) -> "UserContext":
+        """The person and the key's org, as ``GET /api/me`` reports them."""
+        return self._context(await self._me(self.get_access_token()))
+
+    async def whoami(self) -> dict:
+        """D-99's ``whoami --json``: the person, the org, where the org came
+        from (:class:`ResolvedOrg`'s ``org_from``), the role."""
+        resolved = self.resolve()
+        me = await self._me(resolved.key)
+        out = {
+            "person": me.get("email"),
+            "org": me.get("org_id"),
+            "org_name": me.get("org_name"),
+            "org_from": resolved.org_from,
+            "role": me.get("org_role"),
+        }
+        if resolved.org_file:
+            out["org_file"] = resolved.org_file
+        return out
+
+    async def logout(self):
+        """Revoke every stored key on the server, then forget them."""
+        for profile in self.profiles().values():
+            if not profile.get("key_id"):
+                continue  # a --key key: not ours to revoke, just forgotten
+            try:
+                httpx.delete(f"{_host()}/api/keys/{profile['key_id']}",
+                             headers={"Authorization": f"Bearer {profile['api_key']}"}, timeout=10.0)
+            except httpx.HTTPError:
+                pass  # offline: revoke it from /api/keys later
+        if self.CREDENTIALS_FILE.exists():
+            self.CREDENTIALS_FILE.unlink()
+        if self.CONFIG_FILE.exists():
+            self.CONFIG_FILE.unlink()
+
+    def is_logged_in(self) -> bool:
+        """A key exists to use: ``DATASPRING_API_KEY`` or a stored one (which
+        one a command uses is :meth:`resolve`'s)."""
+        return bool(os.environ.get(ENV_KEY)) or bool(self.profiles())
+
+    def get_stored_email(self) -> str | None:
+        """Get stored email from config (doesn't validate the key)."""
+        return self._load_config().get("email")
+
+    def _save_config(self, data: dict):
+        """Save config data (non-sensitive)."""
+        existing = {}
+        if self.CONFIG_FILE.exists():
+            try:
+                existing = json.loads(self.CONFIG_FILE.read_text())
+            except json.JSONDecodeError:
+                pass
+        existing.update(data)
+        self.CONFIG_FILE.write_text(json.dumps(existing, indent=2))
+
+    def _load_config(self) -> dict:
+        """Load config data."""
+        if not self.CONFIG_FILE.exists():
+            return {}
+        try:
+            return json.loads(self.CONFIG_FILE.read_text())
+        except json.JSONDecodeError:
+            return {}
+
+
+# Global auth manager instance
+auth_manager = CLIAuthManager()

{dataspring_cli-0.4.0 → dataspring_cli-0.4.2}/cli/bundled_manifest.py

@@ -6,7 +6,7 @@ the server's to say whether the server has operations this CLI does not
 know. tests/test_skills_surface.py asserts it is current.
 """
 
-MANIFEST_HASH = "386b42bdef87f3cc5aabaa69e1aec1b327b3a2f3f5dc5559eda1cf91a40ae48c"
+MANIFEST_HASH = "b9fdc845fd9d3a22cea19e234b330e7e41d17f5d5ba6b5e1c713123d38109a6d"
 TOOL_KEYS = (
     "business_context_edit",
     "semantic_model_edit",

{dataspring_cli-0.4.0 → dataspring_cli-0.4.2}/cli/contract.py

@@ -636,6 +636,18 @@ class DeployDatacoreAction(DispatchParams):
         ),
     )
     note: str | None = Field(default=None, description="Why, recorded on the learned trail")
+    then_build: bool = Field(
+        default=False,
+        description=(
+            "When the deploy changed any file under models/, also queue a models-only build (the `build` action) "
+            "of the newly deployed snapshot on the raw tables already loaded; build_select narrows it. "
+            "Without it, a deploy that changed models answers with the command that does it"
+        ),
+    )
+    build_select: str | None = Field(
+        default=None,
+        description="With then_build: the dbt selector to rebuild (default: every model, `fqn:*`)",
+    )
 
 
 class RunWindowParams(DispatchParams):
@@ -656,7 +668,11 @@ class RunPipelineAction(DispatchParams):
     pipeline: str = Field(description="Pipeline name (a deployed pipelines/<name>.yaml)")
     window: RunWindowParams | None = Field(
         default=None,
-        description="A date window to load instead of the pipeline's own; wider than backfill_chunk becomes a chunked backfill",
+        description=(
+            "A date window to load instead of the pipeline's own; wider than backfill_chunk becomes a chunked backfill. "
+            "Both ends are inclusive days, and so is every chunk; a resource whose API reads its end bound as exclusive "
+            "declares `window.end: exclusive` in the pipeline and is sent the day after each chunk's last day"
+        ),
     )
     cursor: RunCursorParams | None = Field(default=None, description="{from: <value>}: a cursor to re-pull from")
     backfill_chunk: str | None = Field(
@@ -665,6 +681,27 @@ class RunPipelineAction(DispatchParams):
     )
 
 
+class BuildModelsAction(DispatchParams):
+    """Rebuild the deployed dbt models on the raw tables already loaded: no resource is loaded."""
+
+    action: Literal["build"]
+    pipeline: str | None = Field(
+        default=None,
+        description=(
+            "A deployed pipeline whose `then` block names what to build (its dbt_select, dbt_exclude and tests). "
+            "Omit to build every model of the deployed project"
+        ),
+    )
+    select: str | None = Field(
+        default=None,
+        description=(
+            "A dbt selector (`dbt build --select`), e.g. `marts.finance+` or `+fct_postings`; replaces the "
+            "pipeline's dbt_select and dbt_exclude. Default: the pipeline's then.dbt_select, or every model "
+            "(`fqn:*`) when no pipeline is named"
+        ),
+    )
+
+
 class ResetPipelineAction(DispatchParams):
     action: Literal["reset"]
     pipeline: str = Field(description="The pipeline whose dlt state and raw tables to remove")
@@ -674,8 +711,23 @@ class ResetPipelineAction(DispatchParams):
     )
 
 
+class CancelRunAction(DispatchParams):
+    action: Literal["cancel"]
+    run_id: str = Field(
+        description=(
+            "The queued or running run to stop, or a backfill's parent run (its running child "
+            "is stopped and no further chunk starts); ids from dataspring://datacore/runs"
+        ),
+    )
+
+
 DatacoreRunAction = Annotated[
-    CheckDatacoreAction | DeployDatacoreAction | RunPipelineAction | ResetPipelineAction,
+    CheckDatacoreAction
+    | DeployDatacoreAction
+    | RunPipelineAction
+    | BuildModelsAction
+    | ResetPipelineAction
+    | CancelRunAction,
     Field(discriminator="action"),
 ]
 
@@ -701,8 +753,10 @@ _PERIOD_DOC = (
 
 _COMPARE_TO_DOC = (
     "Compare the window against the one before it (previous_period, stepped "
-    "back by whole calendar periods when the window is whole ones) or the same "
-    "window a year earlier (same_period_last_year). The deltas come back "
+    "back by whole calendar periods when the window is whole ones, and by as "
+    "many periods as it touches, keeping its position, when it cuts a period "
+    "short: a year to date compares with the same days a year earlier) or the "
+    "same window a year earlier (same_period_last_year). The deltas come back "
     "BESIDE the values - each metric column gains <metric>__previous, "
     "<metric>__delta and <metric>__delta_pct - so there is no second result "
     "set to line up and no arithmetic to do. `comparison_period` says which "
@@ -1108,7 +1162,8 @@ class RunSqlParams(DispatchParams):
         description=(
             "One SQL statement (BigQuery Standard SQL on a managed warehouse). "
             "Name tables as <org>_marts.<table>, <org>_core.<table> or "
-            "<org>_staging.<table>; the identity it runs as can read those and "
+            "<org>_staging.<table>, <org> being the organization id with every "
+            "hyphen as an underscore (acme-dk is acme_dk_marts); the identity it runs as can read those and "
             "nothing else, so a write or a reach outside them is refused by "
             "the warehouse."
         )
@@ -1150,9 +1205,10 @@ class CreateTenantAction(DispatchParams):
     slug: str = Field(
         description=(
             "The tenant id, and therefore the organization id and the name in "
-            "every Google Cloud resource it owns (t-<slug>@, <slug>_raw, "
+            "every Google Cloud resource it owns, each derived from it by "
+            "services.tenants (t-<slug>@, <slug>_raw with hyphens as underscores, "
             "datacore-runner--<slug>, gs://dataspring-tenants/<slug>/). "
-            "Lower-case [a-z0-9-], at most 20 characters. Choose it "
+            "Lower-case [a-z0-9-], at most 63 characters. Choose it "
             "deliberately: it cannot be renamed afterwards."
         )
     )