Skip to content

Refactor: Extract Docker execution logic out of structure/ module #17

@astefano

Description

@astefano

Problem

The src/structure/ module is responsible for managing verification structure files (frontmatter parsing, .md file I/O, certificates, config paths). However, it currently also owns the entire Docker/local command execution engine, which is an unrelated concern.

This coupling was introduced in commit 5100ccd ("feat(docker): add production-ready Docker execution support and CI"), which added executor.rs directly into structure/ and placed ExecutionMode / CommandConfig into structure/config.rs. Every subsequent PR (#11, #12, #14) built on top of that placement, deepening the coupling.

What lives in structure/ today that shouldn't

File Docker/execution concerns
executor.rs run_docker(), ensure_image_pulled(), Docker container orchestration (volume mounts, tmpfs, env vars, user mapping)
config.rs ExecutionMode enum, CommandConfig struct, docker-image field, DEFAULT_DOCKER_IMAGE
probe.rs Docker-vs-local branching in require_probe_installed()

Why this is a problem

  1. Semantic incoherence. Every command module (atomize, create, specify, verify, init) imports CommandConfig and ExecutionMode from crate::structure. A module about structure files is acting as the authority on how to run external processes.

  2. Wrong dependency direction. If a future non-structure command needs to run something in Docker, it would have to import from structure/, which makes no sense. The execution layer should be independent and reusable.

  3. Harder to reason about. When reading structure/mod.rs, you see re-exports for both frontmatter parsing and Docker container configuration side by side. New contributors have no way to guess that "structure" means "structure files + process execution."

  4. Testing friction. Testing structure-file logic (frontmatter, certs) currently pulls in the execution types even though they're unrelated.

Proposed solution

Extract execution concerns into a dedicated src/execution/ module:

src/
  execution/           # NEW
    mod.rs             # re-exports
    executor.rs        # run_command, run_local, run_docker, ensure_image_pulled
    config.rs          # CommandConfig, ExecutionMode
    probe.rs           # require_probe_installed, cleanup_intermediate_files
  structure/           # EXISTING, now only about structure files
    mod.rs
    config.rs          # StructureConfig, ConfigPaths (depends on execution::CommandConfig)
    frontmatter.rs
    certs.rs
    utils.rs

This is a pure module extraction — no logic changes, just moving types and updating import paths. structure/config.rs would depend on execution::CommandConfig rather than owning it.

Files that need changes

  • src/structure/executor.rssrc/execution/executor.rs
  • src/structure/probe.rssrc/execution/probe.rs
  • ExecutionMode, CommandConfig out of src/structure/config.rssrc/execution/config.rs
  • src/structure/mod.rs — remove execution re-exports
  • src/execution/mod.rs — new, with re-exports
  • src/main.rs — add mod execution
  • src/commands/atomize.rs, create.rs, specify.rs, verify.rs, init.rs — update imports
  • src/structure/utils.rsrun_command delegates to executor, update import

Context

  • Introduced by commit 5100ccd

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions