@prismatic-io/lux 0.0.1

package/src/orchestrator/doctor.ts

@@ -0,0 +1,781 @@
+import { existsSync } from "node:fs";
+import { lstat } from "node:fs/promises";
+import { resolve } from "node:path";
+import { glob } from "tinyglobby";
+import { z } from "zod";
+import { RubricConfigSchema } from "../assertions/rubric/index.js";
+import type { EvalCase, Registry } from "../core/index.js";
+import { buildRegistryFromConfig, loadLuxConfig, type ResolvedLuxConfig } from "./config.js";
+import { type DiscoveredCase, type DiscoveryResult, discoverCases } from "./discover.js";
+import { cliIdentity, ExperimentCampaignPlanSchema, planExperimentCampaign } from "./experiment.js";
+import {
+  experimentCampaignMode,
+  loadExperimentCampaign,
+  resolveExperimentCampaignPath,
+} from "./experiment-loader.js";
+import { assertionConfigForSchema } from "./grading.js";
+import { loadEvalCase } from "./loader.js";
+import { validatePluginConfig, validatePluginConfigAsync } from "./validate-plugin-config.js";
+
+export const DoctorDiagnosticSchema = z
+  .object({
+    id: z.string(),
+    status: z.enum(["pass", "warn", "fail"]),
+    message: z.string(),
+    detail: z.string().optional(),
+  })
+  .strict();
+export type DoctorDiagnostic = z.infer<typeof DoctorDiagnosticSchema>;
+
+export const DoctorCampaignReportSchema = z
+  .object({
+    path: z.string(),
+    campaignId: z.string().optional(),
+    mode: z.enum(["experiment", "optimize"]).optional(),
+    plan: ExperimentCampaignPlanSchema.optional(),
+    error: z.string().optional(),
+  })
+  .strict();
+export type DoctorCampaignReport = z.infer<typeof DoctorCampaignReportSchema>;
+
+export const DoctorReportSchema = z
+  .object({
+    rootDir: z.string(),
+    ok: z.boolean(),
+    diagnostics: z.array(DoctorDiagnosticSchema),
+    campaigns: z.array(DoctorCampaignReportSchema),
+    summary: z
+      .object({
+        passed: z.number().int().nonnegative(),
+        warnings: z.number().int().nonnegative(),
+        failed: z.number().int().nonnegative(),
+      })
+      .strict(),
+  })
+  .strict();
+export type DoctorReport = z.infer<typeof DoctorReportSchema>;
+
+export const DoctorOptionsSchema = z
+  .object({
+    cwd: z.string().min(1),
+    campaigns: z.array(z.string()).optional(),
+  })
+  .strict();
+export type DoctorOptions = z.input<typeof DoctorOptionsSchema>;
+
+type CliTarget = { label: string; command: string };
+
+class DoctorRecorder {
+  readonly diagnostics: DoctorDiagnostic[] = [];
+  readonly campaigns: DoctorCampaignReport[] = [];
+
+  add(id: string, status: DoctorDiagnostic["status"], message: string, detail?: string): void {
+    this.diagnostics.push({ id, status, message, ...(detail ? { detail } : {}) });
+  }
+
+  finish(rootDir: string): DoctorReport {
+    return finishDoctorReport(rootDir, this.diagnostics, this.campaigns);
+  }
+}
+
+const firstLine = (error: unknown): string =>
+  (error instanceof Error ? error.message : String(error)).split("\n")[0] ?? String(error);
+
+const refName = (reference: unknown): string | undefined => {
+  if (typeof reference === "string") return reference;
+  if (!reference || typeof reference !== "object") return undefined;
+  const name = (reference as { name?: unknown }).name;
+  return typeof name === "string" ? name : undefined;
+};
+
+const refConfig = (reference: unknown): Record<string, unknown> =>
+  reference &&
+  typeof reference === "object" &&
+  (reference as { config?: unknown }).config &&
+  typeof (reference as { config: unknown }).config === "object"
+    ? ((reference as { config: Record<string, unknown> }).config ?? {})
+    : {};
+
+const rawRefConfig = (reference: unknown): unknown =>
+  reference && typeof reference === "object"
+    ? (reference as { config?: unknown }).config
+    : undefined;
+
+const mergeRecords = (base: unknown, local: unknown): unknown => {
+  if (
+    !base ||
+    typeof base !== "object" ||
+    Array.isArray(base) ||
+    !local ||
+    typeof local !== "object" ||
+    Array.isArray(local)
+  ) {
+    return local ?? base;
+  }
+  const merged: Record<string, unknown> = { ...(base as Record<string, unknown>) };
+  for (const [key, value] of Object.entries(local as Record<string, unknown>)) {
+    merged[key] = key in merged ? mergeRecords(merged[key], value) : value;
+  }
+  return merged;
+};
+
+const effectiveDriverReference = (local: unknown, fallback: unknown): unknown => {
+  if (!local) return fallback;
+  if (!fallback || refName(local) !== refName(fallback)) return local;
+  return {
+    name: refName(local),
+    config: mergeRecords(rawRefConfig(fallback), rawRefConfig(local)),
+  };
+};
+
+const caseDriverReferences = (local: unknown, config: ResolvedLuxConfig): unknown[] => {
+  const fallbacks = [
+    config.defaultDriver,
+    ...Object.values(config.profiles ?? {}).map((profile) => profile.driver),
+  ].filter((reference) => reference !== undefined);
+  if (!local) return [...new Set(fallbacks)];
+  if (fallbacks.length === 0) return [local];
+  const references = fallbacks.map((fallback) => effectiveDriverReference(local, fallback));
+  return [
+    ...new Map(references.map((reference) => [JSON.stringify(reference), reference])).values(),
+  ];
+};
+
+const driverCommand = (reference: unknown): string | undefined => {
+  const name = refName(reference);
+  const config = refConfig(reference);
+  if (name === "claude-code") {
+    return typeof config.command === "string" ? config.command : "claude";
+  }
+  if (name === "codex") return typeof config.command === "string" ? config.command : "codex";
+  if (name === "subprocess") {
+    return typeof config.command === "string" ? config.command : undefined;
+  }
+  return undefined;
+};
+
+const answererCommand = (reference: unknown): string | undefined => {
+  const name = refName(reference);
+  if (name !== "persona" && name !== "claude-code") return undefined;
+  const config = refConfig(reference);
+  if (typeof config.command === "string") return config.command;
+  return config.provider === "codex" ? "codex" : "claude";
+};
+
+const rubricCommands = (assertion: unknown, config: ResolvedLuxConfig): string[] => {
+  const rubric = RubricConfigSchema.parse(assertion);
+  const harnesses = [
+    config.harness,
+    ...Object.values(config.profiles ?? {}).map((profile) => profile.harness ?? config.harness),
+  ];
+  const commands = harnesses.map((harness) => {
+    const provider = rubric.provider ?? harness?.provider ?? "claude-code";
+    const inheritsHarness = rubric.provider === undefined || rubric.provider === harness?.provider;
+    if (rubric.command) return rubric.command;
+    if (inheritsHarness && harness?.command) return harness.command;
+    return provider === "codex" ? "codex" : "claude";
+  });
+  return [...new Set(commands)];
+};
+
+const configuredCliTargets = (config: ResolvedLuxConfig): CliTarget[] => {
+  const targets: CliTarget[] = [];
+  const add = (label: string, command: string | undefined): void => {
+    if (command) targets.push({ label, command });
+  };
+  add("default driver", driverCommand(config.defaultDriver));
+  add("default answerer", answererCommand(config.defaultAnswerer));
+  if (config.harness) {
+    add(
+      "default harness",
+      config.harness.command ?? (config.harness.provider === "codex" ? "codex" : "claude"),
+    );
+  }
+  for (const [id, profile] of Object.entries(config.profiles ?? {}).sort(([a], [b]) =>
+    a.localeCompare(b),
+  )) {
+    add(`profile '${id}' driver`, driverCommand(profile.driver ?? config.defaultDriver));
+    add(`profile '${id}' answerer`, answererCommand(profile.answerer ?? config.defaultAnswerer));
+    const harness = profile.harness ?? config.harness;
+    if (harness) {
+      add(
+        `profile '${id}' harness`,
+        harness.command ?? (harness.provider === "codex" ? "codex" : "claude"),
+      );
+    }
+  }
+  return targets.filter(
+    (target, index, all) =>
+      all.findIndex((candidate) => candidate.command === target.command) === index,
+  );
+};
+
+const placeholderPaths = (value: unknown, prefix = ""): string[] => {
+  if (typeof value === "string") {
+    return /\bYOUR_[A-Z0-9_]+\b/.test(value) ? [prefix || "<root>"] : [];
+  }
+  if (Array.isArray(value)) {
+    return value.flatMap((entry, index) => placeholderPaths(entry, `${prefix}[${index}]`));
+  }
+  if (!value || typeof value !== "object") return [];
+  return Object.entries(value).flatMap(([key, entry]) =>
+    placeholderPaths(entry, prefix ? `${prefix}.${key}` : key),
+  );
+};
+
+const discoverCampaignPaths = async (
+  config: ResolvedLuxConfig,
+  authored: readonly string[],
+): Promise<string[]> => {
+  if (authored.length > 0) {
+    return [
+      ...new Set(
+        await Promise.all(
+          authored.map((path) =>
+            resolveExperimentCampaignPath(config.rootDir, resolve(config.rootDir, path)),
+          ),
+        ),
+      ),
+    ];
+  }
+  const experimentsRoot = resolve(config.rootDir, "experiments");
+  if (!existsSync(experimentsRoot)) return [];
+  const rootInfo = await lstat(experimentsRoot);
+  if (rootInfo.isSymbolicLink() || !rootInfo.isDirectory()) {
+    throw new Error(`experiments root must be a real directory: ${experimentsRoot}`);
+  }
+  const discovered = (
+    await glob(["**/*.experiment.ts", "**/*.optimize.ts"], {
+      cwd: experimentsRoot,
+      onlyFiles: true,
+      followSymbolicLinks: false,
+    })
+  )
+    .map((path) => resolve(experimentsRoot, path))
+    .sort();
+  return Promise.all(discovered.map((path) => resolveExperimentCampaignPath(config.rootDir, path)));
+};
+
+const loadDoctorConfig = async (
+  cwd: string,
+  recorder: DoctorRecorder,
+): Promise<ResolvedLuxConfig | null> => {
+  try {
+    const config = await loadLuxConfig(cwd);
+    recorder.add(
+      "config",
+      config.configPath ? "pass" : "warn",
+      config.configPath ? `loaded ${config.configPath}` : "no Lux config; using defaults",
+    );
+    const placeholders = placeholderPaths(config);
+    if (placeholders.length > 0) {
+      recorder.add(
+        "config-placeholders",
+        "warn",
+        "configuration still contains starter placeholders",
+        placeholders.join(", "),
+      );
+    }
+    return config;
+  } catch (error) {
+    recorder.add("config", "fail", "Lux configuration is invalid", firstLine(error));
+    return null;
+  }
+};
+
+const loadDoctorRegistry = (
+  config: ResolvedLuxConfig,
+  recorder: DoctorRecorder,
+): Registry | null => {
+  try {
+    return buildRegistryFromConfig(config);
+  } catch (error) {
+    recorder.add("registry", "fail", "plugin registry is invalid", firstLine(error));
+    return null;
+  }
+};
+
+const configuredDriverReferences = (
+  config: ResolvedLuxConfig,
+): Array<readonly [string, unknown]> => [
+  ["default", config.defaultDriver],
+  ...Object.entries(config.profiles ?? {}).map(
+    ([id, profile]) => [`profile '${id}'`, profile.driver] as const,
+  ),
+];
+
+const configuredAnswererReferences = (
+  config: ResolvedLuxConfig,
+): Array<readonly [string, unknown]> => [
+  ["default", config.defaultAnswerer],
+  ...Object.entries(config.profiles ?? {}).map(
+    ([id, profile]) => [`profile '${id}'`, profile.answerer] as const,
+  ),
+];
+
+const validateConfiguredDrivers = (
+  config: ResolvedLuxConfig,
+  registry: Registry,
+  recorder: DoctorRecorder,
+): void => {
+  for (const [scope, reference] of configuredDriverReferences(config)) {
+    const name = refName(reference);
+    if (!name) continue;
+    const plugin = registry.getDriver(name);
+    if (!plugin) {
+      recorder.add(
+        `driver:${scope}:${name}`,
+        "fail",
+        `${scope} references unknown driver '${name}'`,
+      );
+      continue;
+    }
+    try {
+      validatePluginConfig(
+        plugin.configSchema,
+        rawRefConfig(reference),
+        `${scope} driver '${name}'`,
+      );
+    } catch (error) {
+      recorder.add(
+        `driver-config:${scope}:${name}`,
+        "fail",
+        `${scope} has invalid driver configuration`,
+        firstLine(error),
+      );
+    }
+  }
+};
+
+const validateConfiguredAnswerers = (
+  config: ResolvedLuxConfig,
+  registry: Registry,
+  recorder: DoctorRecorder,
+): void => {
+  for (const [scope, reference] of configuredAnswererReferences(config)) {
+    const name = refName(reference);
+    if (!name) continue;
+    const plugin = registry.getAnswerer(name);
+    if (!plugin) {
+      recorder.add(
+        `answerer:${scope}:${name}`,
+        "fail",
+        `${scope} references unknown answerer '${name}'`,
+      );
+      continue;
+    }
+    try {
+      validatePluginConfig(
+        plugin.configSchema,
+        rawRefConfig(reference),
+        `${scope} answerer '${name}'`,
+      );
+    } catch (error) {
+      recorder.add(
+        `answerer-config:${scope}:${name}`,
+        "fail",
+        `${scope} has invalid answerer configuration`,
+        firstLine(error),
+      );
+    }
+  }
+};
+
+const duplicateCaseIds = (cases: readonly DiscoveredCase[]): string[] => {
+  const counts = new Map<string, number>();
+  for (const discovered of cases) {
+    counts.set(discovered.id, (counts.get(discovered.id) ?? 0) + 1);
+  }
+  return [...counts]
+    .filter(([, count]) => count > 1)
+    .map(([id]) => id)
+    .sort();
+};
+
+const recordCaseDiscovery = (discovery: DiscoveryResult, recorder: DoctorRecorder): void => {
+  const count = discovery.cases.length;
+  recorder.add(
+    "cases",
+    count > 0 ? "pass" : "warn",
+    `discovered ${count} case${count === 1 ? "" : "s"}`,
+  );
+  for (const problem of discovery.problems) {
+    recorder.add(
+      `case:${problem.path}`,
+      "fail",
+      `case failed discovery: ${problem.path}`,
+      problem.reason,
+    );
+  }
+  const duplicates = duplicateCaseIds(discovery.cases);
+  if (duplicates.length > 0) {
+    recorder.add("case-ids", "fail", "case IDs must be unique", duplicates.join(", "));
+  }
+};
+
+const caseDriverFailure = (
+  caseId: string,
+  reference: unknown,
+  registry: Registry,
+): string | null => {
+  const name = refName(reference);
+  if (!name) return "driver reference has no name";
+  const plugin = registry.getDriver(name);
+  if (!plugin) return `unknown driver '${name}'`;
+  try {
+    validatePluginConfig(
+      plugin.configSchema,
+      rawRefConfig(reference),
+      `case '${caseId}' driver '${name}'`,
+    );
+    return null;
+  } catch (error) {
+    return firstLine(error);
+  }
+};
+
+const validateCaseDrivers = (
+  caseId: string,
+  drivers: readonly unknown[],
+  registry: Registry,
+  recorder: DoctorRecorder,
+): void => {
+  if (drivers.length === 0) {
+    recorder.add(
+      `case-driver:${caseId}`,
+      "fail",
+      `case '${caseId}' names no driver and no configured profile supplies one`,
+    );
+    return;
+  }
+  const failures = drivers
+    .map((driver) => caseDriverFailure(caseId, driver, registry))
+    .filter((failure): failure is string => failure !== null);
+  if (failures.length === drivers.length) {
+    recorder.add(
+      `case-driver-config:${caseId}`,
+      "fail",
+      `case '${caseId}' has no valid effective driver configuration`,
+      failures.join("; "),
+    );
+  }
+};
+
+const validateCaseAnswerer = (
+  caseId: string,
+  answerer: unknown,
+  registry: Registry,
+  recorder: DoctorRecorder,
+): void => {
+  const name = refName(answerer);
+  if (!name) return;
+  const plugin = registry.getAnswerer(name);
+  if (!plugin) {
+    recorder.add(
+      `case-answerer:${caseId}`,
+      "fail",
+      `case '${caseId}' references unknown answerer '${name}'`,
+    );
+    return;
+  }
+  try {
+    validatePluginConfig(
+      plugin.configSchema,
+      rawRefConfig(answerer),
+      `case '${caseId}' answerer '${name}'`,
+    );
+  } catch (error) {
+    recorder.add(
+      `case-answerer-config:${caseId}`,
+      "fail",
+      `case '${caseId}' has invalid answerer configuration`,
+      firstLine(error),
+    );
+  }
+};
+
+const validateCaseAssertions = async (
+  caseId: string,
+  authored: EvalCase,
+  config: ResolvedLuxConfig,
+  registry: Registry,
+  recorder: DoctorRecorder,
+): Promise<CliTarget[]> => {
+  const targets: CliTarget[] = [];
+  for (const assertion of authored.assertions ?? []) {
+    const implementation = registry.getAssertion(assertion.type);
+    if (!implementation) {
+      recorder.add(
+        `case-assertion:${caseId}:${assertion.type}`,
+        "fail",
+        `case '${caseId}' references unknown assertion '${assertion.type}'`,
+      );
+      continue;
+    }
+    try {
+      await validatePluginConfigAsync(
+        implementation.configSchema,
+        implementation.configSchema
+          ? assertionConfigForSchema(assertion, implementation.configSchema)
+          : assertion,
+        `case '${caseId}' assertion '${assertion.type}'`,
+      );
+    } catch (error) {
+      recorder.add(
+        `case-assertion-config:${caseId}:${assertion.type}`,
+        "fail",
+        `case '${caseId}' has invalid assertion configuration`,
+        firstLine(error),
+      );
+    }
+    if (assertion.type === "rubric") {
+      for (const command of rubricCommands(assertion, config)) {
+        targets.push({ label: `case '${caseId}' rubric judge`, command });
+      }
+    }
+  }
+  return targets;
+};
+
+const executionTargetsForCase = (
+  caseId: string,
+  drivers: readonly unknown[],
+  answerer: unknown,
+): CliTarget[] => {
+  const targets = drivers.flatMap((driver): CliTarget[] => {
+    const command = driverCommand(driver);
+    return command ? [{ label: `case '${caseId}' driver`, command }] : [];
+  });
+  const command = answererCommand(answerer);
+  if (command) targets.push({ label: `case '${caseId}' answerer`, command });
+  return targets;
+};
+
+const inspectCase = async (
+  discovered: DiscoveredCase,
+  config: ResolvedLuxConfig,
+  registry: Registry,
+  recorder: DoctorRecorder,
+): Promise<CliTarget[]> => {
+  try {
+    const authored = await loadEvalCase(discovered.path);
+    const drivers = caseDriverReferences(authored.driver, config);
+    const answerer = authored.answerer ?? config.defaultAnswerer;
+    validateCaseDrivers(discovered.id, drivers, registry, recorder);
+    validateCaseAnswerer(discovered.id, answerer, registry, recorder);
+    return [
+      ...(await validateCaseAssertions(discovered.id, authored, config, registry, recorder)),
+      ...executionTargetsForCase(discovered.id, drivers, answerer),
+    ];
+  } catch (error) {
+    recorder.add(
+      `case-preflight:${discovered.id}`,
+      "fail",
+      `case preflight failed: ${discovered.path}`,
+      firstLine(error),
+    );
+    return [];
+  }
+};
+
+const inspectCases = async (
+  config: ResolvedLuxConfig,
+  registry: Registry,
+  recorder: DoctorRecorder,
+): Promise<CliTarget[]> => {
+  if (!config.casesRoot) {
+    recorder.add("cases", "warn", "casesRoot is not configured");
+    return [];
+  }
+  try {
+    const discovery = await discoverCases(config.casesRoot);
+    recordCaseDiscovery(discovery, recorder);
+    const targets: CliTarget[] = [];
+    for (const discovered of discovery.cases) {
+      targets.push(...(await inspectCase(discovered, config, registry, recorder)));
+    }
+    return targets;
+  } catch (error) {
+    recorder.add("cases", "fail", "case discovery failed", firstLine(error));
+    return [];
+  }
+};
+
+const uniqueCliTargets = (targets: readonly CliTarget[]): CliTarget[] => {
+  const unique = new Map<string, CliTarget>();
+  for (const target of targets) {
+    if (!unique.has(target.command)) unique.set(target.command, target);
+  }
+  return [...unique.values()];
+};
+
+const inspectCliTarget = async (
+  target: CliTarget,
+  config: ResolvedLuxConfig,
+  recorder: DoctorRecorder,
+): Promise<void> => {
+  try {
+    const identity = await cliIdentity(target.command, config.rootDir);
+    recorder.add(
+      `cli:${target.command}`,
+      identity.version ? "pass" : "warn",
+      `${target.label} CLI '${target.command}' is executable`,
+      identity.version ? `version: ${identity.version}` : "version could not be determined",
+    );
+  } catch (error) {
+    recorder.add(
+      `cli:${target.command}`,
+      "fail",
+      `${target.label} CLI '${target.command}' is unavailable`,
+      firstLine(error),
+    );
+  }
+};
+
+const inspectCliTargets = async (
+  targets: readonly CliTarget[],
+  config: ResolvedLuxConfig,
+  recorder: DoctorRecorder,
+): Promise<void> => {
+  for (const target of uniqueCliTargets(targets)) {
+    await inspectCliTarget(target, config, recorder);
+  }
+};
+
+const isBlockingCampaignWarning = (warning: string): boolean =>
+  warning.includes("below confidence minSamples=") || warning.includes("cannot attain confidence");
+
+const inspectCampaign = async (
+  path: string,
+  config: ResolvedLuxConfig,
+  registry: Registry,
+  recorder: DoctorRecorder,
+): Promise<void> => {
+  try {
+    const loaded = await loadExperimentCampaign(path);
+    const mode = experimentCampaignMode(path, loaded.campaign);
+    const placeholders = placeholderPaths(loaded.campaign);
+    if (placeholders.length > 0) {
+      recorder.add(
+        `campaign-placeholders:${loaded.campaign.id}`,
+        "warn",
+        `campaign '${loaded.campaign.id}' contains starter placeholders`,
+        placeholders.join(", "),
+      );
+    }
+    const plan = await planExperimentCampaign({ config, registry, loaded }, mode);
+    recorder.campaigns.push({ path, campaignId: loaded.campaign.id, mode, plan });
+    recorder.add(
+      `campaign:${loaded.campaign.id}`,
+      plan.fitsProjectedCallBudgets ? "pass" : "fail",
+      `campaign '${loaded.campaign.id}' plans ${plan.projected.metricCalls} metric, ${plan.projected.judgeCalls} judge, and ${plan.projected.proposalCalls} proposal calls`,
+      plan.fitsProjectedCallBudgets ? undefined : "projected work exceeds the authored budget",
+    );
+    for (const [index, warning] of plan.warnings.entries()) {
+      const blocking = isBlockingCampaignWarning(warning);
+      recorder.add(
+        `campaign:${loaded.campaign.id}:${blocking ? "blocking" : "warning"}:${index}`,
+        blocking ? "fail" : "warn",
+        warning,
+      );
+    }
+  } catch (error) {
+    recorder.campaigns.push({ path, error: firstLine(error) });
+    recorder.add(
+      `campaign:${path}`,
+      "fail",
+      `campaign preflight failed: ${path}`,
+      firstLine(error),
+    );
+  }
+};
+
+const inspectCampaigns = async (
+  authoredPaths: readonly string[],
+  config: ResolvedLuxConfig,
+  registry: Registry,
+  recorder: DoctorRecorder,
+): Promise<void> => {
+  let paths: string[];
+  try {
+    paths = await discoverCampaignPaths(config, authoredPaths);
+  } catch (error) {
+    recorder.add(
+      "campaign-discovery",
+      "fail",
+      "experiment campaign discovery failed",
+      firstLine(error),
+    );
+    paths = [];
+  }
+  if (paths.length === 0) {
+    recorder.add(
+      "campaigns",
+      "warn",
+      "no experiment campaigns found",
+      "run `lux init --experiment`",
+    );
+  }
+  for (const path of paths) {
+    await inspectCampaign(path, config, registry, recorder);
+  }
+};
+
+export const doctorProject = async (options: DoctorOptions): Promise<DoctorReport> => {
+  const parsedOptions = DoctorOptionsSchema.parse(options);
+  const recorder = new DoctorRecorder();
+  const config = await loadDoctorConfig(parsedOptions.cwd, recorder);
+  if (!config) return recorder.finish(resolve(parsedOptions.cwd));
+
+  const registry = loadDoctorRegistry(config, recorder);
+  if (!registry) return recorder.finish(config.rootDir);
+
+  validateConfiguredDrivers(config, registry, recorder);
+  validateConfiguredAnswerers(config, registry, recorder);
+  const caseCliTargets = await inspectCases(config, registry, recorder);
+  await inspectCliTargets([...configuredCliTargets(config), ...caseCliTargets], config, recorder);
+  await inspectCampaigns(parsedOptions.campaigns ?? [], config, registry, recorder);
+  return recorder.finish(config.rootDir);
+};
+
+const finishDoctorReport = (
+  rootDir: string,
+  diagnostics: DoctorDiagnostic[],
+  campaigns: DoctorCampaignReport[],
+): DoctorReport => {
+  const summary = {
+    passed: diagnostics.filter((entry) => entry.status === "pass").length,
+    warnings: diagnostics.filter((entry) => entry.status === "warn").length,
+    failed: diagnostics.filter((entry) => entry.status === "fail").length,
+  };
+  return DoctorReportSchema.parse({
+    rootDir,
+    ok: summary.failed === 0,
+    diagnostics,
+    campaigns,
+    summary,
+  });
+};
+
+export const formatDoctorReport = (report: DoctorReport): string => {
+  const symbols = { pass: "✓", warn: "!", fail: "✗" } as const;
+  const terminalText = (value: string): string =>
+    [...value]
+      .map((character) => {
+        const code = character.codePointAt(0) ?? 0;
+        return code <= 0x1f || (code >= 0x7f && code <= 0x9f) ? " " : character;
+      })
+      .join("")
+      .replace(/\s+/g, " ")
+      .trim();
+  return [
+    `lux doctor — ${terminalText(report.rootDir)}`,
+    "",
+    ...report.diagnostics.flatMap((diagnostic) => [
+      `${symbols[diagnostic.status]} ${terminalText(diagnostic.message)}`,
+      ...(diagnostic.detail ? [`  ${terminalText(diagnostic.detail)}`] : []),
+    ]),
+    "",
+    `${report.ok ? "ready" : "not ready"}: ${report.summary.passed} passed, ${report.summary.warnings} warnings, ${report.summary.failed} failed`,
+  ].join("\n");
+};