Repo Manager

Repo Manager

Manage GitHub repository registry and sync operations for the Survey project.

Mode Detection

CLI Commands

Use bun scripts/repo-cli.ts for all registry operations. This is the preferred method over direct JSON manipulation.

Command Reference

Add New Repo

bun scripts/repo-cli.ts add <owner/repo> [options]

Options:
  --description "desc"  Repository description
  --tags a,b,c          Comma-separated tags
  --level <level>       beginner | intermediate | advanced | expert
  --stars <number>      Star count

Examples:

# Add with basic info
bun scripts/repo-cli.ts add vercel/next.js

# Add with full metadata
bun scripts/repo-cli.ts add vercel/next.js \
  --description "The React Framework" \
  --tags react,framework,ssr \
  --level intermediate \
  --stars 120000

Update Existing Repo

bun scripts/repo-cli.ts update <owner/repo> [options]

Options:
  --description "desc"  Update description
  --tags a,b,c          Replace tags
  --level <level>       Update difficulty level
  --stars <number>      Update star count (use "null" to remove)

Examples:

# Update level
bun scripts/repo-cli.ts update vercel/next.js --level advanced

# Update tags
bun scripts/repo-cli.ts update vercel/next.js --tags react,framework,production-ready

# Remove stars field
bun scripts/repo-cli.ts update vercel/next.js --stars null

Remove Repo

bun scripts/repo-cli.ts remove <owner/repo>

Get Repo Details

# Human-readable output
bun scripts/repo-cli.ts get vercel/next.js

# JSON output (for LLM parsing)
bun scripts/repo-cli.ts get vercel/next.js --json

List All Repos

# Human-readable output (one ID per line)
bun scripts/repo-cli.ts list

# JSON output
bun scripts/repo-cli.ts list --json

Validate Registry

# Human-readable output
bun scripts/repo-cli.ts validate

# JSON output
bun scripts/repo-cli.ts validate --json

Repair Registry

Fixes formatting issues, normalizes entries:

bun scripts/repo-cli.ts repair

Use when:

• Registry has inconsistent formatting
• Fields are missing or malformed
• After manual JSON edits

JSON Output Format

Use --json flag for machine-readable output, suitable for LLM parsing.

get --json

{
  "id": "vercel/next.js",
  "url": "https://github.com/vercel/next.js",
  "owner": "vercel",
  "repo": "next.js",
  "description": "The React Framework",
  "stars": 120000,
  "tags": ["react", "framework", "ssr"],
  "level": "intermediate",
  "valid": true
}

list --json

[
  { "id": "vercel/next.js", "url": "https://github.com/vercel/next.js", ... },
  { "id": "facebook/react", "url": "https://github.com/facebook/react", ... }
]

validate --json

Valid registry:

{ "valid": true, "count": 34 }

Invalid registry:

{
  "valid": false,
  "errors": [
    { "id": "invalid-entry", "error": "Missing required field: url" }
  ]
}

Registry Entry Format

interface RepoEntry {
  id: string;           // Format: "owner/repo"
  url: string;          // GitHub URL
  owner: string;        // Repository owner
  repo: string;         // Repository name
  description?: string; // Short description
  stars?: number;       // Star count (optional)
  tags?: string[];      // Category tags (optional)
  level?: string;       // "beginner" | "intermediate" | "advanced" | "expert"
  cloned_at?: string;   // ISO timestamp when cloned
  last_commit?: string; // Last known commit SHA
  renamed_at?: string;  // ISO timestamp when renamed
}

Sync Operations

Primary Script

Use bun scripts/sync-repos.ts for all sync operations.

Available Commands

Output Directory Convention

Cloned repositories go to: github/{owner}/{repo}/

This directory is gitignored - repos are local clones only.

Registry Maintenance

Check Renamed Repos

GitHub repos can be renamed. Use --update-registry to detect and fix:

bun scripts/sync-repos.ts --update-registry

This checks each repo's current name via GitHub API and updates the registry.

Use --rename-dirs to also rename local directories:

bun scripts/sync-repos.ts --update-registry --rename-dirs

Registry Verification

Check and fix registry integrity issues:

# Verify registry integrity (dry run)
bun scripts/sync-repos.ts --verify

# Auto-fix orphaned repos (clone missing repos)
bun scripts/sync-repos.ts --verify-fix

# Fix with controlled concurrency (prevent system overload)
bun scripts/sync-repos.ts --verify-fix --concurrent 3

Verification Checks

Verification Report

Running --verify produces a report showing:

• Total repos in registry
• Orphaned entries (repos in registry without local clone)
• Unindexed repos (local repos not in registry)
• Invalid entries (malformed registry entries)

Error Handling

Registry File Not Found

# Create empty registry
echo '{"version":"1.0","updated_at":"2024-01-01T00:00:00Z","repos":[]}' > {{PATH_MANIFEST.registries}}/repos.json

Invalid Repo Format

• Ensure id matches "owner/repo" pattern
• Verify owner and repo fields match id
• Check URL is valid GitHub URL

Sync Failures

Common causes:

• Network issues -> Retry with backoff
• Rate limiting -> Wait or use GITHUB_TOKEN
• Repo deleted/archived -> Remove from registry
• Permissions -> Check Git credentials

Network Issues

# Check connectivity first
ping github.com

# Use GITHUB_TOKEN for higher rate limits
export GITHUB_TOKEN=ghp_your_token

Quick Reference

Registry CLI Commands

Sync Commands

Registry Schema

{{PATH_MANIFEST.registries}}/repos.json
├── version           "1.0"
├── updated_at        ISO timestamp
└── repos[]
    ├── [0].id          "owner/repo"
    ├── [0].url         "https://github.com/owner/repo"
    ├── [0].owner       "owner"
    ├── [0].repo        "repo"
    ├── [0].description?  string
    ├── [0].stars?       number
    ├── [0].tags?        string[]
    ├── [0].level?       "beginner" | "intermediate" | "advanced" | "expert"
    ├── [0].cloned_at?   ISO timestamp
    ├── [0].last_commit? SHA string
    └── [0].renamed_at?  ISO timestamp

Environment Variables

Separation of Concerns

This skill ONLY manages:

• Registry file ({{PATH_MANIFEST.registries}}/repos.json)
• Repository cloning and syncing
• Registry maintenance

It does NOT:

• Analyze repository content -> Use github-researcher
• Generate documentation -> Use github-researcher
• Compare projects -> Use survey-synthesizer