feat: add local native CLI installer for Linux and macOS

Bootstrap the pinned GraalVM when needed, validate native build prerequisites, and install a verified standalone executable with the aie shortcut. Document usage and add installer fixtures to native CI.

Validated with 14 installer tests, a real macOS ARM64 native build and installation, and the full installed CLI smoke suite. Publication explicitly authorized by the user: commit e push.
This commit is contained in:
2026-11-16 15:32:01 +00:00
parent 8f6cfa5d86
commit 1e440c12ee
16 changed files with 764 additions and 1 deletions
+178
View File
@@ -0,0 +1,178 @@
#!/usr/bin/env bash
# Build from this checkout and install a standalone CLI for the current user.
set -euo pipefail
usage() {
cat <<'EOF'
Usage: scripts/install-native.sh [--bin-dir DIR]
Build and install ai-engineering and the aie shortcut (Linux/macOS).
Default destination: $HOME/.local/bin. Run again to update.
Uses GRAALVM_HOME, a compatible JAVA_HOME, or installs the GraalVM pinned in
.sdkmanrc through SDKMAN (bootstrapped when absent). Requires JDK 25 with
Native Image and the platform's C/C++ toolchain. Downloads require internet.
Does not install system packages or edit shell profiles.
Options:
--bin-dir DIR Installation directory (no sudo needed for the default).
-h, --help Show this help.
EOF
}
die() { printf 'Error: %s\n' "$*" >&2; exit 1; }
log() { printf '\n==> %s\n' "$*"; }
bin_dir="${HOME:?HOME must be set}/.local/bin"
while [[ $# -gt 0 ]]; do
case "$1" in
--bin-dir)
[[ $# -ge 2 && -n "$2" && "$2" != --* ]] || die '--bin-dir requires a directory.'
bin_dir=$2
shift 2
;;
-h|--help) usage; exit 0 ;;
*) usage >&2; die "Unknown argument: $1" ;;
esac
done
project_dir=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd -P)
platform=$(uname -s)
architecture=$(uname -m)
case "$platform/$architecture" in
Linux/x86_64|Linux/aarch64|Linux/arm64|Darwin/arm64) ;;
Darwin/x86_64)
die 'The pinned GraalVM does not support macOS Intel. Use the JVM build (see README.md).'
;;
*) die "Unsupported platform: $platform/$architecture (requires Linux x64/ARM64 or macOS Apple Silicon)." ;;
esac
case "$bin_dir" in /*) ;; *) bin_dir="$PWD/$bin_dir" ;; esac
for name in ai-engineering aie; do
[[ ! -d "$bin_dir/$name" ]] || die "Installation target is a directory: $bin_dir/$name"
done
work_dir=$(mktemp -d "${TMPDIR:-/tmp}/aie-native.XXXXXXXX")
stage_dir=''
cleanup() {
rm -rf -- "$work_dir"
if [[ -n "$stage_dir" ]]; then rm -rf -- "$stage_dir"; fi
}
trap cleanup EXIT
trap 'exit 130' INT
trap 'exit 143' TERM
toolchain_help() {
if [[ "$platform" == Darwin ]]; then
printf 'Install Apple Command Line Tools: xcode-select --install\n' >&2
else
cat >&2 <<'EOF'
Install the C/C++ toolchain and zlib development headers, then retry:
Debian/Ubuntu: sudo apt-get install build-essential zlib1g-dev
Fedora/RHEL: sudo dnf install gcc gcc-c++ glibc-devel zlib-devel libstdc++-static
EOF
fi
}
log 'Checking native build prerequisites'
if [[ "$platform" == Darwin ]]; then
compiler=clang
if ! xcode-select -p >/dev/null 2>&1; then
toolchain_help
die 'Apple Command Line Tools are missing.'
fi
else
compiler=gcc
fi
if ! command -v "$compiler" >/dev/null 2>&1; then
toolchain_help
die "Missing compiler: $compiler"
fi
cat > "$work_dir/check.c" <<'EOF'
#include <stdio.h>
#include <zlib.h>
int main(void) { return zlibVersion() == NULL; }
EOF
link_flags=(-lz)
if [[ "$platform" == Linux ]]; then link_flags+=(-lstdc++); fi
if ! "$compiler" "$work_dir/check.c" -o "$work_dir/check" "${link_flags[@]}"; then
toolchain_help
die 'The compiler, system headers or native libraries are incomplete.'
fi
compatible_graalvm() {
local candidate=$1 java_version native_version
[[ -x "$candidate/bin/java" && -x "$candidate/bin/native-image" ]] || return 1
java_version=$("$candidate/bin/java" -version 2>&1) || return 1
native_version=$("$candidate/bin/native-image" --version 2>&1) || return 1
[[ "$java_version" =~ version\ \"25[.\"] && "$native_version" =~ 25[.\ ] ]]
}
if [[ -n "${GRAALVM_HOME:-}" ]]; then
compatible_graalvm "$GRAALVM_HOME" || die 'GRAALVM_HOME must contain GraalVM JDK 25 with Native Image.'
graalvm_dir=$GRAALVM_HOME
elif [[ -n "${JAVA_HOME:-}" ]] && compatible_graalvm "$JAVA_HOME"; then
graalvm_dir=$JAVA_HOME
else
# Read just the pinned value; do not execute repository configuration.
pinned_java=$(sed -n 's/^java=//p' "$project_dir/.sdkmanrc" | tr -d '\r')
[[ -n "$pinned_java" && "$pinned_java" != *$'\n'* ]] || die 'Expected one java= version in .sdkmanrc.'
export SDKMAN_DIR="${SDKMAN_DIR:-$HOME/.sdkman}"
graalvm_dir="$SDKMAN_DIR/candidates/java/$pinned_java"
if ! compatible_graalvm "$graalvm_dir"; then
for dependency in curl zip unzip; do
command -v "$dependency" >/dev/null 2>&1 || die "Install $dependency before bootstrapping GraalVM with SDKMAN."
done
if [[ ! -s "$SDKMAN_DIR/bin/sdkman-init.sh" ]]; then
log "Installing SDKMAN in $SDKMAN_DIR"
curl --fail --show-error --silent --location --retry 3 \
'https://get.sdkman.io?ci=true&rcupdate=false' -o "$work_dir/sdkman-install.sh"
bash "$work_dir/sdkman-install.sh"
fi
log "Installing GraalVM $pinned_java through SDKMAN"
# SDKMAN shell functions are not compatible with nounset/errexit.
# Isolate their shell options and decline changing an existing default JDK.
(
set +eu
source "$SDKMAN_DIR/bin/sdkman-init.sh" || exit 1
sdkman_auto_answer=false
sdk install java "$pinned_java" <<< 'n'
) || die "SDKMAN could not install $pinned_java. Configure GRAALVM_HOME with a compatible GraalVM JDK 25 and retry."
fi
compatible_graalvm "$graalvm_dir" || die "Invalid GraalVM installation: $graalvm_dir"
fi
graalvm_dir=$(cd -- "$graalvm_dir" && pwd -P)
export JAVA_HOME="$graalvm_dir"
export GRAALVM_HOME="$graalvm_dir"
export PATH="$JAVA_HOME/bin:$PATH"
log "Building with $JAVA_HOME"
(
cd -- "$project_dir"
# Explicitly select this JDK for Gradle toolchain discovery as well as its JVM.
./gradlew --no-daemon --console=plain \
"-Dorg.gradle.java.home=$JAVA_HOME" \
"-Porg.gradle.java.installations.paths=$JAVA_HOME" \
-Porg.gradle.java.installations.auto-detect=false \
-Porg.gradle.java.installations.auto-download=false nativeCompile
)
native_binary="$project_dir/build/native/nativeCompile/ai-engineering"
[[ -x "$native_binary" ]] || die "Build did not produce an executable: $native_binary"
log "Installing in $bin_dir"
mkdir -p -- "$bin_dir"
bin_dir=$(cd -- "$bin_dir" && pwd -P)
# Stage on the destination filesystem. Rename replaces old binaries/symlinks
# without following a previous symlink back into this checkout.
stage_dir=$(mktemp -d "$bin_dir/.aie-install.XXXXXXXX")
install -m 755 "$native_binary" "$stage_dir/ai-engineering"
"$stage_dir/ai-engineering" --help >/dev/null
ln -s ai-engineering "$stage_dir/aie"
mv -f -- "$stage_dir/ai-engineering" "$bin_dir/ai-engineering"
mv -f -- "$stage_dir/aie" "$bin_dir/aie"
log "Installed: $bin_dir/ai-engineering (shortcut: $bin_dir/aie)"
case ":$PATH:" in
*":$bin_dir:"*) ;;
*) printf 'Add this directory to your shell profile and current session:\n export PATH=%q:"$PATH"\n' "$bin_dir" ;;
esac
printf 'Try: %q --help\n' "$bin_dir/aie"
+216
View File
@@ -0,0 +1,216 @@
#!/usr/bin/env python3
"""Installer process tests with disposable homes and offline toolchain fixtures.
Run: python3 scripts/test-install-native.py
These test installation behavior, not native compilation itself.
"""
import os
from pathlib import Path
import shutil
import subprocess
import tempfile
import unittest
INSTALLER = Path(__file__).resolve().with_name("install-native.sh")
class NativeInstallerTest(unittest.TestCase):
def setUp(self):
self.temp = tempfile.TemporaryDirectory(prefix="aie installer ")
self.addCleanup(self.temp.cleanup)
self.root = Path(self.temp.name).resolve()
self.repo = self.root / "source checkout"
self.home = self.root / "user home"
self.tools = self.root / "tools"
self.jdk = self.root / "graalvm 25"
self.home.mkdir()
self.tools.mkdir()
(self.repo / "scripts").mkdir(parents=True)
shutil.copy2(INSTALLER, self.repo / "scripts/install-native.sh")
(self.repo / ".sdkmanrc").write_text("java=25-test-graalce\n")
self.env = {key: value for key, value in os.environ.items()
if not key.startswith(("JAVA", "GRAAL", "SDKMAN", "BASH_ENV"))}
self.env.update(HOME=str(self.home), SDKMAN_DIR=str(self.home / ".sdkman"),
GRAALVM_HOME=str(self.jdk), PATH=f"{self.tools}:/usr/bin:/bin",
FIXTURE_OS="Linux", FIXTURE_ARCH="x86_64",
FIXTURE_LOG=str(self.root / "calls"), FIXTURE_JDK=str(self.jdk))
self.executable(self.tools / "uname", '[[ "$1" == -s ]] && echo "$FIXTURE_OS" || echo "$FIXTURE_ARCH"')
self.executable(self.tools / "gcc", 'exit "${FIXTURE_COMPILER_EXIT:-0}"')
self.executable(self.tools / "clang", 'exit "${FIXTURE_COMPILER_EXIT:-0}"')
self.executable(self.tools / "xcode-select", 'exit "${FIXTURE_XCODE_EXIT:-0}"')
self.executable(self.jdk / "bin/java", 'echo \'openjdk version "25.0.2"\' >&2')
self.executable(self.jdk / "bin/native-image", 'echo "native-image 25.0.2 GraalVM CE"')
self.executable(self.repo / "gradlew", '''
printf '%s\n' "$PWD" "$JAVA_HOME" "$GRAALVM_HOME" "$@" >> "$FIXTURE_LOG"
[[ "$JAVA_HOME" == "$GRAALVM_HOME" ]] || exit 91
[[ "${FIXTURE_BUILD_EXIT:-0}" == 0 ]] || exit "$FIXTURE_BUILD_EXIT"
[[ "${FIXTURE_MISSING_BINARY:-0}" == 0 ]] || exit 0
mkdir -p build/native/nativeCompile
cat > build/native/nativeCompile/ai-engineering <<'EOF'
#!/bin/bash
echo "fixture CLI"
exit "${FIXTURE_BINARY_EXIT:-0}"
EOF
chmod +x build/native/nativeCompile/ai-engineering
''')
def executable(self, path, body):
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text("#!/bin/bash\nset -e\n" + body + "\n")
path.chmod(0o755)
def run_installer(self, *args, success=True):
result = subprocess.run(["/bin/bash", str(self.repo / "scripts/install-native.sh"), *args],
cwd=self.root, env=self.env, text=True,
stdout=subprocess.PIPE, stderr=subprocess.STDOUT, timeout=20)
if success:
self.assertEqual(result.returncode, 0, result.stdout)
else:
self.assertNotEqual(result.returncode, 0, result.stdout)
return result.stdout
def old_installation(self):
dest = self.home / ".local/bin"
self.executable(dest / "ai-engineering", 'echo "old CLI"')
(dest / "aie").symlink_to("ai-engineering")
return dest
def assert_old_installation(self, dest):
self.assertIn("old CLI", (dest / "ai-engineering").read_text())
self.assertEqual(os.readlink(dest / "aie"), "ai-engineering")
self.assertEqual(list(dest.glob(".aie-install.*")), [])
def test_default_install_is_independent_and_can_be_updated(self):
output = self.run_installer()
dest = self.home / ".local/bin"
self.assertFalse((dest / "ai-engineering").is_symlink())
self.assertEqual(os.readlink(dest / "aie"), "ai-engineering")
self.assertEqual((dest / "ai-engineering").stat().st_mode & 0o777, 0o755)
self.assertIn('export PATH=', output)
self.run_installer()
shutil.rmtree(self.repo)
result = subprocess.run([str(dest / "aie"), "--help"], capture_output=True, text=True)
self.assertEqual(result.returncode, 0)
self.assertIn("fixture CLI", result.stdout)
calls = (self.root / "calls").read_text()
self.assertIn(str(self.repo), calls)
self.assertIn(f"-Porg.gradle.java.installations.paths={self.jdk}", calls)
def test_macos_arm_with_relative_destination(self):
self.env.update(FIXTURE_OS="Darwin", FIXTURE_ARCH="arm64")
self.run_installer("--bin-dir", "custom bin")
self.assertTrue((self.root / "custom bin/aie").is_file())
def test_linux_arm(self):
self.env["FIXTURE_ARCH"] = "aarch64"
self.run_installer()
def test_replaces_previous_symlinks_without_following_them(self):
dest = self.home / ".local/bin"
dest.mkdir(parents=True)
old = self.root / "old binary"
old.write_text("keep this target")
(dest / "ai-engineering").symlink_to(old)
(dest / "aie").symlink_to(old)
self.run_installer()
self.assertEqual(old.read_text(), "keep this target")
self.assertFalse((dest / "ai-engineering").is_symlink())
self.assertEqual(os.readlink(dest / "aie"), "ai-engineering")
def test_build_failure_preserves_installation(self):
dest = self.old_installation()
self.env["FIXTURE_BUILD_EXIT"] = "42"
self.run_installer(success=False)
self.assert_old_installation(dest)
def test_binary_check_failure_preserves_installation(self):
dest = self.old_installation()
self.env["FIXTURE_BINARY_EXIT"] = "43"
self.run_installer(success=False)
self.assert_old_installation(dest)
def test_missing_build_output_preserves_installation(self):
dest = self.old_installation()
self.env["FIXTURE_MISSING_BINARY"] = "1"
self.assertIn("did not produce", self.run_installer(success=False))
self.assert_old_installation(dest)
def test_invalid_explicit_graalvm_fails_before_build(self):
self.executable(self.jdk / "bin/java", 'echo \'openjdk version "21.0.2"\' >&2')
self.assertIn("GRAALVM_HOME", self.run_installer(success=False))
self.assertFalse((self.root / "calls").exists())
def test_compatible_java_home(self):
del self.env["GRAALVM_HOME"]
self.env["JAVA_HOME"] = str(self.jdk)
self.run_installer()
self.assertFalse((self.home / ".sdkman").exists())
def test_existing_pinned_jdk_ignores_regular_java_home(self):
del self.env["GRAALVM_HOME"]
self.env["JAVA_HOME"] = str(self.root / "regular JDK")
pinned = self.home / ".sdkman/candidates/java/25-test-graalce"
shutil.copytree(self.jdk, pinned)
self.run_installer()
self.assertIn(str(pinned), (self.root / "calls").read_text())
def test_sdkman_bootstrap_and_install(self):
del self.env["GRAALVM_HOME"]
init = self.root / "sdkman-init.sh"
init.write_text('''
echo "${SDKMAN_UNSET_FIXTURE}" >/dev/null
sdk() {
[[ "$1" == install && "$2" == java && "$3" == 25-test-graalce ]] || return 90
read -r answer
[[ "$answer" == n ]] || return 91
mkdir -p "$SDKMAN_DIR/candidates/java"
cp -R "$FIXTURE_JDK" "$SDKMAN_DIR/candidates/java/$3"
}
''')
bootstrap = self.root / "sdkman-bootstrap.sh"
self.executable(bootstrap, '''
mkdir -p "$SDKMAN_DIR/bin"
cp "$FIXTURE_INIT" "$SDKMAN_DIR/bin/sdkman-init.sh"
''')
self.env.update(FIXTURE_INIT=str(init), FIXTURE_BOOTSTRAP=str(bootstrap))
self.executable(self.tools / "curl", '''
printf '%s\n' "$@" >> "$FIXTURE_LOG"
while [[ $# -gt 0 ]]; do
if [[ "$1" == -o ]]; then cp "$FIXTURE_BOOTSTRAP" "$2"; exit; fi
shift
done
exit 92
''')
for dependency in ("zip", "unzip"):
self.executable(self.tools / dependency, "exit 0")
self.run_installer()
self.assertIn("ci=true&rcupdate=false", (self.root / "calls").read_text())
self.assertFalse((self.home / ".bashrc").exists())
self.assertFalse((self.home / ".zshrc").exists())
def test_unsupported_platforms_and_missing_tools(self):
for platform, arch in (("Darwin", "x86_64"), ("Windows_NT", "x86_64")):
with self.subTest(platform=platform):
self.env.update(FIXTURE_OS=platform, FIXTURE_ARCH=arch)
self.run_installer(success=False)
self.assertFalse((self.root / "calls").exists())
self.env.update(FIXTURE_OS="Darwin", FIXTURE_ARCH="arm64", FIXTURE_XCODE_EXIT="1")
self.assertIn("xcode-select --install", self.run_installer(success=False))
self.env.update(FIXTURE_OS="Linux", FIXTURE_COMPILER_EXIT="1")
self.assertIn("zlib1g-dev", self.run_installer(success=False))
def test_directory_collision_fails_before_build(self):
(self.home / ".local/bin/aie").mkdir(parents=True)
self.assertIn("target is a directory", self.run_installer(success=False))
self.assertFalse((self.root / "calls").exists())
def test_help_and_bad_arguments(self):
self.assertIn("Usage:", self.run_installer("--help"))
for args in (("--bin-dir",), ("--bin-dir", ""), ("--unknown",)):
self.run_installer(*args, success=False)
self.assertFalse((self.root / "calls").exists())
if __name__ == "__main__":
unittest.main(verbosity=2)