about.astro

---
import BaseLayout from '../layouts/BaseLayout.astro';
import Navigation from '../components/Navigation.astro';
import Footer from '../components/Footer.astro';
import PageHeader from '../components/PageHeader.astro';
import GitHubContributors from '../components/GitHubContributors';
import fs from 'fs';
import path from 'path';

// Types
type Contributor = {
  login: string;
  avatar_url: string;
  html_url: string;
  contributions: number;
  name?: string;
};

type Maintainer = {
  login: string;
  avatar_url: string;
  html_url: string;
  name?: string;
  bio?: string;
  contributions?: number;
};

type CacheData = {
  contributors: Contributor[];
  maintainer: Maintainer | null;
  carreauContributions: number | undefined;
  timestamp: number;
};

// Define isDev first before using it
const isDev = import.meta.env.DEV;

// GitHub token from environment variable
// In Astro, use import.meta.env for environment variables
// Set GITHUB_TOKEN in .env file or as environment variable
// Try both import.meta.env and process.env as fallback
// Trim whitespace and newlines in case .env file has extra characters
let GITHUB_TOKEN = import.meta.env.GITHUB_TOKEN || (typeof process !== 'undefined' && process.env ? process.env.GITHUB_TOKEN : undefined);
if (GITHUB_TOKEN) {
  // Aggressively clean the token:
  // 1. Remove quotes if present (some .env files have quotes)
  // 2. Trim all whitespace from start and end
  // 3. Remove all newlines, carriage returns, and tabs
  let cleaned = GITHUB_TOKEN.toString();
  // Remove surrounding quotes
  if ((cleaned.startsWith('"') && cleaned.endsWith('"')) || 
      (cleaned.startsWith("'") && cleaned.endsWith("'"))) {
    cleaned = cleaned.slice(1, -1);
  }
  // Remove all whitespace and control characters
  cleaned = cleaned.replace(/^\s+|\s+$/g, '').replace(/[\r\n\t\s]/g, '');
  GITHUB_TOKEN = cleaned;
}
const CACHE_DIR = path.join(process.cwd(), 'node_modules', '.cache');
const CACHE_FILE = path.join(CACHE_DIR, 'github-cache.json');
const CACHE_DURATION = 60 * 60 * 1000; // 1 hour in milliseconds

// Log GitHub token status
if (isDev) {
  console.log('\n[GitHub API]', GITHUB_TOKEN ? '✓ Using GitHub token (5000 req/hour)' : '⚠ No GitHub token (60 req/hour limit)');
}

// Helper function to create fetch headers
function getFetchHeaders() {
  const headers: HeadersInit = {
    'Accept': 'application/vnd.github.v3+json',
  };
  if (GITHUB_TOKEN) {
    headers['Authorization'] = `Bearer ${GITHUB_TOKEN.trim()}`;
  }
  return headers;
}

// Check GitHub API rate limits at build start
async function checkRateLimit() {
  try {
    const response = await fetch('https://api.github.com/rate_limit', {
      headers: getFetchHeaders(),
    });
    if (response.ok) {
      const data = await response.json();
      const core = data.resources?.core || {};
      const remaining = core.remaining ?? 0;
      const limit = core.limit ?? 0;
      const resetTime = core.reset ? new Date(core.reset * 1000).toLocaleString() : 'unknown';
      console.log(`[GitHub API] Rate limit: ${remaining}/${limit} requests remaining (resets at ${resetTime})`);
      if (remaining === 0) {
        console.error('[GitHub API] ⚠ WARNING: No API requests remaining! Build may fail.');
      }
      return { remaining, limit, resetTime };
    } else {
      const errorText = await response.text();
      console.error(`[GitHub API] ✗ Failed to check rate limit: ${response.status} ${response.statusText}`);
      console.error(`[GitHub API] Response: ${errorText}`);
    }
  } catch (error) {
    console.error('[GitHub API] ✗ Error checking rate limit:', error);
    if (error instanceof Error) {
      console.error('[GitHub API] Error details:', error.message);
    }
  }
  return null;
}

// Check rate limits at build start
await checkRateLimit();

// Helper function to load cache
function loadCache(): CacheData | null {
  if (!isDev || !fs.existsSync(CACHE_FILE)) {
    if (isDev && !fs.existsSync(CACHE_FILE)) {
      console.log('[Cache] No cache file found, will fetch from API');
    }
    return null;
  }
  
  try {
    const cacheContent = fs.readFileSync(CACHE_FILE, 'utf-8');
    const cache: CacheData = JSON.parse(cacheContent);
    const now = Date.now();
    const age = now - cache.timestamp;
    const ageMinutes = Math.floor(age / 60000);
    
    // Validate cache data structure
    if (!cache.contributors || !Array.isArray(cache.contributors)) {
      console.log(`[Cache] ⚠ Cache data is invalid (missing contributors array), fetching fresh data`);
      return null;
    }
    
    const hasValidContributors = cache.contributors.length > 0;
    const hasValidMaintainer = cache.maintainer !== null && 
                                cache.maintainer !== undefined && 
                                typeof cache.maintainer === 'object' &&
                                cache.maintainer.login !== undefined;
    
    // Check if cache is still valid (less than 1 hour old)
    if (age < CACHE_DURATION) {
      if (hasValidContributors || hasValidMaintainer) {
        console.log(`[Cache] ✓ Using cached data (${ageMinutes} minutes old)`);
        if (isDev) {
          console.log(`[Cache]   - Contributors: ${cache.contributors.length}`);
          console.log(`[Cache]   - Maintainer: ${hasValidMaintainer ? 'Yes' : 'No'}`);
        }
        return cache;
      } else {
        console.log(`[Cache] ⚠ Cache data is invalid (empty contributors and no maintainer), fetching fresh data`);
        // Delete invalid cache
        try {
          fs.unlinkSync(CACHE_FILE);
          console.log(`[Cache] Deleted invalid cache file`);
        } catch (error) {
          // Ignore deletion errors
        }
        return null;
      }
    } else {
      console.log(`[Cache] ⚠ Cache expired (${ageMinutes} minutes old), fetching fresh data`);
    }
  } catch (error) {
    console.error('[Cache] Failed to load cache:', error);
  }
  
  return null;
}

// Helper function to save cache
function saveCache(data: CacheData) {
  if (!isDev) {
    return;
  }
  
  try {
    // Ensure cache directory exists
    if (!fs.existsSync(CACHE_DIR)) {
      fs.mkdirSync(CACHE_DIR, { recursive: true });
    }
    
    fs.writeFileSync(CACHE_FILE, JSON.stringify(data, null, 2), 'utf-8');
    console.log('[Cache] ✓ Saved data to cache');
  } catch (error) {
    console.error('[Cache] Failed to save cache:', error);
  }
}

// Try to load from cache first (dev mode only)
let cachedData = loadCache();
let contributors: Contributor[] = [];
let carreauContributions: number | undefined = undefined;
let contributorsError = false;
let maintainer: Maintainer | null = null;
let maintainerError = false;

if (cachedData) {
  // Use cached data (already validated in loadCache)
  contributors = cachedData.contributors || [];
  maintainer = cachedData.maintainer || null;
  carreauContributions = cachedData.carreauContributions;
  
  if (isDev) {
    console.log('[Static Data] 📦 Using static contributor/maintainer data from last build (cached)');
  } else {
    console.log('[Static Data] 📦 Using static contributor/maintainer data from last build');
  }
  
  // Double-check we have valid data
  if (contributors.length === 0 && !maintainer) {
    if (isDev) {
      console.log('[Cache] ⚠ Cached data is empty, fetching fresh data');
    }
    cachedData = null; // Force fresh fetch
  }
}

if (!cachedData) {
  // Fetch fresh data
  if (isDev) {
    console.log('[GitHub API] 🔄 Fetching live contributor data from GitHub API...');
  } else {
    console.log('[GitHub API] 🔄 Fetching live contributor data from GitHub API (build time)...');
  }
  
  try {
    const response = await fetch('https://api.github.com/repos/ipython/ipython/contributors?per_page=30', {
      headers: getFetchHeaders(),
    });
    
    // Check rate limit headers
    if (isDev) {
      const remaining = response.headers.get('x-ratelimit-remaining');
      const limit = response.headers.get('x-ratelimit-limit');
      const resetTime = response.headers.get('x-ratelimit-reset');
      if (remaining && limit) {
        const resetDate = resetTime ? new Date(parseInt(resetTime) * 1000).toLocaleTimeString() : 'unknown';
        console.log(`[GitHub API] Rate limit: ${remaining}/${limit} remaining (resets at ${resetDate})`);
      }
    }
    
    if (response.ok) {
      const contributorsData = await response.json();
      
      // Check if response is empty or invalid
      if (!Array.isArray(contributorsData) || contributorsData.length === 0) {
        const errorMsg = '[GitHub API] ✗ Contributors response is empty or invalid';
        console.error(errorMsg);
        console.error('[GitHub API] Response data:', JSON.stringify(contributorsData, null, 2));
        contributorsError = true;
        if (!isDev) {
          throw new Error(errorMsg);
        }
      } else {
        // Find Carreau's contribution count
        const carreauData = contributorsData.find((c: Contributor) => c.login === 'Carreau');
        if (carreauData) {
          carreauContributions = carreauData.contributions;
        }
        
        // Fetch user details for each contributor to get their names
        // Limit to first 20 to avoid too many API calls
        if (isDev) {
          console.log(`[GitHub API] Fetching user details for ${Math.min(contributorsData.length, 20)} contributors...`);
        }
        
        const contributorsWithNames = await Promise.all(
          contributorsData.slice(0, 20).map(async (contributor: Contributor) => {
            try {
              const userResponse = await fetch(`https://api.github.com/users/${contributor.login}`, {
                headers: getFetchHeaders(),
              });
              if (userResponse.ok) {
                const userData = await userResponse.json();
                return {
                  ...contributor,
                  name: userData.name || contributor.login,
                };
              } else {
                const errorText = await userResponse.text();
                console.error(`[GitHub API] Failed to fetch user ${contributor.login}: ${userResponse.status} ${userResponse.statusText}`);
                console.error(`[GitHub API] Response: ${errorText}`);
              }
            } catch (error) {
              console.error(`[GitHub API] Failed to fetch user ${contributor.login}:`, error);
              if (error instanceof Error) {
                console.error(`[GitHub API] Error details: ${error.message}`);
              }
            }
            return {
              ...contributor,
              name: contributor.login,
            };
          })
        );
        
        contributors = contributorsWithNames;
        if (isDev) {
          console.log(`[GitHub API] ✓ Live data: Fetched ${contributors.length} contributors`);
        } else {
          console.log(`[GitHub API] ✓ Live data (build time): Fetched ${contributors.length} contributors`);
        }
      }
    } else {
      const errorText = await response.text();
      let errorMessage = `Failed to fetch contributors: ${response.status} ${response.statusText}`;
      try {
        const errorJson = JSON.parse(errorText);
        errorMessage = errorJson.message || errorMessage;
        if (errorJson.documentation_url) {
          errorMessage += `\n  Documentation: ${errorJson.documentation_url}`;
        }
      } catch (e) {
        // Not JSON, use raw text
      }
      
      contributorsError = true;
      console.error(`[GitHub API] ✗ ${errorMessage}`);
      console.error(`[GitHub API] Response: ${errorText}`);
      
      if (response.status === 403) {
        const retryAfter = response.headers.get('retry-after');
        if (retryAfter) {
          console.error(`[GitHub API] Retry after ${retryAfter} seconds`);
        }
        const xRateLimitRemaining = response.headers.get('x-ratelimit-remaining');
        if (xRateLimitRemaining === '0') {
          console.error('[GitHub API] Rate limit exhausted!');
        }
      } else if (response.status === 401) {
        console.error(`[GitHub API] Check if token is valid and has correct permissions`);
      }
      
      if (!isDev) {
        throw new Error(errorMessage);
      }
    }
  } catch (error) {
    contributorsError = true;
    console.error('[GitHub API] ✗ Failed to fetch contributors:', error);
    if (error instanceof Error) {
      console.error('[GitHub API] Error details:', error.message);
      console.error('[GitHub API] Stack:', error.stack);
    }
    if (!isDev) {
      throw error;
    }
  }

  // Fetch maintainer (Carreau)
  if (isDev) {
    console.log('[GitHub API] Fetching maintainer (Carreau)...');
  }
  
  try {
    if (isDev) {
      console.log('[GitHub API] 🔄 Fetching live maintainer data from GitHub API...');
    } else {
      console.log('[GitHub API] 🔄 Fetching live maintainer data from GitHub API (build time)...');
    }
    const maintainerResponse = await fetch('https://api.github.com/users/Carreau', {
      headers: getFetchHeaders(),
    });
    
    if (maintainerResponse.ok) {
      const maintainerData = await maintainerResponse.json();
      
      if (!maintainerData || !maintainerData.login) {
        const errorMsg = '[GitHub API] ✗ Maintainer response is empty or invalid';
        console.error(errorMsg);
        console.error('[GitHub API] Response data:', JSON.stringify(maintainerData, null, 2));
        maintainerError = true;
        if (!isDev) {
          throw new Error(errorMsg);
        }
      } else {
        maintainer = {
          login: maintainerData.login,
          avatar_url: maintainerData.avatar_url,
          html_url: maintainerData.html_url,
          name: maintainerData.name || maintainerData.login,
          bio: maintainerData.bio,
          contributions: carreauContributions,
        };
        if (isDev) {
          console.log('[GitHub API] ✓ Live data: Fetched maintainer info');
        } else {
          console.log('[GitHub API] ✓ Live data (build time): Fetched maintainer info');
        }
      }
    } else {
      const errorText = await maintainerResponse.text();
      let errorMessage = `Failed to fetch maintainer: ${maintainerResponse.status} ${maintainerResponse.statusText}`;
      try {
        const errorJson = JSON.parse(errorText);
        errorMessage = errorJson.message || errorMessage;
        if (errorJson.documentation_url) {
          errorMessage += `\n  Documentation: ${errorJson.documentation_url}`;
        }
      } catch (e) {
        // Not JSON, use raw text
      }
      
      maintainerError = true;
      console.error(`[GitHub API] ✗ ${errorMessage}`);
      console.error(`[GitHub API] Response: ${errorText}`);
      
      if (maintainerResponse.status === 403) {
        const retryAfter = maintainerResponse.headers.get('retry-after');
        if (retryAfter) {
          console.error(`[GitHub API] Retry after ${retryAfter} seconds`);
        }
      } else if (maintainerResponse.status === 401) {
        console.error(`[GitHub API] Check if token is valid and has correct permissions`);
      }
      
      if (!isDev) {
        throw new Error(errorMessage);
      }
    }
  } catch (error) {
    maintainerError = true;
    console.error('[GitHub API] ✗ Failed to fetch maintainer:', error);
    if (error instanceof Error) {
      console.error('[GitHub API] Error details:', error.message);
      console.error('[GitHub API] Stack:', error.stack);
    }
    if (!isDev) {
      throw error;
    }
  }

  // Save to cache (dev mode only) - only if we have valid data
  if (isDev && !contributorsError && !maintainerError) {
    if (contributors.length > 0 || maintainer) {
      saveCache({
        contributors,
        maintainer,
        carreauContributions,
        timestamp: Date.now(),
      });
    } else {
      console.log('[Cache] ⚠ Not saving cache - no valid data to cache');
    }
  } else if (isDev && (contributorsError || maintainerError)) {
    console.log('[Cache] ⚠ Not saving cache due to API errors');
    // Delete invalid cache if it exists
    if (fs.existsSync(CACHE_FILE)) {
      try {
        fs.unlinkSync(CACHE_FILE);
        console.log('[Cache] Deleted invalid cache file');
      } catch (error) {
        console.error('[Cache] Failed to delete invalid cache:', error);
      }
    }
  }
  
  if (isDev) {
    console.log(''); // Empty line for readability
  }

  // Save build-time data to static JSON file in /public/
  // Only save if we have valid data (not empty and no errors)
  if (!contributorsError && !maintainerError && (contributors.length > 0 || maintainer)) {
    try {
      const publicDir = path.join(process.cwd(), 'public');
      if (!fs.existsSync(publicDir)) {
        fs.mkdirSync(publicDir, { recursive: true });
      }

      const contributorsDataFile = path.join(publicDir, 'build-data-contributors.json');
      fs.writeFileSync(
        contributorsDataFile,
        JSON.stringify(
          {
            contributors: contributors || [],
            maintainer: maintainer || null,
            carreauContributions,
            timestamp: Date.now(),
          },
          null,
          2
        )
      );
      if (isDev) {
        console.log(
          `[Build Data] ✓ Saved contributors/maintainer data to ${contributorsDataFile} (${contributors.length} contributors, maintainer: ${maintainer ? 'Yes' : 'No'})`
        );
      } else {
        console.log(
          `[Build Data] ✓ Saved contributors/maintainer data (${contributors.length} contributors, maintainer: ${maintainer ? 'Yes' : 'No'})`
        );
      }
    } catch (error) {
      console.error('[Build Data] ✗ Failed to save build-time data:', error);
    }
  } else {
    if (isDev) {
      console.log('[Build Data] ⚠ Not saving contributors/maintainer data - no valid data or API errors occurred');
      if (contributorsError) {
        console.log('[Build Data]   - Contributors fetch failed');
      }
      if (maintainerError) {
        console.log('[Build Data]   - Maintainer fetch failed');
      }
      if (contributors.length === 0 && !maintainer) {
        console.log('[Build Data]   - No data available');
      }
    } else {
      console.error('[Build Data] ✗ Cannot save contributors/maintainer data - GitHub API errors or no data available');
    }
  }
}
---

<BaseLayout title="About IPython">
  <Navigation />

  <main class="min-h-screen bg-white dark:bg-ipython-dark">
    <PageHeader 
      title="About IPython" 
      description="The story behind productive interactive computing"
    />

    <!-- Content -->
    <section class="py-16 max-w-4xl mx-auto px-4 sm:px-6 lg:px-8">
      <div class="space-y-12">
        <!-- Project History -->
        <div>
          <h2 class="heading-lg">Project History</h2>
          <p class="body-text">
            IPython (Interactive Python) was created by Fernando Pérez in 2001 as a more powerful interactive shell for Python. It evolved from Mathematica's notebook interface and was designed to improve the interactive computing experience.
          </p>
          <p class="body-text">
            Over the years, IPython became the foundation for Jupyter notebooks and the broader Project Jupyter ecosystem, revolutionizing how scientists, data analysts, and educators work with code.
          </p>
        </div>

        <!-- Jupyter Relationship -->
        <div>
          <h2 class="heading-lg">IPython and Project Jupyter</h2>
          <p class="body-text">
            Since IPython 4.0 (released in 2015), the language-agnostic components were separated into Project Jupyter. IPython now focuses specifically on interactive Python computing as a Jupyter kernel and terminal interface.
          </p>
          <p class="body-text">
            Today, IPython is a core component of the Jupyter ecosystem, providing the powerful interactive Python backend for notebooks, JupyterLab, and other tools.
          </p>
        </div>

        <!-- Architecture -->
        <div>
          <h2 class="heading-lg">Modern Architecture</h2>
          <p class="text-gray-600 dark:text-gray-400 mb-6">
            IPython is organized into several key components:
          </p>
          <div class="space-y-4">
            <div class="border-l-4 border-theme-secondary pl-6">
              <h3 class="font-bold text-gray-900 dark:text-white mb-2">Terminal IPython</h3>
              <p class="body-text-base">A powerful command-line interface for interactive Python.</p>
            </div>
            <div class="border-l-4 border-theme-secondary pl-6">
              <h3 class="font-bold text-gray-900 dark:text-white mb-2">IPython Kernel</h3>
              <p class="body-text-base">Backend for Jupyter notebooks and JupyterLab.</p>
            </div>
            <div class="border-l-4 border-theme-secondary pl-6">
              <h3 class="font-bold text-gray-900 dark:text-white mb-2">Traitlets</h3>
              <p class="body-text-base">Configuration and type system used by IPython and Jupyter.</p>
            </div>
            <div class="border-l-4 border-theme-secondary pl-6">
              <h3 class="font-bold text-gray-900 dark:text-white mb-2">Display System</h3>
              <p class="body-text-base">Rich output rendering for notebooks and terminals.</p>
            </div>
          </div>
        </div>

        <!-- Governance -->
        <div>
          <h2 class="heading-lg">Governance</h2>
          <p class="body-text">
            IPython is part of Project Jupyter and operates under a community-driven governance model. The project is guided by the Jupyter Governance Council and maintained by volunteers from the open-source community.
          </p>
          <p class="body-text">
            Development decisions are made transparently through GitHub discussions, pull requests, and community meetings. Anyone can contribute to IPython regardless of their background or experience level.
          </p>
        </div>

        <!-- Current Maintainer & Developers -->
        <GitHubContributors client:load initialContributors={contributors} initialMaintainer={maintainer} />


        <!-- License -->
        <div>
          <h2 class="heading-lg">License</h2>
          <p class="body-text">
            IPython is released under the <a href="https://opensource.org/licenses/BSD-3-Clause" class="text-theme-secondary hover:text-theme-secondary/80 transition-colors">BSD 3-Clause License</a>, which allows free use in both commercial and non-commercial projects.
          </p>
        </div>

        <!-- Links -->
        <div class="bg-blue-50 dark:bg-ipython-slate border-l-4 border-theme-secondary p-6 rounded">
          <h3 class="text-xl font-bold mb-4 text-gray-900 dark:text-white">Learn More</h3>
          <ul class="space-y-3 text-gray-600 dark:text-gray-400">
            <li>
              <a href="https://github.com/ipython/ipython" class="text-theme-secondary hover:text-theme-secondary/80 transition-colors">GitHub Repository</a>
            </li>
            <li>
              <a href="https://jupyter.org" class="text-theme-secondary hover:text-theme-secondary/80 transition-colors">Project Jupyter</a>
            </li>
            <li>
              <a href="https://ipython.readthedocs.io" class="text-theme-secondary hover:text-theme-secondary/80 transition-colors">Official Documentation</a>
            </li>
            <li>
              <a href="https://github.com/ipython/ipython/blob/main/LICENSE" class="text-theme-secondary hover:text-theme-secondary/80 transition-colors">Full License</a>
            </li>
          </ul>
        </div>
      </div>
    </section>
  </main>

  <Footer />
</BaseLayout>