preflight-mcp 0.5.0 → 0.5.2

package/README.md

@@ -310,20 +310,39 @@ Parameters:
 - `min_confidence`: 0-1 (default: 0.85)
 - `limit`: Max suggestions (default: 50)
 
-### `preflight_deep_analyze_bundle` *(NEW v0.4.0)*
-One-call deep analysis aggregating tree, search, deps, and traces.
+### `preflight_deep_analyze_bundle` *(Enhanced v0.5.1)*
+One-call deep analysis aggregating tree, search, deps, traces, **overview content**, and **test detection**.
 - Returns unified evidence pack with LLM-friendly summary
+- **Now includes OVERVIEW.md, START_HERE.md, AGENTS.md, README content** (v0.5.1)
+- **Auto-detects test frameworks** (jest, vitest, pytest, go, mocha) (v0.5.1)
+- **Generates copyable `nextCommands`** for follow-up actions (v0.5.1)
 - Auto-generates **claims** with evidence references
 - Tracks analysis progress via **checklistStatus**
 - Reports unanswered questions as **openQuestions**
-- Triggers: "deep analyze", "comprehensive analysis", "深度分析"
+- Triggers: "deep analyze", "comprehensive analysis", "深度分析", "快速了解项目"
+
+**New in v0.5.1 - Aggregated content (reduces round-trips):**
+- `includeOverview` (default: true): Include OVERVIEW.md, START_HERE.md, AGENTS.md
+- `includeReadme` (default: true): Include repo README.md
+- `includeTests` (default: true): Detect test directories and frameworks
 
 Output includes:
+- `overviewContent`: `{overview, startHere, agents, readme}` - bundle documentation content
+- `testInfo`: `{detected, framework, testDirs, testFileCount, configFiles, hint}` - test detection result
+- `nextCommands[]`: Copyable tool calls for next steps (can be directly used as arguments)
 - `claims[]`: Auto-generated findings with evidence
 - `checklistStatus`: Analysis progress (repo_tree, deps, entrypoints, etc.)
 - `openQuestions[]`: Questions with `nextEvidenceToFetch` hints
 - `summary`: Markdown summary with checklist and key findings
 
+**Example `nextCommands` output:**
+```json
+[
+  { "tool": "preflight_search_bundle", "description": "Search for specific code", "args": { "bundleId": "...", "query": "<填入关键词>" } },
+  { "tool": "preflight_read_file", "description": "Read core module", "args": { "bundleId": "...", "file": "src/server.ts" } }
+]
+```
+
 ### `preflight_validate_report` *(NEW v0.4.0)*
 Validate claims and evidence chains for auditability.
 - Checks: missing evidence, invalid file references, broken snippet hashes

package/dist/analysis/deep.js

@@ -8,7 +8,7 @@ import { createEmptyCoverageReport, isCoverageSufficient, } from '../types/evide
  * This is called by the server after gathering data from each source.
  */
 export function buildDeepAnalysis(bundleId, components) {
-    const { tree, search, deps, traces, focusPath, focusQuery, errors = [] } = components;
+    const { tree, search, deps, traces, overviewContent, testInfo, focusPath, focusQuery, errors = [] } = components;
     // Build coverage report
     const coverageReport = createEmptyCoverageReport();
     if (tree) {
@@ -75,9 +75,28 @@ export function buildDeepAnalysis(bundleId, components) {
         }
         summaryParts.push('');
     }
+    // Test detection summary
+    if (testInfo) {
+        summaryParts.push(`## Test Detection`);
+        if (testInfo.detected) {
+            summaryParts.push(`- Framework: ${testInfo.framework ?? 'unknown'}`);
+            summaryParts.push(`- Test files: ${testInfo.testFileCount}`);
+            if (testInfo.testDirs.length > 0) {
+                summaryParts.push(`- Test directories: ${testInfo.testDirs.slice(0, 3).join(', ')}`);
+            }
+            if (testInfo.configFiles.length > 0) {
+                summaryParts.push(`- Config files: ${testInfo.configFiles.join(', ')}`);
+            }
+        }
+        else {
+            summaryParts.push(`- No tests detected`);
+        }
+        summaryParts.push(`- 💡 ${testInfo.hint}`);
+        summaryParts.push('');
+    }
     // Build checklist status
     const checklistStatus = {
-        read_overview: false, // Would need OVERVIEW.md read - caller should set
+        read_overview: !!(overviewContent?.overview || overviewContent?.startHere),
         repo_tree: !!tree && tree.totalFiles > 0,
         search_focus: !!search && search.totalHits > 0,
         dependency_graph_global: !!deps && deps.totalNodes > 0,
@@ -271,6 +290,51 @@ export function buildDeepAnalysis(bundleId, components) {
     if (isCoverageSufficient(coverageReport) && openQuestions.length === 0 && claims.length > 0) {
         nextSteps.push('🎉 Analysis complete - all key areas covered. Ready for detailed review.');
     }
+    // Build nextCommands (copyable JSON for LLM)
+    const nextCommands = [];
+    // Always suggest search as a useful next step
+    nextCommands.push({
+        tool: 'preflight_search_bundle',
+        description: 'Search for specific code or concepts',
+        args: { bundleId, query: '<填入关键词>', scope: 'all', limit: 30 },
+    });
+    // Suggest reading a specific entry point if identified
+    if (deps && deps.topImported.length > 0) {
+        const coreFile = deps.topImported[0].file;
+        nextCommands.push({
+            tool: 'preflight_read_file',
+            description: `Read core module: ${coreFile}`,
+            args: { bundleId, file: coreFile, withLineNumbers: true },
+        });
+    }
+    // Suggest dependency analysis for a specific file if entry point identified
+    if (deps && deps.topImporters.length > 0) {
+        const entryFile = deps.topImporters[0].file;
+        nextCommands.push({
+            tool: 'preflight_evidence_dependency_graph',
+            description: `Analyze dependencies of entry point: ${entryFile}`,
+            args: { bundleId, target: { file: entryFile } },
+        });
+    }
+    // Suggest trace discovery if no traces exist
+    if (!traces || traces.totalLinks === 0) {
+        nextCommands.push({
+            tool: 'preflight_suggest_traces',
+            description: 'Auto-discover test↔code relationships',
+            args: { bundleId, edge_type: 'tested_by', scope: 'repo' },
+        });
+    }
+    // Suggest focused tree if large directory detected
+    if (tree) {
+        const largeDir = tree.topDirs.find(d => d.fileCount > 50);
+        if (largeDir) {
+            nextCommands.push({
+                tool: 'preflight_repo_tree',
+                description: `Explore large directory: ${largeDir.path}`,
+                args: { bundleId, focusDir: largeDir.path, depth: 6 },
+            });
+        }
+    }
     // Add checklist and claims to summary
     summaryParts.push(`## Analysis Checklist`);
     const checklistItems = [
@@ -307,11 +371,104 @@ export function buildDeepAnalysis(bundleId, components) {
         search,
         deps,
         traces,
+        overviewContent,
+        testInfo,
         claims,
         checklistStatus,
         openQuestions,
         coverageReport,
         summary: summaryParts.join('\n'),
         nextSteps,
+        nextCommands,
+    };
+}
+/**
+ * Detect test setup from file tree statistics.
+ * Scans for test directories, test files, and framework config files.
+ */
+export function detectTestInfo(stats, filesFound) {
+    const testDirs = [];
+    let testFileCount = 0;
+    const configFiles = [];
+    let framework = null;
+    // Common test directory patterns
+    const testDirPatterns = ['tests', 'test', '__tests__', 'spec', 'specs', 'e2e', 'integration'];
+    // Check byTopDir for test directories
+    if (stats.byTopDir) {
+        for (const [dir, count] of Object.entries(stats.byTopDir)) {
+            const dirLower = dir.toLowerCase();
+            if (testDirPatterns.some(p => dirLower === p || dirLower.endsWith('/' + p))) {
+                testDirs.push(dir);
+                testFileCount += count;
+            }
+        }
+    }
+    // Framework detection from config files (if filesFound provided)
+    const frameworkConfigs = [
+        { pattern: /^jest\.config\.(js|ts|mjs|cjs|json)$/i, framework: 'jest' },
+        { pattern: /^vitest\.config\.(js|ts|mjs|cjs)$/i, framework: 'vitest' },
+        { pattern: /^pytest\.ini$/i, framework: 'pytest' },
+        { pattern: /^pyproject\.toml$/i, framework: 'pytest' }, // May contain pytest config
+        { pattern: /^setup\.cfg$/i, framework: 'pytest' },
+        { pattern: /^\.mocharc\.(js|json|yml|yaml)$/i, framework: 'mocha' },
+        { pattern: /^mocha\.opts$/i, framework: 'mocha' },
+    ];
+    if (filesFound) {
+        for (const file of filesFound) {
+            for (const cfg of frameworkConfigs) {
+                if (cfg.pattern.test(file.name)) {
+                    configFiles.push(file.path);
+                    if (!framework) {
+                        framework = cfg.framework;
+                    }
+                }
+            }
+        }
+    }
+    // Infer framework from file extensions if not detected from config
+    if (!framework && stats.byExtension) {
+        // Check for test file patterns in extensions
+        const hasTs = (stats.byExtension['.ts'] ?? 0) > 0 || (stats.byExtension['.tsx'] ?? 0) > 0;
+        const hasPy = (stats.byExtension['.py'] ?? 0) > 0;
+        const hasGo = (stats.byExtension['.go'] ?? 0) > 0;
+        if (testDirs.length > 0 || testFileCount > 0) {
+            if (hasGo)
+                framework = 'go';
+            else if (hasPy)
+                framework = 'pytest';
+            else if (hasTs)
+                framework = 'unknown'; // Could be jest/vitest/mocha
+        }
+    }
+    // Count test files by pattern (approximate from extensions)
+    // This is a heuristic - actual test files may vary
+    if (testFileCount === 0 && stats.byExtension) {
+        // If no test directories found, estimate based on common patterns
+        // This is imprecise but gives a hint
+    }
+    const detected = testDirs.length > 0 || testFileCount > 0 || configFiles.length > 0;
+    // Generate hint based on detection results
+    let hint;
+    if (detected) {
+        if (testFileCount > 0) {
+            hint = `Found ${testFileCount} test files. Run preflight_suggest_traces to map code↔test relationships.`;
+        }
+        else if (configFiles.length > 0) {
+            hint = `Test config found (${configFiles[0]}). Run preflight_suggest_traces to discover test files.`;
+        }
+        else {
+            hint = `Test directories found. Run preflight_suggest_traces to map code↔test relationships.`;
+        }
+    }
+    else {
+        hint = 'No tests detected. Consider adding tests or check if test files use non-standard naming.';
+    }
+    return {
+        detected,
+        framework,
+        testDirs,
+        testFileCount,
+        configFiles,
+        hint,
     };
 }

package/dist/bundle/ingest.js

@@ -72,11 +72,21 @@ async function buildIgnore(repoRoot) {
     }
     return ig;
 }
-async function* walkFiles(repoRoot, ig) {
+async function* walkFiles(repoRoot, ig, onSkip) {
     const stack = [repoRoot];
     while (stack.length) {
         const dir = stack.pop();
-        const entries = await fs.readdir(dir, { withFileTypes: true });
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch (err) {
+            // Skip directories that cannot be read (broken symlinks, permission issues, etc.)
+            const rel = path.relative(repoRoot, dir);
+            const relPosix = toPosix(rel);
+            onSkip?.(relPosix, `cannot read directory: ${err.code ?? 'unknown'}`);
+            continue;
+        }
         for (const ent of entries) {
             const abs = path.join(dir, ent.name);
             const rel = path.relative(repoRoot, abs);
@@ -85,12 +95,29 @@ async function* walkFiles(repoRoot, ig) {
             if (ig.ignores(relPosix)) {
                 continue;
             }
-            if (ent.isDirectory()) {
-                stack.push(abs);
-                continue;
+            // Handle symlinks and other special entries
+            try {
+                if (ent.isSymbolicLink()) {
+                    // Check if symlink target exists
+                    try {
+                        await fs.stat(abs);
+                    }
+                    catch {
+                        onSkip?.(relPosix, 'broken symlink');
+                        continue;
+                    }
+                }
+                if (ent.isDirectory()) {
+                    stack.push(abs);
+                    continue;
+                }
+                if (!ent.isFile())
+                    continue;
             }
-            if (!ent.isFile())
+            catch (err) {
+                onSkip?.(relPosix, `cannot stat: ${err.code ?? 'unknown'}`);
                 continue;
+            }
             yield { absPath: abs, relPosix };
         }
     }
@@ -101,7 +128,9 @@ export async function ingestRepoToBundle(params) {
     const files = [];
     const skipped = [];
     const decoder = new TextDecoder('utf-8', { fatal: true });
-    for await (const f of walkFiles(params.repoRoot, ig)) {
+    for await (const f of walkFiles(params.repoRoot, ig, (relPosix, reason) => {
+        skipped.push(`${relPosix} (${reason})`);
+    })) {
         // ignore check already done in walkFiles
         const st = await fs.stat(f.absPath);
         if (st.size > params.options.maxFileBytes) {

package/dist/server.js

@@ -19,7 +19,7 @@ import { DependencyGraphInputSchema, generateDependencyGraph } from './evidence/
 import { TraceQueryInputSchema, TraceUpsertInputSchema, traceQuery, traceUpsert } from './trace/service.js';
 import { suggestTestedByTraces } from './trace/suggest.js';
 import { generateRepoTree, formatTreeResult } from './bundle/tree.js';
-import { buildDeepAnalysis } from './analysis/deep.js';
+import { buildDeepAnalysis, detectTestInfo } from './analysis/deep.js';
 import { validateReport } from './analysis/validate.js';
 // RFC v2: New aggregation tools
 import { ReadFilesInputSchema, createReadFilesHandler, readFilesToolDescription } from './tools/readFiles.js';
@@ -147,7 +147,7 @@ export async function startServer() {
     startHttpServer(cfg);
     const server = new McpServer({
         name: 'preflight-mcp',
-        version: '0.5.0',
+        version: '0.5.2',
         description: 'Create evidence-based preflight bundles for repositories (docs + code) with SQLite FTS search.',
     }, {
         capabilities: {
@@ -2071,6 +2071,9 @@ export async function startServer() {
                 includeSearch: z.boolean().optional().default(true).describe('Include search results (requires focus.query).'),
                 includeDeps: z.boolean().optional().default(true).describe('Include dependency analysis.'),
                 includeTraces: z.boolean().optional().default(true).describe('Include trace link summary.'),
+                includeOverview: z.boolean().optional().default(true).describe('Include OVERVIEW.md, START_HERE.md, AGENTS.md content.'),
+                includeReadme: z.boolean().optional().default(true).describe('Include README.md content from repos.'),
+                includeTests: z.boolean().optional().default(true).describe('Detect test directories and frameworks.'),
                 tokenBudget: z.number().int().optional().describe('Soft limit on output tokens (reduces detail if exceeded).'),
                 maxFiles: z.number().int().min(10).max(1000).optional().default(500).describe('Max files to scan for tree/deps.'),
             }).optional().describe('Analysis options.'),
@@ -2103,6 +2106,20 @@ export async function startServer() {
                 byType: z.record(z.string(), z.number()),
                 coverageEstimate: z.number(),
             }).optional(),
+            overviewContent: z.object({
+                overview: z.string().optional(),
+                startHere: z.string().optional(),
+                agents: z.string().optional(),
+                readme: z.string().optional(),
+            }).optional().describe('Overview content from bundle files (OVERVIEW.md, START_HERE.md, AGENTS.md, README.md).'),
+            testInfo: z.object({
+                detected: z.boolean(),
+                framework: z.enum(['jest', 'vitest', 'pytest', 'go', 'mocha', 'unknown']).nullable(),
+                testDirs: z.array(z.string()),
+                testFileCount: z.number(),
+                configFiles: z.array(z.string()),
+                hint: z.string(),
+            }).optional().describe('Test detection result.'),
             claims: z.array(z.object({
                 id: z.string(),
                 text: z.string(),
@@ -2129,7 +2146,12 @@ export async function startServer() {
             })).describe('Questions that could not be answered.'),
             coverageReport: z.any(),
             summary: z.string().describe('LLM-formatted analysis summary with checklist and claims.'),
-            nextSteps: z.array(z.string()),
+            nextSteps: z.array(z.string()).describe('Human-readable next step suggestions.'),
+            nextCommands: z.array(z.object({
+                tool: z.string(),
+                description: z.string(),
+                args: z.record(z.string(), z.unknown()),
+            })).describe('Copyable next commands for LLM/automation - can be directly used as tool call arguments.'),
             // RFC v2: Top-level evidence aggregation
             evidence: z.array(z.object({
                 path: z.string(),
@@ -2159,6 +2181,8 @@ export async function startServer() {
             let search;
             let deps;
             let traces;
+            let overviewContent;
+            let testInfo;
             // 1. Tree
             if (opts.includeTree ?? true) {
                 try {
@@ -2280,11 +2304,89 @@ export async function startServer() {
                     traces = { totalLinks: 0, byType: {}, coverageEstimate: 0 };
                 }
             }
+            // 5. Overview content (OVERVIEW.md, START_HERE.md, AGENTS.md)
+            if (opts.includeOverview ?? true) {
+                overviewContent = {};
+                const readFile = async (filename) => {
+                    try {
+                        const absPath = safeJoin(paths.rootDir, filename);
+                        return await fs.readFile(absPath, 'utf8');
+                    }
+                    catch {
+                        return undefined;
+                    }
+                };
+                overviewContent.overview = await readFile('OVERVIEW.md');
+                overviewContent.startHere = await readFile('START_HERE.md');
+                overviewContent.agents = await readFile('AGENTS.md');
+            }
+            // 6. README content (from repos)
+            if (opts.includeReadme ?? true) {
+                if (!overviewContent)
+                    overviewContent = {};
+                try {
+                    const manifest = await readManifest(paths.manifestPath);
+                    for (const repo of manifest.repos ?? []) {
+                        if (!repo.id)
+                            continue;
+                        const [owner, repoName] = repo.id.split('/');
+                        if (!owner || !repoName)
+                            continue;
+                        const readmeNames = ['README.md', 'readme.md', 'Readme.md'];
+                        for (const readmeName of readmeNames) {
+                            const readmePath = `repos/${owner}/${repoName}/norm/${readmeName}`;
+                            try {
+                                const absPath = safeJoin(paths.rootDir, readmePath);
+                                overviewContent.readme = await fs.readFile(absPath, 'utf8');
+                                break; // Found README, stop searching
+                            }
+                            catch {
+                                // Try next README name
+                            }
+                        }
+                        if (overviewContent.readme)
+                            break; // Only read first repo's README
+                    }
+                }
+                catch {
+                    // Ignore manifest read errors
+                }
+            }
+            // 7. Test detection
+            if ((opts.includeTests ?? true) && tree) {
+                // Collect files for framework detection
+                const filesFound = [];
+                try {
+                    // Scan for config files at bundle root
+                    const configPatterns = [
+                        'jest.config.js', 'jest.config.ts', 'jest.config.mjs', 'jest.config.json',
+                        'vitest.config.js', 'vitest.config.ts',
+                        'pytest.ini', 'pyproject.toml', 'setup.cfg',
+                        '.mocharc.js', '.mocharc.json', '.mocharc.yml',
+                    ];
+                    for (const cfg of configPatterns) {
+                        try {
+                            const cfgPath = safeJoin(paths.rootDir, cfg);
+                            await fs.access(cfgPath);
+                            filesFound.push({ path: cfg, name: cfg });
+                        }
+                        catch {
+                            // Config file doesn't exist
+                        }
+                    }
+                }
+                catch {
+                    // Ignore errors during config scanning
+                }
+                testInfo = detectTestInfo({ byExtension: tree.byExtension, byTopDir: tree.topDirs.reduce((acc, d) => ({ ...acc, [d.path]: d.fileCount }), {}) }, filesFound.length > 0 ? filesFound : undefined);
+            }
             const result = buildDeepAnalysis(args.bundleId, {
                 tree,
                 search,
                 deps,
                 traces,
+                overviewContent,
+                testInfo,
                 focusPath: focus.path,
                 focusQuery: focus.query,
                 errors,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "preflight-mcp",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "MCP server that creates evidence-based preflight bundles for GitHub repositories and library docs.",
   "type": "module",
   "license": "MIT",