@tonyclaw/agent-inspector 2.0.0

package/src/cli/doctor.ts

@@ -0,0 +1,521 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { createConnection } from "node:net";
+import { resolveDataDir } from "../proxy/dataDir";
+
+const DEFAULT_PORT = 25947;
+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;
+  help: boolean;
+};
+
+export type DoctorParseResult =
+  | { kind: "ok"; options: DoctorOptions }
+  | { kind: "error"; message: string };
+
+export type HealthProbe = {
+  ok: boolean;
+  status: number | null;
+};
+
+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;
+  fetchHealth: (port: number) => Promise<HealthProbe>;
+  isPortOpen: (port: number) => Promise<boolean>;
+};
+
+export type DoctorReport = {
+  checks: readonly DoctorCheck[];
+  passCount: number;
+  warnCount: number;
+  failCount: number;
+  exitCode: number;
+};
+
+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,
+    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;
+      }
+      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 in Settings or import provider settings.",
+    );
+  }
+
+  return check(
+    "Provider config",
+    "warn",
+    "No provider config was found.",
+    "Add a provider in the web UI, import providers, or pass --providers for this check.",
+  );
+}
+
+async function checkProxyHealth(port: number, deps: DoctorDeps): Promise<DoctorCheck> {
+  const health = await deps.fetchHealth(port);
+  const url = `http://localhost:${port}`;
+  if (health.ok) {
+    return check(
+      "Proxy health",
+      "pass",
+      `agent-inspector is healthy at ${url}.`,
+      `Proxy URL: ${url}/proxy`,
+    );
+  }
+
+  if (await deps.isPortOpen(port)) {
+    const suffix = health.status === null ? "" : ` (HTTP ${health.status})`;
+    return check(
+      "Proxy health",
+      "fail",
+      `Port ${port} is accepting connections, but /api/health is not healthy${suffix}.`,
+      "Stop that process, choose --port <n>, or start agent-inspector with --force-restart.",
+    );
+  }
+
+  return check(
+    "Proxy health",
+    "warn",
+    `No process is listening on port ${port}.`,
+    "Start with `agent-inspector`, `agent-inspector --background`, or `bun run dev`.",
+  );
+}
+
+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 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 checks = [
+    await checkProxyHealth(options.port, deps),
+    checkProviderConfig(options, deps),
+    checkPackage(rootDir, deps),
+    checkExtensionSource(rootDir, deps),
+    checkExtensionPackage(rootDir, deps),
+  ];
+
+  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,
+    passCount,
+    warnCount,
+    failCount,
+    exitCode: failCount > 0 ? 1 : 0,
+  };
+}
+
+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 doctorHelp(): string {
+  return [
+    "agent-inspector doctor",
+    "",
+    "Usage:",
+    "  agent-inspector doctor [--port <port>] [--config-dir <dir>] [--providers <json>]",
+    "",
+    "Checks local proxy health, provider config presence, package metadata, and Chrome companion readiness.",
+    "",
+  ].join("\n");
+}
+
+async function fetchHealth(port: number): Promise<HealthProbe> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/api/health`, {
+      cache: "no-store",
+      signal: controller.signal,
+    });
+    return { ok: response.ok, status: response.status };
+  } catch {
+    return { ok: false, status: 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;
+  }
+}
+
+export function createDoctorDeps(): DoctorDeps {
+  return {
+    env: process.env,
+    platform: process.platform,
+    cwd: process.cwd(),
+    exists: existsSync,
+    readText,
+    listDir,
+    fetchHealth,
+    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;
+  }
+  const report = await buildDoctorReport(parsed.options);
+  process.stdout.write(formatDoctorReport(report));
+  return report.exitCode;
+}