keboola-cli 0.93.2__tar.gz → 0.95.0__tar.gz

{keboola_cli-0.93.2 → keboola_cli-0.95.0}/CLAUDE.md

@@ -392,12 +392,14 @@ kbagent auth register-projects [--stack URL|alias] [--all] [--project-id ID ...]
 #   USER-scoped "programmatic session" (kbc_at_* access token + kbc_rt_* refresh token) stored in
 #   auth.json (0600), a sibling of config.json -- config.json's schema and CURRENT_CONFIG_VERSION are
 #   unchanged. --register-projects writes each accessible project into config.json with the sentinel
-#   token `kbc-session://{project_id}`. v1 scope is the Storage + Manage paths: the CLI commands and
-#   `serve` both reach them, because `serve` delegates to the same already-guarded services (see
-#   server/dependencies.py). Everything outside those paths fails fast on a sentinel-token project
-#   (AUTH_NOT_SUPPORTED_ON_STACK) naming the static-token fallback; the authoritative list is
-#   SESSION_UNSUPPORTED_FEATURES in services/_auth_registration.py, shipped to callers as
-#   `session_unsupported_features` in --json -- do not re-derive it by hand. `dev-portal` is NOT on it
+#   token `kbc-session://{project_id}`. A session now works with nearly every command -- the Storage
+#   and Manage client paths plus (added by CLI-13) the Scheduler (flow schedule / schedule-remove),
+#   Data Streams (stream), Data Science (data-app), the semantic-layer group, the AI Service, and
+#   Storage bucket sharing (sharing share / unshare). `serve` reaches them too, because it delegates to
+#   the same already-guarded services (see server/dependencies.py). Only three features still fail fast
+#   on a sentinel-token project (AUTH_NOT_SUPPORTED_ON_STACK) naming the static-token fallback: the
+#   authoritative list is SESSION_UNSUPPORTED_FEATURES in services/_auth_registration.py, shipped to
+#   callers as `session_unsupported_features` in --json -- do not re-derive it by hand. `dev-portal` is NOT on it
 #   (it authenticates with its own identity, never a project token). Over `serve`, a session that
 #   expires at runtime answers HTTP 401 with
 #   error_code SESSION_EXPIRED -- a browser login only completes on the host. Serving session projects
@@ -447,6 +449,31 @@ kbagent auth register-projects [--stack URL|alias] [--all] [--project-id ID ...]
 #   starts the server but no `/auth/*` operation is destructive, so it affects nothing here.
 #   See docs/web-server.md.
 
+kbagent project create --url URL [--project ALIAS] [--name NAME] [--backend snowflake|bigquery] [--sync-backend-init]
+# project create (since 0.95.0, DMD-1940): the ONLY kbagent command that works from nothing --
+#   no account, no token, no `auth login`. POSTs the unauthenticated provisioning endpoint
+#   (`/manage/programmatic-projects`, gated by the `agent-provisioning` stack feature
+#   / `STACK_FEATURES__AGENT_PROVISIONING`, off on most stacks -- the COMMAND is always
+#   registered, so `--help` proves nothing about the stack; without the feature the stack 404s
+#   and this exits 1 with AUTH_NOT_SUPPORTED_ON_STACK, naming the flag and the browser path),
+#   stores the returned project-pinned session in auth.json, and registers the project in
+#   config.json under the `kbc-session://` sentinel -- becoming the default project when nothing
+#   else was registered. THE PROJECT IT CREATES IS OWNED BY NOBODY: the result's `confirm_url` is a
+#   single-use, days-limited link a human must open and sign in at to take ownership; relay it
+#   verbatim. `auth status` re-prints it as `agent_confirm_url` while it is pending, so losing the
+#   terminal is recoverable -- losing the claim window is not. Confirming REVOKES this session, so
+#   the documented next step is `kbagent auth login --stack URL`; the alias survives it (the
+#   sentinel keys on project id + stack, never on the session). Refuses with exit 5 when a session
+#   for that stack already exists -- auth.json holds one session per stack, and whoever has one has
+#   an account and should create the project in the UI. `--backend` omitted keeps the stack
+#   maintainer's own default; `--sync-backend-init` waits for backend init instead of the async
+#   default (which warns that the first Storage command may fail until it lands). The provisioning
+#   POST is never auto-retried on 5xx/429 -- it is not idempotent, and each success creates an
+#   organization, a billable project and a credit grant. A timeout is classified rather than
+#   lumped together: a connect timeout never reached the stack (retryable), a READ timeout was
+#   delivered and may have succeeded (retryable:false, message says not to repeat -- check
+#   `auth status`, whose stored session + claim link is the evidence). `--sync-backend-init`
+#   raises that call's read timeout to 300s, which can outlast an agent's foreground shell.
 kbagent project add --project NAME --url URL --token TOKEN
 kbagent project list
 kbagent project remove --project NAME
@@ -561,6 +588,9 @@ kbagent storage table-detail --project NAME --table-id ID [--branch ID]
 #   partition from INFORMATION_SCHEMA.PARTITIONS). `definition` is present on EVERY response
 #   -- untyped tables get one too -- so null means the stack omitted the key, NOT "untyped".
 #   `storage tables` (the LIST endpoint) is unaffected: the API has no `definition` include.
+#   table-detail also returns `backend_path` (the owning bucket's Storage backendPath, verbatim)
+#   and `sql_path` (quoted, directly queryable path; null when Storage reports no location) --
+#   see the semantic-layer dataset fqn note (#761); version gate in gotchas.md.
 kbagent storage create-bucket --project NAME --stage STAGE --name NAME [--description D] [--backend B] [--branch ID]
 kbagent storage create-table --project NAME --bucket-id ID --name NAME [--column COL:TYPE[(length)] ...] [--primary-key COL] [--not-null COL ...] [--default NAME=VALUE ...] [--source-table-id ID] [--source-branch-id N] [--time-partitioning-type DAY|HOUR|MONTH|YEAR] [--time-partitioning-field COL] [--time-partitioning-expiration-ms MS] [--range-partitioning-field COL --range-partitioning-start S --range-partitioning-end E --range-partitioning-interval I] [--clustering-field COL ...] [--branch ID] [--if-not-exists]
 # --column XOR --source-table-id (0.66.0+, BigQuery only): --source-table-id copies an existing table's data into the requested partition/clustering layout (schema derived from source) -> swap into place with swap-tables. Partition/clustering flags work in both modes (BigQuery only); time vs range partitioning are mutually exclusive. A non-BigQuery project fails fast (pre-flight backend check).
@@ -737,6 +767,67 @@ kbagent branch metadata-list --project NAME [--branch ID|default]
 kbagent branch metadata-get --project NAME --key KEY [--branch ID|default]
 kbagent branch metadata-set --project NAME --key KEY [--text STR | --file PATH | --stdin] [--branch ID|default]
 kbagent branch metadata-delete --project NAME --metadata-id ID [--branch ID|default]
+# branch merge is DEPRECATED (since 0.94.0): it only builds a UI URL and resets the active branch. On a
+#   project with `branches-merge-requests` use the merge-request group below; the command keeps working
+#   (it also serves projects without the feature) and now carries `deprecation` in --json.
+
+# merge-request (since 0.94.0, DMD-1900): the non-SOX Branches 2.0 lifecycle. Hidden alias `mr`. Every
+#   command except list/create takes `[--merge-request-id N | --id N] [--branch B]`: omitted, the target is
+#   the merge request OF the active branch (`branch use`) -- a branch has at most one MR, ever. Both flags at
+#   once -> exit 2. `--project` is single-project (never fans out). Status is the DERIVED state the web UI
+#   shows (in_development|in_review|approved|in_merge|merged|closed|rejected), never the raw one.
+kbagent merge-request list [--project A] [--state STATE]   # derived (in_development|in_review|approved|in_merge|merged|closed|rejected) or raw (development|published|canceled) states; `--help` lists them
+kbagent merge-request detail [--project A] [--merge-request-id N | --branch B] [--activity-log]
+kbagent merge-request create --title T [--project A] [--branch B] [--description D] [--reviewer-id ID ...] [--external-id X]
+kbagent merge-request update [--project A] [--merge-request-id N | --branch B] [--title T] [--description D] [--reviewer-id ID ...] [--external-id X]
+kbagent merge-request request-review [--project A] [--merge-request-id N | --branch B]
+kbagent merge-request approve [--project A] [--merge-request-id N | --branch B]
+kbagent merge-request request-changes [--project A] [--merge-request-id N | --branch B] [--reason TEXT]
+kbagent merge-request auto-merge --strategy immediately|scheduled|none [--at TS] [--project A] [--merge-request-id N | --branch B] [--yes]
+kbagent merge-request merge [--project A] [--merge-request-id N | --branch B] [--yes]
+kbagent merge-request conflicts [--project A] [--merge-request-id N | --branch B]
+kbagent merge-request diff --component-id C --config-id I [--project A] [--merge-request-id N | --branch B] [--format short|full] [--output PATH]
+kbagent merge-request resolve --component-id C --config-id I (--take ours|theirs|delete | --resolved JSON|@file|-) [--project A] [--merge-request-id N | --branch B] [--change-description TEXT]
+# WHAT IS DESTRUCTIVE -- a property of the COMMAND, never of a flag or of the MR's state, so a policy is
+#   evaluated from the command name alone, before any network call. Destructive = anything that moves a
+#   merge request toward or into production: `merge` (deletes the source branch, rewrites production),
+#   `request-review` (on the non-SOX default of 0 approvals it lands the MR directly in `approved`),
+#   `approve` (the last approval is what a merge waits for), `resolve` (removes the blocker a merge waits
+#   on) and `auto-merge` (arms a backend scheduler that runs every `approved` MR whose strategy is
+#   immediately/scheduled through the same MergeProcessor, on its own, retrying every tick -- a DELAYED
+#   PRODUCTION MERGE with `merge` never called; `--strategy none` disarms and rides the same command, same
+#   class). Write = shapes the MR without moving it: `create`, `update` (title/description/reviewers/
+#   external id -- auto-merge is NOT a field here), `request-changes` (moves it AWAY from approved).
+#   So `--deny-destructive` yields an agent that can observe and shape merge requests but never move one.
+#   Under --json every destructive command REQUIRES an explicit target (--merge-request-id or --branch),
+#   checked before anything is resolved: every destructive kbagent command either prompts or is told its
+#   target, and --json has no prompt. In human mode the active-branch fallback stays; `merge` and arming
+#   `auto-merge` prompt (--yes skips), the other destructive commands do not. After request-review/
+#   approve/resolve on an MR that IS armed, human mode warns that the backend will now merge (read off the
+#   write's own result, no extra GET).
+#   On a non-SOX project with the default 0 required approvals: `merge` works straight from `development`;
+#   `request-review` lands directly in `approved` (in_review is unreachable); `approve` answers 422 in every
+#   state. There is NO `close`: `request-changes` by the creator is the UI's cancel and leaves the MR in
+#   `development` (the `closed`/`rejected` derivations depend on reviewer status a 0-approval project never
+#   populates -- same blind spot as the web UI, DMD-1988). Requesting review with no reviewers selected
+#   emails EVERY project member.
+#   Conflicts: `conflicts` lists what changed on both sides (isDeleted = the DEV side's flag); `diff`
+#   classifies per path (both / only you / only production) and, when a side deleted the config wholesale,
+#   recommends the --take; `diff --output FILE` writes `resolution_candidate` (your branch's content, all
+#   five keys: name/description/isDisabled/configuration/rows -- rebase REPLACES, a missing key wipes data,
+#   the service refuses a partial body) to edit and hand back via `resolve --resolved @FILE`. No `--all`.
+#   Errors: a project without the feature answers FEATURE_NOT_ENABLED (exit 5) from every command whose
+#   target was resolved implicitly, reads included -- two wordings, missing feature vs SOX project. A
+#   scoped Storage token 403s (ACCESS_DENIED) on everything but `list`. `MR_MERGE_CONFLICT` /
+#   `MR_NOT_READY_TO_MERGE` (exit 1; the latter retryable) come from the merge 409; a truncated conflict
+#   list in the error carries `details.api_error_params_truncated: true` -- run `conflicts` for the full set.
+#   `merge` blocks for up to 10 minutes (no --wait/--timeout). Every result may carry `warnings[]`
+#   (post-merge cleanup failures, a dropped --change-description on a delete resolution). A merge whose
+#   source branch id could not be read carries `cleanup_skipped: true` + `branch_from_id_raw` (the local
+#   active-branch reset / sync unlink did NOT run -- key on the flag, not on warning text). On a project
+#   where the feature was later switched OFF, `list` rows' `allowed_actions` still recommend writes that
+#   will fail FEATURE_NOT_ENABLED (state-derived, feature-blind); `detail` carries `feature_enabled` and
+#   its hint-next respects it.
 
 kbagent workspace create --project ALIAS [--name NAME] [--backend TYPE] [--ui] [--read-only/--no-read-only]
 kbagent workspace list [--project NAME ...] [--orphaned] [--branch ID] [--qs-compatible]
@@ -916,7 +1007,17 @@ kbagent semantic-layer validate --project P [--model M] [--deep]
 kbagent semantic-layer export --project P [--model M] [--output PATH]
 kbagent semantic-layer diff (--project-a A | --file-a PATH) (--project-b B | --file-b PATH) [--model-a M] [--model-b M]
 kbagent semantic-layer add metric --project P [--model M] --name N --sql SQL --dataset TABLE_ID [--description D] [--yes]
-kbagent semantic-layer add dataset --project P [--model M] --name N --table-id TABLE_ID [--description D] [--grain G] [--primary-key COL ...] [--deep-fields]
+kbagent semantic-layer add dataset --project P [--model M] --name N --table-id TABLE_ID [--description D] [--grain G] [--primary-key COL ...] [--deep-fields] [--fqn FQN]
+# dataset fqn (#761): `add dataset` and `build` read the fqn from the table's Storage location --
+#   the owning bucket's backendPath, surfaced as `sql_path` / `backend_path` on `storage table-detail`.
+#   They used to hardcode a "KEBOOLA" database that exists in no project, so every consumer pasting
+#   the fqn into SQL failed. A LINKED bucket's path names the SOURCE project's database + schema;
+#   swapping in the consuming project's database does not resolve either. `add dataset` now needs
+#   the table to exist (one table-detail call) unless `--fqn` supplies the value verbatim; a table
+#   whose location Storage does not report fails with VALIDATION_ERROR. `build --types-workspace`
+#   queries INFORMATION_SCHEMA in that same database/schema. `validate --deep` warns FQN_MISMATCH
+#   on stored fqns that differ (pre-fix models); repair via export -> fix fqn + metric sql -> import
+#   --overwrite. Version gate lives in gotchas.md (no `(since vNEXT)` on `# ` lines).
 kbagent semantic-layer add relationship --project P [--model M] --name N --from TABLE_ID --to TABLE_ID --on EXPR [--type left|inner]
 kbagent semantic-layer add constraint --project P [--model M] --name N --constraint-type inequality|equality|range|composition|exclusion|temporal|conditional --rule "EXPR" --metrics M1,M2 [--severity error|warning|info]
 kbagent semantic-layer add glossary --project P [--model M] --term TERM [--definition D]

{keboola_cli-0.93.2 → keboola_cli-0.95.0}/CONTRIBUTING.md

@@ -856,6 +856,7 @@ make check              # CI parity: lint + format + typecheck + skill + version
 make lint               # Just the ruff linter
 make format             # Auto-format code
 make typecheck          # Static type check (Astral `ty`)
+make audit              # Audit locked dependencies for known vulnerabilities (uv audit, OSV)
 make test               # Just the test suite (no coverage)
 make test-cov           # Test suite + informational coverage report (term-missing)
 make command-sync-check # Verify every CLI command is registered + documented
@@ -889,8 +890,32 @@ Two GitHub Actions workflows guard the repo:
   (`-m "not integration"`; `e2e` self-skips without credentials). Coverage is
   printed (`--cov ... --cov-report=term-missing`) but **informational** --
   there is no `--cov-fail-under` threshold, so coverage never blocks a merge.
+- **`audit` job** (one run, Python 3.12): `uv audit --frozen` against the OSV
+  advisory database. Deliberately separate and **not** a required check -- its
+  result depends on advisories published over time, not on the diff, so a
+  finding shows red here for visibility but never blocks a merge. Run it locally
+  with `make audit`. See **Fixing an audit finding** below.
 - **`build-windows` job**: real `uv build` wheel checks (issue #320).
 
+**Fixing an audit finding.** Dependabot is the named fix channel, but it
+cannot run here. Its bundled uv is 0.12.7, and that uv must satisfy
+`[tool.uv] required-version`. A bound above 0.12.7 makes every Dependabot
+dependency PR fail with `tool_version_not_supported`. Until Dependabot
+bundles a newer uv, fix each finding by hand:
+
+- **Transitive dependency** (not in `[project.dependencies]` or a dependency
+  group): update it in the lockfile only. Run
+  `uv lock --upgrade-package NAME==FIXED_VERSION`. Do not add it to
+  `pyproject.toml` as a direct dependency. We do not own it, and a pin there
+  is debt that someone must maintain. A transitive dependency has no upper
+  bound, so the resolver keeps the new minimum version on its own. A later
+  `uv lock` keeps it.
+- **Direct dependency**: raise the constraint in `pyproject.toml` instead.
+
+Then verify two things. `uv audit --frozen` reports no vulnerabilities, and
+`uv lock --check` passes. Commit only `uv.lock`. For a direct dependency,
+also commit `pyproject.toml`.
+
 `make check` runs the same gates as the `check` + `test` CI jobs locally and is
 slightly *stricter*: its `test` target uses `-m "not e2e"`, so it also runs the
 `integration` tests that CI's `test` job deselects (`-m "not integration"`).

{keboola_cli-0.93.2 → keboola_cli-0.95.0}/Makefile

@@ -1,6 +1,6 @@
 .DEFAULT_GOAL := help
 
-.PHONY: help install install-server sync test test-unit test-integration test-e2e test-e2e-local test-e2e-invite test-e2e-feature test-e2e-stream test-e2e-auth test-file test-cov lint lint-fix format format-check typecheck typecheck-warn skill-check skill-gen version-sync version-check version-gate-check vnext-check vnext-resolve gate-floor-report release-scope-check changelog changelog-check check-error-codes check-sentinel-guards loc-check loc-report loc-baseline command-sync-check gen-command-reference endpoints-gen endpoints-check check clean hooks web-install web-dev-backend web-dev-frontend web-build web-clean
+.PHONY: help install install-server sync test test-unit test-integration test-e2e test-e2e-local test-e2e-invite test-e2e-feature test-e2e-stream test-e2e-auth test-file test-cov lint lint-fix format format-check typecheck typecheck-warn audit skill-check skill-gen version-sync version-check version-gate-check vnext-check vnext-resolve gate-floor-report release-scope-check changelog changelog-check check-error-codes check-sentinel-guards loc-check loc-report loc-baseline command-sync-check gen-command-reference endpoints-gen endpoints-check check clean hooks web-install web-dev-backend web-dev-frontend web-build web-clean
 
 help: ## Show this help message
 	@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-18s\033[0m %s\n", $$1, $$2}'
@@ -68,6 +68,9 @@ format-check: ## Check code formatting (no changes)
 typecheck: ## Run ty type-checker (Astral). Fails on any error.
 	uv run ty check
 
+audit: ## Audit locked dependencies (all groups + extras) for known vulnerabilities via OSV
+	uv audit --frozen
+
 typecheck-warn: ## Run ty in warning-only mode (always exits 0; used by hooks)
 	@uv run ty check || true
 

{keboola_cli-0.93.2 → keboola_cli-0.95.0}/PKG-INFO

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

{keboola_cli-0.93.2 → keboola_cli-0.95.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "keboola-cli"
-version = "0.93.2"
+version = "0.95.0"
 description = "AI-friendly CLI for managing Keboola projects"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -171,9 +171,12 @@ dev = [
     "ruff>=0.16",
     "ty>=0.0.33",
     "bandit>=1.9.4",
-    "pip-audit>=2.10.0",
 ]
 
+[tool.uv]
+# a higher bound breaks current Dependabot's uv lock
+required-version = ">=0.12.7"
+
 [tool.ty.src]
 include = ["src", "tests", "scripts"]
 

{keboola_cli-0.93.2 → keboola_cli-0.95.0}/scripts/check_sentinel_guards.py

@@ -113,7 +113,34 @@ CREDENTIAL_WRITE_ALLOWED = {
 # endpoint-family mixins -- every one of them a class that runs that same
 # `__init__` -- outside the check. `KeboolaClient` stays listed because it is the
 # name a reader looks for here; it is already covered as a descendant.
-PROJECT_CREDENTIAL_CLIENTS = {"_CoreClient", "KeboolaClient"}
+#
+# CLI-13: the five service clients below reach their backend over a bearer and
+# dropped `SESSION_AUTH_FEATURE`, so the `http_base.py` runtime guard no longer
+# stops a direct construction from a `kbc-session://` `project.token`. They are
+# built only by `make_session_aware_client_factory` (sentinel-aware); listing
+# them here makes Check 4 guard every OTHER construction site, restoring the net
+# their dropped guard removed.
+PROJECT_CREDENTIAL_CLIENTS = {
+    "_CoreClient",
+    "KeboolaClient",
+    "SchedulerClient",
+    "StreamClient",
+    "DataScienceClient",
+    "MetastoreClient",
+    "AiServiceClient",
+}
+
+# Check 4 exemptions keyed `<file>::<enclosing function>`, each with a reason --
+# a construction that is provably safe even though its own scope is not
+# sentinel-aware. Mirrors `CREDENTIAL_WRITE_ALLOWED` for Check 1.
+PROJECT_CLIENT_CONSTRUCTION_ALLOWED = {
+    "client/stream.py::_get_stream_client": (
+        "built from the parent client's already-resolved (token, http_auth): a "
+        "session parent carries token='' + a BearerAuth hook, a static parent a "
+        "real token + no hook, so a raw sentinel can never reach it "
+        "(test_http_base_auth.py::test_stream_sub_client_inherits_the_bearer_hook)"
+    ),
+}
 
 # Check 2: clients that reach Storage or Manage over bearer, or authenticate
 # with an identity of their own, and so must NOT be guarded. Anything else must
@@ -123,6 +150,13 @@ BEARER_CAPABLE_CLIENTS = {
     "ManageClient",  # Manage: the supported bearer path
     "AuthClient",  # talks to the auth service itself, token=""
     "DeveloperPortalClient",  # own username/password identity, never a project token
+    # CLI-13: these reach their backend over a bearer via
+    # make_session_aware_client_factory; the backends accept OAuth tokens.
+    "SchedulerClient",
+    "StreamClient",
+    "DataScienceClient",
+    "MetastoreClient",
+    "AiServiceClient",
 }
 
 # Check 3: guards that describe no user-reachable command surface.
@@ -133,15 +167,9 @@ FEATURE_EXEMPT_GUARDS = {
 # Guard wording -> the substring of the user-facing entry that covers it, so
 # both can read naturally without being byte-identical.
 FEATURE_ALIASES = {
-    "The Keboola AI Service": "AI Service",
-    "The Scheduler Service": "Scheduler Service",
-    "The Metastore Service (semantic layer)": "Metastore Service",
     "semantic-layer token --encrypt": "Metastore Service",
-    "The Data Science Service (data apps)": "Data Science Service",
-    "The Data Streams Service": "Data Streams Service",
     "The importable SDK Client": "importable SDK",
     "kbagent kai": "kbagent kai",
-    "kbagent sharing (master-token path)": "kbagent sharing",
 }
 
 
@@ -390,6 +418,7 @@ def _unguarded_project_clients(root: Path = SRC_ROOT) -> list[str]:
     # same finding under a different name.
     credential_clients = _descendants_of(root, set(PROJECT_CREDENTIAL_CLIENTS))
     for path in _py_files(root):
+        rel = _rel(path, root)
         source = path.read_text(encoding="utf-8")
         tree = ast.parse(source)
         parents = _parent_map(tree)
@@ -408,7 +437,9 @@ def _unguarded_project_clients(root: Path = SRC_ROOT) -> list[str]:
             if _scope_is_sentinel_aware(node, parents, source):
                 continue
             scope = _enclosing_function_name(node, parents)
-            offenders.append(f"{_rel(path, root)}:{node.lineno} (in {scope})")
+            if f"{rel}::{scope}" in PROJECT_CLIENT_CONSTRUCTION_ALLOWED:
+                continue
+            offenders.append(f"{rel}:{node.lineno} (in {scope})")
     return offenders
 
 

{keboola_cli-0.93.2 → keboola_cli-0.95.0}/src/keboola_agent_cli/ai_client.py

@@ -12,6 +12,8 @@ import logging
 from typing import Any, Self
 from urllib.parse import quote
 
+import httpx
+
 from .constants import AI_SERVICE_TIMEOUT
 from .http_base import BaseHttpClient
 
@@ -28,19 +30,18 @@ class AiServiceClient(BaseHttpClient):
     Inherits _do_request() and _raise_api_error() from BaseHttpClient.
     """
 
-    SESSION_AUTH_FEATURE = "The Keboola AI Service"
-
-    def __init__(self, stack_url: str, token: str) -> None:
+    def __init__(self, stack_url: str, token: str, *, http_auth: httpx.Auth | None = None) -> None:
         self._stack_url = stack_url.rstrip("/")
         ai_base_url = self._derive_service_url(self._stack_url, "ai")
-        headers = {
-            "X-StorageApi-Token": token,
-        }
+        headers: dict[str, str] = {}
+        if http_auth is None:
+            headers["X-StorageApi-Token"] = token
         super().__init__(
             base_url=ai_base_url,
             token=token,
             headers=headers,
             timeout=AI_SERVICE_TIMEOUT,
+            http_auth=http_auth,
         )
 
     def __enter__(self) -> Self:

{keboola_cli-0.93.2 → keboola_cli-0.95.0}/src/keboola_agent_cli/auth/auth_client.py

@@ -10,16 +10,18 @@ rather than on the client, and `revoke` is a public endpoint that takes the
 token to revoke in its request body.
 
 Inherits shared retry/backoff (429/5xx) and error-mapping infrastructure from
-:class:`BaseHttpClient`, with four deliberate exceptions that keep the mapping
+:class:`BaseHttpClient`, with five deliberate exceptions that keep the mapping
 but skip the retry loop: `poll_device_token` (a polling 400 is a protocol
 state, not a failure), `refresh` (a blind retry would re-present the refresh
 token, and it runs under a wall-clock ceiling the retry loop would outlast),
-and `login_password`/`verify_mfa_totp` (a blind retry against `/v1/auth/login`
+`login_password`/`verify_mfa_totp` (a blind retry against `/v1/auth/login`
 burns extra requests against the account's rate-limit bucket before the
 server's own `X-RateLimit-Reset` guidance is even read, and against
 `/v1/auth/mfa` would replay a TOTP code the server already marked consumed --
-burning one of the account's limited MFA attempts for nothing). The last
-three share `_request_bypassing_retry`, which maps transport failures
+burning one of the account's limited MFA attempts for nothing), and
+`provision_project` (not idempotent: every success creates an organization, a
+billable project and a credit grant, so a retried 5xx mints a second one). The
+last four share `_request_bypassing_retry`, which maps transport failures
 (`httpx.TimeoutException`/`httpx.TransportError`) the way `_do_request` would
 have, since bypassing the retry loop must not also mean losing that mapping.
 `refresh` makes one further narrow exception of its own for a rotation
@@ -39,6 +41,8 @@ from urllib.parse import urlencode
 import httpx
 
 from ..constants import (
+    AGENT_PROVISIONING_PATH,
+    AGENT_PROVISIONING_SYNC_TIMEOUT,
     AUTH_CLIENT_ID,
     AUTH_DEVICE_PATH,
     AUTH_DEVICE_TOKEN_PATH,
@@ -60,6 +64,7 @@ from ..constants import (
 from ..errors import ErrorCode, KeboolaApiError
 from ..http_base import BaseHttpClient
 from .models import (
+    AgentProvisioningResponse,
     CliTokenResponse,
     DeviceAuthorization,
     DevicePollResult,
@@ -566,20 +571,33 @@ class AuthClient(BaseHttpClient):
         json: dict[str, Any],
         timeout: httpx.Timeout | float | None = None,
         action: str,
+        repeat_unsafe: str = "",
     ) -> httpx.Response:
         """Issue one request outside the shared retry loop, still mapping
         transport failures the way `_do_request` would have.
 
-        Shared by `login_password`, `verify_mfa_totp`, and `refresh`
-        (via `_post_refresh`) -- each bypasses the retry loop for its own
-        reason (see their docstrings and the module docstring), but
-        bypassing retry must not also mean losing the
+        Shared by `login_password`, `verify_mfa_totp`, `refresh` (via
+        `_post_refresh`) and `provision_project` -- each bypasses the retry
+        loop for its own reason (see their docstrings and the module
+        docstring), but bypassing retry must not also mean losing the
         `TimeoutException`/`TransportError` -> structured-error mapping
         `_do_request` gives every other call; without it, a network blip
         would escape as a raw traceback instead of a `--json` error
         envelope. `action` names what the caller was doing
         ("Signing in", "Refreshing your Keboola login", ...), reused in
-        both message templates below.
+        every message template below.
+
+        `repeat_unsafe`, when non-empty, says the call MUST NOT simply be
+        repeated and carries the remedy to print instead. It only changes
+        what happens on a timeout that was already delivered, and it exists
+        because "timed out" is two different events: a connect/pool timeout
+        never reached the server and is always safe to repeat, while a
+        read/write timeout means the request WAS sent and its outcome is
+        unknown. `BaseHttpClient._do_request` already draws exactly that
+        line (and `_non_idempotent_note` says so in prose); flattening it
+        here would tell the caller of a non-idempotent write to run it
+        again, which for `provision_project` means a second organization, a
+        second billable project and a second credit grant.
         """
         kwargs: dict[str, Any] = {"json": json}
         if timeout is not None:
@@ -587,6 +605,17 @@ class AuthClient(BaseHttpClient):
         try:
             return self._client.request(method, path, **kwargs)
         except httpx.TimeoutException as exc:
+            delivered = not isinstance(exc, httpx.ConnectTimeout | httpx.PoolTimeout)
+            if repeat_unsafe and delivered:
+                raise KeboolaApiError(
+                    message=(
+                        f"{action} at {self._base_url} timed out after the request had "
+                        f"been sent, so it may have succeeded anyway. {repeat_unsafe}"
+                    ),
+                    status_code=0,
+                    error_code=ErrorCode.TIMEOUT,
+                    retryable=False,
+                ) from exc
             raise KeboolaApiError(
                 message=f"{action} at {self._base_url} timed out. Run the command again.",
                 status_code=0,
@@ -655,6 +684,123 @@ class AuthClient(BaseHttpClient):
             raise
         raise AssertionError("unreachable: _map_auth_error always raises")
 
+    # ------------------------------------------------------------------
+    # Agent provisioning
+    # ------------------------------------------------------------------
+
+    def provision_project(
+        self,
+        *,
+        project_name: str = "",
+        backend: str | None = None,
+        sync_backend_init: bool = False,
+    ) -> AgentProvisioningResponse:
+        """Provision a brand-new Keboola project (``POST /manage/programmatic-projects``).
+
+        Unauthenticated by design -- this is the one endpoint reachable from a
+        machine with no Keboola identity at all. Answers a project-pinned,
+        Manage-less programmatic session plus a single-use ``confirmUrl`` for
+        the human who will take ownership.
+
+        Bypasses `_do_request`/the shared retry loop -- the same deliberate
+        exception `login_password`, `verify_mfa_totp` and `refresh` already
+        make (see the module docstring), and here for the strongest reason of
+        the four: the call is **not idempotent**. Every success creates an
+        organization, a billable project and a free-credit grant, so a blind
+        retry of a 5xx (or of a read timeout on a response that was already in
+        flight) mints a second project nobody asked for, holding a second slot
+        against the stack's unconfirmed-project cap, with a confirm link the
+        caller never sees. A 503 here is contention on the stack-wide
+        provisioning lock and means nothing was created; it comes back as a
+        retryable error for the *user* to repeat, deliberately not for this
+        client to repeat on its own.
+
+        A timeout is classified, not lumped together: a connect/pool timeout
+        never reached the stack and is reported retryable, while a read
+        timeout means the POST was delivered and may well have succeeded --
+        that one is reported NON-retryable and points at `auth status`, whose
+        stored session (and claim link) is the evidence of whether a project
+        exists. Telling the caller to "run the command again" there is how a
+        second organization, project and credit grant get created over a lost
+        response.
+
+        ``sync_backend_init`` also buys a much longer read budget
+        (`AGENT_PROVISIONING_SYNC_TIMEOUT`): that flag exists to hold the
+        request open until the backend is ready, so the default 30 s would
+        make the timeout above the EXPECTED outcome rather than the rare one.
+        Note it can outlast an agent's foreground tool-shell timeout -- the
+        async default (no flag) is the one to use there.
+
+        ``backend`` of None keeps the stack maintainer's own default. The
+        ``clientId`` is sent for audit attribution: every org/project event of
+        this flow carries the stack's shared agent admin as actor, so without
+        it the audit log says only "the shared admin did it".
+        """
+        body: dict[str, Any] = {"clientId": AUTH_CLIENT_ID}
+        if project_name:
+            body["projectName"] = project_name
+        if backend:
+            body["backend"] = backend
+        if sync_backend_init:
+            body["syncBackendInit"] = True
+
+        response = self._request_bypassing_retry(
+            "POST",
+            AGENT_PROVISIONING_PATH,
+            json=body,
+            # `--sync-backend-init` keeps the response open until the backend
+            # is ready, well past the 30 s client default.
+            timeout=AGENT_PROVISIONING_SYNC_TIMEOUT if sync_backend_init else None,
+            action="Creating a Keboola project",
+            repeat_unsafe=(
+                "Do NOT just run it again -- that would create a second project. "
+                "Check with `kbagent auth status --stack "
+                f"{self._base_url}`: if a session is reported, the project was "
+                "created and the claim link is printed there."
+            ),
+        )
+        if response.status_code >= 400:
+            self._raise_provisioning_error(response)
+        return AgentProvisioningResponse.model_validate(response.json())
+
+    def _raise_provisioning_error(self, response: httpx.Response) -> NoReturn:
+        """Map a failed provisioning response, naming the right remedy on 404.
+
+        A 404 means the `agent-provisioning` stack feature
+        (STACK_FEATURES__AGENT_PROVISIONING) is off -- the endpoint is
+        fail-closed exactly like the rest of this client's surface, and the
+        command itself is always registered, so this response is the ONLY
+        place a caller learns the capability is missing here. The message
+        therefore has to carry the whole answer: what is missing, who can
+        turn it on, and what to do instead meanwhile.
+
+        It cannot go through `_map_auth_error`, whose 404 message is about
+        *browser login*: that one tells the caller to paste a token, which
+        is exactly what a caller of THIS command does not have.
+
+        The body is never parsed here. A stack without the route can answer
+        404 as HTML from a legacy dispatcher, and reading a server message
+        out of that would replace a useful sentence with markup.
+        """
+        if response.status_code == 404:
+            raise KeboolaApiError(
+                message=(
+                    f"Creating a Keboola project from the CLI is not available on "
+                    f"{self._base_url}. It needs the `agent-provisioning` stack feature "
+                    "(STACK_FEATURES__AGENT_PROVISIONING), which is off on this stack -- "
+                    "ask the stack operator to enable it, or use another stack. To use a "
+                    f"project that already exists: create one at {self._base_url} in a "
+                    f"browser, then connect it with `kbagent auth login --stack "
+                    f"{self._base_url}` or `kbagent project add --project <alias> --url "
+                    f"{self._base_url} --token <token>`."
+                ),
+                status_code=404,
+                error_code=ErrorCode.AUTH_NOT_SUPPORTED_ON_STACK,
+                retryable=False,
+            )
+        super()._raise_api_error(response, self._base_url)
+        raise AssertionError("unreachable: BaseHttpClient._raise_api_error always raises")
+
     def introspect(self, access_token: str) -> IntrospectResponse:
         """Fetch session metadata + accessible projects for a live access token.