2026-10-05 21:06:16 +00:00
# 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`
2026-10-06 18:59:29 +00:00
delivers a tagged note page and any declared assets. `PrepareTaggedCheckout`
and `PrepareBuildDependencies` provide explicit local CI preparation.
2026-10-05 21:06:16 +00:00
- `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` ,
2026-10-06 20:15:14 +00:00
`publish` , `build` , `deliver` , and `ci-deliver` commands adapt profiles and
command output to the supported library operations.
2026-10-05 21:06:16 +00:00
See the [CLI contract ](../cli.md ), [configuration reference ](../config.md ),
[candidate check guide ](../consumers/check.md ),
2026-10-06 17:15:46 +00:00
[source publication guide ](../consumers/publish.md ),
2026-10-05 21:06:16 +00:00
[build guide ](../consumers/build.md ),
[delivery guide ](../consumers/delivery.md ), and
[runtime version guide ](../consumers/runtime-version.md ) 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
2026-10-07 23:07:50 +00:00
version `1.25.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:
2026-10-05 21:06:16 +00:00
| 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. |
2026-10-06 17:29:41 +00:00
| `internal/artifact` | Shared build-target normalization, artifact declarations, filename rules, and checksum-manifest naming. |
2026-10-10 02:53:38 +00:00
| `internal/build` | Resolved-identity builds, normalized settings, selected-module compilation, version injection, external native smoke output, and artifact digests. |
2026-10-05 21:06:16 +00:00
| `internal/candidate` | Stable-version, note, repository-state, candidate capture, and post-validation checks. |
2026-10-10 03:10:43 +00:00
| `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, checkout-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. |
2026-10-10 02:43:23 +00:00
| `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 ](gotool.md ). |
2026-10-06 01:00:11 +00:00
| `internal/tempdir` | Disposable system temporary storage outside source worktrees. |
2026-10-09 01:17:58 +00:00
| `internal/process` | Cancellable child-process execution, including owned stdin/stdout pipes for serialized exchanges, with per-command environment overlays and removals. |
2026-10-06 18:59:29 +00:00
| `internal/preparation` | Coordination for expected-commit tag checkout and Go module dependency preparation. |
2026-10-07 23:26:48 +00:00
| `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. |
2026-10-05 21:06:16 +00:00
| `internal/publish` | Publication guards, one validation run, annotated tag creation, push, and recovery state. |
2026-10-09 01:46:07 +00:00
| `internal/runtimeinfo` | Injected version selection and cached fallback metadata lookup for the runtime facade. |
2026-10-05 21:06:16 +00:00
| `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 ](../adr/0001-public-facade.md ) and the
[architecture policy ](../policy/architecture.md ).
2026-10-07 18:26:36 +00:00
Candidate checking captures and validates one clean committed source revision
in `internal/candidate` . Its validation bridge calls `internal/validation` for
2026-10-10 02:43:23 +00:00
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; the candidate package owns those builds and local-state
rechecks; publication owns endpoint guards, tag creation, push, and recovery
around that same candidate validation path. `internal/validation.CandidateTree` reads
2026-10-07 18:31:18 +00:00
committed blobs lazily and resolves local destinations from committed entries;
it does not consult neighboring files or traverse submodule checkouts.
2026-10-07 18:39:15 +00:00
See the [shared validation guide ](validation.md ) for checker, Go command, and
candidate-file integration mechanics.
2026-10-07 18:26:36 +00:00
2026-10-05 21:06:16 +00:00
## 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` |
2026-10-07 23:26:48 +00:00
| 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` |
2026-10-07 23:52:55 +00:00
| 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` |
2026-10-07 23:26:48 +00:00
| 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` |
2026-10-10 02:43:23 +00:00
| Shared Go settings for validation and builds | `internal/gotool` , `internal/process` , `internal/candidate` , `internal/build` | `TestDefaultValidationDoesNotInheritGOFLAGSRunFilter` , `TestNativeAndStaticCommandsUseOwnedBaseline` , `TestPersistentSettingsPreserveCachesAndNativeCTools` , `TestOwnerReusesSettingsUntilInheritedEnvironmentChanges` , `TestOwnerRefreshesWhenPersistentSettingsChange` , `TestCheckSharesGoDiscoveryWithAfterValidateCallback` , `TestCheckBuildsAfterValidationAndKeepsOutputOutsideWorktree` , `TestRunValidatesOnlyTheSelectedModule` , `TestBuildIgnoresAmbientAndPersistentArchitectureTuning` |
2026-10-09 01:23:00 +00:00
| Batched local Git blob reads | `internal/git` , `internal/process` | `TestBlobReaderReadsLooseAndPackedObjects` , `TestBlobReaderMissingObjectKeepsBatchSessionUsable` , `TestCandidateObjectReadsStayLocalInPartialClones` |
2026-10-09 01:17:58 +00:00
| Piped child-process exchanges and cancellation cleanup | `internal/process` | `TestStartPipedExchangesBeforeInputEOFAndPreservesSettings` , `TestStartPipedCancellationAfterReadinessReapsChild` , `TestStartPipedPreservesNonzeroExit` |
2026-10-07 22:31:58 +00:00
| Authoritative endpoint and exact annotated tag publication | `releasekit.Publish` , `internal/publish` , `internal/git` | `TestPublishPushesOnlyTheCapturedAnnotatedTag` , `TestPublishRejectsUnexpectedPushURLBeforeValidation` , `TestPublishComparesExpectedURLWithResolvedInsteadOfDestination` , `TestPublishExpectedPushURLUsesPushURLWhenFetchAndPushDiffer` , `TestCheckIgnoresExpectedPushURL` , `TestResolveUsesPushURLAndQueriesWithoutMutation` |
2026-10-06 16:04:35 +00:00
| Publication partial and uncertain recovery | `internal/publish` , `internal/git` | `TestPublishRejectedPushKeepsLocalTagAndReportsNotPublished` , `TestPublishLostAcknowledgmentConfirmsExactRemoteObject` , `TestPublishLostAcknowledgmentWithChangedEndpointRemainsUnknown` , `TestPublishUnavailableReconciliationRemainsUnknownAndPreservesPushError` |
2026-10-10 02:53:38 +00:00
| 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` |
2026-10-10 03:10:43 +00:00
| 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` |
2026-10-10 03:30:34 +00:00
| Tagged checkout and build dependency preparation | `releasekit.PrepareTaggedCheckout` , `releasekit.PrepareBuildDependencies` , `internal/preparation` , `internal/git` , `internal/gotool` | `TestPrepareTaggedCheckoutFetchesExpectedCommitAndDetaches` , `TestPrepareTaggedCheckoutRejectsWrongCommitBeforeCheckout` , `TestPrepareTaggedCheckoutReportsLocalCheckoutConflict` , `TestPrepareTaggedCheckoutReportsConflictingLocalTag` , `TestPrepareBuildDependenciesUsesSelectedModuleDirectory` , `TestPrepareBuildDependenciesPreservesPreparationEnvironment` , `TestPrepareBuildDependenciesPropagatesCommandFailure` , `TestPrepareBuildDependenciesPropagatesCancellation` |
2026-10-05 21:06:16 +00:00
| Page, manifest, asset comparison, and additive retry outcomes | `internal/gitea` | `TestEnsureReleaseCreatesMissingPageFromCommittedNote` , `TestInspectAssetsDetectsSameNameAndSizeWithDifferentBytes` , `TestUploadMissingPartialFailureThenRerunOnlyMissingAssets` |
2026-10-07 23:52:55 +00:00
| CLI profiles and prepared Woodpecker sequences | `cmd/releasekit` , `cmd/releasekit/internal/cli` , `examples/woodpecker/` | `TestLoadSettingsRejectsInvalidProfiles` , `TestWoodpeckerTagDeliveryTemplate` , `TestWoodpeckerTagDeliveryUsesTaggedModuleVersion` , `TestWoodpeckerSourceDeliveryTemplateSelfBootstraps` , `TestReleaseKitSourceDeliveryWorkflowFromTaggedCheckout` |
2026-10-05 21:06:16 +00:00
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 ](../integrations/gitea.md ) owns the HTTP contract
and hosted response handling. The [Woodpecker examples ](../../examples/woodpecker/ )
are prepared integrations; their YAML is not active in this repository, and no
live Woodpecker runner, configured secret, or hosted delivery has been used.
