Add comprehensive tests for CLI functionality and CodexLens compatibility

- Introduced tests for stale running fallback in CLI watch functionality to ensure proper handling of saved conversations.
- Added compatibility tests for CodexLens CLI to verify index initialization despite compatibility conflicts.
- Implemented tests for Smart Search MCP usage to validate default settings and path handling.
- Created tests for UV Manager to ensure Python preference handling works as expected.
- Added a detailed guide for CCW/Codex commands and skills, covering core commands, execution modes, and templates.

Author: catlog22

ccw/frontend/src/App.tsx

@@ -12,7 +12,10 @@ import { router } from './router';
 import queryClient from './lib/query-client';
 import type { Locale } from './lib/i18n';
 import { useWorkflowStore } from '@/stores/workflowStore';
-import { useActiveCliExecutions } from '@/hooks/useActiveCliExecutions';
+import { useCliStreamStore } from '@/stores/cliStreamStore';
+import { useExecutionMonitorStore } from '@/stores/executionMonitorStore';
+import { useTerminalPanelStore } from '@/stores/terminalPanelStore';
+import { useActiveCliExecutions, ACTIVE_CLI_EXECUTIONS_QUERY_KEY } from '@/hooks/useActiveCliExecutions';
 import { DialogStyleProvider } from '@/contexts/DialogStyleContext';
 import { initializeCsrfToken } from './lib/api';
 
@@ -55,6 +58,10 @@ function QueryInvalidator() {
   useEffect(() => {
     // Register callback to invalidate all workspace-related queries on workspace switch
     const callback = () => {
+      useCliStreamStore.getState().resetState();
+      useExecutionMonitorStore.getState().resetState();
+      useTerminalPanelStore.getState().resetState();
+      queryClient.invalidateQueries({ queryKey: ACTIVE_CLI_EXECUTIONS_QUERY_KEY });
       queryClient.invalidateQueries({
         predicate: (query) => {
           const queryKey = query.queryKey;

ccw/frontend/src/components/shared/CliStreamMonitor/CliStreamMonitorNew.tsx

@@ -3,14 +3,15 @@
 // ========================================
 // Redesigned CLI streaming monitor with smart parsing and message-based layout
 
-import { useState, useCallback, useMemo } from 'react';
+import { useState, useEffect, useCallback, useMemo } from 'react';
 import { useIntl } from 'react-intl';
 import {
   Terminal,
 } from 'lucide-react';
 import { cn } from '@/lib/utils';
 import { useCliStreamStore, type CliOutputLine } from '@/stores/cliStreamStore';
 import { useActiveCliExecutions } from '@/hooks/useActiveCliExecutions';
+import { useWorkflowStore, selectProjectPath } from '@/stores/workflowStore';
 import { useCliStreamWebSocket } from '@/hooks/useCliStreamWebSocket';
 
 // New layout components
@@ -169,6 +170,7 @@ export function CliStreamMonitorNew({ isOpen, onClose }: CliStreamMonitorNewProp
   const executions = useCliStreamStore((state) => state.executions);
   const currentExecutionId = useCliStreamStore((state) => state.currentExecutionId);
   const removeExecution = useCliStreamStore((state) => state.removeExecution);
+  const projectPath = useWorkflowStore(selectProjectPath);
 
   // Active execution sync
   const { isLoading: isSyncing, refetch } = useActiveCliExecutions(isOpen);
@@ -221,6 +223,12 @@ export function CliStreamMonitorNew({ isOpen, onClose }: CliStreamMonitorNewProp
     return filtered;
   }, [messages, filter, searchQuery]);
 
+  useEffect(() => {
+    setSearchQuery('');
+    setFilter('all');
+    setViewMode('preview');
+  }, [projectPath]);
+
   // Copy message content
   const handleCopy = useCallback(async (content: string) => {
     try {

ccw/frontend/src/components/shared/CliStreamMonitorLegacy.tsx

@@ -25,6 +25,7 @@ import { Badge } from '@/components/ui/Badge';
 import { LogBlockList } from '@/components/shared/LogBlock';
 import { useCliStreamStore, type CliOutputLine } from '@/stores/cliStreamStore';
 import { useActiveCliExecutions } from '@/hooks/useActiveCliExecutions';
+import { useWorkflowStore, selectProjectPath } from '@/stores/workflowStore';
 import { useCliStreamWebSocket } from '@/hooks/useCliStreamWebSocket';
 
 // New components for Tab + JSON Cards
@@ -186,6 +187,7 @@ export function CliStreamMonitor({ isOpen, onClose }: CliStreamMonitorProps) {
   const setCurrentExecution = useCliStreamStore((state) => state.setCurrentExecution);
   const removeExecution = useCliStreamStore((state) => state.removeExecution);
   const markExecutionClosedByUser = useCliStreamStore((state) => state.markExecutionClosedByUser);
+  const projectPath = useWorkflowStore(selectProjectPath);
 
   // Active execution sync
   const { isLoading: isSyncing, refetch } = useActiveCliExecutions(isOpen);
@@ -214,6 +216,13 @@ export function CliStreamMonitor({ isOpen, onClose }: CliStreamMonitorProps) {
     }
   }, [executions, currentExecutionId, autoScroll, isUserScrolling]);
 
+  useEffect(() => {
+    setSearchQuery('');
+    setAutoScroll(true);
+    setIsUserScrolling(false);
+    setViewMode('list');
+  }, [projectPath]);
+
   // Handle scroll to detect user scrolling (with debounce for performance)
   const handleScrollRef = useRef<NodeJS.Timeout | null>(null);
   const handleScroll = useCallback(() => {

ccw/frontend/src/hooks/useActiveCliExecutions.test.tsx

@@ -0,0 +1,288 @@
+// ========================================
+// useActiveCliExecutions Hook Tests
+// ========================================
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { renderHook, waitFor } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import * as React from 'react';
+import * as api from '@/lib/api';
+import { useActiveCliExecutions } from './useActiveCliExecutions';
+
+const mockProjectState = vi.hoisted(() => ({
+  projectPath: '/test/project',
+}));
+
+const mockStoreState = vi.hoisted(() => ({
+  executions: {} as Record<string, any>,
+  cleanupUserClosedExecutions: vi.fn(),
+  isExecutionClosedByUser: vi.fn(() => false),
+  removeExecution: vi.fn(),
+  upsertExecution: vi.fn(),
+  setCurrentExecution: vi.fn(),
+}));
+
+const mockUseCliStreamStore = vi.hoisted(() => {
+  const store = vi.fn();
+  Object.assign(store, {
+    getState: vi.fn(() => mockStoreState),
+  });
+  return store;
+});
+
+vi.mock('@/stores/cliStreamStore', () => ({
+  useCliStreamStore: mockUseCliStreamStore,
+}));
+
+vi.mock('@/stores/workflowStore', () => ({
+  useWorkflowStore: vi.fn((selector?: (state: { projectPath: string }) => unknown) => (
+    selector
+      ? selector({ projectPath: mockProjectState.projectPath })
+      : { projectPath: mockProjectState.projectPath }
+  )),
+  selectProjectPath: (state: { projectPath: string }) => state.projectPath,
+}));
+
+vi.mock('@/lib/api', async () => {
+  const actual = await vi.importActual<typeof import('@/lib/api')>('@/lib/api');
+  return {
+    ...actual,
+    fetchExecutionDetail: vi.fn(),
+  };
+});
+
+const fetchMock = vi.fn();
+
+function createTestQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false,
+      },
+    },
+  });
+}
+
+function createWrapper() {
+  const queryClient = createTestQueryClient();
+
+  return ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+}
+
+function createActiveResponse(executions: Array<Record<string, unknown>>) {
+  return {
+    ok: true,
+    statusText: 'OK',
+    json: vi.fn().mockResolvedValue({ executions }),
+  };
+}
+
+describe('useActiveCliExecutions', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.stubGlobal('fetch', fetchMock);
+
+    mockProjectState.projectPath = '/test/project';
+    mockStoreState.executions = {};
+    mockStoreState.cleanupUserClosedExecutions.mockReset();
+    mockStoreState.isExecutionClosedByUser.mockReset();
+    mockStoreState.isExecutionClosedByUser.mockReturnValue(false);
+    mockStoreState.removeExecution.mockReset();
+    mockStoreState.upsertExecution.mockReset();
+    mockStoreState.setCurrentExecution.mockReset();
+    (mockUseCliStreamStore as any).getState.mockReset();
+    (mockUseCliStreamStore as any).getState.mockImplementation(() => mockStoreState);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('requests active executions with scoped project path', async () => {
+    fetchMock.mockResolvedValue(createActiveResponse([]));
+
+    const { result } = renderHook(() => useActiveCliExecutions(true, 60_000), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(() => {
+      expect(result.current.data).toEqual([]);
+    });
+
+    expect(fetchMock).toHaveBeenCalledWith('/api/cli/active?path=%2Ftest%2Fproject');
+  });
+
+  it('filters stale recovered running executions when saved detail is newer', async () => {
+    const startTime = 1_741_392_000_000;
+    mockStoreState.executions = {
+      'exec-stale': {
+        tool: 'codex',
+        mode: 'analysis',
+        status: 'running',
+        output: [],
+        startTime,
+        recovered: true,
+      },
+    };
+
+    fetchMock.mockResolvedValue(createActiveResponse([
+      {
+        id: 'exec-stale',
+        tool: 'codex',
+        mode: 'analysis',
+        status: 'running',
+        output: '[响应] stale output',
+        startTime,
+      },
+    ]));
+
+    vi.mocked(api.fetchExecutionDetail).mockResolvedValue({
+      id: 'exec-stale',
+      tool: 'codex',
+      mode: 'analysis',
+      turns: [],
+      turn_count: 1,
+      created_at: new Date(startTime - 2_000).toISOString(),
+      updated_at: new Date(startTime + 2_000).toISOString(),
+    } as any);
+
+    const { result } = renderHook(() => useActiveCliExecutions(true, 60_000), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(() => {
+      expect(result.current.data).toEqual([]);
+    });
+
+    expect(api.fetchExecutionDetail).toHaveBeenCalledWith('exec-stale', '/test/project');
+    expect(mockStoreState.removeExecution).toHaveBeenCalledWith('exec-stale');
+    expect(mockStoreState.upsertExecution).not.toHaveBeenCalled();
+  });
+
+  it('removes recovered running executions that are absent from the current workspace active list', async () => {
+    mockStoreState.executions = {
+      'exec-old-workspace': {
+        tool: 'codex',
+        mode: 'analysis',
+        status: 'running',
+        output: [],
+        startTime: 1_741_394_000_000,
+        recovered: true,
+      },
+    };
+
+    fetchMock.mockResolvedValue(createActiveResponse([]));
+
+    const { result } = renderHook(() => useActiveCliExecutions(true, 60_000), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(() => {
+      expect(result.current.data).toEqual([]);
+    });
+
+    expect(mockStoreState.removeExecution).toHaveBeenCalledWith('exec-old-workspace');
+    expect(api.fetchExecutionDetail).not.toHaveBeenCalled();
+  });
+
+  it('reselects the best remaining execution when current selection becomes invalid', async () => {
+    mockStoreState.executions = {
+      'exec-running': {
+        tool: 'codex',
+        mode: 'analysis',
+        status: 'running',
+        output: [],
+        startTime: 1_741_395_000_000,
+        recovered: false,
+      },
+      'exec-completed': {
+        tool: 'codex',
+        mode: 'analysis',
+        status: 'completed',
+        output: [],
+        startTime: 1_741_394_000_000,
+        recovered: false,
+      },
+    };
+
+    (mockUseCliStreamStore as any).getState.mockImplementation(() => ({
+      ...mockStoreState,
+      currentExecutionId: 'exec-missing',
+    }));
+    fetchMock.mockResolvedValue(createActiveResponse([]));
+
+    const { result } = renderHook(() => useActiveCliExecutions(true, 60_000), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(() => {
+      expect(result.current.data).toEqual([]);
+    });
+
+    expect(mockStoreState.setCurrentExecution).toHaveBeenCalledWith('exec-running');
+  });
+
+  it('clears current selection when no executions remain after sync', async () => {
+    mockStoreState.executions = {};
+    (mockUseCliStreamStore as any).getState.mockImplementation(() => ({
+      ...mockStoreState,
+      currentExecutionId: 'exec-missing',
+    }));
+    fetchMock.mockResolvedValue(createActiveResponse([]));
+
+    const { result } = renderHook(() => useActiveCliExecutions(true, 60_000), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(() => {
+      expect(result.current.data).toEqual([]);
+    });
+
+    expect(mockStoreState.setCurrentExecution).toHaveBeenCalledWith(null);
+  });
+
+  it('keeps running executions when saved detail is older than active start time', async () => {
+    const startTime = 1_741_393_000_000;
+
+    fetchMock.mockResolvedValue(createActiveResponse([
+      {
+        id: 'exec-live',
+        tool: 'codex',
+        mode: 'analysis',
+        status: 'running',
+        output: '[响应] live output',
+        startTime,
+      },
+    ]));
+
+    vi.mocked(api.fetchExecutionDetail).mockResolvedValue({
+      id: 'exec-live',
+      tool: 'codex',
+      mode: 'analysis',
+      turns: [],
+      turn_count: 1,
+      created_at: new Date(startTime - 20_000).toISOString(),
+      updated_at: new Date(startTime - 10_000).toISOString(),
+    } as any);
+
+    const { result } = renderHook(() => useActiveCliExecutions(true, 60_000), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(() => {
+      expect(result.current.data?.map((execution) => execution.id)).toEqual(['exec-live']);
+    });
+
+    expect(mockStoreState.removeExecution).not.toHaveBeenCalled();
+    expect(mockStoreState.upsertExecution).toHaveBeenCalledWith(
+      'exec-live',
+      expect.objectContaining({
+        status: 'running',
+        recovered: true,
+      })
+    );
+    expect(mockStoreState.setCurrentExecution).toHaveBeenCalledWith('exec-live');
+  });
+});