@techysy/10router 1.1.2 → 1.2.0

package/hooks/sqliteRuntime.js

@@ -41,12 +41,17 @@ function ensureRuntimeDir() {
   return dir;
 }
 
-function hasModule(name) {
-  return fs.existsSync(path.join(getRuntimeNodeModules(), name, "package.json"));
+// Both helpers take the node_modules dir explicitly so a *diagnostic* can ask
+// about a directory it was handed (doctor) while production code keeps the one
+// default that matters. They are the single source of truth for "installed" vs
+// "installed and actually usable": npm happily reports better-sqlite3 as present
+// when its compiled binary never got built.
+function hasModule(name, nodeModulesDir = getRuntimeNodeModules()) {
+  return fs.existsSync(path.join(nodeModulesDir, name, "package.json"));
 }
 
-function isBetterSqliteBinaryValid() {
-  const binary = path.join(getRuntimeNodeModules(), "better-sqlite3", "build", "Release", "better_sqlite3.node");
+function isBetterSqliteBinaryValid(nodeModulesDir = getRuntimeNodeModules()) {
+  const binary = path.join(nodeModulesDir, "better-sqlite3", "build", "Release", "better_sqlite3.node");
   if (!fs.existsSync(binary)) return false;
   try {
     const fd = fs.openSync(binary, "r");
@@ -88,11 +93,19 @@ function runNpmInstall({ cwd, pkgs, extraArgs = [], timeout = 180000 }) {
   return { ok: res.status === 0, code: res.status, stderr: res.stderr || "", stdout: res.stdout || "" };
 }
 
+// Always let npm RECORD these installs — never suppress saving. The runtime dir
+// (~/.10router/runtime) is a single npm project shared by this hook and
+// trayRuntime.js. A package present in node_modules but absent from
+// runtime/package.json is "extraneous", so the next `npm install` in this dir
+// prunes it: sqlite hook installs better-sqlite3 → tray hook installs systray2
+// and prunes better-sqlite3 → the round after prunes systray2 right back.
+// Recording each install as a real dependency makes npm keep both. (Regression
+// guard: tests/unit/runtime-hooks-install-args.test.js asserts no hook ever
+// passes the save-suppressing flag.)
 function npmInstall(pkgs, opts = {}) {
   const cwd = ensureRuntimeDir();
-  const extra = opts.optional ? ["--no-save"] : [];
   if (!opts.silent) console.log("⏳ Installing SQLite engine (first run)...");
-  const res = runNpmInstall({ cwd, pkgs, extraArgs: extra, timeout: opts.timeout || 180000 });
+  const res = runNpmInstall({ cwd, pkgs, timeout: opts.timeout || 180000 });
   if (!res.ok && !opts.silent) {
     const reason = summarizeNpmError(res.stderr);
     console.warn("⚠️  SQLite engine install failed — using fallback");
@@ -107,10 +120,10 @@ function npmInstall(pkgs, opts = {}) {
 // from nested node_modules — verify and reinstall if missing. node:sqlite is
 // built-in. This is purely a *speed optimization* — app works without
 // better-sqlite3 via fallbacks.
-function isSqlJsWasmValid() {
+function isSqlJsWasmValid(nodeModulesDir = getRuntimeNodeModules()) {
   const bundledWasm = path.join(__dirname, "..", "app", "node_modules", "sql.js", "dist", "sql-wasm.wasm");
   if (fs.existsSync(bundledWasm)) return true;
-  const runtimeWasm = path.join(getRuntimeNodeModules(), "sql.js", "dist", "sql-wasm.wasm");
+  const runtimeWasm = path.join(nodeModulesDir, "sql.js", "dist", "sql-wasm.wasm");
   return fs.existsSync(runtimeWasm);
 }
 
@@ -129,7 +142,7 @@ function ensureSqliteRuntime({ silent = false } = {}) {
     return { betterSqlite: true, sqlJs: sqlJsOk };
   }
 
-  const ok = npmInstall([`better-sqlite3@${BETTER_SQLITE3_VERSION}`], { optional: true, silent });
+  const ok = npmInstall([`better-sqlite3@${BETTER_SQLITE3_VERSION}`], { silent });
   return {
     betterSqlite: ok && hasModule("better-sqlite3") && isBetterSqliteBinaryValid(),
     sqlJs: sqlJsOk,
@@ -153,4 +166,9 @@ module.exports = {
   getRuntimeNodeModules,
   runNpmInstall,
   summarizeNpmError,
+  npmInstall,
+  getDataDir,
+  hasModule,
+  isBetterSqliteBinaryValid,
+  isSqlJsWasmValid,
 };

package/hooks/trayRuntime.js

@@ -74,7 +74,10 @@ function ensureRuntimeDir() {
 function npmInstall(pkgs, { silent = false } = {}) {
   const cwd = ensureRuntimeDir();
   if (!silent) console.log("⏳ Installing system tray (first run)...");
-  const res = runNpmInstall({ cwd, pkgs, extraArgs: ["--no-save"], timeout: 120000 });
+  // Let npm record systray2 as a dependency — do NOT suppress saving: the
+  // runtime dir is one shared npm project, so an unrecorded package gets pruned
+  // by the sqlite hook's next install (see npmInstall in sqliteRuntime.js).
+  const res = runNpmInstall({ cwd, pkgs, timeout: 120000 });
   if (!res.ok && !silent) {
     const reason = summarizeNpmError(res.stderr);
     console.warn("⚠️  System tray install failed — tray disabled");
@@ -104,4 +107,4 @@ function ensureTrayRuntime({ silent = false } = {}) {
   return { systray: ok && hasSystray() };
 }
 
-module.exports = { ensureTrayRuntime };
+module.exports = { ensureTrayRuntime, npmInstall };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techysy/10router",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "10Router CLI - Start and manage 10Router server",
   "publishConfig": {
     "access": "public"
@@ -32,7 +32,7 @@
     "react-dom": "19.2.1"
   },
   "comment_postinstall": "`|| exit 0` is deliberate: this hook only warms ~/.10router/runtime, and cli.js re-runs the same ensureSqliteRuntime/ensureTrayRuntime on every start, so a failure here costs nothing. Without it npm aborts the whole install — e.g. running Windows npm against a WSL path, where cmd.exe cannot cd to a UNC directory, falls back to C:\\Windows and node then cannot find hooks/postinstall.js at all, so the script's own try/catch never gets to run.",
-  "comment_sqlite": "sql.js + better-sqlite3 are NOT bundled here. They are installed into ~/.10router/runtime/node_modules by hooks/postinstall.js (and re-checked at runtime by cli.js). This avoids Windows EBUSY errors when updating the global CLI, since native .node files no longer live under the locked install dir.",
+  "comment_sqlite": "sql.js + better-sqlite3 are NOT bundled here. They are installed into ~/.10router/runtime/node_modules by hooks/postinstall.js (and re-checked at runtime by cli.js). This avoids Windows EBUSY errors when updating the global CLI, since native .node files no longer live under the locked install dir. Both runtime deps are installed WITH save (never --no-save): the runtime dir is a single shared npm project, so a package found in node_modules but missing from runtime/package.json is pruned as extraneous by the other hook's next install, and the two hooks would otherwise uninstall each other in a ping-pong.",
   "comment_systray": "systray2 is NOT bundled here. It is lazy-installed into ~/.10router/runtime/node_modules by hooks/postinstall.js on macOS/Linux only. Windows uses PowerShell NotifyIcon (zero binary). This avoids shipping unsigned Go binaries that trigger antivirus false positives (Kaspersky). We use the systray2 fork because the legacy systray@1.0.5 ships a 2017 x86_64 binary that fails on modern macOS dyld.",
   "engines": {
     "node": ">=18.0.0"
@@ -45,6 +45,15 @@
     "api"
   ],
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/techysy/10router.git",
+    "directory": "cli"
+  },
+  "homepage": "https://github.com/techysy/10router#readme",
+  "bugs": {
+    "url": "https://github.com/techysy/10router/issues"
+  },
   "devDependencies": {
     "esbuild": "^0.25.12",
     "nodemon": "^3.1.14"

package/src/cli/doctor.js

@@ -0,0 +1,525 @@
+"use strict";
+
+/**
+ * `10router doctor` — one command that answers "why is this install misbehaving?".
+ *
+ * Why it exists (issue #24): the three failure modes users hit all present the
+ * same way — the dashboard serves a stale/blank page, or the app "installs fine
+ * but will not start" — while every existing self-check answers "fine":
+ *   §1  the two runtime hooks pruned each other's npm installs, so
+ *       better-sqlite3 sat in node_modules but was absent from
+ *       runtime/package.json: `npm ls` cannot see it and /api/health still said
+ *       ok;
+ *   §3  a server from the PREVIOUS build was still holding the port, so the
+ *       binary that answered /api/health was the old one;
+ *   §4  a global better-sqlite3 shadowed the runtime copy, and /api/health did
+ *       not even name the driver it settled on.
+ * All three needed a human to walk processes, node_modules and version markers
+ * by hand. Doctor is that walk, scripted.
+ *
+ * Hard rules (see docs/zh-CN/spec-10router-doctor.md):
+ *   - READ-ONLY. No DB initialisation (the same rule /api/health follows — a
+ *     health probe that opens SQLite is its own outage), no file writes, no
+ *     killing, no restarts. `--fix` is deliberately out of scope: the blast
+ *     radius differs per finding (kill a process / reinstall a dependency /
+ *     migrate data) and that is a product decision, not a diagnosis.
+ *   - Every check is a pure function over already-collected facts, so the whole
+ *     decision table is unit-testable without a port, a process or a real data
+ *     dir. `collectChecks()` is the only part that touches the machine.
+ *   - `--json` is a contract: it carries check IDs and reason codes, NEVER
+ *     translated text, and is versioned by `schemaVersion`.
+ */
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const net = require("net");
+
+const { t } = require("./i18n");
+const { getDataDir, getRuntimeDir, isBetterSqliteBinaryValid, isSqlJsWasmValid } = require("../../hooks/sqliteRuntime");
+const {
+  diskVersionPath,
+  pidFilePath,
+  probeServerVersion,
+  readDiskVersion,
+  readPidFile,
+} = require("./staleServer");
+
+const SCHEMA_VERSION = 1;
+const DEFAULT_PORT = 20128;
+
+/** `cli/app` — the built server this launcher spawns (`<repo>/cli/app`). */
+const APP_DIR = path.join(__dirname, "..", "..", "app");
+/** Written by cli/scripts/build-cli.js; its absence means "a half-finished upgrade". */
+const BUILD_DIST_DIR = ".next-cli-build";
+/** All three must exist for the launcher to have something to serve. */
+const BUILD_MARKERS = ["custom-server.js", "server.js", path.join(BUILD_DIST_DIR, "server")];
+/**
+ * What the runtime dir is expected to hold. sql.js is the always-works fallback,
+ * better-sqlite3 the speed path; systray2 only exists on macOS/Linux (Windows
+ * gets an in-process tray), so it is not "missing" there.
+ */
+const RUNTIME_MODULES = ["sql.js", "better-sqlite3"];
+const RUNTIME_MODULES_POSIX = ["systray2"];
+
+const OK = "ok";
+const YELLOW = "yellow";
+const RED = "red";
+
+const STATUS_ICON = { [OK]: "✅", [YELLOW]: "⚠️ ", [RED]: "❌" };
+
+// ---------------------------------------------------------------------------
+// Probes (the only side-effecting code in this file — all read-only)
+// ---------------------------------------------------------------------------
+
+/** Is anything accepting TCP connections on the port? */
+function probeTcp(port, { timeoutMs = 800, host = "127.0.0.1" } = {}) {
+  return new Promise((resolve) => {
+    const socket = net.connect({ host, port });
+    let settled = false;
+    const done = (value) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(value);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once("connect", () => done(true));
+    socket.once("timeout", () => done(false));
+    socket.once("error", () => done(false));
+  });
+}
+
+/** `/api/health` is read-only by design, so this cannot open the DB. */
+async function probeHealth(port, { fetchImpl = globalThis.fetch, timeoutMs = 2000 } = {}) {
+  if (typeof fetchImpl !== "function") return null;
+  const controller = typeof AbortController === "function" ? new AbortController() : null;
+  const timer = controller ? setTimeout(() => controller.abort(), timeoutMs) : null;
+  try {
+    const res = await fetchImpl(`http://127.0.0.1:${port}/api/health`, {
+      signal: controller ? controller.signal : undefined,
+      cache: "no-store",
+    });
+    if (!res || !res.ok) return null;
+    const data = await res.json();
+    return data && typeof data === "object" ? data : null;
+  } catch {
+    return null;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/** PIDs listening on the port. Read-only twin of cli.js's killProcessOnPort(). */
+function findPortOwners(port, { platform = process.platform, execSync } = {}) {
+  const run = execSync || require("child_process").execSync;
+  try {
+    if (platform === "win32") {
+      const out = String(
+        run(`netstat -ano | findstr :${port}`, {
+          encoding: "utf8",
+          shell: true,
+          windowsHide: true,
+          timeout: 5000,
+        }) || "",
+      ).trim();
+      const pids = out
+        .split("\n")
+        .filter((line) => line.includes("LISTENING"))
+        .map((line) => Number(line.trim().split(/\s+/).pop()))
+        .filter((pid) => Number.isInteger(pid) && pid > 0);
+      return [...new Set(pids)];
+    }
+    const out = String(
+      run(`lsof -ti:${port}`, {
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "ignore"],
+        timeout: 5000,
+      }) || "",
+    ).trim();
+    const pids = out
+      .split("\n")
+      .map((line) => Number(line.trim()))
+      .filter((pid) => Number.isInteger(pid) && pid > 0);
+    return [...new Set(pids)];
+  } catch {
+    // Nothing listening, or netstat/lsof unavailable — "no owner known", never
+    // "no owner", so callers must not conclude the port is free from this alone.
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Small read-only filesystem helpers
+// ---------------------------------------------------------------------------
+
+function isWritable(dir) {
+  try {
+    fs.accessSync(dir, fs.constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readJsonFile(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The runtime dir is one npm project shared by both hooks, so "installed but not
+ * declared" is exactly the §1 state: the next `npm install` here prunes it.
+ *
+ * `broken` is the other half of that story: a module npm considers installed can
+ * still be unusable (better-sqlite3 without its compiled binary, sql.js without
+ * its wasm). That is the state §4 showed as "a fallback driver, and nothing says
+ * why" — the directory looks complete, so only the artifact check catches it.
+ */
+function readRuntimeState(runtimeDir) {
+  const pkg = readJsonFile(path.join(runtimeDir, "package.json"));
+  const declared = Object.keys(pkg?.dependencies || {});
+  const nodeModulesDir = path.join(runtimeDir, "node_modules");
+  let installed = [];
+  try {
+    installed = fs
+      .readdirSync(nodeModulesDir)
+      .filter((name) => name !== ".package-lock.json" && !name.startsWith("."))
+      .filter((name) => fs.existsSync(path.join(nodeModulesDir, name, "package.json")));
+  } catch {
+    installed = [];
+  }
+  const broken = [];
+  if (installed.includes("better-sqlite3") && !isBetterSqliteBinaryValid(nodeModulesDir)) broken.push("better-sqlite3");
+  if (installed.includes("sql.js") && !isSqlJsWasmValid(nodeModulesDir)) broken.push("sql.js");
+  return { declared, installed, broken };
+}
+
+/** The legacy 9Router data dir, still waiting to be migrated. */
+function legacyDirPath({ platform = process.platform } = {}) {
+  return platform === "win32"
+    ? path.join(process.env.APPDATA || "", "9router")
+    : path.join(os.homedir(), ".9router");
+}
+
+// Mirror of src/lib/dataDir.js `hasAppData()` — deliberately NOT "is the dir
+// non-empty": on Windows the data dir doubles as Electron's userData profile
+// (Cache/, GPUCache/ …), so non-emptiness is always true and would pin the
+// migration — and this check — off. Keeping the same file list means doctor and
+// the app can never disagree about whether a migration is still pending.
+const LEGACY_JSON_FILES = ["db.json", "usage.json", "disabledModels.json", "request-details.json"];
+
+function hasAppData(dir) {
+  if (fs.existsSync(path.join(dir, "db", "data.sqlite"))) return true;
+  return LEGACY_JSON_FILES.some((name) => fs.existsSync(path.join(dir, name)));
+}
+
+// ---------------------------------------------------------------------------
+// Checks — pure functions: (facts) -> { id, status, reason, facts }
+// ---------------------------------------------------------------------------
+
+const result = (id, status, reason, facts = {}) => ({ id, status, reason, facts });
+
+function checkDataDir({ dataDir, exists, writable, legacyDir, legacyPending }) {
+  const facts = { dir: dataDir };
+  if (exists && !writable) return result("data-dir", RED, "not-writable", facts);
+  // Only while the copy has genuinely not happened. The migration leaves the
+  // legacy dir in place forever (so it can be retried by hand), so "legacy dir
+  // exists" alone is a permanent condition and would be pure noise here.
+  if (legacyPending) return result("data-dir", YELLOW, "legacy-pending", { ...facts, legacy: legacyDir });
+  if (!exists) return result("data-dir", YELLOW, "missing", facts);
+  return result("data-dir", OK, "ok", facts);
+}
+
+function checkBuild({ appDir, missing, appVersion, launcherVersion }) {
+  const facts = { dir: appDir, version: appVersion || null, launcher: launcherVersion || null };
+  if (missing.length) return result("build", RED, "missing-files", { ...facts, missing });
+  if (!appVersion) return result("build", RED, "no-version", facts);
+  if (appVersion !== launcherVersion) return result("build", RED, "version-mismatch", facts);
+  return result("build", OK, "ok", facts);
+}
+
+function checkRuntimeDeps({ runtimeDir, declared, installed, broken, expected }) {
+  const facts = {
+    dir: runtimeDir,
+    orphaned: expected.filter((m) => installed.includes(m) && !declared.includes(m)),
+    broken: (broken || []).filter((m) => expected.includes(m)),
+    missing: expected.filter((m) => !installed.includes(m)),
+  };
+  if (!fs.existsSync(runtimeDir)) return result("runtime-deps", YELLOW, "no-runtime", facts);
+  if (facts.orphaned.length) return result("runtime-deps", RED, "unregistered", facts);
+  if (facts.broken.length) return result("runtime-deps", RED, "broken-artifact", facts);
+  if (facts.missing.length) return result("runtime-deps", YELLOW, "missing", facts);
+  return result("runtime-deps", OK, "ok", facts);
+}
+
+/**
+ * `driver: null` is NOT a failure: /api/health deliberately never initialises the
+ * DB, so a freshly started server reports null until the first real query. Only
+ * "no driver AND no runtime copy AND the driver layer said why" is fatal.
+ */
+function checkDriver({ health, runtimeCopy }) {
+  const facts = { driver: health?.driver ?? null, error: health?.lastDriverError ?? null, runtimeCopy };
+  if (!health) return result("driver", YELLOW, "no-health", facts);
+  if (!health.driver && !runtimeCopy && health.lastDriverError) return result("driver", RED, "no-driver", facts);
+  if (!health.driver) return result("driver", YELLOW, "not-initialized", facts);
+  if (health.lastDriverError) return result("driver", YELLOW, "fallback", facts);
+  return result("driver", OK, "ok", facts);
+}
+
+/** Launcher vs the on-disk marker vs what is actually answering on the port. */
+function checkVersion({ port, launcherVersion, diskVersion, server }) {
+  const facts = { port, launcher: launcherVersion, disk: diskVersion || null, server: server?.version || null };
+  // Deliberately NOT gated on a running server: launcher ≠ on-disk marker means
+  // two different builds are sharing one data dir, which is true regardless of
+  // whether either of them is up right now.
+  const known = [launcherVersion, diskVersion, server?.version].filter(Boolean);
+  if (new Set(known).size > 1) return result("version", RED, "mismatch", facts);
+  // Something holds the port but does not speak our /api/version.
+  if (server?.reachable && !server.version) return result("version", YELLOW, "no-server-version", facts);
+  return result("version", OK, "ok", facts);
+}
+
+function checkPort({ port, dataDir, listening, owners, pidFilePid, server }) {
+  const facts = { port, owners: owners || [], pidFilePid: pidFilePid || null };
+  if (!listening) {
+    // A pidfile with nothing listening is a leftover from a crashed server; the
+    // next start's heal would rewrite it, so it is informative, not broken.
+    if (pidFilePid) return result("port", YELLOW, "orphan-pidfile", { ...facts, file: pidFilePath(dataDir) });
+    return result("port", OK, "free", facts);
+  }
+  if (server?.version) return result("port", OK, "ok", facts);
+  // Answers TCP but not our /api/version: our own server mid-boot (the pidfile
+  // still matches) or somebody else's service (it does not).
+  if (pidFilePid && owners.includes(pidFilePid)) return result("port", OK, "booting", facts);
+  return result("port", RED, "foreign", facts);
+}
+
+/** The §3b scenario: the port is served by a build that is not the one on disk. */
+function checkStaleProcess({ port, dataDir, server, diskVersion, launcherVersion, pidFilePid, owners }) {
+  const disk = diskVersion || launcherVersion;
+  const facts = {
+    port,
+    server: server?.version || null,
+    disk: disk || null,
+    pidFilePid: pidFilePid || null,
+    owners: owners || [],
+  };
+  const running = server?.version || null;
+  if (!running) {
+    // Nothing verifiable is on the port. A pidfile we cannot match is worth a
+    // look, but a stale build can only be PROVEN by a version, so never red.
+    if (pidFilePid) return result("stale-process", YELLOW, "unverified", facts);
+    return result("stale-process", OK, "idle", facts);
+  }
+  // Comparing against the launcher when the marker is absent keeps the red
+  // signal: "what is serving is not what this launcher ships" is the same fault.
+  if (running !== disk) return result("stale-process", RED, "stale", facts);
+  // It matches, but with no marker on disk a still-running OLD build could never
+  // have noticed an upgrade — the §3b mechanism is silently absent.
+  if (!diskVersion) return result("stale-process", YELLOW, "no-marker", { ...facts, file: diskVersionPath(dataDir) });
+  if (pidFilePid && owners.length && !owners.includes(pidFilePid)) {
+    return result("stale-process", YELLOW, "pid-mismatch", facts);
+  }
+  return result("stale-process", OK, "ok", facts);
+}
+
+/** Informational only — a missing tray never breaks serving, so never red. */
+function checkTray({ platform, systrayInstalled }) {
+  const facts = { platform, systray: Boolean(systrayInstalled) };
+  if (platform === "win32") return result("tray", OK, "bundled", facts);
+  if (!systrayInstalled) return result("tray", YELLOW, "missing", facts);
+  return result("tray", OK, "ok", facts);
+}
+
+// ---------------------------------------------------------------------------
+// Collection — the only machine-touching part
+// ---------------------------------------------------------------------------
+
+const ORDER = ["version", "stale-process", "build", "driver", "runtime-deps", "port", "tray", "data-dir"];
+
+/**
+ * Gather every fact once, then run the pure checks. Injectable so tests never
+ * touch a real port or a real ~/.10router.
+ */
+async function collectChecks({
+  port = DEFAULT_PORT,
+  dataDir = getDataDir(),
+  launcherVersion = require("../../package.json").version,
+  appDir = APP_DIR,
+  runtimeDir = getRuntimeDir(),
+  platform = process.platform,
+  legacyDir = legacyDirPath({ platform }),
+  fetchImpl,
+  execSyncImpl,
+  probeTimeoutMs,
+} = {}) {
+  const probeOptions = { fetchImpl, timeoutMs: probeTimeoutMs };
+
+  const [server, health, listening] = await Promise.all([
+    probeServerVersion(port, probeOptions),
+    probeHealth(port, { fetchImpl, timeoutMs: probeTimeoutMs }),
+    probeTcp(port),
+  ]);
+  const owners = listening ? findPortOwners(port, { platform, execSync: execSyncImpl }) : [];
+
+  const missing = BUILD_MARKERS.filter((rel) => !fs.existsSync(path.join(appDir, rel)));
+  const appVersion = readJsonFile(path.join(appDir, "package.json"))?.version || null;
+
+  const runtime = readRuntimeState(runtimeDir);
+  const expected = [...RUNTIME_MODULES, ...(platform === "win32" ? [] : RUNTIME_MODULES_POSIX)];
+
+  const shared = {
+    dataDir,
+    server,
+    listening,
+    owners,
+    port,
+    pidFilePid: readPidFile(dataDir),
+    diskVersion: readDiskVersion(dataDir),
+    launcherVersion,
+  };
+
+  const checks = [
+    checkVersion({ port, launcherVersion, diskVersion: shared.diskVersion, server }),
+    checkStaleProcess({ ...shared }),
+    checkBuild({ appDir, missing, appVersion, launcherVersion }),
+    checkDriver({
+      health,
+      // "copy present" has to mean *usable*: §4 was a runtime copy that existed
+      // but could not be loaded, which is indistinguishable from absent here.
+      runtimeCopy:
+        runtime.installed.includes("better-sqlite3") && !runtime.broken.includes("better-sqlite3"),
+    }),
+    checkRuntimeDeps({
+      runtimeDir,
+      declared: runtime.declared,
+      installed: runtime.installed,
+      broken: runtime.broken,
+      expected,
+    }),
+    checkPort({ port, dataDir, listening, owners, pidFilePid: shared.pidFilePid, server }),
+    checkTray({ platform, systrayInstalled: runtime.installed.includes("systray2") }),
+    checkDataDir({
+      dataDir,
+      exists: fs.existsSync(dataDir),
+      writable: isWritable(dataDir),
+      legacyDir,
+      legacyPending: fs.existsSync(legacyDir) && !hasAppData(dataDir),
+    }),
+  ];
+
+  return ORDER.map((id) => checks.find((c) => c.id === id));
+}
+
+function summarize(checks, { port = DEFAULT_PORT, dataDir = getDataDir(), launcherVersion } = {}) {
+  const counts = { [OK]: 0, [YELLOW]: 0, [RED]: 0 };
+  for (const c of checks) counts[c.status] = (counts[c.status] || 0) + 1;
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    ok: counts[RED] === 0,
+    version: launcherVersion || require("../../package.json").version,
+    port,
+    dataDir,
+    counts,
+    checks: checks.map(({ id, status, reason, facts }) => ({ id, status, reason, facts })),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+
+/**
+ * One line per check. `doctor.<id>.ok` for a pass, `doctor.<id>.<reason>` for a
+ * finding, so the text can name the actual cause instead of a generic warning.
+ */
+function renderHuman(report) {
+  const lines = [t("doctor.title", { version: report.version, port: report.port }), ""];
+  for (const c of report.checks) {
+    const key = c.status === OK ? `doctor.${c.id}.ok` : `doctor.${c.id}.${c.reason}`;
+    const params = {};
+    for (const [name, value] of Object.entries(c.facts)) {
+      if (Array.isArray(value)) params[name] = value.join(", ") || "—";
+      // An absent fact (no marker, no pidfile, no driver) must not print as
+      // "null" — every message would then read like a crash.
+      else params[name] = value === null || value === undefined || value === "" ? "—" : value;
+    }
+    lines.push(`${STATUS_ICON[c.status]} ${c.id}: ${t(key, params)}`);
+  }
+  lines.push("");
+  lines.push(
+    report.ok
+      ? t("doctor.summaryOk", { ok: report.counts[OK], yellow: report.counts[YELLOW] })
+      : t("doctor.summaryRed", { red: report.counts[RED], yellow: report.counts[YELLOW] }),
+  );
+  lines.push(t("doctor.readOnlyHint"));
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const opts = { json: false, help: false, port: DEFAULT_PORT };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--json") opts.json = true;
+    else if (arg === "--help" || arg === "-h") opts.help = true;
+    else if (arg === "--port" || arg === "-p") {
+      const next = parseInt(argv[i + 1], 10);
+      if (Number.isInteger(next) && next > 0 && next < 65536) opts.port = next;
+      i++;
+    }
+  }
+  return opts;
+}
+
+async function run(argv = [], deps = {}) {
+  const opts = parseArgs(argv);
+  if (opts.help) {
+    console.log(t("doctor.help"));
+    return 0;
+  }
+  const checks = await collectChecks({ ...deps, port: opts.port });
+  const report = summarize(checks, { ...deps, port: opts.port });
+  if (opts.json) console.log(JSON.stringify(report, null, 2));
+  else console.log(renderHuman(report));
+  return report.ok ? 0 : 1;
+}
+
+module.exports = {
+  APP_DIR,
+  BUILD_MARKERS,
+  DEFAULT_PORT,
+  OK,
+  ORDER,
+  RED,
+  RUNTIME_MODULES,
+  RUNTIME_MODULES_POSIX,
+  SCHEMA_VERSION,
+  YELLOW,
+  checkBuild,
+  checkDataDir,
+  checkDriver,
+  checkPort,
+  checkRuntimeDeps,
+  checkStaleProcess,
+  checkTray,
+  checkVersion,
+  collectChecks,
+  findPortOwners,
+  hasAppData,
+  legacyDirPath,
+  parseArgs,
+  probeHealth,
+  probeTcp,
+  readRuntimeState,
+  renderHuman,
+  run,
+  summarize,
+};