SDK Release Management
Relevant source files
The following files were used as context for generating this wiki page:
SDK Release Management handles the lifecycle of generated client SDKs, including versioning, automated testing, and publishing to distribution channels such as npm and Git tags. The system determines when a new release is required by comparing current model inputs against the last published artifact. It ensures that releases are reproducible and verified through consumer tests before publication.
The management process is primarily driven by the crucible sdk CLI commands, which facilitate planning, building, verifying, and publishing SDK artifacts. This system maintains a journal of publications to support resumable uploads and prevents conflicting releases if a distribution channel moves during the process.
Sources: crates/crucible-sdk-release/src/lib.rs:1-20, crates/crucible-cli/src/sdk.rs:7-12
Release Lifecycle and Data Flow
The release process follows a strictly ordered sequence: Plan, Build, Verify, and Publish. This workflow ensures that no artifact is published without being successfully tested and recorded in a stable release directory.
The diagram shows the logical progression of SDK release commands from initial planning to final distribution.
Sources: crates/crucible-cli/src/sdk/release.rs:1-10, crates/crucible-cli/src/sdk.rs:43-85
Release Planning
The planning phase reads each SDK's channel to determine the last release and compares it with the current model and configuration. The system uses the choose function to decide the next version based on:
- Unchanged content: No release is triggered if the generated bytes match the last published artifact.
- Version rules: The version is incremented based on the highest of the last version, the configured floor, or a manual
--bump. - First release: New channels require a
--first-releaseflag to initialize versioning.
Sources: crates/crucible-sdk-release/src/lib.rs:11-15, crates/crucible-cli/src/sdk/release.rs:159-223
Core Components and Data Structures
Configuration and Metadata
The crucible-sdk.toml file defines the SDKs for a service. Each SDK entry specifies the target language, output directory, and release channel.
| Key | Description |
|---|---|
package | The package name used in the distribution registry (e.g., npm scope). |
language | The target programming language (Rust, TS, Python, etc.). |
channel | Distribution config: npm (registry, access) or git (url, branch, tag template). |
out | The local directory where development or release artifacts are written. |
api_version | Optional: Pins the SDK to a specific older release of the model. |
Sources: crates/crucible-cli/src/sdk.rs:157-190, crates/crucible-cli/src/api_versions.rs:163-176
Artifact Records
Release directories contain JSON records that ensure the integrity and reproducibility of the built SDKs.
- plan.json: Records the planned state, including the effective configuration, baseline version, and chosen next version. It includes the
config_sha256digest of the SDK settings. - release.json: Written only after all consumer tests pass. It maps each SDK name to its built version, content digest, and artifact metadata (SHA-256 and size).
- publication.json: A journal that tracks completed uploads to support resuming partial publication attempts.
Sources: crates/crucible-sdk-release/src/record.rs:1-25, crates/crucible-cli/src/sdk/release.rs:436-475
Build and Verification Process
The build command generates the SDK source code, stamps it with provenance data, and packages it for distribution.
Packaging Operations
The packaging logic varies by language and channel type:
- TypeScript/npm: Runs
npm install(with pinned TypeScript version),npm run build, andnpm pack. - Git Channels: Archives the package tree into a tarball.
- Provenance Stamping: Injects
crucible.jsoncontaining the generator version, service ID, service version, and a schema hash.
Sources: crates/crucible-cli/src/sdk/release.rs:567-628, crates/crucible-codegen/src/sdk/client.rs:105-120
Consumer Testing
Before a release is finalized, the system runs configured test commands. These tests are executed against the newly built artifacts. If any test fails, the release.json is not written, preventing the SDK from being published.
Sources: crates/crucible-cli/src/sdk/release.rs:651-700
The sequence illustrates the verification gate where consumer tests must succeed before a release is recorded as valid.
Sources: crates/crucible-cli/src/sdk/release.rs:360-420
Distribution Channels
Crucible supports two primary distribution channel types defined in crucible-sdk-release:
- NpmChannel: Publishes to npm-compatible registries. It handles
.npmrcauthentication and verifies if the version/bytes already exist on the registry before uploading. - GitTagChannel: Publishes by pushing tags to a Git repository. It supports
tagtemplates (e.g.,v{version}) and can "adopt" existing trees into the repository.
Sources: crates/crucible-sdk-release/src/lib.rs:7-10, crates/crucible-cli/src/sdk/release.rs:114-140
Publication Safety
The publish command validates the release directory using verify (re-hashing all artifacts) before attempting any uploads. It operates in two modes:
- Dry Run (Default): Prints what would be uploaded without executing network calls.
- Execute (
--execute): Performs the actual upload to the configured channels.
Sources: crates/crucible-cli/src/sdk.rs:71-84, crates/crucible-sdk-release/src/publish.rs
Summary
SDK Release Management provides a robust, reproducible pipeline for distributing client libraries. By leveraging deterministic code generation, automated consumer testing, and structured release records (plan.json, release.json), the system ensures that every published SDK accurately reflects a specific service model state. The dual-channel support (npm and Git) allows flexible distribution while maintaining strict versioning rules and publication safety.