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

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

@@ -68,6 +68,10 @@ src/keboola_agent_cli/
   constants.py          # Shared constants + dynamic APP_NAME resolution (retry params, timeouts, defaults)
   json_utils.py         # Deep-merge, set_nested_value, compute_diff utilities
   models.py             # Pydantic models shared across layers
+  effective_branch.py   # resolve_branch(): the ONLY code that applies the `branch use` active branch;
+                        #   records project + branch for the `Target:` line / `targets` key (#766)
+  project_ref.py        # resolve_project_ref(): a project ID given where an alias is expected -> the
+                        #   alias (CLI-22); applied by commands/_project_ref.py and serve's dependency
   output.py             # OutputFormatter: JSON vs Rich dual-mode output
   errors.py             # KeboolaApiError, ConfigError, ErrorCode enum, mask_token()
   config_store.py       # JSON persistence for config.json (0600 permissions)
@@ -80,7 +84,7 @@ src/keboola_agent_cli/
   http_base.py          # BaseHttpClient - shared retry/backoff + common HTTP infra
   client/               # Storage API + Queue API package (X-StorageApi-Token);
                         #   split by endpoint family (storage_tables/storage_files/configs/
-                        #   queue/tokens/branches/stream/query/workspaces/misc + _core/_transfer),
+                        #   queue/tokens/branches/stream/query/workspaces/editor/misc + _core/_transfer),
                         #   composed into one KeboolaClient via mixins (#520)
   manage_client.py      # Manage API                   (X-KBC-ManageApiToken)
   ai_client.py          # AI Service API               (component schemas, Kai)
@@ -293,6 +297,28 @@ Full author checklist: see `CONTRIBUTING.md` > "Releasing a beta (pre-release) v
     `auth register-projects` disclose and every doc surface defers to. Run
     `python scripts/check_sentinel_guards.py --list` to see the inventory.
 
+19. **Only `effective_branch.resolve_branch()` applies the active branch.**
+    Commands and services get the branch ID from it and never read
+    `ProjectConfig.active_branch_id` themselves: the function records the
+    project and branch, and `OutputFormatter` reports them (a `Target:` line
+    on stderr, `targets` in the `--json` envelope, also for `--dry-run`).
+    `tests/test_effective_branch.py` fails on a new direct read. A read that
+    only shows or manages the active branch must be on its list, with a reason.
+
+20. **Services receive project aliases, never project IDs.** `--project`
+    (and `project use`, `KBAGENT_PROJECT`, serve's `{project}` / `?project=`)
+    also takes a project ID; the root command group
+    (`commands/_project_ref.py`) translates it to the alias before the command
+    runs. A new command gets this without extra code. A new command whose
+    `--project` is not a registry lookup (a NEW alias like `project add`, an
+    offline filter like `lineage show`) must be added to `NO_LOOKUP_COMMANDS`
+    there, and an option with another name that takes an existing alias (like
+    `config clone --target-project`) to `ALIAS_OPTIONS`.
+    `tests/test_project_ref.py` fails on a new option whose flag contains
+    `project`, `alias` or `stack` until it is in `ALIAS_OPTIONS` or in the
+    test's `NOT_AN_ALIAS` list; an option with any other name (like
+    `sync clone --target`) needs that decision by hand.
+
 ## Claude Code Plugin
 
 The plugin lives here in `plugins/kbagent/` and is **published through `keboola/ai-kit`**. It exposes: a CLI (`kbagent`), three skills (`kbagent`, `kbagent-cicd-migration`, `kbagent-promotion-pipeline`), three slash commands (`/kbagent:setup`, `/keboola`, `/kbagent:review`), and two specialist subagents (`keboola-expert`, `kbagent-pr-reviewer`). All are namespaced under `kbagent:`. `/kbagent:setup` is the documented one-command first-run path (install CLI -> connect project -> `doctor`); it runs in the main context and spawns no subagent.
@@ -357,6 +383,13 @@ plugins/kbagent/
 #   settings.json -> env). Neither set = header omitted, as before. Version gate for this entry
 #   lives in gotchas.md -- a `(since vNEXT)` tag cannot be written on these `# ` comment lines,
 #   because check_version_gates.py parses them as ATX markdown headings (where a `vNEXT` is fatal).
+# --project (CLI-22) takes a registered alias OR a project ID. An alias wins; an ID registered under
+#   several aliases is CONFIG_ERROR (exit 5) listing them, unless all are on one stack and exactly one is a
+#   session alias. Same for KBAGENT_PROJECT, `project use`, `config clone --target-project`,
+#   `sync clone --target`, the `semantic-layer promote/diff` project options, `auth * --stack`, and
+#   serve's {project} / ?project= / ?stack= (path and query only, not request bodies). Not for
+#   `project add` / `project create` (new alias) or `lineage show` (offline filter). Version gate in
+#   gotchas.md.
 # Headless / token-only (0.50.0+): export KBAGENT_PROJECT_FROM_ENV=1 + KBC_TOKEN + KBC_STORAGE_API_URL to synthesize an in-memory `__env__` project (no `project add`, no config.json on disk; token never persisted). Use `--project __env__`. Same env setup also powers `kbagent serve`.
 
 kbagent auth login [--stack URL|alias] [--device-code] [--register-projects]
@@ -408,7 +441,7 @@ kbagent auth register-projects [--stack URL|alias] [--all] [--project-id ID ...]
 #   AUTH_BROWSER_UNAVAILABLE, AUTH_STATE_MISMATCH, SESSION_EXPIRED, SESSION_NOT_FOUND.
 # `auth register-projects` (0.80.0+): fixes the usability gap where nothing was registered unless
 #   --register-projects was passed at login, and where the alias offered was a slug of the project
-#   NAME (never the numeric id, so `--project 9840` never resolves). Lists every project the session
+#   NAME (never the numeric id; the id itself resolves as `--project` once registered, CLI-22). Lists every project the session
 #   can access with a collision-free suggested alias, then lets the caller pick which to register.
 #   --all selects every candidate; --project-id ID (repeatable) selects specific ones (unknown id ->
 #   ConfigError); omitting both runs an interactive arrow-key + spacebar checkbox picker (every
@@ -760,6 +793,8 @@ kbagent permissions check OPERATION
 kbagent branch list [--project NAME]
 kbagent branch create --project ALIAS --name "..." [--description "..."]
 kbagent branch use --project ALIAS --branch ID
+# branch use: every command that then picks a branch names it -- `Target:` on stderr, `targets` in
+#   --json (branch_source explicit|active_branch|git_mapping|manifest|merge_request|production). Version gate in gotchas.md (#766).
 kbagent branch reset --project ALIAS
 kbagent branch delete --project ALIAS --branch ID
 kbagent branch merge --project ALIAS [--branch ID]
@@ -868,7 +903,7 @@ kbagent workspace from-transformation --project ALIAS --component-id ID --config
 
 kbagent data-app list [--project NAME ...] [--branch ID]
 kbagent data-app detail --project NAME --app-id ID [--branch ID]
-kbagent data-app create --project ALIAS --name NAME --slug SLUG (--git-repo URL | --use-managed-git-repo) [--description STR | --description-file PATH] [--git-branch main] [--git-public/--no-git-public] [--git-username USER] [--git-pat-env VAR | --git-pat-file PATH | --git-pat-encrypted KBC::Project...] [--auth password|public] [--size tiny|small|medium|large] [--auto-suspend SECONDS] [--type python-js|python|streamlit|r|...] [--workspace/--no-workspace] [--branch ID] [--no-deploy] [--wait] [--timeout SECONDS] [--keep-on-failure] [--dry-run]
+kbagent data-app create --project ALIAS --name NAME --slug SLUG (--git-repo URL | --use-managed-git-repo) [--description STR | --description-file PATH] [--git-branch main] [--git-public/--no-git-public] [--git-username USER] [--git-pat-env VAR | --git-pat-file PATH | --git-pat-encrypted KBC::Project...] [--auth password|public] [--size tiny|small|medium|large] [--auto-suspend SECONDS] [--type python-js|python|streamlit|r|...] [--workspace/--no-workspace] [--branch ID] [--no-deploy] [--wait] [--timeout SECONDS] [--keep-on-failure] [--dry-run] [--copy] [--reveal]
 # --workspace / --no-workspace (0.87.0+): DEFAULT ON. Writes runtime.workspace.enabled=true --
 #   the ONLY switch that makes the platform provision the ephemeral workspace and inject WORKSPACE_ID,
 #   QUERY_SERVICE_URL and KBC_WORKSPACE_MANIFEST_PATH. Every app that reads Storage needs it. Before
@@ -891,11 +926,27 @@ kbagent data-app create --project ALIAS --name NAME --slug SLUG (--git-repo URL
 #   deploy pins the LATEST configVersion when a git block is present and omits it for a PURE managed
 #   repo (deploys from managedGitRepoId). Use `data-app runs` to debug a deploy that reverts to
 #   stopped (setup-phase failures produce no container logs).
-kbagent data-app deploy --project NAME --app-id ID [--config-version N] [--wait] [--timeout SECONDS] [--branch ID]
+kbagent data-app deploy --project NAME --app-id ID [--config-version N] [--wait] [--timeout SECONDS] [--branch ID] [--copy] [--reveal]
 kbagent data-app start --project NAME --app-id ID [--wait] [--timeout SECONDS]
 kbagent data-app stop --project NAME --app-id ID [--wait] [--timeout SECONDS]
 kbagent data-app delete --project NAME --app-id ID [--yes]
-kbagent data-app password --project NAME --app-id ID
+kbagent data-app password --project NAME --app-id ID [--copy] [--reveal] [--open]
+# data-app password: never prints the password unless --reveal, so it does not go into an AI
+#   agent's context. Project token only (static or session) -- the Manage token and its prompt are
+#   gone. In a terminal (human mode) it waits for `c` to copy (Enter/Esc/q finishes, 120 s timeout);
+#   without a terminal or with --json only --copy copies. Nothing copied -> exit 0,
+#   password_delivered_to null, ui_url = the Keboola UI page that shows it. --reveal + --copy =
+#   INVALID_ARGUMENT. Refuses a non-password app (VALIDATION_ERROR) and a null password (NOT_FOUND).
+#   serve: GET /data-apps/{p}/{app}/password takes no X-Manage-Token; ?reveal=true adds `password`.
+#   create --wait / deploy --wait deliver the password the same way once the app runs (shared
+#   CopyOption / RevealOption + deliver_password in commands/_data_app_password.py); there
+#   --copy / --reveal need --wait and a deploy (else INVALID_ARGUMENT, exit 2, no API call;
+#   --dry-run applies the same rules and adds a `password_delivery` plan). Without a flag and
+#   without the terminal prompt nothing is read (output as before). With a flag, JSON adds only
+#   ui_url / password_delivered_to / password (--reveal); any failed read after the deploy is a
+#   warnings[] entry, exit 0. The serve create / deploy routes are unchanged. BREAKING: scripts
+#   reading `.data.password` from `data-app password` must add --reveal.
+#   Version gate + agent rules: gotchas.md / AGENT_CONTEXT.
 kbagent data-app logs --project NAME --app-id ID [--lines N] [--since ISO8601]
 kbagent data-app runs --project NAME --app-id ID [--limit N]
 kbagent data-app secrets-set --project ALIAS --app-id ID --secret '#KEY=VALUE' [--secret ...] [--secrets-file PATH] [--branch ID] [--allow-plaintext-on-encrypt-failure] [--dry-run] [--no-hint-next]
@@ -942,7 +993,8 @@ kbagent config new --component-id ID [--name NAME] [--project NAME] [--output-di
 #   mirrors the pushed encrypted body -- placeholders would overwrite the remote on next push.
 
 # sync: GitOps -- configs as local files. init/pull/push/diff are filesystem-local (no serve REST surface).
-kbagent sync init --project ALIAS [--directory DIR] [--git-branching] [--adopt-existing]
+kbagent sync init --project ALIAS [--directory DIR] [--git-branching] [--adopt-existing] [--with-workspaces]
+# `sync init --with-workspaces` (CLI-25) sets the manifest key `syncWorkspaces`: pull/diff/push/clone then also sync shared SQL workspaces (keboola.sandboxes with no parameters.id and runtime.shared true; Python/R and legacy SQL sandboxes stay skipped), config only (services/_sync_workspace.py). A `push --force` delete removes the workspace's SQL editor sessions (Editor service, client/editor.py) before the config, `push --dry-run --force` lists them, and a plain push holds the delete back under skipped_deletions; clone warns about workspace input tables missing in the target. With --adopt-existing it turns the key on in an existing manifest. Version gate for this entry lives in gotchas.md.
 kbagent sync pull --project ALIAS [--all-projects] [--force] [--theirs] [--dry-run] [--with-samples] [--no-storage] [--no-jobs] [--job-limit N] [--branch ID]
 # `sync pull` auto-inits: if the target directory has no `.keboola/manifest.json`, pull runs `init` first, so a separate `sync init` is NOT needed for a first checkout. `sync pull --project X -d ./dir` on an empty dir writes the manifest and fetches the configs in one step.
 # `sync pull --force` is conflict-aware (since 0.53.0): locally-modified config whose remote is UNCHANGED is preserved (delta stays pushable, never silently re-stamped); a true merge conflict (local AND remote both changed since last pull) aborts (exit 1, SYNC_CONFLICT, --json lists details.conflicts); local-untouched + remote-changed takes remote.
@@ -950,6 +1002,11 @@ kbagent sync pull --project ALIAS [--all-projects] [--force] [--theirs] [--dry-r
 kbagent sync status [--directory DIR]
 kbagent sync diff --project ALIAS [--all-projects] [--directory DIR] [--branch ID]
 kbagent sync push --project ALIAS [--all-projects] [--dry-run] [--force] [--allow-plaintext-on-encrypt-failure] [--branch ID] [--no-name-drift-warnings]
+# sync push --force (#792): push deletes remote configs and rows ONLY with --force; a plain push lists them
+#   under skipped_deletions (+ skipped_deletions_reason), also in --dry-run, whose summary.deleted counts only
+#   what push would delete. A config/row deleted on the remote since the last pull diffs as remote_deleted and
+#   is never re-created (it lands in skipped). Version gate in gotchas.md.
+# sync push workspace delete (CLI-25): in a `syncWorkspaces` tree, a `push --force` that deletes a shared SQL workspace also deletes its SQL editor sessions (every user's, push branch) and their backend workspaces, which `config restore` does not bring back; `push --dry-run --force` lists them (warnings[] workspace_sessions), a plain push lists the workspace under skipped_deletions and touches no session. `--force` is destructive-class (FLAG_ESCALATIONS `sync.push --force`), so `--deny-destructive` / a cli:destructive deny blocks it while a plain push stays write-class. Version gate for this entry lives in gotchas.md.
 # sync push (since 0.91.0, #686): the manifest baseline `pull_config_hash` is stamped from the API
 #   response (or a read-back), never from disk -- push-deployed multi-statement SQL transformations
 #   (and anything disabled in the UI whose local YAML lacks `is_disabled`) no longer show permanent
@@ -964,8 +1021,8 @@ kbagent sync push --project ALIAS [--all-projects] [--dry-run] [--force] [--allo
 #   with SYNC_LEGACY_BOUNDARY telling you to pull first; genuine edits push normally.
 # sync diff/push (0.89.0+, #649): local side read from exactly ONE tree (target branch subtree, else main/); entries tracked on another branch's tree are excluded from the changeset and reported under orphaned[] + summary.orphaned (reasons + reconcile hints); fix with sync pull. Adopt-by-id is branch-aware.
 # Ignored components (since 0.91.0, #689): keboola.mcp-server-tool joins keboola.sandboxes on ALWAYS_IGNORED_COMPONENTS (the MCP server's auto-created empty mcp-workspace-<hex> configs); the manifest field ignoredComponents (.keboola/manifest.json) is now LIVE and unions with the hardcoded set, honored by pull/diff/push. pull drops manifest entries + local dirs for a newly-ignored component, reported with action "ignored" (distinct from "removed" = deleted on remote); diff filters the local side too, so a stale dir for an ignored component can never classify as DELETED -- closes the delete-dir-then-push trap that used to destroy production keboola.mcp-server-tool configs.
-kbagent sync clone --source DIR --target ALIAS --target-dir DIR [--bucket-map FILE] [--variable-values FILE] [--instance-rename FILE] [--dry-run] [--branch ID]
-# `sync clone` (0.63.0+) copies a reference synced tree into a fresh target project + parameterizes it: applies bucket_map / variable_values / instance_rename overrides (JSON/YAML files), then pushes so every config CREATEs fresh -- keboola.flow task configIds and transformation variable links are remapped reference->ULID by push Phase C/D. Idempotent: re-run with an existing --target-dir reports no_changes. Fails fast if the target already contains the reference's configs (clone needs a fresh target). Override files must be flat {id: scalar} mappings (0.89.0+): a nested mapping/list/null value is rejected with CONFIG_ERROR naming the key + actual type, instead of being silently stringified into a bogus ID. `--branch` is optional on a fresh clone. It defaults to the target's production branch, resolved from the API like `sync init`. Pass it only to target a dev branch of the target.
+kbagent sync clone --source DIR --target ALIAS --target-dir DIR [--bucket-map FILE] [--variable-values FILE] [--instance-rename FILE] [--no-create-buckets] [--dry-run] [--branch ID]
+# `sync clone` (0.63.0+) copies a reference synced tree into a fresh target project + parameterizes it: applies bucket_map / variable_values / instance_rename overrides (JSON/YAML files), then pushes so every config CREATEs fresh -- keboola.flow and keboola.orchestrator task configIds (and configRowIds), schedule targets, and transformation variable and shared-code links are remapped reference->ULID by push Phase C/D (`link_remaps` counts each kind; a link it cannot set is an `errors[]` entry, and a failed PUT is sent again by the next push). Schedules are never activated and data apps never deployed: `warnings[]` (also on --dry-run, human mode prints them) lists those, copied `KBC::` values the target cannot decrypt, and tasks that run a config not in the tree. Only the run that creates the configs reports them; a re-run returns `warnings: []`. Idempotent: re-run with an existing --target-dir reports no_changes. Fails fast if the target already contains the reference's configs (clone needs a fresh target). Override files must be flat {id: scalar} mappings (0.89.0+): a nested mapping/list/null value is rejected with CONFIG_ERROR naming the key + actual type, instead of being silently stringified into a bogus ID. `--branch` is optional on a fresh clone. It defaults to the target's production branch, resolved from the API like `sync init`. Pass it only to target a dev branch of the target. Clone recreates the reference tree's storage buckets in the target from the `storage/buckets.json` pull export BY DEFAULT -- `--no-create-buckets` skips it. Idempotent: an existing bucket is skipped, a per-bucket failure is collected in `bucket_errors`, a linked (shared) bucket is linked to the same source as in the reference (listed in `linked_buckets`; the source's sharing settings decide, a refused link lands in `bucket_errors`). Only the buckets are created, never their tables or data (the export carries no table data). Version gate in gotchas.md.
 kbagent sync branch-link --project ALIAS (--branch-id ID | --branch-name NAME) [--directory DIR]
 kbagent sync branch-unlink [--directory DIR]
 kbagent sync branch-status [--directory DIR]
@@ -1232,7 +1289,7 @@ kbagent update [--beta]
 # completes discovery first, then does the terminal exact-version reinstall and immediately
 # re-executes; failures print a copy-paste recovery command.
 kbagent changelog [--limit N] [--full]
-# Default shows a one-line summary (first sentence) per version; --full / -v expands every note.
+# Default shows first sentences: every BREAKING note of a version, plus its first other notes until at least two show; --full / -v expands every note.
 kbagent serve [--host HOST] [--port PORT] [--ui] [--ui-dist PATH] [--reload] [--log-level LVL] [--cors-origin ORIGIN] [--config-dir DIR] [--no-banner]
 # `--config-dir` on serve (since 0.91.0, #679): `serve` is the only subcommand with a --config-dir of
 #   its own, and most specific wins -- `serve --config-dir X` beats a root `kbagent --config-dir Y`,

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

@@ -353,6 +353,8 @@ When adding a new command (e.g., `kbagent storage create-foo`), you must update
 - [ ] **Service method** in `services/` -- business logic, validation, orchestration
 - [ ] **Command function** in `commands/` -- Typer options, formatter, error handling
 - [ ] **Permission registration** in `permissions.py` (`OPERATION_REGISTRY` dict)
+- [ ] **Branch choice** through `resolve_branch()` in `effective_branch.py` when the command takes `--branch` or uses the active branch -- never read `ProjectConfig.active_branch_id` directly. The function reports the branch (`Target:` line, `targets` in `--json`); `tests/test_effective_branch.py` fails on a new direct read.
+- [ ] **`--project` naming a NEW alias** -- every `--project` option also takes a project ID, translated to the alias before the command runs (`commands/_project_ref.py`, CLI-22). A command whose `--project` is not a registry lookup (a new alias like `project add`, an offline filter like `lineage show`) must be added to `NO_LOOKUP_COMMANDS` there, and an option with another name that takes an existing alias (like `config clone --target-project`) to `ALIAS_OPTIONS`. `tests/test_project_ref.py` fails on a new option whose flag contains `project`, `alias` or `stack` until it is in `ALIAS_OPTIONS` or in the test's `NOT_AN_ALIAS` list (with a reason); an option with any other name needs this decision by hand.
 - [ ] **Service wiring** in `cli.py` if adding a new service class
 - [ ] **HTTP API endpoint** in `src/keboola_agent_cli/server/routers/<group>.py` -- `kbagent serve` exposes the CLI as a REST API so external applications (Web UI, scheduled AI agents, Slack bots, Streamlit dashboards, CI pipelines) can call the platform without forking CLI subprocesses. The current convention is **1:1**: every command in a group has a matching endpoint in that group's router (e.g. `commands/flow.py` has 8 commands, `server/routers/flows.py` has 8 routes). If you add a new command, add the corresponding route. **Skip allowed** only for genuinely terminal-only commands (interactive prompts, Rich-rendered output that has no useful JSON shape, `doctor`/`init`/`update`-style infrastructure that manages kbagent itself rather than Keboola). Document any skip in the PR description with a one-line reason so reviewers don't flag it.
 
@@ -402,6 +404,8 @@ before the PR is mergeable.
 
   > **Running locally without exporting a token:** if the target project is already registered in a kbagent `config.json`, use config-dir mode -- `make test-e2e-local CONFIG_DIR=/path/to/.kbagent ALIAS=my-proj`. The harness reads the token from `config.json` at import time and promotes it into `E2E_API_TOKEN` / `E2E_URL`; an explicit `E2E_API_TOKEN` still wins.
 
+- [ ] **API call-count test for hot read paths** -- a new or changed list/detail command that users and agents run often (the `project`/`config`/`job`/`storage`/`flow` read commands and their peers) adds or updates a case in `tests/test_api_call_counts.py`. It pins the exact calls via `helpers.assert_api_calls`, which compares the method and path and, where the test pins them, the parsed query (`include_query=True`) and the token (`include_token=True`, for multi-project cases). List commands also run with 1 and 10 items and expect the same calls at both sizes: this catches a call made once per item, but not a call made once per batch or page of more than 10 items. Fixtures must look like real API payloads (several component types, a transformation with rows and storage mappings, Queue jobs with `runId`, alias and shared tables), because a per-item call that depends on a field the fixture lacks is not caught. The expected lists are a ratchet: raising one is a deliberate, reviewed change -- say why in the PR
+
 - [ ] **Run `make check`** before committing (lint + format + full test suite)
 - [ ] **Run `make typecheck`** -- `ty` must pass clean (0 diagnostics; the backlog was cleared in 0.45.0, so the gate is blocking, not warning-only)
 - [ ] **No new `tuple[...]` returns** -- multi-value returns use a `@dataclass` ([Code Quality Patterns](#code-quality-patterns))
@@ -631,7 +635,7 @@ silent-drift risks summarized in the
    Those merged PRs are **exactly** the scope of the release: the changelog
    entry and the release notes must cover each of them, and nothing else.
 2. **Edit `pyproject.toml`** -- bump `version = "X.Y.Z"`. Single source of truth; everything else derives from it. This is the release PR's defining change -- if you are doing this in a feature PR, stop and read the section intro above.
-3. **Add a changelog entry** to `src/keboola_agent_cli/changelog.py` -- ONE entry for the new version, covering **every PR merged since the last release** (step 1), no exceptions. CI fails (`make changelog-check`) if this is missing. Author it as the file's docstring describes: **one logical change per bullet** (split the release into several list items rather than one mega-paragraph), each starting with a recognised prefix (`BREAKING:`, `New:`, `Fix:`, `Change:`, `Note:`, `Security:`, ...), carrying its `(#PR)` reference, and leading with a self-contained first sentence. `kbagent changelog` shows only that first sentence per version by default (the rest is revealed by `--full`), so a buried headline or a single wall-of-text bullet reads as an unscannable blob. The first sentence is also **capped at 160 characters**, enforced by `tests/test_changelog_render.py::TestLiveChangelogHeadlines::test_newest_release_notes_are_not_truncated` (so `make check` in step 12 catches it) -- past the cap the default view and the release page show it cut mid-clause. Write a short self-contained first sentence and put the detail in the sentences after it; 2 of 0.90.0's 13 bullets needed exactly this rewrite.
+3. **Add a changelog entry** to `src/keboola_agent_cli/changelog.py` -- ONE entry for the new version, covering **every PR merged since the last release** (step 1), no exceptions. CI fails (`make changelog-check`) if this is missing. Author it as the file's docstring describes: **one logical change per bullet** (split the release into several list items rather than one mega-paragraph), each starting with a recognised prefix (`BREAKING:`, `New:`, `Fix:`, `Change:`, `Note:`, `Security:`, ...), carrying its `(#PR)` reference, and leading with a self-contained first sentence. `kbagent changelog` shows only first sentences by default: of every `BREAKING` bullet of a version, plus of the first other bullets until at least two show (the rest is revealed by `--full`). The `What's new` notice after an update shows the first sentence of every bullet. So a buried headline or a single wall-of-text bullet reads as an unscannable blob. The first sentence is also **capped at 160 characters**, enforced by `tests/test_changelog_render.py::TestLiveChangelogHeadlines::test_newest_release_notes_are_not_truncated` (so `make check` in step 12 catches it) -- past the cap the default view and the release page show it cut mid-clause. Write a short self-contained first sentence and put the detail in the sentences after it; 2 of 0.90.0's 13 bullets needed exactly this rewrite.
 4. **Replace every `vNEXT` placeholder** left behind by the feature PRs with the version being released. Do it mechanically -- never by hand, and never with a repo-wide `sed`:
    ```bash
    make vnext-resolve VERSION=X.Y.Z

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: keboola-cli
-Version: 0.95.0
+Version: 0.96.0
 Summary: AI-friendly CLI for managing Keboola projects
 Author-email: Keboola <dev@keboola.com>
 License-Expression: Apache-2.0
@@ -218,7 +218,7 @@ kbagent workspace query --project prod --workspace-id WS_ID \
 | **Agent Tasks** | Schedule AI agents inside `kbagent serve` (CRON / manual / chained). Two action flavours per task: `claude` / `codex` / `gemini` with a prompt, or a raw kbagent CLI command. Per-run cost & token timeline with authoritative Claude 4.x pricing built-in; persisted JSONL history (`0600`); live SSE replay; **Artifacts tab** auto-renders long-form markdown reports (GFM tables, Copy / Download `.md`). Subprocesses get `KBAGENT_SERVE_URL` + `KBAGENT_SERVE_TOKEN` auto-injected for self-calls via `kbagent http`. (since 0.40.0) |
 | **Workspaces** | Create Snowflake/BQ workspace, load tables, run SQL. Create from transformation config for instant debugging. Orphan detection + garbage collection. |
 | **Sharing** | Cross-project bucket sharing with org/project/user access control. Share, link, unlink. |
-| **Data apps** | First-class lifecycle for Streamlit / Flask / Node deployments (`keboola.data-apps`). `create / deploy / start / stop / password / delete` (since 0.27.0); `secrets-set / -list / -get / -remove` for `#`-prefixed runtime secrets with per-project KMS encryption (since 0.29.0); `validate-repo` pre-flight Golden Rule check that catches misconfigured git repos before a deploy (since 0.29.0); `logs` tails the container log buffer for triaging stuck deploys / runtime crashes (since 0.43.8). Hides the redeploy contract and per-project KMS encryption of git PATs. |
+| **Data apps** | First-class lifecycle for Python/JS apps (`keboola.data-apps`; `python-js` is the default type, Streamlit via `--type streamlit`). `create / deploy / start / stop / password / delete` (since 0.27.0); `secrets-set / -list / -get / -remove` for `#`-prefixed runtime secrets with per-project KMS encryption (since 0.29.0); `validate-repo` pre-flight Golden Rule check that catches misconfigured git repos before a deploy (since 0.29.0); `logs` tails the container log buffer for triaging stuck deploys / runtime crashes (since 0.43.8). Hides the redeploy contract and per-project KMS encryption of git PATs. |
 | **Project members & invitations** | `project invite` (single or `--from-csv` bulk with parallel workers), `project member-list / member-remove / member-set-role`, `project invitation-list / invitation-cancel`. Role whitelist enforced at the CLI layer; Manage API "already invited" treated as `noop` not error (since 0.29.0). |
 | **Lineage** | Column-level dependency analysis across projects. SQL/Python parsing, AI-enhanced detection, interactive web browser, Mermaid/HTML/ER export. |
 | **Semantic layer** | Define and manage a metastore semantic model per project — datasets, metrics, relationships, constraints, glossary. Validate (incl. `--deep`), export, diff two models/files, import/promote across projects, AI-assisted `build` from tables. `kbagent semantic-layer ...` (alias `sl`). |

{keboola_cli-0.95.0 → keboola_cli-0.96.0}/README.md

@@ -190,7 +190,7 @@ kbagent workspace query --project prod --workspace-id WS_ID \
 | **Agent Tasks** | Schedule AI agents inside `kbagent serve` (CRON / manual / chained). Two action flavours per task: `claude` / `codex` / `gemini` with a prompt, or a raw kbagent CLI command. Per-run cost & token timeline with authoritative Claude 4.x pricing built-in; persisted JSONL history (`0600`); live SSE replay; **Artifacts tab** auto-renders long-form markdown reports (GFM tables, Copy / Download `.md`). Subprocesses get `KBAGENT_SERVE_URL` + `KBAGENT_SERVE_TOKEN` auto-injected for self-calls via `kbagent http`. (since 0.40.0) |
 | **Workspaces** | Create Snowflake/BQ workspace, load tables, run SQL. Create from transformation config for instant debugging. Orphan detection + garbage collection. |
 | **Sharing** | Cross-project bucket sharing with org/project/user access control. Share, link, unlink. |
-| **Data apps** | First-class lifecycle for Streamlit / Flask / Node deployments (`keboola.data-apps`). `create / deploy / start / stop / password / delete` (since 0.27.0); `secrets-set / -list / -get / -remove` for `#`-prefixed runtime secrets with per-project KMS encryption (since 0.29.0); `validate-repo` pre-flight Golden Rule check that catches misconfigured git repos before a deploy (since 0.29.0); `logs` tails the container log buffer for triaging stuck deploys / runtime crashes (since 0.43.8). Hides the redeploy contract and per-project KMS encryption of git PATs. |
+| **Data apps** | First-class lifecycle for Python/JS apps (`keboola.data-apps`; `python-js` is the default type, Streamlit via `--type streamlit`). `create / deploy / start / stop / password / delete` (since 0.27.0); `secrets-set / -list / -get / -remove` for `#`-prefixed runtime secrets with per-project KMS encryption (since 0.29.0); `validate-repo` pre-flight Golden Rule check that catches misconfigured git repos before a deploy (since 0.29.0); `logs` tails the container log buffer for triaging stuck deploys / runtime crashes (since 0.43.8). Hides the redeploy contract and per-project KMS encryption of git PATs. |
 | **Project members & invitations** | `project invite` (single or `--from-csv` bulk with parallel workers), `project member-list / member-remove / member-set-role`, `project invitation-list / invitation-cancel`. Role whitelist enforced at the CLI layer; Manage API "already invited" treated as `noop` not error (since 0.29.0). |
 | **Lineage** | Column-level dependency analysis across projects. SQL/Python parsing, AI-enhanced detection, interactive web browser, Mermaid/HTML/ER export. |
 | **Semantic layer** | Define and manage a metastore semantic model per project — datasets, metrics, relationships, constraints, glossary. Validate (incl. `--deep`), export, diff two models/files, import/promote across projects, AI-assisted `build` from tables. `kbagent semantic-layer ...` (alias `sl`). |

keboola_cli-0.96.0/formal/sync/README.md

@@ -0,0 +1,130 @@
+# Formal models of the `kbagent sync` engine (issue #792)
+
+Pilot: can a small model checker find real bugs in `sync pull | diff | push`?
+`tla/` holds a TLA+ model checked with TLC. `lean/` is a separate Lean
+effort, not covered here.
+
+## What the TLA+ model covers
+
+`tla/SyncEngine.tla` is a small finite model of the engine. Every operator
+names the Python function and line range it mirrors.
+
+- **Remote**: 2 branches (`prod`, plus `dev` as a copy of prod). There are
+  2 initial config ids, and 2 more ids for configs created during the run.
+  Content versions are 0..2. One component (`mcp`) can become ignored.
+- **Local**: 2 trees (`main/`, `devt/`) and 5 directory paths. Each
+  `_config.yml` is a record with fields for the component, the id, the name
+  and the content. It also carries two abstract bits:
+  - `cosm`: a byte-only edit. It changes the RAW sha256 (`pull_hash`) but
+    not `config_hash`.
+  - `drift`: the local form of the content hashes differently from the
+    API's view of the same content (#686).
+- **Manifest**: one entry per id: `branchId`, `path`, `componentId`,
+  `pull_hash` (the RAW hash) and `pull_config_hash` (the normalized base).
+- **Actors**:
+  - **User**: edit content, cosmetic edit, `rm -rf` a directory,
+    `config new` scaffold, `config new --push --output-dir`, mark a
+    component ignored.
+  - **Remote**: edit, delete (trash looks the same to sync), create a
+    config, optionally reusing an existing config's name.
+  - **Sync**: `sync pull` (plain / `--force` / `--theirs`), `sync push`, and
+    `sync push` aborted by `ENCRYPTION_FAILED` after some of its changes
+    were already applied. Any of these can use `--branch` for either
+    branch, which also covers `branch use`.
+  - `diff` is a pure function that every invariant can call.
+- **Ghost fields**, used only by invariants:
+  - lineage (which config a file or remote config descends from);
+  - `ed`: the file holds work that is on no remote;
+  - `sv`: the remote version the file was last synced with;
+  - the user-deleted directories;
+  - flags for the last operation.
+
+**Abstracted away**:
+- rows, so I10 is not checked;
+- renames and the name-collision suffix (a pull where two configs land on
+  one path is disabled);
+- `config_hash_version` / legacy-shape migration;
+- companion code files;
+- dry-run;
+- baseline read-back failures;
+- variable and flow-task backfill.
+
+The id pool is bounded: a push that needs more new ids than are free is
+disabled. `PushAbort` applies an arbitrary strict prefix of the changes in
+path/id order. That over-approximates the diff order the code uses.
+
+## How to run
+
+The model needs Java 17 and `tla2tools.jar`.
+
+```sh
+cd formal/sync/tla
+java -XX:+UseParallelGC -cp ~/tools/tla/tla2tools.jar tlc2.TLC -workers auto \
+     -config SyncEngine.cfg SyncEngine.tla   # clean run: invariants that hold
+./run_all.sh                                 # every invariant, one TLC run each (~15 min)
+./trace.py out/<NAME>.json                   # compact counterexample
+```
+
+The depth is bounded by `MaxSteps` (a state constraint). `MaxSteps = 4`
+explores traces of up to 5 actions. BFS returns the shortest counterexample.
+
+## Results (MaxSteps = 4; up to 153k distinct states per run)
+
+| Invariant | Result |
+|---|---|
+| I3 ignored component never planned | **holds** (153,077 states; 196,569 at depth 5 on prod only) |
+| I4 diff/push act only on the source tree | **holds** (153,077 states) |
+| I7 never-fetched entry never deleted | **holds** (104,809 states, never-fetched initial entry) |
+| I1 no double create | violated: a promote push re-creates configs on every run; a resurrect followed by an `ENCRYPTION_FAILED` abort also creates a copy |
+| I2 push deletes only user-removed dirs | violated: **pull's stale-entry sweep deletes a directory the same pull just wrote, and the next push deletes the live remote config** |
+| I2b delete requires `--force` | violated: `push()` never reads `force` (S1). Fixed in the code (G); the model is unchanged |
+| I5 pull keeps local work | violated: a remote delete plus a local edit ends with plain or `--force` pull deleting the edited directory silently |
+| I6 push then diff is clean | violated on `--branch` promote (finding D, since fixed in the engine; the TLA model is unchanged). Holds on production only (30,334 states) |
+| I8 manifest matches disk | violated: the stale sweep, and a promote write-back that records a `devt/` entry for a file in `main/` |
+| I9 an aborted push is atomic | violated (strong reading): the changes before the failing one reached the API and the manifest was never saved |
+| I11 no lost remote update | violated: an adopted file with a config id is diffed 2-way, so push reverts a UI edit |
+| I11b no silent resurrect | violated: a remote delete followed by any push re-creates the config, even with no local edit (S2). Fixed in the code (H); the model is unchanged |
+| I12 a pull resolves REMOTE MODIFIED | violated: after a cosmetic edit, plain pull skips the file forever and `--force` raises a conflict (S3) |
+
+Each violation was checked against the code. The main ones were replayed
+against the real `SyncService` with a stateful fake API (the scratch harness
+from the #792 pilot). Details are in the pilot report.
+
+## Consolidated findings (A..K)
+
+The spec's suspicious spots (S1..S5), the Lean refutations (F1..F8) and the
+TLA+ counterexamples (I1..I12) overlap heavily -- several independently
+rediscover the same code path. This table is the deduplicated result, with
+the regression test for each in `tests/test_sync_formal_counterexamples.py`.
+
+| ID | Finding | Sources | Severity | Test |
+|----|---------|---------|----------|------|
+| A | Remote delete + recreate under the same name: pull writes the new config into the old directory, the stale sweep then deletes that directory; the next push DELETEs the live new config | Lean F8, TLA I2 | HIGH -- **fixed** (#792 A/C PR) | `test_a_recreate_under_same_name_does_not_delete_new_config` |
+| B | Pull compares only `_config.yml`: local edits in `transform.sql`/`code.py`/`_description.md` are silently overwritten when the remote changed, no SYNC_CONFLICT | Lean F6 | HIGH -- **FIXED** (pull's local-modification check now covers every `pull_extra_hashes` companion file) | `test_b_pull_never_overwrites_local_sql_edit` (unmarked regression guard) + `tests/test_sync_pull_companion_files.py` |
+| C | Remote delete + local edit: pull (plain/`--force`) deletes the locally-edited directory with no conflict | Lean F7, TLA I5 | HIGH -- **fixed** (#792 A/C PR) | `test_c_pull_never_deletes_locally_edited_dir_on_remote_delete` |
+| D | `sync push --branch dev` (promote) creates another dev copy of a prod-only config on every push. **Fixed** (fix/792-dev-promote-duplicates): on the promote path the target-branch entry shadows the production entry for the same `main/` dir (`sync/branch_scope.py::_promoted_paths`) | TLA I6/I1 | HIGH | `test_d_promote_push_is_idempotent`, `test_d_promote_push_diff_is_clean_and_edits_update_the_dev_copy` (regression guards) |
+| E | An untracked file carrying a config id (`config new --push --output-dir` scaffold / adopted orphan) is diffed 2-way: push overwrites a UI edit made after the scaffold was written | TLA I11 | MED | `test_e_adopted_scaffold_push_does_not_overwrite_remote_edit` |
+| F | A push aborted by `ENCRYPTION_FAILED` leaves the manifest unsaved; the retry duplicates the change(s) the aborted push already applied | TLA I1b (model trace only; replayed live for this pilot) | MED | `test_f_aborted_push_does_not_duplicate_already_created_config` |
+| G | `sync push` deletes remote configs with no `--force`; the CLI help text says `--force` gates deletion (soft delete to trash since 0.89.0, restorable) | Spec S1, Lean F1, TLA I2b | MED -- **fixed** (push deletes only with `--force`) | `test_g_push_without_force_does_not_delete_remote_config` |
+| H | A config deleted remotely by another actor is silently re-created by the next push, no warning | Spec S2, Lean F2, TLA I11b | MED -- **fixed** (diff reports `remote_deleted`, push skips it) | `test_h_push_does_not_silently_resurrect_deleted_config` |
+| I | Moving a config's directory by hand (`mv`/`git mv`) is seen as remote DELETE + CREATE under a new id | Lean F3 | LOW-MED | `test_i_moving_config_dir_is_not_delete_plus_create` |
+| J | `sync pull --branch dev` reports untouched production configs as "removed" | Spec S4 | LOW | `test_j_branch_scoped_pull_does_not_report_other_branch_configs_removed` |
+| K | A cosmetic local edit (raw vs normalized hash) blocks pull from ever applying a real remote change; `--force` raises a conflict | Spec S3, TLA I12 | LOW (documented, conservative behavior) | `test_k_cosmetic_edit_is_conservative_not_unsafe` (unmarked regression guard, not xfail) |
+
+**A and C are fixed**: a new config never lands on a stale entry's directory
+(it gets a suffixed path), the sweep never deletes a path an entry of the same
+pull owns, and a locally edited directory whose remote vanished is kept and
+reported as `skipped` by plain pull, raises `SYNC_CONFLICT` under `--force`,
+and is deleted only by `--theirs`. That is what the I2 (sweep half), I5 and I8
+(sweep half) counterexamples needed; the models themselves are unchanged, so a
+TLC/Lean rerun still reports them until the model's `Pull` is updated to match.
+Their tests are ordinary regression guards now.
+
+E, F and I reproduce on current code and are `xfail(strict=True)` (D, G and H
+are fixed) -- flipping to a hard failure the moment a fix lands is the point:
+delete the `xfail` marker to adopt the fix. F's test now reaches the aborted
+create through a promote push, because push no longer re-creates the
+remote-deleted config its first version used. J reproduces and
+is `xfail`. K is deliberate, documented behavior, so it is an ordinary
+(unmarked) regression guard instead. B is fixed: its marker was removed
+and the test is now an ordinary regression guard.

{keboola_cli-0.95.0 → keboola_cli-0.96.0}/plugins/kbagent/skills/kbagent-promotion-pipeline/scripts/generate_promotion_pipeline.py

@@ -10,12 +10,15 @@ directory between a SOURCE Keboola project (e.g. dev) and a DESTINATION project
      Pulls every pipeline's directory from its SOURCE project and opens/updates
      one PR against the main branch with the combined diff.
   2. kbagent-promote-validate.yml (pull_request against main)
-     For every pipeline, runs `sync push --dry-run` against the DESTINATION
-     project -- this is the cross-project diff: "if this PR merges, here is
-     exactly what changes in the destination project."
+     For every pipeline, runs `sync push --dry-run --force` against the
+     DESTINATION project -- this is the cross-project diff: "if this PR merges,
+     here is exactly what changes in the destination project."
   3. kbagent-promote-push.yml   (push to main, environment-gated)
      Pushes every pipeline's directory to its DESTINATION project once the PR
-     has merged.
+     has merged, with `--force`: a config deleted in the SOURCE is deleted in
+     the DESTINATION too. Without `--force`, `sync push` deletes nothing
+     (since 0.96.0, #792), and the validate dry-run passes it for the same
+     reason, so it shows what the push does.
 
 Each pipeline needs two Storage API token secrets (`KBC_TOKEN_<NAME>_SOURCE` /
 `KBC_TOKEN_<NAME>_DEST`) and uses kbagent's `KBAGENT_PROJECT_FROM_ENV=1` /
@@ -364,7 +367,7 @@ def gen_validate(pipelines: list[Pipeline]) -> str:
         _pipeline_step(
             p,
             "Destination dry-run",
-            "push --dry-run",
+            "push --dry-run --force",
             p.dest_token_secret,
             p.dest_stack_url,
             json_output=True,
@@ -414,7 +417,9 @@ def _push_job(p: Pipeline) -> str:
         f"{_INSTALL_TOKEN}"
         "      # `sync push` encrypts #-secrets fail-closed by default. Do NOT add\n"
         "      # --allow-plaintext-on-encrypt-failure in CI.\n"
-        f"{_pipeline_step(p, 'Push', 'push', p.dest_token_secret, p.dest_stack_url)}"
+        "      # --force: a config deleted in the source is deleted here too;\n"
+        "      # without it, `sync push` deletes nothing.\n"
+        f"{_pipeline_step(p, 'Push', 'push --force', p.dest_token_secret, p.dest_stack_url)}"
     )
 
 

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

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

{keboola_cli-0.95.0 → keboola_cli-0.96.0}/scripts/file_size_baseline.json

@@ -4,7 +4,7 @@
     "commands/config.py": 2007,
     "commands/lineage.py": 1271,
     "commands/storage.py": 2221,
-    "services/data_app_service.py": 1641,
+    "services/data_app_service.py": 1633,
     "services/storage_service.py": 1684,
     "services/sync_service.py": 1655
   }

{keboola_cli-0.95.0 → keboola_cli-0.96.0}/src/keboola_agent_cli/auth/environment.py

@@ -168,7 +168,7 @@ def detect_browser_environment() -> BrowserEnvironment:
     return BrowserEnvironment(loopback_browser_usable=True, reason="", opener=opener)
 
 
-def open_browser(url: str) -> bool:
+def open_browser(url: str, *, wait_seconds: float = 0.0) -> bool:
     """Best-effort `webbrowser.open` on a daemon thread.
 
     Never raises and never logs ``url`` -- it carries the PKCE code
@@ -177,13 +177,21 @@ def open_browser(url: str) -> bool:
     before spawning the thread) and True once the open has been dispatched;
     a True return does not guarantee a browser window actually appeared, only
     that a handler accepted the request.
+
+    ``wait_seconds`` joins the thread for up to that long. A caller that exits
+    right after the call (``data-app password --open``) passes it, because a
+    daemon thread dies with the process -- possibly before the opener starts.
+    The login flow keeps polling afterwards, so it leaves the default 0.
     """
     try:
         webbrowser.get()
     except webbrowser.Error:
         return False
 
-    threading.Thread(target=_open_silently, args=(url,), daemon=True).start()
+    thread = threading.Thread(target=_open_silently, args=(url,), daemon=True)
+    thread.start()
+    if wait_seconds > 0:
+        thread.join(timeout=wait_seconds)
     return True
 
 

{keboola_cli-0.95.0 → keboola_cli-0.96.0}/src/keboola_agent_cli/auto_update.py

@@ -34,6 +34,7 @@ from .services.version_service import (
     KbagentUpdatePlan,
     _fetch_kbagent_latest_version,
     _is_up_to_date,
+    build_hardlink_retry_command,
     build_kbagent_upgrade_command,
     get_update_timeout,
     prepare_kbagent_update_plan,
@@ -414,6 +415,7 @@ def _schedule_deferred_update(plan: KbagentUpdatePlan) -> None:
         target_version=target,
         install_command=plan.command,
         recovery_command=plan.recovery_command,
+        hardlink_retry_command=build_hardlink_retry_command(plan.command),
     )
     if request_deferred_update(request):
         sys.stderr.write(