# Generate-Info: Repository Statistics

This document describes the repository statistics functionality added to the `generate-info` tool.

## Overview

The `generate-info` tool can now fetch and cache GitGud.io repository statistics to a JSON file that mpv.rocks can consume. This runs alongside the existing releases.json generation.

## Usage

### Generate Repository Statistics

```bash
# Generate repo-stats.json with default output location
go run ./cmd/generate-info/ -repo-stats

# Generate with custom output path
go run ./cmd/generate-info/ -repo-stats -stats-output /var/www/mpv.rocks/api/repo-stats.json

# Generate in quiet mode (useful for cron jobs)
go run ./cmd/generate-info/ -repo-stats -quiet

# Use with API token (for authenticated requests, may provide more data)
go run ./cmd/generate-info/ -repo-stats -token glpat-xxxxxxxxxxxx
```

### Generate Releases JSON (Existing Functionality)

```bash
# Auto mode for releases.json
go run ./cmd/generate-info/ -auto -manager-version 1.0.0

# Interactive mode
go run ./cmd/generate-info/
```

## CLI Flags

| Flag | Default | Description |
|------|---------|-------------|
| `-repo-stats` | false | Generate repo-stats.json instead of releases.json |
| `-stats-output` | (same dir as releases.json) | Output path for repo-stats.json |
| `-token` | (empty) | Project Access Token for authenticated API requests |
| `-quiet` | false | Suppress progress output (useful for cron) |
| `-auto` | false | Run in non-interactive mode (for releases.json) |
| `-output` | releases.json | Output file for releases.json |
| `-manager-version` | (fetched from GitLab) | MPV Manager version to use |

## API Endpoints Used

The tool fetches data from three GitGud.io (GitLab) API endpoints:

### 1. Project Info
```
GET https://gitgud.io/api/v4/projects/45219?license=true
```
Returns: star_count, forks_count, last_activity_at, created_at, license, topics, description, visibility, default_branch

### 2. Issues Statistics
```
GET https://gitgud.io/api/v4/projects/45219/issues_statistics
```
Returns: count of open issues

### 3. Pipeline Status
```
GET https://gitgud.io/api/v4/projects/45219/pipelines?per_page=1
```
Returns: latest CI/CD pipeline status, ref, and commit SHA

## Output JSON Structure

```json
{
  "star_count": 0,
  "forks_count": 0,
  "open_issues_count": 0,
  "ci_status": 0,
  "ci_pipeline": {
    "status": "success",
    "ref": "v0.9.0",
    "sha": "121d0cfe764a478a62793cba5f02da4f5e5f8e38"
  },
  "last_activity_at": "2026-02-21T09:44:12.829Z",
  "created_at": "2026-01-22T11:06:51.608Z",
  "license": {
    "key": "mit",
    "name": "MIT License",
    "url": "https://opensource.org/licenses/MIT"
  },
  "topics": ["go", "linux", "macos", "mpv", "windows"],
  "description": "https://MPV.Rocks - MPV Installer and Manager",
  "web_url": "https://gitgud.io/mike/mpv-manager",
  "default_branch": "master",
  "visibility": "public",
  "fetched_at": "2026-02-21T23:49:41Z"
}
```

### Field Descriptions

| Field | Type | Description |
|-------|------|-------------|
| `star_count` | int | Number of repository stars |
| `forks_count` | int | Number of repository forks |
| `open_issues_count` | int | Number of open issues |
| `ci_status` | int | Latest CI pipeline status code (see below) |
| `ci_pipeline` | object | Latest pipeline details (status, ref, sha) |
| `last_activity_at` | string | ISO 8601 timestamp of last activity |
| `created_at` | string | ISO 8601 timestamp of repository creation |
| `license` | object | License information (key, name, url) |
| `topics` | array | Repository topics/tags |
| `description` | string | Repository description |
| `web_url` | string | Repository web URL |
| `default_branch` | string | Default branch name |
| `visibility` | string | Repository visibility (public/private) |
| `fetched_at` | string | ISO 8601 timestamp when data was fetched |

### CI Status Codes

| Code | Status | Description |
|------|--------|-------------|
| 0 | success | Pipeline completed successfully |
| 1 | pending | Pipeline is waiting to run |
| 2 | running | Pipeline is currently running |
| 3 | failed | Pipeline failed |
| 4 | canceled | Pipeline was canceled |
| 5 | skipped | Pipeline was skipped |
| -1 | unknown | Could not determine status |

## Error Handling

The tool handles errors gracefully:

- If project info fetch fails → Uses defaults (0 for counts, empty strings)
- If issues stats fetch fails → Uses 0 for open_issues_count
- If pipeline fetch fails → Uses -1 for ci_status
- The JSON file is always written with whatever data was successfully fetched

## Systemd Timer Configuration

For automated updates, use a systemd timer:

### `/etc/systemd/system/generate-repo-stats.service`

```ini
[Unit]
Description=Generate MPV.Rocks repository statistics
After=network.target

[Service]
Type=oneshot
User=www-data
WorkingDirectory=/var/www/mpv.rocks
ExecStart=/usr/local/bin/generate-info -repo-stats -quiet -stats-output /var/www/mpv.rocks/api/repo-stats.json

[Install]
WantedBy=multi-user.target
```

### `/etc/systemd/system/generate-repo-stats.timer`

```ini
[Unit]
Description=Generate repo stats every 30 minutes

[Timer]
OnBootSec=5min
OnUnitActiveSec=30min

[Install]
WantedBy=timers.target
```

### Enable the Timer

```bash
sudo systemctl daemon-reload
sudo systemctl enable generate-repo-stats.timer
sudo systemctl start generate-repo-stats.timer
```

### Check Timer Status

```bash
sudo systemctl list-timers generate-repo-stats.timer
```

## Project Details

- **Project**: mpv-manager
- **Project ID**: 45219
- **Repository**: https://gitgud.io/mike/mpv-manager
- **API Base**: https://gitgud.io/api/v4

## Serving the JSON

The output file should be served at `https://mpv.rocks/api/repo-stats.json`. Configure your web server (nginx, Apache, etc.) to serve the file with appropriate CORS headers if needed.

### nginx Example

```nginx
location /api/repo-stats.json {
    alias /var/www/mpv.rocks/api/repo-stats.json;
    add_header Content-Type application/json;
    add_header Cache-Control "public, max-age=1800"; # 30 minutes
}
```