dataspring-cli 0.3.0__py3-none-any.whl

cli/_skills/dataspring-correct/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: dataspring-correct
+description: How to handle a correction — where the fact belongs, what this user may change, and what needs a dbt change instead. Use when a user disputes a number, says a metric means something else, tells you a caveat, asks what you computed, or asks you to remember a query.
+---
+
+# Correcting DataSpring
+
+A correction is a fact arriving late. Find its home, write it where future
+readers see it, and be exact about what changed.
+
+## 1. First explain, never guess
+
+Before agreeing anything is wrong, call `explain_query`; with no
+`params` it explains this session's last query. Quote back the metric it
+resolved, the filters applied (standing preferences included), the effective
+window, and briefly the SQL. Often the number is right and the disagreement
+is about which metric was meant — ambiguity, not a correction. Never
+apologise for a number you have not re-read.
+
+If that query returned an EMPTY or null result, try the other query shape —
+grouped instead of filtered, or vice versa — before reporting that there is
+no data. Explaining a null is not an answer.
+
+## 2. Classify the fact
+
+| Type of fact | Goes in... |
+|---|---|
+| One metric's meaning, computation, unit, source rollup | That metric's description |
+| One metric's known caveat (bug warning, temporal discontinuity, methodology change) | That metric's description |
+| One metric's standing filter rule ("for B2B, pair with...") | That metric's description |
+| One dimension's allowed values, derivation, "use this not raw" steering | That dimension's description, via `semantic_model_edit` |
+| One source's freshness, format quirks, "field X is 100% NULL" | That source's description |
+| Cross-cutting derivation ("B2B is derived in event_segment, never raw event_type") | `business_context` |
+| Org-level system inventory (what's connected, what's sunset) | `business_context` |
+| Org-level coverage gap ("we don't sync system X") | `business_context` |
+| Region, dbt layout, project-level operational pointers | `business_context` |
+| Findings, analysis results, history | NOT in the context layer at all |
+| Per-metric definition logic | NOT in context — lives in the dbt model SQL |
+| The user's own standing intent ("always exclude Direct for me") | A personal preference, via `update_user_preferences` |
+| A question and the query that correctly answers it, confirmed by the user | `verified_query_edit` record, scope `user` |
+
+A verified query is scope `org` only on an admin's say-so. When torn between
+an entity description and `business_context`, choose the entity.
+
+## 3. Offer only what this user may change
+
+Read the WHAT YOU MAY CHANGE block — this user's targets, nothing else. An
+admin gets the systemic fix; a member or viewer a personal preference,
+verified query or quick metric, which fixes their experience immediately.
+Both are complete answers: never route a user elsewhere, never offer what
+ends in a permission error. §7 is the same split for a coverage gap.
+
+## 4. Ownership and ceremony
+
+**DataSpring owns TEXT.** Descriptions, labels and `business_context` write
+immediately, no confirmation, even on dbt-imported entities. Always report
+what changed AND how to undo it:
+
+> Learned: `total_revenue` is gross of VAT.
+> Live now, and survives manifest uploads. Undo with "undo that".
+
+**dbt owns COMPUTATION.** On an IMPORTED metric or model, never promise to
+change how a number is computed. The update returns `proposal: true` with an
+`impact` block and a `dbt_yaml` snippet — nothing was written. Show the
+dashboards affected and the before/after sample:
+
+> Changing `total_revenue` to exclude VAT moves 4 dashboards and takes last
+> month from 123k to 94k.
+
+Then present the YAML verbatim and say what applies it: commit it to dbt —
+it lands on the next manifest upload. Never offer to make the change or ask
+whether to "proceed"; you cannot apply it, and asking implies you can. You
+CAN offer: the text edit, a new metric, a quick metric.
+
+For a NATIVE metric, `requires_confirmation` comes back with the impact on
+the first call; show it and stop. Only the user's NEXT message confirms — a
+validation error, a retry prompt or your own reasoning is not the user, and
+a `confirmed` sent in the same turn is refused. Probe with
+`metric_edit` action `impact` and the verdict comes back with it:
+imported gets the dbt YAML, native the confirmation requirement. Never a
+menu of options with no verdict.
+
+## 5. Metrics that are known to be wrong
+
+When the real fix needs dbt work, do not leave consumers unwarned — write
+the caveat into the description NOW, house style:
+
+> KNOWN ISSUE: measured to the first resolution timestamp only, so tickets
+> that were reopened and resolved again are undercounted — not yet fixed.
+
+Pair it with the dbt YAML proposal for the fix, same turn.
+
+## 6. Undo
+
+"undo that" is `learned_edit` undo with no `learning_id` — it reverts
+the caller's most recent reversible entry; name what was restored. Its list
+action shows what changed and by whom. A proposal cannot be undone — nothing
+was written; say that, not "done".
+
+## 7. Coverage gaps
+
+The declaration is unconditional. Whatever the role, open with the verbatim
+SEMANTIC LAYER GAP block, then give the number as an ephemeral computation
+from rows you fetched: name the metrics it came from, and say it is
+not a defined metric. Only the DURABLE offer differs.
+
+- **Admin / owner** — a real definition, this turn and unasked.
+  Ask `metric_edit` for a `preview`, then quote the `dbt_yaml` in full. A preview writes nothing, so needs no permission; only create needs
+  a yes — a native, additive entity that moves no existing number.
+- **Member / viewer** — a quick metric via `quick_metric_edit` for a
+  recurring need (query it with the `qm:` prefix); an ephemeral computation
+  alone for a one-off. Never an org-scoped offer.
+
+Bad, for an admin: a business heading, an inline ratio, an offer to save a
+quick metric — or to propose a definition, with none shown. Good: the
+declaration, the labelled ratio, the delegated preview's dbt YAML in full,
+then "create it?". Raw SQL is never an option on any path.
+
+## 8. Do not
+
+- Do not describe a queue, review step or approval state; none exist.
+- Do not record a verified query on your own judgement — only when confirmed.
+- Do not store numbers, results or findings in a description, preference or
+  memory — they go stale tomorrow; facts do not.

cli/auth.py

@@ -0,0 +1,375 @@
+"""CLI Authentication - Google OAuth flow and token management.
+
+Handles:
+- Interactive OAuth login via browser
+- Token storage and refresh
+- User context retrieval from ``GET /api/me``
+
+This module is the only place the CLI touches Google directly, and only for
+the OAuth login flow. Who the user is - and which org they are in - is the
+server's answer to ``/api/me``; nothing here opens Firestore.
+"""
+
+import json
+import secrets
+import webbrowser
+from dataclasses import dataclass
+from datetime import datetime
+from http.server import HTTPServer, BaseHTTPRequestHandler
+from pathlib import Path
+from threading import Thread
+from typing import Any
+from urllib.parse import parse_qs, urlparse
+
+import httpx
+from google.auth.transport.requests import Request
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import Flow
+
+
+@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
+    org_name: str
+    role: str
+
+
+class AuthenticationError(Exception):
+    """Raised when authentication fails or user is not logged in."""
+
+    pass
+
+
+class CLIAuthManager:
+    """Manages OAuth tokens for CLI sessions.
+
+    Handles the complete OAuth flow:
+    1. Start local callback server
+    2. Open browser to Google consent screen
+    3. Receive callback with auth code
+    4. Exchange for tokens
+    5. Store refresh token locally
+    6. Resolve the user's org context from the API (``/api/me``)
+    """
+
+    CONFIG_DIR = Path.home() / ".dataspring"
+    CREDENTIALS_FILE = CONFIG_DIR / "credentials.json"
+    CONFIG_FILE = CONFIG_DIR / "config.json"
+
+    # OAuth configuration - Desktop app client for CLI login flow
+    # Created in Google Cloud Console > APIs & Services > Credentials
+    # Application type: Desktop app, Name: DataSpring CLI
+    CLI_OAUTH_CLIENT_ID = "910366018047-ekplje5p344nbq60o8vqk88378turj52.apps.googleusercontent.com"
+    CLI_OAUTH_CLIENT_SECRET = "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"
+
+    SCOPES = [
+        "openid",
+        "https://www.googleapis.com/auth/userinfo.email",
+        "https://www.googleapis.com/auth/userinfo.profile",
+    ]
+
+    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)
+
+    def _get_oauth_config(self) -> dict[str, Any]:
+        """Get OAuth client configuration for desktop app flow."""
+        return {
+            "installed": {
+                "client_id": self.CLI_OAUTH_CLIENT_ID,
+                "client_secret": self.CLI_OAUTH_CLIENT_SECRET,
+                "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+                "token_uri": "https://oauth2.googleapis.com/token",
+                "redirect_uris": ["http://localhost"],
+            }
+        }
+
+    def _save_credentials(self, credentials: Credentials):
+        """Save credentials to file with restricted permissions."""
+        data = {
+            "token": credentials.token,
+            "refresh_token": credentials.refresh_token,
+            "token_uri": credentials.token_uri,
+            "client_id": credentials.client_id,
+            "client_secret": credentials.client_secret,
+            "scopes": list(credentials.scopes) if credentials.scopes else None,
+            "expiry": credentials.expiry.isoformat() if credentials.expiry else None,
+        }
+
+        self.CREDENTIALS_FILE.write_text(json.dumps(data, indent=2))
+        self.CREDENTIALS_FILE.chmod(0o600)
+
+    def _load_credentials(self) -> Credentials | None:
+        """Load credentials from file."""
+        if not self.CREDENTIALS_FILE.exists():
+            return None
+
+        try:
+            data = json.loads(self.CREDENTIALS_FILE.read_text())
+            expiry = None
+            if data.get("expiry"):
+                expiry = datetime.fromisoformat(data["expiry"])
+
+            return Credentials(
+                token=data.get("token"),
+                refresh_token=data.get("refresh_token"),
+                token_uri=data.get("token_uri"),
+                client_id=data.get("client_id"),
+                client_secret=data.get("client_secret"),
+                scopes=data.get("scopes"),
+                expiry=expiry,
+            )
+        except (json.JSONDecodeError, KeyError):
+            return None
+
+    def _refresh_if_needed(self, credentials: Credentials) -> Credentials:
+        """Refresh credentials if expired."""
+        if credentials.expired and credentials.refresh_token:
+            credentials.refresh(Request())
+            self._save_credentials(credentials)
+        return credentials
+
+    async def login(self) -> UserContext:
+        """Interactive OAuth login flow.
+
+        Opens browser for Google consent, then looks up user context.
+
+        Returns:
+            UserContext with user info and org context
+
+        Raises:
+            AuthenticationError: If login fails
+        """
+        config = self._get_oauth_config()
+
+        # Create flow with redirect to localhost
+        flow = Flow.from_client_config(
+            config,
+            scopes=self.SCOPES,
+            redirect_uri="http://localhost:8085/callback",
+        )
+
+        # Generate authorization URL with state for CSRF protection
+        state = secrets.token_urlsafe(32)
+        auth_url, _ = flow.authorization_url(
+            access_type="offline",
+            include_granted_scopes="true",
+            prompt="consent",
+            state=state,
+        )
+
+        # Start local callback server
+        auth_code = None
+        received_state = None
+
+        class CallbackHandler(BaseHTTPRequestHandler):
+            def do_GET(self):
+                nonlocal auth_code, received_state
+                parsed = urlparse(self.path)
+
+                if parsed.path == "/callback":
+                    params = parse_qs(parsed.query)
+                    auth_code = params.get("code", [None])[0]
+                    received_state = params.get("state", [None])[0]
+
+                    self.send_response(200)
+                    self.send_header("Content-type", "text/html")
+                    self.end_headers()
+                    self.wfile.write(
+                        b"<html><body><h1>Login successful!</h1>"
+                        b"<p>You can close this window and return to the terminal.</p>"
+                        b"</body></html>"
+                    )
+                else:
+                    self.send_response(404)
+                    self.end_headers()
+
+            def log_message(self, format, *args):
+                pass  # Suppress server logs
+
+        server = HTTPServer(("localhost", 8085), CallbackHandler)
+
+        # Run server in background thread
+        server_thread = Thread(target=lambda: server.handle_request())
+        server_thread.start()
+
+        # Open browser
+        print("Opening browser for login...")
+        webbrowser.open(auth_url)
+
+        # Wait for callback
+        server_thread.join(timeout=120)
+
+        if not auth_code:
+            raise AuthenticationError("Login timeout or failed to receive auth code")
+
+        if received_state != state:
+            raise AuthenticationError("Invalid state parameter - possible CSRF attack")
+
+        # Exchange code for tokens
+        flow.fetch_token(code=auth_code)
+        credentials = flow.credentials
+
+        # Save credentials
+        self._save_credentials(credentials)
+
+        # Get user context
+        return await self._get_user_context(credentials)
+
+    async def _get_user_context(self, credentials: Credentials) -> UserContext:
+        """Get user context from email in token."""
+        # Get user email from Google userinfo
+        async with httpx.AsyncClient() as client:
+            resp = await client.get(
+                "https://www.googleapis.com/oauth2/v3/userinfo",
+                headers={"Authorization": f"Bearer {credentials.token}"},
+            )
+            if resp.status_code != 200:
+                raise AuthenticationError(f"Failed to get user info: {resp.text}")
+            user_info = resp.json()
+
+        email = user_info.get("email")
+        if not email:
+            raise AuthenticationError("Email not found in OAuth response")
+
+        # Save email to config for future use
+        self._save_config({"email": email})
+
+        # Resolve full user context via backend API — no local Firestore/ADC required
+        from settings import get_settings
+        api_base = get_settings().mcp_server_base_url  # e.g. https://dataspring.app/api
+
+        async with httpx.AsyncClient(timeout=15.0) as api_client:
+            me_resp = await api_client.get(
+                f"{api_base}/me",
+                headers={"Authorization": f"Bearer {credentials.token}"},
+            )
+            if me_resp.status_code == 401:
+                raise AuthenticationError(
+                    "Authentication failed — token rejected by server"
+                )
+            if me_resp.status_code == 403:
+                detail = me_resp.json().get("detail", "Access denied")
+                raise AuthenticationError(detail)
+            if me_resp.status_code != 200:
+                raise AuthenticationError(
+                    f"Failed to resolve user context (HTTP {me_resp.status_code})"
+                )
+            data = me_resp.json()
+
+        return UserContext(
+            uid=data["uid"],
+            email=data["email"] or email,
+            org_id=data["org_id"],
+            org_name=data.get("org_name") or data["org_id"],
+            role=data["org_role"],
+        )
+
+    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 {}
+
+    async def get_user(self) -> UserContext:
+        """Get current user, refreshing token if needed.
+
+        Returns:
+            UserContext with user info and org context
+
+        Raises:
+            AuthenticationError: If not logged in or token refresh fails
+        """
+        credentials = self._load_credentials()
+        if not credentials:
+            raise AuthenticationError("Not logged in. Run 'dataspring login' first.")
+
+        if not credentials.valid:
+            if credentials.refresh_token:
+                try:
+                    credentials = self._refresh_if_needed(credentials)
+                except Exception as e:
+                    raise AuthenticationError(f"Failed to refresh token: {e}")
+            else:
+                raise AuthenticationError(
+                    "Token expired and no refresh token. Run 'dataspring login' again."
+                )
+
+        return await self._get_user_context(credentials)
+
+    async def logout(self):
+        """Clear stored credentials and config."""
+        if self.CREDENTIALS_FILE.exists():
+            self.CREDENTIALS_FILE.unlink()
+        if self.CONFIG_FILE.exists():
+            self.CONFIG_FILE.unlink()
+
+    def is_logged_in(self) -> bool:
+        """Check if user has valid credentials."""
+        credentials = self._load_credentials()
+        if not credentials:
+            return False
+        if credentials.expired and not credentials.refresh_token:
+            return False
+        return True
+
+    def get_stored_email(self) -> str | None:
+        """Get stored email from config (doesn't validate token)."""
+        config = self._load_config()
+        return config.get("email")
+
+    def get_access_token(self) -> str:
+        """Get a valid access token, refreshing if needed.
+
+        Returns:
+            Valid access token string
+
+        Raises:
+            AuthenticationError: If not logged in or token refresh fails
+        """
+        credentials = self._load_credentials()
+        if not credentials:
+            raise AuthenticationError("Not logged in. Run 'dataspring login' first.")
+
+        if not credentials.valid:
+            if credentials.refresh_token:
+                try:
+                    credentials = self._refresh_if_needed(credentials)
+                except Exception as e:
+                    raise AuthenticationError(f"Failed to refresh token: {e}")
+            else:
+                raise AuthenticationError(
+                    "Token expired and no refresh token. Run 'dataspring login' again."
+                )
+
+        return credentials.token
+
+
+# Global auth manager instance
+auth_manager = CLIAuthManager()

cli/bundled_manifest.py

@@ -0,0 +1,36 @@
+"""GENERATED by `python -m services.skill_tables`; do not edit.
+
+The hash of the dispatch manifest this CLI was built against, the one
+``GET /api/dispatch`` answers. ``dataspring --version`` compares it with
+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 = "76c44516f0729b5b4c1d4b8f17ebd7a3ffbd63b94dae6308c740a4af62db1811"
+TOOL_KEYS = (
+    "dashboard_edit",
+    "widget_edit",
+    "page_edit",
+    "section_edit",
+    "business_context_edit",
+    "semantic_model_edit",
+    "metric_edit",
+    "quick_metric_edit",
+    "report_edit",
+    "learned_edit",
+    "verified_query_edit",
+    "warehouse_edit",
+    "query_metrics",
+    "explain_query",
+    "update_context",
+    "export_data",
+    "import_manifest",
+    "render_dashboard",
+    "render_widget",
+    "switch_organization",
+    "submit_error_report",
+    "secret_edit",
+    "run_sql",
+    "datacore_edit",
+    "datacore_run",
+)