collabmd 0.1.20 → 0.1.23

package/src/server/config/env.js

@@ -3,6 +3,7 @@ import { fileURLToPath } from 'url';
 
 import {
   AUTH_STRATEGY_NONE,
+  AUTH_STRATEGY_OIDC,
   AUTH_STRATEGY_PASSWORD,
   SUPPORTED_AUTH_STRATEGIES,
   createRandomAuthPassword,
@@ -54,6 +55,30 @@ function normalizeWsBasePath(basePath) {
   return normalizeRoutePath(basePath, '/ws');
 }
 
+function normalizePublicBaseUrl(rawValue) {
+  const normalized = normalizeOptionalString(rawValue);
+  if (!normalized) {
+    return '';
+  }
+
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(normalized);
+  } catch {
+    throw new Error('PUBLIC_BASE_URL must be an absolute URL.');
+  }
+
+  if (parsedUrl.protocol !== 'https:' && parsedUrl.hostname !== 'localhost' && parsedUrl.hostname !== '127.0.0.1') {
+    throw new Error('PUBLIC_BASE_URL must use https unless it points to localhost.');
+  }
+
+  if ((parsedUrl.pathname && parsedUrl.pathname !== '/') || parsedUrl.search || parsedUrl.hash) {
+    throw new Error('PUBLIC_BASE_URL must not include a path, query string, or hash.');
+  }
+
+  return parsedUrl.origin;
+}
+
 function normalizeAuthStrategy(rawStrategy) {
   const normalized = String(rawStrategy ?? AUTH_STRATEGY_NONE).trim().toLowerCase();
   if (!SUPPORTED_AUTH_STRATEGIES.has(normalized)) {
@@ -65,8 +90,42 @@ function normalizeAuthStrategy(rawStrategy) {
   return normalized;
 }
 
+function normalizeCsvList(value) {
+  if (Array.isArray(value)) {
+    return value
+      .map((entry) => String(entry ?? '').trim())
+      .filter(Boolean);
+  }
+
+  return String(value ?? '')
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+function normalizeEmailAllowlist(value) {
+  return normalizeCsvList(value)
+    .map((entry) => entry.toLowerCase());
+}
+
+function normalizeDomainAllowlist(value) {
+  return normalizeCsvList(value)
+    .map((entry) => entry.replace(/^@+/, '').toLowerCase())
+    .filter(Boolean);
+}
+
 const projectRoot = resolve(fileURLToPath(new URL('../../../', import.meta.url)));
 
+export function resolveConfiguredVaultDir(overrides = {}, env = process.env) {
+  return overrides.vaultDir
+    || env.COLLABMD_VAULT_DIR
+    || resolve(projectRoot, 'data/vault');
+}
+
+export function resolveCliVaultDir(positionals = [], env = process.env) {
+  return resolve(positionals[0] || env.COLLABMD_VAULT_DIR || '.');
+}
+
 function getDefaultHost(nodeEnv) {
   return nodeEnv === 'production' ? '0.0.0.0' : '127.0.0.1';
 }
@@ -134,11 +193,63 @@ function loadGitConfig(overrides = {}) {
   };
 }
 
+function loadOidcConfig(overrides = {}, { basePath = '' } = {}) {
+  const clientId = normalizeOptionalString(
+    overrides.clientId
+    ?? process.env.AUTH_OIDC_CLIENT_ID,
+  );
+  const clientSecret = normalizeOptionalString(
+    overrides.clientSecret
+    ?? process.env.AUTH_OIDC_CLIENT_SECRET,
+  );
+  const publicBaseUrl = normalizePublicBaseUrl(
+    overrides.publicBaseUrl
+    ?? process.env.PUBLIC_BASE_URL,
+  );
+  const issuer = normalizeOptionalString(
+    overrides.issuer
+    ?? process.env.AUTH_OIDC_ISSUER_URL,
+  ) || 'https://accounts.google.com';
+  const flowCookieName = normalizeOptionalString(
+    overrides.flowCookieName
+    ?? process.env.AUTH_OIDC_FLOW_COOKIE_NAME,
+  ) || 'collabmd_auth_flow';
+  const allowedEmails = normalizeEmailAllowlist(
+    overrides.allowedEmails
+    ?? process.env.AUTH_OIDC_ALLOWED_EMAILS,
+  );
+  const allowedDomains = normalizeDomainAllowlist(
+    overrides.allowedDomains
+    ?? process.env.AUTH_OIDC_ALLOWED_DOMAINS,
+  );
+
+  if (!publicBaseUrl) {
+    throw new Error('OIDC auth requires PUBLIC_BASE_URL.');
+  }
+  if (!clientId) {
+    throw new Error('OIDC auth requires AUTH_OIDC_CLIENT_ID.');
+  }
+  if (!clientSecret) {
+    throw new Error('OIDC auth requires AUTH_OIDC_CLIENT_SECRET.');
+  }
+
+  return {
+    allowedDomains,
+    allowedEmails,
+    callbackUrl: `${publicBaseUrl}${basePath}/api/auth/oidc/callback`,
+    clientId,
+    clientSecret,
+    flowCookieName,
+    issuer,
+    provider: 'google',
+    publicBaseUrl,
+  };
+}
+
 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 vaultDir = resolveConfiguredVaultDir(overrides);
+  const basePath = normalizeAppBasePath(process.env.BASE_PATH || '');
   const authOverrides = overrides.auth ?? {};
   const authStrategy = normalizeAuthStrategy(
     authOverrides.strategy
@@ -150,18 +261,22 @@ export function loadConfig(overrides = {}) {
   const password = authStrategy === AUTH_STRATEGY_PASSWORD
     ? (authOverrides.password || process.env.AUTH_PASSWORD || createRandomAuthPassword())
     : '';
+  const oidc = authStrategy === AUTH_STRATEGY_OIDC
+    ? loadOidcConfig(authOverrides.oidc, { basePath })
+    : null;
   const git = loadGitConfig(overrides.git);
 
   return {
     auth: {
       generatedPassword: passwordWasGenerated ? password : '',
+      oidc,
       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 || ''),
+    basePath,
     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),
@@ -174,8 +289,9 @@ export function loadConfig(overrides = {}) {
     publicDir: resolve(projectRoot, 'public'),
     vaultDir,
     publicWsBaseUrl: process.env.PUBLIC_WS_BASE_URL || '',
+    testWsRoomHydrateDelayMs: parsePositiveInt(process.env.TEST_WS_ROOM_HYDRATE_DELAY_MS, 0),
     wsHeartbeatIntervalMs: parsePositiveInt(process.env.WS_HEARTBEAT_INTERVAL_MS, 30_000),
-    wsRoomIdleGraceMs: parsePositiveInt(process.env.WS_ROOM_IDLE_GRACE_MS, 15_000),
+    wsRoomIdleGraceMs: parsePositiveInt(process.env.WS_ROOM_IDLE_GRACE_MS, 60_000),
     wsBasePath: normalizeWsBasePath(process.env.WS_BASE_PATH || '/ws'),
     wsMaxBufferedAmountBytes: parsePositiveInt(
       process.env.WS_MAX_BUFFERED_AMOUNT_BYTES,

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

@@ -11,6 +11,9 @@ 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';
+import { WORKSPACE_ROOM_NAME } from '../domain/workspace-room.js';
+import { FileSystemSyncService } from './infrastructure/workspace/file-system-sync-service.js';
+import { WorkspaceMutationCoordinator } from './infrastructure/workspace/workspace-mutation-coordinator.js';
 
 function getDisplayHost(host) {
   return host === '127.0.0.1' ? 'localhost' : host;
@@ -45,18 +48,43 @@ export function createAppServer(config = loadConfig()) {
     enabled: config.gitEnabled,
     vaultDir: config.vaultDir,
   });
+  const testControls = {
+    wsRoomHydrateDelayMs: Math.max(0, Number(config.testWsRoomHydrateDelayMs || 0)),
+  };
+  let workspaceMutationCoordinator = null;
   const roomRegistry = new RoomRegistry({
-    createRoom: ({ name, onEmpty }) => new CollaborationRoom({
-      documentStore: new CollaborationDocumentStore({
-        backlinkIndex: name === '__lobby__' ? null : backlinkIndex,
+    createRoom: ({ name, onEmpty }) => {
+      const room = new CollaborationRoom({
+        documentStore: new CollaborationDocumentStore({
+          backlinkIndex: name === '__lobby__' || name === WORKSPACE_ROOM_NAME ? null : backlinkIndex,
+          name,
+          vaultFileStore: name === '__lobby__' || name === WORKSPACE_ROOM_NAME ? null : vaultFileStore,
+        }),
+        getHydrateDelayMs: () => testControls.wsRoomHydrateDelayMs,
+        idleGraceMs: config.wsRoomIdleGraceMs,
+        maxBufferedAmountBytes: config.wsMaxBufferedAmountBytes,
         name,
-        vaultFileStore: name === '__lobby__' ? null : vaultFileStore,
-      }),
-      idleGraceMs: config.wsRoomIdleGraceMs,
-      maxBufferedAmountBytes: config.wsMaxBufferedAmountBytes,
-      name,
-      onEmpty,
-    }),
+        onEmpty,
+      });
+
+      if (name === WORKSPACE_ROOM_NAME && workspaceMutationCoordinator?.workspaceState) {
+        room.replaceWorkspaceEntries(workspaceMutationCoordinator.workspaceState.entries, {
+          generatedAt: workspaceMutationCoordinator.workspaceState.scannedAt,
+        });
+      }
+
+      return room;
+    },
+  });
+  workspaceMutationCoordinator = new WorkspaceMutationCoordinator({
+    backlinkIndex,
+    roomRegistry,
+    vaultFileStore,
+  });
+  vaultFileStore.setManagedWriteTracker(workspaceMutationCoordinator);
+  const fileSystemSyncService = new FileSystemSyncService({
+    mutationCoordinator: workspaceMutationCoordinator,
+    vaultFileStore,
   });
   const requestHandler = createRequestHandler(
     config,
@@ -66,6 +94,9 @@ export function createAppServer(config = loadConfig()) {
     roomRegistry,
     plantUmlRenderer,
     gitService,
+    testControls,
+    workspaceMutationCoordinator,
+    fileSystemSyncService,
   );
   const httpServer = createServer((req, res) => {
     requestHandler(req, res).catch((error) => {
@@ -95,6 +126,8 @@ export function createAppServer(config = loadConfig()) {
   async function listen() {
     vaultFileCount = await vaultFileStore.countVaultFiles();
     await backlinkIndex.build();
+    await workspaceMutationCoordinator.initialize();
+    await fileSystemSyncService.start();
 
     return new Promise((resolve, reject) => {
       httpServer.once('error', reject);
@@ -118,6 +151,7 @@ export function createAppServer(config = loadConfig()) {
 
     shutdownPromise = (async () => {
       await collaborationGateway.close();
+      await fileSystemSyncService.close();
       await roomRegistry.reset();
       await Promise.all([
         closeHttpServer(httpServer),
@@ -135,8 +169,13 @@ export function createAppServer(config = loadConfig()) {
     httpServer,
     listen,
     roomRegistry,
+    workspaceMutationCoordinator,
     authService,
+    fileSystemSyncService,
     gitService,
+    setTestHydrateDelayMs(delayMs = 0) {
+      testControls.wsRoomHydrateDelayMs = Math.max(0, Number(delayMs) || 0);
+    },
     vaultFileStore,
     get vaultFileCount() { return vaultFileCount; },
   };

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

@@ -14,9 +14,27 @@ import { createWikiTargetIndex, resolveWikiTargetWithIndex } from '../../domain/
 
 const WIKI_LINK_RE = /\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/g;
 
+function createDeferred() {
+  let resolve;
+  let reject;
+  const promise = new Promise((nextResolve, nextReject) => {
+    resolve = nextResolve;
+    reject = nextReject;
+  });
+  return { promise, reject, resolve };
+}
+
 export class BacklinkIndex {
-  constructor({ vaultFileStore }) {
+  constructor({
+    rebuildDelayMs = 150,
+    setTimeoutFn = setTimeout,
+    clearTimeoutFn = clearTimeout,
+    vaultFileStore,
+  }) {
     this.vaultFileStore = vaultFileStore;
+    this.rebuildDelayMs = rebuildDelayMs;
+    this.setTimeoutFn = setTimeoutFn;
+    this.clearTimeoutFn = clearTimeoutFn;
     /** @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 */
@@ -29,6 +47,11 @@ export class BacklinkIndex {
     this._fileSet = new Set();
     this._wikiTargetIndex = createWikiTargetIndex(this._fileList);
     this._built = false;
+    this._requestedBuildVersion = 0;
+    this._completedBuildVersion = 0;
+    this._buildPromise = null;
+    this._scheduledBuildTimer = null;
+    this._scheduledBuildDeferred = null;
   }
 
   /**
@@ -36,6 +59,74 @@ export class BacklinkIndex {
    * Called once at server startup.
    */
   async build() {
+    this._requestedBuildVersion += 1;
+    return this.flushScheduledBuild();
+  }
+
+  scheduleBuild({ delayMs = this.rebuildDelayMs } = {}) {
+    this._requestedBuildVersion += 1;
+    if (!this._scheduledBuildDeferred) {
+      this._scheduledBuildDeferred = createDeferred();
+    }
+
+    if (this._scheduledBuildTimer) {
+      this.clearTimeoutFn(this._scheduledBuildTimer);
+    }
+
+    this._scheduledBuildTimer = this.setTimeoutFn(() => {
+      this._scheduledBuildTimer = null;
+      const deferred = this._scheduledBuildDeferred;
+      this._scheduledBuildDeferred = null;
+      this._ensureBuiltToRequestedVersion()
+        .then(() => deferred?.resolve())
+        .catch((error) => deferred?.reject(error));
+    }, delayMs);
+    this._scheduledBuildTimer.unref?.();
+
+    return this._scheduledBuildDeferred.promise;
+  }
+
+  async flushScheduledBuild() {
+    if (this._scheduledBuildTimer) {
+      this.clearTimeoutFn(this._scheduledBuildTimer);
+      this._scheduledBuildTimer = null;
+    }
+
+    const deferred = this._scheduledBuildDeferred;
+    this._scheduledBuildDeferred = null;
+
+    try {
+      await this._ensureBuiltToRequestedVersion();
+      deferred?.resolve();
+    } catch (error) {
+      deferred?.reject(error);
+      throw error;
+    }
+  }
+
+  async _ensureBuiltToRequestedVersion() {
+    while (this._completedBuildVersion < this._requestedBuildVersion) {
+      await this._runSingleBuild();
+    }
+  }
+
+  async _runSingleBuild() {
+    if (this._buildPromise) {
+      return this._buildPromise;
+    }
+
+    const targetVersion = this._requestedBuildVersion;
+    this._buildPromise = (async () => {
+      await this._performBuild();
+      this._completedBuildVersion = Math.max(this._completedBuildVersion, targetVersion);
+    })().finally(() => {
+      this._buildPromise = null;
+    });
+
+    return this._buildPromise;
+  }
+
+  async _performBuild() {
     this.forward.clear();
     this.reverse.clear();
     this.contextsBySource.clear();
@@ -169,6 +260,8 @@ export class BacklinkIndex {
    * Returns: [{ file: string, contexts: string[] }]
    */
   async getBacklinks(filePath) {
+    await this.flushScheduledBuild();
+
     const sources = this.reverse.get(filePath);
     if (!sources || sources.size === 0) {
       return [];