Skip to content

Architecture ​

This page explains how the pieces of Maven SDK Go fit together, and how a request flows from your code down to the mvn process and back. Every diagram below is rendered from Mermaid source embedded in this page.

System Context ​

At the top level, your application (or an AI agent) talks to a handful of small, focused packages. Only command and installer ever touch the outside world (the mvn process, the network, the filesystem); the rest are pure Go that operate on paths, XML, and strings.

Blue packages are pure / side-effect free — trivially unit-testable. Amber packages (command, installer) perform I/O and are exercised with mocked processes and HTTP test servers.

Typical AI-agent session ​

The SDK's most common caller is an automated agent that needs to build a project it has never seen. The whole session threads through four packages without the agent ever hard-coding a mvn path:

Package Dependency Graph ​

Internal dependencies are intentionally shallow — there are no cycles, and the leaf packages depend on nothing but the standard library.

PackageDepends onSide effects
findercommand (version check)reads PATH, M2_HOME, filesystem
commandstdlib onlyspawns mvn
pomencoding/xmlnone (pure)
settingsencoding/xmlnone (pure)
local_repositorycommandreads ~/.m2
installerfinder, commandnetwork, filesystem, env

Touchpoints: who touches what ​

Only two packages reach outside the process. Knowing which one owns a given side effect tells you what to mock in tests:

Maven Resolution (finder) ​

FindBestMaven implements a preference cascade: a project-local Maven Wrapper always wins over a system install, because the wrapper pins the exact Maven version the project was built with.

Command Execution Pipeline ​

The command package turns a fluent builder into an *exec.Cmd, runs it, and maps a non-zero exit into a structured *MavenError (never a bare string).

Builder Immutability ​

Convenience methods (Clean(), Install(), …) do not mutate the receiver. Each returns a fresh builder with the extra goal appended, so a single configured builder can be reused for many commands without cross-talk.

Maven Build Lifecycle ​

The convenience methods map onto Maven's three built-in lifecycles. Running a phase runs every phase before it in the same lifecycle.

SDK methodEffective commandTypical use
Install(mvn)mvn clean installlocal build + install to ~/.m2
CleanPackage()mvn clean packageproduce artifact, skip install
CleanDeploy()mvn clean deploypublish to a remote repo
Verify(mvn)mvn verifyrun integration tests + checks

Multi-module reactor build ​

For a multi-module project, Maven's reactor computes a build order from the inter-module dependency graph, then walks every module through the requested phase in that order. WithProjects / WithAlsoMake (-pl / -am) trim the graph; without them the whole reactor runs:

-pl a,c -am ("also-make") rebuilds a and c and a's dependencies upstream — so you don't ship c against a stale a. -amd ("also-make- dependents") does the reverse, rebuilding downstream consumers.

Installer: End-to-End Flow ​

InstallWithOptions is idempotent and platform-aware. It tries the cheapest option first (an already-installed Maven), then a native package manager, and only downloads a binary archive as a last resort.

Download with Mirror Fallback ​

Each mirror is retried with exponential backoff before moving on; a checksum mismatch is treated like a failed download and advances to the next mirror.

Platform Environment Configuration ​

The three operating systems persist MAVEN_HOME and extend PATH very differently. Windows is the tricky one: setx PATH truncates at 1024 chars, so the installer reads the existing user PATH from the registry and appends safely, degrading to a printed hint rather than corrupting PATH.

POM Object Model ​

pom.ParseFile deserializes pom.xml into a Project tree. The accessor methods (GetGAV, GetDependencies, …) provide null-safe reads with sensible defaults (e.g. packaging defaults to jar).

Effective POM assembly ​

A parsed Project is the raw model — what's literally in the file. The effective POM Maven actually builds merges that with the parent, active profiles, and the global/user settings.xml. The SDK parses the raw model into structs; the merge itself is what mvn help:effective-pom materializes:

TIP

Fields left empty in the child (version, scope, plugin config) are inherited from the parent. That's why a Dependency.Version can legitimately be "" in the parsed model — see the POM Parser reference.

Local Repository Layout ​

local_repository maps a Maven coordinate (GAV) onto its on-disk path inside ~/.m2/repository, mirroring Maven's own directory convention.

The group id org.springframework becomes the nested directory org/springframework — each dot is a path separator.

CLI Command Surface ​

The cmd/mvn-skills binary is a thin cobra wrapper over the six packages. Every subcommand resolves the mvn executable the same way (via --executable or finder.FindBestMaven), then delegates to the corresponding package function — so the CLI is just another caller of the SDK, not a parallel implementation.

How a CLI invocation flows ​

A typical mvn-skills build call threads through three layers — flag parsing, executable resolution, then the SDK function — and the SDK function itself drops into the mvn subprocess:

The same shape applies to every subcommand: flags → resolve executable (if needed) → call one SDK function → print. The CLI adds no business logic of its own, which is why the SDK remains the single source of truth.

Where to Next ​

Released under the MIT License.