mdboard 1.2.0 → 2.0.0

package/src/server/api.js

@@ -0,0 +1,616 @@
+/**
+ * mdboard — Dynamic API handlers
+ *
+ * All REST API route handlers, fully config-driven.
+ * No hardcoded entity names — everything generated from entities.json,
+ * structure.json, and api.json.
+ */
+
+'use strict';
+
+const { URL } = require('url');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const {
+  getEntityTypes, getEntity, getFields, getFilterableFields,
+  getAncestors, isCompletedStatus, flattenHierarchy,
+} = require('../core/config');
+const { isValidProject } = require('../core/history');
+const { computeStatus } = require('../cli/status');
+
+// --- HTTP helpers ---
+
+function jsonResponse(res, data, status = 200) {
+  res.writeHead(status, {
+    'Content-Type': 'application/json',
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Methods': 'GET, PATCH, POST, DELETE, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type',
+  });
+  res.end(JSON.stringify(data, null, 2));
+}
+
+function parseBody(req) {
+  return new Promise((resolve) => {
+    const chunks = [];
+    req.on('data', c => chunks.push(c));
+    req.on('end', () => {
+      try { resolve(JSON.parse(Buffer.concat(chunks).toString())); }
+      catch { resolve({}); }
+    });
+  });
+}
+
+// --- Route map ---
+
+/**
+ * Build a map of pluralName → entityType from config.
+ * e.g. "tasks" → "task", "cycles" → "cycle"
+ */
+function buildRouteMap(cfg) {
+  const map = {};
+  for (const type of getEntityTypes(cfg)) {
+    const entity = getEntity(cfg, type);
+    if (entity && entity.plural) {
+      map[entity.plural.toLowerCase()] = type;
+    }
+  }
+  return map;
+}
+
+// --- Generic formatters ---
+
+/**
+ * Format an entity for API response.
+ * Replaces formatTask/formatEpic/formatMilestone/etc.
+ */
+function formatEntity(item, cfg, type, includeContent, ctx) {
+  const fields = getFields(cfg, type);
+  const result = {};
+
+  // Core fields
+  result.id = item.id;
+  result.title = item.title;
+  result.created = item.created;
+
+  // Entity-defined fields
+  for (const name of Object.keys(fields)) {
+    if (item[name] !== undefined) {
+      result[name] = item[name];
+    }
+  }
+
+  // Computed fields
+  if (item._progress !== undefined) result._progress = item._progress;
+  if (item._childCount !== undefined) result._childCount = item._childCount;
+  if (item._completedCount !== undefined) result._completedCount = item._completedCount;
+  if (item._totalPoints !== undefined) result._totalPoints = item._totalPoints;
+  if (item._completedPoints !== undefined) result._completedPoints = item._completedPoints;
+
+  // Source fields
+  if (item._source) {
+    result._source = item._source;
+    result._sourceLabel = item._sourceLabel || item._source;
+    result._sourceColor = item._sourceColor || null;
+    result._readonly = item._readonly || false;
+  }
+
+  // Ancestor refs
+  const ancestors = getAncestors(cfg, type);
+  for (const anc of ancestors) {
+    if (item['_' + anc] !== undefined) result['_' + anc] = item['_' + anc];
+  }
+
+  // Content — lazy-loaded from disk
+  if (includeContent && ctx) {
+    result.content = loadItemContent(item, ctx) || '';
+  }
+
+  return result;
+}
+
+/**
+ * Lazy-load content from disk for a single entity.
+ */
+function loadItemContent(item, ctx) {
+  if (!item._file) return '';
+  try {
+    const { parseFrontmatter } = require('../core/yaml');
+    let basePath;
+    if (item._source && ctx.sources) {
+      const src = ctx.sources.find(s => s.name === item._source);
+      basePath = src && src._resolvedPath ? src._resolvedPath : null;
+    }
+    if (!basePath) {
+      basePath = path.join(ctx.projectDir, 'project');
+    }
+    const raw = fs.readFileSync(path.join(basePath, item._file), 'utf-8');
+    const parsed = parseFrontmatter(raw);
+    return parsed.content || '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Filter entities using query params.
+ * Uses getFilterableFields to know which params to accept.
+ */
+function filterEntities(items, cfg, type, url) {
+  const filterableFields = getFilterableFields(cfg, type);
+
+  for (const field of filterableFields) {
+    const value = url.searchParams.get(field);
+    if (!value) continue;
+
+    items = items.filter(item => {
+      // Check direct field
+      if (item[field] === value) return true;
+      // Check ancestor ref (prefixed with _)
+      if (item['_' + field] === value) return true;
+      return false;
+    });
+  }
+
+  // Special: source filter
+  const source = url.searchParams.get('source');
+  if (source) {
+    items = items.filter(item => item._source === source);
+  }
+
+  return items;
+}
+
+/**
+ * Compute generic metrics across all entity types.
+ */
+function computeMetrics(model, cfg) {
+  const result = { entities: {} };
+  const flat = flattenHierarchy(cfg);
+  const hierarchyEntities = flat.filter(e => !e.standalone);
+  const leafType = hierarchyEntities.length > 0
+    ? hierarchyEntities[hierarchyEntities.length - 1].type
+    : null;
+
+  for (const type of getEntityTypes(cfg)) {
+    const items = model.entities[type] || [];
+    const total = items.length;
+    const completed = items.filter(i => isCompletedStatus(cfg, i.status)).length;
+
+    const entry = { total, completed };
+
+    // Leaf type gets point metrics
+    if (type === leafType) {
+      entry.points = items.reduce((sum, i) => sum + (i.points || 0), 0);
+      entry.completedPoints = items
+        .filter(i => isCompletedStatus(cfg, i.status))
+        .reduce((sum, i) => sum + (i.points || 0), 0);
+    }
+
+    result.entities[type] = entry;
+  }
+
+  return result;
+}
+
+/**
+ * Compute health status.
+ */
+function computeHealth(model, cfg) {
+  const flat = flattenHierarchy(cfg);
+  const hierarchyEntities = flat.filter(e => !e.standalone);
+
+  const leafType = hierarchyEntities.length > 0
+    ? hierarchyEntities[hierarchyEntities.length - 1].type
+    : null;
+
+  const leafItems = leafType ? (model.entities[leafType] || []) : [];
+  const total = leafItems.length;
+  const completed = leafItems.filter(i => isCompletedStatus(cfg, i.status)).length;
+
+  // Find in-progress: look for status field values with "half-circle" icon
+  const inProgress = leafItems.filter(i => {
+    if (!i.status) return false;
+    return !isCompletedStatus(cfg, i.status) && i.status !== 'todo' && i.status !== 'planned';
+  }).length;
+
+  // Active top-level entity
+  const topType = hierarchyEntities.length > 0 ? hierarchyEntities[0].type : null;
+  const topItems = topType ? (model.entities[topType] || []) : [];
+  const activeTop = topItems.find(i => i.status === 'active');
+
+  return {
+    status: 'ok',
+    totals: { total, completed, inProgress },
+    active: activeTop ? { type: topType, id: activeTop.id, title: activeTop.title } : null,
+  };
+}
+
+// --- Main API handler ---
+
+async function handleApi(req, res, ctx) {
+  const { model, config: cfg, port, sources } = ctx;
+  const url = new URL(req.url, `http://localhost:${port}`);
+  const pathname = url.pathname;
+
+  // CORS preflight
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204, {
+      'Access-Control-Allow-Origin': '*',
+      'Access-Control-Allow-Methods': 'GET, PATCH, POST, DELETE, OPTIONS',
+      'Access-Control-Allow-Headers': 'Content-Type',
+    });
+    return res.end();
+  }
+
+  const routeMap = buildRouteMap(cfg);
+
+  // --- Source-scoped routes: /api/sources/:name/... ---
+  const sourceMatch = pathname.match(/^\/api\/sources\/([^/]+)\/(.+)$/);
+  if (sourceMatch && sourceMatch[2] !== 'sync') {
+    const sourceName = decodeURIComponent(sourceMatch[1]);
+    const subPath = sourceMatch[2];
+    return handleSourceRoute(req, res, ctx, url, routeMap, sourceName, subPath);
+  }
+
+  // --- System routes ---
+
+  // GET /api/config
+  if (req.method === 'GET' && pathname === '/api/config') {
+    const result = {
+      preset: cfg._preset,
+      entities: cfg.entities.entities,
+      hierarchy: cfg.structure.hierarchy,
+      standalone: cfg.structure.standalone,
+      completedStatuses: cfg.entities.completedStatuses,
+      priorities: cfg.entities.priorities,
+      ui: cfg.ui,
+      theme: cfg._theme,
+      hasProject: ctx.hasProject != null ? ctx.hasProject : true,
+      projectDir: ctx.projectDir || null,
+    };
+    if (sources && sources.length > 0) {
+      result.workspace = {
+        sources: sources.map(s => ({
+          name: s.name, label: s.label || s.name,
+          color: s.color || null, icon: s.icon || s.name.charAt(0).toUpperCase(),
+          type: s.type || 'local',
+          readonly: s.readonly != null ? s.readonly : (s.type === 'remote'),
+        })),
+        hasMultipleSources: sources.length > 1,
+      };
+    }
+    return jsonResponse(res, result);
+  }
+
+  // GET /api/project
+  if (req.method === 'GET' && pathname === '/api/project') {
+    return jsonResponse(res, model.project || {});
+  }
+
+  // GET /api/sources
+  if (req.method === 'GET' && pathname === '/api/sources') {
+    if (!sources || sources.length === 0) return jsonResponse(res, []);
+    return jsonResponse(res, sources.map(s => {
+      const leafType = getLeafType(cfg);
+      const leafItems = leafType ? (model.entities[leafType] || []) : [];
+      const sourceTasks = leafItems.filter(t => t._source === s.name);
+      return {
+        name: s.name,
+        label: s.label || s.name,
+        color: s.color || null,
+        icon: s.icon || s.name.charAt(0).toUpperCase(),
+        type: s.type || 'local',
+        readonly: s.readonly != null ? s.readonly : (s.type === 'remote'),
+        taskCount: sourceTasks.length,
+        completedCount: sourceTasks.filter(t => isCompletedStatus(cfg, t.status)).length,
+        lastSync: s._lastSync || null,
+        error: s._error || null,
+      };
+    }));
+  }
+
+  // GET /api/metrics
+  if (req.method === 'GET' && pathname === '/api/metrics') {
+    return jsonResponse(res, computeMetrics(model, cfg));
+  }
+
+  // GET /api/health
+  if (req.method === 'GET' && pathname === '/api/health') {
+    return jsonResponse(res, computeHealth(model, cfg));
+  }
+
+  // GET /api/status
+  if (req.method === 'GET' && pathname === '/api/status') {
+    return jsonResponse(res, computeStatus(model, cfg));
+  }
+
+  // GET /api/history — auto-prune entries with missing directories
+  if (req.method === 'GET' && pathname === '/api/history') {
+    const { pruneHistory } = require('../core/history');
+    pruneHistory();
+    return jsonResponse(res, ctx.getProjectHistory ? ctx.getProjectHistory() : []);
+  }
+
+  // GET /api/events (SSE)
+  if (req.method === 'GET' && pathname === '/api/events') {
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+      'Access-Control-Allow-Origin': '*',
+    });
+    res.write(`data: ${JSON.stringify({ type: 'connected' })}\n\n`);
+
+    if (ctx.sseClients) ctx.sseClients.add(res);
+
+    const keepalive = setInterval(() => {
+      try { res.write(': keepalive\n\n'); } catch { /* client gone */ }
+    }, 30000);
+
+    req.on('close', () => {
+      if (ctx.sseClients) ctx.sseClients.delete(res);
+      clearInterval(keepalive);
+    });
+    return;
+  }
+
+  // POST /api/theme
+  if (req.method === 'POST' && pathname === '/api/theme') {
+    const body = await parseBody(req);
+    if (!body.themeId || !body.css) {
+      return jsonResponse(res, { error: 'Missing themeId or css' }, 400);
+    }
+
+    if (body.setDefault) {
+      const globalDir = path.join(os.homedir(), '.config', 'mdboard');
+      if (!fs.existsSync(globalDir)) fs.mkdirSync(globalDir, { recursive: true });
+      fs.writeFileSync(path.join(globalDir, 'mdboard.css'), body.css, 'utf-8');
+      const configPath = path.join(globalDir, 'mdboard.json');
+      let globalCfg = {};
+      try { globalCfg = JSON.parse(fs.readFileSync(configPath, 'utf-8')); } catch {}
+      globalCfg.theme = body.themeId;
+      fs.writeFileSync(configPath, JSON.stringify(globalCfg, null, 2) + '\n', 'utf-8');
+    }
+
+    // Save CSS to project
+    const projectCssPath = path.join(ctx.projectDir, 'project', 'mdboard.css');
+    const fallbackCssPath = path.join(ctx.projectDir, 'mdboard.css');
+    const cssPath = fs.existsSync(path.dirname(projectCssPath)) ? projectCssPath : fallbackCssPath;
+    fs.writeFileSync(cssPath, body.css, 'utf-8');
+
+    // Persist themeId in project/mdboard.json
+    const projectJsonPath = path.join(ctx.projectDir, 'project', 'mdboard.json');
+    const fallbackJsonPath = path.join(ctx.projectDir, 'mdboard.json');
+    const jsonPath = fs.existsSync(path.dirname(projectJsonPath)) ? projectJsonPath : fallbackJsonPath;
+    let projectCfg = {};
+    try { projectCfg = JSON.parse(fs.readFileSync(jsonPath, 'utf-8')); } catch {}
+    projectCfg.theme = body.themeId;
+    fs.writeFileSync(jsonPath, JSON.stringify(projectCfg, null, 2) + '\n', 'utf-8');
+
+    if (ctx.reloadConfig) ctx.reloadConfig();
+    return jsonResponse(res, { ok: true });
+  }
+
+  // POST /api/history/switch
+  if (req.method === 'POST' && pathname === '/api/history/switch') {
+    const body = await parseBody(req);
+    const targetPath = body && body.path;
+    if (!targetPath) return jsonResponse(res, { error: 'Missing path' }, 400);
+    if (!fs.existsSync(targetPath)) return jsonResponse(res, { error: 'Directory does not exist: ' + targetPath }, 400);
+    if (!isValidProject(targetPath)) return jsonResponse(res, { error: 'Not a valid mdboard project: ' + targetPath }, 400);
+    if (ctx.loadProject) {
+      try {
+        ctx.loadProject(targetPath);
+        const name = (ctx.model && ctx.model.project && ctx.model.project.name) || path.basename(targetPath);
+        return jsonResponse(res, { ok: true, projectDir: ctx.projectDir, name });
+      } catch (err) {
+        return jsonResponse(res, { error: err.message }, 500);
+      }
+    }
+    return jsonResponse(res, { error: 'Project switching not available' }, 500);
+  }
+
+  // POST /api/sources — add a new source to workspace.json
+  if (req.method === 'POST' && pathname === '/api/sources') {
+    const body = await parseBody(req);
+    if (!body.name || !body.type) return jsonResponse(res, { error: 'Missing name or type' }, 400);
+    if (body.type === 'local' && !body.path) return jsonResponse(res, { error: 'Missing path for local source' }, 400);
+    if (body.type === 'remote' && !body.url) return jsonResponse(res, { error: 'Missing url for remote source' }, 400);
+
+    // Load or create workspace.json
+    const wsPath = ctx.workspacePath || path.join(ctx.projectDir, 'workspace.json');
+    let ws;
+    try {
+      ws = JSON.parse(fs.readFileSync(wsPath, 'utf-8'));
+    } catch {
+      ws = { sources: [] };
+    }
+    if (!Array.isArray(ws.sources)) ws.sources = [];
+
+    // Check duplicates
+    if (ws.sources.some(s => s.name === body.name)) {
+      return jsonResponse(res, { error: 'A source with name "' + body.name + '" already exists' }, 400);
+    }
+
+    const entry = { name: body.name, type: body.type };
+    if (body.type === 'local') {
+      entry.path = path.relative(path.dirname(wsPath), body.path) || body.path;
+      if (body.root) entry.root = body.root;
+    } else {
+      entry.url = body.url;
+      entry.branch = body.branch || 'main';
+      entry.readonly = true;
+      if (body.root) entry.root = body.root;
+    }
+    if (body.color) entry.color = body.color;
+
+    ws.sources.push(entry);
+    fs.writeFileSync(wsPath, JSON.stringify(ws, null, 2) + '\n', 'utf-8');
+
+    if (ctx.onWorkspaceChange) ctx.onWorkspaceChange();
+    return jsonResponse(res, { ok: true, source: entry }, 201);
+  }
+
+  // POST /api/sources/sync
+  if (req.method === 'POST' && pathname === '/api/sources/sync') {
+    if (ctx.syncRemotes) {
+      try {
+        await ctx.syncRemotes();
+        return jsonResponse(res, { ok: true, message: 'Sync complete' });
+      } catch (err) {
+        return jsonResponse(res, { error: err.message }, 500);
+      }
+    }
+    return jsonResponse(res, { ok: true, message: 'No remote sources' });
+  }
+
+  // --- Dynamic CRUD routes ---
+
+  // Match /api/:plural or /api/:plural/:id
+  const crudMatch = pathname.match(/^\/api\/([\w-]+?)(?:\/([\w:.-]+))?$/);
+  if (crudMatch) {
+    const plural = crudMatch[1];
+    const id = crudMatch[2] ? decodeURIComponent(crudMatch[2]) : null;
+    const entityType = routeMap[plural];
+
+    if (entityType) {
+      return handleCrud(req, res, ctx, url, cfg, routeMap, entityType, id);
+    }
+  }
+
+  return jsonResponse(res, { error: 'Not found' }, 404);
+}
+
+// --- Dynamic CRUD handler ---
+
+async function handleCrud(req, res, ctx, url, cfg, routeMap, entityType, id, sourceName) {
+  const { model } = ctx;
+  const items = model.entities[entityType] || [];
+
+  // GET list
+  if (req.method === 'GET' && !id) {
+    const filtered = filterEntities(items, cfg, entityType, url);
+    const formatted = filtered.map(item => formatEntity(item, cfg, entityType, false));
+    return jsonResponse(res, formatted);
+  }
+
+  // GET single
+  if (req.method === 'GET' && id) {
+    const item = items.find(i => i.id === id) || items.find(i => i._originalId === id);
+    if (!item) return jsonResponse(res, { error: entityType + ' not found: ' + id }, 404);
+    return jsonResponse(res, formatEntity(item, cfg, entityType, true, ctx));
+  }
+
+  // POST create
+  if (req.method === 'POST' && !id) {
+    const body = await parseBody(req);
+
+    // Resolve source
+    let targetSource = sourceName || null;
+    if (!targetSource && ctx.sources && ctx.sources.length > 0) {
+      if (body._source) {
+        targetSource = body._source;
+      } else {
+        const writable = ctx.sources.filter(s =>
+          !(s.readonly != null ? s.readonly : (s.type === 'remote'))
+        );
+        targetSource = writable.length > 0 ? writable[0].name
+          : (ctx.sources.find(s => !(s.readonly != null ? s.readonly : (s.type === 'remote')))?.name || null);
+      }
+    }
+
+    if (!ctx.createItem) return jsonResponse(res, { error: 'Create not supported' }, 400);
+
+    try {
+      const result = ctx.createItem(targetSource, entityType, body);
+      if (ctx.rescanAll) ctx.rescanAll();
+      if (ctx.broadcast) ctx.broadcast({ type: 'update', timestamp: new Date().toISOString() });
+      return jsonResponse(res, { ok: true, ...result }, 201);
+    } catch (err) {
+      return jsonResponse(res, { error: err.message }, 400);
+    }
+  }
+
+  // PATCH update
+  if (req.method === 'PATCH' && id) {
+    const item = items.find(i => i.id === id) || items.find(i => i._originalId === id);
+    if (!item) return jsonResponse(res, { error: entityType + ' not found: ' + id }, 404);
+    if (item._readonly) return jsonResponse(res, { error: 'This item is read-only (remote source)' }, 403);
+
+    const body = await parseBody(req);
+    try {
+      if (ctx.updateFile) ctx.updateFile(item._source || null, item._file, body);
+      if (ctx.rescanAll) ctx.rescanAll();
+      if (ctx.broadcast) ctx.broadcast({ type: 'update', timestamp: new Date().toISOString() });
+      return jsonResponse(res, { ok: true });
+    } catch (err) {
+      return jsonResponse(res, { error: err.message }, 500);
+    }
+  }
+
+  // DELETE
+  if (req.method === 'DELETE' && id) {
+    const item = items.find(i => i.id === id) || items.find(i => i._originalId === id);
+    if (!item) return jsonResponse(res, { error: entityType + ' not found: ' + id }, 404);
+    if (item._readonly) return jsonResponse(res, { error: 'This item is read-only (remote source)' }, 403);
+
+    try {
+      if (ctx.deleteItem) ctx.deleteItem(item._source || null, item);
+      if (ctx.rescanAll) ctx.rescanAll();
+      if (ctx.broadcast) ctx.broadcast({ type: 'update', timestamp: new Date().toISOString() });
+      return jsonResponse(res, { ok: true, deleted: true });
+    } catch (err) {
+      return jsonResponse(res, { error: err.message }, 500);
+    }
+  }
+
+  return jsonResponse(res, { error: 'Method not allowed' }, 405);
+}
+
+// --- Source-scoped routes ---
+
+async function handleSourceRoute(req, res, ctx, url, routeMap, sourceName, subPath) {
+  const { model, config: cfg, sources } = ctx;
+
+  const source = sources ? sources.find(s => s.name === sourceName) : null;
+  if (!source) return jsonResponse(res, { error: 'Source not found: ' + sourceName }, 404);
+
+  const isReadonly = source.readonly != null ? source.readonly : (source.type === 'remote');
+
+  // Check readonly for write operations
+  if ((req.method === 'POST' || req.method === 'DELETE') && isReadonly) {
+    return jsonResponse(res, { error: 'Source is read-only' }, 403);
+  }
+
+  // Parse subPath: could be "tasks", "tasks/TASK-001", etc.
+  const decodedSubPath = decodeURIComponent(subPath);
+  const subMatch = decodedSubPath.match(/^([\w-]+?)(?:\/([\w:.-]+))?$/);
+  if (!subMatch) return jsonResponse(res, { error: 'Not found' }, 404);
+
+  const plural = subMatch[1];
+  const id = subMatch[2] || null;
+  const entityType = routeMap[plural];
+
+  if (!entityType) return jsonResponse(res, { error: 'Not found' }, 404);
+
+  // Filter model items by source
+  const items = (model.entities[entityType] || []).filter(i => i._source === sourceName);
+
+  // Create a source-filtered context for CRUD
+  const sourceModel = { ...model, entities: { ...model.entities, [entityType]: items } };
+  const sourceCtx = { ...ctx, model: sourceModel };
+
+  return handleCrud(req, res, sourceCtx, url, cfg, routeMap, entityType, id, sourceName);
+}
+
+// --- Utility ---
+
+function getLeafType(cfg) {
+  const flat = flattenHierarchy(cfg);
+  const hierarchyEntities = flat.filter(e => !e.standalone);
+  return hierarchyEntities.length > 0 ? hierarchyEntities[hierarchyEntities.length - 1].type : null;
+}
+
+module.exports = { handleApi, jsonResponse, buildRouteMap, formatEntity, filterEntities, computeMetrics, computeHealth };