@karmaniverous/jeeves-server 3.0.0-0

package/src/util/crypto.ts

@@ -0,0 +1,79 @@
+/**
+ * Cryptographic utilities for key computation and verification
+ */
+
+import crypto from 'node:crypto';
+
+/**
+ * Compute path-specific key: HMAC-SHA256(apiKey, normalizedPath)
+ */
+export function computePathKey(apiKey: string, urlPath: string): string {
+  const normalized = urlPath.toLowerCase().replace(/^\/+|\/+$/g, '');
+  const hash = crypto
+    .createHmac('sha256', apiKey)
+    .update(normalized)
+    .digest('hex');
+  return hash.substring(0, 32);
+}
+
+/**
+ * Compute insider key: HMAC-SHA256(apiKey, "insider")
+ * Works for any path, grants full navigation
+ */
+export function computeInsiderKey(apiKey: string): string {
+  const hash = crypto
+    .createHmac('sha256', apiKey)
+    .update('insider')
+    .digest('hex');
+  return hash.substring(0, 32);
+}
+
+/**
+ * Compute outsider key with expiry: HMAC-SHA256(apiKey, path + "|" + expiry)
+ */
+export function computeOutsiderKeyWithExpiry(
+  apiKey: string,
+  urlPath: string,
+  expiry: string | number,
+): string {
+  const normalized = urlPath.toLowerCase().replace(/^\/+|\/+$/g, '');
+  const data = `${normalized}|${String(expiry)}`;
+  const hash = crypto.createHmac('sha256', apiKey).update(data).digest('hex');
+  return hash.substring(0, 32);
+}
+
+/**
+ * Deep share key parameters
+ */
+export interface DeepShareParams {
+  depth: number;
+  dirs: boolean;
+  stack: string; // lz-string compressToEncodedURIComponent'd path stack
+  exp?: string;
+}
+
+/**
+ * Compute deep share key: HMAC-SHA256(seed, path + "|" + d + "|" + dirs + "|" + stack + "|" + exp)
+ * Used for share links with depth \> 0 or dirs enabled.
+ */
+export function computeDeepShareKey(
+  seed: string,
+  urlPath: string,
+  params: DeepShareParams,
+): string {
+  const normalized = urlPath.toLowerCase().replace(/^\/+|\/+$/g, '');
+  const data = `${normalized}|${String(params.depth)}|${params.dirs ? '1' : '0'}|${params.stack}|${params.exp ?? ''}`;
+  const hash = crypto.createHmac('sha256', seed).update(data).digest('hex');
+  return hash.substring(0, 32);
+}
+
+/**
+ * Timing-safe string comparison
+ */
+export function timingSafeEqual(a: string, b: string): boolean {
+  try {
+    return crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b));
+  } catch {
+    return false;
+  }
+}

package/src/util/fileDetection.test.ts

@@ -0,0 +1,115 @@
+/**
+ * Tests for file detection utilities
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  getContentType,
+  isInlineType,
+  looksLikeText,
+} from './fileDetection.js';
+
+describe('file detection', () => {
+  describe('looksLikeText', () => {
+    it('should return true for plain text', () => {
+      const buffer = Buffer.from('Hello, world!', 'utf8');
+      expect(looksLikeText(buffer)).toBe(true);
+    });
+
+    it('should return true for text with newlines', () => {
+      const buffer = Buffer.from('Line 1\nLine 2\nLine 3', 'utf8');
+      expect(looksLikeText(buffer)).toBe(true);
+    });
+
+    it('should return false for binary data with null bytes', () => {
+      const buffer = Buffer.from([0x48, 0x65, 0x00, 0x6c, 0x6c, 0x6f]); // He\0llo
+      expect(looksLikeText(buffer)).toBe(false);
+    });
+
+    it('should return false for binary data at start', () => {
+      const buffer = Buffer.from([0x00, 0x01, 0x02, 0x03]);
+      expect(looksLikeText(buffer)).toBe(false);
+    });
+
+    it('should only check first 8KB', () => {
+      // Create 10KB buffer with null byte at position 9000
+      const buffer = Buffer.alloc(10240);
+      buffer.fill('A'.charCodeAt(0), 0, 9000);
+      buffer[9000] = 0;
+      buffer.fill('A'.charCodeAt(0), 9001);
+
+      // Should return true because null byte is beyond 8KB
+      expect(looksLikeText(buffer)).toBe(true);
+    });
+
+    it('should handle empty buffer', () => {
+      const buffer = Buffer.alloc(0);
+      expect(looksLikeText(buffer)).toBe(true);
+    });
+  });
+
+  describe('getContentType', () => {
+    it('should return correct type for text files', () => {
+      expect(getContentType('.txt')).toBe('text/plain; charset=utf-8');
+      expect(getContentType('.json')).toBe('application/json; charset=utf-8');
+      expect(getContentType('.html')).toBe('text/html; charset=utf-8');
+    });
+
+    it('should return correct type for images', () => {
+      expect(getContentType('.png')).toBe('image/png');
+      expect(getContentType('.jpg')).toBe('image/jpeg');
+      expect(getContentType('.svg')).toBe('image/svg+xml');
+    });
+
+    it('should return correct type for documents', () => {
+      expect(getContentType('.pdf')).toBe('application/pdf');
+      expect(getContentType('.docx')).toBe(
+        'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+      );
+    });
+
+    it('should be case-insensitive', () => {
+      expect(getContentType('.PDF')).toBe('application/pdf');
+      expect(getContentType('.TxT')).toBe('text/plain; charset=utf-8');
+    });
+
+    it('should return octet-stream for unknown extensions', () => {
+      expect(getContentType('.unknown')).toBe('application/octet-stream');
+      expect(getContentType('.xyz123')).toBe('application/octet-stream');
+    });
+  });
+
+  describe('isInlineType', () => {
+    it('should return true for text types', () => {
+      expect(isInlineType('text/plain; charset=utf-8')).toBe(true);
+      expect(isInlineType('text/html')).toBe(true);
+    });
+
+    it('should return true for images', () => {
+      expect(isInlineType('image/png')).toBe(true);
+      expect(isInlineType('image/jpeg')).toBe(true);
+    });
+
+    it('should return true for video/audio', () => {
+      expect(isInlineType('video/mp4')).toBe(true);
+      expect(isInlineType('audio/mpeg')).toBe(true);
+    });
+
+    it('should return true for JSON and PDF', () => {
+      expect(isInlineType('application/json; charset=utf-8')).toBe(true);
+      expect(isInlineType('application/pdf')).toBe(true);
+      expect(isInlineType('application/xml')).toBe(true);
+    });
+
+    it('should return false for archives', () => {
+      expect(isInlineType('application/zip')).toBe(false);
+      expect(isInlineType('application/x-tar')).toBe(false);
+    });
+
+    it('should return false for executables', () => {
+      expect(isInlineType('application/octet-stream')).toBe(false);
+      expect(isInlineType('application/x-msdownload')).toBe(false);
+    });
+  });
+});

package/src/util/fileDetection.ts

@@ -0,0 +1,70 @@
+/**
+ * File type detection and content-type mapping
+ */
+
+import mime from 'mime-types';
+
+/**
+ * Override map for extensions where mime-types returns an incorrect or
+ * unhelpful result for our use case.
+ */
+const OVERRIDES: Record<string, string> = {
+  '.mmd': 'text/plain; charset=utf-8',
+  '.puml': 'text/plain; charset=utf-8',
+  '.plantuml': 'text/plain; charset=utf-8',
+  '.pu': 'text/plain; charset=utf-8',
+  '.log': 'text/plain; charset=utf-8',
+  '.jsonl': 'text/plain; charset=utf-8',
+};
+
+/**
+ * Detect if a buffer looks like text (no null bytes in first 8KB)
+ */
+export function looksLikeText(buffer: Buffer): boolean {
+  const checkSize = Math.min(buffer.length, 8192);
+  for (let i = 0; i < checkSize; i++) {
+    if (buffer[i] === 0) return false;
+  }
+  return true;
+}
+
+/**
+ * Get content type for a file extension (with leading dot, e.g. '.md')
+ */
+export function getContentType(ext: string): string {
+  const dotExt = ext.startsWith('.') ? ext : `.${ext}`;
+  if (OVERRIDES[dotExt.toLowerCase()]) return OVERRIDES[dotExt.toLowerCase()];
+  // mime-types expects extension without the dot
+  return mime.contentType(dotExt.slice(1)) || 'application/octet-stream';
+}
+
+/**
+ * Standard content-type map for diagram export formats.
+ */
+export const DIAGRAM_CONTENT_TYPES: Record<string, string> = {
+  svg: 'image/svg+xml',
+  png: 'image/png',
+  pdf: 'application/pdf',
+  eps: 'application/postscript',
+  txt: 'text/plain; charset=utf-8',
+  latex: 'application/x-latex',
+};
+
+/**
+ * Map file extensions to highlight.js language identifiers.
+ */
+/**
+ * Check if a content type should be displayed inline
+ */
+export function isInlineType(contentType: string): boolean {
+  const inlineTypes = [
+    'image/',
+    'video/',
+    'audio/',
+    'text/',
+    'application/pdf',
+    'application/json',
+    'application/xml',
+  ];
+  return inlineTypes.some((type) => contentType.startsWith(type));
+}

package/src/util/formatters.test.ts

@@ -0,0 +1,105 @@
+/**
+ * Tests for formatting utilities
+ */
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { formatRelativeTime, formatSize, nowIso } from './formatters.js';
+
+describe('formatters', () => {
+  describe('formatSize', () => {
+    it('should format 0 bytes', () => {
+      expect(formatSize(0)).toBe('0 B');
+    });
+
+    it('should format bytes', () => {
+      expect(formatSize(500)).toBe('500 B');
+      expect(formatSize(1023)).toBe('1023 B');
+    });
+
+    it('should format kilobytes', () => {
+      expect(formatSize(1024)).toBe('1.0 KB');
+      expect(formatSize(1536)).toBe('1.5 KB');
+      expect(formatSize(10240)).toBe('10.0 KB');
+    });
+
+    it('should format megabytes', () => {
+      expect(formatSize(1048576)).toBe('1.0 MB');
+      expect(formatSize(1572864)).toBe('1.5 MB');
+    });
+
+    it('should format gigabytes', () => {
+      expect(formatSize(1073741824)).toBe('1.0 GB');
+      expect(formatSize(2147483648)).toBe('2.0 GB');
+    });
+
+    it('should format terabytes', () => {
+      expect(formatSize(1099511627776)).toBe('1.0 TB');
+    });
+  });
+
+  describe('formatRelativeTime', () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+      vi.setSystemTime(new Date('2026-02-15T12:00:00Z'));
+    });
+
+    it('should return null for null input', () => {
+      expect(formatRelativeTime(null)).toBeNull();
+    });
+
+    it('should return null for future timestamps', () => {
+      const future = new Date('2026-02-15T13:00:00Z').toISOString();
+      expect(formatRelativeTime(future)).toBeNull();
+    });
+
+    it('should return "just now" for very recent timestamps', () => {
+      const recent = new Date('2026-02-15T11:59:30Z').toISOString();
+      expect(formatRelativeTime(recent)).toBe('just now');
+    });
+
+    it('should return minutes ago', () => {
+      const mins5 = new Date('2026-02-15T11:55:00Z').toISOString();
+      expect(formatRelativeTime(mins5)).toBe('5m ago');
+
+      const mins45 = new Date('2026-02-15T11:15:00Z').toISOString();
+      expect(formatRelativeTime(mins45)).toBe('45m ago');
+    });
+
+    it('should return hours ago', () => {
+      const hours2 = new Date('2026-02-15T10:00:00Z').toISOString();
+      expect(formatRelativeTime(hours2)).toBe('2h ago');
+
+      const hours12 = new Date('2026-02-15T00:00:00Z').toISOString();
+      expect(formatRelativeTime(hours12)).toBe('12h ago');
+    });
+
+    it('should return days ago', () => {
+      const days1 = new Date('2026-02-14T12:00:00Z').toISOString();
+      expect(formatRelativeTime(days1)).toBe('1d ago');
+
+      const days7 = new Date('2026-02-08T12:00:00Z').toISOString();
+      expect(formatRelativeTime(days7)).toBe('7d ago');
+    });
+
+    it('should prioritize days over hours', () => {
+      const days1Hours5 = new Date('2026-02-14T07:00:00Z').toISOString();
+      expect(formatRelativeTime(days1Hours5)).toBe('1d ago');
+    });
+  });
+
+  describe('nowIso', () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+      vi.setSystemTime(new Date('2026-02-15T12:34:56.789Z'));
+    });
+
+    it('should return current time in ISO format', () => {
+      expect(nowIso()).toBe('2026-02-15T12:34:56.789Z');
+    });
+
+    it('should match ISO 8601 format', () => {
+      expect(nowIso()).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/);
+    });
+  });
+});

package/src/util/formatters.ts

@@ -0,0 +1,44 @@
+/**
+ * Formatting utilities for dates, file sizes, etc.
+ */
+
+/**
+ * Format file size in human-readable format
+ */
+export function formatSize(bytes: number): string {
+  if (bytes === 0) return '0 B';
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  const value = bytes / Math.pow(1024, i);
+  const decimals = i > 0 ? 1 : 0;
+  return `${value.toFixed(decimals)} ${units[i]}`;
+}
+
+/**
+ * Format ISO timestamp as relative time (e.g., "2h ago")
+ */
+export function formatRelativeTime(isoTimestamp: string | null): string | null {
+  if (!isoTimestamp) return null;
+
+  const then = new Date(isoTimestamp).getTime();
+  const now = Date.now();
+  const diffMs = now - then;
+
+  if (diffMs < 0) return null;
+
+  const mins = Math.floor(diffMs / 60000);
+  const hours = Math.floor(mins / 60);
+  const days = Math.floor(hours / 24);
+
+  if (days > 0) return `${String(days)}d ago`;
+  if (hours > 0) return `${String(hours)}h ago`;
+  if (mins > 0) return `${String(mins)}m ago`;
+  return 'just now';
+}
+
+/**
+ * Get current ISO timestamp
+ */
+export function nowIso(): string {
+  return new Date().toISOString();
+}

package/src/util/packageVersion.ts

@@ -0,0 +1,30 @@
+/**
+ * Resolve the service package version by walking up from the caller's directory.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+function findPackageJson(startDir: string): string {
+  let dir = startDir;
+  while (dir !== path.dirname(dir)) {
+    const candidate = path.join(dir, 'package.json');
+    if (fs.existsSync(candidate)) {
+      const pkg = JSON.parse(fs.readFileSync(candidate, 'utf8')) as {
+        name?: string;
+      };
+      // Find our package specifically, not the monorepo root
+      if (pkg.name === '@karmaniverous/jeeves-server') return candidate;
+    }
+    dir = path.dirname(dir);
+  }
+  throw new Error('Could not find @karmaniverous/jeeves-server package.json');
+}
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkgPath = findPackageJson(__dirname);
+const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')) as { version: string };
+
+/** The package version of the jeeves-server service package. */
+export const packageVersion: string = pkg.version;

package/src/util/platform.ts

@@ -0,0 +1,178 @@
+/**
+ * Platform abstraction for filesystem operations.
+ *
+ * Handles the differences between Windows (drive letters, backslashes)
+ * and Linux (mount points, forward slashes) for URL path ↔ filesystem path conversion.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const IS_WINDOWS = process.platform === 'win32';
+
+interface RootEntry {
+  /** URL-safe identifier (drive letter lowercase on Windows, mount name on Linux) */
+  id: string;
+  /** Display label */
+  label: string;
+  /** Filesystem path */
+  fsPath: string;
+}
+
+/**
+ * Discover available filesystem roots.
+ * Windows: enumerate accessible drive letters.
+ * Linux: return configured roots or default to '/'.
+ */
+export function getRoots(
+  configuredRoots?: Record<string, string>,
+): RootEntry[] {
+  if (IS_WINDOWS) {
+    const roots: RootEntry[] = [];
+    for (let code = 65; code <= 90; code++) {
+      const letter = String.fromCharCode(code);
+      const drivePath = `${letter}:\\`;
+      try {
+        fs.accessSync(drivePath, fs.constants.R_OK);
+        roots.push({
+          id: letter.toLowerCase(),
+          label: `${letter}:`,
+          fsPath: drivePath,
+        });
+      } catch {
+        // Drive not accessible
+      }
+    }
+    return roots;
+  }
+
+  // Linux: use configured roots or default to filesystem root
+  if (configuredRoots && Object.keys(configuredRoots).length > 0) {
+    return Object.entries(configuredRoots).map(([id, fsPath]) => ({
+      id,
+      label: fsPath,
+      fsPath: fsPath.endsWith('/') ? fsPath : fsPath + '/',
+    }));
+  }
+
+  return [{ id: 'root', label: '/', fsPath: '/' }];
+}
+
+/**
+ * Convert a URL path to a filesystem path.
+ *
+ * URL paths use forward slashes and start with the root id:
+ *   Windows: /e/jeeves-server/README.md → E:\\jeeves-server\\README.md
+ *   Linux:   /home/user/docs/README.md → /home/user/docs/README.md
+ *            /root/docs/README.md       → /docs/README.md (if root id is "root" mapping to "/")
+ */
+export function urlPathToFs(
+  urlPath: string,
+  roots: RootEntry[],
+): string | null {
+  const normalized = urlPath.replace(/^\/+/, '');
+  if (!normalized) return null;
+
+  if (IS_WINDOWS) {
+    // First segment is the drive letter
+    const slashIdx = normalized.indexOf('/');
+    const driveLetter =
+      slashIdx >= 0 ? normalized.substring(0, slashIdx) : normalized;
+    const rest = slashIdx >= 0 ? normalized.substring(slashIdx + 1) : '';
+
+    if (driveLetter.length !== 1) return null;
+    const fsPath = `${driveLetter.toUpperCase()}:\\${rest.replace(/\//g, '\\')}`;
+    return fsPath;
+  }
+
+  // Linux: match against configured roots
+  for (const root of roots) {
+    if (normalized.startsWith(root.id + '/') || normalized === root.id) {
+      const rest = normalized.substring(root.id.length);
+      // rest starts with '/' or is empty
+      const fsPath = root.fsPath.replace(/\/+$/, '') + (rest || '/');
+      return fsPath;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Convert a filesystem path to a URL path.
+ *
+ * Windows: E:\\jeeves-server\\README.md → /e/jeeves-server/README.md
+ * Linux:   /home/user/docs/README.md → /home/user/docs/README.md (root="root" → "/")
+ */
+export function fsPathToUrl(fsPath: string, roots: RootEntry[]): string {
+  if (IS_WINDOWS) {
+    return (
+      '/' +
+      fsPath
+        .replace(/\\/g, '/')
+        .replace(/^([A-Za-z]):/, (_, d: string) => d.toLowerCase())
+    );
+  }
+
+  // Linux: find the matching root and prepend the root id
+  for (const root of roots) {
+    const rootFs = root.fsPath.replace(/\/+$/, '');
+    if (fsPath === rootFs || fsPath.startsWith(rootFs + '/')) {
+      const rest = fsPath.substring(rootFs.length); // starts with '/' or is empty
+      if (root.id === 'root' && root.fsPath === '/') {
+        // Default root — URL path is just the fs path
+        return rest || '/';
+      }
+      return '/' + root.id + rest;
+    }
+  }
+
+  // Fallback: return as-is with forward slashes
+  return fsPath.replace(/\\/g, '/');
+}
+
+/**
+ * Split a filesystem path into breadcrumb parts.
+ * Returns [\{label, urlPath\}] from root to leaf.
+ */
+export function breadcrumbParts(
+  fsPath: string,
+  roots: RootEntry[],
+): { label: string; path: string }[] {
+  const urlPath = fsPathToUrl(fsPath, roots);
+  const parts = urlPath
+    .replace(/^\/+/, '')
+    .split('/')
+    .filter((p) => p);
+
+  return parts.map((_part, i) => {
+    const accumulated = parts.slice(0, i + 1).join('/');
+    return { label: parts[i], path: accumulated };
+  });
+}
+
+/**
+ * Recursively calculate total size of a directory in bytes.
+ */
+export function getDirSize(dirPath: string): number {
+  let totalSize = 0;
+  try {
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+      const entryPath = path.join(dirPath, entry.name);
+      try {
+        if (entry.isDirectory()) {
+          totalSize += getDirSize(entryPath);
+        } else {
+          const s = fs.statSync(entryPath);
+          totalSize += s.size;
+        }
+      } catch {
+        /* skip inaccessible */
+      }
+    }
+  } catch {
+    /* skip inaccessible */
+  }
+  return totalSize;
+}

package/src/util/state.ts

@@ -0,0 +1,55 @@
+/**
+ * Server state management (key rotation tracking, etc.)
+ */
+
+import fs from 'node:fs';
+
+import { getConfig } from '../config/index.js';
+import type { ServerState } from '../config/types.js';
+
+/**
+ * Load state from file
+ */
+export function loadState(): ServerState {
+  const { stateFile } = getConfig();
+  try {
+    if (fs.existsSync(stateFile)) {
+      const content = fs.readFileSync(stateFile, 'utf8');
+      return JSON.parse(content) as ServerState;
+    }
+  } catch {
+    // Ignore errors, return empty state
+  }
+  return {};
+}
+
+/**
+ * Save state to file
+ */
+export function saveState(state: ServerState): void {
+  const { stateFile } = getConfig();
+  fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf8');
+}
+
+/**
+ * Set key rotation timestamp
+ */
+export function setKeyRotationTimestamp(timestamp: string): void {
+  const state = loadState();
+  state.keyRotatedAt = timestamp;
+  saveState(state);
+}
+
+/**
+ * Set an insider's auto-generated key in state
+ */
+export function setInsiderKey(
+  email: string,
+  seed: string,
+  createdAt: string,
+): void {
+  const state = loadState();
+  if (!state.insiderKeys) state.insiderKeys = {};
+  state.insiderKeys[email.toLowerCase()] = { seed, createdAt };
+  saveState(state);
+}

package/test-docs/diagram-retry-test.md

@@ -0,0 +1,18 @@
+# Diagram Retry Test
+
+## Valid Diagram
+
+```mermaid
+graph LR
+    A[Start] --> B[Process]
+    B --> C[End]
+```
+
+## Invalid Diagram (should fail)
+
+```mermaid
+graph LR
+    A[Start] --> B[Process]
+    B --> C[Success!]
+    C --> D[End]
+```