feat(0.22.0): storage describe-bucket/table/column/batch

[ottomansky]

Summary

• storage describe-bucket — sets KBC.description on a bucket via POST /v2/storage/buckets/{id}/metadata (upsert-by-key, provider=user)
• storage describe-table — sets KBC.description on a table via POST /v2/storage/tables/{id}/metadata
• storage describe-column — sets per-column descriptions using the KBC.column.{name}.description key convention in table metadata (Keboola Storage has no user-writable column-level metadata endpoint; this is the supported workaround)
• storage describe-batch --from-file YAML — batch-applies bucket, table, and column descriptions from a YAML file; item-level failures are collected without aborting remaining work

Round-trip: bucket-detail and table-detail now surface a description field extracted from the metadata array, and table-detail surfaces column_details[].description for annotated columns.

Architecture

• Client (client.py): set_bucket_metadata + set_table_metadata using PHP-array form encoding (metadata[i][key/value]), branch-aware URL prefix
• Service (storage_service.py): describe_bucket, describe_table, describe_columns, describe_batch; updated get_bucket_detail + get_table_detail to extract descriptions from the metadata array
• Commands (commands/storage.py): 4 CLI commands with --text|--file|--stdin (bucket/table) or --column NAME=DESC (column) input; all branch-aware
• Tests: 27 new unit tests (13 CLI via CliRunner + 14 service-layer) + E2E step 14.2

Test plan

• ruff check src/ tests/ + ruff format --check — clean
• pytest tests/test_storage_describe_cli.py — 13/13 passed
• pytest tests/test_storage_describe_service.py — 14/14 passed
• pytest tests/test_client.py -k "Metadata" — 6/6 passed
• All 17 failures in full suite are pre-existing Windows file-permission / POSIX-locking issues (verified on main before this branch)
• Manual E2E against connection.europe-west3.gcp.keboola.com project 1143: all 4 commands + round-trips verified

Replacing with English version for broader team visibility.

[padak]

Changes requested — one required addition per CONTRIBUTING.md

The PR is architecturally clean, test coverage is excellent (1884 passed), version sync OK, make skill-gen clean. Only a required hand-maintained doc is missing:

Required fix

plugins/kbagent/skills/kbagent/references/commands-reference.md — 4 lines missing (CONTRIBUTING.md line 204: "this is a hand-maintained file, NOT auto-generated"). Add to the ## Storage section after delete-bucket:

kbagent storage describe-bucket --project NAME --bucket-id ID --text STR|--file PATH|--stdin [--branch ID]
kbagent storage describe-table --project NAME --table-id ID --text STR|--file PATH|--stdin [--branch ID]
kbagent storage describe-column --project NAME --table-id ID --column NAME=DESCRIPTION [--branch ID]
kbagent storage describe-batch --project NAME --file PATH [--branch ID]

(Verify signatures against your actual @typer.Option definitions.)

Nice-to-have (follow-up)

• Unit test gap: The enhancement in get_bucket_detail/get_table_detail (extracting description from metadata + the new metadata field) is only covered via E2E. Add 2-3 tests to test_services.py for raw_metadata + description precedence.
• gotchas.md: A short paragraph about:
  • Column description workaround — KBC.column.{name}.description convention (the Keboola API has no user-writable column-metadata endpoint).
  • describe-batch partial-failure semantics (it doesn't abort, it collects errors).
  • Precedence between the native API description field and the KBC.description metadata entry.
• Progress indicator: src/keboola_agent_cli/commands/storage.py:1402-1418 — describe-batch prints nothing during the iteration in human mode. With 100+ items it looks frozen. A Rich status/spinner would help.
• Dedicated storage-describe-workflow.md: a YAML schema example + batch workflow would deserve its own doc.

Positives

• Architecturally elegant approach: 4 sugar commands over the /metadata endpoint, upsert-by-key with provider=user, branch-aware.
• urllib.parse.quote(id, safe="") on bucket_id and table_id (path traversal protection).
• describe-batch partial-failure collects errors instead of aborting — the right pattern for batch ops.
• Complete test matrix (14 service + 13 CLI + E2E round-trip with read-back via bucket-detail/table-detail).

[ottomansky]

Required fix + all four nice-to-haves:

• docs(references): add storage describe-* commands to commands-reference — 33ad4be.
• test(storage): cover metadata-extraction in get_bucket_detail/get_table_detail — 6bcdfb7 — 3 new tests. Pinned precedence: KBC.description metadata (provider=user) wins over native description for buckets; non-user providers (e.g. system) ignored on read-back. Native field is fallback when no user metadata entry exists. get_table_detail consults only KBC.description in metadata.
• docs(gotchas): document storage description workarounds and precedence — 0e9078a — KBC.column.{name}.description convention + describe-batch partial-failure semantics + precedence rule.
• feat(storage): add progress spinner to describe-batch human mode — 2002b47 — Rich Progress with bar/spinner/time. StorageService.describe_batch gained an optional progress_callback: Callable[[str, str, int, int], None] | None = None; JSON mode unchanged.
• docs(references): add storage-describe-workflow.md — 0955c1b — overview, single-item examples, batch YAML schema, read-back via bucket-detail/table-detail, partial-failure semantics.
• style(storage): reorder imports in storage_service per ruff — e0a8824 — ruff auto-fix for import ordering.

One signature note: describe-batch uses --from-file PATH (not --file PATH as in your template); updated the docs to match the real @typer.Option.

Targeted tests: 139/139 pass (126 across test_storage_describe_* + 13 client metadata tests). make lint format-check skill-check version-check changelog-check all green.

[padak]

Integrated into release/0.22.0 as squash commit 105f74b (rebased locally on top of v0.21.2 to resolve merge conflicts with main; all Max's review fixes preserved). Original branch fiia/... unchanged.

Full integration PR coming as release/0.22.0 -> main.