mulmoclaude 0.1.0

package/server/utils/httpError.ts

@@ -0,0 +1,61 @@
+// Helpers for the most common error-response pattern in route
+// handlers:
+//
+//   return res.status(400).json({ error: "..." });
+//
+// Before consolidation this appeared in ~100 places, each handler
+// hand-rolling the `{ error: string }` body and picking a status
+// code. The helpers below keep the call site to one line while
+// centralising the response shape so cross-cutting concerns
+// (e.g. adding a `requestId` or `timestamp` later) only need to
+// change here.
+//
+// All helpers return the `Response` object so callers can write
+// either of:
+//
+//   return badRequest(res, "filePath is required");
+//
+//   badRequest(res, "filePath is required");
+//   return;
+//
+// Non-`{ error: string }` shapes (e.g. `{ success: false, message }`
+// returned by a handful of legacy routes, or multi-field error
+// bodies) stay as explicit `res.status(N).json(...)` calls — the
+// helpers intentionally cover only the dominant pattern.
+
+import type { Response } from "express";
+
+/** Send a `{ error: string }` body with the given HTTP status. */
+export function sendError(res: Response, status: number, error: string): Response {
+  return res.status(status).json({ error });
+}
+
+/** 400 Bad Request — malformed input, missing required field, etc. */
+export function badRequest(res: Response, error: string): Response {
+  return sendError(res, 400, error);
+}
+
+/** 401 Unauthorized — missing or invalid credentials. */
+export function unauthorized(res: Response, error: string): Response {
+  return sendError(res, 401, error);
+}
+
+/** 403 Forbidden — auth present but not authorised for the resource. */
+export function forbidden(res: Response, error: string): Response {
+  return sendError(res, 403, error);
+}
+
+/** 404 Not Found — resource doesn't exist. */
+export function notFound(res: Response, error: string): Response {
+  return sendError(res, 404, error);
+}
+
+/** 409 Conflict — duplicate, concurrent modification, already running, etc. */
+export function conflict(res: Response, error: string): Response {
+  return sendError(res, 409, error);
+}
+
+/** 500 Internal Server Error — unexpected failure on the server side. */
+export function serverError(res: Response, error: string): Response {
+  return sendError(res, 500, error);
+}

package/server/utils/id.ts

@@ -0,0 +1,16 @@
+// Unique-ID generation for persisted records. Previously duplicated
+// in schedulerHandlers, todosHandlers, and todosItemsHandlers —
+// consolidated here as part of the server/utils grouping (#350 CLAUDE.md).
+
+import { randomBytes } from "crypto";
+
+/**
+ * Generate a short, unique, human-scannable ID.
+ *
+ * Format: `<prefix>_<epochMs>_<6 random hex chars>`. The prefix
+ * is required so IDs from different domains (todo, scheduler, column)
+ * are visually distinguishable in logs and JSON files.
+ */
+export function makeId(prefix: string): string {
+  return `${prefix}_${Date.now()}_${randomBytes(3).toString("hex")}`;
+}

package/server/utils/json.ts

@@ -0,0 +1,83 @@
+// Tolerant JSON extraction from Claude CLI text output. Claude
+// often wraps JSON in a ```json fenced block or precedes it with
+// conversational text. These helpers find and parse the first
+// valid JSON object regardless of surrounding prose.
+//
+// Previously lived in workspace/journal/archivist.ts; moved here
+// so any module that calls the Claude CLI can reuse them.
+
+/**
+ * Extract the first JSON object from a Claude CLI response.
+ *
+ * Strategy:
+ *   1. Look for a ```json fenced block — most reliable when present.
+ *   2. Fall back to the first balanced `{...}` block in the raw text.
+ *   3. Return `null` if neither yields valid JSON.
+ */
+export function extractJsonObject(raw: string): unknown | null {
+  const fencedBody = findFencedJsonBody(raw);
+  if (fencedBody !== null) {
+    try {
+      return JSON.parse(fencedBody);
+    } catch {
+      // fall through to scan
+    }
+  }
+  const balanced = findBalancedBraceBlock(raw);
+  if (balanced === null) return null;
+  try {
+    return JSON.parse(balanced);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Find the first balanced `{...}` substring, respecting JSON string
+ * escapes. Uses a char-by-char scan (no regex) to avoid slow-regex
+ * lint warnings and backtracking risks on large LLM output.
+ */
+export function findBalancedBraceBlock(raw: string): string | null {
+  const start = raw.indexOf("{");
+  if (start === -1) return null;
+  let depth = 0;
+  let inString = false;
+  let escape = false;
+  for (let i = start; i < raw.length; i++) {
+    const ch = raw[i];
+    if (escape) {
+      escape = false;
+      continue;
+    }
+    if (ch === "\\") {
+      escape = true;
+      continue;
+    }
+    if (ch === '"') {
+      inString = !inString;
+      continue;
+    }
+    if (inString) continue;
+    if (ch === "{") depth++;
+    if (ch === "}" && --depth === 0) return raw.slice(start, i + 1);
+  }
+  return null;
+}
+
+/**
+ * Extract the body of the first ` ```json ... ``` ` fenced block.
+ * Returns `null` if no fenced block is found.
+ */
+export function findFencedJsonBody(raw: string): string | null {
+  const OPEN = "```json";
+  const CLOSE = "```";
+  const openIdx = raw.indexOf(OPEN);
+  if (openIdx === -1) return null;
+  const afterOpen = openIdx + OPEN.length;
+  const bodyStart = raw.indexOf("\n", afterOpen);
+  if (bodyStart === -1) return null;
+  const closeIdx = raw.indexOf(CLOSE, bodyStart + 1);
+  if (closeIdx === -1) return null;
+  const bodyEnd = raw[closeIdx - 1] === "\n" ? closeIdx - 1 : closeIdx;
+  return raw.slice(bodyStart + 1, bodyEnd);
+}

package/server/utils/logBackgroundError.ts

@@ -0,0 +1,22 @@
+import { log } from "../system/logger/index.js";
+
+/**
+ * Build a `.catch` handler for a fire-and-forget background job that
+ * logs the failure under the given prefix. Consolidates the
+ * "unexpected error in background" pattern used across journal,
+ * chat-index, wiki-backlinks, tool-trace, etc.
+ *
+ * Usage:
+ *
+ *   maybeRunJournal({ ... }).catch(logBackgroundError("journal"));
+ *
+ * The handler never rethrows — the caller's promise chain is
+ * terminated cleanly so nothing propagates into the request path.
+ */
+export function logBackgroundError(prefix: string): (err: unknown) => void {
+  return (err) => {
+    log.warn(prefix, "unexpected error in background", {
+      error: String(err),
+    });
+  };
+}

package/server/utils/markdown.ts

@@ -0,0 +1,82 @@
+// Markdown link rewriting utilities. Originally in
+// workspace/journal/linkRewrite.ts; moved to utils/ so any module
+// (journal, wiki, sources) can reuse them.
+//
+// All functions are pure — no filesystem access.
+
+import path from "node:path";
+
+/**
+ * Rewrite every `[text](/workspace/path)` link in `content` to a
+ * true-relative path computed from the given current-file location.
+ * Non-workspace-absolute links (true relative, external URLs,
+ * anchors) are left untouched.
+ */
+export function rewriteWorkspaceLinks(currentFileWsPath: string, content: string): string {
+  const currentDir = path.posix.dirname(currentFileWsPath);
+  return rewriteMarkdownLinks(content, (href) => {
+    if (href.startsWith("//")) return href;
+    if (!href.startsWith("/")) return href;
+    const target = href.slice(1);
+    if (target.length === 0) return href;
+    const { pathPart, suffix } = splitFragmentAndQuery(target);
+    const rel = path.posix.relative(currentDir, pathPart);
+    const safeRel = rel.length > 0 ? rel : ".";
+    return `${safeRel}${suffix}`;
+  });
+}
+
+/**
+ * Walk through `input` and invoke `rewrite` for every `[text](href)`
+ * it encounters, substituting the returned href. Character-level scan
+ * (no regex) to stay lint-clean.
+ */
+export function rewriteMarkdownLinks(input: string, rewrite: (href: string) => string): string {
+  const parts: string[] = [];
+  let i = 0;
+  while (i < input.length) {
+    if (input[i] !== "[") {
+      parts.push(input[i]);
+      i++;
+      continue;
+    }
+    const closeBracket = input.indexOf("]", i + 1);
+    if (closeBracket === -1) {
+      parts.push(input.slice(i));
+      break;
+    }
+    if (input[closeBracket + 1] !== "(") {
+      parts.push(input.slice(i, closeBracket + 1));
+      i = closeBracket + 1;
+      continue;
+    }
+    const openParen = closeBracket + 1;
+    const closeParen = input.indexOf(")", openParen + 1);
+    if (closeParen === -1) {
+      parts.push(input.slice(i));
+      break;
+    }
+    const linkText = input.slice(i + 1, closeBracket);
+    const href = input.slice(openParen + 1, closeParen);
+    parts.push(`[${linkText}](${rewrite(href)})`);
+    i = closeParen + 1;
+  }
+  return parts.join("");
+}
+
+/**
+ * Split a trailing `#fragment` or `?query` off a path so the caller
+ * can rewrite the path portion and concatenate the suffix back.
+ */
+export function splitFragmentAndQuery(s: string): {
+  pathPart: string;
+  suffix: string;
+} {
+  const hashIdx = s.indexOf("#");
+  const queryIdx = s.indexOf("?");
+  let cut = -1;
+  if (hashIdx !== -1) cut = hashIdx;
+  if (queryIdx !== -1 && (cut === -1 || queryIdx < cut)) cut = queryIdx;
+  if (cut === -1) return { pathPart: s, suffix: "" };
+  return { pathPart: s.slice(0, cut), suffix: s.slice(cut) };
+}

package/server/utils/request.ts

@@ -0,0 +1,29 @@
+// Express request helpers — shared query/param extraction.
+//
+// Centralizes patterns that were duplicated across route handlers
+// (3+ different ways to read `req.query.session`).
+
+// Use a minimal interface so the helpers work with any Express
+// Request generic (Request<object, ...>, Request<Params, ...>, etc.)
+// without type incompatibility.
+interface HasQuery {
+  query: Record<string, unknown>;
+}
+
+/**
+ * Extract the session ID from `req.query.session`.
+ * Returns the string value, or "" if missing/non-string.
+ */
+export function getSessionQuery(req: HasQuery): string {
+  const raw = req.query.session;
+  return typeof raw === "string" ? raw : "";
+}
+
+/**
+ * Extract an optional string query parameter.
+ * Returns the string value, or undefined if missing/non-string.
+ */
+export function getOptionalStringQuery(req: HasQuery, key: string): string | undefined {
+  const raw = req.query[key];
+  return typeof raw === "string" ? raw : undefined;
+}

package/server/utils/slug.ts

@@ -0,0 +1,50 @@
+import { createHash } from "crypto";
+
+// Bits of sha256 kept as the non-ASCII fallback id. 16 base64url chars =
+// 96 bits; birthday-collision expectation lives at ~2^48 entries, so
+// collisions are effectively impossible for any realistic workspace.
+const NON_ASCII_HASH_LEN = 16;
+
+// eslint-disable-next-line no-control-regex
+const NON_ASCII_RE = /[^\x00-\x7F]/;
+
+export function hasNonAscii(input: string): boolean {
+  return NON_ASCII_RE.test(input);
+}
+
+// Deterministic short hash for inputs that can't be represented as an
+// ASCII slug. base64url is URL-safe and denser than hex.
+export function hashSlug(input: string, length: number = NON_ASCII_HASH_LEN): string {
+  return createHash("sha256").update(input, "utf-8").digest("base64url").slice(0, length);
+}
+
+// Validates a slug: lowercase alphanumeric + hyphens, 1–64 chars,
+// no leading/trailing hyphen, no consecutive hyphens. Previously
+// duplicated in sources/paths.ts and skills/paths.ts.
+export function isValidSlug(slug: string): boolean {
+  if (typeof slug !== "string") return false;
+  if (slug.length === 0 || slug.length > 64) return false;
+  if (!/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(slug)) return false;
+  if (slug.includes("--")) return false;
+  return true;
+}
+
+export function slugify(title: string, defaultSlug = "page", maxLength = 60): string {
+  const asciiSlug = title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, maxLength);
+
+  if (!hasNonAscii(title)) return asciiSlug || defaultSlug;
+
+  const hash = hashSlug(title.trim());
+  // Preserve a meaningful ASCII prefix (e.g. "doing (進行中)" → "doing-<hash>")
+  // only when at least 3 chars survived the sanitise step — a shorter
+  // prefix wouldn't help readers distinguish entries.
+  if (asciiSlug.length >= 3) {
+    const prefixMax = Math.max(0, maxLength - hash.length - 1);
+    return `${asciiSlug.slice(0, prefixMax)}-${hash}`;
+  }
+  return hash;
+}

package/server/utils/spawn.ts

@@ -0,0 +1,62 @@
+// Helpers for formatting errors from `spawn`-ed Claude CLI subprocesses.
+// Previously duplicated in chat-index/summarizer, sources/summarize,
+// and sources/classifier — each with its own log prefix but identical
+// logic. Consolidated as part of the server/utils grouping.
+
+import { isRecord } from "./types.js";
+
+const PREVIEW_LEN = 500;
+
+/**
+ * Extract a structured error message from Claude CLI JSON stdout.
+ *
+ * The Claude CLI writes a JSON envelope on stdout when it exits
+ * with an error (budget exhaustion, auth failure, etc.). This
+ * function extracts the human-readable reason from that envelope.
+ * Returns `null` if stdout is not parseable JSON or the envelope
+ * does not indicate an error.
+ */
+export function extractClaudeErrorMessage(stdout: string): string | null {
+  const text = stdout.trim();
+  if (!text) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed)) return null;
+  if (parsed.is_error !== true) return null;
+  if (Array.isArray(parsed.errors) && parsed.errors.length > 0) {
+    const joined = parsed.errors.filter((e): e is string => typeof e === "string").join("; ");
+    if (joined.length > 0) return joined;
+  }
+  const subtype = typeof parsed.subtype === "string" ? parsed.subtype : "";
+  const result = typeof parsed.result === "string" ? parsed.result : "";
+  if (subtype && result) return `${subtype}: ${result}`;
+  return subtype || result || null;
+}
+
+/**
+ * Build a human-readable error message from a Claude CLI spawn failure.
+ *
+ * Tries structured JSON extraction first (stdout), then falls back to
+ * stderr (plain text), then stdout as a last resort. The `prefix` is
+ * prepended for log-grep-ability (e.g. `"[chat-index]"`,
+ * `"[sources/classifier]"`).
+ */
+export function formatSpawnFailure(prefix: string, code: number | null, stdout: string, stderr: string): string {
+  const structured = extractClaudeErrorMessage(stdout);
+  if (structured) {
+    return `${prefix} claude exited ${code}: ${structured}`;
+  }
+  const trimmedStderr = stderr.trim();
+  if (trimmedStderr.length > 0) {
+    return `${prefix} claude exited ${code}: ${trimmedStderr.slice(0, PREVIEW_LEN)}`;
+  }
+  const trimmedStdout = stdout.trim();
+  if (trimmedStdout.length > 0) {
+    return `${prefix} claude exited ${code}: ${trimmedStdout.slice(0, PREVIEW_LEN)}`;
+  }
+  return `${prefix} claude exited ${code}: no error output`;
+}

package/server/utils/time.ts

@@ -0,0 +1,34 @@
+// Common time constants in milliseconds. Avoids magic numbers like
+// 3_600_000 scattered across the codebase.
+//
+// All server-side code should import from here instead of using raw
+// numeric literals. When a specific duration is needed (e.g. a
+// 5-second timeout), express it as `5 * ONE_SECOND_MS`.
+
+export const ONE_SECOND_MS = 1_000;
+export const ONE_MINUTE_MS = 60_000;
+export const ONE_HOUR_MS = 3_600_000;
+export const ONE_DAY_MS = 86_400_000;
+
+/** Map time-unit suffixes (s/m/h) to milliseconds. */
+export const TIME_UNIT_MS: Record<string, number> = {
+  s: ONE_SECOND_MS,
+  m: ONE_MINUTE_MS,
+  h: ONE_HOUR_MS,
+};
+
+// ── Common timeout presets ──────────────────────────────────────
+// Named timeouts for recurring patterns. Prefer these over inline
+// `5 * ONE_SECOND_MS` when the same value is used in 3+ places.
+
+/** Quick subprocess probe (docker ps, libreoffice --version, etc.) */
+export const SUBPROCESS_PROBE_TIMEOUT_MS = 5 * ONE_SECOND_MS;
+
+/** Heavy subprocess work (libreoffice conversion, etc.) */
+export const SUBPROCESS_WORK_TIMEOUT_MS = ONE_MINUTE_MS;
+
+/** CLI subprocess timeout (claude -p for summarization, etc.) */
+export const CLI_SUBPROCESS_TIMEOUT_MS = 5 * ONE_MINUTE_MS;
+
+/** Maximum one-shot notification delay */
+export const MAX_NOTIFICATION_DELAY_SEC = 3_600; // 1 hour in seconds

package/server/utils/types.ts

@@ -0,0 +1,47 @@
+// Shared runtime type guards (#504).
+//
+// Centralised here to eliminate 40+ hand-written inline checks
+// scattered across server/ and src/. Import from this module
+// instead of writing `typeof x !== "object" || x === null`.
+
+/** Narrow `unknown` to a plain object (not null, not array). */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Narrow `unknown` to any object (not null, arrays allowed).
+ *  Use `isRecord` when you need to access string keys. */
+export function isObj(value: unknown): value is object {
+  return typeof value === "object" && value !== null;
+}
+
+/** Non-empty string after trimming whitespace. */
+export function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+/** Record whose values are all strings. */
+export function isStringRecord(value: unknown): value is Record<string, string> {
+  if (!isRecord(value)) return false;
+  return Object.values(value).every((v) => typeof v === "string");
+}
+
+/** String array (every element is a string). */
+export function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+
+/** Error-like object with a `code` property (e.g. Node.js fs errors). */
+export function isErrorWithCode(value: unknown): value is { code: string; message?: string } {
+  return isRecord(value) && typeof value.code === "string";
+}
+
+/** Check that a record has a specific key with a string value. */
+export function hasStringProp<K extends string>(value: unknown, key: K): value is Record<K, string> & Record<string, unknown> {
+  return isRecord(value) && typeof value[key] === "string";
+}
+
+/** Check that a record has a specific key with a number value. */
+export function hasNumberProp<K extends string>(value: unknown, key: K): value is Record<K, number> & Record<string, unknown> {
+  return isRecord(value) && typeof value[key] === "number";
+}

package/server/workspace/chat-index/index.ts

@@ -0,0 +1,153 @@
+// Public entry point for the chat index. The agent route calls
+// `maybeIndexSession({ sessionId, activeSessionIds })` from its
+// `finally` block — fire-and-forget. This module:
+//
+//   - skips sessions still being written by a concurrent request
+//   - holds a per-session lock so double-fires for the same id
+//     become no-ops (two sessions can still index in parallel)
+//   - catches ClaudeCliNotFoundError and disables itself for the
+//     rest of the process lifetime to avoid spamming warnings
+//   - catches unexpected errors and logs them so nothing bubbles
+//     back into the request handler
+//
+// All functions accept an explicit `workspaceRoot` so tests can
+// point at a `mkdtempSync` directory.
+
+import { workspacePath as defaultWorkspacePath } from "../workspace.js";
+import { ClaudeCliNotFoundError } from "../journal/archivist.js";
+import { indexSession, listSessionIds, type IndexerDeps } from "./indexer.js";
+import { log } from "../../system/logger/index.js";
+
+// Per-session lock. Indexing different sessions in parallel is
+// fine; indexing the same session twice concurrently would just
+// burn CLI budget for no benefit.
+const running = new Set<string>();
+
+// Flipped once we hit ENOENT on the `claude` CLI so we stop
+// trying for the lifetime of the server process. Reset on
+// restart.
+let disabled = false;
+
+export interface MaybeIndexSessionOptions {
+  sessionId: string;
+  // Skip indexing if the session is still being appended to by a
+  // concurrent /api/agent request — the jsonl may be mid-write.
+  // Ignored when `force` is true so manual rebuild runs can
+  // re-index even a live session (accepting that the transcript
+  // may be slightly out of date).
+  activeSessionIds?: ReadonlySet<string>;
+  workspaceRoot?: string;
+  deps?: IndexerDeps;
+  // Bypass the activeSessionIds guard and the isFresh throttle
+  // for this call. The per-session lock and the `disabled`
+  // sentinel are still respected — forcing doesn't help if the
+  // claude CLI is missing or the same session is already in
+  // flight.
+  force?: boolean;
+}
+
+// Fire-and-forget entry point. Errors are swallowed here; a
+// defensive `.catch(...)` at the call site is still recommended.
+export async function maybeIndexSession(opts: MaybeIndexSessionOptions): Promise<void> {
+  if (disabled) return;
+
+  const { sessionId } = opts;
+  const force = opts.force === true;
+  if (!force && opts.activeSessionIds?.has(sessionId)) return;
+  if (running.has(sessionId)) return;
+
+  // Thread `force` through the indexer via IndexerDeps so the
+  // freshness throttle is also bypassed on forced runs.
+  const effectiveDeps: IndexerDeps = {
+    ...(opts.deps ?? {}),
+    ...(force ? { force: true } : {}),
+  };
+
+  running.add(sessionId);
+  try {
+    await indexSession(opts.workspaceRoot ?? defaultWorkspacePath, sessionId, effectiveDeps);
+  } catch (err) {
+    if (err instanceof ClaudeCliNotFoundError) {
+      disabled = true;
+      log.warn("chat-index", err.message);
+      return;
+    }
+    log.warn("chat-index", "unexpected failure, continuing", {
+      error: String(err),
+    });
+  } finally {
+    running.delete(sessionId);
+  }
+}
+
+// Debug helper: index every session jsonl under workspace/chat/
+// sequentially with `force: true`. Used by the manual rebuild
+// endpoint and the CHAT_INDEX_FORCE_RUN_ON_STARTUP switch so the
+// user can populate titles for existing sessions without waiting
+// for each one to be revisited.
+//
+// Returns counts for logging. Errors on individual sessions do
+// not stop the walk — the failure is logged and processing
+// continues.
+export interface BackfillResult {
+  total: number;
+  indexed: number;
+  skipped: number;
+}
+
+export async function backfillAllSessions(
+  opts: {
+    workspaceRoot?: string;
+    deps?: IndexerDeps;
+  } = {},
+): Promise<BackfillResult> {
+  const workspaceRoot = opts.workspaceRoot ?? defaultWorkspacePath;
+  const ids = await listSessionIds(workspaceRoot);
+  const result: BackfillResult = {
+    total: ids.length,
+    indexed: 0,
+    skipped: 0,
+  };
+  for (const sessionId of ids) {
+    if (disabled) {
+      result.skipped++;
+      continue;
+    }
+    try {
+      const entry = await indexSession(workspaceRoot, sessionId, {
+        ...(opts.deps ?? {}),
+        force: true,
+      });
+      if (entry) {
+        result.indexed++;
+        log.info("chat-index", "indexed", {
+          sessionId,
+          title: entry.title,
+        });
+      } else {
+        result.skipped++;
+      }
+    } catch (err) {
+      if (err instanceof ClaudeCliNotFoundError) {
+        disabled = true;
+        log.warn("chat-index", err.message);
+        result.skipped++;
+        continue;
+      }
+      result.skipped++;
+      log.warn("chat-index", "failed to index", {
+        sessionId,
+        error: String(err),
+      });
+    }
+  }
+  return result;
+}
+
+// Internal hook: tests need to reset the module-level `disabled`
+// and `running` state between cases because node:test doesn't
+// reload modules. Not part of the public runtime contract.
+export function __resetForTests(): void {
+  disabled = false;
+  running.clear();
+}