keboola-cli 0.63.4__py3-none-any.whl

keboola_agent_cli/commands/serve.py

@@ -0,0 +1,272 @@
+"""kbagent serve - launch the FastAPI HTTP server.
+
+Wraps all kbagent services as REST endpoints. Print the bearer token to
+stdout on startup so the Node.js BFF (or any other client) can read it.
+
+With ``--ui`` the same process additionally serves the built React SPA
+from ``web/frontend/dist`` and pre-injects the bearer token into the
+HTML, so end-users don't need to spawn a Node BFF or paste tokens.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import secrets
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+
+import typer
+
+from ..constants import ENV_CONVERSATION_ID
+
+logger = logging.getLogger(__name__)
+
+ENV_AUTH_TOKEN = "KBAGENT_SERVE_TOKEN"
+ENV_UI_DIST = "KBAGENT_UI_DIST"
+
+
+def _default_conversation_id() -> str:
+    """Generate a conversation ID for a fresh ``kbagent serve`` session.
+
+    Format: ``serve-<UTC-timestamp>-<8 hex>``. The timestamp prefix makes
+    log scanning by start time trivial; the hex suffix disambiguates
+    rapid restarts in the same minute. The ``serve-`` prefix is how
+    observability dashboards filter "human-driven session" vs other
+    integrations.
+
+    Reads ``KBAGENT_CONVERSATION_ID`` and reuses it when present so a
+    caller that pre-set the var (CI, supervisor scripts, debugging across
+    a restart) keeps a stable session ID across kbagent serve restarts.
+    """
+    existing = os.environ.get(ENV_CONVERSATION_ID, "").strip()
+    if existing:
+        return existing
+    stamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ")
+    return f"serve-{stamp}-{secrets.token_hex(4)}"
+
+
+def _autodetect_ui_dist() -> Path | None:
+    """Find the built React SPA across install layouts.
+
+    Search order (first match wins):
+    1) ``$KBAGENT_UI_DIST`` env var -- explicit override, never auto-overridden.
+    2) ``keboola_agent_cli/_ui_dist`` *inside the installed package* --
+       populated at wheel build time by the ``hatch_build.py`` hook. This
+       is what ``uv tool install git+...`` and ``pip install`` from PyPI
+       both produce when Node is available (or a maintainer pre-built it).
+    3) ``<repo>/web/frontend/dist`` resolved relative to this source file --
+       editable installs (``uv pip install -e .``) plus local clones.
+    4) ``<cwd>/web/frontend/dist`` -- last-resort for unusual layouts.
+
+    Returns ``None`` if no candidate exists; the caller then surfaces a
+    "no UI bundled" error with rebuild instructions tailored to the
+    likely install method.
+    """
+    env = os.environ.get(ENV_UI_DIST)
+    if env:
+        p = Path(env).expanduser().resolve()
+        return p if (p / "index.html").exists() else None
+
+    # commands/serve.py -> commands -> keboola_agent_cli/ -> _ui_dist
+    bundled = Path(__file__).resolve().parent.parent / "_ui_dist"
+    if (bundled / "index.html").exists():
+        return bundled
+
+    # commands/serve.py -> commands -> keboola_agent_cli -> src -> repo
+    repo_dist = Path(__file__).resolve().parents[3] / "web" / "frontend" / "dist"
+    if (repo_dist / "index.html").exists():
+        return repo_dist
+
+    cwd_dist = Path.cwd() / "web" / "frontend" / "dist"
+    if (cwd_dist / "index.html").exists():
+        return cwd_dist
+    return None
+
+
+def serve_command(
+    host: str = typer.Option(
+        "127.0.0.1",
+        "--host",
+        help="Bind host. Default 127.0.0.1 (localhost-only).",
+    ),
+    port: int = typer.Option(
+        8001,
+        "--port",
+        help="Bind port. Default 8001 to leave 8000 for the Node BFF.",
+    ),
+    reload: bool = typer.Option(
+        False,
+        "--reload",
+        help="Auto-reload on code changes (uvicorn --reload).",
+    ),
+    log_level: str = typer.Option(
+        "info",
+        "--log-level",
+        help="uvicorn log level: critical, error, warning, info, debug, trace.",
+    ),
+    cors_origin: list[str] = typer.Option(
+        None,
+        "--cors-origin",
+        help="Add a CORS origin (repeatable). Default: localhost:5173 / 8000.",
+    ),
+    config_dir: str | None = typer.Option(
+        None,
+        "--config-dir",
+        help="Override config directory path (matches kbagent --config-dir).",
+    ),
+    ui: bool = typer.Option(
+        False,
+        "--ui",
+        help=(
+            "Mount the built React SPA at / so a single uvicorn process serves "
+            "both the API and the UI. ``GET /`` sets an HttpOnly `kbagent_session` "
+            "cookie (SameSite=Strict, Path=/) so the browser boots already "
+            "authenticated -- no Node BFF, no paste step, no token in the JS "
+            "heap or URL. Run `make web-build` once to produce the dist/ folder."
+        ),
+    ),
+    ui_dist: str | None = typer.Option(
+        None,
+        "--ui-dist",
+        help=(
+            "Override the path to the built React dist/ directory. Defaults to "
+            "<repo>/web/frontend/dist relative to the package, or $KBAGENT_UI_DIST. "
+            "Implies --ui."
+        ),
+    ),
+) -> None:
+    """Launch the kbagent HTTP API server.
+
+    The server prints a bearer token on startup. Set ``KBAGENT_SERVE_TOKEN``
+    in advance to pin a value (useful for the Node BFF dev workflow).
+    """
+    # Probe the optional server extras up front so users get a friendly
+    # install hint instead of a Python traceback. We catch BOTH imports
+    # (uvicorn AND the FastAPI surface that ``..server`` pulls in) because
+    # a partial install (one extra present, the other not) was producing
+    # the legacy "ModuleNotFoundError: No module named 'fastapi'" raw
+    # traceback in 0.40.0 -- the previous guard only watched uvicorn.
+    try:
+        import uvicorn
+
+        from ..server import create_app
+    except ModuleNotFoundError as exc:  # pragma: no cover
+        missing = exc.name or "server extras"
+        typer.echo(
+            f"\nkbagent serve requires the optional 'server' extras "
+            f"(missing: {missing}).\n\n"
+            "Reinstall with the [server] extras:\n\n"
+            "  # If you installed via uv tool install (recommended for end users):\n"
+            "  uv tool install --force --with 'keboola-cli[server]' \\\n"
+            "    git+https://github.com/keboola/cli\n\n"
+            "  # If you have a local checkout (development):\n"
+            "  uv pip install -e '.[server]'\n",
+            err=True,
+        )
+        raise typer.Exit(code=1) from None
+
+    auth_token = os.environ.get(ENV_AUTH_TOKEN) or secrets.token_urlsafe(32)
+    os.environ[ENV_AUTH_TOKEN] = auth_token
+
+    # Generate a stable conversation ID for this serve session and export it
+    # to env so child processes (MCP subprocess, AI agent CLI invocations,
+    # scheduled `kbagent http` calls) inherit it and emit X-Conversation-ID
+    # on every Keboola API request. Otherwise observability shows
+    # "Conversation ID not set" in `kbagent doctor`.
+    conversation_id = _default_conversation_id()
+    os.environ[ENV_CONVERSATION_ID] = conversation_id
+
+    cors = list(cors_origin) if cors_origin else None
+
+    serve_url = f"http://{host}:{port}"
+
+    # Resolve --ui/--ui-dist. Either flag opts in; --ui-dist additionally
+    # pins the path. If --ui is on but no dist found, abort with the
+    # "run make web-build" hint instead of silently launching API-only.
+    resolved_ui_dist: str | None = None
+    if ui or ui_dist:
+        candidate = Path(ui_dist).expanduser().resolve() if ui_dist else _autodetect_ui_dist()
+        if candidate is None or not (candidate / "index.html").exists():
+            bundled = Path(__file__).resolve().parent.parent / "_ui_dist"
+            repo_dist = Path(__file__).resolve().parents[3] / "web" / "frontend" / "dist"
+            cwd_dist = Path.cwd() / "web" / "frontend" / "dist"
+            typer.echo(
+                "--ui: no built React SPA found.\n"
+                "\n"
+                "  Searched these locations (none had index.html):\n"
+                f"    1. $KBAGENT_UI_DIST    {os.environ.get(ENV_UI_DIST, '(unset)')}\n"
+                f"    2. installed package   {bundled}\n"
+                f"    3. repo checkout       {repo_dist}\n"
+                f"    4. cwd                 {cwd_dist}\n"
+                "\n"
+                "  How to fix:\n"
+                "    - From git checkout: `make web-build` then re-run.\n"
+                "    - From `uv tool install git+...`: re-install with Node 20+\n"
+                "      on PATH; the build hook will compile the SPA automatically.\n"
+                "    - Or pin a path: `kbagent serve --ui-dist /path/to/dist`.",
+                err=True,
+            )
+            raise typer.Exit(code=1) from None
+        resolved_ui_dist = str(candidate)
+
+    app = create_app(
+        config_dir=config_dir,
+        auth_token=auth_token,
+        cors_origins=cors,
+        serve_url=serve_url,
+        ui_dist=resolved_ui_dist,
+    )
+
+    if resolved_ui_dist:
+        # UI mode: the user opens the browser directly; there is no BFF to
+        # paste the token into. The token is still printed so scripted
+        # callers / curl one-liners keep working.
+        sys.stdout.write(
+            "\n"
+            "  kbagent serve  (single-process UI mode)\n"
+            f"  ├─ open:      http://{host}:{port}/\n"
+            f"  ├─ api docs:  http://{host}:{port}/docs\n"
+            f"  ├─ ui dist:   {resolved_ui_dist}\n"
+            f"  ├─ conv id:   {conversation_id}\n"
+            f"  └─ token:     {auth_token}\n"
+            "\n"
+            "  Browser is auto-authenticated via an HttpOnly kbagent_session cookie\n"
+            "  set on GET /. Token never enters the JS heap or the URL.\n"
+            f"  For curl / scripts: Authorization: Bearer {auth_token}\n"
+            "\n"
+            "  For `kbagent http` in another terminal (bash/zsh):\n"
+            f"    export KBAGENT_SERVE_URL=http://{host}:{port}\n"
+            f"    export KBAGENT_SERVE_TOKEN={auth_token}\n"
+            f"    export KBAGENT_CONVERSATION_ID={conversation_id}\n"
+            "\n"
+        )
+    else:
+        sys.stdout.write(
+            "\n"
+            "  kbagent serve\n"
+            f"  ├─ host:      http://{host}:{port}\n"
+            f"  ├─ docs:      http://{host}:{port}/docs\n"
+            f"  ├─ openapi:   http://{host}:{port}/openapi.json\n"
+            f"  ├─ conv id:   {conversation_id}\n"
+            f"  └─ token:     {auth_token}\n"
+            "\n"
+            f"  Set {ENV_AUTH_TOKEN}={auth_token} for the Node BFF.\n"
+            "  Tip: `kbagent serve --ui` mounts the React SPA on the same port.\n"
+            "\n"
+            "  For `kbagent http` in another terminal (bash/zsh):\n"
+            f"    export KBAGENT_SERVE_URL=http://{host}:{port}\n"
+            f"    export KBAGENT_SERVE_TOKEN={auth_token}\n"
+            f"    export KBAGENT_CONVERSATION_ID={conversation_id}\n"
+            "\n"
+        )
+    sys.stdout.flush()
+
+    uvicorn.run(
+        app,
+        host=host,
+        port=port,
+        reload=reload,
+        log_level=log_level,
+    )

keboola_agent_cli/commands/sharing.py

@@ -0,0 +1,340 @@
+"""Sharing commands - cross-project bucket sharing and linking.
+
+Enable data sharing between Keboola projects:
+- share/unshare: control bucket visibility (requires master token)
+- link/unlink: create/remove linked buckets in target projects
+- list: browse available shared buckets
+"""
+
+import typer
+
+from ..errors import ConfigError, ErrorCode, KeboolaApiError
+from ._helpers import (
+    check_cli_permission,
+    emit_project_warnings,
+    get_formatter,
+    get_service,
+    map_error_to_exit_code,
+)
+
+sharing_app = typer.Typer(
+    help=(
+        "Cross-project bucket sharing and linking.\n\n"
+        "share/unshare require a master token (org membership). "
+        "Set via KBC_MASTER_TOKEN_{ALIAS} or KBC_MASTER_TOKEN env var.\n\n"
+        "list/link/unlink work with the regular project token."
+    )
+)
+
+
+@sharing_app.callback(invoke_without_command=True)
+def _sharing_permission_check(ctx: typer.Context) -> None:
+    check_cli_permission(ctx, "sharing")
+
+
+@sharing_app.command("list")
+def sharing_list(
+    ctx: typer.Context,
+    project: list[str] | None = typer.Option(
+        None,
+        "--project",
+        help="Project alias (repeatable). Omit to query all projects.",
+    ),
+) -> None:
+    """List shared buckets available for linking.
+
+    Shows buckets shared within your organization that can be linked
+    into your projects. Uses the regular project token.
+    """
+    formatter = get_formatter(ctx)
+    service = get_service(ctx, "sharing_service")
+
+    try:
+        result = service.list_shared(aliases=project)
+    except ConfigError as exc:
+        formatter.error(message=exc.message, error_code=ErrorCode.CONFIG_ERROR)
+        raise typer.Exit(code=5) from None
+
+    if formatter.json_mode:
+        formatter.output(result)
+    else:
+        from rich.table import Table
+
+        buckets = result["shared_buckets"]
+        if not buckets:
+            formatter.console.print("[dim]No shared buckets found.[/dim]")
+            return
+
+        table = Table(title="Shared Buckets")
+        table.add_column("Source Project", style="bold")
+        table.add_column("Bucket ID", style="cyan")
+        table.add_column("Sharing Type", style="dim")
+        table.add_column("Backend", style="dim")
+        table.add_column("Tables", justify="right")
+        table.add_column("Rows", justify="right")
+
+        for b in buckets:
+            table.add_row(
+                f"{b['source_project_name']} (#{b['source_project_id']})",
+                b["source_bucket_id"],
+                b["sharing"],
+                b["backend"],
+                str(len(b.get("tables", []))),
+                str(b["rows_count"]),
+            )
+
+        formatter.console.print(table)
+        emit_project_warnings(formatter, result)
+
+
+@sharing_app.command("share")
+def sharing_share(
+    ctx: typer.Context,
+    project: str = typer.Option(
+        ...,
+        "--project",
+        help="Project alias that owns the bucket to share.",
+    ),
+    bucket_id: str = typer.Option(
+        ...,
+        "--bucket-id",
+        help="Bucket ID to share (e.g. out.c-data).",
+    ),
+    sharing_type: str = typer.Option(
+        ...,
+        "--type",
+        help=(
+            "Sharing type: 'organization' (all org members), "
+            "'organization-project' (all project members in org), "
+            "'selected-projects' (specific projects, use --target-project-ids), "
+            "'selected-users' (specific users, use --target-users)."
+        ),
+    ),
+    target_project_ids: str | None = typer.Option(
+        None,
+        "--target-project-ids",
+        help="Comma-separated project IDs (required for --type selected-projects).",
+    ),
+    target_users: str | None = typer.Option(
+        None,
+        "--target-users",
+        help="Comma-separated email addresses (required for --type selected-users).",
+    ),
+) -> None:
+    """Enable sharing on a bucket.
+
+    Requires a master token with organization membership. Set via env var:
+
+      KBC_MASTER_TOKEN_{ALIAS}  (project-specific, e.g. KBC_MASTER_TOKEN_PROD)
+      KBC_MASTER_TOKEN          (global fallback)
+
+    Falls back to the project's configured token if no master token is set.
+    """
+    formatter = get_formatter(ctx)
+    service = get_service(ctx, "sharing_service")
+
+    # Parse target lists
+    parsed_project_ids: list[int] | None = None
+    parsed_users: list[str] | None = None
+
+    if sharing_type == "selected-projects":
+        if not target_project_ids:
+            formatter.error(
+                message="--target-project-ids is required for --type selected-projects",
+                error_code=ErrorCode.USAGE_ERROR,
+            )
+            raise typer.Exit(code=2)
+        parsed_project_ids = [int(pid.strip()) for pid in target_project_ids.split(",")]
+
+    if sharing_type == "selected-users":
+        if not target_users:
+            formatter.error(
+                message="--target-users is required for --type selected-users",
+                error_code=ErrorCode.USAGE_ERROR,
+            )
+            raise typer.Exit(code=2)
+        parsed_users = [u.strip() for u in target_users.split(",")]
+
+    try:
+        result = service.share(
+            alias=project,
+            bucket_id=bucket_id,
+            sharing_type=sharing_type,
+            target_project_ids=parsed_project_ids,
+            target_users=parsed_users,
+        )
+    except ConfigError as exc:
+        formatter.error(message=exc.message, error_code=ErrorCode.CONFIG_ERROR)
+        raise typer.Exit(code=5) from None
+    except KeboolaApiError as exc:
+        formatter.error(message=exc.message, error_code=exc.error_code, retryable=exc.retryable)
+        raise typer.Exit(code=map_error_to_exit_code(exc)) from None
+
+    if formatter.json_mode:
+        formatter.output(result)
+    else:
+        formatter.success(result["message"])
+
+
+@sharing_app.command("unshare")
+def sharing_unshare(
+    ctx: typer.Context,
+    project: str = typer.Option(
+        ...,
+        "--project",
+        help="Project alias that owns the shared bucket.",
+    ),
+    bucket_id: str = typer.Option(
+        ...,
+        "--bucket-id",
+        help="Bucket ID to stop sharing (e.g. out.c-data).",
+    ),
+) -> None:
+    """Disable sharing on a bucket.
+
+    Fails if other projects still have linked buckets pointing to it.
+
+    Requires a master token (see 'sharing share --help' for env var details).
+    """
+    formatter = get_formatter(ctx)
+    service = get_service(ctx, "sharing_service")
+
+    try:
+        result = service.unshare(alias=project, bucket_id=bucket_id)
+    except ConfigError as exc:
+        formatter.error(message=exc.message, error_code=ErrorCode.CONFIG_ERROR)
+        raise typer.Exit(code=5) from None
+    except KeboolaApiError as exc:
+        formatter.error(message=exc.message, error_code=exc.error_code, retryable=exc.retryable)
+        raise typer.Exit(code=map_error_to_exit_code(exc)) from None
+
+    if formatter.json_mode:
+        formatter.output(result)
+    else:
+        formatter.success(result["message"])
+
+
+@sharing_app.command("link")
+def sharing_link(
+    ctx: typer.Context,
+    project: str = typer.Option(
+        ...,
+        "--project",
+        help="Target project alias where the linked bucket will be created.",
+    ),
+    source_project_id: int = typer.Option(
+        ...,
+        "--source-project-id",
+        help="ID of the project that owns the shared bucket.",
+    ),
+    bucket_id: str = typer.Option(
+        ...,
+        "--bucket-id",
+        help="Source bucket ID to link (e.g. out.c-data).",
+    ),
+    name: str | None = typer.Option(
+        None,
+        "--name",
+        help="Display name for the linked bucket. Auto-generated if omitted.",
+    ),
+) -> None:
+    """Link a shared bucket into a project.
+
+    Creates a read-only linked bucket in the target project that mirrors
+    the source bucket's tables. Uses the regular project token
+    (no master token needed).
+
+    Use 'sharing list' to discover available shared buckets.
+    """
+    formatter = get_formatter(ctx)
+    service = get_service(ctx, "sharing_service")
+
+    try:
+        result = service.link(
+            alias=project,
+            source_project_id=source_project_id,
+            source_bucket_id=bucket_id,
+            name=name,
+        )
+    except ConfigError as exc:
+        formatter.error(message=exc.message, error_code=ErrorCode.CONFIG_ERROR)
+        raise typer.Exit(code=5) from None
+    except KeboolaApiError as exc:
+        formatter.error(message=exc.message, error_code=exc.error_code, retryable=exc.retryable)
+        raise typer.Exit(code=map_error_to_exit_code(exc)) from None
+
+    if formatter.json_mode:
+        formatter.output(result)
+    else:
+        formatter.success(result["message"])
+
+
+@sharing_app.command("unlink")
+def sharing_unlink(
+    ctx: typer.Context,
+    project: str = typer.Option(
+        ...,
+        "--project",
+        help="Project alias containing the linked bucket.",
+    ),
+    bucket_id: str = typer.Option(
+        ...,
+        "--bucket-id",
+        help="Linked bucket ID to remove (e.g. in.c-shared-data).",
+    ),
+) -> None:
+    """Remove a linked bucket from a project.
+
+    Deletes the linked bucket. Does not affect the source bucket or
+    other projects that have linked it. Uses the regular project token.
+    """
+    formatter = get_formatter(ctx)
+    service = get_service(ctx, "sharing_service")
+
+    try:
+        result = service.unlink(alias=project, bucket_id=bucket_id)
+    except ConfigError as exc:
+        formatter.error(message=exc.message, error_code=ErrorCode.CONFIG_ERROR)
+        raise typer.Exit(code=5) from None
+    except KeboolaApiError as exc:
+        formatter.error(message=exc.message, error_code=exc.error_code, retryable=exc.retryable)
+        raise typer.Exit(code=map_error_to_exit_code(exc)) from None
+
+    if formatter.json_mode:
+        formatter.output(result)
+    else:
+        formatter.success(result["message"])
+
+
+@sharing_app.command("edges")
+def sharing_edges(
+    ctx: typer.Context,
+    project: list[str] | None = typer.Option(
+        None,
+        "--project",
+        help="Project alias to query (can be repeated for multiple projects).",
+    ),
+) -> None:
+    """Show cross-project data flow edges via bucket sharing.
+
+    Lists how data flows between projects through shared and linked buckets.
+    Each edge represents a source bucket shared to a target project.
+
+    For column-level lineage, use `lineage build` + `lineage show`.
+    """
+    formatter = get_formatter(ctx)
+    service = get_service(ctx, "lineage_service")
+
+    try:
+        result = service.get_lineage(aliases=project)
+    except ConfigError as exc:
+        formatter.error(message=exc.message, error_code=ErrorCode.CONFIG_ERROR)
+        raise typer.Exit(code=5) from None
+
+    if formatter.json_mode:
+        formatter.output(result)
+    else:
+        from ..output import format_lineage_table
+
+        format_lineage_table(formatter.console, result)
+        emit_project_warnings(formatter, result)