mulmoterminal 5.2.0 → 5.3.0

package/README.md

@@ -1220,6 +1220,17 @@ tree; clicking a file opens it in a **CodeMirror** editor (Markdown / JS-TS / JS
 highlighting, everything else as plain text). Markdown files get a **Preview** toggle
 that renders via the server's sandboxed `…/md` HTML. **Save** (or ⌘/Ctrl-S) writes back.
 
+**The open view follows the file on disk.** When an agent in another cell — or any editor —
+rewrites what you are looking at, the editor and the preview catch up on their own; there is
+nothing to reload. If you have unsaved edits of your own, a banner asks which copy to keep
+rather than choosing for you.
+
+The server watches a document while a view is open on it, and only under the workspace or under
+a directory one of your terminals is in — the same directories it serves files from. A Markdown
+file outside all of those still opens and still edits; it is picked up by the pane's periodic
+check rather than the moment it changes, and a Canvas card on it waits for the next thing that
+does announce.
+
 **Beside an enlarged terminal, not only full-screen.** Expand a grid cell (**⤢**) and its
 header gains a **folder** toggle that splits the enlarged area in two: terminal on the left,
 the same explorer + editor on the right, rooted at that cell's directory. Drag the divider
@@ -1228,6 +1239,27 @@ shrinks the pane rather than reflowing xterm into garbage. It works in both zoom
 (cockpit roster and thumbnail filmstrip), the pane re-roots as you walk the zoom between
 terminals, and whether it's open plus how wide it is are remembered per browser.
 
+**Coming back looks the way you left it.** The pane remembers the open file, the directories
+you had expanded, and — for a Markdown file — whether you were reading it in **Preview** or
+editing it: per cell while the session lasts, and per directory across a browser reload (the
+first pane to open on that directory claims it, so a second terminal in the same repository
+starts on its own empty tree). A remembered Preview only comes back over that same file while
+it is still Markdown the server can render; anything else opens in the editor.
+
+It comes back to **where** you were, too: the line at the top of the editor, the line the caret was
+on, and how far down the tree was scrolled. The top line matters on its own — scrolling moves
+neither the selection nor the caret, so someone reading without clicking would otherwise come back
+to the top of a file they were in the middle of. The caret is kept as a line rather than a scroll offset, so it survives
+the pane being a different width next time, and a line past the end of a file that has since been
+edited lands on the nearest real one. The Markdown preview's own scroll position is not remembered
+— its iframe is sandboxed to the point where the app cannot read it.
+
+**It also paints before it has finished reading.** The last listing of each directory is kept, so
+opening the pane on one you have been to before shows that tree at once and swaps in what the
+server says when it arrives — including any directory you expanded while waiting. A directory the
+pane has not read before says so (`Loading…`) rather than claiming to be empty, and a read that
+fails shows the error rather than a tree it can no longer vouch for.
+
 The toggle is not the only way in: while a cell is enlarged, **clicking a file path the agent
 printed** opens it here too, rather than in a new tab or full-screen — see
 [Clicking a file path](#clicking-a-file-path).
@@ -1244,6 +1276,21 @@ than letting you believe an ignore file was applied. There is also a
 [`files-find` shortcut](https://receptron.github.io/mulmoterminal/guide/en/config.html#keymap)
 with no default binding, which opens the pane first if it is closed.
 
+A second button searches **inside** the files. Matches are grouped by file with the matching
+lines under them, and picking one opens the file *and* puts the cursor on that line. Queries are
+literal unless the regex toggle is on, and case is smart — a lower-case query matches either case.
+It is `git grep` underneath, so the same `.gitignore` applies, files your agent created seconds ago
+are searched, and — because the default reads the **working tree** rather than the index — an
+edited-but-unstaged file is searched as it is on disk. The one file no on-disk search can read is
+the one you have open with unsaved edits. In the default literal mode that one is searched in the
+browser from the buffer and marked `unsaved`, so its line numbers are the ones on your screen. In
+**regex mode it is not searched at all** — running a pattern you are still typing on the thread that
+draws the UI can freeze the tab — so the file is left out and the panel says to save it. Either way
+its stale on-disk matches are dropped, because those line numbers describe a file you are not
+looking at. The
+[`files-search` shortcut](https://receptron.github.io/mulmoterminal/guide/en/config.html#keymap)
+is likewise unbound by default.
+
 All reads and writes go through `GET/PUT /api/files/browse/*?cwd=&path=`, and every
 `path` is **contained within the project root** (server-side) — `..`/absolute escapes
 are rejected for reads and writes alike, so editing can't reach outside the directory

package/common/fileChannel.ts

@@ -0,0 +1,42 @@
+// The "this file changed" channel name.
+//
+// Both sides decide it: the server mints it when a file is written or seen to change, and the
+// UI subscribes to it for the document it has open. That makes it a wire shape rather than a
+// server detail, so it lives here.
+//
+// The format is @mulmoclaude/core/file-change's (`pluginFileChannel`), which the UI cannot
+// import — that entry pulls in node:fs. A spec pins this copy to core's rather than trusting
+// the two to stay the same by inspection.
+
+const CHANNEL_PREFIX = "plugin:";
+const PATH_MARKER = ":file:";
+
+/** The scope the markdown plugin's View and the server's markdown matcher agree on. */
+export const MARKDOWN_FILE_SCOPE = "markdown";
+
+/** The channel one file is announced on, under one plugin scope. */
+export function pluginFileChannel(scope: string, posixPath: string): string {
+  return `${CHANNEL_PREFIX}${scope}${PATH_MARKER}${posixPath}`;
+}
+
+/** The scope and path a channel names, or null when it is not one of ours.
+ *
+ *  Split on the FIRST `:file:` only: a POSIX filename may itself contain a colon, so
+ *  everything after that marker is the path verbatim and never re-parsed. */
+export function parsePluginFileChannel(channel: string): { scope: string; path: string } | null {
+  if (!channel.startsWith(CHANNEL_PREFIX)) return null;
+  const rest = channel.slice(CHANNEL_PREFIX.length);
+  const marker = rest.indexOf(PATH_MARKER);
+  if (marker <= 0) return null;
+  const path = rest.slice(marker + PATH_MARKER.length);
+  return path ? { scope: rest.slice(0, marker), path } : null;
+}
+
+/** A path spelled the way the channel spells it.
+ *
+ *  The publisher normalises to POSIX before it mints a channel, so a subscriber that keeps
+ *  Windows separators names a channel nothing is ever published on — and nothing errors,
+ *  which is why this is a function both sides call rather than a rule both sides remember. */
+export function fileChannelPath(filePath: string): string {
+  return filePath.split("\\").join("/");
+}

package/common/fileSearch.ts

@@ -0,0 +1,211 @@
+// What a content search IS, for the two sides that decide it together (#2140).
+//
+// In `common/` because BOTH ends read these rules, not because they happen to share a shape: the
+// server builds git's argv from them, and the browser applies the same literal and case rules to
+// the one file open in the editor with unsaved edits — which no on-disk search can see. If the two
+// drifted, that one file would answer to a different notion of "case-insensitive" than every other
+// file in the list.
+//
+// LITERAL MODE ONLY. In regex mode the browser does not search that buffer at all: the pattern
+// comes from the query, and running one on the thread that draws the UI can hang the tab (the
+// measurement is on `literalMatch`). The file is dropped and the panel says so.
+//
+// The git-specific half — argv, output parsing, the exit codes — stays in
+// `server/files/file-search.ts`, where nothing in the browser has any use for it.
+import { byCodeUnit } from "./byCodeUnit.js";
+
+/** How many matching LINES are returned across the whole search. */
+export const MAX_SEARCH_MATCHES = 500;
+
+/** How many matching lines any ONE file may contribute. Without it a single generated file answers
+ *  the whole budget and the result reads as "only this file matches". */
+export const MAX_MATCHES_PER_FILE = 20;
+
+/** How much of a matching line is carried. A minified bundle is one line of a hundred thousand
+ *  characters, and shipping it whole would cost more than every other result together. */
+export const MAX_SNIPPET_CHARS = 400;
+
+/** Shorter than the shared git timeout: this runs while the user is typing. A repository too slow
+ *  to answer inside it gives an empty result that says it is incomplete, not a hung panel. */
+export const SEARCH_TIMEOUT_MS = 10_000;
+
+export interface SearchRequest {
+  query: string;
+  /** Treat the query as a regular expression rather than as literal characters. */
+  regex: boolean;
+  /** Force case sensitivity. Absent means SMART CASE — see `wantsCaseSensitive`. */
+  caseSensitive?: boolean;
+}
+
+/** One matching line. `line` is 1-based, as git reports it and as an editor counts. */
+export interface SearchMatch {
+  /** Relative to the searched directory, `/`-separated — the same spelling `/api/files/browse/*`
+   *  already speaks, so a result can be opened without translation. */
+  path: string;
+  line: number;
+  /** The matching line, cut to MAX_SNIPPET_CHARS. */
+  text: string;
+  /** The line was longer than the cap and `text` is its beginning. */
+  clipped: boolean;
+}
+
+export interface SearchResult {
+  matches: SearchMatch[];
+  /** Some matches are NOT here — a cap cut the list, or git stopped early. The one wrong answer a
+   *  search can give is "it is not there" when it only means "I did not look at all of it", so this
+   *  is reported rather than inferred from the array's length (which cannot show a per-file cut). */
+  truncated: boolean;
+  /** `git` answered from a repository, so `.gitignore` was applied. `no-index` means it did not —
+   *  there is no ignore file to apply outside a repository, and the UI says so rather than letting
+   *  the reader assume one was read. */
+  source: "git" | "no-index";
+}
+
+/** Smart case: a query typed entirely in lower case matches either case, and one carrying an
+ *  upper-case letter is taken literally. It is what every comparable tool does, which is the whole
+ *  argument — a hand reaches for it without being taught.
+ *
+ *  Decided on the query and NOT on a locale-aware fold: `toLowerCase()` on a Turkish `I` produces a
+ *  dotless `ı` under some locales, so the comparison is against the code points as typed. */
+export function wantsCaseSensitive(request: SearchRequest): boolean {
+  if (request.caseSensitive !== undefined) return request.caseSensitive;
+  return [...request.query].some((ch) => ch !== ch.toLowerCase() && ch === ch.toUpperCase());
+}
+
+/** A query with nothing to search for. Rejected rather than run: an empty pattern matches every
+ *  line of every file, which is a slow way to answer nothing useful. Whitespace alone IS a real
+ *  query — someone looking for a tab or trailing space means it — so only the empty string counts. */
+export const isSearchable = (query: string): boolean => query.length > 0;
+
+/** Matches grouped by file, files in path order and lines in file order — the shape the panel
+ *  renders, decided here so the ordering is one rule rather than one per view.
+ *
+ *  `byCodeUnit` rather than `localeCompare` for the reason the file list already uses it: a locale
+ *  comparison reorders the same project differently on two machines. */
+export function groupByFile(matches: SearchMatch[]): { path: string; matches: SearchMatch[] }[] {
+  const byPath = new Map<string, SearchMatch[]>();
+  matches.forEach((match) => {
+    const existing = byPath.get(match.path);
+    if (existing) existing.push(match);
+    else byPath.set(match.path, [match]);
+  });
+  return [...byPath.keys()].sort(byCodeUnit).map((path) => ({ path, matches: (byPath.get(path) ?? []).sort((a, b) => a.line - b.line) }));
+}
+
+/** Whether a LITERAL query matches a line, under the same case rule the server applies.
+ *
+ *  A plain string search, deliberately — not a RegExp built from the query. `(a+)+b` against a
+ *  THIRTY-TWO character line takes the better part of a minute in a JS engine, so a regex built
+ *  from untrusted text cannot run on the thread that draws the UI: the tab would freeze, taking the
+ *  unsaved buffer this whole mechanism exists to respect with it.
+ *
+ *  Literal is the default mode and needs no regex to begin with, which is what makes the default
+ *  path both correct and unable to hang. Regex mode does not come here at all — see
+ *  `withBufferMatches`. */
+function literalMatch(line: string, request: SearchRequest): boolean {
+  if (wantsCaseSensitive(request)) return line.includes(request.query);
+  return line.toLowerCase().includes(request.query.toLowerCase());
+}
+
+/** The matching lines of one in-memory buffer, in the shape the disk search returns.
+ *
+ *  This exists because an unsaved buffer is invisible to ANY on-disk search — git, ripgrep or a
+ *  hand-rolled scan alike — and the pane can have one. It is affordable precisely because there is
+ *  at most one: `FilesPane` opens a single file, so this is never a scan of a project.
+ *
+ *  LITERAL QUERIES ONLY. The caller decides that; see `withBufferMatches`. */
+export function matchesInBuffer(path: string, text: string, request: SearchRequest): SearchMatch[] {
+  const out: SearchMatch[] = [];
+  text.split("\n").forEach((raw, index) => {
+    if (out.length >= MAX_MATCHES_PER_FILE) return;
+    const line = raw.replace(/\r$/, "");
+    if (!literalMatch(line, request)) return;
+    out.push({ path, line: index + 1, text: line.slice(0, MAX_SNIPPET_CHARS), clipped: line.length > MAX_SNIPPET_CHARS });
+  });
+  return out;
+}
+
+/** What the panel shows, once the open buffer has had its say. */
+export interface BufferMerge {
+  matches: SearchMatch[];
+  /** The open buffer was NOT searched, so a match in it is not in this list. True only in regex
+   *  mode — see `withBufferMatches`. The panel has to SAY this: silence would read as "there is
+   *  nothing in that file", which is the one wrong answer a search can give. */
+  bufferUnsearched: boolean;
+}
+
+/**
+ * Disk matches with the open buffer's own answer substituted for it.
+ *
+ * The trap this closes is the INVERSE of the obvious one. Missing a match in an unsaved file is a
+ * loud failure — nothing appears. But a match found ON DISK in a file that is open and edited is a
+ * QUIET one: the line number and the snippet describe the saved text, so the snippet shows
+ * something not on screen and jumping lands in the wrong place.
+ *
+ * So the file's disk matches are dropped entirely rather than merged: the two describe different
+ * documents and there is no correspondence between their line numbers. **That half holds in BOTH
+ * modes** — it needs no matching at all, only the knowledge that the file has diverged.
+ *
+ * What regex mode loses is the second half: the buffer is not searched, because doing so means
+ * running an untrusted pattern on the UI thread (see `literalMatch`). The file is dropped and the
+ * panel says so, which is the safe direction — a note the reader can act on by saving the file,
+ * rather than a frozen tab or a line number pointing at the wrong place.
+ */
+export function withBufferMatches(diskMatches: SearchMatch[], buffer: { path: string; text: string } | null, request: SearchRequest): BufferMerge {
+  if (!buffer) return { matches: diskMatches, bufferUnsearched: false };
+  const withoutStale = diskMatches.filter((match) => match.path !== buffer.path);
+  if (request.regex) return { matches: withoutStale, bufferUnsearched: true };
+  return { matches: [...withoutStale, ...matchesInBuffer(buffer.path, buffer.text, request)], bufferUnsearched: false };
+}
+
+/** How many lines above and below a selected match the panel shows. Small on purpose: the block
+ *  replaces a one-line row, so every extra line pushes the rest of the list further down. */
+export const CONTEXT_RADIUS_LINES = 2;
+
+/** One line of a context window. Carries `clipped` for the reason `SearchMatch` does — a silently
+ *  cut line is indistinguishable from a short one, and a minified file's single line is enormous. */
+export interface WindowLine {
+  text: string;
+  clipped: boolean;
+}
+
+/** The lines around one line of a file. */
+export interface LineWindow {
+  /** 1-based line number of `lines[0]`. Meaningless when `lines` is empty. */
+  from: number;
+  lines: WindowLine[];
+}
+
+/**
+ * The lines around `around` (1-based), clamped to the text.
+ *
+ * In `common/` because BOTH sides run it: the server over a file it read from disk, the browser
+ * over the buffer being edited — whose surroundings no on-disk read can produce. One rule rather
+ * than two, so the file on screen does not get a different notion of "the lines around this one"
+ * than every other file in the list.
+ *
+ * `around` past the end gives an EMPTY window rather than the tail of the file. The search answered
+ * before this read, so a file that shrank in between has no such line — and the tail would be
+ * numbered correctly while still being wrong: it would surround a match that is no longer there
+ * with a neighbourhood that looks real. Nothing at all says what is true, which is that the line
+ * the caller asked about is gone.
+ *
+ * The clause earns its place only at the BOUNDARY — one line past the end, where `to < from` has
+ * not yet become true on its own. Anything further out is already empty without it.
+ */
+export function lineWindow(text: string, around: number, radius: number): LineWindow {
+  const split = text.split("\n");
+  // A file ending in a newline splits into a trailing "" that is not a line — git does not count
+  // it and neither does an editor. Only ONE is dropped: "a\n\n" really does have a blank line 2.
+  const all = split.length > 1 && split[split.length - 1] === "" ? split.slice(0, -1) : split;
+  const from = Math.max(1, around - radius);
+  const to = Math.min(all.length, around + radius);
+  if (around > all.length || to < from) return { from, lines: [] };
+  return {
+    from,
+    lines: all.slice(from - 1, to).map((raw) => {
+      const line = raw.replace(/\r$/, "");
+      return { text: line.slice(0, MAX_SNIPPET_CHARS), clipped: line.length > MAX_SNIPPET_CHARS };
+    }),
+  };
+}

package/common/keymap.ts

@@ -25,6 +25,7 @@ export const KEYMAP_ACTIONS = [
   "terminal-close",
   "terminal-restart",
   "files-find",
+  "files-search",
   "copy",
   "paste",
 ] as const;
@@ -52,9 +53,9 @@ export const TERMINAL_SCOPED_ACTIONS: readonly KeymapAction[] = ["copy", "paste"
 // Here rather than beside gridShortcutFor because BOTH sides decide from it: the grid dispatches on
 // it, and validateKeymap has to know that these decline the key — the handler returns WITHOUT
 // stopping the event, so a `send` on the same keystroke fires instead (codex on #1906).
-// `files-find` is here because the pane it opens exists only in the ENLARGED row (see
-// docs/grid-view-modes.md) — a tiled grid has nowhere to put it, so the key declines rather than
-// guessing which of nine terminals was meant.
+// `files-find` and `files-search` are here because the pane they open exists only in the ENLARGED
+// row (see docs/grid-view-modes.md) — a tiled grid has nowhere to put it, so the key declines
+// rather than guessing which of nine terminals was meant.
 export const NEEDS_A_CURRENT_TERMINAL: readonly KeymapAction[] = [
   "zoom-next",
   "zoom-prev",
@@ -62,6 +63,7 @@ export const NEEDS_A_CURRENT_TERMINAL: readonly KeymapAction[] = [
   "terminal-close",
   "terminal-restart",
   "files-find",
+  "files-search",
 ];
 
 // The mirror of the list above: actions that walk the TILED grid, and so need nothing enlarged.