# Searchgit

Search GitHub repositories with criteria and browse the results in a clean web interface
(light/dark theme, responsive, English/French UI). The interface reuses the look of
[Logstream](https://gitea.vlab.bzh/cedric/logstream).

```
browser ──/api/search──▶ searchgit (Go) ──REST──▶ api.github.com/search/repositories
        ──/api/saved───▶      ├── 5 min cache
                              └── scheduler ──▶ /data (JSON snapshots)
```

## Getting started

```bash
cp .env.example .env      # optional: set GITHUB_TOKEN
docker compose up -d --build
```

Then open <http://localhost:8080>.

Without Docker: `go run .` (Go 1.24 or newer, data in `./data`), then open <http://localhost:8080>.

## Criteria

| Filter | GitHub qualifier |
|---|---|
| Search field | free text, plus any GitHub qualifier (`user:`, `org:`, `NOT`, `"exact phrase"`, `size:`…) |
| Everywhere / Name / Description / README | `in:name`, `in:description`, `in:readme` |
| Language | `language:Go` (click a language in the list to filter on it) |
| Stars | `stars:>=100` |
| Activity | `pushed:>=YYYY-MM-DD` (1 month to 2 years) |
| Creation date | `created:>=YYYY-MM-DD` |
| License | `license:mit`… |
| Topic | `topic:cli` (click a topic in the list to filter on it) |
| Good first issues | `good-first-issues:>0` |
| Forks / Archived | forks and archived repositories are hidden unless enabled |
| Sort | best match, stars, forks, recently updated, help wanted issues |

The filters are kept in the page URL, so a search can be bookmarked or shared. The footer
shows the exact query sent to GitHub (click it to open the same search on github.com).
**CSV** downloads the loaded results (semicolon separated when the UI is in French, for Excel).

GitHub returns at most the first 1,000 results of a search.

## Scheduled searches (weekly review)

**Schedule** saves the current filters as a search that the server runs on its own:
every week (day and time), every day, or every N hours, in the server time zone (`TZ`).
Each run keeps a snapshot of the first 30, 50 or 100 results.

The **Watch** tab lists the scheduled searches with their last run, and a review page
per search shows, for any run of its history:

- **New**: repositories never returned by a previous run of this search;
- **Rising**: repositories that gained the most stars since the previous run;
- **All**: the whole snapshot, with the star gain of each repository.

A search runs once as soon as it is created: that first run is the baseline the next
ones are compared with. A run missed while the server was stopped is made at startup.
For a weekly "gems" review, a good start is: a topic or a language, *created < 1 month*
(or *< 1 week*), sorted by *most stars*.

## Configuration

| Variable | Default | Role |
|---|---|---|
| `HTTP_ADDR` | `:8080` | listening address |
| `GITHUB_TOKEN` | empty | GitHub token; raises the search quota from 10 to 30 requests per minute |
| `CACHE_TTL` | `5m` | identical searches are served from memory for this long |
| `AUTH_USER` / `AUTH_PASS` | empty | HTTP basic authentication (except `/healthz`) |
| `GITHUB_API` | `https://api.github.com` | API base URL (GitHub Enterprise) |
| `DATA_DIR` | `data` (`/data` in Docker) | scheduled searches and their snapshots (JSON files) |
| `TZ` | `Europe/Paris` in compose | time zone of the schedules |
| `HISTORY_KEEP` | `100` | runs kept per scheduled search (0 = all) |

## API

- `GET /api/search?q=&in=&language=&stars=&maxstars=&minforks=&topic=&license=&pushed=&created=&goodfirst=1&forks=1&archived=1&sort=&order=&page=&per_page=`
  (`pushed` / `created`: `1w`, `1m`, `3m`, `6m`, `1y`, `2y`, `5y`)
- `GET /api/status`: token configured, last known search quota, server time zone
- `GET|POST /api/saved`, `GET|PUT|DELETE /api/saved/{id}`: scheduled searches
  (`{"name", "params", "maxResults", "enabled", "schedule": {"every": "week|day|hours", "weekday", "hour", "minute", "hours"}}`,
  `params` being the `/api/search` query string)
- `POST /api/saved/{id}/run`: run now
- `GET /api/saved/{id}/runs`, `GET /api/saved/{id}/runs/{run|latest}`: history and snapshots
- `GET /healthz`

## Development

```bash
go test ./...
go run .
```

The web interface is plain HTML, CSS and JavaScript in `web/`, embedded in the binary
(no build step).