@kabmo-labs/kabmo 0.7.0 → 0.9.0

package/src/shared/lib/workspace/workspace-panel-widths.ts

@@ -0,0 +1,124 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The desktop workspace group's three panel widths, resolved from one place.
+ *
+ * `WorkspacePanels` used to compute these inline, which was correct but made the
+ * component's own contract hard to read and impossible to unit-test: every rule
+ * here — the two-call order, the pair caps, the leftover width a collapsed chat
+ * hands the editor — is arithmetic over values the caller already has.
+ *
+ * Pure: no hooks, no DOM. The caller measures the group and reads the stored
+ * widths; this module decides what those mean.
+ */
+
+import {
+  DEFAULT_EDITOR_FRACTIONS,
+  DEFAULT_EDITOR_WIDTHS,
+  HANDLE_WIDTH,
+  MIN_EDITOR_PANEL_WIDTH,
+  panelFraction,
+  pairMaxSize,
+  resolvePanelWidth,
+  type EditorWidthMode,
+  type PanelWidths,
+} from '@/shared/lib/workspace/panel-widths';
+import { DEFAULT_RIGHT_PANEL_FRACTION } from '@/shared/lib/workspace/right-panels';
+
+export interface WorkspacePanelWidthsArgs {
+  /** Measured area of the group, or null before the observer reports. */
+  available: number | null;
+  /** This session's remembered widths. */
+  panelWidths: PanelWidths;
+  /** Which slot the editor column is using (a diff wants more room). */
+  editorWidthMode: EditorWidthMode;
+  /** The right panel's active view, whose slot and defaults apply. */
+  activeRightPanel: string;
+  /** The active view's own defaults and floor, when it has them. */
+  activePanel?: { defaultFraction?: number; defaultWidth?: number; minWidth?: number };
+  showEditor: boolean;
+  showRightPanel: boolean;
+  /** The chat column is collapsed, so it holds no floor and no pair share. */
+  chatHidden: boolean;
+}
+
+export interface WorkspacePanelWidths {
+  right: number;
+  editor: number;
+  /** Drag ceilings; `undefined` before the group is measured. */
+  editorMax: number | undefined;
+  rightMax: number | undefined;
+  /** Separators actually rendered, which also consume width. */
+  handleCount: number;
+  /** The right panel's floor, which the drag ceiling also reserves. */
+  rightMin: number;
+}
+
+export function resolveWorkspacePanelWidths(args: WorkspacePanelWidthsArgs): WorkspacePanelWidths {
+  const { available, panelWidths, editorWidthMode, activeRightPanel, activePanel, showEditor, showRightPanel, chatHidden } = args;
+
+  // The separator before the editor is gone while the chat is collapsed: there
+  // is nothing on its left to transfer width to, and the drag's neighbour walk
+  // skips a collapsed panel, so it would render a handle that does nothing.
+  const handleCount = (showEditor && !chatHidden ? 1 : 0) + (showRightPanel ? 1 : 0);
+  const rightMin = activePanel?.minWidth ?? MIN_EDITOR_PANEL_WIDTH;
+
+  // The editor and the right panel are a COUPLED pair: the right panel is
+  // resolved first, reserving the editor's WANTED share (the editor has no
+  // result yet), and the editor then reserves the right panel's ACTUAL width.
+  // That asymmetry is deliberate — an editor asking for more than its default
+  // makes the right panel give way first, and the pair still sums to the total.
+  const editorFraction = panelFraction(panelWidths[editorWidthMode], DEFAULT_EDITOR_FRACTIONS[editorWidthMode], available);
+  const editorReservePx = available != null && available > 0 ? Math.round(editorFraction * available) : 0;
+
+  const right = resolvePanelWidth({
+    stored: panelWidths.right?.[activeRightPanel],
+    defaultFraction: activePanel?.defaultFraction ?? DEFAULT_RIGHT_PANEL_FRACTION,
+    defaultPx: activePanel?.defaultWidth ?? MIN_EDITOR_PANEL_WIDTH,
+    available,
+    min: rightMin,
+    pairReservePx: showEditor ? editorReservePx : 0,
+    // The editor has not been resolved yet, so only its floor can be reserved.
+    siblingWidth: showEditor ? MIN_EDITOR_PANEL_WIDTH : 0,
+    handleCount,
+    chatHidden,
+  });
+
+  // With the chat collapsed the editor takes everything the right panel and the
+  // separators do not. Resolving from its remembered FRACTION would leave the
+  // freed width as an empty gap, which is the opposite of what the mode
+  // promises; the remembered width is untouched, so leaving restores it.
+  const editor = chatHidden
+    ? Math.max(
+        MIN_EDITOR_PANEL_WIDTH,
+        available != null && available > 0
+          ? Math.floor(available - (showRightPanel ? right : 0) - handleCount * HANDLE_WIDTH)
+          : DEFAULT_EDITOR_WIDTHS[editorWidthMode],
+      )
+    : resolvePanelWidth({
+        stored: panelWidths[editorWidthMode],
+        defaultFraction: DEFAULT_EDITOR_FRACTIONS[editorWidthMode],
+        defaultPx: DEFAULT_EDITOR_WIDTHS[editorWidthMode],
+        available,
+        min: MIN_EDITOR_PANEL_WIDTH,
+        pairReservePx: showRightPanel ? right : 0,
+        siblingWidth: showRightPanel ? right : 0,
+        handleCount,
+      });
+
+  return {
+    right,
+    editor,
+    // `resolvePanelWidth` caps what it HANDS to `defaultSize`, but a separator
+    // drag bypasses it — the resizer transfers pixels between two panels clamped
+    // only by their own `maxSize`. Each max is its own cap and the pair total
+    // minus the sibling's FLOOR (it gives way down to its minimum mid-drag).
+    editorMax: pairMaxSize({ available, siblingMin: rightMin, siblingOpen: showRightPanel, chatHidden }),
+    rightMax: pairMaxSize({ available, siblingMin: MIN_EDITOR_PANEL_WIDTH, siblingOpen: showEditor, chatHidden }),
+    handleCount,
+    rightMin,
+  };
+}

package/src/shared/lib/workspace/worktree/branch-name.test.ts

@@ -0,0 +1,95 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Branch naming and slugging.
+ *
+ * Two rules here are load-bearing and each was a defect first:
+ *
+ *  - `slug('..')` is `..`, and `path.join(root, '..')` escapes the root — so a
+ *    dot-only result is REJECTED, not passed through.
+ *  - our own `wt/` namespace is stripped from the folder (the folder does not
+ *    repeat it) while a repository's own namespace stays visible (`feat/x` →
+ *    `feat-x`), so a folder never reads as a second branch name.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import {
+  defaultWorktreeBranch,
+  folderNameForBranch,
+  generateBranchSlug,
+  isPlausibleBranchName,
+  normalizeBranchName,
+  slugWorktreeName,
+  WORKTREE_BRANCH_PREFIX,
+} from '@/shared/lib/workspace/worktree/branch-name';
+
+describe('worktree branch names', () => {
+  test('the generated branch carries our namespace', () => {
+    const branch = defaultWorktreeBranch();
+    expect(branch.startsWith(`${WORKTREE_BRANCH_PREFIX}/`)).toBe(true);
+    expect(branch.slice(WORKTREE_BRANCH_PREFIX.length + 1)).toMatch(/^[a-z]+-[a-z]+$/);
+  });
+
+  test('the ref namespace is stripped and only that', () => {
+    expect(normalizeBranchName('refs/heads/wt/x')).toBe('wt/x');
+    expect(normalizeBranchName('heads/wt/x')).toBe('wt/x');
+    expect(normalizeBranchName('  wt/x  ')).toBe('wt/x');
+  });
+});
+
+describe('folder naming', () => {
+  test('our namespace is stripped, a repository namespace is kept', () => {
+    expect(folderNameForBranch('wt/cosmic-dolphin')).toBe('cosmic-dolphin');
+    expect(folderNameForBranch('feat/payments')).toBe('feat-payments');
+    expect(folderNameForBranch('refs/heads/wt/yak')).toBe('yak');
+    expect(folderNameForBranch('plain')).toBe('plain');
+  });
+
+  test('a folder is one path segment and cannot escape its root', () => {
+    expect(slugWorktreeName('../../etc/passwd')).toBe('etc-passwd');
+    expect(slugWorktreeName('a b/c')).toBe('a-b-c');
+    expect(slugWorktreeName('-weird-')).toBe('weird');
+    // The trap: these two ARE valid path segments and would leave the root.
+    expect(slugWorktreeName('..')).toBe('');
+    expect(slugWorktreeName('.')).toBe('');
+    expect(slugWorktreeName('...')).toBe('');
+  });
+
+  test('a folder name is bounded', () => {
+    expect(slugWorktreeName('x'.repeat(200)).length).toBeLessThanOrEqual(80);
+  });
+
+  test('a non-Latin branch leaves no slug, so the caller generates a name', () => {
+    expect(folderNameForBranch('测试分支')).toBe('');
+  });
+});
+
+describe('generated slugs', () => {
+  test('stay inside the word lists and vary', () => {
+    const seen = new Set<string>();
+    for (let index = 0; index < 60; index += 1) seen.add(generateBranchSlug());
+    expect(seen.size).toBeGreaterThan(10);
+    for (const slug of seen) expect(slug).toMatch(/^[a-z]+-[a-z]+$/);
+  });
+});
+
+describe('branch name plausibility', () => {
+  test('accepts what git accepts', () => {
+    expect(isPlausibleBranchName('wt/ok')).toBe(true);
+    expect(isPlausibleBranchName('feat/payments-v2')).toBe(true);
+  });
+
+  test('refuses what git refuses, before git has to say so', () => {
+    expect(isPlausibleBranchName('')).toBe(false);
+    expect(isPlausibleBranchName('has space')).toBe(false);
+    expect(isPlausibleBranchName('a..b')).toBe(false);
+    expect(isPlausibleBranchName('-leading')).toBe(false);
+    expect(isPlausibleBranchName('trailing/')).toBe(false);
+    expect(isPlausibleBranchName('tilde~1')).toBe(false);
+    expect(isPlausibleBranchName('at@{1}')).toBe(false);
+    expect(isPlausibleBranchName('a//b')).toBe(false);
+  });
+});

package/src/shared/lib/workspace/worktree/branch-name.ts

@@ -0,0 +1,115 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Branch naming and slugging for worktrees — ONE module, because the dialog and
+ * the create route must agree on what a name means. The dialog pre-fills the
+ * branch and derives the folder; the server re-derives both from what arrives.
+ *
+ * The word lists are OpenChamber's Ubuntu-style pairs (their
+ * `lib/git/branchNameGenerator.ts`), and the pick is seeded from
+ * `crypto.getRandomValues` rather than `Math.random`, which is available in the
+ * browser and in Bun without an import.
+ */
+
+/**
+ * Kabmo's namespace for a generated worktree branch. Deliberately `wt`, not
+ * OpenChamber's `openchamber`: omp's own `/wt` already creates `wt/*`, so a
+ * repository that has used either tool reads one convention instead of two.
+ */
+export const WORKTREE_BRANCH_PREFIX = 'wt';
+
+const ADJECTIVES = [
+  'artful', 'bionic', 'cosmic', 'disco', 'focal', 'groovy', 'jammy', 'kinetic',
+  'lunar', 'noble', 'bold', 'brave', 'calm', 'eager', 'gentle', 'happy', 'keen',
+  'lively', 'merry', 'swift', 'warm', 'wise', 'bright', 'clever', 'daring',
+  'agile', 'crisp', 'fresh', 'lucid', 'quick', 'sharp', 'vivid', 'zealous',
+];
+
+const NOUNS = [
+  'aardvark', 'beaver', 'chipmunk', 'dolphin', 'falcon', 'gopher', 'hedgehog',
+  'jackal', 'koala', 'lemur', 'mongoose', 'narwhal', 'otter', 'pangolin',
+  'quokka', 'raccoon', 'salamander', 'toucan', 'walrus', 'yak', 'zebra',
+  'badger', 'condor', 'dingo', 'egret', 'ferret', 'gecko', 'heron', 'iguana',
+];
+
+/** A random index from the platform CSPRNG, so two sessions rarely collide. */
+function pick(values: readonly string[]): string {
+  const bytes = new Uint8Array(2);
+  crypto.getRandomValues(bytes);
+  return values[((bytes[0] ?? 0) << 8 | (bytes[1] ?? 0)) % values.length] as string;
+}
+
+/** One adjective-noun pair, e.g. `cosmic-dolphin`. */
+export function generateBranchSlug(): string {
+  return `${pick(ADJECTIVES)}-${pick(NOUNS)}`;
+}
+
+/** The default branch of a worktree: our namespace plus a generated slug. */
+export function defaultWorktreeBranch(): string {
+  return `${WORKTREE_BRANCH_PREFIX}/${generateBranchSlug()}`;
+}
+
+/** The branch as git names it, without the ref namespace. */
+export function normalizeBranchName(value: string): string {
+  return String(value ?? '')
+    .trim()
+    .replace(/^refs\/heads\//, '')
+    .replace(/^heads\//, '')
+    .replace(/\s+/g, '-')
+    .replace(/^\/+|\/+$/g, '');
+}
+
+/**
+ * One path segment, ≤80 chars, safe on every filesystem we target.
+ *
+ * A leading `.` is stripped and the dot-only results are rejected: `slug('.')`
+ * is `.` and `slug('..')` is `..`, and `path.join(root, name)` resolves those to
+ * the root itself and to its parent. A folder name that escapes its root is not
+ * a name.
+ */
+export function slugWorktreeName(value: string): string {
+  const slug = String(value ?? '')
+    .trim()
+    .replace(/^refs\/heads\//, '')
+    .replace(/^heads\//, '')
+    .replace(/\s+/g, '-')
+    .replace(/^\/+|\/+$/g, '')
+    .split('/')
+    .join('-')
+    .replace(/[^A-Za-z0-9._-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^[.-]+|[.-]+$/g, '')
+    .slice(0, 80);
+  return slug === '.' || slug === '..' ? '' : slug;
+}
+
+/**
+ * The folder a branch gets. Our own `wt/` namespace is stripped — the folder
+ * does not repeat it — while a repository's own namespaces stay visible
+ * (`feat/x` → `feat-x`). A non-Latin branch (`测试分支`) leaves no slug, and the
+ * caller falls back to a generated name rather than an empty folder.
+ */
+export function folderNameForBranch(branch: string): string {
+  const withoutRef = normalizeBranchName(branch);
+  const namespaced = `${WORKTREE_BRANCH_PREFIX}/`;
+  const withoutOwnPrefix = withoutRef.startsWith(namespaced)
+    ? withoutRef.slice(namespaced.length)
+    : withoutRef;
+  return slugWorktreeName(withoutOwnPrefix);
+}
+
+/**
+ * Whether git would plausibly accept this as a branch name. Rejects only what
+ * `git check-ref-format` rejects in every case — the server still asks git
+ * itself, because a plausible name can still collide with an existing ref.
+ */
+export function isPlausibleBranchName(value: string): boolean {
+  if (!value) return false;
+  if (/^[.\-/]/.test(value) || /[/.]$/.test(value)) return false;
+  if (value.includes('..') || value.includes('//') || value.includes('@{')) return false;
+  if (/[\s~^:?*[\\]/.test(value)) return false;
+  return true;
+}

package/src/shared/lib/workspace/worktree/types.ts

@@ -0,0 +1,104 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Worktree shapes shared by the server and the client.
+ *
+ * A worktree session is a normal session whose cwd is a linked checkout, so the
+ * only thing that crosses the wire is where it is and whether it is still there
+ * — everything else is read from git.
+ */
+
+/** One row of `GET /api/worktrees`, and what a create answers with. */
+export interface WorktreeInfo {
+  /** Absolute, canonical path of the checkout. */
+  path: string;
+  /** Branch checked out there (`refs/heads/` stripped); `''` when detached. */
+  branch: string;
+  /** The commit HEAD points at — what a detached row names instead of a branch. */
+  head: string;
+  detached: boolean;
+  /** git reports it prunable, or the directory is gone. */
+  missing: boolean;
+  /** The main checkout — listed, but never removable. */
+  isPrimary: boolean;
+  /** Changed + untracked count. */
+  dirty: number;
+  /**
+   * Commits on this branch that are not on the ref it was created from. Gates
+   * the delete dialog's branch checkbox, because `git branch -d` refuses an
+   * unmerged branch and a checkbox that cannot succeed is worse than none.
+   */
+  aheadOfStart: number;
+  /** The ref recorded when the worktree was created; `''` for an existing branch. */
+  startRef: string;
+  /** Chats whose cwd is inside this worktree. */
+  sessions: number;
+}
+
+/**
+ * The per-session view, carried on `SessionItemData` so every layout and every
+ * plugin reads one field instead of asking git.
+ */
+export interface SessionWorktreeInfo {
+  branch: string;
+  /** Canonical worktree root. */
+  path: string;
+  /** The checkout this worktree belongs to — the folder's `project_path`. */
+  primaryRoot: string;
+  /** `missing` when git still tracks it but the directory is gone. */
+  status: 'ready' | 'missing';
+  detached: boolean;
+}
+
+/** Where a chat that has not started will run. */
+export interface SpawnTarget {
+  folderId: number | null;
+  /** Absolute worktree path, or null for the folder's own checkout. */
+  worktreePath: string | null;
+}
+
+/** Why a worktree action was refused. Codes are stable; messages are not. */
+export type WorktreeErrorCode =
+  | 'not_a_repo'
+  | 'no_commits'
+  | 'invalid_name'
+  | 'branch_exists'
+  | 'branch_in_use'
+  | 'path_exists'
+  | 'create_failed'
+  | 'not_a_worktree'
+  | 'primary_checkout'
+  | 'dirty'
+  | 'dirty_carryover'
+  | 'remove_failed'
+  | 'mock_mode';
+
+/** One refusal, with the field it belongs to so a dialog can mark the input. */
+export interface WorktreeFailure {
+  code: WorktreeErrorCode;
+  message: string;
+  field?: 'branch' | 'folder' | 'location';
+  /** Present for `dirty`: how many files would be lost. */
+  count?: number;
+}
+
+/** `GET /api/worktrees`. */
+export interface WorktreeListPayload {
+  worktrees: WorktreeInfo[];
+  /** The resolved parent directory new worktrees are created in. */
+  base: string;
+  isRepo: boolean;
+  /** Present when the listing failed — never substituted with an empty list. */
+  error?: string;
+}
+
+/** `POST /api/worktrees/validate`. */
+export interface WorktreeValidation {
+  ok: boolean;
+  failures: WorktreeFailure[];
+  /** The name and directory the create would use, so the dialog can show them. */
+  resolved?: { name: string; directory: string; branch: string };
+}

package/src/shared/types/fs.ts

@@ -74,4 +74,14 @@ export interface FsActionResponse {
   error?: string;
   /** The path a create or a transfer landed at, relative to the listed root. */
   path?: string;
+  /** What a create made, so the tree can draw the row it just added. */
+  kind?: 'file' | 'folder';
+  /**
+   * The path a rename moved FROM, relative to the listed root.
+   *
+   * A rename answers with both ends so the panel can move the row in place:
+   * re-reading every open folder to discover a path it was just told is the
+   * reload this field exists to avoid.
+   */
+  previousPath?: string;
 }

package/src/shared/types/realtime.ts

@@ -32,3 +32,32 @@ export interface SidebarStatusEntry {
 
 /** `sidebar:status` — keyed by session id. Absent id means "no volatile fields". */
 export type SidebarStatusPayload = Record<string, SidebarStatusEntry>;
+
+/**
+ * One live session's row fields that can still move between turn boundaries.
+ *
+ * Exactly two, and the list is closed on purpose: everything else about a row
+ * (title, folder, cwd, worktree, archived) only changes on a STRUCTURAL event
+ * that publishes the structure for its own reason. These two are the ones a
+ * run advances mid-turn — the transcript appends, and a subagent's transcript
+ * appears beside it (which is what lights the row's roster chevron).
+ */
+export interface SidebarActivityEntry {
+  /** Newest transcript entry's ISO timestamp — the row's age and its
+   *  `LATEST_SESSION` position. */
+  updatedAt?: string;
+  /** Whether the session has any subagent transcript on disk. */
+  hasSubagents?: boolean;
+}
+
+/**
+ * `sidebar:activity` — session id → the live fields above, for the sessions
+ * with a run in flight.
+ *
+ * Only a running session can move between turn boundaries, so an id that is
+ * absent here simply keeps what the structure gave it. Both sides read the same
+ * sources (the newest JSONL entry's own `timestamp`, and the subagent
+ * transcript directory), so the client merges field by field and lets the
+ * newer stamp win.
+ */
+export type SidebarActivityPayload = Record<string, SidebarActivityEntry>;

package/src/shared/types/settings/state.ts

@@ -48,6 +48,16 @@ export interface SettingsState {
    * cannot render a broken editor, only a different one.
    */
   editorFont: string;
+  /**
+   * Colour theme for the code editor, INDEPENDENT of `theme` above.
+   *
+   * `auto` (the default) keeps the editor on the app palette. Any other value
+   * is a Shiki theme id from `EDITOR_THEMES` — the editor then paints its own
+   * surface, gutter, selection and tokens while the console around it keeps the
+   * app palette. `resolveEditorTheme` treats an id this build no longer ships
+   * as `auto`, so a downgrade renders the app palette rather than half a theme.
+   */
+  editorTheme: string;
   /** Generate a session title from the first run. omp suppresses its
    *  own auto-titling under `--mode rpc-ui` (PI_NO_TITLE), so without this a
    *  Kabmo session keeps its `New Session - <timestamp>` placeholder. Asked

package/src/shared/types/workspace.ts

@@ -3,6 +3,8 @@
  * JSONL discovery and use the omp session UUID (string) as id — hence the
  * union with string ids. Mock/demo mode keeps numeric SQLite ids.
  */
+import type { SessionWorktreeInfo } from '@/shared/lib/workspace/worktree/types';
+
 export interface SessionItemData {
   id: number | string;
   folder_id: number | string;
@@ -38,6 +40,18 @@ export interface SessionItemData {
    * saying so. Absent means the row is not waiting (the normal case).
    */
   waitingFor?: { waitId: string; sessionId: string; title: string | null };
+  /**
+   * The directory the session actually runs in. A worktree session's cwd is the
+   * linked checkout, not the folder's `project_path` — the difference the panels
+   * have to honour and the sidebar badge names.
+   */
+  cwd?: string;
+  /**
+   * The worktree this session runs in, when its cwd is a linked checkout.
+   * Absent for an ordinary session (the common case) and for a session whose cwd
+   * is outside every worktree of its project, which the row draws the same way.
+   */
+  worktree?: SessionWorktreeInfo;
 }
 
 /**

package/src/test-support/file-explorer-disk.test-util.ts

@@ -0,0 +1,76 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The Files panel harness's fake disk, and the two writes a spec drives it with.
+ *
+ * A separate module because the harness file is at the repository's line
+ * ceiling, and because the disk is the part with its own rules: a create and a
+ * rename MUTATE it the way the real route mutates the filesystem, so the very
+ * next read agrees with the row the panel just drew. A stub that answered
+ * "created" while leaving the folder empty would make every local-edit spec pass
+ * against a tree the server would contradict.
+ */
+
+/** The fake disk: `path -> child -> (null for a folder, 'file' for a file)`. */
+export type Disk = Record<string, Record<string, null | 'file'> | undefined>;
+
+/** One directory's own listing, created on demand. */
+function listingOf(disk: Disk, path: string): Record<string, null | 'file'> {
+  disk[path] = disk[path] ?? {};
+  return disk[path]!;
+}
+
+/**
+ * Apply a create: every directory on the way exists afterwards, and the entry
+ * sits in its parent's listing. Returns the entry's path relative to the root.
+ */
+export function writeToDisk(disk: Disk, folder: string, name: string, kind: 'file' | 'folder'): string {
+  const segments = name.split('/');
+  let parent = folder === '.' ? '' : folder;
+  for (const segment of segments.slice(0, -1)) {
+    listingOf(disk, parent || '.')[segment] = null;
+    parent = parent ? `${parent}/${segment}` : segment;
+    listingOf(disk, parent);
+  }
+  const leaf = segments[segments.length - 1];
+  listingOf(disk, parent || '.')[leaf] = kind === 'folder' ? null : 'file';
+  const created = parent ? `${parent}/${leaf}` : leaf;
+  if (kind === 'folder') listingOf(disk, created);
+  return created;
+}
+
+/** Split a relative path into its directory (`.` at the root) and its name. */
+function splitPath(path: string): { dir: string; name: string } {
+  const cut = path.lastIndexOf('/');
+  return cut === -1 ? { dir: '.', name: path } : { dir: path.slice(0, cut), name: path.slice(cut + 1) };
+}
+
+/** Apply a rename: remove the old entry, write the new one, kind preserved. */
+export function moveOnDisk(disk: Disk, fromPath: string, toPath: string): void {
+  const from = splitPath(fromPath);
+  const source = disk[from.dir];
+  const kind = source?.[from.name] === null ? 'folder' : 'file';
+  if (source) delete source[from.name];
+  const to = splitPath(toPath);
+  writeToDisk(disk, to.dir, to.name, kind);
+}
+
+/** Whether `path` already names an entry of the fake disk. */
+export function diskHas(disk: Disk, path: string): boolean {
+  const { dir, name } = splitPath(path);
+  return (disk[dir] ?? {})[name] !== undefined;
+}
+
+/** One directory's entries as the server emits them: folders with `children: null`. */
+export function entriesOf(disk: Disk, path: string): unknown[] {
+  const dir = disk[path] ?? {};
+  return Object.keys(dir).map((child) => {
+    const rel = path === '.' ? child : `${path}/${child}`;
+    return dir[child] === null
+      ? { id: rel, name: child, type: 'folder', path: rel, children: null, ignored: false }
+      : { id: rel, name: child, type: 'file', path: rel, ignored: false };
+  });
+}