feat(search): regex mode + matched columns in kbagent search (DMD-1716, DMD-1717)

[romanbracinik]

What & why

Wires the two client-side capabilities of the Global Search re-architecture into kbagent search. The rebuilt index / ranking upgrade is server-side and already flowed through unchanged; only these opt-in bits needed the CLI:

• --regex (DMD-1716): forwards mode=regex to the Storage API global-search endpoint. Case-insensitive, whole-term match against entity names only (report does not match monthly_report; use .*report.*). Textual-only — combining with --search-type config-based is a usage error (exit 2).
• matched_columns (DMD-1717): a table can now match via one of its column names. The API returns matchedColumns; we surface it as a matched_columns field on every --json result and a "Matched columns" column in the human table — shown only when at least one result actually matched via a column (no empty column otherwise, incl. every --regex search, since regex matches names only).

Changes (3-layer)

• client.py::global_search — regex: bool param → sends mode=regex when set (omitted otherwise; non-regex request byte-identical to before).
• services/search_service.py — threads regex through the textual path; _normalise_item exposes matched_columns ([] when absent, stable JSON shape).
• commands/search.py — --regex flag + validation + conditional "Matched columns" column + (regex) header label.
• Docs: CLAUDE.md, context.py (AGENT_CONTEXT), commands-reference.md, gotchas.md (since v0.66.0); changelog + version bump 0.66.0.

Verification

• Live server contracts verified against a real stack (curl against /v2/storage/global-search): mode=regex → 200 (invalid pattern → 400, not 500); regex is whole-term/case-insensitive over names; matchedColumns: ["<col>"] returned in textual mode when a table matches via a column; regex does not match columns → matched_columns always empty under --regex.
• Tests: +13 unit/CLI tests (client param, service threading + parse, CLI flag/validation/render/JSON, conditional column) + 2 E2E (feature-gate-aware regex contract, config-based usage error). Full suite green; ruff, ty, skill-check, command-sync-check, changelog-check pass.

Notes

• The MCP search tool (separate repo) and the kbc Go CLI are out of scope.
• Screenshot of the CLI demo to be attached.

Closes DMD-1716
Closes DMD-1717

🤖 Generated with Claude Code

[linear]

DMD-1716

DMD-1717

[Copilot]

Pull request overview

Adds opt-in regex mode and matched-column reporting to kbagent search, threading the new regex flag down to the Storage API global-search call and surfacing matchedColumns as matched_columns in both JSON and human output.

Changes:

• Add --regex flag to kbagent search, validate it against --search-type config-based, and forward it through service/client layers as mode=regex.
• Parse API matchedColumns into a stable matched_columns field and conditionally render a “Matched columns” column in human output only when populated.
• Bump version to 0.66.0 and update changelog + command reference docs.

Reviewed changes

Copilot reviewed 17 out of 18 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
uv.lock	Bumps locked project version to 0.66.0.
pyproject.toml	Bumps package version to 0.66.0.
plugins/kbagent/.claude-plugin/plugin.json	Bumps plugin version to 0.66.0.
.claude-plugin/marketplace.json	Updates marketplace plugin version reference to 0.66.0.
src/keboola_agent_cli/client.py	Adds regex param to global_search() and sends mode=regex when enabled.
src/keboola_agent_cli/services/search_service.py	Threads regex through textual search and normalizes matchedColumns to matched_columns; ensures config-based results include matched_columns: [].
src/keboola_agent_cli/commands/search.py	Adds --regex, enforces CLI incompatibility with config-based search, and conditionally renders “Matched columns”.
src/keboola_agent_cli/server/routers/search.py	Exposes regex query param and forwards it to SearchService.search().
src/keboola_agent_cli/commands/context.py	Updates help/context text to document --regex and matched_columns.
src/keboola_agent_cli/changelog.py	Adds 0.66.0 changelog entry describing the new search behavior.
plugins/kbagent/skills/kbagent/references/commands-reference.md	Documents --regex and matched_columns in the command reference.
plugins/kbagent/skills/kbagent/references/gotchas.md	Adds gotcha documentation for regex semantics and matched-columns behavior.
CLAUDE.md	Updates top-level CLI command reference to include --regex and matched-columns notes.
tests/test_client.py	Adds unit tests asserting mode=regex is sent/omitted correctly.
tests/test_search_service.py	Adds tests for regex threading and matchedColumns normalization.
tests/test_search_cli.py	Adds CLI tests for --regex wiring, validation, and matched-columns rendering/JSON.
tests/test_server_router_calls.py	Adds router tests ensuring regex is forwarded/defaulted.
tests/test_e2e.py	Adds E2E coverage for regex feature-gate behavior and CLI usage error on config-based + regex.

Comments suppressed due to low confidence (1)

src/keboola_agent_cli/server/routers/search.py:25

• The /search router now accepts regex=true for all search_type values, but the CLI explicitly treats --regex + --search-type config-based as a usage error. Since this endpoint claims to “Mirror kbagent search”, it should reject the same unsupported combination instead of silently ignoring regex on the config-based path.

    regex: bool = False,
    registry: ServiceRegistry = Depends(get_registry),
) -> dict[str, Any]:
    """Search tables, buckets, configs and flows across one or more projects. Mirrors `kbagent search`."""
    return registry.search.search(

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[romanbracinik]

[Copilot]

Pull request overview

Copilot reviewed 18 out of 19 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 19 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 19 changed files in this pull request and generated no new comments.