collabmd 0.1.21 → 0.1.25

package/src/server/config/env.js

@@ -3,11 +3,13 @@ import { fileURLToPath } from 'url';
 
 import {
   AUTH_STRATEGY_NONE,
+  AUTH_STRATEGY_OIDC,
   AUTH_STRATEGY_PASSWORD,
   SUPPORTED_AUTH_STRATEGIES,
   createRandomAuthPassword,
   createRandomSessionSecret,
 } from '../auth/create-auth-service.js';
+import { loadBuildInfo } from './build-info.js';
 
 function parsePositiveInt(rawValue, fallbackValue) {
   const parsed = Number.parseInt(rawValue ?? '', 10);
@@ -54,6 +56,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 +91,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 +194,64 @@ 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 publicDir = resolve(projectRoot, 'dist/client');
   const authOverrides = overrides.auth ?? {};
   const authStrategy = normalizeAuthStrategy(
     authOverrides.strategy
@@ -150,18 +263,28 @@ 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);
+  const build = loadBuildInfo({
+    explicitBuildId: process.env.COLLABMD_BUILD_ID,
+    projectRoot,
+    publicDir,
+  });
 
   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,
+    build,
     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),
@@ -171,11 +294,12 @@ export function loadConfig(overrides = {}) {
     port: parsePort(process.env.PORT, 1234),
     nodeEnv,
     plantumlServerUrl: process.env.PLANTUML_SERVER_URL || 'https://www.plantuml.com/plantuml',
-    publicDir: resolve(projectRoot, 'public'),
+    publicDir,
     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

@@ -48,6 +48,9 @@ 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 }) => {
@@ -57,6 +60,7 @@ export function createAppServer(config = loadConfig()) {
           name,
           vaultFileStore: name === '__lobby__' || name === WORKSPACE_ROOM_NAME ? null : vaultFileStore,
         }),
+        getHydrateDelayMs: () => testControls.wsRoomHydrateDelayMs,
         idleGraceMs: config.wsRoomIdleGraceMs,
         maxBufferedAmountBytes: config.wsMaxBufferedAmountBytes,
         name,
@@ -90,6 +94,7 @@ export function createAppServer(config = loadConfig()) {
     roomRegistry,
     plantUmlRenderer,
     gitService,
+    testControls,
     workspaceMutationCoordinator,
     fileSystemSyncService,
   );
@@ -168,6 +173,9 @@ export function createAppServer(config = loadConfig()) {
     authService,
     fileSystemSyncService,
     gitService,
+    setTestHydrateDelayMs(delayMs = 0) {
+      testControls.wsRoomHydrateDelayMs = Math.max(0, Number(delayMs) || 0);
+    },
     vaultFileStore,
     get vaultFileCount() { return vaultFileCount; },
   };

package/src/server/domain/collaboration/collaboration-room.js

@@ -126,6 +126,7 @@ function computeTextReplacement(currentContent, nextContent) {
 export class CollaborationRoom {
   constructor({
     documentStore = null,
+    getHydrateDelayMs = null,
     name,
     idleGraceMs = 0,
     maxBufferedAmountBytes,
@@ -141,6 +142,7 @@ export class CollaborationRoom {
       name,
       vaultFileStore,
     });
+    this.getHydrateDelayMs = getHydrateDelayMs;
     this.onEmpty = onEmpty;
     this.doc = new Y.Doc({ gc: true });
     this.awareness = new awarenessProtocol.Awareness(this.doc);
@@ -152,6 +154,12 @@ export class CollaborationRoom {
     this.destroyed = false;
     this.cachedInitialSyncMessage = null;
     this.activePersistPromise = null;
+    this.debugMetrics = {
+      hydrateCount: 0,
+      initialSyncCount: 0,
+      lastHydrate: null,
+      lastInitialSyncAt: 0,
+    };
     this.persistence = new RoomPersistenceController({
       idleGraceMs: this.idleGraceMs,
       onDestroy: () => {
@@ -173,64 +181,96 @@ export class CollaborationRoom {
 
     if (!this.hydratePromise) {
       this.hydratePromise = (async () => {
-        if (this.documentStore?.hasPersistence()) {
-          const snapshot = await this.documentStore.readSnapshot();
-          if (snapshot) {
-            try {
-              if (isExcalidrawRoom(this.name)) {
-                const validationDoc = new Y.Doc({ gc: true });
-                try {
-                  Y.applyUpdate(validationDoc, snapshot, 'hydrate');
-                  if (!this.ensureStructuredExcalidrawState(validationDoc)) {
-                    throw new Error('snapshot did not contain a valid structured Excalidraw scene');
-                  }
+        const startedAt = Date.now();
+        let hydrateSource = 'empty';
+        let snapshotExists = false;
+        let snapshotValid = false;
+        let commentThreadCount = 0;
+        const hydrateDelayMs = Math.max(0, Number(this.getHydrateDelayMs?.() || 0));
+
+        try {
+          if (hydrateDelayMs > 0) {
+            await new Promise((resolve) => setTimeout(resolve, hydrateDelayMs));
+          }
 
-                  Y.applyUpdate(this.doc, Y.encodeStateAsUpdate(validationDoc), 'hydrate');
-                } finally {
-                  validationDoc.destroy();
+          if (this.documentStore?.hasPersistence()) {
+            const snapshot = await this.documentStore.readSnapshot();
+            if (snapshot) {
+              snapshotExists = true;
+              try {
+                if (isExcalidrawRoom(this.name)) {
+                  const validationDoc = new Y.Doc({ gc: true });
+                  try {
+                    Y.applyUpdate(validationDoc, snapshot, 'hydrate');
+                    if (!this.ensureStructuredExcalidrawState(validationDoc)) {
+                      throw new Error('snapshot did not contain a valid structured Excalidraw scene');
+                    }
+
+                    Y.applyUpdate(this.doc, Y.encodeStateAsUpdate(validationDoc), 'hydrate');
+                  } finally {
+                    validationDoc.destroy();
+                  }
+                } else {
+                  Y.applyUpdate(this.doc, snapshot, 'hydrate');
                 }
-              } else {
-                Y.applyUpdate(this.doc, snapshot, 'hydrate');
-              }
 
-              this.hydrated = true;
-              return;
-            } catch (error) {
-              console.warn(
-                `[room:${this.name}] Discarding invalid collaboration snapshot: ${error.message}`,
-              );
-              await this.documentStore.deleteSnapshot?.();
+                snapshotValid = true;
+                hydrateSource = 'snapshot';
+                this.hydrated = true;
+                return;
+              } catch (error) {
+                console.warn(
+                  `[room:${this.name}] Discarding invalid collaboration snapshot: ${error.message}`,
+                );
+                await this.documentStore.deleteSnapshot?.();
+              }
             }
-          }
 
-          const [content, commentThreads] = await Promise.all([
-            this.documentStore.readContent(),
-            this.documentStore.readCommentThreads(),
-          ]);
-          if (content !== null || commentThreads.length > 0) {
-            const ytext = this.doc.getText('codemirror');
-            const comments = this.doc.getArray('comments');
-            this.doc.transact(() => {
-              if (isExcalidrawRoom(this.name)) {
-                const parsedScene = tryParseExcalidrawSceneJson(content);
-                if (parsedScene) {
-                  migrateLegacyExcalidrawRoomData(this.doc, parsedScene);
+            const [content, commentThreads] = await Promise.all([
+              this.documentStore.readContent(),
+              this.documentStore.readCommentThreads(),
+            ]);
+            commentThreadCount = commentThreads.length;
+            if (content !== null || commentThreads.length > 0) {
+              hydrateSource = 'content';
+              const ytext = this.doc.getText('codemirror');
+              const comments = this.doc.getArray('comments');
+              this.doc.transact(() => {
+                if (isExcalidrawRoom(this.name)) {
+                  const parsedScene = tryParseExcalidrawSceneJson(content);
+                  if (parsedScene) {
+                    migrateLegacyExcalidrawRoomData(this.doc, parsedScene);
+                  } else if (content !== null) {
+                    ytext.insert(0, content);
+                  }
                 } else if (content !== null) {
                   ytext.insert(0, content);
                 }
-              } else if (content !== null) {
-                ytext.insert(0, content);
-              }
-              populateCommentThreads(comments, commentThreads);
-            }, 'hydrate');
+                populateCommentThreads(comments, commentThreads);
+              }, 'hydrate');
 
-            void this.documentStore.writeSnapshot(Y.encodeStateAsUpdate(this.doc)).catch((error) => {
-              console.error(`[room:${this.name}] Failed to prime collaboration snapshot: ${error.message}`);
-            });
+              void this.documentStore.writeSnapshot(Y.encodeStateAsUpdate(this.doc)).catch((error) => {
+                console.error(`[room:${this.name}] Failed to prime collaboration snapshot: ${error.message}`);
+              });
+            }
           }
-        }
 
-        this.hydrated = true;
+          this.hydrated = true;
+        } finally {
+          if (this.hydrated) {
+            this.debugMetrics.hydrateCount += 1;
+            this.debugMetrics.lastHydrate = {
+              commentThreadCount,
+              durationMs: Date.now() - startedAt,
+              snapshotExists,
+              snapshotValid,
+              source: hydrateSource,
+            };
+            console.info(
+              `[perf][room:${this.name}] hydrate durationMs=${this.debugMetrics.lastHydrate.durationMs} source=${this.debugMetrics.lastHydrate.source} snapshotExists=${this.debugMetrics.lastHydrate.snapshotExists} snapshotValid=${this.debugMetrics.lastHydrate.snapshotValid} commentThreads=${this.debugMetrics.lastHydrate.commentThreadCount}`,
+            );
+          }
+        }
       })().catch((error) => {
         this.hydratePromise = null;
         console.error(`[room:${this.name}] Failed to hydrate from disk: ${error.message}`);
@@ -479,6 +519,9 @@ export class CollaborationRoom {
   }
 
   sendInitialSync(ws) {
+    this.debugMetrics.initialSyncCount += 1;
+    this.debugMetrics.lastInitialSyncAt = Date.now();
+    console.info(`[perf][room:${this.name}] send-initial-sync count=${this.debugMetrics.initialSyncCount}`);
     return sendMessage.call(this, ws, this.getInitialSyncMessage(), this);
   }
 

package/src/server/index.js

@@ -60,7 +60,9 @@ server.listen().then(({ host, port, wsPath }) => {
   if (server.config.auth.strategy === 'password') {
     console.log(`  auth: password (${server.config.auth.password})`);
   } else if (server.config.auth.strategy === 'oidc') {
-    console.log('  auth: oidc (not implemented yet)');
+    console.log(`  auth: oidc (${server.config.auth.oidc.provider})`);
+    console.log(`  public: ${server.config.auth.oidc.publicBaseUrl}`);
+    console.log(`  callback: ${server.config.auth.oidc.callbackUrl}`);
   } else {
     console.log('  auth: none');
   }

package/src/server/infrastructure/git/command-runner.js

@@ -31,13 +31,14 @@ export class GitCommandRunner {
     }
   }
 
-  async execGit(args) {
+  async execGit(args, { env = null } = {}) {
     const result = await this.execFileImpl('git', ['-c', 'core.quotepath=false', ...args], {
       cwd: this.vaultDir,
       encoding: 'utf8',
       env: {
         ...process.env,
         ...(this.commandEnv ?? {}),
+        ...(env ?? {}),
       },
       maxBuffer: 5 * 1024 * 1024,
       timeout: 10_000,

package/src/server/infrastructure/git/git-service.js

@@ -2,12 +2,29 @@ import { createGitRequestError } from './errors.js';
 import { normalizeRelativeGitPath } from './path-utils.js';
 import { GitCommandRunner } from './command-runner.js';
 import { GitDiffService } from './diff-service.js';
+import { GitHistoryService } from './history-service.js';
 import { parseNameStatusOutput } from './parsers.js';
 import { createEmptyWorkspaceChange, createWorkspaceChange } from './responses.js';
 import { GitStatusService } from './status-service.js';
 import { GitUntrackedFileService } from './untracked-files.js';
 import { PullBackupStore } from '../persistence/pull-backup-store.js';
 
+function buildAuthorEnv(author = null) {
+  const name = String(author?.name ?? '').trim();
+  const email = String(author?.email ?? '').trim();
+
+  if (!name || !email) {
+    return null;
+  }
+
+  return {
+    GIT_AUTHOR_EMAIL: email,
+    GIT_AUTHOR_NAME: name,
+    GIT_COMMITTER_EMAIL: email,
+    GIT_COMMITTER_NAME: name,
+  };
+}
+
 export class GitService {
   constructor({
     commandEnv = null,
@@ -37,6 +54,11 @@ export class GitService {
       statusService: this.statusService,
       untrackedFileService: this.untrackedFileService,
     });
+    this.historyService = new GitHistoryService({
+      commandRunner: this.commandRunner,
+      maxInitialPatchBytes,
+      maxInitialPatchLines,
+    });
     this.pullBackupStore = new PullBackupStore({ vaultDir });
   }
 
@@ -51,6 +73,7 @@ export class GitService {
   invalidateStatusCache() {
     this.statusService.invalidate();
     this.diffService.invalidate();
+    this.historyService.invalidate();
   }
 
   async getStatus(options = {}) {
@@ -87,7 +110,7 @@ export class GitService {
     };
   }
 
-  async commitStaged({ message } = {}) {
+  async commitStaged({ author = null, message } = {}) {
     const normalizedMessage = String(message ?? '').trim();
     if (!normalizedMessage) {
       throw createGitRequestError(400, 'Missing commit message');
@@ -98,7 +121,9 @@ export class GitService {
       throw createGitRequestError(409, 'No staged changes to commit');
     }
 
-    await this.commandRunner.execGit(['commit', '-m', normalizedMessage]);
+    await this.commandRunner.execGit(['commit', '-m', normalizedMessage], {
+      env: buildAuthorEnv(author),
+    });
     const hash = (await this.commandRunner.execGit(['rev-parse', 'HEAD'])).trim();
     const shortHash = (await this.commandRunner.execGit(['rev-parse', '--short', 'HEAD'])).trim();
     this.invalidateStatusCache();
@@ -233,6 +258,27 @@ export class GitService {
     });
   }
 
+  async getHistory({ limit = 30, offset = 0 } = {}) {
+    return this.historyService.listHistory({ limit, offset });
+  }
+
+  async getFileHistory({ limit = 30, offset = 0, path } = {}) {
+    return this.historyService.listFileHistory({ limit, offset, path });
+  }
+
+  async getCommit({ allowLargePatch = false, hash, metaOnly = false, path = null } = {}) {
+    return this.historyService.getCommit({
+      allowLargePatch,
+      hash,
+      metaOnly,
+      path,
+    });
+  }
+
+  async getFileSnapshot({ hash, path } = {}) {
+    return this.historyService.getFileSnapshot({ hash, path });
+  }
+
   async getHeadRef() {
     try {
       const output = await this.commandRunner.execGit(['rev-parse', 'HEAD']);