refactor: semantic function clustering — reduce cross-concern placement and duplication

[Copilot]

Four targeted refactors from the automated semantic clustering analysis of 896 functions across 23 packages.

Changes

• server/session.go → server/system_tools.go: Move sysListServersHandler out of the session lifecycle file. It has no session-management logic — it validates a session exists then delegates to callAndLogSysTool, which belongs alongside the SysServer type and registration helpers it works with.

• strutil consolidation: Delete session_suffix.go (1 fn) and json_clone.go (1 fn); merge SessionSuffix and DeepCloneJSON into strutil.go where the other general-purpose helpers live.

• Single source of truth for integrity validation: Export config.ValidateAndNormalizeIntegrityField (was unexported validateAndNormalizeIntegrityField) and remove the near-duplicate invalidIntegrityFieldError + inline NormalizeIntegrityLevel call from guard/wasm_validate.go. Guard now delegates entirely to config:

  // Before (guard/wasm_validate.go)
  func validateIntegrityField(fieldName string, raw interface{}) error {
      s, ok := raw.(string)
      if !ok { return invalidIntegrityFieldError(fieldName) }  // pipe-separated format
      if _, err := config.NormalizeIntegrityLevel(s, false); err == nil { return nil }
      return invalidIntegrityFieldError(fieldName)
  }
  
  // After
  func validateIntegrityField(fieldName string, raw interface{}) error {
      s, _ := raw.(string)  // empty string fails validation for non-string input
      _, err := config.ValidateAndNormalizeIntegrityField(fieldName, s, false)
      return err
  }

  Error message format unified to "<field> must be one of: none, unapproved, approved, merged". Affected tests updated accordingly.

• logger/doc.go: Add explanation of why per-type setup*/handleError* functions are intentional rather than collapsed — each logger type has unique initialization behaviour (e.g. JSONLLogger has no fallback, ToolsLogger closes its file immediately after opening).

[Copilot]

Pull request overview

This PR performs targeted semantic refactors to reduce cross-concern placement and deduplicate logic across the gateway, while unifying integrity-level validation and its error messages.

Changes:

• Moved sysListServersHandler from session lifecycle code into system_tools.go alongside other sys-tool helpers.
• Consolidated SessionSuffix and DeepCloneJSON into internal/strutil/strutil.go and removed the now-redundant one-function files.
• Exported config.ValidateAndNormalizeIntegrityField and switched the WASM guard integrity validation to delegate to it, updating tests for the unified error message format.

Show a summary per file

File	Description
internal/strutil/strutil.go	Centralizes SessionSuffix and DeepCloneJSON into the main strutil helper file.
internal/strutil/session_suffix.go	Removes the standalone SessionSuffix helper file after consolidation.
internal/strutil/json_clone.go	Removes the standalone DeepCloneJSON helper file after consolidation.
internal/server/system_tools.go	Adds sysListServersHandler next to SysServer and sys tool logic.
internal/server/session.go	Removes sysListServersHandler from session lifecycle code.
internal/logger/doc.go	Documents rationale for per-type setup/error-handler functions in logger implementations.
internal/guard/wasm_validate.go	Delegates integrity validation to exported config helper and removes duplicate logic.
internal/guard/wasm_validate_test.go	Updates assertions to the new unified integrity error message format.
internal/guard/wasm_test.go	Updates integrity error substring expectations to the new format.
internal/guard/guard_test.go	Updates integrity validation error expectations to the new format.
internal/config/guard_policy_validation.go	Exports ValidateAndNormalizeIntegrityField and updates call sites.
internal/config/guard_policy_test.go	Updates tests to call the exported integrity validation helper.

Copilot's findings

Tip

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

• Files reviewed: 12/12 changed files
• Comments generated: 2

[lpcox]

@copilot fix this failing ci check https://github.com/github/gh-aw-mcpg/actions/runs/27831905869/job/82370502865?pr=7761

[Copilot]

@copilot fix this failing ci check https://github.com/github/gh-aw-mcpg/actions/runs/27831905869/job/82370502865?pr=7761

Fixed in the latest commit. guard.AllowedIntegrityLevels was removed as part of the refactor but internal/cmd/flags.go still referenced it. Updated flags.go to call config.AllIntegrityLevels() directly and swapped the import from guard to config.

[lpcox]

@copilot fix this ci check https://github.com/github/gh-aw-mcpg/actions/runs/27832772217/job/82373625834?pr=7761

[Copilot]

@copilot fix this ci check https://github.com/github/gh-aw-mcpg/actions/runs/27832772217/job/82373625834?pr=7761

Fixed. flags_test.go still referenced guard.AllowedIntegrityLevels — updated it to use config.AllIntegrityLevels() and swapped the import accordingly.