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.

fix(hub): a build with no hub key says so on every hub surface (exit 5)

xerj-orgbe36af9ceaa9
diff --git a/engine/crates/xerj-autoindex/src/init.rs b/engine/crates/xerj-autoindex/src/init.rs
index 82123ae96..3df5ba0cd 100644
--- a/engine/crates/xerj-autoindex/src/init.rs
+++ b/engine/crates/xerj-autoindex/src/init.rs
@@ -229,15 +229,19 @@ fn mcp_registration(bin: &str, url: &str) -> String {
)
}
-/// What init says last: where to go next, the hub's one line, and the
-/// per-client MCP registration.
-fn closing_message(bin: &str, url: &str) -> String {
+/// What init says last: where to go next, the hub's one line (only in a build
+/// that can verify hub packs — `hub`), and the per-client MCP registration.
+fn closing_message(bin: &str, url: &str, hub: bool) -> String {
+ let hub_line = if hub {
+ "Public libraries, standards and advisories need no indexing: ask the hub with\n\
+ `xerj \"<question>\"` (the xerj-hub skill says when).\n\n"
+ } else {
+ ""
+ };
format!(
"\ndone. Restart the agent session to pick up the tools, then\n\
`xerj autoindex <folder>` anything you want searchable.\n\n\
- Public libraries, standards and advisories need no indexing: ask the hub with\n\
- `xerj \"<question>\"` (the xerj-hub skill says when).\n\n\
- {}",
+ {hub_line}{}",
mcp_registration(bin, url)
)
}
@@ -448,7 +452,8 @@ pub fn run_init_cli() -> i32 {
}
}
let cwd = std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
- match run_init_in(&cwd, &url, dry) {
+ let hub = xerj_common::hub::hub_key_configured();
+ match run_init_with(&cwd, &url, dry, hub) {
Ok(lines) => {
println!(
"xerj init{} — wiring XERJ into this project:\n",
@@ -457,7 +462,7 @@ pub fn run_init_cli() -> i32 {
for l in &lines {
println!("{l}");
}
- println!("{}", closing_message(&self_bin(), &url));
+ println!("{}", closing_message(&self_bin(), &url, hub));
0
}
Err(e) => {
@@ -467,8 +472,23 @@ pub fn run_init_cli() -> i32 {
}
}
-/// The writable core, separated from argv/cwd so tests drive it directly.
+/// [`run_init_with`] in a build that can use the hub (the hub teaching files
+/// are written). Tests drive this; the CLI passes the build's real answer.
+#[cfg(test)]
pub(crate) fn run_init_in(cwd: &Path, url: &str, dry: bool) -> Result<Vec<String>, String> {
+ run_init_with(cwd, url, dry, true)
+}
+
+/// The writable core, separated from argv/cwd so tests drive it directly.
+/// `hub` is false in a build with no hub signing key: no pack can be verified
+/// there, so the hub teaching files (which teach `xerj "<question>"`) are not
+/// written — an agent taught that line would only ever get exit 5.
+pub(crate) fn run_init_with(
+ cwd: &Path,
+ url: &str,
+ dry: bool,
+ hub: bool,
+) -> Result<Vec<String>, String> {
let mut out = Vec::new();
// 1) MCP registration (.mcp.json, Claude Code project scope; other hosts
@@ -501,11 +521,13 @@ pub(crate) fn run_init_in(cwd: &Path, url: &str, dry: bool) -> Result<Vec<String
&skill_md(),
dry,
)?);
- out.push(write_teaching_file(
- &cwd.join(".claude/skills/xerj-hub/SKILL.md"),
- HUB_SKILL_MD,
- dry,
- )?);
+ if hub {
+ out.push(write_teaching_file(
+ &cwd.join(".claude/skills/xerj-hub/SKILL.md"),
+ HUB_SKILL_MD,
+ dry,
+ )?);
+ }
}
// 3) Cursor rules — only when the project already has a .cursor directory.
@@ -516,11 +538,13 @@ pub(crate) fn run_init_in(cwd: &Path, url: &str, dry: bool) -> Result<Vec<String
&skill_md(),
dry,
)?);
- out.push(write_teaching_file(
- &cwd.join(".cursor/rules/xerj-hub.mdc"),
- HUB_SKILL_MD,
- dry,
- )?);
+ if hub {
+ out.push(write_teaching_file(
+ &cwd.join(".cursor/rules/xerj-hub.mdc"),
+ HUB_SKILL_MD,
+ dry,
+ )?);
+ }
}
// 4) AGENTS.md — the cross-agent convention. Append a short section if the
@@ -569,12 +593,11 @@ pub(crate) fn run_init_in(cwd: &Path, url: &str, dry: bool) -> Result<Vec<String
" auth MCP authenticates with the admin key at {} (local node)",
path.display()
)),
- None => out.push(
+ None => out.push(format!(
" auth no --auth given and no local admin key found; if the node at \
{url} runs with auth on, add \"XERJ_AUTH\": \"ApiKey <key>\" to the \
.mcp.json env — the key is the node's <data-dir>/admin.key"
- .to_string(),
- ),
+ )),
}
} else {
out.push(format!(
@@ -904,7 +927,7 @@ mod tests {
let success = format!("`{MCP_SUCCESS_TOOL}` is in the tool list");
assert!(HUB_SKILL_MD.contains(&success));
assert!(printed.contains(&success), "{printed}");
- let closing = closing_message("/usr/local/bin/xerj", DEFAULT_URL);
+ let closing = closing_message("/usr/local/bin/xerj", DEFAULT_URL, true);
assert!(closing.contains(&printed));
assert!(closing.contains(r#"xerj "<question>""#));
assert!(closing.contains("xerj autoindex <folder>"));
@@ -1189,6 +1212,35 @@ mod tests {
note.contains("XERJ_AUTH") && note.contains("admin.key"),
"the fallback note must name the env var and the key file: {note}"
);
+ assert!(
+ note.contains("http://localhost:9200") && !note.contains("{url}"),
+ "the note names the node it means, not a literal placeholder: {note}"
+ );
+ }
+
+ /// A build with no hub signing key can verify no pack, so `xerj ask` only
+ /// ever exits 5 there: init must not teach it. No hub skill, no hub rule,
+ /// no `xerj "<question>"` line; the local skill and MCP wiring are intact.
+ #[test]
+ fn a_build_without_a_hub_key_does_not_teach_the_hub() {
+ let d = tmp();
+ fs::create_dir_all(d.path().join(".claude")).unwrap();
+ fs::create_dir_all(d.path().join(".cursor")).unwrap();
+ let lines = run_init_with(d.path(), "http://x:1", false, false).unwrap();
+ assert!(d.path().join(".claude/skills/xerj/SKILL.md").exists());
+ assert!(d.path().join(".cursor/rules/xerj.mdc").exists());
+ assert!(d.path().join(".mcp.json").exists());
+ assert!(
+ !d.path().join(".claude/skills/xerj-hub").exists(),
+ "{lines:?}"
+ );
+ assert!(
+ !d.path().join(".cursor/rules/xerj-hub.mdc").exists(),
+ "{lines:?}"
+ );
+ let closing = closing_message("/usr/local/bin/xerj", DEFAULT_URL, false);
+ assert!(!closing.contains(r#"xerj "<question>""#), "{closing}");
+ assert!(closing.contains("xerj autoindex <folder>"), "{closing}");
}
/// A non-loopback URL never triggers discovery, even with a local key
diff --git a/engine/crates/xerj-common/src/hub.rs b/engine/crates/xerj-common/src/hub.rs
index 2c84d3076..cbe235940 100644
--- a/engine/crates/xerj-common/src/hub.rs
+++ b/engine/crates/xerj-common/src/hub.rs
@@ -41,6 +41,24 @@ pub const DISK_BUDGET_BYTES: u64 = 4 * 1024 * 1024 * 1024;
/// the `XERJ_HUB_PUBKEY` environment variable for tests only.
pub const HUB_PUBKEY_HEX: &str = "";
+/// True when this build can verify hub catalogues and packs: a key is compiled
+/// in ([`HUB_PUBKEY_HEX`]) or supplied through `XERJ_HUB_PUBKEY` (tests). A
+/// build without one cannot use Corpus Hub packs at all, so the hub surfaces
+/// (`xerj ask`, `xerj hub sync|pull`, the MCP hub tools, `xerj init`'s hub
+/// skill) say so plainly instead of failing on whatever the network returns.
+pub fn hub_key_configured() -> bool {
+ !HUB_PUBKEY_HEX.is_empty()
+ || std::env::var("XERJ_HUB_PUBKEY")
+ .map(|k| !k.trim().is_empty())
+ .unwrap_or(false)
+}
+
+/// What every hub surface says in a build with no hub key.
+pub const NO_HUB_KEY_MESSAGE: &str = "Corpus Hub packs are not available in this build: it has \
+ no hub signing key, so no catalogue or pack can be verified and nothing was downloaded. \
+ For reference code, index the projects yourself with `xerj corpus add` and search them \
+ with `xerj code` (see `xerj code --help`).";
+
/// What a per-source licence review allows, straight from the registry's
/// `review.use`. Governs whether a pack is pulled silently, with a warning, or
/// never.
diff --git a/engine/crates/xerj-hub/src/ask.rs b/engine/crates/xerj-hub/src/ask.rs
index 45febc6eb..09a5eee2c 100644
--- a/engine/crates/xerj-hub/src/ask.rs
+++ b/engine/crates/xerj-hub/src/ask.rs
@@ -1564,7 +1564,18 @@ pub fn run_ask_with(
.ok()
.filter(|u| !u.is_empty())
.unwrap_or_else(|| DEFAULT_HUB_URL.to_string());
- let catalogue = if args.cached_catalogue_only {
+ // A build with no hub key can never verify a catalogue or a pack, so it
+ // never fetches one: only a catalogue already on this machine is used, and
+ // without one the answer is the plain no-key message (exit 5), not a parse
+ // error from whatever the hub URL happens to serve.
+ let catalogue = if !xerj_common::hub::hub_key_configured() {
+ match load_cached_catalogue(&hub_home) {
+ Ok(c) => c,
+ // The cached-catalogue error says "run `xerj hub sync`", which
+ // cannot help here; the no-key message is the whole answer.
+ Err(_) => return AskOutcome::fail(EXIT_NO_KEY, xerj_common::hub::NO_HUB_KEY_MESSAGE),
+ }
+ } else if args.cached_catalogue_only {
match load_cached_catalogue(&hub_home) {
Ok(c) => c,
Err(msg) => return AskOutcome::fail(EXIT_NO_ANSWER, msg),
@@ -1717,7 +1728,15 @@ pub fn load_cached_catalogue(hub_home: &Path) -> Result<Catalogue, String> {
/// Only the MCP `xerj_hub_find` tool calls this.
pub fn run_find(question: &str, k: usize) -> Result<FindOutcome, String> {
let hub_home = cli::hub_home();
- let catalogue = load_cached_catalogue(&hub_home)?;
+ let catalogue = load_cached_catalogue(&hub_home).map_err(|e| {
+ if xerj_common::hub::hub_key_configured() {
+ e
+ } else {
+ // `xerj hub sync` cannot help in a build with no key: say that,
+ // not "run xerj hub sync".
+ xerj_common::hub::NO_HUB_KEY_MESSAGE.to_string()
+ }
+ })?;
let cwd = std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
Ok(find(question, k, &cwd, &hub_home, &catalogue))
}
diff --git a/engine/crates/xerj-hub/src/cli.rs b/engine/crates/xerj-hub/src/cli.rs
index c723d9513..5b16fd526 100644
--- a/engine/crates/xerj-hub/src/cli.rs
+++ b/engine/crates/xerj-hub/src/cli.rs
@@ -680,8 +680,16 @@ pub(crate) fn plan_pull(slug: &str) -> Result<PullPlan, PullError> {
.unwrap_or_else(|| DEFAULT_HUB_URL.to_string());
// 1. Catalogue → the entry for this slug.
- let cat = load_catalogue(&hub_url, &hub_home, false)
- .map_err(|e| PullError::new(E_INFRA, format!("cannot load catalogue: {e:#}")))?;
+ let cat = load_catalogue(&hub_url, &hub_home, false).map_err(|e| {
+ if xerj_common::hub::hub_key_configured() {
+ PullError::new(E_INFRA, format!("cannot load catalogue: {e:#}"))
+ } else {
+ // A build with no hub key could not verify the pack either; the
+ // catalogue error (often a parse error on whatever the hub URL
+ // serves) is not the useful answer.
+ PullError::new(E_NOKEY, xerj_common::hub::NO_HUB_KEY_MESSAGE)
+ }
+ })?;
let entry = cat.corpora.iter().find(|c| c.slug == slug).ok_or_else(|| {
PullError::new(
E_SLUG,
diff --git a/engine/crates/xerj-hub/src/sync.rs b/engine/crates/xerj-hub/src/sync.rs
index fbfa36090..12d714149 100644
--- a/engine/crates/xerj-hub/src/sync.rs
+++ b/engine/crates/xerj-hub/src/sync.rs
@@ -1119,6 +1119,13 @@ pub fn run_sync_using(
let hub_home = default_hub_root();
let cat = match refresh_catalogue(&hub_url(), &hub_home) {
Ok(c) => c,
+ Err(_) if !xerj_common::hub::hub_key_configured() => {
+ eprintln!(
+ "xerj hub sync: {} Nothing was changed.",
+ xerj_common::hub::NO_HUB_KEY_MESSAGE
+ );
+ return crate::ask::EXIT_NO_KEY;
+ }
Err(e) => {
eprintln!("xerj hub sync: cannot refresh the catalogue; nothing was changed: {e:#}");
return EXIT_INFRA;
diff --git a/engine/crates/xerj-hub/tests/no_hub_key.rs b/engine/crates/xerj-hub/tests/no_hub_key.rs
new file mode 100644
index 000000000..1cda6b7e8
--- /dev/null
+++ b/engine/crates/xerj-hub/tests/no_hub_key.rs
@@ -0,0 +1,64 @@
+//! A build with no hub signing key (`HUB_PUBKEY_HEX` empty, `XERJ_HUB_PUBKEY`
+//! unset) can verify no catalogue and no pack. Every hub surface must say so
+//! plainly with exit 5 — not fail on whatever the hub URL serves (a 200 HTML
+//! page made `xerj ask` print "parse catalogue JSON: expected value at line 1
+//! column 1", exit 1) and not send an MCP agent to `xerj hub sync`, which
+//! cannot help.
+//!
+//! One test in its own binary: it owns the process environment.
+
+use xerj_hub::ask::{self, EXIT_NO_KEY};
+use xerj_hub::cli::{run_ask, run_hub_cli};
+
+#[test]
+fn every_hub_surface_says_the_build_has_no_key() {
+ assert!(
+ xerj_hub::HUB_PUBKEY_HEX.is_empty(),
+ "precondition: no compiled-in key"
+ );
+ std::env::remove_var("XERJ_HUB_PUBKEY");
+ let home = tempfile::tempdir().unwrap();
+ std::env::set_var("XERJ_HUB_HOME", home.path());
+ // A hub that serves a 200 HTML page for every path, like hub.xerj.org's
+ // site fallback does for the unpublished API — the case that misled.
+ let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
+ let hub_url = format!("http://{}", listener.local_addr().unwrap());
+ std::thread::spawn(move || {
+ use std::io::{Read, Write};
+ for conn in listener.incoming() {
+ let Ok(mut c) = conn else { continue };
+ let mut buf = [0u8; 4096];
+ let _ = c.read(&mut buf);
+ let body = "<!doctype html><html><body>hub</body></html>";
+ let _ = write!(
+ c,
+ "HTTP/1.1 200 OK\r\ncontent-type: text/html\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{body}",
+ body.len()
+ );
+ }
+ });
+ std::env::set_var("XERJ_HUB_URL", &hub_url);
+
+ let s = |v: &[&str]| v.iter().map(|x| x.to_string()).collect::<Vec<_>>();
+
+ assert_eq!(
+ run_ask(&s(&["how does lz4 frame work"])),
+ EXIT_NO_KEY,
+ "xerj ask"
+ );
+ assert_eq!(run_hub_cli(&s(&["sync"])), EXIT_NO_KEY, "xerj hub sync");
+ assert_eq!(
+ run_hub_cli(&s(&["pull", "lz4"])),
+ EXIT_NO_KEY,
+ "xerj hub pull"
+ );
+
+ // The MCP `xerj_hub_find` path: the no-key message, not "run xerj hub sync".
+ let err = ask::run_find("how does lz4 frame work", 5).unwrap_err();
+ assert!(err.contains("not available in this build"), "{err}");
+ assert!(!err.contains("xerj hub sync"), "{err}");
+
+ // Usage errors are still usage errors.
+ assert_eq!(run_hub_cli(&s(&["sync", "--bogus"])), 2);
+ assert_eq!(run_ask(&s(&["--hosted", "maybe", "q x"])), ask::EXIT_USAGE);
+}
diff --git a/engine/crates/xerj-server/src/main.rs b/engine/crates/xerj-server/src/main.rs
index c7bbeca32..ea4df8a0b 100644
--- a/engine/crates/xerj-server/src/main.rs
+++ b/engine/crates/xerj-server/src/main.rs
@@ -229,11 +229,8 @@ fn help_text(feedback: bool) -> String {
of peer projects (see xerj code --help)\n\
xerj corpus add|index|list the corpus lifecycle behind `xerj code`\n\
(see xerj corpus --help)\n\
- xerj ask \"<question>\" answer a question from a hub corpus: the\n\
- pre-indexed pack is pulled the first time\n\
- (see xerj ask --help); `xerj \"<question>\"`\n\
- is the same\n\
- xerj index [OPTIONS] direct NDJSON → engine ingest (see xerj\n\
+ {ask_lines}\
+ xerj index [OPTIONS] direct NDJSON → engine ingest (see xerj\n\
index --help)\n\
xerj brain <folder> index + browse in one command (see xerj\n\
brain --help)\n\
@@ -405,9 +402,26 @@ fn help_text(feedback: bool) -> String {
// Counted from the served `tools/list`, not typed: the literal "13"
// went stale the day the three Corpus Hub tools landed (#1443).
mcp_tools = mcp_tool_count(),
+ ask_lines = ask_help_lines(xerj_common::hub::hub_key_configured()),
)
}
+/// The `xerj ask` usage lines. A build with no hub signing key can verify no
+/// pack, so there the line says the command is unavailable instead of
+/// promising a pull that will only ever exit 5.
+fn ask_help_lines(hub: bool) -> &'static str {
+ if hub {
+ "xerj ask \"<question>\" answer a question from a hub corpus: the\n\
+ pre-indexed pack is pulled the first time\n\
+ (see xerj ask --help); `xerj \"<question>\"`\n\
+ is the same\n"
+ } else {
+ "xerj ask \"<question>\" Corpus Hub answers: not available in this\n\
+ build (no hub signing key; exits 5) - use\n\
+ xerj corpus + xerj code instead\n"
+ }
+}
+
/// How many tools `xerj mcp` serves — the length of the same `tool_specs()`
/// array its `tools/list` returns.
fn mcp_tool_count() -> usize {