mulmoclaude 0.1.0

package/server/utils/files/index.ts

@@ -0,0 +1,45 @@
+// 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)
+
+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 {
+  resolveWorkspacePath,
+  resolvePath,
+  readWorkspaceText,
+  readWorkspaceTextSync,
+  readWorkspaceJson,
+  readWorkspaceJsonSync,
+  writeWorkspaceText,
+  writeWorkspaceTextSync,
+  writeWorkspaceJson,
+  existsInWorkspace,
+  ensureWorkspaceDir,
+  readTextUnder,
+  writeTextUnder,
+  readdirUnder,
+  statUnder,
+  ensureDirUnder,
+} from "./workspace-io.js";
+
+// ── Domain I/O ──────────────────────────────────────────────────
+export * from "./session-io.js";
+export * from "./todos-io.js";
+export * from "./scheduler-io.js";
+export * from "./html-io.js";
+export * from "./reference-dirs-io.js";
+export * from "./scheduler-overrides-io.js";

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

@@ -0,0 +1,213 @@
+// 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";
+import { writeFileAtomic } from "./atomic.js";
+import { isEnoent } from "./safe.js";
+import { log } from "../../system/logger/index.js";
+import { summariesRoot, dailyPathFor, topicPathFor, TOPICS_DIR, INDEX_FILE, STATE_FILE, DAILY_DIR, ARCHIVE_DIR } from "../../workspace/journal/paths.js";
+
+import fs 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 {
+    fs.statSync(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function readJournalState<T>(fallback: T, rootOverride?: string): Promise<T> {
+  const filePath = path.join(summariesRoot(root(rootOverride)), STATE_FILE);
+  try {
+    return JSON.parse(await fsp.readFile(filePath, "utf-8")) as T;
+  } catch (err) {
+    if (isEnoent(err)) return fallback;
+    log.error("journal-io", "readJournalState failed", { error: String(err) });
+    return fallback;
+  }
+}
+
+export async function writeJournalState(state: unknown, rootOverride?: string): Promise<void> {
+  const filePath = path.join(summariesRoot(root(rootOverride)), STATE_FILE);
+  await writeFileAtomic(filePath, JSON.stringify(state, null, 2));
+}
+
+// ── Index ───────────────────────────────────────────────────────
+
+export async function writeJournalIndex(md: string, rootOverride?: string): Promise<void> {
+  const filePath = path.join(summariesRoot(root(rootOverride)), INDEX_FILE);
+  await writeFileAtomic(filePath, md);
+}
+
+// ── Daily summaries ─────────────────────────────────────────────
+
+export async function readDailySummary(date: string, rootOverride?: string): Promise<string | null> {
+  try {
+    return await fsp.readFile(dailyPathFor(root(rootOverride), date), "utf-8");
+  } catch (err) {
+    if (isEnoent(err)) return null;
+    log.error("journal-io", `readDailySummary(${date}) failed`, {
+      error: String(err),
+    });
+    return null;
+  }
+}
+
+export async function writeDailySummary(date: string, content: string, rootOverride?: string): Promise<void> {
+  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.
+    throw err;
+  }
+}
+
+export async function writeTopicFile(slug: string, content: string, rootOverride?: string): Promise<void> {
+  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) {
+    await writeTopicFile(slug, content, rootOverride);
+    return "created";
+  }
+  await writeTopicFile(slug, `${existing.trimEnd()}\n\n${content}\n`, rootOverride);
+  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 {
+    const files = await fsp.readdir(dir);
+    return files.filter((file) => file.endsWith(".md")).map((file) => file.replace(/\.md$/, ""));
+  } catch (err) {
+    if (isEnoent(err)) return [];
+    log.error("journal-io", "listTopicSlugs failed", { error: String(err) });
+    return [];
+  }
+}
+
+/** 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>();
+  let files: string[];
+  try {
+    files = await fsp.readdir(dir);
+  } catch {
+    return out;
+  }
+  for (const file of files) {
+    if (!file.endsWith(".md")) continue;
+    try {
+      const content = await fsp.readFile(path.join(dir, file), "utf-8");
+      out.set(file.replace(/\.md$/, ""), content);
+    } catch {
+      // skip unreadable files
+    }
+  }
+  return out;
+}
+
+/** Move a topic to the archive directory. 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`);
+  try {
+    await fsp.mkdir(path.dirname(dst), { recursive: true });
+    await fsp.rename(src, dst);
+    return true;
+  } catch (err) {
+    log.warn("journal-io", `archiveTopic(${slug}) failed`, {
+      error: String(err),
+    });
+    return false;
+  }
+}
+
+// ── Daily file listing ──────────────────────────────────────────
+
+export interface DailyFileEntry {
+  year: string;
+  month: string;
+  day: string;
+}
+
+export async function listDailyFiles(rootOverride?: string): Promise<DailyFileEntry[]> {
+  const dailyRoot = path.join(summariesRoot(root(rootOverride)), DAILY_DIR);
+  const years = await safeReaddir(dailyRoot);
+  const out: DailyFileEntry[] = [];
+  for (const year of years.filter(isYearDir)) {
+    const entries = await listDaysForYear(dailyRoot, year);
+    out.push(...entries);
+  }
+  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[] = [];
+  for (const month of months.filter(isMonthDir)) {
+    const dayFiles = await safeReaddir(path.join(dailyRoot, year, month));
+    for (const dayFile of dayFiles) {
+      if (dayFile.endsWith(".md")) {
+        out.push({ year, month, day: dayFile.replace(/\.md$/, "") });
+      }
+    }
+  }
+  return out;
+}
+
+async function safeReaddir(dir: string): Promise<string[]> {
+  try {
+    return await fsp.readdir(dir);
+  } catch {
+    return [];
+  }
+}
+
+// ── Archived topic count ────────────────────────────────────────
+
+export async function countArchivedTopics(rootOverride?: string): Promise<number> {
+  const dir = path.join(summariesRoot(root(rootOverride)), ARCHIVE_DIR, TOPICS_DIR);
+  try {
+    const files = await fsp.readdir(dir);
+    return files.filter((file) => file.endsWith(".md")).length;
+  } catch {
+    return 0;
+  }
+}

package/server/utils/files/json.ts

@@ -0,0 +1,69 @@
+// 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 fs from "fs";
+import path from "path";
+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).
+ */
+export function loadJsonFile<T>(filePath: string, defaultValue: T): T {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(filePath, "utf-8");
+  } catch (err) {
+    if (isEnoent(err)) return defaultValue;
+    log.error("json", "loadJsonFile read failed", {
+      path: filePath,
+      error: String(err),
+    });
+    throw err;
+  }
+  try {
+    return JSON.parse(raw) as T;
+  } catch (err) {
+    log.error("json", "loadJsonFile parse failed, using default", {
+      path: filePath,
+      error: String(err),
+    });
+    return defaultValue;
+  }
+}
+
+export function saveJsonFile(filePath: string, data: unknown): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.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 fs.promises.readFile(filePath, "utf-8");
+    const parsed: T = JSON.parse(content);
+    return parsed;
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,33 @@
+import fs from "fs/promises";
+import path from "path";
+import { workspacePath } from "../../workspace/workspace.js";
+import { WORKSPACE_DIRS } from "../../workspace/paths.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.
+ */
+export async function saveMarkdown(content: string, prefix: string): Promise<string> {
+  const relPath = buildArtifactPathRandom(WORKSPACE_DIRS.markdowns, prefix, ".md", "document");
+  await fs.writeFile(path.join(workspacePath, relPath), content, "utf-8");
+  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 fs.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 fs.writeFile(absPath, content, "utf-8");
+}
+
+/** Check if a string is a markdown file path (not inline content). */
+export function isMarkdownPath(value: string): boolean {
+  return value.startsWith(`${WORKSPACE_DIRS.markdowns}/`) && value.endsWith(".md");
+}

package/server/utils/files/naming.ts

@@ -0,0 +1,50 @@
+// 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 crypto from "node:crypto";
+import { slugify } from "../slug.js";
+
+// Length of the random hex suffix appended by `buildArtifactPathRandom`.
+// 16 chars = 64 bits ≈ birthday-collision at 2^32 entries — effectively
+// impossible for any realistic per-workspace artifact volume.
+const RANDOM_SUFFIX_LEN = 16;
+
+/**
+ * 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/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, 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
+ */
+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.
+  const slug = slugify(prefix, fallbackSlug);
+  const id = crypto.randomUUID().replace(/-/g, "").slice(0, RANDOM_SUFFIX_LEN);
+  const fname = `${slug}-${id}${ext}`;
+  return path.posix.join(dir, fname);
+}

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

@@ -0,0 +1,45 @@
+// 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 fs from "fs";
+import path from "path";
+import { WORKSPACE_DIRS, workspacePath } from "../../workspace/paths.js";
+import { loadJsonFile } from "./json.js";
+import { writeFileAtomicSync } from "./atomic.js";
+import { log } from "../../system/logger/index.js";
+
+const CONFIG_FILE_NAME = "reference-dirs.json";
+
+function configPath(root: string): string {
+  return path.join(root, WORKSPACE_DIRS.configs, CONFIG_FILE_NAME);
+}
+
+/** Read reference-dirs.json. Returns [] on missing/corrupt file. */
+export function readReferenceDirsJson(root?: string): unknown[] {
+  const filePath = configPath(root ?? workspacePath);
+  const parsed = loadJsonFile<unknown>(filePath, []);
+  if (!Array.isArray(parsed)) {
+    log.warn("reference-dirs-io", "reference-dirs.json is not an array");
+    return [];
+  }
+  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);
+  fs.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 fs.statSync(hostPath).isDirectory();
+  } catch {
+    return false;
+  }
+}

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

@@ -0,0 +1,45 @@
+// Domain I/O: custom roles
+//   config/roles/<id>.json
+//
+// Optional `root` for test DI.
+
+import path from "node:path";
+import fs from "node:fs";
+import { WORKSPACE_DIRS } from "../../workspace/paths.js";
+import { workspacePath } from "../../workspace/paths.js";
+import { writeFileAtomicSync } from "./atomic.js";
+import { isEnoent } from "./safe.js";
+
+const root = (r?: string) => r ?? workspacePath;
+
+function roleFilePath(id: string, r?: string): string {
+  return path.join(root(r), WORKSPACE_DIRS.roles, `${id}.json`);
+}
+
+/** Check if a custom role file exists. */
+export function roleExists(id: string, r?: string): boolean {
+  try {
+    fs.statSync(roleFilePath(id, r));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Delete a custom role file. Returns false if not found. */
+export function deleteRole(id: string, r?: string): boolean {
+  try {
+    fs.unlinkSync(roleFilePath(id, r));
+    return true;
+  } catch (err) {
+    if (isEnoent(err)) return false;
+    throw err;
+  }
+}
+
+/** Save (create or overwrite) a custom role file atomically. */
+export function saveRole(id: string, data: unknown, r?: string): void {
+  const dir = path.join(root(r), WORKSPACE_DIRS.roles);
+  fs.mkdirSync(dir, { recursive: true });
+  writeFileAtomicSync(roleFilePath(id, r), JSON.stringify(data, null, 2));
+}

package/server/utils/files/safe.ts

@@ -0,0 +1,106 @@
+// Safe filesystem wrappers that swallow ENOENT / EACCES so callers
+// can do `if (result === null)` instead of try/catch boilerplate.
+//
+// `resolveWithinRoot` is the realpath-based path-traversal check
+// that underpins every endpoint serving files out of the workspace.
+//
+// Moved from server/utils/fs.ts (issue #366 Phase 1). The old
+// file re-exports these for backwards compat.
+
+import fs from "fs";
+import path from "path";
+import { isErrorWithCode } from "../types.js";
+
+/** Check if an error is ENOENT (file/dir not found). */
+export function isEnoent(err: unknown): boolean {
+  return isErrorWithCode(err) && err.code === "ENOENT";
+}
+
+/** Read a binary file by absolute path. Null on ENOENT. */
+export function readBinarySafeSync(absPath: string): Buffer | null {
+  try {
+    return fs.readFileSync(absPath);
+  } catch {
+    return null;
+  }
+}
+
+/** Read a text file by absolute path (async). Null on ENOENT. */
+export async function readTextSafe(absPath: string): Promise<string | null> {
+  try {
+    return await fs.promises.readFile(absPath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+/** Read a text file by absolute path (sync). Null on ENOENT. */
+export function readTextSafeSync(absPath: string): string | null {
+  try {
+    return fs.readFileSync(absPath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+export function statSafe(absPath: string): fs.Stats | null {
+  try {
+    return fs.statSync(absPath);
+  } catch {
+    return null;
+  }
+}
+
+export async function statSafeAsync(absPath: string): Promise<fs.Stats | null> {
+  try {
+    return await fs.promises.stat(absPath);
+  } catch {
+    return null;
+  }
+}
+
+export function readDirSafe(absPath: string): fs.Dirent[] {
+  try {
+    return fs.readdirSync(absPath, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+export async function readDirSafeAsync(absPath: string): Promise<fs.Dirent[]> {
+  try {
+    return await fs.promises.readdir(absPath, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+export async function readTextOrNull(file: string): Promise<string | null> {
+  try {
+    return await fs.promises.readFile(file, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve a relative path against a root, ensuring the result stays
+ * inside the root after symlink resolution. Returns null on traversal
+ * or if either path doesn't exist on disk.
+ *
+ * `rootReal` MUST already be a realpath.
+ */
+export function resolveWithinRoot(rootReal: string, relPath: string): string | null {
+  const normalized = path.normalize(relPath || "");
+  const resolved = path.resolve(rootReal, normalized);
+  let resolvedReal: string;
+  try {
+    resolvedReal = fs.realpathSync(resolved);
+  } catch {
+    return null;
+  }
+  if (resolvedReal !== rootReal && !resolvedReal.startsWith(rootReal + path.sep)) {
+    return null;
+  }
+  return resolvedReal;
+}

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

@@ -0,0 +1,20 @@
+// Domain I/O: scheduler items
+//   data/scheduler/items.json
+//
+// Sync API. Optional `root` for test DI.
+
+import { WORKSPACE_FILES } from "../../workspace/paths.js";
+import { workspacePath } from "../../workspace/paths.js";
+import { resolvePath } from "./workspace-io.js";
+import { loadJsonFile } from "./json.js";
+import { writeFileAtomicSync } from "./atomic.js";
+
+const root = (r?: string) => r ?? workspacePath;
+
+export function loadSchedulerItems<T>(fallback: T, r?: string): T {
+  return loadJsonFile(resolvePath(root(r), WORKSPACE_FILES.schedulerItems), fallback);
+}
+
+export function saveSchedulerItems(items: unknown, r?: string): void {
+  writeFileAtomicSync(resolvePath(root(r), WORKSPACE_FILES.schedulerItems), JSON.stringify(items, null, 2));
+}