Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

fix(minikube): close bootstrap review gaps

Alfredo Lopez2a8c1cf49fe4
diff --git a/.github/workflows/ci-public.yml b/.github/workflows/ci-public.yml
index e67cce929..753781fe9 100644
--- a/.github/workflows/ci-public.yml
+++ b/.github/workflows/ci-public.yml
@@ -100,8 +100,7 @@ jobs:
- name: Verify Electron runtime
if: matrix.service == 'desktop-app'
working-directory: desktop-app
- run: |
- node -e "const p=require('electron'); if(typeof p !== 'string') process.exit(1); console.log(p)"
+ run: npm run verify:electron
- name: Build
working-directory: ${{ matrix.service }}
diff --git a/AGENTS.md b/AGENTS.md
index 5bbdfbb64..0004a84f1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -97,7 +97,7 @@ checks succeed from `desktop-app`:
```bash
node --version # must report v24.x
-node -e "const p=require('electron'); if(typeof p !== 'string') process.exit(1); console.log(p)"
+npm run verify:electron
```
If it fails with `Electron failed to install correctly`, the dependency install
diff --git a/CLAUDE.md b/CLAUDE.md
index 153aa3702..0214cfd47 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -36,8 +36,8 @@ without its downloaded runtime while `npm ci` still exits successfully. The
pinned Electron package is explicitly approved in `desktop-app/package.json`.
Desktop validation must use Node 24 (Node 26 is not a supported validation
runtime), run `npm ci` without `--ignore-scripts`, and verify
-`require('electron')` resolves to an executable before any test/build result is
-counted. If the check reports `Electron failed to install correctly`, switch to
+`npm run verify:electron` confirms that `require('electron')` resolves to an
+executable before any test/build result is counted. If the check reports `Electron failed to install correctly`, switch to
Node 24, repair the generated dependency directory, and rerun the install;
never bypass the postinstall with `ELECTRON_SKIP_BINARY_DOWNLOAD`, use an
unverified override, or treat the resulting test failure as a product
diff --git a/desktop-app/package.json b/desktop-app/package.json
index a73fe6176..13435a381 100644
--- a/desktop-app/package.json
+++ b/desktop-app/package.json
@@ -10,6 +10,7 @@
"build": "npm run build:main && npm run build:renderer",
"build:main": "tsc -p tsconfig.json",
"build:renderer": "vite build --config ui/vite.config.ts",
+ "verify:electron": "node ./scripts/verify-electron-runtime.mjs",
"icons:generate": "node ./scripts/generate-adaptive-icons.mjs",
"test": "vitest run",
"test:e2e": "vitest run --config test/e2e/vitest.config.ts",
diff --git a/desktop-app/scripts/verify-electron-runtime.mjs b/desktop-app/scripts/verify-electron-runtime.mjs
new file mode 100644
index 000000000..8e51fd565
--- /dev/null
+++ b/desktop-app/scripts/verify-electron-runtime.mjs
@@ -0,0 +1,16 @@
+import electronPath from 'electron'
+import fs from 'node:fs'
+
+const runtimePath = typeof electronPath === 'string' ? electronPath : ''
+if (!runtimePath) {
+ throw new Error('Electron runtime path is unavailable; run npm ci with lifecycle scripts enabled')
+}
+
+const stat = fs.statSync(runtimePath)
+if (!stat.isFile()) {
+ throw new Error(`Electron runtime is not a file: ${runtimePath}`)
+}
+
+const accessMode = process.platform === 'win32' ? fs.constants.F_OK : fs.constants.X_OK
+fs.accessSync(runtimePath, accessMode)
+console.log(`Electron runtime executable: ${runtimePath}`)
diff --git a/docs/get-started/minikube.md b/docs/get-started/minikube.md
index 01d14e82c..2e90b86db 100644
--- a/docs/get-started/minikube.md
+++ b/docs/get-started/minikube.md
@@ -10,7 +10,7 @@ single LLM key you set in `.env`.
## Prerequisites
Docker Desktop with **≥10 GB RAM / 6 CPUs** · `minikube` v1.30+ · `kubectl` ·
-`python3` · Node.js 24+ · `git` · `make` · `ruby` (renders the control-api DB
+`python3` · Node.js 24.x · `git` · `make` · `ruby` (renders the control-api DB
migration overlay; ships with macOS, `apt-get install ruby` on Debian/Ubuntu).
Run `make prereqs` (alias `make doctor`) to check every one of these at once —
diff --git a/scripts/check-prereqs.sh b/scripts/check-prereqs.sh
index ab29dd363..adff1b4fd 100755
--- a/scripts/check-prereqs.sh
+++ b/scripts/check-prereqs.sh
@@ -91,18 +91,19 @@ else
MISSING=$((MISSING + 1))
fi
-# ── Node.js (>= 24) ────────────────────────────────────────────────────
+# ── Node.js 24.x (Desktop/Electron validation contract) ───────────────
if command -v node >/dev/null 2>&1; then
NODE_VER="$(node --version | sed 's/^v//')"
- if version_ge "$NODE_VER" "24.0.0"; then
+ NODE_MAJOR="${NODE_VER%%.*}"
+ if [ "$NODE_MAJOR" = "24" ]; then
ok "node v${NODE_VER}"
else
- err "node v${NODE_VER} (need >= 24)"
+ err "node v${NODE_VER} (need 24.x for Desktop/Electron validation)"
hint "brew install node@24" "curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - && sudo apt-get install -y nodejs"
MISSING=$((MISSING + 1))
fi
else
- err "node not found (need >= 24)"
+ err "node not found (need 24.x for Desktop/Electron validation)"
hint "brew install node@24" "curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - && sudo apt-get install -y nodejs"
MISSING=$((MISSING + 1))
fi
diff --git a/scripts/e2e/load-dotenv.sh b/scripts/e2e/load-dotenv.sh
index 35f3694bf..f563f47fe 100755
--- a/scripts/e2e/load-dotenv.sh
+++ b/scripts/e2e/load-dotenv.sh
@@ -67,11 +67,19 @@ dotenv_canonical_root() {
# worktree-local file would reintroduce per-lane credential drift.
return 0
fi
- [[ -f "${repo_root}/.env" ]] && printf '%s\n' "${repo_root}/.env"
+ if [[ -f "${repo_root}/.env" ]]; then
+ printf '%s\n' "${repo_root}/.env"
+ fi
+ return 0
}
dotenv_load_canonical_root() {
local repo_root="${1:?repository root is required}" env_file
env_file="$(dotenv_canonical_root "${repo_root}")"
- [[ -n "${env_file}" ]] && dotenv_load_file "${env_file}"
+ if [[ -n "${env_file}" ]]; then
+ dotenv_load_file "${env_file}"
+ fi
+ # A canonical .env is optional. Callers run with set -e and should continue
+ # with their documented defaults when the checkout has no local credentials.
+ return 0
}
diff --git a/scripts/e2e/minimal-bootstrap-contract.sh b/scripts/e2e/minimal-bootstrap-contract.sh
index ef8518563..9f0f67306 100755
--- a/scripts/e2e/minimal-bootstrap-contract.sh
+++ b/scripts/e2e/minimal-bootstrap-contract.sh
@@ -6,9 +6,38 @@ clerum_canonical_email() {
printf '%s' "$1" | LC_ALL=C tr '[:upper:]' '[:lower:]'
}
+clerum_minimal_desktop_email() {
+ local admin_email="${1:?admin email is required}"
+ local requested_email="${2-}"
+ local requested_present="${3:-false}"
+ admin_email="$(clerum_canonical_email "$admin_email")"
+ if [ "$requested_present" != "true" ]; then
+ printf '%s' "$admin_email"
+ else
+ clerum_canonical_email "$requested_email"
+ fi
+}
+
clerum_initial_setup_link_is_active() {
[ "${1:-}" = "active" ] &&
[ "${2:-}" = "initial_setup" ] &&
[ -n "${3:-}" ] &&
[ "${4:-}" = "true" ]
}
+
+clerum_initial_setup_link_matches() {
+ [ "${1:-}" = "active" ] &&
+ [ "${2:-}" = "initial_setup" ] &&
+ [ -n "${3:-}" ] &&
+ [ -n "${4:-}" ] &&
+ [ -n "${5:-}" ] &&
+ [ "${4}" = "${5}" ]
+}
+
+clerum_minimal_setup_outcome() {
+ case "${1:-}" in
+ 2[0-9][0-9]) printf '%s' setup_succeeded ;;
+ 409) printf '%s' setup_already_consumed ;;
+ *) printf '%s' setup_failed ;;
+ esac
+}
diff --git a/scripts/e2e/seed-e2e-data.sh b/scripts/e2e/seed-e2e-data.sh
index 2be889589..7c58eb124 100755
--- a/scripts/e2e/seed-e2e-data.sh
+++ b/scripts/e2e/seed-e2e-data.sh
@@ -111,7 +111,11 @@ if [ -z "${ADMIN_EMAIL:-}" ]; then
fi
if [ "$SEED_PROFILE" = "minimal" ]; then
ADMIN_EMAIL="$(clerum_canonical_email "$ADMIN_EMAIL")"
- DEV_EMAIL="$(clerum_canonical_email "$DEV_EMAIL")"
+ if [ -n "${E2E_DEV_LOGIN_EMAIL+x}" ]; then
+ DEV_EMAIL="$(clerum_minimal_desktop_email "$ADMIN_EMAIL" "$DEV_EMAIL" true)"
+ else
+ DEV_EMAIL="$(clerum_minimal_desktop_email "$ADMIN_EMAIL" "" false)"
+ fi
if [ "$DEV_EMAIL" != "$ADMIN_EMAIL" ]; then
printf '%s\n' " ERROR — SEED_PROFILE=minimal requires the Desktop identity email (${DEV_EMAIL}) to equal the bootstrap admin email (${ADMIN_EMAIL}); refusing to create an unlinked ordinary member" >&2
exit 1
@@ -533,7 +537,7 @@ verify_minimal_operator_bootstrap() {
'.admins[] | select(.username == $username and ((.email // "") | ascii_downcase) == $email) | .gfsOperatorLink.desktopUserId // empty')"
link_admin_id="$(echo "$ADMIN_GET_BODY" | jq -r --arg username "$ADMIN_USERNAME" --arg email "$ADMIN_EMAIL" \
'.admins[] | select(.username == $username and ((.email // "") | ascii_downcase) == $email) | .gfsOperatorLink.controlAdminId // empty')"
- if ! clerum_initial_setup_link_is_active "$status" "$source" "$desktop_user_id" "$([ "$link_admin_id" = "$admin_id" ] && printf true || printf false)"; then
+ if ! clerum_initial_setup_link_matches "$status" "$source" "$desktop_user_id" "$link_admin_id" "$admin_id"; then
die "Minimal bootstrap is incomplete: expected one active initial_setup Desktop link for '$ADMIN_EMAIL' (status=$status source=$source desktopUserId=${desktop_user_id:-missing} controlAdminId=${link_admin_id:-missing}); refusing ordinary-user fallback"
fi
ok "Initial admin '$ADMIN_USERNAME' has active initial_setup Desktop operator link (desktopUserId=${desktop_user_id:0:8}…)"
@@ -580,10 +584,11 @@ login_first_legacy() {
if [ "$SEED_PROFILE" = "minimal" ]; then
log "Minimal self-hosted bootstrap: attempting /admin/auth/setup before any admin login"
perform_initial_setup
- if [[ "$SETUP_CODE" =~ ^2 ]]; then
+ setup_outcome="$(clerum_minimal_setup_outcome "$SETUP_CODE")"
+ if [ "$setup_outcome" = "setup_succeeded" ]; then
capture_admin_session_cookie || die "Bootstrap did not return an admin session cookie"
ok "Bootstrapped initial admin '$ADMIN_USERNAME' with Desktop workspace"
- elif [ "$SETUP_CODE" = "409" ]; then
+ elif [ "$setup_outcome" = "setup_already_consumed" ]; then
log "Initial setup already consumed; validating the existing governed link after login"
login_admin_only
else
diff --git a/scripts/minikube/t2-common.sh b/scripts/minikube/t2-common.sh
index ab21e64cf..ecf791eae 100755
--- a/scripts/minikube/t2-common.sh
+++ b/scripts/minikube/t2-common.sh
@@ -331,7 +331,7 @@ if source == "local":
import re
if not isinstance(images, dict) or not images:
raise SystemExit("local-images")
- digest = re.compile(r"^sha256:[0-9a-fA-F]{32,64}$")
+ digest = re.compile(r"^sha256:[0-9a-fA-F]{64}$")
if any(not isinstance(name, str) or not name or not isinstance(value, str) or not digest.fullmatch(value) for name, value in images.items()):
raise SystemExit("local-digests")
print(source + "\t" + tag)
diff --git a/scripts/tests/test-minikube-full-setup.sh b/scripts/tests/test-minikube-full-setup.sh
index 418f1e5c4..1ded75110 100755
--- a/scripts/tests/test-minikube-full-setup.sh
+++ b/scripts/tests/test-minikube-full-setup.sh
@@ -525,7 +525,7 @@ assert_minimal_seed_is_setup_first_and_link_fail_closed() {
if printf '%s\n' "$minimal_block" | grep -Fq 'perform_initial_setup' && \
printf '%s\n' "$minimal_block" | grep -Fq 'login_admin_only' && \
printf '%s\n' "$minimal_block" | grep -Fq 'verify_minimal_operator_bootstrap' && \
- grep -Fq 'clerum_initial_setup_link_is_active' "$seed" && \
+ grep -Fq 'clerum_initial_setup_link_matches' "$seed" && \
grep -Fq 'refusing ordinary-user fallback' "$seed"; then
pass "minimal seed consumes setup before login and fails closed without an active initial_setup link"
else
@@ -544,7 +544,15 @@ assert_minimal_bootstrap_contract_runs_on_system_bash() {
set -e
source "$1"
[ "$(clerum_canonical_email "[email protected]")" = "[email protected]" ]
+ [ "$(clerum_minimal_desktop_email "[email protected]" "" false)" = "[email protected]" ]
+ [ "$(clerum_minimal_desktop_email "[email protected]" "[email protected]" true)" = "[email protected]" ]
clerum_initial_setup_link_is_active active initial_setup desktop-id true
+ clerum_initial_setup_link_matches active initial_setup desktop-id admin-id admin-id
+ ! clerum_initial_setup_link_matches active initial_setup desktop-id "" admin-id
+ ! clerum_initial_setup_link_matches active initial_setup "" admin-id admin-id
+ [ "$(clerum_minimal_setup_outcome 201)" = setup_succeeded ]
+ [ "$(clerum_minimal_setup_outcome 409)" = setup_already_consumed ]
+ [ "$(clerum_minimal_setup_outcome 401)" = setup_failed ]
! clerum_initial_setup_link_is_active revoked initial_setup desktop-id true
! clerum_initial_setup_link_is_active active revoked desktop-id true
! clerum_initial_setup_link_is_active active initial_setup "" true
diff --git a/scripts/tests/test-minikube-t2-scenarios.sh b/scripts/tests/test-minikube-t2-scenarios.sh
index 304c05d08..647d26fe7 100755
--- a/scripts/tests/test-minikube-t2-scenarios.sh
+++ b/scripts/tests/test-minikube-t2-scenarios.sh
@@ -159,6 +159,12 @@ expect_code IMAGE_MANIFEST_MISMATCH not-built-local not-built-local \
env "${repo_env[@]}" T2_IMAGE_MANIFEST="$not_built_local_manifest" T2_IMAGE_SOURCE=local T2_IMAGE_TAG= \
bash -c 'source "$1"; T2_IMAGE_SOURCE=local; T2_IMAGE_TAG=""; t2_image_check' bash "$COMMON"
+short_local_manifest="$tmp/short-local-image-manifest.json"
+printf '{"imageSource":"local","imageTag":"","images":{"clerum/control-api:test":"sha256:0123456789abcdef0123456789abcdef"}}\n' >"$short_local_manifest"
+expect_code IMAGE_MANIFEST_MISMATCH short-local short-local \
+ env "${repo_env[@]}" T2_IMAGE_MANIFEST="$short_local_manifest" T2_IMAGE_SOURCE=local T2_IMAGE_TAG= \
+ bash -c 'source "$1"; T2_IMAGE_SOURCE=local; T2_IMAGE_TAG=""; t2_image_check' bash "$COMMON"
+
ghcr_manifest="$tmp/ghcr-image-manifest.json"
printf '{"imageSource":"ghcr","imageTag":""}\n' >"$ghcr_manifest"
expect_code IMAGE_MANIFEST_MISMATCH tagless-ghcr tagless-ghcr \
diff --git a/scripts/tests/test-plugin-workload-sdk-auth-bootstrap.sh b/scripts/tests/test-plugin-workload-sdk-auth-bootstrap.sh
index cdf4486f9..2c18dd706 100755
--- a/scripts/tests/test-plugin-workload-sdk-auth-bootstrap.sh
+++ b/scripts/tests/test-plugin-workload-sdk-auth-bootstrap.sh
@@ -237,6 +237,16 @@ assert_admin_resolution_contract() {
fi
}
+assert_missing_canonical_dotenv_is_optional() {
+ local no_env_repo="$TMP_ROOT/no-canonical-env"
+ mkdir -p "$no_env_repo"
+ if (set -e; dotenv_load_canonical_root "$no_env_repo"); then
+ pass 'missing canonical .env leaves documented defaults available'
+ else
+ fail 'missing canonical .env aborts the bootstrap under set -e'
+ fi
+}
+
assert_nul_credential_transport() {
local result
result="$(
@@ -267,6 +277,7 @@ assert_nul_credential_transport() {
}
assert_admin_resolution_contract
+assert_missing_canonical_dotenv_is_optional
assert_nul_credential_transport
if grep -Fq 'e2e_write_nul_credentials "$admin_username" "$admin_password"' "$SCRIPT"; then