collabmd 0.1.18

package/src/server/config/env.js

@@ -0,0 +1,186 @@
+import { resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+import {
+  AUTH_STRATEGY_NONE,
+  AUTH_STRATEGY_PASSWORD,
+  SUPPORTED_AUTH_STRATEGIES,
+  createRandomAuthPassword,
+  createRandomSessionSecret,
+} from '../auth/create-auth-service.js';
+
+function parsePositiveInt(rawValue, fallbackValue) {
+  const parsed = Number.parseInt(rawValue ?? '', 10);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallbackValue;
+}
+
+function parsePort(rawPort, fallbackPort) {
+  return parsePositiveInt(rawPort, fallbackPort);
+}
+
+function normalizeOptionalString(value) {
+  const normalized = String(value ?? '').trim();
+  return normalized.length > 0 ? normalized : '';
+}
+
+function normalizeAppBasePath(basePath) {
+  const normalized = normalizeOptionalString(basePath);
+  if (!normalized || normalized === '/') {
+    return '';
+  }
+
+  if (/^[a-zA-Z][a-zA-Z\d+.-]*:/u.test(normalized)) {
+    try {
+      return normalizeAppBasePath(new URL(normalized).pathname);
+    } catch {
+      return '';
+    }
+  }
+
+  const trimmed = normalized.startsWith('/') ? normalized : `/${normalized}`;
+  return trimmed.endsWith('/') ? trimmed.slice(0, -1) : trimmed;
+}
+
+function normalizeRoutePath(routePath, fallbackPath) {
+  if (!routePath || routePath === '/') {
+    return fallbackPath;
+  }
+
+  const trimmed = routePath.startsWith('/') ? routePath : `/${routePath}`;
+  return trimmed.endsWith('/') ? trimmed.slice(0, -1) : trimmed;
+}
+
+function normalizeWsBasePath(basePath) {
+  return normalizeRoutePath(basePath, '/ws');
+}
+
+function normalizeAuthStrategy(rawStrategy) {
+  const normalized = String(rawStrategy ?? AUTH_STRATEGY_NONE).trim().toLowerCase();
+  if (!SUPPORTED_AUTH_STRATEGIES.has(normalized)) {
+    throw new Error(
+      `Unsupported auth strategy "${rawStrategy}". Supported values: ${Array.from(SUPPORTED_AUTH_STRATEGIES).join(', ')}`,
+    );
+  }
+
+  return normalized;
+}
+
+const projectRoot = resolve(fileURLToPath(new URL('../../../', import.meta.url)));
+
+function getDefaultHost(nodeEnv) {
+  return nodeEnv === 'production' ? '0.0.0.0' : '127.0.0.1';
+}
+
+function resolveOptionalPath(filePath) {
+  const normalized = normalizeOptionalString(filePath);
+  return normalized ? resolve(normalized) : '';
+}
+
+function loadGitConfig(overrides = {}) {
+  const remoteOverrides = overrides.remote ?? {};
+  const identityOverrides = overrides.identity ?? {};
+  const enabled = overrides.enabled ?? (process.env.COLLABMD_GIT_ENABLED !== 'false');
+  const repoUrl = normalizeOptionalString(
+    remoteOverrides.repoUrl
+    ?? process.env.COLLABMD_GIT_REPO_URL,
+  );
+  const identityName = normalizeOptionalString(
+    identityOverrides.name
+    ?? process.env.COLLABMD_GIT_USER_NAME
+    ?? process.env.GIT_AUTHOR_NAME
+    ?? process.env.GIT_COMMITTER_NAME,
+  );
+  const identityEmail = normalizeOptionalString(
+    identityOverrides.email
+    ?? process.env.COLLABMD_GIT_USER_EMAIL
+    ?? process.env.GIT_AUTHOR_EMAIL
+    ?? process.env.GIT_COMMITTER_EMAIL,
+  );
+  const sshPrivateKeyFile = resolveOptionalPath(
+    remoteOverrides.sshPrivateKeyFile
+    ?? process.env.COLLABMD_GIT_SSH_PRIVATE_KEY_FILE,
+  );
+  const sshPrivateKeyBase64 = normalizeOptionalString(
+    remoteOverrides.sshPrivateKeyBase64
+    ?? process.env.COLLABMD_GIT_SSH_PRIVATE_KEY_B64,
+  );
+  const sshKnownHostsFile = resolveOptionalPath(
+    remoteOverrides.sshKnownHostsFile
+    ?? process.env.COLLABMD_GIT_SSH_KNOWN_HOSTS_FILE,
+  );
+  const remoteEnabled = repoUrl.length > 0;
+
+  if (remoteEnabled && !sshPrivateKeyFile && !sshPrivateKeyBase64) {
+    throw new Error(
+      'Remote git bootstrap requires COLLABMD_GIT_SSH_PRIVATE_KEY_FILE or COLLABMD_GIT_SSH_PRIVATE_KEY_B64.',
+    );
+  }
+
+  return {
+    cleanup: overrides.cleanup ?? null,
+    commandEnv: overrides.commandEnv ?? null,
+    enabled,
+    identity: {
+      email: identityEmail,
+      name: identityName,
+    },
+    remote: {
+      enabled: remoteEnabled,
+      repoUrl,
+      sshKnownHostsFile,
+      sshPrivateKeyBase64,
+      sshPrivateKeyFile,
+    },
+  };
+}
+
+export function loadConfig(overrides = {}) {
+  const nodeEnv = process.env.NODE_ENV || 'development';
+  const vaultDir = overrides.vaultDir
+    || process.env.COLLABMD_VAULT_DIR
+    || resolve(projectRoot, 'data/vault');
+  const authOverrides = overrides.auth ?? {};
+  const authStrategy = normalizeAuthStrategy(
+    authOverrides.strategy
+    ?? process.env.AUTH_STRATEGY
+    ?? AUTH_STRATEGY_NONE,
+  );
+  const passwordWasGenerated = authStrategy === AUTH_STRATEGY_PASSWORD
+    && !(authOverrides.password || process.env.AUTH_PASSWORD);
+  const password = authStrategy === AUTH_STRATEGY_PASSWORD
+    ? (authOverrides.password || process.env.AUTH_PASSWORD || createRandomAuthPassword())
+    : '';
+  const git = loadGitConfig(overrides.git);
+
+  return {
+    auth: {
+      generatedPassword: passwordWasGenerated ? password : '',
+      password,
+      passwordWasGenerated,
+      sessionCookieName: authOverrides.sessionCookieName || process.env.AUTH_SESSION_COOKIE_NAME || 'collabmd_auth',
+      sessionSecret: authOverrides.sessionSecret || process.env.AUTH_SESSION_SECRET || createRandomSessionSecret(),
+      strategy: authStrategy,
+    },
+    basePath: normalizeAppBasePath(process.env.BASE_PATH || ''),
+    host: process.env.HOST || getDefaultHost(nodeEnv),
+    httpHeadersTimeoutMs: parsePositiveInt(process.env.HTTP_HEADERS_TIMEOUT_MS, 60_000),
+    httpKeepAliveTimeoutMs: parsePositiveInt(process.env.HTTP_KEEP_ALIVE_TIMEOUT_MS, 5_000),
+    httpRequestTimeoutMs: parsePositiveInt(process.env.HTTP_REQUEST_TIMEOUT_MS, 30_000),
+    git,
+    gitEnabled: git.enabled,
+    port: parsePort(process.env.PORT, 1234),
+    nodeEnv,
+    plantumlServerUrl: process.env.PLANTUML_SERVER_URL || 'https://www.plantuml.com/plantuml',
+    publicDir: resolve(projectRoot, 'public'),
+    vaultDir,
+    publicWsBaseUrl: process.env.PUBLIC_WS_BASE_URL || '',
+    wsHeartbeatIntervalMs: parsePositiveInt(process.env.WS_HEARTBEAT_INTERVAL_MS, 30_000),
+    wsRoomIdleGraceMs: parsePositiveInt(process.env.WS_ROOM_IDLE_GRACE_MS, 15_000),
+    wsBasePath: normalizeWsBasePath(process.env.WS_BASE_PATH || '/ws'),
+    wsMaxBufferedAmountBytes: parsePositiveInt(
+      process.env.WS_MAX_BUFFERED_AMOUNT_BYTES,
+      16_777_216,
+    ),
+    wsMaxPayloadBytes: parsePositiveInt(process.env.WS_MAX_PAYLOAD_BYTES, 16_777_216),
+  };
+}

package/src/server/create-app-server.js

@@ -0,0 +1,143 @@
+import { createServer } from 'http';
+
+import { loadConfig } from './config/env.js';
+import { createAuthService } from './auth/create-auth-service.js';
+import { BacklinkIndex } from './domain/backlink-index.js';
+import { CollaborationDocumentStore } from './domain/collaboration/collaboration-document-store.js';
+import { CollaborationRoom } from './domain/collaboration/collaboration-room.js';
+import { GitService } from './infrastructure/git/git-service.js';
+import { PlantUmlRenderer } from './infrastructure/plantuml/plantuml-renderer.js';
+import { RoomRegistry } from './domain/collaboration/room-registry.js';
+import { createRequestHandler } from './infrastructure/http/create-request-handler.js';
+import { VaultFileStore } from './infrastructure/persistence/vault-file-store.js';
+import { attachCollaborationGateway } from './infrastructure/websocket/attach-collaboration-gateway.js';
+
+function getDisplayHost(host) {
+  return host === '127.0.0.1' ? 'localhost' : host;
+}
+
+function closeHttpServer(httpServer) {
+  return new Promise((resolve, reject) => {
+    httpServer.close((error) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+
+      resolve();
+    });
+
+    if (typeof httpServer.closeIdleConnections === 'function') {
+      httpServer.closeIdleConnections();
+    }
+  });
+}
+
+export function createAppServer(config = loadConfig()) {
+  const authService = createAuthService(config);
+  const vaultFileStore = new VaultFileStore({ vaultDir: config.vaultDir });
+  const backlinkIndex = new BacklinkIndex({ vaultFileStore });
+  const plantUmlRenderer = new PlantUmlRenderer({
+    serverUrl: config.plantumlServerUrl,
+  });
+  const gitService = new GitService({
+    commandEnv: config.git?.commandEnv,
+    enabled: config.gitEnabled,
+    vaultDir: config.vaultDir,
+  });
+  const roomRegistry = new RoomRegistry({
+    createRoom: ({ name, onEmpty }) => new CollaborationRoom({
+      documentStore: new CollaborationDocumentStore({
+        backlinkIndex: name === '__lobby__' ? null : backlinkIndex,
+        name,
+        vaultFileStore: name === '__lobby__' ? null : vaultFileStore,
+      }),
+      idleGraceMs: config.wsRoomIdleGraceMs,
+      maxBufferedAmountBytes: config.wsMaxBufferedAmountBytes,
+      name,
+      onEmpty,
+    }),
+  });
+  const requestHandler = createRequestHandler(
+    config,
+    authService,
+    vaultFileStore,
+    backlinkIndex,
+    roomRegistry,
+    plantUmlRenderer,
+    gitService,
+  );
+  const httpServer = createServer((req, res) => {
+    requestHandler(req, res).catch((error) => {
+      console.error('[http] Unhandled request error:', error.message);
+      if (!res.headersSent) {
+        res.writeHead(500, { 'Content-Type': 'text/plain; charset=utf-8' });
+      }
+      res.end('Internal Server Error');
+    });
+  });
+  httpServer.headersTimeout = config.httpHeadersTimeoutMs;
+  httpServer.keepAliveTimeout = config.httpKeepAliveTimeoutMs;
+  httpServer.requestTimeout = config.httpRequestTimeoutMs;
+  const collaborationGateway = attachCollaborationGateway({
+    authService,
+    basePath: config.basePath,
+    heartbeatIntervalMs: config.wsHeartbeatIntervalMs,
+    maxPayload: config.wsMaxPayloadBytes,
+    httpServer,
+    roomRegistry,
+    wsBasePath: config.wsBasePath,
+  });
+
+  let shutdownPromise = null;
+  let vaultFileCount = 0;
+
+  async function listen() {
+    vaultFileCount = await vaultFileStore.countVaultFiles();
+    await backlinkIndex.build();
+
+    return new Promise((resolve, reject) => {
+      httpServer.once('error', reject);
+      httpServer.listen(config.port, config.host, () => {
+        httpServer.off('error', reject);
+        const address = httpServer.address();
+        resolve({
+          address,
+          host: getDisplayHost(config.host),
+          port: typeof address === 'object' && address ? address.port : config.port,
+          wsPath: `${config.basePath || ''}${config.wsBasePath}/:file`,
+        });
+      });
+    });
+  }
+
+  async function close() {
+    if (shutdownPromise) {
+      return shutdownPromise;
+    }
+
+    shutdownPromise = (async () => {
+      await collaborationGateway.close();
+      await roomRegistry.reset();
+      await Promise.all([
+        closeHttpServer(httpServer),
+        config.git?.cleanup?.(),
+      ]);
+    })().then(() => undefined);
+
+    return shutdownPromise;
+  }
+
+  return {
+    close,
+    collaborationGateway,
+    config,
+    httpServer,
+    listen,
+    roomRegistry,
+    authService,
+    gitService,
+    vaultFileStore,
+    get vaultFileCount() { return vaultFileCount; },
+  };
+}

package/src/server/domain/backlink-index.js

@@ -0,0 +1,291 @@
+/**
+ * BacklinkIndex — an in-memory inverted index that tracks which files link
+ * to which other files via [[wiki links]].
+ *
+ * Maintains two maps:
+ *   forward: sourcePath → Set<targetPath>    (outgoing links from a file)
+ *   reverse: targetPath → Set<sourcePath>    (incoming links to a file — backlinks)
+ *
+ * The index is built from the vault at startup, then kept in sync
+ * incrementally whenever a file is persisted, created, deleted, or renamed.
+ */
+
+import { createWikiTargetIndex, resolveWikiTargetWithIndex } from '../../domain/wiki-link-resolver.js';
+
+const WIKI_LINK_RE = /\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/g;
+
+export class BacklinkIndex {
+  constructor({ vaultFileStore }) {
+    this.vaultFileStore = vaultFileStore;
+    /** @type {Map<string, Set<string>>} sourcePath → set of resolved target paths */
+    this.forward = new Map();
+    /** @type {Map<string, Set<string>>} targetPath → set of source paths */
+    this.reverse = new Map();
+    /** @type {Map<string, Map<string, string[]>>} sourcePath → targetPath → contexts[] */
+    this.contextsBySource = new Map();
+    /** @type {string[]} cached flat file list for link resolution */
+    this._fileList = [];
+    /** @type {Set<string>} file path membership set */
+    this._fileSet = new Set();
+    this._wikiTargetIndex = createWikiTargetIndex(this._fileList);
+    this._built = false;
+  }
+
+  /**
+   * Build the full index by scanning every markdown file in the vault.
+   * Called once at server startup.
+   */
+  async build() {
+    this.forward.clear();
+    this.reverse.clear();
+    this.contextsBySource.clear();
+
+    const tree = await this.vaultFileStore.tree();
+    this._fileList = flattenTree(tree);
+    this._fileSet = new Set(this._fileList);
+    this._refreshWikiTargetIndex();
+
+    for (const filePath of this._fileList) {
+      const content = await this.vaultFileStore.readMarkdownFile(filePath);
+      if (content !== null) {
+        this._indexFile(filePath, content);
+      }
+    }
+
+    this._built = true;
+    console.log(`[backlinks] Index built: ${this._fileList.length} files, ${this.reverse.size} targets with backlinks`);
+  }
+
+  /**
+   * Incrementally update the index when a file's content changes.
+   * Call this after every persist / write.
+   */
+  updateFile(filePath, content) {
+    // Remove old forward links for this file
+    this._removeForwardLinks(filePath);
+
+    if (!this._fileSet.has(filePath)) {
+      this._fileSet.add(filePath);
+      this._fileList.push(filePath);
+      this._refreshWikiTargetIndex();
+    }
+
+    // Re-index with new content
+    this._indexFile(filePath, content);
+  }
+
+  /**
+   * Handle file creation — add to file list and index its content.
+   */
+  onFileCreated(filePath, content = '') {
+    if (!this._fileSet.has(filePath)) {
+      this._fileSet.add(filePath);
+      this._fileList.push(filePath);
+      this._refreshWikiTargetIndex();
+    }
+
+    if (content) {
+      this._indexFile(filePath, content);
+    }
+  }
+
+  /**
+   * Handle file deletion — remove from file list and all index entries.
+   */
+  onFileDeleted(filePath) {
+    this._removeForwardLinks(filePath);
+    if (this._fileSet.delete(filePath)) {
+      this._fileList = this._fileList.filter((f) => f !== filePath);
+      this._refreshWikiTargetIndex();
+    }
+
+    // Also remove this file as a reverse entry (no one can link to a deleted file)
+    this.reverse.delete(filePath);
+  }
+
+  /**
+   * Handle file rename — re-map all index entries from oldPath to newPath.
+   */
+  onFileRenamed(oldPath, newPath) {
+    // Move cached contexts for the renamed source file.
+    if (this.contextsBySource.has(oldPath)) {
+      const sourceContexts = this.contextsBySource.get(oldPath);
+      this.contextsBySource.delete(oldPath);
+      this.contextsBySource.set(newPath, sourceContexts);
+    }
+
+    // Move forward links
+    const oldForward = this.forward.get(oldPath);
+    if (oldForward) {
+      this.forward.delete(oldPath);
+      this.forward.set(newPath, oldForward);
+
+      // Update reverse entries: replace oldPath with newPath in all targets
+      for (const targetPath of oldForward) {
+        const sources = this.reverse.get(targetPath);
+        if (sources) {
+          sources.delete(oldPath);
+          sources.add(newPath);
+        }
+      }
+    }
+
+    // Move reverse links (files that linked to oldPath now link to newPath)
+    const oldReverse = this.reverse.get(oldPath);
+    if (oldReverse) {
+      this.reverse.delete(oldPath);
+      const mergedReverse = this.reverse.has(newPath)
+        ? new Set([...this.reverse.get(newPath), ...oldReverse])
+        : oldReverse;
+      this.reverse.set(newPath, mergedReverse);
+
+      // Update forward entries: replace oldPath with newPath in all sources
+      for (const sourcePath of oldReverse) {
+        const targets = this.forward.get(sourcePath);
+        if (targets) {
+          targets.delete(oldPath);
+          targets.add(newPath);
+        }
+
+        const sourceContexts = this.contextsBySource.get(sourcePath);
+        if (sourceContexts?.has(oldPath)) {
+          const previous = sourceContexts.get(newPath) ?? [];
+          sourceContexts.set(newPath, [...previous, ...sourceContexts.get(oldPath)]);
+          sourceContexts.delete(oldPath);
+        }
+      }
+    }
+
+    // Update file list
+    if (this._fileSet.delete(oldPath)) {
+      this._fileSet.add(newPath);
+      this._fileList = this._fileList.map((f) => (f === oldPath ? newPath : f));
+      this._refreshWikiTargetIndex();
+    }
+  }
+
+  /**
+   * Get all backlinks for a file, with context snippets.
+   * Returns: [{ file: string, contexts: string[] }]
+   */
+  async getBacklinks(filePath) {
+    const sources = this.reverse.get(filePath);
+    if (!sources || sources.size === 0) {
+      return [];
+    }
+
+    const results = [];
+
+    for (const sourcePath of sources) {
+      const sourceContexts = this.contextsBySource.get(sourcePath);
+      const relevantContexts = sourceContexts?.get(filePath) ?? [];
+
+      if (relevantContexts.length > 0) {
+        results.push({
+          file: sourcePath,
+          contexts: [...relevantContexts],
+        });
+      }
+    }
+
+    // Sort by filename for stable ordering
+    results.sort((a, b) => a.file.localeCompare(b.file));
+    return results;
+  }
+
+  /**
+   * Get the count of backlinks for a file (cheap — no I/O).
+   */
+  getBacklinkCount(filePath) {
+    return this.reverse.get(filePath)?.size ?? 0;
+  }
+
+  // --- Private methods ---
+
+  _indexFile(filePath, content) {
+    const resolvedTargets = new Set();
+    const contextsByTarget = new Map();
+    const lines = content.split('\n');
+
+    for (const line of lines) {
+      WIKI_LINK_RE.lastIndex = 0;
+      let match;
+      while ((match = WIKI_LINK_RE.exec(line)) !== null) {
+        const target = match[1].trim();
+        if (!target) {
+          continue;
+        }
+
+        const resolved = this._resolveTarget(target);
+        if (!resolved || resolved === filePath) {
+          continue;
+        }
+
+        resolvedTargets.add(resolved);
+
+        if (!contextsByTarget.has(resolved)) {
+          contextsByTarget.set(resolved, []);
+        }
+        contextsByTarget.get(resolved).push(line.trim());
+      }
+    }
+
+    this.contextsBySource.delete(filePath);
+
+    if (resolvedTargets.size > 0) {
+      this.contextsBySource.set(filePath, contextsByTarget);
+      this.forward.set(filePath, resolvedTargets);
+
+      for (const targetPath of resolvedTargets) {
+        if (!this.reverse.has(targetPath)) {
+          this.reverse.set(targetPath, new Set());
+        }
+        this.reverse.get(targetPath).add(filePath);
+      }
+    }
+  }
+
+  _removeForwardLinks(filePath) {
+    this.contextsBySource.delete(filePath);
+
+    const oldTargets = this.forward.get(filePath);
+    if (!oldTargets) return;
+
+    for (const targetPath of oldTargets) {
+      const sources = this.reverse.get(targetPath);
+      if (sources) {
+        sources.delete(filePath);
+        if (sources.size === 0) {
+          this.reverse.delete(targetPath);
+        }
+      }
+    }
+
+    this.forward.delete(filePath);
+  }
+
+  /**
+   * Resolve a wiki-link target string to a vault file path.
+   * Same logic as the client's resolveWikiTarget.
+   */
+  _resolveTarget(target) {
+    return resolveWikiTargetWithIndex(target, this._wikiTargetIndex);
+  }
+
+  _refreshWikiTargetIndex() {
+    this._wikiTargetIndex = createWikiTargetIndex(this._fileList);
+  }
+}
+
+/** Flatten a vault tree into an array of file paths. */
+function flattenTree(nodes) {
+  const files = [];
+  for (const node of nodes) {
+    if (node.type === 'file') {
+      files.push(node.path);
+    } else if (node.children) {
+      files.push(...flattenTree(node.children));
+    }
+  }
+  return files;
+}