faf-cli 4.3.0 → 4.3.1

package/scripts/evaluate-family-member.ts

@@ -0,0 +1,300 @@
+#!/usr/bin/env ts-node
+/**
+ * FAF Integration Quality Evaluation
+ *
+ * Evaluates tools for FAF integration based on:
+ * - Developer adoption (weekly downloads)
+ * - Security & reliability
+ * - Active maintenance
+ * - MCP server availability
+ * - .faf context contribution (slots filled)
+ *
+ * Championship Standard: 85% minimum quality score required
+ */
+
+import https from 'https';
+import { promisify } from 'util';
+
+const get = promisify(https.get);
+
+interface IntegrationQuality {
+  integration: string;
+  weeklyDownloads: number;
+  lastPublish: string;
+  hasVulnerabilities: boolean;
+  qualityScore: number;
+  mcpServers: string[];
+  contextSlotsFilled: number;
+  totalScore: number;
+  tier: 'trophy' | 'gold' | 'silver' | 'bronze' | 'yellow' | 'red';
+  approved: boolean;
+  reasoning: string;
+}
+
+// Minimum quality thresholds for FAF integration approval
+const INTEGRATION_REQUIREMENTS = {
+  weeklyDownloads: 100_000,      // 100k+ shows real developer adoption
+  qualityScore: 85,              // Bronze tier minimum (Championship standard)
+  maxDaysSincePublish: 90,       // Active maintenance within 3 months
+  minContextSlots: 2,            // Must contribute to 2+ .faf context fields
+};
+
+async function fetchJSON(url: string): Promise<any> {
+  return new Promise((resolve, reject) => {
+    https.get(url, (res) => {
+      let data = '';
+      res.on('data', (chunk) => data += chunk);
+      res.on('end', () => {
+        try {
+          resolve(JSON.parse(data));
+        } catch (e) {
+          reject(e);
+        }
+      });
+    }).on('error', reject);
+  });
+}
+
+async function getWeeklyDownloads(pkg: string): Promise<number> {
+  try {
+    const url = `https://api.npmjs.org/downloads/point/last-week/${pkg}`;
+    const data = await fetchJSON(url);
+    return data.downloads || 0;
+  } catch {
+    return 0;
+  }
+}
+
+async function getPackageInfo(pkg: string): Promise<any> {
+  const url = `https://registry.npmjs.com/${pkg}`;
+  return await fetchJSON(url);
+}
+
+function getDaysSincePublish(publishDate: string): number {
+  const now = new Date();
+  const published = new Date(publishDate);
+  const diffTime = Math.abs(now.getTime() - published.getTime());
+  const diffDays = Math.ceil(diffTime / (1000 * 60 * 60 * 24));
+  return diffDays;
+}
+
+function calculateMaintenanceScore(info: any): number {
+  const latestVersion = info['dist-tags']?.latest;
+  if (!latestVersion) return 0;
+
+  const publishDate = info.time?.[latestVersion];
+  if (!publishDate) return 0;
+
+  const daysSince = getDaysSincePublish(publishDate);
+
+  // Scoring:
+  // < 30 days = 100
+  // 30-60 days = 90
+  // 60-90 days = 85
+  // > 90 days = declining score
+  if (daysSince < 30) return 100;
+  if (daysSince < 60) return 90;
+  if (daysSince < 90) return 85;
+  return Math.max(0, 85 - (daysSince - 90));
+}
+
+// MCP servers available for each integration
+const INTEGRATION_MCP_SERVERS: Record<string, string[]> = {
+  'react': ['@react-mcp/server', 'react-mcp-tools'],
+  'next': ['@vercel/mcp-server', '@nextjs/mcp-tools'],
+  'svelte': ['@sveltejs/mcp', 'svelte-kit-mcp'],
+  'vue': ['@vue/mcp-server', 'vue-mcp-tools'],
+  'vite': ['vite-mcp-server'],
+  'typescript': ['typescript-language-server', '@typescript/mcp-tools'],
+  'n8n': ['n8n-mcp', 'n8n-nodes-mcp'],
+  '@supabase/supabase-js': ['@supabase/mcp-server-supabase'],
+  'prisma': ['@prisma/mcp-server'],
+  '@vercel/node': ['@vercel/mcp-server'],
+  'astro': ['@astro/mcp-server'],
+  'zod': ['zod-mcp-validator'],
+  'axios': ['http-mcp-tools'],
+};
+
+// .faf context slots populated by each integration
+const CONTEXT_CONTRIBUTION: Record<string, string[]> = {
+  'react': ['frontend', 'ui_library', 'state_management'],
+  'next': ['frontend', 'backend', 'runtime', 'hosting', 'api_type'],
+  'svelte': ['frontend', 'ui_library', 'state_management'],
+  'vue': ['frontend', 'ui_library', 'state_management'],
+  'vite': ['build', 'package_manager'],
+  'typescript': ['main_language', 'type_system'],
+  'n8n': ['automation_platform', 'workflow_engine', 'integration_layer', 'api_orchestration'],
+  '@supabase/supabase-js': ['database', 'backend', 'api_type'],
+  'prisma': ['database', 'orm'],
+  '@vercel/node': ['runtime', 'hosting'],
+  'astro': ['frontend', 'build', 'hosting'],
+  'zod': ['validation', 'type_system'],
+  'axios': ['http_client', 'api_communication'],
+  'dotenv': ['configuration', 'environment'],
+  'chalk': ['terminal_ui', 'output_formatting'],
+  'yargs': ['cli_framework', 'argument_parsing'],
+};
+
+function getTier(score: number): IntegrationQuality['tier'] {
+  if (score >= 99) return 'trophy';
+  if (score >= 95) return 'gold';
+  if (score >= 90) return 'silver';
+  if (score >= 85) return 'bronze';
+  if (score >= 70) return 'yellow';
+  return 'red';
+}
+
+function getEmoji(tier: IntegrationQuality['tier']): string {
+  const emojis = {
+    trophy: '🏆',
+    gold: '🥇',
+    silver: '🥈',
+    bronze: '🥉',
+    yellow: '🟡',
+    red: '🔴'
+  };
+  return emojis[tier];
+}
+
+async function evaluateIntegration(pkg: string): Promise<IntegrationQuality> {
+  console.log(`\n🔗 Evaluating Integration: ${pkg}...`);
+
+  const weeklyDownloads = await getWeeklyDownloads(pkg);
+  const info = await getPackageInfo(pkg);
+  const maintainedScore = calculateMaintenanceScore(info);
+  const mcpServers = INTEGRATION_MCP_SERVERS[pkg] || [];
+  const contextSlotsFilled = CONTEXT_CONTRIBUTION[pkg]?.length || 0;
+
+  // Calculate total score
+  let totalScore = 0;
+  const scores = {
+    downloads: 0,
+    maintenance: 0,
+    mcp: 0,
+    slots: 0
+  };
+
+  // Downloads (30 points max)
+  if (weeklyDownloads >= 50_000_000) scores.downloads = 30; // 50M+
+  else if (weeklyDownloads >= 10_000_000) scores.downloads = 28; // 10M+
+  else if (weeklyDownloads >= 1_000_000) scores.downloads = 25; // 1M+
+  else if (weeklyDownloads >= 100_000) scores.downloads = 20; // 100k+
+  else scores.downloads = Math.floor((weeklyDownloads / 100_000) * 20);
+
+  // Maintenance (30 points max)
+  scores.maintenance = Math.floor(maintainedScore * 0.3);
+
+  // MCP availability (20 points max)
+  scores.mcp = mcpServers.length > 0 ? 20 : 0;
+
+  // Context contribution (20 points max)
+  scores.slots = Math.min(20, contextSlotsFilled * 5);
+
+  totalScore = scores.downloads + scores.maintenance + scores.mcp + scores.slots;
+
+  const tier = getTier(totalScore);
+  const approved = totalScore >= INTEGRATION_REQUIREMENTS.qualityScore;
+
+  const latestVersion = info['dist-tags']?.latest;
+  const publishDate = info.time?.[latestVersion] || 'unknown';
+
+  const reasoning = [
+    `Adoption: ${weeklyDownloads.toLocaleString()} developers/week (${scores.downloads}/30 pts)`,
+    `Quality: ${maintainedScore}% maintenance score (${scores.maintenance}/30 pts)`,
+    `MCP Integration: ${mcpServers.length} server(s) available (${scores.mcp}/20 pts)`,
+    `Context: Fills ${contextSlotsFilled} .faf slots (${scores.slots}/20 pts)`,
+    `Updated: ${publishDate.split('T')[0]}`
+  ].join('\n  ');
+
+  console.log(`  ${getEmoji(tier)} Quality Score: ${totalScore}/100 (${tier})`);
+  console.log(`  ${approved ? '✅ APPROVED' : '❌ NOT APPROVED'}`);
+
+  return {
+    integration: pkg,
+    weeklyDownloads,
+    lastPublish: publishDate,
+    hasVulnerabilities: false, // TODO: Check npm audit
+    qualityScore: maintainedScore,
+    mcpServers,
+    contextSlotsFilled,
+    totalScore,
+    tier,
+    approved,
+    reasoning
+  };
+}
+
+async function main() {
+  console.log('🔗 FAF Integration Quality Assessment\n');
+  console.log('Championship Standard: 85+ quality score required\n');
+  console.log('='.repeat(60));
+
+  const candidates = [
+    // Phase 1: Core tooling
+    'zod',
+    'axios',
+    'dotenv',
+    'chalk',
+    'yargs',
+
+    // Phase 2: Top frameworks
+    'react',
+    'next',
+    'svelte',
+    'vue',
+    'vite',
+
+    // Phase 3: Full coverage
+    'typescript',
+    '@supabase/supabase-js',
+    'prisma',
+    '@vercel/node',
+    'astro'
+  ];
+
+  const evaluations: IntegrationQuality[] = [];
+
+  for (const pkg of candidates) {
+    try {
+      const evaluation = await evaluateIntegration(pkg);
+      evaluations.push(evaluation);
+      await new Promise(resolve => setTimeout(resolve, 200)); // Rate limit
+    } catch (error) {
+      console.error(`❌ Failed to evaluate ${pkg}:`, error);
+    }
+  }
+
+  console.log('\n' + '='.repeat(60));
+  console.log('\n📊 INTEGRATION APPROVAL SUMMARY\n');
+
+  const approved = evaluations.filter(e => e.approved);
+  const needsWork = evaluations.filter(e => !e.approved);
+
+  console.log(`✅ APPROVED INTEGRATIONS: ${approved.length}/${evaluations.length}`);
+  approved.forEach(e => {
+    console.log(`   ${getEmoji(e.tier)} ${e.integration} - ${e.totalScore}/100 quality score`);
+  });
+
+  console.log(`\n⚠️  NEEDS IMPROVEMENT: ${needsWork.length}/${evaluations.length}`);
+  needsWork.forEach(e => {
+    console.log(`   ${getEmoji(e.tier)} ${e.integration} - ${e.totalScore}/100 (below 85% threshold)`);
+  });
+
+  console.log('\n🔗 RECOMMENDED INTEGRATIONS:\n');
+  console.log('Add these to package.json to enable smart detection:\n');
+  console.log('"dependencies": {');
+  approved.forEach((e, i) => {
+    const comma = i < approved.length - 1 ? ',' : '';
+    console.log(`  "${e.integration}": "latest"${comma}  // ${e.contextSlotsFilled} context slots`);
+  });
+  console.log('}');
+
+  console.log('\n🏁 Integration assessment complete!');
+}
+
+// Run if called directly
+if (require.main === module) {
+  main().catch(console.error);
+}
+
+export { evaluateIntegration, type IntegrationQuality };

package/scripts/generate-docs.ts

@@ -0,0 +1,358 @@
+#!/usr/bin/env ts-node
+
+/**
+ * 📚 Documentation Generator - F1-Inspired Championship Docs
+ * Auto-generates command reference from FAF_INDEX
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { FAF_INDEX } from '../src/commands/index';
+import { FAF_COLORS, FAF_ICONS } from '../src/utils/championship-style';
+
+const DOCS_DIR = path.join(__dirname, '..', 'docs-site');
+
+interface GenerationStats {
+  commandPages: number;
+  conceptPages: number;
+  totalPages: number;
+  errors: string[];
+}
+
+/**
+ * Main documentation generation function
+ */
+async function generateDocs(): Promise<void> {
+  console.log(`${FAF_COLORS.fafCyan('🏗️ Generating FAF CLI Documentation...')}`);
+  
+  const stats: GenerationStats = {
+    commandPages: 0,
+    conceptPages: 0,
+    totalPages: 0,
+    errors: []
+  };
+
+  try {
+    // Ensure docs directory exists
+    await ensureDocsDirectory();
+    
+    // Generate command reference pages
+    await generateCommandPages(stats);
+    
+    // Generate concept pages
+    await generateConceptPages(stats);
+    
+    // Generate index pages
+    await generateIndexPages(stats);
+    
+    // Generate navigation config
+    await generateNavigation();
+    
+    // Show results
+    console.log();
+    console.log(`${FAF_COLORS.fafGreen('✅ Documentation Generation Complete!')}`);
+    console.log(`${FAF_COLORS.fafCyan('├─')} Command pages: ${stats.commandPages}`);
+    console.log(`${FAF_COLORS.fafCyan('├─')} Concept pages: ${stats.conceptPages}`);
+    console.log(`${FAF_COLORS.fafCyan('├─')} Total pages: ${stats.totalPages}`);
+    
+    if (stats.errors.length > 0) {
+      console.log(`${FAF_COLORS.fafOrange('└─')} Errors: ${stats.errors.length}`);
+      stats.errors.forEach(error => {
+        console.log(`   ${FAF_COLORS.fafOrange('⚠️')} ${error}`);
+      });
+    } else {
+      console.log(`${FAF_COLORS.fafGreen('└─')} No errors! 🏆`);
+    }
+    
+  } catch (error) {
+    console.error(`${FAF_COLORS.fafOrange('❌ Generation failed:')} ${error}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Ensure docs directory structure exists
+ */
+async function ensureDocsDirectory(): Promise<void> {
+  const dirs = [
+    path.join(DOCS_DIR, 'pages'),
+    path.join(DOCS_DIR, 'pages', 'commands'),
+    path.join(DOCS_DIR, 'pages', 'concepts'),
+    path.join(DOCS_DIR, 'pages', 'examples'),
+    path.join(DOCS_DIR, 'components'),
+    path.join(DOCS_DIR, 'public', 'screenshots'),
+    path.join(DOCS_DIR, 'public', 'examples')
+  ];
+  
+  for (const dir of dirs) {
+    await fs.mkdir(dir, { recursive: true });
+  }
+}
+
+/**
+ * Generate command reference pages
+ */
+async function generateCommandPages(stats: GenerationStats): Promise<void> {
+  const commands = Object.entries(FAF_INDEX).filter(([_, entry]) => entry.type === 'command');
+  
+  for (const [key, entry] of commands) {
+    try {
+      const content = generateCommandPageContent(key, entry);
+      const filePath = path.join(DOCS_DIR, 'pages', 'commands', `${key}.mdx`);
+      await fs.writeFile(filePath, content);
+      stats.commandPages++;
+      stats.totalPages++;
+    } catch (error) {
+      stats.errors.push(`Command ${key}: ${error}`);
+    }
+  }
+}
+
+/**
+ * Generate concept pages
+ */
+async function generateConceptPages(stats: GenerationStats): Promise<void> {
+  const concepts = Object.entries(FAF_INDEX).filter(([_, entry]) => entry.type === 'concept');
+  
+  for (const [key, entry] of concepts) {
+    try {
+      const content = generateConceptPageContent(key, entry);
+      const filePath = path.join(DOCS_DIR, 'pages', 'concepts', `${key}.mdx`);
+      await fs.writeFile(filePath, content);
+      stats.conceptPages++;
+      stats.totalPages++;
+    } catch (error) {
+      stats.errors.push(`Concept ${key}: ${error}`);
+    }
+  }
+}
+
+/**
+ * Generate index pages
+ */
+async function generateIndexPages(stats: GenerationStats): Promise<void> {
+  // Commands index
+  const commandsIndex = generateCommandsIndexContent();
+  await fs.writeFile(
+    path.join(DOCS_DIR, 'pages', 'commands', 'index.mdx'), 
+    commandsIndex
+  );
+  
+  // Concepts index
+  const conceptsIndex = generateConceptsIndexContent();
+  await fs.writeFile(
+    path.join(DOCS_DIR, 'pages', 'concepts', 'index.mdx'), 
+    conceptsIndex
+  );
+  
+  // Main index
+  const mainIndex = generateMainIndexContent();
+  await fs.writeFile(
+    path.join(DOCS_DIR, 'pages', 'index.mdx'), 
+    mainIndex
+  );
+  
+  stats.totalPages += 3;
+}
+
+/**
+ * Generate command page content
+ */
+function generateCommandPageContent(key: string, entry: any): string {
+  return `# ${key}
+
+${entry.description}
+
+## Usage
+
+\`\`\`bash
+${entry.usage || `faf ${key}`}
+\`\`\`
+
+${entry.examples ? `
+## Examples
+
+${entry.examples.map((example: string) => `\`\`\`bash
+${example}
+\`\`\`\n`).join('')}
+` : ''}
+
+${entry.related ? `
+## Related Commands
+
+${entry.related.map((rel: string) => `- [${rel}](./${rel})`).join('\n')}
+` : ''}
+
+## Category
+
+**${entry.category}** - ${getCategoryDescription(entry.category)}
+`;
+}
+
+/**
+ * Generate concept page content
+ */
+function generateConceptPageContent(key: string, entry: any): string {
+  return `# ${key}
+
+${entry.description}
+
+${entry.related ? `
+## Related
+
+${entry.related.map((rel: string) => `- [${rel}](../${getRelatedType(rel)}/${rel})`).join('\n')}
+` : ''}
+
+## Category
+
+**${entry.category}** - ${getCategoryDescription(entry.category)}
+`;
+}
+
+/**
+ * Generate commands index content
+ */
+function generateCommandsIndexContent(): string {
+  const commands = Object.entries(FAF_INDEX).filter(([_, entry]) => entry.type === 'command');
+  
+  return `# Commands Reference
+
+Complete reference for all FAF CLI commands.
+
+## Core Commands
+
+${commands.filter(([_, entry]) => entry.category === 'core').map(([key, entry]) => 
+  `### [${key}](./${key})
+${entry.description}
+\`\`\`bash
+${entry.usage || `faf ${key}`}
+\`\`\`
+`).join('\n')}
+
+## All Commands
+
+${commands.map(([key, entry]) => `- **[${key}](./${key})** - ${entry.description}`).join('\n')}
+`;
+}
+
+/**
+ * Generate concepts index content
+ */
+function generateConceptsIndexContent(): string {
+  const concepts = Object.entries(FAF_INDEX).filter(([_, entry]) => entry.type === 'concept');
+  
+  return `# Core Concepts
+
+Understanding the fundamentals of FAF CLI and AI context management.
+
+${concepts.map(([key, entry]) => `## [${key}](./${key})
+
+${entry.description}
+`).join('\n')}
+`;
+}
+
+/**
+ * Generate main index content
+ */
+function generateMainIndexContent(): string {
+  return `---
+title: FAF CLI Documentation
+---
+
+# 🏎️ FAF CLI Documentation
+
+Welcome to the **Championship-grade AI context management** documentation!
+
+## Quick Start
+
+\`\`\`bash
+# Install FAF CLI
+npm install -g @faf/cli
+
+# Initialize your project
+faf init
+
+# Check your AI context score
+faf score
+
+# Build trust with AI
+faf trust
+\`\`\`
+
+## What is FAF?
+
+FAF (Foundational AI-Context Format) transforms developer psychology from **hope-driven** to **trust-driven** AI development. In 30 seconds, FAF replaces 20 minutes of questions.
+
+## Core Features
+
+- 🚀 **Universal AI Context** - Works with Claude, ChatGPT, Gemini
+- ⚡ **F1-Inspired Performance** - Championship speed (<40ms status)
+- 🎯 **Trust-Driven Development** - Eliminate AI anxiety
+- 💎 **Technical Credit System** - Psychology revolution vs debt
+
+## Documentation Sections
+
+- **[Commands](/commands)** - Complete CLI reference
+- **[Concepts](/concepts)** - Core concepts and principles
+- **[Examples](/examples)** - Real-world usage patterns
+
+---
+
+**🏁 Making AI development better for everyone!**
+`;
+}
+
+/**
+ * Generate navigation configuration
+ */
+async function generateNavigation(): Promise<void> {
+  const navConfig = `export default {
+  logo: <span>🏎️ FAF CLI</span>,
+  project: {
+    link: 'https://github.com/faf-org/cli'
+  },
+  docsRepositoryBase: 'https://github.com/faf-org/cli/tree/main/docs',
+  sidebar: {
+    defaultMenuCollapseLevel: 1
+  },
+  footer: {
+    text: '🏁 Making AI development better for everyone!'
+  }
+}`;
+  
+  await fs.writeFile(
+    path.join(DOCS_DIR, 'theme.config.tsx'), 
+    navConfig
+  );
+}
+
+/**
+ * Helper functions
+ */
+function getCategoryDescription(category: string): string {
+  const descriptions: Record<string, string> = {
+    core: 'Essential FAF functionality',
+    ai: 'AI integration and compatibility',
+    trust: 'Trust and confidence management',
+    utilities: 'Helper tools and utilities',
+    improvement: 'Context improvement tools',
+    psychology: 'Developer psychology enhancement',
+    concepts: 'Fundamental concepts',
+    discovery: 'Technology discovery and analysis'
+  };
+  return descriptions[category] || 'FAF functionality';
+}
+
+function getRelatedType(key: string): string {
+  const entry = FAF_INDEX[key as keyof typeof FAF_INDEX];
+  if (!entry) return 'commands';
+  return entry.type === 'command' ? 'commands' : 'concepts';
+}
+
+// Run the generator
+if (require.main === module) {
+  generateDocs().catch(console.error);
+}
+
+export { generateDocs };