Quickstart & Scaffolding
Relevant source files
The following files were used as context for generating this wiki page:
Quickstart and scaffolding in Crucible automate the creation and configuration of polyglot SDKs from a central service model. The system provides tools to initialize projects, configure package metadata, and generate standardized documentation and code snippets to accelerate developer onboarding.
Project Scaffolding & SDK Configuration
Crucible uses a configuration file, typically named crucible-sdk.toml, to define the relationship between a service model and its generated client packages. This file serves as the blueprint for project scaffolding, specifying model paths, default metadata, and language-specific SDK settings.
The crucible-sdk.toml Blueprint
The scaffolding process relies on several key configuration blocks:
- Model Identification: Defines the source model used for generation.
- Defaults: Shared metadata applied to all generated SDKs, including descriptions, license types, and author information.
- SDK Definitions: Language-specific blocks (e.g.,
[sdk.ts],[sdk.rust]) that define the target package name, output directory, and distribution channel (e.g., npm registry or Git).
Sources: crates/crucible-cli/tests/sdk.rs:16-36
SDK Scaffolding Flow
The following diagram illustrates the transition from a service model to a fully scaffolded SDK package.
The diagram shows how a single configuration file orchestrates the generation of diverse package manifests and client libraries.
Sources: crates/crucible-cli/tests/sdk.rs:98-154, crates/crucible-codegen-go/src/lib.rs:524-530, crates/crucible-codegen-ruby/src/lib.rs:252-258
Automated Documentation Generation
Crucible scaffolds more than just code; every generated package carries standard documentation designed for both human developers and AI coding agents.
README.md and AGENTS.md
The generator produces two distinct entry-point files for every SDK:
- README.md: Targets human users with installation instructions, client construction steps, and example calls.
- AGENTS.md: Provides a terse, instruction-heavy summary for AI coding agents, ensuring they use exact package and method names rather than inferred ones.
Sources: crates/crucible-codegen-common/src/guide.rs:1-18, crates/crucible-codegen-common/src/guide.rs:293-305
Guide Metadata Structure
The Guide structure encapsulates language-specific facts used to populate these documents:
| Field | Description |
|---|---|
language | The display name of the language (e.g., "TypeScript"). |
install | Shell commands to add the package to a project. |
manifest | Manifest entries (e.g., Maven dependency or Cargo line). |
construct | Code snippet for building the client with credentials. |
auth | Sentences explaining how to authenticate. |
pagination | Rules for iterating through paginated operations. |
Sources: crates/crucible-codegen-common/src/guide.rs:29-84
Quickstart Code Snippets
To facilitate immediate usage, Crucible generates "Call Snippets." These are complete, copy-pasteable programs that demonstrate how to import the client, build it with environment variables, and execute an operation.
Snippet Composition
Snippets are generated per operation and include:
- Imports: All necessary language libraries and model types.
- Client Construction: Logic that typically reads
ENDPOINTandTOKENfrom environment variables. - Input Handling: Sample values generated from the model's types and constraints, or specific examples defined in the model.
- Error Handling: Demonstrations of catching modeled service errors (e.g., using
instanceofin TypeScript oronin Dart).
Sources: crates/crucible-codegen-ts/src/snippet.rs:1-14, crates/crucible-codegen-dart/src/snippet.rs:1-12, crates/crucible-codegen-ts/src/snippet.rs:114-118
Environment-Aware Construction
Scaffolding logic determines if a client construction snippet needs to read from the environment based on whether the endpoint is provided in the configuration or if the service requires bearer tokens.
This diagram depicts how the generator adapts scaffolding based on the deployment environment settings found in the model or CLI flags.
Sources: crates/crucible-codegen-ts/src/snippet.rs:114-131, crates/crucible-codegen-dart/src/snippet.rs:114-138
Package Manifest Scaffolding
Each language generator implements specific logic to emit valid ecosystem manifests, ensuring the generated code functions as a native package.
| Language | Scaffolding Output | Key Runtime Dependencies |
|---|---|---|
| Go | go.mod, client.go, models.go | context, math/big, time |
| Ruby | .gemspec, lib/package.rb, Rakefile | json, net-http, openssl |
| R | DESCRIPTION, NAMESPACE, man/ | curl, jsonlite, openssl |
| C | CMakeLists.txt, Config.cmake.in | yyjson, CURL, OpenSSL |
Sources: crates/crucible-codegen-go/src/lib.rs:524-578, crates/crucible-codegen-ruby/src/lib.rs:252-263, crates/crucible-codegen-r/src/lib.rs:430-440, crates/crucible-codegen-c/src/lib.rs:218-225
Conclusion
Quickstart and scaffolding features in Crucible enable a "model-first" workflow where infrastructure code, package manifests, and onboarding documentation are kept in sync automatically. By generating human-readable READMEs and agent-readable instructions alongside technical snippets, Crucible ensures that scaffolded SDKs are immediately usable and correctly integrated into various language ecosystems.