collabmd 0.1.18

package/src/server/infrastructure/persistence/vault-file-store.js

@@ -0,0 +1,435 @@
+import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'fs/promises';
+import { dirname, join, resolve } from 'path';
+
+import { getVaultTreeNodeType, isVaultFilePath } from '../../../domain/file-kind.js';
+import { getVaultContentAdapter } from './vault-content-adapter.js';
+import {
+  INVALID_VAULT_FILE_PATH_ERROR,
+  isIgnoredVaultEntry,
+  resolveVaultDirectoryPath,
+  resolveVaultFilePath,
+  resolveVaultRenamePaths,
+  sanitizeVaultPath,
+  toVaultRelativePath,
+} from './path-utils.js';
+import { SidecarStore } from './sidecar-store.js';
+
+function createTransactionalPath(targetPath, label) {
+  return `${targetPath}.collabmd-${label}-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2, 10)}`;
+}
+
+function createCommentThreadsPayload(threads = []) {
+  return `${JSON.stringify({
+    threads,
+    version: 1,
+  }, null, 2)}\n`;
+}
+
+async function pathExists(pathValue) {
+  try {
+    await stat(pathValue);
+    return true;
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return false;
+    }
+
+    throw error;
+  }
+}
+
+async function cleanupPaths(paths = []) {
+  await Promise.allSettled(paths.filter(Boolean).map((pathValue) => rm(pathValue, { force: true })));
+}
+
+export class VaultFileStore {
+  constructor({ vaultDir }) {
+    this.vaultDir = resolve(vaultDir);
+    this.sidecarStore = new SidecarStore({ vaultDir: this.vaultDir });
+  }
+
+  async tree() {
+    return this.readDirectory(this.vaultDir);
+  }
+
+  async readDirectory(dirPath) {
+    const entries = [];
+
+    let dirEntries;
+    try {
+      dirEntries = await readdir(dirPath, { withFileTypes: true });
+    } catch {
+      return entries;
+    }
+
+    const sorted = dirEntries.sort((a, b) => {
+      if (a.isDirectory() && !b.isDirectory()) return -1;
+      if (!a.isDirectory() && b.isDirectory()) return 1;
+      return a.name.localeCompare(b.name, undefined, { sensitivity: 'base' });
+    });
+
+    for (const entry of sorted) {
+      if (isIgnoredVaultEntry(entry.name)) {
+        continue;
+      }
+
+      const fullPath = join(dirPath, entry.name);
+      const relativePath = toVaultRelativePath(this.vaultDir, fullPath);
+
+      if (entry.isDirectory()) {
+        entries.push({
+          children: await this.readDirectory(fullPath),
+          name: entry.name,
+          path: relativePath,
+          type: 'directory',
+        });
+        continue;
+      }
+
+      if (isVaultFilePath(entry.name)) {
+        entries.push({
+          name: entry.name,
+          path: relativePath,
+          type: getVaultTreeNodeType(entry.name),
+        });
+      }
+    }
+
+    return entries;
+  }
+
+  resolveContentPath(filePath, { requireVaultFile = true } = {}) {
+    if (!requireVaultFile) {
+      return sanitizeVaultPath(this.vaultDir, filePath);
+    }
+
+    return resolveVaultFilePath(this.vaultDir, filePath).absolute;
+  }
+
+  resolveAdapter(filePath) {
+    const absolute = this.resolveContentPath(filePath);
+    if (!absolute) {
+      return null;
+    }
+
+    const adapter = getVaultContentAdapter(absolute);
+    if (!adapter) {
+      return null;
+    }
+
+    return { absolute, adapter };
+  }
+
+  async readContentFile(filePath, expectedKind) {
+    const resolved = this.resolveAdapter(filePath);
+    if (!resolved || resolved.adapter.kind !== expectedKind) {
+      return null;
+    }
+
+    try {
+      return await readFile(resolved.absolute, 'utf-8');
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        return null;
+      }
+
+      throw error;
+    }
+  }
+
+  async writeContentFile(filePath, content, expectedKind, { invalidateCollaborationSnapshot = true } = {}) {
+    const resolved = this.resolveAdapter(filePath);
+    if (!resolved || resolved.adapter.kind !== expectedKind) {
+      return {
+        ok: false,
+        error: resolved?.adapter?.invalidPathError ?? getVaultContentAdapter(filePath)?.invalidPathError ?? INVALID_VAULT_FILE_PATH_ERROR,
+      };
+    }
+
+    try {
+      await mkdir(dirname(resolved.absolute), { recursive: true });
+      await writeFile(resolved.absolute, content, 'utf-8');
+      if (invalidateCollaborationSnapshot) {
+        await this.deleteCollaborationSnapshot(filePath);
+      }
+      return { ok: true };
+    } catch (error) {
+      return { ok: false, error: error.message };
+    }
+  }
+
+  async readMarkdownFile(filePath) {
+    return this.readContentFile(filePath, 'markdown');
+  }
+
+  async readExcalidrawFile(filePath) {
+    return this.readContentFile(filePath, 'excalidraw');
+  }
+
+  async readMermaidFile(filePath) {
+    return this.readContentFile(filePath, 'mermaid');
+  }
+
+  async readPlantUmlFile(filePath) {
+    return this.readContentFile(filePath, 'plantuml');
+  }
+
+  async writeMarkdownFile(filePath, content, options = {}) {
+    return this.writeContentFile(filePath, content, 'markdown', options);
+  }
+
+  async writeExcalidrawFile(filePath, content, options = {}) {
+    return this.writeContentFile(filePath, content, 'excalidraw', options);
+  }
+
+  async writeMermaidFile(filePath, content, options = {}) {
+    return this.writeContentFile(filePath, content, 'mermaid', options);
+  }
+
+  async writePlantUmlFile(filePath, content, options = {}) {
+    return this.writeContentFile(filePath, content, 'plantuml', options);
+  }
+
+  async persistCollaborationState(filePath, {
+    commentThreads = [],
+    content = '',
+    snapshot = null,
+  } = {}) {
+    const resolved = this.resolveAdapter(filePath);
+    if (!resolved) {
+      return {
+        ok: false,
+        error: getVaultContentAdapter(filePath)?.invalidPathError ?? INVALID_VAULT_FILE_PATH_ERROR,
+      };
+    }
+
+    const operations = [
+      {
+        kind: Array.isArray(commentThreads) && commentThreads.length > 0 ? 'write' : 'delete',
+        targetPath: this.sidecarStore.getCommentThreadPath(filePath),
+        value: createCommentThreadsPayload(commentThreads),
+        writeOptions: 'utf-8',
+      },
+      {
+        kind: snapshot ? 'write' : 'delete',
+        targetPath: this.sidecarStore.getSnapshotPath(filePath),
+        value: snapshot ? Buffer.from(snapshot) : null,
+      },
+      {
+        kind: 'write',
+        targetPath: resolved.absolute,
+        value: content,
+        writeOptions: 'utf-8',
+      },
+    ].filter((operation) => operation.targetPath);
+
+    const stagedWrites = [];
+    const committedOperations = [];
+
+    try {
+      for (const operation of operations) {
+        if (operation.kind !== 'write') {
+          continue;
+        }
+
+        const tempPath = createTransactionalPath(operation.targetPath, 'tmp');
+        await mkdir(dirname(operation.targetPath), { recursive: true });
+        await writeFile(tempPath, operation.value, operation.writeOptions);
+        operation.tempPath = tempPath;
+        stagedWrites.push(tempPath);
+      }
+
+      for (const operation of operations) {
+        const hadExistingTarget = await pathExists(operation.targetPath);
+        const backupPath = hadExistingTarget
+          ? createTransactionalPath(operation.targetPath, 'bak')
+          : null;
+
+        if (backupPath) {
+          await rename(operation.targetPath, backupPath);
+        }
+
+        try {
+          if (operation.kind === 'write') {
+            await rename(operation.tempPath, operation.targetPath);
+            const stagedIndex = stagedWrites.indexOf(operation.tempPath);
+            if (stagedIndex >= 0) {
+              stagedWrites.splice(stagedIndex, 1);
+            }
+          }
+        } catch (error) {
+          if (backupPath) {
+            await rename(backupPath, operation.targetPath);
+          }
+          throw error;
+        }
+
+        committedOperations.push({
+          backupPath,
+          kind: operation.kind,
+          targetPath: operation.targetPath,
+        });
+      }
+
+      await cleanupPaths(committedOperations.map((operation) => operation.backupPath));
+      return { ok: true };
+    } catch (error) {
+      for (const operation of committedOperations.reverse()) {
+        if (operation.kind === 'write') {
+          await rm(operation.targetPath, { force: true });
+        }
+
+        if (operation.backupPath) {
+          await rename(operation.backupPath, operation.targetPath);
+        }
+      }
+
+      await cleanupPaths(stagedWrites);
+      await cleanupPaths(committedOperations.map((operation) => operation.backupPath));
+      return { ok: false, error: error.message };
+    }
+  }
+
+  async readCommentThreads(filePath) {
+    return this.sidecarStore.readCommentThreads(filePath);
+  }
+
+  async writeCommentThreads(filePath, threads = []) {
+    return this.sidecarStore.writeCommentThreads(filePath, threads);
+  }
+
+  async readCollaborationSnapshot(filePath) {
+    return this.sidecarStore.readSnapshot(filePath);
+  }
+
+  async writeCollaborationSnapshot(filePath, snapshot) {
+    return this.sidecarStore.writeSnapshot(filePath, snapshot);
+  }
+
+  async deleteCollaborationSnapshot(filePath) {
+    return this.sidecarStore.deleteSnapshot(filePath);
+  }
+
+  async createFile(filePath, content = '') {
+    const { absolute, error } = resolveVaultFilePath(this.vaultDir, filePath);
+    if (!absolute) {
+      return { ok: false, error };
+    }
+
+    try {
+      await stat(absolute);
+      return { ok: false, error: 'File already exists' };
+    } catch (error) {
+      if (error.code !== 'ENOENT') {
+        throw error;
+      }
+    }
+
+    await mkdir(dirname(absolute), { recursive: true });
+    await writeFile(absolute, content, 'utf-8');
+    await this.deleteCollaborationSnapshot(filePath);
+    return { ok: true };
+  }
+
+  async deleteFile(filePath) {
+    const { absolute, error } = resolveVaultFilePath(this.vaultDir, filePath);
+    if (!absolute) {
+      return { ok: false, error };
+    }
+
+    try {
+      await rm(absolute, { force: true });
+      await this.sidecarStore.deleteAllForFile(filePath);
+      return { ok: true };
+    } catch (error) {
+      return { ok: false, error: error.message };
+    }
+  }
+
+  async renameFile(oldPath, newPath) {
+    const { absoluteNew, absoluteOld, error } = resolveVaultRenamePaths(this.vaultDir, oldPath, newPath);
+    if (!absoluteOld || !absoluteNew) {
+      return { ok: false, error };
+    }
+
+    try {
+      await mkdir(dirname(absoluteNew), { recursive: true });
+      await rename(absoluteOld, absoluteNew);
+      await this.sidecarStore.renameAllForFile(oldPath, newPath);
+      return { ok: true };
+    } catch (error) {
+      return { ok: false, error: error.message };
+    }
+  }
+
+  async createDirectory(dirPath) {
+    const { absolute, error } = resolveVaultDirectoryPath(this.vaultDir, dirPath);
+    if (!absolute) {
+      return { ok: false, error };
+    }
+
+    try {
+      await mkdir(absolute, { recursive: true });
+      return { ok: true };
+    } catch (error) {
+      return { ok: false, error: error.message };
+    }
+  }
+
+  async countVaultFiles() {
+    return this.countFilesInDir(this.vaultDir);
+  }
+
+  async reconcileSidecars({
+    deletedPaths = [],
+    renamedPaths = [],
+  } = {}) {
+    await Promise.allSettled([
+      ...Array.from(new Set((deletedPaths ?? []).filter(Boolean)), (filePath) => this.sidecarStore.deleteAllForFile(filePath)),
+      ...Array.from(
+        new Map(
+          (renamedPaths ?? [])
+            .filter((entry) => entry?.oldPath && entry?.newPath && entry.oldPath !== entry.newPath)
+            .map((entry) => [`${entry.oldPath}:${entry.newPath}`, entry]),
+        ).values(),
+        (entry) => this.sidecarStore.renameAllForFile(entry.oldPath, entry.newPath),
+      ),
+    ]);
+  }
+
+  async countFilesInDir(dirPath) {
+    let count = 0;
+
+    let entries;
+    try {
+      entries = await readdir(dirPath, { withFileTypes: true });
+    } catch {
+      return 0;
+    }
+
+    for (const entry of entries) {
+      if (isIgnoredVaultEntry(entry.name)) {
+        continue;
+      }
+
+      const fullPath = join(dirPath, entry.name);
+      if (entry.isDirectory()) {
+        count += await this.countFilesInDir(fullPath);
+      } else if (isVaultFilePath(entry.name)) {
+        count += 1;
+      }
+    }
+
+    return count;
+  }
+
+  resolveWikiLink(linkTarget) {
+    const normalized = linkTarget.endsWith('.md') ? linkTarget : `${linkTarget}.md`;
+    const absolute = this.resolveContentPath(normalized, { requireVaultFile: false });
+    if (!absolute) {
+      return null;
+    }
+
+    return toVaultRelativePath(this.vaultDir, absolute);
+  }
+}

package/src/server/infrastructure/plantuml/plantuml-renderer.js

@@ -0,0 +1,56 @@
+import { encodePlantUmlText } from '../../domain/plantuml-encoder.js';
+
+function normalizeServerUrl(serverUrl) {
+  const value = String(serverUrl || '').trim();
+  if (!value) {
+    return 'https://www.plantuml.com/plantuml';
+  }
+
+  return value.endsWith('/') ? value.slice(0, -1) : value;
+}
+
+function normalizeSvgPayload(body = '') {
+  const normalized = String(body)
+    .replace(/^\uFEFF/, '')
+    .trim()
+    .replace(/^(?:<\?[\s\S]*?\?>\s*|<!--[\s\S]*?-->\s*)+/i, '');
+
+  return normalized;
+}
+
+export class PlantUmlRenderer {
+  constructor({ fetchImpl = fetch, serverUrl } = {}) {
+    this.fetchImpl = fetchImpl;
+    this.serverUrl = normalizeServerUrl(serverUrl);
+  }
+
+  async renderSvg(source = '') {
+    const encoded = encodePlantUmlText(source);
+    const requestUrl = `${this.serverUrl}/svg/${encoded}`;
+
+    const response = await this.fetchImpl(requestUrl, {
+      headers: {
+        Accept: 'image/svg+xml, text/plain;q=0.9, */*;q=0.1',
+      },
+      signal: AbortSignal.timeout(20_000),
+    });
+
+    const body = await response.text();
+
+    if (!response.ok) {
+      const detail = body.trim() || `Upstream renderer returned ${response.status}`;
+      const error = new Error(detail);
+      error.statusCode = 502;
+      throw error;
+    }
+
+    const normalizedSvg = normalizeSvgPayload(body);
+    if (!normalizedSvg.startsWith('<svg')) {
+      const error = new Error('Upstream renderer returned an invalid SVG payload');
+      error.statusCode = 502;
+      throw error;
+    }
+
+    return normalizedSvg;
+  }
+}

package/src/server/infrastructure/websocket/attach-collaboration-gateway.js

@@ -0,0 +1,194 @@
+import { WebSocketServer } from 'ws';
+
+import { ClientSocketSession } from './client-socket-session.js';
+
+function rejectUpgrade(socket, statusCode, statusMessage, {
+  body = '',
+  headers = {},
+} = {}) {
+  const headerLines = Object.entries(headers)
+    .map(([key, value]) => `${key}: ${value}`)
+    .join('\r\n');
+  const responseBody = String(body ?? '');
+  const contentLengthHeader = responseBody
+    ? `Content-Length: ${Buffer.byteLength(responseBody, 'utf8')}\r\n`
+    : '';
+  socket.write(
+    `HTTP/1.1 ${statusCode} ${statusMessage}\r\n${headerLines}${headerLines ? '\r\n' : ''}${contentLengthHeader}\r\n${responseBody}`,
+  );
+  socket.destroy();
+}
+
+function extractRoomName(pathname, wsBasePath) {
+  const roomSegment = pathname.slice(wsBasePath.length + 1);
+  return decodeURIComponent(roomSegment || 'default');
+}
+
+function stripBasePath(pathname, basePath) {
+  if (!basePath) {
+    return pathname;
+  }
+
+  if (pathname === basePath) {
+    return '/';
+  }
+
+  if (pathname.startsWith(`${basePath}/`)) {
+    return pathname.slice(basePath.length) || '/';
+  }
+
+  return pathname;
+}
+
+function createRequestUrlWithPathname(requestUrl, pathname) {
+  const nextUrl = new URL(requestUrl.toString());
+  nextUrl.pathname = pathname || '/';
+  return nextUrl;
+}
+
+export function attachCollaborationGateway({
+  authService,
+  basePath = '',
+  heartbeatIntervalMs,
+  httpServer,
+  maxPayload,
+  roomRegistry,
+  wsBasePath,
+}) {
+  const websocketServer = new WebSocketServer({
+    maxPayload,
+    noServer: true,
+    perMessageDeflate: false,
+  });
+  const socketSessions = new Map();
+  let isShuttingDown = false;
+  let closePromise = null;
+  const heartbeatTimer = setInterval(() => {
+    websocketServer.clients.forEach((client) => {
+      const session = socketSessions.get(client);
+      if (!session) {
+        return;
+      }
+
+      if (session.isAlive === false) {
+        try {
+          client.terminate();
+        } catch {
+          // Ignore termination errors while collecting dead clients.
+        }
+        return;
+      }
+
+      session.markHeartbeatPending();
+
+      try {
+        client.ping();
+      } catch {
+        try {
+          client.terminate();
+        } catch {
+          // Ignore termination errors while pinging clients.
+        }
+      }
+    });
+  }, heartbeatIntervalMs);
+  heartbeatTimer.unref?.();
+
+  websocketServer.on('connection', (ws, req, requestUrl) => {
+    const roomName = extractRoomName(requestUrl.pathname, wsBasePath);
+    const room = roomRegistry.getOrCreate(roomName);
+    const session = new ClientSocketSession({
+      onDisconnected: (disconnectedRoomName) => {
+        socketSessions.delete(ws);
+        const remaining = roomRegistry.rooms.get(disconnectedRoomName)?.clients.size ?? 0;
+        console.log(`[ws] "${disconnectedRoomName}" disconnected (${remaining} active client(s))`);
+      },
+      onFailed: () => {
+        socketSessions.delete(ws);
+      },
+      room,
+      roomName,
+      ws,
+    });
+    socketSessions.set(ws, session);
+    void session.initialize();
+  });
+
+  httpServer.on('upgrade', (req, socket, head) => {
+    if (isShuttingDown) {
+      rejectUpgrade(socket, 503, 'Server Shutting Down');
+      return;
+    }
+
+    const originalRequestUrl = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
+    const requestUrl = createRequestUrlWithPathname(
+      originalRequestUrl,
+      stripBasePath(originalRequestUrl.pathname, basePath),
+    );
+    const matchesRealtimeRoute =
+      requestUrl.pathname === wsBasePath || requestUrl.pathname.startsWith(`${wsBasePath}/`);
+
+    if (!matchesRealtimeRoute || requestUrl.pathname === wsBasePath) {
+      rejectUpgrade(socket, 404, 'Not Found');
+      return;
+    }
+
+    const authResult = authService.authorizeWebSocketRequest(req, requestUrl);
+    if (!authResult.ok) {
+      rejectUpgrade(socket, authResult.statusCode, authResult.statusMessage, authResult);
+      return;
+    }
+
+    websocketServer.handleUpgrade(req, socket, head, (ws) => {
+      websocketServer.emit('connection', ws, req, requestUrl);
+    });
+  });
+
+  async function close() {
+    if (closePromise) {
+      return closePromise;
+    }
+
+    isShuttingDown = true;
+    clearInterval(heartbeatTimer);
+
+    closePromise = new Promise((resolve, reject) => {
+      const forceCloseTimer = setTimeout(() => {
+        websocketServer.clients.forEach((client) => {
+          try {
+            client.terminate();
+          } catch {
+            // Ignore termination errors during forced shutdown.
+          }
+        });
+      }, 1000);
+      forceCloseTimer.unref?.();
+
+      websocketServer.close((error) => {
+        clearTimeout(forceCloseTimer);
+
+        if (error) {
+          reject(error);
+          return;
+        }
+
+        resolve();
+      });
+
+      websocketServer.clients.forEach((client) => {
+        try {
+          client.close(1001, 'Server shutting down');
+        } catch {
+          // Ignore close errors during shutdown.
+        }
+      });
+    });
+
+    return closePromise;
+  }
+
+  return {
+    close,
+    websocketServer,
+  };
+}