preflight-mcp 0.1.0

package/dist/bundle/facts.js

@@ -0,0 +1,296 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * Detect programming languages from file extensions
+ */
+function detectLanguages(files) {
+    const langMap = new Map();
+    const extToLang = {
+        '.ts': 'TypeScript',
+        '.tsx': 'TypeScript',
+        '.js': 'JavaScript',
+        '.jsx': 'JavaScript',
+        '.mjs': 'JavaScript',
+        '.cjs': 'JavaScript',
+        '.py': 'Python',
+        '.go': 'Go',
+        '.rs': 'Rust',
+        '.java': 'Java',
+        '.rb': 'Ruby',
+        '.php': 'PHP',
+        '.c': 'C',
+        '.cpp': 'C++',
+        '.cc': 'C++',
+        '.h': 'C/C++',
+        '.hpp': 'C++',
+        '.cs': 'C#',
+        '.swift': 'Swift',
+        '.kt': 'Kotlin',
+        '.scala': 'Scala',
+    };
+    for (const file of files) {
+        if (file.kind !== 'code')
+            continue;
+        const ext = path.extname(file.repoRelativePath).toLowerCase();
+        const lang = extToLang[ext] || 'Other';
+        if (!langMap.has(lang)) {
+            langMap.set(lang, new Set());
+        }
+        langMap.get(lang).add(ext);
+    }
+    return Array.from(langMap.entries())
+        .map(([language, exts]) => ({
+        language,
+        fileCount: files.filter((f) => f.kind === 'code' && exts.has(path.extname(f.repoRelativePath).toLowerCase())).length,
+        extensions: Array.from(exts).sort(),
+    }))
+        .sort((a, b) => b.fileCount - a.fileCount);
+}
+/**
+ * Find entry points in the repository
+ */
+async function findEntryPoints(files, bundleRoot, repoId) {
+    const entryPoints = [];
+    const [owner, repo] = repoId.split('/');
+    // Check package.json for Node.js projects
+    const pkgJson = files.find((f) => f.repoRelativePath === 'package.json');
+    if (pkgJson) {
+        try {
+            const content = await fs.readFile(pkgJson.bundleNormAbsPath, 'utf8');
+            const pkg = JSON.parse(content);
+            if (pkg.main) {
+                entryPoints.push({
+                    type: 'package-main',
+                    file: `repos/${owner}/${repo}/norm/${pkg.main}`,
+                    evidence: `${pkgJson.bundleNormRelativePath}:1`,
+                });
+            }
+            if (pkg.bin) {
+                const binEntries = typeof pkg.bin === 'string' ? { [repo]: pkg.bin } : pkg.bin;
+                for (const [name, binPath] of Object.entries(binEntries)) {
+                    entryPoints.push({
+                        type: 'package-bin',
+                        file: `repos/${owner}/${repo}/norm/${binPath}`,
+                        evidence: `${pkgJson.bundleNormRelativePath}:1`,
+                    });
+                }
+            }
+        }
+        catch {
+            // Ignore parsing errors
+        }
+    }
+    // Common entry point patterns
+    const commonEntries = ['index.ts', 'index.js', 'main.ts', 'main.js', 'src/index.ts', 'src/main.ts'];
+    for (const entry of commonEntries) {
+        const file = files.find((f) => f.repoRelativePath === entry);
+        if (file) {
+            entryPoints.push({
+                type: entry.includes('index') ? 'index-file' : 'main-file',
+                file: file.bundleNormRelativePath,
+                evidence: `${file.bundleNormRelativePath}:1`,
+            });
+        }
+    }
+    return entryPoints;
+}
+/**
+ * Extract dependency information
+ */
+async function extractDependencies(files, bundleRoot) {
+    const result = {
+        runtime: [],
+        dev: [],
+        manager: 'unknown',
+    };
+    // Node.js - package.json
+    const pkgJson = files.find((f) => f.repoRelativePath === 'package.json');
+    if (pkgJson) {
+        result.manager = 'npm';
+        try {
+            const content = await fs.readFile(pkgJson.bundleNormAbsPath, 'utf8');
+            const pkg = JSON.parse(content);
+            if (pkg.dependencies) {
+                for (const [name, version] of Object.entries(pkg.dependencies)) {
+                    result.runtime.push({
+                        name,
+                        version: String(version),
+                        evidence: `${pkgJson.bundleNormRelativePath}:1`,
+                    });
+                }
+            }
+            if (pkg.devDependencies) {
+                for (const [name, version] of Object.entries(pkg.devDependencies)) {
+                    result.dev.push({
+                        name,
+                        version: String(version),
+                        evidence: `${pkgJson.bundleNormRelativePath}:1`,
+                    });
+                }
+            }
+        }
+        catch {
+            // Ignore parsing errors
+        }
+    }
+    // Python - requirements.txt
+    const reqTxt = files.find((f) => f.repoRelativePath === 'requirements.txt');
+    if (reqTxt) {
+        result.manager = 'pip';
+        try {
+            const content = await fs.readFile(reqTxt.bundleNormAbsPath, 'utf8');
+            const lines = content.split('\n');
+            for (let i = 0; i < lines.length; i++) {
+                const line = lines[i]?.trim() ?? '';
+                if (!line || line.startsWith('#'))
+                    continue;
+                const match = line.match(/^([a-zA-Z0-9_-]+)(==|>=|<=|~=)?(.+)?/);
+                if (match) {
+                    result.runtime.push({
+                        name: match[1],
+                        version: match[3],
+                        evidence: `${reqTxt.bundleNormRelativePath}:${i + 1}`,
+                    });
+                }
+            }
+        }
+        catch {
+            // Ignore errors
+        }
+    }
+    // Go - go.mod
+    const goMod = files.find((f) => f.repoRelativePath === 'go.mod');
+    if (goMod) {
+        result.manager = 'go';
+        try {
+            const content = await fs.readFile(goMod.bundleNormAbsPath, 'utf8');
+            const lines = content.split('\n');
+            for (let i = 0; i < lines.length; i++) {
+                const line = lines[i]?.trim() ?? '';
+                const match = line.match(/^\s*([^\s]+)\s+v?([0-9.]+)/);
+                if (match) {
+                    result.runtime.push({
+                        name: match[1],
+                        version: match[2],
+                        evidence: `${goMod.bundleNormRelativePath}:${i + 1}`,
+                    });
+                }
+            }
+        }
+        catch {
+            // Ignore errors
+        }
+    }
+    return result;
+}
+/**
+ * Analyze file structure
+ */
+function analyzeFileStructure(files) {
+    const topLevelDirs = new Set();
+    for (const file of files) {
+        const parts = file.repoRelativePath.split('/');
+        if (parts.length > 1 && parts[0]) {
+            topLevelDirs.add(parts[0]);
+        }
+    }
+    const hasTests = files.some((f) => f.repoRelativePath.includes('/test/') ||
+        f.repoRelativePath.includes('/tests/') ||
+        f.repoRelativePath.includes('/__tests__/') ||
+        f.repoRelativePath.includes('.test.') ||
+        f.repoRelativePath.includes('.spec.'));
+    const hasConfig = files.some((f) => f.repoRelativePath.includes('config') ||
+        f.repoRelativePath.endsWith('.config.js') ||
+        f.repoRelativePath.endsWith('.config.ts') ||
+        f.repoRelativePath.endsWith('.json'));
+    return {
+        totalFiles: files.length,
+        totalDocs: files.filter((f) => f.kind === 'doc').length,
+        totalCode: files.filter((f) => f.kind === 'code').length,
+        topLevelDirs: Array.from(topLevelDirs).sort(),
+        hasTests,
+        hasConfig,
+    };
+}
+/**
+ * Detect frameworks from dependencies and file patterns
+ */
+function detectFrameworks(deps, files) {
+    const frameworks = new Set();
+    const allDeps = [...deps.runtime, ...deps.dev].map((d) => d.name.toLowerCase());
+    // JavaScript/TypeScript frameworks
+    if (allDeps.includes('react'))
+        frameworks.add('React');
+    if (allDeps.includes('vue'))
+        frameworks.add('Vue');
+    if (allDeps.includes('angular'))
+        frameworks.add('Angular');
+    if (allDeps.includes('next'))
+        frameworks.add('Next.js');
+    if (allDeps.includes('nuxt'))
+        frameworks.add('Nuxt');
+    if (allDeps.includes('express'))
+        frameworks.add('Express');
+    if (allDeps.includes('fastify'))
+        frameworks.add('Fastify');
+    if (allDeps.includes('nestjs'))
+        frameworks.add('NestJS');
+    // Python frameworks
+    if (allDeps.includes('django'))
+        frameworks.add('Django');
+    if (allDeps.includes('flask'))
+        frameworks.add('Flask');
+    if (allDeps.includes('fastapi'))
+        frameworks.add('FastAPI');
+    // Test frameworks
+    if (allDeps.includes('jest'))
+        frameworks.add('Jest');
+    if (allDeps.includes('vitest'))
+        frameworks.add('Vitest');
+    if (allDeps.includes('pytest'))
+        frameworks.add('Pytest');
+    return Array.from(frameworks).sort();
+}
+/**
+ * Extract all facts from a bundle
+ */
+export async function extractBundleFacts(params) {
+    // Aggregate all files
+    const allFiles = params.repos.flatMap((r) => r.files);
+    // Extract facts
+    const languages = detectLanguages(allFiles);
+    const entryPointsPromises = params.repos.map((r) => findEntryPoints(r.files, params.bundleRoot, r.repoId));
+    const entryPointsArrays = await Promise.all(entryPointsPromises);
+    const entryPoints = entryPointsArrays.flat();
+    const dependencies = await extractDependencies(allFiles, params.bundleRoot);
+    const fileStructure = analyzeFileStructure(allFiles);
+    const frameworks = detectFrameworks(dependencies, allFiles);
+    return {
+        version: '1.0',
+        timestamp: new Date().toISOString(),
+        languages,
+        entryPoints,
+        dependencies,
+        fileStructure,
+        frameworks,
+    };
+}
+/**
+ * Write facts to JSON file
+ */
+export async function writeFacts(factsPath, facts) {
+    await fs.mkdir(path.dirname(factsPath), { recursive: true });
+    await fs.writeFile(factsPath, JSON.stringify(facts, null, 2) + '\n', 'utf8');
+}
+/**
+ * Read facts from JSON file
+ */
+export async function readFacts(factsPath) {
+    try {
+        const content = await fs.readFile(factsPath, 'utf8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/bundle/github.js

@@ -0,0 +1,55 @@
+import { execFile } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export function parseOwnerRepo(input) {
+    const trimmed = input.trim().replace(/^https?:\/\/github\.com\//i, '');
+    const parts = trimmed.split('/').filter(Boolean);
+    if (parts.length < 2) {
+        throw new Error(`Invalid GitHub repo identifier: ${input} (expected owner/repo)`);
+    }
+    return { owner: parts[0], repo: parts[1].replace(/\.git$/i, '') };
+}
+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,
+    });
+    return { stdout, stderr };
+}
+export async function getRemoteHeadSha(cloneUrl) {
+    const { stdout } = await runGit(['ls-remote', cloneUrl, 'HEAD'], { timeoutMs: 60_000 });
+    const line = stdout.trim().split(/\r?\n/)[0];
+    if (!line)
+        throw new Error(`git ls-remote returned empty output for ${cloneUrl}`);
+    const [sha] = line.split(/\s+/);
+    if (!sha || sha.length < 8)
+        throw new Error(`Could not parse remote sha from: ${line}`);
+    return sha;
+}
+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) {
+        args.push('--branch', opts.ref);
+    }
+    args.push(cloneUrl, destDir);
+    await runGit(args, { timeoutMs: 15 * 60_000 });
+}
+export async function getLocalHeadSha(repoDir) {
+    const { stdout } = await runGit(['-C', repoDir, 'rev-parse', 'HEAD']);
+    return stdout.trim();
+}

package/dist/bundle/guides.js

@@ -0,0 +1,65 @@
+import fs from 'node:fs/promises';
+export async function writeAgentsMd(targetPath) {
+    const content = `# AGENTS.md - Rules for using this Preflight Bundle
+
+This bundle is an **evidence pack**. You must stay factual.
+
+## Non-negotiable rules
+- Only use evidence **inside this bundle**.
+- Every factual claim in your answer must include an **Evidence pointer**:
+  - file path (within this bundle) + line range
+  - or a direct quote snippet with a pointer
+- If you cannot find evidence, you must say: **"Not found in this bundle"** and suggest next steps:
+  - run preflight_search_bundle
+  - run preflight_update_bundle
+  - expand bundle scope and rebuild
+
+## Forbidden behavior
+- Do not guess.
+- Do not invent APIs, commands, file paths, or architecture.
+- Avoid words like "probably", "likely", "should" unless you attach evidence.
+
+## How to cite evidence
+Use this format:
+- (evidence: <bundle-relative-path>:<startLine>-<endLine>)
+
+Example:
+- The project uses TypeScript. (evidence: repos/foo/bar/norm/package.json:1-40)
+`;
+    await fs.writeFile(targetPath, content, 'utf8');
+}
+export async function writeStartHereMd(params) {
+    const repoLines = params.repos
+        .map((r) => `- ${r.id}${r.headSha ? ` @ ${r.headSha}` : ''}`)
+        .join('\n');
+    const libraryLines = (params.libraries ?? [])
+        .map((l) => {
+        const resolved = l.id ? ` -> ${l.id}` : '';
+        return `- ${l.kind}: ${l.input}${resolved}`;
+    })
+        .join('\n');
+    const content = `# START_HERE.md - Preflight Bundle ${params.bundleId}
+
+## What this is
+This bundle is a local snapshot of selected repositories (and optionally library docs) for **evidence-based** development.
+
+## Repositories included
+${repoLines || '(none)'}
+
+## Library docs included
+${libraryLines || '(none)'}
+
+## How to use
+1) Read AGENTS.md first and follow its rules.
+2) Read OVERVIEW.md for a quick, evidence-linked map.
+3) Use search to find exact evidence:
+   - tool: preflight_search_bundle
+4) If the repo may have changed, refresh:
+   - tool: preflight_update_bundle
+
+## Tips
+- Prefer quoting exact file content over paraphrasing.
+- When unsure, open the referenced file resource and verify.
+`;
+    await fs.writeFile(params.targetPath, content, 'utf8');
+}

package/dist/bundle/ingest.js

@@ -0,0 +1,152 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import ignore from 'ignore';
+const DEFAULT_IGNORE = [
+    '.git/',
+    'node_modules/',
+    'dist/',
+    'build/',
+    'out/',
+    '.next/',
+    '.turbo/',
+    '.cache/',
+    'coverage/',
+    '__pycache__/',
+    '.venv/',
+    'venv/',
+    '.idea/',
+    '.vscode/',
+];
+function toPosix(p) {
+    return p.replaceAll('\\', '/');
+}
+function sha256Hex(buf) {
+    return crypto.createHash('sha256').update(buf).digest('hex');
+}
+function isProbablyBinary(buf) {
+    const sample = buf.subarray(0, Math.min(buf.length, 8192));
+    for (const b of sample) {
+        if (b === 0)
+            return true;
+    }
+    return false;
+}
+function classifyKind(repoRelativePathPosix) {
+    const base = path.posix.basename(repoRelativePathPosix).toLowerCase();
+    const ext = path.posix.extname(repoRelativePathPosix).toLowerCase();
+    if (base === 'readme' ||
+        base === 'readme.md' ||
+        base.startsWith('readme.') ||
+        base === 'license' ||
+        base.startsWith('license.') ||
+        base === 'contributing' ||
+        base === 'contributing.md' ||
+        base === 'code_of_conduct' ||
+        base === 'code_of_conduct.md' ||
+        base === 'security' ||
+        base === 'security.md' ||
+        base === 'changelog' ||
+        base === 'changelog.md' ||
+        base === 'llms.txt') {
+        return 'doc';
+    }
+    if (repoRelativePathPosix.includes('/docs/') || repoRelativePathPosix.includes('/doc/')) {
+        return 'doc';
+    }
+    if (['.md', '.markdown', '.rst', '.txt', '.adoc'].includes(ext))
+        return 'doc';
+    return 'code';
+}
+async function buildIgnore(repoRoot) {
+    const ig = ignore();
+    ig.add(DEFAULT_IGNORE);
+    // Respect repo .gitignore if present.
+    try {
+        const gitignorePath = path.join(repoRoot, '.gitignore');
+        const raw = await fs.readFile(gitignorePath, 'utf8');
+        ig.add(raw);
+    }
+    catch {
+        // ignore
+    }
+    return ig;
+}
+async function* walkFiles(repoRoot, ig) {
+    const stack = [repoRoot];
+    while (stack.length) {
+        const dir = stack.pop();
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const ent of entries) {
+            const abs = path.join(dir, ent.name);
+            const rel = path.relative(repoRoot, abs);
+            const relPosix = toPosix(rel);
+            // Check ignore rules for both files and directories
+            if (ig.ignores(relPosix)) {
+                continue;
+            }
+            if (ent.isDirectory()) {
+                stack.push(abs);
+                continue;
+            }
+            if (!ent.isFile())
+                continue;
+            yield { absPath: abs, relPosix };
+        }
+    }
+}
+export async function ingestRepoToBundle(params) {
+    const ig = await buildIgnore(params.repoRoot);
+    let totalBytes = 0;
+    const files = [];
+    const skipped = [];
+    const decoder = new TextDecoder('utf-8', { fatal: true });
+    for await (const f of walkFiles(params.repoRoot, ig)) {
+        // ignore check already done in walkFiles
+        const st = await fs.stat(f.absPath);
+        if (st.size > params.options.maxFileBytes) {
+            skipped.push(`${f.relPosix} (too large: ${st.size} bytes)`);
+            continue;
+        }
+        if (totalBytes + st.size > params.options.maxTotalBytes) {
+            skipped.push(`(bundle maxTotalBytes reached) stopped before: ${f.relPosix}`);
+            break;
+        }
+        const buf = await fs.readFile(f.absPath);
+        if (isProbablyBinary(buf)) {
+            skipped.push(`${f.relPosix} (binary)`);
+            continue;
+        }
+        let text;
+        try {
+            text = decoder.decode(buf);
+        }
+        catch {
+            skipped.push(`${f.relPosix} (non-utf8)`);
+            continue;
+        }
+        // Write raw bytes (as checked out by git).
+        const rawDest = path.join(params.rawDestRoot, f.relPosix.split('/').join(path.sep));
+        await fs.mkdir(path.dirname(rawDest), { recursive: true });
+        await fs.writeFile(rawDest, buf);
+        // Write normalized text with LF.
+        const normalized = text.replace(/\r\n/g, '\n');
+        const normDest = path.join(params.normDestRoot, f.relPosix.split('/').join(path.sep));
+        await fs.mkdir(path.dirname(normDest), { recursive: true });
+        await fs.writeFile(normDest, normalized, 'utf8');
+        totalBytes += st.size;
+        const kind = classifyKind(f.relPosix);
+        const sha256 = sha256Hex(Buffer.from(normalized, 'utf8'));
+        const bundleNormRelativePath = `${params.bundleNormPrefixPosix}/${f.relPosix}`;
+        files.push({
+            repoId: params.repoId,
+            kind,
+            repoRelativePath: f.relPosix,
+            bundleNormRelativePath,
+            bundleNormAbsPath: normDest,
+            sha256,
+            bytes: st.size,
+        });
+    }
+    return { files, totalBytes, skipped };
+}

package/dist/bundle/manifest.js

@@ -0,0 +1,14 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+export async function readManifest(manifestPath) {
+    const raw = await fs.readFile(manifestPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed.schemaVersion !== 1) {
+        throw new Error(`Unsupported manifest schemaVersion: ${String(parsed.schemaVersion)}`);
+    }
+    return parsed;
+}
+export async function writeManifest(manifestPath, manifest) {
+    await fs.mkdir(path.dirname(manifestPath), { recursive: true });
+    await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+}