@robota-sdk/agent-command 3.0.0-beta.79 → 3.0.0-beta.81

package/src/doctor/doctor-command-module.ts

@@ -0,0 +1,132 @@
+import { createSystemCommandFromEntry } from '../command-module-utils.js';
+/**
+ * `/doctor` — the interactive surface of the same runner the shell route uses (OBSERVABILITY-1991).
+ *
+ * `/doctor` renders the report; `/doctor repair <check-id>` confirms through the host's user
+ * interaction port and treats an absent port or a cancelled answer as "nothing written". Neither
+ * form creates a provider turn or submits user input: the command reads and, on explicit
+ * confirmation, runs one allowlisted writer.
+ */
+import { confirmAction } from '@robota-sdk/agent-core';
+
+import { createNodeDoctorDeps } from './doctor-node-deps.js';
+import { renderDoctorReport } from './doctor-render.js';
+import { applyDoctorRepair } from './doctor-repair.js';
+import { runDoctor } from './doctor-runner.js';
+
+import type { IDoctorRepairPlan } from './doctor-repair.js';
+import type { IDoctorDisplayVocabulary } from './doctor-render.js';
+import type { IDoctorDeps, IDoctorInputs } from './doctor-types.js';
+import type {
+  ICommandHostUserInteraction,
+  ICommandModule,
+  ISystemCommand,
+} from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandResult, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+export function createDoctorCommandEntry(): ICommand {
+  return {
+    name: 'doctor',
+    displayName: 'Doctor',
+    description:
+      'Diagnose configuration and runtime readiness; `repair <check-id>` applies an allowlisted fix',
+    source: 'doctor',
+    // User-only: install diagnostics and confirmed repairs that write settings are the user's.
+    modelInvocable: false,
+    userInvocable: true,
+    argumentHint: '[repair <check-id>]',
+  };
+}
+
+export class DoctorCommandSource implements ICommandSource {
+  readonly name = 'doctor';
+
+  getCommands(): ICommand[] {
+    return [createDoctorCommandEntry()];
+  }
+}
+
+async function confirmThroughHost(
+  context: ICommandHostUserInteraction,
+  plan: IDoctorRepairPlan,
+): Promise<boolean> {
+  const ui = context.getUserInteraction();
+  if (ui === undefined) return false;
+  const response = await ui.ask(
+    confirmAction(`doctor-repair:${plan.id}`, `Repair ${plan.id}?`, {
+      description: `${plan.description} (${plan.path})`,
+      defaultYes: false,
+    }),
+  );
+  return response.type === 'answer' && response.values[0] === 'yes';
+}
+
+async function executeRepair(
+  id: string,
+  inputs: IDoctorInputs,
+  deps: IDoctorDeps,
+  context: ICommandHostUserInteraction,
+  display: IDoctorDisplayVocabulary,
+): Promise<ICommandResult> {
+  const outcome = await applyDoctorRepair(id, inputs, deps, (plan) =>
+    confirmThroughHost(context, plan),
+  );
+  if (!outcome.applied) {
+    return { success: false, message: outcome.reason, data: { repair: id, applied: false } };
+  }
+  const report = await runDoctor(inputs, deps);
+  const check = report.checks.find((candidate) => candidate.id === id);
+  return {
+    success: true,
+    message: [
+      `Repaired ${id}: ${outcome.plan.description}.`,
+      ...renderDoctorReport(report, `${display.title ?? 'Doctor'} (after repair)`, display),
+    ].join('\n'),
+    data: { repair: id, applied: true, status: check?.status, exitCode: report.exitCode },
+  };
+}
+
+async function executeDoctorCommand(
+  inputs: IDoctorInputs,
+  deps: IDoctorDeps,
+  context: ICommandHostUserInteraction,
+  args: string,
+  display: IDoctorDisplayVocabulary,
+): Promise<ICommandResult> {
+  const [verb, target] = args.trim().split(/\s+/);
+  if (verb === 'repair') {
+    if (target === undefined || target.length === 0) {
+      return { success: false, message: 'Usage: /doctor repair <check-id>' };
+    }
+    return executeRepair(target, inputs, deps, context, display);
+  }
+  const report = await runDoctor(inputs, deps);
+  return {
+    success: report.failCount === 0,
+    message: renderDoctorReport(report, display.title, display).join('\n'),
+    data: {
+      failCount: report.failCount,
+      warnCount: report.warnCount,
+      repairable: [...report.repairable],
+    },
+  };
+}
+
+/** Register `/doctor` over the host-composed inputs; the host decides whether to supply them. */
+export function createDoctorCommandModule(
+  inputs: IDoctorInputs,
+  deps: IDoctorDeps = createNodeDoctorDeps({ ...inputs.env }),
+  display: IDoctorDisplayVocabulary = {},
+): ICommandModule {
+  const entry = createDoctorCommandEntry();
+  const command: ISystemCommand = createSystemCommandFromEntry(entry, {
+    requiresPermission: false,
+    lifecycle: 'inline',
+    execute: (context, args) => executeDoctorCommand(inputs, deps, context, args, display),
+  });
+  return {
+    name: 'agent-command-doctor',
+    commandSources: [new DoctorCommandSource()],
+    systemCommands: [command],
+  };
+}

package/src/doctor/doctor-extensions-probe.ts

@@ -0,0 +1,299 @@
+/**
+ * Plugin, skill, hook and MCP probes (OBSERVABILITY-1991) — each over the owner's inspection API.
+ *
+ * Statuses follow the spec: a plugin the user installed that cannot load is `fail`; a hooks.json the
+ * schema refuses is `warn` (report-only — the loader still loads it); an MCP structural fault is
+ * `warn` until the CLI has an MCP consumer; MCP connection and hook execution are the enumerated
+ * `not-probed` exclusions of a read-only doctor.
+ */
+import {
+  inspectSkillSources,
+  loadHostBundlePluginInspectionFromScopes,
+} from '@robota-sdk/agent-framework';
+
+import type { IDoctorCheck, IDoctorDeps, IDoctorInputs } from './doctor-types.js';
+import type {
+  IBundlePluginInspection,
+  IBundlePluginMcpServer,
+  ISettingsInspection,
+} from '@robota-sdk/agent-framework';
+
+const SKIP_CAUSE: Record<string, string> = {
+  'manifest-unreadable': 'manifest could not be parsed',
+  'manifest-invalid': 'manifest is not a valid plugin.json (name, version, description required)',
+  'load-failed': 'plugin assets could not be loaded',
+};
+
+function pluginChecks(inspections: readonly IBundlePluginInspection[]): IDoctorCheck[] {
+  const checks: IDoctorCheck[] = [];
+  const loaded = inspections.reduce((n, i) => n + i.loaded.length, 0);
+  const present = inspections.filter((i) => i.cacheDirPresent);
+  checks.push(
+    present.length === 0
+      ? {
+          id: 'plugins',
+          label: 'Plugins',
+          status: 'not-configured',
+          cause: 'no plugin cache directory',
+          detail: inspections.map((i) => i.pluginsDir),
+        }
+      : {
+          id: 'plugins',
+          label: 'Plugins',
+          status: 'ok',
+          cause: `${loaded} plugin(s) loaded`,
+          detail: present.map(
+            (i) => `${i.pluginsDir}: ${i.loaded.length} loaded, ${i.skipped.length} skipped`,
+          ),
+        },
+  );
+  for (const inspection of inspections) {
+    for (const skip of inspection.skipped) {
+      if (skip.reason === 'disabled') continue;
+      checks.push({
+        id: `plugin.${skip.pluginId}`,
+        label: 'Plugin',
+        status: 'fail',
+        path: skip.manifestPath,
+        cause: SKIP_CAUSE[skip.reason] ?? skip.reason,
+        ...(skip.detail === undefined ? {} : { detail: [skip.detail] }),
+      });
+    }
+    for (const issue of inspection.hookIssues) {
+      checks.push({
+        id: `plugin.${issue.pluginId}.hooks`,
+        label: 'Plugin hooks',
+        status: 'warn',
+        path: issue.hooksPath,
+        cause: `hooks.json fails the hooks schema: ${issue.issues.map((i) => `${i.path} (${i.code})`).join(', ')}`,
+        detail: ['Report-only: the plugin still loads; these hooks may not run.'],
+      });
+    }
+  }
+  return checks;
+}
+
+function skillChecks(inputs: IDoctorInputs): IDoctorCheck[] {
+  const inspection = inspectSkillSources(inputs.contributionSources, inputs.skillRoots);
+  const present = inspection.roots.filter((root) => root.present);
+  const discovered = present.reduce((n, root) => n + root.discovered.length, 0);
+  const checks: IDoctorCheck[] = [
+    present.length === 0
+      ? {
+          id: 'skills',
+          label: 'Skills and commands',
+          status: 'not-configured',
+          cause: 'no skill or command root present',
+        }
+      : {
+          id: 'skills',
+          label: 'Skills and commands',
+          status: 'ok',
+          cause: `${discovered} discovered`,
+          detail: present.map(
+            (root) => `${root.sourceDisplayName}: ${root.root} (${root.discovered.length})`,
+          ),
+        },
+  ];
+  for (const root of present) {
+    for (const skip of root.skipped) {
+      // A value the parser refuses ends session discovery with a throw; every other skip is tolerated.
+      checks.push({
+        id: `skill.${skip.path}`,
+        label: 'Skill definition',
+        status: skip.reason === 'frontmatter-invalid' ? 'fail' : 'warn',
+        path: `${root.sourceDisplayName}: ${skip.path}`,
+        cause: skip.reason,
+        ...(skip.detail === undefined ? {} : { detail: [skip.detail] }),
+      });
+    }
+  }
+  return checks;
+}
+
+/** The shape of a hook group as both settings layers and plugin `hooks.json` carry it. */
+interface IHookGroupLike {
+  readonly hooks?: ReadonlyArray<{ readonly type?: string; readonly command?: string }>;
+}
+
+function commandHooks(
+  settings: ISettingsInspection,
+  plugins: readonly IBundlePluginInspection[],
+): string[] {
+  const commands: string[] = [];
+  const collect = (hooks: object | undefined): void => {
+    if (hooks === undefined) return;
+    for (const groups of Object.values(
+      hooks as Record<string, readonly IHookGroupLike[] | undefined>,
+    )) {
+      for (const group of groups ?? []) {
+        for (const hook of group.hooks ?? []) {
+          if (hook.type === 'command' && typeof hook.command === 'string')
+            commands.push(hook.command);
+        }
+      }
+    }
+  };
+  collect(settings.merged.hooks);
+  for (const inspection of plugins) for (const plugin of inspection.loaded) collect(plugin.hooks);
+  return commands;
+}
+
+function hookChecks(
+  settings: ISettingsInspection,
+  plugins: readonly IBundlePluginInspection[],
+  deps: IDoctorDeps,
+): IDoctorCheck[] {
+  const commands = commandHooks(settings, plugins);
+  const missing = commands.filter((command) => !deps.resolveCommand(command));
+  return [
+    commands.length === 0
+      ? {
+          id: 'hooks',
+          label: 'Hooks',
+          status: 'not-configured',
+          cause: 'no command hooks configured',
+        }
+      : missing.length === 0
+        ? {
+            id: 'hooks',
+            label: 'Hooks',
+            status: 'ok',
+            cause: `${commands.length} command hook(s); every executable resolves`,
+          }
+        : {
+            id: 'hooks',
+            label: 'Hooks',
+            status: 'warn',
+            cause: `${missing.length} command hook executable(s) not found on PATH`,
+            detail: missing.map((command) => command.split(/\s+/)[0] ?? command),
+          },
+    {
+      id: 'hooks.execution',
+      label: 'Hook execution',
+      status: 'not-probed',
+      cause: 'the doctor does not run hooks',
+    },
+  ];
+}
+
+function mcpServerCheck(server: IBundlePluginMcpServer, deps: IDoctorDeps): IDoctorCheck {
+  const id = `mcp.plugin.${server.pluginId}.${server.name}`;
+  if (server.transport === 'stdio' && server.command !== undefined) {
+    return deps.resolveCommand(server.command)
+      ? {
+          id,
+          label: 'MCP server (plugin)',
+          status: 'ok',
+          path: server.mcpPath,
+          cause: `stdio command ${server.command} resolves`,
+        }
+      : {
+          id,
+          label: 'MCP server (plugin)',
+          status: 'warn',
+          path: server.mcpPath,
+          cause: `stdio command ${server.command} not found on PATH`,
+          detail: server.envKeys.length === 0 ? [] : [`env keys: ${server.envKeys.join(', ')}`],
+        };
+  }
+  if (server.transport === 'http' && server.url !== undefined) {
+    try {
+      new URL(server.url);
+      return {
+        id,
+        label: 'MCP server (plugin)',
+        status: 'ok',
+        path: server.mcpPath,
+        cause: `url ${server.url}`,
+      };
+    } catch {
+      // allow-fallback: an unparseable url is the finding
+      return {
+        id,
+        label: 'MCP server (plugin)',
+        status: 'warn',
+        path: server.mcpPath,
+        cause: 'url is not parseable',
+      };
+    }
+  }
+  return {
+    id,
+    label: 'MCP server (plugin)',
+    status: 'warn',
+    path: server.mcpPath,
+    cause: 'neither command nor url declared',
+  };
+}
+
+function mcpChecks(
+  inputs: IDoctorInputs,
+  plugins: readonly IBundlePluginInspection[],
+  deps: IDoctorDeps,
+): IDoctorCheck[] {
+  const checks: IDoctorCheck[] = [];
+  if (inputs.mcpActivation === undefined) {
+    checks.push({
+      id: 'mcp.activation',
+      label: 'MCP activation',
+      status: 'not-configured',
+      cause: 'this CLI composes no MCP activation adapter',
+    });
+  } else {
+    const summaries = inputs.mcpActivation.list();
+    checks.push({
+      id: 'mcp.activation',
+      label: 'MCP activation',
+      status: 'ok',
+      cause: `${summaries.length} server(s) known`,
+    });
+    for (const summary of summaries) {
+      checks.push({
+        id: `mcp.${summary.serverId}`,
+        label: 'MCP server',
+        status: summary.allowed ? 'ok' : 'warn',
+        cause: `${summary.status} (${summary.source}): ${summary.reason}`,
+      });
+    }
+  }
+  for (const inspection of plugins) {
+    for (const server of inspection.mcpServers) checks.push(mcpServerCheck(server, deps));
+    for (const fault of inspection.mcpFaults) {
+      checks.push({
+        id: `mcp.plugin.${fault.pluginId}`,
+        label: 'MCP declaration (plugin)',
+        status: 'warn',
+        path: fault.mcpPath,
+        cause: `.mcp.json ${fault.reason}`,
+      });
+    }
+  }
+  checks.push({
+    id: 'mcp.connection',
+    label: 'MCP connection',
+    status: 'not-probed',
+    cause: 'the doctor does not connect to MCP servers',
+  });
+  return checks;
+}
+
+/** Plugins, skills, hooks and MCP — in that order. */
+export function probeExtensions(
+  inputs: IDoctorInputs,
+  deps: IDoctorDeps,
+  settings: ISettingsInspection,
+): IDoctorCheck[] {
+  // Enablement is read the way the session loader reads it — from the user settings file through the
+  // plugin settings store — so the doctor and the session agree even where that store's own policy is
+  // a separate open item (recorded on #2670).
+  const plugins = loadHostBundlePluginInspectionFromScopes(inputs.pluginsDirs, {
+    settingsPath: inputs.userSettingsPath,
+  });
+  return [
+    ...pluginChecks(plugins),
+    ...skillChecks(inputs),
+    ...hookChecks(settings, plugins, deps),
+    ...mcpChecks(inputs, plugins, deps),
+  ];
+}

package/src/doctor/doctor-node-deps.ts

@@ -0,0 +1,89 @@
+/** Node defaults for {@link IDoctorDeps}: a TCP connect probe and read-only filesystem facts. */
+import { accessSync, constants, existsSync, statSync } from 'node:fs';
+import { createConnection } from 'node:net';
+import { delimiter, isAbsolute, join } from 'node:path';
+
+import { ownerOnlyGuarantee } from '@robota-sdk/agent-core/node';
+
+import type { IDoctorDeps, IDoctorEndpointProbeResult, IDoctorPathFacts } from './doctor-types.js';
+
+const NETWORK_CHECK_TIMEOUT_MS = 3000;
+const MS_PER_SECOND = 1000;
+const MODE_BITS = 0o777;
+
+/** TCP connect with a bounded timeout; a refusal or a timeout is a result, never a throw. */
+export function probeEndpointViaSocket(
+  host: string,
+  port: number,
+): Promise<IDoctorEndpointProbeResult> {
+  return new Promise((resolve) => {
+    const start = Date.now();
+    const socket = createConnection({ host, port });
+    const timeout = setTimeout(() => {
+      socket.destroy();
+      resolve({
+        reachable: false,
+        error: `timeout (${NETWORK_CHECK_TIMEOUT_MS / MS_PER_SECOND}s)`,
+      });
+    }, NETWORK_CHECK_TIMEOUT_MS);
+    socket.on('connect', () => {
+      clearTimeout(timeout);
+      socket.destroy();
+      resolve({ reachable: true, elapsedMs: Date.now() - start });
+    });
+    socket.on('error', (error) => {
+      clearTimeout(timeout);
+      resolve({ reachable: false, error: error.message });
+    });
+  });
+}
+
+/** Existence, directory-ness, `W_OK` and mode — probed without writing. */
+export function inspectPathFacts(path: string): IDoctorPathFacts {
+  if (!existsSync(path)) return { exists: false, isDirectory: false, writable: false };
+  let isDirectory = false;
+  let mode: number | undefined;
+  try {
+    const stat = statSync(path);
+    isDirectory = stat.isDirectory();
+    mode = stat.mode & MODE_BITS;
+  } catch {
+    // allow-fallback: a path that exists but cannot be stat'ed is reported as not a writable directory
+    return { exists: true, isDirectory: false, writable: false };
+  }
+  let writable = false;
+  try {
+    accessSync(path, constants.W_OK);
+    writable = true;
+  } catch {
+    // allow-fallback: W_OK refused IS the fact being reported
+    writable = false;
+  }
+  return { exists: true, isDirectory, writable, ...(mode === undefined ? {} : { mode }) };
+}
+
+/** A bare command resolves through `PATH`; a path-form command must exist as given. */
+export function resolveCommandOnPath(
+  command: string,
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): boolean {
+  const executable = command.trim().split(/\s+/)[0];
+  if (executable === undefined || executable.length === 0) return false;
+  if (isAbsolute(executable) || executable.includes('/')) return existsSync(executable);
+  const extensions = process.platform === 'win32' ? ['', '.exe', '.cmd', '.bat'] : [''];
+  return (env.PATH ?? '')
+    .split(delimiter)
+    .filter((dir) => dir.length > 0)
+    .some((dir) => extensions.some((ext) => existsSync(join(dir, executable + ext))));
+}
+
+export function createNodeDoctorDeps(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): IDoctorDeps {
+  return {
+    probeEndpoint: probeEndpointViaSocket,
+    inspectPath: inspectPathFacts,
+    resolveCommand: (command) => resolveCommandOnPath(command, env),
+    ownerOnlyGuarantee: () => ownerOnlyGuarantee(),
+  };
+}

package/src/doctor/doctor-redaction.ts

@@ -0,0 +1,99 @@
+/**
+ * The doctor's single rendering boundary for secrets (OBSERVABILITY-1991).
+ *
+ * Defence in depth, not the first line: the inspection APIs the probes read already return facts
+ * (states, paths, issue paths, env KEY names) rather than file content. This pass exists for the
+ * text the doctor cannot prevent from carrying a value — an owner error message, a URL a user typed
+ * a credential into — and for the case the structural layer cannot see: a literal that IS a secret
+ * because the settings layers or the environment say so.
+ */
+
+import { SettingsParseError } from '@robota-sdk/agent-framework';
+
+import type { TSettings } from '@robota-sdk/agent-framework';
+
+const REDACTED = '[redacted]';
+
+/**
+ * `scheme://user:pass@host` → `scheme://[redacted]@host`. The scheme is bounded: an unbounded run,
+ * retried from every word start, was quadratic on long text that never reaches `://`.
+ */
+const URL_USERINFO = /(\b[a-z][a-z0-9+.-]{0,31}:\/\/)([^\s/@]+)@/gi;
+/** `Bearer <token>` in any casing. */
+const BEARER_TOKEN = /\b(bearer)\s+[A-Za-z0-9._~+/=-]{8,}/gi;
+/** Vendor-key shapes: `sk-…`, `sk-ant-…`, `AIza…`, `ghp_…`, `xox?-…`. */
+const KEY_SHAPES =
+  /\b(?:sk-[A-Za-z0-9_-]{8,}|AIza[0-9A-Za-z_-]{20,}|ghp_[A-Za-z0-9]{20,}|xox[abprs]-[A-Za-z0-9-]{10,})\b/g;
+
+const MIN_SECRET_LENGTH = 4;
+/** The quoted excerpt of the input a JSON parser embeds in its message: `..."<snippet>"...`. */
+const PARSER_SNIPPET = /\.\.\."[^"]*"\.\.\./g;
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Mask every known secret value and every credential-shaped token in `text`.
+ *
+ * `secrets` are literal values the doctor learned from its inputs — the resolved credential, every
+ * literal `apiKey` in any settings layer (active or not), every value a `$ENV:` reference names,
+ * every `env` map value. Values shorter than four characters are not masked: they cannot be
+ * credentials and masking them would shred ordinary words.
+ */
+export function redactDiagnosticText(text: string, secrets: Iterable<string> = []): string {
+  let out = text;
+  const seen = new Set<string>();
+  for (const secret of secrets) {
+    if (typeof secret !== 'string' || secret.length < MIN_SECRET_LENGTH || seen.has(secret))
+      continue;
+    seen.add(secret);
+    out = out.replace(new RegExp(escapeRegExp(secret), 'g'), REDACTED);
+  }
+  out = out.replace(URL_USERINFO, `$1${REDACTED}@`);
+  out = out.replace(BEARER_TOKEN, `$1 ${REDACTED}`);
+  out = out.replace(KEY_SHAPES, REDACTED);
+  return out;
+}
+
+/**
+ * An owner error as the doctor may show it. A parse error is named by its class and file only —
+ * its message quotes the file around the fault, which is exactly the content a broken settings
+ * layer never had a chance to contribute to the secret list. Any other message loses a parser
+ * snippet it may carry; the redactor still runs over the result.
+ */
+export function describeDiagnosticError(error: Error): string {
+  if (error instanceof SettingsParseError) {
+    return `${error.name}: ${error.filePath} is not valid JSON (see the settings check)`;
+  }
+  return `${error.name}: ${error.message.replace(PARSER_SNIPPET, '…')}`;
+}
+
+/**
+ * Collect the literal secrets a set of parsed settings layers and the environment expose:
+ * `providers.*.apiKey`, `provider.apiKey` (literal, or the value of a `$ENV:` reference), and
+ * every `env` map value. The doctor never RENDERS any of these; they feed the redactor so that a
+ * value which nonetheless reaches a message is masked.
+ */
+export function collectSettingsSecrets(
+  layers: ReadonlyArray<TSettings | undefined>,
+  env: Readonly<Record<string, string | undefined>>,
+): string[] {
+  const secrets = new Set<string>();
+  const addKey = (value: string | undefined): void => {
+    if (value === undefined) return;
+    if (value.startsWith('$ENV:')) {
+      const resolved = env[value.slice('$ENV:'.length).trim()];
+      if (resolved !== undefined) secrets.add(resolved);
+      return;
+    }
+    secrets.add(value);
+  };
+  for (const layer of layers) {
+    if (layer === undefined) continue;
+    addKey(layer.provider?.apiKey);
+    for (const profile of Object.values(layer.providers ?? {})) addKey(profile.apiKey);
+    for (const value of Object.values(layer.env ?? {})) secrets.add(value);
+  }
+  return [...secrets];
+}

package/src/doctor/doctor-render.ts

@@ -0,0 +1,70 @@
+/** Plain-text rendering of a doctor report — the same lines for the shell route and `/doctor`. */
+import type { IDoctorCheck, IDoctorReport, TDoctorCheckStatus } from './doctor-types.js';
+
+const ICON: Record<TDoctorCheckStatus, string> = {
+  ok: '✓',
+  warn: '⚠',
+  fail: '✗',
+  'not-configured': '○',
+  'not-probed': '–',
+};
+
+/** Optional product wording supplied by the host; omission keeps diagnostics product-neutral. */
+export interface IDoctorDisplayVocabulary {
+  readonly title?: string;
+  readonly productName?: string;
+  readonly formatRepairCommand?: (checkId: string) => string;
+  readonly repairOffer?: string;
+}
+
+function renderCheck(check: IDoctorCheck, display: IDoctorDisplayVocabulary): string[] {
+  const head = `  ${ICON[check.status]} ${check.label} [${check.id}] ${check.status}${check.cause === undefined ? '' : `: ${check.cause}`}`;
+  const lines = [head];
+  if (check.path !== undefined) lines.push(`      path: ${check.path}`);
+  for (const line of check.detail ?? []) lines.push(`      ${line}`);
+  if (check.repair !== undefined) {
+    const repairAction = display.formatRepairCommand?.(check.repair);
+    lines.push(
+      `      repair: ${repairAction ?? `request repair for ${check.repair} through your host`}`,
+    );
+  }
+  return lines;
+}
+
+function summary(report: IDoctorReport, display: IDoctorDisplayVocabulary): string {
+  const productName = display.productName?.trim();
+  if (report.failCount === 0 && report.warnCount === 0)
+    return productName
+      ? `✓ All checks passed. ${productName} is ready to use.`
+      : '✓ All checks passed.';
+  if (report.failCount > 0)
+    return productName
+      ? `✗ ${report.failCount} issue(s) found. Fix the items above to use ${productName}.`
+      : `✗ ${report.failCount} issue(s) found. Fix the items above before use.`;
+  return productName
+    ? `⚠ ${report.warnCount} warning(s). ${productName} may work but check the items above.`
+    : `⚠ ${report.warnCount} warning(s). Check the items above.`;
+}
+
+/** Render the report as lines: a title, every check, then the summary and the repair offers. */
+export function renderDoctorReport(
+  report: IDoctorReport,
+  title = 'Doctor',
+  display: IDoctorDisplayVocabulary = {},
+): string[] {
+  const lines = [
+    '',
+    title,
+    '',
+    ...report.checks.flatMap((check) => renderCheck(check, display)),
+    '',
+    summary(report, display),
+  ];
+  if (report.repairable.length > 0) {
+    lines.push(
+      `  repairable: ${report.repairable.join(', ')} — ${display.repairOffer ?? 'ask your host to apply a repair'}`,
+    );
+  }
+  lines.push('');
+  return lines;
+}