fix: improve CodexLens env defaults, self-exclusion, and route handling

- Adjust env defaults (embed batch 64, workers 2) and add HNSW/chunking params - Exclude .codexlens directory from indexing and file watching - Expand codexlens-routes with improved validation and error handling - Enhance integration tests for broader route coverage Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-20 19:03:51 +08:00 · 2026-03-19 10:34:18 +08:00
parent 683b85228f
commit 00672ec8e5
11 changed files with 478 additions and 191 deletions
--- a/ccw/frontend/src/components/codexlens/EnvSettingsTab.tsx
+++ b/ccw/frontend/src/components/codexlens/EnvSettingsTab.tsx
@@ -85,7 +85,7 @@ const API_ONLY_KEYS = new Set([
 const FIELD_DEFAULTS: Record<string, string> = {
  CODEXLENS_EMBED_API_MODEL: 'text-embedding-3-small',
  CODEXLENS_EMBED_DIM: '1536',
-  CODEXLENS_EMBED_BATCH_SIZE: '512',
+  CODEXLENS_EMBED_BATCH_SIZE: '64',
  CODEXLENS_EMBED_API_CONCURRENCY: '4',
  CODEXLENS_BINARY_TOP_K: '200',
  CODEXLENS_ANN_TOP_K: '50',
@@ -93,7 +93,11 @@ const FIELD_DEFAULTS: Record<string, string> = {
  CODEXLENS_FUSION_K: '60',
  CODEXLENS_RERANKER_TOP_K: '20',
  CODEXLENS_RERANKER_BATCH_SIZE: '32',
-  CODEXLENS_INDEX_WORKERS: '4',
+  CODEXLENS_INDEX_WORKERS: '2',
+  CODEXLENS_CODE_AWARE_CHUNKING: 'true',
+  CODEXLENS_MAX_FILE_SIZE: '1000000',
+  CODEXLENS_HNSW_EF: '150',
+  CODEXLENS_HNSW_M: '32',
 };

 // Collect all keys
@@ -103,6 +107,15 @@ function buildEmptyEnv(): Record<string, string> {
  return Object.fromEntries(ALL_KEYS.map((k) => [k, '']));
 }

+function buildEffectiveEnv(
+  values: Record<string, string>,
+  defaults: Record<string, string>,
+): Record<string, string> {
+  return Object.fromEntries(
+    ALL_KEYS.map((key) => [key, values[key] ?? defaults[key] ?? '']),
+  );
+}
+
 // ========================================
 // Sensitive field with show/hide toggle
 // ========================================
@@ -142,30 +155,28 @@ function SensitiveInput({ value, onChange, id }: SensitiveInputProps) {

 export function EnvSettingsTab() {
  const { formatMessage } = useIntl();
-  const { data: serverEnv, isLoading } = useCodexLensEnv();
+  const { data: envData, isLoading } = useCodexLensEnv();
  const { saveEnv, isSaving } = useSaveCodexLensEnv();

  const [embedMode, setEmbedMode] = useState<EmbedMode>('local');
  const [localEnv, setLocalEnv] = useState<Record<string, string>>(buildEmptyEnv);

+  const serverValues = envData?.values ?? {};
+  const serverDefaults = { ...FIELD_DEFAULTS, ...(envData?.defaults ?? {}) };
+  const serverRecord = buildEffectiveEnv(serverValues, serverDefaults);
+
  // Sync server state into local when loaded and detect embed mode
  useEffect(() => {
-    if (serverEnv) {
-      setLocalEnv((prev) => {
-        const next = { ...prev };
-        ALL_KEYS.forEach((k) => {
-          next[k] = serverEnv[k] ?? '';
-        });
-        return next;
-      });
+    if (envData) {
+      const nextDefaults = { ...FIELD_DEFAULTS, ...(envData.defaults ?? {}) };
+      const nextValues = envData.values ?? {};
+      setLocalEnv(buildEffectiveEnv(nextValues, nextDefaults));
      // Auto-detect mode from saved env
-      if (serverEnv.CODEXLENS_EMBED_API_URL) {
+      if (nextValues.CODEXLENS_EMBED_API_URL) {
        setEmbedMode('api');
      }
    }
-  }, [serverEnv]);
-
-  const serverRecord = serverEnv ?? {};
+  }, [envData]);

  const isDirty = ALL_KEYS.some((k) => localEnv[k] !== (serverRecord[k] ?? ''));

@@ -174,7 +185,17 @@ export function EnvSettingsTab() {
  };

  const handleSave = async () => {
-    await saveEnv(localEnv);
+    const payload = Object.fromEntries(
+      Object.entries(localEnv).flatMap(([key, value]) => {
+        const trimmed = value.trim();
+        const defaultValue = serverDefaults[key] ?? '';
+        if (!trimmed || trimmed === defaultValue) {
+          return [];
+        }
+        return [[key, trimmed]];
+      }),
+    );
+    await saveEnv(payload);
  };

  const handleReset = () => {
@@ -252,7 +273,7 @@ export function EnvSettingsTab() {
                    <Input
                      id={field.key}
                      value={localEnv[field.key] ?? ''}
-                      placeholder={FIELD_DEFAULTS[field.key] ?? ''}
+                      placeholder={serverDefaults[field.key] ?? ''}
                      onChange={(e) => handleChange(field.key, e.target.value)}
                    />
                  )}
--- a/ccw/frontend/src/components/codexlens/McpConfigTab.tsx
+++ b/ccw/frontend/src/components/codexlens/McpConfigTab.tsx
@@ -10,7 +10,7 @@ import { Card, CardHeader, CardTitle, CardContent } from '@/components/ui/Card';
 import { Button } from '@/components/ui/Button';
 import { Badge } from '@/components/ui/Badge';
 import { useCodexLensMcpConfig, useCodexLensEnv } from '@/hooks/useCodexLens';
-import { installMcpTemplate } from '@/lib/api';
+import { addGlobalMcpServer, copyMcpServerToProject } from '@/lib/api';
 import { useWorkflowStore, selectProjectPath } from '@/stores/workflowStore';

 export function McpConfigTab() {
@@ -26,16 +26,34 @@ export function McpConfigTab() {
    setInstalling(true);
    setInstallResult(null);
    try {
-      const res = await installMcpTemplate({
-        templateName: 'codexlens',
-        scope,
-        projectPath: scope === 'project' ? projectPath : undefined,
-      });
+      const mcpServers = mcpConfig?.['mcpServers'];
+      const serverConfig = mcpServers && typeof mcpServers === 'object'
+        ? (mcpServers as Record<string, unknown>).codexlens
+        : undefined;
+
+      if (!serverConfig || typeof serverConfig !== 'object') {
+        throw new Error(formatMessage({ id: 'codexlens.mcp.noConfig' }));
+      }
+
+      const typedConfig = serverConfig as {
+        command: string;
+        args?: string[];
+        env?: Record<string, string>;
+        type?: string;
+      };
+
+      if (scope === 'project') {
+        if (!projectPath) {
+          throw new Error(formatMessage({ id: 'codexlens.mcp.installError' }));
+        }
+        await copyMcpServerToProject('codexlens', typedConfig, projectPath);
+      } else {
+        await addGlobalMcpServer('codexlens', typedConfig);
+      }
+
      setInstallResult({
-        ok: !!res.success,
-        msg: res.success
-          ? formatMessage({ id: 'codexlens.mcp.installSuccess' })
-          : (res.error ?? formatMessage({ id: 'codexlens.mcp.installError' })),
+        ok: true,
+        msg: formatMessage({ id: 'codexlens.mcp.installSuccess' }),
      });
    } catch (err) {
      setInstallResult({ ok: false, msg: (err as Error).message });
@@ -44,7 +62,7 @@ export function McpConfigTab() {
    }
  };

-  const hasApiUrl = !!(envData?.CODEXLENS_EMBED_API_URL);
+  const hasApiUrl = !!(envData?.values.CODEXLENS_EMBED_API_URL);
  const embedMode = hasApiUrl ? 'API' : 'Local fastembed';

  const configJson = mcpConfig ? JSON.stringify(mcpConfig, null, 2) : '';
--- a/ccw/frontend/src/components/codexlens/ModelManagerTab.tsx
+++ b/ccw/frontend/src/components/codexlens/ModelManagerTab.tsx
@@ -23,7 +23,7 @@ export function ModelManagerTab() {
  const { downloadModel, isDownloading } = useDownloadModel();
  const { deleteModel, isDeleting } = useDeleteModel();

-  const hasApiUrl = !!(envData?.CODEXLENS_EMBED_API_URL);
+  const hasApiUrl = !!(envData?.values.CODEXLENS_EMBED_API_URL);
  const embedMode = hasApiUrl ? 'API' : 'Local fastembed';

  const models: ModelEntry[] = modelsData ?? [];
--- a/ccw/frontend/src/hooks/useCodexLens.ts
+++ b/ccw/frontend/src/hooks/useCodexLens.ts
@@ -4,6 +4,7 @@
 // TanStack Query hooks for CodexLens v2 API management

 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { fetchApi } from '@/lib/api';

 // ========================================
 // Domain types (exported for component use)
@@ -25,11 +26,19 @@ export interface IndexStatusData {
 }

 export type McpConfigData = Record<string, unknown>;
+export interface CodexLensEnvData {
+  values: Record<string, string>;
+  defaults: Record<string, string>;
+}

 // Internal API response wrappers
 interface ModelsResponse { success: boolean; models: ModelEntry[] }
 interface IndexStatusResponse { success: boolean; status: IndexStatusData }
-interface EnvResponse { success: boolean; env: Record<string, string> }
+interface EnvResponse {
+  success: boolean;
+  env: Record<string, string>;
+  defaults?: Record<string, string>;
+}
 interface McpConfigResponse { success: boolean; config: McpConfigData }

 // ========================================
@@ -44,27 +53,6 @@ export const codexLensKeys = {
  mcpConfig: () => [...codexLensKeys.all, 'mcpConfig'] as const,
 };

-// ========================================
-// Internal fetch helper (mirrors fetchApi pattern from api.ts)
-// ========================================
-
-async function fetchApi<T>(url: string, options: RequestInit = {}): Promise<T> {
-  const headers = new Headers(options.headers);
-  if (options.body && typeof options.body === 'string') {
-    headers.set('Content-Type', 'application/json');
-  }
-  const response = await fetch(url, {
-    ...options,
-    headers,
-    credentials: 'same-origin',
-  });
-  if (!response.ok) {
-    const text = await response.text().catch(() => response.statusText);
-    throw new Error(text || `Request failed: ${response.status}`);
-  }
-  return response.json() as Promise<T>;
-}
-
 // ========================================
 // Models Hooks
 // ========================================
@@ -174,7 +162,11 @@ export function useRebuildIndex() {
 export function useCodexLensEnv() {
  return useQuery({
    queryKey: codexLensKeys.env(),
-    queryFn: () => fetchApi<EnvResponse>('/api/codexlens/env').then(r => r.env),
+    queryFn: () =>
+      fetchApi<EnvResponse>('/api/codexlens/env').then((r): CodexLensEnvData => ({
+        values: r.env ?? {},
+        defaults: r.defaults ?? {},
+      })),
    staleTime: 60_000,
  });
 }
--- a/ccw/frontend/src/lib/api.ts
+++ b/ccw/frontend/src/lib/api.ts
@@ -237,7 +237,7 @@ export async function initializeCsrfToken(): Promise<void> {
 /**
 * Base fetch wrapper with CSRF token and error handling
 */
-async function fetchApi<T>(
+export async function fetchApi<T>(
  url: string,
  options: RequestInit = {}
 ): Promise<T> {
--- a/ccw/src/core/routes/codexlens-routes.ts
+++ b/ccw/src/core/routes/codexlens-routes.ts
@@ -4,7 +4,7 @@
 */

 import { homedir } from 'os';
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync } from 'fs';
 import { join } from 'path';
 import { spawn } from 'child_process';

@@ -15,12 +15,23 @@ import type { RouteContext } from './types.js';
 /**
 * Spawn a CLI command and collect stdout/stderr
 */
-function spawnCli(cmd: string, args: string[]): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+function spawnCli(
+  cmd: string,
+  args: string[],
+  options: { cwd?: string; env?: Record<string, string> } = {},
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
  return new Promise((resolve, reject) => {
    let stdout = '';
    let stderr = '';

-    const child = spawn(cmd, args);
+    const child = spawn(cmd, args, {
+      cwd: options.cwd,
+      env: {
+        ...process.env,
+        ...readEnvFile(),
+        ...options.env,
+      },
+    });

    child.stdout.on('data', (chunk: Buffer) => {
      stdout += chunk.toString();
@@ -75,6 +86,98 @@ function writeEnvFile(env: Record<string, string>): void {
  writeFileSync(filePath, JSON.stringify(env, null, 2), 'utf-8');
 }

+const CODEXLENS_ENV_DEFAULTS: Record<string, string> = {
+  CODEXLENS_EMBED_API_MODEL: 'text-embedding-3-small',
+  CODEXLENS_EMBED_DIM: '1536',
+  CODEXLENS_EMBED_BATCH_SIZE: '64',
+  CODEXLENS_EMBED_API_CONCURRENCY: '4',
+  CODEXLENS_BINARY_TOP_K: '200',
+  CODEXLENS_ANN_TOP_K: '50',
+  CODEXLENS_FTS_TOP_K: '50',
+  CODEXLENS_FUSION_K: '60',
+  CODEXLENS_RERANKER_TOP_K: '20',
+  CODEXLENS_RERANKER_BATCH_SIZE: '32',
+  CODEXLENS_INDEX_WORKERS: '2',
+  CODEXLENS_CODE_AWARE_CHUNKING: 'true',
+  CODEXLENS_MAX_FILE_SIZE: '1000000',
+  CODEXLENS_HNSW_EF: '150',
+  CODEXLENS_HNSW_M: '32',
+};
+
+function getEnvDefaults(): Record<string, string> {
+  return { ...CODEXLENS_ENV_DEFAULTS };
+}
+
+function normalizeEnvInput(env: Record<string, string>): Record<string, string> {
+  const normalized: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (typeof value !== 'string') {
+      continue;
+    }
+    const trimmed = value.trim();
+    if (trimmed) {
+      normalized[key] = trimmed;
+    }
+  }
+  return normalized;
+}
+
+function filterNonEmptyEnv(env: Record<string, string>): Record<string, string> {
+  const filtered: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (typeof value === 'string' && value.trim() !== '') {
+      filtered[key] = value;
+    }
+  }
+  return filtered;
+}
+
+function buildMcpServerConfig(savedEnv: Record<string, string>): Record<string, unknown> {
+  const filteredEnv = filterNonEmptyEnv(savedEnv);
+  const hasApiEmbedding = Boolean(filteredEnv.CODEXLENS_EMBED_API_URL || filteredEnv.CODEXLENS_EMBED_API_ENDPOINTS);
+
+  if (hasApiEmbedding) {
+    filteredEnv.CODEXLENS_EMBED_API_MODEL ??= CODEXLENS_ENV_DEFAULTS.CODEXLENS_EMBED_API_MODEL;
+    filteredEnv.CODEXLENS_EMBED_DIM ??= CODEXLENS_ENV_DEFAULTS.CODEXLENS_EMBED_DIM;
+  }
+
+  return {
+    command: 'uvx',
+    args: ['--from', 'codexlens-search[mcp]', 'codexlens-mcp'],
+    ...(Object.keys(filteredEnv).length > 0 ? { env: filteredEnv } : {}),
+  };
+}
+
+function getProjectDbPath(projectPath: string): string {
+  return join(projectPath, '.codexlens');
+}
+
+function normalizeIndexStatus(status: unknown): Record<string, unknown> {
+  if (!status || typeof status !== 'object') {
+    return {
+      status: 'unknown',
+      files_tracked: 0,
+      total_chunks: 0,
+      deleted_chunks: 0,
+      raw: status,
+    };
+  }
+
+  const record = status as Record<string, unknown>;
+  const totalChunks = typeof record.total_chunks === 'number'
+    ? record.total_chunks
+    : typeof record.total_chunks_approx === 'number'
+      ? record.total_chunks_approx
+      : 0;
+
+  return {
+    ...record,
+    files_tracked: typeof record.files_tracked === 'number' ? record.files_tracked : 0,
+    total_chunks: totalChunks,
+    deleted_chunks: typeof record.deleted_chunks === 'number' ? record.deleted_chunks : 0,
+  };
+}
+
 // ========== ROUTE HANDLER ==========

 /**
@@ -161,8 +264,8 @@ export async function handleCodexLensRoutes(ctx: RouteContext): Promise<boolean>
      return true;
    }
    try {
-      const dbPath = join(projectPath, '.codexlens');
-      const result = await spawnCli('codexlens-search', ['status', '--db-path', dbPath]);
+      const dbPath = getProjectDbPath(projectPath);
+      const result = await spawnCli('codexlens-search', ['--db-path', dbPath, 'status']);
      if (result.exitCode !== 0) {
        res.writeHead(500, { 'Content-Type': 'application/json' });
        res.end(JSON.stringify({ error: result.stderr || 'Failed to get index status' }));
@@ -175,7 +278,7 @@ export async function handleCodexLensRoutes(ctx: RouteContext): Promise<boolean>
        status = { raw: result.stdout };
      }
      res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ success: true, status }));
+      res.end(JSON.stringify({ success: true, status: normalizeIndexStatus(status) }));
    } catch (err) {
      res.writeHead(500, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify({ error: (err as Error).message }));
@@ -192,7 +295,8 @@ export async function handleCodexLensRoutes(ctx: RouteContext): Promise<boolean>
        return { error: 'projectPath is required', status: 400 };
      }
      try {
-        const result = await spawnCli('codexlens-search', ['sync', '--root', projectPath]);
+        const dbPath = getProjectDbPath(projectPath);
+        const result = await spawnCli('codexlens-search', ['--db-path', dbPath, 'sync', '--root', projectPath]);
        if (result.exitCode !== 0) {
          return { error: result.stderr || 'Failed to sync index', status: 500 };
        }
@@ -213,11 +317,14 @@ export async function handleCodexLensRoutes(ctx: RouteContext): Promise<boolean>
        return { error: 'projectPath is required', status: 400 };
      }
      try {
-        const initResult = await spawnCli('codexlens-search', ['init', '--root', projectPath]);
+        const dbPath = getProjectDbPath(projectPath);
+        // Rebuild must discard stale index artifacts before reinitializing.
+        rmSync(dbPath, { recursive: true, force: true });
+        const initResult = await spawnCli('codexlens-search', ['--db-path', dbPath, 'init']);
        if (initResult.exitCode !== 0) {
          return { error: initResult.stderr || 'Failed to init index', status: 500 };
        }
-        const syncResult = await spawnCli('codexlens-search', ['sync', '--root', projectPath]);
+        const syncResult = await spawnCli('codexlens-search', ['--db-path', dbPath, 'sync', '--root', projectPath]);
        if (syncResult.exitCode !== 0) {
          return { error: syncResult.stderr || 'Failed to sync after init', status: 500 };
        }
@@ -235,7 +342,7 @@ export async function handleCodexLensRoutes(ctx: RouteContext): Promise<boolean>
    try {
      const env = readEnvFile();
      res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ success: true, env }));
+      res.end(JSON.stringify({ success: true, env, defaults: getEnvDefaults() }));
    } catch (err) {
      res.writeHead(500, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify({ error: (err as Error).message }));
@@ -252,7 +359,7 @@ export async function handleCodexLensRoutes(ctx: RouteContext): Promise<boolean>
        return { error: 'env object is required', status: 400 };
      }
      try {
-        writeEnvFile(env);
+        writeEnvFile(normalizeEnvInput(env));
        return { success: true };
      } catch (err) {
        return { error: (err as Error).message, status: 500 };
@@ -265,21 +372,10 @@ export async function handleCodexLensRoutes(ctx: RouteContext): Promise<boolean>
  // GET /api/codexlens/mcp-config
  if (pathname === '/api/codexlens/mcp-config' && req.method === 'GET') {
    try {
-      const env = readEnvFile();
-      // Filter to non-empty string values only
-      const filteredEnv: Record<string, string> = {};
-      for (const [key, value] of Object.entries(env)) {
-        if (typeof value === 'string' && value.trim() !== '') {
-          filteredEnv[key] = value;
-        }
-      }
      const mcpConfig = {
        mcpServers: {
-          codexlens: {
-            command: 'codexlens-mcp',
-            env: filteredEnv
-          }
-        }
+          codexlens: buildMcpServerConfig(readEnvFile()),
+        },
      };
      res.writeHead(200, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify({ success: true, config: mcpConfig }));
--- a/ccw/tests/integration/codexlens-routes.test.ts
+++ b/ccw/tests/integration/codexlens-routes.test.ts
@@ -1,14 +1,25 @@
 /**
- * Integration tests for CodexLens routes.
+ * Integration tests for CodexLens v2 routes.
 *
- * Notes:
- * - Targets runtime implementation shipped in `ccw/dist`.
- * - Exercises real HTTP request/response flow via a minimal test server.
+ * Tests the new v2 API endpoints:
+ * - GET  /api/codexlens/models
+ * - POST /api/codexlens/models/download
+ * - POST /api/codexlens/models/delete
+ * - GET  /api/codexlens/index/status?projectPath=
+ * - POST /api/codexlens/index/sync
+ * - POST /api/codexlens/index/rebuild
+ * - GET  /api/codexlens/env
+ * - POST /api/codexlens/env
+ * - GET  /api/codexlens/mcp-config
 */

-import { after, before, describe, it, mock } from 'node:test';
+import { after, before, beforeEach, describe, it, mock } from 'node:test';
 import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
 import http from 'node:http';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';

 const codexLensRoutesUrl = new URL('../../dist/core/routes/codexlens-routes.js', import.meta.url);
 codexLensRoutesUrl.searchParams.set('t', String(Date.now()));
@@ -41,16 +52,10 @@ async function requestJson(
      },
      (res) => {
        let responseBody = '';
-        res.on('data', (chunk) => {
-          responseBody += chunk.toString();
-        });
+        res.on('data', (chunk) => { responseBody += chunk.toString(); });
        res.on('end', () => {
          let json: any = null;
-          try {
-            json = responseBody ? JSON.parse(responseBody) : null;
-          } catch {
-            json = null;
-          }
+          try { json = responseBody ? JSON.parse(responseBody) : null; } catch { json = null; }
          resolve({ status: res.statusCode || 0, json, text: responseBody });
        });
      },
@@ -67,14 +72,11 @@ function handlePostRequest(
  handler: (body: unknown) => Promise<any>,
 ): void {
  let body = '';
-  req.on('data', (chunk) => {
-    body += chunk.toString();
-  });
+  req.on('data', (chunk) => { body += chunk.toString(); });
  req.on('end', async () => {
    try {
      const parsed = body ? JSON.parse(body) : {};
      const result = await handler(parsed);
-
      if (result?.error) {
        res.writeHead(result.status || 500, { 'Content-Type': 'application/json' });
        res.end(JSON.stringify({ error: result.error }));
@@ -89,23 +91,11 @@ function handlePostRequest(
  });
 }

-async function createServer(initialPath: string, broadcasts: any[]): Promise<{ server: http.Server; baseUrl: string }> {
+async function createServer(): Promise<{ server: http.Server; baseUrl: string }> {
  const server = http.createServer(async (req, res) => {
    const url = new URL(req.url || '/', 'http://localhost');
    const pathname = url.pathname;
-
-    const ctx = {
-      pathname,
-      url,
-      req,
-      res,
-      initialPath,
-      handlePostRequest,
-      broadcastToClients(data: unknown) {
-        broadcasts.push(data);
-      },
-    };
-
+    const ctx = { pathname, url, req, res, handlePostRequest, broadcastToClients() {} };
    try {
      const handled = await mod.handleCodexLensRoutes(ctx);
      if (!handled) {
@@ -124,116 +114,273 @@ async function createServer(initialPath: string, broadcasts: any[]): Promise<{ s
  return { server, baseUrl: `http://127.0.0.1:${port}` };
 }

-describe('codexlens routes integration', async () => {
+async function withServer(fn: (baseUrl: string) => Promise<void>): Promise<void> {
+  const { server, baseUrl } = await createServer();
+  try {
+    await fn(baseUrl);
+  } finally {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+}
+
+// Temp dir for env file isolation
+let tmpDir: string;
+let originalHome: string | undefined;
+let originalUserProfile: string | undefined;
+
+describe('codexlens v2 routes integration', async () => {
  before(async () => {
    mock.method(console, 'log', () => {});
    mock.method(console, 'error', () => {});
    mod = await import(codexLensRoutesUrl.href);
+
+    // Redirect HOME/USERPROFILE so env file writes go to a temp location
+    tmpDir = join(tmpdir(), `codexlens-test-${Date.now()}`);
+    mkdirSync(join(tmpDir, '.ccw'), { recursive: true });
+    originalHome = process.env.HOME;
+    originalUserProfile = process.env.USERPROFILE;
+    process.env.HOME = tmpDir;
+    process.env.USERPROFILE = tmpDir;
+  });
+
+  beforeEach(() => {
+    try { rmSync(join(tmpDir, '.ccw', 'codexlens-env.json'), { force: true }); } catch {}
  });

  after(() => {
    mock.restoreAll();
+    if (originalHome !== undefined) process.env.HOME = originalHome;
+    if (originalUserProfile !== undefined) process.env.USERPROFILE = originalUserProfile;
+    try { rmSync(tmpDir, { recursive: true, force: true }); } catch {}
  });

-  it('GET /api/codexlens/status returns venv status', async () => {
-    const broadcasts: any[] = [];
-    const { server, baseUrl } = await createServer(process.cwd(), broadcasts);
-    try {
-      const res = await requestJson(baseUrl, 'GET', '/api/codexlens/status');
+  // ── GET /api/codexlens/models (real CLI) ──────────────────
+  it('GET /api/codexlens/models returns models array from real CLI', async () => {
+    await withServer(async (baseUrl) => {
+      const res = await requestJson(baseUrl, 'GET', '/api/codexlens/models');
      assert.equal(res.status, 200);
-      assert.equal(typeof res.json, 'object');
-      assert.equal(typeof res.json.ready, 'boolean');
-    } finally {
-      await new Promise<void>((resolve) => server.close(() => resolve()));
-    }
+      assert.equal(res.json.success, true);
+      assert.ok(Array.isArray(res.json.models), 'models should be an array');
+      // Each model should have name and installed fields
+      if (res.json.models.length > 0) {
+        assert.ok(typeof res.json.models[0].name === 'string');
+        assert.ok(typeof res.json.models[0].installed === 'boolean');
+      }
+    });
  });

-  it('GET /api/codexlens/config returns configuration payload', async () => {
-    const broadcasts: any[] = [];
-    const { server, baseUrl } = await createServer(process.cwd(), broadcasts);
-    try {
-      const res = await requestJson(baseUrl, 'GET', '/api/codexlens/config');
+  it('GET /api/codexlens/models returns non-empty list with known model names', async () => {
+    await withServer(async (baseUrl) => {
+      const res = await requestJson(baseUrl, 'GET', '/api/codexlens/models');
      assert.equal(res.status, 200);
-      assert.equal(typeof res.json?.index_dir, 'string');
-      assert.equal(typeof res.json?.index_count, 'number');
-    } finally {
-      await new Promise<void>((resolve) => server.close(() => resolve()));
-    }
+      const names = res.json.models.map((m: any) => m.name);
+      // bge-small should be in the list (it's the default model)
+      assert.ok(names.some((n: string) => n.includes('bge-small')), 'bge-small should be in model list');
+    });
  });

-  it('POST /api/codexlens/config validates required index_dir', async () => {
-    const broadcasts: any[] = [];
-    const { server, baseUrl } = await createServer(process.cwd(), broadcasts);
-    try {
-      const res = await requestJson(baseUrl, 'POST', '/api/codexlens/config', {});
+  // ── POST /api/codexlens/models/download ────────────────────
+  it('POST /api/codexlens/models/download requires name', async () => {
+    await withServer(async (baseUrl) => {
+      const res = await requestJson(baseUrl, 'POST', '/api/codexlens/models/download', {});
      assert.equal(res.status, 400);
-      assert.ok(String(res.json.error).includes('index_dir is required'));
-    } finally {
-      await new Promise<void>((resolve) => server.close(() => resolve()));
-    }
+      assert.ok(res.json.error?.includes('name is required'));
+    });
  });

-  it('GET /api/codexlens/indexing-status returns inProgress flag', async () => {
-    const broadcasts: any[] = [];
-    const { server, baseUrl } = await createServer(process.cwd(), broadcasts);
-    try {
-      const res = await requestJson(baseUrl, 'GET', '/api/codexlens/indexing-status');
+  // ── POST /api/codexlens/models/delete ──────────────────────
+  it('POST /api/codexlens/models/delete requires name', async () => {
+    await withServer(async (baseUrl) => {
+      const res = await requestJson(baseUrl, 'POST', '/api/codexlens/models/delete', {});
+      assert.equal(res.status, 400);
+      assert.ok(res.json.error?.includes('name is required'));
+    });
+  });
+
+  // ── GET /api/codexlens/index/status ────────────────────────
+  it('GET /api/codexlens/index/status requires projectPath query param', async () => {
+    await withServer(async (baseUrl) => {
+      const res = await requestJson(baseUrl, 'GET', '/api/codexlens/index/status');
+      assert.equal(res.status, 400);
+      assert.ok(res.json.error?.includes('projectPath'));
+    });
+  });
+
+  it('GET /api/codexlens/index/status returns status object for real project path', async () => {
+    await withServer(async (baseUrl) => {
+      // Use tmpDir as the project path (unindexed directory)
+      const res = await requestJson(
+        baseUrl,
+        'GET',
+        `/api/codexlens/index/status?projectPath=${encodeURIComponent(tmpDir)}`,
+      );
      assert.equal(res.status, 200);
      assert.equal(res.json.success, true);
-      assert.equal(typeof res.json.inProgress, 'boolean');
-    } finally {
-      await new Promise<void>((resolve) => server.close(() => resolve()));
-    }
+      assert.ok(typeof res.json.status === 'object', 'status should be an object');
+      // status should have a status field (e.g. 'not_initialized')
+      assert.ok(typeof res.json.status.status === 'string', 'status.status should be a string');
+    });
  });

-  it('GET /api/codexlens/semantic/status returns semantic availability', async () => {
-    const broadcasts: any[] = [];
-    const { server, baseUrl } = await createServer(process.cwd(), broadcasts);
-    try {
-      const res = await requestJson(baseUrl, 'GET', '/api/codexlens/semantic/status');
+  it('GET /api/codexlens/index/status normalizes total_chunks from CLI output', async () => {
+    const projectPath = join(tmpDir, 'status-project');
+    const dbPath = join(projectPath, '.codexlens');
+    mkdirSync(projectPath, { recursive: true });
+    execFileSync('codexlens-search', ['--db-path', dbPath, 'init'], { encoding: 'utf8' });
+
+    await withServer(async (baseUrl) => {
+      const res = await requestJson(
+        baseUrl,
+        'GET',
+        `/api/codexlens/index/status?projectPath=${encodeURIComponent(projectPath)}`,
+      );
      assert.equal(res.status, 200);
-      assert.equal(typeof res.json?.available, 'boolean');
-    } finally {
-      await new Promise<void>((resolve) => server.close(() => resolve()));
-    }
+      assert.equal(res.json.status.status, 'ok');
+      assert.equal(res.json.status.total_chunks, 0);
+      assert.equal(res.json.status.deleted_chunks, 0);
+    });
  });

-  it('GET /api/codexlens/indexes returns indexes list payload', async () => {
-    const broadcasts: any[] = [];
-    const { server, baseUrl } = await createServer(process.cwd(), broadcasts);
-    try {
-      const res = await requestJson(baseUrl, 'GET', '/api/codexlens/indexes');
+  // ── POST /api/codexlens/index/sync ─────────────────────────
+  it('POST /api/codexlens/index/sync requires projectPath', async () => {
+    await withServer(async (baseUrl) => {
+      const res = await requestJson(baseUrl, 'POST', '/api/codexlens/index/sync', {});
+      assert.equal(res.status, 400);
+      assert.ok(res.json.error?.includes('projectPath'));
+    });
+  });
+
+  // ── POST /api/codexlens/index/rebuild ──────────────────────
+  it('POST /api/codexlens/index/rebuild requires projectPath', async () => {
+    await withServer(async (baseUrl) => {
+      const res = await requestJson(baseUrl, 'POST', '/api/codexlens/index/rebuild', {});
+      assert.equal(res.status, 400);
+      assert.ok(res.json.error?.includes('projectPath'));
+    });
+  });
+
+  it('POST /api/codexlens/index/rebuild clears stale index state before syncing', async () => {
+    const projectPath = join(tmpDir, 'rebuild-project');
+    rmSync(projectPath, { recursive: true, force: true });
+    mkdirSync(projectPath, { recursive: true });
+    writeFileSync(join(projectPath, 'alpha.ts'), 'export const alpha = 1;\n', 'utf8');
+    writeFileSync(join(projectPath, 'beta.ts'), 'export const beta = 2;\n', 'utf8');
+
+    await withServer(async (baseUrl) => {
+      const initialRebuild = await requestJson(baseUrl, 'POST', '/api/codexlens/index/rebuild', { projectPath });
+      assert.equal(initialRebuild.status, 200);
+      assert.equal(initialRebuild.json.success, true);
+
+      rmSync(join(projectPath, 'alpha.ts'), { force: true });
+
+      const syncRes = await requestJson(baseUrl, 'POST', '/api/codexlens/index/sync', { projectPath });
+      assert.equal(syncRes.status, 200);
+      assert.equal(syncRes.json.success, true);
+
+      const staleStatus = await requestJson(
+        baseUrl,
+        'GET',
+        `/api/codexlens/index/status?projectPath=${encodeURIComponent(projectPath)}`,
+      );
+      assert.equal(staleStatus.status, 200);
+      assert.equal(staleStatus.json.status.files_tracked, 1);
+      assert.ok(staleStatus.json.status.deleted_chunks > 0);
+
+      const rebuilt = await requestJson(baseUrl, 'POST', '/api/codexlens/index/rebuild', { projectPath });
+      assert.equal(rebuilt.status, 200);
+      assert.equal(rebuilt.json.success, true);
+      assert.equal(JSON.parse(rebuilt.json.syncOutput).files_processed, 1);
+
+      const rebuiltStatus = await requestJson(
+        baseUrl,
+        'GET',
+        `/api/codexlens/index/status?projectPath=${encodeURIComponent(projectPath)}`,
+      );
+      assert.equal(rebuiltStatus.status, 200);
+      assert.equal(rebuiltStatus.json.status.files_tracked, 1);
+      assert.equal(rebuiltStatus.json.status.deleted_chunks, 0);
+    });
+  });
+
+  // ── GET /api/codexlens/env ──────────────────────────────────
+  it('GET /api/codexlens/env returns empty object when no file exists', async () => {
+    await withServer(async (baseUrl) => {
+      const res = await requestJson(baseUrl, 'GET', '/api/codexlens/env');
      assert.equal(res.status, 200);
      assert.equal(res.json.success, true);
-      assert.equal(Array.isArray(res.json.indexes), true);
-
-      const totalSize =
-        typeof res.json.totalSize === 'number' ? res.json.totalSize : res.json.summary?.totalSize;
-      const totalSizeFormatted =
-        typeof res.json.totalSizeFormatted === 'string'
-          ? res.json.totalSizeFormatted
-          : res.json.summary?.totalSizeFormatted;
-
-      assert.equal(typeof totalSize, 'number');
-      assert.equal(typeof totalSizeFormatted, 'string');
-    } finally {
-      await new Promise<void>((resolve) => server.close(() => resolve()));
-    }
+      assert.ok(typeof res.json.env === 'object');
+      assert.equal(res.json.env.CODEXLENS_INDEX_WORKERS, undefined);
+      assert.equal(res.json.defaults.CODEXLENS_INDEX_WORKERS, '2');
+      assert.equal(res.json.defaults.CODEXLENS_MAX_FILE_SIZE, '1000000');
+    });
  });

-  it('GET /api/codexlens/dashboard-init returns aggregated payload', async () => {
-    const broadcasts: any[] = [];
-    const { server, baseUrl } = await createServer(process.cwd(), broadcasts);
-    try {
-      const res = await requestJson(baseUrl, 'GET', '/api/codexlens/dashboard-init');
+  // ── POST /api/codexlens/env ─────────────────────────────────
+  it('POST /api/codexlens/env saves env and GET reads it back', async () => {
+    const envPayload = {
+      CODEXLENS_EMBED_API_URL: 'https://api.example.com/v1',
+      CODEXLENS_EMBED_API_MODEL: 'text-embedding-3-small',
+    };
+
+    await withServer(async (baseUrl) => {
+      const saveRes = await requestJson(baseUrl, 'POST', '/api/codexlens/env', { env: envPayload });
+      assert.equal(saveRes.status, 200);
+      assert.equal(saveRes.json.success, true);
+
+      const getRes = await requestJson(baseUrl, 'GET', '/api/codexlens/env');
+      assert.equal(getRes.status, 200);
+      assert.equal(getRes.json.env.CODEXLENS_EMBED_API_URL, 'https://api.example.com/v1');
+      assert.equal(getRes.json.env.CODEXLENS_EMBED_API_MODEL, 'text-embedding-3-small');
+      assert.equal(getRes.json.defaults.CODEXLENS_EMBED_DIM, '1536');
+    });
+  });
+
+  it('POST /api/codexlens/env rejects missing env field', async () => {
+    await withServer(async (baseUrl) => {
+      const res = await requestJson(baseUrl, 'POST', '/api/codexlens/env', { other: 'value' });
+      assert.equal(res.status, 400);
+      assert.ok(res.json.error?.includes('env'));
+    });
+  });
+
+  // ── GET /api/codexlens/mcp-config ──────────────────────────
+  it('GET /api/codexlens/mcp-config returns mcpServers structure', async () => {
+    await withServer(async (baseUrl) => {
+      const res = await requestJson(baseUrl, 'GET', '/api/codexlens/mcp-config');
      assert.equal(res.status, 200);
-      assert.equal(typeof res.json?.installed, 'boolean');
-      assert.ok(res.json?.config);
-      assert.equal(typeof res.json.config.index_dir, 'string');
-      assert.equal(typeof res.json.config.index_count, 'number');
-      assert.ok(res.json?.semantic);
-    } finally {
-      await new Promise<void>((resolve) => server.close(() => resolve()));
-    }
+      assert.equal(res.json.success, true);
+      assert.ok(res.json.config?.mcpServers?.codexlens);
+      assert.equal(res.json.config.mcpServers.codexlens.command, 'uvx');
+      assert.deepEqual(res.json.config.mcpServers.codexlens.args, ['--from', 'codexlens-search[mcp]', 'codexlens-mcp']);
+      assert.equal(res.json.config.mcpServers.codexlens.env, undefined);
+    });
+  });
+
+  it('GET /api/codexlens/mcp-config filters out empty env values', async () => {
+    const envPayload = {
+      CODEXLENS_EMBED_API_URL: 'https://api.example.com/v1',
+      CODEXLENS_EMBED_API_KEY: '',
+      CODEXLENS_EMBED_API_MODEL: 'text-embedding-3-small',
+    };
+
+    await withServer(async (baseUrl) => {
+      await requestJson(baseUrl, 'POST', '/api/codexlens/env', { env: envPayload });
+
+      const res = await requestJson(baseUrl, 'GET', '/api/codexlens/mcp-config');
+      assert.equal(res.status, 200);
+      const mcpEnv = res.json.config.mcpServers.codexlens.env;
+      assert.equal(mcpEnv.CODEXLENS_EMBED_API_URL, 'https://api.example.com/v1');
+      assert.equal(mcpEnv.CODEXLENS_EMBED_API_MODEL, 'text-embedding-3-small');
+      assert.equal(mcpEnv.CODEXLENS_EMBED_DIM, '1536');
+      assert.equal(mcpEnv.CODEXLENS_EMBED_API_KEY, undefined);
+    });
+  });
+
+  // ── Unknown routes ──────────────────────────────────────────
+  it('unhandled routes return 404', async () => {
+    await withServer(async (baseUrl) => {
+      const res = await requestJson(baseUrl, 'GET', '/api/codexlens/nonexistent');
+      assert.equal(res.status, 404);
+    });
  });
 });