sxng-cli 1.1.7 → 1.1.9

package/dist/runCli.sync-conflict-20260629-232915-2SGIW5T.js

@@ -0,0 +1,1109 @@
+/**
+ * SearXNG CLI - CLI Runner (Commander-based)
+ */
+import { Command } from 'commander';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8'));
+import { createSuccessEnvelope, createErrorEnvelope } from './protocol.js';
+import { config } from './config.js';
+import { initConfig } from './init.js';
+import { runExtract } from './commands/extract.js';
+import { runQueryGraph } from './commands/query-graph.js';
+import { runGraphAdd } from './commands/graph-add.js';
+import { runGraphObfuscateCommand } from './commands/graph-obfuscate.js';
+import { ContentExtractor } from './deep/extractor.js';
+import { rrf } from './deep/rrf.js';
+import { normalizeUrl } from './deep/dedupe.js';
+import { deserializeGraph, serializeGraph, graphStats, resultId } from './deep/graph.js';
+import { initSessionDir, resolveSessionPath, appendSessionResults, updateSessionGraph, loadSessionResults, loadSessionGraph } from './deep/session.js';
+import { runSessionList, runSessionDelete } from './commands/session.js';
+import { graphPreprocess } from './deep/graph-preprocess.js';
+import { checkQueryRedundancy } from './deep/query-redundancy.js';
+import { assessResultQuality } from './deep/quality-assess.js';
+import { generateQuerySuggestions } from './deep/query-suggest.js';
+import { determineSearchStage, getStrategyInfo } from './deep/search-strategy.js';
+import { analyzeRecoveryOptions } from './deep/recovery-analysis.js';
+import { getSessionAnalysis } from './deep/iteration-data.js';
+import { runGraphExplore } from './commands/graph-explore.js';
+import { runGraphDrill } from './commands/graph-drill.js';
+import { runGraphTraverse } from './commands/graph-traverse.js';
+import { runGraphSearch } from './commands/graph-search.js';
+import { DirectedGraph } from 'graphology';
+import { writeFileSync, existsSync } from 'fs';
+function formatAsMarkdown(data) {
+    const lines = [];
+    lines.push(`## Search: ${data.query || 'Unknown'}`);
+    lines.push('');
+    const results = data.results || [];
+    if (results.length > 0) {
+        lines.push(`**${results.length}** results`);
+        lines.push('');
+        for (let i = 0; i < results.length; i++) {
+            const r = results[i];
+            let scoreIndicator = '';
+            if (r.score !== undefined && r.score !== null) {
+                const normalizedScore = r.score > 1 ? r.score : r.score * 100;
+                scoreIndicator = ` [${normalizedScore.toFixed(1)}]`;
+            }
+            lines.push(`### ${i + 1}. [${r.title || 'No Title'}](${r.url || '#'})${scoreIndicator}`);
+            lines.push('');
+            if (r.content) {
+                lines.push(r.content);
+                lines.push('');
+            }
+            const meta = [];
+            meta.push(`Engine: ${r.engine || 'unknown'}`);
+            if (r.category)
+                meta.push(`Category: ${r.category}`);
+            if (r.publishedDate)
+                meta.push(`Published: ${r.publishedDate}`);
+            lines.push(meta.join(' · '));
+            lines.push('');
+        }
+    }
+    else {
+        lines.push('No results found.');
+        lines.push('');
+    }
+    if (data.unresponsiveEngines && data.unresponsiveEngines.length > 0) {
+        const unresponsive = data.unresponsiveEngines.map((item) => Array.isArray(item) ? item[0] : item).join(', ');
+        lines.push(`*Unresponsive: ${unresponsive}*`);
+        lines.push('');
+    }
+    if (data.suggestions && data.suggestions.length > 0) {
+        lines.push('**Suggestions:** ' + data.suggestions.join(' · '));
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+function formatOutput(data, format) {
+    if (format === 'md')
+        return formatAsMarkdown(data);
+    return JSON.stringify(data, null, 2);
+}
+function formatPreprocessAsMarkdown(data) {
+    const lines = [];
+    lines.push('## Graph Preprocess Results');
+    lines.push('');
+    lines.push(`**Strategy:** ${data.tokenizationStrategy}`);
+    lines.push(`**Coverage:** ${data.resultsWithContent}/${data.totalResults} results with content`);
+    lines.push(`**Rounds:** ${data.roundsCovered}`);
+    if (data.coOccurrenceTruncated)
+        lines.push('*Co-occurrence matrix was truncated*');
+    lines.push('');
+    if (data.tfidfTerms?.length) {
+        lines.push('### Top TF-IDF Terms');
+        lines.push('');
+        lines.push('| Term | TF-IDF | Doc Freq |');
+        lines.push('|------|--------|----------|');
+        for (const t of data.tfidfTerms.slice(0, 20)) {
+            lines.push(`| ${t.term} | ${t.tfidf.toFixed(2)} | ${t.docFreq} |`);
+        }
+        lines.push('');
+    }
+    if (data.coOccurrences?.length) {
+        lines.push('### Co-occurrences');
+        lines.push('');
+        lines.push('| Term 1 | Term 2 | Count |');
+        lines.push('|--------|--------|-------|');
+        for (const p of data.coOccurrences.slice(0, 20)) {
+            lines.push(`| ${p.term1} | ${p.term2} | ${p.count} |`);
+        }
+        lines.push('');
+    }
+    if (data.existingEntities?.length) {
+        lines.push('### Existing Entities');
+        lines.push('');
+        for (const e of data.existingEntities) {
+            lines.push(`- ${e.label} (degree: ${e.degree}${e.entityType ? `, type: ${e.entityType}` : ''})`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+function formatQualityAsMarkdown(data) {
+    const lines = [];
+    lines.push('## Result Quality Assessment');
+    lines.push('');
+    const verdictEmoji = { good: '✓', acceptable: '△', poor: '✗' };
+    lines.push(`**Verdict:** ${data.verdict.toUpperCase()} ${verdictEmoji[data.verdict] || ''}`);
+    lines.push('');
+    const breakdown = data.breakdown;
+    if (breakdown) {
+        lines.push('| Indicator | Value | Threshold | Pass |');
+        lines.push('|-----------|-------|-----------|------|');
+        const indicators = ['resultCount', 'contentDepth', 'entityRichness', 'sourceDiversity', 'novelty'];
+        const labels = {
+            resultCount: 'Result Count',
+            contentDepth: 'Content Depth',
+            entityRichness: 'Entity Richness',
+            sourceDiversity: 'Source Diversity',
+            novelty: 'Novelty',
+        };
+        for (const key of indicators) {
+            const ind = breakdown[key];
+            if (ind) {
+                const valueStr = key === 'novelty' ? ind.value.toFixed(2) : String(Math.round(ind.value * 100) / 100);
+                const thStr = key === 'novelty' ? ind.threshold.toFixed(2) : String(ind.threshold);
+                lines.push(`| ${labels[key] || key} | ${valueStr} | ${thStr} | ${ind.pass ? '✓' : '✗'} |`);
+            }
+        }
+        lines.push('');
+    }
+    if (data.failedIndicators?.length > 0) {
+        lines.push(`**Failed:** ${data.failedIndicators.join(', ')}`);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+function formatSuggestAsMarkdown(data) {
+    const lines = [];
+    lines.push('## Query Suggestion Data');
+    lines.push('');
+    lines.push(`**Current Stage:** ${data.currentStage}`);
+    lines.push('');
+    if (data.topEntities?.length) {
+        lines.push('### Top Entities');
+        lines.push('');
+        lines.push('| Entity | Obfuscated Label | Degree | Frequency | Type |');
+        lines.push('|--------|------------------|--------|-----------|------|');
+        for (const e of data.topEntities.slice(0, 15)) {
+            lines.push(`| ${e.label} | ${e.obfuscatedLabel || '-'} | ${e.degree} | ${e.frequency} | ${e.entityType || '-'} |`);
+        }
+        lines.push('');
+    }
+    if (data.unexploredDomains?.length) {
+        lines.push('### Unexplored Domains');
+        lines.push('');
+        for (const d of data.unexploredDomains) {
+            lines.push(`- ${d}`);
+        }
+        lines.push('');
+    }
+    if (data.roundHistory?.length) {
+        lines.push('### Round History');
+        lines.push('');
+        lines.push('| Round | Query | Results |');
+        lines.push('|-------|-------|---------|');
+        for (const r of data.roundHistory) {
+            lines.push(`| ${r.round} | ${r.query} | ${r.resultCount} |`);
+        }
+        lines.push('');
+    }
+    if (data.qualityLastRound) {
+        lines.push(`**Last Round Quality:** ${data.qualityLastRound.verdict}`);
+        if (data.qualityLastRound.failedIndicators?.length) {
+            lines.push(` (failed: ${data.qualityLastRound.failedIndicators.join(', ')})`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+function formatStrategyAsMarkdown(data) {
+    const lines = [];
+    lines.push('## Search Strategy Info');
+    lines.push('');
+    lines.push(`**Current Stage:** ${data.currentStage}`);
+    lines.push(`**Round:** ${data.roundNumber}`);
+    lines.push(`**Growth Rate:** ${data.growthRate.toFixed(2)}`);
+    lines.push('');
+    lines.push(`**Recommended Engines:** ${data.recommendedEngines?.join(', ') || '-'}`);
+    lines.push(`**Recommended Categories:** ${data.recommendedCategories?.join(', ') || '-'}`);
+    if (data.transitionReason) {
+        lines.push('');
+        lines.push(`**Transition Reason:** ${data.transitionReason}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+function formatRecoveryAsMarkdown(data) {
+    const lines = [];
+    lines.push('## Recovery Analysis');
+    lines.push('');
+    const verdictEmoji = { good: '✓', acceptable: '△', poor: '✗' };
+    lines.push(`**Quality:** ${data.qualityScore.verdict.toUpperCase()} ${verdictEmoji[data.qualityScore.verdict] || ''}`);
+    lines.push(`**Consecutive Failures:** ${data.recentFailures}`);
+    lines.push('');
+    if (data.lastSuccessfulRound) {
+        lines.push(`**Last Successful Round:** Round ${data.lastSuccessfulRound.round} — "${data.lastSuccessfulRound.query}"`);
+        lines.push('');
+    }
+    if (data.availableStrategies.length > 0) {
+        lines.push('### Available Strategies');
+        lines.push('');
+        for (const s of data.availableStrategies) {
+            lines.push(`**${s.strategy}**`);
+            lines.push(`- Reason: ${s.reason}`);
+            lines.push(`- Suggestion: ${s.suggestion}`);
+            if (s.backtrackTo) {
+                lines.push(`- Backtrack to: Round ${s.backtrackTo.round} — "${s.backtrackTo.query}"`);
+            }
+            lines.push('');
+        }
+    }
+    if (data.roundQualityHistory.length > 0) {
+        lines.push('### Quality History');
+        lines.push('');
+        lines.push('| Round | Query | Verdict | Failed |');
+        lines.push('|-------|-------|---------|--------|');
+        for (const r of data.roundQualityHistory) {
+            lines.push(`| ${r.round} | ${r.query} | ${r.verdict} | ${r.failedIndicators.join(', ') || '-'} |`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+function formatSessionReportAsMarkdown(data) {
+    const lines = [];
+    lines.push('## Session Report');
+    lines.push('');
+    // Quality summary
+    const q = data.quality;
+    const verdictEmoji = { good: '✓', acceptable: '△', poor: '✗' };
+    lines.push(`### Quality: ${q.verdict.toUpperCase()} ${verdictEmoji[q.verdict] || ''}`);
+    lines.push('');
+    if (q.breakdown) {
+        const indicators = ['resultCount', 'contentDepth', 'entityRichness', 'sourceDiversity', 'novelty'];
+        const labels = {
+            resultCount: 'Result Count', contentDepth: 'Content Depth',
+            entityRichness: 'Entity Richness', sourceDiversity: 'Source Diversity', novelty: 'Novelty',
+        };
+        for (const key of indicators) {
+            const ind = q.breakdown[key];
+            if (ind) {
+                const valueStr = key === 'novelty' ? ind.value.toFixed(2) : String(Math.round(ind.value * 100) / 100);
+                lines.push(`- ${labels[key]}: ${valueStr} (threshold: ${ind.threshold}) ${ind.pass ? '✓' : '✗'}`);
+            }
+        }
+        lines.push('');
+    }
+    // Strategy
+    const s = data.strategy;
+    lines.push(`### Strategy: ${s.currentStage}`);
+    lines.push(`- Round: ${s.roundNumber}`);
+    lines.push(`- Growth Rate: ${s.growthRate.toFixed(2)}`);
+    lines.push(`- Engines: ${s.recommendedEngines.join(', ')}`);
+    lines.push(`- Categories: ${s.recommendedCategories.join(', ')}`);
+    if (s.transitionReason)
+        lines.push(`- Transition: ${s.transitionReason}`);
+    lines.push('');
+    // Top entities
+    if (data.suggestions.topEntities?.length) {
+        lines.push('### Top Entities');
+        lines.push('');
+        for (const e of data.suggestions.topEntities.slice(0, 5)) {
+            lines.push(`- ${e.label} (degree: ${e.degree}, freq: ${e.frequency})`);
+        }
+        lines.push('');
+    }
+    // Recovery hint
+    if (q.verdict !== 'good') {
+        lines.push(`> Recovery: ${data.recovery.availableStrategies.length} strategies available. Use \`sxng recovery-analysis <session>\` for details.`);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/** Load query strings from session graph history. */
+function loadSessionQueryHistory(sessionDir) {
+    const graph = loadSessionGraph(sessionDir);
+    const queries = [];
+    graph.forEachNode((node, attrs) => {
+        if (attrs.type === 'query' && attrs.query) {
+            queries.push(attrs.query);
+        }
+    });
+    return queries;
+}
+function addToGraph(graphFile, results) {
+    let graph;
+    if (existsSync(graphFile)) {
+        try {
+            const raw = readFileSync(graphFile, 'utf-8');
+            const parsed = JSON.parse(raw);
+            const graphData = parsed.status === 'ok' && parsed.data?.graph
+                ? parsed.data.graph
+                : (parsed.nodes && parsed.edges ? parsed : null);
+            if (graphData) {
+                graph = deserializeGraph(graphData);
+            }
+            else {
+                graph = new DirectedGraph();
+            }
+        }
+        catch {
+            graph = new DirectedGraph();
+        }
+    }
+    else {
+        graph = new DirectedGraph();
+    }
+    for (let i = 0; i < results.length; i++) {
+        const r = results[i];
+        const id = resultId(r.url);
+        if (!graph.hasNode(id)) {
+            graph.mergeNode(id, {
+                type: 'result',
+                label: r.title,
+                url: r.url,
+                title: r.title,
+                rank: i + 1,
+            });
+        }
+    }
+    const serialized = serializeGraph(graph);
+    const stats = graphStats(graph);
+    writeFileSync(graphFile, JSON.stringify({ status: 'ok', data: { graph: serialized, stats } }, null, 2), 'utf-8');
+}
+async function runSearch(service, options) {
+    const queries = options.queries || (options.query ? [options.query] : []);
+    if (queries.length === 0) {
+        const envelope = createErrorEnvelope('MISSING_QUERY', 'No search query provided', { hint: 'Use: sxng "your search query" or sxng --queries "q1,q2,q3"' });
+        console.log(JSON.stringify(envelope, null, 2));
+        return 1;
+    }
+    if (options.engines && config.allowedEngines.length > 0) {
+        const invalid = options.engines.filter(e => !config.allowedEngines.includes(e));
+        if (invalid.length > 0) {
+            const envelope = createErrorEnvelope('INVALID_ENGINES', `Engines not allowed: ${invalid.join(', ')}`, { hint: `Allowed engines: ${config.allowedEngines.join(', ')}` });
+            console.log(JSON.stringify(envelope, null, 2));
+            return 1;
+        }
+    }
+    const limit = options.limit ?? config.defaultLimit;
+    if (options.session) {
+        const resolved = resolveSessionPath(options.session);
+        options.session = resolved;
+        initSessionDir(resolved, options.owner, options.desc, options.query);
+    }
+    // Pre-search redundancy check
+    if (options.redundancy && options.session) {
+        const history = loadSessionQueryHistory(options.session);
+        const redundancyConfig = {
+            jaccardThreshold: 0.7,
+            action: options.redundancy,
+        };
+        const adjustedQueries = [];
+        const skippedQueries = [];
+        for (const q of queries) {
+            const result = checkQueryRedundancy(q, history, redundancyConfig);
+            if (result.isRedundant) {
+                if (redundancyConfig.action === 'skip') {
+                    skippedQueries.push(q);
+                    continue;
+                }
+                else if (redundancyConfig.action === 'adjust' && result.adjustedQuery) {
+                    adjustedQueries.push(result.adjustedQuery);
+                }
+                else {
+                    // warn — proceed but output warning
+                    adjustedQueries.push(q);
+                }
+                // Output redundancy info
+                if (redundancyConfig.action === 'warn' || redundancyConfig.action === 'adjust') {
+                    const envelope = createSuccessEnvelope({
+                        redundancyWarning: {
+                            query: q,
+                            adjustedQuery: result.adjustedQuery,
+                            maxSimilarity: result.maxSimilarity,
+                            similarQueries: result.similarQueries,
+                            action: redundancyConfig.action,
+                        },
+                    });
+                    console.error(JSON.stringify(envelope, null, 2));
+                }
+            }
+            else {
+                adjustedQueries.push(q);
+            }
+        }
+        if (skippedQueries.length > 0 && skippedQueries.length === queries.length) {
+            // All queries skipped
+            const envelope = createSuccessEnvelope({
+                message: 'All queries skipped due to redundancy',
+                skippedQueries,
+            });
+            console.log(JSON.stringify(envelope, null, 2));
+            return 0;
+        }
+        // Replace queries with adjusted ones (skipped ones removed)
+        queries.length = 0;
+        queries.push(...adjustedQueries);
+    }
+    try {
+        if (queries.length === 1 && !options.merge) {
+            const searchOptions = {
+                query: queries[0],
+                engines: options.engines,
+                categories: options.categories,
+                limit,
+                page: options.page,
+                language: options.language,
+                timeRange: options.timeRange,
+            };
+            const results = await service.search(searchOptions);
+            let sessionInfo = null;
+            if (options.session) {
+                sessionInfo = appendSessionResults(options.session, results.results);
+                for (const query of queries) {
+                    updateSessionGraph(options.session, query, results.results.map(r => ({
+                        url: r.url,
+                        title: r.title,
+                    })));
+                }
+            }
+            const outputFormat = (options.format || config.defaultFormat);
+            let displayResults = results.results;
+            if (options.session) {
+                const allSessionResults = loadSessionResults(options.session);
+                const rankings = [
+                    results.results.map(r => ({ id: normalizeUrl(r.url), ...r })),
+                    allSessionResults.map(r => ({ id: normalizeUrl(r.url), ...r })),
+                ];
+                const fused = rrf(rankings);
+                const urlMap = new Map();
+                for (const r of results.results)
+                    urlMap.set(normalizeUrl(r.url), r);
+                for (const r of allSessionResults)
+                    urlMap.set(normalizeUrl(r.url), r);
+                displayResults = fused
+                    .map(item => {
+                    const original = urlMap.get(item.id);
+                    return original ? { ...original, score: item.score } : null;
+                })
+                    .filter(Boolean);
+                if (limit > 0)
+                    displayResults = displayResults.slice(0, limit);
+            }
+            const displayData = {
+                query: results.query,
+                totalResults: results.numberOfResults,
+                results: displayResults,
+                answers: results.answers,
+                suggestions: results.suggestions,
+                unresponsiveEngines: results.unresponsiveEngines,
+                ...(sessionInfo ? { session: { dir: options.session, added: sessionInfo.added, total: sessionInfo.total } } : {}),
+            };
+            if (outputFormat === 'md') {
+                console.log(formatOutput(displayData, 'md'));
+            }
+            else {
+                console.log(JSON.stringify(createSuccessEnvelope({
+                    ...displayData,
+                    returnedResults: displayResults.length,
+                }), null, 2));
+            }
+            if (options.graph) {
+                addToGraph(options.graph, results.results);
+            }
+            return 0;
+        }
+        const allResponses = [];
+        for (const query of queries) {
+            const searchOptions = {
+                query,
+                engines: options.engines,
+                categories: options.categories,
+                limit,
+                page: options.page,
+                language: options.language,
+                timeRange: options.timeRange,
+            };
+            const response = await service.search(searchOptions);
+            allResponses.push(response);
+        }
+        let rankings = allResponses.map(resp => resp.results.map((r) => ({ id: normalizeUrl(r.url), ...r })));
+        let mergeData = null;
+        if (options.merge) {
+            try {
+                const raw = readFileSync(options.merge, 'utf-8');
+                mergeData = JSON.parse(raw);
+                let mergeResults = mergeData;
+                if (mergeData.status === 'ok' && mergeData.data) {
+                    mergeResults = mergeData.data;
+                }
+                const historicalResults = (mergeResults.results || []);
+                if (historicalResults.length > 0) {
+                    rankings.push(historicalResults.map((r) => ({ id: normalizeUrl(r.url), ...r })));
+                }
+            }
+            catch (error) {
+                const envelope = createErrorEnvelope('MERGE_FILE_FAILED', `Failed to read merge file: ${options.merge}`, { hint: 'Ensure the file exists and contains valid search results JSON' });
+                console.log(JSON.stringify(envelope, null, 2));
+                return 1;
+            }
+        }
+        const rrfFused = rrf(rankings);
+        const allResults = [];
+        const allSuggestions = [];
+        const allAnswers = [];
+        const allUnresponsive = [];
+        for (const resp of allResponses) {
+            allResults.push(...resp.results);
+            for (const s of resp.suggestions) {
+                if (!allSuggestions.includes(s))
+                    allSuggestions.push(s);
+            }
+            for (const a of resp.answers) {
+                if (!allAnswers.includes(a))
+                    allAnswers.push(a);
+            }
+            for (const u of resp.unresponsiveEngines) {
+                const name = Array.isArray(u) ? u[0] : u;
+                if (!allUnresponsive.includes(name))
+                    allUnresponsive.push(name);
+            }
+        }
+        if (mergeData) {
+            let mergeResults = mergeData;
+            if (mergeData.status === 'ok' && mergeData.data) {
+                mergeResults = mergeData.data;
+            }
+            const historical = mergeResults.results || [];
+            allResults.push(...historical);
+            if (mergeResults.suggestions) {
+                for (const s of mergeResults.suggestions) {
+                    if (!allSuggestions.includes(s))
+                        allSuggestions.push(s);
+                }
+            }
+            if (mergeResults.answers) {
+                for (const a of mergeResults.answers) {
+                    if (!allAnswers.includes(a))
+                        allAnswers.push(a);
+                }
+            }
+        }
+        const urlMap = new Map();
+        for (const r of allResults) {
+            const norm = normalizeUrl(r.url);
+            if (!urlMap.has(norm))
+                urlMap.set(norm, r);
+        }
+        let fusedResults = rrfFused
+            .map((item) => {
+            const original = urlMap.get(item.id);
+            if (!original)
+                return null;
+            return { ...original, score: item.score };
+        })
+            .filter(Boolean);
+        if (limit > 0) {
+            fusedResults = fusedResults.slice(0, limit);
+        }
+        let sessionInfo = null;
+        if (options.session) {
+            sessionInfo = appendSessionResults(options.session, fusedResults);
+            for (const query of queries) {
+                updateSessionGraph(options.session, query, fusedResults.map(r => ({
+                    url: r.url,
+                    title: r.title,
+                })));
+            }
+        }
+        const displayQuery = queries.length > 1 ? queries.join(' · ') : queries[0];
+        const outputFormat = (options.format || config.defaultFormat);
+        const displayData = {
+            query: displayQuery,
+            queries,
+            totalResults: allResults.length,
+            results: fusedResults,
+            answers: allAnswers,
+            suggestions: allSuggestions,
+            unresponsiveEngines: allUnresponsive,
+            ...(sessionInfo ? { session: { dir: options.session, added: sessionInfo.added, total: sessionInfo.total } } : {}),
+        };
+        if (outputFormat === 'md') {
+            console.log(formatOutput(displayData, 'md'));
+        }
+        else if (outputFormat === 'json') {
+            console.log(JSON.stringify(createSuccessEnvelope({
+                ...displayData,
+                returnedResults: fusedResults.length,
+            }), null, 2));
+        }
+        else {
+            console.log(formatOutput(displayData, outputFormat));
+        }
+        if (options.graph) {
+            addToGraph(options.graph, fusedResults);
+        }
+        return 0;
+    }
+    catch (error) {
+        const envelope = createErrorEnvelope('SEARCH_FAILED', error instanceof Error ? error.message : 'Search request failed', {
+            retryable: true,
+            hint: 'Check your network connection and SearXNG server status'
+        });
+        console.log(JSON.stringify(envelope, null, 2));
+        return 1;
+    }
+}
+export function createProgram() {
+    const program = new Command();
+    program
+        .name('sxng')
+        .description('SearXNG CLI - Web Search Tool')
+        .version(pkg.version)
+        .argument('[query]', 'Search query')
+        .option('-e, --engines <engines>', 'Comma-separated list of search engines')
+        .option('-c, --categories <cats>', 'Comma-separated list of categories')
+        .option('-l, --limit <n>', 'Maximum number of results', val => parseInt(val, 10))
+        .option('-p, --page <n>', 'Page number for pagination', val => parseInt(val, 10))
+        .option('--lang <code>', 'Language code (e.g., en, zh, ja)')
+        .option('--time <range>', 'Time range: day, week, month, year, all')
+        .option('-f, --format <fmt>', 'Output format: md (default), json')
+        .option('--queries <q1,q2,q3>', 'Multi-query with RRF fusion')
+        .option('--merge <file>', 'Merge new results with previous search JSON')
+        .option('--search-session <dir|new>', 'Session dir, or "new" to auto-create')
+        .option('--owner <name>', 'Session owner (stored in meta.json)')
+        .option('--desc <text>', 'Session description (stored in meta.json)')
+        .option('--graph <file>', 'Save search result metadata to knowledge graph file')
+        .option('--redundancy <action>', 'Query redundancy check: warn | adjust | skip')
+        .option('--quality', 'Assess result quality for current session')
+        .option('--threshold-override <json>', 'Override quality thresholds (JSON, e.g. \'{"resultCount":10}\')')
+        .option('--health', 'Check SearXNG server health')
+        .option('--engines-list', 'List available search engines')
+        .option('--categories-list', 'List available categories')
+        .allowUnknownOption(false);
+    program
+        .command('init')
+        .description('Interactive configuration setup')
+        .action(async () => {
+        const code = await initConfig();
+        process.exit(code);
+    });
+    program
+        .command('extract')
+        .description('Extract article content from URLs or session results')
+        .option('--urls <url1,url2>', 'URLs to extract content from')
+        .option('--from-json <file>', 'Extract from search results JSON file')
+        .option('--session <dir>', 'Extract from session results and merge content back')
+        .option('--obscura', 'Use Obscura as fallback for JS-heavy pages')
+        .option('--obscura-path <path>', 'Path to Obscura binary')
+        .option('--obscura-dump <format>', 'Obscura dump format: html, markdown', 'html')
+        .action(async (opts) => {
+        const extractor = new ContentExtractor({
+            obscura: opts.obscura ?? false,
+            obscuraPath: opts.obscuraPath,
+            obscuraDumpFormat: opts.obscuraDump === 'markdown' ? 'markdown' : 'html',
+        });
+        const extractOptions = {
+            urls: opts.urls?.split(',').map((u) => u.trim()).filter(Boolean),
+            fromJson: opts.fromJson,
+            session: opts.session,
+        };
+        const code = await runExtract(extractor, extractOptions);
+        process.exit(code);
+    });
+    program
+        .command('query-graph')
+        .argument('<path>', 'Graph file or session name')
+        .description('[DEPRECATED] Query subgraph via BFS. Use graph-explore + graph-drill instead.')
+        .option('--seeds <s1,s2>', 'Seed nodes for BFS')
+        .option('--depth <n>', 'BFS depth (default: 2)', val => parseInt(val, 10), 2)
+        .option('--strategy <strategy>', 'Sampling strategy: augmented_chain | dual_core_bridge | community_core_path | deep_chain | mixed')
+        .option('-f, --format <fmt>', 'Output format: md, json')
+        .action(async (path, opts) => {
+        console.warn('[DEPRECATED] query-graph is deprecated. Use graph-explore + graph-drill instead.');
+        const graphFormat = opts.format === 'json' ? 'json' : 'md';
+        const code = await runQueryGraph({
+            graphFile: path,
+            seeds: opts.seeds?.split(',').map((s) => s.trim()).filter(Boolean) || [],
+            depth: opts.depth ?? 2,
+            format: graphFormat,
+            strategy: opts.strategy,
+        });
+        process.exit(code);
+    });
+    program
+        .command('graph-add')
+        .argument('<path>', 'Graph file or session name')
+        .description('Add entities/edges to knowledge graph')
+        .requiredOption('--data <json>', 'JSON with entities/edges')
+        .action(async (path, opts) => {
+        const code = await runGraphAdd({
+            graphFile: path,
+            data: opts.data,
+        });
+        process.exit(code);
+    });
+    program
+        .command('session-list')
+        .description('List all sessions')
+        .action(async () => {
+        const code = await runSessionList();
+        process.exit(code);
+    });
+    program
+        .command('session-delete')
+        .argument('[names]', 'Comma-separated session names to delete')
+        .option('--older <h>', 'Delete sessions older than N hours', val => parseFloat(val))
+        .action(async (names, opts) => {
+        const nameList = (names || '').split(',').map((n) => n.trim()).filter(Boolean);
+        const code = await runSessionDelete(nameList, opts.older);
+        process.exit(code);
+    });
+    program
+        .command('graph-obfuscate')
+        .argument('<path>', 'Graph file or session name')
+        .description('List obfuscation candidates or apply fallback rules (experimental)')
+        .option('--list', 'List entities needing obfuscation (default)')
+        .option('--fallback-rules', 'Apply simple rule-based obfuscation (experimental)')
+        .option('--skip-types <t1,t2>', 'Entity types to skip')
+        .option('-f, --format <fmt>', 'Output format: json (default), md')
+        .addHelpText('after', `
+Examples:
+  sxng graph-obfuscate my-session --list
+  sxng graph-obfuscate my-session --fallback-rules --format md
+
+Note: --fallback-rules is experimental and may produce low-quality obfuscation labels.
+Recommended workflow: use --list to get candidates, then have an LLM generate obfuscated labels,
+and write them back via graph-add.`)
+        .action(async (path, opts) => {
+        const code = await runGraphObfuscateCommand({
+            graphFile: path,
+            list: opts.list ?? !opts.fallbackRules,
+            fallbackRules: opts.fallbackRules ?? false,
+            format: opts.format === 'md' ? 'md' : 'json',
+            skipEntityTypes: opts.skipTypes?.split(',').map((t) => t.trim()).filter(Boolean),
+        });
+        process.exit(code);
+    });
+    program
+        .command('graph-preprocess')
+        .argument('<session>', 'Session directory or name')
+        .description('Preprocess session data: TF-IDF, co-occurrence, entity context')
+        .option('--top <n>', 'Top N terms to return', val => parseInt(val, 10), 30)
+        .option('--co-occurrence-threshold <n>', 'Min co-occurrence count', val => parseInt(val, 10), 2)
+        .option('--max-terms <n>', 'Max terms for co-occurrence matrix', val => parseInt(val, 10), 50)
+        .option('-f, --format <fmt>', 'Output format: json (default), md')
+        .addHelpText('after', `
+Examples:
+  sxng graph-preprocess my-session
+  sxng graph-preprocess my-session --top 50 --format md`)
+        .action(async (session, opts) => {
+        const sessionDir = resolveSessionPath(session);
+        const result = graphPreprocess(sessionDir, {
+            top: opts.top,
+            coOccurrenceThreshold: opts.coOccurrenceThreshold,
+            maxTermsForCoOccurrence: opts.maxTerms,
+        });
+        if (opts.format === 'md') {
+            console.log(formatPreprocessAsMarkdown(result));
+        }
+        else {
+            console.log(JSON.stringify(createSuccessEnvelope(result), null, 2));
+        }
+        process.exit(0);
+    });
+    program
+        .command('suggest-queries')
+        .argument('<session>', 'Session directory or name')
+        .description('Output query suggestion data for Agent follow-up query generation')
+        .option('-f, --format <fmt>', 'Output format: json (default), md')
+        .addHelpText('after', `
+Examples:
+  sxng suggest-queries my-session
+  sxng suggest-queries my-session --format md`)
+        .action(async (session, opts) => {
+        const sessionDir = resolveSessionPath(session);
+        const graph = loadSessionGraph(sessionDir);
+        const results = loadSessionResults(sessionDir);
+        const stage = determineSearchStage(graph);
+        const quality = assessResultQuality(results, results, graph);
+        const data = generateQuerySuggestions(graph, results, stage, quality);
+        if (opts.format === 'md') {
+            console.log(formatSuggestAsMarkdown(data));
+        }
+        else {
+            console.log(JSON.stringify(createSuccessEnvelope(data), null, 2));
+        }
+        process.exit(0);
+    });
+    program
+        .command('strategy-info')
+        .argument('<session>', 'Session directory or name')
+        .description('Output current search stage recommendation (broad vs targeted)')
+        .option('--broad-rounds <n>', 'Rounds before transition check', val => parseInt(val, 10), 2)
+        .option('--transition-threshold <n>', 'Growth rate threshold for stage transition', parseFloat, 0.2)
+        .option('-f, --format <fmt>', 'Output format: json (default), md')
+        .addHelpText('after', `
+Examples:
+  sxng strategy-info my-session
+  sxng strategy-info my-session --format md`)
+        .action(async (session, opts) => {
+        const sessionDir = resolveSessionPath(session);
+        const graph = loadSessionGraph(sessionDir);
+        const info = getStrategyInfo(graph, {
+            broadRounds: opts.broadRounds,
+            transitionThreshold: opts.transitionThreshold,
+        });
+        if (opts.format === 'md') {
+            console.log(formatStrategyAsMarkdown(info));
+        }
+        else {
+            console.log(JSON.stringify(createSuccessEnvelope(info), null, 2));
+        }
+        process.exit(0);
+    });
+    program
+        .command('recovery-analysis')
+        .argument('<session>', 'Session directory or name')
+        .description('Output recovery strategy analysis for Agent decision-making')
+        .option('-f, --format <fmt>', 'Output format: json (default), md')
+        .addHelpText('after', `
+Examples:
+  sxng recovery-analysis my-session
+  sxng recovery-analysis my-session --format md`)
+        .action(async (session, opts) => {
+        const sessionDir = resolveSessionPath(session);
+        const graph = loadSessionGraph(sessionDir);
+        const results = loadSessionResults(sessionDir);
+        const quality = assessResultQuality(results, results, graph);
+        const analysis = analyzeRecoveryOptions(graph, results, quality);
+        if (opts.format === 'md') {
+            console.log(formatRecoveryAsMarkdown(analysis));
+        }
+        else {
+            console.log(JSON.stringify(createSuccessEnvelope(analysis), null, 2));
+        }
+        process.exit(0);
+    });
+    program
+        .command('session-report')
+        .argument('<session>', 'Session directory or name')
+        .description('Show session quality history and stage progression')
+        .option('-f, --format <fmt>', 'Output format: json (default), md')
+        .addHelpText('after', `
+Examples:
+  sxng session-report my-session
+  sxng session-report my-session --format md`)
+        .action(async (session, opts) => {
+        const sessionDir = resolveSessionPath(session);
+        const graph = loadSessionGraph(sessionDir);
+        const results = loadSessionResults(sessionDir);
+        const analysis = getSessionAnalysis(graph, results);
+        if (opts.format === 'md') {
+            console.log(formatSessionReportAsMarkdown(analysis));
+        }
+        else {
+            console.log(JSON.stringify(createSuccessEnvelope(analysis), null, 2));
+        }
+        process.exit(0);
+    });
+    program
+        .command('graph-explore')
+        .argument('<session>', 'Session directory or name')
+        .description('List all relations around a seed entity (Agent graph navigation)')
+        .requiredOption('--seed <entity>', 'Seed entity label to explore')
+        .option('-f, --format <fmt>', 'Output format: md (default), json')
+        .addHelpText('after', `
+Examples:
+  sxng graph-explore my-session --seed "tokio"
+  sxng graph-explore my-session --seed "tokio" --format json
+
+See also: graph-drill, graph-search`)
+        .action(async (session, opts) => {
+        const code = await runGraphExplore({
+            session,
+            seed: opts.seed,
+            format: opts.format === 'json' ? 'json' : 'md',
+        });
+        process.exit(code);
+    });
+    program
+        .command('graph-drill')
+        .argument('<session>', 'Session directory or name')
+        .description('Follow specific relations from an entity (Agent graph navigation)')
+        .requiredOption('--seed <entity>', 'Seed entity label')
+        .requiredOption('--relations <list>', 'Comma-separated relation types to follow')
+        .option('-f, --format <fmt>', 'Output format: md (default), json')
+        .addHelpText('after', `
+Examples:
+  sxng graph-drill my-session --seed "tokio" --relations "alternative_to"
+  sxng graph-drill my-session --seed "tokio" --relations "alternative_to,depends_on" --format json
+
+See also: graph-explore`)
+        .action(async (session, opts) => {
+        const code = await runGraphDrill({
+            session,
+            seed: opts.seed,
+            relations: opts.relations.split(',').map((r) => r.trim()).filter(Boolean),
+            format: opts.format === 'json' ? 'json' : 'md',
+        });
+        process.exit(code);
+    });
+    program
+        .command('graph-traverse')
+        .argument('<session>', 'Session directory or name')
+        .description('Traverse a reasoning path by path node ID (requires path nodes from graph-preprocess)')
+        .requiredOption('--path <path-id>', 'Path node ID (e.g. p:chain_001)')
+        .option('-f, --format <fmt>', 'Output format: md (default), json')
+        .addHelpText('after', `
+Examples:
+  sxng graph-traverse my-session --path "p:chain_001"
+  sxng graph-traverse my-session --path "p:chain_001" --format json
+
+Note: Path nodes are created by graph-preprocess. If no paths exist,
+the command will list available path node IDs.`)
+        .action(async (session, opts) => {
+        const code = await runGraphTraverse({
+            session,
+            pathId: opts.path,
+            format: opts.format === 'json' ? 'json' : 'md',
+        });
+        process.exit(code);
+    });
+    program
+        .command('graph-search')
+        .argument('<session>', 'Session directory or name')
+        .description('Keyword search across entity labels (discover entities before exploring)')
+        .requiredOption('--keyword <term>', 'Search keyword')
+        .option('-l, --limit <n>', 'Max results', val => parseInt(val, 10), 10)
+        .option('-f, --format <fmt>', 'Output format: md (default), json')
+        .addHelpText('after', `
+Examples:
+  sxng graph-search my-session --keyword "async"
+  sxng graph-search my-session --keyword "tokio" --limit 5 --format json
+
+See also: graph-explore (for viewing relations of a known entity)`)
+        .action(async (session, opts) => {
+        const code = await runGraphSearch({
+            session,
+            keyword: opts.keyword,
+            limit: opts.limit,
+            format: opts.format === 'json' ? 'json' : 'md',
+        });
+        process.exit(code);
+    });
+    return program;
+}
+export async function runCli(args, service) {
+    const program = createProgram();
+    // Custom action for default command (search)
+    // Commander passes the [query] argument as first param, then opts
+    program.action(async (query, opts) => {
+        const queryString = query || '';
+        if (opts.version) {
+            console.log(program.version());
+            process.exit(0);
+            return;
+        }
+        if (opts.health) {
+            const health = await service.healthCheck();
+            const envelope = health.status === 'healthy'
+                ? createSuccessEnvelope(health)
+                : createErrorEnvelope('HEALTH_CHECK_FAILED', health.error || 'SearXNG server is not responding', { hint: `Check if SearXNG is running at ${config.baseUrl}` });
+            console.log(JSON.stringify(envelope, null, 2));
+            process.exit(health.status === 'healthy' ? 0 : 1);
+            return;
+        }
+        if (opts.quality) {
+            if (!opts.searchSession) {
+                const envelope = createErrorEnvelope('QUALITY_NO_SESSION', '--quality requires --session', { hint: 'Use: sxng --session <name> --quality' });
+                console.log(JSON.stringify(envelope, null, 2));
+                process.exit(1);
+                return;
+            }
+            const sessionDir = resolveSessionPath(opts.searchSession);
+            const sessionResults = loadSessionResults(sessionDir);
+            const sessionGraph = loadSessionGraph(sessionDir);
+            let thresholdOverride;
+            if (opts.thresholdOverride) {
+                try {
+                    thresholdOverride = JSON.parse(opts.thresholdOverride);
+                }
+                catch {
+                    const envelope = createErrorEnvelope('INVALID_THRESHOLD_OVERRIDE', '--threshold-override must be valid JSON', { hint: 'Example: \'{"resultCount":10}\'' });
+                    console.log(JSON.stringify(envelope, null, 2));
+                    process.exit(1);
+                    return;
+                }
+            }
+            const quality = assessResultQuality(sessionResults, sessionResults, sessionGraph, thresholdOverride);
+            const outputFormat = (opts.format || config.defaultFormat);
+            if (outputFormat === 'md') {
+                console.log(formatQualityAsMarkdown(quality));
+            }
+            else {
+                console.log(JSON.stringify(createSuccessEnvelope(quality), null, 2));
+            }
+            process.exit(0);
+            return;
+        }
+        if (opts.enginesList) {
+            try {
+                const engines = await service.getEngines();
+                if (engines.length === 0) {
+                    const envelope = createErrorEnvelope('ENGINES_FETCH_EMPTY', 'No engines returned from SearXNG server', { hint: 'Check if SearXNG server is properly configured' });
+                    console.log(JSON.stringify(envelope, null, 2));
+                    process.exit(1);
+                    return;
+                }
+                const envelope = createSuccessEnvelope({ engines, source: 'server' });
+                console.log(JSON.stringify(envelope, null, 2));
+                process.exit(0);
+            }
+            catch (error) {
+                const envelope = createErrorEnvelope('ENGINES_FETCH_FAILED', error instanceof Error ? error.message : 'Failed to fetch engines', { hint: 'Check your network connection and SearXNG server status' });
+                console.log(JSON.stringify(envelope, null, 2));
+                process.exit(1);
+            }
+            return;
+        }
+        if (opts.categoriesList) {
+            try {
+                const categories = await service.getCategories();
+                if (categories.length === 0) {
+                    const envelope = createErrorEnvelope('CATEGORIES_FETCH_EMPTY', 'No categories returned from SearXNG server', { hint: 'Check if SearXNG server is properly configured' });
+                    console.log(JSON.stringify(envelope, null, 2));
+                    process.exit(1);
+                    return;
+                }
+                const envelope = createSuccessEnvelope({ categories, source: 'server' });
+                console.log(JSON.stringify(envelope, null, 2));
+                process.exit(0);
+            }
+            catch (error) {
+                const envelope = createErrorEnvelope('CATEGORIES_FETCH_FAILED', error instanceof Error ? error.message : 'Failed to fetch categories', { hint: 'Check your network connection and SearXNG server status' });
+                console.log(JSON.stringify(envelope, null, 2));
+                process.exit(1);
+            }
+            return;
+        }
+        const queries = opts.queries?.split(',').map((q) => q.trim()).filter(Boolean);
+        const code = await runSearch(service, {
+            query: queryString,
+            queries,
+            engines: opts.engines?.split(',').map((e) => e.trim()).filter(Boolean),
+            categories: opts.categories?.split(',').map((c) => c.trim()).filter(Boolean),
+            limit: opts.limit,
+            page: opts.page,
+            language: opts.lang,
+            timeRange: opts.time,
+            format: opts.format,
+            session: opts.searchSession,
+            owner: opts.owner,
+            desc: opts.desc,
+            graph: opts.graph,
+            merge: opts.merge,
+            redundancy: opts.redundancy,
+        });
+        process.exit(code);
+    });
+    try {
+        await program.parseAsync(args, { from: 'user' });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'CommanderError') {
+            console.error(error.message);
+            return 1;
+        }
+        throw error;
+    }
+    return null;
+}
+//# sourceMappingURL=runCli.js.map