core/go-forge
8
0
Fork 0
Code Issues 4 Pull requests Projects Releases Packages Wiki Activity Actions

docs(forge): align service counts with activitypub
Some checks failed
Security Scan / security (push) Successful in 14s
Details
Test / test (push) Has been cancelled
Details

Browse source 
Co-Authored-By: Virgil <virgil@lethean.io>
This commit is contained in:
Virgil 2026-04-02 06:06:01 +00:00
parent 1a8fdf53ef
commit 3fd44911ea
3 changed files with 7 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
CLAUDE.md
View file

@ -33,9 +33,9 @@ The library is a flat package (`package forge`) with a layered design:
5. **`config.go`** — Config resolution: flags > env (`FORGE_URL`, `FORGE_TOKEN`) > defaults (`http://localhost:3000`).
6. **`forge.go`** — Top-level `Forge` struct aggregating all 18 service fields. Created via `NewForge(url, token)` or `NewForgeFromConfig(flagURL, flagToken)`.
6. **`forge.go`** — Top-level `Forge` struct aggregating all 19 service fields. Created via `NewForge(url, token)` or `NewForgeFromConfig(flagURL, flagToken)`.
7. **Service files** (`repos.go`, `issues.go`, etc.) — Each service struct embeds `Resource[T,C,U]` for standard CRUD, then adds hand-written action methods (e.g. `Fork`, `Pin`, `MirrorSync`). 18 services total: repos, issues, pulls, orgs, users, teams, admin, branches, releases, labels, webhooks, notifications, packages, actions, contents, wiki, commits, misc.
7. **Service files** (`repos.go`, `issues.go`, etc.) — Each service struct embeds `Resource[T,C,U]` for standard CRUD, then adds hand-written action methods (e.g. `Fork`, `Pin`, `MirrorSync`). 19 services total: repos, issues, pulls, orgs, users, teams, admin, branches, releases, labels, webhooks, notifications, packages, actions, contents, wiki, commits, misc, activitypub.
8. **`types/`** — Generated Go types from `swagger.v1.json` (229 types). The `//go:generate` directive lives in `types/generate.go`. **Do not hand-edit generated type files** — modify `cmd/forgegen/` instead.

2
docs/architecture.md
View file

@ -15,7 +15,7 @@ go-forge is organised in three layers, each building on the one below:
```
┌─────────────────────────────────────────────────┐
│ Forge (top-level client) │
│ Aggregates 18 service structs │
│ Aggregates 19 service structs │
├─────────────────────────────────────────────────┤
│ Service layer │
│ RepoService, IssueService, PullService, ... │

7
docs/index.md
View file

@ -5,7 +5,7 @@ description: Full-coverage Go client for the Forgejo API with generics-based CRU
# go-forge
`dappco.re/go/core/forge` is a Go client library for the [Forgejo](https://forgejo.org) REST API. It provides typed access to 18 API domains (repositories, issues, pull requests, organisations, and more) through a single top-level `Forge` client. Types are generated directly from Forgejo's `swagger.v1.json` specification, keeping the library in lockstep with the server.
`dappco.re/go/core/forge` is a Go client library for the [Forgejo](https://forgejo.org) REST API. It provides typed access to 19 API domains (repositories, issues, pull requests, organisations, ActivityPub, and more) through a single top-level `Forge` client. Types are generated directly from Forgejo's `swagger.v1.json` specification, keeping the library in lockstep with the server.
**Module path:** `dappco.re/go/core/forge`
**Go version:** 1.26+
@ -75,7 +75,7 @@ Environment variables:
go-forge/
├── client.go HTTP client, auth, error handling, rate limits
├── config.go Config resolution: flags > env > defaults
├── forge.go Top-level Forge struct aggregating all 18 services
├── forge.go Top-level Forge struct aggregating all 19 services
├── resource.go Generic Resource[T, C, U] for CRUD operations
├── pagination.go ListPage, ListAll, ListIter — paginated requests
├── params.go Path variable resolution ({owner}/{repo} -> values)
@ -114,7 +114,7 @@ go-forge/
## Services
The `Forge` struct exposes 18 service fields, each handling a different API domain:
The `Forge` struct exposes 19 service fields, each handling a different API domain:
| Service | Struct | Embedding | Domain |
|-----------------|---------------------|----------------------------------|--------------------------------------|
@ -136,6 +136,7 @@ The `Forge` struct exposes 18 service fields, each handling a different API doma
| `Wiki` | `WikiService` | (standalone) | Wiki pages |
| `Commits` | `CommitService` | (standalone) | Commit statuses, git notes |
| `Misc` | `MiscService` | (standalone) | Markdown, licences, gitignore, version |
| `ActivityPub` | `ActivityPubService` | (standalone) | ActivityPub actors and inboxes |
Services that embed `Resource[T, C, U]` inherit `List`, `ListAll`, `Iter`, `Get`, `Create`, `Update`, and `Delete` methods automatically. Standalone services have hand-written methods because their API endpoints are heterogeneous and do not fit a uniform CRUD pattern.