From ff53fbdcfacc214bf804622382792f52153103da Mon Sep 17 00:00:00 2001
From: Adam Fisher <adam.fisher@theguardian.com>
Date: Tue, 4 Aug 2026 14:35:04 +0000
Subject: [PATCH] Declare the java toolchain in .tool-versions

script/setup installed maven via brew, which is macOS-only. It now resolves
dependencies.

script/test and script/run cd to the project root so they work from any
directory, matching the other skeletons.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 java/.gitignore     |  2 ++
 java/.tool-versions |  2 ++
 java/README.md      | 22 +++++++++++++++++++++-
 java/script/run     |  8 ++++++--
 java/script/setup   | 12 +++++-------
 java/script/test    |  8 ++++++--
 6 files changed, 42 insertions(+), 12 deletions(-)
 create mode 100644 java/.gitignore
 create mode 100644 java/.tool-versions

diff --git a/java/.gitignore b/java/.gitignore
new file mode 100644
index 0000000..b55eb8a
--- /dev/null
+++ b/java/.gitignore
@@ -0,0 +1,2 @@
+# Maven build output
+target/
diff --git a/java/.tool-versions b/java/.tool-versions
new file mode 100644
index 0000000..e1f4375
--- /dev/null
+++ b/java/.tool-versions
@@ -0,0 +1,2 @@
+java corretto-21
+maven 3
diff --git a/java/README.md b/java/README.md
index f4dd227..6ed5587 100644
--- a/java/README.md
+++ b/java/README.md
@@ -2,10 +2,30 @@
 
 Skeleton project for Java using Maven.
 
+## Toolchain
+
+The toolchain is declared in [`.tool-versions`](.tool-versions):
+
+```
+java corretto-21
+maven 3
+```
+
+Install it however you prefer — [mise](https://mise.jdx.dev) is the easiest route:
+
+```bash
+mise install
+```
+
+`./script/setup` does not install the toolchain; it expects the tools above to be on your `PATH`.
+
 ## Usage
 
 Feel free to run the main class and test suites directly through your IDE of choice. If you want to run from the terminal, you can use these commands:
 
-- `./script/setup` to attempt to install required packages (Java and Maven)
+- `./script/setup` to download dependencies
 - `./script/run` to run the main class
 - `./script/test` to run the test suite
+
+The example test passes out of the box. A good way to get your bearings is to break it
+deliberately, watch it fail, then put it back.
diff --git a/java/script/run b/java/script/run
index 73531ee..2f56be4 100755
--- a/java/script/run
+++ b/java/script/run
@@ -1,3 +1,7 @@
-#!/bin/bash
+#!/usr/bin/env bash
 
-mvn exec:java
\ No newline at end of file
+set -euo pipefail
+
+cd "$(dirname "${BASH_SOURCE[0]}")/.."
+
+mvn --quiet exec:java
diff --git a/java/script/setup b/java/script/setup
index 93e702a..ec10912 100755
--- a/java/script/setup
+++ b/java/script/setup
@@ -1,9 +1,7 @@
-#!/bin/bash
+#!/usr/bin/env bash
 
-set -e
+set -euo pipefail
 
-if which brew >/dev/null 2>&1 ; then
-  brew install maven
-else
-  echo "You don't have brew installed, so we can't automatically install Java and Maven. Please install them yourself."
-fi
\ No newline at end of file
+cd "$(dirname "${BASH_SOURCE[0]}")/.."
+
+mvn --quiet dependency:resolve
diff --git a/java/script/test b/java/script/test
index 8689dca..110bee7 100755
--- a/java/script/test
+++ b/java/script/test
@@ -1,3 +1,7 @@
-#!/bin/bash
+#!/usr/bin/env bash
 
-mvn test
\ No newline at end of file
+set -euo pipefail
+
+cd "$(dirname "${BASH_SOURCE[0]}")/.."
+
+mvn test