mulmoclaude 0.1.0

package/server/api/routes/wiki/pageIndex.ts

@@ -0,0 +1,53 @@
+// In-memory index of `wiki/pages/*.md` keyed by slug (= filename
+// without the `.md` extension). Kept fresh via `pagesDir` mtime —
+// adding, removing, or renaming a file under `pagesDir` advances
+// the directory's mtime on every major filesystem we target
+// (macOS APFS, Linux ext4, Windows NTFS), so one cheap `stat()`
+// per request is enough to decide whether to rebuild.
+//
+// Eliminates the sync `readdirSync` + linear `find()` in the old
+// `resolvePagePath` — see #201.
+
+import { readDirSafeAsync, statSafeAsync } from "../../../utils/files/safe.js";
+
+export interface PageIndex {
+  mtimeMs: number;
+  /** slug → filename (e.g. "sakura-internet" → "sakura-internet.md"). */
+  slugs: Map<string, string>;
+}
+
+let cache: PageIndex | null = null;
+
+/**
+ * Get the page index for `pagesDir`. Returns a cached value as long
+ * as the directory's mtime hasn't advanced; otherwise rebuilds.
+ *
+ * Safe to call concurrently — racing builds produce the same result.
+ */
+export async function getPageIndex(pagesDir: string): Promise<PageIndex> {
+  const stat = await statSafeAsync(pagesDir);
+  if (!stat) {
+    // Dir doesn't exist yet (never ingested). Return empty but
+    // don't cache a stale-forever value — the next call will
+    // re-stat and pick up the dir once it lands.
+    return { mtimeMs: 0, slugs: new Map() };
+  }
+  if (cache && cache.mtimeMs >= stat.mtimeMs) {
+    return cache;
+  }
+  const entries = await readDirSafeAsync(pagesDir);
+  const slugs = new Map<string, string>();
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    const name = entry.name;
+    if (!name.endsWith(".md")) continue;
+    slugs.set(name.slice(0, -".md".length), name);
+  }
+  cache = { mtimeMs: stat.mtimeMs, slugs };
+  return cache;
+}
+
+/** Test-only: drop the module-level cache. */
+export function __resetPageIndexCache(): void {
+  cache = null;
+}

package/server/api/routes/wiki.ts

@@ -0,0 +1,363 @@
+import { Router, Request, Response } from "express";
+import path from "path";
+import { WORKSPACE_PATHS } from "../../workspace/paths.js";
+import { readTextSafeSync, readTextSafe } from "../../utils/files/safe.js";
+import { getPageIndex } from "./wiki/pageIndex.js";
+import { badRequest } from "../../utils/httpError.js";
+import { API_ROUTES } from "../../../src/config/apiRoutes.js";
+
+const router = Router();
+
+const pagesDir = () => WORKSPACE_PATHS.wikiPages;
+const indexFile = () => WORKSPACE_PATHS.wikiIndex;
+const logFile = () => WORKSPACE_PATHS.wikiLog;
+
+function readFileOrEmpty(absPath: string): string {
+  return readTextSafeSync(absPath) ?? "";
+}
+
+export interface WikiPageEntry {
+  title: string;
+  slug: string;
+  description: string;
+}
+
+// Slug rules: lowercase, spaces to hyphens, strip everything that
+// isn't a-z / 0-9 / hyphen. Used for both index parsing and page
+// lookup so the two stay consistent.
+export function wikiSlugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/\s+/g, "-")
+    .replace(/[^a-z0-9-]/g, "");
+}
+
+const TABLE_SEPARATOR_PATTERN = /^\|[\s|:-]+\|$/;
+// Capture the href (group 2) alongside the title (group 1) so we can
+// derive the slug from the file name instead of re-slugifying the
+// title. This matters for non-ASCII titles like "さくらインターネット"
+// where `wikiSlugify` returns "" and the slug would otherwise be lost.
+const BULLET_LINK_PATTERN = /^[-*]\s+\[([^\]]+)\]\(([^)]*)\)(?:\s*[—–-]\s*(.*))?/;
+const BULLET_WIKI_LINK_PATTERN = /^[-*]\s+\[\[([^\]]+)\]\](?:\s*[—–-]\s*(.*))?/;
+
+// Each parser returns the entry it produced (if any). The parent
+// loop tries them in order; the first non-null result wins.
+function parseTableRow(trimmed: string): WikiPageEntry | null {
+  const cols = trimmed
+    .split("|")
+    .slice(1, -1)
+    .map((c) => c.trim().replace(/^`|`$/g, ""));
+  if (cols.length < 2) return null;
+  const slug = cols[0];
+  const title = cols[1] || slug;
+  const desc = cols[2] ?? "";
+  if (!slug || !title) return null;
+  return { title, slug, description: desc };
+}
+
+// Extract the slug segment from a bullet link's href. Accepts the
+// canonical `pages/<slug>.md`, a bare `<slug>.md`, or just `<slug>`
+// — the three forms produced by different historical writers of
+// index.md. Returns "" for hrefs that don't look like a wiki page
+// reference (e.g. `https://example.com`) so the caller can fall
+// back to title-based slugification.
+export function extractSlugFromBulletHref(rawHref: string): string {
+  const href = rawHref.trim();
+  if (!href) return "";
+  if (/^[a-z]+:\/\//i.test(href)) return "";
+  const lastSegment = href.split("/").pop() ?? href;
+  return lastSegment.replace(/\.md$/i, "");
+}
+
+function parseBulletLinkRow(trimmed: string): WikiPageEntry | null {
+  const m = BULLET_LINK_PATTERN.exec(trimmed);
+  if (!m) return null;
+  const title = m[1].trim();
+  const href = m[2] ?? "";
+  const desc = m[3]?.trim() ?? "";
+  // Prefer the slug embedded in the href so non-ASCII titles keep
+  // a navigable slug. Fall back to slugifying the title only when
+  // the href has no recognisable slug (rare — usually means the
+  // author put an external URL here).
+  const slug = extractSlugFromBulletHref(href) || wikiSlugify(title);
+  return { title, slug, description: desc };
+}
+
+function parseBulletWikiLinkRow(trimmed: string): WikiPageEntry | null {
+  const m = BULLET_WIKI_LINK_PATTERN.exec(trimmed);
+  if (!m) return null;
+  const title = m[1].trim();
+  const desc = m[2]?.trim() ?? "";
+  return { title, slug: wikiSlugify(title), description: desc };
+}
+
+// Parse entries from index.md — supports three formats:
+// 1. Table: | `slug` | Title | Summary | Date |
+// 2. Bullet link: - [Title](pages/slug.md) — description
+// 3. Wiki link: - [[Title]] — description
+export function parseIndexEntries(content: string): WikiPageEntry[] {
+  const entries: WikiPageEntry[] = [];
+  let inTable = false;
+
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+
+    if (trimmed.startsWith("|")) {
+      // Header / separator rows just toggle the in-table flag and
+      // produce no entry.
+      if (TABLE_SEPARATOR_PATTERN.test(trimmed) || !inTable) {
+        inTable = true;
+        continue;
+      }
+      const entry = parseTableRow(trimmed);
+      if (entry) entries.push(entry);
+      continue;
+    }
+
+    inTable = false;
+
+    const bullet = parseBulletLinkRow(trimmed) ?? parseBulletWikiLinkRow(trimmed);
+    if (bullet) entries.push(bullet);
+  }
+  return entries;
+}
+
+// Resolve a page name to an absolute `.md` path using the in-memory
+// page index (see ./wiki/pageIndex.ts). Index is kept fresh via
+// pagesDir mtime, so zero readdir cost on cache hit.
+async function resolvePagePath(pageName: string): Promise<string | null> {
+  const dir = pagesDir();
+  const { slugs } = await getPageIndex(dir);
+  if (slugs.size === 0) return null;
+
+  const slug = wikiSlugify(pageName);
+
+  const exact = slugs.get(slug);
+  if (exact) return path.join(dir, exact);
+
+  // Fuzzy: same `includes` semantics as the old sync path — iterate
+  // the index's keys, no filesystem access.
+  for (const [key, file] of slugs) {
+    if (slug.includes(key) || key.includes(slug)) {
+      return path.join(dir, file);
+    }
+  }
+  return null;
+}
+
+router.get(API_ROUTES.wiki.base, async (req: Request, res: Response<WikiResponse | ErrorResponse>) => {
+  const slug = typeof req.query.slug === "string" ? req.query.slug : undefined;
+  if (slug) {
+    const filePath = await resolvePagePath(slug);
+    const content = filePath ? readFileOrEmpty(filePath) : "";
+    const resolvedTitle = filePath ? path.basename(filePath, ".md") : slug;
+    res.json({
+      data: {
+        action: "page",
+        title: resolvedTitle,
+        content,
+        pageName: resolvedTitle,
+        error: content ? undefined : `Page not found: ${slug}`,
+      },
+      message: content ? `Showing page: ${resolvedTitle}` : `Page not found: ${slug}`,
+      title: resolvedTitle,
+      instructions: "The wiki page is now displayed on the canvas.",
+      updating: true,
+    });
+  } else {
+    const content = readFileOrEmpty(indexFile());
+    const pageEntries = parseIndexEntries(content);
+    res.json({
+      data: { action: "index", title: "Wiki Index", content, pageEntries },
+      message: content ? `Wiki index — ${pageEntries.length} page(s)` : "Wiki index is empty.",
+      title: "Wiki Index",
+      instructions: "The wiki index is now displayed on the canvas.",
+      updating: true,
+    });
+  }
+});
+
+interface WikiBody {
+  action: string;
+  pageName?: string;
+}
+
+interface WikiData {
+  action: string;
+  title: string;
+  content: string;
+  pageEntries?: WikiPageEntry[];
+  pageName?: string;
+  error?: string;
+}
+
+interface WikiResponse {
+  data: WikiData;
+  message: string;
+  title: string;
+  instructions: string;
+  updating: boolean;
+}
+
+interface ErrorResponse {
+  error: string;
+}
+
+function buildIndexResponse(action: string): WikiResponse {
+  const content = readFileOrEmpty(indexFile());
+  const pageEntries = parseIndexEntries(content);
+  return {
+    data: { action, title: "Wiki Index", content, pageEntries },
+    message: content ? `Wiki index — ${pageEntries.length} page(s)` : "Wiki index is empty.",
+    title: "Wiki Index",
+    instructions: "The wiki index is now displayed on the canvas.",
+    updating: true,
+  };
+}
+
+async function buildPageResponse(action: string, pageName: string): Promise<WikiResponse> {
+  const filePath = await resolvePagePath(pageName);
+  const content = filePath ? readFileOrEmpty(filePath) : "";
+  const resolvedTitle = filePath ? path.basename(filePath, ".md") : pageName;
+  const found = !!content;
+  return {
+    data: {
+      action,
+      title: resolvedTitle,
+      content,
+      pageName: resolvedTitle,
+      error: found ? undefined : `Page not found: ${pageName}`,
+    },
+    message: found ? `Showing page: ${resolvedTitle}` : `Page not found: ${pageName}`,
+    title: resolvedTitle,
+    instructions: found
+      ? "The wiki page is now displayed on the canvas."
+      : `Page not found: wiki/pages/${wikiSlugify(pageName)}.md does not exist. You can create it or check the slug in wiki/index.md.`,
+    updating: true,
+  };
+}
+
+function buildLogResponse(action: string): WikiResponse {
+  const content = readFileOrEmpty(logFile());
+  return {
+    data: { action, title: "Activity Log", content },
+    message: content ? "Wiki activity log" : "Activity log is empty.",
+    title: "Activity Log",
+    instructions: "The wiki activity log is now displayed on the canvas.",
+    updating: true,
+  };
+}
+
+const WIKI_LINK_PATTERN = /\[\[([^\][\r\n]{1,200})\]\]/g;
+
+// Pure helpers extracted from the lint pass — they take what they
+// need as plain inputs so each rule can be unit-tested without
+// touching the filesystem.
+
+export function findOrphanPages(fileSlugs: ReadonlySet<string>, indexedSlugs: ReadonlySet<string>): string[] {
+  const issues: string[] = [];
+  for (const slug of fileSlugs) {
+    if (!indexedSlugs.has(slug)) {
+      issues.push(`- **Orphan page**: \`${slug}.md\` exists but is missing from index.md`);
+    }
+  }
+  return issues;
+}
+
+export function findMissingFiles(pageEntries: readonly WikiPageEntry[], fileSlugs: ReadonlySet<string>): string[] {
+  const issues: string[] = [];
+  for (const entry of pageEntries) {
+    if (!fileSlugs.has(entry.slug)) {
+      issues.push(`- **Missing file**: index.md references \`${entry.slug}\` but the file does not exist`);
+    }
+  }
+  return issues;
+}
+
+export function findBrokenLinksInPage(fileName: string, content: string, fileSlugs: ReadonlySet<string>): string[] {
+  const issues: string[] = [];
+  const wikiLinks = [...content.matchAll(WIKI_LINK_PATTERN)].map((m) => m[1]);
+  for (const link of wikiLinks) {
+    const linkSlug = wikiSlugify(link);
+    if (!fileSlugs.has(linkSlug)) {
+      issues.push(`- **Broken link** in \`${fileName}\`: [[${link}]] → \`${linkSlug}.md\` not found`);
+    }
+  }
+  return issues;
+}
+
+export function formatLintReport(issues: readonly string[]): string {
+  if (issues.length === 0) {
+    return "# Wiki Lint Report\n\n✓ No issues found. Wiki is healthy.";
+  }
+  const noun = `issue${issues.length !== 1 ? "s" : ""}`;
+  return `# Wiki Lint Report\n\n${issues.length} ${noun} found:\n\n${issues.join("\n")}`;
+}
+
+async function collectLintIssues(): Promise<string[]> {
+  const dir = pagesDir();
+  const { slugs } = await getPageIndex(dir);
+  if (slugs.size === 0) {
+    return ["- Wiki `pages/` directory does not exist yet. Start ingesting sources."];
+  }
+  const indexContent = readFileOrEmpty(indexFile());
+  const pageEntries = parseIndexEntries(indexContent);
+  const indexedSlugs = new Set(pageEntries.map((e) => e.slug));
+  const pageFiles = [...slugs.values()];
+  const fileSlugs = new Set(slugs.keys());
+
+  const issues: string[] = [];
+  issues.push(...findOrphanPages(fileSlugs, indexedSlugs));
+  issues.push(...findMissingFiles(pageEntries, fileSlugs));
+  // Parallel read: N small markdown files, ~50 KB each. Bounded by
+  // the number of wiki pages, not by CPU.
+  const contents = await Promise.all(
+    pageFiles.map(async (f) => {
+      const content = await readTextSafe(path.join(dir, f));
+      return content ?? "";
+    }),
+  );
+  for (let i = 0; i < pageFiles.length; i++) {
+    issues.push(...findBrokenLinksInPage(pageFiles[i], contents[i], fileSlugs));
+  }
+  return issues;
+}
+
+async function buildLintReportResponse(action: string): Promise<WikiResponse> {
+  const issues = await collectLintIssues();
+  const report = formatLintReport(issues);
+  const healthy = issues.length === 0;
+  return {
+    data: { action, title: "Wiki Lint Report", content: report },
+    message: healthy ? "Wiki is healthy" : `${issues.length} issue(s) found`,
+    title: "Wiki Lint Report",
+    instructions: healthy ? "Wiki is healthy — no issues found." : `${issues.length} issue(s) found that need fixing:\n${issues.join("\n")}`,
+    updating: true,
+  };
+}
+
+router.post(API_ROUTES.wiki.base, async (req: Request<object, unknown, WikiBody>, res: Response<WikiResponse | ErrorResponse>) => {
+  const { action, pageName } = req.body;
+  switch (action) {
+    case "index":
+      res.json(buildIndexResponse(action));
+      return;
+    case "page":
+      if (!pageName) {
+        badRequest(res, "pageName required for page action");
+        return;
+      }
+      res.json(await buildPageResponse(action, pageName));
+      return;
+    case "log":
+      res.json(buildLogResponse(action));
+      return;
+    case "lint_report":
+      res.json(await buildLintReportResponse(action));
+      return;
+    default:
+      badRequest(res, `Unknown action: ${action}`);
+  }
+});
+
+export default router;

package/server/api/sandboxStatus.ts

@@ -0,0 +1,64 @@
+// Compute the sandbox-auth snapshot exposed via GET /api/sandbox.
+//
+// The popup (`src/components/LockStatusPopup.vue`) consumes this to
+// surface what credentials are actually attached to the Docker
+// container, so users can confirm their `SANDBOX_SSH_AGENT_FORWARD` /
+// `SANDBOX_MOUNT_CONFIGS` env vars took effect without grepping the
+// startup log.
+//
+// Keep the payload **minimum**: names only, no host paths, no skip
+// reasons, no unknown-entry lists. Full detail already lives in the
+// server log via the `log.warn` / `log.info` calls inside
+// `resolveSandboxAuth`. Exposing host paths to the browser is an
+// intentional non-goal (see #329).
+
+import { buildAllowedConfigMounts, resolveMountNames, sshAgentForwardArgs } from "../agent/sandboxMounts.js";
+
+export interface SandboxStatus {
+  /** True iff the host SSH agent socket is bound into the container. */
+  sshAgent: boolean;
+  /**
+   * Allowlisted config mount names that actually got attached — i.e.
+   * the user requested them AND the host path exists. Order preserved
+   * from `SANDBOX_MOUNT_CONFIGS`.
+   */
+  mounts: string[];
+}
+
+export interface BuildSandboxStatusParams {
+  /** Output of `setupSandbox()` — true when Docker is running AND
+   *  `DISABLE_SANDBOX` is unset. When false, the builder returns null
+   *  so the handler serializes an empty `{}` body. */
+  sandboxEnabled: boolean;
+  sshAgentForward: boolean;
+  configMountNames: readonly string[];
+  sshAuthSock?: string | undefined;
+  home?: string;
+  /** Injected for tests; defaults to `process.platform`. */
+  platform?: typeof process.platform;
+}
+
+/**
+ * Returns `null` when the sandbox is disabled — the caller (Express
+ * handler) serializes that as `{}`, matching the agreed API contract
+ * (#329). When enabled, returns the structured `{ sshAgent, mounts }`
+ * snapshot.
+ *
+ * Pure: no logging, no side effects beyond filesystem existence
+ * probes done by `resolveMountNames` (same probes the agent spawner
+ * already runs per request).
+ */
+export function buildSandboxStatus(params: BuildSandboxStatusParams): SandboxStatus | null {
+  if (!params.sandboxEnabled) return null;
+
+  const allowed = buildAllowedConfigMounts(params.home);
+  const parsed = resolveMountNames(params.configMountNames, allowed);
+
+  const ssh = sshAgentForwardArgs(params.sshAgentForward, params.sshAuthSock, params.platform);
+  const sshAgent = ssh.args.length > 0;
+
+  return {
+    sshAgent,
+    mounts: parsed.resolved.map((m) => m.name),
+  };
+}

package/server/events/notifications.ts

@@ -0,0 +1,160 @@
+// Notification system (#144).
+//
+// Publishes NotificationPayload to:
+//   1. Web pub-sub → bell badge + panel
+//   2. Chat-service bridge → Telegram / CLI
+//
+// Callers (trigger sources) use `publishNotification()` to fire.
+// In-memory store keeps the last N notifications for the bell panel.
+// publishNotification() is wrapped in try-catch so failures never
+// propagate to callers (e.g. endRun in session-store).
+
+import { PUBSUB_CHANNELS } from "../../src/config/pubsubChannels.js";
+import {
+  NOTIFICATION_KINDS,
+  NOTIFICATION_ICONS,
+  NOTIFICATION_ACTION_TYPES,
+  NOTIFICATION_PRIORITIES,
+  type NotificationPayload,
+  type NotificationKind,
+  type NotificationAction,
+  type NotificationPriority,
+} from "../../src/types/notification.js";
+import { ONE_SECOND_MS, MAX_NOTIFICATION_DELAY_SEC } from "../utils/time.js";
+import { log } from "../system/logger/index.js";
+
+// ── Dependencies (injected at startup) ──────────────────────────
+
+export interface NotificationDeps {
+  publish: (channel: string, payload: unknown) => void;
+  pushToBridge: (transportId: string, chatId: string, message: string) => void;
+}
+
+let deps: NotificationDeps | null = null;
+
+export function initNotifications(d: NotificationDeps): void {
+  deps = d;
+}
+
+// ── In-memory store ─────────────────────────────────────────────
+
+const MAX_STORED = 50;
+const store: NotificationPayload[] = [];
+
+export function getRecentNotifications(): readonly NotificationPayload[] {
+  return store;
+}
+
+// ── Publish ─────────────────────────────────────────────────────
+
+export interface PublishNotificationOpts {
+  kind: NotificationKind;
+  title: string;
+  body?: string;
+  action?: NotificationAction;
+  priority?: NotificationPriority;
+  sessionId?: string;
+  transportId?: string;
+}
+
+export function publishNotification(opts: PublishNotificationOpts): void {
+  try {
+    const payload: NotificationPayload = {
+      id: crypto.randomUUID(),
+      kind: opts.kind,
+      title: opts.title,
+      body: opts.body,
+      icon: NOTIFICATION_ICONS[opts.kind],
+      action: opts.action ?? { type: NOTIFICATION_ACTION_TYPES.none },
+      firedAt: new Date().toISOString(),
+      priority: opts.priority ?? NOTIFICATION_PRIORITIES.normal,
+      sessionId: opts.sessionId,
+      transportId: opts.transportId,
+    };
+
+    // Store for bell panel
+    store.unshift(payload);
+    if (store.length > MAX_STORED) store.length = MAX_STORED;
+
+    // Push to Web UI via pub-sub
+    if (deps) {
+      deps.publish(PUBSUB_CHANNELS.notifications, payload);
+    }
+
+    // Push to bridge (Telegram/CLI)
+    if (deps && opts.transportId) {
+      deps.pushToBridge(opts.transportId, "notifications", formatBridgeMessage(payload));
+    }
+
+    log.info("notifications", "published", {
+      kind: payload.kind,
+      title: payload.title,
+      id: payload.id,
+    });
+  } catch (err) {
+    // Never let notification failures break the caller (e.g. endRun).
+    log.warn("notifications", "publish failed", { error: String(err) });
+  }
+}
+
+function formatBridgeMessage(p: NotificationPayload): string {
+  const icon = p.kind === NOTIFICATION_KINDS.agent ? "\u2705" : "\u{1F514}";
+  const parts = [icon, p.title];
+  if (p.body) parts.push(p.body);
+  return parts.join(" ");
+}
+
+// ── Legacy test notification (kept for PoC endpoint) ────────────
+
+export const DEFAULT_NOTIFICATION_MESSAGE = "Test notification";
+export const DEFAULT_NOTIFICATION_TRANSPORT_ID = "cli";
+export const DEFAULT_NOTIFICATION_CHAT_ID = "notifications";
+
+export interface ScheduleNotificationOptions {
+  message?: string;
+  delaySeconds?: number;
+  transportId?: string;
+  chatId?: string;
+}
+
+export interface ScheduledNotification {
+  firesAt: string;
+  delaySeconds: number;
+  cancel: () => void;
+}
+
+export function scheduleTestNotification(opts: ScheduleNotificationOptions, legacyDeps: NotificationDeps): ScheduledNotification {
+  const message = opts.message ?? DEFAULT_NOTIFICATION_MESSAGE;
+  const transportId = opts.transportId ?? DEFAULT_NOTIFICATION_TRANSPORT_ID;
+  const chatId = opts.chatId ?? DEFAULT_NOTIFICATION_CHAT_ID;
+  const delaySeconds = clampDelay(opts.delaySeconds);
+  const delayMs = delaySeconds * ONE_SECOND_MS;
+
+  const firesAt = new Date(Date.now() + delayMs).toISOString();
+
+  const timer = setTimeout(() => {
+    publishNotification({
+      kind: NOTIFICATION_KINDS.push,
+      title: message,
+      priority: NOTIFICATION_PRIORITIES.normal,
+    });
+    legacyDeps.pushToBridge(transportId, chatId, message);
+  }, delayMs);
+
+  return {
+    firesAt,
+    delaySeconds,
+    cancel: () => clearTimeout(timer),
+  };
+}
+
+const DEFAULT_DELAY_SECONDS = 60;
+
+function clampDelay(raw: number | undefined): number {
+  if (typeof raw !== "number" || !Number.isFinite(raw)) {
+    return DEFAULT_DELAY_SECONDS;
+  }
+  if (raw < 0) return 0;
+  if (raw > MAX_NOTIFICATION_DELAY_SEC) return MAX_NOTIFICATION_DELAY_SEC;
+  return Math.floor(raw);
+}

package/server/events/pub-sub/index.ts

@@ -0,0 +1,45 @@
+import http from "http";
+import { Server as IOServer } from "socket.io";
+
+export interface IPubSub {
+  /** Publish data to all clients subscribed to this channel. */
+  publish(channel: string, data: unknown): void;
+}
+
+// Channel names are treated as socket.io rooms — one room per
+// channel. Subscribe/unsubscribe is plain `socket.join` /
+// `socket.leave`. Publish broadcasts to the room. Reconnect /
+// heartbeat / multi-transport fallback are handled by socket.io
+// itself, which is why we switched off raw ws.
+
+export function createPubSub(server: http.Server): IPubSub {
+  const io = new IOServer(server, {
+    path: "/ws/pubsub",
+    // Server binds to 127.0.0.1 only, so CORS is moot — but
+    // socket.io defaults to rejecting cross-origin upgrade
+    // requests. Allow same-origin explicitly to cover the
+    // dev-proxy case (vite serves on a different port than the
+    // API server during `yarn dev`).
+    cors: { origin: true, credentials: true },
+    // Skip the long-poll transport negotiation: loopback-only
+    // deployment can always upgrade to WebSocket, and starting
+    // there avoids the 200ms long-poll round trip on first
+    // connection.
+    transports: ["websocket"],
+  });
+
+  io.on("connection", (socket) => {
+    socket.on("subscribe", (channel: unknown) => {
+      if (typeof channel === "string") socket.join(channel);
+    });
+    socket.on("unsubscribe", (channel: unknown) => {
+      if (typeof channel === "string") socket.leave(channel);
+    });
+  });
+
+  return {
+    publish(channel: string, data: unknown): void {
+      io.to(channel).emit("data", { channel, data });
+    },
+  };
+}