[Refactoring] Split assembleOptionalServices (208-line function) in src/services/optional-services.ts into per-sidecar helpers

[github-actions]

Refactoring Opportunity

Summary

• File: src/services/optional-services.ts
• Current size: 250 lines
• Function: assembleOptionalServices — 208 lines (lines 42–250)
• Responsibilities identified: 7 distinct concerns in a single exported function
• Score: 7 (mixed responsibilities +3, security-critical +2, function > 80 lines +2)

Evidence

assembleOptionalServices handles seven independent sidecar-assembly blocks, all guarded by feature flags:

Lines	Block	Concern
64–83	Environment pre-sets	Injects AWF_API_PROXY_IP, AWF_CLI_PROXY_IP, AWF_NETWORK_ISOLATION
87–155	Sysroot init container	Volume filtering + sysroot-stage service + tool-cache warning (~68 lines)
162–178	iptables-init service	buildIptablesInitService + depends_on wiring
182–199	API proxy sidecar	buildApiProxyService + agent env mutations + depends_on
203–212	DoH proxy sidecar	buildDohProxyService + depends_on
216–233	CLI proxy sidecar	buildCliProxyService + agent env mutations + depends_on
241–249	Named volumes	sysroot volume assembly + agentVolumes push

The sysroot block alone is ~68 lines of volume-filtering logic with no relationship to the DoH proxy or CLI proxy blocks. The function was introduced as the extraction target of #5727 but has grown to 208 lines.

Security relevance: the iptables-init and api-proxy sidecar assembly paths are security-critical (iptables NAT rules and credential-injection configuration).

Proposed Split

• Keep assembleOptionalServices as a thin coordinator (~40 lines)
• Extract presetSidecarIpEnvVars(environment, config, networkConfig) — pre-sets AWF_*_IP env vars before init container construction
• Extract assembleSysrootService(params, agentVolumes) — volume-filtering and sysroot-stage service wiring (~70 lines)
• Extract per-sidecar helpers for iptables-init, api-proxy, doh-proxy, and cli-proxy assembly

Affected Callers

grep -rn "from.*optional-services" src/ 2>/dev/null

Output: only src/compose-generator.ts (line 11) imports assembleOptionalServices. Internal helpers remain un-exported.

Effort Estimate

Medium — the sysroot block has side effects (mutates agentVolumes in-place via .length = 0 + push) that require careful extraction.

Benefits

• Sysroot-stage and iptables-init assembly paths can be reviewed and tested independently
• New optional sidecars can be added without growing the monolith
• Per-block unit tests become practical

---

Detected by Refactoring Scanner workflow. Run date: 2026-07-02

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• awmgmcpg

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "awmgmcpg"

See Network Configuration for more information.

Generated by Refactoring Opportunity Scanner · 306.4 AIC · ⊞ 6.7K · ◷

• expires on Aug 31, 2026, 4:02 PM UTC