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. PrepareTaggedCheckout and PrepareBuildDependencies provide explicit local CI preparation.
• 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, deliver, and ci-deliver commands adapt profiles and command output to the supported library operations.

See the CLI contract, configuration reference, candidate check guide, source publication 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.26.0. go.mod requires golang.org/x/mod and Goldmark for internal validation; public facades do not expose either dependency. 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/artifact	Shared build-target normalization, artifact declarations, filename rules, and checksum-manifest naming.
internal/build	Resolved-identity builds, normalized settings, selected-module compilation, version injection, external native smoke output, and artifact digests.
internal/candidate	Stable-version, note, repository-state, candidate capture, and post-validation checks.
internal/delivery	Captured-commit module identity and note selection, literal-tag checkout checks, prebuilt identity binding, managed builds in disposable storage outside the checkout, structural artifact declaration, manifest assembly, one local digest-and-size preflight before hosted requests, and delivery coordination.
internal/git	Git command boundary, committed-tree reads and shared reference traversal, checkout-root and commit capture, lazy local-only batched blob reads, push-destination resolution, exact ref inspection, tagged checkout preparation, and tag operations, including captured-endpoint verification during recovery.
internal/gitea	Gitea API transport, full-tag hosted release pages, asset inspection, manifests, and uploads.
internal/gotool	Operation-local Go configuration discovery and reuse, shared native-validation and static-build environments, and network-capable dependency preparation; see Go command environments.
internal/tempdir	Disposable system temporary storage outside source worktrees.
internal/process	Cancellable child-process execution, including owned stdin/stdout pipes for serialized exchanges, with per-command environment overlays and removals.
internal/preparation	Coordination for expected-commit tag checkout and Go module dependency preparation.
internal/releaseidentity	Committed-object and working-tree module selection, declaration reading, and semantic-version-to-tag derivation.
internal/validation	Shared Go validation with optional race, full-vet, and static package-compilation target selections, formatting, workspace-file and filesystem-replacement checks, per-blob size limits, and selected Markdown destination and fragment checking; internal/candidate retains capture, callback sequencing, and local-state rechecks.
internal/publish	Publication guards, one validation run, annotated tag creation, push, and recovery state.
internal/runtimeinfo	Injected version selection and cached fallback metadata lookup for 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.

Candidate checking captures and validates one clean committed source revision in internal/candidate. Its validation bridge calls internal/validation for the selected module's default offline Go suite, then runs product-specific checks once. Validation and its post-validation build callback share one local Go settings owner. Each Go acquisition checks inherited and persistent inputs; settings are rediscovered when subsequent Go work needs them. An unavailable persistent-settings snapshot disables reuse. The candidate package owns builds and local-state rechecks; publication owns endpoint guards, tag creation, push, and recovery around that same candidate validation path. internal/validation.CandidateTree reads committed blobs lazily and resolves local destinations from committed entries; it does not consult neighboring files or traverse submodule checkouts. See the shared validation guide for checker, Go command, and candidate-file integration mechanics.

Delivery verifies all local binary sizes and digests before hosted requests. Its Gitea upload path reuses that verification and streams missing files once for transport. Independent calls to the internal client's UploadMissing verify missing local files before writing. Both paths share remote inspection, conflict handling, and reconciliation.

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, shared validation, public diagnostics, additional checks, and rechecks	releasekit.Check, releasekit.Publish, internal/candidate, internal/validation, cmd/releasekit/internal/cli	TestRunUsesOneSuiteWithSelectedRaceSetting, TestRunReportsRacePrerequisiteFailureWithoutFallback, TestRunExecutesRaceEnabledSuiteOnHost, TestRunCompilesTargetsAfterTestAndVetInSelectionOrder, TestRunAttributesTargetCompileFailureAndStops, TestRunCompilesSourceOnlyAndExecutablePackagesWithoutArtifacts, TestCandidateRequestMapsGoValidation, TestCandidateRequestPreservesMarkdownObjectSelection, TestLoadSettingsReadsGoValidation, TestLoadSettingsPreservesMarkdownObjectSelection, TestCheckUsesSelectedRaceSuiteBeforeAdditionalChecks, TestCheckCapturesCandidateAndCallsAdditionalChecksOnce, TestCheckReturnsPublicValidationError, TestMarkdownValidationRunsThroughCheckAndPublish, TestCheckStopsBeforeProductAndBuildCallbacksWhenMarkdownBoundaryFails, TestCheckCommandBindsConfiguredChecksToCapturedCandidate, TestPublishCommandPublishesConfiguredCandidate, TestCandidateCommandsPresentValidationDiagnosticsOnce, TestDeliverPageOnlyCreatesAndReusesRelease
Committed-file validation: formatting, workspace files, local replacements, and file size	internal/validation, internal/candidate, releasekit.Check, releasekit.Publish, CLI profile conversion	TestCheckGoFormatUsesCapturedRegularGoBlobs, TestCheckWorkspaceFilesReportsCommittedBlobNames, TestCheckLocalReplacementsParsesCommittedModuleDeclarations, TestCheckLocalReplacementsFollowsCommittedModuleSymlinks, TestCheckFileSizeUsesStrictLimitsAndDefault, TestCheckFileSizeAppliesLiteralPathExclusions, TestCheckFileSizeUsesCommittedBlobSizes, TestCheckFileSizeUsesOnlyCandidateFilesIndividually
Internal Markdown parsing, committed destinations, fragments, boundary observations, and public selection	releasekit.Check, releasekit.Publish, internal/candidate, internal/validation, cmd/releasekit/internal/cli	TestParseMarkdownLinksAndSourceLocations, TestParseMarkdownDecodesEntitiesInDestinations, TestParseMarkdownHeadingAnchors, TestMarkdownCacheKeepsParsedDocumentsPerCandidatePath, TestCheckMarkdownLinksResolvesCommittedDestinationsAndFragments, TestCheckMarkdownLinksReportsMissingPathsAnchorsAndCycles, TestCheckMarkdownLinksUsesResolvedMarkdownIdentity, TestCheckMarkdownLinksReportsBoundaryAndSubmoduleObservations, TestCheckMarkdownLinksPreservesResolverCauseAndCancellation, TestCheckMarkdownLinksPreservesAnchorReadCause, TestRunSelectsMarkdownWithCombinedGoChecksAndReportsOutOfScopeLinks, TestMarkdownValidationRunsThroughCheckAndPublish, TestLoadSettingsPreservesMarkdownObjectSelection, TestValidationSpecPreservesMarkdownObjectSelection
Shared Go settings for validation and builds	internal/gotool, internal/process, internal/candidate, internal/build	TestDefaultValidationDoesNotInheritGOFLAGSRunFilter, TestNativeAndStaticCommandsUseOwnedBaseline, TestPersistentSettingsPreserveCachesAndNativeCTools, TestOwnerReusesSettingsUntilInheritedEnvironmentChanges, TestOwnerRefreshesWhenPersistentSettingsChange, TestCheckSharesGoDiscoveryWithAfterValidateCallback, TestCheckBuildsAfterValidationAndKeepsOutputOutsideWorktree, TestRunValidatesOnlyTheSelectedModule, TestBuildIgnoresAmbientAndPersistentArchitectureTuning
Batched local Git blob reads	internal/git, internal/process	TestBlobReaderReadsLooseAndPackedObjects, TestBlobReaderMissingObjectKeepsBatchSessionUsable, TestCandidateObjectReadsStayLocalInPartialClones
Piped child-process exchanges and cancellation cleanup	internal/process	TestStartPipedExchangesBeforeInputEOFAndPreservesSettings, TestStartPipedCancellationAfterReadinessReapsChild, TestStartPipedPreservesNonzeroExit
Authoritative endpoint and exact annotated tag publication	releasekit.Publish, internal/publish, internal/git	TestPublishPushesOnlyTheCapturedAnnotatedTag, TestPublishRejectsUnexpectedPushURLBeforeValidation, TestPublishComparesExpectedURLWithResolvedInsteadOfDestination, TestPublishExpectedPushURLUsesPushURLWhenFetchAndPushDiffer, TestCheckIgnoresExpectedPushURL, TestResolveUsesPushURLAndQueriesWithoutMutation
Publication partial and uncertain recovery	internal/publish, internal/git	TestPublishRejectedPushKeepsLocalTagAndReportsNotPublished, TestPublishLostAcknowledgmentConfirmsExactRemoteObject, TestPublishLostAcknowledgmentWithChangedEndpointRemainsUnknown, TestPublishUnavailableReconciliationRemainsUnknownAndPreservesPushError
Cross-builds, version smoke checks, module paths, empty target sets, and partial outputs	releasekit.Build, internal/build, internal/artifact, internal/tempdir, buildinfo	TestBuildCreatesSelectedTargetsAndInjectsVersion, TestBuildUsesNestedWorkingTreeModuleAndModuleRelativeOutput, TestBuildResolvesDirtyWorkingTreeDeclaration, TestBuildWithNoTargetsDoesNotInvokeCompiler, TestBuildReturnsPartialArtifactsAfterTargetFailure, TestNormalizeSettingsKeepsBuildInputsAndNormalizesTargets, TestOutsideFallsBackWhenTemporaryDirectoryIsInsideWorktree
Page-only and managed or prebuilt binary delivery	releasekit.Deliver, internal/delivery, internal/gitea, CLI	TestDeliverPageOnlySkipsBuildAndHostedAssets, TestDeliverUsesCommittedModuleIdentityForSeparatePages, TestDeliverRejectsPrebuiltArtifactsForAnotherModuleBeforeHostedRequests, TestDeliverManagedBuildUploadsArtifactsAndCleansTemporaryOutput, TestDeliverBinaryConsumerWithBuildinfoAndSelectedTargets, TestDeliverPrebuiltArtifactsRemainCallerOwned, TestDeliverRejectsSameSizePrebuiltTamperingBeforeHostedWrites, TestDeliverManagedBuildFailureCleansTemporaryOutputBeforeHostedWrites, TestDeliverManagedBuildCancellationCleansTemporaryOutput, TestDeliverBuildsTaggedArtifactsAndReusesAssets, TestDeliverRejectsTamperedAssetsAndStaleReceiptBeforeRemoteWrites, TestEnsureReleaseEscapesSlashContainingTag
Tagged checkout and build dependency preparation	releasekit.PrepareTaggedCheckout, releasekit.PrepareBuildDependencies, internal/preparation, internal/git, internal/gotool	TestPrepareTaggedCheckoutFetchesExpectedCommitAndDetaches, TestPrepareTaggedCheckoutRejectsWrongCommitBeforeCheckout, TestPrepareTaggedCheckoutReportsLocalCheckoutConflict, TestPrepareTaggedCheckoutReportsConflictingLocalTag, TestPrepareBuildDependenciesUsesSelectedModuleDirectory, TestPrepareBuildDependenciesPreservesPreparationEnvironment, TestPrepareBuildDependenciesPropagatesCommandFailure, TestPrepareBuildDependenciesPropagatesCancellation
Shared module identity and tag derivation	internal/releaseidentity, internal/candidate, internal/build, internal/delivery	TestDeriveUsesModuleDeclarationAndPhysicalLayout, TestCommittedAndWorkingTreeDeclarationsUseTheirOwnSources, TestSelectedNestedModuleDoesNotRequireRootDeclaration, TestBuildResolvesDirtyWorkingTreeDeclaration, TestDeliverUsesCommittedModuleIdentityForSeparatePages
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/, examples/multi-module/	TestLoadSettingsRejectsInvalidProfiles, TestWoodpeckerTagDeliveryTemplate, TestWoodpeckerTagDeliveryUsesTaggedModuleVersion, TestWoodpeckerSourceDeliveryTemplateSelfBootstraps, TestReleaseKitSourceDeliveryWorkflowFromTaggedCheckout, TestMultiModuleSelectorMapsSelectorsAndTags, TestMultiModuleLauncherUsesSelectedModuleAndProfile, TestMultiModuleWoodpeckerDelivery

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.