fix(finalize): build javaexec in bin/finalize for source/git buildpack usage

bin/finalize only built src/java/finalize/cli into a temp dir; packaged
buildpacks got bin/javaexec from scripts/build.sh, but source/git usage
(e.g. WithBuildpacks("https://github.com/cloudfoundry/java-buildpack.git"))
had no bin/javaexec and finalize aborted before release completed.

- bin/finalize now also builds src/java/javaexec/cli into the same temp dir
  and passes the path via JAVAEXEC_BINARY_PATH.
- InstallJavaexecLauncher() (renamed from private) prefers JAVAEXEC_BINARY_PATH
  and falls back to <buildpackDir>/bin/javaexec for packaged buildpacks.
- Three unit tests cover packaged path, source/git env-var override, and the
  missing-binary error case.

Author: stokpop

bin/finalize

@@ -14,6 +14,8 @@ output_dir=$(mktemp -d -t finalizeXXX)
 pushd $BUILDPACK_DIR > /dev/null
 echo "-----> Running go build finalize"
 GOROOT=$GoInstallDir $GoInstallDir/bin/go build -mod=vendor -o $output_dir/finalize ./src/java/finalize/cli
+echo "-----> Running go build javaexec"
+GOROOT=$GoInstallDir $GoInstallDir/bin/go build -mod=vendor -o $output_dir/javaexec ./src/java/javaexec/cli
 popd > /dev/null
 
-$output_dir/finalize "$BUILD_DIR" "$CACHE_DIR" "$DEPS_DIR" "$DEPS_IDX" "$PROFILE_DIR"
+JAVAEXEC_BINARY_PATH=$output_dir/javaexec $output_dir/finalize "$BUILD_DIR" "$CACHE_DIR" "$DEPS_DIR" "$DEPS_IDX" "$PROFILE_DIR"

docs/DEVELOPING.md

@@ -97,6 +97,7 @@ Build the buildpack binaries:
 This creates executables in the `bin/` directory:
 - `bin/supply` - Staging phase binary (downloads and installs dependencies)
 - `bin/finalize` - Finalization phase binary (configures runtime)
+- `bin/javaexec` - Shell-free JVM launcher (tokenizes `JAVA_OPTS` without `eval`)
 
 ## Project Structure
 
@@ -118,6 +119,7 @@ java-buildpack/
 │   ├── jres/                           # JRE implementations (7 providers)
 │   ├── supply/cli/                     # Supply phase entrypoint
 │   ├── finalize/cli/                   # Finalize phase entrypoint
+│   ├── javaexec/cli/                   # Shell-free JVM launcher entrypoint
 │   ├── resources/                      # Resource configuration files
 │   └── integration/                    # Integration tests
 ├── scripts/                            # Build and test scripts
@@ -156,6 +158,7 @@ Build for the default platform (Linux):
 ```
 -----> Building supply for linux
 -----> Building finalize for linux
+-----> Building javaexec for linux
 -----> Build complete
 ```
 
@@ -193,6 +196,25 @@ go build -mod vendor -o bin/supply src/java/supply/cli/main.go
 
 # Build finalize
 go build -mod vendor -o bin/finalize src/java/finalize/cli/main.go
+
+# Build javaexec (shell-free JVM launcher, required at runtime)
+go build -mod vendor -o bin/javaexec src/java/javaexec/cli/main.go
+```
+
+### Source/Git Buildpack Usage
+
+When deploying with a git URL (`cf push -b https://github.com/.../java-buildpack.git`),
+Cloud Foundry runs `bin/finalize` directly from the cloned source. In that mode
+`bin/javaexec` does not exist (only packaged buildpacks have it). `bin/finalize`
+therefore builds `javaexec` into a temp directory alongside the finalize binary
+and passes the path via the `JAVAEXEC_BINARY_PATH` environment variable.
+`InstallJavaexecLauncher()` prefers this override and falls back to
+`bin/javaexec` for packaged buildpacks.
+
+To verify this path locally (no CF required):
+
+```bash
+bash scripts/test-javaexec-source-path.sh
 ```
 
 ## Running Tests

docs/design.md

@@ -186,6 +186,12 @@ During the finalize phase (`bin/finalize`), the buildpack:
 1. **Finalizes JRE**: Configures JVM options, memory calculator
 2. **Finalizes Frameworks**: Adds agent paths, system properties
 3. **Finalizes Container**: Generates launch command
+4. **Installs `javaexec`**: Copies the shell-free JVM launcher into
+   `$DEPS_DIR/<idx>/bin/javaexec`. The generated start command invokes it
+   instead of `eval "exec java $JAVA_OPTS ..."` so that `JAVA_OPTS` is
+   tokenized without shell interpretation. For source/git buildpack usage
+   `bin/finalize` builds `javaexec` on the fly and passes its path via
+   `JAVAEXEC_BINARY_PATH` (see [DEVELOPING.md](DEVELOPING.md#sourcegit-buildpack-usage)).
 
 Components can:
 - Read installed dependencies from `$DEPS_DIR/<idx>/`

scripts/test-javaexec-source-path.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+# Manual smoke test for the bin/finalize source/git buildpack path.
+# Simulates what bin/finalize does: build javaexec into a temp dir and pass
+# the path via JAVAEXEC_BINARY_PATH. Verifies the binary builds, that
+# InstallJavaexecLauncher picks up the override, and that javaexec tokenizes
+# JAVA_OPTS correctly when actually invoked.
+set -euo pipefail
+
+BUILDPACK_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+cd "$BUILDPACK_DIR"
+
+tmpdir=$(mktemp -d)
+trap 'rm -rf "$tmpdir"' EXIT
+
+echo "==> [1/4] Build javaexec from source (as bin/finalize now does)"
+go build -mod=vendor -o "$tmpdir/javaexec" ./src/java/javaexec/cli
+echo "    OK: $tmpdir/javaexec ($(wc -c < "$tmpdir/javaexec") bytes)"
+
+echo ""
+echo "==> [2/4] Build finalize from source"
+go build -mod=vendor -o "$tmpdir/finalize" ./src/java/finalize/cli
+echo "    OK: $tmpdir/finalize"
+
+echo ""
+echo "==> [3/4] Unit tests: InstallJavaexecLauncher with JAVAEXEC_BINARY_PATH override"
+go test ./src/java/finalize/ -count=1 -v -run "javaexec launcher" 2>&1 | grep -E "PASS|FAIL|RUN|---"
+
+echo ""
+echo "==> [4/4] Tokenization smoke test: run javaexec with a fake java binary"
+
+# Fake java: prints each received argument on its own line.
+cat > "$tmpdir/fake-java" << 'EOF'
+#!/bin/bash
+printf '%s\n' "$@"
+EOF
+chmod +x "$tmpdir/fake-java"
+
+# Quoted value with spaces → one token; cron expr with * → literal; $(...) → not executed.
+JAVA_OPTS='-Dfoo="bar baz" -DcronSched="0 */7 * * * *" -Dwhere=$(hostname)' \
+  "$tmpdir/javaexec" "$tmpdir/fake-java" -jar app.jar 2>/dev/null > "$tmpdir/actual.txt"
+
+expected="-Dfoo=bar baz
+-DcronSched=0 */7 * * * *
+-Dwhere=\$(hostname)
+-jar
+app.jar"
+
+actual=$(cat "$tmpdir/actual.txt")
+
+if [ "$actual" = "$expected" ]; then
+  echo "    OK: all tokens correct"
+else
+  echo "    FAIL: unexpected output"
+  echo "    expected:"
+  printf '%s\n' "$expected" | sed 's/^/      /'
+  echo "    got:"
+  printf '%s\n' "$actual" | sed 's/^/      /'
+  exit 1
+fi
+
+echo ""
+echo "PASS: source/git buildpack path works."
+echo "      bin/finalize builds javaexec and passes it via JAVAEXEC_BINARY_PATH."
+echo "      javaexec tokenizes JAVA_OPTS correctly without shell execution."

src/integration/README.md

@@ -151,6 +151,12 @@ property that must hold in a real container launch:
 - **The `javaexec` launcher actually starts the JVM** for the affected containers,
   including `Play` (previously `eval exec java $JAVA_OPTS ...`).
 
+**Source/git buildpack path** (`bin/finalize` building `javaexec` on the fly) is
+**not covered** by integration tests here: they use a packaged zip where `bin/javaexec`
+is pre-built by `scripts/build.sh`. The source/git path is covered by unit tests in
+[`../java/finalize/finalize_test.go`](../java/finalize/finalize_test.go) and can be
+verified locally with `bash scripts/test-javaexec-source-path.sh`.
+
 ## Writing New Tests
 
 To add a new test:

src/java/finalize/finalize.go

@@ -115,7 +115,7 @@ func Run(f *Finalizer) error {
 	}
 
 	// Install the javaexec launcher binary used by the start command.
-	if err := f.installJavaexecLauncher(); err != nil {
+	if err := f.InstallJavaexecLauncher(); err != nil {
 		f.Log.Error("Failed to install javaexec launcher: %s", err.Error())
 		return err
 	}
@@ -198,13 +198,20 @@ func (f *Finalizer) finalizeFrameworks(ctx *common.Context) error {
 	return nil
 }
 
-// installJavaexecLauncher copies the javaexec launcher binary from the
-// buildpack's bin/ directory into the dependency directory so it is present in
-// the droplet at runtime. The start command (see containers.JavaExecCommand)
-// invokes it as $DEPS_DIR/<idx>/bin/javaexec to tokenize JAVA_OPTS without a
-// shell. The binary is required: if it is missing the generated start command
-// would fail at launch, so this returns an error rather than continuing.
-func (f *Finalizer) installJavaexecLauncher() error {
+// InstallJavaexecLauncher copies the javaexec launcher binary into the
+// dependency directory so it is present in the droplet at runtime. The start
+// command (see containers.JavaExecCommand) invokes it as
+// $DEPS_DIR/<idx>/bin/javaexec to tokenize JAVA_OPTS without a shell.
+//
+// Source path resolution (first match wins):
+//  1. JAVAEXEC_BINARY_PATH env var — set by bin/finalize for source/git usage
+//     where javaexec is built into a temp dir alongside the finalize binary.
+//  2. <buildpackDir>/bin/javaexec — present in packaged buildpacks built by
+//     scripts/build.sh.
+//
+// The binary is required: missing it means the generated start command would
+// fail at launch, so this returns an error rather than continuing.
+func (f *Finalizer) InstallJavaexecLauncher() error {
 	buildpackDir := f.BuildpackDir
 	if buildpackDir == "" {
 		var err error
@@ -215,6 +222,13 @@ func (f *Finalizer) installJavaexecLauncher() error {
 	}
 
 	src := filepath.Join(buildpackDir, "bin", "javaexec")
+	// For source/git buildpack usage the bin/finalize wrapper builds javaexec
+	// into a temp directory and passes the path here so the source checkout is
+	// not mutated. Prefer the override; fall back to <buildpackDir>/bin/javaexec
+	// for packaged buildpacks where scripts/build.sh provides the binary.
+	if override := os.Getenv("JAVAEXEC_BINARY_PATH"); override != "" {
+		src = override
+	}
 	data, err := os.ReadFile(src)
 	if err != nil {
 		return fmt.Errorf("javaexec launcher binary not found at %s (required by the start command): %w", src, err)

src/java/finalize/finalize_test.go

@@ -242,4 +242,43 @@ dependencies: []
 			Expect(depDir).To(ContainSubstring(depsDir))
 		})
 	})
+
+	Describe("javaexec launcher installation", func() {
+		It("installs launcher from buildpack bin/ for packaged buildpack usage", func() {
+			// Default path: <buildpackDir>/bin/javaexec already written in BeforeEach.
+			Expect(finalizer.InstallJavaexecLauncher()).To(Succeed())
+			installed := filepath.Join(stager.DepDir(), "bin", "javaexec")
+			Expect(installed).To(BeARegularFile())
+		})
+
+		It("installs launcher from JAVAEXEC_BINARY_PATH for source/git buildpack usage", func() {
+			// Simulate bin/finalize wrapper: javaexec built into a temp dir, path passed via env var.
+			// <buildpackDir>/bin/javaexec is still present from BeforeEach, but the env var must take precedence.
+			altBinary, err := os.CreateTemp("", "javaexec-alt-*")
+			Expect(err).NotTo(HaveOccurred())
+			defer os.Remove(altBinary.Name())
+			_, err = altBinary.WriteString("#!/bin/sh\n# alt\n")
+			Expect(err).NotTo(HaveOccurred())
+			Expect(altBinary.Close()).To(Succeed())
+
+			os.Setenv("JAVAEXEC_BINARY_PATH", altBinary.Name())
+			defer os.Unsetenv("JAVAEXEC_BINARY_PATH")
+
+			Expect(finalizer.InstallJavaexecLauncher()).To(Succeed())
+			installed := filepath.Join(stager.DepDir(), "bin", "javaexec")
+			Expect(installed).To(BeARegularFile())
+			content, err := os.ReadFile(installed)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(string(content)).To(ContainSubstring("# alt"))
+		})
+
+		It("fails when launcher is missing and JAVAEXEC_BINARY_PATH is not set", func() {
+			// Point BuildpackDir at an empty dir so bin/javaexec doesn't exist.
+			emptyDir, err := os.MkdirTemp("", "finalize-no-javaexec")
+			Expect(err).NotTo(HaveOccurred())
+			defer os.RemoveAll(emptyDir)
+			finalizer.BuildpackDir = emptyDir
+			Expect(finalizer.InstallJavaexecLauncher()).NotTo(Succeed())
+		})
+	})
 })