[Refactoring] Split `src/host-env.ts` into focused modules

[github-actions]

Refactoring Opportunity

Summary

• File: src/host-env.ts
• Current size: 514 lines
• Responsibilities identified: 8 distinct concerns mixed into a single file

Evidence

host-env.ts exports symbols from at least 8 unrelated areas:

Lines	Responsibility
5–17	Container name constants (AGENT_CONTAINER_NAME, SQUID_CONTAINER_NAME, etc.)
24–30	Env-size threshold constants (MAX_ENV_VALUE_SIZE, ENV_SIZE_WARNING_THRESHOLD)
38–90	Docker host management (setAwfDockerHost, getLocalDockerEnv)
97–163	Security-critical UID/GID range validation (validateIdNotInSystemRange, getSafeHostUid, getSafeHostGid)
165–200	User home directory detection (getRealUserHome)
201–398	GitHub Actions env/PATH file parsing (readGitHubPathEntries, readGitHubEnvEntries, parseGitHubEnvFile — 74-line function, mergeGitHubPathEntries, readEnvFile)
418–447	Network subnet overlap utility (subnetsOverlap)
452–514	SSL config interface, proxy string utilities (stripScheme, parseDifcProxyHost)

The file is imported by 12 production files across the whole codebase, so every module gets access to unrelated symbols, making tree-shaking harder and coupling higher.

Proposed Split

src/constants.ts (~40 lines) — container names, port constants, env-size thresholds

src/docker-host.ts (~40 lines) — setAwfDockerHost, getLocalDockerEnv

src/host-identity.ts (~100 lines) — UID/GID validation, getRealUserHome, ACT_PRESET_BASE_IMAGE, MIN_REGULAR_UID

src/github-env.ts (~200 lines) — readGitHubPathEntries, readGitHubEnvEntries, parseGitHubEnvFile, mergeGitHubPathEntries, readEnvFile, TOOLCHAIN_ENV_VARS

src/host-env.ts (~80 lines, facade) — subnetsOverlap, SslConfig, stripScheme, parseDifcProxyHost, plus re-exports for backward compat

Affected Callers

src/compose-generator.ts
src/config-writer.ts
src/container-cleanup.ts
src/container-lifecycle.ts
src/docker-manager.ts
src/services/agent-environment.ts
src/services/agent-service.ts
src/services/agent-volumes.ts
src/services/api-proxy-service.ts
src/services/cli-proxy-service.ts
src/services/doh-proxy-service.ts
src/services/squid-service.ts

Each caller only uses a subset of host-env.ts exports; the split would make those narrower dependencies explicit.

Security Note

getSafeHostUid / getSafeHostGid / validateIdNotInSystemRange are security-critical — they prevent the agent from running as a system account. Isolating them in a dedicated module makes it easier to audit and test that path independently.

Effort Estimate

Medium — mostly mechanical import updates across 12 files.

Benefits

• Easier to audit the security-critical UID/GID path in isolation
• Reduces coupling: each caller imports only what it needs
• Smaller, focused modules are easier to navigate and review

---

Detected by Refactoring Scanner workflow. Run date: 2026-05-16

Generated by Refactoring Opportunity Scanner · ● 4.6M · ◷

• expires on Jul 15, 2026, 3:19 PM UTC