helm-java

Imported from manusa/helm-java (AGENTS.md). Install upstream with npx skills add manusa/helm-java. Copyright stays with the author.

helm-java — AI Agent Instructions

This file is the primary context for AI coding agents (Claude Code, Copilot, etc.) working in this repo. Read it first; fall back to grep/search only when something here is wrong or missing.

What this project is

A Java client library for Helm with no external CLI dependency. The Helm Go SDK (helm.sh/helm/v3) is compiled to a per-platform shared library via CGO and loaded from Java with JNA. The public Java API is a fluent builder that mirrors Helm CLI verbs: install, upgrade, uninstall, template, package, lint, repo, registry, search, show, status, history, get (values), test, list, dependency, push, version, create.

• Helm SDK version: tracked by native/go.mod (currently helm.sh/helm/v3 v3.21.0).
• Java baseline: source/target 1.8. Tests run on 8 (Linux CI) or 11 (macOS/Windows CI, because macos-latest dropped 8).
• Go baseline: pinned in native/go.mod and .github/workflows/build.yml (GO_VERSION); currently 1.25.10.

Repository layout

Multi-module Maven build (parent pom.xml) + a sibling Go module under native/. To find a file, use the naming patterns in Conventions — don't trust enumerations here, they go stale.

Build & test

The Maven parent has requireFilesExist enforcer that needs all 5 native binaries in native/out/. Submodule helm-java and lib/api skip the rule, but a top-level ./mvnw install will fail without them.

# Discover all targets (categorized: Build / Test / Code Quality / Development / Release)
make help

# Local dev (current platform only — skips the cross-platform enforcer check)
make build-current-platform        # = build-native + mvn clean verify with -Denforcer.skipRules=requireFilesExist

# Full Maven build (needs all 5 native binaries built first)
./mvnw clean install
./mvnw clean install -Dquickly     # skips tests AND invoker plugin

# Native binaries
make build-native                  # current platform (auto-detected: OS/arch → helm-<os>-<arch>.<ext>)
make build-native-cross-platform   # all 5 platforms via xgo (Docker required)

# Single Java test
./mvnw test -pl helm-java -Dtest=HelmInstallTest
./mvnw test -pl helm-java -Dtest=HelmInstallTest#withName

# Go tests
make test-go                       # = cd native && go clean -testcache && go test ./...

# Other useful targets
make build-all                     # cross-platform natives + Java build
make update-go-deps                # bulk-bump non-indirect Go deps
make license                       # apply license-header.txt to .go/.java files
make check-authors                 # verify @author tags (ARGS='--fix' suggests additions)
make release V=1.2.3 VS=1.3.0      # tag release and bump to next snapshot (maintainer only)
make maven-deploy                  # mvn -Prelease clean deploy (CI only; needs Central credentials)

CI:

• .github/workflows/build.yml: Linux job runs make test-go + make build-all on Java 8. Matrix jobs run make build-current-platform on Windows/macOS with Java 11.
• .github/workflows/release.yml and snapshots.yml: Linux Java 8; run make build-all then make maven-deploy.
• Shared CI infra: .github/actions/free-disk-space (composite action) reclaims runner disk space before Ubuntu builds.

Releasing (maintainer only)

Versioning is 0.0.X patch-only; main always sits on 0.0-SNAPSHOT (so VS=0.0 every time). Full flow for cutting v0.0.X:

1. Pre-flight: be on main, clean tree, in sync with origin. Skim git log v0.0.<X-1>..HEAD --oneline to confirm the scope is patch-worthy.
2. Cut the release: make release V=0.0.X VS=0.0. This sets the pom to 0.0.X, commits, tags v0.0.X, pushes the tag (which triggers release.yml), then sets the pom back to 0.0-SNAPSHOT, commits, and pushes main. Two commits land on main plus one tag.
3. Wait for release.yml: ~20 min. gh run watch <run-id> --exit-status until it's green. It builds all 5 native binaries and runs make maven-deploy to Maven Central. If it fails partway, artifacts may be partially staged — don't re-run blindly, inspect first.
4. Create the GitHub Release manually: release.yml only publishes to Maven Central; it does NOT cut a GitHub Release. On https://github.com/manusa/helm-java/releases/new pick the v0.0.X tag and click Generate release notes (this is what every prior release used — a PR list plus the compare/v0.0.<X-1>...v0.0.X link). Publish.
5. Verify on Maven Central: artifacts appear under https://central.sonatype.com/artifact/com.marcnuri.helm-java/helm-java within ~30 min of step 3 finishing.

Don't cancel running tests that hit Kubernetes — they leak cluster resources.

How a call flows (the model to keep in your head)

Java caller
  → Helm.install() returns InstallCommand          (helm-java/.../InstallCommand.java)
  → builder methods set fields
  → .call() invokes HelmLibHolder.INSTANCE.Install(installOptions)
                                                   (lib/api/.../HelmLib.java — JNA interface)
  → JNA marshals InstallOptions → C struct
  → //export Install in native/main.go             (CGO bridge, no logic)
  → helm.Install(...) in native/internal/helm/install.go   (real implementation)
  → returns C.Result (out/err/stdOut/stdErr) → JNA → Result → parsed into Release

Native library loading: Helm class holds HelmLibHolder.INSTANCE, initialized lazily by NativeLibrary.getInstance().load(). getInstance() uses Java ServiceLoader to discover the platform module on the classpath (each platform JAR has META-INF/services/com.marcnuri.helm.jni.NativeLibrary); if none found, falls back to RemoteJarLoader (downloads the correct platform JAR at runtime — works for Gradle, fails when air-gapped). helm-java/pom.xml has OS-activated profiles that pull in the right platform module automatically; both amd64/x86_64 and arm64/aarch64 aliases are handled.

Public API shape (Helm.java)

Verbs come in two forms where it makes sense:

• Static Helm.install(chart) — operates on an external chart path/URL.
• Instance new Helm(path).install() — operates on the chart at the Path the Helm was constructed with.

Verbs with both forms: install, template, show, upgrade. Most others are static-only (list, history, status, get, repo, registry, search, push, test, uninstall, version) or instance-only (dependency, lint, packageIt — naming dodges the package keyword).

Conventions

Java

• Source/target 1.8 — no var, no Map.of(...), no Optional in APIs, no records.
• Apache 2.0 header on every .go and .java file (make license enforces).
• @author Javadoc tags maintained (make check-authors).
• Tests: JUnit 5 + AssertJ. No mocking libraries — use real impls (Testcontainers/KinD for k8s).

Go

• go fmt. CGO //export functions in native/main.go are wrappers ONLY; logic goes in native/internal/helm/<verb>.go.

Naming

• Java command: {Verb}Command.java (e.g. InstallCommand).
• Java JNI options: {Operation}Options.java (e.g. InstallOptions, HistoryOptions, GetValuesOptions).
• Result/domain types: noun, no suffix (e.g. Release, Repository, LintResult, SearchResult).
• Tests: Helm{Feature}Test.java (HelmInstallTest, HelmKubernetesTest); exception: infrastructure tests like NativeLibraryTest.
• Go: file per verb in internal/helm/ (install.go, install_test.go).

Adding a new Helm command (end-to-end)

1. native/internal/helm/<verb>.go — write the real Go function (params struct + function returning (string, error)).
2. native/internal/helm/<verb>_test.go — Go test (use internal/test/env.go helpers if k8s needed).
3. native/main.go:
   • Add struct <Verb>Options { ... } in the CGO comment block.
   • Add //export <Verb> wrapper calling helm.<Verb>(...) via runCommand(...).
4. lib/api/src/main/java/com/marcnuri/helm/jni/<Verb>Options.java — JNA Structure mirroring the C struct (field order MUST match).
5. lib/api/.../HelmLib.java — add Result <Verb>(<Verb>Options options);.
6. helm-java/src/main/java/com/marcnuri/helm/<Verb>Command.java — fluent builder + call() that builds the options and invokes HelmLib. If the command returns structured data, add a result type alongside (e.g. Release).
7. helm-java/src/main/java/com/marcnuri/helm/Helm.java — factory method (static, instance, or both).
8. helm-java/src/test/java/com/marcnuri/helm/Helm{Verb}Test.java — JUnit test (see structure below).
9. Rebuild native: make build-native then ./mvnw test -pl helm-java.

Testing

• Black-box: test the public Java API, not internals.
• Use @Nested classes to group scenarios (typical: Valid / Invalid, or per-mode like ClientOnly / Kubernetes).
• Common setup in outer @BeforeEach; scenario-specific in nested.
• Prefer one assertion concern per @Test for clear failure isolation.
• @TempDir as a field for shared dirs; as a parameter for per-test dirs (see HelmInstallTest).
• k8s integration: HelmKubernetesTest spins up KinD via Testcontainers in @BeforeAll; clean releases in @AfterEach.
• Surefire sets KUBECONFIG=/dev/null in helm-java/pom.xml so tests cannot accidentally hit your local cluster — pass kubeConfigFile/kubeConfigContents explicitly.

class HelmFeatureTest {
  @TempDir private Path tempDir;
  private Helm helm;

  @BeforeEach
  void setUp() {
    helm = Helm.create().withName("test").withDir(tempDir).call();
  }

  @Nested
  class Valid {
    @Test
    void withName() {
      Release result = helm.install().clientOnly().withName("test").call();
      assertThat(result)
        .returns("test", Release::getName)
        .returns("deployed", Release::getStatus);
    }
  }

  @Nested
  class Invalid {
    @Test
    void withMissingChart() {
      InstallCommand cmd = Helm.install("/tmp/nothing").clientOnly().withName("test");
      assertThatThrownBy(cmd::call).message().contains("not found");
    }
  }
}

Debugging native calls

Most commands have .debug():

helm.install().debug().withName("test").call();

Stdout/stderr captured by runCommand in native/main.go and surfaced on the Result.

Troubleshooting

• Enforcer "files do not exist" — missing binaries in native/out/. Use make build-current-platform (skips the rule) for local dev.
• UnsatisfiedLinkError / no NativeLibrary found — platform module isn't on the classpath. Check the OS profile in helm-java/pom.xml activated for your os.family/os.arch.
• KinD tests hang / OOM — Docker not running or under-resourced.
• Go build fails — check go version matches native/go.mod; run cd native && go mod tidy.
• Windows native build — needs MinGW (CGO toolchain).

Things to ignore

• lib/wasi/ and native/wasm/ — abandoned WebAssembly experiment (issue #239). Not in the parent pom, no source files. Don't extend it; don't fix it.

Audits & background

• docs/research/native-codebase-audit.md — point-in-time snapshot of the Go layer (coverage, missing commands, known issues). Check the date before trusting it.