preflight-mcp 0.1.2 → 0.1.4

package/dist/bundle/service.js

@@ -11,10 +11,10 @@ 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';
+import { getProgressTracker, calcPercent } from '../jobs/progressTracker.js';
 const DEDUP_INDEX_FILE = '.preflight-dedup-index.json';
 function sha256Hex(text) {
     return crypto.createHash('sha256').update(text, 'utf8').digest('hex');
@@ -26,48 +26,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,13 +85,13 @@ 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;
     }
 }
-async function updateDedupIndexBestEffort(cfg, fingerprint, bundleId, bundleUpdatedAt) {
+async function updateDedupIndexBestEffort(cfg, fingerprint, bundleId, bundleUpdatedAt, status = 'complete') {
     for (const storageDir of cfg.storageDirs) {
         try {
             const parentAvailable = await isParentAvailable(storageDir);
@@ -127,14 +99,105 @@ async function updateDedupIndexBestEffort(cfg, fingerprint, bundleId, bundleUpda
                 continue;
             await ensureDir(storageDir);
             const idx = await readDedupIndex(storageDir);
-            idx.byFingerprint[fingerprint] = { bundleId, bundleUpdatedAt };
+            idx.byFingerprint[fingerprint] = { bundleId, bundleUpdatedAt, status };
             idx.updatedAt = nowIso();
             await writeDedupIndex(storageDir, idx);
         }
+        catch (err) {
+            logger.debug(`Failed to update dedup index in ${storageDir} (best-effort)`, err instanceof Error ? err : undefined);
+        }
+    }
+}
+/**
+ * Set in-progress lock for a fingerprint. Returns false if already locked (not timed out).
+ */
+async function setInProgressLock(cfg, fingerprint, taskId, repos) {
+    const now = nowIso();
+    const nowMs = Date.now();
+    for (const storageDir of cfg.storageDirs) {
+        try {
+            if (!(await isPathAvailable(storageDir)))
+                continue;
+            await ensureDir(storageDir);
+            const idx = await readDedupIndex(storageDir);
+            const existing = idx.byFingerprint[fingerprint];
+            // Check if there's an existing in-progress lock
+            if (existing?.status === 'in-progress' && existing.startedAt) {
+                const startedMs = new Date(existing.startedAt).getTime();
+                const elapsed = nowMs - startedMs;
+                // If lock hasn't timed out, return the existing entry
+                if (elapsed < cfg.inProgressLockTimeoutMs) {
+                    return { locked: false, existingEntry: existing };
+                }
+                // Lock timed out - will be overwritten
+                logger.warn(`In-progress lock timed out for fingerprint ${fingerprint.slice(0, 8)}...`);
+            }
+            // Set new in-progress lock
+            idx.byFingerprint[fingerprint] = {
+                bundleId: '', // Will be set on completion
+                bundleUpdatedAt: now,
+                status: 'in-progress',
+                startedAt: now,
+                taskId,
+                repos,
+            };
+            idx.updatedAt = now;
+            await writeDedupIndex(storageDir, idx);
+            return { locked: true };
+        }
+        catch (err) {
+            logger.debug(`Failed to set in-progress lock in ${storageDir}`, err instanceof Error ? err : undefined);
+        }
+    }
+    // If we couldn't write to any storage, assume we can proceed (best-effort)
+    return { locked: true };
+}
+/**
+ * Clear in-progress lock (on failure or completion with status='complete').
+ */
+async function clearInProgressLock(cfg, fingerprint) {
+    for (const storageDir of cfg.storageDirs) {
+        try {
+            if (!(await isPathAvailable(storageDir)))
+                continue;
+            const idx = await readDedupIndex(storageDir);
+            const existing = idx.byFingerprint[fingerprint];
+            // Only clear if it's in-progress
+            if (existing?.status === 'in-progress') {
+                delete idx.byFingerprint[fingerprint];
+                idx.updatedAt = nowIso();
+                await writeDedupIndex(storageDir, idx);
+            }
+        }
+        catch (err) {
+            logger.debug(`Failed to clear in-progress lock in ${storageDir}`, err instanceof Error ? err : undefined);
+        }
+    }
+}
+/**
+ * Check if a fingerprint has an in-progress lock (not timed out).
+ */
+export async function checkInProgressLock(cfg, fingerprint) {
+    const nowMs = Date.now();
+    for (const storageDir of cfg.storageDirs) {
+        try {
+            if (!(await isPathAvailable(storageDir)))
+                continue;
+            const idx = await readDedupIndex(storageDir);
+            const existing = idx.byFingerprint[fingerprint];
+            if (existing?.status === 'in-progress' && existing.startedAt) {
+                const startedMs = new Date(existing.startedAt).getTime();
+                const elapsed = nowMs - startedMs;
+                if (elapsed < cfg.inProgressLockTimeoutMs) {
+                    return existing;
+                }
+            }
+        }
         catch {
-            // best-effort
+            // ignore
         }
     }
+    return null;
 }
 async function readBundleSummary(cfg, bundleId) {
     const storageDir = (await findBundleStorageDir(cfg.storageDirs, bundleId)) ?? (await getEffectiveStorageDir(cfg));
@@ -166,6 +229,9 @@ async function findExistingBundleByFingerprint(cfg, fingerprint) {
                 continue;
             const idx = await readDedupIndex(storageDir);
             const hit = idx.byFingerprint[fingerprint];
+            // Skip in-progress entries - they don't have a completed bundle yet
+            if (hit?.status === 'in-progress')
+                continue;
             if (hit?.bundleId && (await bundleExistsMulti(cfg.storageDirs, hit.bundleId))) {
                 return hit.bundleId;
             }
@@ -350,6 +416,33 @@ async function validateBundleCompleteness(bundleRoot) {
         missingComponents,
     };
 }
+/**
+ * Assert that a bundle is complete and ready for operations.
+ * Throws an error with helpful guidance if the bundle is incomplete.
+ * Should be called at the entry point of tools that require a complete bundle
+ * (e.g., dependency graph, trace links, search).
+ */
+export async function assertBundleComplete(cfg, bundleId) {
+    const storageDir = await findBundleStorageDir(cfg.storageDirs, bundleId);
+    if (!storageDir) {
+        throw new Error(`Bundle not found: ${bundleId}`);
+    }
+    const bundleRoot = getBundlePaths(storageDir, bundleId).rootDir;
+    const { isValid, missingComponents } = await validateBundleCompleteness(bundleRoot);
+    if (!isValid) {
+        const issues = missingComponents.join('\n  - ');
+        throw new Error(`Bundle is incomplete and cannot be used for this operation.\n\n` +
+            `Bundle ID: ${bundleId}\n` +
+            `Missing components:\n  - ${issues}\n\n` +
+            `This usually happens when:\n` +
+            `1. Bundle creation was interrupted (timeout, network error, etc.)\n` +
+            `2. Bundle download is still in progress\n\n` +
+            `Suggested actions:\n` +
+            `- Use preflight_update_bundle with force:true to re-download the repository\n` +
+            `- Or use preflight_delete_bundle and preflight_create_bundle to start fresh\n` +
+            `- Check preflight_get_task_status if creation might still be in progress`);
+    }
+}
 /**
  * Detect primary language from ingested files
  */
@@ -657,7 +750,14 @@ async function cloneAndIngestGitHubRepo(params) {
     let fetchedAt = nowIso();
     let refUsed = params.ref;
     try {
-        await shallowClone(cloneUrl, tmpCheckoutGit, { ref: params.ref, timeoutMs: params.cfg.gitCloneTimeoutMs });
+        params.onProgress?.('cloning', 0, `Cloning ${repoId}...`);
+        await shallowClone(cloneUrl, tmpCheckoutGit, {
+            ref: params.ref,
+            timeoutMs: params.cfg.gitCloneTimeoutMs,
+            onProgress: (phase, percent, msg) => {
+                params.onProgress?.('cloning', percent, `${repoId}: ${msg}`);
+            },
+        });
         headSha = await getLocalHeadSha(tmpCheckoutGit);
     }
     catch (err) {
@@ -665,12 +765,17 @@ async function cloneAndIngestGitHubRepo(params) {
         source = 'archive';
         const msg = err instanceof Error ? err.message : String(err);
         notes.push(`git clone failed; used GitHub archive fallback: ${msg}`);
+        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;
@@ -750,6 +855,15 @@ export async function createBundle(cfg, input, options) {
 }
 async function createBundleInternal(cfg, input, options) {
     const fingerprint = computeCreateInputFingerprint(input);
+    const repoIds = input.repos.map((r) => r.repo);
+    const onProgress = options?.onProgress;
+    const tracker = getProgressTracker();
+    // Helper to report progress
+    const reportProgress = (phase, progress, message, total) => {
+        if (onProgress) {
+            onProgress(phase, progress, message, total);
+        }
+    };
     const ifExists = options?.ifExists ?? 'error';
     if (ifExists !== 'createNew') {
         const existing = await findExistingBundleByFingerprint(cfg, fingerprint);
@@ -764,6 +878,28 @@ async function createBundleInternal(cfg, input, options) {
             throw new Error(`Bundle already exists for these inputs: ${existing}`);
         }
     }
+    // Start tracking this task
+    const taskId = tracker.startTask(fingerprint, repoIds);
+    reportProgress('starting', 0, `Starting bundle creation for ${repoIds.join(', ')}`);
+    // Try to acquire in-progress lock
+    const lockResult = await setInProgressLock(cfg, fingerprint, taskId, repoIds);
+    if (!lockResult.locked) {
+        // Another task is already creating this bundle
+        const entry = lockResult.existingEntry;
+        const elapsedSec = entry.startedAt
+            ? Math.round((Date.now() - new Date(entry.startedAt).getTime()) / 1000)
+            : 0;
+        const msg = `Bundle creation already in progress (taskId: ${entry.taskId}, started ${elapsedSec}s ago). ` +
+            `Use preflight_get_task_status to check progress.`;
+        // Throw a special error that can be caught and handled
+        const err = new Error(msg);
+        err.code = 'BUNDLE_IN_PROGRESS';
+        err.taskId = entry.taskId;
+        err.fingerprint = fingerprint;
+        err.repos = entry.repos;
+        err.startedAt = entry.startedAt;
+        throw err;
+    }
     const bundleId = crypto.randomUUID();
     const createdAt = nowIso();
     // Use effective storage dir (falls back if primary unavailable)
@@ -778,9 +914,15 @@ async function createBundleInternal(cfg, input, options) {
     const reposSummary = [];
     try {
         // All operations happen in tmpPaths (temporary directory)
+        const totalRepos = input.repos.length;
+        let repoIndex = 0;
         for (const repoInput of input.repos) {
+            repoIndex++;
+            const repoProgress = Math.round((repoIndex - 1) / totalRepos * 40); // 0-40% for repo fetching
             if (repoInput.kind === 'github') {
                 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({
                     cfg,
                     bundleId,
@@ -788,6 +930,12 @@ async function createBundleInternal(cfg, input, options) {
                     owner,
                     repo,
                     ref: repoInput.ref,
+                    onProgress: (phase, percent, msg) => {
+                        // Map clone/download progress to overall progress (0-40% range per repo)
+                        const overallProgress = repoProgress + Math.round(percent * 0.4 / totalRepos);
+                        reportProgress(phase, overallProgress, `[${repoIndex}/${totalRepos}] ${msg}`);
+                        tracker.updateProgress(taskId, phase, overallProgress, msg);
+                    },
                 });
                 allIngestedFiles.push(...files);
                 reposSummary.push({
@@ -798,8 +946,11 @@ 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);
+                reportProgress('ingesting', repoProgress, `[${repoIndex}/${totalRepos}] Ingesting local ${owner}/${repo}...`);
+                tracker.updateProgress(taskId, 'ingesting', repoProgress, `Ingesting local ${owner}/${repo}...`);
                 const { files, skipped } = await ingestLocalRepo({
                     cfg,
                     bundleId,
@@ -812,21 +963,6 @@ 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: tmpPaths,
-                    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;
@@ -844,6 +980,8 @@ async function createBundleInternal(cfg, input, options) {
             librariesSummary = libIngest.libraries;
         }
         // Build index.
+        reportProgress('indexing', 50, `Building search index (${allIngestedFiles.length} files)...`);
+        tracker.updateProgress(taskId, 'indexing', 50, `Building search index (${allIngestedFiles.length} files)...`);
         await rebuildIndex(tmpPaths.searchDbPath, allIngestedFiles, {
             includeDocs: true,
             includeCode: true,
@@ -901,7 +1039,18 @@ async function createBundleInternal(cfg, input, options) {
             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.
+        reportProgress('analyzing', 70, 'Analyzing code structure...');
+        tracker.updateProgress(taskId, 'analyzing', 70, 'Analyzing code structure...');
+        await generateFactsBestEffort({
+            bundleId,
+            bundleRoot: tmpPaths.rootDir,
+            files: allIngestedFiles,
+            mode: cfg.analysisMode,
+        });
+        // Overview (S2: factual-only with evidence pointers) - generated AFTER FACTS.json
+        reportProgress('generating', 80, 'Generating overview...');
+        tracker.updateProgress(taskId, 'generating', 80, 'Generating overview...');
         const perRepoOverviews = reposSummary
             .filter((r) => r.kind === 'github' || r.kind === 'local')
             .map((r) => {
@@ -916,13 +1065,6 @@ async function createBundleInternal(cfg, input, options) {
             libraries: librariesSummary,
         });
         await writeOverviewFile(tmpPaths.overviewPath, overviewMd);
-        // Generate static facts (FACTS.json). This is intentionally non-LLM and safe to keep inside bundles.
-        await generateFactsBestEffort({
-            bundleId,
-            bundleRoot: tmpPaths.rootDir,
-            files: allIngestedFiles,
-            mode: cfg.analysisMode,
-        });
         // CRITICAL: Validate bundle completeness BEFORE atomic move
         const validation = await validateBundleCompleteness(tmpPaths.rootDir);
         if (!validation.isValid) {
@@ -932,6 +1074,8 @@ async function createBundleInternal(cfg, input, options) {
         }
         // ATOMIC OPERATION: Move from temp to final location
         // This is atomic on most filesystems - bundle becomes visible only when complete
+        reportProgress('finalizing', 90, 'Finalizing bundle...');
+        tracker.updateProgress(taskId, 'finalizing', 90, 'Finalizing bundle...');
         logger.info(`Moving bundle ${bundleId} from temp to final location (atomic)`);
         await ensureDir(effectiveStorageDir);
         try {
@@ -958,7 +1102,10 @@ async function createBundleInternal(cfg, input, options) {
             await mirrorBundleToBackups(effectiveStorageDir, cfg.storageDirs, bundleId);
         }
         // Update de-duplication index (best-effort). This is intentionally after atomic move.
-        await updateDedupIndexBestEffort(cfg, fingerprint, bundleId, createdAt);
+        await updateDedupIndexBestEffort(cfg, fingerprint, bundleId, createdAt, 'complete');
+        // Mark task complete
+        reportProgress('complete', 100, `Bundle created: ${bundleId}`);
+        tracker.completeTask(taskId, bundleId);
         const summary = {
             bundleId,
             createdAt,
@@ -972,14 +1119,21 @@ async function createBundleInternal(cfg, input, options) {
         // 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
+        // Clear in-progress lock on failure
+        await clearInProgressLock(cfg, fingerprint);
+        // Mark task failed
         const errorMsg = err instanceof Error ? err.message : String(err);
+        tracker.failTask(taskId, errorMsg);
+        // Re-throw with enhanced message (unless it's already our BUNDLE_IN_PROGRESS error)
+        if (err?.code === 'BUNDLE_IN_PROGRESS') {
+            throw err;
+        }
         throw new Error(`Failed to create bundle: ${errorMsg}`);
     }
     finally {
         // Ensure temp directory is cleaned up (double safety)
-        await rmIfExists(tmpPaths.rootDir).catch(() => {
-            // Ignore cleanup errors
+        await rmIfExists(tmpPaths.rootDir).catch((err) => {
+            logger.debug('Failed to cleanup temp bundle directory in finally block (non-critical)', err instanceof Error ? err : undefined);
         });
     }
 }
@@ -1008,19 +1162,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 };
 }
@@ -1122,41 +1271,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) {
@@ -1281,15 +1395,27 @@ export async function updateBundle(cfg, bundleId, options) {
     const paths = getBundlePaths(effectiveStorageDir, bundleId);
     const manifest = await readManifest(paths.manifestPath);
     const updatedAt = nowIso();
+    const onProgress = options?.onProgress;
+    // Report progress helper
+    const reportProgress = (phase, progress, message, total) => {
+        if (onProgress) {
+            onProgress(phase, progress, message, total);
+        }
+    };
+    reportProgress('starting', 0, `Updating bundle ${bundleId}...`);
     let changed = false;
     const allIngestedFiles = [];
     const reposSummary = [];
+    const totalRepos = manifest.inputs.repos.length;
+    let repoIndex = 0;
     // Rebuild everything obvious for now (simple + deterministic).
     for (const repoInput of manifest.inputs.repos) {
+        repoIndex++;
         if (repoInput.kind === 'github') {
             const { owner, repo } = parseOwnerRepo(repoInput.repo);
             const repoId = `${owner}/${repo}`;
             const cloneUrl = toCloneUrl({ owner, repo });
+            reportProgress('cloning', calcPercent(repoIndex - 1, totalRepos), `Checking ${repoId}...`, totalRepos);
             let remoteSha;
             try {
                 remoteSha = await getRemoteHeadSha(cloneUrl);
@@ -1301,6 +1427,7 @@ export async function updateBundle(cfg, bundleId, options) {
             if (remoteSha && prev?.headSha && remoteSha !== prev.headSha) {
                 changed = true;
             }
+            reportProgress('downloading', calcPercent(repoIndex - 1, totalRepos), `Fetching ${repoId}...`, totalRepos);
             const { headSha, files, skipped, notes, source } = await cloneAndIngestGitHubRepo({
                 cfg,
                 bundleId,
@@ -1308,6 +1435,9 @@ export async function updateBundle(cfg, bundleId, options) {
                 owner,
                 repo,
                 ref: repoInput.ref,
+                onProgress: (phase, progress, message) => {
+                    reportProgress(phase, progress, message);
+                },
             });
             if (prev?.headSha && headSha && headSha !== prev.headSha) {
                 changed = true;
@@ -1319,7 +1449,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({
@@ -1335,27 +1466,11 @@ 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;
     if (manifest.inputs.libraries?.length) {
+        reportProgress('downloading', 80, 'Fetching Context7 libraries...');
         await rmIfExists(paths.librariesDir);
         await ensureDir(paths.librariesDir);
         const libIngest = await ingestContext7Libraries({
@@ -1368,6 +1483,7 @@ export async function updateBundle(cfg, bundleId, options) {
         librariesSummary = libIngest.libraries;
     }
     // Rebuild index.
+    reportProgress('indexing', 85, `Rebuilding search index (${allIngestedFiles.length} files)...`);
     await rebuildIndex(paths.searchDbPath, allIngestedFiles, {
         includeDocs: manifest.index.includeDocs,
         includeCode: manifest.index.includeCode,
@@ -1393,6 +1509,7 @@ export async function updateBundle(cfg, bundleId, options) {
     };
     await writeManifest(paths.manifestPath, newManifest);
     // Regenerate guides + overview.
+    reportProgress('generating', 90, 'Regenerating guides and overview...');
     await writeAgentsMd(paths.agentsPath);
     await writeStartHereMd({
         targetPath: paths.startHerePath,
@@ -1415,6 +1532,7 @@ export async function updateBundle(cfg, bundleId, options) {
     });
     await writeOverviewFile(paths.overviewPath, overviewMd);
     // Refresh static facts (FACTS.json) after update.
+    reportProgress('analyzing', 95, 'Analyzing bundle...');
     await generateFactsBestEffort({
         bundleId,
         bundleRoot: paths.rootDir,
@@ -1422,11 +1540,13 @@ export async function updateBundle(cfg, bundleId, options) {
         mode: cfg.analysisMode,
     });
     // Mirror to backup storage directories (non-blocking on failures)
+    reportProgress('finalizing', 98, 'Finalizing update...');
     if (cfg.storageDirs.length > 1) {
         await mirrorBundleToBackups(effectiveStorageDir, cfg.storageDirs, bundleId);
     }
     // Keep the de-duplication index fresh (best-effort).
     await updateDedupIndexBestEffort(cfg, fingerprint, bundleId, updatedAt);
+    reportProgress('complete', 100, `Bundle updated: ${bundleId}`);
     const summary = {
         bundleId,
         createdAt: manifest.createdAt,