feat: add local native CLI installer for Linux and macOS
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/AI Engineering/pipeline/head There was a failure building this commit
build / jvm (push) Canceled after 0s
build / native (macos-15, macos-arm64) (push) Canceled after 0s
build / native (ubuntu-24.04, linux-x86_64) (push) Canceled after 0s
build / native (windows-2025, windows-x86_64) (push) Canceled after 0s

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:
Nilton Constantino
2026-11-16 15:32:01 +00:00
parent 8e75bf7516
commit f296d252c6
16 changed files with 764 additions and 1 deletions
+1 -1
View File
@@ -1,3 +1,3 @@
---
schemaVersion: 2
lastWork: "0008"
lastWork: "0009"
@@ -0,0 +1,12 @@
---
schemaVersion: 1
id: "ART-0001"
workId: "WRK-0009"
origin: "Verificações locais nesta sessão"
purpose: "Verificar script instalador, testes de processo, build real macOS ARM64,\
\ instalação temporária e smoke do binário instalado."
path: "artifacts/evidence/ART-0001/payload"
sha256: "367863f40969d194e27c10ee5aa65819bbee873bf28d17dcf5ba53bf0a28fca8"
size: 3304
author: "codex"
createdAt: "2026-11-16T15:21:51.051849Z"
@@ -0,0 +1,51 @@
WRK-0009 — Local native installer verification, 2026-11-16
Changes:
- scripts/install-native.sh: executable Bash 3 compatible installer, Linux x64/ARM64
and macOS Apple Silicon, environment/pinned GraalVM selection and SDKMAN bootstrap,
compiler/header/linker preflight, explicit Gradle JDK, staged executable check,
independent copy plus relative aie link, custom --bin-dir and PATH instructions.
- scripts/test-install-native.py: 14 offline process tests using disposable homes.
- README.md: installation, updating, prerequisites, destinations, architecture limit.
- .github/workflows/build.yml: installer fixtures run in native Linux/macOS jobs.
Commands and observed results:
- bash -n scripts/install-native.sh: exit 0.
- python3 scripts/test-install-native.py: 14 tests passed on final files (12.236s).
Includes Linux x64/ARM64, macOS ARM64, unsupported platforms, compiler failures,
SDKMAN bootstrap, JDK selection, custom paths with spaces, build/binary failures,
preservation of previous installations, symlink replacement, independent copy,
directory conflicts, help and argument validation.
- ./scripts/install-native.sh --bin-dir /tmp/aie-native-install-verification/bin:
real GraalVM CE JDK 25.0.5.0.3 / macOS ARM64; native build successful in 1m23s.
Initial run was interrupted at installation because the script was edited while
Bash was executing it; final unchanged script rerun completed in full (exit 0),
reusing the build (Gradle BUILD SUCCESSFUL in 4s), and installed the binary and aie.
- /tmp/aie-native-install-verification/bin/aie --version:
ai-engineering 0.1.0, exit 0.
- SHA-256 of build/native/nativeCompile/ai-engineering and installed copy matched:
331633bb1fb9176f8b02c65fba62d423701afac0487147e7b60760a9bb2961ba
- SHA-256 of final scripts/install-native.sh:
c64966f6e6a72bbc062d70dbebb9e0f8f0db8fbc1d7e3c479ce3e30ff6a66a25
- git diff --check: exit 0.
- bash scripts/native-smoke.sh /tmp/aie-native-install-verification/bin/ai-engineering:
exit 0. All existing native smoke sections passed using the installed copy:
DF import, simple project, hexadecimal IDs, refinement, local-CLI fixtures,
EPIC coordination, multiple repositories, operational cycle and Plan consolidation.
Exercises processes with no JVM or installed tools in PATH.
Limits:
- Real Linux compilation was not run locally; Linux installation paths exercised
with fixtures and added to existing Linux CI. The real host is macOS ARM64.
- SDKMAN bootstrap tested with controlled offline fixtures, not a live download.
- No install into the user's ~/.local/bin or system package installation was needed
for validation. Gradle cache access required sandbox escalation and was approved.
- Build emitted existing deprecation and SLF4J warnings; build configuration was not
changed as part of this installer task.
- macOS Intel remains excluded because the project's pinned GraalVM lacks support;
see existing docs/roadmap.md and CI matrix. JVM usage remains documented.
External primary references consulted for implementation:
https://sdkman.io/install/ (ci=true, rcupdate=false bootstrap options)
https://sdkman.io/usage/ (specific-version install and default-version prompt)
https://www.graalvm.org/jdk25/reference-manual/native-image/ (native prerequisites)
@@ -0,0 +1,12 @@
---
schemaVersion: 1
id: "ART-0002"
workId: "WRK-0009"
origin: "ai-engineering:plans:00fbcf61c363328aed2f700ecfe8c790f6490d33f792681d90200e26c9d1c0fe"
purpose: "Deterministic aggregation of completed Plans and reviewed cancellations;\
\ not semantic verification of prose criteria"
path: "artifacts/evidence/ART-0002/payload"
sha256: "00fbcf61c363328aed2f700ecfe8c790f6490d33f792681d90200e26c9d1c0fe"
size: 283
author: "system:plans"
createdAt: "2026-11-16T15:21:52.892233Z"
@@ -0,0 +1,10 @@
{
"schemaVersion" : 1,
"workId" : "WRK-0009",
"inputHash" : "5a3b4cc114c116728f6244e4abef2216c71c16b043b16384d3acc170a03360e9",
"plans" : [ {
"id" : "PLN-0001",
"revision" : 5,
"sha256" : "81daac57165bed45352448d6255200d49f3ed58cfdb4576eb586c3f19e237e6e"
} ]
}
@@ -0,0 +1,13 @@
---
schemaVersion: 1
id: "DSC-0001"
workId: "WRK-0009"
discussionId: "main"
kind: "NOTE"
author: "codex"
createdAt: "2026-11-16T15:13:08.421993Z"
respondsTo: null
documentVersion: 2
---
Autorização explícita do usuário nesta sessão: "crie um scriupt para instalar gerar o native corretamente e instala-lo no dir local do user (linux/mac os)". Escopo: criar script e documentação, validar com fixtures e build local; a execução do instalador real no HOME não é necessária para criar o script. Usar GraalVM configurado ou versão fixada via SDKMAN; instalar cópia independente e link aie em ~/.local/bin com destino configurável. Pré-requisitos do sistema terão diagnóstico e comandos de instalação, sem sudo automático. Limite existente: GraalVM fixado não oferece macOS Intel, conforme CI/roadmap do projeto.
@@ -0,0 +1,18 @@
---
schemaVersion: 1
id: "PLN-0001"
workId: "WRK-0009"
title: "Implementar e verificar instalador nativo local"
decisions: []
steps: []
status: "OPEN"
author: "codex"
createdAt: "2026-11-16T15:13:08.894885Z"
revision: 1
previousHash: null
updatedAt: "2026-11-16T15:13:08.894885Z"
updatedBy: "codex"
changeReason: "Plan created"
documentVersion: 2
---
@@ -0,0 +1,31 @@
---
schemaVersion: 1
id: "PLN-0001"
workId: "WRK-0009"
title: "Implementar e verificar instalador nativo local"
decisions: []
steps:
- id: "TSK-0001"
title: "Criar instalador, documentação e verificar instalação e falhas"
description: ""
acceptanceCriteria:
- "Fixtures exercitam Linux/macOS, bootstrap do SDKMAN, seleção de GraalVM, cópia\
\ independente, atualização e preservação da instalação em falhas."
- "Build nativo real executado no macOS disponível e resultado verificado, ou limitaç\
ão registrada com evidência."
dependsOn: []
status: "OPEN"
result: ""
evidence: []
updatedAt: "2026-11-16T15:13:10.473788Z"
status: "OPEN"
author: "codex"
createdAt: "2026-11-16T15:13:08.894885Z"
revision: 2
previousHash: "cca3bd8c40339202e0c12af8e00aa73c8a1088e22da7322abcee3be5eb52e946"
updatedAt: "2026-11-16T15:13:10.474157Z"
updatedBy: "codex"
changeReason: "Step added"
documentVersion: 2
---
@@ -0,0 +1,33 @@
---
schemaVersion: 1
id: "PLN-0001"
workId: "WRK-0009"
title: "Implementar e verificar instalador nativo local"
decisions: []
steps:
- id: "TSK-0001"
title: "Criar instalador, documentação e verificar instalação e falhas"
description: ""
acceptanceCriteria:
- "Fixtures exercitam Linux/macOS, bootstrap do SDKMAN, seleção de GraalVM, cópia\
\ independente, atualização e preservação da instalação em falhas."
- "Build nativo real executado no macOS disponível e resultado verificado, ou limitaç\
ão registrada com evidência."
dependsOn: []
status: "ACTIVE"
result: "Solicitação explícita registrada; implementar script local sem instalar\
\ pacotes do sistema."
evidence: []
updatedAt: "2026-11-16T15:13:12.186839Z"
status: "ACTIVE"
author: "codex"
createdAt: "2026-11-16T15:13:08.894885Z"
revision: 3
previousHash: "e9b05b6c2bc7eab86126ae4b14e2476874b9cde4b9730d88b4af5135575fb662"
updatedAt: "2026-11-16T15:13:12.186870Z"
updatedBy: "codex"
changeReason: "Solicitação explícita registrada; implementar script local sem instalar\
\ pacotes do sistema."
documentVersion: 2
---
@@ -0,0 +1,38 @@
---
schemaVersion: 1
id: "PLN-0001"
workId: "WRK-0009"
title: "Implementar e verificar instalador nativo local"
decisions: []
steps:
- id: "TSK-0001"
title: "Criar instalador, documentação e verificar instalação e falhas"
description: ""
acceptanceCriteria:
- "Fixtures exercitam Linux/macOS, bootstrap do SDKMAN, seleção de GraalVM, cópia\
\ independente, atualização e preservação da instalação em falhas."
- "Build nativo real executado no macOS disponível e resultado verificado, ou limitaç\
ão registrada com evidência."
dependsOn: []
status: "COMPLETED"
result: "Instalador executável e documentação entregues; 14 testes de processo,\
\ build nativo macOS ARM64, instalação em /tmp e smoke completo do CLI instalado\
\ passaram. CI Linux/macOS inclui fixtures; limites de validação registrados na\
\ evidência."
evidence:
- "ART-0001"
updatedAt: "2026-11-16T15:21:51.670542Z"
status: "ACTIVE"
author: "codex"
createdAt: "2026-11-16T15:13:08.894885Z"
revision: 4
previousHash: "10a5fc10c3988d8882b0e4776408d51be33f2adfc863179a796efb2ec82e869b"
updatedAt: "2026-11-16T15:21:51.670570Z"
updatedBy: "codex"
changeReason: "Instalador executável e documentação entregues; 14 testes de processo,\
\ build nativo macOS ARM64, instalação em /tmp e smoke completo do CLI instalado\
\ passaram. CI Linux/macOS inclui fixtures; limites de validação registrados na\
\ evidência."
documentVersion: 2
---
@@ -0,0 +1,35 @@
---
schemaVersion: 1
id: "PLN-0001"
workId: "WRK-0009"
title: "Implementar e verificar instalador nativo local"
decisions: []
steps:
- id: "TSK-0001"
title: "Criar instalador, documentação e verificar instalação e falhas"
description: ""
acceptanceCriteria:
- "Fixtures exercitam Linux/macOS, bootstrap do SDKMAN, seleção de GraalVM, cópia\
\ independente, atualização e preservação da instalação em falhas."
- "Build nativo real executado no macOS disponível e resultado verificado, ou limitaç\
ão registrada com evidência."
dependsOn: []
status: "COMPLETED"
result: "Instalador executável e documentação entregues; 14 testes de processo,\
\ build nativo macOS ARM64, instalação em /tmp e smoke completo do CLI instalado\
\ passaram. CI Linux/macOS inclui fixtures; limites de validação registrados na\
\ evidência."
evidence:
- "ART-0001"
updatedAt: "2026-11-16T15:21:51.670542Z"
status: "COMPLETED"
author: "codex"
createdAt: "2026-11-16T15:13:08.894885Z"
revision: 5
previousHash: "90270df340c46918193f7b18cde24b37efbaaacd750db5089c7c0ff863e4f9bc"
updatedAt: "2026-11-16T15:21:52.215397Z"
updatedBy: "system:plans"
changeReason: "All required steps completed; reviewed cancellations retained"
documentVersion: 2
---
@@ -0,0 +1,74 @@
---
schemaVersion: 1
id: "WRK-0009"
title: "Instalar CLI nativo no diretório local do usuário"
description: ""
goal: "Fornecer um script Linux/macOS que prepare GraalVM, compile o executável nativo\
\ e instale ai-engineering e aie no diretório local do usuário."
motivation: ""
constraints:
- "Não executar instalações de pacotes do sistema nem alterar perfis de shell automaticamente."
acceptanceCriteria:
- "Script executável funciona fora da raiz do projeto, usa GraalVM JDK 25 e instala\
\ em ~/.local/bin ou diretório configurável."
- "Pré-requisitos e plataformas incompatíveis geram orientação clara; falhas de build\
\ não substituem a instalação existente."
- "Documentação e verificações cobrem instalação, atualização, bootstrap e caminhos\
\ com espaços."
status: "COMPLETED"
createdAt: "2026-11-16T15:12:29.813529Z"
updatedAt: "2026-11-16T15:21:52.918649Z"
author: "codex"
repositories: []
discussions:
- "DSC-0001"
decisions: []
artifacts:
- "ART-0001"
- "ART-0002"
plans:
- "PLN-0001"
completions:
- at: "2026-11-16T15:21:52.918649Z"
by: "system:plans"
summary: "All required Plans completed; requester=codex"
humanApproved: false
scopeHash: "a4ae8e2605ab3326448de1b72051d79e0f20115031c073bdb425fc5b8dda8383"
criteria:
- criterion: 1
text: "Script executável funciona fora da raiz do projeto, usa GraalVM JDK 25\
\ e instala em ~/.local/bin ou diretório configurável."
evidence:
- "ART-0002"
- criterion: 2
text: "Pré-requisitos e plataformas incompatíveis geram orientação clara; falhas\
\ de build não substituem a instalação existente."
evidence:
- "ART-0002"
- criterion: 3
text: "Documentação e verificações cobrem instalação, atualização, bootstrap e\
\ caminhos com espaços."
evidence:
- "ART-0002"
integrations: []
noIntegrationReason: "Canonical changes and execution results are recorded in the\
\ Plan step evidence"
origin: "SYSTEM_PLANS"
delegation: null
aggregation:
receipt: "ART-0002"
inputHash: "5a3b4cc114c116728f6244e4abef2216c71c16b043b16384d3acc170a03360e9"
requester: "codex"
requestId: "f9e753dd-fbfd-4b8d-864a-5818a6a37757"
events:
- action: "COMPLETE"
by: "system:plans"
reason: "All required Plans completed; requester=codex"
at: "2026-11-16T15:21:52.918649Z"
archived: false
topics: []
surveys: []
dispositions: []
agentRuns: []
epic: false
---
+6
View File
@@ -44,6 +44,12 @@ jobs:
distribution: graalvm-community
github-token: ${{ secrets.GITHUB_TOKEN }}
- uses: gradle/actions/setup-gradle@v4
- name: Verify local native installer
if: runner.os != 'Windows'
shell: bash
run: |
bash -n scripts/install-native.sh
python3 scripts/test-install-native.py
- name: Build native archive
shell: bash
run: ./gradlew nativeDistZip -PtargetPlatform=${{ matrix.platform }} --console=plain
+36
View File
@@ -55,6 +55,42 @@ The JAR requires Java 25 at runtime. On Windows, use `gradlew.bat` in place of
### Build a native executable
On Linux (x64/ARM64) and macOS (Apple Silicon), build and install for your user:
```sh
./scripts/install-native.sh
```
The script uses a compatible `GRAALVM_HOME` or `JAVA_HOME`, otherwise installs the
GraalVM version pinned in `.sdkmanrc` through [SDKMAN](https://sdkman.io/install/),
installing SDKMAN too when needed. It builds with the Gradle Wrapper, checks the
executable, copies it to `~/.local/bin/ai-engineering`, and creates the `aie`
shortcut. Run the same command again to update. The installed copy works independently
of this checkout. A failed build or executable check leaves the previous installation
in place. Downloads require internet access.
If `~/.local/bin` is not in your `PATH`, add this to your shell profile and current
session (the script prints the appropriate command for your destination):
```sh
export PATH="$HOME/.local/bin:$PATH"
aie --help
```
Use `./scripts/install-native.sh --bin-dir /path/to/bin` to select another destination.
The script can be invoked from any directory and does not modify shell profiles or
install system packages. It requires `curl`, `zip`, and `unzip` when installing GraalVM
through SDKMAN. Install [native build prerequisites](https://www.graalvm.org/jdk25/reference-manual/native-image/)
before running it:
- macOS: `xcode-select --install` (Apple Command Line Tools).
- Debian/Ubuntu: `sudo apt-get install build-essential zlib1g-dev`.
- Fedora/RHEL: `sudo dnf install gcc gcc-c++ glibc-devel zlib-devel libstdc++-static`.
The pinned GraalVM does not support macOS Intel; use the JVM instructions above.
For a manual native build:
The native executable runs without a JVM. Building it requires **GraalVM for
JDK 25**, Native Image, and a C/C++ toolchain for the target platform. Set both
`JAVA_HOME` and `GRAALVM_HOME` to your GraalVM installation.
+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)