claude-code-workflow 7.2.5 → 7.2.7

package/ccw/dist/tools/smart-search.js

@@ -21,13 +21,14 @@ import { z } from 'zod';
 import { spawn, execSync } from 'child_process';
 import { existsSync, readFileSync, statSync } from 'fs';
 import { dirname, join, resolve } from 'path';
-import { ensureReady as ensureCodexLensReady, ensureLiteLLMEmbedderReady, executeCodexLens, getVenvPythonPath, } from './codex-lens.js';
+import { ensureReady as ensureCodexLensReady, checkSemanticStatus, ensureLiteLLMEmbedderReady, executeCodexLens, getVenvPythonPath, } from './codex-lens.js';
 import { getProjectRoot } from '../utils/path-validator.js';
 import { getCodexLensDataDir } from '../utils/codexlens-path.js';
 import { EXEC_TIMEOUTS } from '../utils/exec-constants.js';
 import { generateRotationEndpoints } from '../config/litellm-api-config-manager.js';
 // Timing utilities for performance analysis
 const TIMING_ENABLED = process.env.SMART_SEARCH_TIMING === '1' || process.env.DEBUG?.includes('timing');
+const SEARCH_OUTPUT_MODES = ['full', 'files_only', 'count', 'ace'];
 function createTimer() {
     const startTime = performance.now();
     const marks = [];
@@ -61,7 +62,7 @@ const ParamsSchema = z.object({
     query: z.string().optional().describe('Content search query (for action="search")'),
     pattern: z.string().optional().describe('Glob pattern for path matching (for action="find_files")'),
     mode: z.enum(['fuzzy', 'semantic']).default('fuzzy'),
-    output_mode: z.enum(['full', 'files_only', 'count']).default('full'),
+    output_mode: z.enum(SEARCH_OUTPUT_MODES).default('ace'),
     path: z.string().optional(),
     paths: z.array(z.string()).default([]),
     contextLines: z.number().default(0),
@@ -221,6 +222,7 @@ function readCodexLensSettingsSnapshot() {
         return {
             embedding_backend: normalizeEmbeddingBackend(typeof embedding.backend === 'string' ? embedding.backend : undefined),
             embedding_model: typeof embedding.model === 'string' ? embedding.model : undefined,
+            embedding_auto_embed_missing: typeof embedding.auto_embed_missing === 'boolean' ? embedding.auto_embed_missing : undefined,
             reranker_enabled: typeof reranker.enabled === 'boolean' ? reranker.enabled : undefined,
             reranker_backend: typeof reranker.backend === 'string' ? reranker.backend : undefined,
             reranker_model: typeof reranker.model === 'string' ? reranker.model : undefined,
@@ -244,6 +246,13 @@ function stripAnsi(str) {
 }
 /** Default maximum content length to return (avoid excessive output) */
 const DEFAULT_MAX_CONTENT_LENGTH = 200;
+const CODEX_LENS_FTS_COMPATIBILITY_PATTERNS = [
+    /UsageError:\s*Got unexpected extra arguments?/i,
+    /Option ['"]--method['"] does not take a value/i,
+    /TyperArgument\.make_metavar\(\) takes 1 positional argument but 2 were given/i,
+];
+let codexLensFtsBackendBroken = false;
+const autoEmbedJobs = new Map();
 /**
  * Truncate content to specified length with ellipsis
  * @param content - The content to truncate
@@ -348,12 +357,89 @@ function parseCodexLensJsonOutput(output) {
     }
     return null;
 }
+function isValidRegexPattern(pattern) {
+    try {
+        new RegExp(pattern);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function resolveRipgrepQueryMode(query, regex = true, tokenize = true) {
+    const tokens = tokenize ? tokenizeQuery(query) : [query];
+    if (!regex) {
+        return {
+            regex: false,
+            tokenize,
+            tokens,
+            literalFallback: false,
+        };
+    }
+    const invalidTokens = tokens.filter((token) => token.length > 0 && !isValidRegexPattern(token));
+    if (invalidTokens.length === 0) {
+        return {
+            regex: true,
+            tokenize,
+            tokens,
+            literalFallback: false,
+        };
+    }
+    const preview = truncateContent(invalidTokens[0], 40);
+    return {
+        regex: false,
+        tokenize,
+        tokens,
+        literalFallback: true,
+        warning: invalidTokens.length === 1
+            ? `Query token "${preview}" is not a valid regular expression. Falling back to literal ripgrep matching.`
+            : 'Query contains invalid regular expression tokens. Falling back to literal ripgrep matching.',
+    };
+}
+function isCodexLensCliCompatibilityError(error) {
+    if (!error) {
+        return false;
+    }
+    const cleanError = stripAnsi(error);
+    return CODEX_LENS_FTS_COMPATIBILITY_PATTERNS.some((pattern) => pattern.test(cleanError));
+}
+function noteCodexLensFtsCompatibility(error) {
+    if (!isCodexLensCliCompatibilityError(error)) {
+        return false;
+    }
+    codexLensFtsBackendBroken = true;
+    return true;
+}
+function summarizeBackendError(error) {
+    const cleanError = stripAnsi(error || '').trim();
+    if (!cleanError) {
+        return 'unknown error';
+    }
+    if (isCodexLensCliCompatibilityError(cleanError)) {
+        return 'CodexLens exact search CLI is incompatible with the current Typer/Click runtime';
+    }
+    const regexSummary = cleanError.match(/error:\s*([^\r\n]+)/i);
+    if (/regex parse error/i.test(cleanError) && regexSummary?.[1]) {
+        return `invalid regular expression (${regexSummary[1].trim()})`;
+    }
+    const usageSummary = cleanError.match(/UsageError:\s*([^\r\n]+)/i);
+    if (usageSummary?.[1]) {
+        return usageSummary[1].trim();
+    }
+    const firstMeaningfulLine = cleanError
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find((line) => line && !line.startsWith('│') && !line.startsWith('┌') && !line.startsWith('└'));
+    return truncateContent(firstMeaningfulLine || cleanError, 180);
+}
 function mapCodexLensSemanticMatches(data, scope, maxContentLength) {
     return filterResultsToTargetFile(data.map((item) => {
         const rawScore = item.score || 0;
         const similarityScore = rawScore > 0 ? 1 / (1 + rawScore) : 1;
         return {
             file: item.path || item.file,
+            line: typeof item.line === 'number' ? item.line : undefined,
+            column: typeof item.column === 'number' ? item.column : undefined,
             score: similarityScore,
             content: truncateContent(item.content || item.excerpt, maxContentLength),
             symbol: item.symbol || null,
@@ -399,11 +485,11 @@ function hasCentralizedVectorArtifacts(indexRoot) {
 }
 function collectBackendError(errors, backendName, backendResult) {
     if (backendResult.status === 'rejected') {
-        errors.push(`${backendName}: ${String(backendResult.reason)}`);
+        errors.push(`${backendName}: ${summarizeBackendError(String(backendResult.reason))}`);
         return;
     }
     if (!backendResult.value.success) {
-        errors.push(`${backendName}: ${backendResult.value.error || 'unknown error'}`);
+        errors.push(`${backendName}: ${summarizeBackendError(backendResult.value.error)}`);
     }
 }
 function mergeWarnings(...warnings) {
@@ -412,6 +498,75 @@ function mergeWarnings(...warnings) {
             .map((warning) => warning.trim()))];
     return merged.length > 0 ? merged.join(' | ') : undefined;
 }
+function mergeNotes(...notes) {
+    const merged = [...new Set(notes
+            .filter((note) => typeof note === 'string' && note.trim().length > 0)
+            .map((note) => note.trim()))];
+    return merged.length > 0 ? merged.join(' | ') : undefined;
+}
+function mergeSuggestions(...groups) {
+    const merged = new Map();
+    for (const group of groups) {
+        for (const suggestion of group ?? []) {
+            if (!merged.has(suggestion.command)) {
+                merged.set(suggestion.command, suggestion);
+            }
+        }
+    }
+    return merged.size > 0 ? [...merged.values()] : undefined;
+}
+function formatSmartSearchCommand(action, pathValue, extraParams = {}) {
+    const normalizedPath = pathValue.replace(/\\/g, '/');
+    const args = [`action=${JSON.stringify(action)}`, `path=${JSON.stringify(normalizedPath)}`];
+    for (const [key, value] of Object.entries(extraParams)) {
+        if (value === undefined) {
+            continue;
+        }
+        args.push(`${key}=${JSON.stringify(value)}`);
+    }
+    return `smart_search(${args.join(', ')})`;
+}
+function isAutoEmbedMissingEnabled(config) {
+    return config?.embedding_auto_embed_missing !== false;
+}
+function buildIndexSuggestions(indexStatus, scope) {
+    const suggestions = [];
+    if (!indexStatus.indexed) {
+        suggestions.push({
+            title: 'Initialize index',
+            command: formatSmartSearchCommand('init', scope.workingDirectory),
+            reason: 'No CodexLens index exists for this path yet.',
+        });
+        suggestions.push({
+            title: 'Check index status',
+            command: formatSmartSearchCommand('status', scope.workingDirectory),
+            reason: 'Verify whether the target path is mapped to the expected CodexLens project root.',
+        });
+        return suggestions;
+    }
+    if (!indexStatus.has_embeddings) {
+        suggestions.push({
+            title: 'Generate embeddings',
+            command: formatSmartSearchCommand('embed', scope.workingDirectory),
+            reason: 'The index exists, but semantic/vector retrieval is unavailable until embeddings are generated.',
+        });
+    }
+    else if ((indexStatus.embeddings_coverage_percent ?? 0) < 50) {
+        suggestions.push({
+            title: 'Rebuild embeddings',
+            command: formatSmartSearchCommand('embed', scope.workingDirectory, { force: true }),
+            reason: `Embedding coverage is only ${(indexStatus.embeddings_coverage_percent ?? 0).toFixed(1)}%, so semantic search quality is degraded.`,
+        });
+    }
+    if (indexStatus.warning?.includes('Failed to parse index status')) {
+        suggestions.push({
+            title: 'Re-check status',
+            command: formatSmartSearchCommand('status', scope.workingDirectory),
+            reason: 'The index health payload could not be parsed cleanly.',
+        });
+    }
+    return suggestions.length > 0 ? suggestions : undefined;
+}
 /**
  * Check if CodexLens index exists for current directory
  * @param path - Directory path to check
@@ -437,12 +592,15 @@ async function checkIndexStatus(path = '.') {
                     ...settingsConfig,
                     config_file: configData.config_file,
                     index_dir: configData.index_dir,
-                    embedding_backend: configData.embedding_backend,
-                    embedding_model: configData.embedding_model,
-                    reranker_enabled: configData.reranker_enabled,
-                    reranker_backend: configData.reranker_backend,
-                    reranker_model: configData.reranker_model,
-                    reranker_top_k: configData.reranker_top_k,
+                    embedding_backend: normalizeEmbeddingBackend(configData.embedding_backend) ?? settingsConfig.embedding_backend,
+                    embedding_model: typeof configData.embedding_model === 'string' ? configData.embedding_model : settingsConfig.embedding_model,
+                    embedding_auto_embed_missing: typeof configData.embedding_auto_embed_missing === 'boolean'
+                        ? configData.embedding_auto_embed_missing
+                        : settingsConfig.embedding_auto_embed_missing,
+                    reranker_enabled: typeof configData.reranker_enabled === 'boolean' ? configData.reranker_enabled : settingsConfig.reranker_enabled,
+                    reranker_backend: typeof configData.reranker_backend === 'string' ? configData.reranker_backend : settingsConfig.reranker_backend,
+                    reranker_model: typeof configData.reranker_model === 'string' ? configData.reranker_model : settingsConfig.reranker_model,
+                    reranker_top_k: typeof configData.reranker_top_k === 'number' ? configData.reranker_top_k : settingsConfig.reranker_top_k,
                 };
             }
             catch {
@@ -641,6 +799,7 @@ function checkToolAvailability(toolName) {
  */
 function buildRipgrepCommand(params) {
     const { query, paths = ['.'], contextLines = 0, maxResults = 10, includeHidden = false, regex = false, caseSensitive = true, tokenize = true } = params;
+    const queryMode = resolveRipgrepQueryMode(query, regex, tokenize);
     const args = [
         '-n',
         '--color=never',
@@ -663,13 +822,12 @@ function buildRipgrepCommand(params) {
     if (includeHidden) {
         args.push('--hidden');
     }
-    // Tokenize query for multi-word OR matching
-    const tokens = tokenize ? tokenizeQuery(query) : [query];
+    const { tokens } = queryMode;
     if (tokens.length > 1) {
         // Multi-token: use multiple -e patterns (OR matching)
         // Each token is escaped for regex safety unless regex mode is enabled
         for (const token of tokens) {
-            if (regex) {
+            if (queryMode.regex) {
                 args.push('-e', token);
             }
             else {
@@ -681,7 +839,7 @@ function buildRipgrepCommand(params) {
     }
     else {
         // Single token or no tokenization: use original behavior
-        if (regex) {
+        if (queryMode.regex) {
             args.push('-e', query);
         }
         else {
@@ -689,7 +847,123 @@ function buildRipgrepCommand(params) {
         }
     }
     args.push(...paths);
-    return { command: 'rg', args, tokens };
+    return {
+        command: 'rg',
+        args,
+        tokens,
+        warning: queryMode.warning,
+        literalFallback: queryMode.literalFallback,
+        regex: queryMode.regex,
+    };
+}
+function finalizeRipgrepChunk(accumulator) {
+    if (!accumulator || accumulator.matchCount === 0 || accumulator.chunkLines.length === 0) {
+        return null;
+    }
+    const firstLine = accumulator.chunkLines[0]?.line ?? accumulator.firstMatchLine ?? 1;
+    const lastLine = accumulator.chunkLines[accumulator.chunkLines.length - 1]?.line ?? accumulator.firstMatchLine ?? firstLine;
+    return {
+        file: accumulator.file,
+        line: accumulator.firstMatchLine ?? firstLine,
+        endLine: lastLine,
+        column: accumulator.firstMatchColumn ?? 1,
+        content: accumulator.chunkLines.map((line) => line.text).join('\n').trim(),
+        chunkLines: [...accumulator.chunkLines],
+    };
+}
+function parseRipgrepJsonResults(stdout, effectiveLimit) {
+    const allResults = [];
+    const activeChunks = new Map();
+    const lines = stdout.split('\n').filter((line) => line.trim());
+    let resultLimitReached = false;
+    const flushChunk = (file) => {
+        const finalized = finalizeRipgrepChunk(activeChunks.get(file));
+        activeChunks.delete(file);
+        if (!finalized) {
+            return;
+        }
+        allResults.push(finalized);
+        if (allResults.length >= effectiveLimit) {
+            resultLimitReached = true;
+        }
+    };
+    for (const line of lines) {
+        if (resultLimitReached) {
+            break;
+        }
+        try {
+            const item = JSON.parse(line);
+            if (item.type !== 'match' && item.type !== 'context' && item.type !== 'end') {
+                continue;
+            }
+            const file = item.data?.path?.text;
+            if (!file) {
+                continue;
+            }
+            if (item.type === 'end') {
+                flushChunk(file);
+                continue;
+            }
+            const lineNumber = typeof item.data?.line_number === 'number' ? item.data.line_number : undefined;
+            const rawText = typeof item.data?.lines?.text === 'string'
+                ? item.data.lines.text.replace(/\r?\n$/, '')
+                : '';
+            if (lineNumber === undefined) {
+                continue;
+            }
+            let current = activeChunks.get(file);
+            const isContiguous = current && current.lastLine !== undefined && lineNumber <= current.lastLine + 1;
+            if (!current || !isContiguous) {
+                if (current) {
+                    flushChunk(file);
+                    if (resultLimitReached) {
+                        break;
+                    }
+                }
+                current = {
+                    file,
+                    chunkLines: [],
+                    matchCount: 0,
+                };
+                activeChunks.set(file, current);
+            }
+            const previousLine = current.chunkLines[current.chunkLines.length - 1];
+            const duplicateLine = previousLine && previousLine.line === lineNumber && previousLine.text === rawText;
+            if (!duplicateLine) {
+                current.chunkLines.push({
+                    line: lineNumber,
+                    text: rawText,
+                    isMatch: item.type === 'match',
+                });
+            }
+            else if (item.type === 'match') {
+                previousLine.isMatch = true;
+            }
+            if (item.type === 'match') {
+                current.matchCount += 1;
+                if (current.firstMatchLine === undefined) {
+                    current.firstMatchLine = lineNumber;
+                    current.firstMatchColumn =
+                        item.data.submatches && item.data.submatches[0]
+                            ? item.data.submatches[0].start + 1
+                            : 1;
+                }
+            }
+            current.lastLine = lineNumber;
+        }
+        catch {
+            continue;
+        }
+    }
+    if (!resultLimitReached) {
+        for (const file of [...activeChunks.keys()]) {
+            flushChunk(file);
+            if (resultLimitReached) {
+                break;
+            }
+        }
+    }
+    return { results: allResults.slice(0, effectiveLimit), resultLimitReached };
 }
 function normalizeEmbeddingBackend(backend) {
     if (!backend) {
@@ -774,50 +1048,63 @@ function extractEmbedJsonLine(stdout) {
         .filter((line) => !line.startsWith(EMBED_PROGRESS_PREFIX));
     return [...lines].reverse().find((line) => line.startsWith('{') && line.endsWith('}'));
 }
-async function executeEmbeddingsViaPython(params) {
+function buildEmbeddingPythonCode(params) {
     const { projectPath, backend, model, force, maxWorkers, endpoints = [] } = params;
-    const pythonCode = `
-import json
-import sys
-from pathlib import Path
-from codexlens.storage.registry import RegistryStore
-from codexlens.cli.embedding_manager import generate_dense_embeddings_centralized
-
-target_path = Path(r"__PROJECT_PATH__").expanduser().resolve()
-backend = __BACKEND__
-model = __MODEL__
-force = __FORCE__
-max_workers = __MAX_WORKERS__
-endpoints = json.loads(r'''__ENDPOINTS_JSON__''')
-
-def progress_update(message: str):
-    print("__CCW_EMBED_PROGRESS__" + str(message), flush=True)
-
-registry = RegistryStore()
-registry.initialize()
-try:
-    project = registry.get_project(target_path)
-    if project is None:
-        print(json.dumps({"success": False, "error": f"No index found for: {target_path}"}), flush=True)
-        sys.exit(1)
-
-    index_root = Path(project.index_root)
-    result = generate_dense_embeddings_centralized(
-        index_root,
-        embedding_backend=backend,
-        model_profile=model,
-        force=force,
-        use_gpu=True,
-        max_workers=max_workers,
-        endpoints=endpoints if endpoints else None,
-        progress_callback=progress_update,
-    )
-
-    print(json.dumps(result), flush=True)
-    if not result.get("success"):
-        sys.exit(1)
-finally:
-    registry.close()
+    return `
+import json
+import sys
+from pathlib import Path
+from codexlens.storage.path_mapper import PathMapper
+from codexlens.storage.registry import RegistryStore
+from codexlens.cli.embedding_manager import generate_dense_embeddings_centralized
+
+target_path = Path(r"__PROJECT_PATH__").expanduser().resolve()
+backend = __BACKEND__
+model = __MODEL__
+force = __FORCE__
+max_workers = __MAX_WORKERS__
+endpoints = json.loads(r'''__ENDPOINTS_JSON__''')
+
+def progress_update(message: str):
+    print("__CCW_EMBED_PROGRESS__" + str(message), flush=True)
+
+registry = RegistryStore()
+registry.initialize()
+try:
+    project = registry.get_project(target_path)
+    index_root = None
+    if project is not None:
+        index_root = Path(project.index_root)
+    else:
+        mapper = PathMapper()
+        index_db = mapper.source_to_index_db(target_path)
+        if index_db.exists():
+            index_root = index_db.parent
+        else:
+            nearest = registry.find_nearest_index(target_path)
+            if nearest is not None:
+                index_root = Path(nearest.index_path).parent
+
+    if index_root is None:
+        print(json.dumps({"success": False, "error": f"No index found for: {target_path}"}), flush=True)
+        sys.exit(1)
+
+    result = generate_dense_embeddings_centralized(
+        index_root,
+        embedding_backend=backend,
+        model_profile=model,
+        force=force,
+        use_gpu=True,
+        max_workers=max_workers,
+        endpoints=endpoints if endpoints else None,
+        progress_callback=progress_update,
+    )
+
+    print(json.dumps(result), flush=True)
+    if not result.get("success"):
+        sys.exit(1)
+finally:
+    registry.close()
 `
         .replace('__PROJECT_PATH__', projectPath.replace(/\\/g, '\\\\'))
         .replace('__BACKEND__', backend ? JSON.stringify(backend) : 'None')
@@ -825,6 +1112,90 @@ finally:
         .replace('__FORCE__', force ? 'True' : 'False')
         .replace('__MAX_WORKERS__', typeof maxWorkers === 'number' ? String(Math.max(1, Math.floor(maxWorkers))) : 'None')
         .replace('__ENDPOINTS_JSON__', JSON.stringify(endpoints).replace(/\\/g, '\\\\').replace(/'''/g, "\\'\\'\\'"));
+}
+function spawnBackgroundEmbeddingsViaPython(params) {
+    const { projectPath, backend, model } = params;
+    try {
+        const child = spawn(getVenvPythonPath(), ['-c', buildEmbeddingPythonCode(params)], {
+            cwd: projectPath,
+            shell: false,
+            detached: true,
+            stdio: 'ignore',
+            windowsHide: true,
+            env: { ...process.env, PYTHONIOENCODING: 'utf-8' },
+        });
+        autoEmbedJobs.set(projectPath, {
+            startedAt: Date.now(),
+            backend,
+            model,
+        });
+        const cleanup = () => {
+            autoEmbedJobs.delete(projectPath);
+        };
+        child.on('error', cleanup);
+        child.on('close', cleanup);
+        child.unref();
+        return { success: true };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+async function maybeStartBackgroundAutoEmbed(scope, indexStatus) {
+    if (!indexStatus.indexed || indexStatus.has_embeddings) {
+        return {};
+    }
+    if (!isAutoEmbedMissingEnabled(indexStatus.config)) {
+        return {
+            note: 'Automatic embedding warmup is disabled by CODEXLENS_AUTO_EMBED_MISSING=false.',
+        };
+    }
+    if (autoEmbedJobs.has(scope.workingDirectory)) {
+        return {
+            note: 'Background embedding build is already running for this path.',
+        };
+    }
+    const backend = normalizeEmbeddingBackend(indexStatus.config?.embedding_backend) ?? 'fastembed';
+    const model = indexStatus.config?.embedding_model?.trim() || undefined;
+    const semanticStatus = await checkSemanticStatus();
+    if (!semanticStatus.available) {
+        return {
+            warning: 'Automatic embedding warmup skipped because semantic dependencies are not ready.',
+        };
+    }
+    if (backend === 'litellm' && !semanticStatus.litellmAvailable) {
+        return {
+            warning: 'Automatic embedding warmup skipped because the LiteLLM embedder is not ready.',
+        };
+    }
+    const endpoints = resolveEmbeddingEndpoints(backend);
+    const configuredApiMaxWorkers = indexStatus.config?.api_max_workers;
+    const effectiveApiMaxWorkers = typeof configuredApiMaxWorkers === 'number'
+        ? Math.max(1, Math.floor(configuredApiMaxWorkers))
+        : resolveApiWorkerCount(undefined, backend, endpoints);
+    const spawned = spawnBackgroundEmbeddingsViaPython({
+        projectPath: scope.workingDirectory,
+        backend,
+        model,
+        force: false,
+        maxWorkers: effectiveApiMaxWorkers,
+        endpoints,
+    });
+    if (!spawned.success) {
+        return {
+            warning: `Automatic embedding warmup could not start: ${spawned.error}`,
+        };
+    }
+    return {
+        note: 'Background embedding build started for this path. Re-run semantic search shortly for vector results.',
+    };
+}
+async function executeEmbeddingsViaPython(params) {
+    const { projectPath } = params;
+    const pythonCode = buildEmbeddingPythonCode(params);
     return await new Promise((resolve) => {
         const child = spawn(getVenvPythonPath(), ['-c', pythonCode], {
             cwd: projectPath,
@@ -1040,6 +1411,7 @@ async function executeStatusAction(params) {
         // Embedding backend info
         const embeddingType = cfg.embedding_backend === 'litellm' ? 'API' : 'Local';
         statusParts.push(`Embedding: ${embeddingType} (${cfg.embedding_model || 'default'})`);
+        statusParts.push(`Auto Embed Missing: ${isAutoEmbedMissingEnabled(cfg) ? 'on' : 'off'}`);
         if (typeof cfg.api_max_workers === 'number') {
             statusParts.push(`API Workers: ${cfg.api_max_workers}`);
         }
@@ -1062,6 +1434,12 @@ async function executeStatusAction(params) {
         success: true,
         status: indexStatus,
         message: indexStatus.warning || statusParts.join(' | '),
+        metadata: {
+            action: 'status',
+            path: scope.workingDirectory,
+            warning: indexStatus.warning,
+            suggestions: buildIndexSuggestions(indexStatus, scope),
+        },
     };
 }
 /**
@@ -1180,7 +1558,7 @@ async function executeWatchAction(params) {
  * Runs both exact (FTS) and ripgrep searches in parallel, merges and ranks results
  */
 async function executeFuzzyMode(params) {
-    const { query, path = '.', maxResults = 5, extraFilesCount = 10, codeOnly = true, withDoc = false, excludeExtensions } = params;
+    const { query, path = '.', maxResults = 5, extraFilesCount = 10, codeOnly = true, withDoc = false, excludeExtensions, regex = true, tokenize = true } = params;
     // withDoc overrides codeOnly
     const effectiveCodeOnly = withDoc ? false : codeOnly;
     if (!query) {
@@ -1190,12 +1568,34 @@ async function executeFuzzyMode(params) {
         };
     }
     const timer = createTimer();
+    const ftsWasBroken = codexLensFtsBackendBroken;
+    const ripgrepQueryMode = resolveRipgrepQueryMode(query, regex, tokenize);
+    const fuzzyWarnings = [];
+    let skipExactReason;
+    if (ripgrepQueryMode.literalFallback) {
+        skipExactReason = 'Skipped CodexLens FTS backend for a literal code-pattern query; using ripgrep literal matching.';
+    }
+    else if (codexLensFtsBackendBroken) {
+        skipExactReason = 'CodexLens FTS backend disabled for this process due to CLI compatibility errors.';
+    }
     // Run both searches in parallel
     const [ftsResult, ripgrepResult] = await Promise.allSettled([
-        executeCodexLensExactMode(params),
+        skipExactReason
+            ? Promise.resolve({ success: false, error: skipExactReason })
+            : executeCodexLensExactMode(params),
         executeRipgrepMode(params),
     ]);
     timer.mark('parallel_search');
+    if (!skipExactReason && !ftsWasBroken && codexLensFtsBackendBroken) {
+        fuzzyWarnings.push('CodexLens FTS backend is incompatible with the current CLI runtime. Falling back to ripgrep results.');
+    }
+    if (skipExactReason) {
+        fuzzyWarnings.push(skipExactReason);
+    }
+    if (ripgrepResult.status === 'fulfilled' && ripgrepResult.value.metadata?.warning) {
+        fuzzyWarnings.push(String(ripgrepResult.value.metadata.warning));
+    }
+    const mergedSuggestions = mergeSuggestions(ftsResult.status === 'fulfilled' ? ftsResult.value.metadata?.suggestions : undefined, ripgrepResult.status === 'fulfilled' ? ripgrepResult.value.metadata?.suggestions : undefined);
     // Collect results from both sources
     const resultsMap = new Map();
     // Add FTS results if successful
@@ -1228,8 +1628,10 @@ async function executeFuzzyMode(params) {
     const normalizedResults = filteredFusedResults.map((item) => ({
         file: item.file || item.path,
         line: item.line || 0,
+        endLine: item.endLine || item.line || 0,
         column: item.column || 0,
         content: item.content || '',
+        chunkLines: Array.isArray(item.chunkLines) ? item.chunkLines : undefined,
         score: item.fusion_score || 0,
         matchCount: item.matchCount,
         matchScore: item.matchScore,
@@ -1239,16 +1641,21 @@ async function executeFuzzyMode(params) {
     // Log timing
     timer.log();
     const timings = timer.getTimings();
+    const usingExactResults = resultsMap.has('exact');
     return {
         success: true,
         results,
         extra_files: extra_files.length > 0 ? extra_files : undefined,
         metadata: {
             mode: 'fuzzy',
-            backend: 'fts+ripgrep',
+            backend: usingExactResults ? 'fts+ripgrep' : 'ripgrep',
             count: results.length,
             query,
-            note: `Fuzzy search using RRF fusion of FTS and ripgrep (weights: exact=${fusionWeights.exact}, ripgrep=${fusionWeights.ripgrep})`,
+            note: usingExactResults
+                ? `Fuzzy search using RRF fusion of FTS and ripgrep (weights: exact=${fusionWeights.exact}, ripgrep=${fusionWeights.ripgrep})`
+                : 'Fuzzy search resolved using ripgrep only.',
+            warning: mergeWarnings(...fuzzyWarnings),
+            suggestions: mergedSuggestions,
             timing: TIMING_ENABLED ? timings : undefined,
         },
     };
@@ -1289,19 +1696,10 @@ async function executeAutoMode(params) {
             break;
     }
     // Add classification metadata
-    if (result.metadata) {
-        result.metadata.classified_as = classification.mode;
-        result.metadata.confidence = classification.confidence;
-        result.metadata.reasoning = classification.reasoning;
-        result.metadata.embeddings_coverage_percent = indexStatus.embeddings_coverage_percent;
-        result.metadata.index_status = indexStatus.indexed
-            ? (indexStatus.has_embeddings ? 'indexed' : 'partial')
-            : 'not_indexed';
-        // Add warning if needed
-        if (indexStatus.warning) {
-            result.metadata.warning = indexStatus.warning;
-        }
-    }
+    result.metadata = enrichMetadataWithIndexStatus(result.metadata, indexStatus, scope);
+    result.metadata.classified_as = classification.mode;
+    result.metadata.confidence = classification.confidence;
+    result.metadata.reasoning = classification.reasoning;
     return result;
 }
 /**
@@ -1337,9 +1735,10 @@ async function executeRipgrepMode(params) {
         const args = ['search', query, '--limit', totalToFetch.toString(), '--method', 'fts', '--json'];
         const result = await executeCodexLens(args, { cwd: scope.workingDirectory });
         if (!result.success) {
+            noteCodexLensFtsCompatibility(result.error);
             return {
                 success: false,
-                error: result.error,
+                error: summarizeBackendError(result.error),
                 metadata: {
                     mode: 'ripgrep',
                     backend: 'codexlens-fallback',
@@ -1380,7 +1779,7 @@ async function executeRipgrepMode(params) {
         };
     }
     // Use ripgrep - request more results to support split
-    const { command, args, tokens } = buildRipgrepCommand({
+    const { command, args, tokens, warning: queryModeWarning } = buildRipgrepCommand({
         query,
         paths: scope.searchPaths,
         contextLines,
@@ -1405,34 +1804,11 @@ async function executeRipgrepMode(params) {
             stderr += data.toString();
         });
         child.on('close', (code) => {
-            const allResults = [];
-            const lines = stdout.split('\n').filter((line) => line.trim());
             // Limit total results to prevent memory overflow (--max-count only limits per-file)
             const effectiveLimit = totalToFetch > 0 ? totalToFetch : 500;
-            for (const line of lines) {
-                // Stop collecting if we've reached the limit
-                if (allResults.length >= effectiveLimit) {
-                    resultLimitReached = true;
-                    break;
-                }
-                try {
-                    const item = JSON.parse(line);
-                    if (item.type === 'match') {
-                        const match = {
-                            file: item.data.path.text,
-                            line: item.data.line_number,
-                            column: item.data.submatches && item.data.submatches[0]
-                                ? item.data.submatches[0].start + 1
-                                : 1,
-                            content: item.data.lines.text.trim(),
-                        };
-                        allResults.push(match);
-                    }
-                }
-                catch {
-                    continue;
-                }
-            }
+            const parsedResults = parseRipgrepJsonResults(stdout, effectiveLimit);
+            const allResults = parsedResults.results;
+            resultLimitReached = parsedResults.resultLimitReached;
             // Handle Windows device file errors gracefully (os error 1)
             // If we have results despite the error, return them as partial success
             const isWindowsDeviceError = stderr.includes('os error 1') || stderr.includes('函数不正确');
@@ -1446,6 +1822,9 @@ async function executeRipgrepMode(params) {
                 const { results, extra_files } = splitResultsWithExtraFiles(filteredResults, maxResults, extraFilesCount);
                 // Build warning message for various conditions
                 const warnings = [];
+                if (queryModeWarning) {
+                    warnings.push(queryModeWarning);
+                }
                 if (resultLimitReached) {
                     warnings.push(`Result limit reached (${effectiveLimit}). Use a more specific query or increase limit.`);
                 }
@@ -1539,15 +1918,17 @@ async function executeCodexLensExactMode(params) {
     }
     const result = await executeCodexLens(args, { cwd: scope.workingDirectory });
     if (!result.success) {
+        noteCodexLensFtsCompatibility(result.error);
         return {
             success: false,
-            error: result.error,
+            error: summarizeBackendError(result.error),
             metadata: {
                 mode: 'exact',
                 backend: 'codexlens',
                 count: 0,
                 query,
                 warning: mergeWarnings(indexStatus.warning, result.warning),
+                suggestions: buildIndexSuggestions(indexStatus, scope),
             },
         };
     }
@@ -1611,6 +1992,7 @@ async function executeCodexLensExactMode(params) {
                         warning: mergeWarnings(indexStatus.warning, fuzzyResult.warning),
                         note: 'No exact matches found, showing fuzzy results',
                         fallback: 'fuzzy',
+                        suggestions: buildIndexSuggestions(indexStatus, scope),
                     },
                 };
             }
@@ -1628,6 +2010,7 @@ async function executeCodexLensExactMode(params) {
             count: results.length,
             query,
             warning: mergeWarnings(indexStatus.warning, result.warning),
+            suggestions: buildIndexSuggestions(indexStatus, scope),
         },
     };
 }
@@ -1690,6 +2073,7 @@ async function executeHybridMode(params) {
                 count: 0,
                 query,
                 warning: mergeWarnings(indexStatus.warning, result.warning),
+                suggestions: buildIndexSuggestions(indexStatus, scope),
             },
         };
     }
@@ -1732,6 +2116,7 @@ async function executeHybridMode(params) {
                     count: 0,
                     query,
                     warning: mergeWarnings(indexStatus.warning, result.warning, 'Failed to parse JSON output'),
+                    suggestions: buildIndexSuggestions(indexStatus, scope),
                 },
             };
         }
@@ -1760,6 +2145,7 @@ async function executeHybridMode(params) {
             query,
             note,
             warning: mergeWarnings(indexStatus.warning, result.warning),
+            suggestions: buildIndexSuggestions(indexStatus, scope),
             suggested_weights: getRRFWeights(query),
             timing: TIMING_ENABLED ? timings : undefined,
         },
@@ -1986,30 +2372,100 @@ function filterDominantBaselineScores(results) {
  * Reference: codex-lens/src/codexlens/search/ranking.py
  * Formula: score(d) = Σ weight_source / (k + rank_source(d))
  */
+function normalizeFusionSnippet(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const normalized = value.replace(/\s+/g, ' ').trim();
+    return normalized ? normalized.slice(0, 240) : undefined;
+}
+function buildFusionIdentity(result) {
+    const path = typeof result?.file === 'string'
+        ? result.file
+        : typeof result?.path === 'string'
+            ? result.path
+            : undefined;
+    if (!path) {
+        return null;
+    }
+    const line = typeof result?.line === 'number' && Number.isFinite(result.line)
+        ? result.line
+        : undefined;
+    const endLine = typeof result?.endLine === 'number' && Number.isFinite(result.endLine)
+        ? result.endLine
+        : line;
+    const column = typeof result?.column === 'number' && Number.isFinite(result.column)
+        ? result.column
+        : undefined;
+    if (line !== undefined) {
+        return `${path}#L${line}-${endLine ?? line}:C${column ?? 0}`;
+    }
+    const symbol = typeof result?.symbol === 'string' && result.symbol.trim()
+        ? result.symbol.trim()
+        : undefined;
+    const snippet = normalizeFusionSnippet(result?.content);
+    if (symbol && snippet) {
+        return `${path}::${symbol}::${snippet}`;
+    }
+    if (snippet) {
+        return `${path}::${snippet}`;
+    }
+    if (symbol) {
+        return `${path}::${symbol}`;
+    }
+    return path;
+}
+function scoreFusionRepresentative(result) {
+    let score = 0;
+    if (typeof result?.line === 'number' && Number.isFinite(result.line)) {
+        score += 1000;
+    }
+    if (typeof result?.endLine === 'number' && Number.isFinite(result.endLine)) {
+        score += 250;
+    }
+    if (typeof result?.column === 'number' && Number.isFinite(result.column)) {
+        score += 50;
+    }
+    if (Array.isArray(result?.chunkLines) && result.chunkLines.length > 0) {
+        score += 500 + result.chunkLines.length;
+    }
+    if (typeof result?.symbol === 'string' && result.symbol.trim()) {
+        score += 50;
+    }
+    if (typeof result?.content === 'string') {
+        score += Math.min(result.content.length, 200);
+    }
+    return score;
+}
 function applyRRFFusion(resultsMap, weightsOrQuery, limit, k = 60) {
     const weights = typeof weightsOrQuery === 'string' ? getRRFWeights(weightsOrQuery) : weightsOrQuery;
-    const pathScores = new Map();
+    const fusedScores = new Map();
     resultsMap.forEach((results, source) => {
         const weight = weights[source] || 0;
         if (weight === 0 || !results)
             return;
         results.forEach((result, rank) => {
-            const path = result.file || result.path;
-            if (!path)
+            const identity = buildFusionIdentity(result);
+            if (!identity)
                 return;
             const rrfContribution = weight / (k + rank + 1);
-            if (!pathScores.has(path)) {
-                pathScores.set(path, { score: 0, result, sources: [] });
+            const representativeScore = scoreFusionRepresentative(result);
+            if (!fusedScores.has(identity)) {
+                fusedScores.set(identity, { score: 0, result, sources: [], representativeScore });
             }
-            const entry = pathScores.get(path);
+            const entry = fusedScores.get(identity);
             entry.score += rrfContribution;
+            if (representativeScore > entry.representativeScore) {
+                entry.result = result;
+                entry.representativeScore = representativeScore;
+            }
             if (!entry.sources.includes(source)) {
                 entry.sources.push(source);
             }
         });
     });
     // Sort by fusion score descending
-    return Array.from(pathScores.values())
+    return Array.from(fusedScores.values())
         .sort((a, b) => b.score - a.score)
         .slice(0, limit)
         .map(item => ({
@@ -2206,9 +2662,9 @@ Recommended MCP flow: use **action=\"search\"** for lookups, **action=\"init\"**
             },
             output_mode: {
                 type: 'string',
-                enum: ['full', 'files_only', 'count'],
-                description: 'Output format: full (default), files_only (paths only), count (per-file counts)',
-                default: 'full',
+                enum: [...SEARCH_OUTPUT_MODES],
+                description: 'Output format: ace (default, ACE-style grouped code sections + rendered text), full (raw matches), files_only (paths only), count (per-file counts)',
+                default: 'ace',
             },
             path: {
                 type: 'string',
@@ -2540,6 +2996,108 @@ function applyPagination(results, offset, limit) {
         },
     };
 }
+function formatChunkRange(section) {
+    if (section.lines && section.lines.length > 0) {
+        const start = section.lines[0]?.line;
+        const end = section.lines[section.lines.length - 1]?.line;
+        if (typeof start === 'number' && typeof end === 'number' && end > start) {
+            return `${start}-${end}`;
+        }
+        if (typeof start === 'number') {
+            return String(start);
+        }
+    }
+    if (section.line && section.endLine && section.endLine > section.line) {
+        return `${section.line}-${section.endLine}`;
+    }
+    if (section.line) {
+        return String(section.line);
+    }
+    return '?';
+}
+function renderAceSnippet(section) {
+    if (section.lines && section.lines.length > 0) {
+        return section.lines.map((line) => {
+            const marker = line.isMatch ? '>' : ' ';
+            return `${marker} ${String(line.line).padStart(4, ' ')} | ${line.text}`;
+        });
+    }
+    return section.snippet.split(/\r?\n/).map((line) => `  ${line}`);
+}
+function formatAceLikeOutput(results) {
+    const sections = [];
+    for (const result of results) {
+        const candidate = result;
+        const path = typeof candidate.file === 'string'
+            ? candidate.file
+            : typeof candidate.path === 'string'
+                ? candidate.path
+                : undefined;
+        if (!path) {
+            continue;
+        }
+        const line = typeof candidate.line === 'number' && candidate.line > 0 ? candidate.line : undefined;
+        const column = typeof candidate.column === 'number' && candidate.column > 0 ? candidate.column : undefined;
+        const score = typeof candidate.score === 'number' ? candidate.score : undefined;
+        const symbol = typeof candidate.symbol === 'string' ? candidate.symbol : null;
+        const rawSnippet = typeof candidate.content === 'string'
+            ? candidate.content
+            : typeof candidate.name === 'string'
+                ? candidate.name
+                : typeof candidate.type === 'string'
+                    ? `[${candidate.type}]`
+                    : '';
+        sections.push({
+            path,
+            line,
+            endLine: typeof candidate.endLine === 'number' && candidate.endLine >= (line ?? 0) ? candidate.endLine : line,
+            column,
+            score,
+            symbol,
+            snippet: rawSnippet || '[no snippet available]',
+            lines: Array.isArray(candidate.chunkLines) ? candidate.chunkLines : undefined,
+        });
+    }
+    const groupsMap = new Map();
+    for (const section of sections) {
+        if (!groupsMap.has(section.path)) {
+            groupsMap.set(section.path, {
+                path: section.path,
+                sections: [],
+                total_matches: 0,
+            });
+        }
+        const group = groupsMap.get(section.path);
+        group.sections.push(section);
+        group.total_matches += 1;
+    }
+    const groups = [...groupsMap.values()];
+    const textParts = ['The following code sections were retrieved:'];
+    for (const group of groups) {
+        textParts.push('');
+        textParts.push(`Path: ${group.path}`);
+        group.sections.forEach((section, index) => {
+            const chunkLabel = group.sections.length > 1 ? `Chunk ${index + 1}` : 'Chunk';
+            textParts.push(`${chunkLabel}: lines ${formatChunkRange(section)}${section.score !== undefined ? ` | score=${section.score.toFixed(4)}` : ''}`);
+            if (section.symbol) {
+                textParts.push(`Symbol: ${section.symbol}`);
+            }
+            for (const snippetLine of renderAceSnippet(section)) {
+                textParts.push(snippetLine);
+            }
+            if (index < group.sections.length - 1) {
+                textParts.push('');
+            }
+        });
+    }
+    return {
+        format: 'ace',
+        text: textParts.join('\n'),
+        groups,
+        sections,
+        total: sections.length,
+    };
+}
 /**
  * Transform results based on output_mode
  */
@@ -2567,11 +3125,23 @@ function transformOutput(results, outputMode) {
                 total: results.length,
             };
         }
+        case 'ace':
+            return formatAceLikeOutput(results);
         case 'full':
         default:
             return results;
     }
 }
+function enrichMetadataWithIndexStatus(metadata, indexStatus, scope) {
+    const nextMetadata = { ...(metadata ?? {}) };
+    nextMetadata.embeddings_coverage_percent = indexStatus.embeddings_coverage_percent;
+    nextMetadata.index_status = indexStatus.indexed
+        ? (indexStatus.has_embeddings ? 'indexed' : 'partial')
+        : 'not_indexed';
+    nextMetadata.warning = mergeWarnings(nextMetadata.warning, indexStatus.warning);
+    nextMetadata.suggestions = mergeSuggestions(nextMetadata.suggestions, buildIndexSuggestions(indexStatus, scope));
+    return nextMetadata;
+}
 // Handler function
 export async function handler(params) {
     const parsed = ParamsSchema.safeParse(params);
@@ -2642,11 +3212,19 @@ export async function handler(params) {
                 }
                 break;
         }
+        let autoEmbedNote;
         // Transform output based on output_mode (for search actions only)
         if (action === 'search' || action === 'search_files') {
-            if (result.success && result.results && output_mode !== 'full') {
-                result.results = transformOutput(result.results, output_mode);
-            }
+            const scope = resolveSearchScope(parsed.data.path ?? '.');
+            const indexStatus = await checkIndexStatus(scope.workingDirectory);
+            result.metadata = enrichMetadataWithIndexStatus(result.metadata, indexStatus, scope);
+            const autoEmbedStatus = await maybeStartBackgroundAutoEmbed(scope, indexStatus);
+            autoEmbedNote = autoEmbedStatus.note;
+            result.metadata = {
+                ...(result.metadata ?? {}),
+                note: mergeNotes(result.metadata?.note, autoEmbedStatus.note),
+                warning: mergeWarnings(result.metadata?.warning, autoEmbedStatus.warning),
+            };
             // Add pagination metadata for search results if not already present
             if (result.success && result.results && Array.isArray(result.results)) {
                 const totalResults = result.results.length;
@@ -2662,6 +3240,33 @@ export async function handler(params) {
                     };
                 }
             }
+            if (result.success && result.results && output_mode !== 'full') {
+                result.results = transformOutput(result.results, output_mode);
+                if (output_mode === 'ace'
+                    && result.results
+                    && typeof result.results === 'object'
+                    && 'format' in result.results
+                    && result.results.format === 'ace') {
+                    const advisoryLines = [];
+                    if (result.metadata?.warning) {
+                        advisoryLines.push('', 'Warnings:', `- ${result.metadata.warning}`);
+                    }
+                    if (autoEmbedNote) {
+                        advisoryLines.push('', 'Notes:', `- ${autoEmbedNote}`);
+                    }
+                    if (result.metadata?.suggestions && result.metadata.suggestions.length > 0) {
+                        advisoryLines.push('', 'Suggestions:');
+                        for (const suggestion of result.metadata.suggestions) {
+                            advisoryLines.push(`- ${suggestion.title}: ${suggestion.command}`);
+                            advisoryLines.push(`  ${suggestion.reason}`);
+                        }
+                    }
+                    const aceResults = result.results;
+                    if (advisoryLines.length > 0) {
+                        aceResults.text += `\n${advisoryLines.join('\n')}`;
+                    }
+                }
+            }
         }
         // Add deprecation warning if applicable
         if (deprecationWarning && result.metadata) {
@@ -2680,10 +3285,14 @@ export async function handler(params) {
  * @param onProgress - Optional callback for progress updates
  */
 export const __testables = {
+    isCodexLensCliCompatibilityError,
     parseCodexLensJsonOutput,
     parsePlainTextFileMatches,
     hasCentralizedVectorArtifacts,
+    resolveRipgrepQueryMode,
     resolveEmbeddingSelection,
+    isAutoEmbedMissingEnabled,
+    buildIndexSuggestions,
 };
 export async function executeInitWithProgress(params, onProgress) {
     const path = params.path || '.';