@cloudcli-ai/cloudcli 1.37.1 → 1.37.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudcli-ai/cloudcli",
-  "version": "1.37.1",
+  "version": "1.37.2",
   "productName": "CloudCLI",
   "description": "A web-based UI for Claude Code CLI",
   "type": "module",
@@ -28,6 +28,7 @@
   },
   "scripts": {
     "dev": "concurrently --kill-others \"npm run server:dev\" \"npm run client\"",
+    "preserver": "node scripts/promote-dist-server.mjs recover",
     "server": "node dist-server/server/index.js",
     "server:dev": "tsx --tsconfig server/tsconfig.json server/index.ts",
     "server:dev-watch": "tsx watch --tsconfig server/tsconfig.json server/index.ts",
@@ -42,11 +43,13 @@
     "desktop:icon:mac": "node electron/scripts/generate-macos-icon.js",
     "build": "npm run build:client && npm run build:server",
     "build:client": "vite build",
-    "prebuild:server": "node -e \"require('node:fs').rmSync('dist-server', { recursive: true, force: true })\"",
+    "prebuild:server": "node -e \"require('node:fs').rmSync('dist-server.next', { recursive: true, force: true })\"",
     "build:server": "tsc -p server/tsconfig.json && tsc-alias -p server/tsconfig.json",
+    "postbuild:server": "node scripts/promote-dist-server.mjs",
     "preview": "vite preview",
     "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p server/tsconfig.json",
     "test": "tsx --tsconfig server/tsconfig.json --test \"server/**/*.test.ts\" \"server/**/*.test.js\"",
+    "test:client": "tsx --test \"src/**/*.test.ts\" \"src/**/*.test.tsx\"",
     "lint": "eslint src/ server/",
     "lint:fix": "eslint src/ server/ --fix",
     "start": "npm run build && npm run server",
@@ -175,6 +178,7 @@
     "jszip": "^3.10.1",
     "katex": "^0.16.25",
     "lucide-react": "^0.515.0",
+    "mermaid": "^11.16.1",
     "mime-types": "^3.0.1",
     "multer": "^2.0.1",
     "node-fetch": "^2.7.0",

package/scripts/promote-dist-server.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+// The server build stages into dist-server.next and this script promotes it
+// into place. The live dist-server must never be deleted before the new build
+// is complete: an interrupted build would otherwise leave the installation
+// without a server entrypoint, crash-looping on MODULE_NOT_FOUND at every
+// start until someone rebuilds it by hand.
+import fs from 'node:fs';
+
+const NEXT = 'dist-server.next';
+const LIVE = 'dist-server';
+const OLD = 'dist-server.old';
+const ENTRY = 'server/index.js';
+
+const mode = process.argv[2] ?? 'promote';
+
+if (mode === 'recover') {
+  // Ran before every server start: if a promotion was interrupted between the
+  // two renames, put the previous build back so the server can boot.
+  if (!fs.existsSync(`${LIVE}/${ENTRY}`) && fs.existsSync(`${OLD}/${ENTRY}`)) {
+    console.error('promote-dist-server: restoring previous dist-server after an interrupted promotion.');
+    fs.rmSync(LIVE, { recursive: true, force: true });
+    fs.renameSync(OLD, LIVE);
+  }
+  process.exit(0);
+}
+
+if (mode !== 'promote') {
+  console.error(`promote-dist-server: unknown mode "${mode}" (expected "promote" or "recover").`);
+  process.exit(64);
+}
+
+if (!fs.existsSync(`${NEXT}/${ENTRY}`)) {
+  console.error(`promote-dist-server: ${NEXT}/${ENTRY} is missing; leaving the current ${LIVE} untouched.`);
+  process.exit(1);
+}
+
+fs.rmSync(OLD, { recursive: true, force: true });
+if (fs.existsSync(LIVE)) {
+  fs.renameSync(LIVE, OLD);
+}
+try {
+  fs.renameSync(NEXT, LIVE);
+} catch (error) {
+  // Put the previous build back before failing so the installation still boots.
+  if (fs.existsSync(OLD) && !fs.existsSync(LIVE)) {
+    fs.renameSync(OLD, LIVE);
+  }
+  throw error;
+}
+fs.rmSync(OLD, { recursive: true, force: true });

package/server/index.ts

@@ -9,7 +9,7 @@ import http from 'http';
 import express, { type NextFunction, type Request, type Response } from 'express';
 import cors from 'cors';
 
-import { AppError, findApplicationRoot, getModuleDirectory, terminalTextStyles } from '@/shared/utils.js';
+import { AppError, findApplicationRoot, getModuleDirectory, IS_PLATFORM, terminalTextStyles } from '@/shared/utils.js';
 import {
     closeSessionsWatcher,
     initializeSessionsWatcher,
@@ -50,7 +50,6 @@ import browserUseMcpRoutes from './modules/browser-use/browser-use-mcp.routes.js
 import { browserUseService } from './modules/browser-use/browser-use.service.js';
 import { initializeDatabase, sessionsDb } from './modules/database/index.js';
 import { configureWebPush } from './modules/notifications/index.js';
-import { IS_PLATFORM } from './constants/config.js';
 
 const __dirname = getModuleDirectory(import.meta.url);
 // The server source runs from /server, while the compiled output runs from /dist-server/server.

package/server/modules/agent/agent.module.ts

@@ -12,6 +12,7 @@ import {
   userDb,
 } from '@/modules/database/index.js';
 import { providerModelsService } from '@/modules/providers/index.js';
+import { IS_PLATFORM } from '@/shared/utils.js';
 
 import { createAgentRouter } from './agent.routes.js';
 
@@ -30,7 +31,7 @@ export function createAgentModule(externalDependencies: AgentExternalDependencie
     crypto,
     homeDirectory: os.homedir,
     spawnProcess: spawn,
-    platformMode: process.env.VITE_IS_PLATFORM === 'true',
+    platformMode: IS_PLATFORM,
     users: {
       getFirstUser: () => userDb.getFirstUser(),
     },

package/server/modules/auth/auth.middleware.ts

@@ -1,9 +1,9 @@
 // @ts-nocheck -- JWT request augmentation is narrowed by Auth route contracts.
 import jwt from 'jsonwebtoken';
 
-import { userDb, appConfigDb } from '../database/index.js';
+import { IS_PLATFORM } from '@/shared/utils.js';
 
-const IS_PLATFORM = process.env.VITE_IS_PLATFORM === 'true';
+import { userDb, appConfigDb } from '../database/index.js';
 
 // Use env var if set, otherwise auto-generate a unique secret per installation
 const JWT_SECRET = process.env.JWT_SECRET || appConfigDb.getOrCreateJwtSecret();

package/server/modules/browser-use/browser-use-runtime.ts

@@ -0,0 +1,10 @@
+import { IS_PLATFORM } from '@/shared/utils.js';
+
+/**
+ * Resolves the runtime label exposed by Browser Use status and session APIs.
+ * The Browser Use service and CLI environment-mode regression coverage consume
+ * this after the server or CLI entrypoint has completed environment bootstrapping.
+ */
+export function getBrowserUseRuntime(): 'cloud' | 'local' {
+  return IS_PLATFORM ? 'cloud' : 'local';
+}

package/server/modules/browser-use/browser-use.service.ts

@@ -11,15 +11,16 @@ import { appConfigDb } from '@/modules/database/index.js';
 import { providerMcpService } from '@/modules/providers/index.js';
 import { getModuleDirectory } from '@/shared/utils.js';
 
+import { getBrowserUseRuntime } from './browser-use-runtime.js';
+
 const require = createRequire(import.meta.url);
 const __dirname = getModuleDirectory(import.meta.url);
-const IS_PLATFORM = process.env.VITE_IS_PLATFORM === 'true';
 const MAX_SESSIONS_PER_OWNER = Number.parseInt(process.env.CLOUDCLI_BROWSER_USE_MAX_SESSIONS_PER_OWNER || '3', 10);
 const SESSION_TTL_MS = Number.parseInt(process.env.CLOUDCLI_BROWSER_USE_SESSION_TTL_MS || String(30 * 60 * 1000), 10);
 const BROWSER_USE_SETTINGS_KEY = 'browser_use_settings';
 const BROWSER_USE_MCP_TOKEN_KEY = 'browser_use_mcp_token';
 
-type BrowserUseRuntime = 'cloud' | 'local';
+type BrowserUseRuntime = ReturnType<typeof getBrowserUseRuntime>;
 type BrowserUseSessionStatus = 'ready' | 'stopped' | 'unavailable';
 
 type BrowserUseSession = {
@@ -85,10 +86,6 @@ const MCP_SERVER_NAME = 'cloudcli-browser';
 const LEGACY_MCP_SERVER_NAMES = ['cloudcli-browser-use'];
 const RUNTIME_READINESS_CACHE_TTL_MS = 30_000;
 
-function getRuntime(): BrowserUseRuntime {
-  return IS_PLATFORM ? 'cloud' : 'local';
-}
-
 function readSettings(): BrowserUseSettings {
   try {
     const raw = appConfigDb.get(BROWSER_USE_SETTINGS_KEY);
@@ -446,7 +443,7 @@ export const browserUseService = {
 
     return {
       enabled: settings.enabled,
-      runtime: getRuntime(),
+      runtime: getBrowserUseRuntime(),
       available,
       playwrightInstalled: readiness.playwrightInstalled,
       chromiumInstalled: readiness.chromiumInstalled,
@@ -515,7 +512,7 @@ export const browserUseService = {
       id: randomUUID(),
       ownerId: AGENT_OWNER_ID,
       createdBy: 'agent',
-      runtime: getRuntime(),
+      runtime: getBrowserUseRuntime(),
       status: 'unavailable',
       url: null,
       title: null,

package/server/modules/browser-use/index.ts

@@ -6,3 +6,6 @@
 export async function startBrowserUseMcp(): Promise<void> {
   await import('./browser-use-mcp.js');
 }
+
+// getBrowserUseRuntime: used by Browser Use services and environment-mode regression coverage.
+export { getBrowserUseRuntime } from './browser-use-runtime.js';

package/server/modules/cli/cli.module.ts

@@ -28,7 +28,6 @@ export function createCliApplication(): CliApplication {
     bugsUrl: packageMetadataJson.bugs?.url,
   };
   const fileSystem = {
-    readTextFile: (filePath: string) => fs.readFileSync(filePath, 'utf8'),
     pathExists: (filePath: string) => fs.existsSync(filePath),
     getFileStats: (filePath: string) => {
       const stats = fs.statSync(filePath);

package/server/modules/cli/cli.service.ts

@@ -77,27 +77,7 @@ function isNewerVersion(candidateVersion: string, currentVersion: string): boole
   return false;
 }
 
-function loadEnvironmentFile(dependencies: CliServiceDependencies): void {
-  try {
-    const environmentFile = dependencies.fileSystem.readTextFile(
-      path.join(dependencies.applicationRoot, '.env'),
-    );
-    for (const line of environmentFile.split('\n')) {
-      const trimmedLine = line.trim();
-      if (!trimmedLine || trimmedLine.startsWith('#')) continue;
-
-      const [key, ...valueParts] = trimmedLine.split('=');
-      if (key && valueParts.length > 0 && !dependencies.environment[key]) {
-        dependencies.environment[key] = valueParts.join('=').trim();
-      }
-    }
-  } catch {
-    // The repository-level .env file is optional for every CLI command.
-  }
-}
-
 function showStatus(dependencies: CliServiceDependencies): void {
-  loadEnvironmentFile(dependencies);
   const { environment, fileSystem, output } = dependencies;
   const databasePath = environment.DATABASE_PATH || dependencies.defaultDatabasePath;
   const databaseExists = fileSystem.pathExists(databasePath);

package/server/modules/cli/cli.ts

@@ -1,10 +1,16 @@
 #!/usr/bin/env node
 
-import { createCliApplication } from './index.js';
+// The CLI can reach shared environment constants through its composition root,
+// so finish the root environment bootstrap before loading that import graph.
+// eslint-disable-next-line boundaries/no-unknown
+import '../../load-env.js';
 
-const cliApplication = createCliApplication();
+async function runCli(): Promise<number> {
+  const { createCliApplication } = await import('./index.js');
+  return createCliApplication().run(process.argv.slice(2));
+}
 
-cliApplication.run(process.argv.slice(2)).then((exitCode) => {
+runCli().then((exitCode) => {
   process.exitCode = exitCode;
 }).catch((error: unknown) => {
   const message = error instanceof Error ? error.message : String(error);

package/server/modules/cli/tests/cli-environment-bootstrap.test.ts

@@ -0,0 +1,186 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { copyFile, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+type BootstrapResult = {
+  command: string | null;
+  environmentFileReads: number;
+  mode: string | null;
+  authNextCalled: boolean;
+  authStatus: number;
+  authenticatedUsername: string | null;
+  runtime: string;
+};
+
+const RESULT_PREFIX = '__CLOUDCLI_BOOTSTRAP_RESULT__';
+const testDirectory = path.dirname(fileURLToPath(import.meta.url));
+const applicationRoot = path.resolve(testDirectory, '..', '..', '..', '..');
+
+function sourceModuleUrl(...segments: string[]): string {
+  return pathToFileURL(path.join(applicationRoot, ...segments)).href;
+}
+
+async function runCliBootstrapFixture(isPlatform: boolean): Promise<BootstrapResult> {
+  const fixtureRoot = await mkdtemp(path.join(os.tmpdir(), 'cloudcli-cli-bootstrap-'));
+  const fixtureServerDirectory = path.join(fixtureRoot, 'server');
+  const fixtureCliDirectory = path.join(fixtureServerDirectory, 'modules', 'cli');
+  const fixtureDatabasePath = path.join(fixtureRoot, 'auth.db');
+
+  try {
+    await mkdir(fixtureCliDirectory, { recursive: true });
+    await Promise.all([
+      copyFile(
+        path.join(applicationRoot, 'server', 'load-env.ts'),
+        path.join(fixtureServerDirectory, 'load-env.ts'),
+      ),
+      copyFile(
+        path.join(applicationRoot, 'server', 'modules', 'cli', 'cli.ts'),
+        path.join(fixtureCliDirectory, 'cli.ts'),
+      ),
+    ]);
+    await writeFile(
+      path.join(fixtureRoot, '.env'),
+      [
+        `VITE_IS_PLATFORM=${String(isPlatform)}`,
+        `DATABASE_PATH=${fixtureDatabasePath.replace(/\\/g, '/')}`,
+      ].join('\n'),
+      'utf8',
+    );
+
+    const fixtureIndexSource = `
+import { createCliService } from ${JSON.stringify(sourceModuleUrl('server', 'modules', 'cli', 'cli.service.ts'))};
+import { authenticateToken } from ${JSON.stringify(sourceModuleUrl('server', 'modules', 'auth', 'index.ts'))};
+import { getBrowserUseRuntime } from ${JSON.stringify(sourceModuleUrl('server', 'modules', 'browser-use', 'index.ts'))};
+import { closeConnection, initializeDatabase, userDb } from ${JSON.stringify(sourceModuleUrl('server', 'modules', 'database', 'index.ts'))};
+
+let environmentFileReads = 0;
+
+export function createCliApplication() {
+  const service = createCliService({
+    applicationRoot: ${JSON.stringify(fixtureRoot)},
+    defaultDatabasePath: ${JSON.stringify(fixtureDatabasePath)},
+    homeDirectory: ${JSON.stringify(fixtureRoot)},
+    packageMetadata: { version: '1.0.0' },
+    environment: process.env,
+    fileSystem: {
+      readTextFile: () => {
+        environmentFileReads += 1;
+        return '';
+      },
+      pathExists: () => false,
+      getFileStats: () => ({ size: 0, modifiedAt: new Date(0) }),
+    },
+    output: { log: () => undefined, error: () => undefined },
+    sandboxService: { execute: async () => 0 },
+    getLatestPackageVersion: async () => '1.0.0',
+    updateGlobalPackage: () => undefined,
+    startServer: async () => undefined,
+    startBrowserUseMcp: async () => undefined,
+  });
+
+  return {
+    async run(argumentsList: string[]) {
+      const exitCode = await service.run(argumentsList);
+      await initializeDatabase();
+      userDb.createUser('bootstrap-user', 'password-hash');
+
+      const request: any = { headers: {}, query: {} };
+      const response: any = {
+        statusCode: 200,
+        body: null,
+        headers: {},
+        setHeader(name: string, value: string) {
+          this.headers[name] = value;
+        },
+        status(statusCode: number) {
+          this.statusCode = statusCode;
+          return this;
+        },
+        json(body: unknown) {
+          this.body = body;
+          return this;
+        },
+      };
+      let authNextCalled = false;
+      await authenticateToken(request, response, () => {
+        authNextCalled = true;
+      });
+      const runtime = getBrowserUseRuntime();
+
+      console.log(${JSON.stringify(RESULT_PREFIX)} + JSON.stringify({
+        command: argumentsList[0] ?? null,
+        environmentFileReads,
+        mode: process.env.VITE_IS_PLATFORM ?? null,
+        authNextCalled,
+        authStatus: response.statusCode,
+        authenticatedUsername: request.user?.username ?? null,
+        runtime,
+      }));
+      closeConnection();
+      return exitCode;
+    },
+  };
+}
+`;
+    await writeFile(path.join(fixtureCliDirectory, 'index.ts'), fixtureIndexSource, 'utf8');
+
+    const childEnvironment = { ...process.env };
+    delete childEnvironment.VITE_IS_PLATFORM;
+    delete childEnvironment.DATABASE_PATH;
+    const stdout = execFileSync(
+      process.execPath,
+      [
+        path.join(applicationRoot, 'node_modules', 'tsx', 'dist', 'cli.mjs'),
+        '--tsconfig',
+        path.join(applicationRoot, 'server', 'tsconfig.json'),
+        path.join(fixtureCliDirectory, 'cli.ts'),
+        'status',
+      ],
+      {
+        cwd: applicationRoot,
+        encoding: 'utf8',
+        env: childEnvironment,
+        timeout: 30_000,
+      },
+    );
+    const resultLine = stdout
+      .split(/\r?\n/)
+      .find((line) => line.startsWith(RESULT_PREFIX));
+    assert.ok(resultLine, `Missing bootstrap result in child output:\n${stdout}`);
+    return JSON.parse(resultLine.slice(RESULT_PREFIX.length)) as BootstrapResult;
+  } finally {
+    await rm(fixtureRoot, { recursive: true, force: true });
+  }
+}
+
+test('CLI bootstrap selects Platform authentication and cloud runtime from .env', async () => {
+  const result = await runCliBootstrapFixture(true);
+
+  assert.deepEqual(result, {
+    command: 'status',
+    environmentFileReads: 0,
+    mode: 'true',
+    authNextCalled: true,
+    authStatus: 200,
+    authenticatedUsername: 'bootstrap-user',
+    runtime: 'cloud',
+  });
+});
+
+test('CLI bootstrap selects OSS authentication and local runtime from .env', async () => {
+  const result = await runCliBootstrapFixture(false);
+
+  assert.deepEqual(result, {
+    command: 'status',
+    environmentFileReads: 0,
+    mode: 'false',
+    authNextCalled: false,
+    authStatus: 401,
+    authenticatedUsername: null,
+    runtime: 'local',
+  });
+});

package/server/modules/cli/tests/cli.service.test.ts

@@ -26,9 +26,6 @@ function createHarness() {
     },
     environment,
     fileSystem: {
-      readTextFile: () => {
-        throw new Error('missing');
-      },
       pathExists: () => false,
       getFileStats: () => ({ size: 0, modifiedAt: new Date(0) }),
     },

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

@@ -11,9 +11,13 @@ import type {
 } from '@/shared/types.js';
 import { AppError, FORBIDDEN_WORKSPACE_PATHS, normalizeProjectPath } from '@/shared/utils.js';
 
+const HARD_EXCLUDED_DIRECTORY_NAMES = new Set([
+  'node_modules', '.git', '.svn', '.hg',
+]);
+
 const IGNORED_DIRECTORY_NAMES = new Set([
-  'node_modules', 'dist', 'build', '.next', '.nuxt', '.cache', '.parcel-cache',
-  '.git', '.svn', '.hg',
+  ...HARD_EXCLUDED_DIRECTORY_NAMES,
+  'dist', 'build', '.next', '.nuxt', '.cache', '.parcel-cache',
   '__pycache__', '.pytest_cache', '.mypy_cache', '.tox', 'venv', '.venv',
   'target', 'vendor',
   '.gradle', '.idea', 'coverage', '.nyc_output',
@@ -36,6 +40,15 @@ const MAXIMUM_FILE_TREE_ENTRIES = 10_000;
 
 type FileTreeEntryFilter = (entryPath: string, isDirectory: boolean) => boolean;
 
+function includeEntryByHardExclusions(entryPath: string, isDirectory: boolean): boolean {
+  return !isDirectory || !HARD_EXCLUDED_DIRECTORY_NAMES.has(path.basename(entryPath));
+}
+
+function includeEntryByFallbackDirectoryNames(entryPath: string, isDirectory: boolean): boolean {
+  return includeEntryByHardExclusions(entryPath, isDirectory)
+    && (!isDirectory || !IGNORED_DIRECTORY_NAMES.has(path.basename(entryPath)));
+}
+
 function createFileTreeError(message: string, statusCode: number, code: string): AppError {
   return new AppError(message, { statusCode, code });
 }
@@ -146,6 +159,8 @@ function createGitignoreEntryFilter(
   const gitignore = ignore().add(gitignoreContent);
 
   return (entryPath, isDirectory) => {
+    if (!includeEntryByHardExclusions(entryPath, isDirectory)) return false;
+
     const relativePath = path.relative(projectRoot, entryPath).split(path.sep).join('/');
     const matchPath = isDirectory ? `${relativePath}/` : relativePath;
     return !gitignore.ignores(matchPath);
@@ -191,17 +206,13 @@ export function createFileTreeService(dependencies: FileTreeServiceDependencies)
     try {
       for await (const entry of fileSystem.openDirectory(directoryPath)) {
         const isDirectory = entry.isDirectory();
-        if (isDirectory && IGNORED_DIRECTORY_NAMES.has(entry.name)) {
-          continue;
-        }
         if (!includeEntry(path.join(directoryPath, entry.name), isDirectory)) {
           continue;
         }
 
-        // Charged after ignore filtering so generated directories and
-        // .gitignore exclusions never consume the budget. Every recursive
-        // branch shares one counter, so the cap applies to the whole tree
-        // rather than per directory.
+        // Charged after visibility filtering so ignored entries never consume
+        // the budget. Every recursive branch shares one counter, so the cap
+        // applies to the whole tree rather than per directory.
         if (remainingEntries.value <= 0) {
           throw createFileTreeError(
             `Project file tree exceeds the ${MAXIMUM_FILE_TREE_ENTRIES.toLocaleString()} entry limit. Choose a narrower project directory or add ignore rules.`,
@@ -233,7 +244,7 @@ export function createFileTreeService(dependencies: FileTreeServiceDependencies)
     directoryPath: string,
     maximumDepth: number,
     currentDepth = 0,
-    includeEntry: FileTreeEntryFilter = () => true,
+    includeEntry: FileTreeEntryFilter = includeEntryByFallbackDirectoryNames,
     remainingEntries = { value: MAXIMUM_FILE_TREE_ENTRIES },
   ): Promise<FileTreeNode[]> {
     const visibleEntries = await collectVisibleEntries(directoryPath, includeEntry, remainingEntries);

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

@@ -87,37 +87,67 @@ function createDependencies(
   };
 }
 
-test('listProjectFiles builds a sorted tree and skips generated directories', async () => {
+test('listProjectFiles applies gitignore alongside hard directory exclusions', async () => {
   const projectRoot = path.resolve('file-tree-test-project');
+  const documentationDirectory = path.join(projectRoot, 'docs');
+  const buildDocumentationDirectory = path.join(documentationDirectory, 'build');
+  const gitDirectory = path.join(projectRoot, '.git');
+  const nodeModulesDirectory = path.join(projectRoot, 'node_modules');
   const sourceDirectory = path.join(projectRoot, 'src');
+  const readDirectories: string[] = [];
   const fileSystem = createFakeFileSystem({
     access: async () => undefined,
+    readTextFile: async (filePath) => {
+      assert.equal(filePath, path.join(projectRoot, '.gitignore'));
+      return '*.log';
+    },
     openDirectory: createDirectoryReader((directoryPath) => {
+      readDirectories.push(directoryPath);
       if (directoryPath === projectRoot) {
         return [
+          createDirectoryEntry('.git', true),
           createDirectoryEntry('node_modules', true),
           createDirectoryEntry('README.md', false),
+          createDirectoryEntry('docs', true),
           createDirectoryEntry('src', true),
         ];
       }
+      if (directoryPath === documentationDirectory) {
+        return [createDirectoryEntry('build', true)];
+      }
+      if (directoryPath === buildDocumentationDirectory) {
+        return [createDirectoryEntry('foo.md', false)];
+      }
       if (directoryPath === sourceDirectory) {
         return [createDirectoryEntry('index.ts', false)];
       }
       return [];
     }),
-    lstat: async (candidatePath) => createStats(candidatePath === sourceDirectory, 0o754),
+    lstat: async (candidatePath) => createStats(
+      candidatePath === documentationDirectory
+        || candidatePath === buildDocumentationDirectory
+        || candidatePath === sourceDirectory
+        || candidatePath === gitDirectory
+        || candidatePath === nodeModulesDirectory,
+      0o754,
+    ),
   });
   const service = createFileTreeService(createDependencies(fileSystem, projectRoot));
 
-  const tree = await service.listProjectFiles('project-1');
+  const tree = await service.listProjectFiles('project-1', { respectGitignore: true });
 
-  assert.deepEqual(tree.map((entry) => entry.name), ['src', 'README.md']);
-  const sourceEntry = tree[0];
+  assert.deepEqual(tree.map((entry) => entry.name), ['docs', 'src', 'README.md']);
+  const documentationEntry = tree[0];
+  assert.deepEqual(documentationEntry?.children?.map((entry) => entry.name), ['build']);
+  assert.deepEqual(documentationEntry?.children?.[0]?.children?.map((entry) => entry.name), ['foo.md']);
+  const sourceEntry = tree[1];
   assert.ok(sourceEntry);
   assert.equal(sourceEntry.type, 'directory');
   assert.equal(sourceEntry.permissions, '754');
   assert.equal(sourceEntry.permissionsRwx, 'rwxr-xr--');
   assert.deepEqual(sourceEntry.children?.map((entry) => entry.name), ['index.ts']);
+  assert.equal(readDirectories.includes(gitDirectory), false);
+  assert.equal(readDirectories.includes(nodeModulesDirectory), false);
 });
 
 test('listProjectFiles excludes gitignored entries only when requested', async () => {
@@ -167,23 +197,47 @@ test('listProjectFiles excludes gitignored entries only when requested', async (
   assert.equal(readDirectories.includes(cacheDirectory), false);
 });
 
-test('listProjectFiles returns the normal tree when no gitignore exists', async () => {
+test('listProjectFiles falls back to conventional directory names when no gitignore exists', async () => {
   const projectRoot = path.resolve('file-tree-test-project');
+  const documentationDirectory = path.join(projectRoot, 'docs');
+  const buildDocumentationDirectory = path.join(documentationDirectory, 'build');
+  const nodeModulesDirectory = path.join(projectRoot, 'node_modules');
+  const readDirectories: string[] = [];
   const fileSystem = createFakeFileSystem({
     access: async () => undefined,
     readTextFile: async () => {
       throw Object.assign(new Error('missing'), { code: 'ENOENT' });
     },
-    openDirectory: createDirectoryReader((directoryPath) => directoryPath === projectRoot
-      ? [createDirectoryEntry('debug.log', false)]
-      : []),
-    lstat: async () => createStats(false, 0o644),
+    openDirectory: createDirectoryReader((directoryPath) => {
+      readDirectories.push(directoryPath);
+      if (directoryPath === projectRoot) {
+        return [
+          createDirectoryEntry('debug.log', false),
+          createDirectoryEntry('docs', true),
+          createDirectoryEntry('node_modules', true),
+        ];
+      }
+      if (directoryPath === documentationDirectory) {
+        return [
+          createDirectoryEntry('build', true),
+          createDirectoryEntry('guide.md', false),
+        ];
+      }
+      if (directoryPath === buildDocumentationDirectory) {
+        return [createDirectoryEntry('generated.md', false)];
+      }
+      return [];
+    }),
+    lstat: async (candidatePath) => createStats(candidatePath === documentationDirectory, 0o644),
   });
   const service = createFileTreeService(createDependencies(fileSystem, projectRoot));
 
   const tree = await service.listProjectFiles('project-1', { respectGitignore: true });
 
-  assert.deepEqual(tree.map((entry) => entry.name), ['debug.log']);
+  assert.deepEqual(tree.map((entry) => entry.name), ['docs', 'debug.log']);
+  assert.deepEqual(tree[0]?.children?.map((entry) => entry.name), ['guide.md']);
+  assert.equal(readDirectories.includes(nodeModulesDirectory), false);
+  assert.equal(readDirectories.includes(buildDocumentationDirectory), false);
 });
 
 test('listProjectFiles rejects a tree that exceeds the server entry limit', async () => {