feat(dev): tee stdout/stderr to logs/dev-YYYY-MM-DD.log (#444)

Dev logs used to live only in the tsx-watch terminal scrollback — closing
the window or scrolling past the buffer lost them, so debugging an
intermittent upstream 422 had no evidence trail. installFileLogger opens
a per-day append fd and patches process.stdout/stderr.write to also fan
out to the file. Skipped in production (log shippers handle it), under
Vitest, and via CODEX_PROXY_FILE_LOG=0.

Co-authored-by: icebear0828 <icebear0828@users.noreply.github.com>

Author: icebear0828

CHANGELOG.md

@@ -14,6 +14,7 @@
 
 ### Added
 
+- Dev 默认把 stdout/stderr tee 到 `logs/dev-YYYY-MM-DD.log`（`src/utils/log-file.ts` + `src/utils/install-dev-logger.ts`，`src/index.ts` 顶部 side-effect 引入）：之前 dev 日志只活在 `tsx watch` terminal 的 scrollback 里，关窗或滚出去就找不到，排查上游偶发 422 之类的错误拿不到证据。新模块按天打开 append fd，patch `process.stdout.write` / `process.stderr.write` 同步写入文件 + 调原函数；prod (`NODE_ENV=production`) / 测试 (`VITEST` / `NODE_ENV=test`) / `CODEX_PROXY_FILE_LOG=0` 三档 opt-out，`logs/` 已被 `*.log` gitignore 覆盖。`tests/unit/utils/log-file.test.ts` 7 个用例覆盖 stdout/stderr tee、目录递归创建、uninstall 还原、append 不截断、默认文件名格式
 - Dashboard 用量页新增「时段命中率（Range Hit Rate）」卡片：基于当前选中时间窗口聚合 `cached_tokens / input_tokens`，与原本的全局累计「Cache Hit Rate」卡并列，方便对比近窗口与历史命中率（`web/src/pages/UsageStats.tsx`、`shared/i18n/translations.ts`）
 - Dashboard 用量页新增独立的「Hit Rate Over Time」图：每个 bucket 渲染命中率折线 + 数据点 dot，hover 可见 `cached / input`；`input=0` 的 bucket 自动跳过（不渲染 0% 假命中），单数据点也用 dot 保证可见性（`web/src/components/UsageChart.tsx`）
 - Usage history `five_min` granularity（5 分钟桶）+ Dashboard 新增「5 min」粒度选项与「Last 1h / 6h」时间窗：snapshot 默认 5 分钟一记，新粒度等同于一桶一快照，方便排查刚发生的请求；旧的 hourly/daily 不变，按 granularity 自动收敛兼容窗口（`src/auth/usage-stats.ts`、`src/routes/admin/usage-stats.ts`、`shared/hooks/use-usage-stats.ts`、`web/src/pages/UsageStats.tsx`）

src/index.ts

@@ -1,3 +1,5 @@
+import "./utils/install-dev-logger.js";
+
 import { Hono } from "hono";
 import { serve } from "@hono/node-server";
 import { loadConfig, loadFingerprint, getConfig, hasLocalOverride } from "./config.js";

src/utils/install-dev-logger.ts

@@ -0,0 +1,23 @@
+/**
+ * Side-effect import: in dev, tee process.stdout/stderr to logs/dev-YYYY-MM-DD.log
+ * so terminal scrollback isn't the only place we can debug from.
+ *
+ * Skipped in production (log shippers handle persistence) and under Vitest.
+ */
+
+import { join } from "node:path";
+
+import { installFileLogger } from "./log-file.js";
+
+const isProduction = process.env.NODE_ENV === "production";
+const isTest = Boolean(process.env.VITEST) || process.env.NODE_ENV === "test";
+const disabled = process.env.CODEX_PROXY_FILE_LOG === "0";
+
+if (!isProduction && !isTest && !disabled) {
+  try {
+    installFileLogger({ dir: join(process.cwd(), "logs") });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[dev-file-logger] failed to install: ${msg}\n`);
+  }
+}

src/utils/log-file.ts

@@ -0,0 +1,83 @@
+/**
+ * Tees process.stdout / process.stderr writes into a daily log file.
+ *
+ * Used in dev so terminal scrollback isn't the only place errors live.
+ * Production stays pure stdout/stderr — log shippers handle persistence there.
+ */
+
+import { closeSync, mkdirSync, openSync, writeSync } from "node:fs";
+import { join } from "node:path";
+
+export interface InstallFileLoggerOptions {
+  dir: string;
+  filename?: string;
+}
+
+export interface FileLoggerHandle {
+  path: string;
+  uninstall(): void;
+}
+
+type WriteFn = typeof process.stdout.write;
+
+export function installFileLogger(opts: InstallFileLoggerOptions): FileLoggerHandle {
+  mkdirSync(opts.dir, { recursive: true });
+  const filename = opts.filename ?? defaultFilename(new Date());
+  const path = join(opts.dir, filename);
+  const fd = openSync(path, "a");
+
+  const originalStdout = process.stdout.write;
+  const originalStderr = process.stderr.write;
+
+  process.stdout.write = wrap(originalStdout, process.stdout, fd);
+  process.stderr.write = wrap(originalStderr, process.stderr, fd);
+
+  let uninstalled = false;
+
+  return {
+    path,
+    uninstall(): void {
+      if (uninstalled) return;
+      uninstalled = true;
+      process.stdout.write = originalStdout;
+      process.stderr.write = originalStderr;
+      try {
+        closeSync(fd);
+      } catch {
+        // best-effort: closing twice or after process tear-down is harmless
+      }
+    },
+  };
+}
+
+function wrap(original: WriteFn, stream: NodeJS.WriteStream, fd: number): WriteFn {
+  const wrapped = function (this: unknown, ...args: unknown[]): boolean {
+    try {
+      const chunk = args[0];
+      const encoding =
+        typeof args[1] === "string" ? (args[1] as BufferEncoding) : undefined;
+      writeSync(fd, toBuffer(chunk, encoding));
+    } catch {
+      // never let the file sink break the caller — stdout/stderr must stay live
+    }
+    return (original as (...a: unknown[]) => boolean).apply(stream, args);
+  };
+  return wrapped as WriteFn;
+}
+
+function toBuffer(chunk: unknown, encoding: BufferEncoding | undefined): Buffer {
+  if (typeof chunk === "string") {
+    return Buffer.from(chunk, encoding ?? "utf8");
+  }
+  if (chunk instanceof Uint8Array) {
+    return Buffer.from(chunk);
+  }
+  return Buffer.from(String(chunk));
+}
+
+function defaultFilename(date: Date): string {
+  const yyyy = date.getFullYear();
+  const mm = String(date.getMonth() + 1).padStart(2, "0");
+  const dd = String(date.getDate()).padStart(2, "0");
+  return `dev-${yyyy}-${mm}-${dd}.log`;
+}

tests/unit/utils/log-file.test.ts

@@ -0,0 +1,122 @@
+/**
+ * Tests for installFileLogger — tees process.stdout/stderr writes into a
+ * daily log file under a configurable directory.
+ */
+
+import { describe, it, expect, afterEach } from "vitest";
+import { mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { installFileLogger } from "@src/utils/log-file.js";
+
+describe("installFileLogger", () => {
+  const cleanups: Array<() => void> = [];
+
+  afterEach(() => {
+    while (cleanups.length > 0) {
+      const fn = cleanups.pop();
+      try {
+        fn?.();
+      } catch {
+        // swallow — cleanup is best-effort
+      }
+    }
+  });
+
+  it("tees process.stdout writes into the target file", () => {
+    const dir = mkdtempSync(join(tmpdir(), "codex-proxy-log-"));
+    cleanups.push(() => rmSync(dir, { recursive: true, force: true }));
+
+    const handle = installFileLogger({ dir, filename: "test.log" });
+    cleanups.push(() => handle.uninstall());
+
+    process.stdout.write("hello stdout\n");
+
+    expect(handle.path).toBe(join(dir, "test.log"));
+    expect(readFileSync(handle.path, "utf8")).toContain("hello stdout");
+  });
+
+  it("tees process.stderr writes into the target file", () => {
+    const dir = mkdtempSync(join(tmpdir(), "codex-proxy-log-"));
+    cleanups.push(() => rmSync(dir, { recursive: true, force: true }));
+
+    const handle = installFileLogger({ dir, filename: "test.log" });
+    cleanups.push(() => handle.uninstall());
+
+    process.stderr.write("boom stderr\n");
+
+    expect(readFileSync(handle.path, "utf8")).toContain("boom stderr");
+  });
+
+  it("creates nested target directory if it does not exist", () => {
+    const base = mkdtempSync(join(tmpdir(), "codex-proxy-log-"));
+    cleanups.push(() => rmSync(base, { recursive: true, force: true }));
+    const dir = join(base, "nested", "logs");
+
+    const handle = installFileLogger({ dir, filename: "test.log" });
+    cleanups.push(() => handle.uninstall());
+
+    process.stdout.write("nested\n");
+
+    expect(statSync(handle.path).isFile()).toBe(true);
+    expect(readFileSync(handle.path, "utf8")).toContain("nested");
+  });
+
+  it("uninstall restores original write functions and stops teeing", () => {
+    const dir = mkdtempSync(join(tmpdir(), "codex-proxy-log-"));
+    cleanups.push(() => rmSync(dir, { recursive: true, force: true }));
+
+    const originalStdoutWrite = process.stdout.write;
+    const handle = installFileLogger({ dir, filename: "test.log" });
+    expect(process.stdout.write).not.toBe(originalStdoutWrite);
+
+    process.stdout.write("before\n");
+    handle.uninstall();
+    expect(process.stdout.write).toBe(originalStdoutWrite);
+
+    process.stdout.write("after\n");
+
+    const contents = readFileSync(handle.path, "utf8");
+    expect(contents).toContain("before");
+    expect(contents).not.toContain("after");
+  });
+
+  it("defaults filename to dev-YYYY-MM-DD.log", () => {
+    const dir = mkdtempSync(join(tmpdir(), "codex-proxy-log-"));
+    cleanups.push(() => rmSync(dir, { recursive: true, force: true }));
+
+    const handle = installFileLogger({ dir });
+    cleanups.push(() => handle.uninstall());
+
+    expect(handle.path).toMatch(/dev-\d{4}-\d{2}-\d{2}\.log$/);
+  });
+
+  it("preserves the boolean return value from the underlying write", () => {
+    const dir = mkdtempSync(join(tmpdir(), "codex-proxy-log-"));
+    cleanups.push(() => rmSync(dir, { recursive: true, force: true }));
+
+    const handle = installFileLogger({ dir, filename: "test.log" });
+    cleanups.push(() => handle.uninstall());
+
+    const result = process.stdout.write("payload\n");
+    expect(typeof result).toBe("boolean");
+  });
+
+  it("appends to an existing file instead of truncating", () => {
+    const dir = mkdtempSync(join(tmpdir(), "codex-proxy-log-"));
+    cleanups.push(() => rmSync(dir, { recursive: true, force: true }));
+
+    const first = installFileLogger({ dir, filename: "test.log" });
+    process.stdout.write("first run\n");
+    first.uninstall();
+
+    const second = installFileLogger({ dir, filename: "test.log" });
+    cleanups.push(() => second.uninstall());
+    process.stdout.write("second run\n");
+
+    const contents = readFileSync(second.path, "utf8");
+    expect(contents).toContain("first run");
+    expect(contents).toContain("second run");
+  });
+});