oxy doctor, and failures that say what to do next 3e5772ccf9da

//! `oxy doctor` (spec §19.1): check what commonly goes wrong around a

//! repository, the identity, the configuration and the remotes, and say

//! what to do about each problem. It changes nothing.

use super::*;

#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]

pub enum Health {

    Ok,

    Warn,

    Fail,

}

#[derive(Clone, Debug, PartialEq, Eq)]

pub struct Check {

    /// What the check is about: `repository`, `identity`, `author`, `remote NAME`.

    pub area: String,

    pub health: Health,

    pub message: String,

    /// The next step, for a warning or failure.

    pub hint: Option<String>,

}

#[derive(Clone, Debug, Default, PartialEq, Eq)]

pub struct DoctorReport {

    pub checks: Vec<Check>,

}

impl DoctorReport {

    pub fn worst(&self) -> Health {

        self.checks

            .iter()

            .map(|c| c.health)

            .max()

            .unwrap_or(Health::Ok)

    }

    fn push(

        &mut self,

        area: impl Into<String>,

        health: Health,

        message: impl Into<String>,

        hint: Option<String>,

    ) {

        self.checks.push(Check {

            area: area.into(),

            health,

            message: message.into(),

            hint,

        });

    }

}

/// A lock file older than this is left over from a process that died.

const STALE_LOCK_SECS: u64 = 60;

impl Repo {

    /// Run every check; `online` also contacts each remote.

    pub fn doctor(&self, online: bool) -> DoctorReport {

        let mut rep = DoctorReport::default();

        self.doctor_repository(&mut rep);

        self.doctor_identity(&mut rep);

        self.doctor_author(&mut rep);

        for name in self.config.remotes.keys() {

            self.doctor_remote(&mut rep, name, online);

        }

        if self.config.remotes.is_empty() && !self.bare {

            rep.push("remotes", Health::Ok, "none configured", None);

        }

        rep

    }

    fn doctor_repository(&self, rep: &mut DoctorReport) {

        match self.head_op() {

            Ok(_) => rep.push(

                "repository",

                Health::Ok,

                format!(

                    "{} at {}",

                    if self.bare {

                        "bare repository"

                    } else {

                        "repository"

                    },

                    self.root.display()

                ),

                None,

            ),

            Err(e) => rep.push(

                "repository",

                Health::Fail,

                format!("the operation log does not open: {e}"),

                Some("run `oxy fsck` for details".into()),

            ),

        }

        let mut locks = vec![self.oxy.join("ops").join("lock")];

        if let Ok(rd) = fs::read_dir(self.oxy.join("workspaces")) {

            locks.extend(rd.flatten().map(|e| e.path().join("lock")));

        }

        for lock in locks {

            let age = fs::metadata(&lock)

                .and_then(|m| m.modified())

                .ok()

                .and_then(|t| t.elapsed().ok());

            if let Some(age) = age.filter(|a| a.as_secs() > STALE_LOCK_SECS) {

                rep.push(

                    "repository",

                    Health::Warn,

                    format!(

                        "a lock left by a process that stopped {} s ago: {}",

                        age.as_secs(),

                        lock.display()

                    ),

                    Some(

                        "it is taken over automatically; delete it if no oxy command is running"

                            .into(),

                    ),

                );

            }

        }

    }

    fn doctor_identity(&self, rep: &mut DoctorReport) {

        let Some(key) = self.config.author_key else {

            rep.push(

                "identity",

                Health::Warn,

                "no signing identity: pushes to a repository with a trust policy will be refused",

                Some("create one with `oxy identity create`".into()),

            );

            return;

        };

        let id = match self.identity(&key) {

            Ok(id) => id,

            Err(e) => {

                rep.push(

                    "identity",

                    Health::Fail,

                    format!(

                        "identity {} is configured but cannot be read: {e}",

                        key.short(12)

                    ),

                    Some("restore it, or create a new one with `oxy identity create`".into()),

                );

                return;

            }

        };

        let secret = self.keys_dir.join(format!("{}.secret", key.to_hex()));

        if !secret.is_file() {

            rep.push(

                "identity",

                Health::Fail,

                format!("the secret key for {} is missing ({})", key.short(12), secret.display()),

                Some("copy the key file back from a backup; without it nothing can be signed with this identity".into()),

            );

            return;

        }

        let now = Hlc::now().wall_ms;

        match id.expires {

            Some(t) if t <= now => rep.push(

                "identity",

                Health::Fail,

                format!("{} <{}> expired", id.name, id.email),

                Some("renew it with `oxy identity renew`".into()),

            ),

            Some(t) if t - now < 30 * 86_400_000 => rep.push(

                "identity",

                Health::Warn,

                format!(

                    "{} <{}> expires in {} days",

                    id.name,

                    id.email,

                    (t - now) / 86_400_000

                ),

                Some("renew it with `oxy identity renew`".into()),

            ),

            _ => rep.push(

                "identity",

                Health::Ok,

                format!("{} <{}> ({})", id.name, id.email, key.short(12)),

                None,

            ),

        }

    }

    fn doctor_author(&self, rep: &mut DoctorReport) {

        let defaulted =

            self.config.author_email.ends_with("@localhost") || self.config.author_name.is_empty();

        if defaulted {

            rep.push(

                "author",

                Health::Warn,

                format!("changes are authored as {} <{}>, a default", self.config.author_name, self.config.author_email),

                Some("set yours with `oxy config --user author.name NAME` and `oxy config --user author.email EMAIL`".into()),

            );

        } else {

            rep.push(

                "author",

                Health::Ok,

                format!("{} <{}>", self.config.author_name, self.config.author_email),

                None,

            );

        }

    }

    fn doctor_remote(&self, rep: &mut DoctorReport, name: &str, online: bool) {

        let area = format!("remote {name}");

        let url = &self.config.remotes[name];

        let opts = self.remote_options(name);

        let http = url.starts_with("http://") || url.starts_with("https://");

        let hint = |h: &str| Some(h.replace("<remote>", name));

        if url.starts_with("http://") && !is_loopback(url) {

            rep.push(

                &area,

                Health::Warn,

                format!("{url} is plain HTTP: the token travels unencrypted"),

                hint("use the hub's https:// address"),

            );

        }

        if http && opts.token.is_none() {

            rep.push(

                &area,

                Health::Warn,

                "no token: fetching public repositories works, pushing will not",

                hint("set one with `oxy config remote.<remote>.token TOKEN`"),

            );

        }

        if let Some(ca) = &opts.ca {

            if !ca.is_file() {

                rep.push(&area, Health::Fail, format!("the CA file {} does not exist", ca.display()), hint("download the hub's certificate from /.well-known/oxyhub-ca.pem and run `oxy config remote.<remote>.ca FILE`"));

                return;

            }

        }

        if !online {

            rep.push(&area, Health::Ok, format!("{url} (not contacted)"), None);

            return;

        }

        let reached = crate::protocol::open_remote(url, &opts).and_then(|r| r.repo_id());

        match reached {

            Ok(theirs) if theirs == crate::protocol::UNBOUND_ID => rep.push(

                &area,

                Health::Ok,

                format!("{url} is reachable and empty; the first push binds it"),

                None,

            ),

            Ok(theirs) if self.id().is_ok_and(|mine| mine == theirs) => rep.push(

                &area,

                Health::Ok,

                format!("{url} is reachable and is this repository"),

                None,

            ),

            Ok(_) => rep.push(

                &area,

                Health::Fail,

                format!("{url} is a different repository"),

                hint("check the URL; each repository has its own id"),

            ),

            Err(e) => {

                let msg = e.to_string();

                let first = msg.lines().next().unwrap_or(&msg).to_string();

                rep.push(

                    &area,

                    Health::Fail,

                    first,

                    crate::protocol::hint_for(&msg).map(|h| h.replace("<remote>", name)),

                );

            }

        }

    }

}

fn is_loopback(url: &str) -> bool {

    let host = url

        .split("://")

        .nth(1)

        .unwrap_or("")

        .split(['/', ':'])

        .next()

        .unwrap_or("");

    host == "localhost" || host == "127.0.0.1" || host == "[::1]"

}

                let msg = format!("{url}: HTTP {code}: {}", text.trim());

                Err(RepoError::Msg(with_hint(msg)))

            // The transport error already names the URL.

            Err(e) => Err(RepoError::Msg(with_hint(e.to_string()))),

/// What to do about a failed request, recognised from its message.

pub fn hint_for(message: &str) -> Option<&'static str> {

    let m = message.to_ascii_lowercase();

    let hint = if m.contains("http 401") {

        "the server did not accept the token: set one with `oxy config remote.<remote>.token TOKEN` (a personal access token; pushing needs repo:write)"

    } else if m.contains("http 403") {

        "the token or account lacks permission: pushing needs a token with repo:write and write access to the repository"

    } else if m.contains("http 404") {

        "nothing at this URL: check the owner and repository name, or create the repository on the hub first"

    } else if m.contains("unknownissuer")

        || m.contains("unknown issuer")

        || m.contains("certificate")

        || m.contains("invalidcertificate")

    {

        "the server's certificate is not trusted: for a hub with a self-signed certificate, download it from /.well-known/oxyhub-ca.pem on the hub and run `oxy config remote.<remote>.ca FILE`"

    } else if m.contains("connection refused") {

        "nothing is listening there: check the URL and port, and that the server is running"

    } else if m.contains("dns")

        || m.contains("failed to lookup")

        || m.contains("name or service not known")

    {

        "the host name does not resolve: check the URL"

    } else if m.contains("timed out") || m.contains("timeout") {

        "the server did not answer in time: check the network, or try again"

    } else {

        return None;

    };

    Some(hint)

}

/// `message`, followed by what to do about it when that is known.

pub fn with_hint(message: String) -> String {

    match hint_for(&message) {

        Some(h) => format!("{message}\n  hint: {h}"),

        None => message,

    }

}

            Err(RepoError::Msg(with_hint(format!(

            ))))

        // The transport error already names the URL.

        Err(e) => Err(RepoError::Msg(with_hint(e.to_string()))),

mod doctor;

pub use doctor::{Check, DoctorReport, Health};

            "no oxy repository found at or above {}; start one with `oxy init` or `oxy clone URL`",

            "remote {remote_name:?} is a different repository (repository IDs differ); check its URL with `oxy remote list`"

    pub(crate) fn remote_options(&self, name: &str) -> RemoteOptions {

                        "{remote_name}/{}: attested by {}, which the policy does not authorize for this bookmark; a policy owner can grant it with `oxy policy grant`",

                    "the remote has change {} which you do not; pull first (`oxy pull {remote_name}`), then push again",

#[test]

fn failed_requests_come_with_a_next_step() {

    use crate::protocol::hint_for;

    assert!(hint_for("https://h/x/oxy/v1/push: HTTP 401: bad token")

        .unwrap()

        .contains("token"));

    assert!(hint_for("…: HTTP 403: forbidden")

        .unwrap()

        .contains("repo:write"));

    assert!(hint_for("…: HTTP 404: no such repository")

        .unwrap()

        .contains("owner and repository name"));

    assert!(hint_for("invalid peer certificate: UnknownIssuer")

        .unwrap()

        .contains("oxyhub-ca.pem"));

    assert!(hint_for("Connect error: Connection refused (os error 111)")

        .unwrap()

        .contains("running"));

    assert!(hint_for("Dns Failed: failed to lookup address information")

        .unwrap()

        .contains("resolve"));

    assert_eq!(hint_for("something else entirely"), None);

}

#[test]

fn doctor_names_problems_and_what_to_do() {

    hermetic();

    let dir = tempfile::tempdir().unwrap();

    let root = dir.path();

    let origin = root.join("origin");

    Repo::init_bare_unbound(&origin).unwrap();

    let mut repo = Repo::init(&root.join("r"))

        .unwrap()

        .with_home(root.join("home"));

    let find = |r: &DoctorReport, area: &str, h: Health| {

        r.checks

            .iter()

            .find(|c| c.area == area && c.health == h)

            .cloned()

    };

    let r = repo.doctor(true);

    assert!(find(&r, "identity", Health::Warn)

        .unwrap()

        .hint

        .unwrap()

        .contains("oxy identity create"));

    assert!(find(&r, "repository", Health::Ok).is_some());

    repo.create_identity("Ada", "[email protected]", IdentityScope::Repo)

        .unwrap();

    repo.config.set("author.name", "Ada").unwrap();

    repo.config.set("author.email", "[email protected]").unwrap();

    repo.config

        .set("remote.origin.url", &origin.to_string_lossy())

        .unwrap();

    repo.config

        .set("remote.down.url", "http://127.0.0.1:9/a/b")

        .unwrap();

    repo.config.set("remote.down.token", "t").unwrap();

    repo.config

        .set("remote.badca.url", "https://example.invalid/a/b")

        .unwrap();

    repo.config

        .set(

            "remote.badca.ca",

            &root.join("missing.pem").to_string_lossy(),

        )

        .unwrap();

    repo.save_config().unwrap();

    let r = repo.doctor(true);

    assert!(find(&r, "identity", Health::Ok).is_some(), "{r:?}");

    assert!(find(&r, "author", Health::Ok).is_some(), "{r:?}");

    assert!(find(&r, "remote origin", Health::Ok)

        .unwrap()

        .message

        .contains("first push binds it"));

    let down = find(&r, "remote down", Health::Fail).unwrap();

    assert!(

        down.hint.as_deref().unwrap_or("").contains("running"),

        "{down:?}"

    );

    let badca = find(&r, "remote badca", Health::Fail).unwrap();

    assert!(

        badca.hint.unwrap().contains("remote.badca.ca"),

        "the remote's own name is in the hint"

    );

    assert_eq!(r.worst(), Health::Fail);

    // Offline, nothing is contacted.

    let r = repo.doctor(false);

    assert!(find(&r, "remote down", Health::Fail).is_none());

    assert!(find(&r, "remote down", Health::Ok)

        .unwrap()

        .message

        .contains("not contacted"));

}

oxy doctor          # check identity, config and remotes, with what to do about each problem

### 21.2 Doctor

`oxy doctor` checks what commonly stands between a user and a working repository and says, for each problem, what to do next: the operation log opens and no lock was left by a dead process; the signing identity exists, its secret key file is present, and it has not expired (a warning within 30 days); the author name and email are not the defaults; and for each remote, that plain `http://` is only used on loopback, a token is set, the CA file exists, and (unless `--offline`) the remote answers and is this repository or an unbound one. Failures of remote requests anywhere in `oxy` carry the same next step (an untrusted certificate, a rejected or insufficient token, no repository at the URL, nothing listening, an unknown host, a timeout). The exit status is 1 when a check fails; `--json` gives the checks.

oxy doctor [--offline] [--json]     check identity, config and remotes (§21.2)

*Changelog.* Draft 0.8h (2026-09-28): `oxy fsck` (§21.1); durability rules and the operation head as commit point (§13.6); the operation head moves by compare-and-swap and concurrent operations are merged (§12.1); `oxy doctor` (§21.2). Draft 0.8g (2026-09-27): delegates of a rule's identities may sign reference attestations (§14.5); local-path pushes bind unbound repositories like HTTP ones. Draft 0.8f (2026-09-27): challenge signatures (§14.3) for hosts. Draft 0.8e (2026-09-27): anonymous changes (zero author) are authenticated by a seal from any key, so imported and pre-identity history can be pushed under a policy (§14.4). Draft 0.8d (2026-09-27): unbound hosted repositories adopt the first pusher's id (§16.1). Draft 0.8c (2026-09-27): bare repositories (`oxy init --bare`, §12.2: no workspace, no working copy; hosting) and the reference server as an embeddable library (§15.1). Draft 0.8b (2026-09-27): the machine interface for editors (§24): `root`, `cat`, `version`, `hunks`, `discard`, and `--json` on the reporting commands.

    /// Check the identity, configuration and remotes, and say what to do about any problem

    Doctor {

        /// Do not contact the remotes

        #[arg(long)]

        offline: bool,

        #[arg(long)]

        json: bool,

    },

        Cmd::Doctor { offline, json } => workspace::doctor(offline, json),

/// `oxy doctor`: exit 1 when a check fails, 0 otherwise (warnings allowed).

pub fn doctor(offline: bool, as_json: bool) -> Result<i32> {

    use oxy_core::repo::Health;

    let repo = open()?;

    let sp = ui::spinner(if offline {

        "Checking…"

    } else {

        "Checking, and contacting remotes…"

    });

    let r = repo.doctor(!offline);

    sp.clear();

    let code = if r.worst() == Health::Fail { 1 } else { 0 };

    let word = |h: Health| match h {

        Health::Ok => "ok",

        Health::Warn => "warning",

        Health::Fail => "fail",

    };

    if as_json {

        let checks: Vec<String> = r

            .checks

            .iter()

            .map(|c| {

                json::obj([

                    ("area", json::s(&c.area)),

                    ("health", json::s(word(c.health))),

                    ("message", json::s(&c.message)),

                    ("hint", json::opt(c.hint.as_deref(), json::s)),

                ])

            })

            .collect();

        println!(

            "{}",

            json::obj([("ok", json::b(code == 0)), ("checks", json::arr(checks))])

        );

        return Ok(code);

    }

    let mut last = "";

    for c in &r.checks {

        if c.area != last {

            println!("{}", ui::section(&c.area));

            last = &c.area;

        }

        let mark = match c.health {

            Health::Ok => ui::ok(ui::glyph("✔", "v")),

            Health::Warn => ui::caution(),

            Health::Fail => ui::err(ui::glyph("✖", "x")),

        };

        println!("  {mark} {}", c.message);

        if let Some(h) = &c.hint {

            println!("    {} {}", ui::dim("→"), ui::dim(h));

        }

    }

    let fails = r.checks.iter().filter(|c| c.health == Health::Fail).count();

    let warns = r.checks.iter().filter(|c| c.health == Health::Warn).count();

    if fails + warns == 0 {

        println!("{}", ui::done("Everything looks right."));

    } else {

        println!(

            "{} {}, {}.",

            if fails > 0 {

                ui::err(ui::glyph("✖", "x"))

            } else {

                ui::caution()

            },

            plural(fails, "problem"),

            plural(warns, "warning")

        );

    }

    Ok(code)

}