Skip to content

armgit / xerj

Public Imported from GitHub
0

AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.

xerj ask: exit 6 when the hub catalogue cannot be loaded (#1905)

xerj-orge73a146a1b60
diff --git a/engine/crates/xerj-hub/src/ask.rs b/engine/crates/xerj-hub/src/ask.rs
index 2fdae1100..8aa956e69 100644
--- a/engine/crates/xerj-hub/src/ask.rs
+++ b/engine/crates/xerj-hub/src/ask.rs
@@ -86,6 +86,11 @@ pub const EXIT_NEEDS_DECISION: i32 = 4;
/// A pull was refused because this build has no hub public key: not a pack that
/// failed verification ([`EXIT_UNVERIFIED`]) but one that cannot be judged at all.
pub const EXIT_NO_KEY: i32 = 5;
+/// The hub catalogue could not be loaded (the hub is unreachable, serves no signed
+/// catalogue, or `--offline` has no cached one). Not [`EXIT_NO_ANSWER`]: that one
+/// says "the hub has nothing for this question", which an agent reads as an answer
+/// about the corpus, while this one is about the hub itself and is worth a retry.
+pub const EXIT_HUB_UNAVAILABLE: i32 = 6;
/// Printed (stderr) when the router finds nothing credible.
pub const NO_CORPUS_MESSAGE: &str = "no hub corpus matches; see xerj.org/llms.txt";
@@ -1623,8 +1628,13 @@ pub fn run_ask_with(
Ok(c) => c,
Err(e) => {
return AskOutcome::fail(
- EXIT_NO_ANSWER,
- format!("cannot load the hub catalogue: {e:#}"),
+ EXIT_HUB_UNAVAILABLE,
+ format!(
+ "cannot load the hub catalogue: {e:#}\n\
+ (exit {EXIT_HUB_UNAVAILABLE}: the hub itself is unavailable; this says nothing about \
+ whether a corpus holds the answer. Retry later, point XERJ_HUB_URL at a working hub, \
+ or ask with --offline once a catalogue is cached.)"
+ ),
)
}
}
diff --git a/engine/crates/xerj-hub/src/cli.rs b/engine/crates/xerj-hub/src/cli.rs
index 470f6e6fa..b809a991c 100644
--- a/engine/crates/xerj-hub/src/cli.rs
+++ b/engine/crates/xerj-hub/src/cli.rs
@@ -1354,7 +1354,9 @@ options:
exit codes: 0 answered; 1 no match or nothing to answer from; 2 usage error or
unknown corpus; 3 a pack failed verification; 4 more than one corpus matches
(candidates are printed; re-run with --corpus <slug>); 5 this build has no hub
-public key, so no pack can be verified (nothing was downloaded)";
+public key, so no pack can be verified (nothing was downloaded); 6 the hub
+catalogue could not be loaded (hub unreachable, no signed catalogue served, or
+--offline with none cached): a hub problem, not an answer about any corpus";
/// The first argument of every real `xerj` subcommand.
pub const KNOWN_SUBCOMMANDS: &[&str] = &[
@@ -1729,6 +1731,34 @@ fn now_rfc3339() -> String {
mod tests {
use super::*;
+ #[test]
+ fn ask_hub_unavailable_has_its_own_documented_exit_code() {
+ // "the hub catalogue cannot be loaded" used to share exit 1 with "no
+ // match", which an agent reads as an answer about the corpus.
+ let codes = [
+ ask::EXIT_OK,
+ ask::EXIT_NO_ANSWER,
+ ask::EXIT_USAGE,
+ ask::EXIT_UNVERIFIED,
+ ask::EXIT_NEEDS_DECISION,
+ ask::EXIT_NO_KEY,
+ ask::EXIT_HUB_UNAVAILABLE,
+ ];
+ let mut sorted = codes.to_vec();
+ sorted.sort_unstable();
+ sorted.dedup();
+ assert_eq!(
+ sorted.len(),
+ codes.len(),
+ "exit codes must be distinct: {codes:?}"
+ );
+ assert_eq!(ask::EXIT_HUB_UNAVAILABLE, 6);
+ assert!(
+ ASK_USAGE.contains("6 the hub\ncatalogue could not be loaded"),
+ "{ASK_USAGE}"
+ );
+ }
+
/// A minimal record pack in the layout `xerj corpus build` writes and
/// `harvest::pack::read_manifest` verifies.
fn record_pack(dir: &Path, slug: &str, created_at: &str, records: &str, licence: &str) {
diff --git a/tools/hub-packs/whole_hub_e2e.sh b/tools/hub-packs/whole_hub_e2e.sh
index ea7c6c8c5..6b490df14 100644
--- a/tools/hub-packs/whole_hub_e2e.sh
+++ b/tools/hub-packs/whole_hub_e2e.sh
@@ -328,8 +328,8 @@ if [ "${1:-}" = "--inner" ]; then
run pull env XERJ_HUB_URL="$E2E_DEAD_HUB" "$BIN" hub pull "$E2E_TARGET"; p=$RC; pe=$ERRF
run ask env XERJ_HUB_URL="$E2E_DEAD_HUB" "$BIN" ask --corpus "$E2E_TARGET" "$E2E_TARGET"
if [ "$p" != 0 ] && has "cannot load catalogue" "$pe" && has "$MSG_NO_CACHE" "$pe" \
- && [ "$RC" = 1 ] && has "cannot load the hub catalogue" "$ERRF" && nothing_extracted "$E2E_TARGET"; then
- check hub-unreachable 0 "empty HOME, nothing listening: pull exit $p and ask exit 1, both '…$MSG_NO_CACHE'; nothing extracted"
+ && [ "$RC" = 6 ] && has "cannot load the hub catalogue" "$ERRF" && nothing_extracted "$E2E_TARGET"; then
+ check hub-unreachable 0 "empty HOME, nothing listening: pull exit $p and ask exit 6, both '…$MSG_NO_CACHE'; nothing extracted"
else
check hub-unreachable 1 "pull exit $p, ask exit $RC: $(last_err)"
fi
@@ -338,9 +338,9 @@ if [ "${1:-}" = "--inner" ]; then
html)
run pull env XERJ_HUB_URL="$E2E_HTML_HUB" "$BIN" hub pull "$E2E_TARGET"; p=$RC; pe=$ERRF
run ask env XERJ_HUB_URL="$E2E_HTML_HUB" "$BIN" ask --corpus "$E2E_TARGET" "$E2E_TARGET"
- if [ "$p" != 0 ] && has "$MSG_HTML" "$pe" && [ "$RC" = 1 ] && has "$MSG_HTML" "$ERRF" \
+ if [ "$p" != 0 ] && has "$MSG_HTML" "$pe" && [ "$RC" = 6 ] && has "$MSG_HTML" "$ERRF" \
&& [ ! -e "$HOME/.xerj/hub/catalogue.json" ] && nothing_extracted "$E2E_TARGET"; then
- check hub-html-200 0 "empty HOME, the site's HTML page (200) as the catalogue: '$MSG_HTML' from pull (exit $p) and ask (exit 1); nothing cached or extracted"
+ check hub-html-200 0 "empty HOME, the site's HTML page (200) as the catalogue: '$MSG_HTML' from pull (exit $p) and ask (exit 6); nothing cached or extracted"
else
check hub-html-200 1 "pull exit $p, ask exit $RC: $(last_err)"
fi
@@ -348,8 +348,8 @@ if [ "${1:-}" = "--inner" ]; then
offline)
run offline-empty "$BIN" ask --offline --corpus "$E2E_TARGET" "$E2E_TARGET"
- if [ "$RC" = 1 ] && has "$MSG_OFFLINE_NOCAT" "$ERRF"; then
- check offline-no-catalogue 0 "--offline, empty HOME: exit 1, '$MSG_OFFLINE_NOCAT'"
+ if [ "$RC" = 6 ] && has "$MSG_OFFLINE_NOCAT" "$ERRF"; then
+ check offline-no-catalogue 0 "--offline, empty HOME: exit 6, '$MSG_OFFLINE_NOCAT'"
else
check offline-no-catalogue 1 "exit $RC: $(last_err)"
fi