ReleaseKit/docs/internal/overview.md

Package and capability inventory

Public Go contracts are defined in declarations and GoDoc. ReleaseKit supports two Go facades and a command-line interface:

• The root releasekit package is the orchestration facade. Check validates one local candidate, Publish validates and publishes its exact annotated source tag, Build compiles selected application targets, and Deliver delivers a tagged note page and any declared assets.
• buildinfo is the small runtime facade. Version reports the injected application version, the main-module version when available, or dev.
• cmd/releasekit is the executable interface. Its version, check, publish, build, and deliver commands adapt profiles and command output to the supported library operations.

See the CLI contract, configuration reference, candidate check guide, build guide, delivery guide, and runtime version guide for task-oriented use. Go declarations and GoDoc remain the owners of exact exported contracts.

Module and dependencies

The module is gitea.maximumdirect.net/eric/ReleaseKit, with Go language version 1.25.0. go.mod has no required third-party modules; packages use the standard library and first-party ReleaseKit packages. go list ./... reports these implemented packages:

Package	Responsibility
releasekit	Public orchestration facade and consumer-owned request/result types.
buildinfo	Public runtime version accessor.
cmd/releasekit	Executable entry point, command routing, output, and exit status.
cmd/releasekit/internal/cli	Command parsing, strict JSON profile loading, configured checks, and private build receipts.
internal/apicheck	Compiled-export and import-boundary checks run during development.
internal/build	Selected Go target compilation, version injection, native smoke check, and artifact digests.
internal/candidate	Stable-version, note, repository-state, candidate capture, and post-validation checks.
internal/delivery	Tagged-checkout verification and coordination of release pages, assets, and delivery results.
internal/git	Git command boundary, push-destination resolution, exact ref inspection, and tag operations.
internal/gitea	Gitea API transport, hosted release pages, asset inspection, manifests, and uploads.
internal/process	Cancellable child-process execution with per-command environment overlays.
internal/publish	Publication guards, one validation run, annotated tag creation, push, and recovery state.
internal/runtimeinfo	Private version lookup used by the runtime facade.
internal/versioncontract	Shared stable-version rules and linker-symbol identity.

The buildinfo facade depends only on its small runtime implementation. The root facade forwards to internal implementation packages. The CLI adapter is owned under cmd/releasekit/internal; implementation packages do not import either public facade. internal/apicheck verifies exported type ownership and dependency direction with go run ./internal/apicheck. These constraints are also recorded in ADR 0001 and the architecture policy.

Capability owners and behavioral evidence

The following tests are representative evidence from the current offline suite, not a separate release matrix:

Capability	Implementation owner	Existing evidence
Runtime version lookup and injected application version	buildinfo, internal/runtimeinfo, internal/versioncontract, internal/build	TestVersionInConsumerExecutable, TestVersion
Candidate capture, committed note, one validation, and rechecks	releasekit.Check, internal/candidate, cmd/releasekit/internal/cli	TestCheckCapturesCandidateAndCallsValidationOnce, TestCheckRechecksHeadAndWorktreeAfterCallback, TestCheckCommandBindsConfiguredChecksToCapturedCandidate
Authoritative endpoint and exact annotated tag publication	releasekit.Publish, internal/publish, internal/git	TestPublishPushesOnlyTheCapturedAnnotatedTag, TestResolveUsesPushURLAndQueriesWithoutMutation
Publication partial and uncertain recovery	internal/publish	TestPublishRejectedPushKeepsLocalTagAndReportsNotPublished, TestPublishLostAcknowledgmentConfirmsExactRemoteObject, TestPublishUnavailableReconciliationRemainsUnknownAndPreservesPushError
Cross-builds, version smoke checks, empty target sets, and partial outputs	releasekit.Build, internal/build, buildinfo	TestBuildCreatesSelectedTargetsAndInjectsVersion, TestBuildWithNoTargetsDoesNotInvokeCompiler, TestBuildReturnsPartialArtifactsAfterTargetFailure
Page-only and binary tagged-source delivery	releasekit.Deliver, internal/delivery, internal/gitea, CLI	TestDeliverPageOnlyCreatesAndReusesRelease, TestDeliverBuildsTaggedArtifactsAndReusesAssets, TestDeliverRejectsTamperedAssetsAndStaleReceiptBeforeRemoteWrites
Page, manifest, asset comparison, and additive retry outcomes	internal/gitea	TestEnsureReleaseCreatesMissingPageFromCommittedNote, TestInspectAssetsDetectsSameNameAndSizeWithDifferentBytes, TestUploadMissingPartialFailureThenRerunOnlyMissingAssets
CLI profiles and prepared Woodpecker sequences	cmd/releasekit, cmd/releasekit/internal/cli, examples/woodpecker/	TestLoadSettingsRejectsInvalidProfiles, TestWoodpeckerDeliveryCommandSequences, TestReleaseKitSourceDeliveryWorkflowFromTaggedCheckout

Run the complete suite with go test ./.... The public API and import boundary check is go run ./internal/apicheck. Local HTTP and Git fixtures exercise publication and delivery without real credentials or a hosted service.

Integration references

The Gitea integration guide owns the HTTP contract and hosted response handling. The Woodpecker examples are prepared integrations; their YAML is not active in this repository, and no live Woodpecker runner, configured secret, or hosted delivery has been used. Consumer migrations and measurement of removed consumer infrastructure remain future adoption work.