Skip to main content

Ouro AX

ax-doctor

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.344

It 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): string

Example:

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): DoctorReport

Example:

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; }): string

Example:

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 DoctorReport

Example:

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[];
}