<!-- Generated by scripts/ax-docs.mts from the JSDoc in registry/ouro/ax/. Do not edit; run `pnpm run docs`. -->

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

```sh
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](ax.md) 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".

```ts
function agoText(at: number, now: number): string
```

Example:

```ts
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`.

```ts
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.

```ts
function doctorReport(checks: ChecksReport, state: StateSection[], at: number): DoctorReport
```

Example:

```ts
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.

```ts
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.

```ts
function doctorText(report: DoctorReport, style: TerminalStyle, options?: { verbose?: boolean | undefined; command?: string | undefined; }): string
```

Example:

```ts
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.

```ts
function isDoctorReport(value: unknown): value is DoctorReport
```

Example:

```ts
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.

```ts
type PartState = "up" | "starting" | "stuck" | "down" | "absent";
```

Example:

```ts
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.

```ts
interface StateLine {
  label: string;
  value: string;
  since?: number | null;
  state?: PartState;
}
```

### `StateSection`

A group of facts under one heading: "Versions", "Processes", "Sign-in".

```ts
interface StateSection {
  id: string;
  label: string;
  lines: StateLine[];
}
```
