From 99a388adc289619ed9d58b10839ea9ec2edb0cff Mon Sep 17 00:00:00 2001
From: "E. G. Patrick Bos" <egpbos@gmail.com>
Date: Wed, 9 Sep 2026 12:33:37 +0200
Subject: [PATCH 1/2] Resolve a get_* install path that does not exist yet

tools/get_socrates.sh resolves its optional install-path argument through
portable_realpath, which rejects a path with a missing leaf (BSD realpath,
so every macOS host) or a missing parent (GNU realpath). set -euo pipefail
is enabled only further down the script, so the empty result travelled on
and surfaced as "could not create work tree dir ''" from git clone.
Creating the directory beforehand was the only way to pass a new
destination.

The helper now falls through to its python3 resolver whenever realpath
refuses the path, so a destination that does not exist yet resolves
lexically; git clone then creates it, parents included. The helper is
duplicated across the nine get_*.sh scripts and every copy carries the
same change, pinned by a test that compares the copies as text.
get_socrates.sh additionally stops with a named error if the resolution is
empty, instead of handing an empty string to git, and its usage header now
lists the positional argument.
---
 tests/tools/test_install_scripts.py | 154 +++++++++++++++++++++++++---
 tools/get_aragog.sh                 |  10 +-
 tools/get_boreas.sh                 |  10 +-
 tools/get_lavatmos.sh               |  10 +-
 tools/get_petsc.sh                  |  10 +-
 tools/get_socrates.sh               |  21 +++-
 tools/get_spider.sh                 |  10 +-
 tools/get_thermoenginelite.sh       |  10 +-
 tools/get_vulcan.sh                 |  10 +-
 tools/get_zalmoxis.sh               |  10 +-
 10 files changed, 207 insertions(+), 48 deletions(-)

diff --git a/tests/tools/test_install_scripts.py b/tests/tools/test_install_scripts.py
index f876704f6..fd37083e4 100644
--- a/tests/tools/test_install_scripts.py
+++ b/tests/tools/test_install_scripts.py
@@ -4,7 +4,6 @@
 
 Reusable shell logic replicated inline from ``tools/get_petsc.sh`` and
 ``tools/get_spider.sh``:
-- ``portable_realpath()``: cross-platform path resolution
 - ERR trap: exit-code and step-name capture
 - Platform detection: PETSC_ARCH assignment
 - Homebrew prefix fallback: architecture-aware default
@@ -13,9 +12,13 @@
 
 Blocks lifted out of the shipped scripts at run time, so that rewording a
 script re-runs its cases against the new text:
+- ``portable_realpath()``: cross-platform path resolution, including a
+  destination that does not exist yet, plus the invariant that every
+  ``get_*.sh`` copy of the helper carries the same text
 - ``tools/get_aragog.sh``: the dirty-checkout guard shared across ``get_*.sh``
 - ``tools/get_socrates.sh``: the portable-flag rewrite, its post-build flag
-  check, and the conditional AGNI-wrapper rebuild note
+  check, the install-path resolution, and the conditional AGNI-wrapper
+  rebuild note
 
 Also pins invariants that live in checked-in configuration and documentation
 rather than in shell, each of which fails silently when its counterpart moves:
@@ -48,17 +51,22 @@
 # ---------------------------------------------------------------------------
 # Helper: extract portable_realpath function from a script
 # ---------------------------------------------------------------------------
+def _extract_shell_function(script: str, name: str) -> str:
+    """Return the shipped bash source of ``name`` in ``tools/<script>``.
+
+    Lifting the definition out of the script under test, rather than copying
+    it here, keeps the cases below running against the shipped text.
+    """
+    tools_dir = Path(__file__).resolve().parents[2] / 'tools'
+    lines = (tools_dir / script).read_text().splitlines()
+    start = next(i for i, ln in enumerate(lines) if ln.startswith(f'{name}() {{'))
+    end = next(i for i, ln in enumerate(lines) if ln == '}' and i > start)
+    return '\n'.join(lines[start : end + 1]) + '\n'
+
+
 def _portable_realpath_fn() -> str:
-    """Return the bash source for ``portable_realpath()``."""
-    return """\
-portable_realpath() {
-    if command -v realpath >/dev/null 2>&1; then
-        realpath "$1"
-    else
-        python3 -c "import os,sys; print(os.path.realpath(sys.argv[1]))" "$1"
-    fi
-}
-"""
+    """Return the bash source for the shipped ``portable_realpath()``."""
+    return _extract_shell_function('get_socrates.sh', 'portable_realpath')
 
 
 # ---------------------------------------------------------------------------
@@ -158,6 +166,53 @@ def test_portable_realpath_python_fallback(tmp_path):
     assert resolved == str(target)
 
 
+@pytest.mark.unit
+def test_portable_realpath_resolves_missing_path(tmp_path):
+    """Resolves a destination that does not exist yet, as an install path.
+
+    BSD realpath (macOS) rejects a missing leaf and GNU realpath a missing
+    parent, so both a missing leaf and a missing nested path are covered.
+    An empty result here is the regression: the caller feeds the value
+    straight to ``git clone``, which then fails on an empty work-tree name.
+    """
+    leaf = tmp_path / 'not-created-yet'
+    nested = tmp_path / 'no' / 'such' / 'tree'
+    snippet = (
+        _portable_realpath_fn() + f'\nportable_realpath "{leaf}"\nportable_realpath "{nested}"'
+    )
+    result = subprocess.run(['bash', '-c', snippet], capture_output=True, text=True)
+
+    assert result.returncode == 0, result.stderr
+    resolved = result.stdout.split()
+    assert len(resolved) == 2, result.stdout
+    # tmp_path is under a symlinked /var on macOS, so compare against the
+    # resolved parent rather than against the literal input path.
+    real_root = os.path.realpath(tmp_path)
+    assert resolved[0] == os.path.join(real_root, 'not-created-yet')
+    assert resolved[1] == os.path.join(real_root, 'no', 'such', 'tree')
+
+
+@pytest.mark.unit
+def test_portable_realpath_identical_across_get_scripts():
+    """Every ``tools/get_*.sh`` copy of the helper is the same text.
+
+    The helper is duplicated because the scripts are standalone; a fix
+    applied to one copy and not the others reintroduces the missing-path
+    failure in whichever script was missed.
+    """
+    tools_dir = Path(__file__).resolve().parents[2] / 'tools'
+    copies = {
+        script.name: _extract_shell_function(script.name, 'portable_realpath')
+        for script in sorted(tools_dir.glob('get_*.sh'))
+        if 'portable_realpath() {' in script.read_text()
+    }
+
+    # Guard the guard: a mis-rooted glob would make the comparison vacuous.
+    assert len(copies) >= 5, sorted(copies)
+    assert 'get_socrates.sh' in copies
+    assert len(set(copies.values())) == 1, sorted(copies)
+
+
 # ---------------------------------------------------------------------------
 # ERR trap tests
 # ---------------------------------------------------------------------------
@@ -1019,6 +1074,81 @@ def test_post_build_guard_rejects_cpu_specific_template_flags(tmp_path):
         assert 'GUARD_OK' not in res.stdout
 
 
+# ---------------------------------------------------------------------------
+# Install-path resolution (tools/get_socrates.sh)
+# ---------------------------------------------------------------------------
+
+
+def _run_install_path_block(root, argv, stub_resolver: str = '') -> subprocess.CompletedProcess:
+    """Run the shipped argument split and install-path resolution.
+
+    ``stub_resolver`` replaces ``portable_realpath`` with a fixture, so the
+    empty-resolution branch can be reached without an unusable host.
+    """
+    block = _extract_socrates_block(
+        '# Separate the --force flag', '# Refuse to delete a checkout'
+    )
+    resolver = stub_resolver or _portable_realpath_fn()
+    snippet = f'set -u\nroot="{root}"\n' + resolver + block + '\necho "SOCPATH=$socpath"\n'
+    return subprocess.run(
+        ['bash', '-c', snippet, 'get_socrates.sh', *argv],
+        capture_output=True,
+        text=True,
+    )
+
+
+@pytest.mark.unit
+def test_install_path_resolves_before_the_checkout_exists(tmp_path):
+    """A custom destination that does not exist yet resolves to a real path.
+
+    git clone creates the destination, including its parents, so the script
+    must not require the directory up front. An empty resolution is the
+    failure this pins: git clone then reports an empty work-tree name.
+    """
+    dest = tmp_path / 'no' / 'socrates-here'
+    res = _run_install_path_block(tmp_path / 'root', [str(dest)])
+
+    assert res.returncode == 0, res.stderr
+    socpath = res.stdout.strip().removeprefix('SOCPATH=')
+    assert socpath, res.stderr
+    assert socpath == os.path.join(os.path.realpath(tmp_path), 'no', 'socrates-here')
+
+
+@pytest.mark.unit
+def test_install_path_default_and_force_flag(tmp_path):
+    """--force alone keeps the default destination; a path with it is honoured.
+
+    The flag and the optional positional share one argument list, so the
+    ordering of the two must not shift which value lands in socpath.
+    """
+    root = tmp_path / 'root'
+    dest = tmp_path / 'elsewhere'
+
+    default = _run_install_path_block(root, ['--force'])
+    assert default.returncode == 0, default.stderr
+    assert default.stdout.strip() == f'SOCPATH={root}/socrates'
+
+    override = _run_install_path_block(root, ['--force', str(dest)])
+    assert override.returncode == 0, override.stderr
+    assert override.stdout.strip() == f'SOCPATH={os.path.realpath(tmp_path)}/elsewhere'
+
+
+@pytest.mark.unit
+def test_install_path_rejects_unresolvable_path(tmp_path):
+    """An empty resolution stops the script instead of reaching git clone.
+
+    set -euo pipefail is enabled further down the script, so a resolver that
+    fails here would otherwise leave socpath empty and continue.
+    """
+    stub = 'portable_realpath() {\n    return 1\n}\n'
+    res = _run_install_path_block(tmp_path / 'root', ['some/path'], stub_resolver=stub)
+
+    assert res.returncode == 1, res.stdout
+    assert 'could not resolve install path' in res.stderr
+    assert 'some/path' in res.stderr
+    assert 'SOCPATH=' not in res.stdout
+
+
 # ---------------------------------------------------------------------------
 # Post-rebuild AGNI-wrapper note (tools/get_socrates.sh)
 # ---------------------------------------------------------------------------
diff --git a/tools/get_aragog.sh b/tools/get_aragog.sh
index a19971298..ae2334adc 100755
--- a/tools/get_aragog.sh
+++ b/tools/get_aragog.sh
@@ -17,11 +17,13 @@
 echo "Set up Aragog..."
 
 portable_realpath() {
-    if command -v realpath >/dev/null 2>&1; then
-        realpath "$1"
-    else
-        python3 -c "import os,sys; print(os.path.realpath(sys.argv[1]))" "$1"
+    # Keep this helper in sync across the get_* scripts. A path that does not
+    # exist yet is rejected by realpath (BSD refuses a missing leaf, GNU a
+    # missing parent), so fall through to python3 there too.
+    if command -v realpath >/dev/null 2>&1 && realpath "$1" 2>/dev/null; then
+        return 0
     fi
+    python3 -c "import os,sys; print(os.path.realpath(sys.argv[1]))" "$1"
 }
 
 # Path to PROTEUS folder
diff --git a/tools/get_boreas.sh b/tools/get_boreas.sh
index f86bf9eab..c4d94e053 100755
--- a/tools/get_boreas.sh
+++ b/tools/get_boreas.sh
@@ -13,11 +13,13 @@ set -euo pipefail
 echo "Set up BOREAS..."
 
 portable_realpath() {
-    if command -v realpath >/dev/null 2>&1; then
-        realpath "$1"
-    else
-        python3 -c "import os,sys; print(os.path.realpath(sys.argv[1]))" "$1"
+    # Keep this helper in sync across the get_* scripts. A path that does not
+    # exist yet is rejected by realpath (BSD refuses a missing leaf, GNU a
+    # missing parent), so fall through to python3 there too.
+    if command -v realpath >/dev/null 2>&1 && realpath "$1" 2>/dev/null; then
+        return 0
     fi
+    python3 -c "import os,sys; print(os.path.realpath(sys.argv[1]))" "$1"
 }
 
 # Path to PROTEUS folder
diff --git a/tools/get_lavatmos.sh b/tools/get_lavatmos.sh
index b7a7ca819..be9aab71b 100755
--- a/tools/get_lavatmos.sh
+++ b/tools/get_lavatmos.sh
@@ -4,11 +4,13 @@
 echo "Set up LavAtmos..."
 
 portable_realpath() {
-    if command -v realpath >/dev/null 2>&1; then
-        realpath "$1"
-    else
-        python3 -c "import os,sys; print(os.path.realpath(sys.argv[1]))" "$1"
+    # Keep this helper in sync across the get_* scripts. A path that does not
+    # exist yet is rejected by realpath (BSD refuses a missing leaf, GNU a
+    # missing parent), so fall through to python3 there too.
+    if command -v realpath >/dev/null 2>&1 && realpath "$1" 2>/dev/null; then
+        return 0
     fi
+    python3 -c "import os,sys; print(os.path.realpath(sys.argv[1]))" "$1"
 }
 
 # Path to PROTEUS folder
diff --git a/tools/get_petsc.sh b/tools/get_petsc.sh
index 09266cc9c..f372d72b3 100755
--- a/tools/get_petsc.sh
+++ b/tools/get_petsc.sh
@@ -35,11 +35,13 @@ set -e
 # in PROTEUS's conda environment.
 # -----------------------------------------------------------------------------
 portable_realpath() {
-    if command -v realpath >/dev/null 2>&1; then
-        realpath "$1"
-    else
-        python3 -c "import os,sys; print(os.path.realpath(sys.argv[1]))" "$1"
+    # Keep this helper in sync across the get_* scripts. A path that does not
+    # exist yet is rejected by realpath (BSD refuses a missing leaf, GNU a
+    # missing parent), so fall through to python3 there too.
+    if command -v realpath >/dev/null 2>&1 && realpath "$1" 2>/dev/null; then
+        return 0
     fi
+    python3 -c "import os,sys; print(os.path.realpath(sys.argv[1]))" "$1"
 }
 
 # -----------------------------------------------------------------------------
diff --git a/tools/get_socrates.sh b/tools/get_socrates.sh
index 4f08ab131..fa573644c 100755
--- a/tools/get_socrates.sh
+++ b/tools/get_socrates.sh
@@ -1,5 +1,10 @@
 #!/bin/bash
 # Download and compile socrates
+#
+# Usage:
+#   tools/get_socrates.sh            # install into ./socrates/
+#   tools/get_socrates.sh some/path  # custom destination, created if missing
+#   tools/get_socrates.sh --force    # discard an existing checkout
 
 # Do we have NetCDF?
 if ! [ -x "$(command -v nc-config)" ]; then
@@ -27,11 +32,13 @@ if [ -n "$RAD_DIR" ]; then
 fi
 
 portable_realpath() {
-    if command -v realpath >/dev/null 2>&1; then
-        realpath "$1"
-    else
-        python3 -c "import os,sys; print(os.path.realpath(sys.argv[1]))" "$1"
+    # Keep this helper in sync across the get_* scripts. A path that does not
+    # exist yet is rejected by realpath (BSD refuses a missing leaf, GNU a
+    # missing parent), so fall through to python3 there too.
+    if command -v realpath >/dev/null 2>&1 && realpath "$1" 2>/dev/null; then
+        return 0
     fi
+    python3 -c "import os,sys; print(os.path.realpath(sys.argv[1]))" "$1"
 }
 
 
@@ -64,6 +71,12 @@ done
 
 if [ -n "$install_path" ]; then
     socpath="$(portable_realpath "$install_path")"
+    # set -euo pipefail is not active yet, so an unresolvable path would
+    # otherwise reach git clone as an empty string.
+    if [ -z "$socpath" ]; then
+        echo "ERROR: could not resolve install path '$install_path'." >&2
+        exit 1
+    fi
 else
     socpath="$root/socrates"
 fi
diff --git a/tools/get_spider.sh b/tools/get_spider.sh
index 0514d9d60..0f2952b25 100755
--- a/tools/get_spider.sh
+++ b/tools/get_spider.sh
@@ -37,11 +37,13 @@ set -e
 # in PROTEUS's conda environment.
 # -----------------------------------------------------------------------------
 portable_realpath() {
-    if command -v realpath >/dev/null 2>&1; then
-        realpath "$1"
-    else
-        python3 -c "import os,sys; print(os.path.realpath(sys.argv[1]))" "$1"
+    # Keep this helper in sync across the get_* scripts. A path that does not
+    # exist yet is rejected by realpath (BSD refuses a missing leaf, GNU a
+    # missing parent), so fall through to python3 there too.
+    if command -v realpath >/dev/null 2>&1 && realpath "$1" 2>/dev/null; then
+        return 0
     fi
+    python3 -c "import os,sys; print(os.path.realpath(sys.argv[1]))" "$1"
 }
 
 # -----------------------------------------------------------------------------
diff --git a/tools/get_thermoenginelite.sh b/tools/get_thermoenginelite.sh
index 589c4069f..887a153d1 100755
--- a/tools/get_thermoenginelite.sh
+++ b/tools/get_thermoenginelite.sh
@@ -14,11 +14,13 @@ if ! [ -x "$(command -v pip)" ]; then
 fi
 
 portable_realpath() {
-    if command -v realpath >/dev/null 2>&1; then
-        realpath "$1"
-    else
-        python3 -c "import os,sys; print(os.path.realpath(sys.argv[1]))" "$1"
+    # Keep this helper in sync across the get_* scripts. A path that does not
+    # exist yet is rejected by realpath (BSD refuses a missing leaf, GNU a
+    # missing parent), so fall through to python3 there too.
+    if command -v realpath >/dev/null 2>&1 && realpath "$1" 2>/dev/null; then
+        return 0
     fi
+    python3 -c "import os,sys; print(os.path.realpath(sys.argv[1]))" "$1"
 }
 
 # Path to PROTEUS folder
diff --git a/tools/get_vulcan.sh b/tools/get_vulcan.sh
index 5bc9790ec..65366a549 100755
--- a/tools/get_vulcan.sh
+++ b/tools/get_vulcan.sh
@@ -15,11 +15,13 @@ set -euo pipefail
 echo "Set up VULCAN..."
 
 portable_realpath() {
-    if command -v realpath >/dev/null 2>&1; then
-        realpath "$1"
-    else
-        python3 -c "import os,sys; print(os.path.realpath(sys.argv[1]))" "$1"
+    # Keep this helper in sync across the get_* scripts. A path that does not
+    # exist yet is rejected by realpath (BSD refuses a missing leaf, GNU a
+    # missing parent), so fall through to python3 there too.
+    if command -v realpath >/dev/null 2>&1 && realpath "$1" 2>/dev/null; then
+        return 0
     fi
+    python3 -c "import os,sys; print(os.path.realpath(sys.argv[1]))" "$1"
 }
 
 # Path to PROTEUS folder
diff --git a/tools/get_zalmoxis.sh b/tools/get_zalmoxis.sh
index 96e78293a..79bb9331a 100755
--- a/tools/get_zalmoxis.sh
+++ b/tools/get_zalmoxis.sh
@@ -18,11 +18,13 @@
 echo "Set up Zalmoxis..."
 
 portable_realpath() {
-    if command -v realpath >/dev/null 2>&1; then
-        realpath "$1"
-    else
-        python3 -c "import os,sys; print(os.path.realpath(sys.argv[1]))" "$1"
+    # Keep this helper in sync across the get_* scripts. A path that does not
+    # exist yet is rejected by realpath (BSD refuses a missing leaf, GNU a
+    # missing parent), so fall through to python3 there too.
+    if command -v realpath >/dev/null 2>&1 && realpath "$1" 2>/dev/null; then
+        return 0
     fi
+    python3 -c "import os,sys; print(os.path.realpath(sys.argv[1]))" "$1"
 }
 
 # Path to PROTEUS folder

From 6fd24a3960e88afcba469de7064384660e4773b0 Mon Sep 17 00:00:00 2001
From: "E. G. Patrick Bos" <egpbos@gmail.com>
Date: Wed, 9 Sep 2026 13:41:06 +0200
Subject: [PATCH 2/2] Say why the helper is read from one script only

---
 tests/tools/test_install_scripts.py | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/tests/tools/test_install_scripts.py b/tests/tools/test_install_scripts.py
index fd37083e4..055707206 100644
--- a/tests/tools/test_install_scripts.py
+++ b/tests/tools/test_install_scripts.py
@@ -65,7 +65,15 @@ def _extract_shell_function(script: str, name: str) -> str:
 
 
 def _portable_realpath_fn() -> str:
-    """Return the bash source for the shipped ``portable_realpath()``."""
+    """Return the bash source for the shipped ``portable_realpath()``.
+
+    Nine ``get_*.sh`` scripts carry the helper, so which one is read is
+    arbitrary; ``get_socrates.sh`` is the one whose install-path handling is
+    exercised further down this file. Reading a single copy is sound only
+    because ``test_portable_realpath_identical_across_get_scripts`` pins the
+    copies as the same text: drop that test and these cases stop covering
+    the other eight.
+    """
     return _extract_shell_function('get_socrates.sh', 'portable_realpath')