bell-reader 0.0.0-stage → 1.0.1

package/server/config.ts

@@ -0,0 +1,140 @@
+import { SUITE_APP_IDS, SUITE_LIMITS, type SuiteAppId, type SuiteLinks } from "../shared/suite.js";
+
+export interface RuntimeConfig {
+  host: string;
+  port: number;
+  dataDir: string;
+  allowedOrigins: string[];
+  suiteLinks: SuiteLinks;
+  suiteFetch: Partial<Record<"explain" | "pr", string>>;
+}
+
+function loopbackHostname(hostname: string): boolean {
+  const bare = hostname.replace(/^\[|\]$/g, "");
+  if (bare === "::1" || bare === "localhost") return true;
+  const parts = bare.split(".");
+  return parts.length === 4 && parts[0] === "127" && parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255);
+}
+
+function loopbackIpLiteral(hostname: string): boolean {
+  return hostname !== "localhost" && loopbackHostname(hostname);
+}
+
+function tailnetOf(hostname: string): string | undefined {
+  const labels = hostname.toLowerCase().split(".");
+  return labels.length >= 4 && labels.at(-1) === "net" && labels.at(-2) === "ts" ? labels.slice(-3).join(".") : undefined;
+}
+
+function exactOrigin(value: string, variable: string): URL {
+  if (!/^https?:\/\/[^/?#\\\s@*]+$/i.test(value) || value.endsWith(":")) {
+    throw new Error(`${variable} 格式錯誤：必須是不含路徑、查詢或萬用字元的完整 origin。`);
+  }
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`${variable} 格式錯誤：無法解析網址。`);
+  }
+  if (url.username || url.password || url.search || url.hash || url.pathname !== "/" || url.port === "0") {
+    throw new Error(`${variable} 格式錯誤：不得含帳密、路徑、查詢參數或 port 0。`);
+  }
+  return url;
+}
+
+export function parseAllowedOrigins(raw: string | undefined, variable = "BELL_READER_ALLOWED_ORIGINS"): string[] {
+  const text = (raw ?? "").trim();
+  if (!text) return [];
+  return text.split(",").map((entry) => {
+    const url = exactOrigin(entry.trim(), variable);
+    if (!loopbackHostname(url.hostname) && url.protocol !== "https:") {
+      throw new Error(`${variable} 格式錯誤：非本機來源必須使用 https。`);
+    }
+    return url.origin;
+  });
+}
+
+export function parseSuiteLinks(
+  raw: string | undefined,
+  ownOrigins: string[],
+  variable = "BELL_READER_SUITE_LINKS",
+): SuiteLinks {
+  const text = (raw ?? "").trim();
+  if (!text) return {};
+  const parts = text.split(",").map((part) => part.trim());
+  if (parts.length > SUITE_LIMITS.links) {
+    throw new Error(`${variable} 最多支援 ${SUITE_LIMITS.links} 個產品連結。`);
+  }
+  const ownTailnets = new Set(
+    ownOrigins
+      .map((origin) => {
+        try {
+          return tailnetOf(new URL(origin).hostname);
+        } catch {
+          return undefined;
+        }
+      })
+      .filter((item): item is string => Boolean(item)),
+  );
+  const seen = new Set<string>();
+  const links: SuiteLinks = {};
+  for (const part of parts) {
+    const match = /^([a-z]+)=(.+)$/.exec(part);
+    if (!match) throw new Error(`${variable} 格式錯誤：每項須為 appId=origin。`);
+    const [, appId, value] = match;
+    if (seen.has(appId)) throw new Error(`${variable} 重複設定了 ${appId}。`);
+    seen.add(appId);
+    if (!SUITE_APP_IDS.includes(appId as SuiteAppId) || appId === "reader") {
+      throw new Error(`${variable} 不支援或指向自身：${appId}。`);
+    }
+    const url = exactOrigin(value, `${variable}.${appId}`);
+    if (!loopbackHostname(url.hostname)) {
+      if (url.protocol !== "https:") throw new Error(`${variable}.${appId} 非本機來源必須使用 https。`);
+      const tailnet = tailnetOf(url.hostname);
+      if (!tailnet || !ownTailnets.has(tailnet)) {
+        throw new Error(`${variable}.${appId} 僅允許與本服務相同的 Tailscale tailnet。`);
+      }
+    }
+    links[appId as SuiteAppId] = url.origin;
+  }
+  return links;
+}
+
+export function parseSuiteFetch(
+  raw: string | undefined,
+  variable = "BELL_READER_SUITE_FETCH",
+): Partial<Record<"explain" | "pr", string>> {
+  const text = (raw ?? "").trim();
+  if (!text) return {};
+  const parts = text.split(",").map((part) => part.trim());
+  const seen = new Set<string>();
+  const targets: Partial<Record<"explain" | "pr", string>> = {};
+  for (const part of parts) {
+    const match = /^([a-z]+)=(.+)$/.exec(part);
+    if (!match) throw new Error(`${variable} 格式錯誤：每項須為 appId=origin。`);
+    const [, appId, value] = match;
+    if (seen.has(appId)) throw new Error(`${variable} 重複設定了 ${appId}。`);
+    seen.add(appId);
+    if (appId !== "explain" && appId !== "pr") {
+      throw new Error(`${variable} 只支援讀取 explain 或 pr。`);
+    }
+    const url = exactOrigin(value, `${variable}.${appId}`);
+    if (url.protocol !== "http:" || !loopbackIpLiteral(url.hostname)) {
+      throw new Error(`${variable}.${appId} 伺服器讀取只允許 http://127.x.x.x:port 或 http://[::1]:port。`);
+    }
+    targets[appId] = url.origin;
+  }
+  return targets;
+}
+
+export function loadConfig(env: NodeJS.ProcessEnv = process.env): RuntimeConfig {
+  const port = Number(env.BELL_READER_PORT || env.PORT || 4630);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error("PORT 必須是 1–65535 的整數。");
+  }
+  const host = (env.BELL_READER_HOST || env.HOST || "127.0.0.1").trim();
+  const dataDir = (env.BELL_READER_DATA_DIR || "./data").trim();
+  const allowedOrigins = parseAllowedOrigins(env.BELL_READER_ALLOWED_ORIGINS);
+  const suiteLinks = parseSuiteLinks(env.BELL_READER_SUITE_LINKS, allowedOrigins);
+  const suiteFetch = parseSuiteFetch(env.BELL_READER_SUITE_FETCH);
+  return { host, port, dataDir, allowedOrigins, suiteLinks, suiteFetch };
+}

package/server/errors.ts

@@ -0,0 +1,22 @@
+export class AppError extends Error {
+  constructor(
+    public readonly status: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = "AppError";
+  }
+}
+
+export function publicError(error: unknown): { status: number; message: string } {
+  if (error instanceof AppError) {
+    return { status: error.status, message: error.message };
+  }
+  if (error instanceof DOMException && error.name === "TimeoutError") {
+    return { status: 504, message: "AI 批註等待時間過長，請重試或在設定切換模型供應商。" };
+  }
+  if (error instanceof DOMException && error.name === "AbortError") {
+    return { status: 499, message: "已取消此次批註。" };
+  }
+  return { status: 500, message: "伺服器處理時發生錯誤，請稍後再試。" };
+}

package/server/explain-bridge.ts

@@ -0,0 +1,320 @@
+import http from "node:http";
+import {
+  SUITE_LIMITS,
+  SUITE_OBJECT_ID,
+  SUITE_UNSAFE_TEXT,
+  allowedSuiteRoute,
+} from "../shared/suite.js";
+import type { ExplainBridgeStatus, ExplainTopicMatch, SavedPage } from "../shared/types.js";
+
+// Dedicated agent so host proxy vars (NODE_USE_ENV_PROXY / http_proxy) never intercept loopback sibling reads.
+const loopbackAgent = new http.Agent({ keepAlive: false });
+
+interface ExplainEntry {
+  id: string;
+  title: string;
+  category?: string;
+  tags: string[];
+  url?: string;
+  href: string;
+}
+
+interface CacheState {
+  entries: ExplainEntry[];
+  lastAttemptAt: number;
+  lastSuccessAt?: number;
+  lastFailed: boolean;
+  inflight?: Promise<void>;
+}
+
+function fetchJsonBounded(url: string): Promise<unknown> {
+  // shortcut: 256 KB cap when reading /api/lessons fallback, tighten once /api/suite/topics is deployed everywhere
+  const maxBytes = url.endsWith("/api/lessons") ? 256 * 1024 : SUITE_LIMITS.fetchMaxBytes;
+  const target = new URL(url);
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let request: http.ClientRequest | undefined;
+    const finish = (err: Error | null, value?: unknown) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (err) {
+        request?.destroy();
+        reject(err);
+      } else {
+        resolve(value);
+      }
+    };
+    const timer = setTimeout(() => finish(new Error("Timeout")), SUITE_LIMITS.fetchTimeoutMs);
+    request = http.request(
+      {
+        agent: loopbackAgent,
+        protocol: "http:",
+        hostname: target.hostname.replace(/^\[(.*)\]$/, "$1"),
+        port: Number(target.port || 80),
+        method: "GET",
+        path: `${target.pathname}${target.search}`,
+        headers: { Accept: "application/json" },
+      },
+      (res) => {
+        if (res.statusCode !== 200) return finish(new Error(`HTTP ${res.statusCode}`));
+        const ct = String(res.headers["content-type"] ?? "");
+        if (!/^application\/json\b/i.test(ct)) return finish(new Error("Non-JSON response"));
+        if (Number(res.headers["content-length"]) > maxBytes) return finish(new Error("Response too large"));
+        const chunks: Buffer[] = [];
+        let total = 0;
+        res.on("data", (chunk: Buffer) => {
+          total += chunk.length;
+          if (total > maxBytes) finish(new Error("Response too large"));
+          else chunks.push(chunk);
+        });
+        res.on("end", () => {
+          try {
+            finish(null, JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks))));
+          } catch {
+            finish(new Error("Invalid JSON"));
+          }
+        });
+        res.on("error", () => finish(new Error("Read failed")));
+        res.on("close", () => {
+          if (!res.complete) finish(new Error("Closed prematurely"));
+        });
+      },
+    );
+    request.on("error", () => finish(new Error("Connect failed")));
+    request.end();
+  });
+}
+
+function sanitizeEntry(raw: Record<string, unknown>): ExplainEntry | undefined {
+  const id = typeof raw.id === "string" ? raw.id : "";
+  const title = typeof raw.title === "string" ? raw.title.trim() : "";
+  if (!SUITE_OBJECT_ID.test(id) || id === "." || id === "..") return undefined;
+  if (!title || title.length > SUITE_LIMITS.title || SUITE_UNSAFE_TEXT.test(title)) return undefined;
+  const href = typeof raw.href === "string" && allowedSuiteRoute("explain", raw.href)
+    ? raw.href
+    : `#/note/${id}`;
+  if (!allowedSuiteRoute("explain", href)) return undefined;
+  const tags = Array.isArray(raw.tags)
+    ? raw.tags.filter((t): t is string => typeof t === "string" && t.length <= 40 && !SUITE_UNSAFE_TEXT.test(t)).slice(0, 8)
+    : [];
+  const category =
+    typeof raw.category === "string" && raw.category.length <= 40 && !SUITE_UNSAFE_TEXT.test(raw.category)
+      ? raw.category
+      : undefined;
+  const sourceObj = raw.source && typeof raw.source === "object" ? (raw.source as Record<string, unknown>) : undefined;
+  const url =
+    typeof raw.url === "string"
+      ? raw.url
+      : typeof sourceObj?.url === "string"
+        ? sourceObj.url
+        : undefined;
+  return { id, title, ...(category ? { category } : {}), tags, ...(url ? { url } : {}), href };
+}
+
+function normalizeToken(value: string): string {
+  return value.toLowerCase().replace(/[\s\-_·.,:;!?()[\]{}"'「」『』《》]/g, "");
+}
+
+export class ExplainBridge {
+  private readonly cache: CacheState = {
+    entries: [],
+    lastAttemptAt: 0,
+    lastFailed: false,
+  };
+
+  constructor(
+    private readonly fetchOrigin?: string,
+    private readonly browserOrigin?: string,
+  ) {}
+
+  private async refresh(force = false): Promise<void> {
+    if (!this.fetchOrigin) return;
+    const now = Date.now();
+    if (!force && this.cache.lastAttemptAt && now - this.cache.lastAttemptAt < SUITE_LIMITS.cacheFreshMs) {
+      return;
+    }
+    if (this.cache.inflight) {
+      await this.cache.inflight;
+      return;
+    }
+    this.cache.inflight = (async () => {
+      this.cache.lastAttemptAt = Date.now();
+      try {
+        let parsedEntries: ExplainEntry[] | undefined;
+        // 1. Try minimized /api/suite/topics first
+        try {
+          const data = (await fetchJsonBounded(`${this.fetchOrigin}/api/suite/topics`)) as {
+            topics?: unknown[];
+          };
+          if (Array.isArray(data?.topics)) {
+            parsedEntries = data.topics
+              .filter((item): item is Record<string, unknown> => Boolean(item && typeof item === "object"))
+              .flatMap((item) => sanitizeEntry(item) ?? []);
+          }
+        } catch {
+          // Fallback to /api/lessons or /api/suite/today on v1 Explain instances
+        }
+
+        if (!parsedEntries) {
+          try {
+            const lessons = await fetchJsonBounded(`${this.fetchOrigin}/api/lessons`);
+            if (Array.isArray(lessons)) {
+              parsedEntries = lessons
+                .filter((item): item is Record<string, unknown> => Boolean(item && typeof item === "object"))
+                .flatMap((item) => sanitizeEntry(item) ?? []);
+            }
+          } catch {
+            const today = (await fetchJsonBounded(`${this.fetchOrigin}/api/suite/today`)) as {
+              items?: unknown[];
+            };
+            if (Array.isArray(today?.items)) {
+              parsedEntries = today.items
+                .filter((item): item is Record<string, unknown> => Boolean(item && typeof item === "object"))
+                .flatMap((item) => sanitizeEntry(item) ?? []);
+            }
+          }
+        }
+
+        if (!parsedEntries) throw new Error("No valid Explain endpoint");
+        this.cache.entries = parsedEntries;
+        this.cache.lastSuccessAt = Date.now();
+        this.cache.lastFailed = false;
+      } catch {
+        this.cache.lastFailed = true;
+        if (
+          this.cache.lastSuccessAt &&
+          Date.now() - this.cache.lastSuccessAt > SUITE_LIMITS.staleDropMs
+        ) {
+          this.cache.entries = [];
+        }
+      } finally {
+        this.cache.inflight = undefined;
+      }
+    })();
+    await this.cache.inflight;
+  }
+
+  async matchForPage(page: SavedPage, forceRefresh = false): Promise<ExplainBridgeStatus> {
+    if (!this.fetchOrigin) {
+      return {
+        status: "unconfigured",
+        ...(this.browserOrigin ? { browserOrigin: this.browserOrigin } : {}),
+        matches: [],
+      };
+    }
+    await this.refresh(forceRefresh);
+
+    const hasRecentSuccess =
+      this.cache.lastSuccessAt !== undefined &&
+      Date.now() - this.cache.lastSuccessAt <= SUITE_LIMITS.staleDropMs;
+
+    if (this.cache.lastFailed && !hasRecentSuccess) {
+      return {
+        status: "unavailable",
+        ...(this.browserOrigin ? { browserOrigin: this.browserOrigin } : {}),
+        matches: [],
+      };
+    }
+
+    const status = this.cache.lastFailed ? "stale" : "ready";
+    const terms = new Map<string, string>();
+    const addTerm = (raw: string | undefined) => {
+      if (!raw || raw === "未分類") return;
+      const norm = normalizeToken(raw);
+      if (norm.length >= 2 && !terms.has(norm)) terms.set(norm, raw.trim());
+    };
+
+    addTerm(page.topic);
+    for (const tag of page.tags) addTerm(tag);
+    for (const ann of page.annotations) {
+      addTerm(ann.topic);
+      if (ann.quote.length <= 24) addTerm(ann.quote);
+    }
+    for (const part of page.title.split(/[\s·—\-:|/、，]+/)) {
+      if (part.trim().length >= 2 && part.trim().length <= 24) addTerm(part);
+    }
+
+    const scored: Array<{ entry: ExplainEntry; score: number; reason: string }> = [];
+    for (const entry of this.cache.entries) {
+      if (page.url && entry.url && page.url === entry.url) {
+        scored.push({ entry, score: 100, reason: "同一來源網址" });
+        continue;
+      }
+      const entryTitleNorm = normalizeToken(entry.title);
+      const entryCategoryNorm = entry.category ? normalizeToken(entry.category) : "";
+      const entryTagsNorm = entry.tags.map((t) => ({ raw: t, norm: normalizeToken(t) }));
+
+      let bestScore = 0;
+      let bestReason = "";
+      for (const [norm, display] of terms) {
+        if (!norm) continue;
+        if (entryTagsNorm.some((t) => t.norm === norm || (t.norm.length >= 2 && (t.norm.includes(norm) || norm.includes(t.norm))))) {
+          if (bestScore < 30) {
+            bestScore = 30;
+            bestReason = `相同主題：${display}`;
+          }
+        } else if (entryTitleNorm.includes(norm) || (entryTitleNorm.length >= 2 && norm.includes(entryTitleNorm))) {
+          if (bestScore < 25) {
+            bestScore = 25;
+            bestReason = `相關筆記：${display}`;
+          }
+        } else if (entryCategoryNorm && (entryCategoryNorm === norm || entryCategoryNorm.includes(norm))) {
+          if (bestScore < 15) {
+            bestScore = 15;
+            bestReason = `同分類：${entry.category}`;
+          }
+        }
+      }
+      if (bestScore > 0) {
+        scored.push({ entry, score: bestScore, reason: bestReason });
+      }
+    }
+
+    scored.sort((a, b) => b.score - a.score);
+    const matches: ExplainTopicMatch[] = scored.slice(0, 5).map(({ entry, reason }) => ({
+      id: entry.id,
+      title: entry.title,
+      ...(entry.category ? { category: entry.category } : {}),
+      tags: entry.tags,
+      href: entry.href,
+      reason,
+    }));
+
+    return {
+      status,
+      ...(this.browserOrigin ? { browserOrigin: this.browserOrigin } : {}),
+      matches,
+    };
+  }
+
+  async listAllTopics(forceRefresh = false): Promise<{
+    status: ExplainBridgeStatus["status"];
+    browserOrigin?: string;
+    entries: ExplainEntry[];
+  }> {
+    if (!this.fetchOrigin) {
+      return {
+        status: "unconfigured",
+        ...(this.browserOrigin ? { browserOrigin: this.browserOrigin } : {}),
+        entries: [],
+      };
+    }
+    await this.refresh(forceRefresh);
+    const hasRecentSuccess =
+      this.cache.lastSuccessAt !== undefined &&
+      Date.now() - this.cache.lastSuccessAt <= SUITE_LIMITS.staleDropMs;
+    if (this.cache.lastFailed && !hasRecentSuccess) {
+      return {
+        status: "unavailable",
+        ...(this.browserOrigin ? { browserOrigin: this.browserOrigin } : {}),
+        entries: [],
+      };
+    }
+    return {
+      status: this.cache.lastFailed ? "stale" : "ready",
+      ...(this.browserOrigin ? { browserOrigin: this.browserOrigin } : {}),
+      entries: this.cache.entries,
+    };
+  }
+}