A doctor: a tool's checks (ax-checks) with the state they judged, so a person and an agent read the same facts. It says what runs and since when, the versions and the last attempts, then what is wrong and the command that fixes it. DoctorReport is a checks report with doctor, at and state added, so whatever reads a checks report reads it.
npx shadcn@latest add ourostack/ouro-ui/ax-doctor#v1.3.344It installs lib/ouro/ax/doctor.ts, with ax-checks, ax-terminal. Its tests are ax-doctor-tests. Every item runs on Node 22.18 or later as it is copied: the files import each other as ./<file>.ts. The Ouro AX guide shows how they fit together.
Exports
agoText
How long ago, in a person's words: "just now", "40 s ago", "12 min ago", "3 h ago", "2 days ago". A time after now reads as "just now".
function agoText(at: number, now: number): stringExample:
agoText(Date.now() - 12 * 60_000, Date.now()); // "12 min ago"DOCTOR_VERSION
The version of the doctor's shape; --json carries it as doctor, beside the checks' ax.
const DOCTOR_VERSION: "doctor/1"doctorReport
The checks' report with what the doctor saw and when it looked. Its exit code is the checks' own.
function doctorReport(checks: ChecksReport, state: StateSection[], at: number): DoctorReportExample:
const report = doctorReport(await checks.run(facts), state(facts), Date.now());DoctorReport
The checks' report, with the doctor's version, when it looked and what it saw.
interface DoctorReport extends ChecksReport {
doctor: typeof DOCTOR_VERSION;
at: number;
state: StateSection[];
}doctorText
The report for a person: the checks' verdict on the first line (with the line under it that says what was not run), then what the doctor saw, section by section, then the problems, their fixes and the next steps, as checksText prints them. A section with no lines is left out.
function doctorText(report: DoctorReport, style: TerminalStyle, options?: { verbose?: boolean | undefined; command?: string | undefined; }): stringExample:
stdout.write(`${doctorText(report, terminalStyle(stdout, env), { command: "notes doctor", verbose })}\n`);isDoctorReport
Whether a value is a doctor report, such as the answer of an app's own doctor endpoint, with sections and lines doctorText can print.
function isDoctorReport(value: unknown): value is DoctorReportExample:
const asked = await probeHttp(`${serviceUrl}/api/doctor`);
if (asked.state === "up" && isDoctorReport(asked.body)) return asked.body;PartState
A doctor: a tool's checks (ax-checks) with the state they judged, so a person and an agent read the same facts. It says what runs and since when, the versions and the last attempts, then what is wrong and the command that fixes it. DoctorReport is a checks report with doctor, at and state added, so whatever reads a checks report reads it.
type PartState = "up" | "starting" | "stuck" | "down" | "absent";Example:
const report = doctorReport(await checks.run(facts), [{ id: "processes", label: "Processes", lines: [{ label: "Service", value: "up", state: "up", since: startedAt }] }], Date.now());
stdout.write(json ? JSON.stringify(report) : doctorText(report, terminalStyle(stdout, env), { command: "notes doctor" }));
process.exitCode = report.exitCode;StateLine
One fact: what it is, its value in words, and since when it has held (ms since the epoch) when that is known.
interface StateLine {
label: string;
value: string;
since?: number | null;
state?: PartState;
}StateSection
A group of facts under one heading: "Versions", "Processes", "Sign-in".
interface StateSection {
id: string;
label: string;
lines: StateLine[];
}
