@kabmo-labs/kabmo 0.7.0 → 0.8.0

package/src/server/routes/fs/action-create.test.ts

@@ -6,12 +6,12 @@
 /**
  * The Files panel's "New file" branch.
  *
- * Two rules are load-bearing and neither is visible from the happy path: the
- * name may not carry a path separator (the folder is named by `path`, and a
- * separator would turn a name into an arbitrary write under the root), and an
- * existing file is REFUSED rather than truncated. The second one is the one a
- * naive `Bun.write` gets wrong: `Bun.write` creates or truncates, so a name
- * that collides with a real file would silently blank it.
+ * Two rules are load-bearing and neither is visible from the happy path. The
+ * name may carry SEGMENTS (that is the nested-path grammar, and its refusals
+ * live in `action-nested.test.ts`), and an existing file is REFUSED rather
+ * than truncated — the second is the one a naive `Bun.write` gets wrong:
+ * `Bun.write` creates or truncates, so a name that collides with a real file
+ * would silently blank it.
  */
 
 import { afterEach, describe, expect, test } from 'bun:test';
@@ -34,7 +34,10 @@ async function create(folderPath: string, name: string) {
   form.append('path', folderPath);
   form.append('name', name);
   const res = await action({ request: new Request('http://localhost/api/fs/action', { method: 'POST', body: form }) } as never);
-  return { status: res.status, body: (await res.json()) as { success?: boolean; path?: string; error?: string } };
+  return {
+    status: res.status,
+    body: (await res.json()) as { success?: boolean; kind?: string; path?: string; error?: string },
+  };
 }
 
 describe('fs create', () => {
@@ -43,7 +46,7 @@ describe('fs create', () => {
     const { status, body } = await create('tmp-create-probe', 'notes.md');
 
     expect(status).toBe(200);
-    expect(body).toEqual({ success: true, path: 'tmp-create-probe/notes.md' });
+    expect(body).toEqual({ success: true, kind: 'file', path: 'tmp-create-probe/notes.md' });
     expect(fs.readFileSync(path.join(DIR, 'notes.md'), 'utf8')).toBe('');
   });
 
@@ -67,12 +70,14 @@ describe('fs create', () => {
     expect(fs.readFileSync(path.join(DIR, 'keep.txt'), 'utf8')).toBe('important');
   });
 
-  test('refuses a name carrying a path separator', async () => {
+  test('a path separator is a NESTED path, and `..` is still refused', async () => {
     fs.mkdirSync(DIR, { recursive: true });
-    for (const name of ['../escape.txt', 'sub/escape.txt', 'sub\\escape.txt']) {
-      const { status } = await create('tmp-create-probe', name);
-      expect(status).toBe(400);
-    }
+    // A forward or back separator names a nested destination, which the dialog
+    // is for — the escape itself is the `..` segment, and that stays refused.
+    expect((await create('tmp-create-probe', 'sub/inside.txt')).status).toBe(200);
+    expect((await create('tmp-create-probe', 'sub\\also-inside.txt')).status).toBe(200);
+    expect((await create('tmp-create-probe', '../escape.txt')).status).toBe(400);
+    expect(fs.existsSync(path.join(DIR, 'sub/inside.txt'))).toBe(true);
     expect(fs.existsSync(path.join(process.cwd(), 'escape.txt'))).toBe(false);
   });
 

package/src/server/routes/fs/action-nested.test.ts

@@ -0,0 +1,184 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Nested paths at the route: a create and a rename that name SEGMENTS.
+ *
+ * The Files panel's dialogs used to accept one segment, so `lib/parse.ts` was
+ * unreachable from the UI — the user had to create `lib`, expand it, then the
+ * file. Both actions now take a relative path, and the rules that keep that
+ * inside the folder the user named are asserted here because they are the whole
+ * reason a nested path is safe:
+ *
+ * - a `..` SEGMENT is refused even when it would land back inside the root
+ *   (`a/../b.ts` resolves there), so the refusal is about the path the user
+ *   typed rather than about where it happened to land;
+ * - an ABSOLUTE path is refused, because `path.join(dir, abs)` discards the
+ *   folder the dialog showed;
+ * - a rename resolves against the LISTED root, not the workspace root — a
+ *   rename inside a nested repo used to resolve to a path outside the repo;
+ * - a rename never overwrites an existing destination, and never moves a folder
+ *   into its own subtree.
+ */
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import fs from 'node:fs';
+import path from 'node:path';
+import { action } from '@/server/routes/fs/action';
+
+/** Probes live in the repo root — the one directory the root allow-list always accepts. */
+const DIR = path.join(process.cwd(), 'tmp-nested-probe');
+
+function reset(files: Record<string, string> = {}): void {
+  fs.rmSync(DIR, { recursive: true, force: true });
+  fs.mkdirSync(DIR, { recursive: true });
+  for (const [rel, content] of Object.entries(files)) {
+    const target = path.join(DIR, rel);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content);
+  }
+}
+
+afterEach(() => {
+  fs.rmSync(DIR, { recursive: true, force: true });
+});
+
+async function post(fields: Record<string, string>) {
+  const form = new FormData();
+  form.append('root', process.cwd());
+  for (const [key, value] of Object.entries(fields)) form.append(key, value);
+  const res = await action({ request: new Request('http://localhost/api/fs/action', { method: 'POST', body: form }) } as never);
+  return { status: res.status, body: (await res.json()) as { success?: boolean; kind?: string; path?: string; previousPath?: string; error?: string } };
+}
+
+describe('fs create with a nested path', () => {
+  test('creates every directory that leads to the file', async () => {
+    reset();
+
+    const { status, body } = await post({ actionType: 'create', path: 'tmp-nested-probe', name: 'lib/deep/parse.ts' });
+
+    expect(status).toBe(200);
+    expect(body).toEqual({ success: true, kind: 'file', path: 'tmp-nested-probe/lib/deep/parse.ts' });
+    expect(fs.readFileSync(path.join(DIR, 'lib/deep/parse.ts'), 'utf8')).toBe('');
+  });
+
+  test('creates a FOLDER when asked, and reports the kind back', async () => {
+    reset();
+
+    const { status, body } = await post({ actionType: 'create', path: 'tmp-nested-probe', name: 'a/b', kind: 'folder' });
+
+    expect(status).toBe(200);
+    expect(body).toEqual({ success: true, kind: 'folder', path: 'tmp-nested-probe/a/b' });
+    expect(fs.statSync(path.join(DIR, 'a/b')).isDirectory()).toBe(true);
+  });
+
+  test('normalizes a backslash and repeated separators into one path', async () => {
+    reset();
+
+    const { body } = await post({ actionType: 'create', path: 'tmp-nested-probe', name: 'x\\\\y//z.ts' });
+
+    expect(body.path).toBe('tmp-nested-probe/x/y/z.ts');
+    expect(fs.existsSync(path.join(DIR, 'x/y/z.ts'))).toBe(true);
+  });
+
+  test('refuses a .. segment even when it would land inside the root', async () => {
+    reset({ 'keep/.gitkeep': '' });
+
+    // `keep/../escape.ts` resolves inside the probe directory, so a containment
+    // check alone would accept it — the refusal is about the path as typed.
+    const { status, body } = await post({ actionType: 'create', path: 'tmp-nested-probe', name: 'keep/../escape.ts' });
+
+    expect(status).toBe(400);
+    expect(body.error).toContain('..');
+    expect(fs.existsSync(path.join(DIR, 'escape.ts'))).toBe(false);
+  });
+
+  test('refuses an absolute path', async () => {
+    reset();
+
+    for (const name of ['/tmp/absolute.ts', 'C:/absolute.ts', 'C:relative.ts']) {
+      expect((await post({ actionType: 'create', path: 'tmp-nested-probe', name })).status).toBe(400);
+    }
+  });
+
+  test('refuses a nested path whose final entry already exists', async () => {
+    reset({ 'lib/parse.ts': 'keep me' });
+
+    const { status, body } = await post({ actionType: 'create', path: 'tmp-nested-probe', name: 'lib/parse.ts' });
+
+    expect(status).toBe(409);
+    expect(body.error).toContain('already exists');
+    expect(fs.readFileSync(path.join(DIR, 'lib/parse.ts'), 'utf8')).toBe('keep me');
+  });
+});
+
+describe('fs rename with a nested path', () => {
+  test('renames into a new nested folder, creating its parents', async () => {
+    reset({ 'a.ts': 'A' });
+
+    const { status, body } = await post({ actionType: 'rename', path: 'tmp-nested-probe/a.ts', newPath: 'tmp-nested-probe/lib/deep/a.ts' });
+
+    expect(status).toBe(200);
+    expect(body).toEqual({ success: true, path: 'tmp-nested-probe/lib/deep/a.ts', previousPath: 'tmp-nested-probe/a.ts' });
+    expect(fs.existsSync(path.join(DIR, 'a.ts'))).toBe(false);
+    expect(fs.readFileSync(path.join(DIR, 'lib/deep/a.ts'), 'utf8')).toBe('A');
+  });
+
+  test('a plain rename inside one folder keeps its siblings', async () => {
+    reset({ 'src/a.ts': 'A', 'src/b.ts': 'B' });
+
+    const { body } = await post({ actionType: 'rename', path: 'tmp-nested-probe/src/a.ts', newPath: 'tmp-nested-probe/src/c.ts' });
+
+    expect(body.path).toBe('tmp-nested-probe/src/c.ts');
+    expect(fs.existsSync(path.join(DIR, 'src/b.ts'))).toBe(true);
+  });
+
+  test('refuses an existing destination instead of clobbering it', async () => {
+    reset({ 'a.ts': 'A', 'b.ts': 'B' });
+
+    const { status, body } = await post({ actionType: 'rename', path: 'tmp-nested-probe/a.ts', newPath: 'tmp-nested-probe/b.ts' });
+
+    expect(status).toBe(409);
+    expect(body.error).toContain('already exists');
+    expect(fs.readFileSync(path.join(DIR, 'b.ts'), 'utf8')).toBe('B');
+  });
+
+  test('refuses moving a folder into its own subtree', async () => {
+    reset({ 'src/a.ts': 'A' });
+
+    const { status, body } = await post({ actionType: 'rename', path: 'tmp-nested-probe/src', newPath: 'tmp-nested-probe/src/deep' });
+
+    expect(status).toBe(400);
+    expect(body.error).toContain('inside itself');
+    expect(fs.existsSync(path.join(DIR, 'src/a.ts'))).toBe(true);
+  });
+
+  test('refuses a .. segment and an absolute destination', async () => {
+    reset({ 'a.ts': 'A' });
+
+    expect((await post({ actionType: 'rename', path: 'tmp-nested-probe/a.ts', newPath: 'tmp-nested-probe/../out.ts' })).status).toBe(400);
+    expect((await post({ actionType: 'rename', path: 'tmp-nested-probe/a.ts', newPath: '/tmp/out.ts' })).status).toBe(400);
+    expect(fs.existsSync(path.join(DIR, 'a.ts'))).toBe(true);
+  });
+
+  test('renaming to the same path is a no-op that still reports both ends', async () => {
+    reset({ 'a.ts': 'A' });
+
+    const { status, body } = await post({ actionType: 'rename', path: 'tmp-nested-probe/a.ts', newPath: 'tmp-nested-probe/a.ts' });
+
+    expect(status).toBe(200);
+    expect(body.path).toBe('tmp-nested-probe/a.ts');
+    expect(fs.readFileSync(path.join(DIR, 'a.ts'), 'utf8')).toBe('A');
+  });
+
+  test('a missing source is refused rather than creating an empty entry', async () => {
+    reset();
+
+    const { status } = await post({ actionType: 'rename', path: 'tmp-nested-probe/gone.ts', newPath: 'tmp-nested-probe/here.ts' });
+
+    expect(status).toBe(404);
+    expect(fs.existsSync(path.join(DIR, 'here.ts'))).toBe(false);
+  });
+});

package/src/server/routes/fs/action.ts

@@ -3,10 +3,11 @@ import { errorResponse } from '@/server/lib/route-adapter';
 import fs from 'fs';
 import path from 'path';
 import { isMockMode } from '@/server/mock.server';
-import { getDefaultFsRoot, resolveRoot, resolveWithinRoot } from '@/server/lib/fs/root';
+import { getDefaultFsRoot, isWithinRoot, resolveRoot, resolveWithinRoot } from '@/server/lib/fs/root';
 import { runShell } from '@/server/lib/fs/shell';
 import { revealInFileManager } from '@/server/lib/fs/reveal';
-import { duplicateEntry, nextDuplicateName, pasteEntry } from '@/server/lib/fs/transfer';
+import { duplicateEntry, nextDuplicateName, pasteEntry, toRelPath } from '@/server/lib/fs/transfer';
+import { normalizeRelativePath } from '@/server/lib/fs/relative-path';
 import { transferRefusal } from '@/shared/lib/fs/clipboard';
 import { toDiskText } from '@/shared/lib/code/line-endings';
 
@@ -104,13 +105,15 @@ export async function action({ request }: ActionFunctionArgs) {
       await Bun.write(fullPath, content);
       return json({ success: true });
     } else if (actionType === 'create') {
-      // The Files panel's "New file": an empty file beside the folder that was
-      // right-clicked. Only a NAME is accepted, never a path — a separator
-      // would let the panel write anywhere under the root, and the folder is
-      // already named by `path`.
-      const name = ((formData.get('name') as string) ?? '').trim();
-      if (!name || name === '.' || name === '..' || /[/\\\0]/.test(name)) {
-        return json({ error: 'Enter a file name without slashes' }, { status: 400 });
+      // The Files panel's "New file"/"New folder": an empty entry beside the
+      // folder that was right-clicked. The NAME may carry segments
+      // (`lib/parse.ts`), so one dialog creates a nested path and every
+      // intermediate directory with it — the grammar that keeps it inside the
+      // named folder lives in `normalizeRelativePath`, not in a slash test here.
+      const kind = formData.get('kind') === 'folder' ? 'folder' : 'file';
+      const name = normalizeRelativePath((formData.get('name') as string) ?? '');
+      if (!name) {
+        return json({ error: 'Enter a name without .. or a leading slash' }, { status: 400 });
       }
       const target = resolveWithinRoot(scopedRoot, path.join(filePath || '.', name));
       if (!target) {
@@ -122,21 +125,49 @@ export async function action({ request }: ActionFunctionArgs) {
       if ((await Bun.file(target).stat().catch(() => null)) !== null) {
         return json({ error: `${name} already exists` }, { status: 409 });
       }
-      await fs.promises.mkdir(path.dirname(target), { recursive: true });
-      await Bun.write(target, '');
+      if (kind === 'folder') await fs.promises.mkdir(target, { recursive: true });
+      else {
+        await fs.promises.mkdir(path.dirname(target), { recursive: true });
+        await Bun.write(target, '');
+      }
       // Relative to the LISTED root, which is the identity the tree renders by.
-      return json({ success: true, path: path.relative(scopedRoot, target).split(path.sep).join('/') });
+      return json({ success: true, kind, path: toRelPath(scopedRoot, target) });
     } else if (actionType === 'delete') {
       await fs.promises.rm(fullPath, { recursive: true, force: true });
       return json({ success: true });
     } else if (actionType === 'rename') {
-      const newPath = formData.get('newPath') as string;
-      const fullNewPath = path.resolve(rootDir, newPath);
-      if (fullNewPath !== rootDir && !fullNewPath.startsWith(rootDir + path.sep)) {
+      // `newPath` is relative to the LISTED root, exactly like `path` is. It
+      // used to be resolved against `rootDir`, so renaming inside a nested repo
+      // resolved to a path under the workspace root instead of the repo — a
+      // move out of the tree the row belongs to.
+      const newPath = normalizeRelativePath((formData.get('newPath') as string) ?? '');
+      if (!newPath) {
+        return json({ error: 'Enter a name without .. or a leading slash' }, { status: 400 });
+      }
+      const fullNewPath = resolveWithinRoot(scopedRoot, newPath);
+      if (!fullNewPath) {
         return json({ error: 'Invalid new path' }, { status: 403 });
       }
+      if (fullNewPath === fullPath) return json({ success: true, path: newPath, previousPath: filePath });
+      const source = await Bun.file(fullPath).stat().catch(() => null);
+      if (!source) return json({ error: 'That entry no longer exists' }, { status: 404 });
+      // A folder cannot be moved into itself: `rename(a, a/b)` fails with
+      // EINVAL on every platform, but with an errno the panel cannot explain —
+      // and the destination directory may not exist yet, so the check has to be
+      // on the PATHS rather than on the filesystem.
+      if (source.isDirectory() && isWithinRoot(fullPath, fullNewPath)) {
+        return json({ error: 'A folder cannot be moved inside itself' }, { status: 400 });
+      }
+      // `rename` clobbers silently, so an existing destination is refused: the
+      // entry the user meant to keep would otherwise disappear without a word.
+      if ((await Bun.file(fullNewPath).stat().catch(() => null)) !== null) {
+        return json({ error: `${newPath} already exists` }, { status: 409 });
+      }
+      // The destination's parents are created, which is what makes a rename
+      // INTO a new folder work — the same nested grammar the create accepts.
+      await fs.promises.mkdir(path.dirname(fullNewPath), { recursive: true });
       await fs.promises.rename(fullPath, fullNewPath);
-      return json({ success: true });
+      return json({ success: true, path: newPath, previousPath: filePath });
     } else if (actionType === 'open_explorer') {
       const isDir = (await Bun.file(fullPath).stat().catch(() => null))?.isDirectory() ?? false;
       // A file reveals its containing directory — there is no portable "select

package/src/server/routes/index.ts

@@ -12,6 +12,7 @@ import { waitingBindings } from '@/server/routes/waiting/bindings';
 import { settingsBindings } from '@/server/routes/settings';
 import { fsBindings } from '@/server/routes/fs';
 import { foldersBindings } from '@/server/routes/folders';
+import { worktreesBindings } from '@/server/routes/worktrees';
 import { filesBindings } from '@/server/routes/files';
 import { telemetryBindings } from '@/server/routes/telemetry';
 import { terminalBindings } from '@/server/routes/terminal';
@@ -42,6 +43,7 @@ const allBindings: HandlerBinding[] = [
   ...settingsBindings,
   ...fsBindings,
   ...foldersBindings,
+  ...worktreesBindings,
   ...filesBindings,
   ...telemetryBindings,
   ...terminalBindings,

package/src/server/routes/updates/desktop.ts

@@ -0,0 +1,37 @@
+import { json, NO_STORE_HEADERS } from '@/server/lib/remix-compat';
+import { fetchShellRelease, type ShellRelease } from '@/server/lib/updates/shell-release';
+import { isDesktopShellKind, type DesktopShellKind } from '@/shared/lib/updates/shell-ua';
+
+/**
+ * GET /api/updates/desktop?kind=macos|windows|linux — the newest desktop shell.
+ *
+ * ONE route with an explicit `kind`, unlike the mobile pair's two routes, and
+ * the difference is deliberate. `?kind` here is REQUIRED and refused when it is
+ * missing or names no desktop shell, so no absence can silently mean a platform:
+ * the mobile pair's split exists precisely because a defaulted parameter would
+ * have made "the newest shell" mean Android without anyone saying so.
+ *
+ * Only an INSTALLED desktop shell asks for this — the page reports its own
+ * version over the shell bridge (`__kabmoDesktop.shellVersion`), because a
+ * desktop app carries no User-Agent token. The `url` it answers with is the
+ * RELEASE PAGE rather than a file: every desktop artifact is per-architecture,
+ * and the server cannot know which architecture the window is running on.
+ *
+ * A failed probe is a valid answer (`url: null`), never a 500: the sidebar's job
+ * is to omit a button it cannot back with a link.
+ */
+export async function loader({ request }: { request: Request }) {
+  const kind = new URL(request.url).searchParams.get('kind');
+  if (!isDesktopShellKind(kind ?? '')) {
+    return json(
+      { error: 'kind must be one of macos, windows, linux' },
+      { status: 400, headers: NO_STORE_HEADERS },
+    );
+  }
+
+  const release: ShellRelease | null = await fetchShellRelease(kind as DesktopShellKind);
+  return json(
+    release ?? { url: null, latest: null, releaseUrl: null },
+    { headers: NO_STORE_HEADERS },
+  );
+}

package/src/server/routes/updates/index.ts

@@ -3,6 +3,7 @@ import * as updatesAndroid from '@/server/routes/updates/android';
 import * as updatesApply from '@/server/routes/updates/apply';
 import * as updatesChangelog from '@/server/routes/updates/changelog';
 import * as updatesCheck from '@/server/routes/updates/check';
+import * as updatesDesktop from '@/server/routes/updates/desktop';
 import * as updatesIos from '@/server/routes/updates/ios';
 
 export const updatesBindings: HandlerBinding[] = [
@@ -10,5 +11,6 @@ export const updatesBindings: HandlerBinding[] = [
   ...bindingsFor(updatesApply, '/api/updates/apply'),
   ...bindingsFor(updatesChangelog, '/api/updates/changelog'),
   ...bindingsFor(updatesCheck, '/api/updates/check'),
+  ...bindingsFor(updatesDesktop, '/api/updates/desktop'),
   ...bindingsFor(updatesIos, '/api/updates/ios'),
 ];

package/src/server/routes/worktrees/create.ts

@@ -0,0 +1,138 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * POST /api/worktrees — create a worktree, and POST /api/worktrees/validate —
+ * the same plan without touching disk.
+ *
+ * Both go through `planWorktree`, so the dialog cannot be told "fine" by a check
+ * that the create then contradicts: every refusal a create can raise is raised
+ * by the validate call first, with the same code and the same field.
+ *
+ * The body carries the DIALOG's state, never a resolved path: a client that
+ * could name the directory could name one outside the project.
+ */
+
+import { json } from '@/server/lib/remix-compat';
+import type { ActionFunctionArgs } from '@/server/lib/remix-compat';
+import { methodNotAllowed } from '@/server/lib/route-adapter';
+import { getDb } from '@/server/db.server';
+import { emitRealtimeSignal } from '@/server/lib/realtime/signals.server';
+import { getDataDir } from '@/server/lib/lifecycle/paths';
+import { putWorktreeRow, worktreeIdentityFor } from '@/server/lib/db/worktree-registry.server';
+import { asWorktreeFailure } from '@/server/lib/fs/worktree/errors';
+import { createWorktree, planWorktree } from '@/server/lib/fs/worktree/create';
+import { invalidateWorktreeTopology } from '@/server/lib/fs/worktree/topology';
+import { readWorktreeSettings } from '@/server/lib/fs/worktree/settings.server';
+import type { WorktreeValidation } from '@/shared/lib/workspace/worktree/types';
+import { isMock, mockRefusal, resolveWorktreeProject, worktreeFailureResponse } from '@/server/routes/worktrees/shared';
+
+interface CreateBody {
+  mode?: unknown;
+  branch?: unknown;
+  worktreeName?: unknown;
+  startRef?: unknown;
+  carryIgnored?: unknown;
+}
+
+function readBody(body: CreateBody) {
+  return {
+    mode: body.mode === 'existing' ? ('existing' as const) : ('new' as const),
+    branch: typeof body.branch === 'string' ? body.branch : '',
+    worktreeName: typeof body.worktreeName === 'string' ? body.worktreeName : '',
+    startRef: typeof body.startRef === 'string' ? body.startRef : undefined,
+    carryIgnored: typeof body.carryIgnored === 'boolean' ? body.carryIgnored : undefined,
+  };
+}
+
+export async function action({ request }: ActionFunctionArgs) {
+  if (request.method !== 'POST') return methodNotAllowed({ request, params: {} });
+  if (isMock()) return mockRefusal();
+
+  const url = new URL(request.url);
+  const resolved = await resolveWorktreeProject(url.searchParams.get('root'), url.searchParams.get('folderId'));
+  if (resolved.error) return resolved.error;
+  const projectPath = resolved.root as string;
+
+  const body = (await request.json().catch(() => ({}))) as CreateBody;
+  const parsed = readBody(body);
+  const settings = await readWorktreeSettings();
+  const db = await getDb();
+  const deps = {
+    identityFor: (candidate: string) => worktreeIdentityFor(db, candidate),
+    carryIgnored: settings.carryIgnored,
+    dataDir: getDataDir(),
+    configuredDirectory: settings.directory,
+    record: async (row: {
+      path: string;
+      primaryRoot: string;
+      projectId: string;
+      branch: string;
+      startRef: string;
+      createdAt: string;
+    }) => {
+      await putWorktreeRow(db, {
+        path: row.path,
+        primary_root: row.primaryRoot,
+        project_id: row.projectId,
+        branch: row.branch,
+        start_ref: row.startRef,
+        created_at: row.createdAt,
+      });
+    },
+  };
+
+  try {
+    const created = await createWorktree({ projectPath, ...parsed }, deps);
+    await invalidateWorktreeTopology(created.primaryRoot);
+    // The new folder is structure: every sidebar re-reads, and the panels that
+    // already point at this repository drop their cached topology.
+    emitRealtimeSignal('sidebar-structure');
+    emitRealtimeSignal('workspace-dirty');
+    return json({ worktree: created, carried: created.carried });
+  } catch (error) {
+    return worktreeFailureResponse(error);
+  }
+}
+
+/**
+ * The same plan, without creating anything. Answers every failure rather than
+ * the first, because a dialog that shows one error at a time makes the user
+ * discover the second one after fixing the first.
+ */
+export async function validateAction({ request }: ActionFunctionArgs) {
+  if (request.method !== 'POST') return methodNotAllowed({ request, params: {} });
+  if (isMock()) return mockRefusal();
+
+  const url = new URL(request.url);
+  const resolved = await resolveWorktreeProject(url.searchParams.get('root'), url.searchParams.get('folderId'));
+  if (resolved.error) return resolved.error;
+  const projectPath = resolved.root as string;
+
+  const body = (await request.json().catch(() => ({}))) as CreateBody;
+  const parsed = readBody(body);
+  const settings = await readWorktreeSettings();
+  const db = await getDb();
+
+  try {
+    const plan = await planWorktree(
+      { projectPath, ...parsed },
+      {
+        identityFor: (candidate: string) => worktreeIdentityFor(db, candidate),
+        dataDir: getDataDir(),
+        configuredDirectory: settings.directory,
+      },
+    );
+    const payload: WorktreeValidation = {
+      ok: true,
+      failures: [],
+      resolved: { name: plan.name, directory: plan.directory, branch: plan.branch },
+    };
+    return json(payload);
+  } catch (error) {
+    const payload: WorktreeValidation = { ok: false, failures: [asWorktreeFailure(error)] };
+    return json(payload, { status: 400 });
+  }
+}

package/src/server/routes/worktrees/index.ts

@@ -0,0 +1,25 @@
+import { bindingsFor, type HandlerBinding } from '@/server/lib/route-adapter';
+import * as worktreesList from '@/server/routes/worktrees/list';
+import { action as createAction, validateAction } from '@/server/routes/worktrees/create';
+import { action as removeAction } from '@/server/routes/worktrees/remove';
+
+/**
+ * `/api/worktrees` — list, create, validate, remove.
+ *
+ * Every binding is explicit rather than `actionBindings`, and that is the whole
+ * reason this file exists: `actionBindings` mounts all four mutating verbs AND a
+ * 405 GET fallback, and Elysia lets a later registration win — so mounting the
+ * create module that way would replace the list loader with a "method not
+ * allowed" response on the same path. (`sessions/index.ts` records the same trap
+ * for the batch-delete routes.)
+ *
+ * `validate` is a STATIC segment registered before the collection path.
+ * `DELETE` takes the worktree path in its BODY, not in the URL: a path contains
+ * separators, and a wildcard segment would also answer for `/validate`.
+ */
+export const worktreesBindings: HandlerBinding[] = [
+  ...bindingsFor(worktreesList, '/api/worktrees'),
+  { method: 'POST', path: '/api/worktrees/validate', handler: validateAction },
+  { method: 'POST', path: '/api/worktrees', handler: createAction },
+  { method: 'DELETE', path: '/api/worktrees', handler: removeAction },
+];