preflight-mcp 0.1.1 → 0.1.3

package/dist/bundle/service.js

@@ -11,7 +11,6 @@ import { writeAgentsMd, writeStartHereMd } from './guides.js';
 import { generateOverviewMarkdown, writeOverviewFile } from './overview.js';
 import { rebuildIndex } from '../search/sqliteFts.js';
 import { ingestContext7Libraries } from './context7.js';
-import { ingestDeepWikiRepo } from './deepwiki.js';
 import { analyzeBundleStatic } from './analysis.js';
 import { autoDetectTags, generateDisplayName, generateDescription } from './tagging.js';
 import { bundleCreationLimiter } from '../core/concurrency-limiter.js';
@@ -26,48 +25,20 @@ function normalizeList(values) {
         .map((s) => s.toLowerCase())
         .sort();
 }
-function normalizeDeepWikiUrl(raw) {
-    const trimmed = raw.trim();
-    try {
-        const u = new URL(trimmed);
-        u.hash = '';
-        // Normalize host and strip trailing slash.
-        u.host = u.host.toLowerCase();
-        u.pathname = u.pathname.replace(/\/+$/g, '');
-        return u.toString();
-    }
-    catch {
-        return trimmed;
-    }
-}
 function canonicalizeCreateInput(input) {
     const repos = input.repos
         .map((r) => {
-        if (r.kind === 'github') {
-            const { owner, repo } = parseOwnerRepo(r.repo);
-            return {
-                kind: 'github',
-                repo: `${owner.toLowerCase()}/${repo.toLowerCase()}`,
-                ref: (r.ref ?? '').trim() || undefined,
-            };
-        }
-        if (r.kind === 'local') {
-            // For de-duplication, treat local imports as equivalent to github imports of the same logical repo/ref.
-            const { owner, repo } = parseOwnerRepo(r.repo);
-            return {
-                kind: 'github',
-                repo: `${owner.toLowerCase()}/${repo.toLowerCase()}`,
-                ref: (r.ref ?? '').trim() || undefined,
-            };
-        }
+        // For de-duplication, treat local imports as equivalent to github imports of the same logical repo/ref.
+        const { owner, repo } = parseOwnerRepo(r.repo);
         return {
-            kind: 'deepwiki',
-            url: normalizeDeepWikiUrl(r.url),
+            kind: 'github',
+            repo: `${owner.toLowerCase()}/${repo.toLowerCase()}`,
+            ref: (r.ref ?? '').trim() || undefined,
         };
     })
         .sort((a, b) => {
-        const ka = a.kind === 'github' ? `github:${a.repo}:${a.ref ?? ''}` : `deepwiki:${a.url}`;
-        const kb = b.kind === 'github' ? `github:${b.repo}:${b.ref ?? ''}` : `deepwiki:${b.url}`;
+        const ka = `github:${a.repo}:${a.ref ?? ''}`;
+        const kb = `github:${b.repo}:${b.ref ?? ''}`;
         return ka.localeCompare(kb);
     });
     return {
@@ -113,8 +84,8 @@ async function writeDedupIndex(storageDir, idx) {
         try {
             await fs.unlink(tmpPath);
         }
-        catch {
-            // Ignore cleanup errors
+        catch (cleanupErr) {
+            logger.debug('Failed to cleanup temp dedup index file (non-critical)', cleanupErr instanceof Error ? cleanupErr : undefined);
         }
         throw err;
     }
@@ -131,8 +102,8 @@ async function updateDedupIndexBestEffort(cfg, fingerprint, bundleId, bundleUpda
             idx.updatedAt = nowIso();
             await writeDedupIndex(storageDir, idx);
         }
-        catch {
-            // best-effort
+        catch (err) {
+            logger.debug(`Failed to update dedup index in ${storageDir} (best-effort)`, err instanceof Error ? err : undefined);
         }
     }
 }
@@ -768,21 +739,23 @@ async function createBundleInternal(cfg, input, options) {
     const createdAt = nowIso();
     // Use effective storage dir (falls back if primary unavailable)
     const effectiveStorageDir = await getEffectiveStorageDirForWrite(cfg);
-    await ensureDir(cfg.tmpDir);
-    const paths = getBundlePaths(effectiveStorageDir, bundleId);
-    await ensureDir(paths.rootDir);
-    let bundleCreated = false;
+    // Create bundle in temporary directory for atomic creation
+    const tmpBundlesDir = path.join(cfg.tmpDir, 'bundles-wip');
+    await ensureDir(tmpBundlesDir);
+    const tmpPaths = getBundlePaths(tmpBundlesDir, bundleId);
+    await ensureDir(tmpPaths.rootDir);
+    const finalPaths = getBundlePaths(effectiveStorageDir, bundleId);
     const allIngestedFiles = [];
     const reposSummary = [];
     try {
-        bundleCreated = true; // Mark that bundle directory was created
+        // All operations happen in tmpPaths (temporary directory)
         for (const repoInput of input.repos) {
             if (repoInput.kind === 'github') {
                 const { owner, repo } = parseOwnerRepo(repoInput.repo);
                 const { headSha, files, skipped, notes, source } = await cloneAndIngestGitHubRepo({
                     cfg,
                     bundleId,
-                    storageDir: effectiveStorageDir,
+                    storageDir: tmpBundlesDir,
                     owner,
                     repo,
                     ref: repoInput.ref,
@@ -796,12 +769,13 @@ async function createBundleInternal(cfg, input, options) {
                     notes: [...notes, ...skipped].slice(0, 50),
                 });
             }
-            else if (repoInput.kind === 'local') {
+            else {
+                // Local repository
                 const { owner, repo } = parseOwnerRepo(repoInput.repo);
                 const { files, skipped } = await ingestLocalRepo({
                     cfg,
                     bundleId,
-                    storageDir: effectiveStorageDir,
+                    storageDir: tmpBundlesDir,
                     owner,
                     repo,
                     localPath: repoInput.path,
@@ -810,31 +784,16 @@ async function createBundleInternal(cfg, input, options) {
                 allIngestedFiles.push(...files);
                 reposSummary.push({ kind: 'local', id: `${owner}/${repo}`, source: 'local', notes: skipped.slice(0, 50) });
             }
-            else {
-                // DeepWiki integration: fetch and convert to Markdown.
-                const deepwikiResult = await ingestDeepWikiRepo({
-                    cfg,
-                    bundlePaths: paths,
-                    url: repoInput.url,
-                });
-                allIngestedFiles.push(...deepwikiResult.files);
-                reposSummary.push({
-                    kind: 'deepwiki',
-                    id: deepwikiResult.summary.repoId,
-                    source: 'deepwiki',
-                    notes: deepwikiResult.summary.notes,
-                });
-            }
         }
         // Context7 libraries (best-effort).
         let librariesSummary;
         if (input.libraries?.length) {
             // Clean libraries dir in case something wrote here earlier.
-            await rmIfExists(paths.librariesDir);
-            await ensureDir(paths.librariesDir);
+            await rmIfExists(tmpPaths.librariesDir);
+            await ensureDir(tmpPaths.librariesDir);
             const libIngest = await ingestContext7Libraries({
                 cfg,
-                bundlePaths: paths,
+                bundlePaths: tmpPaths,
                 libraries: input.libraries,
                 topics: input.topics,
             });
@@ -842,7 +801,7 @@ async function createBundleInternal(cfg, input, options) {
             librariesSummary = libIngest.libraries;
         }
         // Build index.
-        await rebuildIndex(paths.searchDbPath, allIngestedFiles, {
+        await rebuildIndex(tmpPaths.searchDbPath, allIngestedFiles, {
             includeDocs: true,
             includeCode: true,
         });
@@ -890,16 +849,23 @@ async function createBundleInternal(cfg, input, options) {
                 includeCode: true,
             },
         };
-        await writeManifest(paths.manifestPath, manifest);
+        await writeManifest(tmpPaths.manifestPath, manifest);
         // Guides.
-        await writeAgentsMd(paths.agentsPath);
+        await writeAgentsMd(tmpPaths.agentsPath);
         await writeStartHereMd({
-            targetPath: paths.startHerePath,
+            targetPath: tmpPaths.startHerePath,
             bundleId,
             repos: reposSummary.map((r) => ({ id: r.id, headSha: r.headSha })),
             libraries: librariesSummary,
         });
-        // Overview (S2: factual-only with evidence pointers).
+        // Generate static facts (FACTS.json) FIRST. This is intentionally non-LLM and safe to keep inside bundles.
+        await generateFactsBestEffort({
+            bundleId,
+            bundleRoot: tmpPaths.rootDir,
+            files: allIngestedFiles,
+            mode: cfg.analysisMode,
+        });
+        // Overview (S2: factual-only with evidence pointers) - generated AFTER FACTS.json
         const perRepoOverviews = reposSummary
             .filter((r) => r.kind === 'github' || r.kind === 'local')
             .map((r) => {
@@ -909,30 +875,46 @@ async function createBundleInternal(cfg, input, options) {
         });
         const overviewMd = await generateOverviewMarkdown({
             bundleId,
-            bundleRootDir: paths.rootDir,
+            bundleRootDir: tmpPaths.rootDir,
             repos: perRepoOverviews,
             libraries: librariesSummary,
         });
-        await writeOverviewFile(paths.overviewPath, overviewMd);
-        // Generate static facts (FACTS.json). This is intentionally non-LLM and safe to keep inside bundles.
-        await generateFactsBestEffort({
-            bundleId,
-            bundleRoot: paths.rootDir,
-            files: allIngestedFiles,
-            mode: cfg.analysisMode,
-        });
-        // Mirror to backup storage directories (non-blocking on failures)
-        if (cfg.storageDirs.length > 1) {
-            await mirrorBundleToBackups(effectiveStorageDir, cfg.storageDirs, bundleId);
-        }
-        // CRITICAL: Validate bundle completeness before finalizing
-        const validation = await validateBundleCompleteness(paths.rootDir);
+        await writeOverviewFile(tmpPaths.overviewPath, overviewMd);
+        // CRITICAL: Validate bundle completeness BEFORE atomic move
+        const validation = await validateBundleCompleteness(tmpPaths.rootDir);
         if (!validation.isValid) {
             const errorMsg = `Bundle creation incomplete. Missing: ${validation.missingComponents.join(', ')}`;
             logger.error(errorMsg);
             throw new Error(errorMsg);
         }
-        // Update de-duplication index (best-effort). This is intentionally after validation.
+        // ATOMIC OPERATION: Move from temp to final location
+        // This is atomic on most filesystems - bundle becomes visible only when complete
+        logger.info(`Moving bundle ${bundleId} from temp to final location (atomic)`);
+        await ensureDir(effectiveStorageDir);
+        try {
+            // Try rename first (atomic, but only works on same filesystem)
+            await fs.rename(tmpPaths.rootDir, finalPaths.rootDir);
+            logger.info(`Bundle ${bundleId} moved atomically to ${finalPaths.rootDir}`);
+        }
+        catch (renameErr) {
+            // Rename failed - likely cross-filesystem. Fall back to copy+delete
+            const errCode = renameErr.code;
+            if (errCode === 'EXDEV') {
+                logger.warn(`Cross-filesystem move detected for ${bundleId}, falling back to copy`);
+                await copyDir(tmpPaths.rootDir, finalPaths.rootDir);
+                await rmIfExists(tmpPaths.rootDir);
+                logger.info(`Bundle ${bundleId} copied to ${finalPaths.rootDir}`);
+            }
+            else {
+                // Some other error, rethrow
+                throw renameErr;
+            }
+        }
+        // Mirror to backup storage directories (non-blocking on failures)
+        if (cfg.storageDirs.length > 1) {
+            await mirrorBundleToBackups(effectiveStorageDir, cfg.storageDirs, bundleId);
+        }
+        // Update de-duplication index (best-effort). This is intentionally after atomic move.
         await updateDedupIndexBestEffort(cfg, fingerprint, bundleId, createdAt);
         const summary = {
             bundleId,
@@ -944,15 +926,19 @@ async function createBundleInternal(cfg, input, options) {
         return summary;
     }
     catch (err) {
-        // If bundle directory was created, clean it up
-        if (bundleCreated) {
-            logger.error(`Bundle creation failed, cleaning up: ${bundleId}`, err instanceof Error ? err : undefined);
-            await cleanupFailedBundle(cfg, bundleId);
-        }
+        // Clean up temp directory on failure
+        logger.error(`Bundle creation failed, cleaning up temp: ${bundleId}`, err instanceof Error ? err : undefined);
+        await rmIfExists(tmpPaths.rootDir);
         // Enhance error message
         const errorMsg = err instanceof Error ? err.message : String(err);
         throw new Error(`Failed to create bundle: ${errorMsg}`);
     }
+    finally {
+        // Ensure temp directory is cleaned up (double safety)
+        await rmIfExists(tmpPaths.rootDir).catch((err) => {
+            logger.debug('Failed to cleanup temp bundle directory in finally block (non-critical)', err instanceof Error ? err : undefined);
+        });
+    }
 }
 /** Check if a bundle has upstream changes without applying updates. */
 export async function checkForUpdates(cfg, bundleId) {
@@ -979,19 +965,14 @@ export async function checkForUpdates(cfg, bundleId) {
                 hasUpdates = true;
             details.push({ repoId, currentSha: prev?.headSha, remoteSha, changed });
         }
-        else if (repoInput.kind === 'local') {
+        else {
+            // Local: can't reliably detect whether local files changed without scanning; assume possible update.
             const { owner, repo } = parseOwnerRepo(repoInput.repo);
             const repoId = `${owner}/${repo}`;
-            // We can't reliably detect whether local files changed without scanning; assume possible update.
             const prev = manifest.repos.find((r) => r.id === repoId);
             details.push({ repoId, currentSha: prev?.headSha, changed: true });
             hasUpdates = true;
         }
-        else {
-            // DeepWiki: can't easily detect changes, assume possible update
-            details.push({ repoId: repoInput.url, changed: true });
-            hasUpdates = true;
-        }
     }
     return { hasUpdates, details };
 }
@@ -1093,41 +1074,6 @@ async function scanBundleIndexableFiles(params) {
             });
         }
     }
-    // 3) deepwiki/<owner>/<repo>/norm/** (docs-only)
-    const deepwikiDir = path.join(params.bundleRootDir, 'deepwiki');
-    const dwSt = await statOrNull(deepwikiDir);
-    if (dwSt?.isDirectory()) {
-        // Only walk the norm subtrees.
-        const owners = await fs.readdir(deepwikiDir, { withFileTypes: true });
-        for (const ownerEnt of owners) {
-            if (!ownerEnt.isDirectory())
-                continue;
-            const owner = ownerEnt.name;
-            const ownerDir = path.join(deepwikiDir, owner);
-            const repos = await fs.readdir(ownerDir, { withFileTypes: true });
-            for (const repoEnt of repos) {
-                if (!repoEnt.isDirectory())
-                    continue;
-                const repo = repoEnt.name;
-                const normDir = path.join(ownerDir, repo, 'norm');
-                const normSt = await statOrNull(normDir);
-                if (!normSt?.isDirectory())
-                    continue;
-                for await (const wf of walkFilesNoIgnore(normDir)) {
-                    if (!wf.relPosix.toLowerCase().endsWith('.md'))
-                        continue;
-                    const bundleRel = `deepwiki/${owner}/${repo}/norm/${wf.relPosix}`;
-                    await pushFile({
-                        repoId: `deepwiki:${owner}/${repo}`,
-                        kind: 'doc',
-                        repoRelativePath: wf.relPosix,
-                        bundleRelPosix: bundleRel,
-                        absPath: wf.absPath,
-                    });
-                }
-            }
-        }
-    }
     return { files, totalBytes, skipped };
 }
 export async function repairBundle(cfg, bundleId, options) {
@@ -1290,7 +1236,8 @@ export async function updateBundle(cfg, bundleId, options) {
             allIngestedFiles.push(...files);
             reposSummary.push({ kind: 'github', id: repoId, source, headSha, notes: [...notes, ...skipped].slice(0, 50) });
         }
-        else if (repoInput.kind === 'local') {
+        else {
+            // Local repository
             const { owner, repo } = parseOwnerRepo(repoInput.repo);
             const repoId = `${owner}/${repo}`;
             const { files, skipped } = await ingestLocalRepo({
@@ -1306,23 +1253,6 @@ export async function updateBundle(cfg, bundleId, options) {
             reposSummary.push({ kind: 'local', id: repoId, source: 'local', notes: skipped.slice(0, 50) });
             changed = true;
         }
-        else {
-            // DeepWiki integration: fetch and convert to Markdown.
-            const deepwikiResult = await ingestDeepWikiRepo({
-                cfg,
-                bundlePaths: paths,
-                url: repoInput.url,
-            });
-            allIngestedFiles.push(...deepwikiResult.files);
-            reposSummary.push({
-                kind: 'deepwiki',
-                id: deepwikiResult.summary.repoId,
-                source: 'deepwiki',
-                notes: deepwikiResult.summary.notes,
-            });
-            // Always mark as changed for DeepWiki since we can't easily detect content changes.
-            changed = true;
-        }
     }
     // Context7 libraries (best-effort).
     let librariesSummary;
@@ -1407,11 +1337,22 @@ export async function updateBundle(cfg, bundleId, options) {
     };
     return { summary, changed };
 }
+/**
+ * Check if a string is a valid UUID (v4 format).
+ * Bundle IDs should be UUIDs with dashes.
+ */
+function isValidBundleId(id) {
+    // UUID v4 format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    return uuidRegex.test(id);
+}
 /** List bundles from a single storage directory. */
 export async function listBundles(storageDir) {
     try {
         const entries = await fs.readdir(storageDir, { withFileTypes: true });
-        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+        return entries
+            .filter((e) => e.isDirectory() && isValidBundleId(e.name))
+            .map((e) => e.name);
     }
     catch {
         return [];
@@ -1457,18 +1398,45 @@ export async function clearBundle(storageDir, bundleId) {
     const p = getBundlePaths(storageDir, bundleId);
     await rmIfExists(p.rootDir);
 }
-/** Clear bundle from ALL storage directories (mirror delete). */
+/**
+ * Clear bundle from ALL storage directories (mirror delete).
+ * Uses fast rename + background deletion to avoid blocking.
+ */
 export async function clearBundleMulti(storageDirs, bundleId) {
     let deleted = false;
     for (const dir of storageDirs) {
         try {
-            if (await bundleExists(dir, bundleId)) {
+            const paths = getBundlePaths(dir, bundleId);
+            // Check if the bundle directory exists
+            try {
+                await fs.stat(paths.rootDir);
+            }
+            catch {
+                // Directory doesn't exist, skip
+                continue;
+            }
+            // Fast deletion strategy: rename first (instant), then delete in background
+            const deletingPath = `${paths.rootDir}.deleting.${Date.now()}`;
+            try {
+                // Rename is atomic and instant on most filesystems
+                await fs.rename(paths.rootDir, deletingPath);
+                deleted = true;
+                // Background deletion (fire-and-forget)
+                // The renamed directory is invisible to listBundles (not a valid UUID)
+                rmIfExists(deletingPath).catch((err) => {
+                    logger.warn(`Background deletion failed for ${bundleId}: ${err instanceof Error ? err.message : String(err)}`);
+                });
+            }
+            catch (err) {
+                // Rename failed (maybe concurrent deletion), try direct delete as fallback
+                logger.warn(`Rename failed for ${bundleId}, falling back to direct delete`);
                 await clearBundle(dir, bundleId);
                 deleted = true;
             }
         }
-        catch {
+        catch (err) {
             // Skip unavailable paths
+            logger.debug(`Failed to delete bundle from ${dir}: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
     return deleted;

package/dist/config.js

@@ -7,16 +7,35 @@ function envNumber(name, fallback) {
     const n = Number(raw);
     return Number.isFinite(n) && n > 0 ? n : fallback;
 }
+function envBoolean(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const v = raw.trim().toLowerCase();
+    if (v === '1' || v === 'true' || v === 'yes' || v === 'y' || v === 'on')
+        return true;
+    if (v === '0' || v === 'false' || v === 'no' || v === 'n' || v === 'off')
+        return false;
+    return fallback;
+}
+function parseAstEngine(raw) {
+    const v = (raw ?? '').trim().toLowerCase();
+    if (v === 'native')
+        return 'native';
+    return 'wasm';
+}
 function parseAnalysisMode(raw) {
     const v = (raw ?? '').trim().toLowerCase();
     if (v === 'none')
         return 'none';
     if (v === 'quick')
         return 'quick';
-    // Back-compat: deep used to exist; treat it as quick (but never run LLM).
+    if (v === 'full')
+        return 'full'; // Phase 2 module analysis
+    // Back-compat: deep used to exist; treat it as full (for better analysis).
     if (v === 'deep')
-        return 'quick';
-    return 'quick';
+        return 'full';
+    return 'full'; // Default to full for better analysis
 }
 /**
  * Parse storage directories from environment.
@@ -43,6 +62,9 @@ export function getConfig() {
     const storageDir = storageDirs[0]; // Primary for new bundles (always at least one from default)
     const tmpDir = process.env.PREFLIGHT_TMP_DIR ?? path.join(os.tmpdir(), 'preflight-mcp');
     const analysisMode = parseAnalysisMode(process.env.PREFLIGHT_ANALYSIS_MODE);
+    const httpEnabled = envBoolean('PREFLIGHT_HTTP_ENABLED', true);
+    const httpHost = (process.env.PREFLIGHT_HTTP_HOST ?? '127.0.0.1').trim() || '127.0.0.1';
+    const httpPort = envNumber('PREFLIGHT_HTTP_PORT', 37123);
     return {
         storageDir,
         storageDirs,
@@ -54,6 +76,10 @@ export function getConfig() {
         maxFileBytes: envNumber('PREFLIGHT_MAX_FILE_BYTES', 512 * 1024),
         maxTotalBytes: envNumber('PREFLIGHT_MAX_TOTAL_BYTES', 50 * 1024 * 1024),
         analysisMode,
+        astEngine: parseAstEngine(process.env.PREFLIGHT_AST_ENGINE),
+        httpEnabled,
+        httpHost,
+        httpPort,
         // Tuning parameters with defaults (can be overridden via env vars)
         maxContext7Libraries: envNumber('PREFLIGHT_MAX_CONTEXT7_LIBRARIES', 20),
         maxContext7Topics: envNumber('PREFLIGHT_MAX_CONTEXT7_TOPICS', 10),

package/dist/context7/client.js

@@ -1,5 +1,6 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { logger } from '../logging/logger.js';
 export async function connectContext7(cfg) {
     const url = new URL(cfg.context7McpUrl);
     const headers = {};
@@ -19,12 +20,14 @@ export async function connectContext7(cfg) {
             maxRetries: 1,
         },
     });
-    const client = new Client({ name: 'preflight-context7', version: '0.1.1' });
+    const client = new Client({ name: 'preflight-context7', version: '0.1.3' });
     await client.connect(transport);
     return {
         client,
         close: async () => {
-            await client.close().catch(() => undefined);
+            await client.close().catch((err) => {
+                logger.debug('Context7 client close failed (non-critical)', err instanceof Error ? err : undefined);
+            });
         },
     };
 }