superkit-mcp-server 1.0.1 → 1.0.2

package/build/tools/validators/apiValidator.js

@@ -0,0 +1,140 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+export async function findApiFiles(projectPath) {
+    let files = [];
+    // very basic matching 
+    async function search(dir) {
+        try {
+            const items = await fs.readdir(dir, { withFileTypes: true });
+            for (const item of items) {
+                if (['node_modules', '.git', 'dist', 'build', '__pycache__'].includes(item.name))
+                    continue;
+                const fullPath = path.join(dir, item.name);
+                if (item.isDirectory()) {
+                    await search(fullPath);
+                }
+                else {
+                    const name = item.name.toLowerCase();
+                    if ((name.includes('api') || fullPath.includes('routes') || fullPath.includes('controllers') || fullPath.includes('endpoints')) &&
+                        (name.endsWith('.ts') || name.endsWith('.js') || name.endsWith('.py'))) {
+                        files.push(fullPath);
+                    }
+                    if (name.includes('openapi') || name.includes('swagger')) {
+                        files.push(fullPath);
+                    }
+                }
+            }
+        }
+        catch { }
+    }
+    await search(projectPath);
+    return files;
+}
+export async function checkOpenApiSpec(filePath) {
+    const result = { file: filePath, passed: [], issues: [], type: 'openapi' };
+    try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        if (filePath.endsWith('.json')) {
+            const spec = JSON.parse(content);
+            if (spec.openapi || spec.swagger)
+                result.passed.push("[OK] OpenAPI version defined");
+            if (spec.info?.title)
+                result.passed.push("[OK] API title defined");
+            if (spec.info?.version)
+                result.passed.push("[OK] API version defined");
+            if (!spec.info?.description)
+                result.issues.push("[!] API description missing");
+            if (spec.paths) {
+                result.passed.push(`[OK] ${Object.keys(spec.paths).length} endpoints defined`);
+                for (const [p, methods] of Object.entries(spec.paths)) {
+                    for (const [method, details] of Object.entries(methods)) {
+                        if (['get', 'post', 'put', 'patch', 'delete'].includes(method)) {
+                            if (!details.responses)
+                                result.issues.push(`[X] ${method.toUpperCase()} ${p}: No responses defined`);
+                            if (!details.summary && !details.description)
+                                result.issues.push(`[!] ${method.toUpperCase()} ${p}: No description`);
+                        }
+                    }
+                }
+            }
+        }
+        else {
+            // Basic YAML
+            if (content.includes('openapi:') || content.includes('swagger:'))
+                result.passed.push("[OK] OpenAPI/Swagger version defined");
+            else
+                result.issues.push("[X] No OpenAPI version found");
+            if (content.includes('paths:'))
+                result.passed.push("[OK] Paths section exists");
+            else
+                result.issues.push("[X] No paths defined");
+        }
+    }
+    catch (e) {
+        result.issues.push(`[X] Parse error: ${e.message}`);
+    }
+    return result;
+}
+export async function checkApiCode(filePath) {
+    const result = { file: filePath, passed: [], issues: [], type: 'code' };
+    try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        // error handling
+        if (/try\s*{|try:|\.catch\(|except\s+|catch\s*\(/.test(content))
+            result.passed.push("[OK] Error handling present");
+        else
+            result.issues.push("[X] No error handling found");
+        // status codes
+        if (/status\s*\(\s*\d{3}\s*\)|statusCode\s*[=:]\s*\d{3}|HttpStatus\.|status_code\s*=\s*\d{3}/.test(content))
+            result.passed.push("[OK] HTTP status codes used");
+        else
+            result.issues.push("[!] No explicit HTTP status codes");
+        // validation
+        if (/validate|schema|zod|joi|yup|pydantic|@Body\(|@Query\(/i.test(content))
+            result.passed.push("[OK] Input validation present");
+        else
+            result.issues.push("[!] No input validation detected");
+        // auth
+        if (/auth|jwt|bearer|token|middleware|guard|@Authenticated/i.test(content))
+            result.passed.push("[OK] Authentication/authorization detected");
+    }
+    catch (e) {
+        result.issues.push(`[X] Read error: ${e.message}`);
+    }
+    return result;
+}
+export async function runApiValidator(projectPath = ".") {
+    const root = path.resolve(projectPath);
+    const files = await findApiFiles(root);
+    let report = `============================================================\n`;
+    report += `  API VALIDATOR - Endpoint Best Practices Check\n`;
+    report += `============================================================\n`;
+    if (files.length === 0) {
+        return { passed: true, report: report + "[!] No API files found.\n" };
+    }
+    const results = [];
+    for (const file of files.slice(0, 15)) {
+        if (file.toLowerCase().includes('openapi') || file.toLowerCase().includes('swagger')) {
+            results.push(await checkOpenApiSpec(file));
+        }
+        else {
+            results.push(await checkApiCode(file));
+        }
+    }
+    let totalIssues = 0, totalPassed = 0;
+    for (const r of results) {
+        report += `\n[FILE] ${path.basename(r.file)} [${r.type}]\n`;
+        for (const p of r.passed) {
+            report += `   ${p}\n`;
+            totalPassed++;
+        }
+        for (const i of r.issues) {
+            report += `   ${i}\n`;
+            if (i.startsWith("[X]"))
+                totalIssues++;
+        }
+    }
+    report += `\n============================================================\n`;
+    report += `[RESULTS] ${totalPassed} passed, ${totalIssues} critical issues\n`;
+    return { passed: totalIssues === 0, report };
+}

package/build/tools/validators/convertRules.js

@@ -0,0 +1,170 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+const SECTIONS = {
+    'async': {
+        'number': 1,
+        'title': 'Eliminating Waterfalls',
+        'impact': 'CRITICAL',
+        'description': 'Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.'
+    },
+    'bundle': {
+        'number': 2,
+        'title': 'Bundle Size Optimization',
+        'impact': 'CRITICAL',
+        'description': 'Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.'
+    },
+    'server': {
+        'number': 3,
+        'title': 'Server-Side Performance',
+        'impact': 'HIGH',
+        'description': 'Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.'
+    },
+    'client': {
+        'number': 4,
+        'title': 'Client-Side Data Fetching',
+        'impact': 'MEDIUM-HIGH',
+        'description': 'Automatic deduplication and efficient data fetching patterns reduce redundant network requests.'
+    },
+    'rerender': {
+        'number': 5,
+        'title': 'Re-render Optimization',
+        'impact': 'MEDIUM',
+        'description': 'Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.'
+    },
+    'rendering': {
+        'number': 6,
+        'title': 'Rendering Performance',
+        'impact': 'MEDIUM',
+        'description': 'Optimizing the rendering process reduces the work the browser needs to do.'
+    },
+    'js': {
+        'number': 7,
+        'title': 'JavaScript Performance',
+        'impact': 'LOW-MEDIUM',
+        'description': 'Micro-optimizations for hot paths can add up to meaningful improvements.'
+    },
+    'advanced': {
+        'number': 8,
+        'title': 'Advanced Patterns',
+        'impact': 'VARIABLE',
+        'description': 'Advanced patterns for specific cases that require careful implementation.'
+    }
+};
+function parseFrontmatter(content) {
+    if (!content.startsWith('---'))
+        return { frontmatter: {}, body: content };
+    const parts = content.split('---');
+    if (parts.length < 3)
+        return { frontmatter: {}, body: content };
+    const frontmatterStr = parts[1].trim();
+    const body = parts.slice(2).join('---').trim();
+    const frontmatter = {};
+    for (const line of frontmatterStr.split('\n')) {
+        const colonIdx = line.indexOf(':');
+        if (colonIdx !== -1) {
+            const key = line.substring(0, colonIdx).trim();
+            const value = line.substring(colonIdx + 1).trim();
+            frontmatter[key] = value;
+        }
+    }
+    return { frontmatter, body };
+}
+async function parseRuleFile(filepath) {
+    const content = await fs.readFile(filepath, 'utf-8');
+    const { frontmatter, body } = parseFrontmatter(content);
+    const filename = path.basename(filepath);
+    const prefix = path.parse(filename).name.split('-')[0];
+    return {
+        filename,
+        prefix,
+        title: frontmatter['title'] || path.parse(filename).name,
+        impact: frontmatter['impact'] || '',
+        impactDescription: frontmatter['impactDescription'] || '',
+        tags: frontmatter['tags'] || '',
+        body,
+        frontmatter
+    };
+}
+async function groupRulesBySection(rulesDir) {
+    const grouped = {};
+    for (const key of Object.keys(SECTIONS))
+        grouped[key] = [];
+    try {
+        const files = await fs.readdir(rulesDir);
+        for (const file of files) {
+            if (file.startsWith('_') || !file.endsWith('.md'))
+                continue;
+            const rule = await parseRuleFile(path.join(rulesDir, file));
+            if (grouped[rule.prefix]) {
+                grouped[rule.prefix].push(rule);
+            }
+            else {
+                console.warn(`[WARNING] Unknown prefix '${rule.prefix}' in file: ${file}`);
+            }
+        }
+    }
+    catch (e) {
+        throw new Error(`Failed to read rules directory: ${e.message}`);
+    }
+    return grouped;
+}
+async function generateSectionFile(sectionPrefix, rules, outputDir, getOutputOnly = false) {
+    if (!rules || rules.length === 0)
+        return "";
+    const sectionMeta = SECTIONS[sectionPrefix];
+    const sectionNum = sectionMeta.number;
+    const sectionTitle = sectionMeta.title;
+    rules.sort((a, b) => a.title.localeCompare(b.title));
+    let content = `# ${sectionNum}. ${sectionTitle}\n\n> **Impact:** ${sectionMeta.impact}\n> **Focus:** ${sectionMeta.description}\n\n---\n\n## Overview\n\nThis section contains **${rules.length} rules** focused on ${sectionTitle.toLowerCase()}.\n\n`;
+    for (let i = 0; i < rules.length; i++) {
+        const rule = rules[i];
+        const ruleId = `${sectionNum}.${i + 1}`;
+        content += `---\n\n## Rule ${ruleId}: ${rule.title}\n\n`;
+        if (rule.impact)
+            content += `**Impact:** ${rule.impact}  \n`;
+        if (rule.tags)
+            content += `**Tags:** ${rule.tags}  \n`;
+        content += `\n${rule.body}\n\n`;
+    }
+    if (getOutputOnly)
+        return content;
+    const outputFilename = `${sectionNum}-${sectionPrefix}-${sectionTitle.toLowerCase().replace(/\s+/g, '-')}.md`;
+    await fs.mkdir(outputDir, { recursive: true });
+    await fs.writeFile(path.join(outputDir, outputFilename), content, 'utf-8');
+    return `[OK] Generated: ${outputFilename} (${rules.length} rules)\n`;
+}
+export async function runConvertRules(projectPath = ".") {
+    let report = `============================================================\n`;
+    report += `CONVERSION SCRIPT: React Best Practices -> .agent Format\n`;
+    report += `============================================================\n`;
+    const baseDir = path.resolve(projectPath);
+    // Mimic the python logic for paths if run from anywhere, or adapt to superkit structure
+    const rulesDir = path.join(baseDir, "skills", "react-best-practices", "rules");
+    const outputDir = path.join(baseDir, ".agent", "skills", "react-best-practices");
+    report += `[*] Reading rules from: ${rulesDir}\n[*] Output to: ${outputDir}\n\n`;
+    try {
+        const stat = await fs.stat(rulesDir);
+        if (!stat.isDirectory())
+            throw new Error("Not a directory");
+    }
+    catch {
+        return { passed: false, report: report + `[ERROR] Rules directory not found: ${rulesDir}\n` };
+    }
+    try {
+        const groupedRules = await groupRulesBySection(rulesDir);
+        let totalRules = 0;
+        for (const rules of Object.values(groupedRules))
+            totalRules += rules.length;
+        report += `[*] Found ${totalRules} total rules\n\n[*] Generating section files...\n`;
+        for (const prefix of Object.keys(SECTIONS)) {
+            const out = await generateSectionFile(prefix, groupedRules[prefix], outputDir);
+            if (out)
+                report += out;
+        }
+        report += `\n[SUCCESS] Conversion complete!\n[*] Generated 8 section files from ${totalRules} rules\n`;
+        return { passed: true, report };
+    }
+    catch (e) {
+        return { passed: false, report: report + `[ERROR] ${e.message}\n` };
+    }
+}

package/build/tools/validators/geoChecker.js

@@ -0,0 +1,176 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+const SKIP_DIRS = new Set([
+    'node_modules', '.next', 'dist', 'build', '.git', '.github',
+    '__pycache__', '.vscode', '.idea', 'coverage', 'test', 'tests',
+    '__tests__', 'spec', 'docs', 'documentation'
+]);
+const SKIP_FILES = new Set([
+    'jest.config', 'webpack.config', 'vite.config', 'tsconfig',
+    'package.json', 'package-lock', 'yarn.lock', '.eslintrc',
+    'tailwind.config', 'postcss.config', 'next.config'
+]);
+function isPageFile(filePath) {
+    const name = path.basename(filePath).toLowerCase();
+    for (const skip of SKIP_FILES) {
+        if (name.includes(skip))
+            return false;
+    }
+    if (name.endsWith('.test') || name.endsWith('.spec') || name.startsWith('test_') || name.startsWith('spec_')) {
+        return false;
+    }
+    const pageIndicators = ['page', 'index', 'home', 'about', 'contact', 'blog', 'post', 'article', 'product', 'service', 'landing'];
+    const parts = filePath.toLowerCase().split(path.sep);
+    if (parts.includes('pages') || parts.includes('app') || parts.includes('routes'))
+        return true;
+    for (const ind of pageIndicators) {
+        if (name.includes(ind))
+            return true;
+    }
+    if (name.endsWith('.html'))
+        return true;
+    return false;
+}
+export async function findWebPages(projectPath) {
+    let files = [];
+    async function search(dir) {
+        try {
+            const items = await fs.readdir(dir, { withFileTypes: true });
+            for (const item of items) {
+                if (SKIP_DIRS.has(item.name))
+                    continue;
+                const fullPath = path.join(dir, item.name);
+                if (item.isDirectory())
+                    await search(fullPath);
+                else {
+                    const ext = path.extname(item.name).toLowerCase();
+                    if (['.html', '.htm', '.jsx', '.tsx'].includes(ext)) {
+                        if (isPageFile(fullPath))
+                            files.push(fullPath);
+                    }
+                }
+            }
+        }
+        catch { }
+    }
+    await search(projectPath);
+    return files.slice(0, 30);
+}
+export async function checkGeoPage(filePath) {
+    const result = { file: path.basename(filePath), passed: [], issues: [], score: 0 };
+    try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        // JSON-LD
+        if (content.includes('application/ld+json')) {
+            result.passed.push("JSON-LD structured data found");
+            if (content.includes('"@type"')) {
+                if (content.includes('Article'))
+                    result.passed.push("Article schema present");
+                if (content.includes('FAQPage'))
+                    result.passed.push("FAQ schema present");
+                if (content.includes('Organization') || content.includes('Person'))
+                    result.passed.push("Entity schema present");
+            }
+        }
+        else {
+            result.issues.push("No JSON-LD structured data (AI engines prefer structured content)");
+        }
+        // Headings
+        const h1Count = (content.match(/<h1[^>]*>/gi) || []).length;
+        const h2Count = (content.match(/<h2[^>]*>/gi) || []).length;
+        if (h1Count === 1)
+            result.passed.push("Single H1 heading (clear topic)");
+        else if (h1Count === 0)
+            result.issues.push("No H1 heading - page topic unclear");
+        else
+            result.issues.push(`Multiple H1 headings (${h1Count}) - confusing for AI`);
+        if (h2Count >= 2)
+            result.passed.push(`${h2Count} H2 subheadings (good structure)`);
+        else
+            result.issues.push("Add more H2 subheadings for scannable content");
+        // Author
+        const lowerC = content.toLowerCase();
+        if (['author', 'byline', 'written-by', 'contributor', 'rel="author"'].some(p => lowerC.includes(p))) {
+            result.passed.push("Author attribution found");
+        }
+        else
+            result.issues.push("No author info (AI prefers attributed content)");
+        // Date
+        if (/datePublished|dateModified|datetime=|pubdate|article:published/i.test(content)) {
+            result.passed.push("Publication date found");
+        }
+        else
+            result.issues.push("No publication date (freshness matters for AI)");
+        // FAQ
+        if (/<details|faq|frequently.?asked|"FAQPage"/i.test(content)) {
+            result.passed.push("FAQ section detected (highly citable)");
+        }
+        const listCount = (content.match(/<(ul|ol)[^>]*>/gi) || []).length;
+        if (listCount >= 2)
+            result.passed.push(`${listCount} lists (structured content)`);
+        const tableCount = (content.match(/<table[^>]*>/gi) || []).length;
+        if (tableCount >= 1)
+            result.passed.push(`${tableCount} table(s) (comparison data)`);
+        // Entities
+        if (/"@type"\s*:\s*"Organization"|"@type"\s*:\s*"LocalBusiness"|"@type"\s*:\s*"Brand"|itemtype.*schema\.org\/(Organization|Person|Brand)|rel="author"/i.test(content)) {
+            result.passed.push("Entity/Brand recognition (E-E-A-T)");
+        }
+        // Stats
+        let stats = 0;
+        const statPatterns = [/\d+%/, /\$[\d,]+/, /study\s+(shows|found)/i, /according to/i, /data\s+(shows|reveals)/i, /\d+x\s+(faster|better|more)/i, /(million|billion|trillion)/i];
+        for (const p of statPatterns)
+            if (p.test(content))
+                stats++;
+        if (stats >= 2)
+            result.passed.push("Original statistics/data (citation magnet)");
+        // Direct answers
+        const ansPatterns = [/is defined as/i, /refers to/i, /means that/i, /the answer is/i, /in short,/i, /simply put,/i, /<dfn/i];
+        if (ansPatterns.some(p => p.test(content)))
+            result.passed.push("Direct answer patterns (LLM-friendly)");
+    }
+    catch (e) {
+        result.issues.push(`Error: ${e.message}`);
+    }
+    const total = result.passed.length + result.issues.length;
+    result.score = total > 0 ? (result.passed.length / total) * 100 : 0;
+    return result;
+}
+export async function runGeoChecker(projectPath = ".") {
+    const root = path.resolve(projectPath);
+    let report = `============================================================\n`;
+    report += `  GEO CHECKER - AI Citation Readiness Audit\n`;
+    report += `============================================================\n`;
+    const pages = await findWebPages(root);
+    if (pages.length === 0) {
+        return { passed: true, report: report + "\n[!] No public web pages found.\n" };
+    }
+    report += `Found ${pages.length} public pages to analyze\n\n`;
+    const results = [];
+    for (const page of pages) {
+        results.push(await checkGeoPage(page));
+    }
+    let sumScore = 0;
+    for (const r of results) {
+        const score = Math.round(r.score);
+        sumScore += score;
+        const status = score >= 60 ? "[OK]" : "[!]";
+        report += `${status} ${r.file}: ${score}%\n`;
+        if (r.issues.length > 0 && score < 60) {
+            for (const issue of r.issues.slice(0, 2))
+                report += `    - ${issue}\n`;
+        }
+    }
+    const avgScore = Math.round(results.length > 0 ? sumScore / results.length : 0);
+    report += `\n============================================================\n`;
+    report += `AVERAGE GEO SCORE: ${avgScore}%\n`;
+    report += `============================================================\n`;
+    if (avgScore >= 80)
+        report += "[OK] Excellent - Content well-optimized for AI citations\n";
+    else if (avgScore >= 60)
+        report += "[OK] Good - Some improvements recommended\n";
+    else if (avgScore >= 40)
+        report += "[!] Needs work - Add structured elements\n";
+    else
+        report += "[X] Poor - Content needs GEO optimization\n";
+    return { passed: avgScore >= 60, report };
+}