mulmoclaude 0.5.2 → 0.6.0

package/server/utils/files/image-store.ts

@@ -1,14 +1,14 @@
-import { mkdir, readFile, realpath, writeFile } from "fs/promises";
+import { mkdir, readFile, realpath } from "fs/promises";
 import path from "path";
 import { WORKSPACE_DIRS, WORKSPACE_PATHS } from "../../workspace/paths.js";
 import { shortId } from "../id.js";
+import { writeFileAtomic } from "./atomic.js";
 import { yearMonthUtc } from "./naming.js";
 import { resolveWithinRoot } from "./safe.js";
 
 const IMAGES_DIR = WORKSPACE_PATHS.images;
 
-// Cached realpath of the images directory. resolveWithinRoot requires
-// its root argument to be a realpath so symlinks are handled correctly.
+// resolveWithinRoot needs a realpath as its root so symlinks resolve correctly.
 let imagesDirReal: string | null = null;
 
 async function ensureImagesDir(): Promise<string> {
@@ -18,13 +18,9 @@ async function ensureImagesDir(): Promise<string> {
   return imagesDirReal;
 }
 
-// Resolve a workspace-relative image path (e.g. "images/abc123.png")
-// into an absolute path that is guaranteed to be inside the images
-// directory. Throws on traversal attempts or non-existent files.
+// Throws on traversal. Strips a leading "images/" so callers can pass either the stored form or bare filename.
 async function safeResolve(relativePath: string): Promise<string> {
   const root = await ensureImagesDir();
-  // Strip the leading "images/" prefix so the caller can pass either
-  // "images/abc.png" (the stored form) or just "abc.png".
   const name = relativePath.replace(new RegExp(`^${WORKSPACE_DIRS.images}/`), "");
   const result = resolveWithinRoot(root, name);
   if (!result) {
@@ -33,40 +29,42 @@ async function safeResolve(relativePath: string): Promise<string> {
   return result;
 }
 
-/** Save raw base64 (no data URI prefix) as a PNG file. New files
- *  land under `images/YYYY/MM/` (UTC) so the dir doesn't accumulate
- *  unbounded — see #764. Returns the workspace-relative path. */
+// #764 sharded under images/YYYY/MM/ (UTC). Buffer pass-through avoids re-encoding the PNG bytes.
 export async function saveImage(base64Data: string): Promise<string> {
   await ensureImagesDir();
   const partition = yearMonthUtc();
-  const parentAbs = path.join(IMAGES_DIR, partition);
-  await mkdir(parentAbs, { recursive: true });
   const filename = `${shortId()}.png`;
-  await writeFile(path.join(parentAbs, filename), Buffer.from(base64Data, "base64"));
+  const absPath = path.join(IMAGES_DIR, partition, filename);
+  await writeFileAtomic(absPath, Buffer.from(base64Data, "base64"));
   return path.posix.join(WORKSPACE_DIRS.images, partition, filename);
 }
 
-/** Overwrite an existing image file. The relativePath must start with "images/". */
 export async function overwriteImage(relativePath: string, base64Data: string): Promise<void> {
   const absPath = await safeResolve(relativePath);
-  await writeFile(absPath, Buffer.from(base64Data, "base64"));
+  await writeFileAtomic(absPath, Buffer.from(base64Data, "base64"));
 }
 
-/** Read an image file and return raw base64 (no data URI prefix). */
 export async function loadImageBase64(relativePath: string): Promise<string> {
   const absPath = await safeResolve(relativePath);
   const buf = await readFile(absPath);
   return buf.toString("base64");
 }
 
-/** Convert a data URI to raw base64. */
 export function stripDataUri(dataUri: string): string {
   return dataUri.replace(/^data:image\/[^;]+;base64,/, "");
 }
 
-/** Check if a string is a file reference (not a data URI). Accepts
- *  arbitrary depth under `images/` (e.g. `images/2026/04/abc.png`)
- *  so the per-month sharded paths from `saveImage` still validate. */
+// Reject `.` / `..` segments split on either `/` or `\` so a
+// traversal-shaped value can't slip past the prefix/suffix gate
+// (Codex review on PR #1084 follow-up to #1052).
+function hasTraversalSegment(value: string): boolean {
+  return value.split(/[/\\]/).some((segment) => segment === ".." || segment === ".");
+}
+
+// Accepts arbitrary depth so saveImage's images/YYYY/MM/abc.png still validates.
 export function isImagePath(value: string): boolean {
-  return value.startsWith(`${WORKSPACE_DIRS.images}/`) && value.endsWith(".png");
+  if (!value.startsWith(`${WORKSPACE_DIRS.images}/`)) return false;
+  if (!value.endsWith(".png")) return false;
+  if (hasTraversalSegment(value)) return false;
+  return true;
 }

package/server/utils/files/index.ts

@@ -1,21 +1,11 @@
-// Consolidated workspace file I/O (#366).
-//
-// This barrel re-exports every public helper so call sites can do:
-//
-//   import { writeFileAtomic, readWorkspaceText } from "../utils/files/index.js";
-//
-// Grouped by concern:
-//
-//   atomic.ts        — write-then-rename primitives
-//   safe.ts          — ENOENT-swallowing wrappers (stat, readdir, readText, resolveWithinRoot)
-//   json.ts          — JSON read/write (sync legacy + async atomic)
-//   workspace-io.ts  — workspace-aware helpers (path resolve + I/O in one call)
+// #366: barrel for workspace file I/O. atomic = write-rename, safe = ENOENT-swallowing, json = sync read + atomic
+// write, workspace-io = path resolve + I/O in one call.
 
 export { writeFileAtomic, writeFileAtomicSync, type WriteAtomicOptions } from "./atomic.js";
 
 export { isEnoent, readTextSafeSync, statSafe, statSafeAsync, readDirSafe, readDirSafeAsync, readTextOrNull, resolveWithinRoot } from "./safe.js";
 
-export { loadJsonFile, saveJsonFile, writeJsonAtomic, readJsonOrNull } from "./json.js";
+export { loadJsonFile, writeJsonAtomic, readJsonOrNull } from "./json.js";
 
 export {
   resolveWorkspacePath,
@@ -36,9 +26,9 @@ export {
   ensureDirUnder,
 } from "./workspace-io.js";
 
-// ── Domain I/O ──────────────────────────────────────────────────
 export * from "./session-io.js";
-export * from "./todos-io.js";
+// todos-io.js removed (#1145) — todo persistence moved into the
+// `@mulmoclaude/todo-plugin` workspace package.
 export * from "./scheduler-io.js";
 export * from "./html-io.js";
 export * from "./reference-dirs-io.js";

package/server/utils/files/journal-io.ts

@@ -1,14 +1,3 @@
-// Domain I/O: workspace journal (summaries)
-//   conversations/summaries/_state.json        — journal state
-//   conversations/summaries/_index.md           — browseable index
-//   conversations/summaries/daily/YYYY/MM/DD.md — daily summaries
-//   conversations/summaries/topics/<slug>.md    — topic files
-//   conversations/summaries/archive/topics/     — archived topics
-//
-// All functions take optional `root` for test DI.
-// Path helpers (summariesRoot, dailyPathFor, topicPathFor) live in
-// journal/paths.ts — this module wraps them with I/O.
-
 import path from "node:path";
 import fsp from "node:fs/promises";
 import { workspacePath } from "../../workspace/paths.js";
@@ -21,8 +10,6 @@ import { statSync } from "node:fs";
 
 const root = (rootOverride?: string) => rootOverride ?? workspacePath;
 
-// ── State ───────────────────────────────────────────────────────
-
 export function journalStateExists(rootOverride?: string): boolean {
   const filePath = path.join(summariesRoot(root(rootOverride)), STATE_FILE);
   try {
@@ -49,15 +36,11 @@ export async function writeJournalState(state: unknown, rootOverride?: string):
   await writeFileAtomic(filePath, JSON.stringify(state, null, 2));
 }
 
-// ── Index ───────────────────────────────────────────────────────
-
 export async function writeJournalIndex(markdown: string, rootOverride?: string): Promise<void> {
   const filePath = path.join(summariesRoot(root(rootOverride)), INDEX_FILE);
   await writeFileAtomic(filePath, markdown);
 }
 
-// ── Daily summaries ─────────────────────────────────────────────
-
 export async function readDailySummary(date: string, rootOverride?: string): Promise<string | null> {
   try {
     return await fsp.readFile(dailyPathFor(root(rootOverride), date), "utf-8");
@@ -74,15 +57,12 @@ export async function writeDailySummary(date: string, content: string, rootOverr
   await writeFileAtomic(dailyPathFor(root(rootOverride), date), content);
 }
 
-// ── Topics ──────────────────────────────────────────────────────
-
 export async function readTopicFile(slug: string, rootOverride?: string): Promise<string | null> {
   try {
     return await fsp.readFile(topicPathFor(root(rootOverride), slug), "utf-8");
   } catch (err) {
     if (isEnoent(err)) return null;
-    // EACCES/EPERM must propagate — swallowing them would cause
-    // appendOrCreateTopic to clobber an unreadable file.
+    // EACCES/EPERM must propagate — swallowing them would let appendOrCreateTopic clobber an unreadable file.
     throw err;
   }
 }
@@ -91,7 +71,6 @@ export async function writeTopicFile(slug: string, content: string, rootOverride
   await writeFileAtomic(topicPathFor(root(rootOverride), slug), content);
 }
 
-/** Append content to an existing topic, or create a new file. */
 export async function appendOrCreateTopic(slug: string, content: string, rootOverride?: string): Promise<"created" | "updated"> {
   const existing = await readTopicFile(slug, rootOverride);
   if (existing === null) {
@@ -102,7 +81,6 @@ export async function appendOrCreateTopic(slug: string, content: string, rootOve
   return "updated";
 }
 
-/** List topic slugs (filenames without .md). */
 export async function listTopicSlugs(rootOverride?: string): Promise<string[]> {
   const dir = path.join(summariesRoot(root(rootOverride)), TOPICS_DIR);
   try {
@@ -115,7 +93,6 @@ export async function listTopicSlugs(rootOverride?: string): Promise<string[]> {
   }
 }
 
-/** Read all topic files at once. Returns slug→content map. */
 export async function readAllTopicFiles(rootOverride?: string): Promise<Map<string, string>> {
   const dir = path.join(summariesRoot(root(rootOverride)), TOPICS_DIR);
   const out = new Map<string, string>();
@@ -137,8 +114,7 @@ export async function readAllTopicFiles(rootOverride?: string): Promise<Map<stri
   return out;
 }
 
-/** Move a topic to the archive directory. Returns false if the
- *  source doesn't exist or the move fails. */
+// Returns false if the source doesn't exist or the move fails.
 export async function archiveTopic(slug: string, rootOverride?: string): Promise<boolean> {
   const src = topicPathFor(root(rootOverride), slug);
   const dst = path.join(summariesRoot(root(rootOverride)), ARCHIVE_DIR, TOPICS_DIR, `${slug}.md`);
@@ -154,14 +130,17 @@ export async function archiveTopic(slug: string, rootOverride?: string): Promise
   }
 }
 
-// ── Daily file listing ──────────────────────────────────────────
-
 export interface DailyFileEntry {
   year: string;
   month: string;
   day: string;
 }
 
+const YEAR_RE = /^\d{4}$/;
+const MONTH_RE = /^\d{2}$/;
+const isYearDir = (name: string) => YEAR_RE.test(name);
+const isMonthDir = (name: string) => MONTH_RE.test(name);
+
 export async function listDailyFiles(rootOverride?: string): Promise<DailyFileEntry[]> {
   const dailyRoot = path.join(summariesRoot(root(rootOverride)), DAILY_DIR);
   const years = await safeReaddir(dailyRoot);
@@ -173,11 +152,6 @@ export async function listDailyFiles(rootOverride?: string): Promise<DailyFileEn
   return out;
 }
 
-const YEAR_RE = /^\d{4}$/;
-const MONTH_RE = /^\d{2}$/;
-const isYearDir = (name: string) => YEAR_RE.test(name);
-const isMonthDir = (name: string) => MONTH_RE.test(name);
-
 async function listDaysForYear(dailyRoot: string, year: string): Promise<DailyFileEntry[]> {
   const months = await safeReaddir(path.join(dailyRoot, year));
   const out: DailyFileEntry[] = [];
@@ -200,8 +174,6 @@ async function safeReaddir(dir: string): Promise<string[]> {
   }
 }
 
-// ── Archived topic count ────────────────────────────────────────
-
 export async function countArchivedTopics(rootOverride?: string): Promise<number> {
   const dir = path.join(summariesRoot(root(rootOverride)), ARCHIVE_DIR, TOPICS_DIR);
   try {

package/server/utils/files/json.ts

@@ -1,22 +1,9 @@
-// JSON file helpers — synchronous (legacy) and async (preferred).
-//
-// Moved from server/utils/file.ts (issue #366 Phase 1). The old
-// file re-exports these for backwards compat.
-
-import { mkdirSync, promises, readFileSync, writeFileSync } from "fs";
-import path from "path";
+import { promises, readFileSync } from "fs";
 import { writeFileAtomic } from "./atomic.js";
 import { isEnoent } from "./safe.js";
 import { log } from "../../system/logger/index.js";
 
-// ── Sync helpers ────────────────────────────────────────────────
-
-/**
- * Read and parse a JSON file synchronously. Returns `defaultValue`
- * on ENOENT (file not yet created) or JSON corruption (logs the
- * error but doesn't crash — user data files must not take down the
- * server). Rethrows unexpected errors (EACCES, EPERM).
- */
+// Returns defaultValue on ENOENT or parse failure (user data files must not take down the server); rethrows EACCES/EPERM.
 export function loadJsonFile<T>(filePath: string, defaultValue: T): T {
   let raw: string;
   try {
@@ -40,24 +27,10 @@ export function loadJsonFile<T>(filePath: string, defaultValue: T): T {
   }
 }
 
-export function saveJsonFile(filePath: string, data: unknown): void {
-  mkdirSync(path.dirname(filePath), { recursive: true });
-  writeFileSync(filePath, JSON.stringify(data, null, 2));
-}
-
-// ── Async ───────────────────────────────────────────────────────
-
-/**
- * JSON-pretty-print `data` and write atomically.
- */
 export async function writeJsonAtomic(filePath: string, data: unknown, opts: Parameters<typeof writeFileAtomic>[2] = {}): Promise<void> {
   await writeFileAtomic(filePath, JSON.stringify(data, null, 2), opts);
 }
 
-/**
- * Read a JSON file and parse it. Returns null if the file is missing,
- * unreadable, or malformed.
- */
 export async function readJsonOrNull<T>(filePath: string): Promise<T | null> {
   try {
     const content = await promises.readFile(filePath, "utf-8");

package/server/utils/files/markdown-image-fill.ts

@@ -1,14 +1,5 @@
-// Replace `![alt](__too_be_replaced_image_path__)` placeholders in
-// markdown with real Gemini-generated images saved to the workspace.
-// Lives under `server/utils/files/` because it sits at the seam
-// between markdown content and on-disk image artifacts; route
-// handlers (e.g. `presentDocument`) just hand off the markdown.
-//
-// Logging policy: every image generation emits start / ok / failed /
-// no-data lines, and every batch emits a tally. Per the timeout-policy
-// comment in `server/agent/mcp-server.ts`, generative-AI work MUST be
-// observable — silent partial failures were the exact failure mode
-// that hid the 10 s bridge-timeout bug.
+// Per the timeout-policy comment in server/agent/mcp-server.ts, generative-AI work MUST be observable — silent
+// partial failures hid the 10s bridge-timeout bug. Every image emits start/ok/failed/no-data + per-batch tally.
 import { generateGeminiImageFromPrompt, isGeminiAvailable } from "../gemini.js";
 import { errorMessage } from "../errors.js";
 import { promptMeta } from "../promptMeta.js";
@@ -21,9 +12,7 @@ const LOG_PREFIX = "present-document";
 async function generateImageFile(prompt: string, index: number, total: number): Promise<string | null> {
   if (!isGeminiAvailable()) return null;
   const startedAt = Date.now();
-  // Prompt is user-controlled and may contain pasted URLs / emails /
-  // credentials, so we log a `{ length, sha256 }` fingerprint instead
-  // of a raw prefix. See `server/utils/promptMeta.ts`.
+  // Prompt is user-controlled and may contain credentials/PII; promptMeta logs {length, sha256} instead of raw bytes.
   const meta = promptMeta(prompt);
   log.info(LOG_PREFIX, "image gen start", {
     index,
@@ -71,33 +60,13 @@ function logBatchTally(results: PlaceholderResult[], total: number, batchStarted
 }
 
 export function buildReplacement(prompt: string, url: string | null): string {
-  // `url` is workspace-relative (e.g. "artifacts/images/2026/04/x.png").
-  // Emit a workspace-root absolute ref ("/...") so the resolution is
-  // independent of where the markdown file itself lands on disk.
-  // Since #764, documents shard under `artifacts/documents/YYYY/MM/`,
-  // and `rewriteMarkdownImageRefs` (front-end) treats a leading "/"
-  // as "rooted at workspace" — so a markdown reference like
-  // "![alt](/artifacts/images/...)" works regardless of the document's
-  // depth. A relative path computed against the unsharded root would
-  // instead be off by two directory levels and 404 in the canvas.
+  // Workspace-rooted "/…" so the ref resolves the same regardless of document depth (#764 sharded documents under
+  // artifacts/documents/YYYY/MM/; a relative path would be off by two directory levels).
   if (url) return `![${prompt}](/${url})`;
-  // No image: keep the alt text visible as an italic marker so the
-  // operator can still see what *would* have been generated.
+  // No image: leave the alt text as an italic marker so the operator can see what *would* have been generated.
   return `*🖼️ Image: ${prompt}*`;
 }
 
-/**
- * Replace every `![alt](__too_be_replaced_image_path__)` placeholder
- * in the input markdown with a real Gemini-generated image.
- *
- * - When `GEMINI_API_KEY` is unset, every placeholder degrades to an
- *   italic text marker (`*🖼️ Image: <alt>*`) so the document still
- *   renders without broken image refs.
- * - On per-image failure, the same fallback applies for that one
- *   placeholder. Other placeholders proceed independently.
- * - All generation runs in parallel via `Promise.all` — typical 9-image
- *   batches finish in 15-25 s rather than per-image-serial.
- */
 export async function fillMarkdownImagePlaceholders(markdown: string): Promise<string> {
   const matches = [...markdown.matchAll(IMAGE_PLACEHOLDER)];
   if (matches.length === 0) return markdown;

package/server/utils/files/markdown-store.ts

@@ -1,44 +1,29 @@
-import { mkdir, readFile, writeFile } from "fs/promises";
+import { readFile } from "fs/promises";
 import path from "path";
 import { workspacePath } from "../../workspace/workspace.js";
 import { WORKSPACE_DIRS } from "../../workspace/paths.js";
+import { writeFileAtomic } from "./atomic.js";
 import { buildArtifactPathRandom } from "./naming.js";
 
-/**
- * Save markdown content as a file. Returns the workspace-relative path.
- * `prefix` is slugified; a random id is always appended to prevent
- * collisions between concurrent writers sharing the same prefix.
- *
- * `buildArtifactPathRandom` now injects a `YYYY/MM` partition (#764),
- * so this function ensures the partition directory exists before
- * writing — `writeFile` doesn't create missing parents on its own.
- */
+// Random-id suffix prevents collisions between concurrent writers sharing a prefix; #764 sharded under YYYY/MM.
 export async function saveMarkdown(content: string, prefix: string): Promise<string> {
   const relPath = buildArtifactPathRandom(WORKSPACE_DIRS.markdowns, prefix, ".md", "document");
   const absPath = path.join(workspacePath, relPath);
-  await mkdir(path.dirname(absPath), { recursive: true });
-  await writeFile(absPath, content, "utf-8");
+  await writeFileAtomic(absPath, content);
   return relPath;
 }
 
-/** Read a markdown file and return its content. */
 export async function loadMarkdown(relativePath: string): Promise<string> {
   const absPath = path.join(workspacePath, relativePath);
   return readFile(absPath, "utf-8");
 }
 
-/** Overwrite an existing markdown file. */
 export async function overwriteMarkdown(relativePath: string, content: string): Promise<void> {
   const absPath = path.join(workspacePath, relativePath);
-  await writeFile(absPath, content, "utf-8");
+  await writeFileAtomic(absPath, content);
 }
 
-/** Check if a string is a markdown file path (not inline content).
- *  Rejects traversal attempts like `artifacts/documents/../outside.md`
- *  so callers can rely on prefix+suffix alone. Mirrors the
- *  `isSpreadsheetPath` policy. The server-side `path.join` in
- *  `overwriteMarkdown` does NOT normalize traversal on its own, so
- *  this gate is the primary defence — keep it strict. */
+// Strict — overwriteMarkdown's path.join doesn't normalize traversal, so this gate is the primary defence.
 export function isMarkdownPath(value: string): boolean {
   if (!value.startsWith(`${WORKSPACE_DIRS.markdowns}/`)) return false;
   if (!value.endsWith(".md")) return false;

package/server/utils/files/naming.ts

@@ -1,59 +1,23 @@
-// Workspace file naming conventions.
-//
-// Centralizes the `slug-${Date.now()}.ext` pattern used across
-// multiple plugins (chart, presentHtml, markdown, spreadsheet, image).
-// Call sites pass a human title + extension; this module handles
-// slugification and timestamp suffixing.
-
 import path from "node:path";
 import { shortId } from "../id.js";
 import { slugify } from "../slug.js";
 
-/**
- * UTC-based `YYYY/MM` partition segment for new artifacts (#764).
- * Keeps each artifact directory from accumulating a flat list of
- * thousands of files. UTC is used (rather than local time) so a
- * workspace synced across machines / timezones still groups files
- * into the same bucket.
- *
- * Exported for unit tests and callers that need the partition without
- * also generating a filename (e.g. saveImage / saveSpreadsheet).
- */
+// #764 partitioning. UTC (not local) so a workspace synced across timezones still groups into the same bucket.
 export function yearMonthUtc(now: Date = new Date()): string {
   const year = now.getUTCFullYear();
   const month = String(now.getUTCMonth() + 1).padStart(2, "0");
   return `${year}/${month}`;
 }
 
-/**
- * Build a workspace-relative path for a new artifact file.
- *
- * @param dir  Workspace-relative directory (e.g. WORKSPACE_DIRS.charts)
- * @param title  Human-readable title (slugified for the filename)
- * @param ext  File extension with leading dot (e.g. ".html", ".json")
- * @param fallbackSlug  Slug to use when title is empty/undefined
- * @returns  Workspace-relative path like "artifacts/charts/2026/04/sales-1776135210389.chart.json"
- */
 export function buildArtifactPath(dir: string, title: string | undefined, ext: string, fallbackSlug = "file"): string {
   const slug = title ? slugify(title) || fallbackSlug : fallbackSlug;
   const fname = `${slug}-${Date.now()}${ext}`;
   return path.posix.join(dir, yearMonthUtc(), fname);
 }
 
-/**
- * Like `buildArtifactPath`, but appends a random hex id instead of a
- * timestamp. Use when multiple concurrent writers may share the same
- * prefix within the same millisecond (e.g. LLM-supplied `filenamePrefix`
- * on the `presentDocument` route).
- *
- * @param dir  Workspace-relative directory
- * @param prefix  Human-readable prefix (slugified via `slugify`)
- * @param ext  File extension with leading dot
- * @param fallbackSlug  Slug to use when the sanitized prefix is empty
- */
+// shortId variant for concurrent writers that share a prefix within the same millisecond (presentDocument route).
 export function buildArtifactPathRandom(dir: string, prefix: string, ext: string, fallbackSlug = "file"): string {
-  // Pass fallbackSlug as slugify's default so it overrides slugify's
-  // built-in "page" default when `prefix` sanitizes to empty.
+  // Pass fallbackSlug as slugify's default so it overrides slugify's built-in "page" when `prefix` sanitizes to empty.
   const slug = slugify(prefix, fallbackSlug);
   const fname = `${slug}-${shortId()}${ext}`;
   return path.posix.join(dir, yearMonthUtc(), fname);

package/server/utils/files/plugins-io.ts

@@ -0,0 +1,100 @@
+// Install ledger I/O for runtime-loaded plugins (#1043 C-2).
+//
+// The ledger is `~/mulmoclaude/plugins/plugins.json`, listing every
+// plugin the user has installed via the install CLI / web UI. Each
+// entry pairs the npm package id with the on-disk tgz filename; the
+// loader replays this at boot to know what to extract from
+// `plugins/` into `plugins/.cache/<name>/<version>/`.
+//
+// Truncating or deleting this file removes nothing on disk but
+// "uninstalls" all runtime plugins on the next boot — the tgz files
+// in `plugins/` and the cache mirror are GC'd on the following start.
+// Editing it by hand is a supported recovery path.
+//
+// Reads tolerate missing / malformed JSON (returns []), so a half-
+// written ledger never bricks server boot. Writes go through the
+// atomic helper, so a crashed install can't leave a corrupt file.
+
+import { existsSync } from "node:fs";
+import { mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { loadJsonFile, writeJsonAtomic } from "./json.js";
+import { WORKSPACE_PATHS } from "../../workspace/paths.js";
+
+export interface LedgerEntry {
+  /** npm package name, e.g. `@gui-chat-plugin/weather`. */
+  name: string;
+  /** Semver string from the tgz's `package.json`, e.g. `0.1.0`. */
+  version: string;
+  /** Basename of the tgz inside `plugins/`. Joined with
+   *  `WORKSPACE_PATHS.plugins` to read. */
+  tgz: string;
+  /** ISO 8601 timestamp of the install. */
+  installedAt: string;
+}
+
+const isLedgerEntry = (value: unknown): value is LedgerEntry => {
+  if (typeof value !== "object" || value === null) return false;
+  const obj = value as Record<string, unknown>;
+  return typeof obj.name === "string" && typeof obj.version === "string" && typeof obj.tgz === "string" && typeof obj.installedAt === "string";
+};
+
+const sanitiseLedger = (raw: unknown): LedgerEntry[] => {
+  if (!Array.isArray(raw)) return [];
+  return raw.filter(isLedgerEntry);
+};
+
+export function readLedger(): LedgerEntry[] {
+  const raw = loadJsonFile<unknown>(WORKSPACE_PATHS.pluginsLedger, []);
+  return sanitiseLedger(raw);
+}
+
+export async function writeLedger(entries: readonly LedgerEntry[]): Promise<void> {
+  const dir = path.dirname(WORKSPACE_PATHS.pluginsLedger);
+  if (!existsSync(dir)) {
+    await mkdir(dir, { recursive: true });
+  }
+  await writeJsonAtomic(WORKSPACE_PATHS.pluginsLedger, [...entries]);
+}
+
+/** Read a runtime-plugin asset (extracted under
+ *  `plugins/.cache/<name>/<version>/`) and return its bytes plus
+ *  the inferred Content-Type. The route handler in
+ *  `runtime-plugin.ts` was previously calling `fs.readFile` directly
+ *  — per `CLAUDE.md` route handlers must go through a domain helper,
+ *  so the lookup table + read live here (#1077 review). */
+export interface PluginAsset {
+  data: Buffer;
+  contentType: string;
+}
+
+export async function readPluginAsset(absPath: string): Promise<PluginAsset> {
+  const data = await readFile(absPath);
+  const ext = path.extname(absPath).toLowerCase();
+  return { data, contentType: pluginAssetContentType(ext) };
+}
+
+// Lookup table over a switch — flat data structure stays under
+// `sonarjs/cognitive-complexity` while keeping the per-extension
+// mapping easy to scan.
+const PLUGIN_ASSET_CONTENT_TYPES: Readonly<Record<string, string>> = {
+  ".js": "application/javascript; charset=utf-8",
+  ".mjs": "application/javascript; charset=utf-8",
+  ".cjs": "application/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".map": "application/json; charset=utf-8",
+  ".html": "text/html; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+};
+
+export function pluginAssetContentType(ext: string): string {
+  return PLUGIN_ASSET_CONTENT_TYPES[ext] ?? "application/octet-stream";
+}

package/server/utils/files/reference-dirs-io.ts

@@ -1,9 +1,3 @@
-// Domain I/O for reference directories.
-//
-// Reads/writes config/reference-dirs.json and checks host paths.
-// All fs access is funneled through shared helpers so path changes
-// propagate from a single constant.
-
 import { mkdirSync, statSync } from "fs";
 import path from "path";
 import { WORKSPACE_DIRS, workspacePath } from "../../workspace/paths.js";
@@ -17,7 +11,7 @@ function configPath(root: string): string {
   return path.join(root, WORKSPACE_DIRS.configs, CONFIG_FILE_NAME);
 }
 
-/** Read reference-dirs.json. Returns [] on missing/corrupt file. */
+// Returns [] on missing/corrupt file.
 export function readReferenceDirsJson(root?: string): unknown[] {
   const filePath = configPath(root ?? workspacePath);
   const parsed = loadJsonFile<unknown>(filePath, []);
@@ -28,14 +22,12 @@ export function readReferenceDirsJson(root?: string): unknown[] {
   return parsed;
 }
 
-/** Write reference-dirs.json atomically. Creates config/ if needed. */
 export function writeReferenceDirsJson(entries: readonly unknown[], root?: string): void {
   const filePath = configPath(root ?? workspacePath);
   mkdirSync(path.dirname(filePath), { recursive: true });
   writeFileAtomicSync(filePath, JSON.stringify(entries, null, 2));
 }
 
-/** Check whether a host path exists and is a directory. */
 export function isExistingDirectory(hostPath: string): boolean {
   try {
     return statSync(hostPath).isDirectory();