[Refactoring] Decompose writeConfigs in src/config-writer.ts into focused sub-steps #4878

Refactoring Opportunity

Summary

• File: src/config-writer.ts
• Current size: 431 lines
• Key function: writeConfigs — 305 lines (the file's only export, lines 126–431)
• Responsibilities identified: 6 distinct concerns
• Score: 7 (+2 function >80 lines, +3 clearly >2 responsibilities, +2 security-critical path)

Evidence

writeConfigs (lines 126–431) inlines six unrelated concerns end-to-end with no extraction:

1. Log / state directory setup (lines 129–222, ~94 lines)
Creates and chowns agent-logs, session-state, squid-logs, api-proxy-logs, cli-proxy-logs, and /tmp/gh-aw/mcp-logs directories. Each ensureDirectory() call has its own inline onCreate/onAfterEnsure callback with ownership logic.

2. Chroot home bind-mount preparation (lines 224–285, ~62 lines)
Creates the emptyHomeDir placeholder and all whitelisted ~/.copilot, ~/.cache, etc. subdirectories on the host so Docker doesn't create them as root-owned. Also resolves and prepares runner tool-cache mountpoints. This concern owns the four private helper functions that lead the file (ensureDirectory, assertRealDirectory, createMissingOwnedDirectorySegments, prepareChrootHomeMountpoint) — none of them are used by any other exported function.

3. Seccomp profile resolution and copy (lines 299–323, ~25 lines)
Two fallback paths to locate seccomp-profile.json (embedded bundle → source tree → dist tree), throws if none found.

4. SSL Bump CA certificate generation (lines 325–344, ~20 lines)
Calls generateSessionCa and initSslDb, logs warnings about interception.

5. Configuration generation and writing (lines 353–388, ~36 lines)
Calls generateSquidConfig + generateDockerCompose, writes squid.conf and docker-compose.yml.

6. Audit artifact writing (lines 390–430, ~41 lines)
Writes redacted docker-compose, raw squid.conf, and policy manifest JSON to an audit/ subdirectory.

The security-critical path (Squid config with domain ACLs, docker-compose with credentials, SSL CA generation) is buried midway through a 305-line function — increasing the review burden for any security-sensitive change.

Proposed Split

Extract concerns #1 and #2 (which together own all 4 private helpers) into a dedicated module:

src/workdir-setup.ts (~175 lines)

• Moves ensureDirectory, assertRealDirectory, createMissingOwnedDirectorySegments, prepareChrootHomeMountpoint here
• Exports prepareWorkDirectories(config: WrapperConfig, logPaths: LogPaths): void — encapsulates concerns Improve links in readme to AW project #1 and Secret proxying #2

src/config-writer.ts (reduced to ~130 lines)

• Imports and calls prepareWorkDirectories
• Retains seccomp resolution, SSL Bump init, config generation, and audit writing
• writeConfigs drops from 305 lines to ~100 lines of clear orchestration:

  prepareWorkDirectories(config, logPaths);
  copySeccompProfile(config);
  const sslConfig = await initSslBump(config);
  writeSquidAndCompose(config, sslConfig);
  writeAuditArtifacts(config, ...);
  

Alternatively, the seccomp resolution (concern #3) could move to src/seccomp-profile.ts if it grows.

Affected Callers

grep -rn "from.*config-writer\|require.*config-writer" src/ 2>/dev/null

Known callers:

• src/docker-manager.ts — re-exports writeConfigs
• src/config-writer.test.ts — tests writeConfigs directly
• src/docker-manager-cleanup.test.ts — imports writeConfigs
• src/docker-manager-reexports.test.ts — import audit

Effort Estimate

Low — pure extract-module refactor; no behavioral change. The 4 private helpers at the top of the file map cleanly to the new module.

Benefits

• Security review of Squid config / docker-compose credential writing is easier when writeConfigs is a short orchestrator
• Chroot home preparation is independently testable without setting up full config-writer mocks
• The directory-setup helpers (ensureDirectory, assertRealDirectory) become easier to reuse
• Reduces the main exported function from 305 lines to ~100 lines

Detected by Refactoring Scanner workflow. Run date: 2026-06-13

Generated by Refactoring Opportunity Scanner · ◷

• expires on Aug 12, 2026, 3:35 PM UTC