[file-diet] Refactor `pkg/workflow/mcp_renderer.go` (1006 lines) into focused modules

[github-actions]

Overview

The file pkg/workflow/mcp_renderer.go has grown to 1006 lines, exceeding the 800-line healthy threshold. It mixes four distinct responsibilities — core dispatch, TOML rendering, GitHub-specific config rendering, and JSON MCP config orchestration — making it difficult to navigate, test, and extend.

Current State

• File: pkg/workflow/mcp_renderer.go
• Size: 1006 lines
• Test file: pkg/workflow/mcp_renderer_test.go (510 lines — ~51% ratio)
• Complexity: Four distinct functional domains, mix of exported and unexported functions, TOML and JSON rendering interleaved with dispatch logic

Full File Analysis

Function / Type Distribution

Lines	Symbol	Domain
93–119	MCPRendererOptions, MCPConfigRendererUnified, NewMCPConfigRenderer	Core types & constructor
123–200	RenderGitHubMCP	Entry-point dispatch
203–259	RenderPlaywrightMCP, renderPlaywrightTOML	Playwright (JSON + TOML)
260–319	RenderSerenaMCP, renderSerenaTOML	Serena (JSON + TOML)
320–386	RenderSafeOutputsMCP/TOML, RenderSafeInputsMCP/TOML	Safe-outputs/inputs (JSON + TOML)
388–461	RenderAgenticWorkflowsMCP, renderAgenticWorkflowsTOML	Agentic workflows (JSON + TOML)
463–581	renderGitHubTOML	GitHub TOML rendering (Codex engine)
584–628	RenderCustomMCPToolConfigHandler, HandleCustomMCPToolInSwitch, MCPToolRenderers	Custom tool dispatch
631–644	JSONMCPConfigOptions	JSON config options
647–772	GitHubMCPDockerOptions, RenderGitHubMCPDockerConfig	GitHub Docker config
775–881	GitHubMCPRemoteOptions, RenderGitHubMCPRemoteConfig	GitHub Remote config
886–899	renderGuardPoliciesJSON	Guard policy helpers
910–1006	RenderJSONMCPConfig	JSON MCP config orchestration

Complexity Hotspots

• renderGitHubTOML (lines 463–581): ~120 lines — duplicates env-var sorting logic found in RenderGitHubMCPDockerConfig
• RenderJSONMCPConfig (lines 910–1006): Large switch-dispatch embedded inside the function with gateway section appended
• RenderGitHubMCPDockerConfig (lines 679–772): Detailed env-var construction with sorted output
• TOML methods are tightly coupled to the MCPConfigRendererUnified receiver but contain no shared state — they are effectively free functions

Refactoring Strategy

Proposed File Splits

Split the file into four focused modules (all in pkg/workflow/):

1. mcp_renderer.go (keep, reduce)

   • Types: MCPRendererOptions, MCPConfigRendererUnified
   • Functions: NewMCPConfigRenderer, all Render*MCP entry-point dispatch methods
   • Estimated LOC: ~280

2. mcp_renderer_toml.go (new)

   • Functions: renderPlaywrightTOML, renderSerenaTOML, renderSafeOutputsTOML, renderSafeInputsTOML, renderAgenticWorkflowsTOML, renderGitHubTOML
   • Responsibility: All TOML-format rendering for Codex engine
   • Estimated LOC: ~220

3. mcp_renderer_github_config.go (new)

   • Types: GitHubMCPDockerOptions, GitHubMCPRemoteOptions
   • Functions: RenderGitHubMCPDockerConfig, RenderGitHubMCPRemoteConfig, renderGuardPoliciesJSON
   • Responsibility: GitHub-specific local (Docker) and remote config rendering
   • Estimated LOC: ~250

4. mcp_renderer_json_config.go (new)

   • Types: JSONMCPConfigOptions, MCPToolRenderers, RenderCustomMCPToolConfigHandler
   • Functions: RenderJSONMCPConfig, HandleCustomMCPToolInSwitch
   • Responsibility: JSON MCP config file orchestration (gateway section, tool dispatch loop)
   • Estimated LOC: ~200

Shared Utilities

• The env-var sorted-output pattern (build map → sort keys → write) appears in both RenderGitHubMCPDockerConfig and renderGitHubTOML. Extract into a small private helper (e.g., writeSortedEnvVarsJSON) once both live in mcp_renderer_github_config.go and mcp_renderer_toml.go respectively.

Interface Abstractions

No new interfaces are required for this split — all functions operate on *strings.Builder and concrete types, which keeps the API surface stable.

Test Coverage Plan

Existing tests in mcp_renderer_test.go (510 lines) already cover the main rendering paths. After the split:

1. mcp_renderer_test.go — Keep existing tests, remove any tests that move to new files
2. mcp_renderer_toml_test.go — Add/move TOML-specific tests:
   • renderGitHubTOML (local and remote modes)
   • renderAgenticWorkflowsTOML (dev vs release mode)
   • renderSafeOutputsTOML / renderSafeInputsTOML (host selection)
3. mcp_renderer_github_config_test.go — Add/move GitHub-specific tests:
   • RenderGitHubMCPDockerConfig (read-only, lockdown, mounts, env vars)
   • RenderGitHubMCPRemoteConfig (auth value, headers, tools field)
   • renderGuardPoliciesJSON (policies present/absent)
4. mcp_renderer_json_config_test.go — Add/move JSON orchestration tests:
   • RenderJSONMCPConfig (all tool types, filter function, gateway config)
   • HandleCustomMCPToolInSwitch (custom MCP config detection)

Target coverage: ≥80% per new file.

Implementation Guidelines

1. Preserve Behavior: All existing functionality must work identically — only file boundaries change
2. Maintain Exports: No changes to exported function/type names or signatures
3. No interface changes: Do not add new exported interfaces; this is a structural refactor only
4. Incremental splits: Move one domain at a time, running make test-unit after each step
5. Build tags: Each new test file must start with //go:build !integration
6. Formatting: Run make fmt after every file change
7. Validation: Run make agent-finish before committing

Acceptance Criteria

• mcp_renderer.go is reduced to ≤300 lines
• Three new files created: mcp_renderer_toml.go, mcp_renderer_github_config.go, mcp_renderer_json_config.go
• Each new file is ≤300 lines
• All tests pass (make test-unit)
• No breaking changes to exported API
• make lint and make build pass
• Env-var sorted-output duplication is eliminated (optional but encouraged)

Additional Context

• Top 10 largest files (for future diet cycles): trial_command.go (998), gateway_logs.go (982), constants.go (979), logs_report.go (932), checkout_manager.go (918), cache.go (879), logs_orchestrator.go (872), frontmatter_types.go (844), compiler_artifact_management.go (834)
• Repository guidelines: Follow patterns in AGENTS.md and scratchpad/validation-refactoring.md
• Code organization: Prefer many small files grouped by functionality

---

Priority: Medium
Effort: Small (structural refactor only — no logic changes, clear domain boundaries)
Expected Impact: Improved navigability, easier isolated testing, reduced merge conflicts

References:

• §22671382998

Generated by Daily File Diet · ◷

• expires on Mar 6, 2026, 1:33 PM UTC

[github-actions]

This issue was automatically closed because it expired on 2026-03-06T13:33:17.190Z.

Closed by Workflow