viteboard 0.1.2 → 0.1.4

package/bin/content-api-plugin.mjs

@@ -0,0 +1,722 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+const WORKSPACE_DIR = ".workspace";
+const WORKSPACE_FILE = "workspace.json";
+const IGNORE_DIRS = new Set([".git", "node_modules", "dist", "build", "coverage", ".next", "out"]);
+const MIME = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".md": "text/markdown; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+};
+const MIME_EXT = {
+  "image/png": ".png",
+  "image/jpeg": ".jpg",
+  "image/webp": ".webp",
+  "image/gif": ".gif",
+  "image/svg+xml": ".svg",
+};
+const MANAGED_ASSET_RE = /^assets\/[a-f0-9]{64}\.(png|jpe?g|webp|gif|svg)$/i;
+const ACTOR_TTL_MS = 30000;
+const LOCK_TTL_MS = 30000;
+const ROOT_LINK_HEADER = '</llms.txt>; rel="describedby"; type="text/plain", </.well-known/viteboard.json>; rel="alternate"; type="application/json"';
+
+export function createContentApiPlugin() {
+  const cwd = process.cwd();
+  const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+  const workspaceDir = path.resolve(cwd, WORKSPACE_DIR);
+  const workspaceFile = path.join(workspaceDir, WORKSPACE_FILE);
+  const machineDir = path.join(packageRoot, "content", "machine");
+  const actorSessions = new Map();
+  const locks = new Map();
+  const sseClients = new Set();
+
+  function send(res, status, body) {
+    res.statusCode = status;
+    res.setHeader("Content-Type", "application/json; charset=utf-8");
+    res.end(JSON.stringify(body));
+  }
+
+  function sendText(res, status, body, type) {
+    res.statusCode = status;
+    res.setHeader("Content-Type", type);
+    res.end(body);
+  }
+
+  function sendSse(res, event, body) {
+    res.write(`event: ${event}\n`);
+    res.write(`data: ${JSON.stringify(body)}\n\n`);
+  }
+
+  function broadcast(event, body) {
+    for (const client of sseClients) {
+      try { sendSse(client, event, body); } catch { sseClients.delete(client); }
+    }
+  }
+
+  function actorFromHeaders(req) {
+    const actorId = String(req.headers["x-viteboard-actor-id"] ?? "").trim();
+    if (!actorId) return null;
+    const actorType = String(req.headers["x-viteboard-actor-type"] ?? "human") === "agent" ? "agent" : "human";
+    const label = String(req.headers["x-viteboard-actor-label"] ?? "").trim() || (actorType === "agent" ? "Agent" : "ViteBoard UI");
+    return { actorId, actorType, label };
+  }
+
+  function lockKey(target) {
+    const suffix = target.targetType === "doc" ? target.path ?? "" : target.boardId ?? "";
+    return `${target.targetType}:${target.rootId}:${suffix}`;
+  }
+
+  function activeActors() { return [...actorSessions.values()].sort((a, b) => a.label.localeCompare(b.label)); }
+  function activeLocks() { return [...locks.values()].sort((a, b) => a.acquiredAt - b.acquiredAt); }
+  function broadcastPresence() { broadcast("presence", { actors: activeActors(), locks: activeLocks() }); }
+  function broadcastLocks() { broadcast("lock-changed", { locks: activeLocks() }); }
+
+  function pruneEphemeral() {
+    const now = Date.now();
+    let changedPresence = false;
+    let changedLocks = false;
+    for (const [actorId, actor] of actorSessions) {
+      if (actor.expiresAt <= now) {
+        actorSessions.delete(actorId);
+        changedPresence = true;
+      }
+    }
+    for (const [key, lock] of locks) {
+      if (lock.expiresAt <= now || !actorSessions.has(lock.actorId)) {
+        locks.delete(key);
+        changedLocks = true;
+      }
+    }
+    if (changedPresence) broadcastPresence();
+    else if (changedLocks) broadcastLocks();
+  }
+
+  setInterval(pruneEphemeral, 10000).unref?.();
+
+  function revisionForText(content) { return createHash("sha1").update(content).digest("hex"); }
+  function hashPath(value) {
+    let hash = 2166136261;
+    for (let i = 0; i < value.length; i++) {
+      hash ^= value.charCodeAt(i);
+      hash = Math.imul(hash, 16777619);
+    }
+    return (hash >>> 0).toString(36);
+  }
+
+  async function readMachineAsset(fileName) { return fs.readFile(path.join(machineDir, fileName), "utf-8"); }
+  async function ensureWorkspaceDir() { await fs.mkdir(workspaceDir, { recursive: true }); }
+  async function readBody(req) {
+    return new Promise((resolve, reject) => {
+      let data = "";
+      req.on("data", (chunk) => {
+        data += chunk;
+        if (data.length > 64 * 1024 * 1024) {
+          reject(new Error("Payload too large"));
+          req.destroy();
+        }
+      });
+      req.on("end", () => resolve(data));
+      req.on("error", reject);
+    });
+  }
+
+  async function canonicalizeProjectRoot(rootPath) {
+    const resolved = path.resolve(rootPath);
+    try { return path.resolve(await fs.realpath(resolved)); } catch { return resolved; }
+  }
+
+  function normalizeRelativePath(relPath) {
+    return relPath.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
+  }
+  function dirnamePosix(filePath) {
+    const normalized = normalizeRelativePath(filePath);
+    const idx = normalized.lastIndexOf("/");
+    return idx === -1 ? "" : normalized.slice(0, idx);
+  }
+  function resolveDocRelativePath(fromFile, target) {
+    const raw = String(target ?? "").trim();
+    if (!raw || /^(https?:|mailto:|tel:|#|data:)/i.test(raw)) return null;
+    if (raw.startsWith("/")) return normalizeRelativePath(raw);
+    const base = dirnamePosix(fromFile);
+    return normalizeRelativePath(base ? `${base}/${raw}` : raw);
+  }
+  function isManagedAssetPath(relPath) { return MANAGED_ASSET_RE.test(normalizeRelativePath(relPath)); }
+
+  async function collectFiles(dir, base = "") {
+    let entries;
+    try { entries = await fs.readdir(dir, { withFileTypes: true }); } catch { return []; }
+    const files = [];
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) continue;
+      const rel = base ? `${base}/${entry.name}` : entry.name;
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) files.push(...(await collectFiles(abs, rel)));
+      else files.push(rel);
+    }
+    return files;
+  }
+
+  function collectBoardAssetRefs(raw) {
+    const refs = new Set();
+    if (typeof raw !== "object" || raw === null) return refs;
+    const elements = Array.isArray(raw.elements) ? raw.elements : [];
+    for (const element of elements) {
+      if (typeof element !== "object" || element === null) continue;
+      const data = element.data;
+      const src = typeof data?.src === "string" ? normalizeRelativePath(data.src) : "";
+      if (isManagedAssetPath(src)) refs.add(src);
+    }
+    return refs;
+  }
+
+  function collectMarkdownAssetRefs(markdown, docPath) {
+    const refs = new Set();
+    const imagePatterns = [/!\[[^\]]*\]\(([^)\s]+)\)/g, /<img\b[^>]*\bsrc=["']([^"']+)["'][^>]*>/gi];
+    for (const pattern of imagePatterns) {
+      pattern.lastIndex = 0;
+      let match;
+      while ((match = pattern.exec(markdown))) {
+        const resolved = resolveDocRelativePath(docPath, match[1]);
+        if (resolved && isManagedAssetPath(resolved)) refs.add(resolved);
+      }
+    }
+    return refs;
+  }
+
+  async function cleanupManagedAssets(rootAbsPath, preservePaths = []) {
+    const allFiles = await collectFiles(rootAbsPath);
+    const managedAssets = allFiles.filter((file) => isManagedAssetPath(file));
+    if (managedAssets.length === 0) return 0;
+    const referenced = new Set();
+    for (const relPath of allFiles) {
+      const abs = safeResolve(rootAbsPath, relPath);
+      if (!abs) continue;
+      if (relPath.endsWith(".board.json")) {
+        try {
+          const raw = JSON.parse(await fs.readFile(abs, "utf-8"));
+          for (const ref of collectBoardAssetRefs(raw)) referenced.add(ref);
+        } catch {}
+        continue;
+      }
+      if (relPath.endsWith(".md")) {
+        try {
+          const markdown = await fs.readFile(abs, "utf-8");
+          for (const ref of collectMarkdownAssetRefs(markdown, relPath)) referenced.add(ref);
+        } catch {}
+      }
+    }
+    for (const relPath of preservePaths) {
+      const normalized = normalizeRelativePath(relPath);
+      if (isManagedAssetPath(normalized)) referenced.add(normalized);
+    }
+    let removed = 0;
+    for (const relPath of managedAssets) {
+      if (referenced.has(relPath)) continue;
+      const abs = safeResolve(rootAbsPath, relPath);
+      if (!abs) continue;
+      try { await fs.unlink(abs); removed++; } catch {}
+    }
+    return removed;
+  }
+
+  function isNestedPath(parent, child) {
+    const normalizedParent = parent.endsWith(path.sep) ? parent : parent + path.sep;
+    return child.startsWith(normalizedParent);
+  }
+
+  function overlapError(existing, candidateRoot) {
+    if (existing.rootPath === candidateRoot) return `"${existing.label}" is already added. Pick a different folder, or remove the existing project first.`;
+    if (isNestedPath(existing.rootPath, candidateRoot)) return `That folder is inside the existing workspace project "${existing.label}". ViteBoard only allows one project root per nested path.`;
+    return `That folder contains the existing workspace project "${existing.label}". Add the more specific project instead, or remove the current one first.`;
+  }
+
+  async function loadManifest() {
+    try {
+      const raw = await fs.readFile(workspaceFile, "utf-8");
+      const parsed = JSON.parse(raw);
+      const rawProjects = Array.isArray(parsed.projects) ? parsed.projects : [];
+      return {
+        version: 1,
+        projects: rawProjects.filter((project) => typeof project?.id === "string" && typeof project?.label === "string" && typeof project?.rootPath === "string"),
+      };
+    } catch { return { version: 1, projects: [] }; }
+  }
+
+  async function saveManifest(manifest) {
+    await ensureWorkspaceDir();
+    await fs.writeFile(workspaceFile, JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+  }
+
+  function rootDisplayPath(projectRoot, docsAbsPath) {
+    const rel = path.relative(projectRoot, docsAbsPath).replace(/\\/g, "/");
+    return rel === "" ? "docs" : rel;
+  }
+
+  function docsRootId(projectId, absPath) { return `root-${hashPath(`${projectId}:${absPath}`)}`; }
+  function projectIdFor(absRoot) { return `project-${hashPath(absRoot)}`; }
+
+  async function discoverDocsRoots(project) {
+    const roots = [];
+    const walk = async (dir) => {
+      let entries;
+      try { entries = await fs.readdir(dir, { withFileTypes: true }); } catch { return; }
+      for (const entry of entries) {
+        if (entry.name.startsWith(".") || IGNORE_DIRS.has(entry.name)) continue;
+        const abs = path.join(dir, entry.name);
+        if (!entry.isDirectory()) continue;
+        if (entry.name === "docs") {
+          const relativePath = normalizeRelativePath(path.relative(project.rootPath, abs));
+          roots.push({
+            id: docsRootId(project.id, abs),
+            projectId: project.id,
+            projectLabel: project.label,
+            absPath: abs,
+            relativePath,
+            displayPath: rootDisplayPath(project.rootPath, abs),
+          });
+        }
+        await walk(abs);
+      }
+    };
+    await walk(project.rootPath);
+    return roots.sort((a, b) => a.displayPath.localeCompare(b.displayPath));
+  }
+
+  async function getWorkspace() {
+    const manifest = await loadManifest();
+    const projects = [];
+    for (const project of manifest.projects) projects.push({ ...project, docsRoots: await discoverDocsRoots(project) });
+    return projects;
+  }
+
+  function toWorkspaceResponse(projects) {
+    return {
+      projects: projects.map((project) => ({
+        id: project.id,
+        label: project.label,
+        rootPath: project.rootPath,
+        docsRoots: project.docsRoots.map((root) => ({
+          id: root.id,
+          projectId: root.projectId,
+          projectLabel: root.projectLabel,
+          relativePath: root.relativePath,
+          displayPath: root.displayPath,
+        })),
+      })),
+    };
+  }
+
+  function safeResolve(root, rel) {
+    const abs = path.resolve(root, rel);
+    if (abs !== root && !abs.startsWith(root + path.sep)) return null;
+    return abs;
+  }
+
+  async function resolveRoot(rootId) {
+    const projects = await getWorkspace();
+    for (const project of projects) {
+      const root = project.docsRoots.find((item) => item.id === rootId);
+      if (root) {
+        const nestedRoots = new Set(project.docsRoots.filter((item) => item.id !== root.id && item.absPath.startsWith(root.absPath + path.sep)).map((item) => item.relativePath));
+        return { root, nestedRoots };
+      }
+    }
+    return null;
+  }
+
+  function boardIdFromFilePath(filePath) { return filePath.replace(/\.board\.json$/, ""); }
+
+  async function buildTree(rootAbsPath, nestedRoots = new Set(), base = "") {
+    let entries;
+    try { entries = await fs.readdir(path.join(rootAbsPath, base), { withFileTypes: true }); } catch { return []; }
+    const nodes = [];
+    for (const entry of entries) {
+      if (entry.name.startsWith(".") || IGNORE_DIRS.has(entry.name)) continue;
+      const rel = base ? `${base}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        if (nestedRoots.has(rel)) continue;
+        nodes.push({ type: "dir", name: entry.name, path: rel, children: await buildTree(rootAbsPath, nestedRoots, rel) });
+      } else {
+        nodes.push({ type: "file", name: entry.name, path: rel });
+      }
+    }
+    nodes.sort((a, b) => a.name.localeCompare(b.name));
+    return nodes;
+  }
+
+  function firstMarkdownPath(nodes) {
+    for (const node of nodes) {
+      if (node.type === "file" && node.name.endsWith(".md")) return node.path;
+      if (node.type === "dir") {
+        const nested = firstMarkdownPath(node.children);
+        if (nested) return nested;
+      }
+    }
+    return null;
+  }
+
+  async function pickProjectFromSystemDialog() {
+    return null;
+  }
+
+  async function sendMachineFile(res, fileName, contentType) {
+    const body = await readMachineAsset(fileName);
+    res.statusCode = 200;
+    res.setHeader("Content-Type", contentType);
+    res.setHeader("Link", ROOT_LINK_HEADER);
+    res.end(body);
+  }
+
+  async function resolveWorkspaceProject(projectId) {
+    const manifest = await loadManifest();
+    return manifest.projects.find((project) => project.id === projectId) ?? null;
+  }
+
+  async function ensureProjectDocsRoot(projectId) {
+    const project = await resolveWorkspaceProject(projectId);
+    if (!project) return null;
+    const existing = (await discoverDocsRoots(project))[0];
+    if (existing) return existing;
+    const abs = path.join(project.rootPath, "docs");
+    await fs.mkdir(abs, { recursive: true });
+    return {
+      id: docsRootId(project.id, abs),
+      projectId: project.id,
+      projectLabel: project.label,
+      absPath: abs,
+      relativePath: "docs",
+      displayPath: "docs",
+    };
+  }
+
+  async function createDocsFolder(projectId, parentPath) {
+    const project = await resolveWorkspaceProject(projectId);
+    if (!project) return null;
+    const parentAbs = safeResolve(project.rootPath, parentPath || ".");
+    if (!parentAbs) return null;
+    const abs = path.join(parentAbs, "docs");
+    await fs.mkdir(abs, { recursive: true });
+    return {
+      id: docsRootId(project.id, abs),
+      projectId: project.id,
+      projectLabel: project.label,
+      absPath: abs,
+      relativePath: normalizeRelativePath(path.relative(project.rootPath, abs)),
+      displayPath: rootDisplayPath(project.rootPath, abs),
+    };
+  }
+
+  async function deleteEmptyParentDirs(startDir, stopDir) {
+    let dir = startDir;
+    while (dir.startsWith(stopDir) && dir !== stopDir) {
+      try {
+        const entries = await fs.readdir(dir);
+        if (entries.length > 0) break;
+        await fs.rmdir(dir);
+      } catch { break; }
+      dir = path.dirname(dir);
+    }
+  }
+
+  async function renamePath(rootAbsPath, oldPath, newPath, ignoreMissing = false) {
+    const oldAbs = safeResolve(rootAbsPath, oldPath);
+    const newAbs = safeResolve(rootAbsPath, newPath);
+    if (!oldAbs || !newAbs) throw new Error("Invalid path");
+    try { await fs.access(oldAbs); } catch (err) {
+      if (ignoreMissing && err.code === "ENOENT") return;
+      throw err;
+    }
+    await fs.mkdir(path.dirname(newAbs), { recursive: true });
+    await fs.rename(oldAbs, newAbs);
+    await deleteEmptyParentDirs(path.dirname(oldAbs), rootAbsPath);
+  }
+
+  async function handler(req, res, next) {
+    pruneEphemeral();
+    const actor = actorFromHeaders(req);
+    const url = req.originalUrl || req.url || "/";
+    const parsed = new URL(url, "http://localhost");
+    const route = parsed.pathname;
+    const method = req.method || "GET";
+    if (route === "/llms.txt" && method === "GET") return void (await sendMachineFile(res, "llms.txt", "text/plain; charset=utf-8"));
+    if (route === "/viteboard-guide.md" && method === "GET") return void (await sendMachineFile(res, "guide.md", "text/markdown; charset=utf-8"));
+    if (route === "/board-v1.schema.json" && method === "GET") return void (await sendMachineFile(res, "board-v1.schema.json", "application/schema+json; charset=utf-8"));
+    if (route === "/viteboard-example.board.json" && method === "GET") return void (await sendMachineFile(res, "example.board.json", "application/json; charset=utf-8"));
+    if (route === "/.well-known/viteboard.json" && method === "GET") return void (await sendMachineFile(res, "viteboard.json", "application/json; charset=utf-8"));
+    if (!route.startsWith("/__api/")) return void next();
+    res.setHeader("Link", ROOT_LINK_HEADER);
+
+    try {
+      if (route === "/__api/events" && method === "GET") {
+        res.statusCode = 200;
+        res.setHeader("Content-Type", "text/event-stream; charset=utf-8");
+        res.setHeader("Cache-Control", "no-cache, no-transform");
+        res.setHeader("Connection", "keep-alive");
+        res.flushHeaders?.();
+        sseClients.add(res);
+        sendSse(res, "hello", { actors: activeActors(), locks: activeLocks() });
+        req.on("close", () => sseClients.delete(res));
+        return;
+      }
+
+      if (route === "/__api/workspace" && method === "GET") return send(res, 200, await toWorkspaceResponse(await getWorkspace()));
+      if (route === "/__api/project-tree" && method === "GET") {
+        const projectId = parsed.searchParams.get("projectId") ?? "";
+        const project = await resolveWorkspaceProject(projectId);
+        if (!project) return send(res, 404, { error: "Project not found" });
+        return send(res, 200, { tree: await buildTree(project.rootPath) });
+      }
+      if (route === "/__api/tree" && method === "GET") {
+        const rootId = parsed.searchParams.get("rootId") ?? "";
+        const resolved = await resolveRoot(rootId);
+        if (!resolved) return send(res, 404, { error: "Docs root not found" });
+        return send(res, 200, { tree: await buildTree(resolved.root.absPath, resolved.nestedRoots) });
+      }
+      if (route === "/__api/file" && method === "GET") {
+        const rootId = parsed.searchParams.get("rootId") ?? "";
+        const rel = parsed.searchParams.get("path") ?? "";
+        const resolved = await resolveRoot(rootId);
+        if (!resolved) return send(res, 404, { error: "Docs root not found" });
+        const abs = safeResolve(resolved.root.absPath, rel);
+        if (!abs) return send(res, 400, { error: "Invalid path" });
+        try {
+          const content = await fs.readFile(abs, "utf-8");
+          return send(res, 200, { path: rel, content, revision: revisionForText(content) });
+        } catch { return send(res, 404, { error: "Not found" }); }
+      }
+      if (route === "/__api/file" && method === "PUT") {
+        const { rootId, path: rel, content, expectedRevision } = JSON.parse(await readBody(req));
+        const resolved = await resolveRoot(String(rootId ?? ""));
+        if (!resolved) return send(res, 404, { error: "Docs root not found" });
+        const abs = safeResolve(resolved.root.absPath, String(rel ?? ""));
+        if (!abs) return send(res, 400, { error: "Invalid path" });
+        try {
+          const current = await fs.readFile(abs, "utf-8").catch((err) => err.code === "ENOENT" ? null : Promise.reject(err));
+          if (expectedRevision && current !== null && revisionForText(current) !== expectedRevision) return send(res, 409, { error: "File changed on disk", currentRevision: revisionForText(current) });
+          await fs.mkdir(path.dirname(abs), { recursive: true });
+          const nextContent = String(content ?? "");
+          await fs.writeFile(abs, nextContent, "utf-8");
+          const revision = revisionForText(nextContent);
+          broadcast("file-changed", { rootId: resolved.root.id, path: String(rel), action: "write", actorId: actor?.actorId ?? null });
+          return send(res, 200, { ok: true, path: rel, revision });
+        } catch (err) { return send(res, 500, { error: err.message }); }
+      }
+      if (route === "/__api/file" && method === "PATCH") {
+        const { rootId, oldPath, newPath, ignoreMissing } = JSON.parse(await readBody(req));
+        const resolved = await resolveRoot(String(rootId ?? ""));
+        if (!resolved) return send(res, 404, { error: "Docs root not found" });
+        await renamePath(resolved.root.absPath, String(oldPath ?? ""), String(newPath ?? ""), !!ignoreMissing);
+        broadcast("file-changed", { rootId: resolved.root.id, path: String(newPath), action: "rename", actorId: actor?.actorId ?? null });
+        return send(res, 200, { ok: true });
+      }
+      if (route === "/__api/file" && method === "DELETE") {
+        const rootId = parsed.searchParams.get("rootId") ?? "";
+        const rel = parsed.searchParams.get("path") ?? "";
+        const resolved = await resolveRoot(rootId);
+        if (!resolved) return send(res, 404, { error: "Docs root not found" });
+        const abs = safeResolve(resolved.root.absPath, rel);
+        if (!abs) return send(res, 400, { error: "Invalid path" });
+        try { await fs.unlink(abs); } catch (err) { if (err.code !== "ENOENT") throw err; }
+        await deleteEmptyParentDirs(path.dirname(abs), resolved.root.absPath);
+        broadcast("file-changed", { rootId: resolved.root.id, path: rel, action: "delete", actorId: actor?.actorId ?? null });
+        return send(res, 200, { ok: true });
+      }
+      if (route === "/__api/directory" && method === "PUT") {
+        const { rootId, path: rel } = JSON.parse(await readBody(req));
+        const resolved = await resolveRoot(String(rootId ?? ""));
+        if (!resolved) return send(res, 404, { error: "Docs root not found" });
+        const abs = safeResolve(resolved.root.absPath, String(rel ?? ""));
+        if (!abs) return send(res, 400, { error: "Invalid path" });
+        await fs.mkdir(abs, { recursive: true });
+        broadcast("file-changed", { rootId: resolved.root.id, path: String(rel), action: "mkdir", actorId: actor?.actorId ?? null });
+        return send(res, 200, { ok: true });
+      }
+      if (route === "/__api/board" && method === "GET") {
+        const rootId = parsed.searchParams.get("rootId") ?? "";
+        const id = parsed.searchParams.get("id") ?? "";
+        const resolved = await resolveRoot(rootId);
+        if (!resolved) return send(res, 404, { error: "Docs root not found" });
+        const abs = safeResolve(resolved.root.absPath, `${id}.board.json`);
+        if (!abs) return send(res, 400, { error: "Invalid id" });
+        try {
+          const content = await fs.readFile(abs, "utf-8");
+          return send(res, 200, { id, doc: JSON.parse(content), revision: revisionForText(content) });
+        } catch { return send(res, 404, { error: "Not found" }); }
+      }
+      if (route === "/__api/board" && method === "PUT") {
+        const { rootId, id, doc, expectedRevision } = JSON.parse(await readBody(req));
+        const resolved = await resolveRoot(String(rootId ?? ""));
+        if (!resolved) return send(res, 404, { error: "Docs root not found" });
+        const abs = safeResolve(resolved.root.absPath, `${id}.board.json`);
+        if (!abs) return send(res, 400, { error: "Invalid id" });
+        const current = await fs.readFile(abs, "utf-8").catch((err) => err.code === "ENOENT" ? null : Promise.reject(err));
+        if (expectedRevision && current !== null && revisionForText(current) !== expectedRevision) return send(res, 409, { error: "Board changed on disk", currentRevision: revisionForText(current) });
+        await fs.mkdir(path.dirname(abs), { recursive: true });
+        const nextContent = JSON.stringify(doc, null, 2) + "\n";
+        await fs.writeFile(abs, nextContent, "utf-8");
+        const revision = revisionForText(nextContent);
+        broadcast("board-changed", { rootId: resolved.root.id, boardId: String(id), action: "write", actorId: actor?.actorId ?? null });
+        return send(res, 200, { ok: true, id, revision });
+      }
+      if (route === "/__api/board" && method === "DELETE") {
+        const rootId = parsed.searchParams.get("rootId") ?? "";
+        const id = parsed.searchParams.get("id") ?? "";
+        const resolved = await resolveRoot(rootId);
+        if (!resolved) return send(res, 404, { error: "Docs root not found" });
+        const abs = safeResolve(resolved.root.absPath, `${id}.board.json`);
+        if (!abs) return send(res, 400, { error: "Invalid id" });
+        try { await fs.unlink(abs); } catch (err) { if (err.code !== "ENOENT") throw err; }
+        broadcast("board-changed", { rootId: resolved.root.id, boardId: id, action: "delete", actorId: actor?.actorId ?? null });
+        return send(res, 200, { ok: true, id });
+      }
+      if (route === "/__api/asset" && method === "GET") {
+        const rootId = parsed.searchParams.get("rootId") ?? "";
+        const rel = parsed.searchParams.get("path") ?? "";
+        const resolved = await resolveRoot(rootId);
+        if (!resolved) return send(res, 404, { error: "Docs root not found" });
+        const abs = safeResolve(resolved.root.absPath, rel);
+        if (!abs) return send(res, 400, { error: "Invalid path" });
+        try {
+          const buf = await fs.readFile(abs);
+          res.statusCode = 200;
+          res.setHeader("Content-Type", MIME[path.extname(abs).toLowerCase()] ?? "application/octet-stream");
+          res.setHeader("Cache-Control", "no-cache");
+          return res.end(buf);
+        } catch { return send(res, 404, { error: "Not found" }); }
+      }
+      if (route === "/__api/asset" && method === "POST") {
+        const { rootId, name, base64, mimeType } = JSON.parse(await readBody(req));
+        const resolved = await resolveRoot(String(rootId ?? ""));
+        if (!resolved) return send(res, 404, { error: "Docs root not found" });
+        const bytes = Buffer.from(String(base64), "base64");
+        const ext = MIME_EXT[String(mimeType ?? "")] ?? (path.extname(String(name ?? "")) || ".png").toLowerCase();
+        const digest = createHash("sha256").update(bytes).digest("hex");
+        const rel = `assets/${digest}${ext}`;
+        const abs = safeResolve(resolved.root.absPath, rel);
+        if (!abs) return send(res, 400, { error: "Invalid path" });
+        await fs.mkdir(path.dirname(abs), { recursive: true });
+        try { await fs.access(abs); } catch { await fs.writeFile(abs, bytes); }
+        broadcast("asset-changed", { rootId: resolved.root.id, path: rel, action: "write", actorId: actor?.actorId ?? null });
+        return send(res, 200, { ok: true, path: rel });
+      }
+      if (route === "/__api/asset/cleanup" && method === "POST") {
+        const { rootId, preservePaths } = JSON.parse(await readBody(req));
+        const resolved = await resolveRoot(String(rootId ?? ""));
+        if (!resolved) return send(res, 404, { error: "Docs root not found" });
+        const removed = await cleanupManagedAssets(resolved.root.absPath, Array.isArray(preservePaths) ? preservePaths.filter((item) => typeof item === "string") : []);
+        if (removed > 0) broadcast("asset-changed", { rootId: resolved.root.id, action: "cleanup", removed, actorId: actor?.actorId ?? null });
+        return send(res, 200, { ok: true, removed });
+      }
+      if (route === "/__api/workspace-file" && method === "GET") {
+        await ensureWorkspaceDir();
+        const manifest = await loadManifest();
+        return sendText(res, 200, JSON.stringify(manifest, null, 2) + "\n", "application/json; charset=utf-8");
+      }
+      if (route === "/__api/workspace/project" && method === "POST") {
+        const { rootPath, label } = JSON.parse(await readBody(req));
+        const absRoot = await canonicalizeProjectRoot(String(rootPath ?? ""));
+        const manifest = await loadManifest();
+        const projectId = projectIdFor(absRoot);
+        const overlap = manifest.projects.find((project) => project.id !== projectId && (isNestedPath(project.rootPath, absRoot) || isNestedPath(absRoot, project.rootPath)));
+        if (overlap) return send(res, 409, { error: overlapError(overlap, absRoot) });
+        if (!manifest.projects.some((project) => project.id === projectId)) {
+          manifest.projects.push({ id: projectId, label: String(label ?? (path.basename(absRoot) || "Project")), rootPath: absRoot });
+          await saveManifest(manifest);
+        }
+        return send(res, 200, await toWorkspaceResponse(await getWorkspace()));
+      }
+      if (route === "/__api/workspace/project" && method === "DELETE") {
+        const projectId = parsed.searchParams.get("id") ?? "";
+        const manifest = await loadManifest();
+        manifest.projects = manifest.projects.filter((project) => project.id !== projectId);
+        await saveManifest(manifest);
+        return send(res, 200, { ok: true, workspace: await toWorkspaceResponse(await getWorkspace()) });
+      }
+      if (route === "/__api/workspace/pick-project" && method === "POST") {
+        const picked = await pickProjectFromSystemDialog();
+        if (!picked) return send(res, 200, { cancelled: true, workspace: await toWorkspaceResponse(await getWorkspace()) });
+        const absRoot = await canonicalizeProjectRoot(picked);
+        const manifest = await loadManifest();
+        const projectId = projectIdFor(absRoot);
+        const overlap = manifest.projects.find((project) => project.id !== projectId && (isNestedPath(project.rootPath, absRoot) || isNestedPath(absRoot, project.rootPath)));
+        if (overlap) return send(res, 409, { error: overlapError(overlap, absRoot) });
+        if (!manifest.projects.some((project) => project.id === projectId)) {
+          manifest.projects.push({ id: projectId, label: path.basename(absRoot) || "Project", rootPath: absRoot });
+          await saveManifest(manifest);
+        }
+        const workspace = await getWorkspace();
+        return send(res, 200, { cancelled: false, workspace: await toWorkspaceResponse(workspace), addedProjectId: projectId });
+      }
+      if (route === "/__api/workspace/project/docs-root" && method === "POST") {
+        const { projectId } = JSON.parse(await readBody(req));
+        const root = await ensureProjectDocsRoot(String(projectId ?? ""));
+        if (!root) return send(res, 404, { error: "Project not found" });
+        const workspace = await getWorkspace();
+        return send(res, 200, { root: { id: root.id, projectId: root.projectId, projectLabel: root.projectLabel, relativePath: root.relativePath, displayPath: root.displayPath }, workspace: await toWorkspaceResponse(workspace) });
+      }
+      if (route === "/__api/workspace/project/create-docs-folder" && method === "POST") {
+        const { projectId, parentPath } = JSON.parse(await readBody(req));
+        const root = await createDocsFolder(String(projectId ?? ""), String(parentPath ?? ""));
+        if (!root) return send(res, 404, { error: "Project not found" });
+        const workspace = await getWorkspace();
+        return send(res, 200, { root: { id: root.id, projectId: root.projectId, projectLabel: root.projectLabel, relativePath: root.relativePath, displayPath: root.displayPath }, workspace: await toWorkspaceResponse(workspace) });
+      }
+      if (route === "/__api/actors/session" && method === "POST") {
+        const payload = JSON.parse(await readBody(req));
+        const now = Date.now();
+        actorSessions.set(payload.actorId, { ...payload, updatedAt: now, expiresAt: now + ACTOR_TTL_MS });
+        broadcastPresence();
+        return send(res, 200, { ok: true });
+      }
+      if (route === "/__api/actors/heartbeat" && method === "POST") {
+        const payload = JSON.parse(await readBody(req));
+        const now = Date.now();
+        actorSessions.set(payload.actorId, { ...payload, updatedAt: now, expiresAt: now + ACTOR_TTL_MS });
+        broadcastPresence();
+        return send(res, 200, { ok: true });
+      }
+      if (route === "/__api/actors/session" && method === "DELETE") {
+        const actorId = parsed.searchParams.get("actorId") ?? "";
+        actorSessions.delete(actorId);
+        for (const [key, lock] of locks) if (lock.actorId === actorId) locks.delete(key);
+        broadcastPresence();
+        return send(res, 200, { ok: true });
+      }
+      if (route === "/__api/locks/acquire" && method === "POST") {
+        const target = JSON.parse(await readBody(req));
+        if (!actor) return send(res, 400, { error: "Missing actor context" });
+        const key = lockKey(target);
+        const existing = locks.get(key);
+        if (existing && existing.actorId !== actor.actorId) return send(res, 409, { error: "Target already locked", lock: existing });
+        const now = Date.now();
+        const lock = { ...target, lockId: `${key}:${now}`, actorId: actor.actorId, actorType: actor.actorType, label: actor.label, acquiredAt: now, expiresAt: now + LOCK_TTL_MS };
+        locks.set(key, lock);
+        broadcastLocks();
+        return send(res, 200, { lock });
+      }
+      if (route === "/__api/locks/release" && method === "POST") {
+        const target = JSON.parse(await readBody(req));
+        locks.delete(lockKey(target));
+        broadcastLocks();
+        return send(res, 200, { ok: true });
+      }
+      return send(res, 404, { error: "Unknown endpoint" });
+    } catch (err) {
+      return send(res, 500, { error: err.message });
+    }
+  }
+
+  return {
+    name: "viteboard-content-api",
+    configureServer(server) { server.middlewares.use(handler); },
+    configurePreviewServer(server) { server.middlewares.use(handler); },
+  };
+}

package/bin/viteboard.mjs

@@ -4,6 +4,7 @@ import { createServer } from "vite";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
 import fs from "node:fs";
+import { createContentApiPlugin } from "./content-api-plugin.mjs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(__dirname, "..");
@@ -29,15 +30,10 @@ async function main() {
     await server.listen();
     server.printUrls();
   } else if (hasDist) {
-    // Installed as a package — serve the pre-built dist with the API plugin
-    // We need to dynamically import the config since it may be .ts
-    const { default: configFn } = await import(path.join(packageRoot, "vite.config.ts"));
-    const config = typeof configFn === "function" ? configFn({}) : configFn;
-    const plugins = Array.isArray(config.plugins) ? config.plugins : [];
-
+    // Installed as a package — serve the pre-built dist with the runtime JS plugin.
     const server = await createServer({
       root: path.join(packageRoot, "dist"),
-      plugins,
+      plugins: [createContentApiPlugin()],
       server: { port, host, open: true },
     });
     await server.listen();

package/content/machine/viteboard.json

@@ -1,6 +1,6 @@
 {
   "name": "ViteBoard",
-  "appVersion": "0.1.2",
+  "appVersion": "0.1.4",
   "machineVersion": 1,
   "summary": "Local-first documentation and infinite-canvas boards stored as plain files.",
   "connectionHints": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viteboard",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Local-first documentation workspace and infinite-canvas whiteboard. Markdown docs, boards, and capability specs as plain files on disk.",
   "license": "MIT",
   "type": "module",