mirror of
https://github.com/tiennm99/awesome-ai-dev-tools.git
synced 2026-10-05 02:13:33 +00:00
tiennm99
519f85b231
`go run build` cannot work — Go resolves a bare argument as an import path, so it looks for a package named "build" in std. Wrap the existing commands in make targets instead, which gives the `make build` / `make check` ergonomics without changing the Go interface underneath. The wrapper earns its keep beyond the aliasing: `make serve` builds and previews dist/ in one step, `make test` runs exactly what CI runs, and `make update` fails with a pointer to LOCAL_DEV.md when GITHUB_TOKEN is unset rather than erroring out mid-run. Cloudflare keeps calling `go run . -build` directly. Locally make is convenience; in the build image it would be a dependency relied on for no benefit.
94 lines
2.5 KiB
Markdown
94 lines
2.5 KiB
Markdown
# Local Development
|
|
|
|
## Prerequisites
|
|
|
|
- Go 1.23 or later
|
|
- `make` (optional — every target is a one-line wrapper you can run by hand)
|
|
- A GitHub personal access token (PAT), for the update step only
|
|
|
|
Run `make` with no arguments to list the available targets.
|
|
|
|
## Getting a GitHub Token
|
|
|
|
1. Go to [https://github.com/settings/tokens](https://github.com/settings/tokens)
|
|
2. Click "Generate new token" → "Generate new token (classic)"
|
|
3. Give it a name (e.g., "awesome-ai-dev-tools")
|
|
4. Select scope: **`public_repo`** (needed to read public repo metadata)
|
|
5. Click "Generate token" and copy the value
|
|
|
|
The updater reads public repos only; `public_repo` scope is sufficient and safe.
|
|
|
|
## The two steps
|
|
|
|
The tool separates fetching data from rendering the site, so only the fetch
|
|
needs a token. See [DEPLOY.md](./DEPLOY.md) for why.
|
|
|
|
### Update (needs a token, hits the network)
|
|
|
|
```bash
|
|
export GITHUB_TOKEN=ghp_your_token_here
|
|
make update # or: go run .
|
|
```
|
|
|
|
This will:
|
|
- Read `data/agents.yml`
|
|
- Fetch live metadata from the GitHub GraphQL API
|
|
- Append star counts to `data/history.jsonl`
|
|
- Write the fetched fields to `data/metadata.json`
|
|
- Regenerate `README.md` from `templates/readme.tmpl`
|
|
|
|
### Build (offline, no token)
|
|
|
|
```bash
|
|
make build # or: go run . -build
|
|
```
|
|
|
|
This joins `data/agents.yml` (tags and notes) with `data/metadata.json` (stars
|
|
and repo metadata) and renders `dist/` — a copy of `site/` plus the generated
|
|
`dist/data.json`. This is exactly what Cloudflare Pages runs.
|
|
|
|
Preview it at <http://localhost:8080>:
|
|
|
|
```bash
|
|
make serve # builds first; override the port with PORT=3000
|
|
```
|
|
|
|
If you only touched `site/index.html` or the tags in `data/agents.yml`, the
|
|
build step alone is enough — no token required.
|
|
|
|
### Validate (offline, no token)
|
|
|
|
```bash
|
|
make check # or: go run . -check
|
|
```
|
|
|
|
### Before pushing
|
|
|
|
`make test` runs what CI runs — vet, tests, `-check` and `-build`:
|
|
|
|
```bash
|
|
make test
|
|
```
|
|
|
|
## Reverting Local Changes
|
|
|
|
Before opening a PR, undo local modifications:
|
|
|
|
```bash
|
|
git restore data/history.jsonl README.md
|
|
```
|
|
|
|
This removes the snapshot files generated by your local run, leaving only your edits to `data/agents.yml`.
|
|
|
|
## Rate Limits
|
|
|
|
- **With GITHUB_TOKEN:** 5,000 requests/hour
|
|
- **Without token:** 60 requests/hour
|
|
|
|
Always set `GITHUB_TOKEN` when testing locally to avoid hitting the unauthenticated limit.
|
|
|
|
## Next Steps
|
|
|
|
To add agents, see [CONTRIBUTING.md](./CONTRIBUTING.md).
|
|
To publish the site, see [DEPLOY.md](./DEPLOY.md).
|