@piecemaker-legal/piecemaker 1.0.0

package/server/modules/database/tests/provider-models.db.integration.test.ts

@@ -0,0 +1,125 @@
+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,
+  providerModelsDb,
+  sessionsDb,
+} from '@/modules/database/index.js';
+import { runMigrations } from '@/modules/database/migrations.js';
+
+test('provider model repository stores custom rows only and maintains session references', async () => {
+  const previousDatabasePath = process.env.DATABASE_PATH;
+  const tempDirectory = await mkdtemp(path.join(os.tmpdir(), 'provider-model-db-'));
+  const databasePath = path.join(tempDirectory, 'auth.db');
+
+  closeConnection();
+  process.env.DATABASE_PATH = databasePath;
+  await writeFile(databasePath, '');
+  await initializeDatabase();
+
+  try {
+    const columns = getConnection().prepare('PRAGMA table_info(provider_models)').all() as Array<{
+      name: string;
+    }>;
+    assert.deepEqual(columns.map((column) => column.name), [
+      'id',
+      'provider',
+      'model_id',
+      'model_name',
+      'sort_order',
+      'created_at',
+      'updated_at',
+    ]);
+    assert.deepEqual(providerModelsDb.listCustomProviderModels('codex'), []);
+
+    const custom = providerModelsDb.createCustomProviderModel('codex', {
+      model: 'Private Gateway Model',
+      id: 'gateway/model-v1',
+    });
+    assert.equal(custom.modelId, 'gateway/model-v1');
+    assert.equal(
+      providerModelsDb.findCustomProviderModelByModelId('codex', 'gateway/model-v1')?.recordId,
+      custom.recordId,
+    );
+
+    const db = getConnection();
+    db.prepare(`
+      INSERT INTO projects (project_id, project_path)
+      VALUES ('project-1', '/tmp/project-1')
+    `).run();
+    db.prepare(`
+      INSERT INTO sessions (session_id, provider, project_path, model, effort)
+      VALUES ('session-1', 'codex', '/tmp/project-1', 'gateway/model-v1', 'high')
+    `).run();
+
+    const updated = providerModelsDb.updateCustomProviderModel('codex', custom.recordId, {
+      model: 'Private Gateway Model 2',
+      id: 'gateway/model-v2',
+    });
+    assert.equal(updated?.modelId, 'gateway/model-v2');
+    assert.equal(sessionsDb.getSessionById('session-1')?.model, 'gateway/model-v2');
+    // A rename keeps the same underlying model, so its effort stays applicable.
+    assert.equal(sessionsDb.getSessionById('session-1')?.effort, 'high');
+
+    const removed = providerModelsDb.deleteCustomProviderModel(
+      'codex',
+      custom.recordId,
+      'gpt-default',
+    );
+    assert.equal(removed?.modelId, 'gateway/model-v2');
+    assert.equal(sessionsDb.getSessionById('session-1')?.model, 'gpt-default');
+    // The effort belonged to the deleted model and must not survive onto the
+    // fallback, which has its own default.
+    assert.equal(sessionsDb.getSessionById('session-1')?.effort, null);
+    assert.equal(providerModelsDb.getCustomProviderModel('codex', custom.recordId), null);
+  } finally {
+    closeConnection();
+    if (previousDatabasePath === undefined) {
+      delete process.env.DATABASE_PATH;
+    } else {
+      process.env.DATABASE_PATH = previousDatabasePath;
+    }
+    await rm(tempDirectory, { recursive: true, force: true });
+  }
+});
+
+test('migrations create the provider model index on an install that lacks it', async () => {
+  const previousDatabasePath = process.env.DATABASE_PATH;
+  const tempDirectory = await mkdtemp(path.join(os.tmpdir(), 'provider-model-index-'));
+  const databasePath = path.join(tempDirectory, 'auth.db');
+
+  closeConnection();
+  process.env.DATABASE_PATH = databasePath;
+  await writeFile(databasePath, '');
+  await initializeDatabase();
+
+  try {
+    const db = getConnection();
+    // Upgraded installs reach runMigrations with provider_models present but no
+    // index, so the CREATE INDEX statement is compiled against the real table
+    // instead of short-circuiting on the existing index name.
+    db.exec('DROP INDEX IF EXISTS idx_provider_models_provider_order');
+
+    runMigrations(db);
+
+    const indexedColumns = (db
+      .prepare('PRAGMA index_info(idx_provider_models_provider_order)')
+      .all() as Array<{ name: string }>)
+      .map((column) => column.name);
+    assert.deepEqual(indexedColumns, ['provider', 'sort_order', 'id']);
+  } finally {
+    closeConnection();
+    if (previousDatabasePath === undefined) {
+      delete process.env.DATABASE_PATH;
+    } else {
+      process.env.DATABASE_PATH = previousDatabasePath;
+    }
+    await rm(tempDirectory, { recursive: true, force: true });
+  }
+});

package/server/modules/database/tests/sessions-provider-mapping.test.ts

@@ -0,0 +1,109 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { closeConnection } from '@/modules/database/connection.js';
+import { initializeDatabase } from '@/modules/database/init-db.js';
+import { sessionsDb } from '@/modules/database/repositories/sessions.db.js';
+
+async function withIsolatedDatabase(runTest: () => void | Promise<void>): Promise<void> {
+  const previousDatabasePath = process.env.DATABASE_PATH;
+  const tempDirectory = await mkdtemp(path.join(tmpdir(), 'sessions-mapping-'));
+  const databasePath = path.join(tempDirectory, 'auth.db');
+
+  closeConnection();
+  process.env.DATABASE_PATH = databasePath;
+  await initializeDatabase();
+
+  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('disk-discovered sessions are keyed by the provider id for both columns', async () => {
+  await withIsolatedDatabase(() => {
+    sessionsDb.createSession('provider-abc', 'claude', '/workspace/demo', 'From Disk');
+
+    const row = sessionsDb.getSessionById('provider-abc');
+    assert.equal(row?.session_id, 'provider-abc');
+    assert.equal(row?.provider_session_id, 'provider-abc');
+
+    const byProviderId = sessionsDb.getSessionByProviderSessionId('provider-abc');
+    assert.equal(byProviderId?.session_id, 'provider-abc');
+  });
+});
+
+test('app sessions get the provider id assigned without creating a duplicate row', async () => {
+  await withIsolatedDatabase(() => {
+    sessionsDb.createAppSession('app-id-1', 'claude', '/workspace/demo', 'Initial CloudCLI message');
+    sessionsDb.assignProviderSessionId('app-id-1', 'provider-xyz');
+
+    // A later synchronizer pass that discovers the transcript on disk must
+    // update the app row in place instead of inserting a provider-keyed row.
+    const returnedId = sessionsDb.createSession(
+      'provider-xyz',
+      'claude',
+      '/workspace/demo',
+      'Synced Name',
+      undefined,
+      undefined,
+      '/fake/path/provider-xyz.jsonl',
+    );
+
+    assert.equal(returnedId, 'app-id-1');
+    assert.equal(sessionsDb.getAllSessions().length, 1);
+
+    const row = sessionsDb.getSessionById('app-id-1');
+    assert.equal(row?.provider_session_id, 'provider-xyz');
+    assert.equal(row?.jsonl_path, '/fake/path/provider-xyz.jsonl');
+    assert.equal(row?.custom_name, 'Initial CloudCLI message');
+  });
+});
+
+test('assignProviderSessionId merges a watcher-created duplicate into the app row', async () => {
+  await withIsolatedDatabase(() => {
+    sessionsDb.createAppSession('app-id-2', 'codex', '/workspace/demo');
+
+    // Simulate the race: the filesystem watcher indexed the provider
+    // transcript before the runtime announced its session id to the gateway.
+    sessionsDb.createSession(
+      'provider-race',
+      'codex',
+      '/workspace/demo',
+      'Watcher Name',
+      undefined,
+      undefined,
+      '/fake/provider-race.jsonl',
+    );
+    assert.equal(sessionsDb.getAllSessions().length, 2);
+
+    sessionsDb.assignProviderSessionId('app-id-2', 'provider-race');
+
+    const rows = sessionsDb.getAllSessions();
+    assert.equal(rows.length, 1);
+    assert.equal(rows[0]?.session_id, 'app-id-2');
+    assert.equal(rows[0]?.provider_session_id, 'provider-race');
+    // Transcript path and name from the duplicate are adopted.
+    assert.equal(rows[0]?.jsonl_path, '/fake/provider-race.jsonl');
+    assert.equal(rows[0]?.custom_name, 'Watcher Name');
+  });
+});
+
+test('legacy provider-keyed rows stay resolvable through both lookups', async () => {
+  await withIsolatedDatabase(() => {
+    sessionsDb.createSession('legacy-1', 'opencode', '/workspace/demo');
+
+    assert.equal(sessionsDb.getSessionById('legacy-1')?.provider, 'opencode');
+    assert.equal(sessionsDb.getSessionByProviderSessionId('legacy-1')?.session_id, 'legacy-1');
+  });
+});

package/server/modules/database/tests/sessions.db.integration.test.ts

@@ -0,0 +1,116 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { closeConnection } from '@/modules/database/connection.js';
+import { initializeDatabase } from '@/modules/database/init-db.js';
+import { projectsDb } from '@/modules/database/repositories/projects.db.js';
+import { sessionsDb } from '@/modules/database/repositories/sessions.db.js';
+
+async function withIsolatedDatabase(runTest: () => void | Promise<void>): Promise<void> {
+  const previousDatabasePath = process.env.DATABASE_PATH;
+  const tempDirectory = await mkdtemp(path.join(tmpdir(), 'sessions-db-'));
+  const databasePath = path.join(tempDirectory, 'auth.db');
+
+  closeConnection();
+  process.env.DATABASE_PATH = databasePath;
+  await initializeDatabase();
+
+  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('session archive queries hide archived rows from active project views', async () => {
+  await withIsolatedDatabase(() => {
+    sessionsDb.createSession('session-active', 'claude', '/workspace/demo-project', 'Active Session');
+    sessionsDb.createSession('session-archived', 'claude', '/workspace/demo-project', 'Archived Session');
+    sessionsDb.updateSessionIsArchived('session-archived', true);
+
+    const activeSessions = sessionsDb.getAllSessions();
+    const archivedSessions = sessionsDb.getArchivedSessions();
+    const activeProjectSessions = sessionsDb.getSessionsByProjectPath('/workspace/demo-project');
+    const allProjectSessions = sessionsDb.getSessionsByProjectPathIncludingArchived('/workspace/demo-project');
+
+    assert.deepEqual(activeSessions.map((session) => session.session_id), ['session-active']);
+    assert.deepEqual(archivedSessions.map((session) => session.session_id), ['session-archived']);
+    assert.deepEqual(activeProjectSessions.map((session) => session.session_id), ['session-active']);
+    assert.deepEqual(
+      allProjectSessions.map((session) => session.session_id).sort(),
+      ['session-active', 'session-archived'],
+    );
+    assert.equal(sessionsDb.countSessionsByProjectPath('/workspace/demo-project'), 1);
+  });
+});
+
+test('createSession reactivates archived rows when the session becomes active again', async () => {
+  await withIsolatedDatabase(() => {
+    sessionsDb.createSession('session-reused', 'claude', '/workspace/demo-project', 'First Name');
+    sessionsDb.updateSessionIsArchived('session-reused', true);
+
+    sessionsDb.createSession('session-reused', 'claude', '/workspace/demo-project', 'Updated Name');
+
+    const activeSessions = sessionsDb.getAllSessions();
+    const archivedSessions = sessionsDb.getArchivedSessions();
+    const restoredSession = sessionsDb.getSessionById('session-reused');
+
+    assert.equal(activeSessions.length, 1);
+    assert.equal(activeSessions[0]?.session_id, 'session-reused');
+    assert.equal(activeSessions[0]?.custom_name, 'Updated Name');
+    assert.equal(archivedSessions.length, 0);
+    assert.equal(restoredSession?.isArchived, 0);
+  });
+});
+
+test('repository reads normalize SQLite UTC timestamps to ISO strings', async () => {
+  await withIsolatedDatabase(() => {
+    sessionsDb.createAppSession('session-timezone', 'claude', '/workspace/demo-project');
+
+    const row = sessionsDb.getSessionById('session-timezone');
+    assert.ok(row?.created_at.endsWith('Z'));
+    assert.ok(row?.updated_at.endsWith('Z'));
+    assert.match(row?.created_at ?? '', /^\d{4}-\d{2}-\d{2}T/);
+    assert.match(row?.updated_at ?? '', /^\d{4}-\d{2}-\d{2}T/);
+  });
+});
+
+test('recent sessions are globally ordered, paginated, and limited to visible conversations', async () => {
+  await withIsolatedDatabase(() => {
+    const fixtures: Array<Parameters<typeof sessionsDb.createSession>> = [
+      ['session-oldest', 'claude', '/workspace/project-a', 'Oldest', '2026-07-18T09:00:00.000Z', '2026-07-18T10:00:00.000Z'],
+      ['session-newest', 'codex', '/workspace/project-b', 'Newest', '2026-07-18T11:00:00.000Z', '2026-07-18T12:00:00.900Z'],
+      ['session-same-second', 'claude', '/workspace/project-a', 'Same second, slightly older', '2026-07-18T12:00:00.000Z', '2026-07-18T12:00:00.100Z'],
+      ['session-middle', 'claude', '/workspace/project-a', 'Middle', '2026-07-18T10:00:00.000Z', '2026-07-18T11:00:00.000Z'],
+      ['session-archived', 'claude', '/workspace/project-a', 'Archived session', '2026-07-18T13:00:00.000Z', '2026-07-18T13:00:00.000Z'],
+      ['session-hidden-project', 'claude', '/workspace/project-hidden', 'Archived project session', '2026-07-18T14:00:00.000Z', '2026-07-18T14:00:00.000Z'],
+    ];
+    fixtures.forEach((fixture) => sessionsDb.createSession(...fixture));
+
+    sessionsDb.updateSessionIsArchived('session-archived', true);
+    projectsDb.updateProjectIsArchived('/workspace/project-hidden', true);
+
+    const firstPage = sessionsDb.getRecentSessionsPage(2, 0);
+    const secondPage = sessionsDb.getRecentSessionsPage(2, 2);
+
+    assert.equal(firstPage.total, 4);
+    assert.deepEqual(
+      firstPage.sessions.map((session) => session.session_id),
+      ['session-newest', 'session-same-second'],
+    );
+    assert.equal(secondPage.total, 4);
+    assert.deepEqual(
+      secondPage.sessions.map((session) => session.session_id),
+      ['session-middle', 'session-oldest'],
+    );
+  });
+});

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

@@ -0,0 +1,116 @@
+import { randomUUID } from 'node:crypto';
+import fs, { promises as fsPromises } from 'node:fs';
+import os from 'node:os';
+
+import mime from 'mime-types';
+import multer from 'multer';
+
+import { projectsDb } from '@/modules/database/index.js';
+import { createFileTreeRouter } from '@/modules/file-tree/file-tree.routes.js';
+import { createFileTreeService } from '@/modules/file-tree/file-tree.service.js';
+import type {
+  FileTreeFileSystem,
+  FileTreeLogger,
+  FileTreeProjectGateway,
+  FileTreeWorkspaceGateway,
+} from '@/shared/types.js';
+import { WORKSPACES_ROOT, validateWorkspacePath } from '@/shared/utils.js';
+
+const MAXIMUM_UPLOAD_SIZE_MEGABYTES = 200;
+const MAXIMUM_UPLOAD_SIZE_BYTES = MAXIMUM_UPLOAD_SIZE_MEGABYTES * 1024 * 1024;
+const MAXIMUM_UPLOAD_FILE_COUNT = 20;
+
+function readFileSystemConcurrency(): number {
+  const configuredConcurrency = Number.parseInt(process.env.FS_CONCURRENCY ?? '', 10);
+  return Number.isFinite(configuredConcurrency) && configuredConcurrency > 0
+    ? configuredConcurrency
+    : 64;
+}
+
+/**
+ * Production filesystem adapter owned by the File Tree composition root.
+ * Application services receive this complete capability explicitly and never
+ * import Node's mutable filesystem APIs themselves.
+ */
+const fileTreeFileSystem: FileTreeFileSystem = {
+  access: (candidatePath) => fsPromises.access(candidatePath),
+  stat: (candidatePath) => fsPromises.stat(candidatePath),
+  lstat: (candidatePath) => fsPromises.lstat(candidatePath),
+  // `opendir` streams entries in batches and the handle is closed by the
+  // iterator protocol, including when the caller stops early at the entry cap.
+  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: (sourcePath, destinationPath) => fsPromises.copyFile(sourcePath, destinationPath),
+  createReadStream: (filePath) => fs.createReadStream(filePath),
+};
+
+/**
+ * Database boundary used only by File Tree production composition.
+ * The Database module is consumed through its barrel; services and routes see
+ * only the narrow project-path lookup contract.
+ */
+const fileTreeProjects: FileTreeProjectGateway = {
+  getProjectPathById: (projectId) => projectsDb.getProjectPathById(projectId),
+};
+
+/**
+ * Workspace-policy boundary used only by File Tree production composition.
+ * Keeping both the configured root and symlink-aware validator together makes
+ * the path policy explicit for every service instance.
+ */
+const fileTreeWorkspace: FileTreeWorkspaceGateway = {
+  rootPath: WORKSPACES_ROOT,
+  validatePath: (candidatePath) => validateWorkspacePath(candidatePath),
+};
+
+const fileTreeLogger: FileTreeLogger = {
+  error: (message, error) => console.error(message, error),
+};
+
+const fileTreeServices = createFileTreeService({
+  fileSystem: fileTreeFileSystem,
+  projects: fileTreeProjects,
+  workspace: fileTreeWorkspace,
+  resolveMimeType: (filePath) => mime.lookup(filePath) || 'application/octet-stream',
+  fileSystemConcurrency: readFileSystemConcurrency(),
+  logger: fileTreeLogger,
+});
+
+const fileUploadMiddleware = multer({
+  storage: multer.diskStorage({
+    destination: os.tmpdir(),
+    filename: (_request, _file, callback) => {
+      callback(null, `cloudcli-file-upload-${randomUUID()}`);
+    },
+  }),
+  limits: {
+    fileSize: MAXIMUM_UPLOAD_SIZE_BYTES,
+    files: MAXIMUM_UPLOAD_FILE_COUNT,
+  },
+}).array('files', MAXIMUM_UPLOAD_FILE_COUNT);
+
+/**
+ * File Tree router used by the server entrypoint to mount the authenticated
+ * browsing, editing, file-management, and upload API under `/api/file-tree`.
+ */
+export const fileTreeRoutes = createFileTreeRouter(
+  fileTreeServices,
+  fileUploadMiddleware,
+  {
+    maximumFileSizeMegabytes: MAXIMUM_UPLOAD_SIZE_MEGABYTES,
+    maximumFileCount: MAXIMUM_UPLOAD_FILE_COUNT,
+  },
+  fileTreeLogger,
+);