std::filesystem::path binary; // xlings binary path

std::filesystem::path home; // XLINGS_HOME directory

std::filesystem::path projectDir; // XLINGS_PROJECT_DIR (empty = global mode)

std::string phase; // "download", "extract", "configure", ...

int percent; // 0..100

std::string message;

std::string code;

std::string message;

std::string hint;

bool recoverable = false;

int exitCode = 0;

std::vector<DataEvent> dataEvents;

std::optional<ErrorEvent> error;

std::string resultJson;

virtual ~EventHandler() = default;

virtual void on_progress(const ProgressEvent&) {}

virtual void on_log (const LogEvent&) {}

virtual void on_data (const DataEvent&) {}

virtual void on_error (const ErrorEvent&) {}

virtual void on_result (const ResultEvent&) {}

std::string name; // xim package id, e.g. "xim:patchelf@0.18.0"

double downloadedBytes = 0;

double totalBytes = 0;

bool started = false;

bool finished = false;

std::vector<std::string> deps; // → "deps"

std::vector<std::pair<std::string,std::string>> workspace; // → "workspace"

std::string subos; // → "subos"

std::vector<std::pair<std::string,std::string>> envs; // → "envs"

bool empty() const {

return deps.empty() && workspace.empty() && subos.empty() && envs.empty();

}

std::string name;

std::string url;

std::string artifact; // artifact source base, e.g. https://github.com/xlings-res/mcpp-index

std::string source; // "auto" | "artifact" | "git"

std::filesystem::path dir; // on-disk index directory

bool present; // pkgs/ tree exists locally

bool fresh; // refreshed within ttlSeconds

std::int64_t ageSeconds; // since last refresh marker, -1 if unknown

std::optional<std::string> rev; // index CONTENT identity, nullopt if absent

constexpr std::size_t W = 12;

if (verb.size() >= W) {

std::println("{} {}", verb, msg);

} else {

std::println("{}{} {}", std::string(W - verb.size(), ' '), verb, msg);

}

if (packageName.empty()) return {};

std::string name(packageName);

return official_index_dir(env) / "pkgs" / std::string(1, name[0]) / (name + ".lua");

auto value = path.string();

std::string escaped;

escaped.reserve(value.size() * 2);

for (char c : value) {

if (c == '\\') escaped += "\\\\";

else escaped.push_back(c);

}

return escaped;

std::string_view packageName) {

auto cache = official_index_dir(env) / ".xlings-index-cache.json";

if (!std::filesystem::exists(cache)) return true;

auto pkg = official_package_file(env, packageName);

if (pkg.empty()) return false;

std::ifstream is(cache);

if (!is) return false;

std::string body((std::istreambuf_iterator<char>(is)), {});

auto rawPath = pkg.string();

return body.find(rawPath) != std::string::npos

|| body.find(json_escaped_path_probe(pkg)) != std::string::npos;

if (!std::filesystem::exists(index_pkgs_dir(indexDir))) return;

std::error_code ec;

std::filesystem::create_directories(indexDir, ec);

auto marker = index_refresh_marker(indexDir);

{

std::ofstream os(marker, std::ios::trunc);

if (!os) return;

os << "ok\n";

}

std::filesystem::last_write_time(

marker, std::filesystem::file_time_type::clock::now(), ec);

// Project-scoped envs used to return early here, which left the global

// indexes unmarked whenever a project with custom `[indices]` triggered the

// sync — so `mcpp index status` reported "unknown" forever on exactly the

// machines that refresh most. The marker is advisory (it debounces and it

// dates the status line; it is NOT what decides whether a refresh is

// needed), so marking it from either env is both safe and more accurate.

mark_index_refreshed(default_index_dir(env));

mark_index_refreshed(official_index_dir(env));

std::error_code ec;

if (!std::filesystem::exists(index_pkgs_dir(indexDir))) return false;

auto marker = index_refresh_marker(indexDir);

if (!std::filesystem::exists(marker)) return false;

auto newest = std::filesystem::last_write_time(marker, ec);

if (ec) return false;

auto now = std::filesystem::file_time_type::clock::now();

auto age = std::chrono::duration_cast<std::chrono::seconds>(now - newest);

// A marker stamped in the FUTURE yields a negative age, which the plain

// `age < ttl` test read as "fresh" — and stayed fresh until the wall clock

// caught up, potentially for years. Future timestamps are routine: clock

// skew in containers/VMs, a tar that preserved mtimes, a restored CI cache.

// An unusable timestamp means "unknown", and unknown must mean stale.

if (age.count() < 0) return false;

return age.count() < ttlSeconds;

std::error_code ec;

auto marker = index_refresh_marker(indexDir);

auto newest = std::filesystem::last_write_time(marker, ec);

if (ec) return -1;

auto now = std::filesystem::file_time_type::clock::now();

auto age = std::chrono::duration_cast<std::chrono::seconds>(now - newest).count();

return age < 0 ? -1 : age; // future stamp → "unknown", same rule as above

std::ifstream is(index_version_file(indexDir), std::ios::binary);

if (!is) return std::nullopt;

std::string body((std::istreambuf_iterator<char>(is)), {});

// The observed files carry no trailing newline, but trim anyway: this value

// is compared for equality and printed, and a stray \r from a Windows-side

// writer would otherwise turn "same rev" into "changed rev" every run.

auto isSpace = [](unsigned char c) { return std::isspace(c) != 0; };

while (!body.empty() && isSpace(static_cast<unsigned char>(body.back())))

body.pop_back();

std::size_t b = 0;

while (b < body.size() && isSpace(static_cast<unsigned char>(body[b]))) ++b;

body.erase(0, b);

if (body.empty()) return std::nullopt;

return body;

std::int64_t ttlSeconds) {

std::error_code ec;

bool present = std::filesystem::exists(index_pkgs_dir(indexDir), ec) && !ec;

return IndexStatus{

.dir = indexDir,

.present = present,

.fresh = is_index_dir_fresh(indexDir, ttlSeconds),

.ageSeconds = index_age_seconds(indexDir),

.rev = read_index_revision(indexDir),

};

std::error_code ec;

std::filesystem::create_directories(p.parent_path(), ec);

std::ofstream os(p);

os << content;

std::string out;

out.reserve(value.size());

for (unsigned char ch : value) {

switch (ch) {

case '"': out += "\\\""; break;

case '\\': out += "\\\\"; break;

case '\b': out += "\\b"; break;

case '\f': out += "\\f"; break;

case '\n': out += "\\n"; break;

case '\r': out += "\\r"; break;

case '\t': out += "\\t"; break;

default:

if (ch < 0x20) {

out += std::format("\\u{:04x}", static_cast<unsigned>(ch));

} else {

out.push_back(static_cast<char>(ch));

}

}

}

return out;

std::string_view s;

std::string find_str(std::string_view key) const {

std::string n = std::format("\"{}\":\"", key);

auto p = s.find(n);

if (p == std::string_view::npos) return "";

p += n.size();

std::string out;

while (p < s.size() && s[p] != '"') {

if (s[p] == '\\' && p + 1 < s.size()) {

out.push_back(s[p+1]); p += 2; continue;

}

out.push_back(s[p++]);

}

return out;

}

double find_num(std::string_view key) const {

std::string n = std::format("\"{}\":", key);

auto p = s.find(n);

if (p == std::string_view::npos) return 0;

p += n.size();

auto e = p;

while (e < s.size()

&& (std::isdigit(static_cast<unsigned char>(s[e]))

|| s[e] == '.' || s[e] == '-' || s[e] == '+'

|| s[e] == 'e' || s[e] == 'E')) ++e;

try { return std::stod(std::string(s.substr(p, e - p))); }

catch (...) { return 0; }

}

bool find_bool(std::string_view key) const {

std::string n = std::format("\"{}\":", key);

auto p = s.find(n);

if (p == std::string_view::npos) return false;

p += n.size();

return s.size() - p >= 4 && s.substr(p, 4) == "true";

}

auto r = mcpp::platform::process::capture(cmd);

if (r.exit_code != 0 && r.output.empty())

return std::unexpected("command failed: " + cmd);

return r.output;

for (auto p = compilerBin.parent_path();

p.has_parent_path() && p != p.root_path();

p = p.parent_path()) {

if (p.filename() == "xpkgs") return p;

}

return std::nullopt;

auto xpkgs = xpkgs_from_compiler(compilerBin);

if (!xpkgs) return std::nullopt;

// <home>/data/xpkgs → <home>/subos/default. Spelled from the xpkgs dir

// rather than from Env so a toolchain inherited from ANOTHER home resolves

// to that home's subos, which is the one whose payloads the binary was

// actually linked against.

auto home = xpkgs->parent_path().parent_path();

if (home.empty()) return std::nullopt;

return home / "subos" / "default";

std::string_view tool) {

auto xpkgs = xpkgs_from_compiler(compilerBin);

if (!xpkgs) return std::nullopt;

auto root = *xpkgs / std::format("xim-x-{}", tool);

std::error_code ec;

if (!std::filesystem::exists(root, ec)) return std::nullopt;

// The first version dir readdir yields. ORDER IS UNDEFINED -- this does

// NOT return the highest, and the comment that said so was wrong for as

// long as it stood. With two versions installed the answer varies by

// filesystem, so a caller that needs a SPECIFIC version must name it;

// see probe.cppm, where the version comes from the resolved runtime

// binding rather than from this scan.

//

// A test asserting the old "highest" claim was attempted and removed: it

// passed or failed by directory order, which makes both outcomes

// uninformative.

for (auto& v : std::filesystem::directory_iterator(root, ec)) {

if (v.is_directory(ec)) return v.path();

}

return std::nullopt;

std::filesystem::path home;

if (const char* h = std::getenv("MCPP_HOME"); h && *h) {

home = h;

} else if (const char* u = std::getenv("HOME"); u && *u) {

home = std::filesystem::path(u) / ".mcpp";

} else {

return std::nullopt;

}

auto xpkgs = home / "registry" / "data" / "xpkgs";

std::error_code ec;

if (!std::filesystem::exists(xpkgs, ec)) return std::nullopt;

return xpkgs;

std::string_view requiredRelPath) {

std::error_code ec;

bool hasContent = false;

for (auto& f : std::filesystem::directory_iterator(versionDir, ec)) {

if (!f.path().filename().string().starts_with(".")) {

hasContent = true;

break;

}

}

if (!hasContent) return false;

if (!requiredRelPath.empty()

&& !std::filesystem::exists(versionDir / requiredRelPath, ec))

return false;

return true;

std::string_view packageName,

std::string_view requiredRelPath) {

std::error_code ec;

std::string suffix = std::format("-x-{}", packageName);

for (auto& entry : std::filesystem::directory_iterator(xpkgs, ec)) {

if (!entry.is_directory(ec)) continue;

auto name = entry.path().filename().string();

if (!name.ends_with(suffix)) continue;

for (auto& v : std::filesystem::directory_iterator(entry.path(), ec)) {

if (!v.is_directory(ec)) continue;

if (payload_dir_qualifies(v.path(), requiredRelPath))

return v.path();

}

}

return std::nullopt;

auto xpkgs = active_home_xpkgs();

if (!xpkgs) return std::nullopt;

return find_package_in_xpkgs(*xpkgs, tool, requiredRelPath);

std::string_view tool,

std::string_view binaryRelPath) {

auto xpkgs = xpkgs_from_compiler(compilerBin);

if (!xpkgs) return std::nullopt;

auto root = *xpkgs / std::format("xim-x-{}", tool);

std::error_code ec;

if (!std::filesystem::exists(root, ec)) return std::nullopt;

for (auto& v : std::filesystem::directory_iterator(root, ec)) {

auto candidate = v.path() / std::string(binaryRelPath);

if (std::filesystem::exists(candidate, ec))

return candidate;

}

return std::nullopt;

std::string_view packageName,

std::string_view requiredRelPath) {

auto xpkgs = xpkgs_from_compiler(compilerBin);

if (!xpkgs) return std::nullopt;

// Search across index prefixes: xim-x-, scode-x-, compat-x-, etc.

if (auto found = find_package_in_xpkgs(*xpkgs, packageName, requiredRelPath))

return found;

// Also check ~/.xlings/data/xpkgs/ (xlings global home) as fallback.

std::error_code ec;

const char* home = std::getenv("HOME");

if (home) {

auto xlingsXpkgs = std::filesystem::path(home) / ".xlings" / "data" / "xpkgs";

if (xlingsXpkgs != *xpkgs && std::filesystem::exists(xlingsXpkgs, ec))

return find_package_in_xpkgs(xlingsXpkgs, packageName, requiredRelPath);

}

return std::nullopt;

auto xvmBin = paths::sandbox_bin(env).string();

if constexpr (mcpp::platform::is_windows) {

mcpp::platform::env::set("XLINGS_HOME", env.home.string());

mcpp::platform::env::set("XLINGS_PROJECT_DIR",

env.projectDir.empty() ? "" : env.projectDir.string());

mcpp::platform::windows::prepend_path(xvmBin);

return env.binary.string();

} else {

if (env.projectDir.empty()) {

// Global mode: unset XLINGS_PROJECT_DIR (existing behavior).

return std::format(

"cd {} && env -u XLINGS_PROJECT_DIR PATH={}:\"$PATH\" XLINGS_HOME={} {}",

shq(env.home.string()),

shq(xvmBin),

shq(env.home.string()),

shq(env.binary.string()));

}

// Project-level mode: set XLINGS_PROJECT_DIR so xlings uses

// additive project repos alongside global repos.

return std::format(

"cd {} && env PATH={}:\"$PATH\" XLINGS_HOME={} XLINGS_PROJECT_DIR={} {}",

shq(env.home.string()),

shq(xvmBin),

shq(env.home.string()),

shq(env.projectDir.string()),

shq(env.binary.string()));

}

std::string_view capability,

std::string_view argsJson) {

return std::format("{} interface {} --args {} {}",

build_command_prefix(env), capability, shq(argsJson),

mcpp::platform::null_redirect);

auto needle = std::string{"\""} + std::string(key) + "\":\"";

auto p = text.find(needle);

if (p == std::string_view::npos) return "";

p += needle.size();

std::string out;

while (p < text.size()) {

char c = text[p++];

if (c == '\\' && p < text.size()) {

char nc = text[p++];

switch (nc) {

case 'n': out.push_back('\n'); break;

case 't': out.push_back('\t'); break;

case 'r': out.push_back('\r'); break;

case '"': out.push_back('"'); break;

case '\\': out.push_back('\\'); break;

default: out.push_back(nc);

}

} else if (c == '"') {

return out;

} else {

out.push_back(c);

}

}

return out;

auto needle = std::string{"\""} + std::string(key) + "\":";

auto p = text.find(needle);

if (p == std::string_view::npos) return std::nullopt;

p += needle.size();

while (p < text.size() && text[p] == ' ') ++p;

bool neg = false;

if (p < text.size() && text[p] == '-') { neg = true; ++p; }

long long n = 0;

bool any = false;

while (p < text.size() && std::isdigit(static_cast<unsigned char>(text[p]))) {

n = n * 10 + (text[p++] - '0');

any = true;

}

if (!any) return std::nullopt;

return neg ? -n : n;

auto needle = std::string{"\""} + std::string(key) + "\":";

auto p = text.find(needle);

if (p == std::string_view::npos) return std::nullopt;

p += needle.size();

while (p < text.size() && text[p] == ' ') ++p;

if (text.substr(p, 4) == "true") return true;

if (text.substr(p, 5) == "false") return false;

return std::nullopt;

auto needle = std::string{"\""} + std::string(key) + "\":";

auto p = text.find(needle);

if (p == std::string_view::npos) return "";

p += needle.size();

while (p < text.size() && text[p] == ' ') ++p;

if (p >= text.size() || (text[p] != '{' && text[p] != '[')) return "";

char open = text[p];

char close = (open == '{') ? '}' : ']';

int depth = 0;

std::size_t start = p;

bool in_string = false;

while (p < text.size()) {

char c = text[p];

if (in_string) {

if (c == '\\' && p + 1 < text.size()) { p += 2; continue; }

if (c == '"') in_string = false;

++p; continue;

}

if (c == '"') { in_string = true; ++p; continue; }

if (c == open) { ++depth; }

else if (c == close) {

--depth;

if (depth == 0) return std::string(text.substr(start, p - start + 1));

}

++p;

}

return "";

auto kind = extract_string(line, "kind");

if (kind == "progress") {

ProgressEvent e;

e.phase = extract_string(line, "phase");

e.percent = static_cast<int>(extract_int(line, "percent").value_or(0));

e.message = extract_string(line, "message");

return e;

}

if (kind == "log") {

LogEvent e;

e.level = extract_string(line, "level");

e.message = extract_string(line, "message");

return e;

}