portable-agent-layer 0.85.10 → 0.85.12

package/README.md

@@ -81,7 +81,7 @@ pal cli status        # check your setup
 | `pal cli export` | Export user state (telos, memory) to a zip |
 | `pal cli import` | Import user state from a zip |
 | `pal cli status` | Show current PAL configuration |
-| `pal cli doctor` | Check prerequisites and system health |
+| `pal cli doctor` | Find what is wrong and the command that fixes each problem (`--verbose` lists every check, `--json` for agents); exits 1 on any failure |
 | `pal cli migrate` | Run pending data migrations (non-destructive) |
 | `pal cli analyze [--actionable]` | Learning analysis: rating trends, failure patterns, graduation candidates |
 | `pal cli usage` | Summarize token usage and estimated cost |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.85.10",
+  "version": "0.85.12",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/doctor/agents.ts

@@ -0,0 +1,336 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { palPkg, platform } from "../../hooks/lib/paths";
+import { NO_SESSION_AGENT_MESSAGE } from "../session-agent";
+import { type Finding, failing, optional, passed, warning } from "./finding";
+
+export type AgentName = "claude" | "opencode" | "cursor" | "copilot" | "codex";
+
+const AGENT_NAMES: AgentName[] = ["claude", "codex", "copilot", "cursor", "opencode"];
+
+export interface ToolCheck {
+  name: string;
+  available: boolean;
+  version?: string;
+}
+
+export interface DoctorResult {
+  bun: ToolCheck;
+  claude: ToolCheck;
+  opencode: ToolCheck;
+  cursor: ToolCheck;
+  copilot: ToolCheck;
+  codex: ToolCheck;
+  rtk: ToolCheck;
+  hasAgent: boolean;
+}
+
+function checkTool(cmd: string, versionArgs: string[] = ["--version"]): ToolCheck {
+  try {
+    const result = spawnSync(cmd, versionArgs, {
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: true,
+      timeout: 5000,
+    });
+    if (result.status === 0) {
+      const version = (result.stdout?.toString() || "").trim().split("\n")[0];
+      return { name: cmd, available: true, version };
+    }
+  } catch {
+    // not found
+  }
+  return { name: cmd, available: false };
+}
+
+/**
+ * Copilot ships as a VS Code extension as well as a CLI, and the extension puts
+ * no `copilot` binary on PATH — but both read hooks, skills and agents out of
+ * ~/.copilot. Fall back to that directory so PAL's copilot checks still run.
+ */
+function checkCopilot(): ToolCheck {
+  const cli = checkTool("copilot", ["version"]);
+  if (cli.available) return cli;
+  if (existsSync(platform.copilotDir())) {
+    return { name: "copilot", available: true, version: "~/.copilot (no CLI on PATH)" };
+  }
+  return cli;
+}
+
+/**
+ * The Cursor CLI installs `cursor-agent` (and `agent`) and no `cursor` command;
+ * `cursor` is the editor's shell command. Both read ~/.cursor, so either counts.
+ */
+function checkCursor(): ToolCheck {
+  const cli = checkTool("cursor-agent");
+  if (cli.available) return cli;
+  return checkTool("cursor");
+}
+
+export function detectAgents(): DoctorResult {
+  if (process.env.PAL_SKIP_DOCTOR === "1") {
+    return {
+      bun: { name: "bun", available: true, version: Bun.version },
+      claude: { name: "claude", available: true },
+      opencode: { name: "opencode", available: true },
+      cursor: { name: "cursor", available: true },
+      copilot: { name: "copilot", available: true },
+      codex: { name: "codex", available: true },
+      rtk: { name: "rtk", available: true },
+      hasAgent: true,
+    };
+  }
+  const claude = checkTool("claude");
+  const opencode = checkTool("opencode");
+  const cursor = checkCursor();
+  const copilot = checkCopilot();
+  const codex = checkTool("codex");
+  return {
+    bun: { name: "bun", available: true, version: Bun.version },
+    claude,
+    opencode,
+    cursor,
+    copilot,
+    codex,
+    rtk: checkTool("rtk"),
+    hasAgent: [claude, opencode, cursor, copilot, codex].some((tool) => tool.available),
+  };
+}
+
+export function installedAgents(result: DoctorResult): AgentName[] {
+  return AGENT_NAMES.filter((name) => result[name].available);
+}
+
+interface AgentLayout {
+  label: string;
+  skillsDir: () => string;
+  hookFile?: () => string;
+  instructions?: { file: () => string; name: string };
+}
+
+const LAYOUT: Record<AgentName, AgentLayout> = {
+  claude: {
+    label: "Claude Code",
+    skillsDir: () => resolve(platform.claudeDir(), "skills"),
+    hookFile: () => resolve(platform.claudeDir(), "settings.json"),
+    instructions: {
+      file: () => resolve(platform.claudeDir(), "CLAUDE.md"),
+      name: "CLAUDE.md",
+    },
+  },
+  codex: {
+    label: "Codex",
+    skillsDir: () => resolve(platform.codexDir(), "skills"),
+    hookFile: () => resolve(platform.codexDir(), "hooks.json"),
+  },
+  copilot: {
+    label: "Copilot",
+    skillsDir: () => resolve(platform.copilotDir(), "skills"),
+    hookFile: () => resolve(platform.copilotDir(), "hooks", "pal-hooks.json"),
+  },
+  cursor: {
+    label: "Cursor",
+    skillsDir: () => resolve(platform.cursorDir(), "skills"),
+    hookFile: () => resolve(platform.cursorDir(), "hooks.json"),
+  },
+  opencode: {
+    label: "opencode",
+    skillsDir: () => resolve(platform.agentsDir(), "skills"),
+  },
+};
+
+const reinstall = (agent: AgentName) => ({
+  say: `Reinstall PAL for ${LAYOUT[agent].label}`,
+  command: `pal cli install --${agent}`,
+});
+
+/** Hook-config keys that carry a shell command: cross-platform and per-shell variants. */
+function isHookCommandField(key: string): boolean {
+  return key === "command" || key === "bash" || key === "powershell";
+}
+
+function extractAllHookCommands(obj: unknown, out: string[] = []): string[] {
+  if (Array.isArray(obj)) {
+    for (const item of obj) extractAllHookCommands(item, out);
+  } else if (obj && typeof obj === "object") {
+    for (const [k, v] of Object.entries(obj)) {
+      if (isHookCommandField(k) && typeof v === "string") {
+        out.push(v);
+      } else {
+        extractAllHookCommands(v, out);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * True when a hook command names its agent, by env prefix or by argv flag.
+ *
+ * An env prefix only parses in one shell family, so hook configs whose host
+ * shell is unknown declare the agent with a shell-agnostic `--agent=` flag.
+ */
+function declaresAgent(cmd: string, agentName: string): boolean {
+  return (
+    cmd.startsWith(`PAL_AGENT=${agentName} `) ||
+    cmd.startsWith(`$env:PAL_AGENT='${agentName}'; `) ||
+    cmd.includes(`--agent=${agentName}`)
+  );
+}
+
+const SCRIPT =
+  /"([^"]+\.(?:ts|js|mjs|sh|ps1))"|'([^']+\.(?:ts|js|mjs|sh|ps1))'|(\S+\.(?:ts|js|mjs|sh|ps1))(?=\s|$)/g;
+
+function scriptPaths(cmd: string): string[] {
+  return Array.from(cmd.matchAll(SCRIPT), (m) => m[1] ?? m[2] ?? m[3] ?? "").filter(
+    isAbsolute
+  );
+}
+
+function isPalHook(cmd: string, agent: AgentName): boolean {
+  return (
+    declaresAgent(cmd, agent) ||
+    scriptPaths(cmd).some((path) => /[\\/]src[\\/]hooks[\\/][^\\/]+$/.test(path))
+  );
+}
+
+function readHookCommands(file: string): string[] | "missing" | "unreadable" {
+  if (!existsSync(file)) return "missing";
+  try {
+    const data = JSON.parse(readFileSync(file, "utf-8"));
+    return extractAllHookCommands(data.hooks ?? data);
+  } catch {
+    return "unreadable";
+  }
+}
+
+function hookFindings(agent: AgentName, file: string): Finding[] {
+  const label = LAYOUT[agent].label;
+  const commands = readHookCommands(file);
+  if (commands === "unreadable")
+    return [
+      failing(
+        `${agent}.hooks.unreadable`,
+        `${label} hook config is not valid JSON (${file})`,
+        {
+          say: `Fix the JSON in ${file}, then reinstall`,
+          command: `pal cli install --${agent}`,
+        }
+      ),
+    ];
+  const pal = commands === "missing" ? [] : commands.filter((c) => isPalHook(c, agent));
+  if (!pal.some((c) => c.includes("LoadContext")))
+    return [
+      failing(
+        `${agent}.hooks.missing`,
+        `${label} hooks are not registered`,
+        reinstall(agent)
+      ),
+    ];
+
+  const findings = [passed(`${agent}.hooks`, `${label}: ${pal.length} hooks registered`)];
+  const undeclared = pal.filter((c) => !declaresAgent(c, agent));
+  if (undeclared.length > 0)
+    findings.push(
+      failing(
+        `${agent}.hooks.undeclared`,
+        `${label}: ${undeclared.length} of ${pal.length} hooks do not name ${agent} as their agent`,
+        reinstall(agent)
+      )
+    );
+  const broken = pal.filter((c) => scriptPaths(c).some((path) => !existsSync(path)));
+  if (broken.length > 0)
+    findings.push(
+      failing(
+        `${agent}.hooks.scripts`,
+        `${label}: ${broken.length} of ${pal.length} hooks run a script that no longer exists (${scriptPaths(broken[0]).find((p) => !existsSync(p))})`,
+        reinstall(agent)
+      )
+    );
+  return findings;
+}
+
+function opencodePluginFindings(): Finding[] {
+  const installed = resolve(platform.opencodeDir(), "plugins", "pal-plugin.ts");
+  const source = resolve(palPkg(), "src", "targets", "opencode", "plugin.ts");
+  if (!existsSync(installed))
+    return [
+      failing(
+        "opencode.hooks.missing",
+        "opencode plugin is not installed",
+        reinstall("opencode")
+      ),
+    ];
+  if (existsSync(source) && statSync(installed).mtimeMs < statSync(source).mtimeMs)
+    return [
+      warning(
+        "opencode.plugin.stale",
+        "opencode plugin is older than PAL's — recent fixes have not reached opencode",
+        reinstall("opencode")
+      ),
+    ];
+  return [passed("opencode.hooks", "opencode plugin installed and current")];
+}
+
+function countSkills(dir: string): number {
+  if (!existsSync(dir)) return 0;
+  return readdirSync(dir).filter((f) => existsSync(resolve(dir, f, "SKILL.md"))).length;
+}
+
+function oneAgentFindings(agent: AgentName): Finding[] {
+  const layout = LAYOUT[agent];
+  const skills = countSkills(layout.skillsDir());
+  const findings = [
+    skills > 0
+      ? passed(`${agent}.skills`, `${layout.label}: ${skills} skills`)
+      : warning(`${agent}.skills`, `${layout.label} has no PAL skills`, reinstall(agent)),
+  ];
+  findings.push(
+    ...(layout.hookFile
+      ? hookFindings(agent, layout.hookFile())
+      : opencodePluginFindings())
+  );
+  if (layout.instructions) {
+    const { file, name } = layout.instructions;
+    findings.push(
+      existsSync(file())
+        ? passed(`${agent}.instructions`, `${name} present`)
+        : failing(`${agent}.instructions`, `${name} is missing`, reinstall(agent))
+    );
+  }
+  return findings;
+}
+
+export function agentFindings(agents: AgentName[]): Finding[] {
+  if (agents.length === 0) return [];
+  const agentsMd = resolve(platform.opencodeDir(), "AGENTS.md");
+  return [
+    existsSync(agentsMd)
+      ? passed("agents-md", "AGENTS.md present")
+      : failing("agents-md", "AGENTS.md is missing", {
+          say: "Reinstall PAL",
+          command: "pal cli install",
+        }),
+    ...agents.flatMap(oneAgentFindings),
+  ];
+}
+
+export function rosterFindings(agents: AgentName[]): Finding[] {
+  if (agents.length === 0)
+    return [
+      failing("agents.none", "No supported agent is installed", {
+        say: NO_SESSION_AGENT_MESSAGE,
+      }),
+    ];
+  const others = AGENT_NAMES.filter((name) => !agents.includes(name));
+  if (others.length === 0) return [];
+  return [
+    optional(
+      "agents.others",
+      `Other agents PAL supports — ${others.map((name) => LAYOUT[name].label).join(", ")}`,
+      {
+        say: `install it, then run pal cli install --${others.length === 1 ? others[0] : "<agent>"}`,
+      }
+    ),
+  ];
+}

package/src/cli/doctor/environment.ts

@@ -0,0 +1,129 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { palPkg } from "../../hooks/lib/paths";
+import { findBinaryOnPath } from "../../hooks/lib/which";
+import type { ToolCheck } from "./agents";
+import { type Finding, type Fix, failing, optional, passed, warning } from "./finding";
+import { osReleaseField, readOsRelease } from "./os-release";
+import { versionControlFindings } from "./version-control";
+
+interface PlaywrightBuild {
+  version: string;
+  revision: string;
+}
+
+interface BrowserHost {
+  browsersPath: string;
+  playwright: PlaywrightBuild | null;
+  platform: NodeJS.Platform;
+  arch: string;
+  osRelease: string;
+}
+
+const NEWEST_UBUNTU_PLAYWRIGHT_KNOWS = 24.04;
+
+function playwrightBrowsersPath(): string {
+  if (process.env.PLAYWRIGHT_BROWSERS_PATH) return process.env.PLAYWRIGHT_BROWSERS_PATH;
+  const home = homedir();
+  if (process.platform === "darwin") return resolve(home, "Library/Caches/ms-playwright");
+  if (process.platform === "win32") return resolve(home, "AppData/Local/ms-playwright");
+  return resolve(home, ".cache/ms-playwright");
+}
+
+function installedPlaywright(): PlaywrightBuild | null {
+  try {
+    const pkg = Bun.resolveSync("playwright-core/package.json", palPkg());
+    const { version } = JSON.parse(readFileSync(pkg, "utf-8"));
+    const { browsers } = JSON.parse(
+      readFileSync(resolve(dirname(pkg), "browsers.json"), "utf-8")
+    );
+    const shell = (browsers as { name: string; revision: string }[]).find(
+      (b) => b.name === "chromium-headless-shell"
+    );
+    return shell ? { version, revision: shell.revision } : null;
+  } catch {
+    return null;
+  }
+}
+
+function hasChromium(host: BrowserHost): boolean {
+  if (!existsSync(host.browsersPath)) return false;
+  const dirs = readdirSync(host.browsersPath);
+  const revision = host.playwright?.revision;
+  return revision
+    ? dirs.some(
+        (d) => d === `chromium_headless_shell-${revision}` || d === `chromium-${revision}`
+      )
+    : dirs.some((d) => d.startsWith("chromium"));
+}
+
+function playwrightPlatformOverride(host: BrowserHost): string {
+  if (host.platform !== "linux") return "";
+  if (osReleaseField(host.osRelease, "ID") !== "ubuntu") return "";
+  const version = Number.parseFloat(osReleaseField(host.osRelease, "VERSION_ID"));
+  if (!(version > NEWEST_UBUNTU_PLAYWRIGHT_KNOWS)) return "";
+  return `PLAYWRIGHT_HOST_PLATFORM_OVERRIDE=ubuntu24.04-${host.arch === "arm64" ? "arm64" : "x64"} `;
+}
+
+export function playwrightFinding(host: BrowserHost): Finding {
+  if (hasChromium(host)) return passed("playwright", "Playwright Chromium installed");
+  const pinned = host.playwright ? `playwright@${host.playwright.version}` : "playwright";
+  const override = playwrightPlatformOverride(host);
+  return warning(
+    "playwright.missing",
+    "Playwright's Chromium is not installed — create-pdf, consulting-report and screenshots fail",
+    {
+      say: override
+        ? "Install it as Ubuntu 24.04, which Playwright supports"
+        : "Install it",
+      command: `${override}bun x ${pinned} install chromium`,
+    }
+  );
+}
+
+function palOnPathFinding(): Finding {
+  const pal = findBinaryOnPath("pal");
+  return pal
+    ? passed("pal.path", `pal on PATH — ${pal}`)
+    : failing("pal.path", "pal is not on PATH — skills that run 'pal cli …' fail", {
+        say: "Install PAL globally",
+        command: "bun add -g portable-agent-layer",
+      });
+}
+
+function rtkInstall(): Fix {
+  if (process.platform === "win32")
+    return {
+      say: "Download rtk.exe from https://github.com/rtk-ai/rtk/releases and add it to PATH",
+    };
+  if (process.platform === "darwin")
+    return { say: "Install rtk", command: "brew install rtk" };
+  return {
+    say: "Install rtk",
+    command:
+      "curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh",
+  };
+}
+
+function rtkFinding(rtk: ToolCheck): Finding {
+  return rtk.available
+    ? passed("rtk", rtk.version || "rtk")
+    : optional("rtk.missing", "rtk — compresses long command output", rtkInstall());
+}
+
+export function environmentFindings(rtk: ToolCheck): Finding[] {
+  return [
+    passed("bun", `Bun ${Bun.version}`),
+    palOnPathFinding(),
+    playwrightFinding({
+      browsersPath: playwrightBrowsersPath(),
+      playwright: installedPlaywright(),
+      platform: process.platform,
+      arch: process.arch,
+      osRelease: readOsRelease(),
+    }),
+    rtkFinding(rtk),
+    ...versionControlFindings(),
+  ];
+}

package/src/cli/doctor/finding.ts

@@ -0,0 +1,35 @@
+/**
+ * One thing the doctor looked at. A problem carries the fix as a sentence and,
+ * where one exists, the exact command — so a later `--fix` can run it and an
+ * agent reading `--json` can propose it.
+ */
+
+export type Severity = "fail" | "warn" | "optional" | "ok";
+
+export interface Fix {
+  say: string;
+  command?: string;
+}
+
+export interface Finding {
+  id: string;
+  severity: Severity;
+  title: string;
+  fix?: Fix;
+}
+
+export function passed(id: string, title: string): Finding {
+  return { id, severity: "ok", title };
+}
+
+export function failing(id: string, title: string, fix?: Fix): Finding {
+  return { id, severity: "fail", title, fix };
+}
+
+export function warning(id: string, title: string, fix?: Fix): Finding {
+  return { id, severity: "warn", title, fix };
+}
+
+export function optional(id: string, title: string, fix: Fix): Finding {
+  return { id, severity: "optional", title, fix };
+}

package/src/cli/doctor/health.ts

@@ -0,0 +1,54 @@
+import { resolve } from "node:path";
+import { cachedStatus, type UpdateCache } from "../../hooks/handlers/update-check";
+import { type HookErrorGroup, recentHookErrors } from "../../hooks/lib/log";
+import { palHome } from "../../hooks/lib/paths";
+import { checkPendingMigrations } from "../migrate";
+import { type Finding, passed, warning } from "./finding";
+
+interface PendingMigration {
+  id: string;
+  description: string;
+  detail?: string;
+}
+
+export function hookErrorFindings(groups: HookErrorGroup[]): Finding[] {
+  if (groups.length === 0)
+    return [passed("hook-errors", "No hook errors in the last 24h")];
+  const log = resolve(palHome(), "debug", "debug.log");
+  return groups.map((group) => {
+    const times = group.count === 1 ? "once" : `${group.count} times`;
+    return warning(
+      `hook-errors.${group.source}`,
+      `${group.source} failed ${times} in the last 24h — last: ${group.last}`,
+      { say: `Full trace in ${log}` }
+    );
+  });
+}
+
+export function migrationFindings(pending: PendingMigration[]): Finding[] {
+  if (pending.length === 0) return [passed("migrations", "No pending migrations")];
+  return pending.map((migration) => {
+    const detail = migration.detail ? ` (${migration.detail})` : "";
+    return warning(
+      `migration.${migration.id}`,
+      `Migration pending: ${migration.description}${detail}`,
+      { say: "Run it", command: "pal cli migrate" }
+    );
+  });
+}
+
+export function updateFinding(cache: UpdateCache | null): Finding {
+  if (!cache?.available) return passed("update", "PAL is up to date");
+  return warning("update", `PAL ${cache.latest} is out (${cache.current} installed)`, {
+    say: "Update",
+    command: "pal cli update",
+  });
+}
+
+export function healthFindings(): Finding[] {
+  return [
+    ...hookErrorFindings(recentHookErrors()),
+    ...migrationFindings(checkPendingMigrations()),
+    updateFinding(cachedStatus()),
+  ];
+}

package/src/cli/doctor/inference.ts

@@ -0,0 +1,91 @@
+import { resolve } from "node:path";
+import { previewInferenceRoute } from "../../hooks/lib/inference";
+import { opencodeBackgroundModel } from "../../hooks/lib/opencode-config";
+import { platform } from "../../hooks/lib/paths";
+import type { AgentName } from "./agents";
+import { type Finding, failing, optional, passed, warning } from "./finding";
+
+type Env = Record<string, string | undefined>;
+
+const SUBPROCESS_ONLY = {
+  PAL_SPAWNED_INFERENCE: "every inference call refuses",
+  PAL_INFERENCE_DEPTH: "the depth breaker fires on the first call",
+  PAL_INFERENCE_DISABLED: "every inference call fails",
+} as const;
+
+const API_KEYS = {
+  PAL_ANTHROPIC_API_KEY: "fallback when the claude CLI cannot answer",
+  PAL_OPENAI_API_KEY: "fallback when the codex CLI cannot answer",
+  PAL_GEMINI_API_KEY: "YouTube analysis and Gemini research",
+  PAL_XAI_API_KEY: "the Grok researcher",
+  PAL_PERPLEXITY_API_KEY: "the Perplexity researcher",
+} as const;
+
+function unsetCommand(name: string, os: NodeJS.Platform): string {
+  return os === "win32" ? `Remove-Item Env:${name}` : `unset ${name}`;
+}
+
+export function leakedEnvFindings(env: Env, os: NodeJS.Platform): Finding[] {
+  return Object.entries(SUBPROCESS_ONLY).map(([name, effect]) =>
+    env[name]
+      ? failing(
+          `env.${name}`,
+          `${name}=${env[name]} leaked into your shell — ${effect}`,
+          {
+            say: "Clear it, and remove it from your shell profile if it is set there",
+            command: unsetCommand(name, os),
+          }
+        )
+      : passed(`env.${name}`, `${name} not set`)
+  );
+}
+
+export function apiKeyFindings(env: Env): Finding[] {
+  return Object.entries(API_KEYS).map(([name, unlocks]) =>
+    env[name]
+      ? passed(`key.${name}`, `${name} set`)
+      : optional(`key.${name}`, `${name} — ${unlocks}`, {
+          say: "set it in your shell profile",
+        })
+  );
+}
+
+function routeFinding(): Finding | null {
+  const preview = previewInferenceRoute();
+  if (preview.route === "disabled") return null;
+  if (preview.route === "none")
+    return failing(
+      "inference.none",
+      `Background inference has no route for ${preview.agent} — ${preview.reason}`,
+      { say: "Install the agent's CLI, or set an API key PAL can fall back to" }
+    );
+  if (preview.route.endsWith("-api"))
+    return warning(
+      "inference.api",
+      `Background inference goes through ${preview.route} (${preview.reason}) — it bills the API key`,
+      { say: "Put the agent's CLI on PATH to use your subscription instead" }
+    );
+  return passed("inference", `Inference: ${preview.route} (${preview.reason})`);
+}
+
+function opencodeModelFinding(): Finding {
+  return opencodeBackgroundModel()
+    ? passed("opencode.model", "opencode background model pinned")
+    : warning(
+        "opencode.model",
+        "opencode background model is not pinned — background inference uses whatever the TUI last picked",
+        {
+          say: `Pin one with "model" in ${resolve(platform.opencodeDir(), "config.json")}`,
+        }
+      );
+}
+
+export function inferenceFindings(agents: AgentName[]): Finding[] {
+  const route = routeFinding();
+  return [
+    ...(route ? [route] : []),
+    ...(agents.includes("opencode") ? [opencodeModelFinding()] : []),
+    ...leakedEnvFindings(process.env, process.platform),
+    ...apiKeyFindings(process.env),
+  ];
+}

package/src/cli/doctor/os-release.ts

@@ -0,0 +1,30 @@
+import { readFileSync } from "node:fs";
+
+export type LinuxFamily = "debian" | "fedora" | "arch" | "alpine" | "suse";
+
+export function osReleaseField(osRelease: string, key: string): string {
+  return osRelease.match(new RegExp(String.raw`^${key}="?([^"\n]*)"?$`, "m"))?.[1] ?? "";
+}
+
+export function linuxFamily(osRelease: string): LinuxFamily | null {
+  const ids = `${osReleaseField(osRelease, "ID")} ${osReleaseField(osRelease, "ID_LIKE")}`
+    .split(/\s+/)
+    .filter(Boolean);
+  const families: [LinuxFamily, string[]][] = [
+    ["debian", ["debian", "ubuntu"]],
+    ["fedora", ["fedora", "rhel", "centos"]],
+    ["arch", ["arch"]],
+    ["alpine", ["alpine"]],
+    ["suse", ["suse", "opensuse"]],
+  ];
+  return families.find(([, names]) => names.some((n) => ids.includes(n)))?.[0] ?? null;
+}
+
+export function readOsRelease(): string {
+  if (process.platform !== "linux") return "";
+  try {
+    return readFileSync("/etc/os-release", "utf-8");
+  } catch {
+    return "";
+  }
+}