@tonyclaw/agent-inspector 4.0.1 → 4.0.2

package/src/cli/doctor.ts

@@ -1,836 +0,0 @@
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { isAbsolute, join, resolve } from "node:path";
-import { createConnection } from "node:net";
-import { appendBasePathToOrigin, getConfiguredBasePath } from "../lib/basePath";
-import { migrateLegacyDataDirs, resolveDataDir } from "../proxy/dataDir";
-
-const DEFAULT_PORT = 9527;
-const PROBE_TIMEOUT_MS = 2000;
-const EXTENSION_REQUIRED_FILES = [
-  "manifest.json",
-  "sidepanel.html",
-  "sidepanel.js",
-  "sidepanel.css",
-  "service-worker.js",
-  "icons/icon.svg",
-  "icons/icon-16.png",
-  "icons/icon-32.png",
-  "icons/icon-48.png",
-  "icons/icon-128.png",
-];
-
-export type DoctorSeverity = "pass" | "warn" | "fail";
-
-export type DoctorCheck = {
-  name: string;
-  severity: DoctorSeverity;
-  message: string;
-  hint: string | null;
-};
-
-export type DoctorOptions = {
-  port: number;
-  configDir: string | null;
-  providersJson: string | null;
-  chromeExtension: boolean;
-  fix: boolean;
-  json: boolean;
-  supportBundle: boolean;
-  verbose: boolean;
-  help: boolean;
-};
-
-export type DoctorParseResult =
-  | { kind: "ok"; options: DoctorOptions }
-  | { kind: "error"; message: string };
-
-export type HealthProbe = {
-  ok: boolean;
-  status: number | null;
-};
-
-export type ReadinessProbe = {
-  ok: boolean;
-  status: number | null;
-  body: unknown;
-};
-
-export type DoctorDeps = {
-  env: Readonly<Record<string, string | undefined>>;
-  platform: typeof process.platform;
-  cwd: string;
-  readText: (path: string) => string | null;
-  exists: (path: string) => boolean;
-  listDir: (path: string) => readonly string[] | null;
-  stat: (path: string) => { isDirectory: boolean; size: number } | null;
-  fetchHealth: (port: number, basePath: string) => Promise<HealthProbe>;
-  fetchReadiness: (port: number, basePath: string) => Promise<ReadinessProbe>;
-  isPortOpen: (port: number) => Promise<boolean>;
-};
-
-export type DoctorReport = {
-  checks: readonly DoctorCheck[];
-  readiness: ReadinessProbe | null;
-  passCount: number;
-  warnCount: number;
-  failCount: number;
-  exitCode: number;
-};
-
-export type DoctorSupportBundle = {
-  schema: "agent-inspector.support-bundle/v1";
-  createdAt: string;
-  report: DoctorReport;
-  environment: {
-    platform: typeof process.platform;
-    cwd: string;
-    basePath: string;
-    port: number;
-    hasControlToken: boolean;
-    hasProxyToken: boolean;
-    hasProviderJsonOverride: boolean;
-  };
-  storage: readonly DoctorCheck[];
-};
-
-function check(name: string, severity: DoctorSeverity, message: string, hint = ""): DoctorCheck {
-  return {
-    name,
-    severity,
-    message,
-    hint: hint === "" ? null : hint,
-  };
-}
-
-function parsePort(raw: string | undefined): number | null {
-  if (raw === undefined || raw.trim() === "") return null;
-  const port = Number(raw);
-  if (!Number.isInteger(port) || port <= 0 || port > 65535) return null;
-  return port;
-}
-
-export function parseDoctorArgs(
-  argv: readonly string[],
-  env: Readonly<Record<string, string | undefined>> = process.env,
-): DoctorParseResult {
-  const envPort = parsePort(env["PORT"]);
-  const options: DoctorOptions = {
-    port: envPort ?? DEFAULT_PORT,
-    configDir: null,
-    providersJson: null,
-    chromeExtension: false,
-    fix: false,
-    json: false,
-    supportBundle: false,
-    verbose: false,
-    help: false,
-  };
-
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    switch (arg) {
-      case undefined:
-        continue;
-      case "--help":
-      case "-h":
-        options.help = true;
-        break;
-      case "--port":
-      case "-p": {
-        const parsed = parsePort(argv[i + 1]);
-        if (parsed === null) {
-          return { kind: "error", message: "doctor: --port must be an integer from 1 to 65535" };
-        }
-        options.port = parsed;
-        i++;
-        break;
-      }
-      case "--config-dir": {
-        const next = argv[i + 1];
-        if (next === undefined || next.trim() === "") {
-          return { kind: "error", message: "doctor: --config-dir requires a path argument" };
-        }
-        options.configDir = next;
-        i++;
-        break;
-      }
-      case "--providers": {
-        const next = argv[i + 1];
-        if (next === undefined || next.trim() === "") {
-          return { kind: "error", message: "doctor: --providers requires a JSON argument" };
-        }
-        options.providersJson = next;
-        i++;
-        break;
-      }
-      case "--chrome-extension":
-        options.chromeExtension = true;
-        break;
-      case "--fix":
-        options.fix = true;
-        break;
-      case "--json":
-        options.json = true;
-        break;
-      case "--support-bundle":
-        options.supportBundle = true;
-        options.json = true;
-        break;
-      case "--verbose":
-        options.verbose = true;
-        break;
-      default:
-        return { kind: "error", message: `doctor: unknown option ${arg}` };
-    }
-  }
-
-  return { kind: "ok", options };
-}
-
-function isObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function providerCountFromParsed(value: unknown): number | null {
-  if (Array.isArray(value)) return value.length;
-  if (isObject(value)) {
-    const providers = value["providers"];
-    if (Array.isArray(providers)) return providers.length;
-  }
-  return null;
-}
-
-function providerCountFromJson(raw: string): "invalid" | number | null {
-  try {
-    const parsed: unknown = JSON.parse(raw);
-    return providerCountFromParsed(parsed);
-  } catch {
-    return "invalid";
-  }
-}
-
-function resolveMaybeRelative(base: string, value: string): string {
-  return isAbsolute(value) ? value : resolve(base, value);
-}
-
-function resolveDefaultDataDir(
-  env: Readonly<Record<string, string | undefined>>,
-  platform: typeof process.platform,
-  exists: (path: string) => boolean,
-): string {
-  return resolveDataDir(exists, env, platform);
-}
-
-function providerConfigCandidates(options: DoctorOptions, deps: DoctorDeps): readonly string[] {
-  const explicitPath = deps.env["AGENT_INSPECTOR_CONFIG_PATH"];
-  if (explicitPath !== undefined && explicitPath !== "") {
-    return [resolveMaybeRelative(deps.cwd, explicitPath)];
-  }
-  if (options.configDir !== null) {
-    const dir = resolveMaybeRelative(deps.cwd, options.configDir);
-    return [join(dir, "providers.json"), join(dir, "config.json")];
-  }
-  const dataDir = resolveDefaultDataDir(deps.env, deps.platform, deps.exists);
-  return [join(dataDir, "providers.json"), join(dataDir, "config.json")];
-}
-
-function checkProviderConfig(options: DoctorOptions, deps: DoctorDeps): DoctorCheck {
-  const providersJson = options.providersJson ?? deps.env["AGENT_INSPECTOR_PROVIDERS_JSON"] ?? null;
-  if (providersJson !== null) {
-    const count = providerCountFromJson(providersJson);
-    if (count === "invalid") {
-      return check(
-        "Provider config",
-        "fail",
-        "Provider JSON override is not valid JSON.",
-        "Fix --providers or AGENT_INSPECTOR_PROVIDERS_JSON; doctor never prints the raw value.",
-      );
-    }
-    if (count !== null) {
-      return check("Provider config", "pass", `${count} provider(s) found in JSON override.`);
-    }
-    return check(
-      "Provider config",
-      "fail",
-      "Provider JSON override does not look like a provider array or { providers } object.",
-      "Use an exported providers JSON payload or configure providers in the UI.",
-    );
-  }
-
-  const candidates = providerConfigCandidates(options, deps);
-  for (const candidate of candidates) {
-    if (!deps.exists(candidate)) continue;
-    const text = deps.readText(candidate);
-    if (text === null) {
-      return check(
-        "Provider config",
-        "fail",
-        `Provider config exists but could not be read: ${candidate}`,
-      );
-    }
-    const count = providerCountFromJson(text);
-    if (count === "invalid") {
-      return check("Provider config", "fail", `Provider config is invalid JSON: ${candidate}`);
-    }
-    if (count !== null && count > 0) {
-      return check("Provider config", "pass", `${count} provider(s) configured.`);
-    }
-    return check(
-      "Provider config",
-      "warn",
-      `Provider config exists but no providers were found: ${candidate}`,
-      "Add a provider through the control API/MCP, or use Settings when a UI is available.",
-    );
-  }
-
-  return check(
-    "Provider config",
-    "warn",
-    "No provider config was found.",
-    "Add a provider through the control API/MCP, use Settings when a UI is available, or pass --providers for this check.",
-  );
-}
-
-function publicOriginForDoctor(port: number, env: DoctorDeps["env"]): string {
-  const configured = env["AGENT_INSPECTOR_PUBLIC_ORIGIN"];
-  if (configured !== undefined && configured.trim() === configured) {
-    try {
-      const parsed = new URL(configured);
-      if (
-        (parsed.protocol === "http:" || parsed.protocol === "https:") &&
-        parsed.username.length === 0 &&
-        parsed.password.length === 0 &&
-        parsed.pathname === "/" &&
-        parsed.search.length === 0 &&
-        parsed.hash.length === 0
-      ) {
-        return parsed.origin;
-      }
-    } catch {
-      // Startup reports invalid public-origin configuration; doctor keeps a safe local hint.
-    }
-  }
-  return `http://localhost:${String(port)}`;
-}
-
-async function checkProxyHealth(port: number, deps: DoctorDeps): Promise<DoctorCheck> {
-  const basePath = getConfiguredBasePath(deps.env);
-  const health = await deps.fetchHealth(port, basePath);
-  const url = publicOriginForDoctor(port, deps.env);
-  const proxyUrl = appendBasePathToOrigin(url, "/proxy", basePath);
-  const healthPath = appendBasePathToOrigin("", "/api/health", basePath);
-  if (health.ok) {
-    return check(
-      "Backend health",
-      "pass",
-      `Agent Inspector backend is healthy at ${appendBasePathToOrigin(url, "/", basePath)}.`,
-      `Agent proxy URL: ${proxyUrl}. UI availability is not part of this backend check.`,
-    );
-  }
-
-  if (await deps.isPortOpen(port)) {
-    const suffix = health.status === null ? "" : ` (HTTP ${health.status})`;
-    return check(
-      "Backend health",
-      "fail",
-      `Port ${port} is accepting connections, but ${healthPath} is not healthy${suffix}.`,
-      "Stop that process, choose --port <n>, or start agent-inspector with --force-restart.",
-    );
-  }
-
-  return check(
-    "Backend health",
-    "warn",
-    `No process is listening on port ${port}.`,
-    "Start with `agent-inspector`, `agent-inspector --background`, or `bun run dev`.",
-  );
-}
-
-function readinessChecks(readiness: ReadinessProbe): readonly DoctorCheck[] {
-  if (!readiness.ok) {
-    const suffix = readiness.status === null ? "" : ` (HTTP ${readiness.status})`;
-    return [
-      check(
-        "Readiness",
-        "warn",
-        `Readiness probe is unavailable${suffix}.`,
-        "Use /readyz locally or run with --verbose for storage and worker hints.",
-      ),
-    ];
-  }
-  if (!isObject(readiness.body)) {
-    return [check("Readiness", "warn", "Readiness response was not an object.")];
-  }
-  const status = readiness.body["status"];
-  const checks = readiness.body["checks"];
-  if (typeof status !== "string" || !isObject(checks)) {
-    return [check("Readiness", "warn", "Readiness response did not include status/checks.")];
-  }
-  const degraded = Object.entries(checks)
-    .filter(([, value]) => value !== "ok")
-    .map(([name, value]) => `${name}=${String(value)}`);
-  if (degraded.length === 0) {
-    return [check("Readiness", "pass", `Runtime readiness is ${status}.`)];
-  }
-  return [
-    check(
-      "Readiness",
-      status === "unavailable" ? "fail" : "warn",
-      `Runtime readiness is ${status}: ${degraded.join(", ")}.`,
-      "Inspect /readyz and /metrics for safe aggregate runtime details.",
-    ),
-  ];
-}
-
-function findProjectRoot(startDir: string, deps: Pick<DoctorDeps, "exists">): string {
-  let current = resolve(startDir);
-  for (let i = 0; i < 6; i++) {
-    if (deps.exists(join(current, "package.json"))) return current;
-    const next = resolve(current, "..");
-    if (next === current) return startDir;
-    current = next;
-  }
-  return startDir;
-}
-
-function checkPackage(rootDir: string, deps: DoctorDeps): DoctorCheck {
-  const packagePath = join(rootDir, "package.json");
-  const text = deps.readText(packagePath);
-  if (text === null) {
-    return check("Package metadata", "warn", "package.json was not found near the CLI bundle.");
-  }
-  try {
-    const parsed: unknown = JSON.parse(text);
-    if (!isObject(parsed)) {
-      return check("Package metadata", "warn", "package.json is not an object.");
-    }
-    const name = parsed["name"];
-    const version = parsed["version"];
-    if (typeof name === "string" && typeof version === "string") {
-      return check("Package metadata", "pass", `${name}@${version}`);
-    }
-    return check("Package metadata", "warn", "package.json is missing name or version.");
-  } catch {
-    return check("Package metadata", "warn", "package.json is not valid JSON.");
-  }
-}
-
-function countFilesInDir(dir: string, deps: Pick<DoctorDeps, "listDir" | "stat">): number | null {
-  const files = deps.listDir(dir);
-  if (files === null) return null;
-  let count = 0;
-  for (const file of files) {
-    const fileStat = deps.stat(join(dir, file));
-    if (fileStat !== null && !fileStat.isDirectory) count += 1;
-  }
-  return count;
-}
-
-function formatBytes(bytes: number): string {
-  if (bytes < 1024) return `${bytes} B`;
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KiB`;
-  if (bytes < 1024 * 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MiB`;
-  return `${(bytes / 1024 / 1024 / 1024).toFixed(1)} GiB`;
-}
-
-function dirSize(
-  dir: string,
-  deps: Pick<DoctorDeps, "listDir" | "stat">,
-  depth = 0,
-): number | null {
-  const dirStat = deps.stat(dir);
-  if (dirStat === null) return null;
-  if (!dirStat.isDirectory) return dirStat.size;
-  if (depth > 4) return 0;
-
-  const files = deps.listDir(dir);
-  if (files === null) return null;
-  let total = 0;
-  for (const file of files) {
-    const childSize = dirSize(join(dir, file), deps, depth + 1);
-    if (childSize !== null) total += childSize;
-  }
-  return total;
-}
-
-function verboseChecks(options: DoctorOptions, deps: DoctorDeps): readonly DoctorCheck[] {
-  const dataDir = resolveDefaultDataDir(deps.env, deps.platform, deps.exists);
-  const logsDir = join(dataDir, "logs");
-  const chunksDir = join(dataDir, "chunks");
-  const providerCandidates = providerConfigCandidates(options, deps);
-  const captureMode =
-    deps.env["AGENT_INSPECTOR_MODE"] ?? deps.env["AGENT_INSPECTOR_CAPTURE_MODE"] ?? "simple";
-  const logCount = countFilesInDir(logsDir, deps);
-  const logSize = dirSize(logsDir, deps);
-  const chunkSize = dirSize(chunksDir, deps);
-  const homeDir =
-    deps.platform === "win32"
-      ? (deps.env["USERPROFILE"] ?? deps.env["APPDATA"] ?? null)
-      : (deps.env["HOME"] ?? null);
-  const claudeSkill =
-    homeDir === null
-      ? null
-      : join(homeDir, ".claude", "skills", "agent-inspector-onboard", "SKILL.md");
-  const claudeCommand =
-    homeDir === null ? null : join(homeDir, ".claude", "commands", "agent-inspector-onboard.md");
-  const codexSkill =
-    homeDir === null
-      ? null
-      : join(homeDir, ".codex", "skills", "agent-inspector-onboard", "SKILL.md");
-  const hasClaudeOnboarding =
-    claudeSkill !== null &&
-    claudeCommand !== null &&
-    deps.exists(claudeSkill) &&
-    deps.exists(claudeCommand);
-  const hasCodexOnboarding = codexSkill !== null && deps.exists(codexSkill);
-
-  return [
-    check("Data directory", "pass", dataDir),
-    check("Provider config search", "pass", providerCandidates.join(", ")),
-    check("Capture mode env", "pass", captureMode),
-    check(
-      "Log storage",
-      logCount === null ? "warn" : "pass",
-      logCount === null
-        ? `Log directory was not found or could not be read: ${logsDir}`
-        : `${logCount} file(s), ${formatBytes(logSize ?? 0)} under ${logsDir}`,
-    ),
-    check(
-      "Chunk storage",
-      chunkSize === null ? "warn" : "pass",
-      chunkSize === null
-        ? `Chunk directory was not found or could not be read: ${chunksDir}`
-        : `${formatBytes(chunkSize)} under ${chunksDir}`,
-    ),
-    check(
-      "Claude onboarding",
-      hasClaudeOnboarding ? "pass" : "warn",
-      hasClaudeOnboarding
-        ? "Claude Code skill and slash command are installed."
-        : "Claude Code onboarding files were not found.",
-      "Run `agent-inspector onboard --force` after installing or upgrading.",
-    ),
-    check(
-      "Codex onboarding",
-      hasCodexOnboarding ? "pass" : "warn",
-      hasCodexOnboarding
-        ? "Codex onboarding skill is installed."
-        : "Codex onboarding skill was not found.",
-      "Run `agent-inspector onboard --force` after installing or upgrading.",
-    ),
-  ];
-}
-
-function checkExtensionSource(rootDir: string, deps: DoctorDeps): DoctorCheck {
-  const extensionDir = join(rootDir, "extensions", "chrome");
-  const missing = EXTENSION_REQUIRED_FILES.filter((file) => !deps.exists(join(extensionDir, file)));
-  if (missing.length === 0) {
-    return check(
-      "Chrome extension source",
-      "pass",
-      "Manifest, side panel, service worker, and icons are present.",
-    );
-  }
-  return check(
-    "Chrome extension source",
-    "fail",
-    `Missing ${missing.length} Chrome extension file(s): ${missing.join(", ")}`,
-    "Restore the extension files before packaging or loading unpacked.",
-  );
-}
-
-function extensionManifestVersion(rootDir: string, deps: DoctorDeps): string | null {
-  const manifestText = deps.readText(join(rootDir, "extensions", "chrome", "manifest.json"));
-  if (manifestText === null) return null;
-  try {
-    const manifest: unknown = JSON.parse(manifestText);
-    if (!isObject(manifest)) return null;
-    const version = manifest["version"];
-    return typeof version === "string" && version !== "" ? version : null;
-  } catch {
-    return null;
-  }
-}
-
-function checkExtensionPackage(rootDir: string, deps: DoctorDeps): DoctorCheck {
-  const distDir = join(rootDir, "dist", "chrome-extension");
-  const files = deps.listDir(distDir);
-  if (files === null) {
-    return check(
-      "Chrome extension package",
-      "warn",
-      "No packaged Chrome extension artifact was found.",
-      "Run `npm run extension:zip` before Chrome Web Store upload.",
-    );
-  }
-
-  const manifestVersion = extensionManifestVersion(rootDir, deps);
-  if (manifestVersion !== null) {
-    const zipName = `agent-inspector-companion-v${manifestVersion}.zip`;
-    const checksumName = `${zipName}.sha256`;
-    const hasZip = files.includes(zipName);
-    const hasChecksum = files.includes(checksumName);
-    if (hasZip && hasChecksum) {
-      return check("Chrome extension package", "pass", `${zipName} with checksum is present.`);
-    }
-    if (hasZip) {
-      return check(
-        "Chrome extension package",
-        "warn",
-        `${zipName} exists but no .sha256 checksum was found.`,
-        "Run `npm run extension:zip` to regenerate the zip and checksum.",
-      );
-    }
-    return check(
-      "Chrome extension package",
-      "warn",
-      `Current Chrome extension package was not found: ${zipName}`,
-      "Run `npm run extension:zip` before Chrome Web Store upload.",
-    );
-  }
-
-  const zip = files.find((file) => file.endsWith(".zip"));
-  const checksum = files.find((file) => file.endsWith(".zip.sha256"));
-  if (zip !== undefined && checksum !== undefined) {
-    return check("Chrome extension package", "pass", `${zip} with checksum is present.`);
-  }
-  if (zip !== undefined) {
-    return check(
-      "Chrome extension package",
-      "warn",
-      `${zip} exists but no .sha256 checksum was found.`,
-      "Run `npm run extension:zip` to regenerate the zip and checksum.",
-    );
-  }
-  return check(
-    "Chrome extension package",
-    "warn",
-    "No Chrome extension zip artifact was found.",
-    "Run `npm run extension:zip` before Chrome Web Store upload.",
-  );
-}
-
-export async function buildDoctorReport(
-  options: DoctorOptions,
-  deps: DoctorDeps = createDoctorDeps(),
-): Promise<DoctorReport> {
-  const rootDir = findProjectRoot(deps.cwd, deps);
-  const basePath = getConfiguredBasePath(deps.env);
-  const readiness = await deps.fetchReadiness(options.port, basePath);
-  const coreChecks = [
-    await checkProxyHealth(options.port, deps),
-    ...readinessChecks(readiness),
-    checkProviderConfig(options, deps),
-    checkPackage(rootDir, deps),
-  ];
-  const checksWithExtension = options.chromeExtension
-    ? [...coreChecks, checkExtensionSource(rootDir, deps), checkExtensionPackage(rootDir, deps)]
-    : coreChecks;
-  const checks = options.verbose
-    ? [...checksWithExtension, ...verboseChecks(options, deps)]
-    : checksWithExtension;
-
-  const passCount = checks.filter((item) => item.severity === "pass").length;
-  const warnCount = checks.filter((item) => item.severity === "warn").length;
-  const failCount = checks.filter((item) => item.severity === "fail").length;
-
-  return {
-    checks,
-    readiness,
-    passCount,
-    warnCount,
-    failCount,
-    exitCode: failCount > 0 ? 1 : 0,
-  };
-}
-
-export function buildDoctorSupportBundle(
-  options: DoctorOptions,
-  deps: DoctorDeps,
-  report: DoctorReport,
-): DoctorSupportBundle {
-  return {
-    schema: "agent-inspector.support-bundle/v1",
-    createdAt: new Date().toISOString(),
-    report,
-    environment: {
-      platform: deps.platform,
-      cwd: deps.cwd,
-      basePath: getConfiguredBasePath(deps.env),
-      port: options.port,
-      hasControlToken:
-        deps.env["AGENT_INSPECTOR_CONTROL_TOKEN"] !== undefined ||
-        deps.env["AGENT_INSPECTOR_API_TOKEN"] !== undefined,
-      hasProxyToken: deps.env["AGENT_INSPECTOR_PROXY_TOKEN"] !== undefined,
-      hasProviderJsonOverride:
-        options.providersJson !== null || deps.env["AGENT_INSPECTOR_PROVIDERS_JSON"] !== undefined,
-    },
-    storage: verboseChecks(options, deps).filter((item) => item.name.includes("storage")),
-  };
-}
-
-export function formatDoctorReport(report: DoctorReport): string {
-  const lines = ["agent-inspector doctor", ""];
-  for (const item of report.checks) {
-    lines.push(`${item.severity.toUpperCase().padEnd(4)} ${item.name}: ${item.message}`);
-    if (item.hint !== null) {
-      lines.push(`     ${item.hint}`);
-    }
-  }
-  lines.push("");
-  lines.push(
-    `Summary: ${report.passCount} pass, ${report.warnCount} warn, ${report.failCount} fail`,
-  );
-  return `${lines.join("\n")}\n`;
-}
-
-export function formatDoctorJson(report: DoctorReport): string {
-  return `${JSON.stringify(report, null, 2)}\n`;
-}
-
-export function formatDoctorSupportBundle(bundle: DoctorSupportBundle): string {
-  return `${JSON.stringify(bundle, null, 2)}\n`;
-}
-
-export function doctorHelp(): string {
-  return [
-    "agent-inspector doctor",
-    "",
-    "Usage:",
-    "  agent-inspector doctor [--port <port>] [--config-dir <dir>] [--providers <json>] [--fix] [--json] [--support-bundle] [--verbose] [--chrome-extension]",
-    "",
-    "Checks local backend health, provider config presence, and package metadata.",
-    "The backend check probes the local health endpoint and does not require a composed Web UI.",
-    "Pass --fix to run safe local repairs before checks, including legacy data-dir migration.",
-    "Pass --json to emit a machine-readable report for CI, scripts, and Jenkins.",
-    "Pass --support-bundle to emit a redacted JSON bundle with readiness causes and storage summary.",
-    "Pass --verbose to include local paths, capture mode, and log storage checks.",
-    "Pass --chrome-extension to also check Chrome companion source and packaged artifacts.",
-    "",
-  ].join("\n");
-}
-
-async function fetchHealth(port: number, basePath: string): Promise<HealthProbe> {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
-  try {
-    const response = await fetch(
-      appendBasePathToOrigin(`http://127.0.0.1:${port}`, "/api/health", basePath),
-      {
-        cache: "no-store",
-        signal: controller.signal,
-      },
-    );
-    return { ok: response.ok, status: response.status };
-  } catch {
-    return { ok: false, status: null };
-  } finally {
-    clearTimeout(timeout);
-  }
-}
-
-async function fetchReadiness(port: number, basePath: string): Promise<ReadinessProbe> {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
-  try {
-    const response = await fetch(
-      appendBasePathToOrigin(`http://127.0.0.1:${port}`, "/readyz", basePath),
-      {
-        cache: "no-store",
-        signal: controller.signal,
-      },
-    );
-    let body: unknown = null;
-    try {
-      body = await response.json();
-    } catch {
-      body = null;
-    }
-    return { ok: response.ok, status: response.status, body };
-  } catch {
-    return { ok: false, status: null, body: null };
-  } finally {
-    clearTimeout(timeout);
-  }
-}
-
-function isPortOpen(port: number): Promise<boolean> {
-  return new Promise((resolveOpen) => {
-    const socket = createConnection({ host: "127.0.0.1", port });
-    const finish = (value: boolean): void => {
-      socket.removeAllListeners();
-      socket.destroy();
-      resolveOpen(value);
-    };
-
-    socket.setTimeout(PROBE_TIMEOUT_MS);
-    socket.once("connect", () => finish(true));
-    socket.once("timeout", () => finish(false));
-    socket.once("error", () => finish(false));
-  });
-}
-
-function readText(path: string): string | null {
-  try {
-    return readFileSync(path, "utf8");
-  } catch {
-    return null;
-  }
-}
-
-function listDir(path: string): readonly string[] | null {
-  try {
-    return readdirSync(path);
-  } catch {
-    return null;
-  }
-}
-
-function stat(path: string): { isDirectory: boolean; size: number } | null {
-  try {
-    const fileStat = statSync(path);
-    return { isDirectory: fileStat.isDirectory(), size: fileStat.size };
-  } catch {
-    return null;
-  }
-}
-
-export function createDoctorDeps(): DoctorDeps {
-  return {
-    env: process.env,
-    platform: process.platform,
-    cwd: process.cwd(),
-    exists: existsSync,
-    readText,
-    listDir,
-    stat,
-    fetchHealth,
-    fetchReadiness,
-    isPortOpen,
-  };
-}
-
-export async function runDoctor(argv: readonly string[]): Promise<number> {
-  const parsed = parseDoctorArgs(argv);
-  if (parsed.kind === "error") {
-    process.stderr.write(`${parsed.message}\n`);
-    return 2;
-  }
-  if (parsed.options.help) {
-    process.stdout.write(doctorHelp());
-    return 0;
-  }
-  if (parsed.options.fix) {
-    migrateLegacyDataDirs();
-  }
-  const report = await buildDoctorReport(parsed.options);
-  if (parsed.options.supportBundle) {
-    const bundle = buildDoctorSupportBundle(parsed.options, createDoctorDeps(), report);
-    process.stdout.write(formatDoctorSupportBundle(bundle));
-  } else {
-    process.stdout.write(
-      parsed.options.json ? formatDoctorJson(report) : formatDoctorReport(report),
-    );
-  }
-  return report.exitCode;
-}