@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/shared/lib/format/time.test.ts

@@ -0,0 +1,113 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Time formatting for the chat timeline.
+ *
+ * The live stream sends a preformatted "Today, 10:30 AM" label that `new Date()`
+ * cannot parse, so `parseTodayLabel` resolves it against the CURRENT day and
+ * `formatMessageStamp` has to route three shapes correctly: an already-"Today,"
+ * label, a bare clock time, and a historical date. A wrong route shows the wrong
+ * day, which is exactly the class of bug this module exists to prevent.
+ * `formatTimestamp` is a best-effort tool-detail stamp: numbers go through the
+ * runtime's locale clock, strings pass through, and anything else is empty —
+ * it must never invent an ISO date.
+ *
+ * All dates here are built from local components (or ISO strings without a zone,
+ * which JS parses as local), so the assertions hold in any timezone.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { formatClock, formatMessageStamp, formatTimestamp, parseTodayLabel } from '@/shared/lib/format/time';
+
+describe('formatClock', () => {
+  test('renders a 12-hour clock with a zero-padded hour', () => {
+    expect(formatClock(new Date(2026, 0, 1, 14, 5))).toBe('02:05 PM');
+    expect(formatClock(new Date(2026, 0, 1, 9, 7))).toBe('09:07 AM');
+  });
+
+  test('midnight and noon use 12', () => {
+    expect(formatClock(new Date(2026, 0, 1, 0, 0))).toBe('12:00 AM');
+    expect(formatClock(new Date(2026, 0, 1, 12, 0))).toBe('12:00 PM');
+  });
+
+  test('accepts an epoch-ms number', () => {
+    expect(formatClock(new Date(2026, 0, 1, 9, 7).getTime())).toBe('09:07 AM');
+  });
+});
+
+describe('parseTodayLabel', () => {
+  test('resolves a Today label against the current local day', () => {
+    const ms = parseTodayLabel('Today, 10:30 AM');
+    expect(ms).not.toBeNull();
+    const parsed = new Date(ms as number);
+    expect(parsed.getHours()).toBe(10);
+    expect(parsed.getMinutes()).toBe(30);
+    expect(parsed.toDateString()).toBe(new Date().toDateString());
+  });
+
+  test('rejects anything that is not a Today label', () => {
+    expect(parseTodayLabel('Yesterday, 10:30 AM')).toBeNull();
+    expect(parseTodayLabel('2026-01-01')).toBeNull();
+  });
+
+  test('rejects a Today label whose time part cannot be parsed', () => {
+    expect(parseTodayLabel('Today, not a time')).toBeNull();
+    expect(parseTodayLabel('Today, 25:99')).toBeNull();
+  });
+});
+
+describe('formatMessageStamp', () => {
+  test('is empty without a timestamp or date', () => {
+    expect(formatMessageStamp()).toBe('');
+    expect(formatMessageStamp({})).toBe('');
+  });
+
+  test('prefers the timestamp over the date', () => {
+    expect(formatMessageStamp({ timestamp: '2026-01-02T03:04:00', date: '2026-01-01T00:00:00' })).toBe(
+      'Jan 2, 03:04 AM',
+    );
+  });
+
+  test('falls back to the date field', () => {
+    expect(formatMessageStamp({ date: '2026-01-02T03:04:00' })).toBe('Jan 2, 03:04 AM');
+  });
+
+  test('normalizes an already-Today label', () => {
+    expect(formatMessageStamp({ timestamp: 'Today, 10:30 AM' })).toBe('Today, 10:30 AM');
+    expect(formatMessageStamp({ timestamp: 'Today,10:30 AM' })).toBe('Today, 10:30 AM');
+  });
+
+  test('resolves a bare clock time against today', () => {
+    expect(formatMessageStamp({ timestamp: '10:30 AM' })).toBe('Today, 10:30 AM');
+    expect(formatMessageStamp({ timestamp: '3:05 pm' })).toBe('Today, 03:05 PM');
+  });
+
+  test('an unparseable value is empty', () => {
+    expect(formatMessageStamp({ timestamp: 'not a date' })).toBe('');
+  });
+});
+
+describe('formatTimestamp', () => {
+  test('renders an epoch-ms value as a locale clock time, not an ISO date', () => {
+    const result = formatTimestamp(new Date(2026, 0, 1, 14, 5).getTime());
+    expect(result).toMatch(/:/);
+    expect(result).not.toMatch(/[T-]/);
+  });
+
+  test('passes a string through unchanged', () => {
+    expect(formatTimestamp('10:30')).toBe('10:30');
+  });
+
+  test('is empty for invalid numbers and non-string, non-number values', () => {
+    expect(formatTimestamp(Number.NaN)).toBe('');
+    expect(formatTimestamp(Number.POSITIVE_INFINITY)).toBe('');
+    expect(formatTimestamp(null)).toBe('');
+    expect(formatTimestamp(undefined)).toBe('');
+    expect(formatTimestamp(true)).toBe('');
+    expect(formatTimestamp({})).toBe('');
+  });
+});

package/src/shared/lib/format/time.ts

@@ -0,0 +1,58 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Shared time formatters for the chat timeline: the live-stream path carries a
+ * preformatted "Today, 10:30 AM" label that `new Date()` cannot parse, so both
+ * the footer display and the run-duration math resolve it against today's date.
+ */
+
+/** "10:30 AM" — 12-hour clock used by every message timestamp. */
+export function formatClock(value: Date | number = new Date()): string {
+  return new Date(value).toLocaleTimeString('en-US', { hour: '2-digit', minute: '2-digit' });
+}
+
+/**
+ * Resolve a preformatted `"Today, <time>"` label to epoch ms against the
+ * current day. Returns null when the label is not a "Today," value or its time
+ * part cannot be parsed.
+ */
+export function parseTodayLabel(raw: string): number | null {
+  if (!raw.startsWith('Today,')) return null;
+  const time = raw.slice('Today,'.length).trim();
+  const parsed = new Date(`${new Date().toDateString()} ${time}`);
+  return Number.isNaN(parsed.getTime()) ? null : parsed.getTime();
+}
+
+/**
+ * Timeline stamp for a message row / run footer: `"Today, 10:30 AM"` for the
+ * live path, `"Sep 9, 04:43 AM"` for historical rows, empty when unparseable.
+ */
+export function formatMessageStamp(msg?: { date?: string; timestamp?: string }): string {
+  const raw = msg?.timestamp || msg?.date;
+  if (!raw) return '';
+  if (raw.startsWith('Today,')) return `Today, ${raw.slice('Today,'.length).trim()}`;
+  // Bare "10:30 AM" timestamp (live path) — resolve against today.
+  if (/^\d{1,2}:\d{2}\s*(AM|PM)$/i.test(raw)) {
+    const parsedMs = parseTodayLabel(`Today, ${raw}`);
+    if (parsedMs !== null) return `Today, ${formatClock(parsedMs)}`;
+  }
+  const date = new Date(raw);
+  if (Number.isNaN(date.getTime())) return '';
+  const day = date.toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
+  return `${day}, ${formatClock(date)}`;
+}
+
+/**
+ * Best-effort tool-detail timestamp: epoch-ms renders as the runtime's default
+ * locale time, a string passes through, anything else renders empty.
+ */
+export function formatTimestamp(value: unknown): string {
+  if (typeof value === 'number') {
+    const d = new Date(value);
+    return Number.isNaN(d.getTime()) ? '' : d.toLocaleTimeString();
+  }
+  return typeof value === 'string' ? value : '';
+}

package/src/shared/lib/fs/browse.ts

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `/api/fs/browse` — the directory listing behind the New Workspace modal and
+ * the folder picker.
+ *
+ * One module for both, because the two surfaces render the SAME listing and a
+ * second copy of the response shape is how they drift: the picker's local
+ * `DirectoryEntry` and the modal's would be structurally identical and
+ * independently maintained.
+ *
+ * The response's `path` is the server's own resolution of what was asked for
+ * (`~` expanded, made absolute), and callers are expected to adopt it — that
+ * is what keeps a path field and the listing it describes naming the same
+ * directory.
+ */
+
+export interface DirectoryEntry {
+  name: string;
+  path: string;
+}
+
+export interface BrowseResponse {
+  /** The resolved directory the listing came from. */
+  path?: string;
+  /** The parent directory, or null at the browse root (the OS home). */
+  parentPath?: string | null;
+  directories?: DirectoryEntry[];
+  error?: string;
+  code?: string;
+}
+
+/** Read one directory's subfolders. Omitting `path` starts at the OS home. */
+export async function fetchDirectories(path?: string): Promise<BrowseResponse> {
+  const query = path ? `?path=${encodeURIComponent(path)}` : '';
+  const res = await fetch(`/api/fs/browse${query}`);
+  const data = (await res.json()) as BrowseResponse;
+  if (!res.ok || data.error) {
+    throw new Error(data.error || `HTTP ${res.status}`);
+  }
+  return data;
+}

package/src/shared/lib/fs/clipboard.test.ts

@@ -0,0 +1,182 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The clipboard rules both ends share.
+ *
+ * Each case here is a rule a naive implementation gets wrong in a way that is
+ * invisible until it destroys something: a name ladder that appends the suffix
+ * after the extension (`report.md copy`, which every editor reads as a new file
+ * type), a paste onto an existing name that overwrites it, and a folder pasted
+ * into its own subtree (which cannot terminate).
+ */
+
+import { describe, expect, test } from 'bun:test';
+import {
+  dropRefusal,
+  duplicateName,
+  fsClipboardScope,
+  parentOf,
+  pasteRefusal,
+  pasteTargetDir,
+  readFsClipboard,
+  transferRefusal,
+  uniqueName,
+  type FsClipboard,
+} from '@/shared/lib/fs/clipboard';
+
+const clip = (over: Partial<FsClipboard> = {}): FsClipboard => ({
+  scope: 'ws\u0000.',
+  path: 'src/a.ts',
+  name: 'a.ts',
+  kind: 'file',
+  mode: 'copy',
+  ...over,
+});
+
+describe('uniqueName', () => {
+  test('returns the name unchanged when it is free', () => {
+    expect(uniqueName('a.ts', () => false)).toBe('a.ts');
+  });
+
+  test('keeps the extension at the end of the copy name', () => {
+    // `report.v2.md copy` reads as a different file type; `report.v2 copy.md`
+    // does not. The extension is what an editor keys off.
+    const taken = new Set(['report.v2.md']);
+    expect(uniqueName('report.v2.md', (c) => taken.has(c))).toBe('report.v2 copy.md');
+  });
+
+  test('walks to the first free numbered copy', () => {
+    const taken = new Set(['a.ts', 'a copy.ts', 'a copy 2.ts']);
+    expect(uniqueName('a.ts', (c) => taken.has(c))).toBe('a copy 3.ts');
+  });
+
+  test('a dot-file is treated as having no extension', () => {
+    const taken = new Set(['.env']);
+    expect(uniqueName('.env', (c) => taken.has(c))).toBe('.env copy');
+  });
+});
+
+describe('duplicateName', () => {
+  test('a file takes the copy ladder', () => {
+    const taken = new Set(['a.ts']);
+    expect(duplicateName('a.ts', 'file', (c) => taken.has(c))).toBe('a copy.ts');
+  });
+
+  test('a folder takes `name copy`, with no extension to preserve', () => {
+    const taken = new Set(['src']);
+    expect(duplicateName('src', 'folder', (c) => taken.has(c))).toBe('src copy');
+    expect(duplicateName('src', 'folder', (c) => c === 'src copy')).toBe('src copy 2');
+  });
+});
+
+describe('pasteTargetDir', () => {
+  test('a folder is its own destination; a file’s is its directory', () => {
+    expect(pasteTargetDir('src', 'folder')).toBe('src');
+    expect(pasteTargetDir('src/deep/a.ts', 'file')).toBe('src/deep');
+    expect(pasteTargetDir('a.ts', 'file')).toBe('.');
+  });
+});
+
+describe('transferRefusal', () => {
+  test('allows a folder pasted beside itself and into a sibling', () => {
+    expect(transferRefusal({ path: 'src', kind: 'folder' }, '.')).toBeNull();
+    expect(transferRefusal({ path: 'src', kind: 'folder' }, 'other')).toBeNull();
+  });
+
+  test('refuses a folder pasted into its own subtree — which cannot terminate', () => {
+    expect(transferRefusal({ path: 'src', kind: 'folder' }, 'src')).toBe('Cannot paste a folder into itself');
+    expect(transferRefusal({ path: 'src', kind: 'folder' }, 'src/deep')).toBe('Cannot paste a folder into itself');
+  });
+
+  test('a FILE may land inside a folder of the same name — no recursion to guard', () => {
+    expect(transferRefusal({ path: 'src', kind: 'file' }, 'src')).toBeNull();
+  });
+
+  test('refuses the root itself as a source', () => {
+    expect(transferRefusal({ path: '.', kind: 'folder' }, 'src')).toContain('workspace root');
+    expect(transferRefusal({ path: '', kind: 'folder' }, '.')).toContain('workspace root');
+  });
+});
+
+describe('parentOf', () => {
+  test('a nested path names its directory; a top-level one names the root', () => {
+    expect(parentOf('src/deep/a.ts')).toBe('src/deep');
+    expect(parentOf('src')).toBe('.');
+    expect(parentOf('a.ts')).toBe('.');
+  });
+});
+
+describe('dropRefusal', () => {
+  test('allows a drop into a sibling folder and onto the root', () => {
+    expect(dropRefusal({ path: 'src/a.ts', kind: 'file' }, 'other')).toBeNull();
+    expect(dropRefusal({ path: 'src/a.ts', kind: 'file' }, '.')).toBeNull();
+    expect(dropRefusal({ path: 'src', kind: 'folder' }, 'other')).toBeNull();
+  });
+
+  test('refuses a drop into the folder the entry already lives in', () => {
+    // A drag is a move, so this is a no-op with nothing to report — and
+    // `dragover` must not draw a drop cursor for it.
+    expect(dropRefusal({ path: 'src/a.ts', kind: 'file' }, 'src')).toBe('Already in this folder');
+    expect(dropRefusal({ path: 'a.ts', kind: 'file' }, '.')).toBe('Already in this folder');
+    expect(dropRefusal({ path: 'src', kind: 'folder' }, '.')).toBe('Already in this folder');
+  });
+
+  test('refuses a folder dropped into its own subtree', () => {
+    expect(dropRefusal({ path: 'src', kind: 'folder' }, 'src/deep')).toContain('itself');
+  });
+});
+
+describe('pasteRefusal', () => {
+  test('reports an empty clipboard rather than pasting nothing', () => {
+    expect(pasteRefusal(null, 'ws\u0000.', '.')).toBe('Nothing to paste');
+  });
+
+  test('refuses an entry taken from another listing', () => {
+    expect(pasteRefusal(clip({ scope: 'other\u0000.' }), 'ws\u0000.', '.')).toContain('another workspace');
+  });
+
+  test('allows a paste of this listing’s entry and applies the folder rule', () => {
+    expect(pasteRefusal(clip(), 'ws\u0000.', 'other')).toBeNull();
+    expect(pasteRefusal(clip({ path: 'src', kind: 'folder' }), 'ws\u0000.', 'src/sub')).toContain('itself');
+  });
+
+  test('a CUT into its own folder is refused; a COPY into it is how a copy is made', () => {
+    // The two modes differ here on purpose: copying a file into the directory
+    // it already lives in is how `a copy.ts` is produced, while a cut there
+    // would have nothing to do.
+    expect(pasteRefusal(clip({ path: 'src/a.ts', mode: 'cut' }), 'ws\u0000.', 'src')).toBe('Already in this folder');
+    expect(pasteRefusal(clip({ path: 'src/a.ts', mode: 'copy' }), 'ws\u0000.', 'src')).toBeNull();
+  });
+});
+
+describe('fsClipboardScope', () => {
+  test('separates root from repo, and treats a missing root as empty', () => {
+    expect(fsClipboardScope('/ws', '.')).toBe('/ws\u0000.');
+    expect(fsClipboardScope(undefined, 'sub')).toBe('\u0000sub');
+    expect(fsClipboardScope('/ws', '.')).not.toBe(fsClipboardScope('/ws', 'sub'));
+  });
+});
+
+describe('readFsClipboard', () => {
+  test('accepts a well-formed entry', () => {
+    expect(readFsClipboard(clip())).toEqual(clip());
+  });
+
+  test('rejects a path that names no child of the listing root', () => {
+    // Every one of these would resolve outside the folder the entry claims.
+    for (const path of ['.', '', '..', 'a/../b', '/etc/passwd', 'a//b']) {
+      expect(readFsClipboard(clip({ path }))).toBeNull();
+    }
+  });
+
+  test('rejects a blob whose shape Cut/Copy never wrote', () => {
+    expect(readFsClipboard(null)).toBeNull();
+    expect(readFsClipboard('a.ts')).toBeNull();
+    expect(readFsClipboard({ path: 'a.ts', name: 'a.ts', scope: 's', kind: 'file' })).toBeNull();
+    expect(readFsClipboard({ path: 'a.ts', name: 'a.ts', scope: 's', mode: 'copy' })).toBeNull();
+    expect(readFsClipboard({ path: 'a.ts', name: 'a.ts', scope: 's', kind: 'file', mode: 'move' })).toBeNull();
+  });
+});

package/src/shared/lib/fs/clipboard.ts

@@ -0,0 +1,182 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The Files panel's clipboard rules: what a Cut/Copy placed on the clipboard,
+ * and which targets may accept a Paste.
+ *
+ * Pure and shared, because the CLIENT decides which menu rows to show (Paste is
+ * offered only where it can land) and the SERVER decides whether the transfer is
+ * legal (the panel is not the only caller a stale tab can reach). One rule,
+ * both ends — a second copy is how the menu ends up offering a paste the route
+ * then refuses.
+ *
+ * A clipboard entry is scoped the way every other Files-panel path is: `path` is
+ * relative to the LISTED root, and `root\0repo` names which listing that is. A
+ * paste into another workspace or nested repo is therefore not this entry's
+ * destination, and `pasteRefusal` says so rather than silently moving a file the
+ * user copied somewhere else.
+ */
+
+/** What a Cut or a Copy put on the clipboard. */
+export interface FsClipboard {
+  /** The `\0`-joined `root\0repo` the path is relative to. */
+  scope: string;
+  /** Path relative to the listed root; never `.` — the root itself cannot be moved. */
+  path: string;
+  name: string;
+  kind: 'file' | 'folder';
+  mode: 'copy' | 'cut';
+}
+
+/** The scope key a panel's listing uses: `${rootPath}\0${repo}`. */
+export function fsClipboardScope(rootPath: string | undefined, repo: string): string {
+  return `${rootPath ?? ''}\u0000${repo}`;
+}
+
+/**
+ * The folder a paste into `targetPath` lands in: the folder itself, or the
+ * file's own directory.
+ *
+ * Both ends compute it (the menu labels the destination, the route resolves it),
+ * so the two must not disagree on where a paste beside a file goes.
+ */
+export function pasteTargetDir(targetPath: string, targetKind: 'file' | 'folder'): string {
+  if (targetKind === 'folder') return targetPath;
+  const cut = targetPath.lastIndexOf('/');
+  return cut === -1 ? '.' : targetPath.slice(0, cut);
+}
+
+/**
+ * The directory an entry lives in — the SOURCE side of `pasteTargetDir`, which
+ * cannot answer it: a folder's destination is itself, but its parent is not.
+ */
+export function parentOf(path: string): string {
+  const cut = path.lastIndexOf('/');
+  return cut === -1 ? '.' : path.slice(0, cut);
+}
+
+/**
+ * The refusal a transfer of `source` into the folder `targetDir` carries, or
+ * null when it may run. Both paths are relative to the same scoped root.
+ *
+ * Shared by BOTH ends: the menu hides Paste on an illegal target and the route
+ * refuses it anyway, so a stale client cannot reach the filesystem through a
+ * rule only the UI enforced. The descendant check is the one that cannot be
+ * skipped — a folder pasted into its own subtree makes the destination a child
+ * of the thing being moved, which never terminates.
+ */
+export function transferRefusal(
+  source: { path: string; kind: 'file' | 'folder' },
+  targetDir: string,
+): string | null {
+  // `.` is the scoped root itself: moving or copying it would retarget the whole
+  // listing, and the clipboard never holds it (the root menu has no Cut/Copy).
+  if (source.path === '' || source.path === '.') return 'The workspace root cannot be moved or copied';
+  if (source.kind === 'folder' && (targetDir === source.path || targetDir.startsWith(`${source.path}/`))) {
+    return 'Cannot paste a folder into itself';
+  }
+  return null;
+}
+
+/**
+ * The refusal a MOVE of `source` into `targetDir` carries — the rule a drag
+ * obeys, and the reason it is not just `transferRefusal`.
+ *
+ * A drag is always a move, so landing back in the directory the entry already
+ * lives in is a no-op with nothing to report. A CUT only hits the same case
+ * when the user pastes into the folder the entry is already in, which is why
+ * `pasteRefusal` applies the same test to `mode: 'cut'` and not to a copy —
+ * copying into one's own directory is how `a copy.ts` is made.
+ */
+export function dropRefusal(
+  source: { path: string; kind: 'file' | 'folder' },
+  targetDir: string,
+): string | null {
+  const refusal = transferRefusal(source, targetDir);
+  if (refusal) return refusal;
+  if (targetDir === parentOf(source.path)) return 'Already in this folder';
+  return null;
+}
+
+/**
+ * Whether a paste of `clip` into the folder `targetDir` is legal.
+ *
+ * `transferRefusal` plus the one check only a client can make: the clipboard
+ * entry's scope is the listing it was copied from, and a paste into another
+ * workspace or nested repo is a different listing — not this entry's
+ * destination. The server cannot compare the two, because the client's scope is
+ * built from the un-resolved `rootPath` (which may be `~`-relative) while the
+ * route holds the resolved directory.
+ */
+export function pasteRefusal(clip: FsClipboard | null, scope: string, targetDir: string): string | null {
+  if (!clip) return 'Nothing to paste';
+  if (clip.scope !== scope) return 'The clipboard holds an entry from another workspace';
+  // A cut has nothing to do in the folder it is already in — the entry would be
+  // renamed to a `copy` name, which is the opposite of what a cut means. The
+  // route refuses the same case in the same words.
+  if (clip.mode === 'cut' && targetDir === parentOf(clip.path)) return 'Already in this folder';
+  return transferRefusal(clip, targetDir);
+}
+
+/**
+ * The first free name for `name` inside `taken`: `a.txt` → `a copy.txt` →
+ * `a copy 2.txt`. A paste (or a duplicate) never overwrites, so a colliding
+ * name is a reason to pick another, not to clobber the file already there.
+ *
+ * The extension stays on the end (`report.v2.md` → `report.v2 copy.md`) because
+ * a suffix appended after it (`report.md copy`) reads as a different file type
+ * to every editor that keys off the extension.
+ */
+export function uniqueName(name: string, taken: (candidate: string) => boolean): string {
+  if (!taken(name)) return name;
+  const dot = name.lastIndexOf('.');
+  const base = dot > 0 ? name.slice(0, dot) : name;
+  const ext = dot > 0 ? name.slice(dot) : '';
+  const first = `${base} copy${ext}`;
+  if (!taken(first)) return first;
+  for (let n = 2; n < 1000; n += 1) {
+    const candidate = `${base} copy ${n}${ext}`;
+    if (!taken(candidate)) return candidate;
+  }
+  return `${base} copy ${Date.now()}${ext}`;
+}
+
+/**
+ * The name a Duplicate gives its new entry: a file takes the `uniqueName`
+ * ladder (`a.txt` → `a copy.txt`), a folder its own (`src` → `src copy`),
+ * because a folder carries no extension to preserve.
+ */
+export function duplicateName(name: string, kind: 'file' | 'folder', taken: (candidate: string) => boolean): string {
+  if (kind === 'file') return uniqueName(name, taken);
+  if (!taken(`${name} copy`)) return `${name} copy`;
+  for (let n = 2; n < 1000; n += 1) {
+    const candidate = `${name} copy ${n}`;
+    if (!taken(candidate)) return candidate;
+  }
+  return `${name} copy ${Date.now()}`;
+}
+
+/**
+ * Guard a stored clipboard blob read back from session state.
+ *
+ * `session_ui_state` is a client-owned store, but it survives reloads and can
+ * be hand-edited, and every path here ends in a filesystem call — so a blob
+ * whose shape is not what Cut/Copy wrote is dropped rather than trusted. The
+ * path check is the one that matters: a `.`, a `..` segment or an absolute
+ * spelling would name a directory other than the one the entry claims.
+ */
+export function readFsClipboard(value: unknown): FsClipboard | null {
+  if (typeof value !== 'object' || value === null) return null;
+  const clip = value as Partial<FsClipboard>;
+  if (typeof clip.scope !== 'string' || typeof clip.path !== 'string' || typeof clip.name !== 'string') return null;
+  if (clip.kind !== 'file' && clip.kind !== 'folder') return null;
+  if (clip.mode !== 'copy' && clip.mode !== 'cut') return null;
+  const segments = clip.path.split('/');
+  if (clip.path === '' || clip.path.startsWith('/') || segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+    return null;
+  }
+  return { scope: clip.scope, path: clip.path, name: clip.name, kind: clip.kind, mode: clip.mode };
+}

package/src/shared/lib/fs/commit-count.test.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { formatCommitCount } from '@/shared/lib/fs/commit-count';
+
+describe('formatCommitCount', () => {
+  // The reported bug: a 646-commit branch whose first page is 50 rows read
+  // "50 commits", which is the page size, not the history.
+  test('reports the loaded page against the branch total', () => {
+    expect(formatCommitCount({ matches: 50, loaded: 50, total: 646, hasMore: true })).toBe('50 of 646');
+  });
+
+  test('reports the bare total once the whole history is loaded', () => {
+    expect(formatCommitCount({ matches: 646, loaded: 646, total: 646, hasMore: false })).toBe('646 commits');
+  });
+
+  // A branch holding fewer commits than one page: `loaded === total` with
+  // `hasMore` still true would be a contradiction, so hasMore wins and the
+  // pair is shown rather than a total that would hide the pending page.
+  test('shows the pair while a page is still pending', () => {
+    expect(formatCommitCount({ matches: 50, loaded: 50, total: 50, hasMore: true })).toBe('50 of 50');
+  });
+
+  // The filter only sees the loaded page, so the denominator must be that page.
+  test('a search reports matches against the loaded page, never the total', () => {
+    expect(formatCommitCount({ matches: 18, loaded: 50, total: 646, hasMore: true, isFiltering: true })).toBe(
+      '18 of 50 loaded'
+    );
+  });
+
+  test('an empty search result still names the page it searched', () => {
+    expect(formatCommitCount({ matches: 0, loaded: 50, total: 646, hasMore: true, isFiltering: true })).toBe(
+      '0 of 50 loaded'
+    );
+  });
+
+  // No total from git (a branch with no commits, or a response that omitted it).
+  test('marks an unknown total as partial while more may follow', () => {
+    expect(formatCommitCount({ matches: 50, loaded: 50, hasMore: true })).toBe('50+ commits');
+    expect(formatCommitCount({ matches: 12, loaded: 12, hasMore: false })).toBe('12 commits');
+  });
+
+  test('a zero total is treated as unknown rather than as a count', () => {
+    expect(formatCommitCount({ matches: 20, loaded: 20, total: 0, hasMore: false })).toBe('20 commits');
+  });
+});

package/src/shared/lib/fs/commit-count.ts

@@ -0,0 +1,34 @@
+/**
+ * The commit modal's header badge.
+ *
+ * Extracted from the component because the wording encodes three facts that are
+ * easy to conflate and were: `total` is the BRANCH's commit count, `loaded` is
+ * what git has handed over so far, and `matches` is what the search filter left
+ * of it. Printing `matches` against `total` claims the filter searched the whole
+ * history; printing `loaded` alone is what made a 646-commit branch read
+ * "50 commits".
+ */
+export interface CommitCountInput {
+  /** Rows currently rendered (the loaded page, or its search matches). */
+  matches: number;
+  /** Rows loaded from git, before the search filter. */
+  loaded: number;
+  /** The branch's real commit count, when the response carried it. */
+  total?: number;
+  hasMore?: boolean;
+  isFiltering?: boolean;
+}
+
+export function formatCommitCount({ matches, loaded, total, hasMore, isFiltering }: CommitCountInput): string {
+  if (isFiltering) {
+    // The filter only ever sees the loaded page, so the denominator must be
+    // that page — `of 646` would claim a search of the whole history.
+    return `${matches} of ${loaded} loaded`;
+  }
+  if (typeof total === 'number' && total > 0) {
+    return hasMore || loaded < total ? `${loaded} of ${total}` : `${total} commits`;
+  }
+  // No total from git — a branch with no commits, or a response that omitted
+  // it. Say what is on screen and mark it as a partial read.
+  return hasMore ? `${loaded}+ commits` : `${loaded} commits`;
+}

package/src/shared/lib/fs/commit-page.ts

@@ -0,0 +1,10 @@
+/**
+ * How many commits one history / graph page carries.
+ *
+ * Shared so the client cannot drift from the page size the server serves. The
+ * client's `hasMore` fallback fires only for a response that carries no
+ * `hasMore` flag (a stub, or an older payload), and a fallback that disagrees
+ * with the real page size ends infinite scroll after the first page — silently,
+ * because a short page and a finished history look identical.
+ */
+export const COMMIT_PAGE_SIZE = 50;