preflight-mcp 0.1.0

package/dist/storage/compression.js

@@ -0,0 +1,249 @@
+import zlib from 'node:zlib';
+import { promisify } from 'node:util';
+import { logger } from '../logging/logger.js';
+const gzip = promisify(zlib.gzip);
+const gunzip = promisify(zlib.gunzip);
+const brotliCompress = promisify(zlib.brotliCompress);
+const brotliDecompress = promisify(zlib.brotliDecompress);
+const deflate = promisify(zlib.deflate);
+const inflate = promisify(zlib.inflate);
+export class CompressionManager {
+    defaultOptions = {
+        type: 'gzip',
+        level: 6,
+        threshold: 1024 // Only compress files larger than 1KB
+    };
+    constructor(options) {
+        if (options) {
+            this.defaultOptions = { ...this.defaultOptions, ...options };
+        }
+    }
+    /**
+     * 压缩数据
+     */
+    async compress(data, options) {
+        const opts = { ...this.defaultOptions, ...options };
+        const inputBuffer = typeof data === 'string' ? Buffer.from(data) : data;
+        const originalSize = inputBuffer.length;
+        // 如果数据太小，不压缩
+        if (originalSize < (opts.threshold || 0)) {
+            return {
+                compressed: false,
+                originalSize,
+                compressedSize: originalSize,
+                compressionRatio: 1,
+                type: 'none',
+                data: inputBuffer
+            };
+        }
+        // 如果不需要压缩
+        if (opts.type === 'none') {
+            return {
+                compressed: false,
+                originalSize,
+                compressedSize: originalSize,
+                compressionRatio: 1,
+                type: 'none',
+                data: inputBuffer
+            };
+        }
+        try {
+            let compressedData;
+            const startTime = Date.now();
+            switch (opts.type) {
+                case 'gzip':
+                    compressedData = await gzip(inputBuffer, { level: opts.level });
+                    break;
+                case 'br':
+                    compressedData = await brotliCompress(inputBuffer, {
+                        params: {
+                            [zlib.constants.BROTLI_PARAM_QUALITY]: opts.level || 6
+                        }
+                    });
+                    break;
+                case 'deflate':
+                    compressedData = await deflate(inputBuffer, { level: opts.level });
+                    break;
+                default:
+                    throw new Error(`Unsupported compression type: ${opts.type}`);
+            }
+            const compressionTime = Date.now() - startTime;
+            const compressionRatio = compressedData.length / originalSize;
+            if (compressionRatio >= 0.95) {
+                logger.debug(`Compression ineffective`, { type: opts.type, ratio: compressionRatio.toFixed(3), timeMs: compressionTime });
+                return {
+                    compressed: false,
+                    originalSize,
+                    compressedSize: originalSize,
+                    compressionRatio: 1,
+                    type: 'none',
+                    data: inputBuffer
+                };
+            }
+            logger.debug(`Compressed data`, { type: opts.type, originalSize, compressedSize: compressedData.length, ratio: compressionRatio.toFixed(3), timeMs: compressionTime });
+            return {
+                compressed: true,
+                originalSize,
+                compressedSize: compressedData.length,
+                compressionRatio,
+                type: opts.type,
+                data: compressedData
+            };
+        }
+        catch (error) {
+            logger.debug(`Failed to compress data`, { error: error instanceof Error ? error.message : String(error) });
+            return {
+                compressed: false,
+                originalSize,
+                compressedSize: originalSize,
+                compressionRatio: 1,
+                type: 'none',
+                data: inputBuffer
+            };
+        }
+    }
+    /**
+     * 解压缩数据
+     */
+    async decompress(data, type) {
+        if (type === 'none') {
+            return data;
+        }
+        try {
+            const startTime = Date.now();
+            let decompressedData;
+            switch (type) {
+                case 'gzip':
+                    decompressedData = await gunzip(data);
+                    break;
+                case 'br':
+                    decompressedData = await brotliDecompress(data);
+                    break;
+                case 'deflate':
+                    decompressedData = await inflate(data);
+                    break;
+                default:
+                    throw new Error(`Unsupported decompression type: ${type}`);
+            }
+            const decompressionTime = Date.now() - startTime;
+            logger.debug(`Decompressed data`, { type, originalSize: data.length, decompressedSize: decompressedData.length, timeMs: decompressionTime });
+            return decompressedData;
+        }
+        catch (error) {
+            logger.error(`Failed to decompress data`, error instanceof Error ? error : undefined);
+            throw error;
+        }
+    }
+    /**
+     * 检测数据的压缩类型
+     */
+    detectCompressionType(data) {
+        if (data.length < 2) {
+            return 'none';
+        }
+        // Gzip magic number: 0x1f 0x8b
+        if (data[0] === 0x1f && data[1] === 0x8b) {
+            return 'gzip';
+        }
+        // Brotli magic number varies, but common patterns
+        if (data.length >= 4 && this.isBrotli(data)) {
+            return 'br';
+        }
+        // Deflate (zlib) magic number: 0x78
+        if ((data[0] === 0x78 && (data[1] === 0x01 || data[1] === 0x9c || data[1] === 0xda))) {
+            return 'deflate';
+        }
+        return 'none';
+    }
+    isBrotli(data) {
+        // Brotli magic number detection
+        // This is a simplified check - real detection would be more complex
+        const header = data.readUInt32LE(0);
+        return (header & 0xFFFFFF) === 0x226849; // Common Brotli header
+    }
+    /**
+     * 估算压缩效果（不实际压缩）
+     */
+    estimateCompression(data) {
+        const inputBuffer = typeof data === 'string' ? Buffer.from(data) : data;
+        // 简单的启发式估算
+        const entropy = this.calculateEntropy(inputBuffer);
+        let estimatedRatio = 1;
+        let recommendedType = 'none';
+        if (inputBuffer.length < 1024) {
+            // 小文件不压缩
+            estimatedRatio = 1;
+            recommendedType = 'none';
+        }
+        else if (entropy < 3.0) {
+            // 低熵数据（如重复文本）压缩效果好
+            estimatedRatio = 0.3;
+            recommendedType = 'br'; // Brotli 通常对文本效果最好
+        }
+        else if (entropy < 6.0) {
+            // 中等熵数据
+            estimatedRatio = 0.6;
+            recommendedType = 'gzip'; // Gzip 是很好的通用选择
+        }
+        else {
+            // 高熵数据（如已压缩或随机数据）压缩效果差
+            estimatedRatio = 0.95;
+            recommendedType = 'none';
+        }
+        return Promise.resolve({ estimatedRatio, recommendedType });
+    }
+    calculateEntropy(data) {
+        const frequency = new Array(256).fill(0);
+        // 计算字节频率
+        for (const byte of data) {
+            frequency[byte]++;
+        }
+        // 计算熵
+        let entropy = 0;
+        const length = data.length;
+        for (const count of frequency) {
+            if (count > 0) {
+                const probability = count / length;
+                entropy -= probability * Math.log2(probability);
+            }
+        }
+        return entropy;
+    }
+    /**
+     * 获取压缩统计信息
+     */
+    getCompressionStats() {
+        return {
+            supportedTypes: ['none', 'gzip', 'br', 'deflate'],
+            defaultType: this.defaultOptions.type,
+            defaultLevel: this.defaultOptions.level || 6,
+            defaultThreshold: this.defaultOptions.threshold || 1024
+        };
+    }
+}
+// 默认压缩管理器实例
+export const defaultCompressionManager = new CompressionManager();
+/**
+ * 便捷函数：压缩数据
+ */
+export async function compressData(data, options) {
+    return defaultCompressionManager.compress(data, options);
+}
+/**
+ * 便捷函数：解压缩数据
+ */
+export async function decompressData(data, type) {
+    return defaultCompressionManager.decompress(data, type);
+}
+/**
+ * 便捷函数：检测压缩类型
+ */
+export function detectCompressionType(data) {
+    return defaultCompressionManager.detectCompressionType(data);
+}
+/**
+ * 便捷函数：估算压缩效果
+ */
+export async function estimateCompression(data) {
+    return defaultCompressionManager.estimateCompression(data);
+}

package/dist/storage/storage-adapter.js

@@ -0,0 +1,316 @@
+import fs from 'node:fs/promises';
+import nodePath from 'node:path';
+export class LocalStorageAdapter {
+    name;
+    type = 'local';
+    basePath;
+    constructor(basePath) {
+        this.name = `LocalStorage(${basePath})`;
+        this.basePath = basePath;
+    }
+    getFullPath(filePath) {
+        // 确保路径是相对于基础路径的
+        if (filePath.startsWith(this.basePath)) {
+            return filePath;
+        }
+        return nodePath.join(this.basePath, filePath);
+    }
+    async exists(filePath) {
+        try {
+            await fs.access(this.getFullPath(filePath));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async readFile(filePath) {
+        return await fs.readFile(this.getFullPath(filePath));
+    }
+    async writeFile(filePath, data) {
+        const fullPath = this.getFullPath(filePath);
+        // 确保目录存在
+        const dir = nodePath.dirname(fullPath);
+        await this.createDirectory(dir);
+        await fs.writeFile(fullPath, data);
+    }
+    async deleteFile(filePath) {
+        await fs.unlink(this.getFullPath(filePath));
+    }
+    async createDirectory(dirPath) {
+        await fs.mkdir(this.getFullPath(dirPath), { recursive: true });
+    }
+    async deleteDirectory(dirPath, recursive = false) {
+        const fullPath = this.getFullPath(dirPath);
+        if (recursive) {
+            await fs.rm(fullPath, { recursive: true, force: true });
+        }
+        else {
+            await fs.rmdir(fullPath);
+        }
+    }
+    async listDirectory(dirPath) {
+        try {
+            const entries = await fs.readdir(this.getFullPath(dirPath), { withFileTypes: true });
+            return entries
+                .map((entry) => nodePath.join(dirPath, entry.name))
+                .filter((name) => !name.endsWith('/.'));
+        }
+        catch {
+            return [];
+        }
+    }
+    async getStats(filePath) {
+        const checkPath = filePath ? this.getFullPath(filePath) : this.basePath;
+        try {
+            const stats = await fs.stat(checkPath);
+            return {
+                totalSize: 0, // 需要系统特定的实现
+                freeSpace: 0, // 需要系统特定的实现
+                usedSpace: stats.size,
+                accessible: true
+            };
+        }
+        catch {
+            return {
+                totalSize: 0,
+                freeSpace: 0,
+                usedSpace: 0,
+                accessible: false
+            };
+        }
+    }
+    async getFileSize(filePath) {
+        const stats = await fs.stat(this.getFullPath(filePath));
+        return stats.size;
+    }
+    async copyFile(source, destination) {
+        await fs.copyFile(this.getFullPath(source), this.getFullPath(destination));
+    }
+    async moveFile(source, destination) {
+        await fs.rename(this.getFullPath(source), this.getFullPath(destination));
+    }
+    async healthCheck() {
+        try {
+            await this.exists('');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+/**
+ * S3 Storage Adapter - NOT YET IMPLEMENTED
+ *
+ * TODO: This is a placeholder implementation. To use S3 storage:
+ * 1. Install AWS SDK: npm install @aws-sdk/client-s3
+ * 2. Implement the getS3Client method
+ * 3. Remove this warning comment
+ *
+ * @experimental This adapter is not functional. Use LocalStorageAdapter instead.
+ */
+export class S3StorageAdapter {
+    name;
+    type = 's3';
+    bucket;
+    region;
+    accessKeyId;
+    secretAccessKey;
+    endpoint;
+    constructor(config) {
+        this.name = `S3Storage(${config.bucket})`;
+        this.bucket = config.bucket;
+        this.region = config.region;
+        this.accessKeyId = config.accessKeyId;
+        this.secretAccessKey = config.secretAccessKey;
+        this.endpoint = config.endpoint;
+    }
+    async getS3Client() {
+        // TODO: Import AWS SDK - requires @aws-sdk/client-s3
+        // This is a placeholder that throws to prevent accidental use.
+        throw new Error('S3StorageAdapter is not implemented. Install @aws-sdk/client-s3 and implement this method.');
+    }
+    async exists(path) {
+        try {
+            const s3 = await this.getS3Client();
+            await s3.headObject({ Bucket: this.bucket, Key: path });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async readFile(path) {
+        const s3 = await this.getS3Client();
+        const result = await s3.getObject({ Bucket: this.bucket, Key: path });
+        return result.Body;
+    }
+    async writeFile(path, data) {
+        const s3 = await this.getS3Client();
+        await s3.putObject({
+            Bucket: this.bucket,
+            Key: path,
+            Body: data
+        });
+    }
+    async deleteFile(path) {
+        const s3 = await this.getS3Client();
+        await s3.deleteObject({ Bucket: this.bucket, Key: path });
+    }
+    async createDirectory(path) {
+        // S3 doesn't require explicit directory creation, but we create a placeholder object
+        const dirPath = path.endsWith('/') ? path : `${path}/`;
+        await this.writeFile(dirPath, '');
+    }
+    async deleteDirectory(path, recursive = false) {
+        if (recursive) {
+            const s3 = await this.getS3Client();
+            const objects = await s3.listObjectsV2({
+                Bucket: this.bucket,
+                Prefix: path.endsWith('/') ? path : `${path}/`
+            });
+            if (objects.Contents && objects.Contents.length > 0) {
+                await s3.deleteObjects({
+                    Bucket: this.bucket,
+                    Delete: {
+                        Objects: objects.Contents.map((obj) => ({ Key: obj.Key }))
+                    }
+                });
+            }
+        }
+        else {
+            await this.deleteFile(path.endsWith('/') ? path : `${path}/`);
+        }
+    }
+    async listDirectory(path) {
+        const s3 = await this.getS3Client();
+        const prefix = path.endsWith('/') ? path : `${path}/`;
+        const result = await s3.listObjectsV2({
+            Bucket: this.bucket,
+            Prefix: prefix,
+            Delimiter: '/'
+        });
+        const files = [];
+        // 添加文件
+        if (result.Contents) {
+            files.push(...result.Contents.map((obj) => obj.Key).filter((key) => key !== prefix));
+        }
+        // 添加子目录
+        if (result.CommonPrefixes) {
+            files.push(...result.CommonPrefixes.map((p) => p.Prefix.slice(0, -1)));
+        }
+        return files;
+    }
+    async getStats(path) {
+        // S3 storage stats would need CloudWatch or similar service
+        return {
+            totalSize: 0,
+            freeSpace: 0,
+            usedSpace: 0,
+            accessible: await this.healthCheck()
+        };
+    }
+    async getFileSize(path) {
+        const s3 = await this.getS3Client();
+        const result = await s3.headObject({ Bucket: this.bucket, Key: path });
+        return result.ContentLength || 0;
+    }
+    async copyFile(source, destination) {
+        const s3 = await this.getS3Client();
+        await s3.copyObject({
+            Bucket: this.bucket,
+            Key: destination,
+            CopySource: `${this.bucket}/${source}`
+        });
+    }
+    async moveFile(source, destination) {
+        await this.copyFile(source, destination);
+        await this.deleteFile(source);
+    }
+    async healthCheck() {
+        try {
+            const s3 = await this.getS3Client();
+            await s3.headBucket({ Bucket: this.bucket });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+export class StorageManager {
+    adapters = new Map();
+    primaryAdapter = 'default';
+    constructor(config) {
+        this.initializeAdapters(config);
+    }
+    initializeAdapters(config) {
+        // Initialize default local storage adapter
+        if (config.storageDirs && config.storageDirs.length > 0) {
+            const localAdapter = new LocalStorageAdapter(config.storageDirs[0]);
+            this.adapters.set('default', localAdapter);
+            this.primaryAdapter = 'default';
+        }
+        // TODO: Initialize other storage adapters here (S3, GCS, Azure Blob Storage, etc.)
+        // These are not yet implemented.
+    }
+    getAdapter(name = 'default') {
+        const adapter = this.adapters.get(name);
+        if (!adapter) {
+            throw new Error(`Storage adapter '${name}' not found`);
+        }
+        return adapter;
+    }
+    addAdapter(name, adapter) {
+        this.adapters.set(name, adapter);
+    }
+    removeAdapter(name) {
+        if (name === this.primaryAdapter) {
+            throw new Error('Cannot remove primary storage adapter');
+        }
+        return this.adapters.delete(name);
+    }
+    setPrimaryAdapter(name) {
+        if (!this.adapters.has(name)) {
+            throw new Error(`Storage adapter '${name}' not found`);
+        }
+        this.primaryAdapter = name;
+    }
+    getPrimaryAdapter() {
+        return this.getAdapter(this.primaryAdapter);
+    }
+    async getAdapterHealth() {
+        const health = {};
+        for (const [name, adapter] of this.adapters) {
+            try {
+                health[name] = await adapter.healthCheck();
+            }
+            catch {
+                health[name] = false;
+            }
+        }
+        return health;
+    }
+    listAdapters() {
+        return Array.from(this.adapters.entries()).map(([name, adapter]) => ({
+            name,
+            type: adapter.type,
+            isPrimary: name === this.primaryAdapter
+        }));
+    }
+}
+// 单例实例
+let storageManager = null;
+export function getStorageManager(config) {
+    if (!storageManager) {
+        if (!config) {
+            throw new Error('StorageManager requires config for initialization');
+        }
+        storageManager = new StorageManager(config);
+    }
+    return storageManager;
+}
+export function resetStorageManager() {
+    storageManager = null;
+}

package/dist/utils/index.js

@@ -0,0 +1,100 @@
+/**
+ * Common utility functions used across the preflight-mcp codebase.
+ * Centralizes repeated helper functions to reduce code duplication.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * Ensure a directory exists, creating it recursively if needed.
+ */
+export async function ensureDir(p) {
+    await fs.mkdir(p, { recursive: true });
+}
+/**
+ * Remove a file or directory if it exists.
+ * Does nothing if the path doesn't exist.
+ */
+export async function rmIfExists(p) {
+    await fs.rm(p, { recursive: true, force: true });
+}
+/**
+ * Get current timestamp in ISO format.
+ */
+export function nowIso() {
+    return new Date().toISOString();
+}
+/**
+ * Convert a path to POSIX format (forward slashes).
+ */
+export function toPosix(p) {
+    return p.replaceAll('\\', '/');
+}
+/**
+ * Calculate SHA256 hash of a buffer and return as hex string.
+ */
+export function sha256Hex(buf) {
+    return crypto.createHash('sha256').update(buf).digest('hex');
+}
+/**
+ * Calculate SHA256 hash of a UTF-8 string and return as hex string.
+ */
+export function sha256HexString(text) {
+    return crypto.createHash('sha256').update(text, 'utf8').digest('hex');
+}
+/**
+ * Check if a path is accessible (exists and can be read).
+ */
+export async function isPathAvailable(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a path's parent directory is accessible.
+ */
+export async function isParentAvailable(p) {
+    const parent = path.dirname(p);
+    return isPathAvailable(parent);
+}
+/**
+ * Copy directory recursively.
+ */
+export async function copyDir(src, dest) {
+    await fs.cp(src, dest, { recursive: true, force: true });
+}
+/**
+ * Write JSON to a file with pretty formatting.
+ */
+export async function writeJson(targetPath, obj) {
+    await ensureDir(path.dirname(targetPath));
+    await fs.writeFile(targetPath, JSON.stringify(obj, null, 2) + '\n', 'utf8');
+}
+/**
+ * Clip UTF-8 text to a maximum byte size.
+ * Returns the clipped text and a flag indicating if truncation occurred.
+ */
+export function clipUtf8(text, maxBytes) {
+    const normalized = text.replace(/\r\n/g, '\n');
+    const buf = Buffer.from(normalized, 'utf8');
+    if (buf.length <= maxBytes)
+        return { text: normalized, truncated: false };
+    // Cutting at a byte boundary may split a multi-byte codepoint; Node will replace invalid sequences.
+    const clipped = buf.subarray(0, maxBytes).toString('utf8');
+    return { text: `${clipped}\n\n[TRUNCATED]\n`, truncated: true };
+}
+/**
+ * Create a URL-safe slug from a string.
+ */
+export function slug(s) {
+    return s
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .slice(0, 64);
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "preflight-mcp",
+  "version": "0.1.0",
+  "description": "MCP server that creates evidence-based preflight bundles for GitHub repositories and library docs.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "preflight-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "smoke": "npm run build && node scripts/smoke.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "better-sqlite3": "^12.5.0",
+    "ignore": "^7.0.5",
+    "node-cron": "^4.2.1",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.2.0",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.0.3",
+    "@types/node-cron": "^3.0.11",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.6",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}