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.
2.5 KiB
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
- Go to https://github.com/settings/tokens
- Click "Generate new token" → "Generate new token (classic)"
- Give it a name (e.g., "awesome-ai-dev-tools")
- Select scope:
public_repo(needed to read public repo metadata) - 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 for why.
Update (needs a token, hits the network)
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.mdfromtemplates/readme.tmpl
Build (offline, no token)
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:
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)
make check # or: go run . -check
Before pushing
make test runs what CI runs — vet, tests, -check and -build:
make test
Reverting Local Changes
Before opening a PR, undo local modifications:
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. To publish the site, see DEPLOY.md.