diff --git a/docs/v6_5_deep_manual_pack/HyperTwist/DEVELOPMENT.md b/docs/v6_5_deep_manual_pack/HyperTwist/DEVELOPMENT.md index 2b1e23d..72bd4fa 100644 --- a/docs/v6_5_deep_manual_pack/HyperTwist/DEVELOPMENT.md +++ b/docs/v6_5_deep_manual_pack/HyperTwist/DEVELOPMENT.md @@ -49,6 +49,12 @@ Use them with this posture: - the retained `mirrors/GitNexus` working reference already includes the newer stack-overflow prevention and cycle-hardening work recorded in its `CHANGELOG.md` +- `HYPERTWIST_GITNEXUS_SKIP_LOCAL_CLI=1` can force the GitNexus wrappers to + skip the retained local CLI and go straight to the `npx` fallback on hosts + where the local mirror runtime is known to be unusable +- `HYPERTWIST_GITNEXUS_DEBUG_LOCAL=1` keeps local GitNexus stderr visible so + retained-runtime problems can be diagnosed instead of being silently + suppressed during the normal fallback path - `scripts/run-hypertwist-sentrux-source-only.sh` now prefers a HyperTwist owned entry path first: `HYPERTWIST_SENTRUX_BINARY`, repo-local `./sentrux` or `./sentrux.exe`, then repo-local `tools/sentrux/bin/`, then a bootstrap @@ -259,6 +265,34 @@ Latest later higher-dimensional proof refresh still on `2026-06-24`: - `generatedAtUtc: 2026-06-24T12:53:32.7234772Z` - `result: passed` +Latest GitNexus wrapper hardening follow-up still on `2026-06-24`: + +- the retained local GitNexus CLI failure on this Linux host is now identified + explicitly instead of being hidden behind a vague fallback message: + `ERR_DLOPEN_FAILED` from `@ladybugdb/core` with an `invalid ELF header` in + the retained mirror runtime +- `scripts/run-hypertwist-gitnexus-analyze.sh` and + `scripts/run-hypertwist-gitnexus-status.sh` now preflight the retained + runtime first, so the wrapper can explain that native-module mismatch before + it falls back to `npx -y gitnexus@latest` +- the same wrappers now also support: + - `HYPERTWIST_GITNEXUS_SKIP_LOCAL_CLI=1` for a deliberate direct-fallback + path + - `HYPERTWIST_GITNEXUS_DEBUG_LOCAL=1` for unsuppressed retained-runtime + diagnostics +- the current bounded source-only mirror then re-indexed successfully at: + - `16,245` nodes + - `38,118` edges + - `668` clusters + - `300` flows +- `scripts/run-hypertwist-gitnexus-status.sh` then reported: + - `Indexed commit: f1fd833` + - `Current commit: f1fd833` + - `Status: up-to-date` +- `scripts/run-hypertwist-sentrux-source-only.sh` stayed green afterward at: + - `Quality: 6139` + - all `7` rules passing + Latest same-day browser/distribution continuity follow-up still on `2026-06-24`: - auth-entry, protected-route loading, dashboard auth health, and release-authority fallback states now share a more deliberate operator-facing recovery shape instead of scattering single-line warnings across public and protected surfaces diff --git a/scripts/lib-hypertwist-gitnexus.sh b/scripts/lib-hypertwist-gitnexus.sh new file mode 100644 index 0000000..f6a9e9c --- /dev/null +++ b/scripts/lib-hypertwist-gitnexus.sh @@ -0,0 +1,35 @@ +#!/usr/bin/env bash + +hypertwist_gitnexus_probe_local_runtime() { + local repo_root="$1" + local local_gitnexus_dir="$repo_root/mirrors/GitNexus/gitnexus" + local local_gitnexus_cli="$local_gitnexus_dir/dist/cli/index.js" + + if [[ ! -f "$local_gitnexus_cli" ]]; then + return 1 + fi + + if [[ "${HYPERTWIST_GITNEXUS_SKIP_LOCAL_CLI:-0}" == "1" ]]; then + echo "Skipping local retained GitNexus CLI because HYPERTWIST_GITNEXUS_SKIP_LOCAL_CLI=1." >&2 + return 1 + fi + + local probe_output="" + local probe_exit=0 + + set +e + probe_output="$( + cd "$local_gitnexus_dir" && + node --input-type=module -e 'try { await import("@ladybugdb/core"); } catch (error) { const code = error?.code ? `${error.code}: ` : ""; const message = error?.message || String(error); console.error(`${code}${message}`); process.exit(1); }' 2>&1 + )" + probe_exit=$? + set -e + + if [[ "$probe_exit" -eq 0 ]]; then + return 0 + fi + + probe_output="${probe_output//$'\n'/ }" + echo "Local retained GitNexus runtime is not usable on this host (${probe_output}). Falling back to npx gitnexus@latest." >&2 + return 1 +} diff --git a/scripts/run-hypertwist-gitnexus-analyze.sh b/scripts/run-hypertwist-gitnexus-analyze.sh index 6b148fc..fd80eda 100644 --- a/scripts/run-hypertwist-gitnexus-analyze.sh +++ b/scripts/run-hypertwist-gitnexus-analyze.sh @@ -2,6 +2,7 @@ set -euo pipefail repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +source "$repo_root/scripts/lib-hypertwist-gitnexus.sh" local_gitnexus_cli="$repo_root/mirrors/GitNexus/gitnexus/dist/cli/index.js" analysis_root="$repo_root/.gitnexus-source-only-root" max_size_kb="${HYPERTWIST_GITNEXUS_MAX_FILE_SIZE_KB:-256}" @@ -73,7 +74,7 @@ run_analysis_attempt() { local analysis_exit_code=0 set +e - if [[ "$cli_kind" == "local" ]]; then + if [[ "$cli_kind" == "local" && "${HYPERTWIST_GITNEXUS_DEBUG_LOCAL:-0}" != "1" ]]; then run_analysis_command command 2>/dev/null else run_analysis_command command @@ -127,12 +128,17 @@ npx_cli_command=( local_cli_command+=("$@") npx_cli_command+=("$@") -if [[ -f "$local_gitnexus_cli" ]]; then +local_cli_available=0 +if hypertwist_gitnexus_probe_local_runtime "$repo_root"; then + local_cli_available=1 +fi + +if [[ "$local_cli_available" -eq 1 ]]; then if run_analysis_attempt "local" "${local_cli_command[@]}"; then exit 0 fi - echo "Local retained GitNexus CLI did not complete cleanly on this host. Falling back to npx gitnexus@latest." >&2 + echo "Local retained GitNexus CLI passed the runtime probe but did not complete cleanly. Falling back to npx gitnexus@latest." >&2 fi run_analysis_attempt "npx" "${npx_cli_command[@]}" diff --git a/scripts/run-hypertwist-gitnexus-status.sh b/scripts/run-hypertwist-gitnexus-status.sh index 44c280f..dc1774c 100644 --- a/scripts/run-hypertwist-gitnexus-status.sh +++ b/scripts/run-hypertwist-gitnexus-status.sh @@ -2,6 +2,7 @@ set -euo pipefail repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +source "$repo_root/scripts/lib-hypertwist-gitnexus.sh" local_gitnexus_cli="$repo_root/mirrors/GitNexus/gitnexus/dist/cli/index.js" analysis_root="$repo_root/.gitnexus-source-only-root" @@ -12,12 +13,21 @@ fi cd "$analysis_root" -if [[ -f "$local_gitnexus_cli" ]]; then - if node "$local_gitnexus_cli" status "$@" 2>/dev/null; then +local_cli_available=0 +if hypertwist_gitnexus_probe_local_runtime "$repo_root"; then + local_cli_available=1 +fi + +if [[ "$local_cli_available" -eq 1 ]]; then + if [[ "${HYPERTWIST_GITNEXUS_DEBUG_LOCAL:-0}" == "1" ]]; then + if node "$local_gitnexus_cli" status "$@"; then + exit 0 + fi + elif node "$local_gitnexus_cli" status "$@" 2>/dev/null; then exit 0 fi - echo "Local retained GitNexus CLI was not runnable on this host. Falling back to npx gitnexus@latest." >&2 + echo "Local retained GitNexus CLI status failed after passing the runtime probe. Falling back to npx gitnexus@latest." >&2 fi exec npx -y gitnexus@latest status "$@" 2>/dev/null