# GitHub Repository Cataloger

A TypeScript tool to catalog and analyze GitHub repositories by prefix, providing detailed insights into languages used, activity status, and repository metrics.

## Features

- 🔍 **Search by Prefix**: Find all repositories starting with a specific prefix
- 🗣️ **Language Analysis**: Identify primary and all languages used in each repository
- 📊 **Activity Status**: Distinguish between active and archived repositories
- 📈 **Detailed Metrics**: Stars, forks, size, creation dates, and more
- 💾 **Export Options**: JSON export for further analysis
- ⚡ **Rate Limiting**: Intelligent API rate limiting with progress tracking
- 🔐 **Token Support**: Optional GitHub token for higher rate limits and private repos

## Quick Start

### 1. Clone & Install

```bash
git clone git@github.com:theorchard/collab.git
cd ratoui/github-cataloger
npm install
```

### 2. Configure Environment

```bash
cp .env.example .env
# Edit .env with your details
```

### 3. Set Required Variables

```bash
GITHUB_USERNAME=your-username
REPO_PREFIX=ows-
```

### 4. Optional: Add GitHub Token

For better rate limits and private repo access:

```bash
GITHUB_TOKEN=ghp_your_token_here
```

### 5. Run

```bash
# Development mode
npm run dev

# Or build and run
npm run build
npm start
```

## Configuration

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `GITHUB_USERNAME` | ✅ | - | Your GitHub username |
| `REPO_PREFIX` | ✅ | `ows-` | Repository name prefix to search for |
| `GITHUB_TOKEN` | ❌ | - | GitHub Personal Access Token |
| `EXPORT_TO_FILE` | ❌ | `true` | Export results to JSON file |
| `OUTPUT_FILENAME` | ❌ | `repo-catalog.json` | Output file name |
| `SHOW_DETAILED` | ❌ | `true` | Show detailed repository info |
| `RATE_LIMIT_DELAY` | ❌ | `200` | Delay between API calls (ms) |
| `RETRY_ATTEMPTS` | ❌ | `3` | Number of retry attempts |

### Getting a GitHub Token

1. Go to GitHub Settings → Developer settings → Personal access tokens
2. Generate a new token with `repo` scope (for private repos) or `public_repo` (for public only)
3. Copy the token to your `.env` file

## Usage Examples

### Basic Usage

```typescript
import { RepositoryCataloger } from './lib/cataloger';

const cataloger = new RepositoryCataloger();
const catalog = await cataloger.catalogRepositories({
  username: 'your-username',
  prefix: 'ows-'
});
```

### With Authentication

```typescript
const cataloger = new RepositoryCataloger('your_github_token');
const catalog = await cataloger.catalogRepositories({
  username: 'your-username',
  prefix: 'ows-',
  sortBy: 'updated',
  sortOrder: 'desc'
});
```

### Generate Summary

```typescript
const summary = cataloger.generateSummary(catalog);
cataloger.printSummary(summary);
cataloger.printDetailedCatalog(catalog);
```

## Sample Output

```
🚀 GitHub Repository Cataloger
================================

👤 Username: your-username
🔍 Prefix: "ows-"
🔑 Token: Provided

🔍 Searching for repositories starting with "ows-" for user: your-username
📊 Rate limit: 4998 requests remaining
📁 Found 5 repositories matching prefix "ows-"

[1/5] Processing: ows-backend
   ✓ ows-backend - TypeScript - 🟢 ACTIVE

[2/5] Processing: ows-frontend
   ✓ ows-frontend - React - 🟢 ACTIVE

[3/5] Processing: ows-legacy
   ✓ ows-legacy - JavaScript - 🔒 ARCHIVED

============================================================
📋 REPOSITORY CATALOG SUMMARY
============================================================

📊 Overview:
   Total Repositories: 5
   🟢 Active: