preflight-mcp 0.1.0 → 0.1.2

package/dist/bundle/cleanup.js

@@ -0,0 +1,155 @@
+/**
+ * Bundle cleanup utilities for MCP architecture
+ * Designed to run on-demand (startup, list, etc.) rather than as a daemon
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { logger } from '../logging/logger.js';
+import { rmIfExists } from '../utils/index.js';
+/**
+ * Check if a string is a valid UUID (v4 format)
+ */
+function isValidBundleId(id) {
+    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);
+}
+/**
+ * Check if a bundle is orphaned (incomplete/corrupted)
+ */
+async function isOrphanBundle(storageDir, bundleId) {
+    const bundlePath = path.join(storageDir, bundleId);
+    const manifestPath = path.join(bundlePath, 'manifest.json');
+    try {
+        // Check if manifest exists and is valid
+        const manifestContent = await fs.readFile(manifestPath, 'utf8');
+        const manifest = JSON.parse(manifestContent);
+        // Valid manifest exists
+        if (manifest.bundleId && manifest.schemaVersion) {
+            return { isOrphan: false };
+        }
+        return { isOrphan: true, reason: 'invalid manifest' };
+    }
+    catch {
+        // Manifest missing or unreadable
+        try {
+            const stats = await fs.stat(bundlePath);
+            const ageHours = (Date.now() - stats.mtimeMs) / (1000 * 60 * 60);
+            return { isOrphan: true, reason: 'missing manifest', ageHours };
+        }
+        catch {
+            return { isOrphan: true, reason: 'directory inaccessible' };
+        }
+    }
+}
+/**
+ * Clean up orphan bundles from a single storage directory
+ * Only removes bundles older than minAgeHours to avoid race conditions
+ */
+async function cleanupOrphansInDir(storageDir, options) {
+    const found = [];
+    const cleaned = [];
+    const skipped = [];
+    try {
+        const entries = await fs.readdir(storageDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            // Handle .deleting directories (from background deletion)
+            if (entry.name.endsWith('.deleting')) {
+                // Always clean .deleting directories (they're already marked for deletion)
+                try {
+                    const deletingPath = path.join(storageDir, entry.name);
+                    await rmIfExists(deletingPath);
+                    logger.info(`Cleaned pending deletion: ${entry.name}`);
+                }
+                catch (err) {
+                    logger.warn(`Failed to clean pending deletion ${entry.name}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                continue;
+            }
+            // Only process directories with valid UUID names
+            if (!isValidBundleId(entry.name)) {
+                continue;
+            }
+            const bundleId = entry.name;
+            const orphanCheck = await isOrphanBundle(storageDir, bundleId);
+            if (orphanCheck.isOrphan) {
+                found.push(bundleId);
+                // Check age threshold
+                if (orphanCheck.ageHours !== undefined && orphanCheck.ageHours < options.minAgeHours) {
+                    skipped.push({
+                        bundleId,
+                        reason: `too new (${orphanCheck.ageHours.toFixed(1)}h < ${options.minAgeHours}h)`,
+                    });
+                    continue;
+                }
+                if (!options.dryRun) {
+                    try {
+                        const bundlePath = path.join(storageDir, bundleId);
+                        await rmIfExists(bundlePath);
+                        cleaned.push(bundleId);
+                        logger.info(`Cleaned orphan bundle: ${bundleId} (${orphanCheck.reason})`);
+                    }
+                    catch (err) {
+                        skipped.push({
+                            bundleId,
+                            reason: `cleanup failed: ${err instanceof Error ? err.message : String(err)}`,
+                        });
+                    }
+                }
+                else {
+                    cleaned.push(bundleId); // In dry-run, mark as "would clean"
+                }
+            }
+        }
+    }
+    catch (err) {
+        logger.warn(`Failed to scan storage dir ${storageDir}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return { found, cleaned, skipped };
+}
+/**
+ * Clean up orphan bundles across all storage directories
+ * Safe to call on every server startup - fast when no orphans exist
+ */
+export async function cleanupOrphanBundles(cfg, options) {
+    const minAgeHours = options?.minAgeHours ?? 1; // Default: 1 hour safety margin
+    const dryRun = options?.dryRun ?? false;
+    const details = [];
+    let totalFound = 0;
+    let totalCleaned = 0;
+    for (const storageDir of cfg.storageDirs) {
+        const result = await cleanupOrphansInDir(storageDir, { minAgeHours, dryRun });
+        totalFound += result.found.length;
+        totalCleaned += result.cleaned.length;
+        if (result.found.length > 0) {
+            details.push({
+                storageDir,
+                ...result,
+            });
+        }
+    }
+    if (totalFound > 0) {
+        logger.info(`Orphan cleanup: found ${totalFound}, cleaned ${totalCleaned}, skipped ${totalFound - totalCleaned}${dryRun ? ' (dry-run)' : ''}`);
+    }
+    return { totalFound, totalCleaned, details };
+}
+/**
+ * Run orphan cleanup on server startup (best-effort, non-blocking)
+ * Only logs warnings on failure, doesn't throw
+ */
+export async function cleanupOnStartup(cfg) {
+    try {
+        const result = await cleanupOrphanBundles(cfg, {
+            minAgeHours: 1,
+            dryRun: false,
+        });
+        if (result.totalCleaned > 0) {
+            logger.info(`Startup cleanup: removed ${result.totalCleaned} orphan bundle(s)`);
+        }
+    }
+    catch (err) {
+        // Non-critical: just log and continue
+        logger.warn(`Startup cleanup failed (non-critical): ${err instanceof Error ? err.message : String(err)}`);
+    }
+}

package/dist/bundle/deepwiki.js

@@ -43,7 +43,7 @@ async function fetchDeepWikiPage(url, timeoutMs = 30000) {
     try {
         const res = await fetch(url, {
             headers: {
-                'User-Agent': 'preflight-mcp/0.1.0',
+                'User-Agent': 'preflight-mcp/0.1.1',
                 'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
             },
             signal: controller.signal,

package/dist/bundle/github.js

@@ -1,8 +1,7 @@
-import { execFile } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { promisify } from 'node:util';
-const execFileAsync = promisify(execFile);
+import { logger } from '../logging/logger.js';
 export function parseOwnerRepo(input) {
     const trimmed = input.trim().replace(/^https?:\/\/github\.com\//i, '');
     const parts = trimmed.split('/').filter(Boolean);
@@ -15,18 +14,76 @@ export function toCloneUrl(ref) {
     return `https://github.com/${ref.owner}/${ref.repo}.git`;
 }
 async function runGit(args, opts) {
-    const { stdout, stderr } = await execFileAsync('git', args, {
-        cwd: opts?.cwd,
-        timeout: opts?.timeoutMs ?? 5 * 60_000,
-        env: {
-            ...process.env,
-            GIT_TERMINAL_PROMPT: '0',
-        },
-        windowsHide: true,
-        encoding: 'utf8',
-        maxBuffer: 10 * 1024 * 1024,
+    const timeoutMs = opts?.timeoutMs ?? 5 * 60_000;
+    return new Promise((resolve, reject) => {
+        const child = spawn('git', args, {
+            cwd: opts?.cwd,
+            env: {
+                ...process.env,
+                GIT_TERMINAL_PROMPT: '0',
+            },
+            windowsHide: true,
+        });
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        let cleanedUp = false;
+        const cleanup = () => {
+            if (cleanedUp)
+                return;
+            cleanedUp = true;
+            if (timeoutHandle) {
+                clearTimeout(timeoutHandle);
+            }
+        };
+        const forceKill = () => {
+            if (child.killed)
+                return;
+            try {
+                // Try SIGKILL for forceful termination
+                child.kill('SIGKILL');
+            }
+            catch (err) {
+                logger.warn('Failed to kill git process', err instanceof Error ? err : undefined);
+            }
+        };
+        // Set up timeout
+        const timeoutHandle = setTimeout(() => {
+            timedOut = true;
+            logger.warn(`Git command timed out after ${timeoutMs}ms`, { args });
+            // Try graceful termination first
+            try {
+                child.kill('SIGTERM');
+            }
+            catch (err) {
+                logger.warn('Failed to send SIGTERM to git process', err instanceof Error ? err : undefined);
+            }
+            // Force kill after 5 seconds if still running
+            setTimeout(forceKill, 5000);
+        }, timeoutMs);
+        child.stdout?.on('data', (data) => {
+            stdout += data.toString('utf8');
+        });
+        child.stderr?.on('data', (data) => {
+            stderr += data.toString('utf8');
+        });
+        child.on('error', (err) => {
+            cleanup();
+            reject(err);
+        });
+        child.on('close', (code, signal) => {
+            cleanup();
+            if (timedOut) {
+                reject(new Error(`Git command timed out after ${timeoutMs}ms: git ${args.join(' ')}`));
+            }
+            else if (code !== 0) {
+                reject(new Error(`Git command failed with code ${code}: ${stderr || stdout}`));
+            }
+            else {
+                resolve({ stdout, stderr });
+            }
+        });
     });
-    return { stdout, stderr };
 }
 export async function getRemoteHeadSha(cloneUrl) {
     const { stdout } = await runGit(['ls-remote', cloneUrl, 'HEAD'], { timeoutMs: 60_000 });
@@ -38,16 +95,44 @@ export async function getRemoteHeadSha(cloneUrl) {
         throw new Error(`Could not parse remote sha from: ${line}`);
     return sha;
 }
+/**
+ * Validate git ref to prevent command injection.
+ * Only allows: alphanumeric, hyphens, underscores, dots, forward slashes
+ */
+function validateGitRef(ref) {
+    if (!ref || ref.length === 0) {
+        throw new Error('Git ref cannot be empty');
+    }
+    if (ref.length > 256) {
+        throw new Error('Git ref too long (max 256 characters)');
+    }
+    // Allow only safe characters: alphanumeric, hyphen, underscore, dot, forward slash
+    // This covers branches, tags, and commit SHAs
+    const safeRefPattern = /^[a-zA-Z0-9_.\/-]+$/;
+    if (!safeRefPattern.test(ref)) {
+        throw new Error(`Invalid git ref: contains unsafe characters. Ref: ${ref}`);
+    }
+    // Prevent refs starting with dash (could be interpreted as git option)
+    if (ref.startsWith('-')) {
+        throw new Error('Invalid git ref: cannot start with hyphen');
+    }
+    // Prevent double dots (path traversal in git refs)
+    if (ref.includes('..')) {
+        throw new Error('Invalid git ref: cannot contain ".."');
+    }
+}
 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'];
     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: 15 * 60_000 });
+    await runGit(args, { timeoutMs: opts?.timeoutMs ?? 15 * 60_000 });
 }
 export async function getLocalHeadSha(repoDir) {
     const { stdout } = await runGit(['-C', repoDir, 'rev-parse', 'HEAD']);

package/dist/bundle/githubArchive.js

@@ -0,0 +1,82 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import AdmZip from 'adm-zip';
+function nowIso() {
+    return new Date().toISOString();
+}
+function githubHeaders(cfg) {
+    const headers = {
+        'User-Agent': 'preflight-mcp/0.1.1',
+        Accept: 'application/vnd.github+json',
+    };
+    if (cfg.githubToken) {
+        headers.Authorization = `Bearer ${cfg.githubToken}`;
+    }
+    return headers;
+}
+async function ensureDir(p) {
+    await fs.mkdir(p, { recursive: true });
+}
+async function fetchJson(url, headers) {
+    const res = await fetch(url, { headers });
+    if (!res.ok) {
+        throw new Error(`GitHub API error ${res.status}: ${res.statusText}`);
+    }
+    return (await res.json());
+}
+async function downloadToFile(url, headers, destPath) {
+    const res = await fetch(url, { headers, redirect: 'follow' });
+    if (!res.ok) {
+        throw new Error(`Download error ${res.status}: ${res.statusText}`);
+    }
+    // Use streaming if possible; otherwise fallback to arrayBuffer.
+    const anyRes = res;
+    const body = anyRes.body;
+    await ensureDir(path.dirname(destPath));
+    if (body && typeof body.pipe === 'function') {
+        // Node.js stream
+        const ws = (await import('node:fs')).createWriteStream(destPath);
+        await new Promise((resolve, reject) => {
+            body.pipe(ws);
+            body.on('error', reject);
+            ws.on('error', reject);
+            ws.on('finish', () => resolve());
+        });
+        return;
+    }
+    // Web stream or no stream support.
+    const buf = Buffer.from(await res.arrayBuffer());
+    await fs.writeFile(destPath, buf);
+}
+async function extractZip(zipPath, destDir) {
+    await ensureDir(destDir);
+    const zip = new AdmZip(zipPath);
+    zip.extractAllTo(destDir, true);
+}
+async function findSingleTopLevelDir(root) {
+    const entries = await fs.readdir(root, { withFileTypes: true });
+    const dirs = entries.filter((e) => e.isDirectory()).map((e) => path.join(root, e.name));
+    if (dirs.length === 1)
+        return dirs[0];
+    return root;
+}
+export async function downloadAndExtractGitHubArchive(params) {
+    const headers = githubHeaders(params.cfg);
+    // Resolve ref if not provided.
+    let refUsed = (params.ref ?? '').trim();
+    if (!refUsed) {
+        const repoInfo = await fetchJson(`https://api.github.com/repos/${params.owner}/${params.repo}`, headers);
+        refUsed = repoInfo.default_branch || 'HEAD';
+    }
+    const zipPath = path.join(params.destDir, `github-zipball-${params.owner}-${params.repo}-${Date.now()}.zip`);
+    // 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);
+    const extractDir = path.join(params.destDir, `extracted-${Date.now()}`);
+    await extractZip(zipPath, extractDir);
+    const repoRoot = await findSingleTopLevelDir(extractDir);
+    // Best-effort cleanup: remove zip file (keep extracted for caller to consume).
+    await fs.rm(zipPath, { force: true }).catch(() => undefined);
+    return { repoRoot, refUsed, fetchedAt: nowIso() };
+}

package/dist/bundle/ingest.js

@@ -32,7 +32,7 @@ function isProbablyBinary(buf) {
     }
     return false;
 }
-function classifyKind(repoRelativePathPosix) {
+export function classifyIngestedFileKind(repoRelativePathPosix) {
     const base = path.posix.basename(repoRelativePathPosix).toLowerCase();
     const ext = path.posix.extname(repoRelativePathPosix).toLowerCase();
     if (base === 'readme' ||
@@ -135,7 +135,7 @@ export async function ingestRepoToBundle(params) {
         await fs.mkdir(path.dirname(normDest), { recursive: true });
         await fs.writeFile(normDest, normalized, 'utf8');
         totalBytes += st.size;
-        const kind = classifyKind(f.relPosix);
+        const kind = classifyIngestedFileKind(f.relPosix);
         const sha256 = sha256Hex(Buffer.from(normalized, 'utf8'));
         const bundleNormRelativePath = `${params.bundleNormPrefixPosix}/${f.relPosix}`;
         files.push({

package/dist/bundle/paths.js

@@ -1,5 +1,28 @@
 import path from 'node:path';
+/**
+ * Validate bundle ID to prevent path traversal attacks.
+ * Only allows: alphanumeric, hyphens, underscores
+ */
+export function validateBundleId(bundleId) {
+    if (!bundleId || bundleId.length === 0) {
+        throw new Error('Bundle ID cannot be empty');
+    }
+    if (bundleId.length > 128) {
+        throw new Error('Bundle ID too long (max 128 characters)');
+    }
+    // Allow only alphanumeric, hyphen, and underscore (no dots or slashes)
+    const safeIdPattern = /^[a-zA-Z0-9_-]+$/;
+    if (!safeIdPattern.test(bundleId)) {
+        throw new Error(`Invalid bundle ID: contains unsafe characters. ID: ${bundleId}`);
+    }
+    // Prevent IDs starting with dot (hidden files)
+    if (bundleId.startsWith('.')) {
+        throw new Error('Invalid bundle ID: cannot start with dot');
+    }
+}
 export function getBundlePaths(storageDir, bundleId) {
+    // Validate bundle ID to prevent path traversal
+    validateBundleId(bundleId);
     const rootDir = path.join(storageDir, bundleId);
     const indexesDir = path.join(rootDir, 'indexes');
     return {