fix(0.30.8): close issue #274 -- per-element sql_resplit closes ODBC statement-count crash

[padak]

Summary

Closes #274.

Closes the remaining gap on the v0.28.0 (#245) script[] normalization. v0.28.0 covered str -> array for the lax-Storage-API / strict-runtime shape validator mismatch. v0.30.8 covers the case where script is already a list but an element packs multiple ;-separated statements — the Snowflake / BigQuery / etc. runtime crashes at odbc_prepare with Actual statement count 2 did not match the desired statement count 1 (SQL state 0A000), the same write-side trap the v0.28.0 fix closed for string inputs.

Repro before fix (verified)

Live-reproduced against project 901 (padak) config 01km0sd189fdrcnjwk89cd1fkc:

1. kbagent config update --configuration-file repro.json with script: ['CREATE TABLE ...; alter session unset week_start;'] (list of 1, packs 2 stmts)
2. Storage API: 200 OK, version 58 -> 59, response envelope normalizations: [] (no warning)
3. kbagent job run --wait: job 1307622107 crashed with:

   odbc_prepare(): SQL error: Actual statement count 2 did not match the
   desired statement count 1, SQL state 0A000 in SQLPrepare
   

4. Rolled config back to 3-block baseline (v60), cleaned up.

Fix

Extend normalize_blocks_codes_script in src/keboola_agent_cli/sync/code_extraction.py. After the existing isinstance(script, str) branch, add an elif is_sql and isinstance(script, list) branch that runs each element through the same split_statements() state machine #245 already wired up, and replaces multi-statement elements inline. Path: smallest possible delta — same is_sql_transformation_component() gate, same splitter helper.

Each replacement emits a sql_resplit entry in the normalizations envelope:

{
  "path": "parameters.blocks[0].codes[0].script[2]",
  "action": "sql_resplit",
  "before_type": "str",
  "after_type": "list",
  "before_length": 1,
  "after_length": 2
}

path points at the original element index on input (not the post-split position) so users can map the warning back to their source payload even when later elements shift due to upstream splits in the same list.

Non-SQL components (Python ; is a valid intra-statement separator: print('a'); print('b')) skip this pass — same is_sql gate as #245.

Tests

• 11 new unit tests in tests/test_normalize_script.py::TestSqlResplitListElements covering: CREATE+ALTER (canonical config update: re-split script[] elements that contain multiple statements (gap beyond #245) #274), CREATE+SELECT (second failure mode from config update: re-split script[] elements that contain multiple statements (gap beyond #245) #274 follow-up), well-formed list no-op, mixed bad+good (only bad element recorded, original-index reporting), multiple bad elements in the same code, ; inside /* ... */ not a separator, ; inside '...' string literal not a separator, Python list passthrough, BigQuery list resplit, defensive None-element passthrough.
• 1 new TestConfigServiceUpdateNormalizes::test_sql_list_element_resplit_before_push integration test pinning that ConfigService.update_config sends the post-resplit payload to the HTTP client.
• Full suite: 2884 passed, 7 skipped, 73 e2e deselected. No regressions.

Plugin / agent surfaces updated (per CLAUDE.md convention #17)

• plugins/kbagent/agents/keboola-expert.md — Rule 6 VERSION GATE entry, matrix row for SQL transformation body updates, inline gotcha block.
• plugins/kbagent/skills/kbagent/references/gotchas.md — extended the existing update_sql_transformation: validate / preserve script field as array (string causes runtime parse error) #245 gotcha with the v0.30.8 list-element re-split section.
• plugins/kbagent/skills/kbagent/references/commands-reference.md — config update auto-normalize note.

Test plan

• make check — lint, format-check, skill-check, version-check, changelog-check, all 2884 unit/integration tests
• End-to-end reproduction on live Keboola project before the fix (job 1307622107 crash with exact ODBC error from config update: re-split script[] elements that contain multiple statements (gap beyond #245) #274)
• All 11 new unit tests pin the new behaviour (each scenario from config update: re-split script[] elements that contain multiple statements (gap beyond #245) #274 + edge cases)
• Integration test pins ConfigService write path
• E2E live verification against kbagent-e2e after merge (not run in CI; can be added to test_e2e.py::TestE2EConfigUpdateNormalization follow-up if desired)

[padak]

Review of #275 — fix(0.30.8): per-element sql_resplit closes ODBC statement-count crash

Generated by kbagent-pr-reviewer subagent. Verdict and findings below
are advisory; the human author retains every veto. CI-coverable issues
(lint, format, tests) are confirmed via make check, not duplicated here.

Summary

This PR closes issue #274 by extending normalize_blocks_codes_script in src/keboola_agent_cli/sync/code_extraction.py with a per-element re-split branch for SQL transformations: when script is already a list but an element packs multiple ;-separated statements, each element is re-run through split_statements() and replaced inline. The fix is well-scoped (smallest possible delta on top of the existing #245 machinery), the live repro is documented, test coverage is thorough (11 unit tests + 1 service-layer integration test), and all plugin/agent surfaces listed in CONTRIBUTING.md's Plugin synchronization map have been updated. One non-blocking gap exists in the CLI-layer (CliRunner) test suite, and the existing human-mode warning message text is mildly misleading for the new action — both noted below.

Verdict: APPROVE

Verdict

• Verdict: APPROVE
• Blocking findings: 0
• Non-blocking findings: 2
• Nits: 1

Blocking findings

(none)

Non-blocking findings

[NB-1] tests/test_normalize_script.py:776 — no CliRunner test exercises the sql_resplit path end-to-end

TestConfigUpdateCliNormalization has two existing tests that cover sql_split (string input) via CliRunner — one for JSON-mode envelope, one for human-mode warning text. Neither was extended for the new sql_resplit path (list-with-multi-statement input). The service-layer integration test at line 733 (test_sql_list_element_resplit_before_push) confirms the post-resplit payload reaches the HTTP client, but it bypasses the Typer command layer entirely. A CliRunner test that feeds --configuration '{"parameters":{"blocks":[...script: ["SELECT 1; SELECT 2;"]]...}}' and asserts envelope["data"]["normalizations"][0]["action"] == "sql_resplit" would pin the full path from CLI argument through service through output formatter, consistent with the existing sql_split coverage. Per CONTRIBUTING.md, every CLI command change requires a CLI-layer test.

Fix: add a test_json_envelope_carries_sql_resplit method to TestConfigUpdateCliNormalization that supplies a list-with-multi-statement element and asserts action == "sql_resplit" in the JSON envelope.

[NB-2] src/keboola_agent_cli/commands/config.py:751 — human-mode warning text says "string -> list" when sql_resplit fires

The _emit_normalizations_warning function (not modified in this PR) emits the hardcoded message "Auto-normalized N script field(s) to array (string -> list)." at line 751. When sql_resplit fires the transformation is list -> list (element expansion), not string -> list. This PR intentionally reuses the existing action-agnostic warning, which is a reasonable trade-off, but the literal message text is now factually wrong for the new case. The PR's own changelog entry acknowledges this ("the line is action-agnostic so it fires for sql_split, wrap_array, AND sql_resplit") but the message was not updated to match. Users who see the warning in human mode and parse it literally will misunderstand what was normalized.

Fix: update the message to "Auto-normalized N script field(s). See --json for details." (dropping to array (string -> list) which is now inaccurate for one of the three action types). This is a one-line change to commands/config.py:751-752. Alternatively, emit per-action counts with accurate text.

Nits

• [NIT-1] tests/test_normalize_script.py:489-503 — test_well_formed_list_is_noop passes cfg (the original dict) to normalize_blocks_codes_script without copy.deepcopy, then asserts out == before. Since the function mutates config in place, cfg and out are the same object and the equality assertion is trivially true even if mutation occurred. The assertion is sound only because no mutation happens for this input, but the test pattern is fragile: a future regression that mutates a well-formed list would not be caught. All other tests in the class correctly use copy.deepcopy(cfg).

Verification log

• gh auth status → authenticated to github.com as padak (active account) ✓
• gh pr view 275 --json state,... → state: OPEN, +489/-68, 10 files, conventional fix(0.30.8): prefix ✓
• git rev-parse --abbrev-ref HEAD in worktree → fix/issue-274-sql-resplit ✓ (matches <branch> input)
• 3-layer compliance: grep typer/click/httpx in new + lines across layers → (none) ✓
• New @*.command() decorators in diff → (none); no new CLI command, so permissions.py, context.py, hints/definitions/, CLAUDE.md All CLI Commands updates are not required ✓
• Plugin synchronization map (all "NO" rows): keboola-expert.md §1 Rule 6 VERSION GATE updated with 0.30.8+ list-element re-split entry ✓; §2 Tool Selection Matrix row for "Update SQL transformation body" updated with 0.30.8+ note ✓; §3 Inline Gotchas new entry added ✓; gotchas.md extended with (since v0.30.8; #274) tag ✓; commands-reference.md config update note updated ✓
• grep 'commands/config.py' /tmp/kbagent-pr-275.files → NOT in PR diff (warning text not updated — leads to NB-2) ✓
• make check (worktree) → ruff clean, 211 files formatted, SKILL.md up-to-date, plugin.json in sync, changelog complete, error-code check OK, 2884 passed, 7 skipped exit 0 ✓
• CliRunner test for sql_resplit path → absent in TestConfigUpdateCliNormalization (leads to NB-1)
• test_well_formed_list_is_noop mutation-safety → uses cfg without deepcopy, trivially true equality (leads to NIT-1)
• Behavior verification: live repro documented in PR description (project 901, job 1307622107, exact ODBC error); cannot re-run without E2E credentials. Unit test test_create_plus_alter_session_resplit_in_place reproduces the canonical input shape from the bug report and confirms correct 2-element split output ✓
• Security: no token exposure, no httpx outside client files, no bare except:, no magic numbers, no print() in production code ✓
• Backward compat: before_length is a new field in sql_resplit records only; existing consumers of normalizations (e.g. commands/config.py:706, test_e2e.py:6772) use .get() / or [] patterns that tolerate extra fields ✓

Open questions for the author

(none)