mdboard 1.0.0 → 1.2.0

package/watcher.js

@@ -0,0 +1,131 @@
+/**
+ * mdboard — File watcher
+ *
+ * Watches project directories for changes to .md, config, and CSS files.
+ * Supports watching multiple directories for multi-source workspaces.
+ */
+
+const fs = require('fs');
+
+const watchTimers = new Map();
+
+/**
+ * Setup recursive watcher on a directory for .md, mdboard.json, and mdboard.css changes.
+ *
+ * @param {string} dir - Directory to watch recursively
+ * @param {object} callbacks - { onChange(filename), onConfigChange(), onCssChange(filename) }
+ */
+function watchDir(dir, callbacks) {
+  if (!fs.existsSync(dir)) return;
+
+  try {
+    fs.watch(dir, { recursive: true }, (eventType, filename) => {
+      if (!filename) return;
+
+      const isMd = filename.endsWith('.md');
+      const isConfig = filename === 'mdboard.json' || filename.endsWith('/mdboard.json');
+      const isCss = filename === 'mdboard.css' || filename.endsWith('/mdboard.css');
+
+      if (!isMd && !isConfig && !isCss) return;
+
+      const key = dir + ':' + filename;
+      if (watchTimers.has(key)) clearTimeout(watchTimers.get(key));
+
+      watchTimers.set(key, setTimeout(() => {
+        watchTimers.delete(key);
+        if (isConfig && callbacks.onConfigChange) callbacks.onConfigChange();
+        if (callbacks.onChange) callbacks.onChange(filename, isCss);
+      }, 200));
+    });
+  } catch {
+    console.warn('  Warning: file watching unavailable for ' + dir);
+  }
+}
+
+/**
+ * Watch a single file for changes (e.g., workspace.json).
+ *
+ * @param {string} filePath - Absolute path to file
+ * @param {function} onChange - Callback on change
+ */
+function watchFile(filePath, onChange) {
+  if (!fs.existsSync(filePath)) return;
+
+  try {
+    fs.watch(filePath, (eventType) => {
+      const key = 'file:' + filePath;
+      if (watchTimers.has(key)) clearTimeout(watchTimers.get(key));
+
+      watchTimers.set(key, setTimeout(() => {
+        watchTimers.delete(key);
+        if (onChange) onChange();
+      }, 200));
+    });
+  } catch {
+    // Non-critical
+  }
+}
+
+/**
+ * Setup watchers for project directories and workspace-level config.
+ *
+ * @param {object} opts
+ * @param {string[]} opts.projectDirs - List of project/ directories to watch recursively
+ * @param {string[]} opts.rootDirs - List of root directories to watch for mdboard.json/css
+ * @param {function} opts.onScan - Called when files change and a rescan is needed
+ * @param {function} opts.onConfigReload - Called when mdboard.json changes
+ * @param {function} opts.onBroadcast - Called with event data to broadcast via SSE
+ * @param {string} [opts.workspacePath] - Path to workspace.json to watch
+ * @param {function} [opts.onWorkspaceChange] - Called when workspace.json changes
+ */
+function setupWatchers(opts) {
+  const { projectDirs, rootDirs, onScan, onConfigReload, onBroadcast, workspacePath, onWorkspaceChange } = opts;
+
+  // Watch each project directory recursively
+  for (const dir of projectDirs) {
+    watchDir(dir, {
+      onConfigChange: () => {
+        if (onConfigReload) onConfigReload();
+      },
+      onChange: (filename, isCss) => {
+        if (onScan) onScan();
+        const eventData = { type: 'update', file: filename, timestamp: new Date().toISOString() };
+        if (isCss) eventData.cssReload = true;
+        if (onBroadcast) onBroadcast(eventData);
+      },
+    });
+  }
+
+  // Watch root directories for workspace-level mdboard.json and mdboard.css
+  for (const dir of rootDirs) {
+    try {
+      fs.watch(dir, (eventType, filename) => {
+        if (!filename) return;
+        if (filename !== 'mdboard.json' && filename !== 'mdboard.css') return;
+
+        const key = 'root:' + dir + ':' + filename;
+        if (watchTimers.has(key)) clearTimeout(watchTimers.get(key));
+
+        watchTimers.set(key, setTimeout(() => {
+          watchTimers.delete(key);
+          if (filename === 'mdboard.json') {
+            if (onConfigReload) onConfigReload();
+            if (onScan) onScan();
+          }
+          const eventData = { type: 'update', file: filename, timestamp: new Date().toISOString() };
+          if (filename === 'mdboard.css') eventData.cssReload = true;
+          if (onBroadcast) onBroadcast(eventData);
+        }, 200));
+      });
+    } catch {
+      // Non-critical
+    }
+  }
+
+  // Watch workspace.json
+  if (workspacePath && onWorkspaceChange) {
+    watchFile(workspacePath, onWorkspaceChange);
+  }
+}
+
+module.exports = { setupWatchers, watchDir, watchFile };

package/workspace.js

@@ -0,0 +1,220 @@
+/**
+ * mdboard — Workspace loader
+ *
+ * Handles multi-repo workspace via workspace.json.
+ * Resolves source paths, manages remote git clones, and provides
+ * author info via git log.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+const CACHE_DIR = path.join(os.homedir(), '.cache', 'mdboard');
+
+/**
+ * Load and resolve workspace.json.
+ *
+ * @param {string} projectDir - The workspace root directory
+ * @param {string} [explicitPath] - Explicit path to workspace.json
+ * @returns {object|null} - Parsed workspace with resolved source paths, or null
+ */
+function loadWorkspace(projectDir, explicitPath) {
+  let wsPath = null;
+  let ws = null;
+
+  const candidates = [];
+  if (explicitPath) candidates.push(path.resolve(explicitPath));
+  if (projectDir) {
+    candidates.push(path.join(projectDir, 'workspace.json'));
+  }
+
+  for (const p of candidates) {
+    try {
+      const raw = fs.readFileSync(p, 'utf-8');
+      ws = JSON.parse(raw);
+      wsPath = p;
+      break;
+    } catch {
+      continue;
+    }
+  }
+
+  if (!ws || !Array.isArray(ws.sources) || ws.sources.length === 0) return null;
+
+  const wsDir = path.dirname(wsPath);
+
+  // Resolve each source
+  for (const source of ws.sources) {
+    if (!source.name) continue;
+
+    source.type = source.type || 'local';
+    source.label = source.label || source.name;
+    source.icon = source.icon || source.name.charAt(0).toUpperCase();
+
+    if (!source.color) {
+      source.color = hashColor(source.name);
+    }
+
+    if (source.readonly == null) {
+      source.readonly = source.type === 'remote';
+    }
+
+    if (source.type === 'local') {
+      if (source.path) {
+        const resolved = path.resolve(wsDir, source.path);
+        const root = source.root || 'project';
+        source._resolvedPath = path.join(resolved, root);
+        source._repoRoot = resolved;
+      }
+    } else if (source.type === 'remote') {
+      const root = source.root || 'project';
+      const cacheKey = source.name;
+      const cachePath = path.join(CACHE_DIR, cacheKey);
+      source._resolvedPath = path.join(cachePath, root);
+      source._repoRoot = cachePath;
+      source._cachePath = cachePath;
+    }
+  }
+
+  // Also resolve the overview (workspace root's project/ dir)
+  const overviewPath = path.join(projectDir, 'project');
+  if (fs.existsSync(overviewPath)) {
+    ws.sources.unshift({
+      name: 'overview',
+      label: 'Overview',
+      icon: '\u2605',
+      color: '#5B6EF5',
+      type: 'local',
+      readonly: false,
+      _resolvedPath: overviewPath,
+      _repoRoot: projectDir,
+    });
+  }
+
+  ws._path = wsPath;
+  ws.settings = ws.settings || {};
+
+  return ws;
+}
+
+/**
+ * Generate a deterministic hex color from a string.
+ */
+function hashColor(str) {
+  const colors = ['#F97316', '#8B5CF6', '#EC4899', '#10B981', '#06B6D4', '#5B6EF5', '#6366F1', '#D4A72C'];
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) hash = str.charCodeAt(i) + ((hash << 5) - hash);
+  return colors[Math.abs(hash) % colors.length];
+}
+
+/**
+ * Sync a single remote source by cloning or pulling.
+ *
+ * @param {object} source - A source entry with type=remote
+ */
+async function syncRemote(source) {
+  if (source.type !== 'remote' || !source.url) return;
+
+  const cachePath = source._cachePath;
+  if (!cachePath) return;
+
+  const branch = source.branch || 'main';
+
+  try {
+    fs.mkdirSync(CACHE_DIR, { recursive: true });
+
+    if (fs.existsSync(path.join(cachePath, '.git'))) {
+      // Pull latest
+      execSync(`git -C "${cachePath}" fetch origin ${branch} --depth=1 && git -C "${cachePath}" reset --hard origin/${branch}`, {
+        stdio: 'pipe',
+        timeout: 30000,
+      });
+    } else {
+      // Clone
+      execSync(`git clone --depth=1 --branch ${branch} "${source.url}" "${cachePath}"`, {
+        stdio: 'pipe',
+        timeout: 60000,
+      });
+    }
+
+    source._lastSync = new Date().toISOString();
+    source._error = null;
+  } catch (err) {
+    source._error = err.message;
+    console.warn(`  Warning: sync failed for ${source.name}: ${err.message}`);
+  }
+}
+
+/**
+ * Sync all remote sources.
+ *
+ * @param {object[]} sources - Array of source entries
+ */
+async function syncAllRemotes(sources) {
+  const remotes = sources.filter(s => s.type === 'remote');
+  for (const source of remotes) {
+    await syncRemote(source);
+  }
+}
+
+/**
+ * Get the git author of the last commit that touched a file.
+ *
+ * @param {string} repoRoot - Path to git repo root
+ * @param {string} relFile - Relative file path
+ * @returns {string|null}
+ */
+const authorCache = new Map();
+const AUTHOR_CACHE_MAX = 500;
+
+function getGitAuthor(repoRoot, relFile) {
+  if (!repoRoot || !relFile) return null;
+
+  const key = repoRoot + ':' + relFile;
+  if (authorCache.has(key)) return authorCache.get(key);
+
+  try {
+    const author = execSync(
+      `git -C "${repoRoot}" log -1 --format="%an" -- "${relFile}"`,
+      { stdio: 'pipe', timeout: 5000 }
+    ).toString().trim();
+
+    if (authorCache.size >= AUTHOR_CACHE_MAX) {
+      const first = authorCache.keys().next().value;
+      authorCache.delete(first);
+    }
+    authorCache.set(key, author || null);
+    return author || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * List all cached remote repos.
+ *
+ * @returns {string[]} - Directory names in cache
+ */
+function listCache() {
+  try {
+    return fs.readdirSync(CACHE_DIR).filter(e => !e.startsWith('.'));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Clean the entire cache directory.
+ */
+function cleanCache() {
+  try {
+    fs.rmSync(CACHE_DIR, { recursive: true, force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { loadWorkspace, syncRemote, syncAllRemotes, getGitAuthor, listCache, cleanCache, CACHE_DIR };

package/yaml.js

@@ -0,0 +1,129 @@
+/**
+ * mdboard — YAML frontmatter parser and serializer
+ *
+ * Lightweight parser for YAML frontmatter in markdown files.
+ * No external dependencies.
+ */
+
+function parseFrontmatter(content) {
+  const result = { frontmatter: {}, content: '' };
+  if (!content.startsWith('---')) return { frontmatter: {}, content };
+
+  const end = content.indexOf('\n---', 3);
+  if (end === -1) return { frontmatter: {}, content };
+
+  const yaml = content.substring(4, end).trim();
+  result.content = content.substring(end + 4).trim();
+  result.frontmatter = parseYaml(yaml);
+  return result;
+}
+
+function parseYaml(text) {
+  const obj = {};
+  const lines = text.split('\n');
+  let i = 0;
+
+  while (i < lines.length) {
+    const line = lines[i];
+    const match = line.match(/^(\w[\w.-]*)\s*:\s*(.*)/);
+
+    if (!match) { i++; continue; }
+
+    const key = match[1];
+    const rawValue = match[2].trim();
+
+    if (rawValue === '' || rawValue === '') {
+      const nested = {};
+      let dashList = null;
+      let j = i + 1;
+
+      while (j < lines.length) {
+        const nextLine = lines[j];
+        if (!nextLine.match(/^\s/) || nextLine.trim() === '') break;
+
+        const dashMatch = nextLine.match(/^\s+-\s+(.*)/);
+        const nestedMatch = nextLine.match(/^\s+(\w[\w.-]*)\s*:\s*(.*)/);
+
+        if (dashMatch) {
+          if (!dashList) dashList = [];
+          dashList.push(parseValue(dashMatch[1].trim()));
+        } else if (nestedMatch) {
+          nested[nestedMatch[1]] = parseValue(nestedMatch[2].trim());
+        }
+        j++;
+      }
+
+      obj[key] = dashList || (Object.keys(nested).length > 0 ? nested : parseValue(rawValue));
+      i = j;
+      continue;
+    }
+
+    obj[key] = parseValue(rawValue);
+    i++;
+  }
+
+  return obj;
+}
+
+function parseValue(raw) {
+  if (raw === '' || raw === undefined) return null;
+
+  if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
+    return raw.slice(1, -1);
+  }
+
+  if (raw.startsWith('[') && raw.endsWith(']')) {
+    const inner = raw.slice(1, -1).trim();
+    if (inner === '') return [];
+    return inner.split(',').map(s => parseValue(s.trim()));
+  }
+
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  if (raw === 'null' || raw === '~') return null;
+  if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw);
+
+  return raw;
+}
+
+function serializeValue(v) {
+  if (v === null || v === undefined) return '';
+  if (typeof v === 'boolean') return v ? 'true' : 'false';
+  if (typeof v === 'number') return String(v);
+  if (typeof v === 'string') {
+    if (/[:#\[\]{}&*!|>'"%@`,\n]/.test(v) || v === '' || v === 'true' || v === 'false' || v === 'null') {
+      return '"' + v.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+    }
+    return v;
+  }
+  return String(v);
+}
+
+function serializeYaml(obj) {
+  const lines = [];
+  for (const [key, value] of Object.entries(obj)) {
+    if (key.startsWith('_')) continue;
+    if (value === undefined) continue;
+    if (value === null) {
+      lines.push(key + ':');
+      continue;
+    }
+    if (Array.isArray(value)) {
+      if (value.length === 0) {
+        lines.push(key + ': []');
+      } else {
+        lines.push(key + ': [' + value.map(v => serializeValue(v)).join(', ') + ']');
+      }
+    } else if (typeof value === 'object') {
+      lines.push(key + ':');
+      for (const [k, v] of Object.entries(value)) {
+        lines.push('  ' + k + ': ' + serializeValue(v));
+      }
+    } else {
+      lines.push(key + ': ' + serializeValue(value));
+    }
+  }
+  return lines.join('\n');
+}
+
+module.exports = { parseFrontmatter, parseYaml, parseValue, serializeYaml, serializeValue };