build: runner lookup through declared payloads then PATH, with typed messages (#544)

Author: speak-agent

src/build/runner_lookup.cppm

@@ -0,0 +1,138 @@
+// mcpp.build.runner_lookup — where the runner's program is, and what to say
+// when it is not.
+//
+// The lookup is mcpp's own rather than posix_spawnp's for one measured reason:
+// a bare name on PATH resolves to an xvm shim, and the shim answers for the
+// current subos rather than for the package (e2e 130 in CI: `mcpp run` exec'ing
+// the bare `qemu-system-riscv64` answered "not installed" while
+// `qemu-system-riscv64 --version` in the same job succeeded; `python3` on the
+// development host answers "not installed in this subos (_) — installed
+// elsewhere"). The payload's bin/ is the binary itself, so it is searched
+// first. That is what lets a runner name a program the project declared under
+// `[xlings] deps` without writing the payload's home-and-version path into the
+// manifest — the thing BuildConfig::runner's comment says a static manifest
+// cannot do.
+//
+// Doing the lookup here has a second effect: "not found anywhere" is decided
+// before any spawn, so a spawn-time ENOENT can only mean the program was found
+// and its interpreter or loader was not. The two messages differ, and neither
+// guesses.
+//
+// Design: .agents/docs/2026-09-02-runner-beyond-baremetal-design.md §4.3-4.4.
+
+module;
+#include <cerrno>
+
+export module mcpp.build.runner_lookup;
+
+import std;
+import mcpp.platform;
+
+export namespace mcpp::build::runner_lookup {
+
+struct Lookup {
+    std::optional<std::filesystem::path> program;   // absolute, executable
+    std::vector<std::filesystem::path>   searched;  // in order, for the message
+};
+
+namespace detail {
+inline bool executable_file(const std::filesystem::path& p) {
+    std::error_code ec;
+    if (!std::filesystem::is_regular_file(p, ec)) return false;
+    if constexpr (mcpp::platform::is_windows) return true;
+    auto perms = std::filesystem::status(p, ec).permissions();
+    using P = std::filesystem::perms;
+    return (perms & (P::owner_exec | P::group_exec | P::others_exec)) != P::none;
+}
+} // namespace detail
+
+// `argv0` absolute, or containing a directory separator: taken as-is when it
+// is an executable file. Otherwise `<each depBinDir>/argv0`, then each `PATH`
+// entry (`pathEnv` split on the platform's list separator); the first
+// executable regular file wins. Every directory looked in is recorded so the
+// not-found message can list them.
+inline Lookup locate(std::string_view argv0,
+                     std::span<const std::filesystem::path> depBinDirs,
+                     std::string_view pathEnv)
+{
+    Lookup out;
+    std::filesystem::path a0(argv0);
+    const bool hasDir = a0.is_absolute()
+                     || argv0.find('/') != std::string_view::npos
+                     || argv0.find('\\') != std::string_view::npos;
+    if (hasDir) {
+        std::error_code ec;
+        if (detail::executable_file(a0)) out.program = std::filesystem::absolute(a0, ec);
+        out.searched.push_back(a0.parent_path());
+        return out;
+    }
+    for (auto const& d : depBinDirs) {
+        out.searched.push_back(d);
+        if (auto c = d / a0; detail::executable_file(c)) { out.program = c; return out; }
+    }
+    constexpr char sep = mcpp::platform::is_windows ? ';' : ':';
+    for (auto part : std::views::split(pathEnv, sep)) {
+        std::string_view sv(part.begin(), part.end());
+        if (sv.empty()) continue;
+        std::filesystem::path d(sv);
+        out.searched.push_back(d);
+        if (auto c = d / a0; detail::executable_file(c)) { out.program = c; return out; }
+    }
+    return out;
+}
+
+// What the kernel's refusal means. Only ENOEXEC (and EBADARCH where the
+// platform defines it) says "this host cannot load the artifact"; everything
+// else — EACCES, ENOENT on a found program, E2BIG — is reported verbatim and
+// never turned into advice about runners.
+enum class SpawnClass { Unloadable, Other };
+
+inline SpawnClass classify(int e) {
+    if (e == ENOEXEC) return SpawnClass::Unloadable;
+#if defined(EBADARCH)
+    if (e == EBADARCH) return SpawnClass::Unloadable;
+#endif
+    return SpawnClass::Other;
+}
+
+inline std::string errno_text(int e) {
+    return std::generic_category().message(e);
+}
+
+inline std::string not_found_message(std::string_view triple, std::string_view argv0,
+                                     std::span<const std::filesystem::path> searched) {
+    std::string dirs;
+    for (auto const& d : searched) dirs += "\n           " + d.string();
+    return std::format(
+        "runner '{}' for '{}' was not found. Searched:{}\n"
+        "       Declare the package that provides it under [xlings] deps, or "
+        "install it on PATH.\n"
+        "       Pass --no-runner to execute the artifact directly on this host.",
+        argv0, triple, dirs);
+}
+
+inline std::string spawn_failed_message(std::string_view program, int e) {
+    return std::format("'{}' could not be started: {} (error {})",
+                       program, errno_text(e), e);
+}
+
+// The hosted sibling of mcpp::freestanding::no_runner_message. It reports what
+// the kernel answered rather than asserting why: on a hosted triple mcpp does
+// not know whether the refusal is a foreign ISA or a file that is not an
+// executable at all, and the example it prints is a user-mode emulator.
+inline std::string unrunnable_message(std::string_view triple,
+                                      const std::filesystem::path& artifact, int e) {
+    return std::format(
+        "this host cannot execute '{}': {} (error {}).\n"
+        "       The artifact was built for '{}'. Declare how to run it here:\n"
+        "\n"
+        "           [target.{}]\n"
+        "           runner = [\"qemu-aarch64-static\"]\n"
+        "\n"
+        "       The artifact path is appended, or substituted for `{{}}` if the "
+        "template contains it.\n"
+        "       A host that can execute it directly may pass --no-runner.",
+        artifact.string(), errno_text(e), e, triple, triple);
+}
+
+} // namespace mcpp::build::runner_lookup

tests/unit/test_runner_lookup.cpp

@@ -0,0 +1,128 @@
+#include <gtest/gtest.h>
+#include <cerrno>
+#include <fstream>
+
+import std;
+import mcpp.build.runner_lookup;
+
+using namespace mcpp::build::runner_lookup;
+
+// The lookup order is the whole point (#544 §4.4): a declared payload's bin/
+// beats PATH, because a bare name on PATH reaches an xvm shim that answers for
+// the current subos rather than for the package. The directories are real and
+// the files are executable, so what is asserted is the rule, not a mock of it.
+#if !defined(_WIN32)
+
+namespace {
+std::filesystem::path fresh_root(std::string_view name) {
+    auto root = std::filesystem::temp_directory_path() / name;
+    std::filesystem::remove_all(root);
+    std::filesystem::create_directories(root);
+    return root;
+}
+std::filesystem::path make_exe(const std::filesystem::path& dir, std::string_view name) {
+    std::filesystem::create_directories(dir);
+    auto p = dir / name;
+    { std::ofstream o(p); o << "#!/bin/sh\nexit 0\n"; }
+    std::filesystem::permissions(p, std::filesystem::perms::owner_all);
+    return p;
+}
+} // namespace
+
+TEST(RunnerLookup, PayloadBinBeatsPath) {
+    auto root = fresh_root("mcpp-runner-lookup-1");
+    auto inPayload = make_exe(root / "payload" / "bin", "qemu-x");
+    make_exe(root / "path", "qemu-x");
+    std::vector<std::filesystem::path> bins{root / "payload" / "bin"};
+    auto l = locate("qemu-x", bins, (root / "path").string());
+    ASSERT_TRUE(l.program.has_value());
+    EXPECT_EQ(*l.program, inPayload);
+}
+
+TEST(RunnerLookup, PathIsSearchedAfterPayloads) {
+    auto root = fresh_root("mcpp-runner-lookup-2");
+    auto onPath = make_exe(root / "path", "qemu-y");
+    std::vector<std::filesystem::path> bins{root / "payload" / "bin"};   // absent dir
+    auto l = locate("qemu-y", bins, (root / "path").string());
+    ASSERT_TRUE(l.program.has_value());
+    EXPECT_EQ(*l.program, onPath);
+    ASSERT_EQ(l.searched.size(), 2u);
+    EXPECT_EQ(l.searched[0], root / "payload" / "bin");
+    EXPECT_EQ(l.searched[1], root / "path");
+}
+
+TEST(RunnerLookup, NonExecutableFileIsSkipped) {
+    auto root = fresh_root("mcpp-runner-lookup-3");
+    std::filesystem::create_directories(root / "p1");
+    { std::ofstream o(root / "p1" / "tool"); o << "data"; }   // no exec bit
+    auto real = make_exe(root / "p2", "tool");
+    auto l = locate("tool", {}, (root / "p1").string() + ":" + (root / "p2").string());
+    ASSERT_TRUE(l.program.has_value());
+    EXPECT_EQ(*l.program, real);
+}
+
+TEST(RunnerLookup, NotFoundListsEveryDirectorySearched) {
+    auto root = fresh_root("mcpp-runner-lookup-4");
+    std::vector<std::filesystem::path> bins{root / "a" / "bin"};
+    auto l = locate("nope", bins, (root / "p1").string() + ":" + (root / "p2").string());
+    EXPECT_FALSE(l.program.has_value());
+    ASSERT_EQ(l.searched.size(), 3u);
+    auto msg = not_found_message("aarch64-linux-musl", "nope", l.searched);
+    EXPECT_NE(msg.find("runner 'nope'"), std::string::npos) << msg;
+    EXPECT_NE(msg.find("aarch64-linux-musl"), std::string::npos) << msg;
+    EXPECT_NE(msg.find((root / "a" / "bin").string()), std::string::npos) << msg;
+    EXPECT_NE(msg.find((root / "p2").string()), std::string::npos) << msg;
+    EXPECT_NE(msg.find("[xlings] deps"), std::string::npos) << msg;
+    EXPECT_NE(msg.find("--no-runner"), std::string::npos) << msg;
+}
+
+TEST(RunnerLookup, AbsoluteArgv0IsTakenAsIs) {
+    auto root = fresh_root("mcpp-runner-lookup-5");
+    auto abs = make_exe(root, "runner.sh");
+    auto l = locate(abs.string(), {}, "");
+    ASSERT_TRUE(l.program.has_value());
+    EXPECT_EQ(*l.program, abs);
+    // ...and an absolute path that is not there is not searched for elsewhere.
+    auto missing = locate((root / "absent.sh").string(), {}, root.string());
+    EXPECT_FALSE(missing.program.has_value());
+}
+
+TEST(RunnerLookup, EmptyPathEntriesAreIgnored) {
+    auto root = fresh_root("mcpp-runner-lookup-6");
+    auto onPath = make_exe(root / "p", "tool");
+    auto l = locate("tool", {}, ":" + (root / "p").string() + "::");
+    ASSERT_TRUE(l.program.has_value());
+    EXPECT_EQ(*l.program, onPath);
+    EXPECT_EQ(l.searched.size(), 1u);
+}
+
+TEST(RunnerLookup, ClassifiesENOEXECAsUnloadable) {
+    EXPECT_EQ(classify(ENOEXEC), SpawnClass::Unloadable);
+    EXPECT_EQ(classify(EACCES), SpawnClass::Other);
+    EXPECT_EQ(classify(ENOENT), SpawnClass::Other);
+    EXPECT_EQ(classify(0), SpawnClass::Other);
+}
+
+TEST(RunnerLookup, UnrunnableMessageNamesKernelAnswerTripleAndKey) {
+    auto msg = unrunnable_message("aarch64-linux-musl", "/x/bin/app", ENOEXEC);
+    EXPECT_NE(msg.find("Exec format error"), std::string::npos) << msg;
+    EXPECT_NE(msg.find("/x/bin/app"), std::string::npos) << msg;
+    EXPECT_NE(msg.find("built for 'aarch64-linux-musl'"), std::string::npos) << msg;
+    EXPECT_NE(msg.find("[target.aarch64-linux-musl]"), std::string::npos) << msg;
+    EXPECT_NE(msg.find("runner = [\"qemu-aarch64-static\"]"), std::string::npos) << msg;
+    EXPECT_NE(msg.find("--no-runner"), std::string::npos) << msg;
+}
+
+TEST(RunnerLookup, SpawnFailedMessageIsVerbatim) {
+    auto msg = spawn_failed_message("/x/bin/qemu", EACCES);
+    EXPECT_NE(msg.find("'/x/bin/qemu' could not be started"), std::string::npos) << msg;
+    EXPECT_NE(msg.find("Permission denied"), std::string::npos) << msg;
+    EXPECT_NE(msg.find("(error 13)"), std::string::npos) << msg;
+    EXPECT_EQ(msg.find("runner = ["), std::string::npos) << msg;   // no runner advice
+}
+
+#else
+
+TEST(RunnerLookup, WindowsCoveredByIntegration) { SUCCEED(); }
+
+#endif