[padak]

Summary

Complete development branch lifecycle management for Keboola projects, eliminating the 5-step manual workflow described in the ideal-workflow-proposal. Users can now create, switch, reset, delete, and merge branches entirely from the CLI, with persistent active branch state that auto-resolves in all MCP tool operations.

Also adds LLM export (wraps kbc llm export) and version check commands, plus security hardening and architecture improvements.

New Commands

Branch Lifecycle

Command	Description
kbagent branch create --project ALIAS --name "fix-x"	Create branch + auto-activate
kbagent branch use --project ALIAS --branch ID	Switch to existing branch
kbagent branch reset --project ALIAS	Revert to main branch
kbagent branch delete --project ALIAS --branch ID	Delete branch (auto-resets if active)
kbagent branch merge --project ALIAS	Get KBC UI merge URL (no force-merge)

LLM Export

Command	Description
kbagent llm export [--project ALIAS]	AI-optimized project export via kbc Go binary

Wraps kbc llm export with credentials auto-resolved from config store. Detects kbc binary, validates project, runs export to per-project output dirs.

Version Check

Command	Description
kbagent version	Show kbagent version + check kbc and MCP server updates

Parallel version fetching from GitHub releases (kbc) and PyPI (keboola-mcp-server), with rich formatted output.

Key Features

Active Branch Persistence

• active_branch_id stored per-project in config.json
• tool list and tool call auto-resolve active branch (no --branch flag needed)
• Visible in project list, project status, and branch list tables (>>> marker)

Async Job Handling

• Branch create/delete are async Storage API operations (POST returns a job, not branch data)
• KeboolaClient._wait_for_storage_job() polls until completion (1s interval, 60s max)
• Real branch ID extracted from job.results.id (not the job ID)

Typical Branch Workflow

kbagent branch create --project prod --name "fix-transform-x"
  # creates branch AND sets it as active
kbagent tool call list_configs --project prod
  # auto-uses active branch
kbagent tool call update_sql_transformation --project prod --input '{...}'
  # auto-uses active branch
kbagent branch merge --project prod
  # returns KBC UI URL for safe review, resets to main

Security Fixes

Fix	File	Description
TOCTOU race	config_store.py	Atomic write via os.open(0o600) + os.replace() - config file never exists with world-readable permissions
XSS	kbc-explorer/index.html	escapeHtml() helper for all innerHTML with dynamic data (project names, bucket names)
None key	lineage_service.py	Skip projects with project_id=None in lineage lookup (was creating None dict key)
None in set	org_service.py	Filter None from existing_project_ids set

Architecture Improvements

Change	File(s)	Description
Lazy MCP timeouts	mcp_service.py	_get_tool_timeout() / _get_init_timeout() read env vars at call time, not import time
Centralized constants	constants.py	VALID_COMPONENT_TYPES, VALID_STATUSES moved from command layer
Branch type	commands/tool.py	--branch changed from str to int (consistent with branch.py)
Dedup validation	commands/tool.py	_validate_branch_requires_project() extracted from duplicate blocks
Output dir	explorer_service.py	_default_output_dir() uses Path.cwd() instead of package-relative path
Import constant	explorer_service.py	Uses MAX_JOB_LIMIT from constants.py instead of local duplicate

Files Changed

• 41 files changed, +3447 / -662 lines
• 687 tests passed, 3 skipped, 0 failures
• Lint clean (ruff)

Test Plan

• All 687 unit tests pass
• Ruff lint clean
• Security review passed (0 high-confidence findings)
• Architecture review completed
• Live-tested branch create/list/merge with real Keboola project
• Active branch >>> marker verified in branch list output
• Backward compatible - existing config.json without active_branch_id loads correctly
• Manual smoke test of full branch workflow on staging project