preflight-mcp 0.1.4 → 0.1.5

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) {

package/dist/bundle/service.js

@@ -746,6 +746,7 @@ async function cloneAndIngestGitHubRepo(params) {
     let repoRootForIngest = tmpCheckoutGit;
     let headSha;
     const notes = [];
+    const warnings = [];
     let source = 'git';
     let fetchedAt = nowIso();
     let refUsed = params.ref;
@@ -763,23 +764,49 @@ async function cloneAndIngestGitHubRepo(params) {
     catch (err) {
         // Fallback: GitHub archive download (zipball) + extract.
         source = 'archive';
-        const msg = err instanceof Error ? err.message : String(err);
-        notes.push(`git clone failed; used GitHub archive fallback: ${msg}`);
+        const errMsg = err instanceof Error ? err.message : String(err);
+        notes.push(`git clone failed; used GitHub archive fallback: ${errMsg}`);
+        // User-facing warning: communicate the network issue clearly
+        warnings.push(`⚠️ [${repoId}] Git clone failed (network issue), switched to ZIP download.\n` +
+            `   Reason: ${errMsg.slice(0, 200)}${errMsg.length > 200 ? '...' : ''}`);
         params.onProgress?.('downloading', 0, `Downloading ${repoId} archive...`);
-        const archive = await downloadAndExtractGitHubArchive({
-            cfg: params.cfg,
-            owner: params.owner,
-            repo: params.repo,
-            ref: params.ref,
-            destDir: tmpArchiveDir,
-            onProgress: (downloaded, total, msg) => {
-                const percent = total ? Math.round((downloaded / total) * 100) : 0;
-                params.onProgress?.('downloading', percent, `${repoId}: ${msg}`);
-            },
-        });
-        repoRootForIngest = archive.repoRoot;
-        fetchedAt = archive.fetchedAt;
-        refUsed = archive.refUsed;
+        // Track zip path for error message
+        const zipPath = path.join(tmpArchiveDir, `github-zipball-${params.owner}-${params.repo}-partial.zip`);
+        try {
+            const archive = await downloadAndExtractGitHubArchive({
+                cfg: params.cfg,
+                owner: params.owner,
+                repo: params.repo,
+                ref: params.ref,
+                destDir: tmpArchiveDir,
+                onProgress: (downloaded, total, msg) => {
+                    const percent = total ? Math.round((downloaded / total) * 100) : 0;
+                    params.onProgress?.('downloading', percent, `${repoId}: ${msg}`);
+                },
+            });
+            repoRootForIngest = archive.repoRoot;
+            fetchedAt = archive.fetchedAt;
+            refUsed = archive.refUsed;
+            // Success: ZIP download completed
+            warnings.push(`✅ [${repoId}] ZIP download completed successfully as fallback.`);
+        }
+        catch (zipErr) {
+            // ZIP download also failed - provide helpful error with temp path
+            const zipErrMsg = zipErr instanceof Error ? zipErr.message : String(zipErr);
+            // Check if partial file exists
+            const partialExists = await statOrNull(tmpArchiveDir);
+            const tempPathMsg = partialExists
+                ? `\n   Partial files may exist in: ${tmpArchiveDir}`
+                : '';
+            throw new Error(`Both git clone and ZIP download failed for ${repoId}.\n\n` +
+                `Git error: ${errMsg.slice(0, 150)}\n` +
+                `ZIP error: ${zipErrMsg.slice(0, 150)}${tempPathMsg}\n\n` +
+                `Suggestions:\n` +
+                `1. Check your network connection\n` +
+                `2. Verify the repository exists: https://github.com/${repoId}\n` +
+                `3. If you have the repo locally, use 'kind: local' with 'path: /your/local/path'\n` +
+                `4. If behind a proxy, configure GITHUB_TOKEN environment variable`);
+        }
     }
     const bundlePaths = getBundlePaths(params.storageDir, params.bundleId);
     const rawDest = repoRawDir(bundlePaths, params.owner, params.repo);
@@ -813,7 +840,7 @@ async function cloneAndIngestGitHubRepo(params) {
     });
     await rmIfExists(tmpCheckoutGit);
     await rmIfExists(tmpArchiveDir);
-    return { headSha, files: ingested.files, skipped: ingested.skipped, notes, source };
+    return { headSha, files: ingested.files, skipped: ingested.skipped, notes, warnings, source };
 }
 function groupFilesByRepoId(files) {
     const byRepo = new Map();
@@ -912,6 +939,9 @@ async function createBundleInternal(cfg, input, options) {
     const finalPaths = getBundlePaths(effectiveStorageDir, bundleId);
     const allIngestedFiles = [];
     const reposSummary = [];
+    const allWarnings = [];
+    // Track temp checkout directory for cleanup
+    const tmpCheckoutsDir = path.join(cfg.tmpDir, 'checkouts', bundleId);
     try {
         // All operations happen in tmpPaths (temporary directory)
         const totalRepos = input.repos.length;
@@ -923,7 +953,7 @@ async function createBundleInternal(cfg, input, options) {
                 const { owner, repo } = parseOwnerRepo(repoInput.repo);
                 reportProgress('cloning', repoProgress, `[${repoIndex}/${totalRepos}] Fetching ${owner}/${repo}...`);
                 tracker.updateProgress(taskId, 'cloning', repoProgress, `Fetching ${owner}/${repo}...`);
-                const { headSha, files, skipped, notes, source } = await cloneAndIngestGitHubRepo({
+                const { headSha, files, skipped, notes, warnings, source } = await cloneAndIngestGitHubRepo({
                     cfg,
                     bundleId,
                     storageDir: tmpBundlesDir,
@@ -938,6 +968,7 @@ async function createBundleInternal(cfg, input, options) {
                     },
                 });
                 allIngestedFiles.push(...files);
+                allWarnings.push(...warnings);
                 reposSummary.push({
                     kind: 'github',
                     id: `${owner}/${repo}`,
@@ -1112,6 +1143,7 @@ async function createBundleInternal(cfg, input, options) {
             updatedAt: createdAt,
             repos: reposSummary,
             libraries: librariesSummary,
+            warnings: allWarnings.length > 0 ? allWarnings : undefined,
         };
         return summary;
     }
@@ -1135,6 +1167,10 @@ async function createBundleInternal(cfg, input, options) {
         await rmIfExists(tmpPaths.rootDir).catch((err) => {
             logger.debug('Failed to cleanup temp bundle directory in finally block (non-critical)', err instanceof Error ? err : undefined);
         });
+        // Clean up temp checkouts directory (git clones, zip extracts)
+        await rmIfExists(tmpCheckoutsDir).catch((err) => {
+            logger.debug('Failed to cleanup temp checkouts directory in finally block (non-critical)', err instanceof Error ? err : undefined);
+        });
     }
 }
 /** Check if a bundle has upstream changes without applying updates. */
@@ -1297,6 +1333,14 @@ export async function repairBundle(cfg, bundleId, options) {
     // Manifest is required for safe repairs (no fetching/re-ingest).
     const manifest = await readManifest(paths.manifestPath);
     const actionsTaken = [];
+    const unfixableIssues = [];
+    // Check for unfixable issues (require re-download, can't be repaired offline)
+    const reposHasContent = before.missingComponents.every(c => !c.includes('repos/'));
+    if (!reposHasContent) {
+        unfixableIssues.push('repos/ directory is empty or missing - this requires re-downloading the repository. ' +
+            'Use preflight_delete_bundle and preflight_create_bundle to start fresh, ' +
+            'or use preflight_update_bundle with force:true to re-fetch.');
+    }
     // Determine what needs repair.
     const stAgents = await statOrNull(paths.agentsPath);
     const stStartHere = await statOrNull(paths.startHerePath);
@@ -1384,6 +1428,7 @@ export async function repairBundle(cfg, bundleId, options) {
         mode,
         repaired: actionsTaken.length > 0,
         actionsTaken,
+        unfixableIssues: unfixableIssues.length > 0 ? unfixableIssues : undefined,
         before,
         after,
         updatedAt,

package/dist/context7/client.js

@@ -20,7 +20,7 @@ export async function connectContext7(cfg) {
             maxRetries: 1,
         },
     });
-    const client = new Client({ name: 'preflight-context7', version: '0.1.3' });
+    const client = new Client({ name: 'preflight-context7', version: '0.1.5' });
     await client.connect(transport);
     return {
         client,

package/dist/server.js

@@ -99,7 +99,7 @@ export async function startServer() {
     startHttpServer(cfg);
     const server = new McpServer({
         name: 'preflight-mcp',
-        version: '0.1.4',
+        version: '0.1.5',
         description: 'Create evidence-based preflight bundles for repositories (docs + code) with SQLite FTS search.',
     }, {
         capabilities: {
@@ -382,22 +382,23 @@ export async function startServer() {
         description: 'Create a new bundle from GitHub repos or local directories (or update an existing one if ifExists=updateExisting). Use when: "index this repo", "create bundle for", "add repo to preflight", "索引这个仓库", "创建bundle", "添加GitHub项目", "学习这个项目". NOTE: If the bundle contains code files, consider asking user if they want to generate dependency graph (preflight_evidence_dependency_graph) or establish trace links (preflight_trace_upsert).',
         inputSchema: CreateBundleInputSchema,
         outputSchema: {
-            bundleId: z.string(),
-            createdAt: z.string(),
-            updatedAt: z.string(),
+            // Normal completion fields
+            bundleId: z.string().optional(),
+            createdAt: z.string().optional(),
+            updatedAt: z.string().optional(),
             resources: z.object({
                 startHere: z.string(),
                 agents: z.string(),
                 overview: z.string(),
                 manifest: z.string(),
-            }),
+            }).optional(),
             repos: z.array(z.object({
                 kind: z.enum(['github', 'local']),
                 id: z.string(),
                 source: z.enum(['git', 'archive', 'local']).optional(),
                 headSha: z.string().optional(),
                 notes: z.array(z.string()).optional(),
-            })),
+            })).optional(),
             libraries: z
                 .array(z.object({
                 kind: z.literal('context7'),
@@ -408,6 +409,20 @@ export async function startServer() {
                 files: z.array(z.string()).optional(),
             }))
                 .optional(),
+            // User-facing warnings (e.g., git clone failed, used zip fallback)
+            warnings: z.array(z.string()).optional(),
+            // In-progress status fields
+            status: z.enum(['in-progress', 'complete']).optional(),
+            message: z.string().optional(),
+            taskId: z.string().optional(),
+            fingerprint: z.string().optional(),
+            /** Repo IDs requested (for in-progress status only, different from repos array) */
+            requestedRepos: z.array(z.string()).optional(),
+            startedAt: z.string().optional(),
+            elapsedSeconds: z.number().optional(),
+            currentPhase: z.string().optional(),
+            currentProgress: z.number().optional(),
+            currentMessage: z.string().optional(),
         },
         annotations: {
             openWorldHint: true,
@@ -431,8 +446,19 @@ export async function startServer() {
                 ...summary,
                 resources,
             };
+            // Build text response - prominently show warnings if any
+            let textResponse = '';
+            if (summary.warnings && summary.warnings.length > 0) {
+                textResponse += '📢 **Network Issues Encountered:**\n';
+                for (const warn of summary.warnings) {
+                    textResponse += `${warn}\n`;
+                }
+                textResponse += '\n';
+            }
+            textResponse += `✅ Bundle created: ${summary.bundleId}\n`;
+            textResponse += `Repos: ${summary.repos.map(r => `${r.id} (${r.source})`).join(', ')}`;
             return {
-                content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
+                content: [{ type: 'text', text: textResponse }],
                 structuredContent: out,
             };
         }
@@ -450,7 +476,7 @@ export async function startServer() {
                     message: `Bundle creation already in progress. Use preflight_get_task_status to check progress.`,
                     taskId: err.taskId,
                     fingerprint: err.fingerprint,
-                    repos: err.repos,
+                    requestedRepos: err.repos,
                     startedAt: err.startedAt,
                     elapsedSeconds: elapsedSec,
                     currentPhase: task?.phase,
@@ -474,6 +500,8 @@ export async function startServer() {
             mode: z.enum(['validate', 'repair']),
             repaired: z.boolean(),
             actionsTaken: z.array(z.string()),
+            /** Issues that cannot be fixed by repair (require re-download) */
+            unfixableIssues: z.array(z.string()).optional(),
             before: z.object({
                 isValid: z.boolean(),
                 missingComponents: z.array(z.string()),
@@ -495,11 +523,21 @@ export async function startServer() {
                 rebuildGuides: args.rebuildGuides,
                 rebuildOverview: args.rebuildOverview,
             });
-            const summaryLine = out.mode === 'validate'
-                ? `VALIDATE ${out.bundleId}: ${out.before.isValid ? 'OK' : 'MISSING'} (${out.before.missingComponents.length} issue(s))`
-                : out.repaired
-                    ? `REPAIRED ${out.bundleId}: ${out.actionsTaken.length} action(s), now ${out.after.isValid ? 'OK' : 'STILL_MISSING'} (${out.after.missingComponents.length} issue(s))`
-                    : `NOOP ${out.bundleId}: nothing to repair (already OK)`;
+            let summaryLine;
+            if (out.mode === 'validate') {
+                summaryLine = `VALIDATE ${out.bundleId}: ${out.before.isValid ? 'OK' : 'INVALID'} (${out.before.missingComponents.length} issue(s))`;
+            }
+            else if (out.unfixableIssues && out.unfixableIssues.length > 0) {
+                // Has unfixable issues - clearly communicate this
+                summaryLine = `⚠️ UNFIXABLE ${out.bundleId}: ${out.unfixableIssues.length} issue(s) cannot be repaired offline.\n` +
+                    out.unfixableIssues.map(i => `  - ${i}`).join('\n');
+            }
+            else if (out.repaired) {
+                summaryLine = `REPAIRED ${out.bundleId}: ${out.actionsTaken.length} action(s), now ${out.after.isValid ? 'OK' : 'STILL_INVALID'} (${out.after.missingComponents.length} issue(s))`;
+            }
+            else {
+                summaryLine = `NOOP ${out.bundleId}: nothing to repair (already OK)`;
+            }
             return {
                 content: [{ type: 'text', text: summaryLine }],
                 structuredContent: out,

package/package.json

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