datamasque-cli 1.0.0__py3-none-any.whl

datamasque_cli/client.py

@@ -0,0 +1,109 @@
+"""Authenticated DataMasque client factory.
+
+Resolves credentials from environment variables or the active profile,
+builds a `DataMasqueClient`, and authenticates it before returning.
+"""
+
+from __future__ import annotations
+
+import os
+
+from datamasque.client import DataMasqueClient
+from datamasque.client.exceptions import DataMasqueApiError, DataMasqueTransportError
+from datamasque.client.models.dm_instance import DataMasqueInstanceConfig
+
+from datamasque_cli.config import Config, Profile, load_config
+from datamasque_cli.output import abort
+
+ENV_URL = "DATAMASQUE_URL"
+ENV_USERNAME = "DATAMASQUE_USERNAME"
+ENV_PASSWORD = "DATAMASQUE_PASSWORD"
+ENV_VERIFY_SSL = "DATAMASQUE_VERIFY_SSL"
+
+# `false`-y env values that disable TLS verification.
+_FALSE_VALUES = frozenset({"false", "0", "no", "off"})
+
+
+def _verify_ssl_from_env(default: bool) -> bool:
+    """Resolve `verify_ssl` from `DATAMASQUE_VERIFY_SSL`, falling back to `default`."""
+    raw = os.environ.get(ENV_VERIFY_SSL)
+    if raw is None:
+        return default
+    return raw.strip().lower() not in _FALSE_VALUES
+
+
+def profile_from_env() -> Profile | None:
+    """Build a profile from environment variables, or return None if not set."""
+    url = os.environ.get(ENV_URL)
+    username = os.environ.get(ENV_USERNAME)
+    password = os.environ.get(ENV_PASSWORD)
+    if url and username and password:
+        return Profile(
+            url=url.rstrip("/"),
+            username=username,
+            password=password,
+            verify_ssl=_verify_ssl_from_env(default=True),
+        )
+    return None
+
+
+def _resolve_profile(config: Config, profile_name: str | None) -> Profile:
+    profile = config.get_profile(profile_name)
+    if not profile.is_configured:
+        name = profile_name or config.active_profile
+        abort(
+            f"Profile '{name}' is not configured. "
+            f"Run: dm auth login --profile {name} --url <URL> --username <USER>\n"
+            f"Or set {ENV_URL}, {ENV_USERNAME}, and {ENV_PASSWORD} environment variables."
+        )
+    return profile
+
+
+def get_client(profile_name: str | None = None) -> DataMasqueClient:
+    """Build and authenticate a `DataMasqueClient`.
+
+    Credential resolution order:
+    1. Environment variables (DATAMASQUE_URL, DATAMASQUE_USERNAME, DATAMASQUE_PASSWORD)
+    2. Named profile (--profile flag)
+    3. Active profile from config file
+    """
+    # Env vars take precedence unless a specific profile was requested.
+    env_profile = profile_from_env() if profile_name is None else None
+    if env_profile is not None:
+        profile = env_profile
+    else:
+        config = load_config()
+        profile = _resolve_profile(config, profile_name)
+
+    # `DATAMASQUE_VERIFY_SSL` always wins over the stored profile so you can
+    # flip TLS verification per-call without re-running `dm auth login`.
+    verify_ssl = _verify_ssl_from_env(default=profile.verify_ssl)
+    instance_config = DataMasqueInstanceConfig(
+        base_url=profile.url,
+        username=profile.username,
+        password=profile.password,
+        verify_ssl=verify_ssl,
+    )
+
+    client = DataMasqueClient(instance_config)
+
+    try:
+        client.authenticate()
+    except DataMasqueTransportError as e:
+        abort(_format_transport_error(profile.url, e, verify_ssl=verify_ssl))
+    except DataMasqueApiError as e:
+        abort(f"Authentication failed: {e}")
+
+    return client
+
+
+# Substrings that suggest the underlying error was a TLS failure rather than
+# a plain network outage, so we can point local-build users at `--insecure`.
+_SSL_HINT_TERMS = ("ssl", "certificate", "verify")
+
+
+def _format_transport_error(url: str, error: Exception, *, verify_ssl: bool) -> str:
+    message = f"Could not connect to {url}: {error}"
+    if verify_ssl and any(term in str(error).lower() for term in _SSL_HINT_TERMS):
+        message += "\nIf this is a self-signed local build, retry with --insecure or set DATAMASQUE_VERIFY_SSL=false."
+    return message

datamasque_cli/commands/auth.py

@@ -0,0 +1,154 @@
+"""Authentication and profile management commands."""
+
+from __future__ import annotations
+
+import typer
+
+from datamasque_cli.client import get_client, profile_from_env
+from datamasque_cli.config import DEFAULT_PROFILE, Profile, load_config, save_config
+from datamasque_cli.output import abort, print_info, print_success, print_table
+
+# `login` and `status` handle connection errors locally
+# because they need softer behaviour than `get_client`'s hard abort:
+# login saves credentials even when the server is unreachable,
+# and status prints profile info before attempting connection.
+
+app = typer.Typer(help="Authentication and profile management.")
+
+
+@app.command()
+def login(
+    profile: str = typer.Option("default", help="Profile name to store credentials under"),
+    is_insecure: bool = typer.Option(
+        False,
+        "--insecure",
+        help="Skip TLS verification when talking to this instance (self-signed / expired cert).",
+    ),
+) -> None:
+    """Save credentials for a DataMasque instance.
+
+    Fully interactive: prompts for URL, username, and password. Credentials
+    are saved to `~/.config/datamasque-cli/config.toml` (mode 0600). For
+    non-interactive / CI use, set `DATAMASQUE_URL`, `DATAMASQUE_USERNAME`,
+    and `DATAMASQUE_PASSWORD` env vars instead — `dm` reads them directly
+    without a saved profile. Pair with `DATAMASQUE_VERIFY_SSL=false` to
+    skip TLS verification on a per-call basis.
+    """
+    url = typer.prompt("DataMasque URL").rstrip("/")
+    if not url.startswith(("http://", "https://")):
+        abort(f"URL must start with http:// or https:// (got '{url}').")
+
+    username = typer.prompt("Username")
+    password = typer.prompt("Password", hide_input=True)
+    config = load_config()
+
+    config.set_profile(
+        profile,
+        Profile(url=url, username=username, password=password, verify_ssl=not is_insecure),
+    )
+    config.active_profile = profile
+    save_config(config)
+    print_success(f"Credentials saved to profile '{profile}'.")
+
+    print_info("Verifying connection...")
+    try:
+        get_client(profile)
+    except SystemExit:
+        # Credentials are already saved; connection verification is best-effort.
+        return
+    print_success("Authentication successful.")
+
+
+@app.command()
+def logout(
+    profile: str | None = typer.Option(None, help="Profile to remove. Removes active profile if omitted."),
+) -> None:
+    """Remove stored credentials for a profile."""
+    config = load_config()
+    name = profile or config.active_profile
+
+    if not config.delete_profile(name):
+        abort(f"Profile '{name}' does not exist.")
+
+    # If we just deleted the active profile, fall back to another one.
+    if name == config.active_profile:
+        remaining = config.list_profile_names()
+        config.active_profile = remaining[0] if remaining else DEFAULT_PROFILE
+
+    save_config(config)
+    print_success(f"Profile '{name}' removed.")
+
+
+@app.command("use")
+def use_profile(
+    profile: str = typer.Argument(help="Profile name to set as active"),
+) -> None:
+    """Set the active profile."""
+    config = load_config()
+
+    if profile not in config.profiles:
+        abort(f"Profile '{profile}' does not exist. Run: dm auth login --profile {profile}")
+
+    config.active_profile = profile
+    save_config(config)
+    print_success(f"Active profile set to '{profile}'.")
+
+
+@app.command("list")
+def list_profiles() -> None:
+    """List all configured profiles."""
+    config = load_config()
+    names = config.list_profile_names()
+
+    if not names:
+        print_info("No profiles configured. Run: dm auth login")
+        return
+
+    rows = []
+    for name in names:
+        p = config.profiles[name]
+        is_active = name == config.active_profile
+        rows.append(
+            [
+                "*" if is_active else "",
+                name,
+                p.url,
+                p.username,
+            ]
+        )
+
+    print_table(["", "Profile", "URL", "Username"], rows)
+
+
+@app.command()
+def status() -> None:
+    """Show current authentication status and instance info."""
+    # Env vars take precedence over any saved profile in `get_client`,
+    # so report them here as the actual source rather than the stale profile.
+    env_profile = profile_from_env()
+    if env_profile is not None:
+        profile_label = "(env)"
+        profile = env_profile
+    else:
+        config = load_config()
+        profile = config.get_profile()
+        if not profile.is_configured:
+            abort(f"Profile '{config.active_profile}' is not configured. Run: dm auth login")
+        profile_label = config.active_profile
+
+    print_info(f"Profile: {profile_label}")
+    print_info(f"URL: {profile.url}")
+    print_info(f"Username: {profile.username}")
+
+    try:
+        client = get_client()
+    except SystemExit:
+        # `get_client` aborts on connection/auth failure,
+        # but here we want a softer warning since profile info was already printed.
+        return
+
+    license_info = client.get_current_license_info()
+    print_success("Authenticated.")
+    print_info(f"Licence: {license_info.uuid}")
+    expiry = license_info.expiry_date.isoformat() if license_info.expiry_date else "unknown"
+    print_info(f"Expiry: {expiry}")

datamasque_cli/commands/connections.py

@@ -0,0 +1,325 @@
+"""Connection management commands."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+from datamasque.client import DataMasqueClient
+from datamasque.client.models.connection import (
+    AzureConnectionConfig,
+    ConnectionConfig,
+    DatabaseConnectionConfig,
+    DatabaseType,
+    DynamoConnectionConfig,
+    MountedShareConnectionConfig,
+    S3ConnectionConfig,
+    SnowflakeConnectionConfig,
+)
+
+from datamasque_cli.client import get_client
+from datamasque_cli.output import abort, print_success, redact_sensitive_fields, render_output
+
+_FILE_CONNECTION_TYPES = (MountedShareConnectionConfig, S3ConnectionConfig, AzureConnectionConfig)
+
+
+def _format_role(conn: ConnectionConfig) -> str:
+    """Return `source`, `destination`, `source+destination`, or `—` for a connection.
+
+    Database-type connections always act as the source and mask in place,
+    so there's no source/destination split to display.
+    """
+    if not isinstance(conn, _FILE_CONNECTION_TYPES):
+        return "source"
+    if conn.is_file_mask_source and conn.is_file_mask_destination:
+        return "source+destination"
+    if conn.is_file_mask_source:
+        return "source"
+    if conn.is_file_mask_destination:
+        return "destination"
+    return "—"
+
+
+app = typer.Typer(help="Manage database and file connections.")
+
+# Maps the `type` field in JSON to the right config class.
+_CONNECTION_CLASSES = {
+    "database": DatabaseConnectionConfig,
+    "s3": S3ConnectionConfig,
+    "azure": AzureConnectionConfig,
+    "mounted_share": MountedShareConnectionConfig,
+    "snowflake": SnowflakeConnectionConfig,
+    "dynamodb": DynamoConnectionConfig,
+}
+
+
+@app.command("list")
+def list_connections(
+    profile: str | None = typer.Option(None, "--profile", "-p", help="Profile to use"),
+    is_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+) -> None:
+    """List all configured connections."""
+    client = get_client(profile)
+    connections = client.list_connections()
+
+    data = []
+    for conn in connections:
+        class_name = type(conn).__name__
+        entry: dict[str, object] = {
+            "id": conn.id,
+            "name": conn.name,
+            "type": class_name.replace("ConnectionConfig", "").replace("Config", ""),
+            "role": _format_role(conn),
+        }
+        data.append(entry)
+
+    render_output(
+        data,
+        is_json=is_json,
+        columns=["id", "name", "type", "role"],
+        title="Connections",
+    )
+
+
+@app.command("get")
+def get_connection(
+    name: str = typer.Argument(help="Connection name"),
+    profile: str | None = typer.Option(None, "--profile", "-p", help="Profile to use"),
+    is_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+) -> None:
+    """Show details for a specific connection."""
+    client = get_client(profile)
+    connections = client.list_connections()
+
+    match = next((c for c in connections if c.name == name), None)
+    if match is None:
+        abort(f"Connection '{name}' not found.")
+
+    data = redact_sensitive_fields(match.model_dump())
+    render_output(data, is_json=is_json, title=f"Connection: {name}")
+
+
+@app.command("create")
+def create_connection(
+    file: Path | None = typer.Option(None, "--file", "-f", help="JSON file defining the connection"),
+    name: str | None = typer.Option(None, help="Connection name"),
+    conn_type: str | None = typer.Option(None, "--type", "-t", help="database, s3, azure, mounted_share"),
+    host: str | None = typer.Option(None, help="Database host"),
+    port: str | None = typer.Option(None, help="Database port"),
+    database: str | None = typer.Option(None, help="Database name"),
+    user: str | None = typer.Option(None, help="Database user"),
+    password: str | None = typer.Option(None, help="Database password"),
+    db_type: str | None = typer.Option(None, "--db-type", help="postgres, mysql, oracle, mssql, mariadb, etc."),
+    schema: str | None = typer.Option(None, help="Schema name"),
+    base_directory: str | None = typer.Option(None, "--base-dir", help="Base directory (file connections)"),
+    is_source: bool = typer.Option(False, "--source", help="Is a file mask source"),
+    is_destination: bool = typer.Option(False, "--destination", help="Is a file mask destination"),
+    bucket: str | None = typer.Option(None, help="S3 bucket name"),
+    profile: str | None = typer.Option(None, "--profile", "-p", help="Profile to use"),
+) -> None:
+    """Create or update a connection.
+
+    Use --file for full control (JSON), or flags for quick database/file connections.
+
+    Examples:
+
+        # From JSON file (any connection type)
+        dm connections create --file connection.json
+
+        # Quick database connection
+        dm connections create --name mydb --type database --db-type postgres \\
+            --host db.example.com --port 5432 --database mydb --user admin --password secret
+
+        # Quick mounted share
+        dm connections create --name input --type mounted_share --base-dir my-data --source
+    """
+    client = get_client(profile)
+
+    if file is not None:
+        _create_from_file(client, file)
+        return
+
+    if name is None or conn_type is None:
+        abort("Provide either --file or both --name and --type.")
+
+    config = _build_connection_config(
+        name=name,
+        conn_type=conn_type,
+        host=host,
+        port=port,
+        database=database,
+        user=user,
+        password=password,
+        db_type=db_type,
+        schema=schema,
+        base_directory=base_directory,
+        is_source=is_source,
+        is_destination=is_destination,
+        bucket=bucket,
+    )
+
+    client.create_or_update_connection(config)
+    print_success(f"Connection '{name}' created/updated.")
+
+
+def _create_from_file(client: DataMasqueClient, file: Path) -> None:
+    """Create a connection from a JSON file."""
+    data = json.loads(file.read_text())
+    conn_type = data.pop("type", "database")
+
+    if conn_type not in _CONNECTION_CLASSES:
+        valid = ", ".join(_CONNECTION_CLASSES)
+        abort(f"Unknown connection type '{conn_type}'. Valid: {valid}")
+
+    # Convert db_type string to enum for database connections
+    if conn_type == "database" and "database_type" in data:
+        data["database_type"] = DatabaseType(data["database_type"])
+
+    klass = _CONNECTION_CLASSES[conn_type]
+    config = klass(**data)
+    client.create_or_update_connection(config)
+    print_success(f"Connection '{config.name}' created/updated.")
+
+
+def _build_connection_config(
+    *,
+    name: str,
+    conn_type: str,
+    host: str | None,
+    port: str | None,
+    database: str | None,
+    user: str | None,
+    password: str | None,
+    db_type: str | None,
+    schema: str | None,
+    base_directory: str | None,
+    is_source: bool,
+    is_destination: bool,
+    bucket: str | None,
+) -> DatabaseConnectionConfig | S3ConnectionConfig | MountedShareConnectionConfig:
+    """Build a connection config from CLI flags."""
+    if conn_type == "database":
+        if not all([host, port, database, user, password, db_type]):
+            abort("Database connections require: --host, --port, --database, --user, --password, --db-type")
+        return DatabaseConnectionConfig(
+            name=name,
+            host=host,
+            port=port,
+            database=database,
+            user=user,
+            password=password,
+            database_type=DatabaseType(db_type),
+            schema=schema,
+        )
+
+    if conn_type == "mounted_share":
+        if base_directory is None:
+            abort("Mounted share connections require: --base-dir")
+        return MountedShareConnectionConfig(
+            name=name,
+            base_directory=base_directory,
+            is_file_mask_source=is_source,
+            is_file_mask_destination=is_destination,
+        )
+
+    if conn_type == "s3":
+        if base_directory is None or bucket is None:
+            abort("S3 connections require: --base-dir, --bucket")
+        return S3ConnectionConfig(
+            name=name,
+            base_directory=base_directory,
+            bucket=bucket,
+            is_file_mask_source=is_source,
+            is_file_mask_destination=is_destination,
+        )
+
+    abort(f"Use --file for '{conn_type}' connections (too many fields for CLI flags).")
+
+
+@app.command("test")
+def test_connection(
+    name: str = typer.Argument(help="Connection name or ID to test"),
+    profile: str | None = typer.Option(None, "--profile", "-p", help="Profile to use"),
+) -> None:
+    """Verify a connection can reach its target.
+
+    Posts the stored connection to the server's test endpoint, which attempts
+    an actual database handshake or filesystem/bucket open and reports
+    success, a warning, or a hard failure.
+    """
+    client = get_client(profile)
+
+    match = next((c for c in client.list_connections() if c.name == name or str(c.id) == name), None)
+    if match is None:
+        abort(f"Connection '{name}' not found.")
+
+    response = client.make_request("POST", f"/api/connections/{match.id}/test/", data={})
+    body = response.json() if response.content else {}
+    warning = body.get("message") if isinstance(body, dict) else None
+
+    if warning:
+        print_success(f"Connection '{match.name}' reachable (warning: {warning}).")
+    else:
+        print_success(f"Connection '{match.name}' reachable.")
+
+
+@app.command("update")
+def update_connection(
+    name: str = typer.Argument(help="Connection name or ID to update"),
+    host: str | None = typer.Option(None, help="New database host"),
+    port: str | None = typer.Option(None, help="New database port"),
+    database: str | None = typer.Option(None, help="New database name"),
+    user: str | None = typer.Option(None, help="New database user"),
+    password: str | None = typer.Option(None, help="New database password"),
+    schema: str | None = typer.Option(None, help="New schema name"),
+    base_directory: str | None = typer.Option(None, "--base-dir", help="New base directory (file connections)"),
+    profile: str | None = typer.Option(None, "--profile", "-p", help="Profile to use"),
+) -> None:
+    """Update selected fields on an existing connection without recreating it.
+
+    Preserves the connection's UUID, so any ruleset or run history that
+    references it stays intact. Pass only the fields that should change.
+    """
+    client = get_client(profile)
+
+    match = next((c for c in client.list_connections() if c.name == name or str(c.id) == name), None)
+    if match is None:
+        abort(f"Connection '{name}' not found.")
+
+    updates: dict[str, object] = {
+        key: value
+        for key, value in {
+            "host": host,
+            "port": port,
+            "database": database,
+            "user": user,
+            "password": password,
+            "schema": schema,
+            "base_directory": base_directory,
+        }.items()
+        if value is not None
+    }
+    if not updates:
+        abort("Pass at least one field to update (e.g. --password, --host).")
+
+    client.make_request("PATCH", f"/api/connections/{match.id}/", data=updates)
+    print_success(f"Connection '{match.name}' updated: {', '.join(updates)}.")
+
+
+@app.command("delete")
+def delete_connection(
+    name: str = typer.Argument(help="Connection name to delete"),
+    profile: str | None = typer.Option(None, "--profile", "-p", help="Profile to use"),
+    is_confirmed: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation"),
+) -> None:
+    """Delete a connection by name."""
+    client = get_client(profile)
+    if not any(c.name == name for c in client.list_connections()):
+        abort(f"Connection '{name}' not found.")
+
+    if not is_confirmed:
+        typer.confirm(f"Delete connection '{name}'?", abort=True)
+
+    client.delete_connection_by_name_if_exists(name)
+    print_success(f"Connection '{name}' deleted.")