@sleep2agi/commhub-server 0.9.0-preview.4 → 0.9.0-preview.41

package/src/db-adapter.ts

@@ -212,10 +212,28 @@ export class PgAdapter implements DbAdapter {
 //  Factory
 // ════════════════════════════════════════════
 
+export type DbTarget =
+  | { kind: "postgres"; url: string }
+  | { kind: "sqlite"; path: string };
+
 /**
- * Create the appropriate adapter based on environment.
- * - DATABASE_URL starts with "postgres://" → PgAdapter
- * - Otherwise → SQLiteAdapter with COMMHUB_DB or default path
+ * Refuse every inherited DATABASE_URL under the Bun test environment before
+ * adapter selection, logging, DNS, or construction. A test that intentionally
+ * exercises PostgreSQL needs a separately reviewed isolated harness; accepting
+ * a shell/CI DATABASE_URL here could connect a unit test to production.
+ */
+export function assertSafeTestDatabaseEnv(env: NodeJS.ProcessEnv = process.env): void {
+  if (env.NODE_ENV === "test" && env.DATABASE_URL) {
+    throw new Error(
+      "[commhub] REFUSING to honor inherited DATABASE_URL under NODE_ENV=test.\n" +
+      "  Tests must unset DATABASE_URL and set COMMHUB_DB to an isolated path.\n" +
+      "  This guard is fail-closed and has no opt-in bypass."
+    );
+  }
+}
+
+/**
+ * Pure target selection after the inherited-DATABASE_URL safety gate.
  *
  * Test-default-prod GUARD: when `NODE_ENV === "test"` (set automatically by
  * `bun test`) AND `COMMHUB_DB` is unset, we REFUSE to fall through to the
@@ -227,27 +245,20 @@ export class PgAdapter implements DbAdapter {
  * pre-existing history of test pollution in the same DB). The guard makes
  * the failure mode loud + actionable instead of silent + destructive.
  *
- * The guard does NOT fire when:
- *   - COMMHUB_DB is set (the test runner's documented contract); or
- *   - NODE_ENV is unset (production server) or any non-"test" value.
- *
- * Operators who run `bun -e` snippets that touch the DB are expected to
- * `COMMHUB_DB=/tmp/...` themselves — `bun -e` doesn't set NODE_ENV, so the
- * guard can't catch that case. The rule (never read or write the
- * production hub database) is documented in CLAUDE.md.
+ * The production default path is a capability, not a generic fallback:
+ * only canonical server entrypoints set COMMHUB_SERVER=1 before importing
+ * the database graph. Tests, scripts, and `bun -e` probes must name an
+ * explicit COMMHUB_DB (or a reviewed PostgreSQL DATABASE_URL), so forgetting
+ * one fails before mkdir/open/write instead of touching the live Hub.
  */
-export function createAdapter(): DbAdapter {
-  const dbUrl = process.env.DATABASE_URL;
+function resolveDatabaseTargetAfterGuard(env: NodeJS.ProcessEnv): DbTarget {
+  const dbUrl = env.DATABASE_URL;
   if (dbUrl && (dbUrl.startsWith("postgres://") || dbUrl.startsWith("postgresql://"))) {
-    console.log("[commhub] database: PostgreSQL");
-    return new PgAdapter(dbUrl);
+    return { kind: "postgres", url: dbUrl };
   }
-  // Default: SQLite
-  const { mkdirSync } = require("fs");
-  const { dirname } = require("path");
 
   // Test-default-prod GUARD (see docblock above).
-  if (process.env.NODE_ENV === "test" && !process.env.COMMHUB_DB) {
+  if (env.NODE_ENV === "test" && !env.COMMHUB_DB) {
     throw new Error(
       "[commhub] REFUSING to open the default SQLite database under NODE_ENV=test.\n" +
       "  Tests must explicitly set COMMHUB_DB to a throwaway path so they don't\n" +
@@ -257,10 +268,40 @@ export function createAdapter(): DbAdapter {
     );
   }
 
-  const dbPath = process.env.COMMHUB_DB || `${process.env.HOME}/.commhub/commhub.db`;
-  mkdirSync(dirname(dbPath), { recursive: true });
-  console.log(`[commhub] database: ${dbPath}`);
-  const rawDb = new Database(dbPath);
+  if (!env.COMMHUB_DB && env.COMMHUB_SERVER !== "1") {
+    throw new Error(
+      "[commhub] REFUSING to open the default production SQLite database from a non-server entrypoint.\n" +
+      "  Scripts and probes must set an explicit COMMHUB_DB path. The canonical\n" +
+      "  Hub entrypoints set COMMHUB_SERVER=1 before loading the database."
+    );
+  }
+
+  return { kind: "sqlite", path: env.COMMHUB_DB || `${env.HOME}/.commhub/commhub.db` };
+}
+
+/** Pure public resolver used by tests without constructing an adapter. */
+export function resolveDatabaseTarget(env: NodeJS.ProcessEnv = process.env): DbTarget {
+  assertSafeTestDatabaseEnv(env);
+  return resolveDatabaseTargetAfterGuard(env);
+}
+
+/**
+ * Create the appropriate adapter based on environment.
+ * The inherited-DATABASE_URL guard is deliberately the first executable line.
+ */
+export function createAdapter(): DbAdapter {
+  assertSafeTestDatabaseEnv(process.env);
+  const target = resolveDatabaseTargetAfterGuard(process.env);
+  if (target.kind === "postgres") {
+    console.log("[commhub] database: PostgreSQL");
+    return new PgAdapter(target.url);
+  }
+
+  const { mkdirSync } = require("fs");
+  const { dirname } = require("path");
+  mkdirSync(dirname(target.path), { recursive: true });
+  console.log(`[commhub] database: ${target.path}`);
+  const rawDb = new Database(target.path);
   rawDb.exec("PRAGMA journal_mode=WAL");
   rawDb.exec("PRAGMA busy_timeout=5000");
   return new SQLiteAdapter(rawDb);

package/src/db-timestamp.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "bun:test";
+import { parseDbTimestampMs } from "./db-timestamp.js";
+
+const NAIVE = "2026-08-27 11:23:54";
+const EXPECTED = Date.UTC(2026, 7, 27, 11, 23, 54);
+
+describe("parseDbTimestampMs", () => {
+  // ⚠ 这条在 **TZ=UTC 的环境**下没有分辨力：裸 Date.parse 在 UTC 下恰好正确。
+  // CI runner 与容器默认就是 UTC（本仓 Docker 套件亦然），所以缺陷在常规跑法里
+  // 恒绿。（更正：Bun 是尊重 TZ 的，不存在"bun test 固定 UTC"——通信评审牛 #1279
+  // 独审③ 独立复跑证伪了我最初的说法。）真正稳定见红的门是下面那条强制子进程。
+  it("treats a naive SQLite timestamp as UTC", () => {
+    expect(parseDbTimestampMs(NAIVE)).toBe(EXPECTED);
+  });
+
+  // 分辨力关键：宿主是 UTC 时,裸 Date.parse 与正确写法结果相同,断言恒绿。
+  // 强制子进程 TZ=Asia/Shanghai,让缺陷在任何 CI 时区下都显形。
+  it("is unaffected by a non-UTC host timezone (child process TZ=Asia/Shanghai)", () => {
+    const r = Bun.spawnSync({
+      cmd: ["bun", "-e",
+        `const {parseDbTimestampMs} = await import("${import.meta.dir}/db-timestamp.ts");` +
+        `console.log(parseDbTimestampMs("${NAIVE}"));`],
+      env: { ...process.env, TZ: "Asia/Shanghai" },
+    });
+    expect(Number(r.stdout.toString().trim())).toBe(EXPECTED);
+  });
+
+  it("keeps explicit-offset timestamps intact", () => {
+    expect(parseDbTimestampMs("2026-08-27T11:23:54Z")).toBe(EXPECTED);
+    expect(parseDbTimestampMs("2026-08-27T19:23:54+08:00")).toBe(EXPECTED);
+  });
+
+  it("an online window of 5min holds for a heartbeat written 1s ago", () => {
+    const now = Date.now();
+    const iso = new Date(now - 1000).toISOString().slice(0, 19).replace("T", " ");
+    expect(now - parseDbTimestampMs(iso)).toBeLessThanOrEqual(5 * 60_000);
+  });
+});

package/src/db-timestamp.ts

@@ -0,0 +1,15 @@
+/**
+ * SQLite 里的时间戳列（sessions.last_seen_at、tasks.created_at 等）存的是
+ * **无时区标记的 UTC 串**（`YYYY-MM-DD HH:MM:SS`，由 SQLite `datetime('now')` 写入）。
+ *
+ * 裸 `Date.parse("2026-08-27 11:23:54")` 会按**宿主机本地时区**解释这个串。
+ * 生产机 TZ=CST+0800 时，它比真实 UTC 时刻早 8 小时——所以 `now - parsed`
+ * 恒为 +480 分钟，任何「最近 N 秒内算在线」的判据都会恒判离线。
+ * 在 TZ=UTC 的机器上两种写法结果相同，缺陷不会显形。
+ */
+export function parseDbTimestampMs(value: string): number {
+  const s = String(value).trim();
+  // 已带时区标记（ISO 的 Z / ±HH:MM）就原样交给 Date
+  if (/[Zz]$|[+-]\d{2}:?\d{2}$/.test(s)) return Date.parse(s);
+  return Date.parse(s.replace(" ", "T") + "Z");
+}