preflight-mcp 0.1.0

package/dist/bundle/tagging.js

@@ -0,0 +1,206 @@
+/**
+ * Auto-detect tags for a bundle based on its content
+ */
+export function autoDetectTags(params) {
+    const tags = new Set();
+    // 1. Detect by repo name patterns
+    for (const repoId of params.repoIds) {
+        const lowerRepo = repoId.toLowerCase();
+        // MCP related
+        if (lowerRepo.includes('mcp') || lowerRepo.includes('model-context-protocol')) {
+            tags.add('mcp');
+            tags.add('ai-tools');
+        }
+        // Agent frameworks
+        if (lowerRepo.includes('agent') || lowerRepo.includes('langchain') || lowerRepo.includes('autogen')) {
+            tags.add('agents');
+            tags.add('ai');
+        }
+        // Development tools
+        if (lowerRepo.includes('tool') || lowerRepo.includes('cli') || lowerRepo.includes('util')) {
+            tags.add('dev-tools');
+        }
+        // Testing/debugging
+        if (lowerRepo.includes('test') || lowerRepo.includes('debug') || lowerRepo.includes('mock')) {
+            tags.add('testing');
+            tags.add('debugging');
+        }
+        // Web scraping / crawling
+        if (lowerRepo.includes('scraper') || lowerRepo.includes('crawler') || lowerRepo.includes('spider')) {
+            tags.add('web-scraping');
+        }
+        // Anti-detection / bypassing
+        if (lowerRepo.includes('bypass') || lowerRepo.includes('anti') || lowerRepo.includes('stealth')) {
+            tags.add('anti-detection');
+            tags.add('web-scraping');
+        }
+        // Code analysis
+        if (lowerRepo.includes('lint') || lowerRepo.includes('analyzer') || lowerRepo.includes('ast')) {
+            tags.add('code-analysis');
+            tags.add('dev-tools');
+        }
+    }
+    // 2. Detect by frameworks (if facts available)
+    if (params.facts) {
+        for (const framework of params.facts.frameworks) {
+            const lowerFw = framework.toLowerCase();
+            if (lowerFw.includes('react') || lowerFw.includes('vue') || lowerFw.includes('angular')) {
+                tags.add('frontend');
+                tags.add('web-framework');
+            }
+            if (lowerFw.includes('express') || lowerFw.includes('fastify') || lowerFw.includes('nestjs')) {
+                tags.add('backend');
+                tags.add('web-framework');
+            }
+            if (lowerFw.includes('next') || lowerFw.includes('nuxt')) {
+                tags.add('full-stack');
+                tags.add('web-framework');
+            }
+            if (lowerFw.includes('django') || lowerFw.includes('flask') || lowerFw.includes('fastapi')) {
+                tags.add('backend');
+                tags.add('python');
+            }
+            if (lowerFw.includes('jest') || lowerFw.includes('vitest') || lowerFw.includes('pytest')) {
+                tags.add('testing');
+            }
+        }
+        // Language tags
+        for (const lang of params.facts.languages) {
+            const lowerLang = lang.language.toLowerCase();
+            if (lowerLang === 'typescript' || lowerLang === 'javascript') {
+                tags.add('javascript');
+            }
+            else if (lowerLang === 'python') {
+                tags.add('python');
+            }
+            else if (lowerLang === 'go') {
+                tags.add('golang');
+            }
+            else if (lowerLang === 'rust') {
+                tags.add('rust');
+            }
+        }
+        // Dependency-based detection
+        const allDeps = [
+            ...params.facts.dependencies.runtime.map((d) => d.name.toLowerCase()),
+            ...params.facts.dependencies.dev.map((d) => d.name.toLowerCase()),
+        ];
+        if (allDeps.some((d) => d.includes('puppeteer') || d.includes('playwright') || d.includes('selenium'))) {
+            tags.add('browser-automation');
+            tags.add('web-scraping');
+        }
+        if (allDeps.some((d) => d.includes('axios') || d.includes('fetch') || d.includes('request'))) {
+            tags.add('http-client');
+        }
+        if (allDeps.some((d) => d.includes('cheerio') || d.includes('beautifulsoup') || d.includes('jsdom'))) {
+            tags.add('html-parsing');
+            tags.add('web-scraping');
+        }
+    }
+    // 3. Detect by file patterns
+    const fileNames = params.files.map((f) => f.repoRelativePath.toLowerCase());
+    if (fileNames.some((f) => f.includes('dockerfile') || f.includes('docker-compose'))) {
+        tags.add('docker');
+        tags.add('devops');
+    }
+    if (fileNames.some((f) => f.includes('kubernetes') || f.includes('k8s'))) {
+        tags.add('kubernetes');
+        tags.add('devops');
+    }
+    if (fileNames.some((f) => f.includes('ci') || f.includes('github/workflows'))) {
+        tags.add('ci-cd');
+        tags.add('devops');
+    }
+    if (fileNames.some((f) => f.includes('readme') || f.includes('docs/'))) {
+        tags.add('documented');
+    }
+    return Array.from(tags).sort();
+}
+/**
+ * Generate a human-readable display name from repo IDs
+ */
+export function generateDisplayName(repoIds) {
+    if (repoIds.length === 0)
+        return 'Empty Bundle';
+    if (repoIds.length === 1) {
+        // Single repo: use repo name
+        const parts = repoIds[0].split('/');
+        return parts[1] || parts[0] || 'Unknown';
+    }
+    // Multiple repos: combine smartly
+    const repoNames = repoIds.map((id) => {
+        const parts = id.split('/');
+        return parts[1] || parts[0] || 'unknown';
+    });
+    if (repoNames.length <= 3) {
+        return repoNames.join(' + ');
+    }
+    return `${repoNames[0]} + ${repoNames.length - 1} more`;
+}
+/**
+ * Generate a brief description from facts
+ */
+export function generateDescription(params) {
+    if (!params.facts) {
+        return `Bundle containing ${params.repoIds.length} repository(ies)`;
+    }
+    const parts = [];
+    // Primary language
+    if (params.facts.languages.length > 0) {
+        const topLang = params.facts.languages[0];
+        if (topLang) {
+            parts.push(`${topLang.language} project`);
+        }
+    }
+    // Project type
+    if (params.facts.frameworks.length > 0) {
+        const frameworks = params.facts.frameworks.slice(0, 2).join(', ');
+        parts.push(`using ${frameworks}`);
+    }
+    // Special categories
+    if (params.tags.includes('mcp')) {
+        parts.push('(MCP Server)');
+    }
+    else if (params.tags.includes('agents')) {
+        parts.push('(AI Agent)');
+    }
+    else if (params.tags.includes('web-scraping')) {
+        parts.push('(Web Scraping)');
+    }
+    if (parts.length === 0) {
+        return `Bundle with ${params.facts.fileStructure.totalFiles} files`;
+    }
+    return parts.join(' ');
+}
+/**
+ * Get category for a bundle based on tags (for grouping)
+ */
+export function getCategoryFromTags(tags) {
+    // Priority order for categorization
+    if (tags.includes('mcp'))
+        return 'mcp-servers';
+    if (tags.includes('agents'))
+        return 'ai-agents';
+    if (tags.includes('web-scraping'))
+        return 'web-scraping';
+    if (tags.includes('code-analysis'))
+        return 'code-analysis';
+    if (tags.includes('testing') || tags.includes('debugging'))
+        return 'testing-debugging';
+    if (tags.includes('web-framework'))
+        return 'web-frameworks';
+    if (tags.includes('dev-tools'))
+        return 'dev-tools';
+    if (tags.includes('devops'))
+        return 'devops';
+    // Language-based fallback
+    if (tags.includes('javascript'))
+        return 'javascript';
+    if (tags.includes('python'))
+        return 'python';
+    if (tags.includes('golang'))
+        return 'golang';
+    if (tags.includes('rust'))
+        return 'rust';
+    return 'uncategorized';
+}

package/dist/config.js

@@ -0,0 +1,65 @@
+import os from 'node:os';
+import path from 'node:path';
+function envNumber(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+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 === 'deep')
+        return 'quick';
+    return 'quick';
+}
+/**
+ * Parse storage directories from environment.
+ * Supports:
+ * - PREFLIGHT_STORAGE_DIRS (semicolon-separated, e.g. "D:\path1;E:\path2")
+ * - PREFLIGHT_STORAGE_DIR (single path, for backward compatibility)
+ */
+function parseStorageDirs() {
+    // Multi-path takes precedence
+    const multiPath = process.env.PREFLIGHT_STORAGE_DIRS;
+    if (multiPath) {
+        return multiPath.split(';').map((p) => p.trim()).filter((p) => p.length > 0);
+    }
+    // Fallback to single path
+    const singlePath = process.env.PREFLIGHT_STORAGE_DIR;
+    if (singlePath) {
+        return [singlePath];
+    }
+    // Default
+    return [path.join(os.homedir(), '.preflight-mcp', 'bundles')];
+}
+export function getConfig() {
+    const storageDirs = parseStorageDirs();
+    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);
+    return {
+        storageDir,
+        storageDirs,
+        tmpDir,
+        githubToken: process.env.GITHUB_TOKEN,
+        context7ApiKey: process.env.CONTEXT7_API_KEY,
+        context7McpUrl: process.env.CONTEXT7_MCP_URL ?? 'https://mcp.context7.com/mcp',
+        maxFileBytes: envNumber('PREFLIGHT_MAX_FILE_BYTES', 512 * 1024),
+        maxTotalBytes: envNumber('PREFLIGHT_MAX_TOTAL_BYTES', 50 * 1024 * 1024),
+        analysisMode,
+        // Tuning parameters with defaults (can be overridden via env vars)
+        maxContext7Libraries: envNumber('PREFLIGHT_MAX_CONTEXT7_LIBRARIES', 20),
+        maxContext7Topics: envNumber('PREFLIGHT_MAX_CONTEXT7_TOPICS', 10),
+        maxFtsQueryTokens: envNumber('PREFLIGHT_MAX_FTS_QUERY_TOKENS', 12),
+        maxSkippedNotes: envNumber('PREFLIGHT_MAX_SKIPPED_NOTES', 50),
+        defaultMaxAgeHours: envNumber('PREFLIGHT_DEFAULT_MAX_AGE_HOURS', 24),
+        maxSearchLimit: envNumber('PREFLIGHT_MAX_SEARCH_LIMIT', 200),
+        defaultSearchLimit: envNumber('PREFLIGHT_DEFAULT_SEARCH_LIMIT', 30),
+    };
+}

package/dist/context7/client.js

@@ -0,0 +1,30 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+export async function connectContext7(cfg) {
+    const url = new URL(cfg.context7McpUrl);
+    const headers = {};
+    // Context7 supports running without a key (rate-limited). If present, pass it.
+    if (cfg.context7ApiKey) {
+        headers['CONTEXT7_API_KEY'] = cfg.context7ApiKey;
+    }
+    const transport = new StreamableHTTPClientTransport(url, {
+        requestInit: {
+            headers,
+        },
+        reconnectionOptions: {
+            // Keep retries low to avoid hanging bundle generation.
+            initialReconnectionDelay: 500,
+            maxReconnectionDelay: 2000,
+            reconnectionDelayGrowFactor: 1.5,
+            maxRetries: 1,
+        },
+    });
+    const client = new Client({ name: 'preflight-context7', version: '0.1.0' });
+    await client.connect(transport);
+    return {
+        client,
+        close: async () => {
+            await client.close().catch(() => undefined);
+        },
+    };
+}

package/dist/context7/tools.js

@@ -0,0 +1,58 @@
+export function textFromToolResult(res) {
+    const content = 'content' in res ? res.content : undefined;
+    if (!Array.isArray(content))
+        return '';
+    const parts = [];
+    for (const c of content) {
+        if (c && c.type === 'text' && typeof c.text === 'string') {
+            parts.push(c.text);
+        }
+    }
+    return parts.join('\n');
+}
+function collectStrings(value, out) {
+    if (typeof value === 'string') {
+        out.push(value);
+        return;
+    }
+    if (!value || typeof value !== 'object')
+        return;
+    if (Array.isArray(value)) {
+        for (const v of value)
+            collectStrings(v, out);
+        return;
+    }
+    for (const v of Object.values(value)) {
+        collectStrings(v, out);
+    }
+}
+export function extractContext7IdsFromResult(res) {
+    const candidates = [];
+    if (res.structuredContent) {
+        collectStrings(res.structuredContent, candidates);
+    }
+    const text = textFromToolResult(res);
+    if (text) {
+        // Match strings like /owner/repo, /scope/pkg, etc.
+        const re = /\/[A-Za-z0-9@._-]+(?:\/[A-Za-z0-9@._-]+)+/g;
+        for (const m of text.matchAll(re)) {
+            if (m[0])
+                candidates.push(m[0]);
+        }
+    }
+    // Normalize + de-dupe, keep order.
+    const seen = new Set();
+    const ids = [];
+    for (const raw of candidates) {
+        const s = raw.trim();
+        if (!s.startsWith('/'))
+            continue;
+        if (!s.includes('/'))
+            continue;
+        if (seen.has(s))
+            continue;
+        seen.add(s);
+        ids.push(s);
+    }
+    return ids;
+}

package/dist/core/scheduler.js

@@ -0,0 +1,166 @@
+import cron from "node-cron";
+import { logger } from '../logging/logger.js';
+export class Job {
+    // 可选的失败重试配置
+    getMaxRetries() {
+        return 3;
+    }
+    getRetryDelay() {
+        return 1000; // 1秒
+    }
+}
+export class Scheduler {
+    tasks = new Map();
+    isRunning = false;
+    async start() {
+        if (this.isRunning) {
+            return;
+        }
+        this.isRunning = true;
+        // Start any tasks that were scheduled while the scheduler was stopped.
+        for (const [name, jobTask] of this.tasks) {
+            jobTask.task.start();
+            logger.debug(`Started job: ${name}`);
+        }
+        logger.info('Scheduler started');
+    }
+    build(JobClass) {
+        const job = new JobClass();
+        const jobName = job.getName();
+        return {
+            schedule: (cronExpression) => {
+                const task = cron.createTask(cronExpression, async () => {
+                    await this.executeJob(jobName, job);
+                });
+                const jobTask = {
+                    job,
+                    task,
+                    cronExpression,
+                    retries: 0,
+                    running: false
+                };
+                this.tasks.set(jobName, jobTask);
+                if (this.isRunning) {
+                    task.start();
+                }
+                logger.info(`Scheduled job ${jobName}`, { cronExpression });
+            },
+        };
+    }
+    async executeJob(jobName, job, isRetry = false) {
+        const jobTask = this.tasks.get(jobName);
+        if (!jobTask) {
+            logger.error(`Job ${jobName} not found in task registry`);
+            return;
+        }
+        if (!this.isRunning) {
+            // Scheduler stopped: don't execute or schedule retries.
+            return;
+        }
+        // Avoid overlapping executions.
+        if (jobTask.running) {
+            return;
+        }
+        // If a retry is already scheduled, let it run instead of piling up executions from cron.
+        if (!isRetry && jobTask.retryTimeout) {
+            return;
+        }
+        jobTask.running = true;
+        try {
+            const startTime = Date.now();
+            logger.debug(`Executing job: ${jobName}`);
+            await job.run();
+            const duration = Date.now() - startTime;
+            jobTask.lastRun = new Date();
+            jobTask.retries = 0;
+            jobTask.lastError = undefined;
+            if (jobTask.retryTimeout) {
+                clearTimeout(jobTask.retryTimeout);
+                jobTask.retryTimeout = undefined;
+            }
+            logger.info(`Job ${jobName} completed`, { durationMs: duration });
+        }
+        catch (error) {
+            jobTask.lastError = error instanceof Error ? error : new Error(String(error));
+            logger.error(`Job ${jobName} failed`, error instanceof Error ? error : undefined);
+            if (!this.isRunning) {
+                return;
+            }
+            const maxRetries = job.getMaxRetries();
+            if (jobTask.retries < maxRetries) {
+                jobTask.retries++;
+                const delay = job.getRetryDelay() * Math.pow(2, jobTask.retries - 1);
+                logger.info(`Retrying job ${jobName}`, { attempt: jobTask.retries, maxRetries, delayMs: delay });
+                if (jobTask.retryTimeout) {
+                    clearTimeout(jobTask.retryTimeout);
+                }
+                jobTask.retryTimeout = setTimeout(() => {
+                    jobTask.retryTimeout = undefined;
+                    void this.executeJob(jobName, job, true);
+                }, delay);
+                jobTask.retryTimeout.unref?.();
+            }
+            else {
+                logger.error(`Job ${jobName} failed after ${maxRetries} retries`);
+            }
+        }
+        finally {
+            jobTask.running = false;
+        }
+    }
+    async stop() {
+        if (!this.isRunning) {
+            return;
+        }
+        // Mark stopped first so in-flight jobs won't schedule retries.
+        this.isRunning = false;
+        for (const [name, jobTask] of this.tasks) {
+            jobTask.task.stop();
+            if (jobTask.retryTimeout) {
+                clearTimeout(jobTask.retryTimeout);
+                jobTask.retryTimeout = undefined;
+            }
+            jobTask.running = false;
+            logger.debug(`Stopped job: ${name}`);
+        }
+        logger.info('Scheduler stopped');
+    }
+    async clear() {
+        for (const [name, jobTask] of this.tasks) {
+            if (jobTask.retryTimeout) {
+                clearTimeout(jobTask.retryTimeout);
+                jobTask.retryTimeout = undefined;
+            }
+            jobTask.running = false;
+            jobTask.task.destroy();
+            logger.debug(`Destroyed job: ${name}`);
+        }
+        this.tasks.clear();
+        logger.info('Scheduler cleared all tasks');
+    }
+    // 获取任务状态
+    getJobStatus(name) {
+        const jobTask = this.tasks.get(name);
+        if (!jobTask) {
+            return null;
+        }
+        const status = jobTask.task.getStatus();
+        return {
+            scheduled: !['stopped', 'destroyed'].includes(status),
+            lastRun: jobTask.lastRun,
+            lastError: jobTask.lastError,
+            retries: jobTask.retries,
+            cronExpression: jobTask.cronExpression
+        };
+    }
+    // 获取所有任务状态
+    getAllJobsStatus() {
+        const status = {};
+        for (const [name] of this.tasks) {
+            status[name] = this.getJobStatus(name);
+        }
+        return status;
+    }
+}
+// 单例实例
+export const PreflightScheduler = new Scheduler();

package/dist/errors.js

@@ -0,0 +1,150 @@
+/**
+ * Custom error types for preflight-mcp.
+ * Provides structured error handling with error codes and context.
+ */
+/**
+ * Base error class for all preflight-mcp errors.
+ */
+export class PreflightError extends Error {
+    code;
+    context;
+    cause;
+    constructor(message, code, options) {
+        super(message);
+        this.name = 'PreflightError';
+        this.code = code;
+        this.context = options?.context;
+        this.cause = options?.cause;
+        // Maintains proper stack trace for where our error was thrown (V8 only)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            context: this.context,
+            cause: this.cause?.message,
+            stack: this.stack,
+        };
+    }
+}
+/**
+ * Error thrown when a bundle is not found.
+ */
+export class BundleNotFoundError extends PreflightError {
+    constructor(bundleId) {
+        super(`Bundle not found: ${bundleId}`, 'BUNDLE_NOT_FOUND', {
+            context: { bundleId },
+        });
+        this.name = 'BundleNotFoundError';
+    }
+}
+/**
+ * Error thrown when storage operations fail.
+ */
+export class StorageError extends PreflightError {
+    constructor(message, options) {
+        super(message, 'STORAGE_ERROR', options);
+        this.name = 'StorageError';
+    }
+}
+/**
+ * Error thrown when no storage directory is available.
+ */
+export class StorageUnavailableError extends StorageError {
+    constructor(attemptedPaths) {
+        super('No storage directory available. All mount points are inaccessible.', {
+            context: { attemptedPaths },
+        });
+        this.name = 'StorageUnavailableError';
+    }
+}
+/**
+ * Error thrown when bundle creation fails.
+ */
+export class BundleCreationError extends PreflightError {
+    constructor(message, bundleId, options) {
+        super(`Failed to create bundle: ${message}`, 'BUNDLE_CREATION_ERROR', {
+            ...options,
+            context: { ...options?.context, bundleId },
+        });
+        this.name = 'BundleCreationError';
+    }
+}
+/**
+ * Error thrown when bundle validation fails.
+ */
+export class BundleValidationError extends PreflightError {
+    constructor(bundleId, missingComponents) {
+        super(`Bundle creation incomplete. Missing: ${missingComponents.join(', ')}`, 'BUNDLE_VALIDATION_ERROR', {
+            context: { bundleId, missingComponents },
+        });
+        this.name = 'BundleValidationError';
+    }
+}
+/**
+ * Error thrown when GitHub operations fail.
+ */
+export class GitHubError extends PreflightError {
+    constructor(message, options) {
+        super(message, 'GITHUB_ERROR', options);
+        this.name = 'GitHubError';
+    }
+}
+/**
+ * Error thrown when Context7 operations fail.
+ */
+export class Context7Error extends PreflightError {
+    constructor(message, options) {
+        super(message, 'CONTEXT7_ERROR', options);
+        this.name = 'Context7Error';
+    }
+}
+/**
+ * Error thrown when search operations fail.
+ */
+export class SearchError extends PreflightError {
+    constructor(message, options) {
+        super(message, 'SEARCH_ERROR', options);
+        this.name = 'SearchError';
+    }
+}
+/**
+ * Error thrown when file ingestion fails.
+ */
+export class IngestError extends PreflightError {
+    constructor(message, options) {
+        super(message, 'INGEST_ERROR', options);
+        this.name = 'IngestError';
+    }
+}
+/**
+ * Error thrown for configuration-related issues.
+ */
+export class ConfigError extends PreflightError {
+    constructor(message, options) {
+        super(message, 'CONFIG_ERROR', options);
+        this.name = 'ConfigError';
+    }
+}
+/**
+ * Helper to wrap unknown errors as PreflightError.
+ */
+export function wrapError(err, code = 'UNKNOWN_ERROR') {
+    if (err instanceof PreflightError) {
+        return err;
+    }
+    if (err instanceof Error) {
+        return new PreflightError(err.message, code, { cause: err });
+    }
+    return new PreflightError(String(err), code);
+}
+/**
+ * Type guard to check if an error is a PreflightError.
+ */
+export function isPreflightError(err) {
+    return err instanceof PreflightError;
+}

package/dist/index.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { startServer } from './server.js';
+startServer().catch((err) => {
+    // Stdio MCP servers should write logs to stderr.
+    console.error('[preflight-mcp] fatal:', err);
+    process.exitCode = 1;
+});