duckhaven-cli 0.1.0__py3-none-any.whl

dh/commands/dbt.py

@@ -0,0 +1,272 @@
+"""`dh lineage` and `dh semantic` — publishing dbt artifacts.
+
+This is the pair of commands the CLI most clearly earns. Both import routes take a
+**local build artifact** and post it, which a browser cannot do at all, and which
+the docs currently tell people to do with hand-written `curl`. Each of those
+invocations re-implements base-URL joining, bearer auth, content-type selection
+and error parsing, and gets at least one of them wrong.
+
+The end-to-end flow these replace:
+
+    dbt parse --target prod
+    dh lineage import  dbt target/manifest.json --catalog-json target/catalog.json
+    dh semantic import dbt target/manifest.json
+    dh semantic validate analytics
+    dh semantic publish  analytics
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from dh import context
+from dh.errors import ConflictError
+
+lineage_app = typer.Typer(name="lineage", help="Publish and retire lineage from other producers.")
+semantic_app = typer.Typer(name="semantic", help="Publish and manage semantic models.")
+
+_RECONCILE = typer.Option(
+    None,
+    "--reconcile",
+    help="provider_run (default) retires what the artifact no longer declares; none does not.",
+)
+
+
+def _load_json(path: Path) -> dict:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ConflictError("bad_artifact", f"{path} is not valid JSON: {exc}") from exc
+
+
+# --- Lineage ---------------------------------------------------------------
+
+
+@lineage_app.command("import")
+def import_lineage(
+    ctx: typer.Context,
+    provider: str = typer.Argument(..., help="Producer name, e.g. dbt."),
+    artifact: Path = typer.Argument(..., exists=True, help="The producer's artifact."),
+    catalog_json: Path = typer.Option(
+        None,
+        "--catalog-json",
+        exists=True,
+        help="dbt's catalog.json, which unlocks column-level lineage.",
+    ),
+    reconcile: str = _RECONCILE,
+) -> None:
+    """Publish a producer's own artifact, translated by that producer's adapter.
+
+    For dbt this is `target/manifest.json`. Passing `--catalog-json` as well sends
+    both under one body, which is what makes **column-level** lineage possible --
+    assembling that envelope by hand is the part people get wrong.
+
+    Publish when the project *changes*, not when it runs: the manifest describes
+    the dependencies your code declares, so re-posting an unchanged one achieves
+    nothing.
+    """
+    cli = context.of(ctx)
+    settings = cli.settings()
+    body = _load_json(artifact)
+    if catalog_json:
+        body = {"manifest": body, "catalog": _load_json(catalog_json)}
+    path = f"workspaces/{settings.require('workspace')}/lineage/imports/{provider}"
+    with cli.client(settings) as client:
+        result = client.post(path, json=body, params={"reconcile": reconcile})
+    cli.note(
+        f"created {result.get('created', 0)}, updated {result.get('updated', 0)}, "
+        f"removed {result.get('removed', 0)}, skipped {len(result.get('skipped') or [])}"
+    )
+    cli.emit(result)
+
+
+@lineage_app.command("import-edges")
+def import_edges(
+    ctx: typer.Context,
+    file: Path = typer.Argument(..., exists=True, help="A canonical edge list."),
+    provider: str = typer.Option(..., "--provider", help="Producer asserting these edges."),
+    run_id: str = typer.Option(None, "--run-id", help="Required with --reconcile provider_run."),
+    reconcile: str = _RECONCILE,
+) -> None:
+    """Publish already-canonical edges from a producer with no adapter.
+
+    The edge list may be a bare array or the full request body. At most 5000 edges
+    per request; split a larger set across calls sharing one `--run-id`.
+    """
+    cli = context.of(ctx)
+    settings = cli.settings()
+    loaded = _load_json(file)
+    body = loaded if isinstance(loaded, dict) else {"edges": loaded}
+    body.setdefault("provider", provider)
+    if run_id:
+        body["run_id"] = run_id
+    if reconcile:
+        body["reconcile"] = reconcile
+    path = f"workspaces/{settings.require('workspace')}/lineage/imports"
+    with cli.client(settings) as client:
+        cli.emit(client.post(path, json=body))
+
+
+@lineage_app.command("purge")
+def purge_lineage(
+    ctx: typer.Context,
+    provider: str = typer.Option(..., "--provider"),
+    yes: bool = context.YES,
+) -> None:
+    """Remove every edge a retired producer asserted. Requires workspace owner."""
+    cli = context.of(ctx)
+    cli.confirm("Purge all lineage published by", provider, yes=yes)
+    settings = cli.settings()
+    path = f"workspaces/{settings.require('workspace')}/lineage/imports"
+    with cli.client(settings) as client:
+        cli.emit(client.delete(path, params={"provider": provider}))
+
+
+# --- Semantic --------------------------------------------------------------
+
+
+@semantic_app.command("import")
+def import_semantics(
+    ctx: typer.Context,
+    provider: str = typer.Argument(..., help="Producer name, e.g. dbt."),
+    artifact: Path = typer.Argument(..., exists=True, help="Manifest or YAML document."),
+    reconcile: str = _RECONCILE,
+) -> None:
+    """Publish semantic definitions from an external producer.
+
+    The file is sent **byte for byte**. One route serves hand-written YAML and
+    machine-written JSON, and it reads the body raw so a YAML parse error points
+    at the line the author wrote rather than one the CLI re-encoded.
+
+    Imported models arrive as **drafts**: an import is a pipeline publishing, not
+    a person deciding. Promote them with `dh semantic validate` then
+    `dh semantic publish`.
+    """
+    cli = context.of(ctx)
+    settings = cli.settings()
+    path = f"workspaces/{settings.require('workspace')}/semantic/imports/{provider}"
+    with cli.client(settings) as client:
+        result = client.post(
+            path,
+            content=artifact.read_bytes(),
+            headers={"Content-Type": "text/plain; charset=utf-8"},
+            params={"reconcile": reconcile},
+        )
+    cli.note("Imported as drafts. Promote with `dh semantic validate` then `publish`.")
+    cli.emit(result)
+
+
+@semantic_app.command("purge")
+def purge_semantics(
+    ctx: typer.Context,
+    provider: str = typer.Option(..., "--provider"),
+    yes: bool = context.YES,
+) -> None:
+    """Remove everything one provider published. Requires workspace owner."""
+    cli = context.of(ctx)
+    cli.confirm("Purge all semantics published by", provider, yes=yes)
+    settings = cli.settings()
+    path = f"workspaces/{settings.require('workspace')}/semantic/imports"
+    with cli.client(settings) as client:
+        client.delete(path, params={"provider": provider})
+    cli.note(f"Purged everything published by {provider!r}.")
+
+
+model_app = typer.Typer(name="model", help="Semantic models.")
+semantic_app.add_typer(model_app)
+
+
+@model_app.command("list")
+def list_models(ctx: typer.Context) -> None:
+    """The workspace's semantic models, published and draft."""
+    cli = context.of(ctx)
+    settings = cli.settings()
+    with cli.client(settings) as client:
+        cli.emit(client.get(f"workspaces/{settings.require('workspace')}/semantic/models"))
+
+
+@model_app.command("get")
+def get_model(ctx: typer.Context, model: str) -> None:
+    """One model in full: datasets, dimensions, metrics and relationships."""
+    cli = context.of(ctx)
+    settings = cli.settings()
+    with cli.client(settings) as client:
+        cli.emit(client.get(f"workspaces/{settings.require('workspace')}/semantic/models/{model}"))
+
+
+def _transition(action: str, doc: str):
+    """The three model state changes, which differ only in their path segment."""
+
+    def command(ctx: typer.Context, model: str) -> None:
+        cli = context.of(ctx)
+        settings = cli.settings()
+        base = f"workspaces/{settings.require('workspace')}/semantic/models/{model}"
+        with cli.client(settings) as client:
+            cli.emit(client.post(f"{base}/{action}"))
+
+    command.__doc__ = doc
+    return command
+
+
+semantic_app.command("validate")(
+    _transition("validate", "Check a model without publishing it. Safe to run in CI.")
+)
+semantic_app.command("publish")(
+    _transition("publish", "Make a model authoritative to the assistant. Validates first.")
+)
+semantic_app.command("deprecate")(
+    _transition("deprecate", "Retire a published model without deleting it.")
+)
+
+
+relationship_app = typer.Typer(name="relationship", help="Joins between a model's datasets.")
+semantic_app.add_typer(relationship_app)
+
+
+@relationship_app.command("add")
+def add_relationship(
+    ctx: typer.Context,
+    model: str = typer.Argument(..., help="Model slug."),
+    name: str = typer.Option(..., "--name"),
+    left: str = typer.Option(..., "--left", help="The many side; traversal starts here."),
+    right: str = typer.Option(..., "--right", help="The unique side; needs a primary key."),
+    join: list[str] = typer.Option(..., "--join", help="Repeatable: left_column=right_column."),
+    cardinality: str = typer.Option(None, "--cardinality", help="Defaults to many_to_one."),
+) -> None:
+    """Declare a join between two of a model's datasets."""
+    cli = context.of(ctx)
+    settings = cli.settings()
+    body = {
+        "name": name,
+        "left_dataset": left,
+        "right_dataset": right,
+        "join_columns": [_join(pair) for pair in join],
+    }
+    if cardinality:
+        body["cardinality"] = cardinality
+    base = f"workspaces/{settings.require('workspace')}/semantic/models/{model}"
+    with cli.client(settings) as client:
+        cli.emit(client.post(f"{base}/relationships", json=body))
+
+
+def _join(pair: str) -> dict[str, str]:
+    left, sep, right = pair.partition("=")
+    if not sep or not left or not right:
+        raise ConflictError(
+            "bad_join", f"Could not read join {pair!r}. Use left_column=right_column."
+        )
+    return {"left": left, "right": right}
+
+
+@relationship_app.command("remove")
+def remove_relationship(ctx: typer.Context, model: str, name: str) -> None:
+    """Remove a relationship from a model."""
+    cli = context.of(ctx)
+    settings = cli.settings()
+    base = f"workspaces/{settings.require('workspace')}/semantic/models/{model}"
+    with cli.client(settings) as client:
+        client.delete(f"{base}/relationships/{name}")
+    cli.note(f"Removed relationship {name!r} from {model!r}.")

dh/commands/grant.py

@@ -0,0 +1,129 @@
+"""`dh grant` — catalog access control.
+
+Access control is the kind of change people want reviewable and applied from a
+script rather than clicked into a browser, which is what puts it in v1 despite
+the blast radius.
+
+`GET .../grants` returns the current grants *and* the principals they could name,
+so the one request that shows the state also resolves an email to a user id. The
+workspace members list cannot: `MemberOut` carries no email.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from dh import context
+from dh.commands.catalog import resolve_catalog
+from dh.errors import ConflictError
+
+app = typer.Typer(name="grant", help="Catalog access control.")
+
+_CATALOG = typer.Option(None, "--catalog", help="Catalog to act on.")
+
+
+def _grants_path(cli, client, settings, catalog: str | None) -> str:
+    target = resolve_catalog(cli, client, settings, catalog)
+    return f"workspaces/{settings.require('workspace')}/catalogs/{target}"
+
+
+def _resolve_principal(payload: dict, who: str) -> str:
+    """A user id from an id, an email, or a name.
+
+    Requiring a pasted UUID would throw away the one advantage this command has
+    over `curl`, so an ambiguous or unknown value lists the candidates instead.
+    """
+    principals = payload.get("principals") or []
+    for field in ("user_id", "email", "name"):
+        matches = [p for p in principals if str(p.get(field, "")).lower() == who.lower()]
+        if len(matches) == 1:
+            return str(matches[0]["user_id"])
+        if len(matches) > 1:
+            raise ConflictError(
+                "ambiguous_principal",
+                f"{who!r} matches more than one principal by {field}; use the user id.",
+            )
+    known = ", ".join(sorted(str(p.get("email") or p.get("name")) for p in principals)) or "none"
+    raise ConflictError("no_such_principal", f"No principal matching {who!r}. Known: {known}")
+
+
+@app.command("list")
+def list_grants(
+    ctx: typer.Context,
+    catalog: str = _CATALOG,
+    principals: bool = typer.Option(False, "--principals", help="List candidates instead."),
+) -> None:
+    """Who has what on the catalog, and in which access mode."""
+    cli = context.of(ctx)
+    settings = cli.settings()
+    with cli.client(settings) as client:
+        payload = client.get(f"{_grants_path(cli, client, settings, catalog)}/grants")
+    if principals:
+        cli.emit(payload.get("principals") or [])
+        return
+    cli.note(f"access mode: {payload.get('access_mode')}")
+    cli.emit(payload.get("grants") or [])
+
+
+@app.command("set")
+def set_grant(
+    ctx: typer.Context,
+    user: str = typer.Option(..., "--user", help="User id, email or name."),
+    tier: str = typer.Option(..., "--tier", help="metadata, reader or writer."),
+    schema: str = typer.Option(None, "--schema", help="Narrow the grant to one schema."),
+    table: str = typer.Option(None, "--table", help="Narrow it further to one table."),
+    catalog: str = _CATALOG,
+) -> None:
+    """Grant a principal access to the catalog, a schema, or one table.
+
+    Idempotent: setting a grant that already exists updates its tier. The target
+    is keyed in the body rather than the path because the key is composite and
+    not URL-safe, which is why this is a PUT with no id in the URL.
+    """
+    if table and not schema:
+        # The server enforces this too; refusing here saves a round trip and
+        # names the missing flag rather than the missing field.
+        raise ConflictError("schema_required", "--table also needs --schema.")
+    cli = context.of(ctx)
+    settings = cli.settings()
+    with cli.client(settings) as client:
+        base = _grants_path(cli, client, settings, catalog)
+        current = client.get(f"{base}/grants")
+        body = {"user_id": _resolve_principal(current, user), "tier": tier}
+        if schema:
+            body["schema_name"] = schema
+        if table:
+            body["table_name"] = table
+        cli.emit(client.put(f"{base}/grants", json=body))
+
+
+@app.command("remove")
+def remove_grant(ctx: typer.Context, grant_id: str, catalog: str = _CATALOG) -> None:
+    """Revoke one grant by its id, as shown by `dh grant list`."""
+    cli = context.of(ctx)
+    settings = cli.settings()
+    with cli.client(settings) as client:
+        base = _grants_path(cli, client, settings, catalog)
+        client.delete(f"{base}/grants/{grant_id}")
+    cli.note(f"Removed grant {grant_id}.")
+
+
+@app.command("access-mode")
+def set_access_mode(
+    ctx: typer.Context,
+    mode: str = typer.Argument(..., help="open or scoped."),
+    catalog: str = _CATALOG,
+) -> None:
+    """Switch the catalog between open and scoped access.
+
+    `open` means every workspace member can read it; `scoped` means only what
+    grants allow. Switching to `scoped` takes effect immediately, so a catalog
+    with no grants becomes unreadable to everyone but its admins.
+    """
+    if mode not in ("open", "scoped"):
+        raise ConflictError("bad_access_mode", f"Expected open or scoped, got {mode!r}.")
+    cli = context.of(ctx)
+    settings = cli.settings()
+    with cli.client(settings) as client:
+        base = _grants_path(cli, client, settings, catalog)
+        cli.emit(client.patch(f"{base}/access-mode", json={"access_mode": mode}))

dh/commands/health.py

@@ -0,0 +1,64 @@
+"""`dh health` and `dh version` — is this deployment up, and what is it running."""
+
+from __future__ import annotations
+
+import typer
+
+from dh import __version__, context
+from dh.errors import DhError, NotFoundError
+from dh.rest import RestClient
+
+
+def health(ctx: typer.Context) -> None:
+    """Liveness, readiness, and the deployment's own health report.
+
+    Each check is reported rather than raised, so one failing dependency still
+    shows the state of the others -- which is the whole reason to run this.
+    """
+    cli = context.of(ctx)
+    settings = cli.settings()
+    with cli.client(settings) as client:
+        rows = [
+            _probe(client, "healthz", "liveness"),
+            _probe(client, "readyz", "readiness"),
+            _probe(client, "maintenance/health", "deployment"),
+        ]
+        workspace = settings.get("workspace")
+        if workspace:
+            rows.append(_probe(client, f"workspaces/{workspace}/health", "workspace"))
+    cli.emit(rows)
+
+
+def _probe(client: RestClient, path: str, name: str) -> dict[str, object]:
+    try:
+        body = client.get(path)
+    except DhError as exc:
+        return {"check": name, "ok": False, "detail": exc.message}
+    detail = body.get("status") if isinstance(body, dict) else None
+    return {"check": name, "ok": True, "detail": detail or "ok"}
+
+
+def version(ctx: typer.Context) -> None:
+    """The CLI's version, and the server's when one is reachable.
+
+    `api_version` is the server's wire-contract integer; a pipeline can assert on
+    it. A server old enough to lack `GET /api/version` reports null rather than
+    failing, matching how the connector treats the same 404.
+    """
+    cli = context.of(ctx)
+    settings = cli.settings()
+    payload: dict[str, object] = {"cli": __version__, "server": None, "api_version": None}
+    host, token = settings.get("host"), settings.get("token")
+    if host and token:
+        try:
+            with RestClient(host, token) as client:
+                body = client.get("version")
+            payload["server"] = body.get("version")
+            payload["api_version"] = body.get("api_version")
+        except NotFoundError:
+            payload["server"] = "unknown (server predates /api/version)"
+        except DhError as exc:
+            # `dh version` must work offline: it is what people run first when
+            # something is wrong, and failing here would hide the CLI's own version.
+            cli.note(f"Could not reach the server: {exc.message}")
+    cli.emit(payload)

dh/commands/profile.py

@@ -0,0 +1,80 @@
+"""`dh profile` — inspect and edit the local profile file. No HTTP."""
+
+from __future__ import annotations
+
+import typer
+
+from dh import config as config_mod
+from dh import context
+from dh.errors import ConfigError
+from dh.resolve import SECRET
+
+app = typer.Typer(name="profile", help="Inspect and edit local connection profiles.")
+
+
+@app.command("list")
+def list_profiles(ctx: typer.Context) -> None:
+    """List the configured profiles and which one is the default."""
+    cli = context.of(ctx)
+    cfg = config_mod.load()
+    if not cfg.profiles:
+        cli.note(f"No profiles in {cfg.path}. Run `dh auth login` to create one.")
+        cli.emit([])
+        return
+    default = cfg.resolved_default()
+    cli.emit(
+        [
+            {
+                "name": name,
+                "default": name == default,
+                "host": cfg.profiles[name].host,
+                "workspace": cfg.profiles[name].workspace,
+            }
+            for name in sorted(cfg.profiles)
+        ]
+    )
+
+
+@app.command("show")
+def show_profile(
+    ctx: typer.Context,
+    name: str = typer.Argument(None, help="Defaults to the default profile."),
+) -> None:
+    """Show one profile. The token is reported as present, never printed."""
+    cli = context.of(ctx)
+    cfg = config_mod.load()
+    target = name or cfg.resolved_default()
+    if not target:
+        raise ConfigError("no_profile", f"No profiles configured in {cfg.path}.")
+    profile = cfg.get(target)
+    if profile is None:
+        raise ConfigError("no_such_profile", f"No profile named {target!r} in {cfg.path}")
+    cli.emit(
+        {
+            "name": profile.name,
+            **{
+                field: ("set" if getattr(profile, field) else None)
+                if field in SECRET
+                else getattr(profile, field)
+                for field in config_mod.FIELDS
+            },
+        }
+    )
+
+
+@app.command("use")
+def use_profile(ctx: typer.Context, name: str) -> None:
+    """Make a profile the default for subsequent commands."""
+    cli = context.of(ctx)
+    cfg = config_mod.load()
+    config_mod.save(config_mod.set_default(cfg, name))
+    cli.note(f"Default profile is now {name!r}.")
+
+
+@app.command("remove")
+def remove_profile(ctx: typer.Context, name: str) -> None:
+    """Delete a profile and the token stored with it."""
+    cli = context.of(ctx)
+    cfg = config_mod.load()
+    config_mod.save(config_mod.remove(cfg, name))
+    cli.note(f"Removed profile {name!r}.")