keboola-cli 0.96.2__tar.gz → 0.97.0__tar.gz

{keboola_cli-0.96.2 → keboola_cli-0.97.0}/CLAUDE.md

@@ -1054,7 +1054,7 @@ kbagent dev-portal deprecate --app VENDOR.APP_ID [--identity A] [--dry-run]
 kbagent encrypt values --project ALIAS --component-id ID --input JSON|@file|- [--output-file PATH]
 
 kbagent semantic-layer model list --project P
-kbagent semantic-layer model create --project P --name N [--description D] [--sql-dialect Snowflake]
+kbagent semantic-layer model create --project P --name N [--description D] [--sql-dialect Snowflake] [--scope project|organization|targeted] [--target-project ALIAS|ID ...]
 kbagent semantic-layer model delete --project P --model M [--yes]
 kbagent semantic-layer show --project P [--model M] [--type dataset|metric|relationship|constraint|glossary]
 kbagent semantic-layer search-context --project P [--pattern G ...] [--type model|dataset|metric|relationship|constraint|glossary|all] [--limit N]
@@ -1092,19 +1092,55 @@ kbagent semantic-layer import --project P --file PATH [--model M] [--types T,T,.
 kbagent semantic-layer promote --from-project A --to-project B [--from-model M] [--to-model M] [--types T,T,...] [--dry-run] [--yes]
 kbagent semantic-layer build --project P [--model M] --tables T,T,... [--name N] [--dry-run] [--keep-on-failure] [--output PATH]
 kbagent semantic-layer token --encrypt --project P --component-id C
+# scope (PSGO-140, new): visibility scope for a semantic-layer item -- "project"
+#   (owner only), "organization" (every project in the org), or "targeted" (owner +
+#   explicit --target-project grants). --scope/--target-project are also accepted by `model
+#   create` and every `add <kind>` above. --scope omitted: `model create` makes a "project"
+#   item, `add <kind>` INHERITS its model's scope (an org-level model gets org-level children;
+#   a targeted model, its target projects); an inherited organization scope is permission-gated
+#   like a typed one, and a non-org-admin gets a 403 on it (pass --scope project). --target-project takes a registered alias OR a
+#   numeric project ID (repeatable or comma-separated; an alias must be on the owner's stack);
+#   without --scope targeted it exits 2. With --scope targeted and no --target-project: a real
+#   terminal launches an interactive picker over the other projects on the stack; --json fails
+#   fast (exit 2). A bad alias/ID/--scope/--type is a usage error (exit 2), never a traceback.
+#   Creating directly at --scope organization requires the organization-admin ROLE (403
+#   otherwise) -- an ordinary token instead uses `scope request-create` + an org-admin's
+#   `scope set --scope organization`. Elevation is ONE-WAY (no downgrade endpoint), which is why
+#   every `--scope organization` (here and on `model create` / `add <kind>`) is destructive-class
+#   (FLAG_ESCALATIONS). `edit`, `import --overwrite` and `promote` update in place (PUT): an item
+#   keeps its id, scope, grants and pending elevation request. `scope add|remove` merge into the
+#   grants client-side (not atomic; refused from a project that does not own the item, because
+#   the server hides the grants from a non-owner -- use `scope set --target-project` there).
+#   Verbs follow the CLI spec (#791): get / add / remove / set / request-create / request-delete /
+#   request-list; `scope set` takes exactly ONE of --scope organization, --target-project (replace
+#   the whole list) or --clear.
+kbagent semantic-layer scope get --project P --type model|dataset|metric|relationship|constraint|glossary --context-id ID
+kbagent semantic-layer scope add --project P --type T --context-id ID --target-project ALIAS|ID [--target-project ...]
+kbagent semantic-layer scope remove --project P --type T --context-id ID --target-project ALIAS|ID [--target-project ...]
+kbagent semantic-layer scope set --project P --type T --context-id ID (--scope organization | --target-project ALIAS|ID [...] | --clear) [--dry-run] [--yes]
+kbagent semantic-layer scope request-create --project P --type T --context-id ID
+kbagent semantic-layer scope request-delete --project P --type T --context-id ID
+kbagent semantic-layer scope request-list --project P --type T [--limit N] [--offset N]
+# scope over `kbagent serve`: GET/PUT /semantic-layer/scope/{context_id}, POST/DELETE
+#   .../target-projects, PUT/DELETE .../elevation-request, GET /semantic-layer/scope/elevation-requests;
+#   POST /semantic-layer/models and /items/{kind} take `scope` + `target_projects`.
 kbagent semantic-layer reference-data list --project P [--model M]
 kbagent semantic-layer reference-data get --project P (--id ID | --dimension D)
 kbagent semantic-layer reference-data set --project P [--model M] --dimension D --members-file PATH [--dataset-id T] [--description X]
 kbagent semantic-layer reference-data delete --project P --id ID [--yes]
 # Alias: `kbagent sl ...` (hidden) is equivalent to `kbagent semantic-layer ...`.
-# semantic-layer REQUIRES A MASTER (project admin) Storage token (#711): the Metastore's
-#   auth gate -- unlike the Storage API -- rejects every valid non-master token with an opaque
-#   401 "Failed to create project scope" (the underlying MasterTokenRequiredError is swallowed
-#   server-side). kbagent reclassifies exactly that 401 to MISSING_MASTER_TOKEN (exit 3) with
-#   the remedy; other unexplained 401s anywhere map to AUTH_REJECTED instead of the false
-#   "Invalid or expired token" (INVALID_TOKEN stays for 401s that DO blame the credential).
-#   Version gate for this entry lives in gotchas.md -- `(since vNEXT)` cannot be written on
-#   these `# ` comment lines (check_version_gates.py parses them as ATX headings).
+# semantic-layer READS work with any valid, non-disabled, non-expired Storage token
+#   (0.97.0, PSGO-282): the Metastore no longer requires a master token for GET/List. WRITES
+#   (add/edit/remove/import/promote/build/scope add|remove|set) still need a project-admin token
+#   (master token or any admin-role user token) -- a non-admin token 403s on the write. Before
+#   PSGO-282 the Metastore's auth gate rejected EVERY valid non-master token, including reads,
+#   with an opaque 401 "Failed to create project scope" (#711, MasterTokenRequiredError swallowed
+#   server-side); kbagent still reclassifies exactly that 401 to MISSING_MASTER_TOKEN (exit 3) as
+#   a safety net for a deployment that predates the fix. Other unexplained 401s anywhere map to
+#   AUTH_REJECTED instead of the false "Invalid or expired token" (INVALID_TOKEN stays for 401s
+#   that DO blame the credential). Version gate for this entry lives in gotchas.md -- `(since
+#   0.97.0)` cannot be written on these `# ` comment lines (check_version_gates.py parses them as
+#   ATX headings).
 
 kbagent http get PATH [--timeout SECONDS]
 kbagent http post PATH [--body JSON|@file|-] [--timeout SECONDS]

{keboola_cli-0.96.2 → keboola_cli-0.97.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: keboola-cli
-Version: 0.96.2
+Version: 0.97.0
 Summary: AI-friendly CLI for managing Keboola projects
 Author-email: Keboola <dev@keboola.com>
 License-Expression: Apache-2.0

{keboola_cli-0.96.2 → keboola_cli-0.97.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "keboola-cli"
-version = "0.96.2"
+version = "0.97.0"
 description = "AI-friendly CLI for managing Keboola projects"
 readme = "README.md"
 requires-python = ">=3.12"

{keboola_cli-0.96.2 → keboola_cli-0.97.0}/src/keboola_agent_cli/changelog.py

@@ -26,6 +26,22 @@ from .constants import CHANGELOG_HEADLINE_MAX_CHARS
 
 # Ordered newest-first.  Each value is a list of brief one-line descriptions.
 CHANGELOG: dict[str, list[str]] = {
+    "0.97.0": [
+        "New (#715): semantic-layer items can now be shared with chosen projects or with the "
+        "whole organization, not only kept in the owning project (AI-3790). `model create` and "
+        "every `add <kind>` take `--scope project|targeted|organization` and `--target-project` "
+        "(a registered alias or a project ID). The new `semantic-layer scope` command group "
+        "shows and changes who sees an existing item: `get`, `add`, `remove` and `set`, plus "
+        "`request-create`, `request-delete` and `request-list` for requests to make an item "
+        "organization-wide. Without `--scope`, `model create` keeps the model in its project, "
+        "and `add <kind>` uses the scope of its model. Making an item organization-wide needs "
+        "the organization-admin role and cannot be reverted, so `--deny-destructive` blocks it. "
+        "`kbagent serve` has the same functions under `/semantic-layer/scope`.",
+        "Fix (#715): `semantic-layer edit`, `import --overwrite` and `promote` now update an item "
+        "in place, so it keeps its ID, its visibility and its history. Before, they deleted the "
+        "item and created it again with a new ID. A failed update changes nothing, so the "
+        "`rollback` field in the result is now always `null`.",
+    ],
     "0.96.2": [
         "Fix (#825): the `data-app` commands now label the app link `Open the app:` and the "
         "Keboola UI link `Configuration:`, so it is clear which link opens what. Before, the "

{keboola_cli-0.96.2 → keboola_cli-0.97.0}/src/keboola_agent_cli/commands/_semantic_layer_crud.py

@@ -18,7 +18,21 @@ from ._helpers import (
     get_formatter,
     get_service,
 )
-from ._semantic_layer_helpers import _handle_service_call, _is_stdin_tty
+from ._semantic_layer_helpers import (
+    ScopeChoice,
+    _handle_service_call,
+    _is_stdin_tty,
+    resolve_scope_targets,
+)
+
+_SCOPE_HELP = (
+    "Visibility: 'project' (owner only), 'organization' (every project in the org), or "
+    "'targeted' (owner + --target-project grants). Default: the model's own scope."
+)
+_TARGET_PROJECT_HELP = (
+    "Project alias or ID to grant visibility to (repeatable or comma-separated; "
+    "--scope targeted only)."
+)
 
 # ---------------------------------------------------------------------------
 # semantic-layer add -- one sub-subcommand per entity type
@@ -68,10 +82,20 @@ def add_metric(
     dataset: str = typer.Option(..., "--dataset", help="Dataset tableId this metric belongs to"),
     description: str = typer.Option("", "--description", help="Optional description"),
     yes: bool = typer.Option(False, "--yes", "-y", help="Skip the dataset-mismatch warning"),
+    scope: ScopeChoice | None = typer.Option(None, "--scope", help=_SCOPE_HELP),
+    target_project: list[str] = typer.Option([], "--target-project", help=_TARGET_PROJECT_HELP),
 ) -> None:
     """Add a metric to a semantic-layer model."""
     formatter = get_formatter(ctx)
     service = get_service(ctx, "semantic_layer_service")
+    target_projects = resolve_scope_targets(
+        ctx,
+        operation="semantic-layer.add.metric",
+        scope=scope,
+        target_project=target_project,
+        owner_alias=project,
+        inherit_from_model=(model,),
+    )
     result = _handle_service_call(
         ctx,
         service.add_metric,
@@ -84,6 +108,8 @@ def add_metric(
         assume_yes=yes,
         is_tty=_is_stdin_tty(),
         confirm_cb=typer.confirm,
+        scope=scope,
+        target_projects=target_projects,
     )
     formatter.output(result, _print_item_added("metric"))
 
@@ -115,10 +141,20 @@ def add_dataset(
             'location from Storage, e.g. \'"DB"."out.c-bucket"."table"\'.'
         ),
     ),
+    scope: ScopeChoice | None = typer.Option(None, "--scope", help=_SCOPE_HELP),
+    target_project: list[str] = typer.Option([], "--target-project", help=_TARGET_PROJECT_HELP),
 ) -> None:
     """Add a dataset (FQN read from the table's Storage location)."""
     formatter = get_formatter(ctx)
     service = get_service(ctx, "semantic_layer_service")
+    target_projects = resolve_scope_targets(
+        ctx,
+        operation="semantic-layer.add.dataset",
+        scope=scope,
+        target_project=target_project,
+        owner_alias=project,
+        inherit_from_model=(model,),
+    )
     result = _handle_service_call(
         ctx,
         service.add_dataset,
@@ -131,6 +167,8 @@ def add_dataset(
         primary_key=primary_key,
         deep_fields=deep_fields,
         fqn=fqn,
+        scope=scope,
+        target_projects=target_projects,
     )
     formatter.output(result, _print_item_added("dataset"))
 
@@ -145,10 +183,20 @@ def add_relationship(
     to: str = typer.Option(..., "--to", help="Target dataset tableId"),
     on: str = typer.Option(..., "--on", help="Join condition"),
     type_: str = typer.Option("left", "--type", help="Join type: 'left' or 'inner'."),
+    scope: ScopeChoice | None = typer.Option(None, "--scope", help=_SCOPE_HELP),
+    target_project: list[str] = typer.Option([], "--target-project", help=_TARGET_PROJECT_HELP),
 ) -> None:
     """Add a relationship between two datasets."""
     formatter = get_formatter(ctx)
     service = get_service(ctx, "semantic_layer_service")
+    target_projects = resolve_scope_targets(
+        ctx,
+        operation="semantic-layer.add.relationship",
+        scope=scope,
+        target_project=target_project,
+        owner_alias=project,
+        inherit_from_model=(model,),
+    )
     result = _handle_service_call(
         ctx,
         service.add_relationship,
@@ -159,6 +207,8 @@ def add_relationship(
         to=to,
         on=on,
         type_=type_,
+        scope=scope,
+        target_projects=target_projects,
     )
     formatter.output(result, _print_item_added("relationship"))
 
@@ -194,6 +244,8 @@ def add_constraint(
     severity: str = typer.Option(
         "warning", "--severity", help="One of: error|warning|info (the 3-level API enum)."
     ),
+    scope: ScopeChoice | None = typer.Option(None, "--scope", help=_SCOPE_HELP),
+    target_project: list[str] = typer.Option([], "--target-project", help=_TARGET_PROJECT_HELP),
 ) -> None:
     """Add a constraint."""
     formatter = get_formatter(ctx)
@@ -205,6 +257,14 @@ def add_constraint(
             error_code=ErrorCode.VALIDATION_ERROR,
         )
         raise typer.Exit(code=2)
+    target_projects = resolve_scope_targets(
+        ctx,
+        operation="semantic-layer.add.constraint",
+        scope=scope,
+        target_project=target_project,
+        owner_alias=project,
+        inherit_from_model=(model,),
+    )
     result = _handle_service_call(
         ctx,
         service.add_constraint,
@@ -215,6 +275,8 @@ def add_constraint(
         rule=rule,
         metrics=metrics_list,
         severity=severity,
+        scope=scope,
+        target_projects=target_projects,
     )
     formatter.output(result, _print_item_added("constraint"))
 
@@ -226,10 +288,20 @@ def add_glossary(
     model: str | None = typer.Option(None, "--model", help="Model name or UUID"),
     term: str = typer.Option(..., "--term", help="Glossary term"),
     definition: str = typer.Option("", "--definition", help="Optional definition"),
+    scope: ScopeChoice | None = typer.Option(None, "--scope", help=_SCOPE_HELP),
+    target_project: list[str] = typer.Option([], "--target-project", help=_TARGET_PROJECT_HELP),
 ) -> None:
     """Add a glossary term."""
     formatter = get_formatter(ctx)
     service = get_service(ctx, "semantic_layer_service")
+    target_projects = resolve_scope_targets(
+        ctx,
+        operation="semantic-layer.add.glossary",
+        scope=scope,
+        target_project=target_project,
+        owner_alias=project,
+        inherit_from_model=(model,),
+    )
     result = _handle_service_call(
         ctx,
         service.add_glossary,
@@ -237,12 +309,14 @@ def add_glossary(
         model_name_or_uuid=model,
         term=term,
         definition=definition,
+        scope=scope,
+        target_projects=target_projects,
     )
     formatter.output(result, _print_item_added("glossary"))
 
 
 # ---------------------------------------------------------------------------
-# semantic-layer edit -- DELETE+POST with rollback + rename cascade
+# semantic-layer edit -- in-place PUT + rename cascade
 # ---------------------------------------------------------------------------
 
 
@@ -250,7 +324,7 @@ edit_app = typer.Typer(
     name="edit",
     help=(
         "Edit a metric, dataset, constraint, relationship, or glossary term "
-        "(DELETE+POST with rollback)."
+        "(in-place update; keeps scope and id)."
     ),
     no_args_is_help=True,
 )
@@ -383,7 +457,7 @@ def edit_constraint(
         None, "--new-metrics", help="Comma-separated list of metric names"
     ),
 ) -> None:
-    """Edit a constraint (DELETE+POST, with local validators)."""
+    """Edit a constraint (in-place update, with local validators)."""
     formatter = get_formatter(ctx)
     service = get_service(ctx, "semantic_layer_service")
     metrics_list = (
@@ -420,7 +494,7 @@ def edit_relationship(
         None, "--new-type", help="Replace join type (left | inner)"
     ),
 ) -> None:
-    """Edit a relationship (DELETE+POST). Validates ``--new-type`` locally."""
+    """Edit a relationship (in-place update). Validates ``--new-type`` locally."""
     formatter = get_formatter(ctx)
     service = get_service(ctx, "semantic_layer_service")
     result = _handle_service_call(

keboola_cli-0.97.0/src/keboola_agent_cli/commands/_semantic_layer_helpers.py

@@ -0,0 +1,181 @@
+"""Shared helpers for the ``semantic-layer`` command group.
+
+Split out of :mod:`commands.semantic_layer` so that the ``add`` / ``edit`` /
+``remove`` sub-apps -- which live in :mod:`commands._semantic_layer_crud` --
+can reuse the same error-handling and stdin-TTY probe without forcing a
+circular import between the two command modules.
+"""
+
+from __future__ import annotations
+
+import sys
+from enum import StrEnum
+
+import typer
+
+from ..errors import ConfigError, ErrorCode, KeboolaApiError
+from ._checkbox_select import CheckboxItem, CheckboxUnavailable, checkbox_select
+from ._helpers import check_cli_operation, get_formatter, get_service, map_error_to_exit_code
+
+
+class ScopeChoice(StrEnum):
+    """Fixed values of ``--scope`` on the create commands (rendered as a click Choice)."""
+
+    PROJECT = "project"
+    ORGANIZATION = "organization"
+    TARGETED = "targeted"
+
+
+class ElevationScope(StrEnum):
+    """``scope set --scope`` accepts only ``organization`` (scope changes are one-way)."""
+
+    ORGANIZATION = "organization"
+
+
+class ItemType(StrEnum):
+    """Semantic item kinds addressable by ``scope`` commands (``--type``)."""
+
+    MODEL = "model"
+    DATASET = "dataset"
+    METRIC = "metric"
+    RELATIONSHIP = "relationship"
+    CONSTRAINT = "constraint"
+    GLOSSARY = "glossary"
+
+
+def _handle_service_call(ctx: typer.Context, func, *args, **kwargs):  # type: ignore[no-untyped-def]
+    """Run a service call, mapping ``ConfigError`` / ``KeboolaApiError`` to exit codes.
+
+    Returns the service result on success; on failure, prints the structured
+    error envelope (JSON mode) or a red error line (human mode) and raises
+    ``typer.Exit`` with the appropriate code.
+    """
+    formatter = get_formatter(ctx)
+    try:
+        return func(*args, **kwargs)
+    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,
+            details=exc.details,
+        )
+        # A bad option value is a usage error (exit 2), not a general failure.
+        is_usage_error = exc.error_code == ErrorCode.INVALID_ARGUMENT
+        raise typer.Exit(code=2 if is_usage_error else map_error_to_exit_code(exc)) from None
+
+
+def _is_stdin_tty() -> bool:
+    """Return ``True`` when stdin is attached to a TTY (interactive shell)."""
+    return hasattr(sys.stdin, "isatty") and sys.stdin.isatty()
+
+
+def resolve_scope_targets(
+    ctx: typer.Context,
+    *,
+    operation: str,
+    scope: str | None,
+    target_project: list[str] | None,
+    owner_alias: str,
+    inherit_from_model: tuple[str | None] | None = None,
+) -> list[str] | None:
+    """Validate ``--scope`` / ``--target-project`` of a create command.
+
+    Returns the ``--target-project`` values (aliases or IDs; the service
+    resolves them) for ``--scope targeted``, else ``None``. ``--scope
+    organization`` is gated here as destructive (``operation`` is the command's
+    permission key, e.g. ``semantic-layer.add.dataset``); so is an omitted
+    ``--scope`` that would inherit ``organization`` from the model
+    (``inherit_from_model=(model,)`` on the ``add`` commands). ``--target-project``
+    without ``--scope targeted`` is a usage error, never silently ignored.
+
+    With ``--scope targeted`` and no target, this is the "ask when uncertain"
+    mechanism: on a real terminal it launches the checkbox picker over every
+    OTHER registered project on the owner's stack; in a non-TTY or ``--json``
+    context it hard-fails instead of silently defaulting -- widening an
+    object's visibility across projects is not a guess this CLI makes.
+    """
+    engine = ctx.obj.get("permission_engine")
+    if scope is None and inherit_from_model is not None and engine is not None and engine.active:
+        # `add <kind>` without --scope takes its model's scope: an inherited
+        # organization scope widens visibility just like a typed one, so it goes
+        # through the same permission gate.
+        service = get_service(ctx, "semantic_layer_service")
+        inherited = _handle_service_call(
+            ctx, service.child_scope, alias=owner_alias, model_name_or_uuid=inherit_from_model[0]
+        )
+        if inherited == "organization":
+            check_cli_operation(ctx, f"{operation} --scope organization")
+    if scope == "organization":
+        check_cli_operation(ctx, f"{operation} --scope organization")
+    if scope != "targeted":
+        if target_project:
+            get_formatter(ctx).error(
+                message="--target-project requires --scope targeted.",
+                error_code=ErrorCode.INVALID_ARGUMENT,
+            )
+            raise typer.Exit(code=2)
+        return None
+    if target_project:
+        return list(target_project)
+
+    formatter = get_formatter(ctx)
+    project_service = get_service(ctx, "project_service")
+    projects = project_service.list_projects()
+    owner_stack = next((p["stack_url"] for p in projects if p["alias"] == owner_alias), None)
+    candidates = [
+        p
+        for p in projects
+        if p["alias"] != owner_alias and (owner_stack is None or p["stack_url"] == owner_stack)
+    ]
+    if not candidates:
+        formatter.error(
+            message=(
+                "--scope targeted needs at least one other registered project to "
+                "target. Register one with `kbagent project add`, pass "
+                "--target-project, or use --scope project."
+            ),
+            error_code=ErrorCode.INVALID_ARGUMENT,
+        )
+        raise typer.Exit(code=2)
+
+    if formatter.json_mode:
+        formatter.error(
+            message=(
+                "--scope targeted requires --target-project (repeatable) in "
+                "--json mode -- there is no terminal to pick from."
+            ),
+            error_code=ErrorCode.INVALID_ARGUMENT,
+        )
+        raise typer.Exit(code=2)
+
+    items = [
+        CheckboxItem(
+            label=p["alias"],
+            hint=f"{p.get('project_name', '')} ({p.get('project_id', '?')})",
+        )
+        for p in candidates
+    ]
+    try:
+        selected = checkbox_select(
+            items, title="Select project(s) to grant visibility to (targeted scope):"
+        )
+    except CheckboxUnavailable:
+        formatter.error(
+            message=(
+                "--scope targeted requires --target-project (repeatable) -- no "
+                "interactive terminal available to pick from."
+            ),
+            error_code=ErrorCode.INVALID_ARGUMENT,
+        )
+        raise typer.Exit(code=2) from None
+    if not selected:
+        formatter.error(
+            message="No target project selected. Pass --target-project or use --scope project.",
+            error_code=ErrorCode.INVALID_ARGUMENT,
+        )
+        raise typer.Exit(code=2)
+    return [candidates[i]["alias"] for i in selected]