preflight-mcp 0.1.3 → 0.1.5

package/README.md

@@ -15,8 +15,12 @@ Each bundle contains:
 
 ## Features
 
-- **12 MCP tools** to create/update/repair/search/read bundles, generate evidence graphs, and manage trace links
-- **De-duplication**: prevent repeated indexing of the same normalized inputs
+- **13 MCP tools** to create/update/repair/search/read bundles, generate evidence graphs, and manage trace links
+- **Progress tracking**: Real-time progress reporting for long-running operations (create/update bundles)
+- **Bundle integrity check**: Prevents operations on incomplete bundles with helpful error messages
+- **De-duplication with in-progress lock**: Prevent duplicate bundle creation even during MCP timeouts
+- **Global dependency graph**: Generate project-wide import relationship graphs
+- **Batch file reading**: Read all key bundle files in a single call
 - **Resilient GitHub fetching**: configurable git clone timeout + GitHub archive (zipball) fallback
 - **Offline repair**: rebuild missing/empty derived artifacts (index/guides/overview) without re-fetching
 - **Static facts extraction** via `analysis/FACTS.json` (non-LLM)
@@ -117,7 +121,7 @@ Run end-to-end smoke test:
 npm run smoke
 ```
 
-## Tools (12 total)
+## Tools (13 total)
 
 ### `preflight_list_bundles`
 List bundle IDs in storage.
@@ -146,8 +150,10 @@ Input (example):
 **Note**: If the bundle contains code files, consider using `preflight_evidence_dependency_graph` for dependency analysis or `preflight_trace_upsert` for trace links.
 
 ### `preflight_read_file`
-Read a file from bundle (OVERVIEW.md, START_HERE.md, AGENTS.md, manifest.json, or any repo file).
-- Triggers: "查看概览", "项目概览", "看README", "bundle详情", "bundle状态", "仓库信息"
+Read file(s) from bundle. Two modes:
+- **Batch mode** (omit `file`): Returns ALL key files (OVERVIEW.md, START_HERE.md, AGENTS.md, manifest.json, repo READMEs) in one call
+- **Single file mode** (provide `file`): Returns that specific file
+- Triggers: "查看bundle", "bundle概览", "项目信息", "show bundle"
 - Use `file: "manifest.json"` to get bundle metadata (repos, timestamps, tags, etc.)
 
 ### `preflight_delete_bundle`
@@ -189,10 +195,12 @@ Optional parameters:
 - `limit`: Max total hits across all bundles
 
 ### `preflight_evidence_dependency_graph`
-Generate an evidence-based dependency graph for a target file/symbol (imports + callers).
+Generate an evidence-based dependency graph. Two modes:
+- **Target mode** (provide `target.file`): Analyze a specific file's imports and callers
+- **Global mode** (omit `target`): Generate project-wide import graph of all code files
 - Deterministic output with source ranges for edges.
 - Uses Tree-sitter parsing when `PREFLIGHT_AST_ENGINE=wasm`; falls back to regex extraction otherwise.
-- Emits `imports` edges (file → module) and, when resolvable, `imports_resolved` edges (file → internal file).
+- Emits `imports` edges (file → module) and `imports_resolved` edges (file → internal file).
 
 ### `preflight_trace_upsert`
 Upsert traceability links (commit↔ticket, symbol↔test, code↔doc, etc.) for a bundle.
@@ -210,6 +218,12 @@ Parameters:
 
 Note: This is also automatically executed on server startup (background, non-blocking).
 
+### `preflight_get_task_status`
+Check status of bundle creation/update tasks (progress tracking).
+- Triggers: "check progress", "what is the status", "查看任务状态", "下载进度"
+- Query by `taskId` (from error), `fingerprint`, or `repos`
+- Shows: phase, progress percentage, message, elapsed time
+
 ## Resources
 
 ### `preflight://bundles`

package/dist/bundle/github.js

@@ -13,8 +13,26 @@ export function parseOwnerRepo(input) {
 export function toCloneUrl(ref) {
     return `https://github.com/${ref.owner}/${ref.repo}.git`;
 }
+/**
+ * Parse git clone progress from stderr.
+ * Git outputs progress like:
+ * - "Receiving objects:  45% (1234/2741)"
+ * - "Resolving deltas:  60% (100/167)"
+ */
+function parseGitProgress(line) {
+    // Match patterns like "Receiving objects:  45% (1234/2741)"
+    const match = line.match(/(Receiving objects|Resolving deltas|Counting objects|Compressing objects):\s+(\d+)%/);
+    if (match) {
+        return {
+            phase: match[1],
+            percent: parseInt(match[2], 10),
+        };
+    }
+    return null;
+}
 async function runGit(args, opts) {
     const timeoutMs = opts?.timeoutMs ?? 5 * 60_000;
+    const onProgress = opts?.onProgress;
     return new Promise((resolve, reject) => {
         const child = spawn('git', args, {
             cwd: opts?.cwd,
@@ -65,7 +83,19 @@ async function runGit(args, opts) {
             stdout += data.toString('utf8');
         });
         child.stderr?.on('data', (data) => {
-            stderr += data.toString('utf8');
+            const chunk = data.toString('utf8');
+            stderr += chunk;
+            // Parse and report progress
+            if (onProgress) {
+                // Git progress can come in chunks, split by lines
+                const lines = chunk.split(/[\r\n]+/);
+                for (const line of lines) {
+                    const progress = parseGitProgress(line);
+                    if (progress) {
+                        onProgress(progress.phase, progress.percent, `${progress.phase}: ${progress.percent}%`);
+                    }
+                }
+            }
         });
         child.on('error', (err) => {
             cleanup();
@@ -125,14 +155,15 @@ export async function shallowClone(cloneUrl, destDir, opts) {
     await fs.mkdir(path.dirname(destDir), { recursive: true });
     // Clean dest if exists.
     await fs.rm(destDir, { recursive: true, force: true });
-    const args = ['-c', 'core.autocrlf=false', 'clone', '--depth', '1', '--no-tags', '--single-branch'];
+    // Use --progress to force progress output even when not attached to a terminal
+    const args = ['-c', 'core.autocrlf=false', 'clone', '--depth', '1', '--no-tags', '--single-branch', '--progress'];
     if (opts?.ref) {
         // Validate ref before using it in git command
         validateGitRef(opts.ref);
         args.push('--branch', opts.ref);
     }
     args.push(cloneUrl, destDir);
-    await runGit(args, { timeoutMs: opts?.timeoutMs ?? 15 * 60_000 });
+    await runGit(args, { timeoutMs: opts?.timeoutMs ?? 15 * 60_000, onProgress: opts?.onProgress });
 }
 export async function getLocalHeadSha(repoDir) {
     const { stdout } = await runGit(['-C', repoDir, 'rev-parse', 'HEAD']);

package/dist/bundle/githubArchive.js

@@ -7,7 +7,7 @@ function nowIso() {
 }
 function githubHeaders(cfg) {
     const headers = {
-        'User-Agent': 'preflight-mcp/0.1.3',
+        'User-Agent': 'preflight-mcp/0.1.5',
         Accept: 'application/vnd.github+json',
     };
     if (cfg.githubToken) {
@@ -36,7 +36,7 @@ async function fetchJson(url, headers, timeoutMs = DEFAULT_API_TIMEOUT_MS) {
         clearTimeout(timeoutId);
     }
 }
-async function downloadToFile(url, headers, destPath, timeoutMs = DEFAULT_DOWNLOAD_TIMEOUT_MS) {
+async function downloadToFile(url, headers, destPath, timeoutMs = DEFAULT_DOWNLOAD_TIMEOUT_MS, onProgress) {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
     try {
@@ -44,12 +44,51 @@ async function downloadToFile(url, headers, destPath, timeoutMs = DEFAULT_DOWNLO
         if (!res.ok) {
             throw new Error(`Download error ${res.status}: ${res.statusText}`);
         }
-        // Use streaming if possible; otherwise fallback to arrayBuffer.
+        // Get content length for progress reporting
+        const contentLengthHeader = res.headers.get('content-length');
+        const totalBytes = contentLengthHeader ? parseInt(contentLengthHeader, 10) : undefined;
+        await ensureDir(path.dirname(destPath));
+        // Use streaming to report progress
         const anyRes = res;
         const body = anyRes.body;
-        await ensureDir(path.dirname(destPath));
+        if (body && typeof body[Symbol.asyncIterator] === 'function') {
+            // Async iterator for progress tracking
+            const fsModule = await import('node:fs');
+            const ws = fsModule.createWriteStream(destPath);
+            let downloadedBytes = 0;
+            let lastReportTime = Date.now();
+            const reportIntervalMs = 500; // Report at most every 500ms
+            try {
+                for await (const chunk of body) {
+                    ws.write(chunk);
+                    downloadedBytes += chunk.length;
+                    // Throttle progress reports
+                    const now = Date.now();
+                    if (onProgress && (now - lastReportTime > reportIntervalMs)) {
+                        lastReportTime = now;
+                        const percent = totalBytes ? Math.round((downloadedBytes / totalBytes) * 100) : 0;
+                        const msg = totalBytes
+                            ? `Downloaded ${formatBytes(downloadedBytes)} / ${formatBytes(totalBytes)} (${percent}%)`
+                            : `Downloaded ${formatBytes(downloadedBytes)}`;
+                        onProgress(downloadedBytes, totalBytes, msg);
+                    }
+                }
+            }
+            finally {
+                ws.end();
+                await new Promise((resolve) => ws.on('finish', () => resolve()));
+            }
+            // Final progress report
+            if (onProgress) {
+                const msg = totalBytes
+                    ? `Downloaded ${formatBytes(downloadedBytes)} / ${formatBytes(totalBytes)} (100%)`
+                    : `Downloaded ${formatBytes(downloadedBytes)}`;
+                onProgress(downloadedBytes, totalBytes, msg);
+            }
+            return;
+        }
         if (body && typeof body.pipe === 'function') {
-            // Node.js stream
+            // Node.js stream (fallback without progress)
             const ws = (await import('node:fs')).createWriteStream(destPath);
             await new Promise((resolve, reject) => {
                 body.pipe(ws);
@@ -59,14 +98,27 @@ async function downloadToFile(url, headers, destPath, timeoutMs = DEFAULT_DOWNLO
             });
             return;
         }
-        // Web stream or no stream support.
+        // Web stream or no stream support (fallback without progress)
         const buf = Buffer.from(await res.arrayBuffer());
         await fs.writeFile(destPath, buf);
+        if (onProgress) {
+            onProgress(buf.length, buf.length, `Downloaded ${formatBytes(buf.length)}`);
+        }
     }
     finally {
         clearTimeout(timeoutId);
     }
 }
+/** Format bytes for display */
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes}B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)}KB`;
+    if (bytes < 1024 * 1024 * 1024)
+        return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)}GB`;
+}
 async function extractZip(zipPath, destDir) {
     await ensureDir(destDir);
     const zip = new AdmZip(zipPath);
@@ -91,7 +143,7 @@ export async function downloadAndExtractGitHubArchive(params) {
     // Use the API zipball endpoint so ref can be branch/tag/SHA (including slashes via URL-encoding).
     const zipballUrl = `https://api.github.com/repos/${params.owner}/${params.repo}/zipball/${encodeURIComponent(refUsed)}`;
     await ensureDir(params.destDir);
-    await downloadToFile(zipballUrl, headers, zipPath);
+    await downloadToFile(zipballUrl, headers, zipPath, DEFAULT_DOWNLOAD_TIMEOUT_MS, params.onProgress);
     const extractDir = path.join(params.destDir, `extracted-${Date.now()}`);
     await extractZip(zipPath, extractDir);
     const repoRoot = await findSingleTopLevelDir(extractDir);