| name | gin-kit-development |
| description | Build and maintain the gin-kit runtime, CLI, project types, database integrations, generated API or UI applications, and documentation. |
| license | MIT |
| compatibility | Requires Go 1.26; UI template work also requires Node.js 20+. |
gin-kit development
Read AGENTS.md before editing. gin-kit provides two deliberate project types:
runtime is the default. It imports the versioned gin-kit runtime and keeps
only application-owned code in the generated repository.standalone vendors runtime copies under
internal/platform/ for developers who want to inspect or replace every
layer. The HTTP contract must stay identical across project types.
Keep the generated flow explicit:
router -> handler (DTO in/out) -> service -> repository -> database
Use constructors and context-aware interfaces. Transport shapes live in
internal/dto; services take request DTOs and return domain values. Put
schema changes in versioned SQL migrations. Go code templates must use
.tmpl so they are not compiled as part of the gin-kit repository.
Useful commands:
go test ./...
go vet ./...
go test -race ./...
test -z "$(gofmt -l cmd runtime internal)"
go run ./cmd/doccheck
gin-kit new <name> --project-type runtime|standalone [--auth --example --docker]
gin-kit run
gin-kit generate resource <Name> --fields "title:string,done:bool"
gin-kit db up
gin-kit explain architecture
Template-change protocol
- Change the template under
internal/cli/templates/ (scaffold) or
internal/cli/generators/ (generate commands). They are separate
go:embed trees.
- Run
.github/scripts/scaffold-smoke.sh for the standard matrix cells so
local checks match CI (it always rebuilds the CLI — a stale binary at
/tmp/gin-kit produces confusing "unknown flag" failures otherwise).
- If the change touches
tasks_* templates, also scaffold --example
projects in both project types and both modes and run go test ./... in each —
the CI matrix does not cover --example.
- Runtime-development smoke tests may use a local module replacement
(
--runtime-replace); user-facing generated projects must pin the
release version and must not contain a local replacement.
Known traps:
- The Runtime project type emits only an explicit allowlist of shared templates
(
templateOutputPath in internal/cli/new.go). The allowlist matches the
file name before the .tmpl suffix is stripped — renaming a template
to or from .tmpl without updating the allowlist silently drops it from
Runtime projects.
- Path gates:
auth_//auth/ requires --auth, tasks_ requires
--example, docker/ requires --docker, web/session paths require UI
mode.
- Templates under
templates/runtime/ overwrite same-named shared files —
except migrations/00001_init.sql, where the shared file wins; add
runtime-only migrations under new filenames.
Documentation discipline
Every behavior change updates its documentation in the same PR (matrix in
AGENTS.md): new features need a documentation-site page
(website/src/content/docs/ + sidebar), a CHANGELOG entry, docs/cli.md
when the CLI changes, and template AI-guidance updates when the generated
workflow changes. Verify site changes with
cd website && npm run check && npm run build.
Source documentation
Every package-level declaration, struct field, and interface method in
cmd/, runtime/, and internal/ needs an English doc comment. Explain the
actual behavior and important defaults, ownership, concurrency, errors, or
security constraints rather than repeating the identifier. Test entry points
are self-describing, but reusable test helpers and fixtures are documented.
Run go run ./cmd/doccheck; CI and release checks enforce the same rule.
Security and contracts
Use Argon2id for passwords, short-lived access tokens, rotating refresh tokens, secure cookies, CSRF protection, and explicit production-secret validation. Never log passwords, tokens, or credentials.
Keep generic lifecycle, HTTP policy, response, validation, and security behavior
inside the runtime. Customization must use explicit options,
interfaces, hooks, middleware, raw Gin access, or a documented module fork.
Avoid reflection-based containers and hidden application dependencies.
The canonical JSON error envelope includes code, message, request_id,
and optional details.fields. Validation errors use JSON/form field names
and must never echo submitted values. Malformed JSON is a 400 invalid_json;
semantic validation is a 422 validation_failed; oversized bodies are a
413 body_too_large. Response DTOs never include credential-like fields.
Git and pull request workflow
Work on a focused branch and submit changes through a pull request. Use
Conventional Commit-style subjects for branch commits and pull request titles,
then wait for every required check before merging. Preserve GitHub's canonical
merge commit with:
gh pr merge <number> --merge
Do not pass --subject or --body, use squash/rebase merging, push directly
to main, or bypass branch protection without explicit maintainer
authorization. After the merge, fetch main and confirm that the commit
subject is Merge pull request #<number> from <owner>/<branch> and that it has
two parents. Do not rewrite published history solely to normalize a merge
message.
Release tags are maintainer-only operations: never create or push an
annotated v0.x.y tag without explicit authorization for the exact version.
Read docs/releasing.md before preparing a release.
