@fyresmith/hive-server 2.3.1 → 2.4.0

package/lib/vaultManager.js

@@ -3,15 +3,26 @@ import { resolve, join, sep, extname, relative, dirname } from 'path';
 import { readFile, writeFile as fsWriteFile, rename, unlink, mkdir, stat, readdir } from 'fs/promises';
 import { existsSync } from 'fs';
 import chokidar from 'chokidar';
+import { getMetadataAllowlist, isMetadataPathAllowed } from './adapterRegistry.js';
 
 // ---------------------------------------------------------------------------
 // Deny / allow lists
 // ---------------------------------------------------------------------------
 
-const DENY_PREFIXES = ['.obsidian', 'Attachments', '.git'];
+const DENY_PREFIXES = ['.obsidian', '.hive-history', 'Attachments', '.git'];
 const DENY_FILES = ['.DS_Store', 'Thumbs.db'];
 // Keep synced content text-based to ensure hash/read/write semantics stay safe.
 const ALLOW_EXTS = new Set(['.md', '.canvas']);
+const METADATA_ALLOWLIST = new Set(getMetadataAllowlist());
+const HISTORY_DIR_NAME = '.hive-history';
+const HISTORY_FILES_DIR = 'files';
+const DEFAULT_HISTORY_LIMIT = 50;
+const MAX_HISTORY_LIMIT = 500;
+const HISTORY_RETENTION_PER_FILE = Math.max(
+  1,
+  parseInt(process.env.HIVE_HISTORY_RETENTION_PER_FILE ?? '200', 10) || 200,
+);
+const VERSION_ID_RE = /^\d{13}-[a-z0-9]+$/;
 
 // ---------------------------------------------------------------------------
 // Internals
@@ -34,6 +45,137 @@ function getVaultRoot() {
  */
 const manifestCache = new Map();
 
+function getHistoryRoot() {
+  const custom = process.env.HIVE_HISTORY_PATH?.trim();
+  if (custom) return resolve(custom);
+  return join(getVaultRoot(), HISTORY_DIR_NAME);
+}
+
+function encodeHistoryKey(relPath) {
+  return Buffer.from(relPath, 'utf-8').toString('base64url');
+}
+
+function historyDirForPath(relPath) {
+  return join(getHistoryRoot(), HISTORY_FILES_DIR, encodeHistoryKey(relPath));
+}
+
+function normalizeHistoryActor(actor) {
+  if (!actor || typeof actor !== 'object') return null;
+  const id = typeof actor.id === 'string' ? actor.id : null;
+  const username = typeof actor.username === 'string' ? actor.username : null;
+  if (!id && !username) return null;
+  return { id, username };
+}
+
+function normalizeHistorySource(source) {
+  return typeof source === 'string' && source.length > 0 ? source : null;
+}
+
+function clampLimit(value, fallback) {
+  if (!Number.isFinite(value)) return fallback;
+  const n = Math.trunc(value);
+  if (n < 1) return 1;
+  if (n > MAX_HISTORY_LIMIT) return MAX_HISTORY_LIMIT;
+  return n;
+}
+
+async function listHistoryFiles(relPath) {
+  const dir = historyDirForPath(relPath);
+  let names;
+  try {
+    names = await readdir(dir);
+  } catch (err) {
+    if (err?.code === 'ENOENT') return [];
+    throw err;
+  }
+
+  return names
+    .filter((name) => name.endsWith('.json'))
+    .sort();
+}
+
+async function readHistoryRecord(absPath) {
+  const raw = await readFile(absPath, 'utf-8');
+  return JSON.parse(raw);
+}
+
+function toHistoryMeta(record) {
+  return {
+    versionId: record.versionId,
+    relPath: record.relPath,
+    ts: record.ts,
+    action: record.action,
+    hash: record.hash,
+    size: record.size,
+    actor: record.actor ?? null,
+    source: record.source ?? null,
+  };
+}
+
+async function pruneHistory(relPath) {
+  const files = await listHistoryFiles(relPath);
+  if (files.length <= HISTORY_RETENTION_PER_FILE) return;
+
+  const dir = historyDirForPath(relPath);
+  const trimCount = files.length - HISTORY_RETENTION_PER_FILE;
+  for (const name of files.slice(0, trimCount)) {
+    try {
+      await unlink(join(dir, name));
+    } catch {
+      // Best effort; skip failures and continue pruning.
+    }
+  }
+}
+
+async function writeHistoryRecord(relPath, content, history = {}) {
+  if (!isAllowed(relPath)) return;
+  const action = typeof history.action === 'string' && history.action.length > 0
+    ? history.action
+    : 'write';
+
+  const dir = historyDirForPath(relPath);
+  await mkdir(dir, { recursive: true });
+
+  const hash = hashContent(content);
+  const existing = await listHistoryFiles(relPath);
+  if (existing.length > 0) {
+    const lastFile = existing[existing.length - 1];
+    try {
+      const latest = await readHistoryRecord(join(dir, lastFile));
+      if (latest?.hash === hash && latest?.action === action) {
+        return;
+      }
+    } catch {
+      // Ignore malformed historical entry and continue writing a new one.
+    }
+  }
+
+  const ts = Date.now();
+  const versionId = `${ts}-${Math.random().toString(36).slice(2, 10)}`;
+  const record = {
+    versionId,
+    relPath,
+    ts,
+    action,
+    hash,
+    size: Buffer.byteLength(content, 'utf-8'),
+    actor: normalizeHistoryActor(history.actor),
+    source: normalizeHistorySource(history.source),
+    content,
+  };
+
+  await fsWriteFile(join(dir, `${versionId}.json`), JSON.stringify(record), 'utf-8');
+  await pruneHistory(relPath);
+}
+
+async function writeHistoryRecordBestEffort(relPath, content, history = {}) {
+  try {
+    await writeHistoryRecord(relPath, content, history);
+  } catch (err) {
+    console.warn(`[history] Failed to record version for ${relPath}:`, err?.message ?? err);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Path helpers
 // ---------------------------------------------------------------------------
@@ -58,6 +200,15 @@ export function safePath(relPath) {
  */
 export function isDenied(relPath) {
   const normalised = relPath.replace(/\\/g, '/');
+  if (isMetadataPathAllowed(normalised)) return false;
+
+  if (normalised === '.obsidian/' || normalised === '.obsidian') {
+    // Allow descending into .obsidian only when we explicitly whitelist files inside.
+    if ([...METADATA_ALLOWLIST].some((entry) => entry.startsWith('.obsidian/'))) {
+      return false;
+    }
+  }
+
   const parts = normalised.split('/');
   const base = parts[parts.length - 1];
   if (DENY_FILES.includes(base)) return true;
@@ -72,6 +223,7 @@ export function isDenied(relPath) {
  * @param {string} relPath
  */
 export function isAllowed(relPath) {
+  if (isMetadataPathAllowed(relPath)) return true;
   if (isDenied(relPath)) return false;
   return ALLOW_EXTS.has(extname(relPath).toLowerCase());
 }
@@ -192,7 +344,7 @@ export { readFile_ as readFile };
  * @param {string} relPath
  * @param {string} content
  */
-export async function writeFile(relPath, content) {
+export async function writeFile(relPath, content, options = {}) {
   const abs = safePath(relPath);
   const tmp = abs + '.tmp';
   await mkdir(dirname(abs), { recursive: true });
@@ -200,16 +352,22 @@ export async function writeFile(relPath, content) {
   await rename(tmp, abs);
   // Invalidate cache entry so next manifest reflects new content
   manifestCache.delete(relPath);
+  await writeHistoryRecordBestEffort(relPath, content, options.history);
 }
 
 /**
  * Delete a file.
  * @param {string} relPath
  */
-export async function deleteFile(relPath) {
+export async function deleteFile(relPath, options = {}) {
   const abs = safePath(relPath);
+  const previous = await readFile(abs, 'utf-8');
   await unlink(abs);
   manifestCache.delete(relPath);
+  await writeHistoryRecordBestEffort(relPath, previous, {
+    ...(options.history ?? {}),
+    action: options.history?.action ?? 'delete',
+  });
 }
 
 /**
@@ -217,13 +375,71 @@ export async function deleteFile(relPath) {
  * @param {string} oldRelPath
  * @param {string} newRelPath
  */
-export async function renameFile(oldRelPath, newRelPath) {
+export async function renameFile(oldRelPath, newRelPath, options = {}) {
   const oldAbs = safePath(oldRelPath);
   const newAbs = safePath(newRelPath);
+  const previous = await readFile(oldAbs, 'utf-8');
   await mkdir(dirname(newAbs), { recursive: true });
   await rename(oldAbs, newAbs);
   manifestCache.delete(oldRelPath);
   manifestCache.delete(newRelPath);
+
+  const history = options.history ?? {};
+  await writeHistoryRecordBestEffort(oldRelPath, previous, {
+    ...history,
+    action: 'rename-out',
+  });
+  await writeHistoryRecordBestEffort(newRelPath, previous, {
+    ...history,
+    action: 'rename-in',
+  });
+}
+
+/**
+ * List historical versions for a file (newest first).
+ * @param {string} relPath
+ * @param {number} [limit]
+ */
+export async function listFileHistory(relPath, limit = DEFAULT_HISTORY_LIMIT) {
+  if (!isAllowed(relPath)) return [];
+  const clampedLimit = clampLimit(Number(limit), DEFAULT_HISTORY_LIMIT);
+  const dir = historyDirForPath(relPath);
+  const names = await listHistoryFiles(relPath);
+  const out = [];
+
+  for (const name of names.reverse()) {
+    try {
+      const record = await readHistoryRecord(join(dir, name));
+      if (record?.relPath !== relPath) continue;
+      out.push(toHistoryMeta(record));
+      if (out.length >= clampedLimit) break;
+    } catch {
+      // Skip malformed entries.
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Read a historical file version.
+ * @param {string} relPath
+ * @param {string} versionId
+ */
+export async function readFileHistoryVersion(relPath, versionId) {
+  if (!isAllowed(relPath)) {
+    throw new Error('Path not allowed');
+  }
+  if (typeof versionId !== 'string' || !VERSION_ID_RE.test(versionId)) {
+    throw new Error('Invalid version ID');
+  }
+
+  const abs = join(historyDirForPath(relPath), `${versionId}.json`);
+  const record = await readHistoryRecord(abs);
+  if (record?.relPath !== relPath) {
+    throw new Error('Version/path mismatch');
+  }
+  return record;
 }
 
 // ---------------------------------------------------------------------------

package/lib/yjsServer.js

@@ -79,7 +79,12 @@ async function flushRoomState(state) {
 
       const text = ydoc.getText('content').toString();
       try {
-        await vault.writeFile(state.relPath, text);
+        await vault.writeFile(state.relPath, text, {
+          history: {
+            action: 'yjs-write',
+            source: 'yjs',
+          },
+        });
         const hash = vault.hashContent(text);
         state.lastPersistAt = Date.now();
         state.lastPersistHash = hash;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fyresmith/hive-server",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "type": "module",
   "description": "Collaborative Obsidian vault server",
   "main": "index.js",
@@ -27,11 +27,11 @@
     "build": "npm run verify && npm pack --dry-run",
     "status": "node bin/hive.js status",
     "verify": "node scripts/verify.mjs",
+    "test:unit": "node --test test/**/*.test.js",
     "install-hive": "node scripts/install-hive.mjs",
-    "test": "npm run verify"
+    "test": "npm run test:unit && npm run verify"
   },
   "dependencies": {
-    "@fyresmith/hive-server": "^2.2.0",
     "chalk": "^5.6.2",
     "chokidar": "^3.6.0",
     "commander": "^13.1.0",