refactor: split port diagnostics helpers

src/commands/doctor-format.ts

@@ -0,0 +1,67 @@
+import { GATEWAY_LAUNCH_AGENT_LABEL } from "../daemon/constants.js";
+import { resolveGatewayLogPaths } from "../daemon/launchd.js";
+import type { GatewayServiceRuntime } from "../daemon/service-runtime.js";
+
+type RuntimeHintOptions = {
+  platform?: NodeJS.Platform;
+  env?: Record<string, string | undefined>;
+};
+
+export function formatGatewayRuntimeSummary(
+  runtime: GatewayServiceRuntime | undefined,
+): string | null {
+  if (!runtime) return null;
+  const status = runtime.status ?? "unknown";
+  const details: string[] = [];
+  if (runtime.pid) details.push(`pid ${runtime.pid}`);
+  if (runtime.state && runtime.state.toLowerCase() !== status) {
+    details.push(`state ${runtime.state}`);
+  }
+  if (runtime.subState) details.push(`sub ${runtime.subState}`);
+  if (runtime.lastExitStatus !== undefined) {
+    details.push(`last exit ${runtime.lastExitStatus}`);
+  }
+  if (runtime.lastExitReason) {
+    details.push(`reason ${runtime.lastExitReason}`);
+  }
+  if (runtime.lastRunResult) {
+    details.push(`last run ${runtime.lastRunResult}`);
+  }
+  if (runtime.lastRunTime) {
+    details.push(`last run time ${runtime.lastRunTime}`);
+  }
+  if (runtime.detail) details.push(runtime.detail);
+  return details.length > 0 ? `${status} (${details.join(", ")})` : status;
+}
+
+export function buildGatewayRuntimeHints(
+  runtime: GatewayServiceRuntime | undefined,
+  options: RuntimeHintOptions = {},
+): string[] {
+  const hints: string[] = [];
+  if (!runtime) return hints;
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  if (runtime.cachedLabel && platform === "darwin") {
+    hints.push(
+      `LaunchAgent label cached but plist missing. Clear with: launchctl bootout gui/$UID/${GATEWAY_LAUNCH_AGENT_LABEL}`,
+    );
+  }
+  if (runtime.status === "stopped") {
+    hints.push(
+      "Service is loaded but not running (likely exited immediately).",
+    );
+    if (platform === "darwin") {
+      const logs = resolveGatewayLogPaths(env);
+      hints.push(`Logs: ${logs.stdoutPath}`);
+      hints.push(`Errors: ${logs.stderrPath}`);
+    } else if (platform === "linux") {
+      hints.push(
+        "Logs: journalctl --user -u clawdbot-gateway.service -n 200 --no-pager",
+      );
+    } else if (platform === "win32") {
+      hints.push('Logs: schtasks /Query /TN "Clawdbot Gateway" /V /FO LIST');
+    }
+  }
+  return hints;
+}