diff --git a/.claude/skills/client-lib-conventions/SKILL.md b/.claude/skills/client-lib-conventions/SKILL.md new file mode 100644 index 0000000..18e1d91 --- /dev/null +++ b/.claude/skills/client-lib-conventions/SKILL.md @@ -0,0 +1,47 @@ +--- +name: client-lib-conventions +description: Use when writing, extending, reviewing, or scaffolding this Go HTTP-JSON client library — the shared Denis Shaporov / acidsailor API-design conventions (service facades, value request / pointer response, NewClient, prefix-free method naming, restkit error aliases, oapi-codegen models-only). +--- + +# Client-library API conventions + +Apply these when adding or changing the API surface of this library. + +## Constructor +`NewClient(...) (*Client, error)` with functional options (`Option`, or +`ClientOption` when a generated model already claims the name `Option`). + +## Service grouping (multi-resource clients) +Group methods into service facades exposed as **pointer fields** on `*Client`: + +```go +client.Orders.Get(ctx, req) +``` + +The facade is an unexported `type ordersService struct{ c *Client }`, held as a +`*ordersService` field, wired once in `NewClient`, with **pointer receivers** +(`func (s *ordersService) ...`). A small single-purpose client with no resource +taxonomy stays flat (methods directly on `*Client`). + +## Method signatures +`(ctx context.Context, req XxxRequest) (*XxxResponse, error)`: + +- `context.Context` first. +- Request passed **by value** (`req XxxRequest`); no variadic options. +- Response returned as a **pointer** (`*T`). + +## Returns +- Single object → `*T`. +- Collection → `[]T` (never `[]*T`). + +## Naming +- Methods drop the redundant resource prefix: `GetOrder`→`Get`, `GetOrders`→`List`, + `PlaceOrder`→`Place`. Keep the original meaning otherwise. +- Request structs: `Request` (faceted) / `Request` (flat). +- Response DTOs keep their generated names (do not rename oapi-codegen output). + +## Errors & transport +Re-export `restkit`'s typed errors as aliases (`ResponseError`, `RequestError`, +`ConfigError`) plus the `Op*` stage constants; no sentinel errors — the typed +error is the category, matched with `errors.As`. Models are generated by +oapi-codegen (models-only); never hand-edit `models.gen.go`. diff --git a/.copier-answers.yml b/.copier-answers.yml index 70a8be6..1b64e5c 100644 --- a/.copier-answers.yml +++ b/.copier-answers.yml @@ -1,5 +1,5 @@ # Changes here will be overwritten by Copier; NEVER EDIT MANUALLY. -_commit: v1.2.1 +_commit: v1.5.0 _src_path: gh:acidsailor/go-scaffolds author: Denis Shaporov / acidsailor author_email: d@shaporov.dev diff --git a/.gitignore b/.gitignore index 43e4a8d..24dcd80 100644 --- a/.gitignore +++ b/.gitignore @@ -29,6 +29,7 @@ go.work.sum # Task runner cache /.task/ -# Local agent tooling -/.claude/ +# Local agent tooling (keep committed skills, ignore worktrees/settings) +/.claude/* +!/.claude/skills/ /.worktrees/ diff --git a/taskfile.yml b/taskfile.yml index 337ae3d..46289db 100644 --- a/taskfile.yml +++ b/taskfile.yml @@ -35,6 +35,6 @@ tasks: - goreleaser release --clean update: - desc: Pull latest go-scaffolds v1 template tooling (3-way merge; source untouched) + desc: Pull latest go-scaffolds v1 template tooling (3-way merge; source untouched; no prompts) cmds: - - uvx copier update --vcs-ref v1 + - uvx copier update --defaults --vcs-ref v1