go-build/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

core/go-build is the build system, release pipeline, and SDK generation tool for the Core ecosystem. Three subsystems under pkg/ — build, release, sdk — can be used as libraries or wired together via CLI commands in cmd/. This repo produces no standalone binary; cmd/ packages register commands via cli.RegisterCommands() in init() functions, compiled into the core binary from forge.lthn.ai/core/cli. Module path: dappco.re/go/core/build.

Build & Test

go build ./...                                          # compile all packages
go test ./...                                           # run all tests
go test ./pkg/build/... -run TestLoadConfig_Good        # single test by name
go test -race ./...                                     # with race detection

Go workspace: this module is part of ~/Code/go.work. Run go work sync after cloning. Set GOPRIVATE=dappco.re/*,forge.lthn.ai/* for private module fetching.

Architecture

The three subsystems share common types but are independent:

• pkg/build/ — Config loading (.core/build.yaml), project discovery via marker files, Builder interface, archiving (tar.gz/zip), checksums (SHA-256)
• pkg/build/builders/ — Go, Wails, Docker, LinuxKit, C++, Taskfile builder implementations
• pkg/build/signing/ — Signer interface with GPG, macOS codesign/notarisation, Windows (placeholder). Credentials support $ENV expansion
• pkg/release/ — Version resolution from git tags, conventional-commit changelog generation, release orchestration. Two entry points: Run() (full pipeline) and Publish() (pre-built artifacts from dist/)
• pkg/release/publishers/ — Publisher interface: GitHub, Docker, npm, Homebrew, Scoop, AUR, Chocolatey, LinuxKit
• pkg/sdk/ — OpenAPI spec detection, breaking-change diff via oasdiff, SDK code generation
• pkg/sdk/generators/ — Generator interface with registry. TypeScript, Python, Go, PHP generators (native tool -> npx -> Docker fallback)
• cmd/build/ — core build commands (build, from-path, pwa, sdk, release)
• cmd/ci/ — core ci commands (publish, init, changelog, version)
• cmd/sdk/ — core sdk commands (diff, validate)

Key Data Flow

.core/build.yaml -> LoadConfig() -> BuildConfig
project dir      -> Discover()   -> ProjectType -> getBuilder() -> Builder.Build() -> []Artifact
                                    -> SignBinaries() -> ArchiveAll() -> ChecksumAll() -> Publisher.Publish()

Key Interfaces

• build.Builder — Name(), Detect(fs, dir), Build(ctx, cfg, targets)
• publishers.Publisher — Name(), Publish(ctx, release, pubCfg, relCfg, dryRun)
• signing.Signer — Name(), Available(), Sign(ctx, fs, path)
• generators.Generator — Language(), Generate(ctx, opts), Available(), Install()

Filesystem Abstraction

All file operations use io.Medium from dappco.re/go/core/io. Production uses io.Local; tests inject mocks for isolation.

Configuration Files

• .core/build.yaml — Build config (targets, flags, signing)
• .core/release.yaml — Release config (publishers, changelog, SDK settings)

Coding Standards

• UK English in comments and strings (colour, organisation, notarisation)
• Strict types — all parameters and return types explicitly typed
• Error wrapping — coreerr.E("package.Function", "message", err) via coreerr "dappco.re/go/core/log"
• testify (assert/require) for assertions
• Test naming — _Good (happy path), _Bad (expected errors), _Ugly (edge cases)
• Conventional commits — type(scope): description
• Licence — EUPL-1.2

Extension Points

New builder: implement build.Builder in pkg/build/builders/, add to getBuilder() in cmd/build/cmd_project.go and pkg/release/release.go, optionally add ProjectType to pkg/build/build.go and marker to pkg/build/discovery.go.

New publisher: implement publishers.Publisher in pkg/release/publishers/, add to getPublisher() in pkg/release/release.go, add config fields to PublisherConfig in pkg/release/config.go and buildExtendedConfig().

New SDK generator: implement generators.Generator in pkg/sdk/generators/, register in pkg/sdk/sdk.go GenerateLanguage().

Dependencies

• forge.lthn.ai/core/cli — Command registration (cli.RegisterCommands, cli.Command) (not yet migrated)
• dappco.re/go/core/io — Filesystem abstraction (io.Medium, io.Local)
• dappco.re/go/core/i18n — Internationalisation (i18n.T(), i18n.Label())
• dappco.re/go/core/log — Structured logging
• github.com/Snider/Borg — XZ compression for archives
• github.com/getkin/kin-openapi + github.com/oasdiff/oasdiff — OpenAPI parsing and diff