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
---