Repository navigation
[architect] Spec: Refactor vmtest package structure to split concerns #607
Description
Overview
Issue #604 identifies that pkg/vmtest couples image building, layer composition, and VM orchestration, making it difficult to reuse layer logic independently.
This spec defines the exact refactoring steps to split vmtest into focused packages.
Current Structure
- pkg/vmtest/image.go (264 LOC) — Dockerfile→OCI building
- pkg/vmtest/layer.go (661 LOC) — Layer composition, patching, filesystem overlays
- pkg/vmtest/run.go (673 LOC) — VM boot orchestration, lifecycle
- pkg/vmtest/runner.go (155 LOC) — Harness lifecycle ✓ (already well-abstracted)
- pkg/vmtest/spec.go (409 LOC) — Test manifest DSL, validation
Target Structure
Phase 1: Extract Pure Layer Logic → pkg/image/layer
Goal: Make layer composition independently importable.
- Create pkg/image/layer/
- Move layer.go → pkg/image/layer/
- Move layer_test.go → pkg/image/layer/
- Update package name: vmtest → layer
- Update imports within layer.go (no pkg/vmtest imports except for Spec type initially)
- Have pkg/vmtest/layer.go re-export types from pkg/image/layer for backwards compat
Deliverables:
- A project importing 'pkg/image/layer' gets only crypt, yaml, and shell dependencies
- No VM orchestration or kubevirt imports in the layer package
Phase 2: Extract Image Building → pkg/image/build
- Create pkg/image/build/
- Move image.go → pkg/image/build/
- Move image_test.go → pkg/image/build/
- Update package name, imports
- pkg/vmtest/image.go re-exports for compat
Phase 3: Extract Spec DSL → pkg/vmtest/spec (stays)
- Clean up internal-only types (buildContext, contextFile) to private
- Clear separation: spec is DSL only, independent of build/layer logic
Phase 4: Lean Down pkg/vmtest
- vmtest becomes the test harness orchestrator only
- Public API: Run, NewRunner, interfaces (ImagePreparer, VMLifecycle, etc.)
- Continue re-exporting types from pkg/image packages if external callers use them
Risk & Mitigation
| Risk | Mitigation |
|---|---|
| Large number of imports to update | Do phases atomically, test after each phase |
| Backwards compatibility break | Re-export key types from vmtest until deprecation period |
| Circular dependencies | Ensure pkg/image/ packages never import pkg/vmtest |
Success Criteria
- pkg/image/layer can be imported standalone without pulling VM/kubevirt deps
- pkg/image/build can be imported standalone (depends on layer only)
- pkg/vmtest imports from pkg/image packages instead of defining layer logic
- All existing tests pass
- vmtest's public API (Run, NewRunner, Result, Spec, etc.) is stable or re-exported
- A new tool outside corral can do: 'import "pkg/image/layer"' and use layer composition
Filed by architect agent (ACMM L6 — full mode)
🐝 Hive Agent: architect | Instance: new-hive-99 | SHA: 9a37f20
— hive: agent=architect backend=pi model=kiro-api-key/claude-haiku-4-5:low pi=1.2.0
Activity
hanthor commentedon Oct 31, 2026
Maintainer note: #631 was closed as superseded. Phase 1 (
pkg/image/layerbehind a Spec-freeLayerConfig) is #670, per the Option 1 decision on #604. Phase 2 (pkg/image/build) should start frommainafter #670 lands, as a separate move-only PR without compatibility re-exports.324 remaining items
hanthor-hive-agent commentedon Nov 9, 2026
@hanthor is configured as this hive's
project.ai_author, so Hive treats comments from it as its own and will not act on/hivecommands from it. To un-park this issue, remove the parking label by hand, or setproject.ai_authorto an account that is not a maintainer (clear it to author as the GitHub App bot).hanthor-hive-agent commentedon Nov 9, 2026
@hanthor is configured as this hive's
project.ai_author, so Hive treats comments from it as its own and will not act on/hivecommands from it. To un-park this issue, remove the parking label by hand, or setproject.ai_authorto an account that is not a maintainer (clear it to author as the GitHub App bot).hanthor-hive-agent commentedon Nov 9, 2026
@hanthor is configured as this hive's
project.ai_author, so Hive treats comments from it as its own and will not act on/hivecommands from it. To un-park this issue, remove the parking label by hand, or setproject.ai_authorto an account that is not a maintainer (clear it to author as the GitHub App bot).hanthor-hive-agent commentedon Nov 9, 2026
@hanthor is configured as this hive's
project.ai_author, so Hive treats comments from it as its own and will not act on/hivecommands from it. To un-park this issue, remove the parking label by hand, or setproject.ai_authorto an account that is not a maintainer (clear it to author as the GitHub App bot).hanthor-hive-agent commentedon Nov 9, 2026
@hanthor is configured as this hive's
project.ai_author, so Hive treats comments from it as its own and will not act on/hivecommands from it. To un-park this issue, remove the parking label by hand, or setproject.ai_authorto an account that is not a maintainer (clear it to author as the GitHub App bot).hanthor-hive-agent commentedon Nov 9, 2026
@hanthor is configured as this hive's
project.ai_author, so Hive treats comments from it as its own and will not act on/hivecommands from it. To un-park this issue, remove the parking label by hand, or setproject.ai_authorto an account that is not a maintainer (clear it to author as the GitHub App bot).hanthor-hive-agent commentedon Nov 9, 2026
@hanthor is configured as this hive's
project.ai_author, so Hive treats comments from it as its own and will not act on/hivecommands from it. To un-park this issue, remove the parking label by hand, or setproject.ai_authorto an account that is not a maintainer (clear it to author as the GitHub App bot).hanthor-hive-agent commentedon Nov 9, 2026
@hanthor is configured as this hive's
project.ai_author, so Hive treats comments from it as its own and will not act on/hivecommands from it. To un-park this issue, remove the parking label by hand, or setproject.ai_authorto an account that is not a maintainer (clear it to author as the GitHub App bot).hanthor-hive-agent commentedon Nov 9, 2026
@hanthor is configured as this hive's
project.ai_author, so Hive treats comments from it as its own and will not act on/hivecommands from it. To un-park this issue, remove the parking label by hand, or setproject.ai_authorto an account that is not a maintainer (clear it to author as the GitHub App bot).hanthor-hive-agent commentedon Nov 9, 2026
@hanthor is configured as this hive's
project.ai_author, so Hive treats comments from it as its own and will not act on/hivecommands from it. To un-park this issue, remove the parking label by hand, or setproject.ai_authorto an account that is not a maintainer (clear it to author as the GitHub App bot).hanthor commentedon Nov 10, 2026
Applied @hanthor's 2026-11-02
/hive decisionabove by hand: removedblocked, addedapproved-direction. The hive refused the command because @hanthor is itsproject.ai_author, and the repeated refusal replies were a marker-trust bug (fix proposed in hivecommons/hive#17512).