dataspring-cli 0.3.0__py3-none-any.whl

cli/version.py

@@ -0,0 +1,123 @@
+"""``dataspring --version``: the CLI's version, and its skew against the server.
+
+The wheel is built against one dispatch manifest (``cli/bundled_manifest.py``
+carries its hash). A deployed server may be newer: it then has operations or
+fields this CLI does not know, and the only way the CLI learns that is by
+comparing hashes with ``GET /api/dispatch`` (decision D19). Not logged in,
+or the server unreachable: the version still prints; the comparison is a
+note, never a failure.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from importlib.metadata import PackageNotFoundError, version as _dist_version
+from pathlib import Path
+
+import httpx
+
+DIST = "dataspring-cli"
+UPGRADE_HINT = "run `dataspring upgrade`"
+
+#: Where the server's hash is remembered between commands: next to the
+#: credentials, keyed by a fingerprint of the access token, so it is fetched
+#: once per login session (a token lives about an hour) and not per command.
+CACHE_FILE = Path.home() / ".dataspring" / "manifest-check.json"
+CACHE_TTL_SECONDS = 3600
+
+
+def cli_version() -> str:
+    try:
+        return _dist_version(DIST)
+    except PackageNotFoundError:
+        return "unknown"
+
+
+def bundled_hash() -> str | None:
+    try:
+        from cli.bundled_manifest import MANIFEST_HASH
+    except ImportError:
+        return None
+    return MANIFEST_HASH
+
+
+def fetch_server_hash(base: str, token: str) -> str:
+    """The manifest hash ``GET /api/dispatch`` answers, bearer-authenticated."""
+    with httpx.Client(timeout=15.0) as client:
+        response = client.get(f"{base}/api/dispatch", headers={"Authorization": f"Bearer {token}"})
+    response.raise_for_status()
+    return response.json()["hash"]
+
+
+def session_server_hash(base: str, token: str) -> str | None:
+    """The server's manifest hash for this login session, fetched at most
+    once per token (and once an hour); ``None`` when it cannot be read."""
+    fingerprint = hashlib.sha256(token.encode("utf-8")).hexdigest()[:16]
+    try:
+        cached = json.loads(CACHE_FILE.read_text(encoding="utf-8"))
+        if cached.get("token") == fingerprint and time.time() - float(cached.get("at", 0)) < CACHE_TTL_SECONDS:
+            return cached.get("hash")
+    except (OSError, ValueError, AttributeError):
+        pass
+    try:
+        server = fetch_server_hash(base, token)
+    except (httpx.HTTPError, KeyError, ValueError):
+        return None
+    try:
+        CACHE_FILE.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        CACHE_FILE.write_text(json.dumps({"token": fingerprint, "hash": server, "at": time.time()}), encoding="utf-8")
+    except OSError:
+        pass
+    return server
+
+
+_hinted = False
+
+
+def skew_hint(base: str, token: str) -> str | None:
+    """The one line a command prints when the server's manifest differs from
+    the one this CLI was built against; once per process, ``None`` when in
+    sync or when the server could not be compared."""
+    global _hinted
+    if _hinted:
+        return None
+    server = session_server_hash(base, token)
+    bundled = bundled_hash()
+    if server is None or bundled is None or server == bundled:
+        return None
+    _hinted = True
+    return skew_lines(server, bundled)[1]
+
+
+def _short(value: str | None) -> str:
+    return value[:12] if value else "(none)"
+
+
+def skew_lines(server: str | None, bundled: str | None, *, server_note: str | None = None) -> list[str]:
+    """The manifest lines of the version report."""
+    if server_note:
+        return [f"manifest: cli {_short(bundled)}; {server_note}"]
+    if server == bundled:
+        return [f"manifest: server {_short(server)}, cli {_short(bundled)} (in sync)"]
+    return [
+        f"manifest: server {_short(server)}, cli {_short(bundled)}",
+        f"the server has operations or fields this CLI does not know; {UPGRADE_HINT}",
+    ]
+
+
+def version_report(*, base: str, token: str | None) -> list[str]:
+    """Everything ``--version`` prints, one entry per line."""
+    lines = [f"{DIST} {cli_version()}"]
+    bundled = bundled_hash()
+    if token is None:
+        lines += skew_lines(None, bundled, server_note="log in to compare with the server")
+        return lines
+    try:
+        server = fetch_server_hash(base, token)
+    except (httpx.HTTPError, KeyError, ValueError) as e:
+        lines += skew_lines(None, bundled, server_note=f"server not compared ({type(e).__name__})")
+        return lines
+    lines += skew_lines(server, bundled)
+    return lines

dataspring_cli-0.3.0.dist-info/METADATA

@@ -0,0 +1,202 @@
+Metadata-Version: 2.5
+Name: dataspring-cli
+Version: 0.3.0
+Summary: DataSpring CLI - Query metrics and manage dashboards from the terminal
+Project-URL: Homepage, https://dataspring.app
+Project-URL: Documentation, https://dataspring.app/docs
+Author-email: DataSpring <support@dataspring.app>
+License: Proprietary
+Keywords: analytics,bi,dashboard,dbt,metricflow,metrics
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.12
+Requires-Dist: google-auth-oauthlib>=1.4.1
+Requires-Dist: google-auth>=2.57.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic-settings>=2.15.0
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typer>=0.27.1
+Description-Content-Type: text/markdown
+
+# DataSpring CLI
+
+Query metrics and manage dashboards from the terminal.
+
+## Installation
+
+### Using uv (Recommended)
+
+```bash
+# Install from local build
+uv tool install ./backend
+
+# Or install from GitHub (once published)
+uv tool install git+https://github.com/dataspring/dataspring#subdirectory=backend
+```
+
+### Using pip
+
+```bash
+pip install ./backend
+```
+
+## Quick Start
+
+```bash
+# Login with Google OAuth
+dataspring login
+
+# Check who you're logged in as
+dataspring whoami
+
+# List available metrics
+dataspring metrics list
+
+# Query metrics
+dataspring query -m total_revenue -g month --limit 5
+
+# Get visualization suggestions
+dataspring query -m total_revenue -g month --suggest-viz
+
+# Export to JSON
+dataspring query -m total_revenue --format json > data.json
+```
+
+## Commands
+
+### Authentication
+
+```bash
+dataspring login          # Login via Google OAuth (opens browser)
+dataspring whoami         # Show current user and organization
+dataspring logout         # Clear stored credentials
+dataspring org list       # List your organizations
+dataspring org switch ID  # Switch to a different organization
+```
+
+### Querying Metrics
+
+```bash
+# List available metrics
+dataspring metrics list
+dataspring metrics list --format json
+
+# Get metric details
+dataspring metrics show total_revenue
+
+# Query data
+dataspring query -m revenue -g month                    # Monthly revenue
+dataspring query -m revenue -d region --limit 10        # By region
+dataspring query -m revenue -m orders -g week           # Multiple metrics
+dataspring query -m revenue --start 2024-01-01 --end 2024-12-31
+
+# With visualization suggestion
+dataspring query -m revenue -g month --suggest-viz
+
+# List dimensions
+dataspring dimensions list
+```
+
+### Dashboard Management
+
+```bash
+# List dashboards
+dataspring dashboards list
+
+# Show dashboard details
+dataspring dashboards show DASHBOARD_ID
+
+# Create a new dashboard
+dataspring dashboards create "My Dashboard"
+dataspring dashboards create "Team Metrics" -v org  # Visible to team
+
+# Delete a dashboard
+dataspring dashboards delete DASHBOARD_ID
+dataspring dashboards delete DASHBOARD_ID --yes     # Skip confirmation
+```
+
+### Manifest Management (Admin Only)
+
+```bash
+# View manifest status
+dataspring manifest status
+
+# Export manifest
+dataspring manifest export -o manifest.yaml
+
+# Import manifest
+dataspring manifest upload manifest.yaml
+dataspring manifest upload manifest.yaml --force  # Overwrite conflicts
+
+# Semantic models
+dataspring models list
+dataspring models show orders
+dataspring models create model.yaml
+dataspring models update orders updated.yaml
+dataspring models delete orders
+
+# Metrics
+dataspring metrics create metric.yaml
+dataspring metrics update total_revenue updated.yaml
+dataspring metrics delete total_revenue
+dataspring metrics preview metric.yaml  # Test before saving
+```
+
+## Output Formats
+
+All commands support `--format`:
+
+| Format | Description |
+|--------|-------------|
+| `table` | Human-readable ASCII table (default) |
+| `json` | JSON output for scripting |
+| `yaml` | YAML output for config editing |
+
+```bash
+dataspring metrics list --format json | jq '.[0]'
+dataspring dashboards show abc123 --format yaml > dashboard.yaml
+```
+
+## Configuration
+
+Credentials are stored in `~/.dataspring/`:
+
+```
+~/.dataspring/
+├── credentials.json    # OAuth tokens (encrypted)
+└── config.json         # User preferences
+```
+
+## Development
+
+```bash
+# Build the wheel
+cd backend
+uv build
+
+# Install locally for testing
+uv tool install dist/dataspring_cli-*.whl --force
+
+# Run tests
+uv run pytest tests/ -v
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `FIRESTORE_EMULATOR_HOST` | Use Firestore emulator |
+| `FIREBASE_AUTH_EMULATOR_HOST` | Use Auth emulator |
+| `ENV` | Environment: `production`, `development`, `test` |

dataspring_cli-0.3.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+cli/__init__.py,sha256=RJi9Y5W2jatsoYYtgi6Iu6UkHEi55lvsuNBdsY7pRXc,453
+cli/auth.py,sha256=rg6CIt0BcG7Ags0WRsFsso3ol7Au7dYMkoUloJq3AGQ,13150
+cli/bundled_manifest.py,sha256=KLtAHwOJHT-5l_B_v3uJJNIdvvILtRjBbOz8LayocLw,988
+cli/contract.py,sha256=68XWcf9EgsIFqey4kzzpJCoR01Pkl6tNmqRDjcX7yrk,40174
+cli/generated.py,sha256=MtN1u2oM1xl_v-Q2cZ75lkdI64b1DpaGJ1vsM2H6UmI,84414
+cli/main.py,sha256=tKvRk-FfCvxd1vl-TVCcdVZRawknJbdwL_NMwe3uuwM,112840
+cli/output.py,sha256=DOficOs7Dfi4hbR6i-39HFxwZBk1FI_oUZeZP57XPjs,6853
+cli/runtime.py,sha256=um_WqkG911j_cJEmpLlaU-csrCortTaYbFY024VvVAE,7456
+cli/skills_commands.py,sha256=-ZvMN-w9T6P2Tc05iAY4THgX5vMsAF6jj9-oTjNOD3Q,8868
+cli/skilltree.py,sha256=r-BJ2p1U5OVhIEZbkZoOgtJ2tuDo00CCQcd1fu3O1f8,12807
+cli/upgrade.py,sha256=UfNPzwy0lal5D6NBzS3lgzDTNUOrcLNIvW1lfQpn3pU,2095
+cli/version.py,sha256=ARcAiq_TgTntMsJC_9isC9gcBymLQmkUcVm1zoyJy9k,4467
+settings.py,sha256=Ok4qe_nkAxhvq8oXHH74zq99B9hnSrvl738GIG0F95s,3520
+cli/_skills/dataspring-author/SKILL.md,sha256=GdZvc_CpocT7UUmwEST_IUBv1qg85jVZ6gwPrlKIM4c,19693
+cli/_skills/dataspring-consume/SKILL.md,sha256=rQ-xwBesfu91k9OAaYxLMoOwQxSIqW9mXBNwTUvi8XI,38829
+cli/_skills/dataspring-correct/SKILL.md,sha256=SYgHkHKhn2fis1kc7m_cnDWss_lSZ1eJXj1Br8I0T6E,6448
+dataspring_cli-0.3.0.dist-info/METADATA,sha256=p-tp8r74D4dOIk0jyL9G_jUggmn5BMg_05ANye85G-8,5091
+dataspring_cli-0.3.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+dataspring_cli-0.3.0.dist-info/entry_points.txt,sha256=X4YdpJ6kFTyolhrFZNlzkXT3dhE_H_4E3YUHna6oXUM,44
+dataspring_cli-0.3.0.dist-info/RECORD,,

dataspring_cli-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.3
+Root-Is-Purelib: true
+Tag: py3-none-any

dataspring_cli-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dataspring = cli.main:app

settings.py

@@ -0,0 +1,78 @@
+"""Application settings using Pydantic BaseSettings."""
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables and .env file."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    # The Google OAuth client the CLI logs in with. A Google access token is
+    # only accepted as a DataSpring credential when it was minted for this
+    # client (see auth.verify_oauth_token); must match
+    # cli.auth.CLIAuthManager.CLI_OAUTH_CLIENT_ID.
+    cli_oauth_client_id: str = (
+        "910366018047-ekplje5p344nbq60o8vqk88378turj52.apps.googleusercontent.com"
+    )
+
+    # MCP OAuth Configuration (for Claude.ai integration)
+    # Create OAuth 2.0 credentials in Google Cloud Console:
+    # 1. Go to APIs & Services > Credentials
+    # 2. Create OAuth 2.0 Client ID (Web application)
+    # 3. Add authorized redirect URI: <your-server-url>/mcp/auth/callback
+    mcp_oauth_client_id: str | None = None
+    mcp_oauth_client_secret: str | None = None
+    mcp_server_base_url: str = "https://dataspring.app/api"
+    # JWT signing key for MCP tokens - MUST be persistent across server restarts
+    # Generate with: python -c "import secrets; print(secrets.token_urlsafe(32))"
+    mcp_jwt_signing_key: str | None = None
+    # Public origin of the DataSpring dashboard SPA (used for MCP Apps embed URLs).
+    # In prod: https://dataspring.app. Locally: http://localhost:5173.
+    dataspring_frontend_base_url: str = "https://dataspring.app"
+
+    # Internal secret for Cloud Function -> Backend communication
+    # Used by the scheduled reports executor to authenticate with the backend
+    # Generate with: python -c "import secrets; print(secrets.token_urlsafe(32))"
+    internal_secret: str | None = None
+
+    # Deep health probe authentication and Nightnurse heartbeat sink.
+    # HEALTH_PROBE_SECRET is sent by Cloud Scheduler. NIGHTNURSE_PING_URL is a
+    # bearer URL, stored in Secret Manager, that receives success/fail pings.
+    health_probe_secret: str | None = None
+    nightnurse_ping_url: str | None = None
+
+    # BigQuery cost controls (warehouse.BigQueryClient; review item 16).
+    # Every job the backend submits carries these. A per-org override for the
+    # byte cap lives on the warehouse config document (`bigquery.max_bytes_billed`).
+    #
+    # The most one query may bill, in bytes. BigQuery refuses a job that would
+    # scan more, before it runs, and the refusal reaches the caller as
+    # `error_code: bytes_billed_exceeded`. 10 GiB is ~$0.06 on on-demand
+    # pricing and far above any dashboard or agent query on a modelled table.
+    bigquery_max_bytes_billed: int = 10 * 1024**3
+    # Server-side job timeout (BigQuery stops the job) and the client-side wait
+    # on its result; on expiry the job is cancelled, never abandoned.
+    bigquery_job_timeout_seconds: int = 60
+    # Rows a query may return when the caller sets no limit. Applies to every
+    # warehouse (BigQuery via `result(max_results=)`, DuckDB via `fetchmany`).
+    query_max_rows: int = 10_000
+
+    # Feature flags
+    schedules_enabled: bool = False  # Scheduled reports (email delivery not implemented yet)
+
+
+# Singleton instance
+_settings: Settings | None = None
+
+
+def get_settings() -> Settings:
+    """Get the singleton settings instance."""
+    global _settings
+    if _settings is None:
+        _settings = Settings()
+    return _settings