@cloudcli-ai/cloudcli 1.36.3 → 1.37.1

package/server/modules/websocket/tests/websocket-heartbeat.service.test.ts

@@ -0,0 +1,78 @@
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import test from 'node:test';
+
+import { WebSocket } from 'ws';
+
+import { attachWebSocketHeartbeat } from '@/modules/websocket/services/websocket-server.service.js';
+
+function createFakeSocket() {
+  const socket = new EventEmitter() as EventEmitter & {
+    readyState: number;
+    pingCount: number;
+    terminateCount: number;
+    ping: () => void;
+    terminate: () => void;
+  };
+  socket.readyState = WebSocket.OPEN;
+  socket.pingCount = 0;
+  socket.terminateCount = 0;
+  socket.ping = () => {
+    socket.pingCount += 1;
+  };
+  socket.terminate = () => {
+    socket.terminateCount += 1;
+  };
+  return socket;
+}
+
+function createScheduler() {
+  let callback: (() => void) | null = null;
+  let wasCleared = false;
+
+  return {
+    setInterval(nextCallback: () => void) {
+      callback = nextCallback;
+      return 1 as unknown as NodeJS.Timeout;
+    },
+    clearInterval() {
+      wasCleared = true;
+    },
+    tick() {
+      callback?.();
+    },
+    cleared() {
+      return wasCleared;
+    },
+  };
+}
+
+test('heartbeat terminates an open socket that does not answer its ping', () => {
+  const socket = createFakeSocket();
+  const scheduler = createScheduler();
+  attachWebSocketHeartbeat(socket as never, 30_000, scheduler);
+
+  scheduler.tick();
+  assert.equal(socket.pingCount, 1);
+  assert.equal(socket.terminateCount, 0);
+
+  scheduler.tick();
+  assert.equal(socket.terminateCount, 1);
+  assert.equal(scheduler.cleared(), true);
+});
+
+test('heartbeat keeps responsive sockets open and stops after close', () => {
+  const socket = createFakeSocket();
+  const scheduler = createScheduler();
+  attachWebSocketHeartbeat(socket as never, 30_000, scheduler);
+
+  scheduler.tick();
+  socket.emit('pong');
+  scheduler.tick();
+
+  assert.equal(socket.pingCount, 2);
+  assert.equal(socket.terminateCount, 0);
+
+  socket.emit('close');
+  assert.equal(scheduler.cleared(), true);
+});

package/server/modules/worktrees/index.ts

@@ -0,0 +1,2 @@
+// worktreesRoutes: used by the server entrypoint to mount the complete Worktrees HTTP API at `/api/worktrees`.
+export { worktreesRoutes } from './worktrees.module.js';

package/server/modules/worktrees/services/worktree-create-and-open.service.ts

@@ -0,0 +1,53 @@
+import type {
+  CreateAndOpenWorktreeResult,
+  CreateWorktreeInput,
+  CreateWorktreeResult,
+  OpenWorktreeInput,
+  RemoveWorktreeInput,
+  RemoveWorktreeResult,
+  WorktreeProjectView,
+} from '@/shared/types.js';
+import { AppError } from '@/shared/utils.js';
+
+/**
+ * Creates a Git worktree and registers it as a project for the Worktrees module.
+ * Registration failure is compensated by removing only state created here.
+ */
+export async function createAndOpenWorktree(
+  input: CreateWorktreeInput,
+  dependencies: {
+    createWorktree: (input: CreateWorktreeInput) => Promise<CreateWorktreeResult>;
+    openWorktree: (input: OpenWorktreeInput) => Promise<WorktreeProjectView>;
+    removeWorktree: (input: RemoveWorktreeInput) => Promise<RemoveWorktreeResult>;
+  },
+): Promise<CreateAndOpenWorktreeResult> {
+  const created = await dependencies.createWorktree(input);
+
+  try {
+    const project = await dependencies.openWorktree({
+      projectPath: input.projectPath,
+      worktreePath: created.worktreePath,
+    });
+    return { ...created, project };
+  } catch (openError) {
+    try {
+      await dependencies.removeWorktree({
+        projectPath: input.projectPath,
+        worktreePath: created.worktreePath,
+        force: true,
+        deleteBranch: created.createdBranch,
+      });
+    } catch (cleanupError) {
+      throw new AppError('Worktree registration failed and its Git changes could not be rolled back', {
+        code: 'WORKTREE_CREATE_ROLLBACK_FAILED',
+        statusCode: 500,
+        details: {
+          registrationError: openError instanceof Error ? openError.message : String(openError),
+          rollbackError: cleanupError instanceof Error ? cleanupError.message : String(cleanupError),
+        },
+      });
+    }
+
+    throw openError;
+  }
+}

package/server/modules/worktrees/services/worktree-create.service.ts

@@ -0,0 +1,104 @@
+import path from 'node:path';
+
+import type {
+  CreateWorktreeInput,
+  CreateWorktreeResult,
+  GitCommandRunner,
+  WorktreeFileSystem,
+} from '@/shared/types.js';
+import { AppError, normalizeProjectPath } from '@/shared/utils.js';
+import {
+  listWorktreePorcelainEntries,
+  validateWorktreeBranchName,
+} from '@/modules/worktrees/services/worktree-git.service.js';
+
+/**
+ * Turns a branch name into a filesystem-safe folder name:
+ * "feature/login-form" → "feature-login-form".
+ */
+function sanitizeBranchForDirectoryName(branch: string): string {
+  const sanitized = branch
+    .replace(/[/\\:*?"<>|\s]+/g, '-')
+    .replace(/\.+$/g, '')
+    .replace(/^-+|-+$/g, '');
+
+  if (!sanitized) {
+    throw new AppError('Branch name cannot be converted to a folder name', {
+      code: 'INVALID_WORKTREE_FOLDER_NAME',
+      statusCode: 400,
+    });
+  }
+
+  return sanitized;
+}
+
+/**
+ * Creates a new worktree in a sibling folder of the repository:
+ * `<repoParent>/<repoName>-worktrees/<branch>`. Existing local branches are
+ * checked out directly; unknown branch names are created from `baseBranch`
+ * (falling back to the main worktree's branch).
+ */
+export async function createWorktree(
+  input: CreateWorktreeInput,
+  dependencies: {
+    runGit: GitCommandRunner;
+    fileSystem: WorktreeFileSystem;
+  },
+): Promise<CreateWorktreeResult> {
+  const { fileSystem, runGit } = dependencies;
+  const branch = validateWorktreeBranchName(input.branch);
+
+  const entries = await listWorktreePorcelainEntries(input.projectPath, runGit);
+  const repositoryRoot = entries[0].path;
+
+  const checkedOutElsewhere = entries.find((entry) => entry.branch === branch);
+  if (checkedOutElsewhere) {
+    throw new AppError(`Branch "${branch}" is already checked out in another worktree`, {
+      code: 'BRANCH_ALREADY_CHECKED_OUT',
+      statusCode: 409,
+      details: checkedOutElsewhere.path,
+    });
+  }
+
+  const worktreesContainer = path.join(
+    path.dirname(repositoryRoot),
+    `${path.basename(repositoryRoot)}-worktrees`,
+  );
+  const worktreePath = normalizeProjectPath(
+    path.join(worktreesContainer, sanitizeBranchForDirectoryName(branch)),
+  );
+
+  if (await fileSystem.pathExists(worktreePath)) {
+    throw new AppError(`Folder already exists: ${worktreePath}`, {
+      code: 'WORKTREE_FOLDER_EXISTS',
+      statusCode: 409,
+    });
+  }
+
+  const { stdout: branchListOutput } = await runGit(
+    ['branch', '--list', branch, '--format=%(refname:short)'],
+    repositoryRoot,
+  );
+  const branchExists = branchListOutput
+    .split('\n')
+    .some((line) => line.trim() === branch);
+
+  if (branchExists) {
+    await runGit(['worktree', 'add', worktreePath, branch], repositoryRoot);
+  } else {
+    const baseBranch = input.baseBranch?.trim() || entries[0].branch;
+    if (!baseBranch) {
+      throw new AppError('Cannot determine a base branch (main worktree is detached)', {
+        code: 'WORKTREE_BASE_BRANCH_UNKNOWN',
+        statusCode: 400,
+      });
+    }
+
+    await runGit(
+      ['worktree', 'add', worktreePath, '-b', branch, validateWorktreeBranchName(baseBranch)],
+      repositoryRoot,
+    );
+  }
+
+  return { worktreePath, branch, createdBranch: !branchExists };
+}

package/server/modules/worktrees/services/worktree-git.service.ts

@@ -0,0 +1,207 @@
+// cross-spawn: drop-in spawn with Windows .cmd/PATHEXT resolution (same choice as routes/git.js).
+import spawn from 'cross-spawn';
+
+import type { GitCommandResult, GitCommandRunner, WorktreePorcelainEntry } from '@/shared/types.js';
+import { AppError, normalizeProjectPath } from '@/shared/utils.js';
+
+/**
+ * Default `GitCommandRunner`: spawns `git <args>` in `cwd` and captures output.
+ * Rejects with an `AppError` carrying git's stderr when the command fails, so
+ * callers (and ultimately the API client) see the real git diagnostic.
+ */
+export function runGitCommand(args: string[], cwd: string): Promise<GitCommandResult> {
+  return new Promise((resolve, reject) => {
+    const child = spawn('git', args, { cwd, shell: false });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout?.on('data', (data: Buffer) => {
+      stdout += data.toString();
+    });
+
+    child.stderr?.on('data', (data: Buffer) => {
+      stderr += data.toString();
+    });
+
+    child.on('error', (error) => {
+      reject(
+        new AppError(`Failed to run git: ${error.message}`, {
+          code: 'GIT_SPAWN_FAILED',
+          statusCode: 500,
+        }),
+      );
+    });
+
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve({ stdout, stderr });
+        return;
+      }
+
+      reject(
+        new AppError(`git ${args.join(' ')} failed`, {
+          code: 'GIT_COMMAND_FAILED',
+          statusCode: 500,
+          details: (stderr || stdout).trim(),
+        }),
+      );
+    });
+  });
+}
+
+/**
+ * Defense-in-depth branch-name validation (mirrors routes/git.js), tightened to
+ * also reject the leading-dash / lone-dot forms git itself refuses.
+ */
+export function validateWorktreeBranchName(branch: string): string {
+  const trimmed = branch.trim();
+  const components = trimmed.split('/');
+  if (
+    !trimmed ||
+    trimmed.startsWith('-') ||
+    trimmed.startsWith('/') ||
+    trimmed.endsWith('/') ||
+    trimmed.endsWith('.') ||
+    trimmed === '.' ||
+    trimmed === '..' ||
+    trimmed.includes('..') ||
+    trimmed.includes('//') ||
+    components.some((component) =>
+      component.startsWith('.') || component.toLowerCase().endsWith('.lock')) ||
+    !/^[a-zA-Z0-9._/-]+$/.test(trimmed)
+  ) {
+    throw new AppError('Invalid branch name', {
+      code: 'INVALID_BRANCH_NAME',
+      statusCode: 400,
+    });
+  }
+  return trimmed;
+}
+
+/**
+ * Parses `git worktree list --porcelain` output. Entries are separated by blank
+ * lines; the first entry is always the main worktree. Paths come back with
+ * forward slashes even on Windows, so they are normalized here for stable
+ * comparisons against DB-stored project paths.
+ */
+export function parseWorktreeListPorcelain(output: string): WorktreePorcelainEntry[] {
+  const entries: WorktreePorcelainEntry[] = [];
+  let current: WorktreePorcelainEntry | null = null;
+
+  const flush = () => {
+    if (current) {
+      entries.push(current);
+      current = null;
+    }
+  };
+
+  for (const rawLine of output.split('\n')) {
+    const line = rawLine.trimEnd();
+    if (!line) {
+      flush();
+      continue;
+    }
+
+    if (line.startsWith('worktree ')) {
+      flush();
+      current = {
+        path: normalizeProjectPath(line.slice('worktree '.length)),
+        headSha: null,
+        branch: null,
+        isDetached: false,
+        isLocked: false,
+        isPrunable: false,
+      };
+      continue;
+    }
+
+    if (!current) {
+      continue;
+    }
+
+    if (line.startsWith('HEAD ')) {
+      current.headSha = line.slice('HEAD '.length).trim() || null;
+    } else if (line.startsWith('branch ')) {
+      // Porcelain reports the full ref, e.g. "branch refs/heads/feature/x".
+      current.branch = line.slice('branch '.length).replace(/^refs\/heads\//, '').trim() || null;
+    } else if (line === 'detached') {
+      current.isDetached = true;
+    } else if (line === 'locked' || line.startsWith('locked ')) {
+      current.isLocked = true;
+    } else if (line === 'prunable' || line.startsWith('prunable ')) {
+      current.isPrunable = true;
+    }
+  }
+
+  flush();
+  return entries;
+}
+
+/**
+ * Lists the repository's worktrees (main worktree first) for the repo that
+ * contains `projectPath`. Throws a 400 `AppError` when the directory is not
+ * inside a git repository.
+ */
+export async function listWorktreePorcelainEntries(
+  projectPath: string,
+  runGit: GitCommandRunner,
+): Promise<WorktreePorcelainEntry[]> {
+  let output: string;
+  try {
+    const result = await runGit(['worktree', 'list', '--porcelain'], projectPath);
+    output = result.stdout;
+  } catch (error) {
+    throw new AppError('Not a git repository', {
+      code: 'NOT_A_GIT_REPOSITORY',
+      statusCode: 400,
+      details: error instanceof AppError ? error.details : String(error),
+    });
+  }
+
+  const entries = parseWorktreeListPorcelain(output);
+  if (entries.length === 0) {
+    throw new AppError('No worktrees found for repository', {
+      code: 'WORKTREE_LIST_EMPTY',
+      statusCode: 500,
+    });
+  }
+
+  return entries;
+}
+
+/**
+ * Finds the worktree entry matching `worktreePath` (normalized comparison).
+ * Throws a 404 `AppError` when the path is not a registered worktree of the
+ * repository — this is the guard that stops arbitrary paths reaching git.
+ */
+export function findWorktreeEntryByPath(
+  entries: WorktreePorcelainEntry[],
+  worktreePath: string,
+): WorktreePorcelainEntry {
+  const normalized = normalizeProjectPath(worktreePath);
+  const comparable = (value: string) =>
+    process.platform === 'win32' ? value.toLowerCase() : value;
+
+  const match = entries.find((entry) => comparable(entry.path) === comparable(normalized));
+  if (!match) {
+    throw new AppError('Path is not a worktree of this repository', {
+      code: 'WORKTREE_NOT_FOUND',
+      statusCode: 404,
+    });
+  }
+
+  return match;
+}
+
+/**
+ * Counts dirty paths (`git status --porcelain`) inside one worktree. Status
+ * failures propagate so callers never mistake an unreadable worktree for clean.
+ */
+export async function countChangedFiles(
+  worktreePath: string,
+  runGit: GitCommandRunner,
+): Promise<number> {
+  const { stdout } = await runGit(['status', '--porcelain'], worktreePath);
+  return stdout.split('\n').filter((line) => line.trim().length > 0).length;
+}

package/server/modules/worktrees/services/worktree-list.service.ts

@@ -0,0 +1,143 @@
+import type {
+  GitCommandRunner,
+  ListWorktreesInput,
+  ProjectRepositoryRow,
+  WorktreeDescriptor,
+  WorktreeListResult,
+  WorktreePorcelainEntry,
+} from '@/shared/types.js';
+import { normalizeProjectPath } from '@/shared/utils.js';
+import {
+  countChangedFiles,
+  listWorktreePorcelainEntries,
+} from '@/modules/worktrees/services/worktree-git.service.js';
+
+type ListWorktreesDependencies = {
+  runGit: GitCommandRunner;
+  getProjectByPath: (projectPath: string) => ProjectRepositoryRow | null;
+};
+
+const WORKTREE_LIST_CONCURRENCY = 4;
+
+async function mapWithConcurrency<TInput, TOutput>(
+  inputs: TInput[],
+  concurrency: number,
+  mapper: (input: TInput, index: number) => Promise<TOutput>,
+): Promise<TOutput[]> {
+  const results = new Array<TOutput>(inputs.length);
+  let nextIndex = 0;
+
+  async function worker(): Promise<void> {
+    while (nextIndex < inputs.length) {
+      const index = nextIndex;
+      nextIndex += 1;
+      results[index] = await mapper(inputs[index], index);
+    }
+  }
+
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, inputs.length) }, () => worker()),
+  );
+  return results;
+}
+
+/**
+ * Computes how many commits `branch` is ahead/behind `baseBranch`. Runs in the
+ * main worktree so both refs are resolvable regardless of which worktree has
+ * them checked out. Returns zeros when the comparison is impossible (same
+ * branch, detached HEAD, unborn refs).
+ */
+async function countAheadBehind(
+  repositoryRoot: string,
+  baseBranch: string | null,
+  branch: string | null,
+  runGit: GitCommandRunner,
+): Promise<{ ahead: number; behind: number }> {
+  if (!baseBranch || !branch || baseBranch === branch) {
+    return { ahead: 0, behind: 0 };
+  }
+
+  try {
+    const { stdout } = await runGit(
+      ['rev-list', '--left-right', '--count', `${baseBranch}...${branch}`],
+      repositoryRoot,
+    );
+    const [behindRaw, aheadRaw] = stdout.trim().split(/\s+/);
+    return {
+      ahead: Number.parseInt(aheadRaw ?? '0', 10) || 0,
+      behind: Number.parseInt(behindRaw ?? '0', 10) || 0,
+    };
+  } catch {
+    return { ahead: 0, behind: 0 };
+  }
+}
+
+/** Reads the last commit subject + ISO date of a worktree's HEAD (null on unborn branches). */
+async function readLastCommit(
+  worktreePath: string,
+  runGit: GitCommandRunner,
+): Promise<{ subject: string | null; date: string | null }> {
+  try {
+    const { stdout } = await runGit(['log', '-1', '--format=%s%x00%cI'], worktreePath);
+    const [subject, date] = stdout.trim().split('\0');
+    return { subject: subject || null, date: date || null };
+  } catch {
+    return { subject: null, date: null };
+  }
+}
+
+/**
+ * Builds the full Worktrees panel payload for the repository containing
+ * `projectPath`: every worktree with dirty count, ahead/behind vs the base
+ * branch, last commit info, and the linked CloudCLI project (when registered).
+ */
+export async function listWorktrees(
+  input: ListWorktreesInput,
+  dependencies: ListWorktreesDependencies,
+): Promise<WorktreeListResult> {
+  const { runGit, getProjectByPath } = dependencies;
+  const entries = await listWorktreePorcelainEntries(input.projectPath, runGit);
+
+  // The first porcelain entry is always the main worktree; its checked-out
+  // branch is the merge target ("base branch") offered by the UI.
+  const mainEntry = entries[0];
+  const repositoryRoot = mainEntry.path;
+  const baseBranch = mainEntry.branch;
+
+  const requestedPath = normalizeProjectPath(input.projectPath);
+  const comparable = (value: string) =>
+    process.platform === 'win32' ? value.toLowerCase() : value;
+
+  const worktrees = await mapWithConcurrency(
+    entries,
+    WORKTREE_LIST_CONCURRENCY,
+    async (entry: WorktreePorcelainEntry, index: number): Promise<WorktreeDescriptor> => {
+      const [changedFileCount, aheadBehind, lastCommit] = await Promise.all([
+        countChangedFiles(entry.path, runGit),
+        countAheadBehind(repositoryRoot, baseBranch, index === 0 ? null : entry.branch, runGit),
+        readLastCommit(entry.path, runGit),
+      ]);
+
+      const linkedProject = getProjectByPath(entry.path);
+
+      return {
+        path: entry.path,
+        branch: entry.branch,
+        headSha: entry.headSha,
+        isMain: index === 0,
+        isCurrent: comparable(entry.path) === comparable(requestedPath),
+        isLocked: entry.isLocked,
+        isDetached: entry.isDetached,
+        changedFileCount,
+        ahead: aheadBehind.ahead,
+        behind: aheadBehind.behind,
+        lastCommitSubject: lastCommit.subject,
+        lastCommitDate: lastCommit.date,
+        linkedProjectId: linkedProject?.project_id ?? null,
+        linkedProjectArchived: Boolean(linkedProject?.isArchived),
+      };
+    },
+  );
+
+  return { repositoryRoot, baseBranch, worktrees };
+}