@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/shared/lib/fs/git-unmerged.test.ts

@@ -0,0 +1,123 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The unmerged-vocabulary table and the conflict-marker reader.
+ *
+ * These are the two rules every conflict surface reads from, and both encode a
+ * fact that is invisible in the code that consumes them:
+ *
+ *  - a porcelain pair like `UU` is the two SIDES of a conflict, not an
+ *    index/worktree pair, so `isUnmergedCode` is what stops `getGitStatusInfo`
+ *    and `ChangesList` from reading one through the other's rules;
+ *  - `--ours`/`--theirs` are INVERTED during a rebase, so the words on a resolve
+ *    button have to come from the file's own markers rather than from those two
+ *    names.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import {
+  OPERATION_LABELS,
+  UNMERGED_CODES,
+  isUnmergedCode,
+  parseConflictMarkers,
+} from '@/shared/lib/fs/git-unmerged';
+
+describe('isUnmergedCode', () => {
+  test('accepts exactly the seven unmerged pairs', () => {
+    for (const code of Object.keys(UNMERGED_CODES)) {
+      expect(isUnmergedCode(code)).toBe(true);
+    }
+    expect(Object.keys(UNMERGED_CODES).sort()).toEqual(['AA', 'AU', 'DD', 'DU', 'UA', 'UD', 'UU']);
+  });
+
+  test('rejects a clean-status code and the one-letter legacy spellings', () => {
+    // The clean codes reach the same presenter (the diff panel, the editor
+    // tabs), and a case-folded match would claim them as conflicts.
+    for (const code of ['M', 'A', 'D', 'U', '?', '??', ' M', 'M ', 'MM', 'R', 'C', 'uu', '']) {
+      expect(isUnmergedCode(code)).toBe(false);
+    }
+  });
+
+  test('rejects a non-string', () => {
+    expect(isUnmergedCode(undefined)).toBe(false);
+    expect(isUnmergedCode(null)).toBe(false);
+    expect(isUnmergedCode(42)).toBe(false);
+    expect(isUnmergedCode({})).toBe(false);
+  });
+
+  test('narrows, so the table can be indexed', () => {
+    const code: unknown = 'UU';
+    // The guard is what makes this type-check; a plain lookup could not.
+    expect(isUnmergedCode(code) ? UNMERGED_CODES[code] : null).toBe('Conflicted — both modified');
+  });
+});
+
+describe('parseConflictMarkers', () => {
+  test('reads both side labels out of a real conflict block', () => {
+    const text = [
+      'line one',
+      '<<<<<<< HEAD',
+      'MAIN',
+      '=======',
+      'FEATURE',
+      '>>>>>>> feature/payments',
+      'line three',
+    ].join('\n');
+    expect(parseConflictMarkers(text)).toEqual({ ours: 'HEAD', theirs: 'feature/payments' });
+  });
+
+  test('a rebase writes a commit subject as the theirs label', () => {
+    // Measured: `>>>>>>> a563c8a (main)` — the label is not always a branch name,
+    // which is exactly why the buttons copy it verbatim instead of prettifying.
+    const text = '<<<<<<< HEAD\nFEAT\n=======\nMAIN\n>>>>>>> a563c8a (main)\n';
+    expect(parseConflictMarkers(text)).toEqual({ ours: 'HEAD', theirs: 'a563c8a (main)' });
+  });
+
+  test('a file with no markers answers an empty pair, not a guess', () => {
+    // The caller falls back to the words ours/theirs on `{}`; inventing a label
+    // would put a name on a button that does not match the file.
+    expect(parseConflictMarkers('plain\ncontent\n')).toEqual({});
+    expect(parseConflictMarkers('')).toEqual({});
+  });
+
+  test('reads only the FIRST block', () => {
+    const text = [
+      '<<<<<<< HEAD', 'A', '=======', 'B', '>>>>>>> first',
+      'middle',
+      '<<<<<<< HEAD', 'C', '=======', 'D', '>>>>>>> second',
+    ].join('\n');
+    // One dialog answers one file, and the first block is the one the reader met.
+    expect(parseConflictMarkers(text)).toEqual({ ours: 'HEAD', theirs: 'first' });
+  });
+
+  test('a marker with no label yields undefined for that side', () => {
+    // A bare `<<<<<<<` (no trailing text) is legal; the caller's `|| 'ours'`
+    // fallback is what turns it into a usable word.
+    const markers = parseConflictMarkers('<<<<<<<\nA\n=======\nB\n>>>>>>>\n');
+    expect(markers.ours).toBeUndefined();
+    expect(markers.theirs).toBeUndefined();
+  });
+
+  test('does not treat a marker mid-line as one', () => {
+    // `startsWith` is the rule: git writes markers at column 0, and a line that
+    // merely mentions one must not be read as a side.
+    const text = 'code: <<<<<<< HEAD is the marker\n>>>>>>> not-a-side either\n';
+    expect(parseConflictMarkers(text)).toEqual({ theirs: 'not-a-side either' });
+  });
+});
+
+describe('OPERATION_LABELS', () => {
+  test('names every operation, including the two rebase spellings', () => {
+    // `rebase-merge` and `rebase-apply` are different FILES but the same word to
+    // a reader, so the bar says "rebase" for both.
+    expect(OPERATION_LABELS.merge).toBe('merge');
+    expect(OPERATION_LABELS.rebase).toBe('rebase');
+    expect(OPERATION_LABELS['rebase-apply']).toBe('rebase');
+    expect(OPERATION_LABELS['cherry-pick']).toBe('cherry-pick');
+    expect(OPERATION_LABELS.revert).toBe('revert');
+    expect(OPERATION_LABELS['stash-pop']).toBe('stash pop');
+  });
+});

package/src/shared/lib/fs/git-unmerged.ts

@@ -0,0 +1,100 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Unmerged index entries: the seven porcelain pairs `git status` reports while
+ * a merge, rebase, cherry-pick, revert or stash pop has stopped on a conflict.
+ *
+ * The pairs are NOT two independent columns the way a normal change is. Git
+ * writes one letter per SIDE — `U` for unmerged, `A`/`D` for the add/delete the
+ * side performed — so `UU` is "both modified", `AU` is "added by us" and `UA`
+ * is "added by them". Reading them the way a clean status is read (`status[0]`
+ * = index, `status[1]` = worktree) is what made every conflicted file report as
+ * STAGED, and made `UU`/`UA`/`UD` fall through to the untracked branch and
+ * render as "Untracked" — a conflicted file described as a file git has never
+ * heard of.
+ *
+ * The table is the whole point: a code outside it is not a conflict, so
+ * `isUnmergedCode` is the one predicate every surface tests, and a new pair
+ * (git has never added one) would be a row rather than a branch at each call
+ * site. Every pair's badge reads `Conflict`; the pair's own sentence is the
+ * row's tooltip, and it is here rather than at the call site because the same
+ * seven sentences are needed by the list, the tree and the diff toolbar.
+ */
+
+export const UNMERGED_CODES = {
+  UU: 'Conflicted — both modified',
+  AA: 'Conflicted — both added',
+  DD: 'Conflicted — both deleted',
+  AU: 'Conflicted — added by us',
+  UA: 'Conflicted — added by them',
+  DU: 'Conflicted — deleted by us',
+  UD: 'Conflicted — deleted by them',
+} as const;
+
+export type UnmergedCode = keyof typeof UNMERGED_CODES;
+
+/**
+ * True for one of the seven unmerged pairs.
+ *
+ * A type guard rather than a lookup at each call site: it narrows, so
+ * `UNMERGED_CODES[status]` type-checks after it, and the table is the only
+ * place the vocabulary is written down. Case-sensitive and exact on purpose —
+ * the pairs are uppercase, and a case-folded match would also claim the
+ * one-letter legacy codes other callers pass in (`getGitStatusInfo` is reached
+ * with `M`/`A`/`D`/`U` from the diff panel and the editor tabs).
+ */
+export function isUnmergedCode(status: unknown): status is UnmergedCode {
+  return typeof status === 'string' && Object.prototype.hasOwnProperty.call(UNMERGED_CODES, status);
+}
+
+/** Which side of a conflict a `<<<<<<<` / `>>>>>>>` marker block came from. */
+export interface ConflictMarkers {
+  /** The label git wrote after `<<<<<<<` — `HEAD`, or a branch/commit name. */
+  ours?: string;
+  /** The label git wrote after `>>>>>>>`. */
+  theirs?: string;
+}
+
+/**
+ * Read the two side labels out of a file holding conflict markers.
+ *
+ * This is the ONLY honest source for the words on a resolve button. `git
+ * checkout --ours` / `--theirs` are inverted during a rebase — verified: on the
+ * same two commits, a merge conflict's `--ours` yields the branch you are on
+ * while a rebase conflict's `--ours` yields the branch being rebased ONTO — so
+ * a button labelled "ours" that runs `--ours` silently takes the other side in
+ * half the conflict states. The markers git itself wrote carry the right names,
+ * and they are what the reader sees in the file.
+ *
+ * Scans only the first block (a file can hold several), because one dialog
+ * answers one file and the first block's labels are the ones the reader met
+ * first. A file with no markers yields `{}` — the caller falls back to
+ * `ours`/`theirs`.
+ */
+export function parseConflictMarkers(text: string): ConflictMarkers {
+  const markers: ConflictMarkers = {};
+  for (const line of text.split('\n')) {
+    if (!markers.ours && line.startsWith('<<<<<<<')) {
+      markers.ours = line.slice(7).trim() || undefined;
+      continue;
+    }
+    if (line.startsWith('>>>>>>>')) {
+      markers.theirs = line.slice(7).trim() || undefined;
+      break;
+    }
+  }
+  return markers;
+}
+
+/** How an operation is named in a sentence — `merge`, `rebase`, `stash pop`. */
+export const OPERATION_LABELS = {
+  merge: 'merge',
+  rebase: 'rebase',
+  'rebase-apply': 'rebase',
+  'cherry-pick': 'cherry-pick',
+  revert: 'revert',
+  'stash-pop': 'stash pop',
+} as const;

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

@@ -0,0 +1,90 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { isVirtualPath, stripReadSelector } from '@/shared/lib/fs/paths';
+
+describe('stripReadSelector', () => {
+  test('peels every selector shape omp accepts', () => {
+    // A `read` may name its lines on the path itself, and the whole string was
+    // carried around as if it were the file name — the language detector read
+    // the extension as `tsx:205-215:raw` and answered `text`, so the code
+    // surface rendered unhighlighted. Measured on a real session store: 9517 of
+    // 18128 read paths carry a selector, and 1268 of them (`:raw`, `:img`, a
+    // comma list) were missed by the previous `:N-M`-only strip.
+    expect(stripReadSelector('src/Read.tsx:205-215:raw')).toBe('src/Read.tsx');
+    expect(stripReadSelector('src/Read.tsx:raw')).toBe('src/Read.tsx');
+    expect(stripReadSelector('src/Read.tsx:205-215')).toBe('src/Read.tsx');
+    expect(stripReadSelector('src/a.ts:50')).toBe('src/a.ts');
+    expect(stripReadSelector('src/a.ts:50-')).toBe('src/a.ts');
+    expect(stripReadSelector('src/a.ts:50+150')).toBe('src/a.ts');
+    expect(stripReadSelector('src/a.ts:-60')).toBe('src/a.ts');
+    expect(stripReadSelector('src/a.ts:5-16,960-973')).toBe('src/a.ts');
+    expect(stripReadSelector('src/a.ts:19,59')).toBe('src/a.ts');
+    expect(stripReadSelector('src/a.ts:conflicts')).toBe('src/a.ts');
+    expect(stripReadSelector('src/a.ts:img')).toBe('src/a.ts');
+    expect(stripReadSelector('src/a.ts:raw:50-100')).toBe('src/a.ts');
+    expect(stripReadSelector('a.py:10-20:raw')).toBe('a.py');
+  });
+
+  test('a compound selector in either order comes off whole', () => {
+    expect(stripReadSelector('src/a.ts:1-50:raw')).toBe('src/a.ts');
+    expect(stripReadSelector('src/a.ts:raw:-60')).toBe('src/a.ts');
+  });
+
+  test('an incomplete selector is left alone', () => {
+    // omp's own splitter only peels a chunk that ENDS in a digit, `.` or `-`,
+    // which is what rejects the in-flight `path:50+`.
+    expect(stripReadSelector('src/a.ts:50+')).toBe('src/a.ts:50+');
+  });
+
+  test('a chunk that is not a selector stays part of the path', () => {
+    // The trailing rule is a chunk SHAPE test, not "the path looks like a
+    // file": a Windows drive letter and a version-ish suffix both survive,
+    // which is the conservatism omp's own splitter applies.
+    expect(stripReadSelector('C:\\proj\\x.ts')).toBe('C:\\proj\\x.ts');
+    expect(stripReadSelector('src/a.ts')).toBe('src/a.ts');
+    expect(stripReadSelector('release/v1.2.3:notes.md')).toBe('release/v1.2.3:notes.md');
+  });
+
+  test('a URL is untouched — its colon can be a port', () => {
+    // `http://host:8080/x` would otherwise lose `:8080` to the line-range rule.
+    expect(stripReadSelector('http://host:8080/x.ts')).toBe('http://host:8080/x.ts');
+    expect(stripReadSelector('xd://eval/browser')).toBe('xd://eval/browser');
+    expect(stripReadSelector('proc://kabmo-dev')).toBe('proc://kabmo-dev');
+    expect(stripReadSelector('skill://diagnose')).toBe('skill://diagnose');
+  });
+
+  test('query and hash come off', () => {
+    expect(stripReadSelector('src/a.ts?x=1#L4')).toBe('src/a.ts');
+    expect(stripReadSelector('src/a.ts:12-30?raw=1')).toBe('src/a.ts');
+  });
+});
+
+describe('isVirtualPath', () => {
+  test('recognizes an omp internal URL', () => {
+    expect(isVirtualPath('proc://kabmo-dev')).toBe(true);
+    expect(isVirtualPath('xd://lsp')).toBe(true);
+    expect(isVirtualPath('agent://Sleeper')).toBe(true);
+    expect(isVirtualPath('skill://pr-review')).toBe(true);
+    expect(isVirtualPath('artifact://17')).toBe(true);
+  });
+
+  test('leaves a real path alone', () => {
+    expect(isVirtualPath('src/x.ts')).toBe(false);
+    expect(isVirtualPath('/tmp/x.png')).toBe(false);
+    expect(isVirtualPath('C:\\proj\\x.ts')).toBe(false);
+    expect(isVirtualPath('~/x.ts')).toBe(false);
+  });
+
+  test('a bare colon is not a scheme — a Windows drive letter stays a path', () => {
+    expect(isVirtualPath('C:/proj/x.ts')).toBe(false);
+  });
+
+  test('nothing is not a virtual path', () => {
+    expect(isVirtualPath(undefined)).toBe(false);
+    expect(isVirtualPath('')).toBe(false);
+  });
+});

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

@@ -0,0 +1,109 @@
+/**
+ * Path helpers shared by the Files panel and every surface that opens a file.
+ *
+ * `/api/fs/dir` emits every entry as a path relative to the listing's base
+ * directory — the workspace root, or the selected nested repo — and reports
+ * that base back as `root`. Copy Path rebuilds the absolute path from those
+ * two halves; a relative path on its own is not resolvable outside the panel
+ * (the client-side `rootPath` may be `~`-relative, rejected by the server, or
+ * absent entirely in mock mode).
+ *
+ * `buildFsRawUrl` is the byte-stream counterpart of that same scoping: it is
+ * what an image tab points its `<img>` at, so the file it names is the file
+ * the tab names, nested repo included.
+ */
+
+/**
+ * URL of one file's raw bytes through `/api/fs/raw`, carrying the same scope
+ * (`root`, nested `repo`) as `/api/fs/read` so an image opened from a nested
+ * repo resolves to the file the tab names. `repo: '.'` is omitted: the server
+ * treats an absent repo as the scoped root.
+ */
+export function buildFsRawUrl(file: { path: string; root?: string; repo?: string }): string {
+  const params = new URLSearchParams({ path: file.path });
+  if (file.root) params.set('root', file.root);
+  if (file.repo && file.repo !== '.') params.set('repo', file.repo);
+  return `/api/fs/raw?${params.toString()}`;
+}
+
+/**
+ * True for an omp internal URL (`proc://`, `xd://`, `agent://`, `skill://`, …)
+ * rather than a path on disk.
+ *
+ * The File panel's lazy read points `/api/fs/read` at whatever path a `read`
+ * named, and a virtual URL names no file: `read proc://kabmo-dev` sent
+ * `/api/fs/read?path=proc%3A%2F%2Fkabmo-dev`, the route refused it, and
+ * the panel printed `// Loaded file: proc://kabmo-dev` as if that were the
+ * file's contents. Only a path with a scheme and no local meaning is excluded —
+ * a Windows drive letter (`C:\x`) is a single colon and stays a path.
+ */
+export function isVirtualPath(path: string | undefined): boolean {
+  return typeof path === 'string' && /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(path);
+}
+
+/**
+ * omp's read-tool selector grammar, mirroring `splitPathAndSel` in
+ * `@oh-my-pi/pi-tui/tools/read.ts`: a line range (or a comma list of them), a
+ * tail count, or a display mode — alone or compounded (`path:1-50:raw`,
+ * `path:raw:1-50`, `path:raw:-60`).
+ *
+ * The `N-`/`N..` open-ended and `N+K` forms are part of the grammar, and a
+ * chunk is only a selector when it ENDS in a digit, `.` or `-` — that trailing
+ * rule is what rejects an incomplete `N+`, exactly as omp's own lookbehind does.
+ */
+const READ_MODE_CHUNK_RE = /^(?:raw|conflicts|img)$/i;
+const READ_RANGE_CHUNK_RE = new RegExp(
+  String.raw`^(?:-\d+|L?\d+(?:(?:\.\.|[-+])L?\d*)?(?:,L?\d+(?:(?:\.\.|[-+])L?\d*)?)*)$`,
+  'i',
+);
+
+/**
+ * Strip the trailing read-tool selector from a path, so the path names the FILE
+ * and nothing else.
+ *
+ * `read` accepts a selector on the path itself (`Read.tsx:205-215:raw`) and the
+ * Kabmo carried the whole string around as if it were the file name: the
+ * language detector read the extension as `tsx:205-215:raw`, answered `text`,
+ * and the code surface rendered unhighlighted (measured on a real session
+ * store: 9517 of 18128 read paths carry a selector, and 1268 of those — every
+ * `:raw`, `:img` and comma-list — were missed by the previous `:N-M`-only
+ * strip). `/api/fs/read` and `/api/fs/raw` want the bare path for the same
+ * reason: neither route parses a selector, and the image sniff read
+ * `x.png:raw` as an unknown extension.
+ *
+ * A URL is returned untouched. Its colon can be a port — `http://host:8080/x`
+ * would otherwise lose `:8080` to the line-range rule — and no fs route ever
+ * receives one.
+ *
+ * A chunk is only peeled while it matches the selector grammar AND ends in a
+ * digit, `.` or `-` (omp's own trailing lookbehind: it is what rejects the
+ * incomplete `N+`), so a file legally named `a:1-50` keeps its name — the same
+ * conservatism omp's splitter applies.
+ */
+export function stripReadSelector(path: string): string {
+  if (!path || isVirtualPath(path)) return path;
+  const cut = path.search(/[?#]/);
+  let result = cut === -1 ? path : path.slice(0, cut);
+  for (;;) {
+    const colon = result.lastIndexOf(':');
+    if (colon <= 0) break;
+    const chunk = result.slice(colon + 1);
+    const isMode = READ_MODE_CHUNK_RE.test(chunk);
+    // A numeric chunk must END in a digit, `.` or `-`: omp's own trailing
+    // lookbehind, and what rejects the incomplete `N+` (`path:50+`).
+    const isRange = READ_RANGE_CHUNK_RE.test(chunk) && /[\d.-]$/.test(chunk);
+    if (!isMode && !isRange) break;
+    result = result.slice(0, colon);
+  }
+  return result;
+}
+
+export function toAbsolutePath(baseDir: string | null | undefined, relPath: string): string {
+  // `/`- and `./`-prefixed raws are stripped; a dot-file name (`.env`) is not a prefix.
+  const rel = relPath.replace(/^(?:\.?[/\\])+/, '').replace(/[/\\]+$/, '');
+  const base = (baseDir ?? '').replace(/[/\\]+$/, '');
+  if (!base) return rel;
+  if (!rel) return base;
+  // Join with the base's own separator: `C:\proj` + `src` → `C:\proj\src`.
+  return `${base}${base.includes('\\') && !base.includes('/') ? '\\' : '/'}${rel}`;
+}

package/src/shared/lib/fs/repo-groups.ts

@@ -0,0 +1,85 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * How a flat list of repositories is grouped for the repo management modal.
+ *
+ * Discovery returns a flat list — `.` for the workspace root itself, then one
+ * entry per nested repository (`projects/jns6_5/token`) — and a flat list of
+ * fifty rows is exactly what the modal exists to make navigable. The grouping
+ * is the same one a reader already has in their head from the file tree: the
+ * workspace root, then one group per top-level directory.
+ *
+ * **Sorted, never in discovery order.** `findGitDirs` pushes entries in
+ * `readdir` order, which is filesystem order and differs between machines and
+ * after a directory is written; a list that reorders itself between two reads of
+ * the same workspace is a list nobody can scan. Paths sort with the same
+ * comparison a file listing uses.
+ *
+ * A single-segment repo (`token`) has no folder to group under, so it belongs to
+ * the root group — it IS a direct child of the workspace, which is what the
+ * group means.
+ */
+
+export interface RepoGroup {
+  /** Stable key for React; `''` is the workspace root's own group. */
+  key: string;
+  /** Heading text; `null` for the root group, which needs no heading. */
+  label: string | null;
+  /** Root-relative paths, sorted. */
+  paths: string[];
+}
+
+/**
+ * Group repos by their first path segment, root first.
+ *
+ * `rootIsRepo` decides whether `.` gets the root group to itself or is grouped
+ * with the direct children: when the workspace root IS a repository, its row is
+ * the one the panels default to and it leads the list on its own; when it is
+ * not (a folder of nested repos), a `.` row would be a row git cannot read and
+ * discovery does not produce one.
+ */
+export function groupRepos(repos: readonly string[]): RepoGroup[] {
+  const groups = new Map<string, RepoGroup>();
+
+  for (const repo of repos) {
+    if (!repo || repo === '.') {
+      if (!groups.has('')) groups.set('', { key: '', label: null, paths: [] });
+      groups.get('')!.paths.push('.');
+      continue;
+    }
+    const slash = repo.indexOf('/');
+    const key = slash === -1 ? '' : repo.slice(0, slash);
+    let group = groups.get(key);
+    if (!group) {
+      group = { key, label: key === '' ? null : key, paths: [] };
+      groups.set(key, group);
+    }
+    group.paths.push(repo);
+  }
+
+  for (const group of groups.values()) {
+    group.paths.sort((a, b) => (a === '.' ? -1 : b === '.' ? 1 : a.localeCompare(b)));
+  }
+
+  // Root group first, then folders alphabetically. The root is the repository
+  // the panels are most likely showing and the one a reader looks for first.
+  return [...groups.values()].sort((a, b) => {
+    if (a.key === '') return -1;
+    if (b.key === '') return 1;
+    return a.key.localeCompare(b.key);
+  });
+}
+
+/**
+ * The name a row is listed under inside its group: the part below the group
+ * heading, so `projects/jns6_5/token` under `projects` reads `jns6_5/token`
+ * rather than repeating the folder it is already filed under.
+ */
+export function repoNameWithinGroup(path: string, groupKey: string): string {
+  if (path === '.') return 'workspace root';
+  if (groupKey === '') return path;
+  return path.slice(groupKey.length + 1);
+}

package/src/shared/lib/fs/repo-label.test.ts

@@ -0,0 +1,118 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The label and grouping rules behind the repo picker.
+ *
+ * Both are shared by five panels, so a mistake here is one mistake rendered in
+ * five places. The grouping has the load-bearing half: the list must sort, or a
+ * workspace whose `readdir` order differs between two reads renders its rows in
+ * a different order each time the dialog opens — and a list nobody can scan is
+ * the thing the modal exists to fix.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { groupRepos, repoNameWithinGroup } from '@/shared/lib/fs/repo-groups';
+import { repoLabel, repoShortLabel, workspaceFolderName } from '@/shared/lib/fs/repo-label';
+
+describe('workspaceFolderName', () => {
+  test('names the root by its last path segment', () => {
+    expect(workspaceFolderName('/home/dev/JatisMobile/Workspace')).toBe('Workspace');
+  });
+
+  test('a trailing separator names the same directory', () => {
+    expect(workspaceFolderName('/home/dev/Workspace/')).toBe('Workspace');
+  });
+
+  test('a Windows path splits on backslashes too', () => {
+    expect(workspaceFolderName('C:\\work\\chamber')).toBe('chamber');
+  });
+
+  test('a path with no name falls back rather than labelling empty', () => {
+    expect(workspaceFolderName('/')).toBe('workspace root');
+    expect(workspaceFolderName('')).toBe('workspace root');
+    expect(workspaceFolderName(undefined)).toBe('workspace root');
+  });
+});
+
+describe('repoLabel', () => {
+  test('the root reads as the workspace folder', () => {
+    expect(repoLabel('.', '/home/dev/Workspace')).toBe('Workspace');
+  });
+
+  test('a nested repo keeps its whole path', () => {
+    // The list is where `jns6_5/token` and `jns7/token` have to be told apart,
+    // so the full path is the label rather than the basename.
+    expect(repoLabel('projects/jns6_5/token', '/ws')).toBe('projects/jns6_5/token');
+  });
+});
+
+describe('repoShortLabel', () => {
+  test('a nested repo is named by its last segment in a trigger', () => {
+    expect(repoShortLabel('projects/jns6_5/token', '/ws')).toBe('token');
+  });
+
+  test('the root keeps the workspace folder name', () => {
+    expect(repoShortLabel('.', '/home/dev/Workspace')).toBe('Workspace');
+  });
+
+  test('a single-segment repo is its own label', () => {
+    expect(repoShortLabel('token', '/ws')).toBe('token');
+  });
+});
+
+describe('groupRepos', () => {
+  test('groups by first path segment, root first then folders alphabetically', () => {
+    const groups = groupRepos(['projects/b/two', 'projects/a/one', '.', 'other/x']);
+    expect(groups.map((g) => g.key)).toEqual(['', 'other', 'projects']);
+    expect(groups[0].paths).toEqual(['.']);
+    expect(groups[2].paths).toEqual(['projects/a/one', 'projects/b/two']);
+  });
+
+  test('a single-segment repo belongs to the root group', () => {
+    // `token` IS a direct child of the workspace, which is what the root group
+    // means — filing it under a folder named after itself would invent a level.
+    const groups = groupRepos(['token', '.']);
+    expect(groups).toHaveLength(1);
+    expect(groups[0].paths).toEqual(['.', 'token']);
+  });
+
+  test('sorts within a group so two reads render the same order', () => {
+    // `findGitDirs` pushes in readdir order, which is filesystem order.
+    const shuffled = groupRepos(['p/z', 'p/a', 'p/m']);
+    const reversed = groupRepos(['p/m', 'p/a', 'p/z']);
+    expect(shuffled[0].paths).toEqual(['p/a', 'p/m', 'p/z']);
+    expect(reversed[0].paths).toEqual(shuffled[0].paths);
+  });
+
+  test('the root group leads even when its key sorts last alphabetically', () => {
+    const groups = groupRepos(['.', 'zzz/x']);
+    expect(groups.map((g) => g.key)).toEqual(['', 'zzz']);
+  });
+
+  test('an empty list answers no groups', () => {
+    expect(groupRepos([])).toEqual([]);
+  });
+
+  test('a root group has no heading; a folder group is headed by its name', () => {
+    const groups = groupRepos(['.', 'projects/x']);
+    expect(groups[0].label).toBeNull();
+    expect(groups[1].label).toBe('projects');
+  });
+});
+
+describe('repoNameWithinGroup', () => {
+  test('the part below the heading, so the folder is not repeated', () => {
+    expect(repoNameWithinGroup('projects/jns6_5/token', 'projects')).toBe('jns6_5/token');
+  });
+
+  test('a repo in the root group keeps its whole path', () => {
+    expect(repoNameWithinGroup('token', '')).toBe('token');
+  });
+
+  test('the root itself is named, not left as a dot', () => {
+    expect(repoNameWithinGroup('.', '')).toBe('workspace root');
+  });
+});