Merge branch 'task/ocx-status-diagnostics' into dev

Author: lidge-jun

docs-site/src/content/docs/ko/reference/cli.md

@@ -37,7 +37,8 @@ ocx start --port 8080
 
 ### `ocx status`
 
-프록시가 실행 중인지(그리고 해당 PID) 여부를 출력합니다.
+읽기 전용 진단 요약을 출력합니다: 프록시 PID, `/healthz` 연결 상태, 대시보드 URL,
+설정 파일 경로, 기본 프로바이더, Codex 자동 시작 설정, 서비스 상태, shim 상태.
 
 ## 모델 및 Codex
 

docs-site/src/content/docs/reference/cli.md

@@ -37,7 +37,8 @@ catalog entries so plain `codex` works natively again. `eject` is an alias of `r
 
 ### `ocx status`
 
-Print whether the proxy is running (and its PID) or not.
+Print a read-only diagnostic summary: proxy PID, `/healthz` reachability, dashboard URL,
+config path, default provider, Codex autostart setting, service state, and shim state.
 
 ## Models & Codex
 

docs-site/src/content/docs/zh-cn/reference/cli.md

@@ -32,7 +32,8 @@ ocx start --port 8080
 
 ### `ocx status`
 
-打印代理是否正在运行(及其 PID)。
+打印只读诊断摘要: 代理 PID、`/healthz` 可达性、仪表盘 URL、配置文件路径、默认
+provider、Codex 自动启动设置、服务状态和 shim 状态。
 
 ## 模型与 Codex
 

src/cli.ts

@@ -3,9 +3,9 @@ import { execFileSync, spawn } from "node:child_process";
 import { rmSync } from "node:fs";
 import { restoreNativeCodex } from "./codex-inject";
 import { restoreLegacyOpenaiHistory } from "./codex-history-provider";
-import { codexAutoStartEnabled, getConfigDir, loadConfig, readPid, removePid, saveConfig, writePid } from "./config";
+import { codexAutoStartEnabled, getConfigDir, getConfigPath, loadConfig, readPid, removePid, saveConfig, writePid } from "./config";
 import { findAvailablePort } from "./ports";
-import { serviceCommand, stopServiceIfInstalled, uninstallServiceIfInstalled } from "./service";
+import { serviceCommand, serviceStatusSummary, stopServiceIfInstalled, uninstallServiceIfInstalled } from "./service";
 import { drainAndShutdown, startServer } from "./server";
 import { maybeShowStarPrompt } from "./star-prompt";
 
@@ -365,13 +365,56 @@ async function handleUninstall() {
   console.log("\n✅ opencodex local state removed. Remove the package with: npm uninstall -g @bitkyc08/opencodex");
 }
 
-function handleStatus() {
+type HealthCheck = {
+  ok: boolean;
+  label: string;
+};
+
+async function checkProxyHealth(port: number, hostname?: string): Promise<HealthCheck> {
+  const url = `http://${healthHost(hostname)}:${port}/healthz`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 800);
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    if (!response.ok) return { ok: false, label: `${url} returned HTTP ${response.status}` };
+    const body = await response.json().catch(() => null) as { version?: unknown; uptime?: unknown } | null;
+    const version = typeof body?.version === "string" ? ` v${body.version}` : "";
+    const uptime = typeof body?.uptime === "number" ? `, uptime ${Math.round(body.uptime)}s` : "";
+    return { ok: true, label: `${url} ok${version}${uptime}` };
+  } catch (error) {
+    const reason = error instanceof Error && error.name === "AbortError" ? "timed out" : "unreachable";
+    return { ok: false, label: `${url} ${reason}` };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function handleStatus() {
+  const config = loadConfig();
+  const port = config.port ?? 10100;
   const pid = readPid();
-  if (pid) {
-    console.log(`✅ Proxy running (PID ${pid})`);
+  const health = await checkProxyHealth(port, config.hostname);
+  const proxyLabel = pid && health.ok
+    ? `running (PID ${pid})`
+    : pid
+      ? `PID file points to PID ${pid}, but health check failed`
+      : health.ok
+        ? "reachable, but PID file is missing or stale"
+        : "not running";
+
+  if (pid || health.ok) {
+    console.log(`✅ Proxy: ${proxyLabel}`);
   } else {
-    console.log("❌ Proxy not running");
+    console.log(`❌ Proxy: ${proxyLabel}`);
   }
+  console.log(`   Health: ${health.label}`);
+  console.log(`   Dashboard: http://localhost:${port}/`);
+  console.log(`   Config: ${getConfigPath()}`);
+  console.log(`   Default provider: ${config.defaultProvider}`);
+  console.log(`   Codex autostart: ${codexAutoStartEnabled(config) ? "enabled" : "disabled"}`);
+  console.log(`   Service: ${serviceStatusSummary()}`);
+  const { codexShimStatus } = await import("./codex-shim");
+  console.log(`   ${codexShimStatus()}`);
 }
 
 function handleRecoverHistory() {
@@ -411,7 +454,7 @@ switch (command) {
     await handleUninstall();
     break;
   case "status":
-    handleStatus();
+    await handleStatus();
     break;
   case "ensure":
     await handleEnsure();

src/service.ts

@@ -283,6 +283,26 @@ export function uninstallServiceIfInstalled(): boolean {
   return false;
 }
 
+export function serviceStatusSummary(): string {
+  if (process.platform === "darwin") {
+    if (!existsSync(plistPath())) return "not installed";
+    const status = statusLaunchd();
+    return status ? "installed (launchd)" : "installed, not loaded";
+  }
+  if (process.platform === "win32") {
+    const status = statusWindows();
+    return status ? "installed (Task Scheduler)" : "not installed";
+  }
+  if (process.platform === "linux") {
+    if (existsSync("/.dockerenv")) return "unsupported in Docker";
+    if (!isSystemd()) return "unsupported: systemd not found";
+    if (!existsSync(unitPath())) return "not installed";
+    const status = statusSystemd();
+    return status ? "installed (systemd user)" : "installed, not running";
+  }
+  return `unsupported on ${process.platform}`;
+}
+
 export function serviceCommand(sub?: string): void {
   const ops = platformOps();
   if (!ops) {

tests/cli-help.test.ts

@@ -9,6 +9,43 @@ const repoRoot = dirname(fileURLToPath(new URL("../package.json", import.meta.ur
 const cliPath = join(repoRoot, "src", "cli.ts");
 
 describe("CLI subcommand help", () => {
+  test("status prints diagnostics without starting the proxy", () => {
+    const opencodexHome = mkdtempSync(join(tmpdir(), "ocx-status-"));
+    try {
+      const configPath = join(opencodexHome, "config.json");
+      writeFileSync(configPath, JSON.stringify({
+        port: 9,
+        providers: {
+          openai: {
+            adapter: "openai-responses",
+            baseUrl: "https://chatgpt.com/backend-api/codex",
+            authMode: "forward",
+          },
+        },
+        defaultProvider: "openai",
+        codexAutoStart: false,
+      }), "utf8");
+
+      const result = spawnSync(process.execPath, [cliPath, "status"], {
+        cwd: repoRoot,
+        env: { ...process.env, OPENCODEX_HOME: opencodexHome },
+        encoding: "utf8",
+      });
+
+      expect(result.status).toBe(0);
+      expect(result.stdout).toContain("Proxy:");
+      expect(result.stdout).toContain("Health: http://127.0.0.1:9/healthz");
+      expect(result.stdout).toContain("Dashboard: http://localhost:9/");
+      expect(result.stdout).toContain(`Config: ${configPath}`);
+      expect(result.stdout).toContain("Default provider: openai");
+      expect(result.stdout).toContain("Codex autostart: disabled");
+      expect(result.stdout).toContain("Service:");
+      expect(result.stdout).toContain("Codex autostart shim");
+    } finally {
+      rmSync(opencodexHome, { recursive: true, force: true });
+    }
+  });
+
   test("restore --help prints usage without mutating Codex config", () => {
     const codexHome = mkdtempSync(join(tmpdir(), "ocx-help-"));
     try {