@kabmo-labs/kabmo 0.7.0 → 0.8.0

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/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 };
+  });
+}

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

@@ -7,14 +7,11 @@
  * The Files panel's test harness: a fake disk, a real realtime server, and the
  * click helpers the panel's specs drive it with.
  *
- * Extracted because TWO spec files exercise the same panel — the listing
- * behaviours and the root context menu — and each was carrying its own copy of
- * the mount, the HTTP stub and the click helpers. A second copy is how the two
- * files drift into testing different setups.
- *
- * The HTTP stub is a real directory model: specs mutate `disk` between reads,
- * which is what makes a refresh assertion fail on a panel that answered from
- * its children cache instead of from the server.
+ * Extracted because several spec files exercise the same panel, and each was
+ * carrying its own copy of the mount, the HTTP stub and the helpers. The HTTP
+ * stub is a real directory model (see `file-explorer-disk.test-util`): specs
+ * mutate `disk` between reads, which is what makes a refresh assertion fail on a
+ * panel that answered from its children cache instead of from the server.
  */
 
 import { Window } from 'happy-dom';
@@ -29,14 +26,13 @@ import { startRealtimeTestServer, type RealtimeTestServer } from '@/test-support
 import { installDomGlobals, pristineWebSocket, restoreDomGlobals } from '@/test-support/pristine-globals';
 import type { TopicResolver } from '@/server/lib/realtime/hub.server';
 import type { GitStatusPayload } from '@/server/lib/fs/git-status-read';
+import { diskHas, entriesOf, moveOnDisk, writeToDisk, type Disk } from '@/test-support/file-explorer-disk.test-util';
+
+export type { Disk } from '@/test-support/file-explorer-disk.test-util';
 
 export const ROOT = '/ws';
 export const SESSION = 'new-files-panel';
 const TOPIC = fsTopic(`${ROOT}\u0000.`);
-
-/** The fake disk: `path -> child -> (null for a folder, 'file' for a file)`. */
-export type Disk = Record<string, Record<string, null | 'file'> | undefined>;
-
 const GIT_STATUS: GitStatusPayload = { changes: [], branch: 'main', branches: [], remoteBranches: [] };
 
 export interface FileExplorerHarness {
@@ -46,9 +42,9 @@ export interface FileExplorerHarness {
   dirReads: string[];
   /** Paths whose NEXT read answers a non-JSON 500 (a transport failure). */
   failNext: Set<string>;
-  /** Every create the panel posted, as its form fields. */
+  /** Every create / rename / transfer the panel posted, as its form fields. */
   createRequests: Array<Record<string, string>>;
-  /** Every duplicate/paste the panel posted, as its form fields. */
+  renameRequests: Array<Record<string, string>>;
   transferRequests: Array<Record<string, string>>;
   /** Files the panel asked the editor to open, in order. */
   openedFiles: Array<{ path: string; name: string }>;
@@ -66,44 +62,36 @@ export interface FileExplorerHarness {
   panelBackground: () => HTMLElement;
   /** Right-click the background, leaving its menu open. */
   openMenuOnBackground: () => Promise<void>;
-  /** Right-click the background and click the menu's New File row. */
+  /** Right-click the background and click its New File / New Folder row. */
   openRootNewFile: () => Promise<void>;
+  openRootNewFolder: () => Promise<void>;
   /** Type a name into the open create dialog and submit it. */
   submitNewFile: (name: string) => Promise<void>;
+  /** Type a destination into the open rename dialog and submit it. */
+  submitRename: (path: string) => Promise<void>;
+  renameInput: () => HTMLInputElement | null;
+  /** Every row name the tree is currently drawing, in order. */
+  visibleNames: () => string[];
+  /** The whole rendered document's text — a dialog's inline refusal lives here. */
+  documentText: () => string;
   /** Every button label currently in the document — the menu assertions read it. */
   buttonLabels: () => string[];
   /** Click a button by its exact label (a context-menu row, a dialog action). */
   clickMenuRow: (label: string) => Promise<void>;
-  /**
-   * Drag the row named `from` onto the row named `to`, or onto the panel
-   * background when `to` is null — the whole gesture, in the order the browser
-   * raises it: dragstart on the source, dragover on the target (where a target
-   * refuses), then drop.
-   */
+  /** Drag `from` onto `to` (or the background when null): dragstart, dragover, drop. */
   dragRow: (from: string, to: string | null) => Promise<void>;
-  /** Install the DOM globals (call from `beforeAll`). */
+  /** DOM globals for the whole file (call from beforeAll / afterAll). */
   install: () => void;
-  /** Restore the runner's own globals (call from `afterAll`). */
   restore: () => void;
 }
 
-/** One directory's entries as the server emits them: folders with `children: null`. */
-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 };
-  });
-}
-
 export function createFileExplorerHarness(): FileExplorerHarness {
   const harness: FileExplorerHarness = {
     disk: {},
     dirReads: [],
     failNext: new Set(),
     createRequests: [],
+    renameRequests: [],
     transferRequests: [],
     openedFiles: [],
     container: null as unknown as HTMLElement,
@@ -127,6 +115,7 @@ export function createFileExplorerHarness(): FileExplorerHarness {
     async mount() {
       harness.failNext = new Set();
       harness.createRequests = [];
+      harness.renameRequests = [];
       harness.transferRequests = [];
       harness.openedFiles = [];
       // A fresh mount is a fresh session: the panel's per-session UI state
@@ -144,8 +133,8 @@ export function createFileExplorerHarness(): FileExplorerHarness {
       target.WebSocket = pristineWebSocket;
       target.fetch = async (input: unknown, init?: RequestInit) => {
         const url = String(input);
-        const json = (body: unknown) => new Response(JSON.stringify(body), {
-          status: 200,
+        const json = (body: unknown, status = 200) => new Response(JSON.stringify(body), {
+          status,
           headers: { 'content-type': 'application/json' },
         });
         if (url.includes('/state')) return json({ sessionId: SESSION, state: {} });
@@ -161,11 +150,25 @@ export function createFileExplorerHarness(): FileExplorerHarness {
             harness.transferRequests.push(fields);
             return json({ success: true, path: `moved-${fields.actionType}` });
           }
+          if (fields.actionType === 'rename') {
+            harness.renameRequests.push(fields);
+            // The real route refuses an existing destination; the disk is the
+            // authority here too, so a refusal spec drives the same path.
+            const destination = fields.newPath;
+            if (destination !== fields.path && diskHas(harness.disk, destination)) {
+              return json({ error: `${destination} already exists` }, 409);
+            }
+            moveOnDisk(harness.disk, fields.path, destination);
+            return json({ success: true, path: destination, previousPath: fields.path });
+          }
           harness.createRequests.push(fields);
-          // The create route answers with the new file's path relative to the
+          // The create route answers with the new entry's path relative to the
           // LISTED root; the folder is `.` for the panel's own background menu.
-          const rel = fields.path === '.' ? fields.name : `${fields.path}/${fields.name}`;
-          return json({ success: true, path: rel });
+          // `kind` rides back because the tree draws a folder differently from a
+          // file, and the request is the only place it is stated.
+          const kind = fields.kind === 'folder' ? 'folder' : 'file';
+          const rel = writeToDisk(harness.disk, fields.path, fields.name, kind);
+          return json({ success: true, kind, path: rel });
         }
         if (url.includes('/api/fs/dir')) {
           const path = new URL(url, 'http://127.0.0.1').searchParams.get('path') ?? '.';
@@ -241,8 +244,36 @@ export function createFileExplorerHarness(): FileExplorerHarness {
       await harness.openMenuOnBackground();
       await harness.clickMenuRow('New File');
     },
+    async openRootNewFolder() {
+      await harness.openMenuOnBackground();
+      await harness.clickMenuRow('New Folder');
+    },
+    async submitRename(path) {
+      const input = harness.renameInput();
+      if (!input) throw new Error('no rename dialog');
+      await act(async () => {
+        input.value = path;
+        input.dispatchEvent(new window.Event('input', { bubbles: true }));
+      });
+      for (let i = 0; i < 5; i += 1) await act(async () => {});
+      await harness.clickMenuRow('Rename');
+      for (let i = 0; i < 20; i += 1) await act(async () => {});
+    },
+    renameInput() {
+      return document.querySelector('input[aria-label^="Rename "]') as HTMLInputElement | null;
+    },
+    visibleNames() {
+      // A row's name span is the leaf that carries it; the row wrapper reads the
+      // same text, so the SPAN is what is collected (one per row).
+      return [...harness.container.querySelectorAll('span')]
+        .map((el) => el.textContent?.trim() ?? '')
+        .filter((text) => text.length > 0);
+    },
+    documentText() {
+      return document.body.textContent ?? '';
+    },
     async submitNewFile(name) {
-      const input = document.querySelector('input[aria-label="New file name"]') as HTMLInputElement | null;
+      const input = document.querySelector('input[aria-label^="New "]') as HTMLInputElement | null;
       if (!input) throw new Error('no create dialog');
       await act(async () => {
         input.value = name;