mdboard 1.3.0 → 2.1.0

package/src/server/api.js

@@ -1,20 +1,25 @@
 /**
- * mdboard — API handlers
+ * mdboard — Dynamic API handlers
  *
- * All REST API route handlers. Receives a context object with
- * model, config, and helper functions.
- *
- * Supports:
- *  - Source-scoped routes: /api/sources/:name/tasks, etc.
- *  - Overview routes: /api/overview/milestones, etc.
- *  - Legacy routes: /api/tasks, etc. (backward compatible)
- *  - CRUD: POST to create, DELETE to archive
+ * 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 { resolveTheme } = require('../core/config');
+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, {
@@ -37,198 +42,195 @@ function parseBody(req) {
   });
 }
 
+// --- Route map ---
+
 /**
- * Build PATCH route map from config.
+ * Build a map of pluralName → entityType from config.
+ * e.g. "tasks" → "task", "cycles" → "cycle"
  */
-function buildPatchMap(config) {
-  const map = {
-    features: 'tasks', tasks: 'tasks',
-    epics: 'epics', milestones: 'milestones', sprints: 'sprints',
-    notes: 'notes',
-  };
-  map[config.entities.task.plural.toLowerCase()] = 'tasks';
-  map[config.entities.epic.plural.toLowerCase()] = 'epics';
-  map[config.entities.milestone.plural.toLowerCase()] = 'milestones';
-  map[config.entities.sprint.plural.toLowerCase()] = 'sprints';
+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;
 }
 
-function sourceFields(item) {
-  if (!item._source) return {};
-  return {
-    source: item._source,
-    sourceLabel: item._sourceLabel || item._source,
-    sourceColor: item._sourceColor || null,
-    readonly: item._readonly || false,
-    author: item._author || null,
-  };
-}
+// --- Generic formatters ---
 
-function formatTask(f) {
-  return {
-    id: f.id,
-    title: f.title,
-    epic: f._epic || f.epic,
-    milestone: f._milestone || f.milestone,
-    sprint: f.sprint,
-    status: f.status,
-    priority: f.priority,
-    points: f.points,
-    assigned: f.assigned,
-    branches: f.branches,
-    pull_requests: f.pull_requests,
-    links: f.links || null,
-    created: f.created,
-    started: f.started,
-    completed: f.completed,
-    content: f.content,
-    ai: f._ai && Object.keys(f._ai).length > 0 ? f._ai : undefined,
-    aiOwn: f._aiOwn && Object.keys(f._aiOwn).length > 0 ? f._aiOwn : undefined,
-    ...sourceFields(f),
-  };
-}
+/**
+ * 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];
+    }
+  }
 
-function formatMilestone(ms) {
-  return {
-    id: ms.id,
-    title: ms.title,
-    status: ms.status,
-    deadline: ms.deadline,
-    tracks: ms.tracks || null,
-    progress: ms._progress || 0,
-    featureCount: ms._featureCount || 0,
-    completedCount: ms._completedCount || 0,
-    created: ms.created,
-    content: ms.content,
-    ai: ms._ai && Object.keys(ms._ai).length > 0 ? ms._ai : undefined,
-    aiOwn: ms._aiOwn && Object.keys(ms._aiOwn).length > 0 ? ms._aiOwn : undefined,
-    ...sourceFields(ms),
-  };
-}
+  // 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;
+  }
 
-function formatEpic(e) {
-  return {
-    id: e.id,
-    title: e.title,
-    milestone: e._milestone,
-    status: e.status,
-    priority: e.priority,
-    dependencies: e.dependencies,
-    featureCount: e._featureCount || 0,
-    completedCount: e._completedCount || 0,
-    totalPoints: e._totalPoints || 0,
-    progress: e._progress || 0,
-    content: e.content,
-    ai: e._ai && Object.keys(e._ai).length > 0 ? e._ai : undefined,
-    aiOwn: e._aiOwn && Object.keys(e._aiOwn).length > 0 ? e._aiOwn : undefined,
-    ...sourceFields(e),
-  };
-}
+  // Ancestor refs
+  const ancestors = getAncestors(cfg, type);
+  for (const anc of ancestors) {
+    if (item['_' + anc] !== undefined) result['_' + anc] = item['_' + anc];
+  }
 
-function formatSprint(s) {
-  return {
-    id: s.id,
-    milestone: s._milestone,
-    status: s.status,
-    goal: s.goal,
-    start_date: s.start_date,
-    end_date: s.end_date,
-    planned_points: s.planned_points,
-    completed_points: s.completed_points,
-    features: s.features,
-    ...sourceFields(s),
-  };
-}
+  // Content — lazy-loaded from disk
+  if (includeContent && ctx) {
+    result.content = loadItemContent(item, ctx) || '';
+  }
 
-function formatNote(n, includeContent) {
-  const result = {
-    id: n.id,
-    title: n.title,
-    created: n.created,
-    updated: n.updated,
-    ...sourceFields(n),
-  };
-  if (includeContent) result.content = n.content;
   return result;
 }
 
-function filterTasks(tasks, url) {
-  const status = url.searchParams.get('status');
-  const epic = url.searchParams.get('epic');
-  const milestone = url.searchParams.get('milestone');
-  const sprint = url.searchParams.get('sprint');
-  const source = url.searchParams.get('source');
+/**
+ * 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;
+    });
+  }
 
-  if (status) tasks = tasks.filter(f => f.status === status);
-  if (epic) tasks = tasks.filter(f => f.epic === epic);
-  if (milestone) tasks = tasks.filter(f => f.milestone === milestone);
-  if (sprint) tasks = tasks.filter(f => f.sprint === sprint);
-  if (source) tasks = tasks.filter(f => f.source === source);
+  // Special: source filter
+  const source = url.searchParams.get('source');
+  if (source) {
+    items = items.filter(item => item._source === source);
+  }
 
-  return tasks;
+  return items;
 }
 
-function computeHealth(model, config) {
-  const completedStatus = config.completedStatus;
-  const inProgressStatus = (config.statuses.task.find(s => s.icon === 'half-circle') || {}).key || 'in-progress';
-
-  const activeMilestone = model.milestones.find(m => m.status === 'active');
-  const activeSprint = model.sprints.find(s => s.status === 'active');
-  const totalFeatures = model.tasks.length;
-  const completedFeatures = model.tasks.filter(f => f.status === completedStatus).length;
-  const inProgressFeatures = model.tasks.filter(f => f.status === inProgressStatus).length;
-
-  const completedSprints = model.sprints.filter(s => s.status === 'completed');
-  let velocity = null;
-  if (completedSprints.length > 0) {
-    const totalVelocity = completedSprints.reduce((sum, s) => {
-      const planned = s.planned_points || 1;
-      const completed = s.completed_points || 0;
-      return sum + Math.round((completed / planned) * 100);
-    }, 0);
-    velocity = Math.round(totalVelocity / completedSprints.length);
+/**
+ * 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 {
-    status: 'ok',
-    activeMilestone: activeMilestone ? activeMilestone.id : null,
-    activeSprint: activeSprint ? activeSprint.id : null,
-    totalFeatures,
-    completedFeatures,
-    inProgressFeatures,
-    velocity,
-  };
+  return result;
 }
 
 /**
- * Get items filtered by source name from the global model.
+ * Compute health status.
  */
-function itemsBySource(model, sourceName) {
-  const filter = (arr) => arr.filter(x => x._source === sourceName);
+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 {
-    project: model.project && model.project._source === sourceName ? model.project : null,
-    milestones: filter(model.milestones),
-    epics: filter(model.epics),
-    tasks: filter(model.tasks),
-    sprints: filter(model.sprints),
-    boards: filter(model.boards),
-    reviews: filter(model.reviews),
-    notes: filter(model.notes),
+    status: 'ok',
+    totals: { total, completed, inProgress },
+    active: activeTop ? { type: topType, id: activeTop.id, title: activeTop.title } : null,
   };
 }
 
-/**
- * Handle all API requests.
- *
- * @param {object} req - HTTP request
- * @param {object} res - HTTP response
- * @param {object} ctx - Context object:
- *   model, config, port, projectDir, broadcast, sources, sourceStates,
- *   updateFile(sourceName, relFile, updates), rescanAll(), syncRemotes(),
- *   createItem(sourceName, collection, data), archiveItem(sourceName, collection, id)
- */
+// --- Main API handler ---
+
 async function handleApi(req, res, ctx) {
-  const { model, config, port, sources } = ctx;
+  const { model, config: cfg, port, sources } = ctx;
   const url = new URL(req.url, `http://localhost:${port}`);
   const pathname = url.pathname;
 
@@ -242,652 +244,373 @@ async function handleApi(req, res, ctx) {
     return res.end();
   }
 
-  // ─── Source-scoped routes: /api/sources/:name/... ───────────────────
+  const routeMap = buildRouteMap(cfg);
+
+  // --- Source-scoped routes: /api/sources/:name/... ---
   const sourceMatch = pathname.match(/^\/api\/sources\/([^/]+)\/(.+)$/);
-  if (sourceMatch) {
+  if (sourceMatch && sourceMatch[2] !== 'sync') {
     const sourceName = decodeURIComponent(sourceMatch[1]);
     const subPath = sourceMatch[2];
-    return handleSourceRoute(req, res, ctx, url, sourceName, subPath);
+    return handleSourceRoute(req, res, ctx, url, routeMap, sourceName, subPath);
   }
 
-  // ─── Overview routes: /api/overview/... ─────────────────────────────
-  if (pathname.startsWith('/api/overview/')) {
-    return handleOverviewRoute(req, res, ctx, url, pathname);
-  }
-
-  // ─── GET /api/history ───────────────────────────────────────────────
-  if (req.method === 'GET' && pathname === '/api/history') {
-    if (ctx.getProjectHistory) {
-      return jsonResponse(res, ctx.getProjectHistory());
+  // --- 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, []);
+    return jsonResponse(res, result);
   }
 
-  // ─── POST routes ────────────────────────────────────────────────────
-  if (req.method === 'POST') {
-    if (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) || require('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);
-    }
-
-    if (pathname === '/api/theme') {
-      const body = await parseBody(req);
-      if (!body.themeId || !body.css) {
-        return jsonResponse(res, { error: 'Missing themeId or css' }, 400);
-      }
-
-      const path = require('path');
-      const os = require('os');
-
-      if (body.setDefault) {
-        // Global: write CSS to ~/.config/mdboard/mdboard.css
-        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');
-        // Also save theme ID in config JSON
-        const configPath = path.join(globalDir, 'mdboard.json');
-        let cfg = {};
-        try { cfg = JSON.parse(fs.readFileSync(configPath, 'utf-8')); } catch {}
-        cfg.theme = body.themeId;
-        fs.writeFileSync(configPath, JSON.stringify(cfg, null, 2) + '\n', 'utf-8');
-      } else {
-        // Local: write CSS to project/mdboard.css
-        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');
-      }
-
-      return jsonResponse(res, { ok: true });
-    }
-
-    if (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' });
-    }
-
-    // Legacy CRUD: POST /api/tasks, /api/milestones, etc.
-    const postMap = { tasks: 'tasks', milestones: 'milestones', epics: 'epics', sprints: 'sprints', notes: 'notes' };
-    const postMatch = pathname.match(/^\/api\/([\w-]+)$/);
-    if (postMatch && postMap[postMatch[1]]) {
-      return handleLegacyCreate(req, res, ctx, postMap[postMatch[1]]);
-    }
-
-    return jsonResponse(res, { error: 'Not found' }, 404);
+  // GET /api/project
+  if (req.method === 'GET' && pathname === '/api/project') {
+    return jsonResponse(res, model.project || {});
   }
 
-  // ─── DELETE routes (legacy): DELETE /api/:collection/:id ────────────
-  if (req.method === 'DELETE') {
-    const deleteMatch = pathname.match(/^\/api\/([\w-]+)\/(.+)$/);
-    if (deleteMatch) {
-      const patchMap = buildPatchMap(config);
-      const collection = patchMap[deleteMatch[1]];
-      if (collection) {
-        return handleDelete(req, res, ctx, collection, decodeURIComponent(deleteMatch[2]));
-      }
-    }
-    return jsonResponse(res, { error: 'Not found' }, 404);
+  // 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,
+      };
+    }));
   }
 
-  // ─── PATCH routes (legacy) ──────────────────────────────────────────
-  if (req.method === 'PATCH') {
-    const match = pathname.match(/^\/api\/([\w-]+)\/(.+)$/);
-    if (match) {
-      const patchMap = buildPatchMap(config);
-      const collection = patchMap[match[1]];
-      if (collection) {
-        return handlePatch(req, res, collection, decodeURIComponent(match[2]), ctx);
-      }
-    }
-    return jsonResponse(res, { error: 'Not found' }, 404);
+  // GET /api/metrics
+  if (req.method === 'GET' && pathname === '/api/metrics') {
+    return jsonResponse(res, computeMetrics(model, cfg));
   }
 
-  // ─── GET /api/notes/:id ─────────────────────────────────────────────
-  if (req.method === 'GET') {
-    const noteMatch = pathname.match(/^\/api\/notes\/(.+)$/);
-    if (noteMatch) {
-      const noteId = decodeURIComponent(noteMatch[1]);
-      const note = model.notes.find(n => n.id === noteId);
-      if (!note) return jsonResponse(res, { error: 'Note not found: ' + noteId }, 404);
-      return jsonResponse(res, formatNote(note, true));
-    }
+  // GET /api/health
+  if (req.method === 'GET' && pathname === '/api/health') {
+    return jsonResponse(res, computeHealth(model, cfg));
   }
 
-  // ─── GET routes (legacy + global) ──────────────────────────────────
-  switch (pathname) {
-    case '/api/config': {
-      const result = {
-        entities: config.entities,
-        statuses: config.statuses,
-        priorities: config.priorities,
-        boardColumns: config.boardColumns,
-        completedStatus: config.completedStatus,
-      };
-      const theme = resolveTheme(ctx.projectDir, process.env.MDBOARD_CONFIG);
-      result.theme = theme || null;
-      result.hasProject = ctx.hasProject != null ? ctx.hasProject : true;
-      result.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);
-    }
-
-    case '/api/project':
-      return jsonResponse(res, model.project || {});
+  // GET /api/status
+  if (req.method === 'GET' && pathname === '/api/status') {
+    return jsonResponse(res, computeStatus(model, cfg));
+  }
 
-    case '/api/milestones':
-      return jsonResponse(res, model.milestones.map(formatMilestone));
+  // 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() : []);
+  }
 
-    case '/api/epics':
-      return jsonResponse(res, model.epics.map(formatEpic));
+  // 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`);
 
-    case '/api/tasks':
-    case '/api/features':
-      return jsonResponse(res, filterTasks(model.tasks.map(formatTask), url));
+    if (ctx.sseClients) ctx.sseClients.add(res);
 
-    case '/api/sprints':
-      return jsonResponse(res, model.sprints.map(formatSprint));
+    const keepalive = setInterval(() => {
+      try { res.write(': keepalive\n\n'); } catch { /* client gone */ }
+    }, 30000);
 
-    case '/api/sprint': {
-      const activeSprint = model.sprints.find(s => s.status === 'active');
-      if (!activeSprint) return jsonResponse(res, null);
+    req.on('close', () => {
+      if (ctx.sseClients) ctx.sseClients.delete(res);
+      clearInterval(keepalive);
+    });
+    return;
+  }
 
-      const board = model.boards.find(b =>
-        b._dir === activeSprint._dir && b._milestone === activeSprint._milestone &&
-        (!activeSprint._source || b._source === activeSprint._source)
-      );
-      return jsonResponse(res, {
-        ...formatSprint(activeSprint),
-        board: board ? board.content : null,
-      });
+  // 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);
     }
 
-    case '/api/metrics': {
-      const cs = config.completedStatus;
-      return jsonResponse(res, {
-        totalTasks: model.tasks.length,
-        completedTasks: model.tasks.filter(t => t.status === cs).length,
-        totalMilestones: model.milestones.length,
-        totalEpics: model.epics.length,
-        totalPoints: model.tasks.reduce((sum, t) => sum + (t.points || 0), 0),
-        completedPoints: model.tasks.filter(t => t.status === cs).reduce((sum, t) => sum + (t.points || 0), 0),
-      });
+    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');
     }
 
-    case '/api/health':
-      return jsonResponse(res, computeHealth(model, config));
-
-    case '/api/sources': {
-      if (!sources || sources.length === 0) return jsonResponse(res, []);
-
-      return jsonResponse(res, sources.map(s => {
-        const sourceTasks = model.tasks.filter(t => t._source === s.name);
-        const completedStatus = config.completedStatus;
-        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 => t.status === completedStatus).length,
-          lastSync: s._lastSync || null,
-          error: s._error || null,
-        };
-      }));
-    }
-
-    case '/api/notes':
-      return jsonResponse(res, model.notes.map(function(n) { return formatNote(n, false); }));
-
-    case '/api/ai-suggestions':
-      return jsonResponse(res, ctx.getAiSuggestions ? ctx.getAiSuggestions() : { skills: [], agents: [], mcps: [], commands: [], context: [] });
-
-    case '/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`);
+    // 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 });
+  }
 
-      if (ctx.sseClients) {
-        ctx.sseClients.add(res);
+  // 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);
       }
-
-      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;
     }
-
-    default:
-      return jsonResponse(res, { error: 'Not found' }, 404);
+    return jsonResponse(res, { error: 'Project switching not available' }, 500);
   }
-}
 
-// ═══════════════════════════════════════════════════════════════════════
-// Source-scoped routes
-// ═══════════════════════════════════════════════════════════════════════
-
-async function handleSourceRoute(req, res, ctx, url, sourceName, subPath) {
-  const { model, config, sources } = ctx;
-
-  // Validate source
-  const source = sources ? sources.find(s => s.name === sourceName) : null;
-  if (!source) {
-    return jsonResponse(res, { error: 'Source not found: ' + sourceName }, 404);
-  }
-
-  const sourceModel = itemsBySource(model, sourceName);
-  const isReadonly = source.readonly != null ? source.readonly : (source.type === 'remote');
-
-  // ── GET routes ──
-  if (req.method === 'GET') {
-    // GET /api/sources/:name/notes/:id
-    const noteSubMatch = subPath.match(/^notes\/(.+)$/);
-    if (noteSubMatch) {
-      const noteId = decodeURIComponent(noteSubMatch[1]);
-      const note = (sourceModel.notes || []).find(n => n.id === noteId);
-      if (!note) return jsonResponse(res, { error: 'Note not found: ' + noteId }, 404);
-      return jsonResponse(res, formatNote(note, true));
+  // 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 = [];
 
-    switch (subPath) {
-      case 'config': {
-        // Source-specific config (from sourceStates if available)
-        const sourceState = ctx.sourceStates ? ctx.sourceStates.get(sourceName) : null;
-        const srcConfig = sourceState ? sourceState.config : config;
-        return jsonResponse(res, {
-          entities: srcConfig.entities,
-          statuses: srcConfig.statuses,
-          priorities: srcConfig.priorities,
-          boardColumns: srcConfig.boardColumns,
-          completedStatus: srcConfig.completedStatus,
-          source: { name: source.name, label: source.label, color: source.color, readonly: isReadonly },
-        });
-      }
-
-      case 'project': {
-        const sourceState = ctx.sourceStates ? ctx.sourceStates.get(sourceName) : null;
-        const proj = sourceState && sourceState.model ? sourceState.model.project : sourceModel.project;
-        return jsonResponse(res, proj || {});
-      }
-
-      case 'milestones':
-        return jsonResponse(res, sourceModel.milestones.map(formatMilestone));
-
-      case 'epics':
-        return jsonResponse(res, sourceModel.epics.map(formatEpic));
-
-      case 'tasks':
-        return jsonResponse(res, filterTasks(sourceModel.tasks.map(formatTask), url));
-
-      case 'sprints':
-        return jsonResponse(res, sourceModel.sprints.map(formatSprint));
+    // Check duplicates
+    if (ws.sources.some(s => s.name === body.name)) {
+      return jsonResponse(res, { error: 'A source with name "' + body.name + '" already exists' }, 400);
+    }
 
-      case 'sprint': {
-        const activeSprint = sourceModel.sprints.find(s => s.status === 'active');
-        if (!activeSprint) return jsonResponse(res, null);
-        const board = sourceModel.boards.find(b =>
-          b._dir === activeSprint._dir && b._milestone === activeSprint._milestone
-        );
-        return jsonResponse(res, {
-          ...formatSprint(activeSprint),
-          board: board ? board.content : null,
-        });
-      }
+    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;
 
-      case 'notes':
-        return jsonResponse(res, (sourceModel.notes || []).map(function(n) { return formatNote(n, false); }));
-
-      case 'health':
-        return jsonResponse(res, computeHealth(sourceModel, config));
-
-      case 'metrics': {
-        const cs2 = config.completedStatus;
-        return jsonResponse(res, {
-          totalTasks: sourceModel.tasks.length,
-          completedTasks: sourceModel.tasks.filter(t => t.status === cs2).length,
-          totalMilestones: sourceModel.milestones.length,
-          totalEpics: sourceModel.epics.length,
-          totalPoints: sourceModel.tasks.reduce((sum, t) => sum + (t.points || 0), 0),
-          completedPoints: sourceModel.tasks.filter(t => t.status === cs2).reduce((sum, t) => sum + (t.points || 0), 0),
-        });
-      }
+    ws.sources.push(entry);
+    fs.writeFileSync(wsPath, JSON.stringify(ws, null, 2) + '\n', 'utf-8');
 
-      default:
-        return jsonResponse(res, { error: 'Not found' }, 404);
-    }
+    if (ctx.onWorkspaceChange) ctx.onWorkspaceChange();
+    return jsonResponse(res, { ok: true, source: entry }, 201);
   }
 
-  // ── POST routes (create) ──
-  if (req.method === 'POST') {
-    if (isReadonly) {
-      return jsonResponse(res, { error: 'Source is read-only' }, 403);
-    }
-
-    const entityMap = { tasks: 'tasks', milestones: 'milestones', epics: 'epics', sprints: 'sprints', notes: 'notes' };
-    if (entityMap[subPath] && ctx.createItem) {
-      const body = await parseBody(req);
+  // POST /api/sources/sync
+  if (req.method === 'POST' && pathname === '/api/sources/sync') {
+    if (ctx.syncRemotes) {
       try {
-        const result = ctx.createItem(sourceName, entityMap[subPath], body);
-        if (ctx.rescanAll) ctx.rescanAll();
-        if (ctx.broadcast) ctx.broadcast({ type: 'update', timestamp: new Date().toISOString() });
-        return jsonResponse(res, { ok: true, ...result }, 201);
+        await ctx.syncRemotes();
+        return jsonResponse(res, { ok: true, message: 'Sync complete' });
       } catch (err) {
-        return jsonResponse(res, { error: err.message }, 400);
+        return jsonResponse(res, { error: err.message }, 500);
       }
     }
-
-    return jsonResponse(res, { error: 'Not found' }, 404);
+    return jsonResponse(res, { ok: true, message: 'No remote sources' });
   }
 
-  // ── PATCH routes: /api/sources/:name/:entity/:id ──
-  if (req.method === 'PATCH') {
-    const patchMatch = subPath.match(/^([\w-]+)\/(.+)$/);
-    if (patchMatch) {
-      const patchMap = buildPatchMap(config);
-      const collection = patchMap[patchMatch[1]];
-      if (collection) {
-        const id = decodeURIComponent(patchMatch[2]);
-        return handlePatch(req, res, collection, id, ctx, sourceName);
-      }
-    }
-    return jsonResponse(res, { error: 'Not found' }, 404);
-  }
+  // --- Dynamic CRUD routes ---
 
-  // ── DELETE routes: /api/sources/:name/:entity/:id ──
-  if (req.method === 'DELETE') {
-    if (isReadonly) {
-      return jsonResponse(res, { error: 'Source is read-only' }, 403);
-    }
+  // 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];
 
-    const deleteMatch = subPath.match(/^([\w-]+)\/(.+)$/);
-    if (deleteMatch) {
-      const patchMap = buildPatchMap(config);
-      const collection = patchMap[deleteMatch[1]];
-      if (collection) {
-        const id = decodeURIComponent(deleteMatch[2]);
-        return handleDelete(req, res, ctx, collection, id, sourceName);
-      }
+    if (entityType) {
+      return handleCrud(req, res, ctx, url, cfg, routeMap, entityType, id);
     }
-    return jsonResponse(res, { error: 'Not found' }, 404);
   }
 
-  return jsonResponse(res, { error: 'Method not allowed' }, 405);
+  return jsonResponse(res, { error: 'Not found' }, 404);
 }
 
-// ═══════════════════════════════════════════════════════════════════════
-// Overview routes
-// ═══════════════════════════════════════════════════════════════════════
+// --- Dynamic CRUD handler ---
 
-function handleOverviewRoute(req, res, ctx, url, pathname) {
-  const { model, config } = ctx;
+async function handleCrud(req, res, ctx, url, cfg, routeMap, entityType, id, sourceName) {
+  const { model } = ctx;
+  const items = model.entities[entityType] || [];
 
-  if (req.method !== 'GET') {
-    return jsonResponse(res, { error: 'Method not allowed' }, 405);
+  // 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);
   }
 
-  switch (pathname) {
-    case '/api/overview/milestones': {
-      // Global milestones with tracked sub-milestone progress
-      const globalMs = model.milestones.map(ms => {
-        const formatted = formatMilestone(ms);
-
-        // If this milestone has `tracks`, compute combined progress
-        if (ms.tracks && Array.isArray(ms.tracks)) {
-          const tracked = [];
-          for (const ref of ms.tracks) {
-            const parts = String(ref).split(':');
-            if (parts.length === 2) {
-              const [srcName, msId] = parts;
-              const sub = model.milestones.find(m =>
-                (m._source === srcName) && (m.id === ref || m._originalId === msId || m.id === msId)
-              );
-              if (sub) {
-                tracked.push({
-                  ref,
-                  source: sub._source,
-                  sourceColor: sub._sourceColor,
-                  id: sub.id,
-                  title: sub.title,
-                  progress: sub._progress || 0,
-                  featureCount: sub._featureCount || 0,
-                  completedCount: sub._completedCount || 0,
-                });
-              }
-            }
-          }
-          formatted.tracked = tracked;
-          if (tracked.length > 0) {
-            const totalFeatures = tracked.reduce((s, t) => s + t.featureCount, 0);
-            const totalCompleted = tracked.reduce((s, t) => s + t.completedCount, 0);
-            formatted.combinedProgress = totalFeatures > 0 ? Math.round((totalCompleted / totalFeatures) * 100) : 0;
-          }
-        }
-        return formatted;
-      });
-      return jsonResponse(res, globalMs);
-    }
+  // 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));
+  }
 
-    case '/api/overview/links': {
-      // Collect all cross-project links
-      const links = [];
-      for (const task of model.tasks) {
-        if (task.links && Array.isArray(task.links)) {
-          for (const link of task.links) {
-            links.push({
-              from: task.id,
-              fromSource: task._source || null,
-              fromSourceColor: task._sourceColor || null,
-              to: link,
-              toSource: String(link).split(':')[0] || null,
-            });
-          }
-        }
-      }
+  // POST create
+  if (req.method === 'POST' && !id) {
+    const body = await parseBody(req);
 
-      // Compute reverse links
-      const reverseMap = {};
-      for (const link of links) {
-        if (!reverseMap[link.to]) reverseMap[link.to] = [];
-        reverseMap[link.to].push({ from: link.from, source: link.fromSource, sourceColor: link.fromSourceColor });
+    // 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);
       }
-
-      return jsonResponse(res, { links, reverseLinks: reverseMap });
     }
 
-    case '/api/overview/metrics': {
-      // Aggregated metrics across all sources
-      const completedStatus = config.completedStatus;
-      const sourceMetrics = {};
-
-      if (ctx.sources) {
-        for (const s of ctx.sources) {
-          const tasks = model.tasks.filter(t => t._source === s.name);
-          sourceMetrics[s.name] = {
-            label: s.label || s.name,
-            color: s.color || null,
-            totalTasks: tasks.length,
-            completedTasks: tasks.filter(t => t.status === completedStatus).length,
-            totalPoints: tasks.reduce((sum, t) => sum + (t.points || 0), 0),
-          };
-        }
-      }
+    if (!ctx.createItem) return jsonResponse(res, { error: 'Create not supported' }, 400);
 
-      return jsonResponse(res, {
-        totalTasks: model.tasks.length,
-        completedTasks: model.tasks.filter(t => t.status === completedStatus).length,
-        totalMilestones: model.milestones.length,
-        totalEpics: model.epics.length,
-        sources: sourceMetrics,
-      });
+    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);
     }
-
-    default:
-      return jsonResponse(res, { error: 'Not found' }, 404);
-  }
-}
-
-// ═══════════════════════════════════════════════════════════════════════
-// CRUD helpers
-// ═══════════════════════════════════════════════════════════════════════
-
-async function handlePatch(req, res, collection, id, ctx, sourceName) {
-  const { model, config } = ctx;
-  const body = await parseBody(req);
-
-  // Resolve item — try exact id first, then try stripping source prefix
-  let item;
-  const findIn = (arr) => {
-    let found = arr.find(x => x.id === id);
-    if (!found) found = arr.find(x => x._originalId === id);
-    // If sourceName is provided, further filter
-    if (found && sourceName && found._source && found._source !== sourceName) found = null;
-    return found;
-  };
-
-  switch (collection) {
-    case 'tasks': item = findIn(model.tasks); break;
-    case 'epics': item = findIn(model.epics); break;
-    case 'milestones': item = findIn(model.milestones); break;
-    case 'sprints': item = findIn(model.sprints); break;
-    case 'notes': item = findIn(model.notes); break;
   }
 
-  if (!item) return jsonResponse(res, { error: collection.slice(0, -1) + ' not found: ' + id }, 404);
-
-  // Readonly guard
-  if (item._readonly) {
-    return jsonResponse(res, { error: 'This item is read-only (remote source)' }, 403);
+  // 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);
+    }
   }
 
-  try {
-    if (ctx.updateFile) {
-      ctx.updateFile(item._source || null, item._file, body);
+  // 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);
     }
-    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);
   }
+
+  return jsonResponse(res, { error: 'Method not allowed' }, 405);
 }
 
-async function handleDelete(req, res, ctx, collection, id, sourceName) {
-  const { model } = ctx;
+// --- Source-scoped routes ---
 
-  let item;
-  const findIn = (arr) => {
-    let found = arr.find(x => x.id === id);
-    if (!found) found = arr.find(x => x._originalId === id);
-    if (found && sourceName && found._source && found._source !== sourceName) found = null;
-    return found;
-  };
+async function handleSourceRoute(req, res, ctx, url, routeMap, sourceName, subPath) {
+  const { model, config: cfg, sources } = ctx;
 
-  switch (collection) {
-    case 'tasks': item = findIn(model.tasks); break;
-    case 'epics': item = findIn(model.epics); break;
-    case 'milestones': item = findIn(model.milestones); break;
-    case 'sprints': item = findIn(model.sprints); break;
-    case 'notes': item = findIn(model.notes); break;
-  }
+  const source = sources ? sources.find(s => s.name === sourceName) : null;
+  if (!source) return jsonResponse(res, { error: 'Source not found: ' + sourceName }, 404);
 
-  if (!item) return jsonResponse(res, { error: collection.slice(0, -1) + ' not found: ' + id }, 404);
+  const isReadonly = source.readonly != null ? source.readonly : (source.type === 'remote');
 
-  if (item._readonly) {
-    return jsonResponse(res, { error: 'This item is read-only (remote source)' }, 403);
+  // Check readonly for write operations
+  if ((req.method === 'POST' || req.method === 'DELETE') && isReadonly) {
+    return jsonResponse(res, { error: 'Source is read-only' }, 403);
   }
 
-  try {
-    if (ctx.archiveItem) {
-      ctx.archiveItem(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, archived: true });
-  } catch (err) {
-    return jsonResponse(res, { error: err.message }, 500);
-  }
-}
+  // 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);
 
-async function handleLegacyCreate(req, res, ctx, collection) {
-  const body = await parseBody(req);
+  const plural = subMatch[1];
+  const id = subMatch[2] || null;
+  const entityType = routeMap[plural];
 
-  // Resolve source: explicit _source from body, or legacy (no workspace) mode
-  let sourceName = null;
-  if (ctx.sources && ctx.sources.length > 0) {
-    if (body._source) {
-      sourceName = body._source;
-    } else {
-      // Prefer non-overview, non-readonly writable source
-      const writable = ctx.sources.filter(s =>
-        s.name !== 'overview' && !(s.readonly != null ? s.readonly : (s.type === 'remote'))
-      );
-      sourceName = writable.length > 0 ? writable[0].name
-        : (ctx.sources.find(s => !(s.readonly != null ? s.readonly : (s.type === 'remote')))?.name || null);
-    }
-  }
+  if (!entityType) return jsonResponse(res, { error: 'Not found' }, 404);
 
-  if (!ctx.createItem) {
-    return jsonResponse(res, { error: 'Create not supported' }, 400);
-  }
+  // Filter model items by source
+  const items = (model.entities[entityType] || []).filter(i => i._source === sourceName);
 
-  try {
-    const result = ctx.createItem(sourceName, collection, 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);
-  }
+  // 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, buildPatchMap };
+module.exports = { handleApi, jsonResponse, buildRouteMap, formatEntity, filterEntities, computeMetrics, computeHealth };