@kabmo-labs/kabmo 0.7.0 → 0.9.0

package/src/server/lib/fs/worktree/list.test.ts

@@ -0,0 +1,207 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Worktree listing, against real repositories.
+ *
+ * Three answers here cannot be faked by a hand-written porcelain string, and
+ * each is a case that has to keep working:
+ *
+ *  - a linked worktree is NOT the primary, and a deleted directory is `missing`
+ *    while its entry stays in the list (the sessions that lived there must keep
+ *    their row);
+ *  - two spellings of one directory reconcile — on macOS git prints
+ *    `/private/tmp/...` for a path the caller typed as `/tmp/...`, and a
+ *    comparison that ignored that decided a worktree was not inside itself;
+ *  - the session → worktree lookup picks the INNER worktree, because that is
+ *    the directory the agent writes to.
+ */
+
+import { afterAll, describe, expect, test } from 'bun:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { canonicalPath, pathHolds } from '@/server/lib/fs/canonical';
+import { findBranchInUse, listWorktrees, parseWorktreePorcelain } from '@/server/lib/fs/worktree/list';
+import { invalidateWorktreeTopology, readProjectWorktrees, worktreeForCwd } from '@/server/lib/fs/worktree/topology';
+import { removeDir } from '@/test-support/remove-dir';
+
+const FIXTURE_ROOT = fs.mkdtempSync(path.join(os.tmpdir(), 'kabmo-worktree-list-'));
+
+function git(cwd: string, ...args: string[]): string {
+  const result = Bun.spawnSync({
+    cmd: ['git', ...args],
+    cwd,
+    env: { ...Bun.env, GIT_EDITOR: 'true', GIT_TERMINAL_PROMPT: '0' },
+  });
+  return result.stdout.toString();
+}
+
+function makeRepo(name: string): string {
+  const dir = path.join(FIXTURE_ROOT, name);
+  fs.mkdirSync(dir, { recursive: true });
+  git(dir, 'init', '-q', '-b', 'main', '.');
+  git(dir, 'config', 'user.email', 'test@example.invalid');
+  git(dir, 'config', 'user.name', 'Test');
+  fs.writeFileSync(path.join(dir, 'f.txt'), 'a\n');
+  git(dir, 'add', '-A');
+  git(dir, 'commit', '-q', '-m', 'base');
+  return dir;
+}
+
+afterAll(async () => {
+  await invalidateWorktreeTopology();
+  removeDir(FIXTURE_ROOT);
+});
+
+describe('parseWorktreePorcelain', () => {
+  const PORCELAIN = [
+    'worktree /repo',
+    'HEAD aaa',
+    'branch refs/heads/main',
+    '',
+    'worktree /wt/detached',
+    'HEAD bbb',
+    'detached',
+    '',
+    'worktree /wt/gone',
+    'HEAD ccc',
+    'branch refs/heads/feat',
+    'prunable gitdir file points to non-existent location',
+    '',
+    'worktree /bare',
+    'bare',
+    '',
+  ].join('\n');
+
+  test('reads the branch, a detached HEAD, a prunable entry, and drops a bare repo', () => {
+    const entries = parseWorktreePorcelain(PORCELAIN);
+    expect(entries.map((entry) => entry.path)).toEqual(['/repo', '/wt/detached', '/wt/gone']);
+    expect(entries[0]?.branch).toBe('main');
+    expect(entries[1]?.detached).toBe(true);
+    expect(entries[1]?.branch).toBe('');
+    expect(entries[2]?.missing).toBe(true);
+  });
+
+  test('a bare repository is not a checkout anything can run in', () => {
+    expect(parseWorktreePorcelain(PORCELAIN).some((entry) => entry.path === '/bare')).toBe(false);
+  });
+});
+
+describe('listWorktrees', () => {
+  test('flags the primary and a linked worktree apart', async () => {
+    const repo = makeRepo('list-basic');
+    const linked = path.join(FIXTURE_ROOT, 'list-basic-wt');
+    git(repo, 'worktree', 'add', '-q', '-b', 'feat', linked);
+
+    const entries = await listWorktrees(repo);
+    const primary = entries.find((entry) => entry.isPrimary);
+    const other = entries.find((entry) => !entry.isPrimary);
+    expect(primary?.path).toBe(await canonicalPath(repo));
+    expect(other?.branch).toBe('feat');
+    expect(other?.missing).toBe(false);
+    // Paths come back canonical, whichever spelling git was handed.
+    expect(other?.path).toBe(await canonicalPath(linked));
+  });
+
+  test('a directory deleted outside git stays listed as missing', async () => {
+    const repo = makeRepo('list-missing');
+    const linked = path.join(FIXTURE_ROOT, 'list-missing-wt');
+    git(repo, 'worktree', 'add', '-q', '-b', 'gone', linked);
+    fs.rmSync(linked, { recursive: true, force: true });
+
+    const entries = await listWorktrees(repo);
+    const entry = entries.find((candidate) => !candidate.isPrimary);
+    expect(entry?.missing).toBe(true);
+    // And the missing path still canonicalizes, so it can be matched at all.
+    expect(entry?.path).toBe(await canonicalPath(linked));
+  });
+
+  test('findBranchInUse names the worktree that holds a branch', async () => {
+    const repo = makeRepo('list-in-use');
+    const linked = path.join(FIXTURE_ROOT, 'list-in-use-wt');
+    git(repo, 'worktree', 'add', '-q', '-b', 'held', linked);
+
+    const hit = await findBranchInUse(repo, 'held');
+    expect(hit?.path).toBe(await canonicalPath(linked));
+    expect(await findBranchInUse(repo, 'free')).toBeNull();
+  });
+});
+
+describe('canonical paths', () => {
+  test('a sibling sharing a prefix is not inside', async () => {
+    const base = path.join(FIXTURE_ROOT, 'holds');
+    fs.mkdirSync(path.join(base, 'repo', 'src'), { recursive: true });
+    fs.mkdirSync(path.join(base, 'repo-other'), { recursive: true });
+
+    expect(await pathHolds(path.join(base, 'repo'), path.join(base, 'repo'))).toBe(true);
+    expect(await pathHolds(path.join(base, 'repo'), path.join(base, 'repo', 'src'))).toBe(true);
+    expect(await pathHolds(path.join(base, 'repo'), path.join(base, 'repo-other'))).toBe(false);
+  });
+
+  test('a MISSING path resolves through its nearest existing ancestor', async () => {
+    const base = path.join(FIXTURE_ROOT, 'canonical-missing');
+    fs.mkdirSync(base, { recursive: true });
+    const missing = path.join(base, 'gone', 'deeper');
+    expect(await canonicalPath(missing)).toBe(path.join(await canonicalPath(base), 'gone', 'deeper'));
+  });
+
+  test('`..` cannot escape', async () => {
+    const base = path.join(FIXTURE_ROOT, 'canonical-escape');
+    fs.mkdirSync(base, { recursive: true });
+    expect(await pathHolds(base, path.join(base, '..', 'elsewhere'))).toBe(false);
+  });
+});
+
+describe('session → worktree', () => {
+  test('an inner worktree wins over the checkout that contains it', async () => {
+    const repo = makeRepo('topology');
+    const outer = path.join(FIXTURE_ROOT, 'topology-outer');
+    git(repo, 'worktree', 'add', '-q', '-b', 'outer', outer);
+    fs.mkdirSync(path.join(outer, 'sub'), { recursive: true });
+
+    const entries = await listWorktrees(repo);
+    const primary = entries.find((entry) => entry.isPrimary)?.path as string;
+
+    const inner = await worktreeForCwd(entries, path.join(outer, 'sub'), primary);
+    expect(inner?.path).toBe(await canonicalPath(outer));
+    expect(inner?.branch).toBe('outer');
+    expect(inner?.status).toBe('ready');
+
+    // A session in the checkout itself has no badge — it is not a worktree session.
+    expect(await worktreeForCwd(entries, primary, primary)).toBeNull();
+  });
+
+  test('a missing worktree still answers, with status `missing`', async () => {
+    const repo = makeRepo('topology-missing');
+    const linked = path.join(FIXTURE_ROOT, 'topology-missing-wt');
+    git(repo, 'worktree', 'add', '-q', '-b', 'vanish', linked);
+    fs.rmSync(linked, { recursive: true, force: true });
+
+    const entries = await listWorktrees(repo);
+    const primary = entries.find((entry) => entry.isPrimary)?.path as string;
+    const badge = await worktreeForCwd(entries, linked, primary);
+    expect(badge?.status).toBe('missing');
+    expect(badge?.branch).toBe('vanish');
+  });
+
+  test('the topology read is cached, and invalidation drops it', async () => {
+    const repo = makeRepo('topology-cache');
+    const first = await readProjectWorktrees(repo);
+    const second = await readProjectWorktrees(repo);
+    expect(second).toBe(first); // same array identity — a real cache hit
+
+    const linked = path.join(FIXTURE_ROOT, 'topology-cache-wt');
+    git(repo, 'worktree', 'add', '-q', '-b', 'new-one', linked);
+    // Cached: the new worktree is not visible yet.
+    expect((await readProjectWorktrees(repo)).length).toBe(1);
+
+    // AWAITED: the invalidation resolves the canonical key asynchronously, so an
+    // un-awaited call races the read below — measured on both CI legs, where the
+    // read won and the cache still answered one entry.
+    await invalidateWorktreeTopology(await canonicalPath(repo));
+    expect((await readProjectWorktrees(repo)).length).toBe(2);
+  });
+});

package/src/server/lib/fs/worktree/list.ts

@@ -0,0 +1,142 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `git worktree list --porcelain`, parsed into rows.
+ *
+ * The two markers a naive parse loses, and both matter to a reader:
+ *
+ *  - **no `branch` line** → detached HEAD, which the row shows as `detached @
+ *    <sha>` and the delete dialog treats as not-a-branch;
+ *  - **`prunable`** → the directory is gone or the gitdir pointer is broken. The
+ *    entry STAYS in the list: the sessions that lived there must keep their row,
+ *    and dropping it would hide them with no way back.
+ *
+ * Paths are canonicalized here, once, for every consumer — git echoes the
+ * spelling it was given while the repository root resolves through symlinks, and
+ * two spellings of one directory must not read as two worktrees.
+ */
+
+import { existsSync } from 'fs';
+import { canonicalPath } from '@/server/lib/fs/canonical';
+import { runGit } from '@/server/lib/fs/git-run';
+import { resolveProjectRoot } from '@/server/lib/omp/core/worktree';
+
+export interface WorktreeEntry {
+  path: string;
+  /** `refs/heads/` stripped; `''` when detached. */
+  branch: string;
+  head: string;
+  detached: boolean;
+  /** git reports it prunable, or the directory is not there. */
+  missing: boolean;
+  /** The checkout the worktree was created from — never removable. */
+  isPrimary: boolean;
+}
+
+/** Split on blank lines; a bare repository is not a checkout anything can run in. */
+export function parseWorktreePorcelain(stdout: string): Omit<WorktreeEntry, 'isPrimary'>[] {
+  interface Pending {
+    path: string;
+    branch?: string;
+    head?: string;
+    missing: boolean;
+    bare: boolean;
+  }
+
+  const entries: Omit<WorktreeEntry, 'isPrimary'>[] = [];
+  let current: Pending | null = null;
+
+  const flush = () => {
+    if (!current?.path || current.bare) {
+      current = null;
+      return;
+    }
+    const branch = current.branch ?? '';
+    const head = current.head ?? '';
+    entries.push({
+      path: current.path,
+      branch,
+      head,
+      detached: !branch && Boolean(head),
+      missing: current.missing,
+    });
+    current = null;
+  };
+
+  for (const rawLine of stdout.split('\n')) {
+    const line = rawLine.trimEnd();
+    if (!line) {
+      flush();
+      continue;
+    }
+    if (line.startsWith('worktree ')) {
+      flush();
+      current = { path: line.slice('worktree '.length).trim(), missing: false, bare: false };
+      continue;
+    }
+    if (!current) continue;
+    if (line.startsWith('HEAD ')) {
+      current.head = line.slice('HEAD '.length).trim();
+      continue;
+    }
+    if (line.startsWith('branch ')) {
+      current.branch = line.slice('branch '.length).trim().replace(/^refs\/heads\//, '');
+      continue;
+    }
+    if (line === 'bare') current.bare = true;
+    if (line === 'prunable' || line.startsWith('prunable ')) current.missing = true;
+  }
+  flush();
+
+  return entries;
+}
+
+/** Every worktree of the repository `cwd` belongs to, primary first. */
+export async function listWorktrees(cwd: string): Promise<WorktreeEntry[]> {
+  const primaryRoot = await resolveProjectRoot(cwd);
+  const listed = await runGit(['worktree', 'list', '--porcelain'], { cwd: primaryRoot, maxBuffer: 1024 * 1024 });
+  if (listed.exitCode !== 0) throw new Error(listed.stderr.trim() || 'Failed to list git worktrees');
+
+  const canonicalPrimary = await canonicalPath(primaryRoot);
+  const entries: WorktreeEntry[] = [];
+  for (const entry of parseWorktreePorcelain(listed.stdout)) {
+    const canonical = await canonicalPath(entry.path);
+    entries.push({
+      ...entry,
+      path: canonical,
+      isPrimary: canonical === canonicalPrimary,
+      // A directory removed without `prune` answers `existsSync` false, and both
+      // signals mean the same thing to a reader.
+      missing: entry.missing || !existsSync(canonical),
+    });
+  }
+  return entries;
+}
+
+/**
+ * Whether `cwd` is inside a work tree at all.
+ *
+ * The check a plain directory fails, and the one every caller here needs before
+ * it may talk about worktrees: `git worktree list` in a non-repository exits
+ * non-zero, so without this a notes folder bound as a workspace reads as a
+ * BROKEN repository rather than as one that has none.
+ */
+export async function isWorkTree(cwd: string): Promise<boolean> {
+  const probe = await runGit(['rev-parse', '--is-inside-work-tree'], { cwd });
+  return probe.exitCode === 0 && probe.stdout.trim() === 'true';
+}
+
+/** Whether `branch` is checked out in any worktree of this repository, and where. */
+export async function findBranchInUse(cwd: string, branch: string): Promise<{ path: string } | null> {
+  const entries = await listWorktrees(cwd);
+  const hit = entries.find((entry) => entry.branch === branch);
+  return hit ? { path: hit.path } : null;
+}
+
+export async function refExists(cwd: string, ref: string): Promise<boolean> {
+  const probe = await runGit(['show-ref', '--verify', '--quiet', ref], { cwd });
+  return probe.exitCode === 0;
+}

package/src/server/lib/fs/worktree/location.test.ts

@@ -0,0 +1,206 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Repository identity, and the settings-driven location rule.
+ *
+ * Identity has one property that is easy to get wrong and expensive when it is:
+ * the derivation (`rev-list --max-parents=0 --all`, sorted, first) is NOT stable.
+ * Measured: a repository that gains a branch with unrelated history inserts a
+ * second root and the sorted-first value MOVES, so a repository would start
+ * looking for its worktrees in a different folder. That is why a stored value
+ * always wins — the behavior this file pins.
+ */
+
+import { afterAll, describe, expect, test } from 'bun:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { canonicalPath } from '@/server/lib/fs/canonical';
+import { deriveProjectId, resolveProjectId } from '@/server/lib/fs/worktree/project-id';
+import {
+  defaultWorktreeRoot,
+  generateAvailableName,
+  resolveConfiguredWorktreeRoot,
+  resolveTargetDirectory,
+  worktreeNameCandidates,
+} from '@/server/lib/fs/worktree/location';
+import { removeDir } from '@/test-support/remove-dir';
+
+const FIXTURE_ROOT = fs.mkdtempSync(path.join(os.tmpdir(), 'kabmo-worktree-location-'));
+
+const GIT_ENV_FOR_TESTS = {
+  ...Bun.env,
+  GIT_EDITOR: 'true',
+  GIT_TERMINAL_PROMPT: '0',
+  GIT_AUTHOR_NAME: 'Test',
+  GIT_AUTHOR_EMAIL: 'test@example.invalid',
+  GIT_COMMITTER_NAME: 'Test',
+  GIT_COMMITTER_EMAIL: 'test@example.invalid',
+};
+
+function git(cwd: string, ...args: string[]): string {
+  return Bun.spawnSync({ cmd: ['git', ...args], cwd, env: GIT_ENV_FOR_TESTS }).stdout.toString();
+}
+
+function makeRepo(name: string): string {
+  const dir = path.join(FIXTURE_ROOT, name);
+  fs.mkdirSync(dir, { recursive: true });
+  git(dir, 'init', '-q', '-b', 'main', '.');
+  fs.writeFileSync(path.join(dir, 'f.txt'), 'a\n');
+  git(dir, 'add', '-A');
+  git(dir, 'commit', '-q', '-m', 'base');
+  return dir;
+}
+
+afterAll(() => {
+  removeDir(FIXTURE_ROOT);
+});
+
+describe('deriveProjectId', () => {
+  test('two clones of one repository share the identity', async () => {
+    const bare = path.join(FIXTURE_ROOT, 'origin.git');
+    fs.mkdirSync(bare, { recursive: true });
+    git(bare, 'init', '-q', '--bare');
+
+    const first = makeRepo('clone-a');
+    git(first, 'remote', 'add', 'origin', bare);
+    const head = git(first, 'rev-parse', 'HEAD').trim();
+    git(first, 'push', '-q', 'origin', `${head}:refs/heads/main`);
+
+    const second = path.join(FIXTURE_ROOT, 'clone-b');
+    git(FIXTURE_ROOT, 'clone', '-q', bare, second);
+
+    const a = await deriveProjectId(first);
+    const b = await deriveProjectId(second);
+    expect(a).not.toBeNull();
+    expect(a).toBe(b);
+  });
+
+  test('an unborn repository has no identity — the `no_commits` refusal', async () => {
+    const empty = path.join(FIXTURE_ROOT, 'unborn');
+    fs.mkdirSync(empty, { recursive: true });
+    git(empty, 'init', '-q', '-b', 'main', '.');
+    expect(await deriveProjectId(empty)).toBeNull();
+  });
+
+  test('a stored identity wins over a re-derivation', async () => {
+    const repo = makeRepo('identity-stored');
+    const stored = 'stored-project-id';
+    const identityFor = async () => stored;
+    expect(await resolveProjectId(await canonicalPath(repo), identityFor)).toBe(stored);
+  });
+
+  test('an added orphan branch changes the derivation — hence the cache', async () => {
+    const repo = makeRepo('identity-orphan');
+    const derived = await deriveProjectId(repo);
+    expect(derived).not.toBeNull();
+
+    git(repo, 'checkout', '-q', '--orphan', 'other');
+    git(repo, 'rm', '-rq', '--cached', '.');
+    git(repo, 'add', '-A');
+    git(repo, 'commit', '-q', '-m', 'other root');
+
+    // Two roots now exist, so the sorted-first value is a different question
+    // than it was — which is exactly why the stored value is consulted first.
+    const roots = git(repo, 'rev-list', '--max-parents=0', '--all')
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean);
+    expect(roots.length).toBe(2);
+
+    // The stored value is consulted first, whatever the derivation now answers.
+    const stored = derived as string;
+    const later = await resolveProjectId(await canonicalPath(repo), async () => stored);
+    expect(later).toBe(stored);
+  });
+});
+
+describe('worktree location', () => {
+  // A literal POSIX spelling is not portable: `path.resolve('/repo', '.worktrees')`
+  // answers `D:\repo\.worktrees` on a Windows runner, which is the CORRECT
+  // answer for that platform and not a product bug. Every expectation is
+  // therefore built through `path`, so the rule is asserted rather than the
+  // separator.
+  const checkout = path.resolve('/repo');
+  const home = path.resolve('/home/u');
+
+  test('three spellings, and the resolved value is always the parent', () => {
+    expect(resolveConfiguredWorktreeRoot('', checkout)).toBeNull();
+    expect(resolveConfiguredWorktreeRoot(null, checkout)).toBeNull();
+    expect(resolveConfiguredWorktreeRoot('   ', checkout)).toBeNull();
+    expect(resolveConfiguredWorktreeRoot('../wt', checkout)).toBe(path.resolve(checkout, '..', 'wt'));
+    expect(resolveConfiguredWorktreeRoot('.worktrees', checkout)).toBe(path.join(checkout, '.worktrees'));
+    expect(resolveConfiguredWorktreeRoot('/abs/wt', checkout)).toBe(path.resolve(checkout, '/abs/wt'));
+    expect(resolveConfiguredWorktreeRoot('~/wt', checkout, home)).toBe(path.join(home, 'wt'));
+    expect(resolveConfiguredWorktreeRoot('~', checkout, home)).toBe(home);
+  });
+
+  test('the default root is keyed per repository, outside every checkout', () => {
+    expect(defaultWorktreeRoot('/data', 'abc123')).toBe(path.join('/data', 'worktrees', 'abc123'));
+  });
+
+  test('the slug is tried first, then slug-word-word', () => {
+    const candidates = worktreeNameCandidates('quick-otter');
+    expect(candidates[0]).toBe('quick-otter');
+    expect(candidates[1]).toMatch(/^quick-otter-[a-z]+-[a-z]+$/);
+    expect(candidates.length).toBe(26);
+  });
+
+  test('a taken folder moves to the next candidate rather than refusing', async () => {
+    const root = path.join(FIXTURE_ROOT, 'collide');
+    fs.mkdirSync(path.join(root, 'quick-otter'), { recursive: true });
+
+    const target = await resolveTargetDirectory({
+      root,
+      preferredName: 'quick-otter',
+      generatedBranch: (name) => `wt/${name}`,
+      branchExists: async () => false,
+    });
+    expect(target.directory).not.toBe(path.join(root, 'quick-otter'));
+    expect(target.name.startsWith('quick-otter-')).toBe(true);
+  });
+
+  test('a taken BRANCH is skipped too, so folder and branch never disagree', async () => {
+    const root = path.join(FIXTURE_ROOT, 'branch-collide');
+    fs.mkdirSync(root, { recursive: true });
+
+    const target = await resolveTargetDirectory({
+      root,
+      preferredName: 'quick-otter',
+      generatedBranch: (name) => `wt/${name}`,
+      branchExists: async (branch) => branch === 'wt/quick-otter',
+    });
+    expect(target.branch).not.toBe('wt/quick-otter');
+    expect(target.branch).toBe(`wt/${target.name}`);
+  });
+
+  test('a typed branch is used verbatim in both modes', async () => {
+    const root = path.join(FIXTURE_ROOT, 'verbatim');
+    fs.mkdirSync(root, { recursive: true });
+    const target = await resolveTargetDirectory({
+      root,
+      preferredName: 'payments',
+      explicitBranch: 'feat/payments',
+      generatedBranch: (name) => `wt/${name}`,
+      // Even when every generated name is taken, the typed branch is used.
+      branchExists: async () => true,
+    });
+    expect(target.branch).toBe('feat/payments');
+    expect(target.name).toBe('payments');
+  });
+
+  test('a generated name avoids both a folder and a branch', async () => {
+    const root = path.join(FIXTURE_ROOT, 'generated');
+    fs.mkdirSync(root, { recursive: true });
+    const name = await generateAvailableName({
+      root,
+      branchExists: async (branch) => branch === 'wt/blocked',
+      attempts: 4,
+    });
+    expect(name).not.toBe('blocked');
+    expect(name).toMatch(/^[a-z]+-[a-z]+$/);
+  });
+});

package/src/server/lib/fs/worktree/location.ts

@@ -0,0 +1,114 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Where a worktree lands — OpenChamber's rule, adopted as-is:
+ *
+ *   root = configured directory (resolved) || <data dir>/worktrees/<projectID>
+ *   path = <root>/<name>
+ *
+ * Three spellings for the setting, unchanged from theirs: a relative path
+ * resolves against the CANONICAL checkout (so a linked worktree still reads the
+ * project's own setting), an absolute path is used as-is, and `~` means the home
+ * directory. The resolved value is always the PARENT — the name is appended.
+ *
+ * A name is never refused because it is taken: candidates are tried in order, so
+ * "quick otter" in a repository that already has one becomes
+ * `quick-otter-cosmic-dolphin` rather than an error the user has to read.
+ */
+
+import path from 'path';
+import { homedir } from 'os';
+import { pathExists } from '@/server/lib/omp/core/paths';
+import {
+  generateBranchSlug,
+  slugWorktreeName,
+  WORKTREE_BRANCH_PREFIX,
+} from '@/shared/lib/workspace/worktree/branch-name';
+
+/** How many names to try before giving up. OpenChamber's 26, kept. */
+export const WORKTREE_NAME_ATTEMPTS = 26;
+
+/**
+ * Resolve the setting into a parent directory. `null` when unset, so the caller
+ * keeps its own default rather than resolving an empty string to the checkout.
+ */
+export function resolveConfiguredWorktreeRoot(
+  configured: unknown,
+  primaryCheckout: string,
+  home: string = homedir(),
+): string | null {
+  const trimmed = String(configured ?? '').trim();
+  if (!trimmed) return null;
+  if (trimmed === '~') return path.resolve(home);
+  if (/^~[\\/]/.test(trimmed)) return path.resolve(home, trimmed.slice(2));
+  return path.resolve(primaryCheckout, trimmed);
+}
+
+/** `<data dir>/worktrees/<projectID>` — outside every checkout, keyed per repository. */
+export function defaultWorktreeRoot(dataDir: string, projectId: string): string {
+  return path.join(dataDir, 'worktrees', projectId);
+}
+
+/** `<slug>`, then `<slug>-<adjective>-<noun>` × attempts-1. */
+export function worktreeNameCandidates(preferredName: string, attempts = WORKTREE_NAME_ATTEMPTS): string[] {
+  const base = slugWorktreeName(preferredName);
+  if (!base) {
+    return Array.from({ length: attempts }, () => generateBranchSlug());
+  }
+  return Array.from({ length: attempts }, (_, index) =>
+    index === 0 ? base : `${base}-${generateBranchSlug()}`,
+  );
+}
+
+export interface ResolvedWorktreeTarget {
+  name: string;
+  directory: string;
+  branch: string;
+}
+
+export interface ResolveTargetInput {
+  root: string;
+  preferredName: string;
+  /** The dialog's branch, used verbatim and only the directory is checked. */
+  explicitBranch?: string | null;
+  /** The branch a generated candidate would get. */
+  generatedBranch: (name: string) => string;
+  branchExists: (branch: string) => Promise<boolean>;
+}
+
+/**
+ * Pick a free name. A candidate is rejected when its directory exists OR — for a
+ * generated branch — when the branch it would get already exists, so the folder
+ * and the branch can never disagree about which one is "the name".
+ */
+export async function resolveTargetDirectory(input: ResolveTargetInput): Promise<ResolvedWorktreeTarget> {
+  const explicit = input.explicitBranch?.trim() || null;
+  for (const name of worktreeNameCandidates(input.preferredName)) {
+    const directory = path.join(input.root, name);
+    if (await pathExists(directory)) continue;
+    if (explicit) return { name, directory, branch: explicit };
+    const branch = input.generatedBranch(name);
+    if (await input.branchExists(branch)) continue;
+    return { name, directory, branch };
+  }
+  throw new Error('Failed to generate a unique worktree name');
+}
+
+/** A generated slug that collides with neither a folder nor a branch. */
+export async function generateAvailableName(input: {
+  root: string;
+  branchExists: (branch: string) => Promise<boolean>;
+  attempts?: number;
+}): Promise<string> {
+  const attempts = input.attempts ?? WORKTREE_NAME_ATTEMPTS;
+  for (let index = 0; index < attempts; index += 1) {
+    const slug = generateBranchSlug();
+    if (await pathExists(path.join(input.root, slug))) continue;
+    if (await input.branchExists(`${WORKTREE_BRANCH_PREFIX}/${slug}`)) continue;
+    return slug;
+  }
+  throw new Error('Failed to generate a unique worktree name');
+}