@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/capabilities/doctor/doctor.render.test.ts

@@ -0,0 +1,170 @@
+/**
+ * Render goldens for `pragma doctor` — the band-grouped report AND the plain-path
+ * color gate (F1).
+ *
+ * The banded Global/Project grouping (`partitionByBand` → sections) is pinned for
+ * both the plain and llm formatters, locking the unified Global/Project
+ * vocabulary (the report no longer says MACHINE/PROJECT). Separately, the plain
+ * formatter tints ONLY on a color-capable TTY: `supports-color` reports a
+ * non-zero `chalk.level` off a TTY under `GITHUB_ACTIONS` / `FORCE_COLOR`, so the
+ * `isTTY` gate (via the shared style seam) keeps ANSI out of
+ * `doctor --format plain | tee`. `beforeEach` forces color OFF so the banded
+ * goldens stay deterministic; the color tests opt a level back in explicitly.
+ */
+
+import chalk from "chalk";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { doctorFormatters } from "./doctor.render.js";
+import type { DoctorData } from "./types.js";
+
+/** A fixture spanning all three groups: environment (no band), global, project. */
+const BANDED_DATA: DoctorData = {
+  checks: [
+    { name: "Node version", status: "pass", detail: "v20 detected" },
+    {
+      name: "Shell completions",
+      status: "pass",
+      detail: "zsh installed and resolving",
+      band: "global",
+    },
+    {
+      name: "MCP configured",
+      status: "fail",
+      detail: "detected Windsurf but pragma not configured",
+      remedy: "pragma setup mcp",
+      band: "global",
+    },
+    {
+      name: "Skills symlinked",
+      status: "skip",
+      detail: "no AI harnesses detected",
+      band: "project",
+    },
+  ],
+  passed: 2,
+  failed: 1,
+  skipped: 1,
+};
+
+/** A fixture spanning pass/fail/skip, sub-items, and a remedy — every color path. */
+const COLOR_DATA: DoctorData = {
+  checks: [
+    { name: "Node version", status: "pass", detail: "v24" },
+    {
+      name: "package refs",
+      status: "fail",
+      detail: "3 configured, 0 locked",
+      items: [
+        { label: "core", status: "fail", detail: "unlocked" },
+        { label: "ui", status: "fail", detail: "unlocked" },
+      ],
+      remedy: "pragma sources update",
+    },
+    { name: "Skills symlinked", status: "skip", detail: "no harness" },
+  ],
+  passed: 1,
+  failed: 1,
+  skipped: 1,
+};
+
+/** Run `body` with stdout's `isTTY` forced to `value`, then restore it. */
+function withStdoutTty(value: boolean | undefined, body: () => void): void {
+  const stream = process.stdout as { isTTY?: boolean };
+  const saved = stream.isTTY;
+  stream.isTTY = value;
+  try {
+    body();
+  } finally {
+    stream.isTTY = saved;
+  }
+}
+
+let prevLevel: number;
+beforeAll(() => {
+  prevLevel = chalk.level;
+});
+beforeEach(() => {
+  chalk.level = 0; // color-free ⇒ deterministic text (color tests opt back in)
+});
+afterAll(() => {
+  chalk.level = prevLevel;
+});
+
+describe("doctor render — banded plain report", () => {
+  it("groups checks under Global then Project headers (unified labels)", () => {
+    const out = doctorFormatters.plain(BANDED_DATA);
+    const lines = out.split("\n");
+    // The two banded section headers use the unified Global/Project vocabulary.
+    expect(lines).toContain("Global");
+    expect(lines).toContain("Project");
+    // The superseded MACHINE/PROJECT labels are gone.
+    expect(out).not.toContain("MACHINE");
+    expect(out).not.toMatch(/^PROJECT$/m);
+  });
+
+  it("orders environment → Global → Project, banding each check correctly", () => {
+    const out = doctorFormatters.plain(BANDED_DATA);
+    // Environment check leads with no header; the two global-band checks sit
+    // under Global; the project-band check sits under Project.
+    const at = (needle: string): number => out.indexOf(needle);
+    expect(at("Node version")).toBeGreaterThanOrEqual(0);
+    expect(at("Node version")).toBeLessThan(at("Global"));
+    expect(at("Global")).toBeLessThan(at("Shell completions"));
+    expect(at("MCP configured")).toBeLessThan(at("Project"));
+    expect(at("Project")).toBeLessThan(at("Skills symlinked"));
+    // A failing banded check keeps its inline remedy under its band.
+    expect(out).toContain("fix: pragma setup mcp");
+    // The tally closes the report.
+    expect(out).toContain("2 passed");
+  });
+});
+
+describe("doctor render — banded llm report", () => {
+  it("groups checks under ### Global then ### Project headers", () => {
+    const out = doctorFormatters.llm(BANDED_DATA);
+    expect(out).toContain("### Global");
+    expect(out).toContain("### Project");
+    expect(out).not.toContain("### Machine");
+    const at = (needle: string): number => out.indexOf(needle);
+    // Environment leads (no section header), then the two banded sections.
+    expect(at("Node version")).toBeLessThan(at("### Global"));
+    expect(at("### Global")).toBeLessThan(at("Shell completions"));
+    expect(at("Shell completions")).toBeLessThan(at("### Project"));
+    expect(at("### Project")).toBeLessThan(at("Skills symlinked"));
+    expect(out).toContain("_2 passed, 1 failed, 1 skipped_");
+  });
+});
+
+describe("doctor render — json", () => {
+  it("is the exact DoctorData round-trip", () => {
+    expect(JSON.parse(doctorFormatters.json(BANDED_DATA))).toEqual(BANDED_DATA);
+  });
+});
+
+describe("doctor render — piped output is ANSI-free (F1)", () => {
+  it("plain emits ZERO ANSI off a TTY even when chalk reports color (CI/FORCE_COLOR)", () => {
+    chalk.level = 3;
+    withStdoutTty(undefined, () => {
+      const out = doctorFormatters.plain(COLOR_DATA);
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: asserting NO ESC byte survives
+      expect(out).not.toMatch(/\x1b\[/);
+      // The structural, color-free content still renders (glyphs, names, remedy).
+      expect(out).toContain("pragma doctor");
+      expect(out).toContain("✓  Node version");
+      expect(out).toContain("✗  package refs");
+      expect(out).toContain("○  Skills symlinked");
+      expect(out).toContain("↳ fix: pragma sources update");
+      expect(out).toContain("  1 passed · 1 failed · 1 skipped");
+    });
+  });
+});
+
+describe("doctor render — color ON (attended TTY)", () => {
+  it("plain tints the output on a color-capable TTY", () => {
+    chalk.level = 1;
+    withStdoutTty(true, () => {
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: asserting the literal ESC byte is the point
+      expect(doctorFormatters.plain(COLOR_DATA)).toMatch(/\x1b\[/);
+    });
+  });
+});

package/src/capabilities/doctor/doctor.render.ts

@@ -0,0 +1,198 @@
+/**
+ * Formatters for `pragma doctor` — plain (chalk on a TTY), llm (Markdown), json.
+ *
+ * Ported from the old shell's `doctor/formatters/doctor.ts`, retargeted at the
+ * kernel `Formatters` contract. The plain path is colored ONLY on a color-capable
+ * TTY: it consults the shared {@link defaultStyle} seam (stdout `isTTY` AND a
+ * non-zero chalk level), so a piped / redirected / CI run — where `supports-color`
+ * can report a level with no TTY (`GITHUB_ACTIONS`, `FORCE_COLOR`) — renders the
+ * plain form byte-for-byte instead of leaking ANSI into `doctor --format plain`.
+ * Glyphs are plain constants tinted at render time; nothing is baked at load.
+ */
+
+import chalk from "chalk";
+import { defaultStyle, type RenderStyle } from "../../kernel/render/style.js";
+import type { Formatters } from "../../kernel/spec/types.js";
+import { BAND_LABELS } from "../shared/bands.js";
+import type { CheckResult, CheckStatus, DoctorData } from "./types.js";
+
+/** Uncolored status glyphs — tinted at render time (never baked at module load). */
+const STATUS_GLYPHS: Record<CheckStatus, string> = {
+  pass: "✓",
+  fail: "✗",
+  skip: "○",
+};
+
+const SUB_BULLET = "·";
+const FIX_ARROW = "↳";
+const INDENT = "     "; // aligns sub-lines under the check name
+
+/** The TTY styler plus `red` — the one tint {@link RenderStyle} does not carry. */
+interface DoctorStyle extends RenderStyle {
+  red(text: string): string;
+}
+
+/**
+ * Build the doctor styler for this process's stdout: the shared TTY seam, plus a
+ * `red` gated on the SAME decision, so a fail tint appears only on a color TTY.
+ *
+ * @returns A colorizing styler on a color-capable TTY, else the identity styler.
+ * @note Impure — {@link defaultStyle} reads `process.stdout.isTTY` + chalk level.
+ */
+function doctorStyle(): DoctorStyle {
+  const style = defaultStyle();
+  return {
+    ...style,
+    red: style.enabled ? (text) => chalk.red(text) : (text) => text,
+  };
+}
+
+/** Tint a status glyph by meaning — green pass, red fail, yellow skip. */
+function paintGlyph(status: CheckStatus, style: DoctorStyle): string {
+  const glyph = STATUS_GLYPHS[status];
+  if (status === "pass") return style.green(glyph);
+  if (status === "fail") return style.red(glyph);
+  return style.yellow(glyph);
+}
+
+/**
+ * Render one check as terminal lines: a headline row (icon, aligned name,
+ * detail), an optional indented breakdown of sub-items, and — for failures — an
+ * inline remedial instruction.
+ */
+function formatCheckPlain(
+  check: CheckResult,
+  nameWidth: number,
+  style: DoctorStyle,
+): string[] {
+  const name = check.name.padEnd(nameWidth);
+  const label = check.status === "fail" ? style.red(name) : style.bold(name);
+  const lines = [
+    `  ${paintGlyph(check.status, style)}  ${label}  ${style.dim(check.detail)}`,
+  ];
+
+  if (check.items && check.items.length > 0) {
+    const itemWidth = Math.max(...check.items.map((i) => i.label.length));
+    const anyStatus = check.items.some((i) => i.status !== undefined);
+    for (const item of check.items) {
+      const icon = anyStatus
+        ? item.status
+          ? `${paintGlyph(item.status, style)} `
+          : "  "
+        : "";
+      const itemLabel = item.detail ? item.label.padEnd(itemWidth) : item.label;
+      const detail = item.detail ? `  ${style.dim(item.detail)}` : "";
+      lines.push(
+        `${INDENT}${style.dim(SUB_BULLET)} ${icon}${itemLabel}${detail}`,
+      );
+    }
+  }
+
+  if (check.status === "fail" && check.remedy) {
+    lines.push(
+      `${INDENT}${style.cyan(FIX_ARROW)} ${style.cyan("fix:")} ${check.remedy}`,
+    );
+  }
+
+  return lines;
+}
+
+/** Render the pass/fail/skip tally, coloring non-zero fail/skip. */
+function formatSummary(data: DoctorData, style: DoctorStyle): string {
+  const parts = [style.green(`${data.passed} passed`)];
+  parts.push(
+    data.failed > 0
+      ? style.red(`${data.failed} failed`)
+      : style.dim(`${data.failed} failed`),
+  );
+  parts.push(
+    data.skipped > 0
+      ? style.yellow(`${data.skipped} skipped`)
+      : style.dim(`${data.skipped} skipped`),
+  );
+  return `  ${parts.join(style.dim(" · "))}`;
+}
+
+/**
+ * Partition checks into ordered bands: environment (no band), then the global
+ * and project bands. Declaration order is preserved within each band, so the
+ * report stays deterministic.
+ */
+function partitionByBand(checks: readonly CheckResult[]): {
+  environment: CheckResult[];
+  machine: CheckResult[];
+  project: CheckResult[];
+} {
+  return {
+    environment: checks.filter((c) => c.band === undefined),
+    machine: checks.filter((c) => c.band === "global"),
+    project: checks.filter((c) => c.band === "project"),
+  };
+}
+
+export const doctorFormatters: Formatters<DoctorData> = {
+  plain(data) {
+    const style = doctorStyle();
+    const nameWidth = Math.max(...data.checks.map((c) => c.name.length), 0);
+    const lines: string[] = [style.bold("pragma doctor"), ""];
+    const { environment, machine, project } = partitionByBand(data.checks);
+    const section = (heading: string, checks: CheckResult[]): void => {
+      if (checks.length === 0) return;
+      if (heading) lines.push(style.bold(heading));
+      for (const check of checks)
+        lines.push(...formatCheckPlain(check, nameWidth, style));
+      lines.push("");
+    };
+    // Environment checks lead (no header); the global then project bands are the
+    // two banded sections before the tally.
+    section("", environment);
+    section(BAND_LABELS.global, machine);
+    section(BAND_LABELS.project, project);
+    lines.push(formatSummary(data, style));
+    return lines.join("\n");
+  },
+
+  llm(data) {
+    const renderCheck = (check: CheckResult): string[] => {
+      const icon =
+        check.status === "pass" ? "✓" : check.status === "fail" ? "✗" : "○";
+      const out = [`- ${icon} **${check.name}**: ${check.detail}`];
+      for (const item of check.items ?? []) {
+        const itemIcon =
+          item.status === "pass"
+            ? "✓ "
+            : item.status === "fail"
+              ? "✗ "
+              : item.status === "skip"
+                ? "○ "
+                : "";
+        const detail = item.detail ? `: ${item.detail}` : "";
+        out.push(`  - ${itemIcon}${item.label}${detail}`);
+      }
+      if (check.status === "fail" && check.remedy) {
+        out.push(`  - _fix:_ \`${check.remedy}\``);
+      }
+      return out;
+    };
+
+    const lines: string[] = ["## Doctor", ""];
+    const { environment, machine, project } = partitionByBand(data.checks);
+    const section = (heading: string, checks: CheckResult[]): void => {
+      if (checks.length === 0) return;
+      if (heading) lines.push(`### ${heading}`, "");
+      for (const check of checks) lines.push(...renderCheck(check));
+    };
+    section("", environment);
+    section(BAND_LABELS.global, machine);
+    section(BAND_LABELS.project, project);
+    lines.push(
+      "",
+      `_${data.passed} passed, ${data.failed} failed, ${data.skipped} skipped_`,
+    );
+    return lines.join("\n");
+  },
+
+  json(data) {
+    return JSON.stringify(data);
+  },
+};

package/src/capabilities/doctor/doctor.test.ts

@@ -0,0 +1,209 @@
+/**
+ * `pragma doctor` — the nine environment health checks.
+ *
+ * Runs against isolated HOME/cwd/XDG so the harness/config/completion checks are
+ * deterministic (no harnesses, no config, no rc files). Covers the shape, a
+ * representative pass/fail/skip spread, the store check (down via an injected
+ * throwing store; up via the canonical fixture), exit 0 despite failures, and
+ * the MCP read-only envelope.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type { ConfigLayers } from "../../kernel/config/types.js";
+import { executeVerb } from "../../kernel/project/cli/dispatch.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import { createQueryFacade } from "../../kernel/runtime/facade.js";
+import type {
+  GlobalFlags,
+  LazyStore,
+  PragmaRuntime,
+} from "../../kernel/runtime/types.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import {
+  ALL_VISIBLE_CONFIG,
+  CANONICAL_TTL,
+} from "../../testing/fixtures/graph/canonical.js";
+import { bootFixtureRuntime } from "../../testing/helpers/fixtureGraph.js";
+import { projectMcp } from "../../testing/helpers/projectMcp.js";
+import { checkMcpConfigured } from "./checks/checkMcpConfigured.js";
+import { doctorModule } from "./index.js";
+import { runChecks } from "./runChecks.js";
+import type { DoctorData } from "./types.js";
+
+const FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+const NO_MUT = { dryRun: false, undo: false, yes: false };
+const doctorVerb = doctorModule.verbs[0] as VerbSpec;
+
+const roots: string[] = [];
+const tmp = (prefix: string): string => {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+  roots.push(dir);
+  return dir;
+};
+
+let prevHome: string | undefined;
+let prevXdg: string | undefined;
+let prevPath: string | undefined;
+beforeEach(() => {
+  prevHome = process.env.HOME;
+  prevXdg = process.env.XDG_CONFIG_HOME;
+  prevPath = process.env.PATH;
+  // Empty HOME/XDG so `~`-based harness signals, rc files, and the global config
+  // are all absent — the harness/config/completion checks become deterministic.
+  process.env.HOME = tmp("pragma-doctor-home-");
+  process.env.XDG_CONFIG_HOME = tmp("pragma-doctor-xdg-");
+  // Point PATH at an empty dir so no harness `process` signal fires off the
+  // ambient PATH (e.g. a `claude`/`codex` binary on the CI/dev host) — keeping
+  // "no harnesses detected" deterministic regardless of what is installed.
+  process.env.PATH = tmp("pragma-doctor-path-");
+});
+afterEach(() => {
+  process.env.HOME = prevHome;
+  process.env.XDG_CONFIG_HOME = prevXdg;
+  process.env.PATH = prevPath;
+  for (const dir of roots) rmSync(dir, { recursive: true, force: true });
+  roots.length = 0;
+});
+
+const defaultLayers: ConfigLayers = {
+  config: { channel: "normal" },
+  origins: {
+    tier: "default",
+    channel: "default",
+    detail: "default",
+    packages: "default",
+    stories: "default",
+    prefixes: "default",
+    prompts: "default",
+  },
+  global: { path: "", exists: false },
+  project: { exists: false },
+};
+
+/** A runtime whose store fails to boot — for the store-down check path. */
+function throwingStoreRuntime(cwd: string): PragmaRuntime {
+  const store: LazyStore = {
+    get booted() {
+      return false;
+    },
+    async get() {
+      throw new Error("store down");
+    },
+    invalidate() {},
+  };
+  return {
+    cwd,
+    version: "9.9.9",
+    globalFlags: FLAGS,
+    loadConfig: async () => defaultLayers,
+    store,
+    query: createQueryFacade(store),
+  };
+}
+
+const byName = (data: DoctorData, name: string) =>
+  data.checks.find((c) => c.name === name);
+
+describe("doctor — shape & spread", () => {
+  it("returns 9 checks whose tallies sum, each with a valid status", async () => {
+    const data = await runChecks(bootRuntime(FLAGS, tmp("pragma-proj-")));
+    expect(data.checks).toHaveLength(9);
+    expect(data.passed + data.failed + data.skipped).toBe(9);
+    for (const check of data.checks) {
+      expect(["pass", "fail", "skip"]).toContain(check.status);
+    }
+    // Deterministic under the isolated env.
+    expect(byName(data, "Node version")?.status).toBe("pass");
+    // The 3 default-config packages are configured but not locked here → an
+    // attributable fail listing them, with the sources-update remedy.
+    const pkgRefs = byName(data, "package refs");
+    expect(pkgRefs?.status).toBe("fail");
+    expect(pkgRefs?.remedy).toBe("pragma sources update");
+    expect(pkgRefs?.items?.length).toBe(3);
+    // No harnesses in an empty HOME/cwd — attributable fail + skips.
+    expect(byName(data, "MCP configured")?.status).toBe("fail");
+    expect(byName(data, "Skills symlinked")?.status).toBe("skip");
+    expect(byName(data, "MCP commands")?.status).toBe("skip");
+    // No project/global config in the isolated XDG.
+    expect(byName(data, "pragma config")?.status).toBe("fail");
+  });
+});
+
+describe("doctor — the store check", () => {
+  it("a store that fails to boot is an attributable fail, not a crash", async () => {
+    const data = await runChecks(throwingStoreRuntime(tmp("pragma-proj-")));
+    expect(data.checks).toHaveLength(9);
+    const keStore = byName(data, "ke store");
+    expect(keStore?.status).toBe("fail");
+    expect(keStore?.remedy).toBeTruthy();
+  });
+
+  it("a booted store passes with an entity total", async () => {
+    const fixture = await bootFixtureRuntime({
+      ttl: CANONICAL_TTL,
+      config: ALL_VISIBLE_CONFIG,
+    });
+    const data = await runChecks(fixture.runtime);
+    const keStore = byName(data, "ke store");
+    expect(keStore?.status).toBe("pass");
+    expect(keStore?.detail).toMatch(/entities/);
+    await fixture.dispose();
+  });
+});
+
+describe("doctor — dispatch & MCP", () => {
+  it("exits 0 even when checks fail (failures live in the envelope)", async () => {
+    const outcome = await executeVerb(
+      doctorVerb,
+      {},
+      NO_MUT,
+      bootRuntime(FLAGS, tmp("pragma-proj-")),
+    );
+    expect(outcome.exitCode).toBe(0);
+  });
+
+  it("MCP doctor is read-only and returns the checks envelope", async () => {
+    const mcp = await projectMcp([doctorModule], tmp("pragma-proj-"));
+    const tools = await mcp.listTools();
+    const doctorTool = tools.find((t) => t.name === "doctor");
+    expect(
+      (doctorTool?.annotations as { readOnlyHint?: boolean } | undefined)
+        ?.readOnlyHint,
+    ).toBe(true);
+
+    const envelope = await mcp.callTool("doctor");
+    await mcp.cleanup();
+    expect(envelope.ok).toBe(true);
+    expect((envelope.data as DoctorData).checks).toHaveLength(9);
+  });
+});
+
+describe("doctor — MCP checks band by detected harness scope, not check name", () => {
+  it("bands a configured GLOBAL-scope harness (Windsurf) as global", async () => {
+    // Windsurf is a global-only harness whose MCP config lives in the home band.
+    // The old static map tagged every "MCP configured" result PROJECT; the fix
+    // derives the band from the harness's real scope, so this reports `global`.
+    const cwd = tmp("pragma-doctor-proj-");
+    mkdirSync(join(cwd, ".windsurf"), { recursive: true }); // ⇒ Windsurf detected
+    const home = process.env.HOME ?? "";
+    const wsDir = join(home, ".codeium", "windsurf");
+    mkdirSync(wsDir, { recursive: true });
+    writeFileSync(
+      join(wsDir, "mcp_config.json"),
+      JSON.stringify({ mcpServers: { pragma: { command: "pragma" } } }),
+    );
+
+    const check = await checkMcpConfigured(cwd);
+    expect(check.status).toBe("pass");
+    expect(check.detail).toContain("Windsurf");
+    expect(check.band).toBe("global"); // NOT the old static "project"
+  });
+});

package/src/capabilities/doctor/doctor.verb.ts

@@ -0,0 +1,46 @@
+/**
+ * The `doctor` verb spec (noun `doctor`, self-verb).
+ *
+ * A read (`mutates: false`) that declares `needsStore: false` — the covenant has
+ * neither flag — so the dispatcher never pre-boots the store. The one store
+ * check boots it lazily inside a try/catch, keeping doctor storeless-by-default
+ * while still reporting store health. `run` lazily imports the orchestrator, so
+ * building the tree pulls neither the checks nor `@canonical/harnesses`.
+ *
+ * Exit-code decision: doctor always exits 0 — failures live in the `{ failed }`
+ * envelope (agents read the data; CI greps it). See PARITY_GAP
+ * `doctor-exit-zero-with-failures`.
+ */
+
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { CapabilityModule, VerbSpec } from "../../kernel/spec/types.js";
+import { doctorFormatters } from "./doctor.render.js";
+import type { DoctorData } from "./types.js";
+
+const doctorVerb: VerbSpec<Record<string, unknown>, DoctorData> = {
+  path: ["doctor"],
+  summary: "Check environment health — Node, config, store, MCP, and skills.",
+  doc: "Runs nine diagnostic checks and reports pass/fail/skip with inline remedies. Storeless by default; the store check boots lazily and never fails the run.",
+  params: [],
+  output: { formatters: doctorFormatters },
+  examples: [
+    { cmd: "pragma doctor" },
+    { cmd: "pragma doctor --format json", note: "machine-readable checks" },
+  ],
+  capability: {
+    needsStore: false,
+    mutates: false,
+    mcp: {
+      expose: true,
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+  },
+  run: (_params, runtime) =>
+    import("./runChecks.js").then((m) => m.runChecks(runtime)),
+};
+
+/** The `doctor` capability module. */
+export const doctorModule: CapabilityModule = {
+  name: "doctor",
+  verbs: [asVerb(doctorVerb)],
+};

package/src/capabilities/doctor/index.ts

@@ -0,0 +1,6 @@
+/**
+ * The `doctor` capability barrel.
+ */
+
+export { doctorModule } from "./doctor.verb.js";
+export type { CheckResult, CheckStatus, DoctorData } from "./types.js";