@cloudcli-ai/cloudcli 1.37.2 → 1.37.4

package/server/modules/database/tests/user-preferences.db.integration.test.ts

@@ -0,0 +1,135 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import {
+  closeConnection,
+  getConnection,
+  initializeDatabase,
+  sessionDraftsDb,
+  userPreferencesDb,
+} from '@/modules/database/index.js';
+
+const USER_ID = 1;
+
+async function withDatabase(runTest: () => void | Promise<void>): Promise<void> {
+  const previousDatabasePath = process.env.DATABASE_PATH;
+  const tempDirectory = await mkdtemp(path.join(os.tmpdir(), 'user-prefs-db-'));
+  const databasePath = path.join(tempDirectory, 'auth.db');
+
+  closeConnection();
+  process.env.DATABASE_PATH = databasePath;
+  await writeFile(databasePath, '');
+  await initializeDatabase();
+
+  // Both tables cascade from users(id), so a row has to exist to write against.
+  getConnection()
+    .prepare('INSERT INTO users (id, username, password_hash) VALUES (?, ?, ?)')
+    .run(USER_ID, 'tester', 'hash');
+
+  try {
+    await runTest();
+  } finally {
+    closeConnection();
+    if (previousDatabasePath === undefined) {
+      delete process.env.DATABASE_PATH;
+    } else {
+      process.env.DATABASE_PATH = previousDatabasePath;
+    }
+    await rm(tempDirectory, { recursive: true, force: true });
+  }
+}
+
+test('preferences round-trip every JSON shape a setting can take', async () => {
+  await withDatabase(() => {
+    userPreferencesDb.savePreferences(USER_ID, {
+      theme: 'dark',
+      tasksEnabled: false,
+      claudePermissions: { allowedTools: ['Read'], skipPermissions: true },
+    });
+
+    assert.deepEqual(userPreferencesDb.getPreferences(USER_ID), {
+      theme: 'dark',
+      tasksEnabled: false,
+      claudePermissions: { allowedTools: ['Read'], skipPermissions: true },
+    });
+  });
+});
+
+test('saving preferences merge-patches instead of replacing the whole set', async () => {
+  await withDatabase(() => {
+    userPreferencesDb.savePreferences(USER_ID, { theme: 'dark', userLanguage: 'de' });
+    userPreferencesDb.savePreferences(USER_ID, { theme: 'light' });
+
+    assert.deepEqual(userPreferencesDb.getPreferences(USER_ID), {
+      theme: 'light',
+      userLanguage: 'de',
+    });
+  });
+});
+
+test('a preference set to undefined is removed', async () => {
+  await withDatabase(() => {
+    userPreferencesDb.savePreferences(USER_ID, { theme: 'dark', userLanguage: 'de' });
+    userPreferencesDb.savePreferences(USER_ID, { userLanguage: undefined });
+
+    assert.deepEqual(userPreferencesDb.getPreferences(USER_ID), { theme: 'dark' });
+  });
+});
+
+test('one unreadable preference value does not cost the user the others', async () => {
+  await withDatabase(() => {
+    userPreferencesDb.savePreferences(USER_ID, { theme: 'dark' });
+    getConnection()
+      .prepare(
+        `INSERT INTO user_preferences (user_id, preference_key, preference_value)
+         VALUES (?, ?, ?)`
+      )
+      .run(USER_ID, 'broken', 'not json');
+
+    assert.deepEqual(userPreferencesDb.getPreferences(USER_ID), { theme: 'dark' });
+  });
+});
+
+test('drafts round-trip text and queued message per scope', async () => {
+  await withDatabase(() => {
+    sessionDraftsDb.saveDraft(USER_ID, 'session-a', { text: 'half typed', queuedMessage: null });
+    sessionDraftsDb.saveDraft(USER_ID, 'project:p1', {
+      text: '',
+      queuedMessage: { content: 'run it' },
+    });
+
+    const drafts = sessionDraftsDb.getDrafts(USER_ID);
+    const byScope = new Map(drafts.map((draft) => [draft.scope, draft]));
+
+    assert.equal(byScope.get('session-a')?.text, 'half typed');
+    assert.equal(byScope.get('session-a')?.queuedMessage, null);
+    assert.equal(byScope.get('project:p1')?.text, '');
+    assert.deepEqual(byScope.get('project:p1')?.queuedMessage, { content: 'run it' });
+  });
+});
+
+test('saving an empty draft deletes the row rather than keeping a blank one', async () => {
+  await withDatabase(() => {
+    sessionDraftsDb.saveDraft(USER_ID, 'session-a', { text: 'typed', queuedMessage: null });
+    sessionDraftsDb.saveDraft(USER_ID, 'session-a', { text: '', queuedMessage: null });
+
+    assert.deepEqual(sessionDraftsDb.getDrafts(USER_ID), []);
+  });
+});
+
+test('deleteDraft removes only the named scope', async () => {
+  await withDatabase(() => {
+    sessionDraftsDb.saveDraft(USER_ID, 'session-a', { text: 'a', queuedMessage: null });
+    sessionDraftsDb.saveDraft(USER_ID, 'session-b', { text: 'b', queuedMessage: null });
+
+    sessionDraftsDb.deleteDraft(USER_ID, 'session-a');
+
+    assert.deepEqual(
+      sessionDraftsDb.getDrafts(USER_ID).map((draft) => draft.scope),
+      ['session-b'],
+    );
+  });
+});

package/server/modules/file-tree/file-tree.module.ts

@@ -14,7 +14,7 @@ import type {
   FileTreeProjectGateway,
   FileTreeWorkspaceGateway,
 } from '@/shared/types.js';
-import { WORKSPACES_ROOT, validateWorkspacePath } from '@/shared/utils.js';
+import { WORKSPACES_ROOT, resolveReadOnlyRootPath, validateWorkspacePath } from '@/shared/utils.js';
 
 const MAXIMUM_UPLOAD_SIZE_MEGABYTES = 200;
 const MAXIMUM_UPLOAD_SIZE_BYTES = MAXIMUM_UPLOAD_SIZE_MEGABYTES * 1024 * 1024;
@@ -73,6 +73,7 @@ const fileTreeProjects: FileTreeProjectGateway = {
 const fileTreeWorkspace: FileTreeWorkspaceGateway = {
   rootPath: WORKSPACES_ROOT,
   validatePath: (candidatePath) => validateWorkspacePath(candidatePath),
+  resolveReadOnlyRootPath: (candidatePath) => resolveReadOnlyRootPath(candidatePath),
 };
 
 const fileTreeLogger: FileTreeLogger = {

package/server/modules/file-tree/file-tree.service.ts

@@ -312,6 +312,51 @@ export function createFileTreeService(dependencies: FileTreeServiceDependencies)
     });
   }
 
+  /**
+   * Resolves a directory the browser may list.
+   *
+   * The read-only roots (the system temp directory and the Claude projects
+   * directory, see `READ_ONLY_ROOTS` in shared/utils) are browsable but never
+   * writable, so they are checked before the workspace policy rejects them.
+   * `createWorkspaceFolder` deliberately does not do this, which is what keeps
+   * them read-only.
+   */
+  async function resolveBrowsablePath(targetPath: string): Promise<string> {
+    const readOnlyPath = await dependencies.workspace.resolveReadOnlyRootPath(targetPath);
+    if (readOnlyPath) {
+      return readOnlyPath;
+    }
+
+    const validation = await dependencies.workspace.validatePath(targetPath);
+    if (!validation.valid) {
+      throw createFileTreeError(validation.error ?? 'Path is outside the workspace root', 403, 'INVALID_WORKSPACE_PATH');
+    }
+
+    return validation.resolvedPath || targetPath;
+  }
+
+  /**
+   * Resolves a path the viewer is allowed to read.
+   *
+   * A file reference in a transcript is normally inside the project, but a
+   * background command's log lives in the system temp directory and a
+   * background agent's output file is a link from there into the Claude
+   * projects directory, and the transcript quotes those paths verbatim. Those
+   * resolve through the read-only root policy instead of the project root; the
+   * writing endpoints keep using `resolvePathInsideProject` alone, so nothing
+   * outside the project can be changed.
+   */
+  async function resolveReadablePath(projectRoot: string, targetPath: string): Promise<string> {
+    if (path.isAbsolute(targetPath)) {
+      const readOnlyPath = await dependencies.workspace.resolveReadOnlyRootPath(targetPath);
+      if (readOnlyPath) {
+        return readOnlyPath;
+      }
+    }
+
+    return resolvePathInsideProject(projectRoot, targetPath);
+  }
+
   async function cleanupTemporaryFiles(files: FileTreeUploadedFile[]): Promise<void> {
     await Promise.all(files.map(async (file) => {
       try {
@@ -328,12 +373,8 @@ export function createFileTreeService(dependencies: FileTreeServiceDependencies)
         ? expandWorkspacePath(dependencies.workspace.rootPath, inputPath)
         : dependencies.workspace.rootPath;
       const targetPath = path.resolve(requestedPath);
-      const validation = await dependencies.workspace.validatePath(targetPath);
-      if (!validation.valid) {
-        throw createFileTreeError(validation.error ?? 'Path is outside the workspace root', 403, 'INVALID_WORKSPACE_PATH');
-      }
+      const resolvedPath = await resolveBrowsablePath(targetPath);
 
-      const resolvedPath = validation.resolvedPath || targetPath;
       try {
         await fileSystem.access(resolvedPath);
         const stats = await fileSystem.stat(resolvedPath);
@@ -409,7 +450,7 @@ export function createFileTreeService(dependencies: FileTreeServiceDependencies)
 
     async readTextFile(projectId, filePath) {
       const projectRoot = await resolveProjectRoot(projectId);
-      const resolvedPath = resolvePathInsideProject(projectRoot, filePath);
+      const resolvedPath = await resolveReadablePath(projectRoot, filePath);
       try {
         const content = await fileSystem.readTextFile(resolvedPath);
         return { content, path: resolvedPath };
@@ -417,13 +458,14 @@ export function createFileTreeService(dependencies: FileTreeServiceDependencies)
         mapFileSystemError(error, {
           ENOENT: { message: 'File not found', statusCode: 404 },
           EACCES: { message: 'Permission denied', statusCode: 403 },
+          EISDIR: { message: 'Path is a directory, not a file', statusCode: 400 },
         });
       }
     },
 
     async openFile(projectId, filePath) {
       const projectRoot = await resolveProjectRoot(projectId);
-      const resolvedPath = resolvePathInsideProject(projectRoot, filePath);
+      const resolvedPath = await resolveReadablePath(projectRoot, filePath);
       try {
         await fileSystem.access(resolvedPath);
       } catch {

package/server/modules/file-tree/tests/file-tree.service.test.ts

@@ -1,16 +1,23 @@
 import assert from 'node:assert/strict';
+import { createReadStream } from 'node:fs';
+import fsPromises from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
 import { Readable } from 'node:stream';
 import test from 'node:test';
+import { fileURLToPath } from 'node:url';
 
 import { createFileTreeService } from '@/modules/file-tree/file-tree.service.js';
 import type {
   FileTreeDirectoryEntry,
   FileTreeFileSystem,
   FileTreeServiceDependencies,
+  FileTreeServices,
   FileTreeStats,
 } from '@/shared/types.js';
-import { AppError } from '@/shared/utils.js';
+import { AppError, resolveReadOnlyRootPath, validateWorkspacePath } from '@/shared/utils.js';
+
+const testDirectory = path.dirname(fileURLToPath(import.meta.url));
 
 function createDirectoryEntry(name: string, directory: boolean): FileTreeDirectoryEntry {
   return {
@@ -80,6 +87,7 @@ function createDependencies(
     workspace: {
       rootPath: projectRoot,
       validatePath: async (candidatePath) => ({ valid: true, resolvedPath: candidatePath }),
+      resolveReadOnlyRootPath: async () => null,
     },
     resolveMimeType: () => 'text/plain',
     fileSystemConcurrency: 4,
@@ -343,6 +351,26 @@ test('readTextFile rejects traversal before invoking the filesystem adapter', as
   assert.deepEqual(readPaths, []);
 });
 
+test('readTextFile reports a directory as a client error, not a 500', async () => {
+  const projectRoot = path.resolve('file-tree-test-project');
+  const fileSystem = createFakeFileSystem({
+    readTextFile: async () => {
+      const error = new Error('EISDIR: illegal operation on a directory, read');
+      (error as NodeJS.ErrnoException).code = 'EISDIR';
+      throw error;
+    },
+  });
+  const service = createFileTreeService(createDependencies(fileSystem, projectRoot));
+
+  await assert.rejects(
+    service.readTextFile('project-1', 'decisions'),
+    (error: unknown) => error instanceof AppError
+      && error.code === 'EISDIR'
+      && error.statusCode === 400
+      && error.message === 'Path is a directory, not a file',
+  );
+});
+
 test('createEntry performs filesystem mutation only through the injected adapter', async () => {
   const projectRoot = path.resolve('file-tree-test-project');
   const targetPath = path.join(projectRoot, 'notes.txt');
@@ -369,3 +397,137 @@ test('createEntry performs filesystem mutation only through the injected adapter
   assert.equal(result.path, targetPath);
   assert.deepEqual(writtenFiles, [{ filePath: targetPath, content: '' }]);
 });
+
+/**
+ * Builds the service against the real filesystem and the real workspace policy,
+ * which is the only way to exercise the read-only roots: the whole guarantee
+ * rests on `realpath` resolving symlinks before the comparison.
+ */
+function createRealFileSystemService(projectRoot: string): FileTreeServices {
+  return createFileTreeService({
+    fileSystem: {
+      access: (candidatePath) => fsPromises.access(candidatePath),
+      stat: (candidatePath) => fsPromises.stat(candidatePath),
+      lstat: (candidatePath) => fsPromises.lstat(candidatePath),
+      openDirectory: async function* (directoryPath) {
+        yield* await fsPromises.opendir(directoryPath);
+      },
+      realpath: (candidatePath) => fsPromises.realpath(candidatePath),
+      readTextFile: (filePath) => fsPromises.readFile(filePath, 'utf8'),
+      writeTextFile: (filePath, content) => fsPromises.writeFile(filePath, content, 'utf8'),
+      async makeDirectory(directoryPath, recursive) {
+        await fsPromises.mkdir(directoryPath, { recursive });
+      },
+      rename: (oldPath, newPath) => fsPromises.rename(oldPath, newPath),
+      async removeDirectory(directoryPath) {
+        await fsPromises.rm(directoryPath, { recursive: true, force: true });
+      },
+      unlink: (filePath) => fsPromises.unlink(filePath),
+      copyFile: (source, destination) => fsPromises.copyFile(source, destination),
+      createReadStream: (filePath) => createReadStream(filePath),
+    },
+    projects: { getProjectPathById: async () => projectRoot },
+    workspace: {
+      rootPath: projectRoot,
+      validatePath: (candidatePath) => validateWorkspacePath(candidatePath),
+      resolveReadOnlyRootPath: (candidatePath) => resolveReadOnlyRootPath(candidatePath),
+    },
+    resolveMimeType: () => 'text/plain',
+    fileSystemConcurrency: 4,
+    logger: { error: () => undefined },
+  });
+}
+
+test('the temp directory can be browsed and read, but never written to', async () => {
+  const temporaryDirectory = await fsPromises.mkdtemp(path.join(os.tmpdir(), 'file-tree-tmp-'));
+  const projectRoot = await fsPromises.mkdtemp(path.join(os.tmpdir(), 'file-tree-project-'));
+
+  try {
+    // The shape a task notification quotes: an agent's output file written to
+    // the system temp directory, outside every project.
+    await fsPromises.mkdir(path.join(temporaryDirectory, 'tasks'));
+    const outputPath = path.join(temporaryDirectory, 'tasks', 'agent.output');
+    await fsPromises.writeFile(outputPath, 'what the agent found', 'utf8');
+
+    const service = createRealFileSystemService(projectRoot);
+
+    const browsed = await service.browseWorkspace(temporaryDirectory);
+    assert.deepEqual(browsed.suggestions.map((entry) => entry.name), ['tasks']);
+
+    const opened = await service.readTextFile('project-1', outputPath);
+    assert.equal(opened.content, 'what the agent found');
+
+    const streamed = await service.openFile('project-1', outputPath);
+    streamed.stream.destroy();
+
+    // Read-only means read-only: nothing may be created or changed there.
+    await assert.rejects(
+      service.saveTextFile('project-1', outputPath, 'overwritten'),
+      (error: unknown) => (error as AppError).code === 'PATH_OUTSIDE_PROJECT',
+    );
+    await assert.rejects(
+      service.createWorkspaceFolder(path.join(temporaryDirectory, 'new-folder')),
+      (error: unknown) => (error as AppError).code === 'INVALID_WORKSPACE_PATH',
+    );
+    await assert.rejects(
+      service.createEntry({
+        projectId: 'project-1',
+        parentPath: path.join(temporaryDirectory, 'tasks'),
+        type: 'file',
+        name: 'planted.txt',
+      }),
+      (error: unknown) => (error as AppError).code === 'PATH_OUTSIDE_PROJECT',
+    );
+    await assert.rejects(
+      service.renameEntry({ projectId: 'project-1', oldPath: outputPath, newName: 'renamed.output' }),
+      (error: unknown) => (error as AppError).code === 'PATH_OUTSIDE_PROJECT',
+    );
+    const uploadedTemporaryPath = path.join(projectRoot, 'upload.tmp');
+    await fsPromises.writeFile(uploadedTemporaryPath, 'upload', 'utf8');
+    await assert.rejects(
+      service.storeUploadedFiles({
+        projectId: 'project-1',
+        targetPath: path.join(temporaryDirectory, 'tasks'),
+        relativePaths: [],
+        requestedFileCount: 1,
+        files: [{ originalName: 'upload.txt', temporaryPath: uploadedTemporaryPath, size: 6, mimeType: 'text/plain' }],
+      }),
+      (error: unknown) => (error as AppError).code === 'PATH_OUTSIDE_PROJECT',
+    );
+    await assert.rejects(
+      service.deleteEntry({ projectId: 'project-1', targetPath: outputPath }),
+      (error: unknown) => (error as AppError).code === 'PATH_OUTSIDE_PROJECT',
+    );
+    assert.deepEqual(await fsPromises.readdir(path.join(temporaryDirectory, 'tasks')), ['agent.output']);
+    assert.equal(await fsPromises.readFile(outputPath, 'utf8'), 'what the agent found');
+  } finally {
+    await fsPromises.rm(temporaryDirectory, { recursive: true, force: true });
+    await fsPromises.rm(projectRoot, { recursive: true, force: true });
+  }
+});
+
+test('reading through a symlink out of the temp directory is still refused', async () => {
+  const temporaryDirectory = await fsPromises.mkdtemp(path.join(os.tmpdir(), 'file-tree-tmp-'));
+  const projectRoot = await fsPromises.mkdtemp(path.join(os.tmpdir(), 'file-tree-project-'));
+  // The link target has to sit under no read-only root. Beside this file is
+  // deterministic; a directory under `$HOME` lands under `/tmp` whenever a
+  // test run isolates its home there, and the Claude projects directory is a
+  // read-only root too.
+  const outsideDirectory = await fsPromises.mkdtemp(path.join(testDirectory, 'file-tree-outside-'));
+
+  try {
+    assert.equal(await resolveReadOnlyRootPath(outsideDirectory), null);
+    await fsPromises.writeFile(path.join(outsideDirectory, 'secret.txt'), 'secret', 'utf8');
+    await fsPromises.symlink(outsideDirectory, path.join(temporaryDirectory, 'escape'));
+
+    const service = createRealFileSystemService(projectRoot);
+    await assert.rejects(
+      service.readTextFile('project-1', path.join(temporaryDirectory, 'escape', 'secret.txt')),
+      (error: unknown) => (error as AppError).code === 'PATH_OUTSIDE_PROJECT',
+    );
+  } finally {
+    await fsPromises.rm(temporaryDirectory, { recursive: true, force: true });
+    await fsPromises.rm(projectRoot, { recursive: true, force: true });
+    await fsPromises.rm(outsideDirectory, { recursive: true, force: true });
+  }
+});

package/server/modules/git/git-branch-diff.service.ts

@@ -0,0 +1,204 @@
+import path from 'node:path';
+
+import type { GitProcessRunner } from '@/shared/types.js';
+import { AppError, getGitErrorDetails } from '@/shared/utils.js';
+
+// Single-letter status the Compare tab renders as a badge. Git's own
+// `--name-status` letters are folded into this set (see `toBranchDiffStatus`).
+type BranchDiffFileStatus = 'M' | 'A' | 'D' | 'R' | 'U';
+
+type BranchDiffFile = {
+  path: string;
+  /** Pre-rename path, only present for `R` entries. */
+  oldPath?: string;
+  status: BranchDiffFileStatus;
+};
+
+type BranchDiffInput = {
+  /** Repository root — every reported path is relative to it. */
+  projectPath: string;
+  /** Branch or remote-tracking ref the working copy is compared against. */
+  base: string;
+  runCommand: GitProcessRunner;
+};
+
+type BranchDiffFileInput = BranchDiffInput & {
+  /** Repository-relative path of the file to diff. */
+  file: string;
+  /**
+   * Pre-rename path for `R` entries. Diffing only the new path would make git
+   * report the whole file as added, so both paths are handed to git together
+   * and it pairs them into a rename with just the real content changes.
+   */
+  oldPath?: string;
+  /** Reads an untracked file so its content can be rendered as an all-additions diff. */
+  readFile: (absolutePath: string) => Promise<string>;
+};
+
+function toBranchDiffStatus(rawStatus: string): BranchDiffFileStatus {
+  // `--name-status` emits R<score>/C<score> for renames and copies; a copy is
+  // a brand-new file from the reader's point of view, and type changes (T) are
+  // modifications.
+  switch (rawStatus.charAt(0)) {
+    case 'A':
+    case 'C':
+      return 'A';
+    case 'D':
+      return 'D';
+    case 'R':
+      return 'R';
+    default:
+      return 'M';
+  }
+}
+
+function parseNameStatus(output: string): BranchDiffFile[] {
+  // `-z` output is `<status>\0<path>\0`, with renames/copies contributing a
+  // second path: `R100\0<old>\0<new>\0`. A trailing NUL leaves an empty token.
+  const tokens = output.split('\0');
+  const files: BranchDiffFile[] = [];
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const rawStatus = tokens[index];
+    if (!rawStatus) {
+      continue;
+    }
+
+    const status = toBranchDiffStatus(rawStatus);
+    const isTwoPathEntry = rawStatus.startsWith('R') || rawStatus.startsWith('C');
+    const firstPath = tokens[index + 1];
+    const secondPath = isTwoPathEntry ? tokens[index + 2] : undefined;
+    index += isTwoPathEntry ? 2 : 1;
+
+    if (!firstPath) {
+      continue;
+    }
+
+    if (isTwoPathEntry) {
+      if (!secondPath) {
+        continue;
+      }
+      files.push(status === 'R' ? { path: secondPath, oldPath: firstPath, status } : { path: secondPath, status });
+      continue;
+    }
+
+    files.push({ path: firstPath, status });
+  }
+
+  return files;
+}
+
+function parseUntrackedPaths(output: string): string[] {
+  return output.split('\0').filter(Boolean);
+}
+
+/**
+ * Turns a user-chosen base branch into the merge-base commit shared with HEAD.
+ * Rejects refs that would parse as git options and refs git cannot resolve
+ * before running `merge-base`, so the routes answer with a 400 and a stable
+ * code instead of a raw git failure.
+ */
+async function resolveMergeBase(input: BranchDiffInput): Promise<string> {
+  const { projectPath, base, runCommand } = input;
+  const cwd = { cwd: projectPath };
+
+  // validateBranchName in the routes accepts a leading '-', which git would
+  // otherwise read as an option (e.g. `--output=file`).
+  if (!base || base.startsWith('-')) {
+    throw new AppError(`Invalid base branch "${base}"`, {
+      code: 'GIT_INVALID_BASE_REF',
+      statusCode: 400,
+    });
+  }
+
+  try {
+    await runCommand('git', ['rev-parse', '--verify', '--quiet', '--end-of-options', `${base}^{commit}`], cwd);
+  } catch {
+    throw new AppError(`Unknown branch or ref "${base}"`, {
+      code: 'GIT_UNKNOWN_BASE_REF',
+      statusCode: 400,
+    });
+  }
+
+  let mergeBaseOutput: string;
+  try {
+    ({ stdout: mergeBaseOutput } = await runCommand('git', ['merge-base', '--', base, 'HEAD'], cwd));
+  } catch (error) {
+    throw new AppError(`"${base}" and the current branch share no common history`, {
+      code: 'GIT_NO_MERGE_BASE',
+      statusCode: 400,
+      details: getGitErrorDetails(error),
+    });
+  }
+
+  const mergeBase = mergeBaseOutput.trim();
+  if (!mergeBase) {
+    throw new AppError(`"${base}" and the current branch share no common history`, {
+      code: 'GIT_NO_MERGE_BASE',
+      statusCode: 400,
+    });
+  }
+
+  return mergeBase;
+}
+
+/**
+ * Used by the Git routes module for `GET /branch-diff`: lists every file the
+ * working copy (committed, staged, unstaged and untracked) differs in from the
+ * merge base of `base` and HEAD — the PR-style "what this branch changed".
+ * Results are sorted by path.
+ */
+export async function listBranchDiffFiles(input: BranchDiffInput): Promise<{
+  base: string;
+  mergeBase: string;
+  files: BranchDiffFile[];
+}> {
+  const { projectPath, base, runCommand } = input;
+  const cwd = { cwd: projectPath };
+  const mergeBase = await resolveMergeBase(input);
+
+  // `git diff <commit>` compares the working tree (index + unstaged edits)
+  // against the commit, which is exactly the "everything so far" view.
+  const [{ stdout: nameStatusOutput }, { stdout: untrackedOutput }] = await Promise.all([
+    runCommand('git', ['diff', '--name-status', '-M', '-z', mergeBase, '--'], cwd),
+    runCommand('git', ['ls-files', '--others', '--exclude-standard', '-z'], cwd),
+  ]);
+
+  const files = [
+    ...parseNameStatus(nameStatusOutput),
+    ...parseUntrackedPaths(untrackedOutput).map((path): BranchDiffFile => ({ path, status: 'U' })),
+  ].sort((left, right) => left.path.localeCompare(right.path));
+
+  return { base, mergeBase, files };
+}
+
+/**
+ * Used by the Git routes module for `GET /branch-diff/file`: the raw unified
+ * diff of one file between the merge base and the working copy. Untracked
+ * files are not visible to `git diff`, so their content is synthesized into
+ * the same all-additions shape the `/diff` route produces.
+ */
+export async function getBranchDiffForFile(input: BranchDiffFileInput): Promise<string> {
+  const { projectPath, file, oldPath, runCommand, readFile } = input;
+  const cwd = { cwd: projectPath };
+  const mergeBase = await resolveMergeBase(input);
+
+  // Ask git (not the filesystem) whether the path is untracked so a path that
+  // escapes the repository is rejected by git before anything is read.
+  const { stdout: untrackedOutput } = await runCommand(
+    'git',
+    ['ls-files', '--others', '--exclude-standard', '-z', '--', file],
+    cwd,
+  );
+  const isUntracked = parseUntrackedPaths(untrackedOutput).includes(file);
+
+  if (isUntracked) {
+    const content = await readFile(path.join(projectPath, file));
+    const lines = content.split('\n');
+    return `--- /dev/null\n+++ b/${file}\n@@ -0,0 +1,${lines.length} @@\n${lines.map((line) => `+${line}`).join('\n')}`;
+  }
+
+  const pathspecs = oldPath && oldPath !== file ? [oldPath, file] : [file];
+  const { stdout: diff } = await runCommand('git', ['diff', '-M', mergeBase, '--', ...pathspecs], cwd);
+  return diff;
+}

package/server/modules/git/git-branch.service.ts

@@ -1,21 +1,11 @@
+import type { GitProcessRunner } from '@/shared/types.js';
 import { AppError } from '@/shared/utils.js';
 
-type GitCommandResult = {
-  stdout: string;
-  stderr: string;
-};
-
-type GitCommandRunner = (
-  command: string,
-  args: string[],
-  options: { cwd: string },
-) => Promise<GitCommandResult>;
-
 type DeleteLocalBranchInput = {
   projectPath: string;
   branch: string;
   force: boolean;
-  runCommand: GitCommandRunner;
+  runCommand: GitProcessRunner;
 };
 
 /** Used by the Git routes module to safely delete a non-current local branch. */