mdboard 1.0.0 → 1.2.0

package/api.js

@@ -0,0 +1,752 @@
+/**
+ * mdboard — 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
+ */
+
+const { URL } = require('url');
+
+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({}); }
+    });
+  });
+}
+
+/**
+ * Build PATCH route map from config.
+ */
+function buildPatchMap(config) {
+  const map = {
+    features: 'tasks', tasks: 'tasks',
+    epics: 'epics', milestones: 'milestones', sprints: 'sprints',
+  };
+  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';
+  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,
+  };
+}
+
+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,
+    ...sourceFields(f),
+  };
+}
+
+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,
+    ...sourceFields(ms),
+  };
+}
+
+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,
+    ...sourceFields(e),
+  };
+}
+
+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),
+  };
+}
+
+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');
+
+  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);
+
+  return tasks;
+}
+
+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);
+  }
+
+  return {
+    status: 'ok',
+    activeMilestone: activeMilestone ? activeMilestone.id : null,
+    activeSprint: activeSprint ? activeSprint.id : null,
+    totalFeatures,
+    completedFeatures,
+    inProgressFeatures,
+    velocity,
+  };
+}
+
+/**
+ * Get items filtered by source name from the global model.
+ */
+function itemsBySource(model, sourceName) {
+  const filter = (arr) => arr.filter(x => x._source === sourceName);
+  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),
+    metrics: model.metrics && model.metrics._source === sourceName ? model.metrics : 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)
+ */
+async function handleApi(req, res, ctx) {
+  const { model, config, 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();
+  }
+
+  // ─── Source-scoped routes: /api/sources/:name/... ───────────────────
+  const sourceMatch = pathname.match(/^\/api\/sources\/([^/]+)\/(.+)$/);
+  if (sourceMatch) {
+    const sourceName = decodeURIComponent(sourceMatch[1]);
+    const subPath = sourceMatch[2];
+    return handleSourceRoute(req, res, ctx, url, sourceName, subPath);
+  }
+
+  // ─── Overview routes: /api/overview/... ─────────────────────────────
+  if (pathname.startsWith('/api/overview/')) {
+    return handleOverviewRoute(req, res, ctx, url, pathname);
+  }
+
+  // ─── POST routes ────────────────────────────────────────────────────
+  if (req.method === 'POST') {
+    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' };
+    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);
+  }
+
+  // ─── 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);
+  }
+
+  // ─── 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 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,
+      };
+      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 || {});
+
+    case '/api/milestones':
+      return jsonResponse(res, model.milestones.map(formatMilestone));
+
+    case '/api/epics':
+      return jsonResponse(res, model.epics.map(formatEpic));
+
+    case '/api/tasks':
+    case '/api/features':
+      return jsonResponse(res, filterTasks(model.tasks.map(formatTask), url));
+
+    case '/api/sprints':
+      return jsonResponse(res, model.sprints.map(formatSprint));
+
+    case '/api/sprint': {
+      const activeSprint = model.sprints.find(s => s.status === 'active');
+      if (!activeSprint) return jsonResponse(res, null);
+
+      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,
+      });
+    }
+
+    case '/api/metrics':
+      return jsonResponse(res, model.metrics || {});
+
+    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/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;
+    }
+
+    default:
+      return jsonResponse(res, { error: 'Not found' }, 404);
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// 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') {
+    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':
+        return jsonResponse(res, sourceModel.project || {});
+
+      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));
+
+      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,
+        });
+      }
+
+      case 'health':
+        return jsonResponse(res, computeHealth(sourceModel, config));
+
+      case 'metrics':
+        return jsonResponse(res, sourceModel.metrics || {});
+
+      default:
+        return jsonResponse(res, { error: 'Not found' }, 404);
+    }
+  }
+
+  // ── 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' };
+    if (entityMap[subPath] && ctx.createItem) {
+      const body = await parseBody(req);
+      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);
+      } catch (err) {
+        return jsonResponse(res, { error: err.message }, 400);
+      }
+    }
+
+    return jsonResponse(res, { error: 'Not found' }, 404);
+  }
+
+  // ── 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);
+  }
+
+  // ── DELETE routes: /api/sources/:name/:entity/:id ──
+  if (req.method === 'DELETE') {
+    if (isReadonly) {
+      return jsonResponse(res, { error: 'Source is read-only' }, 403);
+    }
+
+    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);
+      }
+    }
+    return jsonResponse(res, { error: 'Not found' }, 404);
+  }
+
+  return jsonResponse(res, { error: 'Method not allowed' }, 405);
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Overview routes
+// ═══════════════════════════════════════════════════════════════════════
+
+function handleOverviewRoute(req, res, ctx, url, pathname) {
+  const { model, config } = ctx;
+
+  if (req.method !== 'GET') {
+    return jsonResponse(res, { error: 'Method not allowed' }, 405);
+  }
+
+  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);
+    }
+
+    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,
+            });
+          }
+        }
+      }
+
+      // 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 });
+      }
+
+      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),
+          };
+        }
+      }
+
+      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,
+      });
+    }
+
+    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;
+  }
+
+  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);
+  }
+
+  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);
+  }
+}
+
+async function handleDelete(req, res, ctx, collection, id, sourceName) {
+  const { model } = ctx;
+
+  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;
+  };
+
+  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;
+  }
+
+  if (!item) return jsonResponse(res, { error: collection.slice(0, -1) + ' not found: ' + id }, 404);
+
+  if (item._readonly) {
+    return jsonResponse(res, { error: 'This item is read-only (remote source)' }, 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);
+  }
+}
+
+async function handleLegacyCreate(req, res, ctx, collection) {
+  const body = await parseBody(req);
+
+  // 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 (!ctx.createItem) {
+    return jsonResponse(res, { error: 'Create not supported' }, 400);
+  }
+
+  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);
+  }
+}
+
+module.exports = { handleApi, jsonResponse, buildPatchMap };